Skip to content
TypeScript
11.6 KB
Raw Blame

pxl reference

Art files are plain JavaScript (or TypeScript) evaluated with the DSL as globals. Nothing draws at definition time: sprite, scene, ... record definitions; everything renders at build time, so assets may reference each other in any order.

Coordinates are 0-based from the top-left. Sizes are w, h. Colors are a single palette key ("k"), a hex string ("#1b1630", "#rgb", "#rrggbbaa"), "." (skip: leave the pixel) or "_" (erase to transparent).

Palette

Call Effect
use("pico8") Built-in palette: pico8 (default), sweetie16, db16, endesga32, gray8. Keys are index chars 0-9a-z.
use(["#000", "#fff", ...]) Custom list, keys 0-9a-zA-Z by index.
pal({ k: "#1b1630", g: 11, h: "k" }) Add/override single-char keys: hex, palette index, or copy of another key. . _ # space are reserved.
ramps("kDdu", "kTtq") Light ramps, dark → light. shade steps a color left, light steps right. When a key is in several ramps, the first ramp wins.

Every asset keeps the palette that was active where it was defined, so files with different palettes can be included and stamped together.

Assets

sprite(name, opts?, ...items)
scene(name, { w, h, bg?, ... }, ...items)
layer(name, layerOpts?, ...items)      // only as an item of a sprite or scene
group(name, ["a", "b", "rock_*", ...])  // random pick per placement; repeat a name to weight it
sheet(name, ["slime*", "heart", groupName], { cols?, pad? })
include("other.px.js")                  // path relative to the current file

Names starting with _ are parts: usable everywhere but not exported, and not matched by sheet globs.

Items (run in order)

  • Grid string: one char per pixel, drawn at 0,0. Rows are trimmed, blank edge rows dropped, short rows padded. ./space keep, _ erases. Use template literals for multi-line grids.
  • Op: rect(...), stamp(...), ... (below).
  • Function: (c) => { ... } gets the canvas; call ops as methods (c.rect(...)), plus c.w, c.h, c.is(x, y, "ab") (pixel is one of these keys; "*" opaque, "." transparent), c.key(x, y), c.get(x, y) (packed color), c.rng(seed) (deterministic, follows reseed).
  • Layer: drawn on its own image, then blended in at its place in the list.

Sprite / scene options

Option Meaning
w, h Canvas size. Sprites infer it from grid strings (including grids inside layers) when omitted; scenes require it.
base: "name" Start from a copy of another asset (variant). Overlay coordinates are the base's final coordinates (outline included).
bg Scene background color.
mx: true Mirror the left half onto the right after all items. Inferred width doubles (write half a row). mx: "c": odd width, shared center column. my likewise vertically.
swap: { g: "r" } Recolor after drawing.
flip: "x" | "y" | "xy", rot: 90 | 180 | 270 Transform.
outline: "k" 1px outline around opaque pixels; grows the canvas 1px on every side. outline8 also fills diagonals.
crop: true Trim to opaque bounds.
layers: true Also export each layer as out/<sprites|scenes>/<name>/<layer>.png.

Post-processing order: mirror → swap → flip → rot → outline → crop.

Layer options

Option Meaning
x, y Offset of every op in the layer.
hidden: true Skip when compositing (still exported with layers: true).
shade: true | n | { m: "M" } Blend layer: not drawn. Wherever it is opaque, what's below steps darker along the ramps (n steps, or the given map).
light: ... Same, lighter. Cast shadows, light spills, glows.
density: 0..1 Ordered-dither the layer (soft edges). Stack a low-density big shape and a full small one for falloff.

Ops

? marks optional arguments.

Shapes

