docs: add some docs

docs/technical/architecture.md

@@ -30,8 +30,32 @@ This document describes the code that exists today in the repository.
 
 ## Audio
 
-- `src/managers/AudioManager.ts` currently provides pooled one-shot sound playback and looped music playback.
-- Trigger interactions may play audio directly through `AudioManager`.
+- `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`.
 
 ## Debug System
 
@@ -59,6 +83,7 @@ This document describes the code that exists today in the repository.
 
 - `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/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.
@@ -80,6 +105,7 @@ This document describes the code that exists today in the repository.
 - 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`.
-- Missions, zones, cinematics, and dialogue systems are not implemented.
+- Missions, zones, and cinematics are not implemented.
+- Dialogue playback exists, but queueing, branching, and gameplay-triggered dialogue 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.

docs/technical/editor.md

@@ -23,6 +23,7 @@ src/
 ├── components/
 │   └── editor/
 │       ├── EditorControls.tsx
+│       ├── EditorSrtPanel.tsx
 │       └── scene/
 │           ├── EditorMap.tsx
 │           └── EditorScene.tsx
@@ -37,10 +38,14 @@ src/
 │   └── editor/
 │       └── editor.ts
 └── utils/
+    ├── dialogues/
+    │   └── loadDialogueManifest.ts
     ├── editor/
     │   └── loadEditorScene.ts
