# pxstud.io Lua scripting API — Types

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

## Types
The named sets of values used across the API. A value you pass must be one of these.

### ColorMode
How a sprite stores pixel colors. Converting between modes is lossy out of rgba.
- "rgba" — Full color with transparency: four bytes per pixel.
- "grayscale" — Shades of gray (with alpha), from each color's Rec. 709 luma, as in Aseprite.
- "indexed" — Each pixel is an index into the sprite's palette.

### LayerType
What a layer holds.
- "image" — Pixel art: one image per frame (a cel).
- "tilemap" — Tiles from the layer's own tileset, placed on a grid per frame.
- "reference" — An imported picture to trace over; never exported, never painted on.
- "adjustment" — Holds no pixels, only effects: they change everything composited beneath it in its group (or the whole picture), on every frame, at the layer's opacity. Colour and per-pixel effects only (levels, gradient map, noise, vignette, ...). Clipped, it changes just its base layer.
- "group" — A folder of layers. Holds no pixels; hiding or locking it hides or locks everything inside. At normal blend and full opacity its layers blend straight into what's below (pass-through) unless the group is isolated; an isolated group, or any other blend or opacity, composites its layers together first, then blends them as one image.

### BlendMode
How a layer's colors combine with the layers beneath it.
- "normal" — The layer's own colors, source-over.
- "multiply" — Multiplies colors; always darkens.
- "screen" — Inverse of multiply; always lightens.
- "overlay" — Multiply in the shadows, screen in the highlights, by the layer below.
- "darken" — Keeps the darker color of each channel.
- "lighten" — Keeps the lighter color of each channel.
- "color-dodge" — Brightens the layer below to reflect this one.
- "color-burn" — Darkens the layer below to reflect this one.
- "hard-light" — Multiply or screen by this layer's own colors.
- "soft-light" — A gentler hard-light.
- "difference" — Absolute difference of the colors.
- "exclusion" — A lower-contrast difference.
- "hue" — This layer's hue with the saturation and luminosity beneath.
- "saturation" — This layer's saturation with the hue and luminosity beneath.
- "color" — This layer's hue and saturation with the luminosity beneath.
- "luminosity" — This layer's luminosity with the hue and saturation beneath.
- "addition" — Adds the colors.
- "subtract" — Subtracts this layer from the one below.
- "divide" — Divides the layer below by this one.

### TagDirection
How a tag's frame span plays.
- "forward" — First frame to last, then repeat.
- "reverse" — Last frame to first, then repeat.
- "pingpong" — First to last, then back again.
- "pingpongReverse" — Last to first, then back again.

### UserDataKind
Which kind of thing a user data target names (see app.setUserData).
- "sprite" — The sprite itself.
- "layer" — A layer or group: layerId.
- "cel" — A layer's image on one frame: layerId and frameId.
- "tag" — An animation tag: tagId. Its colour stays Tag.color, so userData.color is not accepted.
- "slice" — A slice: sliceId.
- "tileset" — A tilemap layer's tileset: layerId.

### FillMode
Whether a shape is drawn as a border or solid.
- "outline" — Only the 1px border.
- "filled" — Every pixel inside the shape.

### BucketFillMode
Which pixels a flood fill or the magic wand reaches.
- "contiguous" — Only the connected region around the starting pixel.
- "global" — Every matching pixel on the canvas, connected or not.

### FillPattern
The repeating two-color pattern a flood fill paints, tiled from the canvas's top-left corner so neighbouring fills line up.
- "solid" — Only the fill color (no pattern).
- "checker" — A 1px checkerboard of the two colors.
- "dither25" — A 2x2 ordered dither: one pixel in four is the fill color.
- "dither75" — A 2x2 ordered dither: three pixels in four are the fill color.
- "hstripes" — 1px horizontal stripes, alternating the two colors.
- "vstripes" — 1px vertical stripes, alternating the two colors.
- "diagonal" — Diagonal lines of the fill color, one every 4px.
- "grid" — A grid of fill-color lines on a 4px pitch.
- "dots" — Single fill-color dots on a 4px pitch.
- "bricks" — A brick wall: fill-color mortar, 8x4 bricks offset every other row.

