# claygoo

> A browser physics platformer. Claygoo is a real soft body: a ring of 24 nodes with a
> heavy pilot ball rolling loose inside it, simulated in Matter.js. He has no legs and no
> walk cycle, so every move is him hurling that inner ball and letting the rest of the bag
> follow. A level is finished by collecting every star in it. Levels are plain JSON in a
> 560 by 560 world, and the game ships with an editor that draws that JSON.

Play it at https://claygoo.com. That URL serves the game and nothing else: no landing page,
no marketing, no docs site. This file is the reference for how the game plays and how a
level is stored, written for an agent that has no other context.

The source repository is private. There is no public code URL, no npm package, and nothing
to install. The game is a set of static files served over HTTP, and the only public
artifacts are the pages and JSON under https://claygoo.com.

Source paths below are named for precision and are relative to the repository's `game/`
directory: `play.html` is the game page, `editor.html` the editor, and `lib/` holds the
engine. They are pointers for anyone holding the repository, not URLs to fetch.

## Play it

https://claygoo.com opens level 1 of the shipped 40 level campaign. The shipped levels carry
no `name`, so the game labels them `level N` by position.

- `https://claygoo.com/?level=12` opens level 12. The number is 1 based and clamps into
  range. Every level change pushes history, so back and forward walk the levels visited.
- The left sidebar lists every level as a live thumbnail drawn from the level data. On a
  coarse pointer it becomes a drawer behind the `☰` button.
- Picking a level from the sidebar boots it paused behind a START overlay. Continuing from
  a completed level, replaying, or restarting skips that overlay.
- Progress is per browser, in `localStorage` under the key `claygoo.play.done.v1`. It holds
  an array of `"<index>:<name>"` strings, so a reordered or renamed pack forgets rather than
  crediting the wrong level. Only the built in pack is saved; an imported pack is a visit.
- A level ends when the last star is collected. That freezes the world mid tick and raises
  the LEVEL COMPLETE overlay. A level with zero stars can never be completed, because the
  completion check only runs inside a star collection.

The bar carries restart, fullscreen and a light and dark theme toggle. `⇪ import levels` in
the sidebar, or dropping a `.json` file anywhere on the page, plays your own pack instead, and
`built-in pack` returns to the shipped levels. **An imported pack is temporary: it records no
completion progress**, because only the built-in pack is tracked under that localStorage key.

The shipped pack lives at https://claygoo.com/levels/claygoo-levels.json and is fetched at
load, so the page needs a server. Opening the HTML from the filesystem fails on both the
fetch and the ES module imports.

## Controls

Keyboard, in play mode:

| key | action |
|---|---|
| `←` `→` or `A` `D` | move. On goo these crawl along the strip instead |
| `↑` or `W` | jump. On goo this climbs, and a third press away from the goo lets go |
| `↓` or `S` | duck. On goo this crawls down. Held alone for 3.2 s it becomes the pancake |
| `R` | restart the level (a page level binding, not an engine one) |
| `Enter` or `Space` | activate the first button of whichever overlay is up |
| `Escape` | close the level drawer or the options menu |

The game page passes `escapeExits: false` to the engine, so `Escape` never leaves play mode
there. In an embed that leaves the option at its default, `Escape` hands control back to the
host by switching the engine to `auto` mode.

Space is deliberately unbound as a jump. The engine embeds in scrolling pages, and a window
level `preventDefault` on space would steal scroll from a reader who never asked to play.
`lib/movement.test.js` asserts that space raises the body by less than 15 units.

On a coarse pointer the engine draws four 62px thumb buttons in two horizontal pairs, one
per thumb: `◀ ▶` on the left, `▼ ▲` on the right. They sit inside the safe area insets.

Ducking scales the whole body by `DUCK.scale` (0.65) over `DUCK.ease` (0.12 s), in the air
or on the ground, so he fits through gaps he otherwise cannot. Every size bearing quantity
scales together: both spring rest lengths, the pressure target by the square, `MIN_THICK`,
and the pilot ball's leash.

### How he moves, measured

These are the bands `lib/movement.test.js` enforces against the real engine, driven
headlessly. Design against the bands, not against a remembered number.

