Makone — Make Worlds with Code

You are in a world-building repo. There is no agent layer here: you (your coding agent) are the agent, skills/ is your knowledge, harness/ is your eyes and hands, and the work lands in worlds/<name>/.

Read first

1. docs/principles.md — scar-tissue axioms, re-read before every session
2. docs/architecture.md — layers, contracts and the reasoning behind them

Routing: what does the user want to build?

Five layers of skills: world/ overall workflow · craft/ general craft · game/ game-specific · object/ single-object-specific · three/ API reference. Every skill directory has a SKILL.md — its index, routing problem → page. Read that one file, then pull only the page you need; skills/SKILL.md is the index of indexes. Everything in this repo — code, comments, docs — is written in English. Talk to the user in their own language.

Hard rules (non-negotiable)

1. Brief first: before touching code, nail down one specific feeling worth being obsessive about, and write it into the brief field of world.json — one sentence, concrete enough to smell. Then commit to a lighting key in the same file — natural (the default) · low · high. verify measures the frame's value range and fails a world that contradicts its own key (skills/world/SKILL.md step 3). This exists because "brief first" pulls hard toward dusk, night and rain — evocative writing does — and darkness is the cheapest way to hide unfinished form. Going dark is allowed; drifting there is not.
2. Only a closed loop counts as done: after changing code you must run node harness/capture.mjs <name>, look at the shots yourself, and self-assess honestly against the skill's standards. No screenshot evidence, no claiming it's done. Past the first round, shoot it --against the last one: judging a new frame against your memory of the old one is how a regression survives a review that looked at it. The single-file HTML is part of done, not a follow-up — a passing verify writes it for you, and export.mjs --check fails if a module world has none.
3. Pure-code assets: no external GLTF/texture libraries. Form = procedural geometry + CSG + shaders, characters = mannequin-js.
4. Complete contract: every world exports createWorld(container) satisfying the runtime/world.js contract. Capabilities are not declared — implementing seekTo means you have a timeline, implementing act means you're playable; the harness probes for it (architecture D6).
5. Reuse, don't rebuild: when an existing work has to move to a new contract, change the wiring only — entry point, loop, contract methods. Its geometry, materials and tuning are the author's. If you want a different work, make a new one.
6. Physics is opt-in: only put Rapier on things that must move; quality comes first.
7. checkpoint = git commit: one commit per milestone, roll back with git.

worlds (details in worlds/README.md)

Flat structure, one world per directory; the category is a property inside world.json, not a directory: type (scene/game/object, an open set). format is module for every world. worlds/index.json is generated by harness/catalog.mjs and is the sole data contract for the gallery and downstream sites. New works are always module format, named with a single lowercase word (no - or _).

Common commands

node harness/serve.mjs                      # local static server (open http://localhost:5180/ for the gallery)
node harness/create.mjs <name> --type scene --brief "..."
node harness/capture.mjs <name> --shots 4   # orbit shots; --arc a0,a1 for walled scenes; --at 0,0.5,0.9 for timelines; --after s to simulate first
node harness/capture.mjs <name> --hero      # ONE frame at 1920×1080 — the look-before-you-call-it-done shot
node harness/capture.mjs <name> --against   # the same frames again, beside last round's, with a
                                            #   number on each. Shots are overwritten every run, so
                                            #   without this every round is judged against MEMORY of
                                            #   the last one — which is how a world lost a starfish
                                            #   under its own floor for two rounds and nobody noticed
                                            #   something had stopped being in the picture.
                                            #   Declare `capture.views` in world.json (named eye/at
                                            #   viewpoints) so the labels are stable and the
                                            #   comparison means something.
node harness/capture.mjs <name> --play 62,250  # PLAYABLE worlds: drive it through pilot.js and shoot at those
                                            #   simulated seconds. Without it a game is only ever photographed
                                            #   standing still on its first frame — two of the games in here have
                                            #   a complete visual record of four shots of their own title card.
                                            #   Combines with --hero: `--play 64 --hero` is the money shot.