Op Notes
px(x, y, c)
rect(x, y, w, h, c) · box(x, y, w, h, c) filled · 1px border
line(x0, y0, x1, y1, c, width?) width > 1 = round brush (tubes, poles, thick strokes)
hline(x, y, len, c) · vline(x, y, len, c)
circ(cx, cy, r, c) · ring(cx, cy, r, c) pixel-art circles; ring is a clean 1px border
ellipse(cx, cy, rx, ry, c, ring?)
poly([x0, y0, x1, y1, ...], c) filled; vertices on pixel corners ([0,0, 4,0, 4,4, 0,4] = rect(0,0,4,4))
fill(x, y, c) 4-connected flood fill
wire(x0, y0, x1, y1, sag, c, { hang?, every = 6, start?, ...placement }) sagging cable; hang stamps an asset/group under it every every px (string lights)
text(x, y, "str", c, { scale = 1, gap = 1, lead = 1, align: "l"|"c"|"r", shadow? }) built-in 3×5 font: A-Z 0-9 and common punctuation, \n for lines

Texture and tone

Op Notes
dither(x, y, w, h, c1, c2, density = 0.5) Bayer 4×4; c2 covers density
grad(x, y, w, h, "abc", dir = "v", soft = 0.5) bands with dithered seams; "h" horizontal; soft 0 = hard bands
noise(x, y, w, h, "ab", density = 0.1, seed = 1, on?) deterministic speckle; on: "g" only touches those keys ("*" any opaque)
shade(where?, steps = 1, density = 1) · light(...) step colors along ramps inside a region
recolor({ a: "b" }, where?, density = 1) swap colors inside a region

Regions (where, clip): undefined = everywhere, [cx, cy, r] circle, [x, y, w, h] rect, [x0, y0, x1, y1, x2, y2, ...] polygon, or (x, y) => boolean.

Placing assets

Op Notes
stamp(name, x, y, opts?)
tile(name, x, y, cols, rows, opts?) grid of copies (each cell picks separately for groups)
pattern(name, x, y, w, h, opts?) fill an area with copies; edges cut to fit
tilemap("gg\nd.", { map: { g: "grass", d: "dirt" }, size?, w?, h?, x?, y?, ...placement }) character map; . empty
scatter(name, x, y, w, h, count, { on?, clip?, below?, ...placement }) brush: count picks centered at random points; on = center must land on these keys; clip = paint only onto them; below = masks read the composite under this layer
clip(region, ...items) run items with drawing restricted to the region (half domes, roof slopes, masked textures)

Any name may be a sprite, scene, group, or glob ("tree_*"). Placement opts: flip, rot, swap, rflip: "x"|"y"|"xy" (random flips), rswap: [{ g: "r" }, {}] (random recolor; {} = none), seed, reseed: true | n (rebuild the placed asset with its own random choices; true derives it from the position, so tile("house", 0, 0, 4, 1, { reseed: true }) gives four different houses from one definition).

Randomness is seeded from the placement position + seed, so builds are reproducible and moving one placement doesn't reshuffle the others. Change seed to reroll.

Lighting

lamp(x, y, { r, color, power }), lighting({ cell, sky, ambient, emit, ... }), and the layer flags solid, wall, unlit: see lighting.md. The same file covers normal maps: bump("dome"|"bevel"|"luma", { w, depth, on, where }) and the numpad grid normals(x, y, grid).

Glow

glow(keys, { where, r = 6, strength = 0.5, color, bands, ramp }) goes directly in a sprite or scene body (like lighting) and works on everything drawn before it: every pixel whose color is one of keys spills a halo onto the opaque pixels within r, falling off with distance. The glowing pixels themselves are left as they are, and transparent pixels stay empty.

Option Meaning
where Region: only pixels inside it glow (the halo may spread past it).
r Halo radius in px.
strength How strongly the halo brightens (screen blend in the glowing color; 0..1+).
color One tint for the whole halo instead of each pixel's own color.
bands Quantize the falloff into this many rings: crisp, pixel-art halos.
ramp Palette mode: step neighbours up to ramp shades lighter along the ramps, dithering between steps. Stays in the palette; ignores strength/color. Use it before lighting().

