1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
# AGENTS.md
## Git discipline
**Every feature or fix gets its own branch.** Never work directly on `main`.
### Starting work
```sh
git checkout -b feat/<short-description> # new feature
git checkout -b fix/<short-description> # bug fix
```
### Committing
- Commit after every meaningful, compiling change — small commits make rollbacks painless.
- Commit messages: imperative, lowercase, no period. E.g. `add attack animation`, `fix entity occlusion`.
- Never commit broken code. Run `cargo build` before every commit.
### Before merging
```sh
git checkout main
git merge --no-ff feat/<branch> # always a merge commit, preserves history
```
### Rollbacks
- `git revert <sha>` to undo a specific commit without rewriting history.
- `git reset --hard <sha>` only on local branches you haven't pushed.
- If a branch goes off the rails, abandon it: `git checkout main && git branch -D feat/broken`.
### Change tracking
- `git --no-pager log --oneline --graph` to visualise history.
- `git --no-pager diff main...feat/branch` to see what a branch adds before merging.
- Tags for milestones: `git tag -a v0.1 -m "turn-based loop + entities + combat"`.
---
## Project structure
```
src/
├── main.rs — window, input, game loop
├── game.rs — game state, maze, entities, combat, inventory, animation
├── renderer.rs — ray-caster, entity sprites, HUD, screen effects
└── texture.rs — procedural texture generation (wall, floor, exit)
docs/
├── PLAN.md — phased implementation plan
├── CONTEXT.md — canonical domain glossary
└── adr/ — architecture decision records
```
## Build & run
```sh
cargo build # debug build
cargo build --release # release (no console on Windows)
cargo run # build + run
```
No external build tools — just `cargo`.
## Code style
- Rust 2024 edition.
- No `ref mut` in patterns (2024 makes it implicit).
- `#[allow(dead_code)]` on deliberately unused scaffolding for future phases.
- Public fields only where needed by other modules; prefer private otherwise.
- Constants for magic numbers (`MOVE_DURATION`, `MAX_HP`, etc.).
- Messages use `.to_uppercase()` for display — the 5×5 font only has uppercase glyphs.
## Design philosophy
- **Turn-based but smooth.** Player actions trigger discrete turns, but all movement is animated (180ms walk, 120ms turn, 120ms attack lunge).
- **One cell, one entity.** A grid cell holds at most one enemy, hallucination, or pickup.
- **The dungeon lies to you.** Hallucinations and fake pickups look real. Sanity controls how much the world gaslights the player.
- **Weakness is hunger, not a timer.** It drains HP to 1 at max, but only enemies can kill you.
|