-    └── map/
-        └── loadMapSceneData.ts
+    ├── map/
+    │   └── loadMapSceneData.ts
+    └── subtitles/
+        └── parseSrt.ts
 ```
 
 ## Responsibilities
@@ -57,6 +62,8 @@ src/
 
 `src/components/editor/EditorControls.tsx` renders the HTML control panel outside the canvas.
 
+`src/components/editor/EditorSrtPanel.tsx` renders the dialogue subtitle editor inside the control panel. It loads the dialogue manifest, loads one SRT file per voice/language, validates cue structure, previews dialogue audio, and can save SRT files through a dev-server endpoint.
+
 `src/controls/editor/FlyController.tsx` provides editor movement controls for player-style navigation.
 
 `src/utils/map/loadMapSceneData.ts` is shared by the game map and editor. It loads `/map.json` and resolves available `public/models/{name}/model.glb` files first, then falls back to `public/models/{name}/model.gltf`.
@@ -134,6 +141,39 @@ The editor supports two output paths:
 
 The dev-only `/api/save-map` endpoint is implemented by the Vite plugin in `vite.config.ts`. It writes to `public/map.json` and enforces a maximum payload size.
 
+## Dialogue SRT Editing
+
+Dialogue subtitle editing is part of the `/editor` side panel.
+
+Runtime dialogue files are grouped under `public/sounds/dialogue/`:
+
+```txt
+public/
+└── sounds/
+    └── dialogue/
+        ├── dialogues.json
+        └── subtitles/
+            ├── fr/
+            │   ├── narrateur.srt
+            │   ├── fermier.srt
+            │   └── electricienne.srt
+            └── en/
+                └── ...
+```
+
+The current model is one SRT file per voice and language. A dialogue entry references the cue it needs through `subtitleCueIndex`; it does not own a dedicated SRT file.
+
+`EditorSrtPanel` uses:
+
+- `loadDialogueManifest()` to read `/sounds/dialogue/dialogues.json`
+- `parseSrt()` to validate local textarea content and find active cues during audio preview
+- `/api/save-srt` to write edited SRT files during local development
+- `/api/validate-dialogues` to validate the manifest, linked audio, French SRT files, and referenced cue indexes
+
+SRT timecodes are relative to the dialogue audio file being previewed, not to the global game timeline.
+
+Missing English SRT files are warnings because runtime loading falls back to French subtitles when the selected language is not available.
+
 ## Styling
 
 Editor styles are in `src/index.css` under the `/* Editor page */` section. Classes are prefixed with `editor-` to avoid collisions with the game UI.
@@ -144,3 +184,5 @@ Editor styles are in `src/index.css` under the `/* Editor page */` section. Clas
 - Large `map.json` files are not virtualized, culled, or LOD-managed.
 - There is no snap-to-grid, duplication, material editing, or object creation workflow.
 - Save to Server is a Vite dev-server helper, not a production backend API.
+- SRT Save is also a Vite dev-server helper, not a production backend API.
+- The editor validates dialogue assets but does not yet create, delete, or reorder dialogue manifest entries.

docs/user/editor.md

@@ -74,6 +74,32 @@ This is useful for checking numeric transform values before saving or exporting.
 
 The button is hidden in production builds because production persistence is not implemented.
 
+## Editing Dialogue Subtitles
+
+The side panel also includes an SRT editor for dialogue subtitles.
+
+1. Choose a voice: `narrateur`, `fermier`, or `electricienne`.
+2. Choose a language: `FR` or `EN`.
+3. Edit the SRT text directly in the textarea.
+4. Use the audio preview to check the selected dialogue.
+5. Use `Set start`, `Set end`, `-100ms`, and `+100ms` to adjust the selected cue timing against the audio.
+6. Use `Save SRT` during local development, or `Export SRT` to download the file manually.
+
+Each SRT file belongs to one voice, not one dialogue. Cue indexes must match the `subtitleCueIndex` values referenced by the dialogue manifest.
+
+## Validating Dialogue Assets
+
+Use `Validate` in the SRT panel to check the dialogue manifest and linked assets.
+
+The validation checks:
+
+- `public/sounds/dialogue/dialogues.json`
+- referenced dialogue audio files
+- French SRT files
+- subtitle cue indexes referenced by the manifest
+
+Missing English SRT files are warnings because the runtime falls back to French subtitles.
+
 ## Current Limitations
 
 - The editor only modifies existing nodes.
@@ -81,3 +107,4 @@ The button is hidden in production builds because production persistence is not
 - It does not edit model files or textures.
 - It does not provide production persistence.
 - Fallback cubes indicate missing models; they are editor placeholders, not exported assets.
+- SRT saving is a local Vite dev-server helper, not a production backend feature.

docs/user/features.md

@@ -27,8 +27,28 @@ This document lists features that are implemented in the current codebase.
 
 ## Audio
 
-- One-shot sound playback for trigger interactions
-- Simple per-sound pooling through `AudioManager`
+- Category-based volumes for music, SFX, and dialogue
+- Looped background music playback through `AudioManager`
+- One-shot sound playback for SFX and dialogue, with simple per-sound pooling
+- Optional stereo pan for one-shot sounds
+
+## Dialogue And Subtitles
+
+- Dialogue manifest in `public/sounds/dialogue/dialogues.json`
+- Dialogue audio loaded from `public/sounds/dialogue/`
+- One SRT subtitle file per voice and language
+- French subtitle fallback when the selected language file is missing
+- Runtime subtitle overlay with speaker-specific colors
+- Timecoded dialogue trigger support for dialogue entries that define `timecode`
+
+## Game Options Menu
+
+- `Esc` opens and closes the in-game options menu
+- Music, SFX, and dialogue volume sliders
+- Subtitle visibility toggle
+- Subtitle language choice between French and English
+- Repair runtime choice between local JavaScript and Python server mode
+- Quit action that clears browser-accessible cookies and returns to `/`
 
 ## Debug Tooling
 
@@ -52,13 +72,17 @@ This document lists features that are implemented in the current codebase.
 - Player-style navigation mode with `WASD`, `ZQSD`, arrow keys, `Space`, and `Shift`
 - JSON export for downloading the edited map
 - Dev-server save endpoint for writing changes back to `public/map.json`
+- SRT editor for dialogue subtitles
+- Audio preview and timing helpers for SRT cues
+- Dev-server save endpoint for SRT files
+- Dialogue manifest validation from the editor UI
 
 ## Not Implemented Yet
 
 - mission system
 - zone system
 - cinematic system
-- dialogue system
+- dialogue queueing and gameplay-triggered dialogue branches
 - loading flow
 - minimap and mission HUD
 - full production separation between gameplay and debug scenes

src/data/docs/docsTranslations.ts

@@ -113,8 +113,32 @@ Ce document décrit le code réellement présent aujourd'hui dans le dépôt.
 
 ## Audio
 
-- \`src/managers/AudioManager.ts\` fournit actuellement une lecture de sons one-shot avec pool.
-- Les interactions trigger peuvent lancer directement un son via \`AudioManager\`.
+- \`src/managers/AudioManager.ts\` fournit la lecture de sons one-shot avec pool, la musique en boucle, les volumes par catégorie et un pan stéréo optionnel pour les sons one-shot.
+- Les catégories audio supportées sont \`music\`, \`sfx\` et \`dialogue\`.
+- Les interactions trigger peuvent lancer directement des SFX via \`AudioManager\`.
+
+## Menu options
+
+- \`src/managers/stores/useSettingsStore.ts\` stocke les réglages de volume musique, volume SFX, volume dialogue, sous-titres, langue des sous-titres, runtime de réparation et visibilité du menu.
+- \`src/components/ui/GameSettingsMenu.tsx\` rend le menu options en jeu.
+- \`src/components/ui/GameUI.tsx\` monte le menu comme overlay HTML hors canvas.
+- \`Esc\` ouvre et ferme le menu, et \`src/world/player/PlayerController.tsx\` ignore les inputs joueur pendant son ouverture.
+- Les changements de volume sont transmis à \`AudioManager\` par catégorie.
+
+## Dialogues et sous-titres
+
+- \`public/sounds/dialogue/dialogues.json\` est le manifeste runtime des dialogues.
+- Les fichiers audio de dialogue vivent dans \`public/sounds/dialogue/\`.
+- Les fichiers de sous-titres vivent dans \`public/sounds/dialogue/subtitles/{fr|en}/\`.
+- Le modèle actuel utilise un fichier SRT par voix et par langue.
+- \`src/types/dialogues/dialogues.ts\` contient les types du manifeste.
+- \`src/utils/dialogues/dialogueManifestValidation.ts\` valide la forme du manifeste au runtime.
+- \`src/utils/dialogues/loadDialogueManifest.ts\` charge le manifeste et les cues SRT, avec fallback français si la langue sélectionnée manque.
+- \`src/utils/subtitles/parseSrt.ts\` parse les blocs et timecodes SRT.
+- \`src/utils/dialogues/playDialogue.ts\` joue l'audio de dialogue et synchronise le sous-titre actif avec le temps de l'élément audio.
+- \`src/managers/stores/useSubtitleStore.ts\` stocke la cue de sous-titre affichée.
+- \`src/components/ui/Subtitles.tsx\` rend l'overlay de sous-titres.
+- \`src/world/GameDialogues.tsx\` déclenche actuellement les dialogues qui définissent un \`timecode\`.
 
 ## Système debug
 
@@ -135,7 +159,8 @@ Ce document décrit le code réellement présent aujourd'hui dans le dépôt.
 - Le dépôt est encore un prototype, pas le runtime complet du jeu.
 - \`src/world/debug/TestMap.tsx\` fait encore partie de la composition active.
 - Il n'existe pas encore d'orchestrateur gameplay central comme \`GameManager\`.
-- Les systèmes de missions, zones, cinématiques et dialogues ne sont pas implémentés.
+- Les systèmes de missions, zones et cinématiques ne sont pas implémentés.
+- La lecture de dialogues existe, mais la file d'attente, les branches et l'orchestration par gameplay restent limitées.
 - Le joueur utilise une collision octree et des règles simples, pas une pile physique gameplay complète.
 `;
 
