# pxstud.io Lua scripting API — Context settings

> Part of the pxstud.io Lua scripting reference, whose overview (https://pxstud.io/docs/scripting.md) explains its conventions. The option groups and types it refers to are in https://pxstud.io/docs/scripting/option-groups.md and https://pxstud.io/docs/scripting/types.md. Everything in one file: https://pxstud.io/llms-full.txt. The whole site's index: https://pxstud.io/llms.txt.

## 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.