← all games

action-adventure-fable-max — GAME.md

# Moonfall Cove

Top-down action-adventure vignette. The moon fell into the harbor three nights
ago; you are Pip, Assistant Lantern Clerk (Third Class), on your first night
shift. Find out where the moon went and put it back. Tone: warm, deadpan,
gently absurd.

## Story arc

1. **Beginning (Cove):** Mayor Cormorant (not three herons in a coat) explains
   the situation and unlocks the west gate once you re-light the three dock
   lanterns in the right order.
2. **Middle (Fen, Caves):** Widow Plume's mail moths are grounded in the dark.
   Re-light her moth-lamp and she teaches you the Moth Tether. The lighthouse
   cellar key was carried into the Tide Caves; getting it needs the Tether
   (pearl-and-plate puzzle) and the Burst (brazier gates). Lore reveals the
   moon wasn't stolen — it dove in on purpose, to comfort something crying in
   the lighthouse cellar.
3. **End (Lighthouse):** The crier is the Gloam, sixty years of swept-up dark
   living in the cellar. It swallowed the moon like a nightlight. Boss: light
   braziers to daze it, tether its shell plates off, burst its core — it pops
   into a shy Gloamling. Carry the moon (inventory item) up to the lamp cradle
   and the lighthouse launches it home. Epilogue dialogue everywhere; the
   Gloamling adopts the lighthouse lamp as its nightlight.

## Areas (one scene, spatial zones, camera-bound rooms)

| Zone | Position | Content |
|---|---|---|
| Harbor Cove (hub) | center | Mayor, Auntie Brine's jam stall, 3-lantern puzzle, signs, harbor + fallen-moon hole in the sky |
| Whispering Fen | west | Murkles patrol, Widow Plume + moth grove (Tether unlock), echo-stone lore cache, cave mouth |
| Tide Caves | north | dark rooms, brazier gates (Burst), pearl/tide-plate puzzle (Tether), Shellback Murkles, key chest |
| Lighthouse Cellar | east | boss arena: 4 braziers, the Gloam |
| Lamp Room | above cellar | finale: lamp cradle, moon launch, epilogue |

## Player abilities (`@yagejs-addons/abilities`)

- **Glow Burst** (`attack`: Space/J, touch A): radial flash. Combat: damages +
  stuns Murkles (they flee while lit). Puzzle: lights lanterns, braziers,
  moth-lamp, gloom-lilies. Cooldown ~0.8 s.
- **Moth Tether** (`tether`: K/E, touch B): beam that grabs the nearest
  tetherable in front: pulls pearls onto plates, yanks shell plates off
  Shellbacks and the boss, pulls loose pickups to you. Unlocked mid-game by
  Widow Plume. Cooldown ~1.2 s.
- Gating: Fen gate needs the lantern puzzle (Burst); caves inner door needs
  pearls placed (Tether); cellar needs the Rusty Key.

## Inventory (`@yagejs-addons/inventory`)

Items: `moon-jam` (consumable, heals 2 hearts, stack 5), `rusty-key` (key
item, opens cellar), `the-moon` (key item, finale), `tide-charm` (lore
trinket from echo stones, optional). Panel on `inventory` (I/Tab, touch Y);
`use` action wired to healing.

## Enemies (`@yagejs-addons/steering`)

- **Murkle:** patrol = followPath loop (per-spawn waypoints) or wander+contain;
  chase = pursue player inside 140 px; flee = flee player ~2.5 s after a Burst
  hit. TouchDamage 1 heart. 2 Burst hits to pop.
- **Shellback Murkle:** shell = Burst-immune; Tether removes shell, then as
  Murkle.
- **The Gloam (boss):** slow pursue; braziers gutter out; ≥3 lit ⇒ dazed
  (core exposed); tether 3 shell plates off; then Burst core ×3; each core hit
  speeds it up and spawns 2 Murkles. Non-lethal ending.

## Dialogue (`@yagejs-addons/dialogue`)

Compact DSL scripts, one shared DialogueController on a host entity, box
presenter + speech-bubble barks. Storage cells bridge story flags/inventory
(`has_item(...)` function). NPCs: Mayor Cormorant (4 story stages), Widow
Plume (3 stages), Auntie Brine (jam via compliment choice), the Moon, the
Gloamling, plus narrator signs.

## Input actions

