GRD: Escape the Dungeon - Game Requirements Document

Document Status

• Owner: DungeonBreak docs/lab team
• Date: 2026-02-28
• Status: Living document (gameplay discovery loop; roadmap Phase 19 complete)
• Location: .planning/GRD-escape-the-dungeon.md
• Relationship: Complements PRD (architecture, scope) with concrete gameplay behavior.
• Simulation north star: scratch/game-state.md, .concept/PROCESS.md, .concept/SIMULATION-AGENT-GUIDE.md
• UI components: .planning/UI-COMPONENT-REGISTRY.md, .planning/KAPLAY-INTERFACE-SPEC.md
• Code reference: docs-site/lib/escape-the-dungeon/

Purpose

The GRD defines how the game plays: concrete turn flow, formulas, prerequisites, and state changes.

• PRD defines what we are building and why.
• GRD defines how the runtime behaves.

Gameplay Discovery Loop

Scope -> Simulate (scratch/game-state.md) -> Check -> Refine (discovery artifacts) -> Emit -> Sync back -> repeat

1. Scope: define a simulation goal (example: trigger skill evolution and one cutscene chain).
2. Simulate: play in chat or browser and log updates in scratch/game-state.md.
3. Check: confirm expected behavior, identify gaps.
4. Refine: capture discoveries in .concept/DISCOVERY-LOG.md and backlog in .concept/CONTENT-BACKLOG.md.
5. Emit: update this GRD when behavior contracts change.
6. Sync back: once code ships, ensure GRD reflects implementation.

Core Identifiers

Depth and level are separate everywhere (state, UI, logs, tests).

Turn Loop (Concrete Order)

For each player action:

1. Parse input to action.
2. Prerequisite check (room, stats, skills, target, state).
3. Execute action effects.
4. Apply room vector influence (room_base * 0.05, clamp traits to [-1, 1]).
5. Write deed and project deltas (per-feature cap 0.22, global cap 0.35).
6. Evaluate skill unlock/evolution availability.
7. Resolve cutscene triggers.
8. Resolve deterministic global events.
9. Spawn one hostile from exit room (cannot enter rune_forge).
10. NPC tick: each NPC chooses one legal action.
11. Persist autosave snapshot.

Action Effects

Action Prerequisites

Deed Memory Model (Including Misinformation)

Deeds are stored as information vectors and can reference self or other entities.

DeedMemory contract:

• deed_id: stable id
• actor_entity_id: who did the action
• subject_entity_id: who the deed is about (self or other)
• canonical_text: normalized deed text
• embedding: deterministic vector projection
• belief_state: verified | rumor | misinformed
• source_entity_id: who supplied the information
• confidence: float in [0, 1]
• timestamp_turn

Rules:

1. Entities can hold incorrect deeds about others (belief_state = misinformed).
2. Dialogue can spread correct or incorrect deeds.
3. Action scoring may consume deed beliefs regardless of correctness.
4. Verified observations can overwrite misinformed beliefs when confidence is higher.

Combat Encounter Model (No Grid)

Combat is encounter simulation, not a positional grid.

Turn model: Opening or closing the combat UI does not spend a turn. Each fight or flee choice is a dungeon turn. Combat resolution advances time; browsing the combat screen does not.

Inputs to resolution:

• Equipped gear and weapon tier
• Entity attributes and derived level
• Traits/features (including momentum and survival)
• Active effects/passives
• Room context modifiers
• Opponent profile and faction relationship
• Internal skill-priority policy

Player controls in combat are high-level only:

• fight
• flee

flee contract:

1. No hard-fail roll.
2. Player chooses direction.
3. If direction is legal, player moves immediately.
4. Enemy does not get a same-turn free counteraction.
5. Enemy can pursue in later turns under normal movement logic.

Dialogue choices are non-combat flow and do not replace encounter resolution.

Room Vectors (Base, before 0.05 scale)

Fame Formula

• Base: 1.0 * (effort_spent / 10)
• Room interest: 0.6*Projection + 0.4*Levity + 0.25*Direction + 0.2*Survival
• Novelty multiplier: 0.75 if repeat stream, else 1.0
• Risk multiplier: combat 1.0, treasure 0.6, other 0.35
• Momentum bonus: Momentum * 0.04
• Skill bonus: +0.15 if Battle Broadcast unlocked
• Diminishing factor: 1 / (1 + Fame / 120)

Act and Chapter Structure

• Acts: 1, 2, 3 (four chapters per act; 12 levels total).
• Chapter: One depth corresponds to one chapter. Ascending depth completes a chapter.
• Chapter complete cutscene: Fires when player ascends (e.g. "Chapter Closed"). Per-chapter boss or narrative cutscenes are content-driven.
• Opening narrative: When starting a new game, show a narrative from the player's first-person perspective: they find themselves at the bottom of the dungeon, not knowing why or how they got there, and are trying to escape. Same engine; gridless first-person UI is descriptive only.

