wlls.dev
This repository has no description
1# Development Path
2
3Thanatograph should be built around one early question:
4
5Can a previous failed run become a readable, physical actor that the player can use, fear, and plan around?
6
7Everything else should serve that test until the answer is clearly yes.
8
9## Current State
10
11- Odin/Raylib project scaffold is in place.
12- Hot reload and release builds already exist.
13- `src/game` currently owns only the exported game API, a `Game_Memory` pointer, and a blank render frame.
14- The pitch defines a strong core mechanic, but no gameplay systems exist yet.
15
16## Development Principles
17
18- Prove the echo mechanic before building a broad roguelike.
19- Prefer deterministic fixed-step simulation for gameplay, even if rendering stays variable.
20- Keep persistent run history explicit and inspectable.
21- Treat `src/sim` as the authoritative gameplay boundary. It should be runnable and testable without Raylib, rendering, frame-time, or platform APIs.
22- Recreate runs from deterministic causes: simulation version/config, seed, initial state descriptor, and one command per tick. Use transcripts for proof and debugging, not as gameplay authority.
23- Keep dungeon scope tiny until echo interaction is fun.
24- Build tooling only when it shortens iteration on the core loop.
25- Avoid engine generality unless the game immediately benefits from it.
26
27## Core Technical Risks
28
29- Deterministic replay must be stable enough that echoes feel like past selves, not approximate ghosts.
30- Authoritative simulation must avoid platform-dependent behavior, including wall-clock time, render frames, unordered iteration, global random state, and replay-relevant raw floats where quantized/fixed values would be safer.
31- Echoes need local recovery when the live world diverges, without losing the emotional truth of replay.
32- Combat must stay readable when live player, enemies, and multiple echoes interact.
33- Gear recovery needs clear ownership rules to avoid duplication exploits and player confusion.
34- Hot reload is useful, but `Game_Memory` changes currently restart memory, so long-lived history should eventually sit behind stable allocations or serialization.
35
36## First Playable Target
37
38The first playable should be an echo laboratory, not a full dungeon crawler.
39
40Target experience:
41
42- Start in a small room-and-corridor dungeon.
43- Move, attack, take damage, die, and restart.
44- On the next run, the previous run replays as a physical echo.
45- The echo can collide, distract an enemy, attack, and die.
46- A death marker appears where the original run ended.
47- If the echo reaches its death marker, it resolves visibly.
48
49If this is not compelling with one room, one enemy, one weapon, and one echo, adding more content will not fix it.
50
51## Suggested Architecture Order
52
531. Establish an app/game loop split inside `src/game` and an authoritative `src/sim` boundary.
542. Add a deterministic fixed-timestep simulation clock and command-history replay substrate.
553. Add a headless run harness that can drive simulation from text/scripted input and emit deterministic transcript/digest output.
564. Render a primitive player/room only after the headless simulation path exists.
575. Define a minimal world model: tiles, actors, hitboxes, health, attacks, and simple room reset.
586. Replay an echo by feeding recorded input into the same actor controller.
597. Add guide tracks, landmarks, deviation scoring, local correction, and severing.
608. Add death events, remembered gear, and corpse recovery as data owned by run history.
619. Expand dungeon generation/content after the run/echo loop is proven.
62
63## Three-Month Milestones
64
65### Month 1: Mechanic Prototype
66
67Goal: one death creates one useful physical echo.
68
69- Fixed-step simulation.
70- Top-down movement and collision.
71- One test dungeon layout.
72- One melee attack.
73- One enemy type with simple pursuit/attack behavior.
74- Player death and run restart.
75- Input recording and deterministic replay.
76- One echo replaying the previous run.
77- Basic debug overlay for tick, run id, actor count, and replay state.
78
79Exit criteria:
80
81- A previous run can distract or damage an enemy in a way the current player can exploit.
82- Replay is stable across repeated restarts for the same recorded input.
83
84### Month 2: Game Loop Prototype
85
86Goal: echoes become strategic resources with consequences.
87
88- Multiple stored death events.
89- Multiple simultaneous echoes with caps if needed.
90- Echo death-marker resolution.
91- Corpse and remembered gear recovery.
92- Random live-run loot with non-duplicating remembered gear.
93- Two or three enemy types.
94- Traps or doors that make routing matter.
95- First pass at rooms connected into a small dungeon.
96
97Exit criteria:
98
99- The player can intentionally route a bad run to create a future advantage.
100- Recovering gear from a past death creates a meaningful risk/reward decision.
101
102### Month 3: Vertical Slice
103
104Goal: a short, shippable-feeling dungeon with the core identity intact.
105
106- One cohesive dungeon theme.
107- Three to five enemy types total.
108- One boss designed around echo interaction.
109- Echo resolution outcomes: evaporate, corrupt, rare ally.
110- Basic title, run start, death, and victory flow.
111- Audio and visual readability pass.
112- Performance and memory pass.
113- Release build packaging pass.
114
115Exit criteria:
116
117- A new player can understand why an echo exists and make at least one clever use of it without explanation.
118- The game can be played for 10-20 minutes and produce memorable failure stories.
119
120## Near-Term Implementation Queue
121
1221. Build deterministic fixed-step simulation and command-history replay in `src/sim`.
1232. Add canonical state digest/comparison and a command-line replay test recipe.
1243. Add a headless text/script harness that can run simulation without Raylib and emit stable transcript output.
1254. Render a controllable player marker in a fixed arena from simulation state.
1265. Add simple tile collision.
1276. Add one enemy and health/death.
1287. Restart after death and spawn an echo from the prior input history.
1298. Make the echo share the same movement/combat code path as the player.
1309. Add guide tracks, landmarks, deviation scoring, local correction, and severing.
13110. Add death markers, corpse/gear ownership, and simple resolution when an echo reaches its marker.
132
133## Early Non-Goals
134
135- Procedural generation.
136- Inventory UI.
137- Complex animation.
138- Save files.
139- Complex narrative systems.
140- Online features.
141- More than one player character.
142
143## Open Design Questions
144
145- Should echoes collide with the live player, or only with enemies/world geometry? **For now, let's have them phase through player**
146- Should replay store raw inputs, resolved intentions, or both? **Current direction: store normalized, quantized simulation commands as the causative record; store derived transcript/landmarks for proof, debugging, and echo correction.**
147- Should enemies be deterministic per run seed, or should echoes adapt to changed enemy positions immediately? **Need to think through this still**
148- How many echoes can be present before readability breaks?
149- Is corruption random, condition-based, or both? **All outcomes of echoes at end of life are random. Dissolution should be highest chance, with corruption / allyship as rarer events. My initial thought was 4/6 chance for dissolution, 1/6 for ally, 1/6 for corrupt.**
150
151## Design Notes
152
153Top-down camera centered on player, not perfectly rigid.
154- follow player with slight smoothing
155- small mouse/look-ahead offset
156- player viewport modest so offscreen timing matters
157- no free camera pan in core game
158
159Movement is continuous and real-time
160- WASD / left stick movement
161- mouse / right stick for facing / aim
162- immediate acceleration
163- simple collision circles/capsules against tile walls
164- no stamina, consider dodge
165- brief commitment windows
166
167Visibility is low light / fog for gameplay readability, not just atmosphere
168
169Fixed authoritative simulation at 60hz with variable rendering
170- game state only changes in fixed simulation ticks, rendering reads state and draws it
171- real frame time -> accumulator -> 0..N fixed sim ticks -> render once
172- SIM_HZ = 60, SIM_DT = 1.0 / 60.0