fix: archi

docs/technical/architecture.md

@@ -1,43 +1,47 @@
-# Implemented Architecture
+# Current Architecture
 
 This document describes the code that exists today in the repository.
 
 ## Runtime Structure
 
-- `src/App.tsx` mounts the `Canvas`, the 3D `World`, the debug perf overlay, and the HTML crosshair overlay.
-- `src/world/World.tsx` composes the active 3D scene.
-- `src/world/Map.tsx` loads and centers the blocking map model.
-- `src/world/Lighting.tsx` owns the current ambient and directional light setup.
-- `src/world/Environment.tsx` owns the current background color.
-- `src/world/player/FPSController.tsx` provides the current player camera, pointer lock, and `ZQSD` movement.
-- `src/utils/debug/` contains debug-only tooling such as `lil-gui`, scene helpers, and the free debug camera.
-- `src/components/ui/Crosshair.tsx` is the only current HTML overlay component in use.
+- `src/App.tsx` mounts the `Canvas`, the 3D `World`, the debug perf overlay, and the HTML overlays.
+- `src/world/World.tsx` composes the active scene, including:
+  - environment and lighting
+  - debug helpers and debug camera mode
+  - either the map scene or the debug physics test scene
+  - the player rig when the active camera mode is `player`
+- `src/world/Map.tsx` loads the main map model and builds the collision octree.
+- `src/world/debug/TestScene.tsx` provides a debug-oriented interaction and physics scene.
+- `src/world/player/PlayerComponent.tsx` mounts the camera and controller.
+- `src/world/player/PlayerController.tsx` owns pointer lock movement, jump handling, and interaction input.
 
-## Camera Modes
+## Interaction Model
 
-The application currently has two camera modes:
+- `src/stateManager/InteractionManager.ts` is the current interaction state source.
+- `src/components/3d/InteractableObject.tsx` handles focus detection through distance and raycasting.
+- `src/components/3d/TriggerObject.tsx` implements trigger-style interactions.
+- `src/components/3d/GrabbableObject.tsx` implements hold-and-release interactions.
+- `src/hooks/useInteraction.ts` exposes the interaction snapshot to React UI.
+- `src/components/ui/InteractPrompt.tsx` shows the `E` prompt for trigger interactions.
 
-- `player`
-  - controlled by `FPSController`
-  - player height is `1.75m`
-  - movement uses `ZQSD`
-  - `E` is reserved for future interaction
-- `debug`
-  - controlled by `DebugCameraControls`
-  - enabled from the debug panel
+## Audio
 
-The active mode is stored in the debug subsystem and consumed through `src/hooks/debug/useCameraMode.ts`.
+- `src/stateManager/AudioManager.ts` currently provides pooled one-shot sound playback.
+- Trigger interactions may play audio directly through `AudioManager`.
 
 ## Debug System
 
-- `src/utils/debug/Debug.ts` is a singleton wrapper around `lil-gui`
-- `src/utils/debug/DebugPerf.tsx` lazy-loads `r3f-perf`
-- `src/utils/debug/scene/DebugHelpers.tsx` mounts grid and axes in debug mode
-- `src/utils/debug/scene/DebugCameraControls.tsx` mounts the free camera in debug mode
+- Debug mode is enabled with `?debug`.
+- `src/utils/debug/Debug.ts` owns the `lil-gui` instance and debug controls.
+- `src/hooks/debug/useCameraMode.ts` and `src/hooks/debug/useSceneMode.ts` subscribe to debug state.
+- `src/utils/debug/DebugPerf.tsx` lazily mounts `r3f-perf` in debug mode.
+- `src/utils/debug/scene/DebugHelpers.tsx` mounts debug helpers.
+- `src/utils/debug/scene/DebugCameraControls.tsx` mounts the free debug camera.
 
 ## Current Limitations
 
-- There is no gameplay state manager implemented yet.
-- There are no zone systems, missions, dialogue systems, or cinematic systems implemented yet.
-- Player movement currently uses a simple height clamp instead of real collision or ground detection.
-- The map is currently a blocking preview scene, not a full playable world.
+- The repository is still a prototype, not the full intended game runtime.
+- `src/world/debug/TestScene.tsx` is still part of the active scene composition.
+- There is no central gameplay orchestrator such as `GameManager` yet.
+- Missions, zones, cinematics, and dialogue systems are not implemented.
+- The player uses octree collision and simple movement rules, not a complete gameplay physics stack.

docs/technical/target-architecture.md

@@ -2,60 +2,69 @@
 
 This document describes the intended medium-term architecture for the project.
 
+## Relationship To The Current Code
+
+- `docs/technical/architecture.md` is the source of truth for what exists now.
+- This document is intentionally aspirational.
+- If this document conflicts with the current implementation, the current implementation wins.
+
 ## Goals
 
-- Keep `main` stable, `develop` as the integration branch, and `feat/*` for feature work.
-- Keep the runtime split between scene composition, gameplay systems, debug tooling, and HTML UI.
+- Keep `App.tsx` small and orchestration-oriented.
+- Separate production world code from debug-only runtime paths.
 - Keep one clear source of truth per concern.
+- Grow gameplay systems incrementally instead of prebuilding empty architecture.
 
 ## Intended Layers
 
 ### App Layer
 
-- `App.tsx` should stay small and orchestration-oriented.
-- It should mount the canvas scene and top-level HTML overlays.
+- `App.tsx` mounts the canvas scene and top-level HTML overlays.
+- It should stay thin and avoid gameplay logic.
 
 ### World Layer
 
-- `src/world/` should contain only production scene objects and scene composition.
+- `src/world/` should contain production scene composition and production scene objects.
 - Expected responsibilities:
   - world composition
-  - map/environment/lighting
+  - map, environment, lighting
   - player controller
-  - zones
-  - post-processing used in production
+  - production interaction anchors
+  - production post-processing, if needed
 
 ### Debug Layer
 
-- `src/utils/debug/` should contain only developer tooling.
+- Debug-only scenes and tooling should be isolated from the production world path.
 - Expected responsibilities:
   - `lil-gui`
   - performance overlay
   - scene helpers
   - free camera and calibration controls
+  - temporary test scenes used during development
 
 ### UI Layer
 
-- `src/components/ui/` should contain HTML overlays used by the player.
-- Expected examples:
+- `src/components/ui/` should contain player-facing HTML overlays.
+- Expected future examples:
   - crosshair
-  - loading screen
+  - loading flow
   - mission HUD
   - narrative overlays
 
 ### Gameplay Layer
 
-- Gameplay state should eventually live in dedicated managers and thin hooks once those systems exist.
-- Expected future concerns:
+- As the project grows, gameplay state can move toward a clearer orchestration layer.
+- Likely future concerns:
   - missions
   - zones
   - cinematics
+  - dialogue
   - audio
   - interactions
 
 ## Rules
 
-- `world/` should not contain debug-only tooling.
-- `debug/` should not own production gameplay systems.
-- Shared types should live close to their domain and move outward only when they gain multiple real consumers.
-- New files should only be created when they have an active runtime purpose.
+- Prefer direct, working code over speculative scaffolding.
+- Shared types should stay close to their domain until they have multiple real consumers.
+- Avoid creating new managers or service layers without an active runtime need.
+- Debug-only runtime paths should be clearly marked and easy to remove later.