diff --git a/docs/technical/architecture.md b/docs/technical/architecture.md index f8fdbda..ca0092c 100644 --- a/docs/technical/architecture.md +++ b/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. diff --git a/docs/technical/editor.md b/docs/technical/editor.md index 6a0a4c0..72576a9 100644 --- a/docs/technical/editor.md +++ b/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. diff --git a/docs/user/editor.md b/docs/user/editor.md index d98ba2a..d6bf288 100644 --- a/docs/user/editor.md +++ b/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. diff --git a/docs/user/features.md b/docs/user/features.md index 1a3a210..46462ee 100644 --- a/docs/user/features.md +++ b/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 diff --git a/src/data/docs/docsTranslations.ts b/src/data/docs/docsTranslations.ts index 166cfc0..3de7690 100644 --- a/src/data/docs/docsTranslations.ts +++ b/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. `;