math-pixel/La-Fabrik
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: audit app architecture and refresh feature documentation
🔍 Lint / 🪄 Check lint (push) Has been cancelled
Details
🔍 Lint / 🎨 Check format (push) Has been cancelled
Details
🔍 Lint / 🔎 Typecheck (push) Has been cancelled
Details
🔍 Lint / 🏗 Build (push) Has been cancelled
Details
📊 Quality / 🔒 Security Audit (push) Has been cancelled
Details
📊 Quality / 📋 Dependency Freshness (push) Has been cancelled
Details
📊 Quality / 📦 Bundle Size (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Tom Boullay
2026-05-12 11:46:11 +02:00
parent b04aa95966
commit c09818aa67
32 changed files with 1869 additions and 1144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+142 -103
View File
@@ -1,124 +1,163 @@
# La-Fabrik
An interactive 3D web experience for La Fabrik Durable — a low-tech repair and transformation service in Altera, a post-capitalist city rebuilt in 2039. Players step into the role of a newly onboarded technician and experience a day at the service: repairing an e-bike, fixing a power grid, and upgrading a vertical farm's irrigation system.
La-Fabrik is an interactive 3D web experience built with React, Vite, Three.js, React Three Fiber, Rapier, GSAP, MediaPipe, and Zustand.
Built with React, Three.js, and Vite. Runs in the browser, no installation required.
The current prototype puts the player in a repair-oriented world where they progress through a short mission chain: intro, e-bike repair, power pylon repair, vertical farm repair, then outro. The project also includes a local editor for map, dialogue, subtitle, and cinematic data.
## 📦 Tech Stack
## Current Scope
### Build & Language
- Playable fullscreen 3D scene at `/`
- Production map loaded from `public/map.json`
- Progressive map/model/collision/stage loading overlay
- Player controller with pointer lock, `ZQSD` movement, jump, octree collision, trigger input, and grab input
- Reusable repair-game flow for `bike`, `pylone`, and `ferme`
- Repair case animation, exploded model scan, broken-part markers, grabbable replacements, snap-to-placeholder placement, install validation, reassembly, and completion
- Shared interaction system for trigger and grab objects
- Rapier physics for gameplay objects while the player keeps a Three.js octree collision controller
- Hand tracking through either a local Python WebSocket backend or browser-side MediaPipe
- Category-based audio manager for music, SFX, and dialogue
- Dialogue manifest, SRT subtitles, subtitle overlay, and dialogue queueing
- Cinematic manifest with GSAP camera keyframes and optional dialogue cues
- In-game settings menu for volumes, subtitles, subtitle language, and the currently staged repair-runtime toggle
- Debug mode with `?debug`, lil-gui controls, game-state panel, hand-tracking panel, debug camera, physics playground, and R3F perf
- `/editor` route for map transforms, SRT editing, dialogue manifest editing, cinematic manifest editing, preview, validation, export, and dev-server saves
- `/docs` route that renders the repository documentation inside the app
| Package |
| -------------------------------------------------- |
| [TypeScript](https://www.typescriptlang.org/docs/) |
| [React](https://react.dev/learn) |
| [Vite](https://vite.dev/guide/) |
| [ESLint](https://eslint.org/docs/latest/) |
| [Prettier](https://prettier.io/docs/) |
## Routes
### 3D Engine
| Route | Purpose |
| --------- | --------------------------------------------------- |
| `/` | Playable 3D experience |
| `/?debug` | Playable scene with debug GUI and overlays |
| `/editor` | Local map, dialogue, subtitle, and cinematic editor |
| `/docs` | In-app documentation index |
| Package |
| ----------------------------------------------------------------------------------------- |
| [Three.js](https://threejs.org/docs/) |
| [@react-three/fiber](https://docs.pmnd.rs/react-three-fiber/getting-started/introduction) |
| [@react-three/drei](https://pmndrs.github.io/drei) |
| [@react-three/rapier](https://rapier.rs/docs/) |
| [GSAP](https://gsap.com/docs/v3/Installation/) |
## Tech Stack
### Performance & Effects
| Area | Packages |
| --------------------- | ------------------------------------------------------------------------------ |
| App | React 19, TypeScript, Vite, TanStack Router |
| 3D | Three.js, React Three Fiber, drei |
| Physics and animation | `@react-three/rapier`, GSAP, Three.js `AnimationMixer` |
| State | Zustand, custom singleton managers where imperative runtime objects are needed |
| Hand tracking | `@mediapipe/tasks-vision`, optional FastAPI backend |
| Docs | `react-markdown`, `remark-gfm` |
| Quality | ESLint, Prettier, TypeScript project build |
| Package |
| --------------------------------------------------------------------------- |
| [r3f-perf](https://github.com/utsuboco/r3f-perf) |
| [AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer) |
## Project Structure
## 🗂 Project Structure
```
la-fabrik/
├── public/
│ ├── models/
│ │ ├── map/ # Base map — loaded once at start
│ │ ├── workshop/
│ │ ├── powerGrid/
│ │ └── farm/
│ ├── textures/
│ └── sounds/
│
└── src/
├── world/ # Persistent 3D world composition
│ ├── World.tsx # Active scene composition
│ ├── GameMap.tsx # Map loading and progressive rendering
│ ├── GameMapCollision.tsx # Collision-only octree source
│ ├── Lighting.tsx # Ambient, directional, point lights
│ ├── Environment.tsx # Scene background / sky model
│ ├── GameMusic.tsx # Game scene music lifecycle
│ ├── debug/ # Debug-only test scene
│ │ └── TestMap.tsx
│ └── player/
│ ├── Player.tsx # Player rig composition
│ ├── PlayerCamera.tsx # Player camera mount
│ └── PlayerController.tsx # Pointer lock movement and inputs
│
├── components/
│ ├── three/ # Shared R3F components by domain
│ │ ├── gameplay/ # Core repair gameplay prototype
│ │ ├── handTracking/ # R3F hand tracking debug models
│ │ ├── interaction/ # Trigger, grab, focus wrappers
│ │ ├── models/ # GLTF model components
│ │ └── world/ # Environment-specific 3D objects
│ └── ui/ # HTML overlays — outside Canvas
│ ├── Crosshair.tsx
│ ├── debug/ # Debug-only HTML overlay panels
│ │ ├── DebugOverlayLayout.tsx
│ │ ├── GameStateDebugPanel.tsx
│ │ └── HandTrackingDebugPanel.tsx
│ ├── HandTrackingVisualizer.tsx
│ └── InteractPrompt.tsx
│
├── managers/ # Current singleton-style services
│ ├── AudioManager.ts # Music and SFX playback
│ └── InteractionManager.ts # Focus, nearby, grab state
│
├── hooks/ # React hooks by domain
│ ├── debug/ # Debug state and GUI folders
│ ├── docs/ # Docs language context access
│ ├── editor/ # Editor loading and history
│ ├── gameplay/ # Repair gameplay helpers
│ ├── handTracking/ # Webcam/WebSocket hand tracking
│ ├── interaction/ # Interaction manager subscriptions
│ └── three/ # Three.js/R3F helpers
│
├── data/
│ ├── interaction/ # Interaction tuning
│ ├── player/ # Player tuning
│ ├── gameplay/ # Repair gameplay static config
│ └── world/ # Environment and lighting config
│
├── utils/
│ ├── core/ # Logger and generic utilities
│ ├── debug/ # Dev-only tools and scene inspection
│ ├── editor/ # Editor-only parsing utilities
│ ├── map/ # Map loading and validation
│ └── three/ # Three.js helpers
├── types/ # Shared TypeScript domain types
├── App.tsx # App bootstrap and route switch
└── main.tsx
```txt
.
|-- backend/ # Optional Python hand-tracking backend
|-- docs/
| +-- technical/ # Architecture and implementation notes
| +-- user/ # Feature and user-facing guides
|-- public/
| +-- assets/ # UI videos, PDFs, logos, world videos
| +-- cinematics.json # Runtime cinematic manifest
| +-- map.json # Runtime/editor map data
| +-- models/ # GLTF/GLB assets resolved by model folder name
| +-- sounds/ # Music, SFX, dialogue audio, SRT subtitles
|-- src/
| +-- components/
| | +-- docs/ # In-app docs layout and renderer
| | +-- editor/ # Editor panels and editor scene
| | +-- three/ # R3F components by domain
| | +-- ui/ # HTML game/debug overlays
| +-- controls/ # Editor fly/player-style controls
| +-- data/ # Static tuning/config per domain
| +-- hooks/ # React hooks by domain
| +-- lib/ # Browser hand-tracking helpers
| +-- managers/ # Audio, interaction, and Zustand stores
| +-- pages/ # Route-level pages
| +-- providers/ # Docs and hand-tracking providers
| +-- routes/ # Lazy route wrappers
| +-- types/ # Shared domain types
| +-- utils/ # Core, map, editor, dialogue, subtitle, Three helpers
| +-- world/ # Production/debug world composition and player
`-- vite.config.ts # Vite config plus local editor save endpoints
```
## 🚀 Getting Started
## Getting Started
Install and run the frontend:
```bash
git clone https://github.com/La-Fabrik-Durable/La-Fabrik.git
cd La-Fabrik
npm install
npm run dev
```
- app: `http://localhost:5173`
- debug mode: `http://localhost:5173?debug`
Open:
## 📜 License
```txt
http://localhost:5173
```
See [LICENSE](./LICENSE) file.
Useful local URLs:
```txt
http://localhost:5173/?debug
http://localhost:5173/editor
http://localhost:5173/docs
```
Run checks:
```bash
npm run typecheck
npm run lint
npm run format:check
npm run build
```
## Optional Hand-Tracking Backend
The app can use browser-side MediaPipe, but the default debug source is the local backend.
```bash
python3.11 -m venv backend/.venv
source backend/.venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r backend/requirements.txt
python backend/download_model.py
python -m backend.main
```
Backend endpoints:
```txt
GET http://localhost:8000/health
WS ws://localhost:8000/ws
```
## Documentation Index
| File | Purpose |
| --------------------------------------- | ---------------------------------------------------------- |
| `docs/technical/architecture.md` | Current runtime architecture |
| `docs/technical/scene-runtime.md` | Scene loading, world composition, and player spawn gates |
| `docs/technical/repair-game.md` | Repair-game implementation and state flow |
| `docs/technical/interaction.md` | Trigger, grab, focus, and hand-grab system |
| `docs/technical/target-architecture.md` | Intended medium-term architecture direction |
| `docs/technical/audio.md` | Music, SFX, dialogue, subtitles, and editor validation |
| `docs/technical/hand-tracking.md` | Webcam, backend/browser MediaPipe, glove, and gesture flow |
| `docs/technical/zustand.md` | Game, settings, and subtitle stores |
| `docs/technical/three-debugging.md` | DevTools workflow for stepping into Three.js internals |
| `docs/technical/editor.md` | Editor implementation details |
| `docs/technical/animation.md` | Animated, explodable, and reusable 3D model components |
| `docs/user/features.md` | Implemented feature inventory |
| `docs/user/main-feature.md` | User-facing repair-game walkthrough |
| `docs/user/editor.md` | Editor user guide |
| `docs/code-review-preparation.md` | French code-review preparation support |
## Current Caveats
- This is still a prototype, not a complete game runtime.
- The repair-runtime toggle is stored in settings and displayed in the UI, but the repair game currently still runs locally in React/Three.
- `useRepairMovementLocked()` currently returns `false`, so the movement-lock rule and indicator are present but disabled on `develop`.
- Production editor persistence does not exist. Save endpoints in `vite.config.ts` are local Vite dev-server helpers.
- The player uses octree collision while gameplay objects use Rapier. Keep that boundary deliberate unless the whole player controller is migrated.
## License
See `LICENSE`.