| move | contract |
|---|---|
| held run for 2 s on flat ground | travels 120 to 420 units, checked over three RNG seeds |
| standing jump, centroid rise | 35 to 75 units. `↑` and `W` agree within 8 |
| a 190 unit pit | uncrossable in the air on any seed |
| a lone vertical wall | one floor jump plus one wall kick, under 150 units of rise, however long you spam |
| a 90 unit shaft of two facing walls | gains more than 60 units over 12 alternating kicks |
| duck | squeezes below 80% of standing height and recovers above 85% |

The alternation rule is the reason a lone wall caps out: one wall yields exactly one kick,
and `lastWallDir` refuses a repeat until a floor contact, a rest on goo, or a respawn resets
it. Two facing walls are therefore a ladder while one tall wall is a genuine seal. Budget
level height against that split.

He cannot scoot up a slope; anything uphill has to be hopped. Faces up to 80 degrees from
horizontal still count as floors (`FLOOR_NY = 0.17` in `lib/blob.js`), so steep scrambles
stay hoppable, and only genuinely vertical rock is a wall.

### The cling and the goo crawl

Claygoo carries a `grip` value in `[0, 1]` that welds him to any surface he touches. Grip
charges on flat ground and drains under load, where load counts walls at 1.0 and overhangs
or ceilings at 1.6. At defaults that is about 1.0 s hanging on a vertical wall and about
0.63 s on a ceiling before he peels, and 0.35 s in clear air to recharge (`STICK` in
`lib/blob.js`). A flat floor contributes zero load, so standing still charges him.

Ink black **goo** strips painted on a terrain surface (`level.goo`) turn that countdown off.
Inside a goo strip the load is zeroed, so the weld holds him to a wall, an overhang or a
ceiling indefinitely, and holding a direction drives him along the strip at `GOO_SPEED`
(1.9 units per tick) instead of scooting. Direction is screen space and recomputed every
tick: the held arrow vector is dotted against the path tangent, so a turn sharper than about
63 degrees stops him and diagonals round a corner without stopping.

Getting off goo is graded, by design, so a held key can never launch him. A fresh cardinal
press pointing out of the goo loosens the weld one rung; the second press loosens it again
and leaves him dangling from a few pinned contacts indefinitely; only a third press in the
same direction fires the goo jump. Any movement input re sticks him to full instantly. The
jump key is the immediate, ungraded way out.

### The pancake

Hold `↓` alone, standing on a floor, with no other key held, for `PAN.charge` (3.2 s) and he
morphs over 0.3 s into a flat slab laid along the terrain surface. There is no charging
animation of any kind before the morph.

While flat he is invulnerable: `spikeTick` and `enemyContactTick` both return early on
`flatSafe()`, and that safety covers the whole morph plus a 0.25 s grace after standing up.
Enemies walk over him rather than through him. He cannot move as a body; instead `←` and `→`
walk his head along the top of him at `PAN.slide` (90 units per second), `↑` launches him out
of the pose, and `↓` stands him back up. A surface with no room for a slab refuses the morph
visibly and resets the charge rather than silently doing nothing.

### The ice cube

Touching an ice cube encases him and freezes him exactly in the pose he is in, hanging where
the ice formed. He does not fall, and a moving deck sweeps straight through him. The freeze
is a position fact, not a force: the 24 node positions and the pilot ball are captured once
and written straight back after every solve.

The controls collapse to a single job, aiming. A **fresh** direction press opens a 0.2 s
window (`ICE_WIN`); keys already held join the chord the moment it opens but can never open
it themselves. Per axis the last press wins, so `←` then `→` is a right launch rather than a
cancelled one, and all four directions count. At expiry the casket shatters and throws him
about 80 percent higher than an ordinary jump, roughly 89 units against 50. `lib/ice.test.js`
pins that as a ratio against a jump measured in the same test, never as a unit count.

Ice is not armour. `iceCollect()` runs before the kill checks, so grabbing a cube while
touching a spike consumes the cube and then kills you, and spikes and enemies stay lethal for
the whole freeze. He does still collect stars while encased, deliberately, and the last one
completes the level as usual. `ICE_LOCK` (0.25 s) bars any cube from catching him again
straight after a launch, so a cluster cannot eat his takeoff.

### The rotator

A rotator is a slowly spinning circled arrow in the same grey substance as the ice cube. It
spins in the direction it will turn the world. Touching one turns the whole level about the
centre of the square world, carries his live pose through the same quarter turn map, and
consumes the item. Gravity never rotates.

