update: doc dialogue and cinematic tools
This commit is contained in:
Tom Boullay
@@ -56,6 +56,18 @@ This document describes the code that exists today in the repository.
|
||||
- `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`.
|
||||
- Dialogue playback is queued so multiple dialogue requests do not overlap.
|
||||
|
||||
## Cinematics
|
||||
|
||||
- `public/cinematics.json` is the runtime cinematic manifest.
|
||||
- `src/types/cinematics/cinematics.ts` contains cinematic manifest types.
|
||||
- `src/utils/cinematics/cinematicManifestValidation.ts` validates manifest shape at runtime.
|
||||
- `src/utils/cinematics/loadCinematicManifest.ts` loads `/cinematics.json`.
|
||||
- `src/world/GameCinematics.tsx` triggers cinematics that define a global `timecode`.
|
||||
- Cinematics use GSAP timelines to animate the active camera position and look target.
|
||||
- `dialogueCues` on a cinematic trigger dialogue IDs at times relative to the cinematic start.
|
||||
- `src/managers/stores/useGameStore.ts` exposes `isCinematicPlaying`, used to lock player input during cinematics.
|
||||
|
||||
## Debug System
|
||||
|
||||
@@ -83,6 +95,8 @@ 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/EditorDialogueManifestPanel.tsx` edits `public/sounds/dialogue/dialogues.json`.
|
||||
- `src/components/editor/EditorCinematicManifestPanel.tsx` edits `public/cinematics.json`.
|
||||
- `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.
|
||||
@@ -105,7 +119,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, and cinematics are not implemented.
|
||||
- Dialogue playback exists, but queueing, branching, and gameplay-triggered dialogue orchestration are still limited.
|
||||
- Missions and zones are not implemented.
|
||||
- Dialogue branching and gameplay-triggered 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,8 @@ src/
|
||||
├── components/
|
||||
│ └── editor/
|
||||
│ ├── EditorControls.tsx
|
||||
│ ├── EditorCinematicManifestPanel.tsx
|
||||
│ ├── EditorDialogueManifestPanel.tsx
|
||||
│ ├── EditorSrtPanel.tsx
|
||||
│ └── scene/
|
||||
│ ├── EditorMap.tsx
|
||||
@@ -62,6 +64,10 @@ src/
|
||||
|
||||
`src/components/editor/EditorControls.tsx` renders the HTML control panel outside the canvas.
|
||||
|
||||
`src/components/editor/EditorDialogueManifestPanel.tsx` renders the dialogue manifest editor. It loads `dialogues.json`, edits dialogue entries, previews selected dialogue playback, creates missing French SRT cues, and saves the manifest through a dev-server endpoint.
|
||||
|
||||
`src/components/editor/EditorCinematicManifestPanel.tsx` renders the cinematic manifest editor. It loads `cinematics.json`, edits camera keyframes and dialogue cues, previews selected cinematics in the editor canvas, and saves the manifest through a dev-server endpoint.
|
||||
|
||||
`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.
|
||||
@@ -174,6 +180,45 @@ SRT timecodes are relative to the dialogue audio file being previewed, not to th
|
||||
|
||||
Missing English SRT files are warnings because runtime loading falls back to French subtitles when the selected language is not available.
|
||||
|
||||
## Dialogue Manifest Editing
|
||||
|
||||
`EditorDialogueManifestPanel` edits `public/sounds/dialogue/dialogues.json` in memory and persists it through `/api/save-dialogues`.
|
||||
|
||||
The panel supports:
|
||||
|
||||
- adding a dialogue entry
|
||||
- deleting a dialogue entry
|
||||
- editing `id`, `voice`, `audio`, `subtitleCueIndex`, and optional `timecode`
|
||||
- previewing the selected dialogue through `playDialogueById()`
|
||||
- creating a missing French SRT cue through `/api/save-srt`
|
||||
|
||||
When a dialogue is added, the editor computes the next `subtitleCueIndex` for the selected voice from the manifest. The generated SRT cue is a valid placeholder block and should be edited later in the SRT panel.
|
||||
|
||||
`/api/save-dialogues` is implemented in `vite.config.ts`. It validates manifest shape before writing to `public/sounds/dialogue/dialogues.json`.
|
||||
|
||||
## Cinematic Manifest Editing
|
||||
|
||||
`EditorCinematicManifestPanel` edits `public/cinematics.json` in memory and persists it through `/api/save-cinematics`.
|
||||
|
||||
The manifest shape is:
|
||||
|
||||
```ts
|
||||
interface CinematicDefinition {
|
||||
id: string;
|
||||
timecode?: number;
|
||||
cameraKeyframes: CinematicCameraKeyframe[];
|
||||
dialogueCues?: CinematicDialogueCue[];
|
||||
}
|
||||
```
|
||||
|
||||
`cameraKeyframes` are relative to the cinematic start. At least two keyframes are required and keyframe times must increase.
|
||||
|
||||
`dialogueCues` are also relative to the cinematic start and reference dialogue IDs from `dialogues.json`. They are used by `GameCinematics` to synchronize dialogue playback with camera timelines. A dialogue synchronized this way should not also define a global `timecode` in `dialogues.json`.
|
||||
|
||||
The editor preview sends the selected `CinematicDefinition` to `EditorScene`, where GSAP animates the current editor camera. Orbit and fly controls are disabled during preview.
|
||||
|
||||
`/api/save-cinematics` is implemented in `vite.config.ts`. It validates manifest shape before writing to `public/cinematics.json`.
|
||||
|
||||
## 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.
|
||||
@@ -185,4 +230,5 @@ Editor styles are in `src/index.css` under the `/* Editor page */` section. Clas
|
||||
- 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.
|
||||
- Dialogue and cinematic manifest saves are Vite dev-server helpers, not production backend APIs.
|
||||
- Dialogue creation still uses placeholder audio paths until real MP3 files are added.
|
||||
|
||||
+57
-1
@@ -76,7 +76,28 @@ The button is hidden in production builds because production persistence is not
|
||||
|
||||
## Editing Dialogue Subtitles
|
||||
|
||||
The side panel also includes an SRT editor for dialogue subtitles.
|
||||
The side panel also includes dialogue tools for the dialogue manifest and SRT subtitles.
|
||||
|
||||
### Dialogue Manifest
|
||||
|
||||
Use the `Dialogues` panel to edit `public/sounds/dialogue/dialogues.json` without opening the JSON file manually.
|
||||
|
||||
Available actions:
|
||||
|
||||
- `Reload` reloads the manifest from disk.
|
||||
- `Add` creates a local dialogue entry for the current voice and assigns the next available SRT cue index.
|
||||
- `Save` writes the manifest through the local Vite dev server.
|
||||
- `Preview dialogue` plays the selected dialogue and shows subtitles in the editor overlay.
|
||||
- `Create FR SRT cue` creates the matching French SRT cue if it is missing.
|
||||
- `Delete dialogue` removes the selected entry locally.
|
||||
|
||||
After using `Add`, save the manifest to keep the new dialogue entry. The generated SRT cue is written immediately to the French SRT file, but the dialogue manifest is still only local until `Save` is clicked.
|
||||
|
||||
New dialogue audio paths start as placeholders such as `/sounds/dialogue/new_dialogue_24.mp3`. Replace them with real MP3 paths before validating the final asset set.
|
||||
|
||||
### SRT Editor
|
||||
|
||||
Use the `SRT` panel to edit one subtitle file at a time.
|
||||
|
||||
1. Choose a voice: `narrateur`, `fermier`, or `electricienne`.
|
||||
2. Choose a language: `FR` or `EN`.
|
||||
@@ -100,6 +121,40 @@ The validation checks:
|
||||
|
||||
Missing English SRT files are warnings because the runtime falls back to French subtitles.
|
||||
|
||||
## Editing Cinematics
|
||||
|
||||
Use the `Cinematics` panel to edit `public/cinematics.json`.
|
||||
|
||||
Each cinematic contains:
|
||||
|
||||
- an `id`
|
||||
- an optional global `timecode`
|
||||
- two or more camera keyframes
|
||||
- optional dialogue cues synchronized to the cinematic timeline
|
||||
|
||||
Camera keyframes define:
|
||||
|
||||
- `time`: seconds relative to the cinematic start
|
||||
- `position`: camera position `[x, y, z]`
|
||||
- `target`: point the camera looks at `[x, y, z]`
|
||||
|
||||
Dialogue cues define:
|
||||
|
||||
- `time`: seconds relative to the cinematic start
|
||||
- `dialogueId`: an entry from `public/sounds/dialogue/dialogues.json`
|
||||
|
||||
Available actions:
|
||||
|
||||
- `Reload` reloads the cinematic manifest from disk.
|
||||
- `Add` creates a new local cinematic with two camera keyframes.
|
||||
- `Save` writes `public/cinematics.json` through the local Vite dev server.
|
||||
- `Preview cinematic` plays the selected camera animation in the editor canvas.
|
||||
- `Add keyframe` and `Remove` edit the camera path.
|
||||
- `Add dialogue` and `Remove` edit dialogue cues linked to the cinematic.
|
||||
- `Delete cinematic` removes the selected cinematic locally.
|
||||
|
||||
Cinematic dialogue cues are the preferred way to synchronize a dialogue with a cinematic. Avoid also giving the same dialogue a global `timecode`, or it can be triggered twice.
|
||||
|
||||
## Current Limitations
|
||||
|
||||
- The editor only modifies existing nodes.
|
||||
@@ -108,3 +163,4 @@ Missing English SRT files are warnings because the runtime falls back to French
|
||||
- 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.
|
||||
- Dialogue and cinematic saves are local Vite dev-server helpers, not production backend features.
|
||||
|
||||
+12
-2
@@ -40,6 +40,15 @@ This document lists features that are implemented in the current codebase.
|
||||
- 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`
|
||||
- Dialogue queueing to avoid overlapping dialogue playback
|
||||
|
||||
## Cinematics
|
||||
|
||||
- Cinematic manifest in `public/cinematics.json`
|
||||
- Timecoded cinematic trigger support
|
||||
- GSAP camera keyframe playback
|
||||
- Optional dialogue cues synchronized to cinematic timelines
|
||||
- Player input lock while a cinematic is active
|
||||
|
||||
## Game Options Menu
|
||||
|
||||
@@ -75,14 +84,15 @@ This document lists features that are implemented in the current codebase.
|
||||
- SRT editor for dialogue subtitles
|
||||
- Audio preview and timing helpers for SRT cues
|
||||
- Dev-server save endpoint for SRT files
|
||||
- Dialogue manifest editor with preview and assisted French SRT cue creation
|
||||
- Cinematic manifest editor with camera keyframes, dialogue cues, and canvas preview
|
||||
- Dialogue manifest validation from the editor UI
|
||||
|
||||
## Not Implemented Yet
|
||||
|
||||
- mission system
|
||||
- zone system
|
||||
- cinematic system
|
||||
- dialogue queueing and gameplay-triggered dialogue branches
|
||||
- gameplay-triggered dialogue branches beyond current prototype triggers
|
||||
- loading flow
|
||||
- minimap and mission HUD
|
||||
- full production separation between gameplay and debug scenes
|
||||
|
||||
Reference in New Issue
Block a user