La-Fabrik/docs/user/features.md

# Implemented Features

This document lists the user-visible and developer-facing features implemented in the current `develop` branch.

## Application And Routes

- React 19 application bootstrapped by Vite and TypeScript
- TanStack Router route tree
- `/` playable 3D experience
- `/editor` local content editor
- `/docs` in-app documentation browser
- Lazy-loaded docs pages rendered from repository Markdown files

## 3D World

- Fullscreen React Three Fiber canvas
- Production world composition in `src/world/World.tsx`
- Environment model/background through `Environment` and `SkyModel`
- Shared lighting setup
- Production map loaded from `public/map.json`
- Model resolution from `public/models/{name}/model.glb`, then `model.gltf`
- Fallback cubes when a map node has no available model
- Progressive scene loading overlay for game, debug physics scene, and editor
- Stabilized game scene loading gates for map, model, collision, octree, and gameplay stage readiness
- Game stage content mounted only after the map has loaded
- Player, music, dialogues, and gameplay-dependent systems mounted only after gameplay is ready

## Player

- Player camera mode
- Pointer-lock mouse look
- `ZQSD` movement
- Jump with `Space`
- Trigger interaction with `E`
- Grab interaction with primary mouse button
- Spawn reset based on scene mode
- Input lock while the settings menu is open
- Input lock while a cinematic is playing
- Octree collision against dedicated map collision nodes, currently scoped to the `terrain` node
- Repair movement-lock hook and indicator exist, but the hook currently returns `false`, so movement is not locked during repair on the current branch

## Physics And Collision

- Separate collision responsibility between player and gameplay objects
- Player collision uses a Three.js capsule plus octree
- Gameplay objects use Rapier rigid bodies and colliders
- Production `GameStageContent` is mounted inside a Rapier `Physics` provider
- Debug physics scene owns its own Rapier playground
- Map collision octree is built from explicit collision nodes instead of the full visible map

## Interaction System

- Shared `InteractionManager` singleton for focused object, nearby object, holding state, and hand-holding state
- React subscription through `useSyncExternalStore`
- Distance and camera-ray focus detection in `InteractableObject`
- Trigger interactions through `TriggerObject`
- Grab interactions through `GrabbableObject`
- Trigger prompt shown by `InteractPrompt`
- Optional trigger SFX and optional spawned model support
- Debug interaction sphere visibility through the `Interaction` lil-gui folder
- Hand-controlled grab support for grabbable objects
- Snap-to-target behavior after releasing grabbable objects

## Repair Gameplay

- Reusable `RepairGame` mounted for `ebike`, `pylon`, and `farm`
- Mission progression driven by Zustand and shared `MissionStep` types
- Production repair positions:
  - `ebike` at `[42.2399, 4.5484, 34.6468]`
  - `pylon` at `[64, 0, -66]`
  - `farm` at `[-24, 0, 42]`
- Debug physics repair playground zones for all three missions
- Data-driven mission config in `src/data/gameplay/repairMissions.ts`
- Mission flow: `locked -> waiting -> inspected -> fragmented -> scanning -> repairing -> reassembling -> done`
- `.webm` 3D prompts for mission object, interaction, and broken parts
- Repair object inspection
- Repair case spawn, pop animation, proximity float, wobble, open/close lid animation, exit animation, and open/close sounds
- Repair case placeholder traversal from GLTF nodes named `placeholder_*`
- Fallback placeholder positions when a case asset has no placeholder nodes
- Fragmentation through repair-case trigger or two-fists hand gesture
- Exploded model visualization through `ExplodableModel`
- Scan visual that steps through exploded parts
- Broken-part detection by configured `nodeName`, with diagnostics when configured parts are missing
- Persistent broken-part highlight and broken-part prompt after discovery
- Grabbable replacement part choices, including distractor parts
- Grabbable broken parts that must be deposited back into the case
- Snap-to-placeholder placement
- Correct-part, wrong-part, and stored-part visual feedback
- Blocked install feedback when validation is attempted too early
- Install target that validates only when the correct replacement is placed and all broken parts are stored
- Inverse reassembly animation
- Completion particles
- Completion target that closes/exits the repair case before calling `completeMission`

## Game Progression Store

- Zustand `useGameStore` for durable gameplay progression
- Main states: `intro`, `ebike`, `pylon`, `farm`, `outro`
- Per-mission repair step state
- Per-mission completion flags
- Generic mission helpers: `setMissionStep`, `completeMission`, `advanceGameState`, `rewindGameState`, `resetGame`
- `isCinematicPlaying` flag used by the player input lock
- Debug game-state panel that can jump between main states and sub-states

## Settings And UI Overlays

- `Esc` opens and closes the settings menu
- Music, SFX, and dialogue volume sliders
- Subtitle visibility toggle
- Subtitle language choice between French and English
- Repair-runtime choice between JavaScript and Python modes stored in settings
- Quit action that clears browser-accessible cookies and returns to `/`
- Crosshair overlay
- Interaction prompt
- Subtitle overlay
- Repair movement-lock indicator component, currently inactive because the lock hook returns `false`
- Debug overlay layout
- Scene loading overlay