Color mode leaves the palette (like lighting). Several glows can stack, each with its own keys and radius. After lighting(), pixels still glow by their palette key even though the light has changed their colors.

Animation

anim(name, { fps = 8, frames, loop = true, base, w, h, outline, mx, ... }, ...items)
frame({ ms, hold }?, ...items)          // only inside an anim (top level or in its layers)

An anim is a sprite with frames. Its items run in order on every frame, except frame(...) items: the k-th frame() only runs on frame k, so frames are patches over the shared items (or over base). Post-processing (mirror, outline, ...) runs on each frame. A frame lasts 1000 / fps ms, or ms, or hold × that. loop: false plays once and holds the last frame.

anim("candle", { outline: "k", fps: 5 }, `
  .l.
  lLl
  xxx`,
  frame(), frame(grid(0, 0, "l_.\n_Ll")), frame(grid(0, 0, "._l\nlL_")))   // "_" erases
anim("frog", { base: "frog_idle" }, frame({ ms: 2200 }), frame({ ms: 200 }, grid(1, 1, "ff")))

Procedural: without frame() items, frames: n sets the count and functions draw from c.frame (0..n-1), c.frames and c.phase (frame / frames, 0..<1). Use phase with sin for loops that wrap seamlessly:

anim("fire", { w: 22, h: 23, frames: 6, fps: 10 }, (c) => {
  const k = c.phase * Math.PI * 2
  c.poly([2, 21, 10, 21 - Math.round(16 + Math.sin(k) * 2), 19, 21], "h")
})

Placing anims animates the placer. A sprite or scene that stamps (tiles, scatters, ...) an anim, directly or through other assets, is animated too: it loops over the least common multiple of what it contains (capped at 60s), sampled at their common step. Keep durations on a shared grid (e.g. multiples of 100ms) so loops stay short. Placement options:

Option Meaning
frame: n Freeze on frame n (the placer doesn't animate from it).
delay: ms Start later, snapped to the anim's step: desync copies.
rdelay: true Random start per placement (seeded, reproducible).

Output: anims go to anims/<name>.png (horizontal strip), anims/<name>.json (per-frame duration + meta.frameTags, Aseprite style: Phaser, Godot, ... read it) and anims/<name>.gif. Animated sprites and scenes get <name>.gif next to their PNG (which shows frame 0). Previews: _preview/<name>.png shows an anim's frames side by side; anything animated also gets _preview/<name>.gif. Sheets expand anims into name_0, name_1, ... with durations and tags. pxl ascii prints every frame of an anim. The live viewer loops animated assets after the painting replay ends ("animate" toggle).

CLI

node <pxl>/bin/pxl.js build <file> [--out DIR] [--only a,b] [--scale N] [--no-preview]
node <pxl>/bin/pxl.js serve <file> [--port 4321] [--out DIR | --no-out] [--no-preview]
node <pxl>/bin/pxl.js ascii <file> <name>
node <pxl>/bin/pxl.js list  <file>

Outputs go to <file dir>/out: sprites/<n>.png, scenes/<n>.png, <sheet>.png + <sheet>.json (TexturePacker hash format: Phaser, Godot importers, ...), _preview/<n>.png (upscaled to ~768px, checkerboard behind transparency, pixel grid at scale ≥ 6 with every 8th line darker).

serve opens a live viewer that rebuilds on save, follows the asset you edited and replays its painting steps (each top-level op, layer and post-processing step, with its file:line). It also writes the same outputs as build.

Library

import { loadProject, loadSource, writeOutputs, serve, ascii, preview } from "pxl-pixelart";
const p = loadProject("art.px.js");
const img = p.image("slime");          // Img { w, h, data: Uint32Array of 0xRRGGBBAA }

pxl-pixelart/core exports the platform-independent engine (no Node APIs).