La-Fabrik/docs/technical/architecture.md

Current Architecture

This document describes the code that exists today in the repository.

Runtime Structure

• src/main.tsx mounts React.
• src/App.tsx mounts the TanStack RouterProvider.
• src/router.tsx declares the top-level routes:
  • / mounts the playable 3D scene, debug perf overlay, and HTML overlays.
  • /editor mounts the map editor page.
• 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/hooks/world/useWorldSceneLoading.ts owns the production scene loading state shared by World, GameMap, and the player octree readiness.
• src/world/GameMap.tsx loads map nodes from public/map.json, resolves available models, renders them progressively, and shows fallback cubes for missing models.
• src/world/GameMapCollision.tsx builds the player collision octree from dedicated collision nodes only.
• src/world/GameStageContent.tsx is wrapped in Rapier Physics in the production game scene so stage gameplay objects can use physics without moving the map or player to Rapier. It now mounts reusable RepairGame instances for bike, pylone, and ferme mission states.
• src/world/debug/TestMap.tsx provides a debug-oriented interaction and physics map with the existing grab/trigger/model-preview objects plus separate Bike, Pylone, and Farm repair playground zones.
• src/world/player/Player.tsx mounts the camera and controller.
• src/world/player/PlayerController.tsx owns pointer lock movement, jump handling, repair-step movement locking, and interaction input.

Physics Boundaries

The project currently uses two collision layers with separate responsibilities:

• GameMapCollision builds an octree used by the player controller for map collision.
• The player octree must be built from a small collision-only subset of map nodes. It currently uses the terrain node only instead of traversing the full visible map, because building an octree from all rendered props can overload the browser renderer.
• GameStageContent is wrapped in Rapier Physics for gameplay objects such as repair triggers, cases, grabbables, and future mission-specific objects.
• TestMap owns its own Rapier Physics playground so repair gameplay can be tuned per mission state without depending on the production map layout.

Keep the player and map octree outside the Rapier provider until there is a deliberate migration plan. This avoids mixing player movement rules with object physics before the gameplay systems need it.

Interaction Model

• src/managers/InteractionManager.ts is the current interaction state source.
• src/components/three/interaction/InteractableObject.tsx handles focus detection through distance and raycasting.
• src/components/three/interaction/TriggerObject.tsx implements trigger-style interactions.
• src/components/three/interaction/GrabbableObject.tsx implements hold-and-release interactions.
• src/hooks/interaction/useInteraction.ts exposes the interaction snapshot to React UI.
• src/components/ui/InteractPrompt.tsx shows the E prompt for trigger interactions.

Audio

• src/managers/AudioManager.ts provides pooled one-shot playback, looped music playback, category volumes, and optional stereo pan for one-shot sounds.
• Supported audio categories are music, sfx, and dialogue.
• Trigger interactions may play SFX directly through AudioManager.

Settings Menu

• src/managers/stores/useSettingsStore.ts stores settings for music volume, SFX volume, dialogue volume, subtitle visibility, subtitle language, repair runtime, and menu visibility.
• src/components/ui/GameSettingsMenu.tsx renders the in-game options menu.
• src/components/ui/GameUI.tsx mounts the settings menu as an HTML overlay outside the canvas.
• Esc opens and closes the menu, and src/world/player/PlayerController.tsx ignores player input while the menu is open.
• Volume changes are forwarded to AudioManager by category.

Dialogues And Subtitles

• public/sounds/dialogue/dialogues.json is the runtime dialogue manifest.
• Dialogue audio files live under public/sounds/dialogue/.
• Subtitle files live under public/sounds/dialogue/subtitles/{fr|en}/.
• The current subtitle model is one SRT file per voice and language.
• src/types/dialogues/dialogues.ts contains the dialogue manifest types.
• src/utils/dialogues/dialogueManifestValidation.ts validates manifest shape at runtime.
• src/utils/dialogues/loadDialogueManifest.ts loads the manifest and SRT cues, with French fallback when the selected language is missing.
• src/utils/subtitles/parseSrt.ts parses SRT blocks and timecodes.
• src/utils/dialogues/playDialogue.ts plays dialogue audio and synchronizes the active subtitle against the audio element time.
• src/managers/stores/useSubtitleStore.ts stores the currently displayed subtitle cue.
• src/components/ui/Subtitles.tsx renders the subtitle overlay.
• src/world/GameDialogues.tsx currently triggers dialogue entries that define a timecode.
• Dialogue playback is queued so multiple dialogue requests do not overlap.

Cinematics

