Skip to content

This document explains how the engine works inside, for people who want to change it. It does not cover why the system is shaped this way (see DESIGN.md) or the spec format itself (see SPEC.md). Figures and motion models get a short section here; the full reference is figures.md. The web runtimes get a short section too; their references are runtime.md (<pixel-sprite>) and stage.md (<pixel-stage>).

Every mechanism below cites the file and function that implements it. If the code and this document disagree, the code is right. Please fix the document in the same change.

  1. Pipeline
  2. Module map
  3. Spec resolution: extends and figures
  4. Validation, compilation and lint
  5. Animation internals
  6. Rendering internals
  7. Output: sheets, bundles, export, runtime
  8. Invariants
  9. How to extend
  10. Testing
flowchart TD
  A["spec JSON (may have extends / figure)"] --> B["resolveExtends<br/>extend.js"]
  B --> C["resolveFigure → expandFigure<br/>figure.js"]
  C -->|"bones → parts<br/>motions → generateMotion (motion.js)<br/>→ oversampled tracks"| D["plain spec"]
  D --> E["validate<br/>spec.js"]
  E -->|"errors"| X["{path, message} list<br/>(CLI / studio show it)"]
  E --> F["compile<br/>spec.js"]
  F --> L["checkBounds<br/>lint.js (warnings)"]
  F --> G["renderFrame(compiled, {res, anim, frame, style})<br/>render.js"]
  subgraph per frame
    G --> H["samplePose<br/>animate.js: tracks, reach (rig.js solveReach),<br/>+ followOffsets"]
    H --> I["worldMatrices<br/>rig.js (pixel-snapped offsets)"]
    I --> J["rasterize: SDF test at each pixel centre<br/>shapes.js"]
    J --> K["shade: ramp, light, texture, shine, dither,<br/>contact shadow → inner lines → outline"]
  end
  K --> M["frame {w, h, rgba, ids, materials}"]
  M --> N["renderAnimation / renderSheet<br/>render.js"]
  N --> O["buildBundle<br/>bundle.js (PNG via host encoder,<br/>+ skins, bakePoints, ground, states)"]
  O --> P["&lt;pixel-sprite&gt;<br/>@pixel-studio/runtime"]
  P --> S["&lt;pixel-stage&gt; / &lt;pixel-actor&gt;<br/>@pixel-studio/runtime/stage"]
  N --> R["exportSheet<br/>export.js (Aseprite JSON for Phaser / PixiJS)"]
  M --> Q["contactSheet (image.js) / frameToAscii (ascii.js)"]

The same steps as text:

spec ──resolveSpec──▶ plain spec ──validate──▶ {errors, warnings}
│ (no errors)
▼
compile ──▶ compiled {size, materials, parts, animations, style,
points, ground, skins, states}
│
for each animation × frame × resolution:
▼
resolveStyle(compiled, res, overrides) ──▶ style (lod preset < spec.style < overrides)
samplePose(compiled, anim, f) ──▶ Map(partId → {x, y, rot, sx, sy, show})
worldMatrices(parts, pose, snap) ──▶ Map(partId → affine matrix), visibility
raster pass (one SDF sample per pixel) ──▶ hitPart / hitShape / local point per pixel
shade pass ──▶ rgba + material ids
inner-line pass, outline pass ──▶ final frame
▼
renderSheet ──▶ buildBundle ──▶ JSON {format, size, ground, animations, points?, skins?, states?,
variants[{res, image, skin?}]} ──▶ <pixel-sprite> ──▶ <pixel-stage>
└─▶ exportSheet ──▶ sheet + Aseprite JSON (frames, frameTags, slices) ──▶ Phaser / PixiJS

Each stage passes plain data to the next. Nothing downstream of resolveSpec knows that figures, motions or variants exist. (Skins are the exception that proves the rule: compile turns each skin into a whole compiled character of its own, so the renderer still sees only plain compiled specs.) By the time validate runs, a goose dressed on the goose figure with a walk motion is ordinary parts and keyframe arrays.

src/core/ (the engine; isomorphic, zero dependencies)

