healer-man/docs/BITE_SIZED_EDITOR.md

Bite-Sized spot authoring

Open GM Menu → Bite-Sized Editor, select a dungeon and spot, and use Go to spot. GM administration also provides the same entry. A selected character and an online GM account are required. Leave an online activity or Dungeon Race before editing.

The scene uses the normal renderer, movement, and hold-right-drag camera. The right panel scrolls and collapses to leave the world visible. Click the world or press Walk in scene, then use WASD to move, Space to jump, and hold the right mouse button to look. Focusing a panel control suspends movement and camera input until you return focus to the scene. The panel can stay open while you walk and place points.

• Select Party start, Random boss spawn, or an individual mob point. Walk to a grounded position and press Set here, edit coordinates/facing, or use Go to point. Cyan markers show all five party seats, yellow markers show mobs, and the red marker shows the random boss anchor.
• The searchable mob picker starts with the full parent dungeon. Other dungeons includes imported mobs and their source names. Each point is independent; repeated creature types are supported. Assets are prepared before previews.
• New spots start empty with After all mobs die. A zero-mob layout activates its boss immediately. Present from start activates it alongside the mobs. Ordinary bosses always come from the parent dungeon and are rolled per run.
• New spots use the parent's full geometry without the original artificial branch closures. Duplicates retain the copied spot's legacy closures.
• Test run exercises the draft with combat, completion, and no saved rewards, progression, checkpoints, or rankings. Return to editing starts another placement session. A test completion appears in the panel.
• Save & publish validates the draft's references, IDs, transforms, grounded anchors and reachable navigation. Keep at least one spot in every dungeon. Imported layouts also validate their retained permanent branch closures. A revision conflict or download/validation failure leaves the draft intact. Refresh published preserves a dirty draft; Discard restores published data. Drafts are held in this client session until published or discarded.

Runtime and persistence

shared/bite-sized-layouts.mjs owns normalization, gameplay identity, and independent deterministic location, spot, mob and boss rolls. Ordinary runs choose a spot uniformly within their dungeon and retain its creature types. Randomized activities keep the two existing source pools, choose an eligible parent dungeon and spot, then deal rolled creatures into those placements without replacement until a pool is exhausted. Both activity IDs remain unchanged for saves and network protocols.

BiteSizedRunSelection includes the complete immutable layout snapshot, its stable ID/gameplay revision, parent source, boss and resolved mob references. Checkpoints, online activities and race matches pin it. Publishing affects new runs; retries, offline cached resumes, party members and race opponents retain their snapshot. Legacy checkpoints keep the original layout, and legacy randomized runs preserve the original Stockades creature deal.

src/game/biteSizedLayoutRuntime.ts materializes placements over the selected parent definition. contentSourceDungeonId controls environment, navigation and artwork resolution. src/app/biteSizedLayoutContent.ts verifies that parent's content and selected creature assets before entry and retains a bounded preparation cache. Published configuration is cached in local storage; checkpoint snapshots do not depend on the latest configuration being available online.

server/bite-sized-layouts.mjs owns SQLite bite_sized_layout_config and immutable bite_sized_spot_revisions. Public reads use /api/bite-sized-layouts; authenticated GM reads/writes use /api/gm/bite-sized-layouts. PUT accepts { expectedRevision, config }. ?spotId=<id>&revision=<number> reads archived data, including removed spots; ?history=1 lists historical revisions. Gameplay edits create timing revisions, while renames retain the timing revision and immutable historical data.

Dungeon and race clear-time rankings include spot ID/revision alongside existing boss/difficulty dimensions. Existing results migrate to the original default spot, revision zero. Results carry spot names; timing screens expose spot and revision filters. Overall race wins keep their aggregate dimensions.

Generated owners and verification

Run npm run bitesized:generate after changing parent definitions, supported source creatures, or navigation assets. scripts/generate-bite-sized-layouts.ts emits shared/bite-sized-defaults.json and shared/bite-sized-catalog.json from the authoritative registry/templates. scripts/generate-bite-sized-navigation.ts emits a compressed API-side navigation surface/reachability index and bundles the same TypeScript floor validator into server/generated/. These artifacts must ship with the API server; the server does not need rendering downloads for validation.

Focused coverage lives in src/game/biteSizedLayouts.test.ts, src/game/biteSizedLayoutsStore.test.ts, src/app/biteSizedLayoutContent.test.ts and server/bite-sized-layouts.test.mjs, alongside the existing dungeon, content, checkpoint, online, race and input tests. Run npm run build and npm run release:check before delivery.

node scripts/playtest-bite-sized-editor.cjs runs Edge against an isolated temporary API database and the dev app at port 5173. Override BITE_SIZED_EDITOR_URL when using another dev port. It records WoW/RoM authoring, imported previews, both boss settings, completion and unranked safeguards, panel input gating, right-drag release without pointer lock, and randomized entry into distinct parent maps under playtest-artifacts/bite-sized-editor/.

Set BITE_SIZED_EDITOR_INPUT_ONLY=1 for a focused WASD, panel-focus, combat-gating and right-drag check. It writes editor-movement.png and movement-observations.json in the same evidence directory.