Cutscene Triggers

Global Events

Skills (Unlock and Evolution)

Perception branch is exclusive: Appraisal and X-Ray cannot both be unlocked in one run.

Traits and Features

Traits (range [-1, 1]):

• Comprehension
• Constraint
• Construction
• Direction
• Empathy
• Equilibrium
• Freedom
• Levity
• Projection
• Survival

Features:

• Fame (default 0)
• Effort (default 100)
• Awareness (default 0)
• Guile (default 0)
• Momentum (default 0)

Archetype Compass Contract

• Archetypes are loaded from shared JSON contracts and scored against entity trait vectors each turn.
• Status surfaces expose:
  • archetype_heading (top score label)
  • ranked archetype score list for explainability.
• Archetype heading changes are logged in event metadata for balancing analysis.

World Topology

• 12 levels (depth 12 to 1)
• 50 rooms per level (5×10)
• Room-bound: No physics, colliders, or mesh grid; rooms are discrete cells. Future open-world mode will introduce continuous space and is a separate mode.

Fog of War (Grid Mode)

Discovery radius is formulaic: derived from attribute(s) and/or trait(s), not a fixed constant. Revealed cells = visited rooms + rooms within fogRadius steps of any visited room. Contract: fogRadius(entity) -> number. Candidate inputs: insight, Awareness. Formula TBD; implementation must support easy swap.

• Per level: 1 start, 1 exit, 20 treasure, 5 rune forge
• 4 dungeoneers per level
• One hostile spawn from exit each turn
• Hostiles cannot enter rune forge rooms

Treasure Room Items

Treasure rooms include:

• Treasure Cache (tags: treasure, loot, vector delta: Projection +0.4, Survival +0.2)
• Weapon item (rarity weighted by depth)

Reference Playthrough Contract (25 Turns)

A deterministic 25-turn integration run is required in automated tests.

Canonical replay seed for v1:

• CANONICAL_SEED_V1 = 20260227

Coverage map by turn window:

1. Turns 1-4: movement boundaries, look, room vector influence.
2. Turns 5-8: search, item state changes, cutscene trigger.
3. Turns 9-11: talk and rumor spread between entities.
4. Turns 12-14: deed projection and misinformation propagation.
5. Turns 15-17: combat encounter with fight then flee.
6. Turns 18-20: skill unlock/evolution gate checks (including rune forge).
7. Turns 21-23: livestream fame/effort effects and deed broadcasting.
8. Turns 24-25: page/chapter logging assertions and snapshot determinism checks.

Required assertions:

• Action availability and blocked reasons are stable.
• Depth and level remain separate and correct.
• Deed beliefs include at least one misinformed record.
• Cutscene queue behavior is visible in feed output.
• Same seed and same action script produce same final snapshot hash.

Phased Roadmap: What We Do and What We Phase Out

Phased-out for now:

• Physics, colliders, tile meshes, canvas AI pathfinding
• Media (sprites, audio)—we use components and primitives only
• Non-room topology

Intentionally light:

• Text and ASCII as primary content; some UI (buttons, overlays) for interaction
• RTS-like discrete cells; room boundaries define movement

MCP Tool Interface Contract (Phase 18)

Machine interface is defined over engine APIs so external tools (MCP or other agents) can drive turns without browser UI. Agent play includes walkthrough-style scripts, AI behavior, and report generation; agents consume the same action surface and state contracts as human players.

Required operations:

1. create_session(seed?) -> session_id
2. get_snapshot(session_id) -> snapshot
3. list_actions(session_id, entity_id?) -> legal_actions[]
4. dispatch_action(session_id, action) -> turn_result
5. get_log_page(session_id, chapter, entity_id?) -> page_entries[]
6. restore_snapshot(session_id, snapshot) -> ok

Implementation: packages/engine-mcp exposes these operations as MCP tools over stdio.

Contract rules:

• Action payloads use the same schemas as browser runtime actions.
• Repeated runs with same seed + same action script must return deterministic snapshots and event ordering.
• Errors must be explicit (invalid_action, blocked_action, invalid_payload, session_not_found) with readable reasons.
• Current automated runner is deterministic-policy based; autonomous LLM turn choosing is not implemented.

Autonomous LLM gameplay (future, out-of-scope) would require all of:

• Tool-call budget controls and bounded retry policy per turn.
• Reproducible decision trace capture (prompt/model/tool calls) for deterministic drift triage.
• Separate reliability and safety gates beyond replay parity tests.
• Stable evaluation harness that compares model-play outcomes to deterministic baselines.

Assistant Frame Window-Agent Contract (Phase 19)