node harness/verify.mjs <name> --quick      # ~15s: does it still LOAD, is the console clean, is the
                                            #   exported bundle still current. Nothing else. Run it after
                                            #   any edit you were about to call done without looking —
                                            #   a world sat broken for a whole round because a string
                                            #   replace missed and nothing had loaded it since
node harness/probe.mjs <name> --scout x,y,z --dist 0.3   # WHERE can this point be seen from? one ray per
                                            #   candidate, so a whole sphere of viewpoints costs less than one
                                            #   screenshot. A camera inside a wall and a camera looking at a wall
                                            #   render the same rectangle — hunting a viewpoint by re-rendering
                                            #   is a slot machine, and this is the way out of it
node harness/probe.mjs <name> --look a,b,c --at x,y,z   # is that sight line clear, and what blocks it
node harness/probe.mjs <name> --rows        # evenly spaced rows of instances that are inside each other
node harness/verify.mjs <name>              # console errors / contract / budget / frameMs, JSON output (module format only)
                                            #   a PASS also refreshes worlds/<name>/<name>.html (--no-export to skip)
                                            #   read `warnings`: material traps that render as "too dark" and
                                            #   look like lighting bugs (skills/three/instancing-traps.md)
                                            #   read `hands`: real pointer + key input is driven at the world
                                            #     and every control it drew is pressed while the world ticks.
                                            #     A control that is REBUILT while the button is held can never
                                            #     be clicked (a browser only fires click when down and up land
                                            #     on the same node) — that is a hard failure, and it is how a
                                            #     crafting panel became unusable with every other gate green
                                            #   read `rows`: repeated parts whose neighbours intersect. A row's
                                            #     pitch bounds it in ONE direction and most published dimensions
                                            #     are the other one (docs/principles.md E16)
                                            #   read `chroma`: sat + hue spread. spread < 0.15 is a monochrome —
                                            #   `luma` cannot see that, and it passes every key (skills/world step 3)
                                            #   a world with a long cycle names the moments that must be judged,
                                            #   each with its own key — otherwise only its first six seconds are
                                            #   ever measured and the night never reaches the gate:
                                            #     "verify": { "at": [ { "s": 2,  "key": "natural", "name": "day" },
                                            #                         { "s": 64, "key": "low", "name": "night" } ] }
node harness/sweep.mjs                      # run verify across the WHOLE library and report
                                            #   what has rotted. Nothing else re-measures the
                                            #   worlds: export.mjs --check only compares a
                                            #   bundle's hash to its sources, so a world can sit
                                            #   on main failing its own declared key for months
                                            #   — rooftop did (docs/principles.md E14). A sweep
                                            #   is a MEASUREMENT: every child runs --no-export,
                                            #   so it cannot quietly rewrite 66 bundles.
                                            #   --quick for the cheap tier, --changed for just
                                            #   what git says you touched, --jobs N for width
node harness/botplay.mjs <name>             # playable worlds only: fly the whole thing through worlds/<name>/pilot.js
                                            #   the pilot lives OUTSIDE the world and uses only observe/getState/act.
                                            #   An autopilot inside main.js proves nothing (docs/principles.md E11)
node harness/export.mjs --check             # gate: every module world has a single-file bundle, and every
                                            #   bundle still matches the source beside it (each one carries
                                            #   a hash of the sources it was built from)
node harness/catalog.mjs                    # regenerate index.json after editing world.json (--check for a gate)

Never reference a file that does not exist. The scripts in harness/ and the skills in skills/ are the complete committed set; if a workflow seems to call for something else, check that it is there before you write it into a doc, a comment or an instruction to the user.

One exception, and it exists because it cost a session: the covers next to every world (cover.png / cover.gif / cover.anim.webp) are NOT made by anything in harness/. They come from an uncommitted local script, .local/cover.mjs — one run, one camera, one set of frames, three encodes. .local/ is gitignored, so it is missing from a fresh clone and invisible to ls harness/ and to git log. Look there before you write a cover script; one was written from scratch here, and it produced a cover that did not match the gallery it was going into.