PixelCraft for humans

Read it. Tweak it. Hand it back.

You never have to write PixelCraft to create with PixelPlace—your agent can do that. Learning a few lines simply gives you another way to steer: change a colour, nudge a shape, or understand exactly what your collaborator made.

Open Studio Browse the reference

The whole idea

A program starts with an exact canvas and named colours, then draws from back to front. The source stays readable, diffable, and reversible.

canvas 16x16
pal bg=#1a1c2c ink=#f4f4f4 heart=#ef7d57

rect 0,0 16x16 bg
rect 4,4 8x8 ink
px 6,6 9,6 bg
rect 6,9 4x2 heart

Three useful moves

Enough language to join the edit

Change a colour

Palette names make global art direction legible. Change one hex value; every use updates.

pal sky=#1a1c2c glow=#ffcd75
rect 0,0 16x16 sky
circ 8,8 3 glow

Move a whole form

Wrap related marks in offset. One pair of numbers moves the complete cluster.

offset 2,-1 {
  rect 4,5 8x6 body
  px 6,7 9,7 eye
}

Make a clean loop

A timeline declares its frames. Expressions keep motion consistent and easy to revise.

timeline 0..3 {
  each {
    circ 8,(8 - sin01(tt) * 2) 3 glow
  }
}

This reference comes from the same compiler documentation as the agent's get_pixelcraft_guide tool, so the human and agent learn from one source of truth.

Set up and draw

canvas WxH

Required. Set canvas size (1..256 per side)

canvas 16x16

version 0.1

Optional top-level language line pragma

version "0.1.x"

pal ...

Define indexed or named palette

pal bg=#1a1c2c skin=#ef7d57

pal :pico8 | :dawnbringer16 | :gameboy | :endesga32

Load a built-in palette preset

pal :pico8

pal+ ...

Explicit palette append syntax

pal+ :gameboy ui=#f0f0f0

pal name=#hex..#hex steps N

Gradient range (creates name0..nameN-1)

pal sky=#1a1c2c..#6eb5ff steps 5

let name = EXPR

Declare variable ($name to reference)

let size = 4

const name = EXPR

Declare semantic scalar symbol (forward refs supported in compiler flow)

const pulse = (sin01($t) * 4)

letpair name = PAIR_EXPR

Declare reusable pair alias

letpair spray = 8x4

defpt name = POINT_EXPR

Declare declarative point symbol (forward refs supported in compiler flow)

defpt flame = face +1,-1

box name X,Y WxH

Declare a named layout region with semantic points like topLeft and center

box hud 2,2 20x10

box name in parent dock POINT WxH [offset X,Y]

Dock a child layout region to a parent box edge/corner using matching semantic points

box footer in hud dock bottomRight 12x4 offset -2,-2

layer "name"

Create/switch layer (first created = back)

layer "details"

with layer "name" [clear] { ... }

Scoped layer block (desugars to push/layer/body/pop)

with layer "fx" clear { glow center 6 aura }

fade [layer "name"] FACTOR

Multiply the alpha of everything already on a layer by FACTOR (0..1); repeated fades make trails and afterimages that deterministically dissolve

with layer "trail" fade 0.8 { px ($x),($y) spark }

offset DX,DY { ... }

Scoped translation block: shifts all drawing inside by (DX, DY); expressions allowed, nested blocks compose

offset ($sway),($bob) { px 4,4 ink line 0,0 8,8 ink }

clear [COLOR|layer "name" [COLOR]]

Clear/fill active or named layer

clear layer "fx" #00000000

font "name" { glyph ... }

Bitmap font declaration (preamble)

font "tiny" { glyph "A" advance 4 { "11" "11" } }

push

Save drawing state (mirror, cursor, offset, color, layer)

push

pop

Restore most recently saved state

pop

px X,Y COLOR

Pixel (supports multi-point)

px 0,0 4,4 8,8 1

rect X,Y WxH COLOR

Filled rectangle

rect 2,2 4x6 2

orect X,Y WxH COLOR

Rectangle outline

orect 2,2 4x6 trim

line X1,Y1 X2,Y2 COLOR

Line segment

line 0,0 15,15 1

oline X1,Y1 X2,Y2 COLOR

Outline line segment

oline 0,1 15,1 glow

circ X,Y R COLOR

Filled circle

circ 8,8 3 glow

arc X,Y R START END COLOR

Clockwise arc stroke (0 degrees = +X)

arc 8,8 4 315 45 glow

ocirc X,Y R COLOR

Circle outline

ocirc 8,8 3 glow

ellipse X,Y RXxRY COLOR

Filled ellipse

ellipse 8,8 4x2 glow

oellipse X,Y RXxRY COLOR

Ellipse outline

oellipse 8,8 4x2 glow

poly X,Y ... COLOR

Filled polygon

poly 2,5 8,1 14,5 3

opoly X,Y ... COLOR

Polygon outline

opoly 2,5 8,1 14,5 3