Section titled “src/core/ (the engine; isomorphic, zero dependencies)”
File Responsibility Main exports
index.js Public API barrel (@pixel-studio/core). Hosts should import from here. It exports no live registries: shapeTypes(), textures(), motionModels(), leggedModels() return frozen copies. the pipeline (resolveSpec, validate, compile, render, buildBundle, exportSheet, …), plug-ins, constants
internal.js Building blocks for tools (@pixel-studio/core/internal): the CLI, studio and tests import them; no compatibility promise. createImage, blit, bakePoints, samplePose, samplePoseAt, sampleValue, frameTime, followOffsets, worldMatrices, solveReach, overflowForPose, resolveExtends, mergeVariant, expandFigure, paletteOf, buildMixes
extend.js Variants: merge a spec onto its extends base (points and skins by name), then call resolveFigure. resolveExtends, mergeVariant, resolveSpec
figure.js Expand figure: bones become parts, motions become tracks (author tracks layered on top), model events become frame numbers, and the figure’s foot line (ground) and attachment points are fitted. views add the same character seen from other angles (idle@front, turn@front, …). resolveFigure, expandFigure
motion.js Motion models (gait, idle, pose, hop, jump, climb, fall, sit) that generate per-sample track arrays with planted feet, plus speed/speedY/wall and timed events. generateMotion, MOTION_MODELS, LEGGED_MODELS, OVERSAMPLE
spec.js Structural validation (JSON paths, did-you-mean; validateStates for the state machine) and compilation into the renderer’s structure, skins included. validate, compile, TRACK_PROPS, skinSpec (not re-exported from index.js)
shapes.js Signed distance functions and compileShape (sdf, thickness R, bbox). SHAPE_TYPES, compileShape, sdEllipse, sdRoundRect, sdCapsule, sdPolygon
animate.js Track sampling, pose composition, follow-through springs. sampleValue, frameTime, samplePose, samplePoseAt, followOffsets
rig.js 2D affine maths, world matrices, CCD reach solver, bounds sampling. worldMatrices, solveReach, ccd, overflowForPose, invert, apply, angleOf, localMatrix, mul
lint.js Checks that need poses: parts leaving the canvas, reach targets missed. checkBounds
render.js Style resolution, rasterizer, pixel-art shader, animation and sheet rendering, per-animation playback metadata. renderFrame, renderAnimation, renderSheet, animationMeta, resolveStyle, lodForRes, DETAIL_PRESETS, DETAIL_NAMES, MAX_RES
color.js Hex parsing, HSV/HSL conversion, hue-shifted ramps, darken. buildRamp, baseIndex, parseHex, toHex, darken
textures.js Procedural textures sampled in part-local pixel space. TEXTURES, sampleTexture, hash2
image.js RGBA image helpers and the contact sheet used by preview. contactSheet, createImage, blit, checker (not re-exported from index.js)
ascii.js A frame as text (one letter per material, # outline, . empty). frameToAscii
bundle.js Render one sheet per resolution (and per skin, stored as a colour swap + overlay of the default sheet when smaller) and package them for the runtime with size, ground, baked points and states; optionally without some views. buildBundle, bakePoints, skinDelta, keepViews, BUNDLE_FORMAT ('pixel-sprite/1')
export.js One sheet plus Aseprite “hash” JSON for game engines (Phaser, PixiJS): frames, tags, slices for points, Pixel Studio extras. exportSheet
mix.js Transition clips (mixes): a few frames that interpolate the pose from the end of one animation to the start of another, added to the compiled animations as "from>to". buildMixes
plugins.js Extension points: register shapes, textures and motion models; they join the built-in tables so validation and pixel brief treat them like built-ins. Read-only snapshots of those tables. registerShape, registerTexture, registerMotion, registeredPlugins, usePlugin, shapeTypes, textures, motionModels, leggedModels
png.js PNG bytes for any host (zlib injected): indexed (PLTE + tRNS, 1–8 bits) up to 256 colours, else RGBA8 with per-row filters. pngBytes, paletteOf
File Responsibility Main exports / entry
src/node/png.js pngBytes with node:zlib deflate level 9. Node-only. encodePNG(w, h, rgba) → Buffer
packages/runtime/src/pixel-sprite.js <pixel-sprite> web component: loads a bundle, picks a variant (and skin), plays frames from the sheet, fires baked events, runs the bundle’s state machine, and exports the shared frame clock. Does not import the engine. PixelSprite, clock, pickVariant, deviceScale, checkBundle, StateMachine, parseCondition, BurstDetector, BUNDLE_FORMAT
packages/runtime/src/pixel-stage.js <pixel-stage> and <pixel-actor>: characters that roam a page, standing on, jumping between, climbing and hiding behind opted-in elements. Imports only clock from pixel-sprite.js. PixelStage, PixelActor, World, checkScene, runScene, jumpArc, cells
bin/pixel.mjs CLI: validate, preview, ascii, render, export, bundle, resolve, where, figures, brief. Loads files, calls resolveSpec, then the core. pixel bin (see package.json)
scripts/build-demo.mjs Builds demo/assets/*.bundle.json from examples/*.json at 16/32/64 px, writes a 64 px poster of each (demo/assets/*.poster.png) and a 32 px exportSheet sheet for goose-root, copies both runtimes (pixel-sprite.js, pixel-stage.js), and with --previews writes previews/*.png. npm run build:demo, npm run previews
demo/index.html, demo/flock.html, demo/stage.html, demo/runner.html Demo pages: sprites on a site (including a state machine and skins section), the goose flock, <pixel-stage> characters roaming a page, and a tiny runner game played by the fox. pages
scripts/serve.mjs Zero-dependency static server for the repo root (studio and demo), port PORT or 5173. npm run studio
studio/app.js Studio UI: editor → resolveSpec → validate → compile → checkBounds → render (current view, LOD strip at 16/24/32/48/64 px, sheet), rig overlay, export with a canvas PNG encoder. browser module
studio/agent.js Agent tab: calls the Anthropic SDK from the browser (loaded lazily from esm.sh), validation-repair loop, contact-sheet critique. initAgent, extractSpec
studio/goose.html Goose workbench: resolves {extends: <goose>, …features} in the page, renders frames on demand with renderFrame, hides parts/shapes on a copy of the compiled spec (bones stay), exports a variant spec and checks it builds. Features live in studio/goose-features.json. page
studio/figures.html Figure viewer: inline module that draws each figure’s skeleton with samplePoseAt + followOffsets (smooth time, trails, onion skin). page
studio/index.html, studio/studio.css Studio markup and styles. —

resolveSpec(spec, {loadRef, loadFigure, warn}) in extend.js is the single entry point for turning an authored file into a plain spec. It runs two steps in a fixed order:

  1. resolveExtends follows the extends chain recursively, up to depth 8. It raises "chain is too deep (cycle?)" after that. Each level calls mergeVariant(resolvedBase, variant). Merge rules:

    • materials merge per field, and null removes;
    • parts are patched by id: remove: true removes the part and its descendants, addShapes appends, other fields replace, and unknown ids are appended;
    • materialMap re-points shape materials, including the variant’s own shapes;
    • materials that the base used but the variant no longer uses are dropped;
    • animations merge per track property, and null removes;
    • tracks and reach constraints that refer to removed parts are dropped;
    • points and skins merge by name, and null removes one;
    • style merges.

    Errors carry e.errors = [{path:'$', message}], the same shape as validation errors.

  2. resolveFigure (figure.js) loads the figure by name through loadFigure and calls expandFigure. Because extends runs first, a variant of a figure-based spec (for example examples/goose-root.json extends goose-base.json, which uses "figure": "goose") patches the unexpanded dressing, and the figure is expanded once at the end.

Loaders are injected by the host, which keeps the core free of I/O. The CLI resolves extends paths relative to the referring file (bin/pixel.mjs, loadSpec). The studio and build-demo.mjs resolve them inside examples/. All three read figures from figures/<name>.json.

expandFigure(spec, figure, fit, warn) in figure.js:

  • Bones become parts. Each bone {id, parent, from, to, z, side, follow} becomes a part with pivot = from, tip = to, z = bone.z ?? index and shapes: []. side: "far" adds shade: -0.3. Bones are first fitted by fit.scale, fit.offset and fit.origin (default: bottom centre of the canvas), and patched by fit.bones.
  • Dressing. A spec part whose id matches a bone is merged into that bone part. A part with bone: "x" becomes a child of bone x, with pivot = from and z = bone.z + 0.5. Any other part is appended as is. A spec with no parts gets a stick figure: capsules of r 1.4 with material bone, joint circles of r 2.4 (1.8 at leaf tips) with material joint, and style.outline: 'dark'.
  • Motions become tracks. For each animation with motion, the preset parameters (figure.motions[name]) are merged with the animation’s own fields. generateMotion (motion.js) is then called with the expanded parts, figure.rig and the author’s tracks as input. It simulates the motion twice (the first pass warm-starts the IK so the loop closes) and records M samples per track. M = frames × OVERSAMPLE when looping and (frames − 1) × OVERSAMPLE + 1 for one-shots, with OVERSAMPLE = 4. Values are rounded to 0.01. A track whose samples are all equal collapses to a number. Foot misses over 0.3 units are reported through warn.
  • Layering. layerTracks resamples the author’s tracks at the same M points and combines them with the generated ones: x, y and rot add, sx and sy multiply, show replaces. Root x/y/rot tracks are not layered a second time, because generateMotion already applied them before solving the legs (so feet stay planted under author body motion).
  • Gait and hop animations get speed, in units per second. The page moves the sprite at this speed so planted feet do not slide. Climb animations get speedY (units per second upward) and wall (the x of the wall the feet hold).
  • Events. generateMotion reports events in normalized time u: footstep per leg (data: {leg}) for gait and climb, takeoff/land for hop, launch/land for jump. expandFigure turns u into the first frame at or after it (ceil(u·frames) mod frames looping, ceil(u·(frames − 1)) one-shot), appends the author’s events, and sorts by frame. "events": false drops the model’s events. holds is copied through.
  • Ground and points. Unless the spec sets ground, expandFigure takes the figure’s ground (fitted), else groundOf: the lowest toe of the rig’s legs, else the shadow bone’s line, else the root bone. Figure points on existing bones are fitted and merged under the spec’s own points.
  • Rig roles. root is always required; the models in LEGGED_MODELS (gait, pose, jump, climb, sit) also need legs. Optional roles: neck, head, arms, tail, wings (flapped in fall, climb and jump), shadow, view.

Generated tracks are keyframe arrays with M entries. With linear interpolation (section 5), frame f lands exactly on sample f × OVERSAMPLE. The extra samples only matter where time is sampled between frames: the follow-through simulation and the studio’s smooth figure view. After expansion the output is a plain spec. validate rejects any leftover figure or motion key with a message that says to resolve it first.

validate returns {errors: [{path, message}], warnings: [{path, message}]}. Paths are JSONPath-like strings built while walking the spec, for example $.parts[3].shapes[0].material or $.animations.walk.tracks.legL.rot. Errors block compilation. Warnings never do.

  • Did-you-mean. didYouMean(word, options) returns the option with the smallest Levenshtein distance, provided that distance is below 3. It is appended to errors for unknown shape types, textures, materials, parents, track parts, track properties and reach chain ids.
  • Unknown keys produce warnings, not errors, through unknownKeys(obj, kind, ...) against the KNOWN table. Every object kind (top level, material, part, shape, animation, follow, reach, style, wave, keys) has an entry there.
  • Structural checks:
    • hex colours, and shine in 0..1;
    • unique part ids, unknown parents, and parent cycles;
    • per-type required shape fields (SHAPE_REQUIRED), and polygons with at least 3 points;
    • op must be add or cut; cuts need no material;
    • profile in dome|flat|none;
    • frames is an integer 1..64, and fps is in 1..60;
    • track values must be a number, a non-empty number array, {keys} or {wave} (isTrackValue);
    • style.outline in none|dark|selective.
  • Bones without shapes. A part with a tip may have shapes: [].
  • Off-canvas warning. compileShape is run on each shape and its bbox is checked against size, before part transforms. This only happens while no errors have been found yet.
  • Unused material warnings.
  • Reach (validateReach): the chain ids must exist, every chain id must be end or one of its ancestors, tip must be a point, target must be a pair of track values, aim needs at least one chain part besides end, and limits must be {id: [min, max]} for chain members only.
  • Animation extras: speedY and wall are numbers; events are {frame, name, data?} with an integer frame inside the animation; holds keys are frame indices and values are in (0, 16].
  • Points: each names an existing part, and at is [x, y], "pivot", or "tip" (bones only).
  • Ground: a number in 0..size[1].
  • Skins: each is an object with only parts, materials, materialMap and style (SKIN_KEYS). When the spec has no other errors yet, skinSpec(spec, patch) (the spec without skins and states, merged with the patch by mergeVariant) is validated, and its errors are re-reported under $.skins.<name>.
  • States (validateStates): nodes is non-empty and every node’s anim exists; then is a node or "previous"; random fidgets name existing animations; initial and transition from/to are nodes (from may be "*"); when conditions parse (name, !name, name op literal, joined by && or and) and name declared inputs; inputs start as a number, boolean, word or "trigger"; a node’s rate is a speed in (0, 4] or the name of an input; a transition’s at is a string ("now", "end", "sync" or an event name); interactions use on: click|enter|leave|burst|calm and fire/set declared inputs. Unknown states keys warn.
  • Mixes: mixes is an object; each key is "from>to" naming two different existing animations; each value is an object with frames a whole number 1..8, ease linear or smooth, and fps in 1..60.

ease names, wave shape names, and the types of style values and of material.tones / textureScale / textureStrength are validated too. Not validated: event data (any JSON value), the timing fields of states random fidgets (every, weight), and a non-array states.interactions (ignored).

compile calls validate and throws Error('invalid spec: ...') with .errors if there are any. Otherwise it normalizes the spec:

  • Materials become {color, texture, textureScale: 1, textureStrength: 0.35, shine: 0, flat, outline: true, tones}. A bare hex string "#rrggbb" is accepted as a material.
  • Parts become {id, index, parent, pivot (default: canvas centre), z (default: array index), tip, follow, base: {x, y, rot, sx, sy, show}, shade, shapes}.
  • Follow. compileFollow turns follow: n into {freq: 3, damping: 0.3, amount: n, max: 40}.
  • Shapes are compileShape(s) (sdf, R, bbox) plus op, material, minDetail (1), maxDetail (3), profile (dome) and shade (0).
  • Animations become {name, frames, fps: 8, loop: true, tracks, reach: [], speed: 0, speedY: 0, wall: null, events: [], holds: null}. Events are sorted by frame; holds keys become numbers.
  • No animations. A spec without animations gets still (1 frame, 1 fps).
  • Points become {part, at} with "tip" and "pivot" replaced by the part’s rest-pose point.
  • ground and states are copied (null when absent).
  • Skins. Each skin is compiled recursively, compile(skinSpec(spec, patch)), into a full compiled character with the same animations; compiled.skins maps names to them (null without skins).

checkBounds(compiled, {margin = 0.5}) (lint.js)

Section titled “checkBounds(compiled, {margin = 0.5}) (lint.js)”

checkBounds samples every frame of every animation with samplePose, so tracks, reach and follow-through are all included. For each frame:

  • Overflow. overflowForPose (rig.js) transforms each visible part’s edge samples into world units and records how far they go past each canvas edge. samplesFor produces the edge samples: bbox points on a 0.75-unit grid with -1.5 < sdf ≤ 0, cached per compiled shape in a WeakMap. Overflows larger than margin are aggregated per part and edge. The warning lists the frame ranges, for example "head" goes 8.2 units past the right edge in frames 2–7.
  • Reach. Any reach constraint whose pose.reachMiss is above 1 unit gets a warning that names the chain and suggests what to relax.

Bounds warnings use the same {path, message} shape as validation warnings, plus anim, part, edge, frames and amount. The CLI (compileOrExit, validate) and the studio (rebuild) print them next to validation output.

sampleValue(v, t, loop, isStep, defaultOffset) takes normalized time t ∈ [0, 1) (or [0, 1] for one-shots):

Form Evaluation
3 constant
[a, b, c, ...] interp(keys, t, loop, 'linear')
{keys, ease} interp with linear, smooth (smoothstep f²(3−2f)) or step. Any other string behaves as linear.
{wave, phase, cycles, offset, shape} offset + wave × w(x) with x = (t × cycles + phase) % 1. w is sin (default), tri (same phase as sin), square (+1 for the first half), or `bounce = −

interp spreads keys evenly over the cycle:

  • Looping: the span is n, so the last key interpolates back to the first. [0, 10] reaches 10 at t = 0.5 and is back to 5 at t = 0.75.
  • One-shot: the span is n − 1, so the last key is reached at t = 1 and held.

show is always stepped. Arrays and keys use step, and a wave becomes 1 when its value is ≥ 0. sx/sy waves use defaultOffset = 1, so {"wave": 0.06} oscillates over 0.94..1.06. Numbers and arrays on sx/sy are absolute factors.

loop: t = f / frames (frame 0 and the virtual frame `frames` coincide → seamless)
one-shot: t = f / (frames − 1) (first and last frames hit t = 0 and t = 1 exactly)
frames ≤ 1: t = 0

renderFrame wraps the frame index with frame % frames. loop defaults to true in compile. The runtime decides what happens after the last frame (section 7).

For each part, the base transform from compile is combined with the sampled track values. A missing track leaves the base unchanged:

x = base.x + track.x rot = base.rot + track.rot
y = base.y + track.y sx = base.sx × track.sx sy = base.sy × track.sy
show = (track.show ?? base.show) ≥ 0.5

The local matrix is built by localMatrix(pivot, t) in rig.js:

local = T(pivot + (x, y)) · R(rot) · S(sx, sy) · T(−pivot)
world = world(parent) · local (worldMatrices, parents resolved recursively)
visible = show && visible(parent)

Pivots and offsets are in rest-pose canvas units. Rotation is in degrees, clockwise on screen (y points down). The pivot is both the rotation origin and the scale origin. Matrices are [a, b, c, d, e, f] with x' = a·x + c·y + e and y' = b·x + d·y + f. invert clamps the determinant to 1e-9, so a zero scale does not produce NaNs.

After the tracks are applied, samplePoseAt solves each anim.reach[i] in order. The constraint’s target and aim are themselves track values, sampled at t.

  • solveReach(parts, pose, r, target, aim) runs ccd starting from the current (track) rotations. If the tip still misses by more than 0.05 units, it restarts from four perturbed seeds (chain[0]/chain[1] rotated by ±60° or ±120°) and keeps the best result. CCD can settle in a local minimum, for example a joint bent the wrong way, and the restarts get it out. It returns the remaining distance, which is stored in pose.reachMiss[i].

  • ccd(parts, pose, r, target, aim, iters = 32) runs up to 32 passes and stops early under 0.05 units. Each pass visits the joints from the end of the chain back to the root. For each joint it:

    1. recomputes world matrices;
    2. if aim is set, sets the end part’s local rotation so its world angle equals aim;
    3. rotates the joint by the wrapped angle between “pivot → tip” and “pivot → target”.

    With aim, the end part is not one of the solved joints. limits clamp the local rot to [min, max] as absolute values, which include the base rotation.

ccd is also used by motion.js for necks, heads and legs that are not two-bone. Two-bone legs use the exact law-of-cosines solver twoBone. Front-view legs use frontLeg, which foreshortens with sy.

Cost: each CCD step recomputes every part’s world matrix twice, and reach runs inside samplePoseAt, which the follow-through simulation calls once per substep.

Follow-through (animate.js, followOffsets)

Section titled “Follow-through (animate.js, followOffsets)”

A part with follow is a damped angular spring that hangs from its pivot. samplePose adds the spring angle to the part’s rot after tracks and reach:

pose.get(id).rot += followOffsets(compiled, anim).get(id)[f % frames]

samplePoseAt alone, as the studio figure viewer uses it, has no follow-through.

followOffsets(compiled, anim) simulates once per animation and caches the result in a WeakMap keyed by the compiled animation object:

  • Spring. k = (2π·freq)² and c = 2·damping·2π·freq, so damping is the damping ratio (1 = critically damped).

  • Driving forces. Each substep poses the rig at that time, with the current spring angles of all followers included, so chains of followers interact. It then computes world matrices and takes, for each follower:

    • the linear acceleration of its pivot a, by second finite differences over the last three substeps. This becomes a torque around the pivot using the lever arm r to the part’s centre of mass: (r × −a) / max(4, |r|²), converted to degrees. centerOf computes the centre of mass as the area-weighted centre of the shape bboxes, or the bone midpoint, or the pivot.
    • the angular acceleration of its parent α, which the part resists (−α).

    The sum is multiplied by amount. The spring is integrated with semi-implicit Euler, and the angle is clamped to ±max, with the velocity toward the limit zeroed.

  • Substeps. There are SUBSTEPS = 8 per frame. dt = 1 / (8 · fps). Generated motions have 4 samples per frame, which the 8 substeps interpolate linearly.

  • Warm-up. Looping animations run 4 passes over the cycle and record the last, so the spring has settled into its periodic state and the loop is seamless. One-shots run one pass from rest.

  • Recording. Every 8th substep the angle is recorded per frame, rounded to 0.01°.

  • No followers or fewer than 2 frames gives null (cached too).

All of this is in render.js unless noted otherwise.

The style is built from these layers, with later layers winning:

defaults { light: −45, elevation: 50, outlineColor: '#1b1424', snap: true, hueShift: 1,
ambient: 0.15, curvature: 0.8, flip: false }
< DETAIL_PRESETS[lod]
< spec.style (null / undefined / '' values ignored)
< overrides (CLI flags, studio knobs; same filtering)
lod = overrides.lod || lodForRes(res)

resolveStyle throws a readable error for a lod other than 1, 2 or 3 and for overrides that break the style rules (for example tones outside 2..6). renderAnimation refuses a res outside 1..MAX_RES (512).

lodForRes(res) returns 1 for res ≤ 20, 2 for res ≤ 40, and 3 otherwise. DETAIL_NAMES = {1: 'icon', 2: 'sprite', 3: 'portrait'}.

Key lod 1 lod 2 lod 3
tones 2 3 5
texture 0 0.6 1
dither false false true
outline dark selective selective
innerLines false false true
contactShadow false true true
ambientBoost 0.25 0 0

A shape is drawn only when minDetail ≤ lod ≤ maxDetail (defaults 1 and 3). Parts whose shapes are all gated out, and bones with no shapes, are skipped entirely.

  • Size. The canvas is size units (default [100, 100]). For a requested res, the frame is H = round(res) pixels tall and W = round(res × width / height) wide, with scale = H / height pixels per unit. res is the frame height.
  • Sampling. Pixel (px, py) samples the world point ((px + 0.5) / scale, (py + 0.5) / scale), its centre. There is no supersampling or anti-aliasing: each pixel takes one binary sample. flip mirrors the sampling (px → W − 1 − px) and negates the x gradient, so the light stays on the same screen side.
  • Pixel snapping. When st.snap is on, worldMatrices gets an adjust hook that runs snapUnits on each part’s x and y offset before building its matrix. An offset under 0.35 px becomes 0. Anything larger rounds to whole pixels, with a minimum of 1 px. Rotation and scale are not snapped, and the effect accumulates through the hierarchy, because each part’s local offset is snapped on its own.

compileShape (shapes.js) returns, for each shape:

  • sdf(x, y): signed distance in part-local units, negative inside. rect is a rounded box (r, rot), ellipse/circle an ellipse (with rot), capsule a segment with radii r → r2, and polygon an even-odd polygon distance, minus r when rounding is set.
  • R: the thickness, the largest inner distance. For an ellipse that is min(rx, ry), for a rect min(w, h)/2, for a capsule max(r1, r2). For a polygon it is estimated on a 13×13 grid over the bbox. The minimum is 0.01.
  • bbox in local units.

For each pixel, renderFrame walks the visible parts in draw order, sorted by z then by array index. It maps the pixel centre into each part’s local space with the inverse world matrix. Then:

  1. A shape is skipped early when the local point is outside its bbox padded by R + 0.75/scale.
  2. Thin-feature preservation. A shape thinner than a pixel is inflated just enough to claim the nearest pixel centre. The hit threshold is thr = reach − R when R < reach, otherwise 0. reach is half a pixel (0.5/scale) for elongated shapes, so lines stay 1 px wide. For “dots”, whose bbox is under 3 px in both directions, reach is 0.75/scale, a little over the half-diagonal.
  3. Inside a part, shapes are tested in array order. An add shape with sdf ≤ thr becomes the hit. A cut shape clears the part’s hit so far. Later shapes override earlier ones, and a cut only erases shapes of its own part that come before it.
  4. Across parts, a later (front) part that hits overwrites earlier ones, like a painter’s algorithm. The pixel records the part, the winning shape, and the local point.

Material unions. Before rasterizing, every part groups its non-cut shapes by material into a surface. Its sdf is the minimum of the member SDFs and its R is the largest member R. Lighting uses the surface, not the individual shape, so overlapping shapes of one material read as one lit volume without seams. The hit test itself still uses individual shapes.

For a hit pixel with material mat, the shader does the following:

  1. Ramp. ramp = buildRamp(mat.color, tones = mat.tones ?? st.tones, {hueShift}), memoized in the module-level rampCache. The base colour sits at bi = baseIndex(tones), which is 1 for 2 or 3 tones, 2 for 4 or 5, and 3 for 6.
  2. flat materials skip everything below and use the base tone. This is for eyes and emissive details.
  3. Normal.
    • (gx, gy): the normalized gradient of the surface SDF, by central differences in world space with eps = 0.35 px.
    • u: depth inside the surface, clamp(−sdf / R, 0, 1). It is 0 at the edge and 1 at the thickest point.
    • rho: tilt toward the edge, chosen by the shape’s profile:
      • dome: 1 − u;
      • flat: tilted only in the outer 30% ((1 − u/0.3) × 0.6);
      • none: 0.
    • Then rho = min(rho × curvature, 0.85) and n = (gx·rho, gy·rho, √(1 − rho²)).
  4. Light. L = (sin az·cos el, −cos az·cos el, sin el), where az = light (0 = from the top, negative = from the left) and el = elevation. The diffuse term is diff = max(0, n·L). It is remapped around the flat-facing value flatB = L.z: v = (diff − flatB)/(1 − flatB) above it and (diff − flatB)/flatB below it, so v ∈ [−1, 1] and a surface facing the viewer gets v = 0.
  5. Offsets. v += ambient + ambientBoost + part.shade + shape.shade.
  6. Contact shadow (when contactShadow is on). The pixel one step toward the light is checked: (sign(round(L.x·1.4)), sign(round(L.y·1.4))), which is up-left for the default light. If a part with strictly higher z covers that pixel, and its material is neither flat nor outline: false, then v −= 0.7. Eyes and glints do not cast shadows.
  7. Tone index. f = bi + v·bi for v < 0, otherwise bi + v·(tones − 1 − bi). v = −1 maps to the darkest tone and v = +1 to the lightest.
  8. Texture (when mat.texture and st.texture > 0). f += sampleTexture(name, floor(localX·scale), floor(localY·scale), textureScale) × textureStrength × st.texture × 1.3. The coordinates are part-local pixels at the current resolution, so the texture moves with the limb and its feature size is in pixels.
  9. Shine (when mat.shine > 0). Blinn-Phong with half vector normalize(L + (0, 0, 1)) and exponent 40. When spec × (0.5 + shine) > 0.55, the pixel takes the top tone.
  10. Dither. When dither is on and the fractional part of f is in (0.3, 0.7), a 4×4 Bayer threshold, indexed by the part-local pixel coordinate (so the pattern also sticks to the part), picks floor or ceil. Otherwise f is rounded. The result is clamped to [0, tones − 1].

ids[i] stores the material index. It is −1 for empty pixels and −2 for outline pixels. frameToAscii and the tests use it.

Ramps are built in HSV around the base colour:

Hue Saturation Value
Shadows, t = (bi − i)/bi drifts toward 250° (blue-violet) by 0.2·t·hueShift of the arc, capped at 60° of arc (≤ 12° at hueShift: 1) +0.14·t·(1 − s) ×(1 − 0.42·t)
Highlights, t = (i − bi)/(n − 1 − bi) drifts toward 55° (yellow) by 0.14·t·hueShift, capped at 50° of arc ×(1 − 0.35·t) +(1 − v)·0.65·t

Greys (s < 0.08) are handled differently. Their shadows take hue 250 with saturation capped at 0.18, and their highlights keep their hue.

darken(rgb, amount) uses the same cool drift. It adds 0.1 saturation and scales the value by 1 − amount. An invalid hex renders magenta ([255, 0, 255]).

sampleTexture(name, x, y, s) takes integer local pixel coordinates and a scale s = max(1, round(textureScale)), and returns a brightness offset of roughly ±1. The textures are:

  • noise: hash per cell;
  • fur: vertical streaks per column plus a variation along y every 3s;
  • scales: offset rows of cells 3s + 1 wide;
  • stripes: horizontal bands every 2s;
  • checker;
  • cloth: diagonal threads;
  • bricks: 6s × 3s with mortar lines;
  • spots: one jittered spot per 6s cell;
  • metal: horizontal brushed bands.

Randomness comes from hash2, an integer hash, so it is deterministic.

Both passes run after shading.

  • Inner lines (when innerLines is on). A pixel gets one when a 4-neighbour belongs to a different part with strictly higher z, and both materials are non-flat with outline not false. The pixel is repainted with darken(ramp[0], 0.15) of its own material, so the back part gets the line.

  • Outline (unless outline: 'none'). Each empty pixel that has a 4-neighbour covered by a material with outline not false becomes an outline pixel. The neighbours are checked in the order up, left, right, down, and the first match is the source. Outline pixels have ids = −2.

    • dark: uses style.outlineColor.
    • selective: uses darken(sourceRamp[0], 0.45), tinted by the neighbouring material.

    The outline sits outside the silhouette, so it grows the sprite by 1 px. That is why SPEC.md asks for margin around the character.

7. Output: sheets, bundles, export, runtime

Section titled “7. Output: sheets, bundles, export, runtime”
  • renderAnimation(compiled, name, res, overrides) resolves the style once and renders every frame.
  • renderSheet(compiled, res, overrides, names) puts one row per animation and one column per frame. Width is the maximum frame count, and unused cells stay transparent. It returns meta = {res, lod, frameW, frameH, animations: {name: {row, ...animationMeta(anim)}}}.
  • animationMeta(anim) (render.js) is the playback description shared by sheets, bundles and the CLI’s render JSON: frames, fps, loop, plus speed, speedY, wall, mix ({from, to}, on transition clips) and events when set, and durations (ms per frame, 1000/fps × hold) only when the animation has holds.
  • buildBundle(compiled, {resolutions = [16, 32, 64], overrides, encode, views, deltas = true}) (bundle.js) first drops the views not listed in views (keepViews: animations named x@view), then sorts the resolutions ascending and renders a sheet per resolution. It encodes each sheet with the host-supplied encode(w, h, rgba): encodePNG → data URL in Node, pngBytes with CompressionStream in the studio. Each skin in compiled.skins gets the same resolutions again, appended as variants tagged skin. skinDelta(base, skin) tries to express a skin sheet as recolor (each default colour → the skin colour it most often becomes) plus an overlay of the pixels still different; it gives up (null) if the skin makes an opaque pixel transparent. The delta is used when its encoded size is below the full sheet’s. It returns {format: 'pixel-sprite/1', name, size, ground, animations, skins?, states?, points?, skinPoints?, variants: [{res, lod, frameW, frameH, image, skin?}]}. ground is compiled.ground, or groundFromPixels: the bottom of the lowest opaque row of the first frame of the largest sheet, in units. points comes from bakePoints(compiled), which poses every frame with samplePose + worldMatrices and records [x, y, rotDeg] per point, animation and frame, in units (so one table serves every variant). Each skin’s points are baked too; a skin whose table differs from the default one (it moves the parts points ride on) gets it under skinPoints.<skin>.
  • exportSheet(compiled, res, {image, overrides}) (export.js) renders one sheet and writes Aseprite “hash” JSON: frames keyed by running index ("0", "1", …; what Phaser’s createFromAseprite expects) with per-frame duration, meta.frameTags per animation (repeat: "1" on non-looping ones), a PixiJS animations map, one 1×1 slice per point with a key per frame (from bakePoints, converted to frame pixels), and meta.pixelStudio with size, ground (falling back to groundFromPixels, like buildBundle) and per-animation fps, loop, speed, speedY, wall, events. It returns {width, height, rgba, json}; the CLI’s export command encodes and writes the two files.
  • <pixel-sprite> (@pixel-studio/runtime, src/pixel-sprite.js) does not import the engine; it reads only the bundle. Full reference: runtime.md.
    • Skins. The skin attribute filters variants to those with that skin (none = the default look; an unknown skin falls back to the default look) before choosing one.
    • Variant choice. pickVariant scores each variant by the integer scale k = round(size / frameH). Among variants with k ≥ 2 that land within 20% of size, the highest res wins. Otherwise the closest fit wins, preferring k ≥ 2.
    • Drawing. deviceScale turns the CSS scale k into whole device pixels per sprite pixel, m = round(k × devicePixelRatio). The canvas backing store is frame × m and its CSS size frame × m / dpr; each frame is drawn with drawImage from (frame × frameW, row × frameH) with smoothing off, so pixels are even at fractional DPRs. Draws happen only when the frame changes.
    • Animation clock. One exported clock drives all sprites and page code with one dt capped at 100 ms. It requests the next frame before running subscribers and isolates each in try/catch.
    • Loading. One load path per element guarded by a token, so overlapping src changes cannot race; the bundle, variant and sheet are committed together. Bundles are cached per URL (failures evicted), validated with checkBundle, and sheets are decoded once per variant (ImageBitmap). The host box is reserved from size before load; light-DOM children are the fallback until status="ready" (mirrored to the legacy state attribute until 0.2.0-alpha), and again on pixel-error.
    • Page observers. One IntersectionObserver for all sprites, a live reduced-motion listener, and a device-pixel-ratio listener that re-lays-out every sprite.
    • Playback.
      • Each frame shows for 1000 / fps ms, or for its entry in durations (scaled when the fps attribute overrides the rate).
      • Looping animations wrap.
      • Non-looping animations stop on their last frame and fire pixel-end.
      • play(name, {once: true}) (used by click-anim) fires pixel-end and then returns to the hover or base animation.
      • Events. Entering a frame that has baked events fires pixel-event ({anim, frame, name, data}), also for frames skipped while catching up after a slow frame.
    • Page geometry. el.point(name, {relative}) scales the baked points of the current frame to client (or box-relative) px, mirrored with flip; el.groundOffset is the foot line in CSS px from the top of the box; el.pxPerSecond() / el.pxPerSecondY() turn speed / speedY into CSS px per second; el.hitTest(x, y) reads the sheet pixel under a client point on one shared 1×1 probe canvas (never the display canvas) and treats unreadable cross-origin sheets as a hit.
    • State machine. If the bundle has states (and the element does not have states="off"), a StateMachine (DOM-free, conditions parsed by parseCondition) picks the animations: inputs via el.set(name, value) and el.fire(trigger), transitions at now, end, sync (keep the phase) or an event name, then nodes and random fidgets; el.stateNode and a pixel-statechange event report it. Its interactions (click, enter, leave) replace hover-anim/click-anim.
    • Pausing. Sprites pause while off-screen (IntersectionObserver), when paused is set, or under prefers-reduced-motion. Off-screen or under reduced motion, a one-shot or non-looping animation still ends on time: a timer for its full duration fires pixel-end, so code waiting for it never hangs.
    • Events. Every event goes through one emit() helper: pixel-<name>, bubbling and composed. Until 0.2.0-alpha is out it also fires the pre-0.2 name with its old options (LEGACY_EVENTS).
    • Node. A Base class guard lets Node import pickVariant, StateMachine and the other helpers for tests.
  • <pixel-stage> (@pixel-studio/runtime/stage, src/pixel-stage.js) puts <pixel-actor> characters (each wraps a <pixel-sprite> with states="off") on the page. Full reference: stage.md.
    • World. World reads the boxes of data-pixel-surface|climbable|perch|hide|occluder|avoid elements in one batch, only when marked dirty (ResizeObserver, MutationObserver, resize, load, transitionend, animationend, document.fonts.ready, or world.invalidate()), and builds platforms from surface tops plus a document floor.
    • Planning. An actor routes to a target with a cheapest-path search over platforms linked by drops, jumps and climbs (cost = px walked + a cost per action). Behaviours: wander, sit, hide, climb, jump and idling. Jumps follow jumpArc, timed to the animation’s launch→land events; climbs move at pxPerSecondY; feet stand on groundOffset.
    • Occlusion. Occluders and hiding spots are cut out of the actor with an even-odd clip-path; cells splits overlapping holes into disjoint rectangles first.
    • Events. Actor and stage events go through the file’s own emit() (pixel-tap, pixel-activity, …, plus the legacy names for one alpha). The inner sprite runs with burst="off" and states="off", and its events are stopped at the actor’s shadow root, so listeners on the actor hear each thing once. Scenes keep short names ("waitFor": "tap"); sceneEventName maps them to the pixel- events on actors and the stage.
    • Input and accessibility. Tapping or clicking an actor’s opaque pixels (hitTest) shoos it and swallows that click; a pause button (state kept in localStorage) stops all actors; under prefers-reduced-motion they stand still.

Keep these true, and treat any change that breaks one as a design change. The verification column records what was checked for this document.

Invariant What it means Verified
Zero dependencies package.json has no dependencies or devDependencies. Node code uses only node: built-ins. Yes. No dependency fields and no node_modules. The one exception is opt-in: studio/agent.js loads @anthropic-ai/sdk from esm.sh at runtime, and only when the Agent tab is used.
Isomorphic core src/core/*.js uses only language built-ins: no DOM, no Node APIs, no I/O, no globals. Hosts inject loaders (resolveSpec) and encoders (buildBundle). Yes. A grep of src/core for document, window, process, require(, node:, fs, fetch, Buffer, globalThis, performance, Date and console. finds nothing, and every import in src/core is relative (./).
Determinism The same spec and settings give the same pixels on every run and host. Yes. There is no Math.random. Textures use hash2. Rendering examples/fox.json twice at 32 px gave identical SHA-1 hashes, and engine.test.mjs asserts identical RGBA for two renders. The caches (rampCache, followCache, edgeSamples) memoize pure functions of their keys.
Everything reduces to a plain spec extends, figure and motion are resolved before validate. Generated motion is ordinary keyframe arrays. The renderer, lint, CLI where, and the studio rig overlay see only parts and tracks. Yes. validate errors on any remaining figure or motion. pixel resolve prints the plain spec.
Validation never throws, compile never renders invalid specs validate returns lists. compile throws one error carrying .errors, and so do resolveExtends and resolveFigure, so every host shows {path, message} the same way. Yes for structure. Some value types are not validated and can crash rendering (issues below).
Geometry is never resampled as a bitmap Every frame and resolution rasterizes the SDFs again. Rotation and scale go through matrices. Yes (renderFrame).
Detail-dependent behaviour lives in DETAIL_PRESETS and minDetail/maxDetail The renderer branches on style keys, not on res, so every tier can be overridden. Yes. The only res-dependent lookup is lodForRes.
Textures and dither are in part-local space They move with parts instead of swimming. Yes (render.js, using hitLX/hitLY).
Runtime is independent of the engine pixel-sprite.js reads bundles only; pixel-stage.js imports only pixel-sprite.js. demo/assets/ holds copies of both. Yes. Neither runtime imports src/core, and both copies are byte-identical today. build-demo.mjs refreshes them.

These are open. (Issues found while writing the docs that have since been fixed are not listed: negative wave phases, unvalidated style/material/track values, CLI argument handling, renderFrame/renderSheet/ buildBundle misuse errors.)

  • Dead code. hitD (render.js, written but never read) and toneIdx (render.js, same); rgbToHsl/hslToRgb (color.js) are exported but unused.
  • Unbounded cache. rampCache (render.js) is a module-level Map with no eviction. It grows with every distinct colour, tones and hueShift combination, for example while a colour is edited live in the studio.
  • CLI extends paths. bin/pixel.mjs keys resolved extends paths by the reference string, so two different files named by the same relative string at different depths of a chain would resolve against the wrong directory.
  • Inline figures are not fitted. resolveFigure ignores scale, offset and bones patches when figure is an inline object rather than a name.

Without touching the engine: plug-ins. src/core/plugins.js exposes registerShape, registerTexture and registerMotion. Registered names join SHAPE_TYPES / SHAPE_REQUIRED / SHAPE_KEYS, TEXTURES, and MOTION_MODELS (and LEGGED_MODELS), the engine’s private tables (the public API only hands out frozen copies), so validation, did-you-mean warnings and pixel brief treat them like built-ins; compileShape, sampleTexture and generateMotion fall back to the registered functions (customShapes, customTextures, customMotions). Plug-in motions return per-sample tracks, normalized and checked by pluginMotion in motion.js. The CLI loads plug-in modules with --plugin (usePlugin); examples/plugins/extras.mjs is a working example, tested in test/plugins.test.mjs (in its own process, since registries are global). Bundles stay data-only, so the runtime is unaffected. The recipes below are for changing the engine itself.

In every recipe, run npm test and then render something with node bin/pixel.mjs preview <spec> to look at the result. Rendering changes are visual; the tests only catch structure and regressions.

  1. src/core/shapes.js: add the name to SHAPE_TYPES and a case in compileShape that returns sdf (negative inside, part-local units), R (thickness: largest inner distance, used for lighting depth and thin-feature preservation) and bbox (it must contain the shape; it drives early-out, lint edge sampling and centerOf). Export the raw SDF function if it is useful on its own.
  2. src/core/spec.js: add required fields to SHAPE_REQUIRED, new field names to KNOWN.shape, and any extra checks inside the part.shapes.forEach block in validate.
  3. docs/SPEC.md, section “Shapes”.
  4. Tests in test/engine.test.mjs: an SDF sign/distance assertion (like 'SDFs: sign and distance') and a render assertion that the shape’s material appears in renderFrame(...).ids.
  1. src/core/textures.js: add the name to TEXTURES and a case in sampleTexture(name, x, y, s). It receives integer part-local pixel coordinates and an integer scale s ≥ 1, and returns roughly −1..1 (the shader multiplies by textureStrength × style.texture × 1.3). Use hash2 for randomness, never Math.random.
  2. Validation picks up TEXTURES automatically, including did-you-mean.
  3. Update the texture lists in docs/SPEC.md and README.md.
  4. Test: render a material with the texture at lod 3 and assert that more than one tone appears, and that two renders are identical.
  1. src/core/spec.js: add to KNOWN.material, validate the value in the materials loop of validate, and give it a default in compile (the materials[name] = {...} object).
  2. src/core/render.js: read it from mat in the shading loop of renderFrame, or in the inner-line or outline passes.
  3. extend.js merges material fields generically, so nothing is needed there.
  4. docs/SPEC.md, section “Materials”. Add a test in test/engine.test.mjs.

A new style key follows the same path: KNOWN.style in spec.js, a default in resolveStyle or a per-tier value in DETAIL_PRESETS, consumed in renderFrame, and documented in the SPEC.md style table. Validate its type in validate (next to the other style checks) so it cannot reach the renderer as NaN.

Track properties are transform channels, so several places must agree:

  1. src/core/spec.js: add to TRACK_PROPS and KNOWN.part (the rest value), and add the rest value to base in compile.
  2. src/core/animate.js samplePoseAt: decide how it composes with the base (add or multiply), and its defaultOffset for waves.
  3. src/core/rig.js localMatrix (and worldMatrices if it affects visibility or the hierarchy). If it should snap to pixels, update the adjust callback in renderFrame.
  4. src/core/figure.js: add the rest value to motionParts[].base, and choose add, multiply or replace in layerTracks. If motion models should generate it, change rec in motion.js.
  5. Tests: 'track values: ...' style unit tests plus a render or worldMatrices assertion (see test/rig.test.mjs).
  1. src/core/motion.js: add the name to MOTION_MODELS and implement it inside generateMotion. The function is one loop over M samples. Per sample it does the following, so a new model usually changes the feet, the root placement or the limbs and reuses the rest:

    1. compute foot targets (feet);
    2. place the root (place);
    3. lower the hips if a leg cannot reach;
    4. stabilize the head (ccd);
    5. solve the legs (twoBone, frontLeg or ccd);
    6. set arms, tail and shadow;
    7. record the pose relative to the base.

    Note that pose is currently aliased to idle. If the page should react to moments in the motion, push {u, name, data?} onto events; expandFigure converts them to frames.

  2. If the model needs rig.legs, add it to LEGGED_MODELS in motion.js; expandFigure checks root for every model and legs for those.

  3. Add presets with "model": "<name>" to the motions of the relevant figures/*.json, and document the parameters in figures.md.

  4. Tests in test/figure.test.mjs. The first test already asserts that every figure’s motions expand with no warnings, no foot-miss notes and no bounds warnings. Add a model-specific test in the style of 'hop: ...' or 'gait: planted feet ...', which measures toe positions with worldMatrices.

Add figures/<name>.json with name, size, bones, rig and motions (format in figures.md). test/figure.test.mjs iterates over the directory, so the new figure is tested automatically for clean expansion, validation, foot placement and bounds. The CLI’s figures command and bare-name preview also read the directory. studio/figures.html has a hard-coded FIGURES list; add the name there.

  1. bin/pixel.mjs: add a case to the switch (cmd). Use loadSpec(path) (resolves extends and figure), compileOrExit(spec) (prints warnings, exits 1 on errors, prints bounds warnings), overridesFrom(args) for the shared render flags, and encodePNG for images. compileOrExit also applies --skin (every command except bundle).
  2. Document it in the header comment block. The default case prints every line that starts with // at column 0 as the help text.
  3. Mention it in README.md and the “Agent workflow” section of docs/SPEC.md if agents should use it. There are no CLI tests today. If you add one, spawn node bin/pixel.mjs with node:child_process from a new test/cli.test.mjs.
Terminal window
npm test # node --test test/*.test.mjs (Node ≥ 20, no dependencies)

The test suite uses node:test and node:assert/strict. The engine tests import from src/core/index.js (and src/core/internal.js for building blocks) and build small specs inline. blob() in engine.test.mjs and arm() in rig.test.mjs are the helpers.

File Covers
test/engine.test.mjs SDF signs and distances. Validation paths, did-you-mean, parent cycles, bad tracks, and unknown-key warnings. LOD selection and overrides. Ramp ordering with the base colour kept. Track sampling (keys, waves, steps). Render determinism, size and outline. Thin features at 16 px. Pixel-snapped motion. minDetail gating. cut scoped to its own part. Sheet layout. PNG round-trip through inflateSync. Bundle variants. sx/sy waves around 1.
test/rig.test.mjs Reach: the tip hits a per-frame target, aim fixes the end orientation, limits are respected, validation messages. Bounds warnings with frames and edges. extends: material merge, part patch/add/remove with descendants, animation merge, materialMap, chained resolveExtends.
test/figure.test.mjs Every figure expands cleanly: no errors, no warnings, no motion notes, no bounds warnings. Gait feet move backward at exactly speed. pose keeps feet planted. Dressing and bone layers ride their bones, and tracks layer on the motion. Figure errors point at paths. Follow-through lags during the gait and stays still at rest. Every example resolves and validates. Front view: planted feet, foreshortening. Hop: gravity arc, volume-preserving squash, shadow shrink. Events: footsteps at touchdowns, hop takeoff/land, jump launch/land, author events. Climb: feet planted on the wall at speedY. Ground line from the figure, fitted and overridable. Points baked per frame, with validation messages. Holds become durations; bundles carry ground, size, events, points, speedY. Variants merge points by name. States validated against animations and inputs; skins compile as patched characters. exportSheet: Aseprite frames and tags, PixiJS map, slices, extras.
test/runtime.test.mjs pickVariant: integer scale ≥ 2, most detail within 20%, closest fit otherwise. The shared clock (a throwing subscriber cannot stop it; dt clamp and reset), checkBundle errors, deviceScale at fractional DPRs. jumpArc lands on time at the apex height; cells splits overlapping cut-outs into disjoint cells. parseCondition and StateMachine (inputs, sync, waiting for footstep, triggers, then: "previous", random fidgets).
test/plugins.test.mjs Plug-ins, in their own file because registrations are process-wide: a registered shape, texture and motion validate, render and animate like built-ins; registration errors are clear.
test/references.test.mjs The reference registry (references/, checked by scripts/references.mjs): every source is cited and every logged value matches, references/CREDITS.md is up to date with sources.json, and the checks catch bad licences, drifted values, unknown sources and measurement files that do not say who, when and how.
test/browser/runtime.html 24 in-browser checks of <pixel-sprite> (open it on real devices; passes in Chromium and the iOS 18.1 Safari simulator): single load on upgrade, reserved box, errors and reload(), races, shared sheets, device-pixel scaling, decorative alt, touch and mouse input, one-shots, the clock, footstep events, holds, point() with flip, groundOffset, hitTest(), the state machine, skins, transition clips, rage clicks. Run in Firefox and WebKit with scripts/browser-check.mjs.

Not covered by tests: the CLI, the studio, the <pixel-stage> / <pixel-actor> elements beyond jumpArc and cells (try demo/stage.html), <pixel-sprite> beyond the Node helpers except in the manual browser page, individual textures, dither, innerLines, contactShadow, shine, and the issues listed in section 8.

Pixel Studio

Agents describe characters; the engine draws them as pixel art at every level of detail; websites play them with one tag.

© 2026 Pixel Studio · v0.2.0-alpha.2 · Released under the MIT licence.