Merge branch 'develop' into feat/intro

docs/technical/game-states.md

@@ -0,0 +1,226 @@
+# Game States & Substates
+
+Documentation technique pour le testing et debugging du flow de jeu.
+
+## Vue d'ensemble
+
+```
+intro ──► bike ──► pylone ──► ferme ──► outro
+```
+
+---
+
+## Main States
+
+| State    | Description                                                        |
+| -------- | ------------------------------------------------------------------ |
+| `intro`  | Séquence d'introduction (cinématique, naming, premier déplacement) |
+| `bike`   | Mission de réparation du vélo                                      |
+| `pylone` | Quête du pylone (alert → searching → helped → manipulation)        |
+| `ferme`  | Mission de réparation de la ferme                                  |
+| `outro`  | Fin du jeu                                                         |
+
+---
+
+## Intro (GameStep)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ intro.currentStep                                          │
+└─────────────────────────────────────────────────────────────┘
+
+intro ──► sequence_video ──► naming ──► start-move ──► bike
+```
+
+### Étapes
+
+| Step             | Trigger  | Action                                         | Passage vers                                     |
+| ---------------- | -------- | ---------------------------------------------- | ------------------------------------------------ |
+| `intro`          | Initial  | État initial                                   | Auto → `sequence_video` quand `sceneReady: true` |
+| `sequence_video` | GameFlow | Déclenche la cinématique dans `GameCinematics` | Fin cinématique → `naming`                       |
+| `naming`         | IntroUI  | Affiche l'input pour le prénom                 | Submit → `start-move`                            |
+| `start-move`     | GameFlow | Active le mouvement (`canMove: true`)          | Via zone "fabrikExit" → `bike`                   |
+
+### Transition vers bike
+
+- **Trigger**: Zone `fabrikExit` dans `zones.ts`
+- **Action**: `advanceGameState()` dans `ZoneDetection.tsx`
+- **Résultat**: `mainState: "bike"`, `intro.hasCompleted: true`
+
+---
+
+## Bike (MissionStep)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ bike.currentStep (MissionStep)                             │
+└─────────────────────────────────────────────────────────────┘
+
+locked ──► waiting ──► inspected ──► fragmented ──► scanning ──► repairing ──► reassembling ──► done
+```
+
+### Transition vers pylone
+
+- **Trigger**: `bike.currentStep: "done"`
+- **Action**: `completeBikeState()` dans useGameStore
+- **Résultat**: `mainState: "pylone"`, `pylone.currentStep: "locked"`
+
+---
+
+## Pylone (PyloneStep)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ pylone.currentStep (PyloneStep)                            │
+└─────────────────────────────────────────────────────────────┘
+
+locked (bypass) ──► alert ──► searching ──► helped ──► manipulation ──► outro
+```
+
+### Étapes
+
+| Step           | Trigger                            | Action                             | Passage vers                                              |
+| -------------- | ---------------------------------- | ---------------------------------- | --------------------------------------------------------- |
+| `locked`       | Initial (après bike)               | État initial                       | **Bypass automatique** → `alert` via `advanceGameState()` |
+| `alert`        | `advanceGameState()`               | Affiche l'alerte (à implémenter)   | Via `advanceGameState()`                                  |
+| `searching`    | `advanceGameState()`               | Déclenché par zone "searchingZone" | Via `advanceGameState()`                                  |
+| `helped`       | Interaction avec `NPCHelper`       | Dialogue avec le villageois        | Via interaction 3D                                        |
+| `manipulation` | Interaction avec `PyloneDestroyed` | Interaction avec l'objet central   | Via `advanceGameState()` → `outro`                        |
+
+### Bypass automatique
+
+```typescript
+// useGameStore.ts - advancePyloneStep()
+if (state.pylone.currentStep === "locked") {
+  return { pylone: { ...state.pylone, currentStep: "alert" } };
+}
+```
+
+### Transition vers outro
+
+- **Trigger**: `pylone.currentStep: "manipulation"` + `advanceGameState()`
+- **Action**: `advancePyloneStep()` détecte fin de la séquence
+- **Résultat**: `mainState: "outro"`
+
+---
+
+## Ferme (MissionStep)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ferme.currentStep (MissionStep)                             │
+└─────────────────────────────────────────────────────────────┘
+
+locked ──► waiting ──► inspected ──► fragmented ──► scanning ──► repairing ──► reassembling ──► done
+```
+
+### Transition vers outro
+
+- **Trigger**: `ferme.currentStep: "done"`
+- **Action**: `completeFermeState()` dans useGameStore
+- **Résultat**: `mainState: "outro"`, `ferme.irrigationFixed: true`
+
+---
+
+## Outro
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ outro.hasStarted                                           │
+└─────────────────────────────────────────────────────────────┘
+
+waiting ──► started
+```
+
+---
+
+## Debug Panel
+
+Le debug panel permet de tester toutes les transitions :
+
+### Utilisation
+
+1. Ouvrir le jeu en mode debug (`Debug: true` dans `Debug.ts`)
+2. Le panneau "Game State" apparaît en bas à gauche
+3. **Main state**: Sélectionner le state principal
+4. **Sub state**: Sélectionner le sub-state
+5. **Previous/Next step**: Avancer ou reculer d'un step
+6. **Reset**: Remettre à l'état initial
+
+### Raccourcis clavier
+
+| Action  | Clavier            |
+| ------- | ------------------ |
+| Avancer | Debug panel button |
+| Reculer | Debug panel button |
+| Reset   | Debug panel button |
+
+---
+
+## Comment tester chaque section
+
+### Tester l'intro
+
+1. Vérifier que `sceneReady: false` au démarrage
+2. Attendre que le loader termine (`sceneReady: true`)
+3. Vérifier `intro.currentStep: "intro"` → auto vers `sequence_video`
+4. Si cinématique fonctionne : `sequence_video` → `naming`
+5. Entrer un prénom : `naming` → `start-move`
+6. Vérifier `canMove: true` après `start-move`
+7. Entrer dans la zone `fabrikExit` → `mainState: "bike"`
+
+### Tester bike
+
+1. Via debug panel, avancer jusqu'à `done`
+2. Vérifier `mainState: "pylone"`
+
+### Tester pylone
+
+1. Via debug panel, avancer (bypass `locked` → `alert`)
+2. Vérifier `pylone.currentStep: "alert"`
+3. Avancer : `alert` → `searching` → `helped` → `manipulation`
+4. Après `manipulation`, vérifier `mainState: "outro"`
+
+### Tester ferme
+
+1. Via debug panel, avancer dans bike jusqu'à `done`
+2. Vérifier `mainState: "pylone"` → `ferme` (après pylone)
+3. Avancer jusqu'à `done`
+4. Vérifier `mainState: "outro"`
+
+---
+
+## Fichiers clés
+
+| Fichier                                           | Rôle                                  |
+| ------------------------------------------------- | ------------------------------------- |
+| `src/managers/stores/useGameStore.ts`             | Store Zustand avec toutes les actions |
+| `src/types/game.ts`                               | Définition de `GameStep`              |
+| `src/types/gameplay/pylone.ts`                    | Définition de `PyloneStep`            |
+| `src/types/gameplay/repairMission.ts`             | Définition de `MissionStep`           |
+| `src/components/game/GameFlow.tsx`                | Logique de transition de l'intro      |
+| `src/components/zone/ZoneDetection.tsx`           | Déclenchement des zones               |
+| `src/components/ui/debug/GameStateDebugPanel.tsx` | Outil de debug                        |
+
+---
+
+## État initial
+
+```typescript
+{
+  mainState: "intro",
+  isCinematicPlaying: false,
+  sceneReady: false,
+  missionFlow: {
+    activityCity: true,
+    canMove: false,
+    dialogMessage: null,
+    playerName: "",
+  },
+  intro: { currentStep: "intro", dialogueAudio: null, hasCompleted: false, isBikeUnlocked: false },
+  bike: { currentStep: "locked", dialogueAudio: null, isRepaired: false },
+  pylone: { currentStep: "locked", dialogueAudio: null, isPowered: false },
+  ferme: { currentStep: "locked", dialogueAudio: null, irrigationFixed: false },
+  outro: { dialogueAudio: null, hasStarted: false },
+}
+```

public/cinematics.json

@@ -1,6 +1,21 @@
 {
   "version": 1,
   "cinematics": [
+    {
+      "id": "intro_sequence",
+      "trigger": "intro_sequence",
+      "cameraKeyframes": [
+        { "time": 0, "position": [8, 5, 12], "target": [0, 2, 0] },
+        { "time": 8, "position": [12, 4, -6], "target": [10, 1.4, -8] },
+        { "time": 16, "position": [5, 6, -15], "target": [0, 3, -20] },
+        { "time": 24, "position": [0, 8, -30], "target": [0, 0, -40] }
+      ],
+      "dialogueCues": [
+        { "time": 0, "dialogueId": "intro_welcome" },
+        { "time": 8, "dialogueId": "intro_explanation" },
+        { "time": 16, "dialogueId": "intro_mission" }
+      ]
+    },
     {
       "id": "intro_overview",
       "timecode": 0,