moonlit-engine/docs/SPEC.md

# Moonlit Engine — design spec

A SCUMM-style, web-based adventure game **engine**. This repo is the engine
only: game ideas, art and music generation come later. The engine is
content-agnostic and data-driven — a game is a JSON spec, not code.

Status: v0.1 — core complete and tested (68 tests), web harness working,
asset *integration* in place, asset *generation* explicitly out of scope.

---

## 1. Design principles

1. **Headless core.** `src/core/` has zero DOM, zero timers, zero network.
   It takes an injected clock and emits events. Everything runs under
   `node --test`. The browser layer (`web/`) is ~150 lines of glue.
2. **Declarative everything.** Conditions, effects, dialogue, scenes and
   interactions are plain JSON. No `eval`, ever. Specs and saves stay
   inspectable, validatable and diffable.
3. **Report every problem at once.** The loader validates the whole spec
   in one pass and lists *all* errors (agents iterate on full error lists,
   not one crash at a time). Same house rule as the midi-playlist repo.
4. **Never declare success without a passing run.** `./tools/run_all.sh`
   (validate + tests) must be green before any claim of "works".
5. **Degrade gracefully while art doesn't exist yet.** Missing asset files
   draw labelled placeholder boxes and warn once per id. A game with zero
   art files is fully playable for design purposes.

## 2. Architecture

```
game.json ──► loader.js (validate + compile)        ┌─► canvas.js  (draws)
                │                                   ├─► hud.js     (verb bar / text box / squares)
                ▼                                   ├─► audio.js   (music w/ loop points, sfx)
engine.js ◄── tick(dt) from rAF or fake clock       └─► boot.js    (DOM glue, save slots)
   │
   ├── world.js      mutable state: room, inventory, flags, vars, characters
   ├── verbs.js      verb-coin interaction resolution
   ├── dialogue.js   branching conversation trees
   ├── walkable.js   polygons, clamping, Dijkstra paths
   ├── conditions.js JSON condition evaluator (no eval)
   ├── effects.js    JSON world mutations (no eval)
   ├── save.js       versioned JSON snapshots
   └── events.js     pub/sub; renderers/audio subscribe, core never calls them
```

The core emits events (`roomEnter`, `say`, `dialogueLine`, `playMusic`,
`walkStart`, …). Renderers subscribe. The core never knows a browser exists.

## 3. Lifecycle

Phases: `boot → title → menu → playing → ended`.

- **Title screen** — web layer's business (a DOM overlay in the demo).
  The engine exposes `newGame()`, `load()`, `startScene()`.
- **Intro** — just a *scene* (`scenes.intro` in the spec): timed slides,
  text, music, then `goto` the first room. Skippable (`skipScene()`).
- **Menus** (save/load/options/volume) — web layer; the engine exposes
  `hud.canSave()` and save/load APIs. Keeping menus out of the core means
  a future game can dress them however it likes.
- **Playing** — the verb/click/dialogue loop, with scene and dialogue
  overlays.
- **Ended** — an `endGame` effect sets `phase = "ended"`; clicks stop;
  the web layer shows the ending screen.

## 4. The game spec (game.json)

Top-level keys: `meta`, `startRoom`, `startInventory`, `walkSpeed`,
`defaultVerb`, `moveVerb`, `verbs[]`, `rooms[]`, `objects[]`,
`characters[]`, `interactions[]`, `dialogues{}`, `scenes{}`, `music[]`,
`sfx[]`, `assets[]`.

### Rooms & walkable areas
A room is a background asset id, one or more **walkable polygons**
(`[[x,y],...]` in a 640×480 coordinate space), an `entry` point, `exits`
(`{to, at:[x,y], label}`) and optional `onEnter` effects. The loader warns
(never errors) when an exit has no return exit — adventure convention, not
a hard rule.

### Objects
`{id, room, name, hotspot:{x,y,w,h}, takes?, tags?, sprite?}`. `takes:
true` objects leave the room once in inventory. `room: "*"` = everywhere.
`tags` feed tag-based interactions.

### Characters
Must include one with `id: "player"` (the walker). Others have a room,
position, sprite and tags. Characters render back-to-front by y.

### Verbs & interactions (the verb coin)
The verb table is free-form: classic nine-coin, modern two-verb, whatever.
Each verb has a label and a **default response** — the engine always
answers.

Interactions are a flat list:
`{verb, noun | tag, with?, conditions?, effects?, response?, priority?}`.

Resolution order: **exact noun id > tag > `*`**, then higher `priority`,
then spec order. Conditions gate each candidate; first full match wins.
`with` marks item-with interactions (`give mug to barkeep`).

### Conditions (JSON, no eval)
`{flag}`, `{not}`, `{all:[...]}`, `{any:[...]}`,
`{var, op: eq|ne|lt|lte|gt|gte, value}`, `{has: item}`, `{at: room}`,
`{here: character}`, `{dialogue, node}`, `{seen: scene}`.

