docs: add some docs
This commit is contained in:
Tom Boullay
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
+27
-3
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user