`left/right/up/down` (WASD+arrows, virtual stick), `attack` (Space/J, touch A),
`tether` (K/E, touch B), `interact` (E/Enter, touch A doubles via proximity —
dedicated touch button C), `inventory` (I/Tab, touch Y), `cancel` (Escape),
`sort` (R), `move-up/-down/-left/-right` (menu nav, share WASD/arrows), `skip`
(Escape, dialogue). Dialogue/inventory focus policy: abilities and movement
gate off while a modal UI is open; dialogue and inventory never open together.

## Presentation

- 960×540 virtual, letterbox. Night palette: indigo `#141b30` base, slate-teal
  ground, amber light `#ffc45e`, coral accent `#ff7e6b`, moon cream `#f2ecd8`.
- All visuals code-drawn (GraphicsComponent + runtime textures). Player is a
  cream-cloaked figure carrying a lantern on a pole (identity = light).
- Lighting: dark overlay per zone + additive glow sprites; lantern flicker;
  bloom on the glow layer; vignette at screen scope; fireflies, mist, moth
  particles; y-sorted world layer.
- Audio: hand-rolled WebAudio synth (no asset files) — pad drone, waves,
  crickets, buoy bell, cave drips, wind; SFX for every action (burst, tether,
  pickup, dialogue blips, hurt, pop, door, plate click, ignite, heal, quest
  stinger).

## Status: complete and verified

Full loop plays start to finish from a fresh page, driven by real keyboard
input, `tsc --noEmit` and `vite build` both clean, zero disabled
components/systems across the run.

## Source map

- `main.ts` — engine boot: renderer 960×540 letterbox, physics (no gravity),
  input action map, particles, UI, debug. Registers `GameState` + `Synth`.
- `state.ts` — `GameState` (flags, shared `Inventory`, dialogue var storage,
  HUD pub/sub, derived `uiBlocked`), item catalog.
- `palette.ts` / `collision.ts` / `traits.ts` / `events.ts` — shared vocab.
- `audio/synth.ts` — all sound: WebAudio synth, 5 crossfaded ambience beds +
  scheduled one-shots per zone, one SFX method per action.
- `fx.ts` — runtime particle/glow textures, glow children, ring/poof/beam/
  floatText one-shots, `GlowFlicker`, `Lifetime`.
- `world/` — `zones.ts` (rects, darkness, respawns), `builder.ts` (per-zone
  art + walls + door specs), `populate.ts` (props/NPCs/enemies/boss),
  `ambient.ts` (per-zone ambient particles).
- `entities/` — `Player/`, `Murkle` (+ Shellback), `Gloam` (boss), `Npc`,
  `Door`, `Wall`, `props/` (Lantern, Brazier, MothLamp, EchoStone, Pearl,
  TidePlate, GateBars, Pickup, Chest, Sign, LampCradle).
- `abilities/defs.ts` — Glow Burst + Moth Tether ability defs and steps.
- `dialogue/` — `scripts.ts` (compact-DSL conversations + signs + barks),
  `service.ts` (box + bubble controllers, focus policy).
- `quests.ts` — `QuestDirector`: prop events → flags, objectives, spawns,
  puzzle logic, finale.
- `ui/hud.ts` — hearts, ability icons + cooldown, objective, toasts, zone
  banner, billboard interact prompt.
- `scenes/GameScene.ts` — layers, camera, darkness/travel, faint/respawn,
  wires everything; dev-only `window.__moonfall` probe bridge.

## Verified (Inspector freeze+step, real keyboard input, fresh page)

Mayor conversation (all branches) → movement unlocked immediately after
(soft-lock guard) → lantern puzzle both orders → gate travel → Plume + moth
lamp → Tether teach → cave-mouth walk-in → gate braziers → pearl/plate puzzle
(real Tether) → Shellback shell-off → chest/key → cellar door (key gate) →
full boss loop (light/daze/pull ×3/burst-core ×3 with relights, jam heal) →
Gloam pops → Gloamling + moon spawn → moon pickup → lamp stairs → cradle
finale → epilogue flags + restored sky + movement intact. Mobile viewport:
virtual stick + ✦/◉/💬/☰ buttons drive burst, move, and open the bag via real
touch PointerEvents. Audio: every SFX method + 5 zone ambience mixes fire
without error.

## Save

None (single-sitting vignette).

---

Update this file after every implementation step.