update : docs and skills

2026-04-15 11:06:41 +02:00
parent 8dae23acc3
commit 3da749c73e
6 changed files with 858 additions and 382 deletions
@@ -0,0 +1,381 @@
+# Architecture Patterns
+
+The project uses **two complementary patterns**:
+
+- **Singleton service classes** for orchestration and side effects
+- **Declarative React components** for all 3D scene objects
+
+This distinction is intentional. Scene elements such as the map, lights, environment, zones, and player are implemented as **React Three Fiber components** and mounted through `<Canvas>`.
+Global systems such as gameplay flow, cinematics, audio, and debug tooling are implemented as **manager classes**.
+
+Consistency matters, but the codebase does **not** force the same lifecycle pattern on scene components and global services.
+
+---
+
+## 1. Singleton Pattern for Global Managers Only
+
+Only cross-cutting services use the singleton pattern.
+
+Examples:
+
+- `GameManager`
+- `CinematicManager`
+- `AudioManager`
+- `ZoneManager`
+- `Debug`
+- `EventEmitter`
+
+These services must exist once, be accessible from anywhere, and coordinate the experience globally.
+
+```ts
+// stateManager/GameManager.ts
+export class GameManager {
+  private static _instance: GameManager | null = null;
+
+  cinematic!: CinematicManager;
+  audio!: AudioManager;
+  zone!: ZoneManager;
+
+  static getInstance(): GameManager {
+    if (!GameManager._instance) {
+      GameManager._instance = new GameManager();
+    }
+    return GameManager._instance;
+  }
+
+  private constructor() {
+    this.cinematic = CinematicManager.getInstance();
+    this.audio = AudioManager.getInstance();
+    this.zone = ZoneManager.getInstance();
+  }
+
+  destroy(): void {
+    this.cinematic.destroy();
+    this.audio.destroy();
+    this.zone.destroy();
+    GameManager._instance = null;
+  }
+}
+```
+
+Usage:
+
+```ts
+const game = GameManager.getInstance();
+game.startMission("workshop");
+```
+
+**Important:** scene objects such as `Map`, `WorkshopZone`, `Lighting`, or `Environment` are **not** singletons and must remain standard React components.
+
+---
+
+## 2. Scene Objects Are React Components, Not Manager Classes
+
+All 3D scene objects are implemented as **declarative React components**.
+
+This includes:
+
+- maps
+- lights
+- environments
+- player controllers
+- zones
+- interactive props
+- postprocessing layers
+
+This keeps the code aligned with the R3F runtime instead of rebuilding a parallel imperative engine.
+
+Example:
+
+```tsx
+// world/zones/WorkshopZone.tsx
+import { useEffect, useRef } from "react";
+import * as THREE from "three";
+import { useFrame } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+
+export function WorkshopZone() {
+  const root = useRef<THREE.Group>(null);
+  const gltf = useGLTF("/models/workshop/ebike.glb");
+  const mixer = useRef<THREE.AnimationMixer | null>(null);
+
+  useEffect(() => {
+    mixer.current = new THREE.AnimationMixer(gltf.scene);
+
+    return () => {
+      mixer.current?.stopAllAction();
+      mixer.current = null;
+    };
+  }, [gltf.scene]);
+
+  useFrame((_, delta) => {
+    mixer.current?.update(delta);
+  });
+
+  return <primitive ref={root} object={gltf.scene.clone()} />;
+}
+```
+
+Per-frame values such as movement, interpolation, camera smoothing, and physics must stay in:
+
+- `useRef`
+- `useFrame`
+- Rapier bodies
+- other frame-based systems
+
+They must **never** go through React state.
+
+---
+
+## 3. Single Source of Truth for Durable Gameplay State
+
+The project uses a single authoritative `GameManager` for durable gameplay state.
+
+React components subscribe to that state through thin hooks.
+Other managers communicate through `GameManager`, which acts as the main gameplay orchestrator.
+
+High-frequency values such as movement, camera interpolation, or physics never go through React state and stay in refs or frame-based systems.
+
+```ts
+// stateManager/GameManager.ts
+type Phase = "loading" | "intro" | "exploring" | "cinematic" | "outro";
+type ZoneId = "workshop" | "powerGrid" | "farm" | null;
+
+type GameSnapshot = {
+  phase: Phase;
+  activeZone: ZoneId;
+  missionId: string | null;
+  missionStep: number;
+  inputLocked: boolean;
+  dialogueId: string | null;
+};
+
+export class GameManager {
+  private static _instance: GameManager | null = null;
+  private listeners = new Set<() => void>();
+
+  private state: GameSnapshot = {
+    phase: "loading",
+    activeZone: null,
+    missionId: null,
+    missionStep: 0,
+    inputLocked: false,
+    dialogueId: null,
+  };
+
+  static getInstance(): GameManager {
+    if (!GameManager._instance) {
+      GameManager._instance = new GameManager();
+    }
+    return GameManager._instance;
+  }
+
+  getState(): GameSnapshot {
+    return this.state;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(): void {
+    this.listeners.forEach((cb) => cb());
+  }
+
+  setPhase(phase: Phase): void {
+    this.state.phase = phase;
+    this.emit();
+  }
+
+  setActiveZone(zone: ZoneId): void {
+    this.state.activeZone = zone;
+    this.emit();
+  }
+
+  startMission(id: string): void {
+    this.state.missionId = id;
+    this.state.missionStep = 0;
+    this.emit();
+  }
+}
+```
+
+```ts
+// hooks/useGameState.ts
+import { useEffect, useState } from "react";
+import { GameManager } from "@/stateManager/GameManager";
+
+export function useGameState() {
+  const game = GameManager.getInstance();
+  const [state, setState] = useState(game.getState());
+
+  useEffect(() => {
+    return game.subscribe(() => {
+      setState({ ...game.getState() });
+    });
+  }, [game]);
+
+  return state;
+}
+```
+
+This keeps the architecture simple:
+
+- **GameManager** owns durable gameplay state
+- **other managers** handle side effects
+- **React components** render that state
+- **R3F frame systems** handle fast-changing values
+
+---
+
+## 4. Side Effects Stay in Specialized Managers
+
+Managers other than `GameManager` should not become secondary state stores.
+
+Their role is to manage side effects and specialized runtime logic, such as:
+
+- GSAP timelines
+- audio playback
+- zone entry detection
+- interaction triggers
+- camera lock/unlock
+- temporary event coordination
+
+They can read from `GameManager`, react to its state, or notify it of important transitions.
+
+Example flow:
+
+```
+Component / Hook
+      ↓
+GameManager.getInstance()
+      ├── startMission('workshop')
+      ├── cinematic.play('intro_workshop')
+      ├── audio.playAmbience('workshop')
+      └── zone.setActive('workshop')
+```
+
+This keeps the dependency graph understandable while avoiding duplicated durable state.
+
+---
+
+## 5. Memory Management — Dispose Only What You Own
+
+GPU memory must be cleaned carefully.
+
+However, the project does **not** blindly deep-dispose every object on unmount.
+Only resources explicitly created and owned by the current component or manager should be disposed.
+
+This includes things like:
+
+- custom materials
+- render targets
+- postprocessing passes
+- manually created geometries
+- manually created textures
+- temporary clones with owned resources
+
+Shared or cached assets must **not** be blindly disposed.
+
+```ts
+// utils/Dispose.ts
+import * as THREE from "three";
+
+export class Dispose {
+  static material(material: THREE.Material): void {
+    for (const value of Object.values(material)) {
+      if (value instanceof THREE.Texture) {
+        value.dispose();
+      }
+    }
+    material.dispose();
+  }
+
+  static mesh(mesh: THREE.Mesh): void {
+    mesh.geometry?.dispose();
+
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : [mesh.material];
+
+    for (const material of materials) {
+      if (material) this.material(material);
+    }
+  }
+
+  static renderTarget(rt: THREE.WebGLRenderTarget): void {
+    rt.texture.dispose();
+    rt.dispose();
+  }
+}
+```
+
+Example usage:
+
+```ts
+useEffect(() => {
+  const material = new THREE.ShaderMaterial({
+    vertexShader,
+    fragmentShader,
+  });
+
+  meshRef.current.material = material;
+
+  return () => {
+    Dispose.material(material);
+  };
+}, []);
+```
+
+**Rule:** disposal is ownership-based, not automatic and not blind.
+
+---
+
+## 6. Debug Utility
+
+The debug panel can be activated by appending `?debug` to the URL:
+
+`http://localhost:5173?debug`
+
+All debug logic is centralized in `Debug.ts`.
+Do not scatter debug checks across the codebase.
+
+```ts
+// utils/Debug.ts
+import GUI from "lil-gui";
+
+export class Debug {
+  private static _instance: Debug | null = null;
+
+  readonly active: boolean;
+  gui: GUI | null = null;
+
+  static getInstance(): Debug {
+    if (!Debug._instance) Debug._instance = new Debug();
+    return Debug._instance;
+  }
+
+  private constructor() {
+    this.active = new URLSearchParams(window.location.search).has("debug");
+    if (this.active) {
+      this.gui = new GUI({ title: "La-Fabrik Debug" });
+    }
+  }
+
+  destroy(): void {
+    this.gui?.destroy();
+    Debug._instance = null;
+  }
+}
+```
+
+Usage:
+
+```ts
+const debug = Debug.getInstance();
+
+if (debug.active) {
+  debug.gui!.add(params, "bloomIntensity", 0, 3).name("Bloom");
+}
+```