Requirements
Every spec, every version. Every R-v5.XX has a permalink.
This page renders every greenfield escape-the-dungeon project's current REQUIREMENTS.xml: the v4 pressure-oriented base plus the v5 addendum with 21 playtest-driven additions. Each requirement has a stable anchor so other pages can link to individual rules (e.g. R-v5.13 for the rule-based-combat choice).
All three templates carry the same spec — the difference between the three projects is workflow (GAD / Bare / Emergent), not requirements. Full version history: see timeline below or read the REQUIREMENTS-VERSIONS.md narrative on GitHub.
3 template files
5 versions in history
v5
escape-the-dungeon
Escape the Dungeon · GAD
v4 base — goal
Build a playable roguelike dungeon crawler "Escape the Dungeon" where players must
exercise INGENUITY through spell crafting and adaptation to progress. This is not a
features checklist — it is a problem-solving loop disguised as a dungeon crawler.
Every mechanical system must create friction that rewards creative player choice.
Core principle (v4)
**Baseline starter abilities must NOT be sufficient to comfortably complete a full
floor without adaptation or enhancement.** If a player can brute-force progression
using only what they start with, the design has failed. Encounters must demand
spell crafting, skill use, resource management, or build specialization.
Gate criteria (v4 base)
G1
game-loop
The complete game loop must work without softlock. A test run must walk through: 1. Title screen renders and "New Game" starts a run 2. Player enters first room with visible navigation options 3. Player navigates to a second room (scene transition succeeds) 4. Player encounters combat OR dialogue and resolves it 5. After resolution, player returns to room navigation state 6. Player continues into …
G2
forge-with-ingenuity-payoff
The game must include a functional spell-crafting system AND at least one encounter per floor where the crafted/adapted spell provides a meaningful advantage. Crafting requirements: - Player can access a forge / spell-craft interface during gameplay - Player selects at least 2 crafting inputs (runes or components) - System produces a new, usable spell from the combination - Crafted spell can be eq…
G3
ui-quality
The game must present a fully intentional UI. Required: - Readable, visually structured layout with spacing and hierarchy - Room-type icons or sprite representations - Encounter/entity visual representation via sprite, portrait, or coherent placeholder - Themed visual differentiation across room types (color, background, or panel treatment) - Styled interactive controls (buttons with visible affor…
G4
pressure-mechanics
The game must include at least TWO systems that constrain player behavior such that crafting or adapting spells provides a meaningful advantage or is required for success. Pick at least two from these categories: A. **Resource pressure** — limited mana pool, limited healing, forge training has a cost, cannot spam indefinitely B. **Enemy counterplay** — resistances, immunities, behavior that punish…
v5 addendum — 20 playtest-driven additions
R-v5.01
amends G2
Training via encounter, not menu
Affinity must increase as a side effect of casting spells in encounters, not as a direct menu action. Remove any "select affinity → train" menu that picks the trained element for the player. Introduce a Training Dummy encounter (low-XP, no-loot combat room type) whose only purpose is letting the player cast without risk so affinity rises through use. Any room with combat must produce affinity gain for the elements/ runes the cast spell used. The forge becomes a place to forge and combine, not to train. Rationale: the casting of spells must be what increases rune affinity; direct training menus turn a discovery loop into a shopping list.
R-v5.02
Rune discovery as a gameplay loop
Not all runes are listed or available at game start. Runes must be DISCOVERED across the dungeon. Starter inventory contains a small subset of runes (2-3). The rest are found as loot drops from combat/elite encounters, hidden in event rooms, sold by merchants, or awarded by NPC dialogue outcomes. The rune forge UI must visibly distinguish known vs undiscovered runes (locked slots, ???, or similar). At least one rune per floor must be gated behind a non-combat interaction.
R-v5.03
Merchants with buy/sell/trade
The dungeon must contain at least one merchant encounter per floor. Merchant room type. Inventory of runes, potions, and items with gold cost. Three operations: buy (cost gold), sell (gain gold), trade (exchange owned item for stocked item with a relative value rule). Gold or an equivalent currency becomes a tracked resource.
R-v5.04
NPC dialogue with branching outcomes
Authored NPCs must appear with dialogue options that trigger items, events, or combat. At least 3 authored NPCs across the dungeon with 2+ dialogue branches each. Dialogue choices must cause persistent game state changes: item gain, rune unlock, enemy spawn, merchant discount, quest flag.
R-v5.05
Inventory/bag with grid and equippable items
Player must have a visible inventory UI. Bag with a finite grid of slots. Items have categories: consumable (potions, keys), rune, equipment (weapon, armor, trinket, focus, etc.). Equipment slots must exist on a character sheet with at least: main-hand, off-hand, body, trinket. Equipping an item must affect combat stats or spell outputs in a measurable way. Items must drop from combat, events, and merchants.
R-v5.06
Visible character sheet with combat/physical skills and a skill tree
Player must be able to inspect their character at any time. Panel showing: HP, mana, affinities, physical/combat stats, resistances, equipped items, known spells, known physical skills. Skill tree or equivalent progression graph for physical/combat skills, SEPARATE FROM SPELLS. Physical skills cost stamina or a non-mana resource to distinguish from spells.
R-v5.07
Spell slots and skill slots (loadout constraint)
When the player has many spells/skills, they must choose which to equip. Fixed-size spell loadout (suggested: 4-6 equipped slots out of all known spells). Fixed-size physical skill loadout (suggested: 2-4 equipped slots). Loadout can only be changed in rest rooms or at specific stations, not mid-combat. Build pressure mechanic satisfying G4.
R-v5.09
amends G1
Session persistence
The game must support resumable sessions. On room-clear or floor-clear, the game checkpoints the player's state. If the player closes the browser or the session ends, re-opening the game presents a Continue option that restores the most recent checkpoint. New Game starts fresh. Both paths must work without error.
R-v5.10
amends G3
Transient UI feedback
UI feedback elements (toasts, status messages, combat results) must be transient and session-scoped. Each element auto-dismisses after a brief display period (3-5 seconds) or provides an explicit dismiss control. Starting a new session must present a clean UI with no carried-over feedback from a previous session.
R-v5.11
amends room-types
Rest rooms must offer rest
Any room typed Rest (including the rune forge rest variant) must expose a Rest action that restores HP/mana and allows loadout changes. Forge rooms may combine Forge + Train + Rest actions, but Rest must be one of the action buttons if the room claims Rest as a room type.
R-v5.12
amends G3
Navigation and map usability
Map/navigation UI must be more than a linear list. Map view must show at minimum a 2D graph layout of discovered rooms with current position, cleared/uncleared state, and available exits. Navigation from the map must be one click, not a multi-step menu. See R-v5.17 for the stronger form.
R-v5.13
amends G1 G4
Auto-resolve combat with tactical loadout (Unicorn Overlord style)
Combat resolves automatically based on the player's pre-set loadout, equipped spells/skills, and tactical rules. The player does NOT click-attack individual enemies during combat. Instead: 1. Before an encounter, the player configures: equipped spells, equipped physical skills (per loadout slots from R-v5.07), formation/positioning of party members (if applicable), and action-policy rules (e.g. "use heal when HP below 30%", "prioritize targets weak to equipped element"). 2. Combat plays out in real-time with a visible combat log showing each action, its effect, and why it was chosen (which rule triggered). 3. The player can PAUSE at any time to adjust loadout, swap spells, or change action-policy rules. The fight resumes with the new configuration. 4. Resolution depends on the loadout quality, spell/skill choices, and how well the action policies match the enemy composition — this is where the forge and rune crafting systems pay off. This model rewards preparation and build-crafting over reflexes. The ingenuity requirement (G2) is satisfied by encounters where the default loadout fails and the player must pause, rethink, and adapt their tactical rules.
R-v5.14
Trait-driven behavior for all entities
Every entity with agency (enemies, NPCs, the player character) has traits that drive their behavior. Traits are NOT static labels — they shift based on: - Dialogue choices the player makes (choosing aggressive responses shifts the player toward "aggressive" trait, which changes available dialogue options with NPCs who react to that trait) - Moral interactions (sparing vs defeating enemies, helping vs ignoring NPCs, stealing vs buying from merchants) - Combat actions (repeatedly using fire spells shifts affinity toward fire, which may change how fire-resistant enemies react) Enemy behavior in auto-resolve combat is governed by their traits: an aggressive enemy prioritizes attack, a territorial enemy holds position, a cowardly enemy flees at low HP. NPC dialogue options expand or contract based on trait alignment between the player and the NPC. Traits have visible NUMERIC values on the character sheet (e.g. aggression: 0.7, compassion: 0.3, arcane affinity: 0.8). When a trait shifts, the numeric change is shown inline (combat log or a brief HUD notification like "+0.1 aggression").
R-v5.15
Real-time game clock
The dungeon has an in-game clock that progresses in real time (suggested ratio: 1 real hour = 1 in-game day). The clock can influence gameplay: encounter composition may shift by time of day, merchant stock may rotate, certain NPC events may be time-gated. Day/night UI tinting is a SOFT bonus (not a gate). The clock is purely flavor and pacing — it does NOT add turn-based tick mechanics or per-tick processing. All rendering remains event-driven per R-v5.21.
R-v5.16
Affinity reward loop
Boosting a rune's affinity must produce a visible, valuable reward — not just a stat increment hidden on a sheet. Suggested rewards at affinity thresholds: new rune variant unlocked, existing spells using that rune gain a visual effect tier, new spell combinations become craftable, access to an affinity-gated event or NPC. At least one affinity reward must be visible in the forge UI (e.g. an affinity progress bar with named milestones).
R-v5.17
amends G3 R-v5.12
Central visual navigation map with player location
Stronger form of R-v5.12. The navigation view must be a persistent, reachable, visual map. Accessible from a single button/keystroke at any time in exploration mode. Shows the player token on its current room, room type icons, discovered vs undiscovered rooms, cleared vs active rooms, and visible exit connections between rooms. Clicking an adjacent room must move the player there in one action. Preferred layout: 2D grid or spatial floor map.
R-v5.18
Visual player vs enemy identity in encounters
Encounter rendering must make it obvious which visual element is the player and which is the enemy. Distinct portrait, positioning, or color treatment. Reference style: Pokemon or Unicorn Overlord (UO preferred). No rendering where the player cannot visually distinguish themselves from the first enemy without reading text labels.
R-v5.19
Spells as craftable ingredients + procedural-but-semantic naming
Spell crafting accepts runes AND existing spells as ingredients. A spell used as an ingredient consumes or copies from the existing spell (design choice explicit). Combining two spells or a spell + rune produces an evolved spell with procedurally generated but semantically meaningful naming. Naming scheme must be consistent but varied — similar combinations produce similar names, slight differences produce slightly varied names. Not too verbose. Example scheme: root spell + modifier noun keyed to added element/spell. "Fireball" + Ice rune → "Frostfall Ember". Two Frostfall Embers fused → "Glacial Ember" (same family, progressed). This requirement mirrors the emergent-evolution working hypothesis (gad-68): the in-game rune/spell/ merge system is an explicit narrative analogue for the agent's skill-authoring/merge loop.
R-v5.20
Unique ingredients per spell
Each spell recipe requires unique ingredients — the same rune cannot be used twice in a single spell's ingredient list. Selecting a rune already in the current recipe must deselect it or be rejected. The same rune CAN appear across different spells in the spellbook. Affinity gain is calculated per unique rune slot consumed.
R-v5.21
Event-driven rendering (remove per-tick redraws)
All UI updates must be event-driven, not per-tick. No redraw loops firing at a fixed rate regardless of state changes. Observable symptom to eliminate: glitchy redraws on button clicks, observed across ALL round-4 builds. This is a perf-and-stability gate failure mode. Acceptable patterns: React reconciliation on state change, requestAnimationFrame scheduling only when animation is active.
v5
escape-the-dungeon-bare
Escape the Dungeon · Bare
v4 base — goal
Build a playable roguelike dungeon crawler "Escape the Dungeon" where players must
exercise INGENUITY through spell crafting and adaptation to progress. This is not a
features checklist — it is a problem-solving loop disguised as a dungeon crawler.
Every mechanical system must create friction that rewards creative player choice.
Core principle (v4)
**Baseline starter abilities must NOT be sufficient to comfortably complete a full
floor without adaptation or enhancement.** If a player can brute-force progression
using only what they start with, the design has failed. Encounters must demand
spell crafting, skill use, resource management, or build specialization.
Gate criteria (v4 base)
G1
game-loop
The complete game loop must work without softlock. A test run must walk through: 1. Title screen renders and "New Game" starts a run 2. Player enters first room with visible navigation options 3. Player navigates to a second room (scene transition succeeds) 4. Player encounters combat OR dialogue and resolves it 5. After resolution, player returns to room navigation state 6. Player continues into …
G2
forge-with-ingenuity-payoff
The game must include a functional spell-crafting system AND at least one encounter per floor where the crafted/adapted spell provides a meaningful advantage. Crafting requirements: - Player can access a forge / spell-craft interface during gameplay - Player selects at least 2 crafting inputs (runes or components) - System produces a new, usable spell from the combination - Crafted spell can be eq…
G3
ui-quality
The game must present a fully intentional UI. Required: - Readable, visually structured layout with spacing and hierarchy - Room-type icons or sprite representations - Encounter/entity visual representation via sprite, portrait, or coherent placeholder - Themed visual differentiation across room types (color, background, or panel treatment) - Styled interactive controls (buttons with visible affor…
G4
pressure-mechanics
The game must include at least TWO systems that constrain player behavior such that crafting or adapting spells provides a meaningful advantage or is required for success. Pick at least two from these categories: A. **Resource pressure** — limited mana pool, limited healing, forge training has a cost, cannot spam indefinitely B. **Enemy counterplay** — resistances, immunities, behavior that punish…
v5 addendum — 20 playtest-driven additions
R-v5.01
amends G2
Training via encounter, not menu
Affinity must increase as a side effect of casting spells in encounters, not as a direct menu action. Remove any "select affinity → train" menu that picks the trained element for the player. Introduce a Training Dummy encounter (low-XP, no-loot combat room type) whose only purpose is letting the player cast without risk so affinity rises through use. Any room with combat must produce affinity gain for the elements/ runes the cast spell used. The forge becomes a place to forge and combine, not to train. Rationale: the casting of spells must be what increases rune affinity; direct training menus turn a discovery loop into a shopping list.
R-v5.02
Rune discovery as a gameplay loop
Not all runes are listed or available at game start. Runes must be DISCOVERED across the dungeon. Starter inventory contains a small subset of runes (2-3). The rest are found as loot drops from combat/elite encounters, hidden in event rooms, sold by merchants, or awarded by NPC dialogue outcomes. The rune forge UI must visibly distinguish known vs undiscovered runes (locked slots, ???, or similar). At least one rune per floor must be gated behind a non-combat interaction.
R-v5.03
Merchants with buy/sell/trade
The dungeon must contain at least one merchant encounter per floor. Merchant room type. Inventory of runes, potions, and items with gold cost. Three operations: buy (cost gold), sell (gain gold), trade (exchange owned item for stocked item with a relative value rule). Gold or an equivalent currency becomes a tracked resource.
R-v5.04
NPC dialogue with branching outcomes
Authored NPCs must appear with dialogue options that trigger items, events, or combat. At least 3 authored NPCs across the dungeon with 2+ dialogue branches each. Dialogue choices must cause persistent game state changes: item gain, rune unlock, enemy spawn, merchant discount, quest flag.
R-v5.05
Inventory/bag with grid and equippable items
Player must have a visible inventory UI. Bag with a finite grid of slots. Items have categories: consumable (potions, keys), rune, equipment (weapon, armor, trinket, focus, etc.). Equipment slots must exist on a character sheet with at least: main-hand, off-hand, body, trinket. Equipping an item must affect combat stats or spell outputs in a measurable way. Items must drop from combat, events, and merchants.
R-v5.06
Visible character sheet with combat/physical skills and a skill tree
Player must be able to inspect their character at any time. Panel showing: HP, mana, affinities, physical/combat stats, resistances, equipped items, known spells, known physical skills. Skill tree or equivalent progression graph for physical/combat skills, SEPARATE FROM SPELLS. Physical skills cost stamina or a non-mana resource to distinguish from spells.
R-v5.07
Spell slots and skill slots (loadout constraint)
When the player has many spells/skills, they must choose which to equip. Fixed-size spell loadout (suggested: 4-6 equipped slots out of all known spells). Fixed-size physical skill loadout (suggested: 2-4 equipped slots). Loadout can only be changed in rest rooms or at specific stations, not mid-combat. Build pressure mechanic satisfying G4.
R-v5.09
amends G1
Session persistence
The game must support resumable sessions. On room-clear or floor-clear, the game checkpoints the player's state. If the player closes the browser or the session ends, re-opening the game presents a Continue option that restores the most recent checkpoint. New Game starts fresh. Both paths must work without error.
R-v5.10
amends G3
Transient UI feedback
UI feedback elements (toasts, status messages, combat results) must be transient and session-scoped. Each element auto-dismisses after a brief display period (3-5 seconds) or provides an explicit dismiss control. Starting a new session must present a clean UI with no carried-over feedback from a previous session.
R-v5.11
amends room-types
Rest rooms must offer rest
Any room typed Rest (including the rune forge rest variant) must expose a Rest action that restores HP/mana and allows loadout changes. Forge rooms may combine Forge + Train + Rest actions, but Rest must be one of the action buttons if the room claims Rest as a room type.
R-v5.12
amends G3
Navigation and map usability
Map/navigation UI must be more than a linear list. Map view must show at minimum a 2D graph layout of discovered rooms with current position, cleared/uncleared state, and available exits. Navigation from the map must be one click, not a multi-step menu. See R-v5.17 for the stronger form.
R-v5.13
amends G1 G4
Auto-resolve combat with tactical loadout (Unicorn Overlord style)
Combat resolves automatically based on the player's pre-set loadout, equipped spells/skills, and tactical rules. The player does NOT click-attack individual enemies during combat. Instead: 1. Before an encounter, the player configures: equipped spells, equipped physical skills (per loadout slots from R-v5.07), formation/positioning of party members (if applicable), and action-policy rules (e.g. "use heal when HP below 30%", "prioritize targets weak to equipped element"). 2. Combat plays out in real-time with a visible combat log showing each action, its effect, and why it was chosen (which rule triggered). 3. The player can PAUSE at any time to adjust loadout, swap spells, or change action-policy rules. The fight resumes with the new configuration. 4. Resolution depends on the loadout quality, spell/skill choices, and how well the action policies match the enemy composition — this is where the forge and rune crafting systems pay off. This model rewards preparation and build-crafting over reflexes. The ingenuity requirement (G2) is satisfied by encounters where the default loadout fails and the player must pause, rethink, and adapt their tactical rules.
R-v5.14
Trait-driven behavior for all entities
Every entity with agency (enemies, NPCs, the player character) has traits that drive their behavior. Traits are NOT static labels — they shift based on: - Dialogue choices the player makes (choosing aggressive responses shifts the player toward "aggressive" trait, which changes available dialogue options with NPCs who react to that trait) - Moral interactions (sparing vs defeating enemies, helping vs ignoring NPCs, stealing vs buying from merchants) - Combat actions (repeatedly using fire spells shifts affinity toward fire, which may change how fire-resistant enemies react) Enemy behavior in auto-resolve combat is governed by their traits: an aggressive enemy prioritizes attack, a territorial enemy holds position, a cowardly enemy flees at low HP. NPC dialogue options expand or contract based on trait alignment between the player and the NPC. Traits have visible NUMERIC values on the character sheet (e.g. aggression: 0.7, compassion: 0.3, arcane affinity: 0.8). When a trait shifts, the numeric change is shown inline (combat log or a brief HUD notification like "+0.1 aggression").
R-v5.15
Real-time game clock
The dungeon has an in-game clock that progresses in real time (suggested ratio: 1 real hour = 1 in-game day). The clock can influence gameplay: encounter composition may shift by time of day, merchant stock may rotate, certain NPC events may be time-gated. Day/night UI tinting is a SOFT bonus (not a gate). The clock is purely flavor and pacing — it does NOT add turn-based tick mechanics or per-tick processing. All rendering remains event-driven per R-v5.21.
R-v5.16
Affinity reward loop
Boosting a rune's affinity must produce a visible, valuable reward — not just a stat increment hidden on a sheet. Suggested rewards at affinity thresholds: new rune variant unlocked, existing spells using that rune gain a visual effect tier, new spell combinations become craftable, access to an affinity-gated event or NPC. At least one affinity reward must be visible in the forge UI (e.g. an affinity progress bar with named milestones).
R-v5.17
amends G3 R-v5.12
Central visual navigation map with player location
Stronger form of R-v5.12. The navigation view must be a persistent, reachable, visual map. Accessible from a single button/keystroke at any time in exploration mode. Shows the player token on its current room, room type icons, discovered vs undiscovered rooms, cleared vs active rooms, and visible exit connections between rooms. Clicking an adjacent room must move the player there in one action. Preferred layout: 2D grid or spatial floor map.
R-v5.18
Visual player vs enemy identity in encounters
Encounter rendering must make it obvious which visual element is the player and which is the enemy. Distinct portrait, positioning, or color treatment. Reference style: Pokemon or Unicorn Overlord (UO preferred). No rendering where the player cannot visually distinguish themselves from the first enemy without reading text labels.
R-v5.19
Spells as craftable ingredients + procedural-but-semantic naming
Spell crafting accepts runes AND existing spells as ingredients. A spell used as an ingredient consumes or copies from the existing spell (design choice explicit). Combining two spells or a spell + rune produces an evolved spell with procedurally generated but semantically meaningful naming. Naming scheme must be consistent but varied — similar combinations produce similar names, slight differences produce slightly varied names. Not too verbose. Example scheme: root spell + modifier noun keyed to added element/spell. "Fireball" + Ice rune → "Frostfall Ember". Two Frostfall Embers fused → "Glacial Ember" (same family, progressed). This requirement mirrors the emergent-evolution working hypothesis (gad-68): the in-game rune/spell/ merge system is an explicit narrative analogue for the agent's skill-authoring/merge loop.
R-v5.20
Unique ingredients per spell
Each spell recipe requires unique ingredients — the same rune cannot be used twice in a single spell's ingredient list. Selecting a rune already in the current recipe must deselect it or be rejected. The same rune CAN appear across different spells in the spellbook. Affinity gain is calculated per unique rune slot consumed.
R-v5.21
Event-driven rendering (remove per-tick redraws)
All UI updates must be event-driven, not per-tick. No redraw loops firing at a fixed rate regardless of state changes. Observable symptom to eliminate: glitchy redraws on button clicks, observed across ALL round-4 builds. This is a perf-and-stability gate failure mode. Acceptable patterns: React reconciliation on state change, requestAnimationFrame scheduling only when animation is active.
v5
escape-the-dungeon-emergent
Escape the Dungeon · Emergent
v4 base — goal
Build a playable roguelike dungeon crawler "Escape the Dungeon" where players must
exercise INGENUITY through spell crafting and adaptation to progress. This is not a
features checklist — it is a problem-solving loop disguised as a dungeon crawler.
Every mechanical system must create friction that rewards creative player choice.
Core principle (v4)
**Baseline starter abilities must NOT be sufficient to comfortably complete a full
floor without adaptation or enhancement.** If a player can brute-force progression
using only what they start with, the design has failed. Encounters must demand
spell crafting, skill use, resource management, or build specialization.
Gate criteria (v4 base)
G1
game-loop
The complete game loop must work without softlock. A test run must walk through: 1. Title screen renders and "New Game" starts a run 2. Player enters first room with visible navigation options 3. Player navigates to a second room (scene transition succeeds) 4. Player encounters combat OR dialogue and resolves it 5. After resolution, player returns to room navigation state 6. Player continues into …
G2
forge-with-ingenuity-payoff
The game must include a functional spell-crafting system AND at least one encounter per floor where the crafted/adapted spell provides a meaningful advantage. Crafting requirements: - Player can access a forge / spell-craft interface during gameplay - Player selects at least 2 crafting inputs (runes or components) - System produces a new, usable spell from the combination - Crafted spell can be eq…
G3
ui-quality
The game must present a fully intentional UI. Required: - Readable, visually structured layout with spacing and hierarchy - Room-type icons or sprite representations - Encounter/entity visual representation via sprite, portrait, or coherent placeholder - Themed visual differentiation across room types (color, background, or panel treatment) - Styled interactive controls (buttons with visible affor…
G4
pressure-mechanics
The game must include at least TWO systems that constrain player behavior such that crafting or adapting spells provides a meaningful advantage or is required for success. Pick at least two from these categories: A. **Resource pressure** — limited mana pool, limited healing, forge training has a cost, cannot spam indefinitely B. **Enemy counterplay** — resistances, immunities, behavior that punish…
v5 addendum — 20 playtest-driven additions
R-v5.01
amends G2
Training via encounter, not menu
Affinity must increase as a side effect of casting spells in encounters, not as a direct menu action. Remove any "select affinity → train" menu that picks the trained element for the player. Introduce a Training Dummy encounter (low-XP, no-loot combat room type) whose only purpose is letting the player cast without risk so affinity rises through use. Any room with combat must produce affinity gain for the elements/ runes the cast spell used. The forge becomes a place to forge and combine, not to train. Rationale: the casting of spells must be what increases rune affinity; direct training menus turn a discovery loop into a shopping list.
R-v5.02
Rune discovery as a gameplay loop
Not all runes are listed or available at game start. Runes must be DISCOVERED across the dungeon. Starter inventory contains a small subset of runes (2-3). The rest are found as loot drops from combat/elite encounters, hidden in event rooms, sold by merchants, or awarded by NPC dialogue outcomes. The rune forge UI must visibly distinguish known vs undiscovered runes (locked slots, ???, or similar). At least one rune per floor must be gated behind a non-combat interaction.
R-v5.03
Merchants with buy/sell/trade
The dungeon must contain at least one merchant encounter per floor. Merchant room type. Inventory of runes, potions, and items with gold cost. Three operations: buy (cost gold), sell (gain gold), trade (exchange owned item for stocked item with a relative value rule). Gold or an equivalent currency becomes a tracked resource.
R-v5.04
NPC dialogue with branching outcomes
Authored NPCs must appear with dialogue options that trigger items, events, or combat. At least 3 authored NPCs across the dungeon with 2+ dialogue branches each. Dialogue choices must cause persistent game state changes: item gain, rune unlock, enemy spawn, merchant discount, quest flag.
R-v5.05
Inventory/bag with grid and equippable items
Player must have a visible inventory UI. Bag with a finite grid of slots. Items have categories: consumable (potions, keys), rune, equipment (weapon, armor, trinket, focus, etc.). Equipment slots must exist on a character sheet with at least: main-hand, off-hand, body, trinket. Equipping an item must affect combat stats or spell outputs in a measurable way. Items must drop from combat, events, and merchants.
R-v5.06
Visible character sheet with combat/physical skills and a skill tree
Player must be able to inspect their character at any time. Panel showing: HP, mana, affinities, physical/combat stats, resistances, equipped items, known spells, known physical skills. Skill tree or equivalent progression graph for physical/combat skills, SEPARATE FROM SPELLS. Physical skills cost stamina or a non-mana resource to distinguish from spells.
R-v5.07
Spell slots and skill slots (loadout constraint)
When the player has many spells/skills, they must choose which to equip. Fixed-size spell loadout (suggested: 4-6 equipped slots out of all known spells). Fixed-size physical skill loadout (suggested: 2-4 equipped slots). Loadout can only be changed in rest rooms or at specific stations, not mid-combat. Build pressure mechanic satisfying G4.
R-v5.09
amends G1
Session persistence
The game must support resumable sessions. On room-clear or floor-clear, the game checkpoints the player's state. If the player closes the browser or the session ends, re-opening the game presents a Continue option that restores the most recent checkpoint. New Game starts fresh. Both paths must work without error.
R-v5.10
amends G3
Transient UI feedback
UI feedback elements (toasts, status messages, combat results) must be transient and session-scoped. Each element auto-dismisses after a brief display period (3-5 seconds) or provides an explicit dismiss control. Starting a new session must present a clean UI with no carried-over feedback from a previous session.
R-v5.11
amends room-types
Rest rooms must offer rest
Any room typed Rest (including the rune forge rest variant) must expose a Rest action that restores HP/mana and allows loadout changes. Forge rooms may combine Forge + Train + Rest actions, but Rest must be one of the action buttons if the room claims Rest as a room type.
R-v5.12
amends G3
Navigation and map usability
Map/navigation UI must be more than a linear list. Map view must show at minimum a 2D graph layout of discovered rooms with current position, cleared/uncleared state, and available exits. Navigation from the map must be one click, not a multi-step menu. See R-v5.17 for the stronger form.
R-v5.13
amends G1 G4
Auto-resolve combat with tactical loadout (Unicorn Overlord style)
Combat resolves automatically based on the player's pre-set loadout, equipped spells/skills, and tactical rules. The player does NOT click-attack individual enemies during combat. Instead: 1. Before an encounter, the player configures: equipped spells, equipped physical skills (per loadout slots from R-v5.07), formation/positioning of party members (if applicable), and action-policy rules (e.g. "use heal when HP below 30%", "prioritize targets weak to equipped element"). 2. Combat plays out in real-time with a visible combat log showing each action, its effect, and why it was chosen (which rule triggered). 3. The player can PAUSE at any time to adjust loadout, swap spells, or change action-policy rules. The fight resumes with the new configuration. 4. Resolution depends on the loadout quality, spell/skill choices, and how well the action policies match the enemy composition — this is where the forge and rune crafting systems pay off. This model rewards preparation and build-crafting over reflexes. The ingenuity requirement (G2) is satisfied by encounters where the default loadout fails and the player must pause, rethink, and adapt their tactical rules.
R-v5.14
Trait-driven behavior for all entities
Every entity with agency (enemies, NPCs, the player character) has traits that drive their behavior. Traits are NOT static labels — they shift based on: - Dialogue choices the player makes (choosing aggressive responses shifts the player toward "aggressive" trait, which changes available dialogue options with NPCs who react to that trait) - Moral interactions (sparing vs defeating enemies, helping vs ignoring NPCs, stealing vs buying from merchants) - Combat actions (repeatedly using fire spells shifts affinity toward fire, which may change how fire-resistant enemies react) Enemy behavior in auto-resolve combat is governed by their traits: an aggressive enemy prioritizes attack, a territorial enemy holds position, a cowardly enemy flees at low HP. NPC dialogue options expand or contract based on trait alignment between the player and the NPC. Traits have visible NUMERIC values on the character sheet (e.g. aggression: 0.7, compassion: 0.3, arcane affinity: 0.8). When a trait shifts, the numeric change is shown inline (combat log or a brief HUD notification like "+0.1 aggression").
R-v5.15
Real-time game clock
The dungeon has an in-game clock that progresses in real time (suggested ratio: 1 real hour = 1 in-game day). The clock can influence gameplay: encounter composition may shift by time of day, merchant stock may rotate, certain NPC events may be time-gated. Day/night UI tinting is a SOFT bonus (not a gate). The clock is purely flavor and pacing — it does NOT add turn-based tick mechanics or per-tick processing. All rendering remains event-driven per R-v5.21.
R-v5.16
Affinity reward loop
Boosting a rune's affinity must produce a visible, valuable reward — not just a stat increment hidden on a sheet. Suggested rewards at affinity thresholds: new rune variant unlocked, existing spells using that rune gain a visual effect tier, new spell combinations become craftable, access to an affinity-gated event or NPC. At least one affinity reward must be visible in the forge UI (e.g. an affinity progress bar with named milestones).
R-v5.17
amends G3 R-v5.12
Central visual navigation map with player location
Stronger form of R-v5.12. The navigation view must be a persistent, reachable, visual map. Accessible from a single button/keystroke at any time in exploration mode. Shows the player token on its current room, room type icons, discovered vs undiscovered rooms, cleared vs active rooms, and visible exit connections between rooms. Clicking an adjacent room must move the player there in one action. Preferred layout: 2D grid or spatial floor map.
R-v5.18
Visual player vs enemy identity in encounters
Encounter rendering must make it obvious which visual element is the player and which is the enemy. Distinct portrait, positioning, or color treatment. Reference style: Pokemon or Unicorn Overlord (UO preferred). No rendering where the player cannot visually distinguish themselves from the first enemy without reading text labels.
R-v5.19
Spells as craftable ingredients + procedural-but-semantic naming
Spell crafting accepts runes AND existing spells as ingredients. A spell used as an ingredient consumes or copies from the existing spell (design choice explicit). Combining two spells or a spell + rune produces an evolved spell with procedurally generated but semantically meaningful naming. Naming scheme must be consistent but varied — similar combinations produce similar names, slight differences produce slightly varied names. Not too verbose. Example scheme: root spell + modifier noun keyed to added element/spell. "Fireball" + Ice rune → "Frostfall Ember". Two Frostfall Embers fused → "Glacial Ember" (same family, progressed). This requirement mirrors the emergent-evolution working hypothesis (gad-68): the in-game rune/spell/ merge system is an explicit narrative analogue for the agent's skill-authoring/merge loop.
R-v5.20
Unique ingredients per spell
Each spell recipe requires unique ingredients — the same rune cannot be used twice in a single spell's ingredient list. Selecting a rune already in the current recipe must deselect it or be rejected. The same rune CAN appear across different spells in the spellbook. Affinity gain is calculated per unique rune slot consumed.
R-v5.21
Event-driven rendering (remove per-tick redraws)
All UI updates must be event-driven, not per-tick. No redraw loops firing at a fixed rate regardless of state changes. Observable symptom to eliminate: glitchy redraws on button clicks, observed across ALL round-4 builds. This is a perf-and-stability gate failure mode. Acceptable patterns: React reconciliation on state change, requestAnimationFrame scheduling only when animation is active.
Version history
Every requirements version has its own entry. Each version defines a round (decision gad-72) — new requirements version = new round.
v5
2026-04-09
**Core shift from v4:** Playtest-driven expansion. v4 was a designer rewrite; v5 comes entirely from user play of Bare v5 (0.805 rubric), Emergent v4 (rescored to 0.885 after user beat floor 1), GAD v9 (rate-limited), and GAD v10 (api-interrupted). Everything in v4 still applies — v5 adds 21 new/amended requirements (R-v5.01..21) on top as a structured `<addendum>` section inside the same template XML. **Changes from v4:** - **R-v5.01** Training via encounter, not menu — affinity rises from casting, not selecting. Training Dummy encounter room type. - **R-v5.02** Rune discovery as a gameplay loop — starter subset only, rest found in world, one rune per floor gated behind non-combat. - **R-v5.03** Merchants with buy/sell/trade — at least one per floor, gold as tracked resource. - **R-v5.04** NPC dialogue with branching outcomes — 3+ NPCs, 2+ branches each, choices change game state. - **R-v5.05** Inventory/bag with grid + equippable items — weapon/off-hand/body/trinket slots affecting stats. - **R-v5.06** Visible character sheet + skill tree — physical/combat skills separate from spells, distinct resource. - **R-v5.07** Spell and skill loadout slots — forced specialization as a build-pressure mechanic. - **R-v5.08** Progression sources sufficient to reach end boss (amends G1) — guaranteed mana-max / spell-power upgrade per floor. - **R-v5.09** Save checkpoints + continue-after-death (amends G1) — Continue must never hard-brick. - **R-v5.10** Notification lifecycle (amends G3) — auto-dismiss, clear on new game, no persistence across sessions. - **R-v5.11** Rest rooms must offer rest — forge rooms combining Forge+Train+Rest must expose Rest as an action. - **R-v5.12** Navigation and map usability (amends G3) — minimum 2D graph layout, one-click navigation. - **R-v5.13** Combat model must be explicitly chosen — **Model A (rule-based simulation, Unicorn-Overlord-style)** preferred over direct-control. - **R-v5.14** Action policies driven by entity traits — applies to enemies AND NPCs; dialogue changes with trait shifts. - **R-v5.15** Real-time game-time model — 1hr real = 1 day game, remove tick system, UI time-shading is soft. - **R-v5.16** Affinity reward loop — visible payoff for boosting a rune, not just a hidden stat. - **R-v5.17** Central visual navigation map with player token (stronger form of R-v5.12). - **R-v5.18** Visual player vs enemy identity — Pokemon / Unicorn Overlord style (UO preferred). - **R-v5.19** Spells as craftable ingredients — spells + runes both combine, procedural-but-semantic naming. Explicitly mirrors the emergent-evolution hypothesis (gad-68) as an in-game narrative analogue. - **R-v5.20** Rune uniqueness within a single spell — bug fix for Bare v5's double-affinity exploit. - **R-v5.21** Event-driven rendering — kill the per-tick redraw glitches observed across ALL round-4 builds. **Scoring impact:** - v4 gates remain (G1, G2, G3, G4). v5 amendments tighten G1 (death/continue, end-boss reachable), G2 (training is encounter-driven), G3 (notification lifecycle, map usability). - New scored dimensions: `inventory_and_equipment_present`, `npc_dialogue_present` — not gates, but meaningful score hits if missing. - Rubric weights unchanged from v4. **Deferred to v6:** - Deep evolution trees (multi-stage mutations). - Rune affinity decay when unused. - Multi-character party play — out of scope for escape-the-dungeon family. **Brownfield vs greenfield:** - Greenfield v5 applies to escape-the-dungeon, escape-the-dungeon-bare, escape-the-dungeon-emergent (same three templates all updated together). - Brownfield v5 extensions are not yet authored — round 5 starts greenfield-first. **Round 5 unblock:** This version is the trigger for round 5. Round 5 runs serially (gad-67) against this requirements set. HTTP 529 investigation + GAD v11 retry queued, see task registry. **Source:** `evals/_v5-requirements-addendum.md` holds the prose version with full user rationale quotes. The XML addendum in each template is the machine-readable form. **Decision references:** gad-65 (CSH), gad-68 (emergent-evolution), gad-71 (data/ pseudo-database for bug tracking), gad-72 (rounds framework — this is now round 5), gad-73 (fundamental skills triumvirate — the R-v5.19 spells-as-ingredients mechanic is the in-game analogue).
v4
2026-04-08
**Core shift from v3:** Pressure-oriented design. Previous versions were feature checklists. v4 reframes around "every system must create friction that rewards creative player choice." Central principle: **baseline starter abilities must NOT be sufficient to comfortably complete a full floor**. **Changes from v3:** - Authored-only (explicitly no procedural generation) - Floors → Rooms → Boss gate hierarchy; 5-8 rooms per floor - Room types: Combat, Elite, Forge, Rest, Event (mechanically distinct) - Each floor must introduce a mechanical constraint that can't be brute-forced with default spells - Respawning encounters on cleared floors allowed (grinding) - G2 forge gate expanded: not just "crafting exists" but **at least one encounter per floor must significantly favor crafted/adapted spells** - G4 pressure mechanics gate added: must include at least 2 of (resource pressure, enemy counterplay, encounter design pressure, build pressure) - New ingenuity_score dimension measures whether player had to adapt - Skills system: scored (not gate) — combat must support at least one non-spell action category but full skill system is bonus - Asset sourcing: attempt-first workflow (find-sprites skill), coherent fallback allowed only when sourcing genuinely fails - Terminology split: UI shows "Traits", code uses `narrativeStats` **Deferred to v5:** - Rune affinity decay when unused - Deep evolution trees (multi-stage mutations) - Full authored spell customization (naming still allowed in v4) **Scoring impact:** - Gates: game-loop, forge-with-ingenuity-payoff, ui-quality, pressure-mechanics (4 gates now) - Composite weights unchanged from v3 (human_review 0.30, low-score caps) - New ingenuity_score as a scored dimension (not yet in composite — evaluated in round 4 results) **Brownfield vs greenfield:** - Greenfield v4 applies to escape-the-dungeon, escape-the-dungeon-bare, escape-the-dungeon-emergent - Brownfield v4 extensions live in `_brownfield-extensions-v4.md` (similar direction, applied to bare v3 baseline) **Decision references:** gad-41 (pressure reframe), gad-42 (skills scored), gad-43 (sprite sourcing), gad-44 (Traits terminology), gad-48 (GAD diagnosis deferred) ---
v3
2026-04-08
**Changes from v2:** - Restructured into explicit `<gate-criteria>` section with 3 numbered gates - **G1 Game loop**: complete cycle title → new game → room → navigate → combat → return → continue - **G2 Spell crafting**: rune forge with combine → create → use. Loot doesn't count. - **G3 UI quality**: icons, styled buttons, HP bars, room-type differentiation, entity sprites/portraits - Added asset sourcing guidance (npm packages > web search > generated > geometric fallback) - Added `<vertical-slice>` build order (UI first, systems after) - Explicit "don't get stuck gold-plating" guardrail for assets **Scoring impact:** - Composite formula v3: weights (0.15, 0.15, 0.15, 0.10, 0.05, 0.30) - human_review weight 0.30 (up from 0.15) - Low-score caps: < 0.20 → 0.40, < 0.10 → 0.25 **Problems that emerged:** - Rune forge was built but not integrated with progression (no affinity, no evolution, no training) - No floor progression — players stuck on first floor forever - No grinding / respawning encounters - Skills (physical actions) vs spells (mana) not differentiated - Narrative stats shown as labels that confused players — needed to be called "Traits" - Agents ignored asset sourcing and used raw text-only UI ---
v2
2026-04-08
**Changes from v1:** - Added 2 gate criteria (production build renders, playable vertical slice) - Added `<vertical-slice>` section describing the UI-first build order - Marked gates with `gate="true"` attribute - Trimmed source gameplay design doc from 640 → 127 lines **Scoring impact:** - Gate criteria override: if any `gate="true"` fails, requirement_coverage = 0 **Problems that emerged:** - Gates helped but bare and GAD still produced broken game loops - UI quality gate was vague — agents produced "raw ASCII" output and claimed it passed - Rune forge (spell crafting) was listed as a criterion but always skipped ---
v1
2026-04-06
**Scope:** Systems-focused. 12 success criteria describing what the agent should build. No gates. No UI quality mandate. No priority on vertical slice. **Problems that emerged:** - Agents built invisible backend systems with no UI - requirement_coverage scored 1.0 while the game showed a blank screen - No way to distinguish "code exists" from "game works" ---