`turn[].turns` counts quarter turns counter clockwise, so `1` is a counter clockwise quarter
turn, `2` is a half turn, and `3` is the clockwise rotator: the data walks three quarters
counter clockwise, and the player sees one clockwise quarter turn sweep, which is the short
arc to the same place.

This works because the world is a 560 by 560 square while the screen only ever shows the
fixed central band, `y` from 130 to 430 (`VIEW_TOP`, `VIEW_BOT` in `lib/level.js`). The
viewport never moves. The strips of level above and below the visible band are real,
paintable space that becomes the left and right thirds of the view after a quarter turn.

Rotation is data, not a render effect: `rotateLevel(level, turns)` in `lib/rotate.js` derives
a new level record from the canonical unrotated one, and the engine rebuilds the world from
it. Derived orientations always come from the canonical record, never by re rotating a
derived one, because `560 - x` is not exactly invertible in floating point.

## The world

- **560 by 560 units**, fixed, `W` and `H` in `lib/level.js`. The canvas scales to its
  container with a `ResizeObserver` and DPR handling, but level coordinates never change.
- **The visible band is `y` in `[130, 430]`**, 560 by 300. Anything outside it is hidden
  until a rotator brings it into view.
- **`y` grows downward.** Higher ground means a smaller `y`. The shipped levels use `y = 402`
  as their ground floor.
- **Falling past `y = 490`** (`VIEW_BOT + 60`) restarts the level in play mode.
- Two static side walls sit just outside the frame, labelled `bound`. They are a fence, not
  terrain: zero friction, excluded from the cling, so they cannot be clung to, climbed or
  wall jumped. Terrain drawn flush to `x = 0` or `x = 560` is still real terrain.
- One tick is **1/60 s**, fixed. Velocities in the source are units per tick, not per second.
- Physics is vendored Matter.js **0.20.0**, loaded as a plain `<script>` onto `window.Matter`.
  The cling mechanic depends on 0.20 internals, specifically that `pair.separation` scales
  the static friction threshold in `Resolver.solveVelocity` and that `Pair.update` recomputes
  slop from body properties every tick. Upgrading Matter needs both re verified.

## What a level contains

| thing | behaviour |
|---|---|
| **terrain** | closed polygons with optional holes. The only shape model; hills, islands, caves and overhangs are all the same kind of thing |
| **stars** | the objective. Collected when a membrane node centre enters the drawn star (`STAR_R` 12) at its live bobbing pose. No padding, no sweep radius. They never respawn |
| **spikes** | no Matter body at all, just a per tick hit test against the drawn 14 by 16 triangle. They do not block movement, cannot be stood on, and kill on touch |
| **enemies** | an irregular 8 spike star, `E_R` 12. Contact kills instantly. The Matter body is the polygon whose vertices are the spike tips, and the enemy is a collision ghost to Claygoo, so the kill region is exactly the drawn art |
| **platforms** | moving one way decks, drawn 92 by 12, travelling along any line. Claygoo owns at most one deck at a time, so a deck can never hit him from the side or bisect him |
| **goo** | sticky ink strips painted along a stretch of terrain surface. See the cling section above |
| **ice** | floating cubes that freeze him and open the aim window |
| **turn** | rotators that turn the level a quarter, half or three quarter turn |

Two enemy brains. `type: "pace"` is a step roller: it does not slide, it tips the polygon over
onto its next face roughly every 0.45 s, and it reverses at a wall, a ledge, an unclimbable
riser ahead, or 2.5 s without forward progress. `type: "still"` has no brain but is still a
live rigid body that falls, collides and kills. A pacing enemy given `x1`/`y1` stops free
roaming and crawls the terrain boundary back and forth between the two points instead,
gripping walls and ceilings.

The enemy's tip jitter is re randomized on every restart, so an exact silhouette is never
reproducible between attempts. Design against its 12 unit envelope, not a particular shape.

Ties go to the player: `starTick` runs before the spike and enemy checks, and completing a
level freezes the world and short circuits them. Grabbing the last star on the same tick you
touch a spike completes the level.

## The level format

A level is plain JSON. A pack is `{ "v": 1, "levels": [ ... ] }`. The game's `readPack` also
accepts a bare array of levels or a single level object.

