Merge branch 'develop' into feat-editor

src/App.tsx

@@ -1,4 +1,5 @@
 import { Routes, Route } from "react-router-dom";
+import { Suspense } from "react";
 import { Canvas } from "@react-three/fiber";
 import { Crosshair } from "@/components/ui/Crosshair";
 import { InteractPrompt } from "@/components/ui/InteractPrompt";
@@ -14,8 +15,10 @@ function App(): React.JSX.Element {
         element={
           <>
             <Canvas camera={{ position: [85, 60, 85], fov: 42 }} shadows>
-              <World />
-              <DebugPerf />
+               <Suspense fallback={null}>
+                  <World />
+                  <DebugPerf />
+                </Suspense>
             </Canvas>
             <Crosshair />
             <InteractPrompt />
@@ -27,4 +30,4 @@ function App(): React.JSX.Element {
   );
 }
 
-export default App;
+export default App;

src/components/3d/GrabbableObject.tsx

@@ -0,0 +1,140 @@
+import { useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { RigidBody } from "@react-three/rapier";
+import type { RapierRigidBody } from "@react-three/rapier";
+import * as THREE from "three";
+import { InteractableObject } from "@/components/3d/InteractableObject";
+import {
+  GRAB_DEFAULT_COLLIDERS,
+  GRAB_DEFAULT_LABEL,
+  GRAB_HOLD_DISTANCE_DEFAULT,
+  GRAB_HOLD_DISTANCE_MAX,
+  GRAB_HOLD_DISTANCE_MIN,
+  GRAB_HOLD_DISTANCE_STEP,
+  GRAB_STIFFNESS_DEFAULT,
+  GRAB_STIFFNESS_MAX,
+  GRAB_STIFFNESS_MIN,
+  GRAB_STIFFNESS_STEP,
+  GRAB_THROW_BOOST_DEFAULT,
+  GRAB_THROW_BOOST_MAX,
+  GRAB_THROW_BOOST_MIN,
+  GRAB_THROW_BOOST_STEP,
+} from "@/data/grabConfig";
+import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
+import type { ColliderShape, Vector3Tuple } from "@/types/3d";
+
+interface GrabbableObjectProps {
+  position: Vector3Tuple;
+  children: React.ReactNode;
+  colliders?: ColliderShape;
+  label?: string;
+}
+
+// Shared params let one debug folder drive every instance.
+const params = {
+  stiffness: GRAB_STIFFNESS_DEFAULT,
+  throwBoost: GRAB_THROW_BOOST_DEFAULT,
+  holdDistance: GRAB_HOLD_DISTANCE_DEFAULT,
+};
+
+const ZERO_ANGULAR_VELOCITY = { x: 0, y: 0, z: 0 };
+
+const _holdTarget = new THREE.Vector3();
+const _currentPos = new THREE.Vector3();
+const _velocity = new THREE.Vector3();
+
+export function GrabbableObject({
+  position,
+  children,
+  colliders = GRAB_DEFAULT_COLLIDERS,
+  label = GRAB_DEFAULT_LABEL,
+}: GrabbableObjectProps): React.JSX.Element {
+  const camera = useThree((state) => state.camera);
+  const rbRef = useRef<RapierRigidBody>(null);
+  const isHolding = useRef(false);
+
+  useDebugFolder("GrabbableObject", (folder) => {
+    folder
+      .add(
+        params,
+        "stiffness",
+        GRAB_STIFFNESS_MIN,
+        GRAB_STIFFNESS_MAX,
+        GRAB_STIFFNESS_STEP,
+      )
+      .name("Hold stiffness");
+    folder
+      .add(
+        params,
+        "throwBoost",
+        GRAB_THROW_BOOST_MIN,
+        GRAB_THROW_BOOST_MAX,
+        GRAB_THROW_BOOST_STEP,
+      )
+      .name("Throw boost");
+    folder
+      .add(
+        params,
+        "holdDistance",
+        GRAB_HOLD_DISTANCE_MIN,
+        GRAB_HOLD_DISTANCE_MAX,
+        GRAB_HOLD_DISTANCE_STEP,
+      )
+      .name("Hold distance");
+  });
+
+  useFrame(() => {
+    if (!isHolding.current || !rbRef.current) return;
+
+    camera.getWorldDirection(_holdTarget);
+    _holdTarget.multiplyScalar(params.holdDistance).add(camera.position);
+
+    const t = rbRef.current.translation();
+    _currentPos.set(t.x, t.y, t.z);
+
+    _velocity
+      .subVectors(_holdTarget, _currentPos)
+      .multiplyScalar(params.stiffness);
+
+    rbRef.current.setLinvel(
+      { x: _velocity.x, y: _velocity.y, z: _velocity.z },
+      true,
+    );
+    rbRef.current.setAngvel(ZERO_ANGULAR_VELOCITY, true);
+  });
+
+  return (
+    <RigidBody
+      ref={rbRef}
+      type="dynamic"
+      colliders={colliders}
+      position={position}
+    >
+      <InteractableObject
+        kind="grab"
+        label={label}
+        position={position}
+        bodyRef={rbRef}
+        onPress={() => {
+          isHolding.current = true;
+        }}
+        onRelease={() => {
+          isHolding.current = false;
+          if (!rbRef.current || params.throwBoost === GRAB_THROW_BOOST_DEFAULT)
+            return;
+          const v = rbRef.current.linvel();
+          rbRef.current.setLinvel(
+            {
+              x: v.x * params.throwBoost,
+              y: v.y * params.throwBoost,
+              z: v.z * params.throwBoost,
+            },
+            true,
+          );
+        }}
+      >
+        {children}
+      </InteractableObject>
+    </RigidBody>
+  );
+}

src/components/3d/InteractableObject.tsx

@@ -1,73 +1,94 @@
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
-import { RigidBody } from "@react-three/rapier";
 import type { RapierRigidBody } from "@react-three/rapier";
 import * as THREE from "three";
+import type GUI from "lil-gui";
 import type { RefObject } from "react";
+import {
+  INTERACTION_DEBUG_SPHERE_COLOR,
+  INTERACTION_DEBUG_SPHERE_OPACITY,
+  INTERACTION_DEBUG_SPHERE_SEGMENTS,
+} from "@/data/debugConfig";
 import { Debug } from "@/utils/debug/Debug";
 import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
-import {
-  InteractionManager,
-  type InteractableHandle,
-  type InteractableKind,
-} from "@/stateManager/InteractionManager";
+import { InteractionManager } from "@/stateManager/InteractionManager";
 import { INTERACTION_RADIUS } from "@/data/interactionConfig";
+import type { Vector3Tuple } from "@/types/3d";
+import type { InteractableHandle, InteractableKind } from "@/types/interaction";
 
-interface InteractableObjectProps {
-  kind: InteractableKind;
+interface InteractableObjectBaseProps {
   label: string;
-  position: [number, number, number];
-  rigidBodyType?: "dynamic" | "fixed";
-  colliders?: "cuboid" | "ball" | "hull";
-  rbRef?: RefObject<RapierRigidBody | null>;
+  position: Vector3Tuple;
+  bodyRef?: RefObject<RapierRigidBody | null>;
   onPress: () => void;
-  onRelease?: () => void;
   children: React.ReactNode;
 }
 
+interface TriggerInteractableObjectProps extends InteractableObjectBaseProps {
+  kind: "trigger";
+}
+
+interface GrabInteractableObjectProps extends InteractableObjectBaseProps {
+  kind: "grab";
+  onRelease: () => void;
+}
+
+type InteractableObjectProps =
+  | TriggerInteractableObjectProps
+  | GrabInteractableObjectProps;
+
+type MutableInteractableHandle = {
+  kind: InteractableKind;
+  label: string;
+  onPress: () => void;
+  onRelease?: () => void;
+};
+
 const _cameraPos = new THREE.Vector3();
 const _cameraDir = new THREE.Vector3();
 const _objectPos = new THREE.Vector3();
 const _raycaster = new THREE.Raycaster();
 
-export function InteractableObject({
-  kind,
-  label,
-  position,
-  rigidBodyType = "dynamic",
-  colliders = "cuboid",
-  rbRef,
-  onPress,
-  onRelease = () => {},
-  children,
-}: InteractableObjectProps): React.JSX.Element {
+export function InteractableObject(
+  props: InteractableObjectProps,
+): React.JSX.Element {
+  const { kind, label, position, bodyRef, onPress, children } = props;
+  const onRelease = props.kind === "grab" ? props.onRelease : undefined;
   const camera = useThree((state) => state.camera);
-  const internalRef = useRef<RapierRigidBody>(null);
-  const bodyRef = rbRef ?? internalRef;
   const groupRef = useRef<THREE.Group>(null);
   const debugSphereRef = useRef<THREE.Mesh>(null);
 
-  const handle = useRef<InteractableHandle>({
-    kind,
-    label,
-    onPress,
-    onRelease,
-  });
+  const handle = useRef<InteractableHandle>(
+    props.kind === "grab"
+      ? { kind: props.kind, label, onPress, onRelease: props.onRelease }
+      : { kind: props.kind, label, onPress },
+  );
 
   useEffect(() => {
-    handle.current.onPress = onPress;
-    handle.current.onRelease = onRelease;
-  });
+    const current = handle.current as MutableInteractableHandle;
+    current.kind = kind;
+    current.label = label;
+    current.onPress = onPress;
 
-  useDebugFolder("Interaction", (folder) => {
+    if (kind === "grab" && onRelease) {
+      current.onRelease = onRelease;
+      return;
+    }
+
+    delete current.onRelease;
+    return undefined;
+  }, [kind, label, onPress, onRelease]);
+
+  const setupInteractionDebugFolder = useCallback((folder: GUI) => {
     folder
       .add({ radius: INTERACTION_RADIUS }, "radius")
       .name("Interaction radius")
       .disable();
-  });
+  }, []);
+
+  useDebugFolder("Interaction", setupInteractionDebugFolder);
 
   useFrame(() => {
-    const body = bodyRef.current;
     const group = groupRef.current;
     const debug = Debug.getInstance();
     const manager = InteractionManager.getInstance();
@@ -77,8 +98,8 @@ export function InteractableObject({
         debug.active && debug.getShowInteractionSpheres();
     }
 
-    if (body) {
-      const t = body.translation();
+    if (bodyRef?.current) {
+      const t = bodyRef.current.translation();
       _objectPos.set(t.x, t.y, t.z);
     } else {
       _objectPos.set(...position);
@@ -99,7 +120,6 @@ export function InteractableObject({
     _raycaster.far = INTERACTION_RADIUS;
 
     const hits = group ? _raycaster.intersectObject(group, true) : [];
-
     const validHit = hits.find((h) => h.object !== debugSphereRef.current);
 
     if (validHit) {
@@ -110,24 +130,23 @@ export function InteractableObject({
   });
 
   return (
-    <RigidBody
-      ref={bodyRef}
-      type={rigidBodyType}
-      colliders={colliders}
-      position={position}
-    >
-      <group ref={groupRef}>
-        {children}
-        <mesh ref={debugSphereRef} visible={false}>
-          <sphereGeometry args={[INTERACTION_RADIUS, 16, 16]} />
-          <meshBasicMaterial
-            color="#facc15"
-            wireframe
-            transparent
-            opacity={0.25}
-          />
-        </mesh>
-      </group>
-    </RigidBody>
+    <group ref={groupRef}>
+      {children}
+      <mesh ref={debugSphereRef} visible={false}>
+        <sphereGeometry
+          args={[
+            INTERACTION_RADIUS,
+            INTERACTION_DEBUG_SPHERE_SEGMENTS,
+            INTERACTION_DEBUG_SPHERE_SEGMENTS,
+          ]}
+        />
+        <meshBasicMaterial
+          color={INTERACTION_DEBUG_SPHERE_COLOR}
+          wireframe
+          transparent
+          opacity={INTERACTION_DEBUG_SPHERE_OPACITY}
+        />
+      </mesh>
+    </group>
   );
 }

src/components/3d/TriggerObject.tsx

@@ -0,0 +1,94 @@
+import { useState } from "react";
+import { useGLTF } from "@react-three/drei";
+import { RigidBody } from "@react-three/rapier";
+import { InteractableObject } from "@/components/3d/InteractableObject";
+import {
+  TRIGGER_DEFAULT_COLLIDERS,
+  TRIGGER_DEFAULT_LABEL,
+  TRIGGER_DEFAULT_SOUND_VOLUME,
+  TRIGGER_DEFAULT_SPAWN_OFFSET,
+} from "@/data/triggerConfig";
+import { AudioManager } from "@/stateManager/AudioManager";
+import type { ColliderShape, Vector3Tuple } from "@/types/3d";
+
+interface SpawnedModel {
+  id: number;
+  position: Vector3Tuple;
+}
+
+interface TriggerObjectProps {
+  position: Vector3Tuple;
+  children: React.ReactNode;
+  colliders?: ColliderShape;
+  label?: string;
+  soundPath?: string;
+  soundVolume?: number;
+  spawnModel?: string;
+  spawnOffset?: Vector3Tuple;
+}
+
+let _spawnCounter = 0;
+
+function SpawnedModelInstance({
+  path,
+  position,
+}: {
+  path: string;
+  position: Vector3Tuple;
+}): React.JSX.Element {
+  const { scene } = useGLTF(path);
+  return <primitive object={scene.clone()} position={position} />;
+}
+
+export function TriggerObject({
+  position,
+  children,
+  colliders = TRIGGER_DEFAULT_COLLIDERS,
+  label = TRIGGER_DEFAULT_LABEL,
+  soundPath,
+  soundVolume = TRIGGER_DEFAULT_SOUND_VOLUME,
+  spawnModel,
+  spawnOffset = TRIGGER_DEFAULT_SPAWN_OFFSET,
+}: TriggerObjectProps): React.JSX.Element {
+  const [spawned, setSpawned] = useState<SpawnedModel[]>([]);
+
+  return (
+    <>
+      <RigidBody type="fixed" colliders={colliders} position={position}>
+        <InteractableObject
+          kind="trigger"
+          label={label}
+          position={position}
+          onPress={() => {
+            if (soundPath) {
+              AudioManager.getInstance().playSound(soundPath, soundVolume);
+            }
+
+            if (spawnModel) {
+              const spawnPos: Vector3Tuple = [
+                position[0] + spawnOffset[0],
+                position[1] + spawnOffset[1],
+                position[2] + spawnOffset[2],
+              ];
+              setSpawned((prev) => [
+                ...prev,
+                { id: ++_spawnCounter, position: spawnPos },
+              ]);
+            }
+          }}
+        >
+          {children}
+        </InteractableObject>
+      </RigidBody>
+
+      {spawnModel &&
+        spawned.map((s) => (
+          <SpawnedModelInstance
+            key={s.id}
+            path={spawnModel}
+            position={s.position}
+          />
+        ))}
+    </>
+  );
+}

src/components/ui/InteractPrompt.tsx

@@ -1,3 +1,4 @@
+import { INTERACT_KEY } from "@/data/keybindings";
 import { useCameraMode } from "@/hooks/debug/useCameraMode";
 import { useInteraction } from "@/hooks/useInteraction";
 
@@ -10,7 +11,7 @@ export function InteractPrompt(): React.JSX.Element | null {
 
   return (
     <div className="interact-prompt" aria-live="polite">
-      <kbd className="interact-prompt__key">E</kbd>
+      <kbd className="interact-prompt__key">{INTERACT_KEY.toUpperCase()}</kbd>
       <span className="interact-prompt__label">{focused.label}</span>
     </div>
   );

src/data/debugConfig.ts

@@ -0,0 +1,16 @@
+export const INTERACTION_DEBUG_SPHERE_SEGMENTS = 16;
+export const INTERACTION_DEBUG_SPHERE_COLOR = "#facc15";
+export const INTERACTION_DEBUG_SPHERE_OPACITY = 0.25;
+
+export const MAP_DEBUG_BOX_HELPER_COLOR = 0x00ff88;
+
+export const DEBUG_CAMERA_DAMPING_FACTOR = 0.05;
+export const DEBUG_CAMERA_MIN_DISTANCE = 100;
+export const DEBUG_CAMERA_MAX_DISTANCE = 1000;
+
+export const DEBUG_GRID_SIZE = 180;
+export const DEBUG_GRID_DIVISIONS = 36;
+export const DEBUG_GRID_PRIMARY_COLOR = "#1d4ed8";
+export const DEBUG_GRID_SECONDARY_COLOR = "#1e293b";
+export const DEBUG_GRID_Y = 0.01;
+export const DEBUG_AXES_SIZE = 10;

src/data/environmentConfig.ts

@@ -0,0 +1,2 @@
+export const GAME_SCENE_SKYBOX_PATH = "/skybox/sky.exr";
+export const PHYSICS_SCENE_BACKGROUND_COLOR = "#0b1018";

src/data/grabConfig.ts

@@ -0,0 +1,18 @@
+export const GRAB_DEFAULT_COLLIDERS = "cuboid";
+export const GRAB_DEFAULT_LABEL = "Prendre";
+
+export const GRAB_STIFFNESS_DEFAULT = 15;
+export const GRAB_THROW_BOOST_DEFAULT = 1.0;
+export const GRAB_HOLD_DISTANCE_DEFAULT = 2;
+
+export const GRAB_STIFFNESS_MIN = 1;
+export const GRAB_STIFFNESS_MAX = 50;
+export const GRAB_STIFFNESS_STEP = 1;
+
+export const GRAB_THROW_BOOST_MIN = 0.5;
+export const GRAB_THROW_BOOST_MAX = 3.0;
+export const GRAB_THROW_BOOST_STEP = 0.1;
+
+export const GRAB_HOLD_DISTANCE_MIN = 0.5;
+export const GRAB_HOLD_DISTANCE_MAX = 5.0;
+export const GRAB_HOLD_DISTANCE_STEP = 0.1;

src/data/keybindings.ts

@@ -0,0 +1,7 @@
+export const MOVE_FORWARD_KEY = "z";
+export const MOVE_BACKWARD_KEY = "s";
+export const MOVE_LEFT_KEY = "q";
+export const MOVE_RIGHT_KEY = "d";
+export const JUMP_KEY = " ";
+export const INTERACT_KEY = "e";
+export const PRIMARY_INTERACT_MOUSE_BUTTON = 0;

src/data/lightingConfig.ts

@@ -0,0 +1,30 @@
+export const AMBIENT_LIGHT_COLOR = "#dbeafe";
+export const SUN_LIGHT_COLOR = "#fff7ed";
+
+export const LIGHTING_DEFAULTS = {
+  ambientIntensity: 1.8,
+  sunIntensity: 2.8,
+  sunX: 60,
+  sunY: 80,
+  sunZ: 30,
+};
+
+export const AMBIENT_INTENSITY_MIN = 0;
+export const AMBIENT_INTENSITY_MAX = 5;
+export const AMBIENT_INTENSITY_STEP = 0.1;
+
+export const SUN_INTENSITY_MIN = 0;
+export const SUN_INTENSITY_MAX = 8;
+export const SUN_INTENSITY_STEP = 0.1;
+
+export const SUN_X_MIN = -100;
+export const SUN_X_MAX = 100;
+export const SUN_X_STEP = 1;
+
+export const SUN_Y_MIN = 0;
+export const SUN_Y_MAX = 150;
+export const SUN_Y_STEP = 1;
+
+export const SUN_Z_MIN = -100;
+export const SUN_Z_MAX = 100;
+export const SUN_Z_STEP = 1;

src/data/playerConfig.ts

@@ -0,0 +1,15 @@
+import type { Vector3Tuple } from "@/types/3d";
+
+export const PLAYER_EYE_HEIGHT = 1.75;
+export const PLAYER_CAPSULE_RADIUS = 0.35;
+
+export const PLAYER_WALK_SPEED = 11;
+export const PLAYER_AIR_CONTROL_FACTOR = 0.35;
+export const PLAYER_JUMP_SPEED = 9;
+export const PLAYER_GRAVITY = 30;
+export const PLAYER_MAX_DELTA = 0.05;
+export const PLAYER_ACCELERATION_MULTIPLIER = 9;
+export const PLAYER_XZ_DAMPING_FACTOR = 8;
+
+export const PLAYER_SPAWN_POSITION_GAME: Vector3Tuple = [0, 100, 0];
+export const PLAYER_SPAWN_POSITION_PHYSICS: Vector3Tuple = [0, 3, 0];

src/data/testSceneConfig.ts

@@ -0,0 +1,21 @@
+import type { Vector3Tuple } from "@/types/3d";
+
+export const TEST_SCENE_FLOOR_POSITION: Vector3Tuple = [0, -0.5, 0];
+export const TEST_SCENE_FLOOR_SIZE: Vector3Tuple = [200, 1, 200];
+export const TEST_SCENE_FLOOR_COLLIDER_HALF_EXTENTS: Vector3Tuple = [
+  100, 0.5, 100,
+];
+
+export const TEST_SCENE_GRABBABLE_POSITION: Vector3Tuple = [0, 1, -3];
+export const TEST_SCENE_GRABBABLE_BOX_SIZE: Vector3Tuple = [0.5, 0.5, 0.5];
+export const TEST_SCENE_GRABBABLE_COLOR = "#e07b39";
+export const TEST_SCENE_GRABBABLE_ROUGHNESS = 0.6;
+export const TEST_SCENE_GRABBABLE_METALNESS = 0.1;
+
+export const TEST_SCENE_TRIGGER_POSITION: Vector3Tuple = [3, 2, -3];
+export const TEST_SCENE_TRIGGER_SOUND_PATH = "/sounds/fa.mp3";
+export const TEST_SCENE_TRIGGER_RADIUS = 0.4;
+export const TEST_SCENE_TRIGGER_SEGMENTS = 32;
+export const TEST_SCENE_TRIGGER_COLOR = "#3b82f6";
+export const TEST_SCENE_TRIGGER_ROUGHNESS = 0.3;
+export const TEST_SCENE_TRIGGER_METALNESS = 0.5;

src/data/triggerConfig.ts

@@ -0,0 +1,6 @@
+import type { Vector3Tuple } from "@/types/3d";
+
+export const TRIGGER_DEFAULT_COLLIDERS = "ball";
+export const TRIGGER_DEFAULT_LABEL = "Interagir";
+export const TRIGGER_DEFAULT_SOUND_VOLUME = 1;
+export const TRIGGER_DEFAULT_SPAWN_OFFSET: Vector3Tuple = [0, 0, 0];

src/hooks/debug/useCameraMode.ts

@@ -1,13 +1,6 @@
-import { useSyncExternalStore } from "react";
 import type { CameraMode } from "@/types/debug";
-import { Debug } from "@/utils/debug/Debug";
+import { useDebugStore } from "@/hooks/debug/useDebugStore";
 
 export function useCameraMode(): CameraMode {
-  const debug = Debug.getInstance();
-
-  return useSyncExternalStore(
-    (listener) => debug.subscribe(listener),
-    () => debug.getCameraMode(),
-    () => debug.getCameraMode(),
-  );
+  return useDebugStore((debug) => debug.getCameraMode());
 }

src/hooks/debug/useDebugFolder.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import type GUI from "lil-gui";
 import { Debug } from "@/utils/debug/Debug";
 
@@ -6,12 +6,23 @@ export function useDebugFolder(
   name: string,
   setup: (folder: GUI) => void,
 ): void {
+  const setupRef = useRef(setup);
+
+  useEffect(() => {
+    setupRef.current = setup;
+  }, [setup]);
+
   useEffect(() => {
     const debug = Debug.getInstance();
     if (!debug.active) return;
+
     const folder = debug.createFolder(name);
-    if (!folder) return;
-    setup(folder);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+    if (folder) {
+      setupRef.current(folder);
+    }
+
+    return () => {
+      debug.destroyFolder(name);
+    };
+  }, [name]);
 }

src/hooks/debug/useDebugStore.ts

@@ -0,0 +1,12 @@
+import { useSyncExternalStore } from "react";
+import { Debug } from "@/utils/debug/Debug";
+
+export function useDebugStore<T>(selector: (debug: Debug) => T): T {
+  const debug = Debug.getInstance();
+
+  return useSyncExternalStore(
+    (listener) => debug.subscribe(listener),
+    () => selector(debug),
+    () => selector(debug),
+  );
+}

src/hooks/debug/useSceneMode.ts

@@ -1,13 +1,6 @@
-import { useSyncExternalStore } from "react";
 import type { SceneMode } from "@/types/debug";
-import { Debug } from "@/utils/debug/Debug";
+import { useDebugStore } from "@/hooks/debug/useDebugStore";
 
 export function useSceneMode(): SceneMode {
-  const debug = Debug.getInstance();
-
-  return useSyncExternalStore(
-    (listener) => debug.subscribe(listener),
-    () => debug.getSceneMode(),
-    () => debug.getSceneMode(),
-  );
+  return useDebugStore((debug) => debug.getSceneMode());
 }

src/hooks/useInteraction.ts

@@ -1,18 +1,12 @@
-import { useEffect, useState } from "react";
-import {
-  InteractionManager,
-  type InteractionSnapshot,
-} from "@/stateManager/InteractionManager";
+import { useSyncExternalStore } from "react";
+import { InteractionManager } from "@/stateManager/InteractionManager";
+import type { InteractionSnapshot } from "@/types/interaction";
+
+const manager = InteractionManager.getInstance();
 
 export function useInteraction(): InteractionSnapshot {
-  const manager = InteractionManager.getInstance();
-  const [state, setState] = useState<InteractionSnapshot>(manager.getState());
-
-  useEffect(() => {
-    return manager.subscribe(() => {
-      setState({ ...manager.getState() });
-    });
-  }, [manager]);
-
-  return state;
+  return useSyncExternalStore(
+    manager.subscribe.bind(manager),
+    manager.getState.bind(manager),
+  );
 }

src/hooks/useOctreeGraphNode.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react";
+import type { RefObject } from "react";
+import type { Object3D } from "three";
+import { Octree } from "three/addons/math/Octree.js";
+import type { OctreeReadyHandler } from "@/types/3d";
+
+export function useOctreeGraphNode(
+  graphNodeRef: RefObject<Object3D | null>,
+  onOctreeReady: OctreeReadyHandler,
+): void {
+  const octreeBuilt = useRef(false);
+
+  useEffect(() => {
+    const graphNode = graphNodeRef.current;
+    if (octreeBuilt.current || !graphNode) return;
+    octreeBuilt.current = true;
+
+    graphNode.updateMatrixWorld(true);
+
+    const octree = new Octree();
+    octree.fromGraphNode(graphNode);
+    onOctreeReady(octree);
+  }, [graphNodeRef, onOctreeReady]);
+}

src/stateManager/AudioManager.ts

@@ -1,5 +1,14 @@
+import { logger } from "@/utils/logger";
+
 export class AudioManager {
   private static _instance: AudioManager | null = null;
+  private readonly _audioPools = new Map<string, HTMLAudioElement[]>();
+
+  private static readonly MAX_POOL_SIZE_PER_SOUND = 6;
+  private static readonly IGNORED_PLAYBACK_ERRORS = new Set([
+    "AbortError",
+    "NotAllowedError",
+  ]);
 
   static getInstance(): AudioManager {
     if (!AudioManager._instance) {
@@ -12,12 +21,65 @@ export class AudioManager {
   private constructor() {}
 
   playSound(path: string, volume = 1): void {
-    const audio = new Audio(path);
+    const audio = this._acquireAudio(path);
     audio.volume = Math.max(0, Math.min(1, volume));
-    void audio.play();
+    audio.currentTime = 0;
+
+    void audio.play().catch((error: unknown) => {
+      if (
+        error instanceof DOMException &&
+        AudioManager.IGNORED_PLAYBACK_ERRORS.has(error.name)
+      ) {
+        return;
+      }
+
+      logger.error("AudioManager", "Failed to play sound", {
+        path,
+        error: AudioManager._toLogValue(error),
+      });
+    });
   }
 
   destroy(): void {
+    this._audioPools.forEach((pool) => {
+      pool.forEach((audio) => {
+        audio.pause();
+        audio.src = "";
+      });
+    });
+    this._audioPools.clear();
     AudioManager._instance = null;
   }
+
+  private _acquireAudio(path: string): HTMLAudioElement {
+    const existingPool = this._audioPools.get(path);
+
+    if (existingPool) {
+      const availableAudio = existingPool.find(
+        (audio) => audio.paused || audio.ended,
+      );
+      if (availableAudio) return availableAudio;
+
+      if (existingPool.length < AudioManager.MAX_POOL_SIZE_PER_SOUND) {
+        const pooledAudio = new Audio(path);
+        existingPool.push(pooledAudio);
+        return pooledAudio;
+      }
+
+      const recycledAudio = existingPool[0];
+      if (recycledAudio) return recycledAudio;
+    }
+
+    const initialAudio = new Audio(path);
+    this._audioPools.set(path, [initialAudio]);
+    return initialAudio;
+  }
+
+  private static _toLogValue(error: unknown): Error | DOMException | string {
+    if (error instanceof Error || error instanceof DOMException) {
+      return error;
+    }
+
+    return String(error);
+  }
 }

src/stateManager/InteractionManager.ts

@@ -1,23 +1,19 @@
-export type InteractableKind = "grab" | "trigger";
-
-export interface InteractableHandle {
-  kind: InteractableKind;
-  label: string;
-  onPress: () => void;
-  onRelease: () => void;
-}
-
-export interface InteractionSnapshot {
-  focused: InteractableHandle | null;
-  holding: boolean;
-}
+import type {
+  GrabInteractableHandle,
+  InteractableHandle,
+  InteractionSnapshot,
+} from "@/types/interaction";
 
 export class InteractionManager {
   private static _instance: InteractionManager | null = null;
 
   private _focused: InteractableHandle | null = null;
   private _holding = false;
-  private _holdingHandle: InteractableHandle | null = null;
+  private _holdingHandle: GrabInteractableHandle | null = null;
+  private _snapshot: InteractionSnapshot = {
+    focused: null,
+    holding: false,
+  };
   private readonly _listeners = new Set<() => void>();
 
   static getInstance(): InteractionManager {
@@ -31,20 +27,13 @@ export class InteractionManager {
   private constructor() {}
 
   getState(): InteractionSnapshot {
-    return {
-      focused: this._focused,
-      holding: this._holding,
-    };
+    return this._snapshot;
   }
 
   setFocused(handle: InteractableHandle | null): void {
     if (this._focused === handle) return;
-    // Never interrupt an active grab via focus change
-    if (this._holding) {
-      this._focused = handle;
-      this._emit();
-      return;
-    }
+    if (this._holding) return;
+
     this._focused = handle;
     this._emit();
   }
@@ -52,14 +41,20 @@ export class InteractionManager {
   pressInteract(): void {
     if (!this._focused) return;
 
-    this._holding = this._focused.kind === "grab";
-    if (this._holding) this._holdingHandle = this._focused;
+    if (this._focused.kind === "grab") {
+      this._holding = true;
+      this._holdingHandle = this._focused;
+    } else {
+      this._holding = false;
+      this._holdingHandle = null;
+    }
+
     this._focused.onPress();
     this._emit();
   }
 
   releaseInteract(): void {
-    const handle = this._holdingHandle ?? this._focused;
+    const handle = this._holding ? this._holdingHandle : null;
     if (!handle) return;
 
     handle.onRelease();
@@ -77,11 +72,22 @@ export class InteractionManager {
   }
 
   destroy(): void {
+    this._focused = null;
+    this._holding = false;
+    this._holdingHandle = null;
+    this._snapshot = {
+      focused: null,
+      holding: false,
+    };
     this._listeners.clear();
     InteractionManager._instance = null;
   }
 
   private _emit(): void {
+    this._snapshot = {
+      focused: this._focused,
+      holding: this._holding,
+    };
     this._listeners.forEach((cb) => cb());
   }
 }

src/types/3d.ts

@@ -0,0 +1,7 @@
+import type { Octree } from "three/addons/math/Octree.js";
+
+export type Vector3Tuple = [number, number, number];
+
+export type ColliderShape = "cuboid" | "ball" | "hull";
+
+export type OctreeReadyHandler = (octree: Octree) => void;

src/types/interaction.ts

@@ -0,0 +1,23 @@
+export type InteractableKind = "grab" | "trigger";
+
+export interface TriggerInteractableHandle {
+  kind: "trigger";
+  label: string;
+  onPress: () => void;
+}
+
+export interface GrabInteractableHandle {
+  kind: "grab";
+  label: string;
+  onPress: () => void;
+  onRelease: () => void;
+}
+
+export type InteractableHandle =
+  | TriggerInteractableHandle
+  | GrabInteractableHandle;
+
+export interface InteractionSnapshot {
+  focused: InteractableHandle | null;
+  holding: boolean;
+}

src/types/logger.ts

@@ -0,0 +1,26 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type LogValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Error
+  | DOMException
+  | { [key: string]: LogValue }
+  | LogValue[];
+
+export type LogContext = Readonly<Record<string, LogValue>>;
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  scope: string;
+  message: string;
+  context?: LogContext;
+}
+
+export interface LoggerConfig {
+  minLevel: LogLevel;
+}

src/utils/EventEmitter.ts

@@ -1,8 +1,5 @@
 type Listener<TPayload> = (payload: TPayload) => void;
 
-// TypeScript cannot narrow mapped-type indexed access by a generic key TKey
-// (microsoft/TypeScript#30581). The helper below encapsulates the one necessary
-// cast so the rest of the class stays cast-free.
 type ListenerMap<TEvents extends Record<string, unknown>> = {
   [TKey in keyof TEvents]?: Set<Listener<TEvents[TKey]>>;
 };

src/utils/debug/Debug.ts

@@ -1,5 +1,6 @@
 import GUI from "lil-gui";
 import type { CameraMode, SceneMode } from "@/types/debug";
+import { isDebugEnabled } from "@/utils/debug/isDebugEnabled";
 
 export class Debug {
   private static instance: Debug | null = null;
@@ -7,7 +8,7 @@ export class Debug {
   public readonly active: boolean;
   private readonly gui: GUI | null;
   private readonly folders = new Map<string, GUI>();
-  private readonly registeredFolders = new Set<string>();
+  private readonly folderRefCounts = new Map<string, number>();
   private readonly listeners = new Set<() => void>();
   private readonly controls: {
     cameraMode: CameraMode;
@@ -28,7 +29,7 @@ export class Debug {
   }
 
   private constructor() {
-    this.active = new URLSearchParams(window.location.search).has("debug");
+    this.active = isDebugEnabled();
     this.gui = this.active ? new GUI({ title: "La-Fabrik Debug" }) : null;
 
     if (this.gui) {
@@ -63,27 +64,41 @@ export class Debug {
   }
 
   /**
-   * Creates a named GUI folder. Returns the folder on first call, null on
-   * subsequent calls with the same name — callers should skip `.add()` when
-   * null is returned to avoid duplicating controls under StrictMode double-mount.
+   * Acquires a named GUI folder. Returns the folder on first acquisition and null
+   * on subsequent acquisitions so callers only register controls once.
    */
   createFolder(name: string): GUI | null {
     if (!this.gui) return null;
 
-    if (this.registeredFolders.has(name)) return null;
-
-    this.registeredFolders.add(name);
-
     const existing = this.folders.get(name);
 
-    if (existing) return existing;
+    if (existing) {
+      this.folderRefCounts.set(name, (this.folderRefCounts.get(name) ?? 0) + 1);
+      return null;
+    }
 
     const folder = this.gui.addFolder(name);
     this.folders.set(name, folder);
+    this.folderRefCounts.set(name, 1);
 
     return folder;
   }
 
+  destroyFolder(name: string): void {
+    const folder = this.folders.get(name);
+    const refCount = this.folderRefCounts.get(name);
+    if (!folder || refCount === undefined) return;
+
+    if (refCount > 1) {
+      this.folderRefCounts.set(name, refCount - 1);
+      return;
+    }
+
+    folder.destroy();
+    this.folders.delete(name);
+    this.folderRefCounts.delete(name);
+  }
+
   subscribe(listener: () => void): () => void {
     this.listeners.add(listener);
 

src/utils/debug/isDebugEnabled.ts

@@ -0,0 +1,7 @@
+export function isDebugEnabled(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  return new URLSearchParams(window.location.search).has("debug");
+}

src/utils/debug/scene/DebugCameraControls.tsx

@@ -1,13 +1,28 @@
 import { OrbitControls } from "@react-three/drei";
+import {
+  DEBUG_CAMERA_DAMPING_FACTOR,
+  DEBUG_CAMERA_MAX_DISTANCE,
+  DEBUG_CAMERA_MIN_DISTANCE,
+} from "@/data/debugConfig";
+import {
+  PLAYER_EYE_HEIGHT,
+  PLAYER_SPAWN_POSITION_GAME,
+} from "@/data/playerConfig";
+
+const DEBUG_CAMERA_TARGET = [
+  PLAYER_SPAWN_POSITION_GAME[0],
+  PLAYER_EYE_HEIGHT,
+  PLAYER_SPAWN_POSITION_GAME[2],
+] as const;
 
 export function DebugCameraControls(): React.JSX.Element {
   return (
     <OrbitControls
       enableDamping
-      dampingFactor={0.05}
-      minDistance={100}
-      maxDistance={1000}
-      target={[0, 1.75, 0]}
+      dampingFactor={DEBUG_CAMERA_DAMPING_FACTOR}
+      minDistance={DEBUG_CAMERA_MIN_DISTANCE}
+      maxDistance={DEBUG_CAMERA_MAX_DISTANCE}
+      target={DEBUG_CAMERA_TARGET}
     />
   );
 }

src/utils/debug/scene/DebugHelpers.tsx

@@ -1,3 +1,11 @@
+import {
+  DEBUG_AXES_SIZE,
+  DEBUG_GRID_DIVISIONS,
+  DEBUG_GRID_PRIMARY_COLOR,
+  DEBUG_GRID_SECONDARY_COLOR,
+  DEBUG_GRID_SIZE,
+  DEBUG_GRID_Y,
+} from "@/data/debugConfig";
 import { Debug } from "@/utils/debug/Debug";
 
 export function DebugHelpers(): React.JSX.Element | null {
@@ -10,10 +18,15 @@ export function DebugHelpers(): React.JSX.Element | null {
   return (
     <>
       <gridHelper
-        args={[180, 36, "#1d4ed8", "#1e293b"]}
-        position={[0, 0.01, 0]}
+        args={[
+          DEBUG_GRID_SIZE,
+          DEBUG_GRID_DIVISIONS,
+          DEBUG_GRID_PRIMARY_COLOR,
+          DEBUG_GRID_SECONDARY_COLOR,
+        ]}
+        position={[0, DEBUG_GRID_Y, 0]}
       />
-      <axesHelper args={[10]} />
+      <axesHelper args={[DEBUG_AXES_SIZE]} />
     </>
   );
 }

src/utils/logger.ts

@@ -0,0 +1,111 @@
+import type {
+  LogContext,
+  LogEntry,
+  LogLevel,
+  LoggerConfig,
+} from "@/types/logger";
+import { isDebugEnabled } from "@/utils/debug/isDebugEnabled";
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+const LEVEL_LABELS: Record<LogLevel, string> = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+};
+
+const LEVEL_STYLES: Record<LogLevel, string> = {
+  debug: "color: #94a3b8; font-weight: 600;",
+  info: "color: #60a5fa; font-weight: 600;",
+  warn: "color: #f59e0b; font-weight: 600;",
+  error: "color: #f87171; font-weight: 600;",
+};
+
+const SCOPE_STYLE = "color: #e5e7eb; font-weight: 600;";
+const MESSAGE_STYLE = "color: inherit;";
+
+class Logger {
+  private readonly config: LoggerConfig;
+
+  constructor(config: LoggerConfig) {
+    this.config = config;
+  }
+
+  debug(scope: string, message: string, context?: LogContext): void {
+    this.log("debug", scope, message, context);
+  }
+
+  info(scope: string, message: string, context?: LogContext): void {
+    this.log("info", scope, message, context);
+  }
+
+  warn(scope: string, message: string, context?: LogContext): void {
+    this.log("warn", scope, message, context);
+  }
+
+  error(scope: string, message: string, context?: LogContext): void {
+    this.log("error", scope, message, context);
+  }
+
+  private log(
+    level: LogLevel,
+    scope: string,
+    message: string,
+    context?: LogContext,
+  ): void {
+    if (!this.shouldLog(level)) return;
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      scope,
+      message,
+      ...(context ? { context } : {}),
+    };
+
+    const formattedMessage = `%c[${LEVEL_LABELS[level]}]%c [${scope}]%c ${message}`;
+    const args = [
+      formattedMessage,
+      LEVEL_STYLES[level],
+      SCOPE_STYLE,
+      MESSAGE_STYLE,
+      entry,
+    ] as const;
+
+    switch (level) {
+      case "debug":
+        console.debug(...args);
+        return;
+      case "info":
+        console.info(...args);
+        return;
+      case "warn":
+        console.warn(...args);
+        return;
+      case "error":
+        console.error(...args);
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.config.minLevel];
+  }
+}
+
+function resolveMinLevel(): LogLevel {
+  if (typeof window === "undefined") {
+    return "info";
+  }
+
+  return isDebugEnabled() ? "debug" : "info";
+}
+
+export const logger = new Logger({
+  minLevel: resolveMinLevel(),
+});

src/world/Environment.tsx

@@ -1,3 +1,18 @@
+import { Environment as DreiEnvironment } from "@react-three/drei";
+import {
+  GAME_SCENE_SKYBOX_PATH,
+  PHYSICS_SCENE_BACKGROUND_COLOR,
+} from "@/data/environmentConfig";
+import { useSceneMode } from "@/hooks/debug/useSceneMode";
+
 export function Environment(): React.JSX.Element {
-  return <color attach="background" args={["#0b1018"]} />;
+  const sceneMode = useSceneMode();
+
+  if (sceneMode === "physics") {
+    return (
+      <color attach="background" args={[PHYSICS_SCENE_BACKGROUND_COLOR]} />
+    );
+  }
+
+  return <DreiEnvironment background files={GAME_SCENE_SKYBOX_PATH} />;
 }

src/world/Lighting.tsx

@@ -1,6 +1,26 @@
 import { useRef } from "react";
 import { useFrame } from "@react-three/fiber";
 import type { AmbientLight, DirectionalLight } from "three";
+import {
+  AMBIENT_INTENSITY_MAX,
+  AMBIENT_INTENSITY_MIN,
+  AMBIENT_INTENSITY_STEP,
+  AMBIENT_LIGHT_COLOR,
+  LIGHTING_DEFAULTS,
+  SUN_INTENSITY_MAX,
+  SUN_INTENSITY_MIN,
+  SUN_INTENSITY_STEP,
+  SUN_LIGHT_COLOR,
+  SUN_X_MAX,
+  SUN_X_MIN,
+  SUN_X_STEP,
+  SUN_Y_MAX,
+  SUN_Y_MIN,
+  SUN_Y_STEP,
+  SUN_Z_MAX,
+  SUN_Z_MIN,
+  SUN_Z_STEP,
+} from "@/data/lightingConfig";
 import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
 
 type LightingState = {
@@ -11,24 +31,40 @@ type LightingState = {
   sunZ: number;
 };
 
-const LIGHTING_STATE: LightingState = {
-  ambientIntensity: 1.8,
-  sunIntensity: 2.8,
-  sunX: 60,
-  sunY: 80,
-  sunZ: 30,
-};
+const LIGHTING_STATE: LightingState = { ...LIGHTING_DEFAULTS };
 
 export function Lighting(): React.JSX.Element {
   const ambient = useRef<AmbientLight>(null);
   const sun = useRef<DirectionalLight>(null);
 
   useDebugFolder("Lighting", (folder) => {
-    folder.add(LIGHTING_STATE, "ambientIntensity", 0, 5, 0.1).name("Ambient");
-    folder.add(LIGHTING_STATE, "sunIntensity", 0, 8, 0.1).name("Sun Intensity");
-    folder.add(LIGHTING_STATE, "sunX", -100, 100, 1).name("Sun X");
-    folder.add(LIGHTING_STATE, "sunY", 0, 150, 1).name("Sun Y");
-    folder.add(LIGHTING_STATE, "sunZ", -100, 100, 1).name("Sun Z");
+    folder
+      .add(
+        LIGHTING_STATE,
+        "ambientIntensity",
+        AMBIENT_INTENSITY_MIN,
+        AMBIENT_INTENSITY_MAX,
+        AMBIENT_INTENSITY_STEP,
+      )
+      .name("Ambient");
+    folder
+      .add(
+        LIGHTING_STATE,
+        "sunIntensity",
+        SUN_INTENSITY_MIN,
+        SUN_INTENSITY_MAX,
+        SUN_INTENSITY_STEP,
+      )
+      .name("Sun Intensity");
+    folder
+      .add(LIGHTING_STATE, "sunX", SUN_X_MIN, SUN_X_MAX, SUN_X_STEP)
+      .name("Sun X");
+    folder
+      .add(LIGHTING_STATE, "sunY", SUN_Y_MIN, SUN_Y_MAX, SUN_Y_STEP)
+      .name("Sun Y");
+    folder
+      .add(LIGHTING_STATE, "sunZ", SUN_Z_MIN, SUN_Z_MAX, SUN_Z_STEP)
+      .name("Sun Z");
   });
 
   useFrame(() => {
@@ -51,7 +87,7 @@ export function Lighting(): React.JSX.Element {
       <ambientLight
         ref={ambient}
         intensity={LIGHTING_STATE.ambientIntensity}
-        color="#dbeafe"
+        color={AMBIENT_LIGHT_COLOR}
       />
       <directionalLight
         ref={sun}
@@ -61,7 +97,7 @@ export function Lighting(): React.JSX.Element {
           LIGHTING_STATE.sunZ,
         ]}
         intensity={LIGHTING_STATE.sunIntensity}
-        color="#fff7ed"
+        color={SUN_LIGHT_COLOR}
         castShadow
       />
     </>

src/world/Map.tsx

@@ -2,34 +2,25 @@ import { useEffect, useRef } from "react";
 import { useThree } from "@react-three/fiber";
 import { useGLTF } from "@react-three/drei";
 import * as THREE from "three";
-import { Octree } from "three/addons/math/Octree.js";
+import { MAP_DEBUG_BOX_HELPER_COLOR } from "@/data/debugConfig";
+import { useOctreeGraphNode } from "@/hooks/useOctreeGraphNode";
+import type { OctreeReadyHandler } from "@/types/3d";
 import { Debug } from "@/utils/debug/Debug";
 
 const MAP_PATH = "/models/map/model.gltf";
 
 interface MapProps {
-  onOctreeReady: (octree: Octree) => void;
+  onOctreeReady: OctreeReadyHandler;
 }
 
 export function Map({ onOctreeReady }: MapProps): React.JSX.Element {
   const { scene: gltfScene } = useGLTF(MAP_PATH);
   const groupRef = useRef<THREE.Group>(null);
-  const octreeBuilt = useRef(false);
   const boxHelpersRef = useRef<THREE.BoxHelper[]>([]);
   const { scene } = useThree();
 
-  useEffect(() => {
-    if (octreeBuilt.current || !groupRef.current) return;
-    octreeBuilt.current = true;
+  useOctreeGraphNode(groupRef, onOctreeReady);
 
-    groupRef.current.updateMatrixWorld(true);
-
-    const octree = new Octree();
-    octree.fromGraphNode(groupRef.current);
-    onOctreeReady(octree);
-  }, [onOctreeReady]);
-
-  // BoxHelper wireframes in debug mode — one per mesh in the model
   useEffect(() => {
     const debug = Debug.getInstance();
     if (!debug.active || !groupRef.current) return;
@@ -38,7 +29,7 @@ export function Map({ onOctreeReady }: MapProps): React.JSX.Element {
 
     groupRef.current.traverse((child) => {
       if (!(child instanceof THREE.Mesh)) return;
-      const helper = new THREE.BoxHelper(child, 0x00ff88);
+      const helper = new THREE.BoxHelper(child, MAP_DEBUG_BOX_HELPER_COLOR);
       scene.add(helper);
       helpers.push(helper);
     });

src/world/World.tsx

@@ -1,5 +1,9 @@
-import { useState, useCallback } from "react";
+import { useState } from "react";
 import type { Octree } from "three/addons/math/Octree.js";
+import {
+  PLAYER_SPAWN_POSITION_GAME,
+  PLAYER_SPAWN_POSITION_PHYSICS,
+} from "@/data/playerConfig";
 import { useCameraMode } from "@/hooks/debug/useCameraMode";
 import { useSceneMode } from "@/hooks/debug/useSceneMode";
 import { DebugCameraControls } from "@/utils/debug/scene/DebugCameraControls";
@@ -14,7 +18,10 @@ export function World(): React.JSX.Element {
   const cameraMode = useCameraMode();
   const sceneMode = useSceneMode();
   const [octree, setOctree] = useState<Octree | null>(null);
-  const onOctreeReady = useCallback((o: Octree) => setOctree(o), []);
+  const playerSpawnPosition =
+    sceneMode === "game"
+      ? PLAYER_SPAWN_POSITION_GAME
+      : PLAYER_SPAWN_POSITION_PHYSICS;
 
   return (
     <>
@@ -24,16 +31,13 @@ export function World(): React.JSX.Element {
       {cameraMode === "debug" ? <DebugCameraControls /> : null}
 
       {sceneMode === "game" ? (
-        <Map onOctreeReady={onOctreeReady} />
+        <Map onOctreeReady={setOctree} />
       ) : (
-        <TestScene onOctreeReady={onOctreeReady} />
+        <TestScene onOctreeReady={setOctree} />
       )}
 
       {cameraMode !== "debug" ? (
-        <PlayerComponent
-          octree={octree}
-          spawnY={sceneMode === "game" ? 100 : 3}
-        />
+        <PlayerComponent octree={octree} spawnPosition={playerSpawnPosition} />
       ) : null}
     </>
   );

src/world/debug/TestScene.tsx

@@ -1,48 +1,89 @@
-import { useEffect, useRef } from "react";
+import { useRef } from "react";
 import { Physics, RigidBody, CuboidCollider } from "@react-three/rapier";
 import * as THREE from "three";
-import { Octree } from "three/addons/math/Octree.js";
-import { GrabCube } from "@/world/objects/GrabCube";
-import { TriggerSphere } from "@/world/objects/TriggerSphere";
+import { GrabbableObject } from "@/components/3d/GrabbableObject";
+import { TriggerObject } from "@/components/3d/TriggerObject";
+import {
+  TEST_SCENE_FLOOR_COLLIDER_HALF_EXTENTS,
+  TEST_SCENE_FLOOR_POSITION,
+  TEST_SCENE_FLOOR_SIZE,
+  TEST_SCENE_GRABBABLE_BOX_SIZE,
+  TEST_SCENE_GRABBABLE_COLOR,
+  TEST_SCENE_GRABBABLE_METALNESS,
+  TEST_SCENE_GRABBABLE_POSITION,
+  TEST_SCENE_GRABBABLE_ROUGHNESS,
+  TEST_SCENE_TRIGGER_COLOR,
+  TEST_SCENE_TRIGGER_METALNESS,
+  TEST_SCENE_TRIGGER_POSITION,
+  TEST_SCENE_TRIGGER_RADIUS,
+  TEST_SCENE_TRIGGER_ROUGHNESS,
+  TEST_SCENE_TRIGGER_SEGMENTS,
+  TEST_SCENE_TRIGGER_SOUND_PATH,
+} from "@/data/testSceneConfig";
+import { useOctreeGraphNode } from "@/hooks/useOctreeGraphNode";
+import type { OctreeReadyHandler } from "@/types/3d";
 
 interface TestSceneProps {
-  onOctreeReady: (octree: Octree) => void;
+  onOctreeReady: OctreeReadyHandler;
 }
 
 export function TestScene({
   onOctreeReady,
 }: TestSceneProps): React.JSX.Element {
   const floorRef = useRef<THREE.Group>(null);
-  const octreeBuilt = useRef(false);
 
-  useEffect(() => {
-    if (octreeBuilt.current || !floorRef.current) return;
-    octreeBuilt.current = true;
-
-    floorRef.current.updateMatrixWorld(true);
-
-    const octree = new Octree();
-    octree.fromGraphNode(floorRef.current);
-    onOctreeReady(octree);
-  }, [onOctreeReady]);
+  useOctreeGraphNode(floorRef, onOctreeReady);
 
   return (
     <>
-      {/* Invisible floor mesh for Octree player collision */}
       <group ref={floorRef}>
-        <mesh visible={false} position={[0, -0.5, 0]}>
-          <boxGeometry args={[200, 1, 200]} />
+        <mesh visible={false} position={TEST_SCENE_FLOOR_POSITION}>
+          <boxGeometry args={TEST_SCENE_FLOOR_SIZE} />
           <meshBasicMaterial />
         </mesh>
       </group>
 
-      {/* Rapier physics for interactable objects */}
       <Physics>
         <RigidBody type="fixed">
-          <CuboidCollider args={[100, 0.5, 100]} position={[0, -0.5, 0]} />
+          <CuboidCollider
+            args={TEST_SCENE_FLOOR_COLLIDER_HALF_EXTENTS}
+            position={TEST_SCENE_FLOOR_POSITION}
+          />
         </RigidBody>
-        <GrabCube />
-        <TriggerSphere />
+
+        <GrabbableObject
+          position={TEST_SCENE_GRABBABLE_POSITION}
+          colliders="cuboid"
+        >
+          <mesh castShadow receiveShadow>
+            <boxGeometry args={TEST_SCENE_GRABBABLE_BOX_SIZE} />
+            <meshStandardMaterial
+              color={TEST_SCENE_GRABBABLE_COLOR}
+              roughness={TEST_SCENE_GRABBABLE_ROUGHNESS}
+              metalness={TEST_SCENE_GRABBABLE_METALNESS}
+            />
+          </mesh>
+        </GrabbableObject>
+
+        <TriggerObject
+          position={TEST_SCENE_TRIGGER_POSITION}
+          soundPath={TEST_SCENE_TRIGGER_SOUND_PATH}
+        >
+          <mesh castShadow receiveShadow>
+            <sphereGeometry
+              args={[
+                TEST_SCENE_TRIGGER_RADIUS,
+                TEST_SCENE_TRIGGER_SEGMENTS,
+                TEST_SCENE_TRIGGER_SEGMENTS,
+              ]}
+            />
+            <meshStandardMaterial
+              color={TEST_SCENE_TRIGGER_COLOR}
+              roughness={TEST_SCENE_TRIGGER_ROUGHNESS}
+              metalness={TEST_SCENE_TRIGGER_METALNESS}
+            />
+          </mesh>
+        </TriggerObject>
       </Physics>
     </>
   );

src/world/objects/GrabCube.tsx

@@ -1,80 +0,0 @@
-import { useRef } from "react";
-import { useFrame, useThree } from "@react-three/fiber";
-import type { RapierRigidBody } from "@react-three/rapier";
-import * as THREE from "three";
-import { InteractableObject } from "@/components/3d/InteractableObject";
-import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
-
-const CUBE_SIZE = 0.5;
-const HOLD_DISTANCE = 2;
-const SPAWN_POSITION: [number, number, number] = [0, 1, -3];
-
-const params = { stiffness: 15, throwBoost: 1.0 };
-
-const _holdTarget = new THREE.Vector3();
-const _currentPos = new THREE.Vector3();
-const _velocity = new THREE.Vector3();
-
-export function GrabCube(): React.JSX.Element {
-  const camera = useThree((state) => state.camera);
-  const rbRef = useRef<RapierRigidBody>(null);
-  const isHolding = useRef(false);
-
-  useDebugFolder("GrabCube", (folder) => {
-    folder.add(params, "stiffness", 1, 50, 1).name("Hold stiffness");
-    folder.add(params, "throwBoost", 0.5, 3.0, 0.1).name("Throw boost");
-  });
-
-  useFrame(() => {
-    if (!isHolding.current || !rbRef.current) return;
-
-    camera.getWorldDirection(_holdTarget);
-    _holdTarget.multiplyScalar(HOLD_DISTANCE).add(camera.position);
-
-    const t = rbRef.current.translation();
-    _currentPos.set(t.x, t.y, t.z);
-
-    _velocity
-      .subVectors(_holdTarget, _currentPos)
-      .multiplyScalar(params.stiffness);
-
-    rbRef.current.setLinvel(
-      { x: _velocity.x, y: _velocity.y, z: _velocity.z },
-      true,
-    );
-    rbRef.current.setAngvel({ x: 0, y: 0, z: 0 }, true);
-  });
-
-  return (
-    <InteractableObject
-      kind="grab"
-      label="Prendre"
-      position={SPAWN_POSITION}
-      rigidBodyType="dynamic"
-      colliders="cuboid"
-      rbRef={rbRef}
-      onPress={() => {
-        isHolding.current = true;
-      }}
-      onRelease={() => {
-        isHolding.current = false;
-        if (rbRef.current && params.throwBoost !== 1.0) {
-          const v = rbRef.current.linvel();
-          rbRef.current.setLinvel(
-            {
-              x: v.x * params.throwBoost,
-              y: v.y * params.throwBoost,
-              z: v.z * params.throwBoost,
-            },
-            true,
-          );
-        }
-      }}
-    >
-      <mesh castShadow receiveShadow>
-        <boxGeometry args={[CUBE_SIZE, CUBE_SIZE, CUBE_SIZE]} />
-        <meshStandardMaterial color="#e07b39" roughness={0.6} metalness={0.1} />
-      </mesh>
-    </InteractableObject>
-  );
-}

src/world/objects/TriggerSphere.tsx

@@ -1,32 +0,0 @@
-import { AudioManager } from "@/stateManager/AudioManager";
-import { InteractableObject } from "@/components/3d/InteractableObject";
-
-const SPHERE_RADIUS = 0.4;
-const SPAWN_POSITION: [number, number, number] = [3, 2, -3];
-const SOUND_PATH = "/sounds/fa.mp3";
-
-interface TriggerSphereProps {
-  soundPath?: string;
-}
-
-export function TriggerSphere({
-  soundPath = SOUND_PATH,
-}: TriggerSphereProps): React.JSX.Element {
-  return (
-    <InteractableObject
-      kind="trigger"
-      label="Interagir"
-      position={SPAWN_POSITION}
-      rigidBodyType="fixed"
-      colliders="ball"
-      onPress={() => {
-        AudioManager.getInstance().playSound(soundPath);
-      }}
-    >
-      <mesh castShadow receiveShadow>
-        <sphereGeometry args={[SPHERE_RADIUS, 32, 32]} />
-        <meshStandardMaterial color="#3b82f6" roughness={0.3} metalness={0.5} />
-      </mesh>
-    </InteractableObject>
-  );
-}

src/world/player/PlayerCamera.tsx

@@ -1,9 +1,6 @@
 import { useEffect } from "react";
 import { PointerLockControls } from "@react-three/drei";
 
-export const PLAYER_EYE_HEIGHT = 1.75;
-export const PLAYER_CAPSULE_RADIUS = 0.35;
-
 export function PlayerCamera(): React.JSX.Element {
   useEffect(() => {
     return () => {

src/world/player/PlayerComponent.tsx

@@ -1,28 +1,29 @@
 import { useEffect } from "react";
 import { useThree } from "@react-three/fiber";
 import type { Octree } from "three/addons/math/Octree.js";
+import type { Vector3Tuple } from "@/types/3d";
 import { PlayerCamera } from "@/world/player/PlayerCamera";
 import { PlayerController } from "@/world/player/PlayerController";
 
 interface PlayerComponentProps {
-  octree?: Octree | null;
-  spawnY?: number;
+  octree: Octree | null;
+  spawnPosition: Vector3Tuple;
 }
 
 export function PlayerComponent({
-  octree = null,
-  spawnY = 100,
+  spawnPosition,
+  octree,
 }: PlayerComponentProps): React.JSX.Element {
   const camera = useThree((state) => state.camera);
 
   useEffect(() => {
-    camera.position.set(0, spawnY, 0);
-  }, [camera, spawnY]);
+    camera.position.set(...spawnPosition);
+  }, [camera, spawnPosition]);
 
   return (
     <>
       <PlayerCamera />
-      <PlayerController octree={octree} />
+      <PlayerController octree={octree} spawnPosition={spawnPosition} />
     </>
   );
 }

src/world/player/PlayerController.tsx

@@ -3,16 +3,28 @@ import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { Capsule } from "three/addons/math/Capsule.js";
 import type { Octree } from "three/addons/math/Octree.js";
-import { InteractionManager } from "@/stateManager/InteractionManager";
 import {
-  PLAYER_EYE_HEIGHT,
+  INTERACT_KEY,
+  JUMP_KEY,
+  MOVE_BACKWARD_KEY,
+  MOVE_FORWARD_KEY,
+  MOVE_LEFT_KEY,
+  MOVE_RIGHT_KEY,
+  PRIMARY_INTERACT_MOUSE_BUTTON,
+} from "@/data/keybindings";
+import {
+  PLAYER_ACCELERATION_MULTIPLIER,
+  PLAYER_AIR_CONTROL_FACTOR,
   PLAYER_CAPSULE_RADIUS,
-} from "@/world/player/PlayerCamera";
-
-const WALK_SPEED = 11;
-const AIR_CONTROL = 0.35;
-const JUMP_SPEED = 9;
-const GRAVITY = 30;
+  PLAYER_EYE_HEIGHT,
+  PLAYER_GRAVITY,
+  PLAYER_JUMP_SPEED,
+  PLAYER_MAX_DELTA,
+  PLAYER_WALK_SPEED,
+  PLAYER_XZ_DAMPING_FACTOR,
+} from "@/data/playerConfig";
+import { InteractionManager } from "@/stateManager/InteractionManager";
+import type { Vector3Tuple } from "@/types/3d";
 
 type Keys = {
   forward: boolean;
@@ -32,6 +44,7 @@ const DEFAULT_KEYS: Keys = {
 
 interface PlayerControllerProps {
   octree: Octree | null;
+  spawnPosition: Vector3Tuple;
 }
 
 const _forward = new THREE.Vector3();
@@ -39,15 +52,18 @@ const _right = new THREE.Vector3();
 const _wishDir = new THREE.Vector3();
 const _up = new THREE.Vector3(0, 1, 0);
 const _translateVec = new THREE.Vector3();
+const _collisionCorrection = new THREE.Vector3();
 
-export function PlayerController({ octree }: PlayerControllerProps): null {
+export function PlayerController({
+  octree,
+  spawnPosition,
+}: PlayerControllerProps): null {
   const camera = useThree((state) => state.camera);
   const keys = useRef<Keys>({ ...DEFAULT_KEYS });
   const velocity = useRef(new THREE.Vector3());
   const onFloor = useRef(false);
   const wantsJump = useRef(false);
 
-  // Capsule: start = feet, end = eyes
   const capsule = useRef(
     new Capsule(
       new THREE.Vector3(0, PLAYER_CAPSULE_RADIUS, 0),
@@ -56,39 +72,40 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
     ),
   );
 
-  // Sync capsule to camera spawn position on mount
   useEffect(() => {
-    const spawnY = camera.position.y;
     capsule.current.start.set(
-      0,
-      spawnY - PLAYER_EYE_HEIGHT + PLAYER_CAPSULE_RADIUS,
-      0,
+      spawnPosition[0],
+      spawnPosition[1] - PLAYER_EYE_HEIGHT + PLAYER_CAPSULE_RADIUS,
+      spawnPosition[2],
     );
-    capsule.current.end.set(0, spawnY, 0);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+    capsule.current.end.set(...spawnPosition);
+    velocity.current.set(0, 0, 0);
+    onFloor.current = false;
+    wantsJump.current = false;
+    camera.position.copy(capsule.current.end);
+  }, [camera, spawnPosition]);
 
   useEffect(() => {
     const interaction = InteractionManager.getInstance();
 
     const handleKeyDown = (event: KeyboardEvent): void => {
       switch (event.key.toLowerCase()) {
-        case "z":
+        case MOVE_FORWARD_KEY:
           keys.current.forward = true;
           break;
-        case "s":
+        case MOVE_BACKWARD_KEY:
           keys.current.backward = true;
           break;
-        case "q":
+        case MOVE_LEFT_KEY:
           keys.current.left = true;
           break;
-        case "d":
+        case MOVE_RIGHT_KEY:
           keys.current.right = true;
           break;
-        case " ":
+        case JUMP_KEY:
           wantsJump.current = true;
           break;
-        case "e":
+        case INTERACT_KEY:
           if (interaction.getState().focused?.kind === "trigger") {
             interaction.pressInteract();
           }
@@ -101,23 +118,18 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
 
     const handleKeyUp = (event: KeyboardEvent): void => {
       switch (event.key.toLowerCase()) {
-        case "z":
+        case MOVE_FORWARD_KEY:
           keys.current.forward = false;
           break;
-        case "s":
+        case MOVE_BACKWARD_KEY:
           keys.current.backward = false;
           break;
-        case "q":
+        case MOVE_LEFT_KEY:
           keys.current.left = false;
           break;
-        case "d":
+        case MOVE_RIGHT_KEY:
           keys.current.right = false;
           break;
-        case "e":
-          if (interaction.getState().focused?.kind === "trigger") {
-            interaction.releaseInteract();
-          }
-          break;
         default:
           return;
       }
@@ -125,14 +137,14 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
     };
 
     const handleMouseDown = (event: MouseEvent): void => {
-      if (event.button !== 0) return;
+      if (event.button !== PRIMARY_INTERACT_MOUSE_BUTTON) return;
       if (interaction.getState().focused?.kind === "grab") {
         interaction.pressInteract();
       }
     };
 
     const handleMouseUp = (event: MouseEvent): void => {
-      if (event.button !== 0) return;
+      if (event.button !== PRIMARY_INTERACT_MOUSE_BUTTON) return;
       if (interaction.getState().holding) {
         interaction.releaseInteract();
       }
@@ -153,10 +165,8 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
   }, []);
 
   useFrame((_, delta) => {
-    // Clamp delta so physics don't explode on tab focus regain
-    const dt = Math.min(delta, 0.05);
+    const dt = Math.min(delta, PLAYER_MAX_DELTA);
 
-    // Compute wish direction from camera yaw (XZ only)
     camera.getWorldDirection(_forward);
     _forward.setY(0);
     if (_forward.lengthSq() > 0) {
@@ -171,33 +181,32 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
     if (keys.current.right) _wishDir.add(_right);
     if (_wishDir.lengthSq() > 0) _wishDir.normalize();
 
-    // Accelerate horizontally
-    const accel = onFloor.current ? WALK_SPEED : WALK_SPEED * AIR_CONTROL;
-    velocity.current.x += _wishDir.x * accel * dt * 9;
-    velocity.current.z += _wishDir.z * accel * dt * 9;
+    const accel = onFloor.current
+      ? PLAYER_WALK_SPEED
+      : PLAYER_WALK_SPEED * PLAYER_AIR_CONTROL_FACTOR;
+    velocity.current.x +=
+      _wishDir.x * accel * dt * PLAYER_ACCELERATION_MULTIPLIER;
+    velocity.current.z +=
+      _wishDir.z * accel * dt * PLAYER_ACCELERATION_MULTIPLIER;
 
-    // Exponential damping on XZ
-    const damping = Math.exp(-8 * dt);
+    const damping = Math.exp(-PLAYER_XZ_DAMPING_FACTOR * dt);
     velocity.current.x *= damping;
     velocity.current.z *= damping;
 
-    // Gravity + jump
     if (onFloor.current) {
       velocity.current.y = Math.max(0, velocity.current.y);
       if (wantsJump.current) {
-        velocity.current.y = JUMP_SPEED;
+        velocity.current.y = PLAYER_JUMP_SPEED;
         onFloor.current = false;
       }
     } else {
-      velocity.current.y -= GRAVITY * dt;
+      velocity.current.y -= PLAYER_GRAVITY * dt;
     }
     wantsJump.current = false;
 
-    // Move capsule
     _translateVec.copy(velocity.current).multiplyScalar(dt);
     capsule.current.translate(_translateVec);
 
-    // Resolve collisions against octree
     if (octree) {
       const result = octree.capsuleIntersect(capsule.current);
       onFloor.current = false;
@@ -206,21 +215,18 @@ export function PlayerController({ octree }: PlayerControllerProps): null {
         onFloor.current = result.normal.y > 0;
 
         if (!onFloor.current) {
-          // Cancel velocity component going into the wall
           const vn = result.normal.dot(velocity.current);
           velocity.current.addScaledVector(result.normal, -vn);
         } else {
           velocity.current.y = Math.max(0, velocity.current.y);
         }
 
-        // Push capsule out of geometry
         capsule.current.translate(
-          result.normal.clone().multiplyScalar(result.depth),
+          _collisionCorrection.copy(result.normal).multiplyScalar(result.depth),
         );
       }
     }
 
-    // Sync camera to capsule top (eye position)
     camera.position.copy(capsule.current.end);
   });