Context settings

The settings draw commands use for every option they aren't given — the same values the editor's toolbar shows. Read them with app.getContext(), change any with app.setContext({ ... }). They aren't part of the document and aren't undoable.

• foregroundColor (color — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; default { r = 0, g = 0, b = 0, a = 255 }) — The paint color: every draw command's color, and the gradient's start color.
• backgroundColor (color — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; default { r = 255, g = 255, b = 255, a = 255 }) — The secondary color: the gradient's end color, and what swapColors exchanges.
• brushSize (integer 1–64; default 1) — Brush size in pixels for the built-in shapes (ignored by a custom brush). Also sets the spray radius (2x the size).
• brushShape (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal" | "custom"; default "circle") — "line" is a 1px line tilted by brushAngle; "square" is rotated by it; "circle", "diamond", "cross", "x" and "star" ignore it; "horizontal" is a line at angle 0 that ignores it; "custom" paints customBrush.
• brushAngle (integer 0–180; default 0) — Brush angle in degrees (0-180): tilts the "line" brush and rotates the "square" brush. Ignored by other shapes.
• customBrush ({ width, height, mask } or false; default nil) — The mask a custom brush paints: { rows = { ".#.", "###", ".#." } } or { width, height, mask } with mask a flat 0/1 list. Normally set with app.useBrush(name) from a brush defined with app.defineBrush. Without one, a custom brush paints a 1px dot.
• pixelPerfect (boolean; default false) — Removes doubled corner steps from freehand strokes (any brush size); the brush is stamped along the corrected path.
• eraserRightClick (EraserRightClick: "background" | "replace"; default "background") — Eraser right button: "background" paints the background color everywhere it touches, "replace" turns only foreground-colored pixels into the background color (Aseprite).
• ink (Ink: "copy" | "simple" | "lock-alpha" | "shading"; default "copy") — How paint (strokes, spray, shapes, lines, polygon, contour, bucket, gradient, fillSelection) combines with existing pixels: "copy" replaces them (the default), "simple" alpha-composites, "lock-alpha" recolors only visible pixels, "shading" steps pixels along shades.
• shades (list of colors — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; default {}) — The ramp the shading ink steps along, in order: the editor's Shades box (or the selected palette range). Draw commands use it when ink is shading.
• stabilizer (integer 0–64; default 0) — Stabilizer strength for freehand strokes: each point is averaged with the previous N points, smoothing wobble (the stroke lags the cursor). 0 = off.
• pressureSize (boolean; default true) — Let pen pressure (a mouse counts as full pressure) drive the brush size, from dynamicsMinSize up to brushSize.
• pressureAngle (boolean; default false) — Let pen pressure (a mouse counts as full pressure) drive the brush angle, from dynamicsMinAngle to dynamicsMaxAngle.
• pressureGradient (boolean; default false) — Let pen pressure (a mouse counts as full pressure) blend the color from foregroundColor to backgroundColor along the stroke.
• pressureMin (integer 0–100; default 0) — Reading (percent) of the pressure sensor that maps to the low end. Greater than pressureMax inverts the mapping.
• pressureMax (integer 0–100; default 100) — Reading (percent) of the pressure sensor that maps to the high end.
• velocitySize (boolean; default false) — Let pointer speed drive the brush size, from dynamicsMinSize up to brushSize.
• velocityAngle (boolean; default false) — Let pointer speed drive the brush angle, from dynamicsMinAngle to dynamicsMaxAngle.
• velocityGradient (boolean; default false) — Let pointer speed blend the color from foregroundColor to backgroundColor along the stroke.
• velocityMin (integer 0–100; default 0) — Reading (percent) of the velocity sensor that maps to the low end. Greater than velocityMax inverts the mapping.
• velocityMax (integer 0–100; default 100) — Reading (percent) of the velocity sensor that maps to the high end.
• dynamicsMinSize (integer 1–64; default 1) — Brush size at the low end of a sensor mapped to size (the high end is brushSize).
• dynamicsMinAngle (integer 0–180; default 0) — Brush angle at the low end of a sensor mapped to angle.
• dynamicsMaxAngle (integer 0–180; default 180) — Brush angle at the high end of a sensor mapped to angle.
• dynamicsDither (boolean; default false) — Gradient dynamics pick foregroundColor or backgroundColor per pixel (ordered dither) instead of blending. Indexed sprites snap blends to the nearest palette color.
• dynamicsCurve (integer 25–400; default 100) — Sensitivity curve in percent: the sensor value is raised to curve/100 (100 = linear, above 100 needs more pressure/speed to take effect).
• symmetry (list of SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; default {}) — The active sprite's symmetry setting (each sprite keeps its own, like its axis position): mirror axes through the symmetry center. Readable information only — draw commands do not apply it unless you pass symmetry = app.getContext().symmetry. Empty = off; several axes combine (horizontal + vertical = 4-way).
• symmetryX (number (multiple of 0.5) or false; default nil) — Where the vertical symmetry axis (and the point both diagonals cross) sits: pixels from the canvas's left edge, a multiple of 0.5 (whole = between pixels, x.5 = through a pixel's middle). nil = centered. Like symmetry, readable information only: pass symmetryX = app.getContext().symmetryX to a draw command to follow it. Set false to re-center.
• symmetryY (number (multiple of 0.5) or false; default nil) — Where the horizontal symmetry axis (and the diagonals' crossing) sits: pixels from the canvas's top edge, a multiple of 0.5. nil = centered. Set false to re-center.
• tilemapMode (TilemapEditMode: "tiles" | "pixels-edit" | "pixels-auto"; default "pixels-auto") — How pixel paint treats a tilemap layer: "pixels-auto" gives each painted cell its own tile, "pixels-edit" edits the shared tile in place (every placement updates), "tiles" allows only whole-tile stamping.
• shapeFillMode (FillMode: "outline" | "filled"; default "outline") — Rectangles, ellipses, polygons and closed curves: outline or filled.
• cornerRadius (integer 0–1024 (every corner), or a list of four, clockwise from the top-left; default { 0, 0, 0, 0 }) — Rectangle: corner radii in pixels, clockwise from the top-left (0 = a square corner), each clamped to half the smaller side.
• selectionCornerRadius (integer 0–1024 (every corner), or a list of four, clockwise from the top-left; default { 0, 0, 0, 0 }) — Rectangular marquee: corner radii in pixels, clockwise from the top-left (0 = a square corner).
• cornerRadiusLinked (boolean; default true) — The tool options bar edits all four corner radii together (one Radius field) instead of one field per corner.
• lineWidth (integer 1–64; default 1) — Line and Curve tools: thickness in pixels (1 = a hard 1px line); wider lines get round ends.
• curvePixelPerfect (boolean; default true) — Curve tool: remove the L-shaped corners a 1px curve picks up, for clean pixel-art lines.
• bucketFillMode (BucketFillMode: "contiguous" | "global"; default "contiguous") — Flood fill: only the connected region, or every matching pixel.
• bucketTolerance (integer 0–255; default 0) — Flood fill: the largest per-channel difference that still counts as the same color.
• bucketCloseGap (integer 0–5; default 0) — Flood fill (contiguous): treat gaps in the outline up to this many pixels wide as closed, so the fill doesn't leak through them. 0 = off.
• bucketDiagonal (boolean; default false) — Flood fill (contiguous): also spread to diagonal neighbours (8-connected), so the region leaks through 1px diagonal lines.
• bucketStopAtGrid (boolean; default false) — Flood fill: confine the region to the grid cell the click lands in.
• bucketPattern (FillPattern: "solid" | "checker" | "dither25" | "dither75" | "hstripes" | "vstripes" | "diagonal" | "grid" | "dots" | "bricks"; default "solid") — Flood fill: paint a repeating two-color pattern (the fill color and the other of foreground/background) instead of a solid color. "solid" = no pattern.
• wandFillMode (BucketFillMode: "contiguous" | "global"; default "contiguous") — Magic wand: only the connected region, or every matching pixel. Separate from the flood fill's bucketFillMode.
• wandTolerance (integer 0–255; default 0) — Magic wand: the largest per-channel difference that still counts as the same color. Separate from the flood fill's bucketTolerance.
• wandDiagonal (boolean; default false) — Magic wand (contiguous): also spread to diagonal neighbours (8-connected), so the region leaks through 1px diagonal lines.
• wandStopAtGrid (boolean; default false) — Magic wand: confine the region to the grid cell the click lands in.
• sprayRate (integer 1–64; default 8) — Spray: dots per point.
• scatterX (integer 0–64; default 8) — Scatter: how far each stamp can land left or right of the path, in pixels.
• scatterY (integer 0–64; default 8) — Scatter: how far each stamp can land above or below the path, in pixels.
• scatterCount (integer 1–16; default 2) — Scatter: stamps placed at each step along the path.
• blurStrength (integer 1–4; default 1) — Blur: neighborhood radius in pixels.
• jumbleStrength (integer 0–100; default 100) — Jumble: percent chance each touched pixel is scrambled.
• dodgeBurnStrength (integer 1–100; default 25) — Dodge/burn: how far each touched pixel's OKLCH lightness moves (100 = half of black-to-white).
• dodgeBurnHueShift (integer 0–60; default 0) — Dodge/burn: degrees each touched pixel's OKLCH hue turns toward warm yellow (dodge) or cool blue (burn), never past it; 0 keeps the hue.
• ditherPattern (DitherPattern: "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise"; default "bayer2") — Dither brush: the ordered pattern it paints through. Patterns tile from the sprite's top-left corner, so strokes line up.
• ditherDensity (integer 0–100; default 50) — Dither brush: the share of the pattern's pixels it paints, in percent (50 with bayer2 is a checkerboard).
• gradientType (GradientType: "linear" | "radial"; default "linear") — Gradient: a straight ramp between the points, or radiating from the start point.
• gradientDithering (GradientDithering: "none" | "bayer2" | "bayer4" | "bayer8" | "dots" | "lines-h" | "lines-v" | "diagonal" | "noise"; default "bayer4") — Gradient: the ordered-dithering pattern (none = a smooth ramp).
• gradientSnap (GradientSnap: "free" | "palette"; default "free") — Gradient: free blends, or only palette colors (each pixel the nearest palette color; dithering steps between neighbouring palette colors).
• gradientColors (GradientColors: "fg-bg" | "stops"; default "fg-bg") — Gradient: run from the foreground to the background color, or along gradientStops ("stops"; fewer than two stops falls back to foreground to background).
• gradientStops (list of up to 32 { color, position } (position 0–1, in order), or of colors spread evenly; default {}) — Gradient: the multi-stop ramp from the start point, as { color, position } entries (position 0-1, in order; two at one position make a hard edge). A plain list of colors is spread evenly. Used when gradientColors is "stops"; the editor's Stops bar edits it.
• eyedropperSource (EyedropperSource: "composite" | "layer"; default "composite") — Eyedropper: sample what the canvas shows, or only the active layer.
• tileIndex (integer ≥ 0; default 1) — Tile stamp: the 1-based tile to place (0 = the empty tile).
• tileFlipH (boolean; default false) — Tile stamp: flip placed tiles horizontally.
• tileFlipV (boolean; default false) — Tile stamp: flip placed tiles vertically.
• tileRotate90 (boolean; default false) — Tile stamp: rotate placed tiles 90° clockwise.
• tilePlace (boolean; default false) — Place tiles: on a tilemap layer the pencil, eraser, line, shape tools and bucket place the tile stamp's tile (erase it, for the eraser) on the cells they cover instead of painting pixels.
• isoShape (IsoShape: "box" | "ramp" | "stairs" | "pyramid" | "prism" | "cylinder" | "cone" | "sphere" | "dome"; default "box") — Iso Shape tool: the solid it draws.
• isoWidth (integer 1–1024; default 8) — Iso Shape tool: footprint along x (down-right), in iso units (one row of the edge staircase each).
• isoDepth (integer 1–1024; default 8) — Iso Shape tool: footprint along y (down-left), in iso units.
• isoHeight (integer 0–1024; default 8) — Iso Shape tool: height in pixels (0 = flat).
• isoBevel (integer 0–1024; default 0) — Iso Shape tool: boxes only, how many pixels the top edges are chamfered (0 = square).
• isoCap (integer 2–4; default 3) — Iso Shape tool: the flat run at the top and bottom vertices, 2 (even), 3 (odd) or 4 (multiples of four). Also the W / D drag step (2 units at cap 4).
• isoStyle (IsoShapeStyle: "filled" | "outline" | "filled-outline"; default "filled-outline") — Iso Shape tool: faces, outline, or both.
• isoHiddenEdges (boolean; default false) — Iso Shape tool: also draw the edges behind the solid.
• isoDirection (IsoDirection: "+x" | "-x" | "+y" | "-y"; default "+x") — Iso Shape tool: which way a ramp or stairs descend, or a prism's slopes face.
• isoAutoShade (boolean; default true) — Iso Shape tool: derive the five colors from the foreground color along shades (true), or use isoColors (false).
• isoColors (list of colors — "#rgb", "#rrggbb[aa]" or { r, g, b, a }; default { { r = 34, g = 32, b = 52, a = 255 }, { r = 69, g = 68, b = 79, a = 255 }, { r = 203, g = 219, b = 252, a = 255 }, { r = 139, g = 155, b = 180, a = 255 }, { r = 90, g = 105, b = 136, a = 255 } }) — Iso Shape tool: the colors used when isoAutoShade is off, in order outline, inner edge, top, left, right.

As Markdown: context-settings.md.