From afff34fff4dff57f3103e752b7120870537ce5d9 Mon Sep 17 00:00:00 2001 From: Jonas Haugesen Date: Tue, 7 Apr 2026 03:02:29 +0200 Subject: [PATCH] docs: panopticon auto-update for snow_trail --- .pi/skills/panopticon/SKILL.md | 2 +- .pi/skills/panopticon/changelog.md | 62 ++++++++------ .pi/skills/panopticon/guide.md | 130 +++++++++++++++-------------- .pi/skills/panopticon/structure.md | 46 +++++----- 4 files changed, 131 insertions(+), 109 deletions(-) diff --git a/.pi/skills/panopticon/SKILL.md b/.pi/skills/panopticon/SKILL.md index 1b2afbb..270e9b8 100644 --- a/.pi/skills/panopticon/SKILL.md +++ b/.pi/skills/panopticon/SKILL.md @@ -21,4 +21,4 @@ Pure Rust retro-aesthetic 3D game using SDL3 windowing, wgpu rendering, and rapi - [Structure](structure.md) — modules, types, data flow, dependencies - [Guide](guide.md) — conventions, patterns, anti-patterns, testing -- [Changelog](changelog.md) — recent changes, active areas, stability +- [Changelog](changelog.md) — recent changes, active areas, stability \ No newline at end of file diff --git a/.pi/skills/panopticon/changelog.md b/.pi/skills/panopticon/changelog.md index 4fed7b5..31b320d 100644 --- a/.pi/skills/panopticon/changelog.md +++ b/.pi/skills/panopticon/changelog.md @@ -1,25 +1,32 @@ # Changelog -*Last updated: Friday, April 3, 2026* +*Last updated: Tuesday, April 7, 2026* ## Active Areas | Area | Changes (30d) | Status | |------|---|---| -| Main loop & systems | 9 churn | Active — intent-based architecture solidifying | +| Main loop & systems | 9 churn | Active — explicit storage parameters | | Dialog system | 10 churn | Active — projectiles, camera, rendering | | Render core | 15 churn | Active — text pipeline, font atlas, globals | | World state | 8 churn | Active — intent storage, component management | | Player mechanics | 6 churn | Stable — character bundle, player states | | Shader system | 4 churn | Active — gizmo lines, dissolve, snow light | +| Content pipeline | 1 churn | New — Blender export addon | ## Recent Changes +### System Signature Refactor (Major) +- **Completed**: All 16 systems refactored to take explicit `Storage` parameters instead of `&World`/`&mut World`. +- **Pattern**: Functions receive only storages they need (e.g., `camera_follow_system` takes `&Storage`, `&Storage`, `&mut Storage`). +- **Benefit**: Explicit data dependencies improve borrow checker clarity and code readability. +- **Main loop** (`src/main.rs`): Updated to pass individual storage fields at call sites rather than whole `World` reference. +- **Affected systems**: `camera_input_system`, `camera_intent_system`, `camera_follow_system`, `camera_noclip_system`, `camera_ground_clamp_system`, `dialog_camera_transition_system`, `dialog_camera_system`, `player_input_system`, `physics_sync_system`, `render_system`, `particle_intent_system`, `particle_update_system`, `trigger_system`, `dialog_system`, `dialog_projectile_system`, all state machines. + ### Intent-Based Architecture -- **Completed major refactor** (3 weeks ago): Systems now communicate through one-frame `Storage` intents instead of direct function calls. -- **Intent types**: `FollowPlayerIntent`, `StopFollowingIntent`, `CameraTransitionIntent`, `SpawnParticleIntent` +- **Completed major refactor** (3 weeks ago): Systems communicate through one-frame `Storage` intents instead of direct function calls. +- **Intent types**: `FollowPlayerIntent`, `StopFollowingIntent`, `CameraTransitionIntent`, `SpawnParticleIntent`. - **Consumer pattern**: Systems read intents from world storage, act on them, then remove them. Producers don't import consumer modules. -- **Documented pattern** in `docs/intent-based-architecture.md` with full execution order contract. ### Dialog System Suite - **Dialog state machine**: Ink-based story progression with display timer, projectile phases, parry mechanics. @@ -33,51 +40,58 @@ - **Vertex-based text**: Custom `TextVertex` (position, UV) fed into dedicated text pipeline with view-proj uniform. ### Particle System -- **Intent-driven spawning**: `SpawnParticleIntent` queues particle emissions; `particle_intent_system` transfers into persistent `ParticleBuffers`. +- **Intent-driven spawning**: `particle_intent_system` reads `spawn_particle_intents` Vec, transfers configs into persistent `ParticleBuffers`. - **Configurable emitters**: Burst count, lifetime range, speed range, directional spread (cone), gravity, size range, color gradient. -- **Snow particle integration**: Spawned continuously at camera position for screen-fill effect. +- **Snow particle integration**: Spawned continuously at camera position for screen-fill effect; `spawn_snow_particles` adds particles to `ParticleBuffers`. ### Render Pipeline -- **Global renderer via thread-local**: `render::global` module centralizes `Device`/`Queue` access for loaders and systems; long-term goal is explicit `RenderContext` params. -- **Gizmo shader**: Fragment shader outputs world-normal as axis color (X=red, Y=green, Z=blue) for entity transform editing. -- **Snow light accumulation**: Persistent texture tracking deformation; blue-noise dithering maps snow brightness into tile pattern (brightness > threshold → dither step). +- **Global renderer via thread-local**: `render::global` module centralizes `Device`/`Queue` access for loaders and systems. +- **Draw call generation**: `render_system` reads `entities`, `transforms`, `meshes`, `dissolves` storages; generates `DrawCall` per visible entity. +- **Gizmo shader**: Fragment shader outputs world-normal as axis color (X=red, Y=green, Z=blue). +- **Snow light accumulation**: Persistent texture tracking deformation; blue-noise dithering maps snow brightness into tile pattern. - **Dissolve shader**: Blue-noise masked alpha cutoff; controlled by `enable_dissolve` uniform. ### Tree Occlusion & Instances -- **Tree dissolve system**: Per-instance dissolve amounts lerp toward targets at configurable speed. -- **Occlusion detection**: Instances between camera and player dissolve based on perpendicular distance to camera-to-player ray. -- **Instance buffer sync**: Tree instances updated into GPU buffer after dissolve state changes. +- **Tree dissolve system**: Per-instance dissolve amounts lerp toward targets; updated via `tree_occlusion_system` which reads player transforms and cameras. +- **Instance buffer sync**: `tree_instance_buffer_update_system` syncs dissolve state changes to GPU buffer after state updates. ### Trigger & Event Flow -- **Sphere-based triggers**: Continuous state tracking (Idle ↔ Inside); fires `TriggerEvent` with `Entered`/`Exited` kinds. +- **Sphere-based triggers**: `trigger_system` runs each fixed step; reads `triggers`, `transforms`, `player_tags` storages; fires `TriggerEvent` with `Entered`/`Exited` kinds. - **Activation filtering**: `TriggerFilter::Player` specifies which entity types can activate. -- **Event queue**: Events collected in `world.trigger_events` and consumed by dialog system to spawn bubbles. +- **Event queue**: Events collected in `world.trigger_events` and consumed by `dialog_system` to spawn bubbles. ### Player State Machine - **State hierarchy**: Idle, Walking, Jumping, Falling, Leaping (dash), Rolling. +- **Physics per-state**: `state_machine_physics_system` applies damping on enter (Idle), horizontal input application (Walking), vertical velocity control (Jumping). - **Transition logic**: Grounded checks, input presence, airtime duration. -- **Physics per-state**: Damping on enter (Idle), horizontal input application (Walking), vertical velocity control (Jumping). ### Editor & Inspector - **Dear ImGui integration**: Inspector window with player state display, entity transform gizmos. -- **Entity selection**: Right-click picking; gizmo renders for selected entity when editor active. +- **Entity selection**: Right-click picking calls `picking::pick_entity` with ray; gizmo renders for selected entity when editor active. - **UI mode gating**: Systems check `editor.wants_keyboard()`/`wants_mouse()` to suppress game input during inspector focus. +### Blender Export Addon +- **Plugin**: `blender/addons/snow_trail_export.py` provides one-click glTF + EXR export from Blender 5.0. +- **glTF operator** (`SNOWTRAIL_OT_export_gltf`): Exports selected mesh objects to `assets/meshes/{blend_filename}.gltf` with configurable modifiers, vertex colors, materials. +- **Heightmap bake operator** (`SNOWTRAIL_OT_export_heightmap`): Calls `generate_heightmap.py` to bake terrain Z-position as 32-bit EXR to `assets/textures/terrain_heightmap.exr` (1024px default). +- **UI panel**: "Snow Trail" category in 3D viewport; auto-discovers project root by walking directory tree until `assets/` and `blender/` found. + ## Stability | Area | Last Changed | Status | |---|---|---| | Physics manager | 80+ days | Stable | -| Camera follow | 30 days | Stable — intent system reduced coupling | +| Camera follow | 30 days | Stable — now takes explicit storage params | | Movement component | 30+ days | Stable | | Mesh loader | 30+ days | Stable | -| Spotlight sync | 30 days | Stable | -| State machine physics | 30 days | Stable — core transitions unchanged | +| Spotlight sync | 30 days | Stable — explicit storage params applied | +| State machine physics | 30 days | Stable | | Debug colliders | 30+ days | Stable | +| System signatures | New | Stable — refactor complete, no behavioral changes | ## Open Threads -- **Global renderer thread-local**: Marked for gradual migration to explicit `RenderContext` parameters on systems/loaders. Current implementation works; refactor is low-priority. -- **Text rendering completeness**: Font atlas + text pipeline in place; scaling and color support functional. No known issues. -- **Dialog parry mechanics**: Projectile system complete; integration with Ink outcomes working. Gameplay tuning (PARRY_WINDOW_RADIUS, HIT_RADIUS) ongoing. -- **Tree occlusion performance**: Occlusion system runs every frame; no visibility culling yet. Scalability unknown for >100 trees. \ No newline at end of file +- **Global renderer thread-local**: Marked for gradual migration to explicit `RenderContext` parameters on systems/loaders. +- **Dialog parry mechanics**: Gameplay tuning (PARRY_WINDOW_RADIUS, HIT_RADIUS) ongoing. +- **Tree occlusion performance**: Occlusion system runs every frame; no visibility culling yet. Scalability unknown for >100 trees. +- **Heightmap bake normalization**: Exported EXR uses raw Z-coordinate; game may need per-level scale application. \ No newline at end of file diff --git a/.pi/skills/panopticon/guide.md b/.pi/skills/panopticon/guide.md index e0a0064..6bdcb3d 100644 --- a/.pi/skills/panopticon/guide.md +++ b/.pi/skills/panopticon/guide.md @@ -42,16 +42,24 @@ pub struct CameraTransitionIntent { } // systems/camera.rs - consumer -pub fn camera_intent_system(world: &mut World) { - let transition_entities: Vec = world.camera_transition_intents.all(); +pub fn camera_intent_system( + follow_player_intents: &mut Storage, + stop_following_intents: &mut Storage, + camera_transition_intents: &mut Storage, + follows: &mut Storage, + transforms: &mut Storage, + cameras: &mut Storage, + player_tags: &Storage<()>, + camera_transitions: &mut Storage, +) { + let transition_entities: Vec = camera_transition_intents.all(); for entity in transition_entities { - let duration = world - .camera_transition_intents + let duration = camera_transition_intents .get(entity) .map(|i| i.duration) .unwrap_or(0.5); - start_camera_transition(world, entity, duration); - world.camera_transition_intents.remove(entity); // consumed + start_camera_transition(camera_transitions, transforms, cameras, entity, duration); + camera_transition_intents.remove(entity); } } ``` @@ -135,18 +143,17 @@ state_machine.add_transition::(move |world| { ```rust // systems/spotlight_sync.rs -pub fn spotlight_sync_system(world: &World) -> Vec { - let mut spotlights = Vec::new(); - for entity in world.spotlights.all() { - // Closure captures immutably—safe to call multiple times - if let Some(spotlight_component) = world.spotlights.get(entity) { - if let Some(transform) = world.transforms.get(entity) { +pub fn spotlight_sync_system(spotlights: &Storage, transforms: &Storage) -> Vec { + let mut result = Vec::new(); + for entity in spotlights.all() { + if let Some(spotlight_component) = spotlights.get(entity) { + if let Some(transform) = transforms.get(entity) { let position = transform.position + spotlight_component.offset; - spotlights.push(Spotlight::new(position, ..)); + result.push(Spotlight::new(position, ..)); } } } - spotlights + result } // With mutation @@ -155,25 +162,46 @@ world.movements.with_mut(entity, |movement| { }); ``` -### System Function Signature -**Why**: Pass only the storages (or immutable `World`) that the system needs. Makes data dependencies explicit. +### System Function Signature (Explicit Storage Parameters) +**Why**: Pass only the specific storages (or read-only `&World`) that the system needs. Makes data dependencies explicit for the reader and borrow checker. **This is the standard pattern—all systems follow this.** ```rust // Good: explicit dependencies -pub fn camera_follow_system(world: &mut World) { - let camera_entities: Vec<_> = world.follows.all(); +pub fn camera_follow_system( + follows: &mut Storage, + cameras: &Storage, + transforms: &mut Storage, +) { + let camera_entities: Vec<_> = follows.all(); for camera_entity in camera_entities { - // Access what's needed - if let Some(follow) = world.follows.get(camera_entity) { - world.transforms.with_mut(camera_entity, |t| { - t.position = target_position + new_offset; - }); + if let Some(follow) = follows.get(camera_entity) { + if let Some(camera) = cameras.get(camera_entity) { + transforms.with_mut(camera_entity, |t| { + t.position = follow.target_position + new_offset; + }); + } } } } -// For read-only systems -pub fn spotlight_sync_system(world: &World) -> Vec { .. } +// Read-only system +pub fn spotlight_sync_system(spotlights: &Storage, transforms: &Storage) -> Vec { .. } + +// Dialog system example +pub fn dialog_system( + entities: &mut EntityManager, + trigger_events: &[TriggerEvent], + dialog_sources: &Storage, + bubble_tags: &mut Storage<()>, + dialog_bubbles: &mut Storage, + transforms: &mut Storage, + names: &mut Storage, + player_tags: &Storage<()>, + projectile_tags: &mut Storage<()>, + dialog_projectiles: &mut Storage, + dialog_outcomes: &mut Vec, + delta: f32, +) { .. } ``` ### Default Trait for Configuration Components @@ -227,14 +255,14 @@ fn system_a(world: &mut World) { **Do this instead:** ```rust // ✅ Good: intent in queue, flat pipeline -pub fn system_a(world: &mut World) { - world.some_intents.insert(entity, MyIntent { .. }); +pub fn system_a(cameras: &mut Storage) { + cameras.insert(entity, CameraTransitionIntent { .. }); } -pub fn system_b(world: &mut World) { - for entity in world.some_intents.all() { +pub fn system_b(camera_transitions: &mut Storage) { + for entity in camera_transitions.all() { // process - world.some_intents.remove(entity); + camera_transitions.remove(entity); } } ``` @@ -273,46 +301,24 @@ use crate::physics::PhysicsManager; let velocity = *PhysicsManager::with_rigidbody_mut(..); ``` -### Global or Context-Based Component Queries -**Don't do this:** -```rust -// ❌ Bad: loses intent, repeats queries -for entity in world.meshes.all() { - if let Some(mesh) = world.meshes.get(entity) { .. } -} -for entity in world.meshes.all() { - if let Some(mesh) = world.meshes.get(entity) { .. } -} -``` - -**Do this instead:** -```rust -// ✅ Good: query once, iterate clearly -let entities: Vec<_> = world.meshes.all(); -for entity in entities { - if let Some(mesh_comp) = world.meshes.get(entity) { - // process - } -} -``` - ### Overly Generic (World/&mut World) Parameters **Don't do this:** ```rust -// ❌ Bad: implicit dependencies -fn update_position(world: &mut World, entity: EntityHandle) { - // What do we actually need? +// ❌ Bad: implicit dependencies, breaks borrow checker +pub fn camera_follow_system(world: &mut World) { + // What storages do we actually need? } ``` **Do this instead:** ```rust -// ✅ Good: explicit dependencies -fn update_position( +// ✅ Good: explicit, focused dependencies +pub fn camera_follow_system( + follows: &mut Storage, + cameras: &Storage, transforms: &mut Storage, - entity: EntityHandle, ) { - transforms.with_mut(entity, |t| t.position.y += 1.0); + // Clear what data is needed } ``` @@ -351,4 +357,6 @@ cargo test -- --nocapture # Show output - See **CLAUDE.md** in project root for authoritative style rules (no inline comments, doc comments for public APIs only) - See **docs/self-gating-systems.md** for detailed intent-based pipeline patterns - See `src/states/player_states.rs` for canonical State impl examples -- See `src/bundles/player.rs` for complete Bundle pattern with state machine setup \ No newline at end of file +- See `src/bundles/player.rs` for complete Bundle pattern with state machine setup +- See `src/systems/camera.rs` for canonical system function signatures with explicit storage parameters +- See `src/systems/dialog_system.rs` for complex multi-storage system example \ No newline at end of file diff --git a/.pi/skills/panopticon/structure.md b/.pi/skills/panopticon/structure.md index 5b12a97..2ba0485 100644 --- a/.pi/skills/panopticon/structure.md +++ b/.pi/skills/panopticon/structure.md @@ -25,16 +25,16 @@ Component types define entity data. Key storages: Per-entity state machine: `StateMachine` holds current `TypeId`, registered state types, and transitions. `State` trait defines lifecycle (`on_enter`, `on_physics_update`, `on_exit`). Transitions are condition predicates checked each update. Player entity uses this for locomotion states. ### `src/systems/` -Flat list of update functions called in main loop. No cross-system coupling; all communication via world state and intents. -- **Camera**: `camera_input_system` → generates intents; `camera_intent_system` consumes them; `camera_follow_system` (follows player), `camera_noclip_system`, `camera_transition_system`, `camera_ground_clamp_system` -- **Input**: `player_input_system` reads SDL3 `InputState`, writes `InputComponent` -- **Physics**: `state_machine_physics_system` (fixed-step), `PhysicsManager::physics_step()`, `physics_sync_system` (copies rapier bodies back to transforms), `trigger_system` (AABB overlap → events) -- **Dialog**: `dialog_system` (ticks story state), `dialog_projectile_system` (moves projectiles), `dialog_camera_system` (focuses camera on speaker), `dialog_bubble_render_system` (generates billboard/text draw calls) -- **Rendering**: `render_system` collects `DrawCall` from meshes/transforms; `spotlight_sync_system` syncs light positions to shader uniform -- **State machine**: `state_machine_system` (per-frame), `state_machine_physics_system` (fixed-step) tick state lifecycle -- **Trees**: `tree_occlusion_system` (culls trees behind camera), `tree_dissolve_update_system` (animates dissolve), `tree_instance_buffer_update_system` (writes GPU buffer) -- **Snow**: `snow_system` deforms snow layer at physics contacts; `particle_intent_system`/`particle_update_system` manage particle emitters -- **Rotate**: `rotate_system` rotates entities by delta +Flat list of update functions called in main loop. Systems receive specific storage parameters (e.g., `&mut Storage`, `&Storage`) instead of `&World`/`&mut World`. This makes data dependencies explicit for both borrow checker and reader. No cross-system coupling; all communication via world state and intents. +- **Camera**: `camera_input_system(cameras, follows, input_state)` → generates intents; `camera_intent_system(follow_player_intents, stop_following_intents, camera_transition_intents, ...)` consumes them; `camera_follow_system(follows, cameras, transforms)`, `camera_noclip_system(cameras, follows, transforms, input_state, delta)`, `camera_transition_system(camera_transitions, transforms, cameras, delta)`, `camera_ground_clamp_system(cameras, follows, transforms)` +- **Input**: `player_input_system(cameras, follows, player_tags, inputs, input_state)` reads SDL3 `InputState`, writes `InputComponent` +- **Physics**: `state_machine_physics_system(&mut World, FIXED_TIMESTEP)` (fixed-step), `PhysicsManager::physics_step()`, `physics_sync_system(entities, physics, transforms)` copies rapier bodies back to transforms, `trigger_system(trigger_events, triggers, transforms, player_tags)` (AABB overlap → events) +- **Dialog**: `dialog_system(entities, trigger_events, dialog_sources, bubble_tags, dialog_bubbles, transforms, names, player_tags, projectile_tags, dialog_projectiles, dialog_outcomes, delta)` ticks story state; `dialog_projectile_system(player_tags, transforms, projectile_tags, dialog_projectiles, spawn_particle_intents, dialog_outcomes, leaping_states, rolling_states, input_state)` moves projectiles; `dialog_camera_system(cameras, transforms, bubble_tags, player_pos, delta)` focuses camera on speaker; `dialog_bubble_render_system(transforms, dialog_bubbles, bubble_tags, camera_pos, view_proj)` generates billboard/text draw calls +- **Rendering**: `render_system(entities, transforms, meshes, dissolves)` → `Vec` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls; `spotlight_sync_system(spotlights, transforms)` syncs light positions to shader uniform +- **State machine**: `state_machine_system(&mut World, delta)` (per-frame), `state_machine_physics_system(&mut World, FIXED_TIMESTEP)` (fixed-step) tick state lifecycle +- **Trees**: `tree_occlusion_system(player_tags, transforms, cameras, tree_instances)` culls trees behind camera; `tree_dissolve_update_system(tree_instances, delta)` animates dissolve; `tree_instance_buffer_update_system(tree_instances)` writes GPU buffer +- **Snow**: `snow_system(cameras, transforms, player_tags, follows, snow_layer)` deforms snow layer at physics contacts; `particle_intent_system(particle_buffers, spawn_particle_intents)`/`particle_update_system(particle_buffers, delta)` manage particle emitters +- **Rotate**: `rotate_system(rotates, transforms, delta)` rotates entities by delta ### `src/bundles/` Factory functions to spawn pre-configured entity groups: @@ -90,26 +90,26 @@ Utility modules: ray casting for mouse pick, fullscreen blit/framebuffer downsam 1. **Initialization** (`main.rs` `init()`): SDL3 window → wgpu renderer (Vulkan) → World creation → load scene (Space from glTF) → spawn bundles (player, terrain, camera, lights) → initialize physics 2. **Main loop** (`main.rs` `main()` with 60 Hz fixed physics + variable-rate graphics): - - **Per-frame** (delta): Input events → `player_input_system` (fills `InputComponent`) + `camera_input_system` (generates intents) - - **Intent processing**: `camera_intent_system` consumes intents, updates `CameraComponent`/`CameraTransition` - - **Camera systems**: follow player, noclip, transition, clamp to ground + - **Per-frame** (delta): Input events → `player_input_system(cameras, follows, player_tags, inputs, input_state)` (fills `InputComponent`) + `camera_input_system(cameras, follows, input_state)` (generates intents) + - **Intent processing**: `camera_intent_system(follow_player_intents, stop_following_intents, camera_transition_intents, follows, transforms, cameras, player_tags, camera_transitions)` consumes intents, updates `CameraComponent`/`CameraTransition` + - **Camera systems**: `camera_follow_system(follows, cameras, transforms)` follows player; `camera_noclip_system(cameras, follows, transforms, input_state, delta)` noclip mode; `camera_transition_system(camera_transitions, transforms, cameras, delta)` animated transitions; `camera_ground_clamp_system(cameras, follows, transforms)` clamps to ground - **Fixed physics** (1/60s accumulator): - - `state_machine_physics_system`: tick state's `on_physics_update()` + - `state_machine_physics_system(&mut World, FIXED_TIMESTEP)`: tick state's `on_physics_update()` - `PhysicsManager::physics_step()`: rapier integration - - `physics_sync_system`: copy rigidbody poses to `Transform` - - `trigger_system`: detect collisions, emit events - - `dialog_system`, `dialog_projectile_system`: Ink story tick, projectile movement - - **Per-frame systems**: `state_machine_system` (non-physics update), rotate, particle, tree dissolve, snow deformation, spotlight sync - - **Render collection**: `render_system` → `Vec` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls + - `physics_sync_system(entities, physics, transforms)`: copy rigidbody poses to `Transform` + - `trigger_system(trigger_events, triggers, transforms, player_tags)`: detect collisions, emit events + - `dialog_system(entities, trigger_events, dialog_sources, bubble_tags, dialog_bubbles, transforms, names, player_tags, projectile_tags, dialog_projectiles, dialog_outcomes, delta)` ticks story state; `dialog_projectile_system(player_tags, transforms, projectile_tags, dialog_projectiles, spawn_particle_intents, dialog_outcomes, leaping_states, rolling_states, input_state)` moves projectiles + - **Per-frame systems**: `state_machine_system(&mut World, delta)` ticks state lifecycle; `rotate_system(rotates, transforms, delta)` rotates entities; `particle_intent_system(particle_buffers, spawn_particle_intents)`/`particle_update_system(particle_buffers, delta)` manage particles; `tree_occlusion_system(player_tags, transforms, cameras, tree_instances)` culls; `tree_dissolve_update_system(tree_instances, delta)`/`tree_instance_buffer_update_system(tree_instances)` updates dissolve; `snow_system(cameras, transforms, player_tags, follows, snow_layer)` deforms snow; `spotlight_sync_system(spotlights, transforms)` syncs lights + - **Render collection**: `render_system(entities, transforms, meshes, dissolves)` → `Vec` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls - **Submission**: `submit_frame()` renders draw calls, dialog bubbles/text, particles to framebuffer; blit to screen; optional ImGui overlay -3. **Frame cleanup**: `InputState::clear_just_pressed()` (flags reset for next frame) +3. **Frame cleanup**: `InputState::clear_just_pressed()` resets one-frame flags ## Key Types | Type | Module | Description | |------|--------|-------------| | `EntityHandle` | entity | u64 opaque entity ID | -| `Storage` | world | HashMap storage for per-entity component data | +| `Storage` | world | HashMap storage for per-entity component data; exposes `.get()`, `.get_mut()`, `.with_mut()`, `.all()` methods | | `World` | world | ECS container: entities, 20+ storages, intent queues, singleton state | | `Transform` | utility/transform | Position (Vec3), rotation (Quat), scale (Vec3); matrix conversions | | `StateMachine` | states/state | Per-entity state machine: current state TypeId, registered states, transitions | @@ -146,10 +146,10 @@ Utility modules: ray casting for mouse pick, fullscreen blit/framebuffer downsam ## Dependencies -- **Engine**: wgpu (GPU), rapier3d (physics), glam (math), nalgebra (nalgebra for physics conversions), SDL3 (windowing/input) +- **Engine**: wgpu (GPU), rapier3d (physics), glam (math), nalgebra (physics conversions), SDL3 (windowing/input) - **Content**: bladeink (Ink story scripting), image crate (EXR heightmaps), gltf (scene loading) - **Editor**: Dear ImGui via imgui crate + SDL3 integration -- **Internal**: All systems read/write `World`; systems are called in fixed sequence from main loop; no circular dependencies +- **Internal**: All systems take explicit storage parameters from `World`; systems are called in fixed sequence from main loop; no circular dependencies - **Thread-local singletons**: `Renderer` (render/global.rs), `PhysicsManager` (physics.rs), `GLOBAL_RENDERER`, `GLOBAL_PHYSICS` ## Initialization Order