action-adventure-luna-xhigh — GAME.md

# Quarterly Synergy Quest — game manifest

## Game states and scenes

- `PlayScene` owns the connected world, player, NPCs, enemies, puzzles, HUD, inventory panel, and progression. The office hub is the starting region; the three dungeon regions are connected by locked gates in the same scene so the player can always read the larger arc.
- The ending is a scene-owned modal state inside `PlayScene`. When the Founder is defeated, the world stops accepting gameplay actions and a final three-beat founder dialogue runs through the dialogue addon. Restarting the page starts a fresh run.
- `PlayScene` transitions are spatial: `office -> atrium -> catacombs -> pitch-vault`. The office gate needs the brass keycard, the catacomb gate needs a completed dash traversal, and the pitch-vault gate needs the hacked elevator plus the two dungeon seals.

## Entities and components

- `Player`: transform, code-drawn avatar, physics body/collider, `Health`, `HitReceiver`, `Abilities`, `Facing`, `PlayerController`, and particle/light feedback. `PlayerController` updates facing and the attack telegraph from scheduled component updates. The entity emits ability effects through typed ability steps.
- `Enemy`: code-drawn actor, physics body/collider, `Health`, `HitReceiver`, `Stagger`, `PhysicsSteeringAgent`, and `EnemyBrain`. Variants are patrol, chase, and flee; `EnemyBrain` owns only the behavior switch.
- `Boss`: larger Hittable enemy with distinct health pools, a readable entrance, particle/light feedback, and dialogue-driven entrance/outro.
- `Npc`: code-drawn character, `DialogueActor`, and `DialogueController`. Dialogue scripts read the shared progression state and branch after the keycard or seal milestones.
- `PuzzleTerminal`, `Door`, `Collectible`, and `AmbientDetail`: each owns one interactable or visual responsibility. Puzzle consequences write to `ProgressState`; they do not reach into HUD code.
- Shared components: `Hud`, `ProgressState`, `PlayerController`, `EnemyBrain`, and `AmbientMotion` supplied by particle emitters and lighting.

## Communication

- Typed addon events carry `HealthDamaged`, `HealthDied`, `HitReceived`, `AbilityStarted`, `AbilityEnded`, dialogue events, and inventory events.
- The scene passes stable references to the player, inventory model, progression component, and HUD at composition time. HUD reads narrow state and does not mutate world state.
- A single `ProgressState` component is the scene-owned source for gates, dialogue branches, and the objective tracker. Dialogue uses `cells` to read it and commands to record story beats.
- No global event bus is required; all global-looking facts have a scene-owned owner.

## Directory strategy

Layer-first: `scenes/`, `entities/`, `components/`, `presentation/`, and `state/`. Feature folders are not mixed beside layer folders.

## Input and presentation

- `move`: WASD / arrow keys.
- `attack`: J / mouse primary — Paper Cut.
- `surge`: K — Synergy Surge.
- `dash`: Space / Shift — Deadline Dash.
- `hack`: E — Hack terminal / interact.
- `inventory`: Tab — open the addon inventory panel.
- `cancel`: Escape — close a modal dialogue or inventory panel.
- The HUD advertises these affordances immediately and updates the objective, area name, health, ability cooldowns, and item counts.
- Paper Cut shows a bright 54px attack wedge for 0.28 seconds. The hitbox is active from 0.06 to 0.18 seconds. Deadline Dash crosses about 200px in 0.30 seconds and shows a glowing audit seam in the atrium.
- Every ability has an action and puzzle role: Paper Cut trims the elevator's final red tape and hits enemies; Hack damages nearby hostiles and operates terminals; Deadline Dash clears the atrium audit seam and damages during its invulnerable burst; Synergy Surge damages crowds and activates the two relays.

## Items and save shape

- Inventory items: brass keycard, cold brew, red tape, and founder token. The inventory addon renders them in a visible panel and exposes Use actions for consumables plus Inspect actions for lore items.
- Save payload is intentionally session-only for this run. A future save would persist `ProgressState` plus `inventory.snapshot()`; no save plugin is installed because it is not part of this probe.

## Assets

- Visuals combine YAGE `GraphicsComponent` shapes with two CC0 Kenney assets copied through the `yage-assets` CLI: `public/assets/particle-slash-arc.png` is the Paper Cut sweep, and `public/assets/dungeon-brazier-lit.png` marks the room lights.
- The scene preloads both texture handles before it creates the sprite components. Particles use YAGE emitters, sound uses `@yagejs-addons/synth`, and lighting uses `@yagejs/lighting`.