snow_trail/CLAUDE.md

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