## Audio

- Singleton `AudioManager`
- Looped music playback
- One-shot SFX/dialogue playback
- Per-path one-shot audio pools
- Category volumes for `music`, `sfx`, and `dialogue`
- Optional stereo panning for one-shot sounds
- Playback-rate option for one-shot sounds
- Browser autoplay fallback for music: retry after user `pointerdown` or `keydown`
- Game music mounted through `GameMusic`
- Current game music path: `/sounds/musique/test.mp3`
- Current base music volume: `0.33`
- Repair case open/close sounds
- Trigger-object SFX support

## Dialogue And Subtitles

- Runtime dialogue manifest in `public/sounds/dialogue/dialogues.json`
- Dialogue audio under `public/sounds/dialogue/`
- One SRT file per voice and language
- French and English subtitle folders
- Runtime SRT parsing
- Subtitle cue lookup by voice, selected language, and `subtitleCueIndex`
- French fallback when the selected language file is unavailable
- Dialogue playback through the `dialogue` audio category
- Runtime subtitle synchronization from audio `timeupdate`
- Speaker-aware subtitle overlay
- Dialogue queueing to avoid overlapping dialogue playback
- Global timecode dialogue triggering through `GameDialogues`

## Cinematics

- Runtime cinematic manifest in `public/cinematics.json`
- Cinematic manifest validation
- GSAP camera keyframe playback
- Camera position and look target interpolation
- Optional dialogue cues relative to cinematic start time
- Player input lock while a cinematic is active
- Current world integration only mounts `GameCinematics` during `mainState === "outro"`

## Hand Tracking

- Optional webcam hand tracking provider around the playable scene
- Source switch in debug GUI: local Python backend or browser-side MediaPipe
- Backend WebSocket endpoint at `ws://localhost:8000/ws`
- Backend health endpoint at `http://localhost:8000/health`
- Browser-side MediaPipe through `@mediapipe/tasks-vision`
- Lazy activation so camera/tracking is not always active
- Production activation during repair steps that need hand input
- Debug activation in physics mode while near, holding, or hand-holding interactions
- Hand snapshot context for R3F and UI consumers
- Fist detection
- Two-fists hold gesture for repair fragmentation
- Hand grab support for `GrabbableObject`
- Hand-tracking debug panel with status, source/server state, hand count, fist state, and glove model status
- SVG hand visualizer fallback
- `gant_l` and `gant_r` R3F glove overlays when tracking is active

## Debug Tooling

- `?debug` query param enables debug systems
- `lil-gui` root debug folder
- Camera mode switch between player and debug camera
- Scene mode switch between production game and physics test scene
- R3F perf toggle
- Debug overlay toggle
- Hand-tracking source switch
- Interaction sphere debug toggle
- Grabbable tuning controls for stiffness, throw boost, and hold distance
- Debug helpers: grid and axes
- Debug camera controls
- Debug game-state panel
- Debug hand-tracking panel
- Physics test scene with floor, grabbable object, trigger object, repair zones, and animated model preview
- Animated `electricienne_animated` model preview restored in the debug physics scene

## Map And Content Editor

- `/editor` route
- Automatic loading of `public/map.json`
- Folder upload fallback when map data is not available
- Shared `MapNode` format with runtime map loading
- Render available map models
- Fallback cubes for missing models
- Object selection by click
- Transform modes: translate, rotate, scale
- Transform keyboard shortcuts: `T`, `R`, `S`
- Selection lock
- Explicit selection clear
- Undo and redo
- Player-style editor navigation with `WASD`, `ZQSD`, arrows, `Space`, and `Shift`
- JSON inspector
- JSON export
- Dev-server save endpoint for `public/map.json`
- Dialogue manifest editor
- SRT subtitle editor
- Audio preview and cue timing helpers
- French SRT cue creation helper
- Dialogue asset validation endpoint
- Cinematic manifest editor
- Cinematic camera keyframe editor
- Cinematic dialogue cue editor
- Cinematic preview in the editor canvas
- Dev-server endpoints for dialogue, SRT, and cinematic saves

## In-App Documentation

- `/docs` documentation layout
- Markdown rendered through `react-markdown` and `remark-gfm`
- Technical docs for architecture, scene runtime, repair game, interaction, editor, audio, hand tracking, Zustand, Three debugging, animation, and target architecture
- User docs for implemented features, main feature, editor usage, and code-review preparation

## Not Implemented Or Incomplete

- Complete production mission manager/orchestrator
- Full mission HUD or minimap
- Full zone system
- Dialogue branching
- Production persistence for editor saves
- Production backend for repair-game runtime selection
- Production save/load of player progression
- Full migration of player movement to Rapier
- Advanced hand smoothing and calibrated glove finger animation
- Snap-to-grid, object creation, object deletion, material editing, or model editing in the map editor