### GradientType
The shape of a gradient.
- "linear" — A straight ramp from the first point to the second.
- "radial" — A ramp radiating out from the first point.

### GradientDithering
The ordered-dithering pattern applied to a gradient's ramp.
- "none" — A smooth ramp (shows color banding).
- "bayer2" — A 2x2 Bayer matrix: the coarsest checker steps.
- "bayer4" — A 4x4 Bayer matrix.
- "bayer8" — An 8x8 Bayer matrix (finer).
- "dots" — Clustered dots on a 4px grid that grow into each other (halftone).
- "lines-h" — Horizontal lines that thicken along the ramp.
- "lines-v" — Vertical lines that thicken along the ramp.
- "diagonal" — Diagonal lines that thicken along the ramp.
- "noise" — An even, pattern-free scatter (interleaved gradient noise).

### GradientSnap
Whether a gradient's colors are free blends or snapped to the palette.
- "free" — Any color: the stops blend smoothly into each other.
- "palette" — Palette colors only: each pixel takes the nearest palette color; with dithering, the ramp steps between neighbouring palette colors.

### GradientColors
Where the gradient tool takes its colors from.
- "fg-bg" — From the foreground color to the background color.
- "stops" — Along the gradientStops list (fewer than two stops falls back to foreground to background).

### DitherPattern
An ordered pattern the dither brush paints through: a pixel is painted where the pattern's threshold there is below the density. Patterns tile from the sprite's top-left corner, so strokes line up.
- "bayer2" — A 2x2 Bayer matrix: 50% is a checkerboard.
- "bayer4" — A 4x4 Bayer matrix: 16 even steps.
- "bayer8" — An 8x8 Bayer matrix: 64 even steps (the finest).
- "dots" — Clustered dots on a 4px grid that grow into each other (halftone).
- "lines-h" — Horizontal lines that thicken with the density.
- "lines-v" — Vertical lines that thicken with the density.
- "diagonal" — Diagonal lines that thicken with the density.
- "noise" — An even, pattern-free scatter (interleaved gradient noise).

### BrushShape
The footprint a brush paints.
- "circle" — A round dot of the brush size.
- "square" — A square of the brush size, rotated by the brush angle.
- "line" — A 1px line of the brush size, tilted by the brush angle (0 = horizontal, 90 = vertical; a calligraphy nib).
- "diamond" — A diamond (a square standing on its corner) of the brush size.
- "cross" — A plus sign of the brush size (2px-wide arms at even sizes).
- "x" — An X: both diagonals of the brush-size square.
- "star" — A five-pointed star, one point up, of the brush size.
- "horizontal" — Alias for a line at angle 0: a flat size x 1 bar that ignores the brush angle.
- "custom" — The context's custom brush mask, at its own size.

### SymmetryAxis
A mirror line through the canvas center. Several axes combine (horizontal + vertical = 4-way).
- "horizontal" — A horizontal line: mirrors top to bottom (flips Y).
- "vertical" — A vertical line: mirrors left to right (flips X).
- "diagonal" — The top-left to bottom-right diagonal.
- "antidiagonal" — The top-right to bottom-left diagonal.

### TilemapEditMode
How pixel paint treats a tilemap layer.
- "tiles" — Only whole-tile stamping edits the layer; pixel tools are refused.
- "pixels-edit" — Paint edits the tile a cell already uses, in place: every placement of it updates.
- "pixels-auto" — Paint changes only the painted cells, like Aseprite Auto: an identical tile (also flipped/rotated, per the tileset match options) is reused, otherwise a new tile is made (a shared one is copied first), and tiles left unused by the edit are removed.

### TilePaintMode
How app.paintTilemapPixels applies pixels to tiles.
- "edit" — Edit the tiles the cells already use, in place (all placements update).
- "auto" — Per painted cell: reuse an identical (or flipped/rotated, per the tileset match options) tile, else copy on write / create one; then remove tiles the edit orphaned.

### SelectionCombineMode
How a new selection shape combines with the current selection.
- "replace" — The new shape becomes the selection.
- "add" — Union with the current selection.
- "subtract" — Remove the new shape from the current selection.
- "intersect" — Keep only where both overlap.