```json
{
  "v": 3,
  "name": "mesa",
  "spawn": { "x": 40 },
  "terrain": [{
    "pts": [[0, 402], [200, 402], [200, 330], [330, 330], [330, 402], [560, 402], [560, 560], [0, 560]],
    "holes": [[[230, 356], [300, 356], [300, 388], [230, 388]]]
  }],
  "platforms": [],
  "spikes": [{ "x": 460, "y": 402, "angle": 0 }],
  "goo": [],
  "stars": [{ "x": 265, "y": 300 }],
  "ice": [],
  "turn": [],
  "enemies": [{ "x": 100, "type": "pace", "dir": 1 }]
}
```

That is a 72 unit mesa with an enclosed cave inside it, a star on top, a spike on the flat to
the right, and a spikeball pacing the left. It normalizes without a single clamp, validates
with zero errors and zero warnings, and mounts and settles at spawn.

### The two `v` fields mean different things

This is the sharpest edge in the format.

- **`v` on the pack document is `1`.** It is the document format version and has not moved.
- **`v` on each level is `3`.** It is the coordinate world version, and it is the only thing
  standing between a level and a silent migration.

`normalizeLevel()` runs `migrateLevelV3()` first, and that migration treats a missing or
lower `v` as an old 560 by 300 band world level. It adds `V3_SHIFT` (130) to **every** `y` in
the record, then extrudes any polygon edge that used to rest on the old world floor down to
the new one. A hand written level that already uses square world coordinates but omits
`"v": 3` therefore has its whole geometry pushed 130 units down and its rings rewritten, with
no error. Stamp `"v": 3` on every level you author by hand.

Levels older than that still load. A v1 level is a `ground` heightmap plus a separate
`islands` list; `normalizeLevel` migrates it to polygons and then through the v3 shift.
Migration is one way and nothing writes the old shapes back out.

### Fields

`normalizeLevel()` in `lib/level.js` is the schema. It deep copies, fills defaults, clamps
into range, and throws on garbage such as a level with neither a usable `terrain` nor a
`ground` of at least 2 points.

| field | type | default | clamp | notes |
|---|---|---|---|---|
| `v` | number | treated as `2` | | stamp `3`. See above |
| `name` | string | `"level"` | | cosmetic. The shipped pack omits it and the game labels by position |
| `spawn.x` | number | `60` | `0 ... 560` | |
| `spawn.y` | number | ground at `spawn.x` minus 29 | `130 ... 430` | his **centre**, and it clamps to the visible band, not to the world box. Omit it and he settles on the surface; set it and he falls from there |
| `terrain[].pts` | `[x, y][]` | | `0 ... 560` both axes | **required**, at least 3 points. The closed outer boundary, winding does not matter |
| `terrain[].holes` | `[x, y][][]` | `[]` | same | closed inner boundaries, each carving an enclosed cave. Rings with fewer than 3 points are dropped |
| `platforms[].x0, y0` | number | `0`, `316` | x `0 ... 560`, y `20 ... 540` | the dock end, where the deck starts and returns |
| `platforms[].x1, y1` | number | `0`, `316` | same | the far end |
| `platforms[].speed` | number | `58` | `1 ... 400` | world units per second |
| `platforms[].pause` | number | `2.8` | `0 ... 30` | seconds held at each end |
| `spikes[].x, y` | number | `0`, `402` | `0 ... 560` both axes | should sit on the surface |
| `spikes[].angle` | number | `0` | *unclamped* | radians, `0` points up. Match the surface slope |
| `goo[].x, y` | number | | `0 ... 560` both | one end of a sticky strip. **Both endpoint pairs are required**; an entry missing either is dropped |
| `goo[].x1, y1` | number | | same | the far end. The sticky region is the surface walk between them, walls and ceilings included. A path shorter than `GOO.min` (12) is grown or the strip is dropped |
| `goo[].via` | `[x, y]` | *absent* | | optional witness point on the intended arc. Two endpoints cannot say which way round a closed ring once the strip passes half the perimeter. Absent means let length pick, which is every shipped strip |
| `stars[].x, y` | number | `0`, `0` | `0 ... 560` both | free floating, no support needed |
| `ice[].x, y` | number | `0`, `0` | `0 ... 560` both | free floating. Missing or non array `ice` becomes `[]` |
| `turn[].x, y` | number | `0`, `0` | `0 ... 560` both | a rotator's centre |
| `turn[].turns` | number | `1` | `1 ... 3`, rounded | quarter turns counter clockwise on touch. `3` reads as one clockwise quarter turn |
| `enemies[].x` | number | `0` | `0 ... 560` | |
| `enemies[].y` | number | topmost ground at `x` | `0 ... 560` | the **surface** it stands on, not its centre. Picks the layer when surfaces stack: a cave floor's `y` seats it inside the cave, the roof's `y` on top |
| `enemies[].type` | `"pace"` or `"still"` | `"pace"` | | anything not `"still"` becomes `"pace"` |
| `enemies[].dir` | `1` or `-1` | `1` | | initial **facing**. Anything not `-1` becomes `1` |
| `enemies[].x1, y1` | number | *absent* | `0 ... 560` both | optional patrol endpoint, both or neither. Turns a pacer into a boundary crawler between the two points |
| `enemies[].via` | `[x, y]` | *absent* | | the same optional witness `goo[].via` carries, resolved the same way |

