# CLAUDE.md

Pure Rust game: SDL3 windowing, wgpu rendering, rapier3d physics, low-res retro aesthetic with dithering. Content created in Blender 5.0 (glTF meshes + EXR heightmaps).

## Code Style

- **NO inline comments unless ABSOLUTELY necessary** — code must be self-documenting
- Doc comments (`///`) only for public APIs and complex algorithms
- Run `cargo fmt` before committing (`brace_style = "AlwaysNextLine"`, `control_brace_style = "AlwaysNextLine"`)
- **NO inline paths** — always add `use` statements at the top of files, never inline
- **NO `use` statements inside functions or impl blocks** — all `use` must be at the file (module) level

**Intent-Based Architecture:**
- Systems don't call each other. Cross-system communication goes through **intents** — one-frame typed structs in `Storage<T>` queues on `World`
- Producer inserts intent → consumer reads, acts, removes. Producer doesn't know which system processes it
- The main loop is a flat pipeline; systems self-gate based on data presence
- See `docs/self-gating-systems.md` for full pattern + examples

**Storage Parameters:**
- Functions should take specific storages they need rather than `&World` or `&mut World`
- Pass individual fields (`&world.transforms`, `&mut world.state_machines`) at the call site
- This makes data dependencies explicit for both the borrow checker and the reader

## Architecture

Pure ECS: entities are IDs, components are plain data in `HashMap<EntityHandle, T>` storages, systems are functions receiving `&mut World`. No `Rc<RefCell<>>`.

## Sub-Agents & Codebase Exploration

**Use the `explorer` sub-agent for all codebase work.** Unless the target is trivially obvious (e.g., you already know the exact file path and line number) and unless you are the explorer agent. This includes:
- Understanding existing code before making changes
- Searching for related functions/types
- Investigating bugs or architectural patterns
- Finding usages of a function across the codebase