Browser /play will expose Assistant Frame-compatible bridge wiring so in-window agents can consume a structured game surface when supported by host tooling.

Contract rules:

• Standard button-first DOM gameplay remains valid and unchanged.
• Frame bridge path must map to the same engine actions as UI buttons.
• If no frame host is present, gameplay behavior must fall back cleanly to existing local/browser flow.
• Remote MCP endpoint (/api/mcp) is enabled by default in deployed runtime and requires signed-in authentication.
• Remote MCP hardening baseline is always enforced (rate limiting, payload validation, session isolation, and audit metadata).

Extended Playthrough Contract (Phase 18)

Beyond the 25-turn baseline, Phase 18 includes a deterministic >= 75-turn scripted run that includes:

• branching dialogue choices
• multiple combat and flee chains
• skill unlock and at least one evolution
• rumor propagation with misinformation correction
• faction/reputation gate transitions
• companion recruitment attempt
• chapter/act/page progression checks

The 25-turn fixture remains baseline; the 75-turn suite is agent-regression coverage via canonical-dense-trace-v1.json.

Phase 17 long-run suite contract:

• deterministic windows: 100, 250, 500 turns
• emitted metrics: action usage, archetype distribution, survival/escape rates, dead action types, turn-time stats
• report paths:
  • packages/engine/test-reports/long-run-balance-report.json
  • docs-site/test-reports/balance-sim-report.json

Phase 19 release-report contract:

• each shipped game version must publish version-coupled play report artifacts
• each shipped game version must publish a machine-readable pass/fail test manifest
• report filenames include release version and commit/build identifier
• docs must expose links to the matching report set for that version

Phase 20 report schema normalization contract:

• compact reports use reference-based event storage (packed-v1) to minimize duplication while preserving full replay fidelity
• packed ledger contains lookup tables (actors, actions, rooms, messages) and numeric row references
• entity summaries refer to event indices instead of duplicating dialogue payload records
• optional split-artifact mode writes summary report with eventLedgerFormat = external-v1 plus an external ledger file
• report top-level schema version is agent-play-report/v2; external ledger payload schema is agent-play-event-ledger/v1
• viewer implementations must support both inline-v1 and packed-v1 report formats by schema version
• viewers that consume split artifacts must support either JSON hydration (json-v1) or row streaming iteration (jsonl-v1) before timeline traversal
• split-artifact ledgers add JSONL row-stream mode so viewers can iterate timeline entries without loading the full ledger JSON document
• MCP/LLM turn chooser is de-scoped for foreseeable delivery and is not an active roadmap item

Performance and Pressure Contract

Targets:

• Browser turn loop p95 <= 2s under pressure cap 120 entities when items are modeled as entities.
• No visible UI stall longer than 2s for a single action.

Pressure controls:

• Deterministic pruning/backpressure policy when entity cap is exceeded.
• If items are plain room/inventory data (not entity objects), the cap is applied to active simulated entities only.
• Pruning decisions are logged to chapter/system pages for auditability.
• Balance harness batches (simulateBalanceBatch) are used to track aggregate action usage, archetype distribution, fame, and escape rates across canonical seeds.

Shared Contracts and Replay Artifacts

Cross-language reusable assets live as JSON contracts:

• Action definitions and prerequisites
• Formula constants and delta caps
• Vector anchors and room templates
• Skills, items, cutscenes, global events

Deterministic replay assets:

• Golden trace fixtures (seed + scripted actions + expected snapshots)
• Reference playthrough snapshots
• Vector/feature usage report generated in CI

Simulation Coverage Checklist

Tick when simulated in a run:

• Actions: move, train, rest, search, talk, speak, fight, flee, live_stream, steal, recruit, murder, evolve_skill, choose_dialogue
• Rooms: corridor, start, exit, training, rest, treasure, rune_forge, combat
• Cutscenes: A Locked Cache, Steel Memory, Signal in the Dark, Hands Like Smoke, Chapter Closed, Surface Air
• Skills: Appraisal/X-Ray, Keen Eye, Shadow Hand, Battle Broadcast, evolutions
• Events: depth_pressure_turn_40, fame_watchers_20
• Deed misinformation appears and later reconciliation is possible
• 25-turn reference run (CANONICAL_SEED_V1) passes deterministic snapshot checks

Simulation Artifacts

GRD Update Process

1. Add findings to scratch/game-state.md.
2. Curate validated findings to .concept/DISCOVERY-LOG.md.
3. Update GRD when behavior contracts change.
4. Update PRD when architecture or scope changes.
5. Keep GRD and implementation synchronized each loop.
6. Add or refine UI components in .planning/UI-COMPONENT-REGISTRY.md when screens are designed; update .planning/KAPLAY-INTERFACE-SPEC.md when layouts change.