`normalizeLevel` rebuilds the level from scratch, so any extra keys you attach are dropped.
Two sharp edges: it dereferences array members directly, so `"platforms": [null]` throws
rather than being skipped, and its platform `y` range is wider than the range the editor lets
you drag a deck to, so hand authored decks can sit where the editor will not put them.

`enemies[].dir` is a facing, not a winding, and must never be read as one. `goo[].via` and
`enemies[].via` are witness points precisely because a winding number describes the vertex
order of a terrain ring, and any boolean terrain edit relists those rings freely.

### Terrain becomes physics by vertical slab decomposition

`decomposeTerrain()` sweeps left to right, cutting at every vertex `x` and at every point
where two edges cross, so a self intersecting boundary still decomposes correctly. Between
two neighbouring cuts the shape is a simple vertical slab, and it emits one convex trapezoid
per solid interval in that slab. A column with a cave in it yields two stacked trapezoids,
roof and floor, with the void between them. Three consequences when authoring:

1. **A vertical riser gets no body of its own.** Its neighbours' slab side faces are the wall.
   Two points with the same `x` are how you build a cliff.
2. **A slab that tapers to a point still gets a body**, a triangle rather than a trapezoid.
   That is what makes the tip of an overhang solid.
3. **Overlapping polygons are one mass.** The queries union them and the editor fuses them on
   release.

Slabs tile the polygon exactly and every corner is a point of the polygon you drew, so the
collider is the drawn shape. A polygon whose boundary reaches the bottom of the world is
ground and gets extended down past the world edge so nothing tunnels underneath; a polygon
that floats clear is an island; a gap between two polygons is a pit.

### Design rules

- **Ship at least one star.** A level with none is unfinishable.
- **Terrain is closed polygons, not a heightmap.** A boundary may double back in `x`, which
  is exactly what an overhang is, and a column with no polygon in it is a hole.
- **Ledges: about 30 units is comfortable, about 55 is the hard ceiling on a single jump,
  about 94 across in the air.** A vertical face adds exactly one wall kick on top, roughly
  115 to 125 units total from its base floor. A lone wall taller than that is a seal, two
  facing walls are a ladder down to about 52 units of gap, and slopes up to 80 degrees are
  hoppable floors.
- **Stars collect on true touch.** Place a star where he can genuinely reach the art.
- **Keep spikes about 60 units from the spawn point.** The default spawn drops him about 5
  units and the landing splat spreads his membrane far enough to reach a spike up to about 45
  away. Measured: 60 is clean, 45 kills the first landing, 30 loops forever.
- **Spikes do not block.** A spike wall is a kill zone, not a barrier.
- **Enemies need real estate.** Give a pacer 60 or more units of walkable ground or it just
  oscillates on its turn cooldown, and it will never enter the outer 17 units at either wall.
  The values `17` and `543` are hardcoded in `lib/enemy.js` and assume `W = 560`.
- **Keep everything inside the visible band unless a rotator brings it in.** Standable
  surface in the hidden strips above or below `[130, 430]` is a validator error.

## The level editor

`editor.html` is the authoring surface. It is deliberately **not** deployed to
https://claygoo.com, because it saves by PUTing the pack back to
`levels/claygoo-levels.json`, which only the local dev server answers. On a static host the
save button would fail silently.

