# 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.