### SelectionModifyOp
How Select > Modify changes the selection's shape.
- "expand" — Grows the selection outward by the amount.
- "contract" — Shrinks the selection inward by the amount; parts thinner than that vanish.
- "border" — Keeps only the selection's inside edge band, the amount wide; the middle is deselected.

### SelectionModifyShape
How distance is measured when growing or shrinking a selection.
- "circle" — Straight-line distance: corners round off (at 1 pixel only the 4 orthogonal neighbours count).
- "square" — Grid distance: corners stay square (all 8 neighbours count at 1 pixel).

### EyedropperSource
What the eyedropper samples.
- "composite" — What the canvas shows: every visible layer blended.
- "layer" — Only the active layer's pixels.

### Ink
How freehand paint (drawStroke, spray) combines the paint color with the pixels already there.
- "copy" — Replaces the pixel with the paint color, alpha included (a transparent color erases). The default.
- "simple" — Alpha-composites the paint color over the existing pixel: an opaque color replaces it, a translucent one tints it.
- "lock-alpha" — Recolors only pixels that are already visible (alpha above 0), keeping each one's alpha.
- "shading" — Ignores the paint color: a pixel whose color is in the shades list moves one step forward in it (or one step back with shadeReverse); other pixels are untouched. Each pixel shifts at most once per stroke.