The editor lays every level out as a 560 by 560 square in a responsive grid, 3 columns at
1660px and above, 2 below that, 1 under 1000px. The full square always shows: the play band
stays paper coloured, the strips above and below sit under a grey overlay because they rotate
into side view, and the four corners are hatched because they are visible in no orientation.
Nothing is simulated while editing; each strip is a pure canvas render straight from the data.

Ten tools, each with a single letter shortcut:

| key | tool | what it does |
|---|---|---|
| `V` | select | click to pick anything, drag to move it. Vertices move freely, so dragging one back past its neighbour is how you get an overhang. Double click a terrain edge to insert a vertex, option click a vertex to delete it. Click a polygon's interior to select and drag the whole piece; push two together and they fuse on release |
| `G` | ground | freehand draw the terrain. Draw unions a brush in, erase subtracts a ribbon out. This is the tool that carves caves |
| `P` | platform | click to drop a deck. Drag the body to move the whole path, drag the ring at the far end to set the destination |
| `S` | spike | click near the surface. It snaps to the nearest ground point and inherits that segment's angle |
| `O` | goo | click near the surface. Drag either endpoint ring to stretch the strip along the same terrain piece, walls and ceilings included |
| `T` | star | click anywhere |
| `I` | ice cube | click anywhere |
| `U` | rotator | click anywhere. The bar then offers counter clockwise 90, 180, or clockwise 90, which write `turns` 1, 2 and 3 |
| `E` | enemy | click. It seats on the surface at or below your click, so clicking inside a cave stands it on the cave floor. Choose paces or still and the starting direction first |
| `C` | start position | move the spawn |

Also: arrows nudge the selection by 1 and by 10 with shift, `Delete` or `Backspace` removes
it, `Escape` clears the selection or stops a test play, `⌘Z` and `⇧⌘Z` undo and redo, and
`[`, `]` or `R` cycle the selected strip's orientation tab.

**The ground tool is the interesting one.** Your stroke becomes a brush shape, and that brush
is unioned into or subtracted out of the terrain as a real boolean operation, then re traced
into clean polygons. Scooping through the middle of a hill carves an enclosed cave; scooping
into a hillside gives an open cave mouth or an overhang; scooping all the way to the bottom
cuts a real pit. Edits keep the rest of the level consistent: spikes re seat and re angle to
the new surface, enemies follow their own surface, patrol and goo endpoints re snap, and a
buried or floating spawn is nudged back to standable ground.

**Orientation tabs and the validator.** The selected strip carries read only R0, R90, R180 and
R270 previews. R0 is the only editing surface; a rotated tab refuses edits and says so. Test
play honours the tab, so an R90 preview test plays the R90 world. A validator badge runs
`validateLevel()` from `lib/validate.js` over every orientation reachable from R0 by following
rotators, reporting errors coded `E1` through `E13` and warnings `W1` through `W8`. The
errors that matter most when authoring: `E4` a spawn outside the band or with no ground under
it, `E7` and `E8` standable surface in the hidden strips, `E10` a rotator straddling a band
edge, `E12` an item hidden in every reachable orientation. The validator does not claim route
reachability; that stays a manual test play.

The editor sends the whole JSON document back to that path as a debounced PUT after edits, and
the local server validates it and replaces the file atomically.

Documents autosave to `localStorage` under `claygoo-levels-v3` and, when a dev server is
answering, PUT to `levels/claygoo-levels.json` on every edit. The doc actions on the right of
the bar are copy JSON, which puts the whole document on the clipboard, download JSON, and
import JSON, which takes a paste, a chosen file, or a `.json` dropped anywhere on the page,
then asks whether to append the incoming levels or replace the pack. Imported levels are
normalized and lose their names.

Dragging a strip by its handle reorders the pack, which is also what renumbers the labels.

## Running it locally

```bash
cd claygoo
python3 serve.py
# http://localhost:8931/game/play.html    the game
# http://localhost:8931/game/             the footer demo plus the physics tuner
# http://localhost:8931/game/editor.html  the level editor
# http://localhost:8931/game/hitbox.html  the kill and collect region inspector
```

`serve.py` is `http.server` with `Cache-Control: no-store`, correct MIME types for ES
modules, and one addition: a `PUT` to a path under `game/levels/*.json` writes the request
body back to that file, JSON validated and written through a temp file then renamed. That
`PUT` is the editor's autosave, and it is why the editor needs this server rather than any
static one.