### Effects (JSON, no eval)
`setFlag`, `setVar`, `addVar`, `give`, `remove`, `goTo`, `moveTo`,
`walkTo`, `say`, `playMusic`, `stopMusic`, `playSfx`, `startDialogue`,
`startScene`, `animate`, `endGame`.

### Dialogue
Named dialogues with a `start` node and a node map. Nodes: `speaker`,
`text`, then either `choices[]` (waits for the player; each choice has
`to`/`end`, optional `conditions`/`effects`) or `next` (auto-advances on
a timed hold) or neither (ends). Nodes can fire `onEnter` effects.
Mid-conversation position lives in world state, so saves resume
conversations. Finished dialogues are marked done and never auto-resume.

### Scenes (intro / cutscenes)
Ordered steps: `music`, `stopMusic`, `sfx`, `slide {asset, ms}`,
`text {text, ms}`, `wait {ms}`, `setFlag`, `startDialogue`, `goto {room}`.
Instant steps fall through; timed ones wait on the clock. Skipping jumps
to the final `goto`.

## 5. Game mechanics

- **Movement**: click a walkable point → pathfind (Dijkstra over boundary
  waypoints between polygons, endpoints line-of-sight joined) → the engine
  moves the player at `walkSpeed` px/s on `tick(dt)`. Clicks outside the
  walkable area clamp to the nearest edge. Doors are exits: walk verb +
  exit click changes rooms and fires `onEnter`.
- **Inventory**: `give`/`remove` effects; `has` conditions; taken objects
  disappear from rooms; the HUD lists names.
- **World state**: flags (booleans) and vars (numbers) — the only way
  stories remember things. Unknown flags read false / vars read 0, so
  specs may gate on flags created later.
- **Hit-testing priority**: characters → objects → exits → walkable floor.

## 6. User interaction

- **Verb then target** (SCUMM): select verb, click hotspot. No verb
  selected: click walks (or fires `defaultVerb` if the spec sets one).
- **Keyboard**: number keys 1–9 pick verbs, Esc clears the verb, Space
  skips scenes.
- **Dialogue squares**: choices render as buttons; hidden by conditions.
- **Touch**: single taps = clicks; works as-is via canvas pointer events.
- **The engine always answers**: unmatched interactions fall back to the
  verb's default response. Dead air is a spec bug, not an engine bug.

## 7. Save / load

Saves are plain JSON strings (`SAVE_VERSION = 1`, game-name tagged,
timestamped) — the web layer parks them in `localStorage`; the core never
touches storage. Loading rejects: bad JSON, missing/future version, wrong
game. Migration hooks exist for format changes. Mid-dialogue saves resume
at the saved node. Saving is gated off mid-dialogue/mid-scene (`canSave`).

## 8. Assets & audio — integration only

- **Asset manifest** in the spec: `{id, file, frames?, framesPerRow?,
  framesRows?}`. The engine references ids; the web layer loads files.
  Missing files → labelled placeholder + one warning. How files get made
  is out of scope (that's the ComfyUI / midi-playlist side, later).
- **Music carries loop points** — `loopStartMs` / `loopEndMs` per track,
  mirroring the MIDI repo's loop-marker convention. The web audio layer
  plays the intro head once, then loops the body forever. The
  *Moonlit Mangrove Calypso* track (bars 4–36 loop) is the reference
  example: `example/game.json` ships it with loop points set.
- **Formats**: images png/jpg/webp; audio ogg/mp3 (anything WebAudio
  decodes). Sprites are horizontal/row grids; frame timing per anim.

## 9. Testing policy

`node --test tests/*.test.js` — 68 tests, one file per module:
conditions, effects, walkable (incl. doorway traversal + unreachable
areas), loader (example validates clean; every error class reported in
one pass; dangling refs; symmetry warnings), verbs (specificity,
priority, condition fallthrough, with-items), dialogue (branching, timed
auto-advance, hidden choices, mid-dialogue snapshots), save (round-trip,
version/game rejection, resume), engine end-to-end (intro scene on the
clock, walking, clamping, take/give chains, dialogue gating, endGame),
render (manifest degradation, frame cycling, fake-canvas draw ops, HUD
model).

`./tools/run_all.sh` = validate example + full suite. Green or it didn't happen.

## 10. Conventions

- Coordinates: 640×480 room space, y-down, sprites anchored bottom-centre.
- Interaction precedence is spec order at equal specificity — put the
  conditional variant **before** the unconditional one.
- Dialogue nodes are named strings, not indices.
- Save format changes require bumping `SAVE_VERSION` + a migration.

## 11. Roadmap (deliberately not in v0.1)

1. Game idea + writing (the fun part, next session).
2. Asset generation pipeline: ComfyUI for backgrounds/sprites,
   midi-playlist → ogg for music, wired into the manifest.
3. Sprite animation polish (facing, walk cycles), character `animate`.
4. Multiple save slots, options menu, gamepad.
5. Room transitions with fades; parallax backgrounds.