### EraserRightClick
What the eraser paints with the right mouse button.
- "background" — Paints the background color over every pixel the eraser touches.
- "replace" — Replaces only pixels of the foreground color with the background color (Aseprite's eraser); other pixels are untouched.

### FlipAxis
Which way to flip a region.
- "horizontal" — Left to right (mirror across a vertical line).
- "vertical" — Top to bottom (mirror across a horizontal line).

### TransformInterpolation
How pixels are resampled when a selection is scaled, rotated or skewed.
- "nearest" — Fast Rotation: each output pixel copies the nearest source pixel. Fast and exact, but diagonals come out jagged.
- "rotsprite" — RotSprite: upscales the source 8x with Scale2X, resamples there, and samples back down. Keeps pixel-art edges clean when rotating; never invents colors.
- "bilinear" — Bilinear: blends the four nearest source pixels (alpha-weighted). Smooth, antialiased results for scaling and rotating painterly or high-res art; invents in-between colors (an indexed sprite snaps them to the palette).

### IsoProjection
Which face of an isometric cube a region is projected onto (pixel-exact, never blended).
- "left" — The left face: a vertical shear whose rows run down to the right along the slope.
- "right" — The right face: a vertical shear whose rows run up to the right along the slope.
- "floor" — The top face: the region's x axis runs down-right and its y axis down-left along the slope, so a square becomes a diamond (twice as wide as tall at 2:1).

### IsoShape
The solid the Iso Shape tool (drawIsoShape) draws, in pixel-art dimetric projection.
- "box" — A rectangular block: W x D footprint, H tall.
- "ramp" — A wedge whose top slopes from H down to the ground, descending toward `direction`.
- "stairs" — Steps descending toward `direction`, about two footprint units deep each.
- "pyramid" — Four triangular faces from the footprint up to an apex H above its center.
- "prism" — A roof: two slopes meeting at a ridge H up. The slopes face `direction` and its opposite.
- "cylinder" — A round column with pixel-ellipse caps; W is the diameter (D is ignored), H the height.
- "cone" — A round base tapering to an apex H above its center; W is the diameter (D is ignored).
- "sphere" — A ball resting on the footprint's center; W is the diameter (D and H are ignored).
- "dome" — Half a ball on a round base; W is the diameter (D is ignored), H the height of its top.

### IsoShapeStyle
Which parts of an iso shape are painted.
- "filled" — The faces (and the inner edges between them), no silhouette outline.
- "outline" — The silhouette outline and inner edges only; the faces stay untouched.
- "filled-outline" — Faces, inner edges and the silhouette outline.

### IsoDirection
Which way a ramp or stairs descend, or which way a prism's slopes face, along the iso axes (x runs down-right on screen, y down-left).
- "+x" — Toward +x: down-right, the right face's side.
- "-x" — Toward -x: up-left, away from the viewer.
- "+y" — Toward +y: down-left, the left face's side.
- "-y" — Toward -y: up-right, away from the viewer.

### CanvasAnchor
Where existing content sits when the canvas is resized (the 3x3 anchor picker).
- "top-left" — Pinned to the top-left corner.
- "top" — Centered along the top edge.
- "top-right" — Pinned to the top-right corner.
- "left" — Centered along the left edge.
- "center" — Centered.
- "right" — Centered along the right edge.
- "bottom-left" — Pinned to the bottom-left corner.
- "bottom" — Centered along the bottom edge.
- "bottom-right" — Pinned to the bottom-right corner.

### OutlinePlace
Which side of the shape's edge the outline is drawn on.
- "outside" — Paints background pixels that touch the shape; the shape grows by the outline.
- "inside" — Repaints the shape's own edge pixels; the shape keeps its size.

### OutlineShape
A preset for the 3x3 outline matrix, which says which neighbors count as touching.
- "circle" — The 4 orthogonal neighbors (a plus): diagonal corners stay open, giving rounder outlines.
- "square" — All 8 neighbors: diagonal corners are filled too, giving a thicker, squarer outline.

### StrokePosition
Where Stroke Selection's line sits relative to the selection's edge.
- "inside" — Along the inside of the edge: the selection keeps its size.
- "center" — Centered on the edge: half the width outside it, half inside.
- "outside" — Along the outside of the edge: the stroke grows past the selection.

### AdjustHueMode
The colour model Hue/Saturation works in.
- "hsv" — Hue, saturation, value (as in Aseprite): the lightness slider moves the brightest channel toward full or zero.
- "hsl" — Hue, saturation, lightness (as in Aseprite): the lightness slider moves toward white or black.
- "oklch" — Perceptual OKLCH: hue turns and chroma scales at constant perceived lightness, so a hue shift doesn't brighten or darken colours; the lightness slider moves toward white or black. Colours pushed outside sRGB lose chroma rather than clip.

### AdjustCurveChannel
Which channel a colour curve edits.
- "value" — Red, green and blue alike (applied before the single-channel curves).
- "red" — Only the red channel.
- "green" — Only the green channel.
- "blue" — Only the blue channel.
- "alpha" — Only the alpha channel.

### AdjustIndexedMode
How a colour adjustment is applied on an indexed sprite. Ignored in rgba and grayscale.
- "remap" — Recolours the pixels, then snaps each changed pixel to the nearest palette entry. Selection-aware; the palette is untouched.
- "palette" — Edits the palette entries the targeted cels use, so every pixel (in any cel) using those entries changes. The selection is ignored.

### GradientMapSpace
The colour space a gradient map blends between its stops in.
- "rgb" — Straight sRGB: the plain per-channel ramp pixel art tools use.
- "oklab" — Perceptual OKLab: even-looking steps, no muddy greys between saturated stops.
- "oklch" — OKLCH: blends hue as an angle, so two stops pass through the colours between them.

### FxShape
The footprint of an outline, shadow or glow spread.
- "circle" — A rounded footprint: reach is measured as straight-line distance.
- "square" — A square footprint: reach is the same in every direction, corners included.
- "diamond" — A diamond footprint: reach is measured along the grid (|dx| + |dy|).

### ShadowEdge
How a soft shadow's edge is drawn (with softness above 0).
- "dithered" — An ordered dither of fully opaque shadow pixels, denser where the shadow is stronger; keyed to the canvas, so it doesn't shimmer as the art moves.
- "hard" — Each pixel is shadow where the softened shadow is at least half strength, else nothing.
- "smooth" — A real alpha ramp: half-transparent shadow pixels (not pixel-art safe).

### ConvolveEdges
What the Convolution Matrix reads beyond the edge of the cel.
- "clamp" — Repeats the nearest edge pixel.
- "tiled" — Wraps around to the opposite edge (for tileable art).

### DitherMethod
How colours with no exact palette match are approximated when reducing to a palette (Convert to Indexed, Reduce Colors, GIF export).
- "none" — Each pixel takes its nearest palette colour (flat areas, visible banding).
- "bayer2" — Ordered dithering with a 2x2 Bayer matrix: a coarse, regular checker of the two nearest colours.
- "bayer4" — Ordered dithering with a 4x4 Bayer matrix.
- "bayer8" — Ordered dithering with an 8x8 Bayer matrix (the finest pattern).
- "floydSteinberg" — Floyd-Steinberg error diffusion: each pixel's error spreads to its unprocessed neighbours (smooth, noisy; patterns shift when pixels change, so it can shimmer in animation).
- "atkinson" — Atkinson error diffusion: spreads only 3/4 of the error, so highlights and shadows stay clean (the classic Macintosh look).

### ReduceColorsPalette
Where Reduce Colors gets the colours it maps pixels onto.
- "generate" — Generates the best `colors` colours from the targeted cels (median cut).
- "palette" — Uses the sprite's palette (the transparent entry excluded): dithers the art onto it without converting to indexed.

### TweenEaseFamily
The shape of a tween's easing curve (combined with a TweenEaseMode, except linear and hold).
- "linear" — Constant speed.
- "hold" — Keeps the start value until the next keyframe, then jumps.
- "sine" — Gentle ease (a quarter sine wave).
- "quad" — Ease by t^2.
- "cubic" — Ease by t^3.
- "quart" — Ease by t^4.
- "quint" — Ease by t^5.
- "expo" — Sharp ease (exponential).
- "circ" — Ease along a quarter circle.
- "back" — Winds up (in) or overshoots (out) by `overshoot` before settling.
- "elastic" — Overshoots and wobbles into place (`amplitude`, `period`).
- "bounce" — Lands and bounces `bounces` times before settling.

### TweenEaseMode
Which end of the tween an easing family shapes.
- "in" — Starts slow (or winds up) and ends fast.
- "out" — Starts fast and settles slowly (or overshoots) at the end.
- "inOut" — Eased at both ends: the in curve for the first half, the out curve for the second.

### TweenPath
The route a tween's position takes between its start and end, as an offset across the straight line.
- "straight" — The straight line.
- "arc" — One hump of `height` pixels (a jump).
- "wave" — A sine wave of `amplitude` pixels, `cycles` full waves long, starting at `phase` turns.
- "zigzag" — A triangle wave of `amplitude` pixels, `cycles` full zigzags long.
- "shake" — Random jitter of up to `amplitude` pixels each frame, the same every time for one `seed`.
- "custom" — A drawn route: cubic Bézier `points` from the start position to the end position, travelled at constant speed (the position easing sets the pace).

### TweenSubpixel
How a tween turns fractional positions into whole pixels.
- "round" — Rounds each frame's position to the nearest pixel.
- "floor" — Rounds each frame's position down.
- "monotonic" — Rounds, but never steps back against the direction of travel (no jitter on slow eases). Falls back to round for easings that overshoot.

### TweenTiming
What a tween's progress counts.
- "frames" — Frames: every in-between frame advances progress by the same amount.
- "time" — Time: progress follows the frames' durations, so a longer frame covers more of the motion.

### TweenPivotSpace
What a tween's `pivotX` and `pivotY` are measured in.
- "cel" — Fractions of the start keyframe cel's box (0.5, 0.5 = its centre).
- "sprite" — Sprite pixels: one fixed point on the canvas, so several layers tweened with the same pose move rigidly as a group.

### TweenFade
How a tween shows its opacity track (and a crossfade).
- "alpha" — Partial opacity: the cel's opacity follows the track.
- "dither" — An ordered-dither dissolve: whole pixels appear or disappear through a pattern fixed to the canvas, so only existing colours are ever shown.

### TweenDither
The pattern a dither fade dissolves through, tiled from the canvas's top-left corner.
- "bayer2" — A 2x2 Bayer matrix: 4 steps, 50% is a checkerboard.
- "bayer4" — A 4x4 Bayer matrix: 16 even steps.
- "bayer8" — An 8x8 Bayer matrix: 64 even steps (the finest).
- "cluster" — Clustered dots on a 4px grid that grow into each other (halftone).

### TweenStaggerOrder
Which layer of a stagger starts first.
- "topDown" — The top layer first, then each layer below it.
- "bottomUp" — The bottom layer first, then each layer above it.
- "given" — In the order the layers are listed (the selection order).

### TweenStaggerLength
What a stagger does with each later layer's span.
- "keep" — Every span keeps the same end keyframe: later layers wait, then move faster to finish together.
- "extend" — Each later span ends `step` frames later than the one before, so every layer's motion keeps the same length.