Two more packs sit beside the campaign in `levels/` and are **not** deployed:
`claygoo-ice-levels.json`, five levels each built around one ice beat, and
`claygoo-gauntlet.json`, five hard trials plus five wilds that are wacky and possibly
unwinnable. Import either into the game page to play it.

```bash
npm test              # node --test over game/lib/*.test.js and game/*.test.js
npm run equiv         # record and compare full physics traces
npm run deploy        # build site/ from play.html's import graph, then wrangler deploy
```

`npm test` drives the **real engine**, real Matter, real input path, real fixed step loop, in
plain node with no browser. `lib/test-dom.js` forges just enough DOM: physics and input are
real and only rendering and layout are stubbed. The assertion doctrine is predicates with
tick budgets, whole trace never events such as no death and no NaN, and wide bands taken from
the design contract. Never exact positions, golden traces, or tick exact timing, because
physics diverges across seeds and math builds.

`npm run equiv` is the gate for a change that is meant to change no behaviour. It replays 37
scripted goo scenarios and records full precision state every tick, plus a digest of path
sampling over every level, and reports whether two recordings are bit for bit identical. That
is reachable because the harness seeds `Math.random` and Matter is deterministic at a fixed
timestep. No baseline is checked in; record one before you start.

```bash
npm run equiv -- record /tmp/before.jsonl
npm run equiv -- record /tmp/after.jsonl
npm run equiv -- compare /tmp/before.jsonl /tmp/after.jsonl
```

`npm run deploy` walks `play.html`'s own import graph rather than a hardcoded file list, so a
new engine module joins the deploy the day it is imported, and copies the pack, the icons,
the social image and Matter alongside. `play.html` ships twice, once as itself and once as
`index.html`, because the root URL is the game.

## Embedding the engine

`mountGame()` is the whole runtime; everything else is data or drawing.

```js
import { mountGame } from './lib/engine.js';
import { normalizeLevel } from './lib/level.js';

const api = await mountGame(container, {
  level: normalizeLevel(raw),
  mode: 'play',                       // or 'auto' with a driver
  matterUrl: '/path/to/matter.min.js',
  colors: { body: '#232B36', eye: '#EFF1F4', soft: '#5C6675', amber: '#D98E2B' },
  tune: { jump: 11 },                 // partial override, merged over the defaults
  hooks: { onStar, onComplete, onRestart, onModeChange, onTurn, onOverlay },
});
```

Other options: `driver(dt, api)` steers the blob every tick in `auto` mode, `glued()` and
`latchFilter(i, api)` control deck rides for scripted runs, `logger(line)` gives 20Hz play
telemetry, plus `debug`, `debugText()`, `reducedMotion`, `paused` (boot settled but not
running, for a START overlay), `escapeExits` (default `true`), and `touchHost` (where the
thumb buttons hang).

The returned `api`: `setMode` and `getMode`, `setColors`, `setTune` and `getTune`, `setSpeed`,
`reset`, `restart`, `freeze`, `setPaused`, `isPaused`, `isFrozen`, `act('jump' | 'hurl', arg)`,
`debug()`, `bodyCounts()`, `destroy()`, plus live readers `blob`, `enemies`, `grounded()`,
`groundedN()`, `onFloor()`, `riders()`, `deckIndex()`, `platforms()`, `stars()`, `ice()`,
`turn()`, `terrainBodyCount()`, `tune` and `canvas`.

`onOverlay(ctx, { colors, blob, enemies, stars, spikes, clock })` is the odd one out. It is
not an event but a draw slot, called at the very end of rendering with the world transform
still applied, so a host can paint in level coordinates.

Twenty one `tune` keys apply instantly with no rebuild. The defaults, from `DEFAULT_TUNE` in
`lib/engine.js`:

```js
{
  gravity: 1, jump: 8.5, scoot: 5.5, cap: 13.5, wallJump: 4.5,
  heft: 4, ballGrav: 0, bounce: 0, airdrag: 0,
  launch: 'bulk', share: 0.34, pressGate: 0.25,
  leashClamp: 'on', stepRecenter: 'on',
  scootArc: 18, scootJit: 0,
  wallMin: 4,
  skin: 0.001, edge: 0.47, bend: 0.16, area: 1,
}
```

