diff --git a/Notes/Clarification Q&A.txt b/Notes/Clarification Q&A.txt new file mode 100644 index 0000000..7864b77 --- /dev/null +++ b/Notes/Clarification Q&A.txt @@ -0,0 +1,12 @@ +Implementation Clarification Q&A: +--------------------------------- +1. Should the app keep full room geometry internally and show a cleaner simplified map visually, or do you want the visible map to be as literal as the paper layout? +2. Do you want to support player-entered/manual dice at all, or should MVP stay fully automated with only a roll log? +3. For in-app presentation, should we favor short flavor snippets plus structured effects, rather than reproducing long room text from the books? +4. Do you want lightweight debug/recovery tools planned from the start for blocked generation states, or should we keep the production flow completely clean and handle edge-case recovery only in code/tests? + +1. Let's opt for configurable, but default to clean map visually with the geometry tracked internally. This allows us to have a more user-friendly interface while still maintaining the necessary data for game mechanics. +2. For MVP, let's keep it fully automated with only a roll log. This will simplify the initial development and allow us to focus on core features. We can consider adding manual dice input in future updates based on user feedback. +3. Let's favor short flavor snippets plus structured effects for in-app presentation. This will make the content more digestible and engaging for players, while still conveying the necessary information effectively. +4. Let's plan for lightweight debug/recovery tools from the start. This will help us quickly identify and resolve any issues that arise during development and testing, ensuring a smoother user experience and faster iteration cycles. + diff --git a/Planning/IMPLEMENTATION_NOTES.md b/Planning/IMPLEMENTATION_NOTES.md new file mode 100644 index 0000000..e1c2ff8 --- /dev/null +++ b/Planning/IMPLEMENTATION_NOTES.md @@ -0,0 +1,415 @@ +# 2D6 Dungeon Implementation Notes + +## Purpose +This document records the digital-only rulings needed to implement **2D6 Dungeon** as a web app. + +It exists because the books describe a paper play experience, and some parts rely on: + +- player judgment +- manual map drawing +- flexible interpretation of room text +- ad hoc bookkeeping + +The goal here is to make those areas deterministic enough for software without losing the feel of the original game. + +This document should be treated as: + +- the source of truth for adaptation choices +- a companion to `GAME_SPEC.md` +- a guide for coding heuristics and tests + +## Scope +These notes cover: + +- what the app automates +- what the player still chooses manually +- how ambiguous rules should be resolved in code +- where MVP intentionally simplifies the physical game flow + +These notes do **not** replace the rulebooks. They explain how the app should behave when the books leave room for interpretation. + +## Adaptation Principles + +### 1. Preserve rules outcomes, not paper rituals +The app should preserve the gameplay consequences of the books even when the physical procedure changes. + +Examples: + +- automatically logging calculations instead of requiring note-taking +- rendering a generated map instead of requiring player drawing +- resolving table lookups in-app instead of asking players to cross-reference PDFs + +### 2. Prefer explicit player confirmation over hidden automation +If a rule has a meaningful tactical or strategic choice, the app should ask. + +If a rule is pure bookkeeping, the app should automate it. + +### 3. Keep ambiguity visible +When the app applies a heuristic, it should log: + +- what rule area triggered +- what choice the engine made +- why it made that choice + +### 4. Separate flavor from mechanics +Where possible, descriptive room text should be stored separately from mechanical effects so the engine can act deterministically. + +## MVP Defaults +These are the default implementation decisions unless superseded later. + +- MVP supports one adventurer and one active campaign. +- MVP supports Level 1 only. +- MVP uses encoded structured content instead of freeform text parsing. +- MVP automates all table rolls and does not support player-entered dice. +- MVP keeps a visible roll log, including primary and secondary die for `D66`. +- MVP uses deterministic heuristics for map generation and edge-case resolution. +- MVP keeps optional tables out of the default ruleset. +- MVP should include lightweight debug and recovery tooling in development builds. + +## Automation Boundaries + +### The app should automate + +- dice rolling +- modifier application +- modified-range clamping +- room generation +- room connectivity validation +- encounter lookup +- combat arithmetic +- armour reduction and deflection handling +- XP updates +- inventory quantity changes +- save/load and autosave + +### The player should choose + +- starting weapon +- starting armour +- starting scroll +- movement direction when multiple exits are available +- when to use potions or scrolls +- combat manoeuvre selection +- whether to continue exploring or leave the dungeon +- town purchase and service choices + +### The app should confirm before applying + +- leaving the current level +- consuming one-time items +- selling valuable or quest-like items +- any action that would end a run or lock out a choice + +## Dice And Roll Presentation + +### Default behavior + +- All rolls are performed by the engine. +- Every roll is logged with raw dice, modifiers, and final result. +- `D66` logs must preserve: + - first die + - second die + - combined number + - whether a modifier/clamp changed the lookup result + +### UI note +The interface should visually distinguish: + +- raw roll +- modifier +- final lookup result + +This matters because many outcomes will otherwise feel opaque in a digital version. + +Manual dice entry is intentionally out of scope for MVP. + +## Map Generation Heuristics + +### Internal representation +Use a true room-and-exit graph with spatial coordinates. + +Each room should have: + +- grid origin +- width and height +- connected exits +- room class +- generation source tables + +The visual map can be simplified, but the internal representation should preserve geometry well enough to support: + +- overlap checks +- boundary checks +- last-room logic +- secret door fallback logic + +### Visual map modes +Map display should be configurable. + +Default behavior: + +- show a cleaner player-friendly rendered map +- keep full underlying room geometry for rules and validation + +Future-friendly behavior: + +- allow a more literal geometry-heavy rendering mode later without changing saved data + +### Coordinate system + +- Use integer grid coordinates. +- Treat each room as a rectangle on the level plane. +- Exits connect through wall midpoints rather than abstract node links only. + +### Collision handling +When generated room geometry would overlap an existing room: + +1. Attempt legal placement using the generated exit direction and dimensions. +2. If placement is invalid, mark the attempted exit as blocked for this generation pass. +3. If all generated exits are invalid, trigger the fallback flow for stalled progression. + +### Boundary handling +If a generated room extends outside the legal dungeon boundary: + +1. Do not resize the room silently. +2. Reject the placement. +3. Continue trying other legal generated exits if available. +4. If no legal exits remain, use the same stalled-progression fallback. + +### Room permanence +Once a room is generated and placed, it should not be regenerated differently on reload or after backtracking. + +### Last-room logic +For MVP, define the "last room" operationally: + +- it is the most recently generated reachable uncleared room on the active level when no other forward generation options remain +- if the rulebook requires a special feature to appear in the last room, the engine should assign it only after reachability has been evaluated against the current known graph + +This avoids trying to infer narrative intent from room flavor. + +## Stalled Progression And Secret Door Fallback + +### Trigger condition +Treat progression as stalled when: + +- the player has no unresolved reachable exits that can generate a new room +- the required reveal threshold or level-completion condition has not been met + +### MVP fallback rule +When stalled progression is detected: + +1. Search eligible existing rooms in reverse discovery order. +2. Select the most recently discovered room that can legally host a secret exit. +3. Create one secret door/exit there. +4. Log that the fallback rule was used. +5. Mark the level so the fallback cannot be applied repeatedly unless the rules explicitly allow it. + +### Eligibility rules +A room is eligible for fallback if: + +- it is reachable +- it is already generated +- it has wall space for another exit +- adding the exit can produce a legal new room placement + +### Reasoning +This keeps the game moving while avoiding hidden retries that would make map generation feel arbitrary. + +## Room Content And Text Handling + +### Content storage rule +Room results should be encoded as: + +1. structured mechanical fields +2. optional flavor text +3. explicit references to follow-up tables or entities + +Do not rely on runtime parsing of prose to determine rules. + +### Verbatim text policy +Use book text sparingly in the app and store it as display content, not executable logic. + +Implementation note: + +- if a room paragraph mixes flavor and mechanics, split it during content entry +- keep a source reference so the original wording is traceable during validation +- favor short flavor snippets in the main gameplay UI, with structured mechanical effects driving resolution + +### Unique and narrative rooms +When a room or result is effectively unique: + +- add a uniqueness flag in content +- track whether it has already appeared in campaign or run state +- prevent duplicate generation unless the books explicitly allow repeats + +## Encounter Generation + +### Encounter lookup +Encounter resolution should be a two-step process: + +1. determine encounter type from the room/level table +2. resolve creature or event content from the referenced table/card + +This preserves traceability and makes it easier to validate incomplete data. + +### Multi-enemy groups +When a result generates multiple creatures: + +- store them as separate combatants linked to one encounter +- keep a shared encounter source +- allow combat logs to refer to both the encounter and the individual creature instances + +## Combat Resolution Notes + +### Combat visibility +Combat must always show: + +- selected manoeuvre +- roll used +- exact strike or other bonuses +- shift spent +- damage dealt +- armour prevented +- interrupt effects +- fatigue effects + +### Interrupt handling +For MVP: + +- interrupts should pause normal combat resolution and create an explicit pending interrupt state +- the engine resolves the interrupt fully before continuing the original action + +### Fatigue handling +Fatigue should be represented as explicit round-based state, not inferred on the fly from the combat log. + +This makes saves and tests much more reliable. + +### Simultaneous effects +When two effects could reasonably happen at the same time, use this priority: + +1. trigger interrupts +2. apply hit/miss determination +3. apply armour/deflection +4. apply damage +5. apply defeat checks +6. apply post-hit or post-kill rewards/effects + +If the books later define a stricter order for a specific edge case, that specific rule overrides this general priority. + +## Inventory And Economy Rules + +### Inventory tracking +The app should track quantities explicitly for: + +- rations +- potions +- scrolls +- treasure +- light sources +- stackable loot + +### Identification +For MVP, use a simple boolean identified state where content requires it. + +Do not build a more elaborate unidentified-item subsystem unless the source material clearly needs it. + +### Sell protection +Items tagged as `quest` or `unique` should trigger a confirmation before sale or disposal. + +## Save System Rules + +### Autosave policy +Autosave should occur after: + +- room generation +- room resolution +- combat round resolution +- inventory changes +- town actions +- level transitions + +### Save integrity +A save must include: + +- campaign state +- active run state, if any +- content version +- rules version +- enough roll/log history to explain the latest state transitions + +### Determinism policy +Once a roll or room generation result has occurred, it should be stored, not re-rolled on load. + +## Error Handling And Manual Recovery + +### Missing content reference +If a rule points to missing encoded data: + +1. block only the affected action +2. show a developer-readable error message +3. preserve the save +4. log the missing table or content ID + +### Impossible generation state +If the engine reaches a state where no legal room can be placed and fallback has already been used: + +1. mark the run as blocked, not corrupted +2. expose a debug/admin recovery action in development builds +3. log the full generation context for diagnosis + +### Debug tooling expectation +Plan lightweight developer-facing recovery tools from the start. + +Initial scope: + +- inspect current room graph and unresolved exits +- inspect the latest generation and roll logs +- force-save diagnostic snapshots +- manually unblock a run in development mode only + +## Content Entry Conventions + +### Table encoding +Each encoded table should include: + +- source book +- source page +- table code +- dice type +- result keys +- structured effects where possible +- freeform notes only when mechanics cannot be fully structured yet + +### Traceability +Every creature, room, and item should preserve a link back to: + +- source page +- originating table, when applicable + +### MVP content status +For MVP, content can be entered in three passes: + +1. minimally playable structured data +2. improved rules annotations +3. richer flavor and display text + +## Testing Notes + +The most important adaptation-specific tests are: + +1. `D66` primary/secondary order is preserved in logs and lookups. +2. Modified ranges clamp to the nearest legal result. +3. Room generation never creates overlapping rooms. +4. Secret door fallback triggers exactly once under the chosen MVP rule. +5. Reloading a save does not change previously generated rooms or rolls. +6. Interrupts pause and resume combat in the correct order. +7. Unique room or event results do not duplicate after save/load or backtracking. + +## Confirmed Product Decisions + +These decisions are approved for planning and implementation: + +1. Map display should be configurable, with a clean visual map as the default and full internal geometry preserved for rules. +2. MVP should remain fully automated for dice, with transparency provided through the roll log rather than player-entered rolls. +3. In-app presentation should favor short flavor snippets plus structured mechanical effects. +4. Lightweight debug and recovery tools should be planned from the start for development use. diff --git a/Source/2D6 Dungeon - Play Sheet.pdf b/Source/2D6 Dungeon - Play Sheet.pdf new file mode 100644 index 0000000..ec91330 Binary files /dev/null and b/Source/2D6 Dungeon - Play Sheet.pdf differ