Every naming rule and config key on one page. Each section has a full page in docs/.
Illustrator SVG export, Object IDs: Layer Names. Upper-case prefixes, then -
or _. -2 copies keep their type.
| id | Inside | Does | Reports |
|---|---|---|---|
field |
walkable area | ||
section_<n>, border |
screens, in order | ||
negative-space |
field |
hole | |
ENTERABLE-<name> |
any | interior enterables/<name>.svg |
enter:, exit:<name> |
RESTRICTED-<name> |
any | enterable, locked | locked:, unlock:<name> |
REQUIRE-case-<c>, REQUIRE-state-<s>, REQUIRE-item-<i> |
RESTRICTED |
unlock condition | |
ENTER-building, ENTER-exit |
enterable | door in, way out | |
OBJECT-<name> |
any | area; empty: E | interact:<name> |
ANIMATE-<asset> |
OBJECT |
frames objects/<asset>_0.svg… |
animate:<asset> |
BREAKABLE-<name> |
OBJECT |
breaks; _damaged, _broken art |
break:<name> |
INVENTORY-<item> |
OBJECT |
an item to take, E: CHECK | take:<item> |
EVENT-<name> |
any | trigger area | event:<name> |
DEPTH-<name> |
any | stands on the ground, depth-sorted by its bottom edge |
Planned: ENTER-vehicle, MISSING-, SWITCH-, USABLE-.
Paths: PARENT/CHILD, such as RESTRICTED-storage-room/ENTER-building.
config/levels/<level>/level-design.json:
{ "version": 1, "start", "groups", "cases", "restricted": { "<name>": { "until", "type" } }, "look", "states" }
| State key | Value |
|---|---|
svg |
loads, none, layer-state-change, fade-out |
set |
{ "<case>": true or false } |
cases |
{ "<case>": { "condition": "alive = 0" } }, followed from this state on |
reset |
"level", or ["break:<n>", "animate:<layer>", "unlock:<n>", "case:<n>"] |
player |
spawn (left, right, path), after, animation (walk, idle), health (full, inherit, store), inventory (empty, inherit, store) |
spawn |
[{ group, type: "enemy", from (path or edges), count, pick (random, in-order), pool, order, animation, after, every, then (fight, flee), inherit }]; a pool entry is a name or { "enemy", "count", "re-render", "render": { "<part>": "<palette>" }, "name" } |
animate-layers |
[{ layer, position-x, position-y (SVG units from the art's place), type (linear, ease-in, ease-out, ease-in-out), duration, after }] |
next |
[{ "on": "<trigger>", "when": { "<case>": true }, "to": "<state>" }] |
groups.enemy.<name>: a crew written once; a state’s spawn of it wins key by key.
order: random, sequence, reverse, same (load), or a list of names; left
out, all at once after a door. Conditions: alive, alive:<group>, fled:<group>,
inventory:<item>, case:, state:, with = != < <= > >= and a number.
restricted type: once (default) or condition (open while it holds).
| Trigger | Is |
|---|---|
break: enter: exit: interact: animate: event: locked: unlock: lock: |
level events |
spawn:<group> defeated:<group> fled:<group> arrive:<state> |
design events |
take: use: drop: combine: look: talk: |
player events, every time |
case:<name>, state:<name> |
conditions |
Reports: state:, case: (turns true), spawn:, defeated:, fled:, arrive:,
unlock:, lock:, and animate:<layer> when a moving layer arrives.
No version: a draft, converted with notes.
| Command | Does |
|---|---|
npm run skills -- claude (copilot, codex, all) |
install the level-design skill for that agent; npm run skills:check says if a copy is current |
/level-design <what should happen> (Codex: $level-design) |
writes the brief, the design, a sandbox test and the art to-do |
node scripts/checkLevelDesign.js <level> --matrix |
the sandbox’s status line, then what every action does in every state, and the gaps |
node scripts/checkLevelDesign.js <level> --layers |
the art’s layers by kind, with the paths a design writes |
Catalog (a test’s "items", such as config/debug/items.json):
{ "slots": 8, "items": { "<id>": { name, art, look, stack, use, consume, combine } } }.
use: { "heal": 25 }, { "scatter": 1 }, { "say": "..." }.
| Key | Does |
|---|---|
| E at an item | what it is; take it? YES / NO |
| I or Tab | the item screen: USE, CHECK, COMBINE; Esc back |
| Ctrl+I | the command line: look, talk, use <item>, take <item>, inventory, help |
<Name>.svg · <Name>_<action>.svg · <Name>_<action>_<n>.svg (from _0, no gaps).
Enemies in config/enemy-assets.json: "<animation>": { "mode", "suffixes" }.
| Mode | Plays |
|---|---|
hold / loop / sequence / yoyo |
one pose / cycles / once / 0 1 2 1 0 |
Suffix lookup: literal file, then another animation’s frames, then _0, _1, …
New enemy: art, config entry, ENEMY_DEFS line in js/entities/enemy.js.
Recolor: a design’s pool entry { "enemy", "render": { "<part>": "<palette>" } }, palettes in
config/palettes.json; each shape takes its tone (vest-mid → mid), outlines stay.
| File | For |
|---|---|
assets/objects/Object_Box.svg, _Damaged, _Broken, Object_Health.svg |
crates and pickups |
assets/levels/<level>/objects/<asset>_0.svg… |
ANIMATE-<asset> |
assets/levels/<level>/objects/<name>_damaged.svg, _broken.svg |
BREAKABLE-<name>, artboard the size of the piece |
Playback: sandbox levelMap.animate: { "<asset>": { "mode": "loop" | "yoyo" | "hold", "fps": 6 } }.
config/debug/sandbox.json: { "active", "tests": { "<key>": { level, scene,
design, items, inventory, spawn, cfg, levelMap, enterables, enemies, checklist } } }.
Read on every RESTART. Console: map table and warnings. Show Hitboxes: outlines
and the design’s state box. ITEMS block: GIVE, USE, DROP.