Go through `api.setTune()`, never `api.tune`. Sixteen of those keys are re read from the
object every tick, so mutating it directly happens to work, but `gravity`, `heft`, `skin`,
`bounce` and `airdrag` are pushed into Matter bodies inside `setTune` and do nothing if you
write the object yourself.

**Mount side effects**, which matter if you embed more than one or share the page with other
keyboard handling: `mountGame` appends a `<style>` to `document.head`, adds the class
`fg-root` to your container, and registers `keydown`, `keyup` and `blur` on **`window`**, not
on the canvas. `destroy()` unwinds all of it, so always call it.

## Gotchas

1. **`mountGame()` does not validate.** Call `normalizeLevel()` yourself. It reads
   `level.terrain` and `level.spawn.x` at mount time, so a level missing `spawn` is a
   `TypeError` before the first tick, not a soft failure.
2. **A level without `"v": 3` is silently shifted 130 units down** and its rings re sealed.
   See the two `v` fields section above.
3. **`matterUrl` defaults to a path outside `game/`**, at `../../character/vendor/matter.min.js`.
   Copying `game/` alone breaks it; ship a `matter.min.js` alongside and pass the path.
4. **Contacts lag one tick.** Input handling reads the previous tick's contact set, because
   the input step runs before `Engine.update` and the contact scan runs after it.
5. **Two contact questions, deliberately different.** `grounded()` is "at least one node is
   touching any static body", which a fence scrape satisfies. `onFloor()` is the strict one,
   "at least one contact whose surface is under him". The scoot and jump gates hang off
   `onFloor()`, never `grounded()`; gating them on any contact is what used to let him ladder
   up a wall by holding into it and tapping jump.
6. **`freeze()` is only mostly one way.** Visibility and scroll restarts refuse while frozen,
   but `setMode()` to a different mode clears it. Remount to truly reset.
7. **`api.setSpeed(m)` is a time scale, not a movement speed**, valid from 0.25 to 4. It
   changes how many fixed ticks fire, never the tick length, because the physics tuning
   assumes 60Hz.
8. **The rAF loop burns at most 4 fixed steps per frame**, so a background tab cannot fast
   forward. The game also pauses itself when scrolled offscreen or on a hidden tab, and under
   `prefers-reduced-motion` it runs 90 settle steps at boot and then freezes on that frame.
9. **A boolean terrain edit re traces on a 2 unit raster**, so it is not a perfect no op. Any
   draw or erase overlapping a polygon's bounding box re rasterizes that polygon, and
   vertices can shift by roughly half a step even where the stroke changed nothing.
10. **`17` and `543` in `lib/enemy.js` assume `W = 560`.** Change the world size and pacers
    turn in the wrong place.
11. **`lib/face.js` is vendored verbatim from `character/pass-blob.js`, but `lib/blob.js` is a
    fork of it.** Re copying `pass-blob.js` over `blob.js` would delete the entire cling
    mechanic and every game move.
12. **The editor trusts its own localStorage.** Its loader does not normalize, so a stored
    document missing one of the item arrays throws on boot and leaves a blank editor with no
    in UI recovery. Import and test play do normalize.

## Limits and non-goals

- **This is a game, not a library.** Nothing here is published, versioned or installable, and
  `mountGame` is not a supported public API. It is documented above because the editor and
  the game page both call it, not because it is stable.
- **The editor is local only.** It does not ship to https://claygoo.com and it depends on a
  server that answers `PUT`. There is no hosted level authoring and no level sharing service.
- **Progress is per browser and per device.** There are no accounts, no cloud saves and no
  leaderboards.
- **There is no scrolling camera.** The viewport is a fixed 560 by 300 band and a level is
  one screen. If you need more space, that is what rotators are for.
- **Nothing is multiplayer, and there is no audio.**
- **Rendering is entirely unverified headlessly.** The test DOM stubs every canvas call, so
  anything visual has to be checked in a real browser.
- **The physics is nondeterministic in a browser but deterministic under the test harness**,
  which seeds `Math.random` and drives a fixed timestep. Do not expect a level to play out
  identically twice on a real machine, and do not write a test that depends on it.

## Links

- Play: https://claygoo.com
- A specific level: https://claygoo.com/?level=12
- The shipped level pack: https://claygoo.com/levels/claygoo-levels.json
- Web app manifest: https://claygoo.com/manifest.webmanifest