• public/cinematics.json is the runtime cinematic manifest.
• src/types/cinematics/cinematics.ts contains cinematic manifest types.
• src/utils/cinematics/cinematicManifestValidation.ts validates manifest shape at runtime.
• src/utils/cinematics/loadCinematicManifest.ts loads /cinematics.json.
• src/world/GameCinematics.tsx triggers cinematics that define a global timecode.
• Cinematics use GSAP timelines to animate the active camera position and look target.
• dialogueCues on a cinematic trigger dialogue IDs at times relative to the cinematic start.
• src/managers/stores/useGameStore.ts exposes isCinematicPlaying, used to lock player input during cinematics.

Debug System

• 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/components/debug/DebugPerf.tsx lazily mounts r3f-perf in debug mode.
• src/components/ui/debug/DebugOverlayLayout.tsx mounts the compact HTML debug overlay when enabled from lil-gui.
• src/components/ui/debug/GameStateDebugPanel.tsx exposes current game state, main/sub-state switching, previous/next step controls, and reset.
• src/components/ui/debug/HandTrackingDebugPanel.tsx shows hand tracking status, usage, loaded glove model, hand count, and fist state while hand tracking is active.
• src/components/ui/SceneLoadingOverlay.tsx displays the fullscreen loading state for 3D scenes, including the production game scene, debug physics scene, and editor scene.
• src/components/three/handTracking/HandTrackingGlove.tsx places the rigged gant_l and gant_r models on detected hands in the debug physics scene.
• src/components/debug/scene/DebugHelpers.tsx mounts debug helpers.
• src/components/debug/scene/DebugCameraControls.tsx mounts the free debug camera.
• lil-gui global debug controls include camera mode, scene mode, R3F Perf, and Debug Overlay; interaction-specific controls live in the Interaction folder.

3D Component Domains

• src/components/three/models/ contains reusable model helpers such as ExplodableModel.
• src/components/three/interaction/ contains reusable interaction wrappers such as InteractableObject, TriggerObject, and GrabbableObject.
• src/components/three/handTracking/ contains R3F hand tracking debug models such as the glove overlays.
• src/components/three/gameplay/ contains the reusable production RepairGame flow, repair case, repair steps, and repair prompt components.
• src/components/three/world/ contains reusable world/environment objects such as SkyModel.

Editor System

• src/pages/editor/page.tsx is the route-level editor page for /editor.
• src/components/editor/EditorControls.tsx renders the HTML editor control panel.
• src/components/editor/EditorDialogueManifestPanel.tsx edits public/sounds/dialogue/dialogues.json.
• src/components/editor/EditorCinematicManifestPanel.tsx edits public/cinematics.json.
• src/components/editor/EditorSrtPanel.tsx renders the dialogue SRT editor inside the editor control panel.
• src/components/editor/scene/EditorScene.tsx composes the editor canvas scene, camera controls, lights, shortcuts, and map rendering.
• src/components/editor/scene/EditorMap.tsx renders map nodes, fallback cubes, selection highlighting, and transform controls.
• src/controls/editor/FlyController.tsx provides player-style editor navigation.
• src/hooks/editor/useEditorSceneData.ts loads scene data and handles folder upload fallback.
• src/hooks/editor/useEditorHistory.ts owns editor undo and redo state.
• src/utils/editor/loadEditorScene.ts handles editor-only folder upload parsing.
• src/utils/map/loadMapSceneData.ts is shared by the game scene and editor to load public/map.json and resolve model URLs.
• src/types/editor/editor.ts contains the shared MapNode, SceneData, and TransformMode types.
• src/types/gameplay/repairMission.ts contains shared repair mission ids, mission steps, and guards used across store, config, debug UI, and gameplay components.

Map Data

• public/map.json is expected to be a MapNode[].
• Each map node name maps to public/models/{name}/model.glb when available, with public/models/{name}/model.gltf kept as fallback.
• The editor renders a fallback cube for missing models.
• The game scene renders fallback cubes for nodes whose model cannot be resolved.
• The game scene currently uses terrain as the collision source for the player octree. Additional collision nodes should be explicit lightweight collision assets, not arbitrary visible decoration models.

Current Limitations

• The repository is a prototype, not the full intended game runtime.
• src/world/debug/TestMap.tsx is part of the active scene composition.
• There is no central gameplay orchestrator such as GameManager.
• Mission state exists in Zustand and the repair flow is implemented as a prototype for the current repair missions.
• Cinematics and dialogues exist as prototype timecode-driven systems; dialogue branching and broader gameplay orchestration are still limited.
• The player uses octree collision and simple movement rules, not a complete gameplay physics stack.
• Editor save-to-server is implemented as a Vite dev-server plugin, not a production backend API.