@@ -400,8 +425,28 @@ Ce document liste les fonctionnalités présentes dans le code actuel.
 
 ## Audio
 
-- Lecture de sons one-shot pour les interactions trigger
-- Pool simple par son via \`AudioManager\`
+- Volumes par catégorie pour la musique, les SFX et les dialogues
+- Lecture de musique en boucle via \`AudioManager\`
+- Lecture de sons one-shot pour les SFX et les dialogues, avec pool simple par son
+- Pan stéréo optionnel pour les sons one-shot
+
+## Dialogues et sous-titres
+
+- Manifeste de dialogues dans \`public/sounds/dialogue/dialogues.json\`
+- Audios de dialogue chargés depuis \`public/sounds/dialogue/\`
+- Un fichier SRT par voix et par langue
+- Fallback vers les sous-titres français quand le fichier de langue sélectionné manque
+- Overlay de sous-titres runtime avec couleurs par speaker
+- Déclenchement timecodé pour les dialogues qui définissent \`timecode\`
+
+## Menu options
+
+- \`Esc\` ouvre et ferme le menu options en jeu
+- Sliders de volume musique, SFX et dialogue
+- Toggle d'affichage des sous-titres
+- Choix de langue des sous-titres entre français et anglais
+- Choix du runtime de réparation entre JavaScript local et serveur Python
+- Action quitter qui nettoie les cookies accessibles au navigateur et retourne vers \`/\`
 
 ## Outils debug
 
@@ -412,12 +457,27 @@ Ce document liste les fonctionnalités présentes dans le code actuel.
 - Caméra libre debug
 - Overlay \`r3f-perf\`
 
+## Éditeur de carte
+
+- Route \`/editor\` pour inspecter et éditer \`public/map.json\`
+- Chargement automatique de \`public/map.json\` quand il existe
+- Rendu des modèles disponibles depuis \`public/models/{name}/model.glb\` ou \`model.gltf\`
+- Cubes de fallback pour les nodes dont le modèle manque
+- Sélection d'objet au clic
+- Modes de transformation translation, rotation et scale
+- Export JSON pour télécharger la carte modifiée
+- Endpoint de sauvegarde dev-server pour écrire \`public/map.json\`
+- Éditeur SRT pour les sous-titres de dialogue
+- Preview audio et outils de timing pour les cues SRT
+- Endpoint de sauvegarde dev-server pour les fichiers SRT
+- Validation du manifeste de dialogues depuis l'UI de l'éditeur
+
 ## Pas encore implémenté
 
 - système de missions
 - système de zones
 - système de cinématiques
-- système de dialogues
+- file d'attente de dialogues et branches déclenchées par gameplay
 - flow de chargement
 - minimap et HUD de mission
 - séparation complète production / debug pour les scènes gameplay
@@ -476,6 +536,32 @@ Les modèles sont chargés depuis "/public/models". Si un modèle manque, l'édi
 
 Cette action est masquée dans les builds de production car il n'existe pas encore d'API de persistance production.
 
+## Éditer les sous-titres de dialogue
+
+Le panneau latéral contient aussi un éditeur SRT pour les sous-titres de dialogue.
+
+1. Choisir une voix : \`narrateur\`, \`fermier\` ou \`electricienne\`.
+2. Choisir une langue : \`FR\` ou \`EN\`.
+3. Modifier le texte SRT directement dans la textarea.
+4. Utiliser la preview audio pour vérifier le dialogue sélectionné.
+5. Utiliser \`Set start\`, \`Set end\`, \`-100ms\` et \`+100ms\` pour ajuster le timing de la cue sélectionnée avec l'audio.
+6. Utiliser \`Save SRT\` en développement local, ou \`Export SRT\` pour télécharger le fichier manuellement.
+
+Chaque fichier SRT appartient à une voix, pas à un dialogue. Les indexes de cue doivent correspondre aux valeurs \`subtitleCueIndex\` référencées par le manifeste de dialogues.
+
+## Valider les assets de dialogue
+
+Utilise \`Validate\` dans le panneau SRT pour vérifier le manifeste et les assets liés.
+
+La validation vérifie :
+
+- \`public/sounds/dialogue/dialogues.json\`
+- les fichiers audio de dialogue référencés
+- les fichiers SRT français
+- les indexes de cue référencés par le manifeste
+
+Les fichiers SRT anglais manquants sont des warnings parce que le runtime retombe sur les sous-titres français.
+
 ## Inspecteur JSON
 
 Le panneau latéral affiche le JSON brut de la carte :
@@ -491,4 +577,5 @@ Utilise-le pour vérifier les valeurs numériques exactes avant export ou sauveg
 - Il n'y a pas encore d'interface pour créer ou supprimer des objets.
 - La sauvegarde production n'est pas implémentée.
 - Les modèles manquants s'affichent comme cubes de fallback au lieu de bloquer tout l'éditeur.
+- La sauvegarde SRT est un helper local du serveur Vite, pas une API backend de production.
 `;