Tom Boullay
cfb761e66c
🔍 Lint / 🪄 Check lint (pull_request) Has been cancelled
🔍 Lint / 🎨 Check format (pull_request) Has been cancelled
🔍 Lint / 🔎 Typecheck (pull_request) Has been cancelled
🔍 Lint / 🏗 Build (pull_request) Has been cancelled
📊 Quality / 🔒 Security Audit (pull_request) Has been cancelled
📊 Quality / 📋 Dependency Freshness (pull_request) Has been cancelled
📊 Quality / 📦 Bundle Size (pull_request) Has been cancelled
245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
# Editor User Guide
|
|
|
|
The map editor is available at `/editor`. It is a browser-based tool for editing the runtime map, cinematic manifest, dialogue manifest, and SRT subtitle files without manually jumping between JSON and subtitle files.
|
|
|
|
## Purpose
|
|
|
|
Use the editor when you need to:
|
|
|
|
- move, rotate, or scale objects from `public/map.json`
|
|
- inspect the raw JSON generated by the editor
|
|
- preview and edit cinematics from `public/cinematics.json`
|
|
- create, preview, and validate dialogue entries from `public/sounds/dialogue/dialogues.json`
|
|
- edit FR/EN SRT subtitle files per voice
|
|
|
|
The map editor reads the same map data as the runtime scene:
|
|
|
|
- `public/map.json` contains the object list.
|
|
- `public/models/{name}/model.glb` contains the matching 3D model for each object name. `model.gltf` is still supported as a fallback during migration.
|
|
- Missing models are displayed as gray fallback cubes, so incomplete maps remain editable.
|
|
|
|
## Map Node Format
|
|
|
|
Each entry in `public/map.json` represents one object:
|
|
|
|
| Field | Description |
|
|
| ---------- | ------------------------------------------------- |
|
|
| `name` | Model folder name in `public/models/{name}` |
|
|
| `type` | Object category |
|
|
| `position` | Object position as `[x, y, z]` |
|
|
| `rotation` | Object rotation as `[x, y, z]`, expressed radians |
|
|
| `scale` | Object scale as `[x, y, z]` |
|
|
|
|
## Panel Layout
|
|
|
|
The right panel is split into dropdown groups:
|
|
|
|
- `Editor`: map transform tools, shortcuts, selection, view mode, JSON preview, and file actions.
|
|
- `Cinematics`: editor for `public/cinematics.json`.
|
|
- `Dialogues`: editor for `public/sounds/dialogue/dialogues.json`.
|
|
- `SRT`: editor for subtitle files in `public/sounds/dialogue/subtitles/`.
|
|
|
|
Only the `Editor` group is open by default. Open the other groups when you need audio or cinematic tooling.
|
|
|
|
## Map Editing Workflow
|
|
|
|
1. Open `/editor` in the local app.
|
|
2. Click an object in the scene to select it.
|
|
3. Choose a transform mode: translate, rotate, or scale.
|
|
4. Drag the transform gizmo in the 3D view.
|
|
5. Check the JSON inspector if you need exact values.
|
|
6. Use undo or redo if the transform is not correct.
|
|
7. Export the JSON or save it to the dev server.
|
|
|
|
## Controls
|
|
|
|
| Action | Input |
|
|
| -------------------- | -------------------------- |
|
|
| Select object | Click object |
|
|
| Deselect | `Esc` or click empty space |
|
|
| Lock selection | `Lock` button in Selection |
|
|
| Clear selection | `X` button in Selection |
|
|
| Translate mode | `T` |
|
|
| Rotate mode | `R` |
|
|
| Scale mode | `S` |
|
|
| Undo | `Ctrl+Z` |
|
|
| Redo | `Ctrl+Y` |
|
|
| Locked view movement | `WASD`, `ZQSD`, arrows |
|
|
| Move up | `Space` |
|
|
| Move down | `Shift` |
|
|
|
|
## Selection
|
|
|
|
The `Selection` section shows the selected object name and its index in `public/map.json`.
|
|
|
|
- Click an object to select it.
|
|
- Click empty space or press `Esc` to clear the selection.
|
|
- Use the `X` button to clear the selection explicitly.
|
|
- Use the `Lock` button to protect the current selection while editing.
|
|
|
|
When selection is locked:
|
|
|
|
- clicking another object does not change the selection
|
|
- clicking empty space does not clear the selection
|
|
- pressing `Esc` does not clear the selection
|
|
- the `X` button still clears the selection intentionally
|
|
|
|
## View Mode
|
|
|
|
The `Lock view` action switches the editor into a movement mode closer to the runtime player camera. Use it to navigate larger scenes while keeping the transform tools available.
|
|
|
|
## JSON Inspector
|
|
|
|
The `JSON` section shows the raw map data that will be exported or saved:
|
|
|
|
- When no object is selected, it shows the full map node list.
|
|
- When an object is selected, it highlights the JSON lines for that object.
|
|
|
|
Use it to verify exact numeric transform values before saving or exporting. The JSON inspector is read-only; transform values are changed through the gizmo in the scene.
|
|
|
|
## Saving Changes
|
|
|
|
### Export JSON
|
|
|
|
`Export JSON` downloads the current map node list as `map.json`. Use this when you want to manually replace `public/map.json`.
|
|
|
|
### Save To Server
|
|
|
|
`Save to server` is available only during local development. It writes the edited map back to `public/map.json` through the Vite dev-server endpoint.
|
|
|
|
The button is hidden in production builds because production persistence is not implemented.
|
|
|
|
## Editing Dialogue Subtitles
|
|
|
|
The side panel includes two separate audio text tools:
|
|
|
|
- `Dialogues` edits the dialogue manifest, which links dialogue IDs to audio files and SRT cue indexes.
|
|
- `SRT` edits the actual subtitle text and cue timings.
|
|
|
|
The important model is: one dialogue entry points to one cue inside one SRT file. The SRT file is grouped by voice and language, not by dialogue.
|
|
|
|
### Dialogue Manifest
|
|
|
|
Use the `Dialogues` panel to edit `public/sounds/dialogue/dialogues.json` without opening the JSON file manually.
|
|
|
|
Each dialogue entry contains:
|
|
|
|
| Field | Meaning |
|
|
| ------------------ | ----------------------------------------------------------------- |
|
|
| `id` | Unique dialogue ID used by cinematics and runtime triggers |
|
|
| `voice` | Voice file group: `narrateur`, `fermier`, or `electricienne` |
|
|
| `audio` | Runtime audio path, usually under `/sounds/dialogue/` |
|
|
| `subtitleCueIndex` | Cue number inside the selected voice/language SRT file |
|
|
| `timecode` | Optional global runtime trigger time, in seconds from scene start |
|
|
|
|
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.
|
|
|
|
Recommended workflow for a new dialogue:
|
|
|
|
1. Open `Dialogues`.
|
|
2. Click `Add`.
|
|
3. Choose the correct `voice`.
|
|
4. Replace the generated `id` with a readable stable ID.
|
|
5. Replace the placeholder `audio` path with the real MP3 path.
|
|
6. Check the generated `subtitleCueIndex`.
|
|
7. Click `Create FR SRT cue` if the cue does not exist yet.
|
|
8. Click `Save`.
|
|
9. Open `SRT`, edit the cue text and timings, then save the SRT file.
|
|
10. Run `Validate` from the SRT panel.
|
|
|
|
### 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`.
|
|
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.
|
|
|
|
SRT timings are relative to the dialogue audio file, not to the global game timeline and not to the cinematic timeline. For example, `00:00:01,000` means one second after that dialogue audio starts.
|
|
|
|
## 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, not errors, because the runtime falls back to French subtitles. This is intentional until the English translation workflow is ready.
|
|
|
|
## 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`
|
|
|
|
Recommended workflow for a cinematic:
|
|
|
|
1. Open `Cinematics`.
|
|
2. Select an existing cinematic or click `Add`.
|
|
3. Set a stable `id`.
|
|
4. Add or adjust camera keyframes.
|
|
5. Keep keyframe `time` values increasing from start to end.
|
|
6. Add dialogue cues when a dialogue must start during the camera sequence.
|
|
7. Click `Preview cinematic` to test the camera path in the editor canvas.
|
|
8. Click `Save` when the manifest is correct.
|
|
|
|
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.
|
|
|
|
Use `dialogueCues` when the dialogue belongs to a cinematic. Use a dialogue `timecode` only for simple global scene timing outside a cinematic.
|
|
|
|
## Current Limitations
|
|
|
|
- The editor only modifies existing nodes.
|
|
- It does not create or delete objects.
|
|
- 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.
|
|
- Dialogue and cinematic saves are local Vite dev-server helpers, not production backend features.
|