glow X,Y R COLOR

Radial glow (fades to transparent)

glow 8,8 4 #ffcd75

dither checker|bayer|noise at X,Y WxH A B [seed N]

Two-color dither fill with deterministic mode/seed

dither noise at 0,0 16x16 bg fog seed 42

fill X,Y COLOR

Flood fill

fill 0,0 bg

color COLOR

Set current color for following commands

color skin

text "..." at X,Y font "name" color C

Render bitmap text (supports align/tracking/lineHeight/wrap)

text "HELLO" at 2,2 font "tiny" color skin align center

Position, compose, and animate

center

Canvas center keyword

circ center 4 1

+X,+Y

Relative coordinate from cursor

px +1,+0 2

cursor X,Y

Set cursor position manually

cursor 8,8

anchor name X,Y

Name semantic positions

anchor face 8,6

mirror :x|:y|:xy|off

Symmetry mode

mirror :x

group "name" [pivot X,Y] { ... }

Reusable code block with optional stamp pivot

group "eye" pivot 1,1 { px 0,0 1 }

bitmap "name" [pivot X,Y] { ... }

ASCII sprite definition with optional stamp pivot

bitmap "spark" pivot 1,1 { ".1." "111" ".1." }

tileset "name" tileSize WxH [seed N] { tile ... [weight N] }

Tile symbol library for tilemaps (preamble, supports deterministic symbol variants)

tileset "terrain" tileSize 8x8 seed 7 { tile "W" "window_off" weight 4 tile "W" "window_on" weight 1 }

tilemap "name" from "tileset" { ... }

Grid layout of tile symbols (preamble)

tilemap "field" from "terrain" { "GGSS" "G..S" }

stamp "name" at X,Y [opacity A]

Place group/bitmap

stamp "spark" at 4,2

stamp "name" at X,Y :flipx :flipy

Place stamp with flip

stamp "arrow" at 4,2 :flipx

stamp "name" at X,Y :rot90

Place stamp with rotation (90/180/270)

stamp "arrow" at 4,2 :rot90

stamp "name" at X,Y :center

Center bitmap footprint on target point

stamp "arrow" at center :center

stamp "name" at X,Y :pivot

Align the target's declared pivot to the target point

stamp "icon_sword" at 12,12 :pivot

repeat N step DxDy { ... }

Offset loop ($i = 0..N-1 inside)

repeat 4 step 2x0 { px 0,0 1 }

timeline A..B { each { ... } range C..D { ... } at N,M { ... } every N [offset O] { ... } }

Compact animation timeline that expands to frames

timeline 0..7 { each { px ($frameNumber,0) 1 } }

tile "name" at X,Y WxH [step WxH]

Region tiling (supports transforms)

tile "grass" at 0,0 32x32

map "tilemap" at X,Y

Render a tilemap using its tileset symbols

map "field" at 0,0

scatter "name" in X,Y WxH count N seed S

Random stamp placement (seeded PRNG)

scatter "star" in 0,0 32x32 count 20 seed 42

emit "name" at X,Y [count N] [spread WxH] [drift DXxDY] [time T] [vel VXxVY] [jitter JXxJY] [active A..B] [life L] [loop N] [fade] [seed S]

Seeded particle-like stamps with optional per-frame drift

emit "spark" at 8,8 count 10 spread 6x4 drift -1x0 time ($frame - 3) vel -1x0 jitter 2x1 life 6 loop 24 fade seed 42

Semantics worth knowing

Version pragma is optional and top-level only (version 0.1 or quoted variants like "0.1.x").
Palette indices are strict: 0..(palette_length-1); out-of-range values emit runtime errors and fall back to 0.
Default bitmap index chars are 0-9, a-z, and A-Z (indices 0..61).
Declaration names cannot reuse reserved keywords (for example drift); prefer names like driftVec or delta.
center behavior depends on command type; for visual stamp centering, use stamp ... :center.
Declare pivot X,Y on a group or bitmap, then use stamp ... :pivot for semantic alignment (great for icons and HUD parts).
Transforms apply to both bitmap and group stamps; flips are applied before rotation.
Editor bitmap local commit supports direct stamp placements (including transforms), scoped static repeat tracing, and scoped static tile tracing. scatter/emit, group-nested stamp paths, and unresolved/oversized repeat/tile expansions remain unsupported in v1.
Editor tilemap paint mode supports Target = Tilemap ... with direct map-instance picking, brush/erase cell edits, and source-mapped row commit. Group-nested map paths are currently not selectable for pointer painting.
Bitmap-target commit edits the shared bitmap source; the instance picker chooses mapping origin only, not a per-instance sprite clone.
emit is stateless per frame and deterministic for the same seed + frame/time/loop inputs.
Inside frame/frames, keep canvas, pal, group, bitmap, tileset, and tilemap in preamble.

You know enough. Make one change, look at the canvas, and let the conversation continue.

Create with an agent