add editor documentation pages
This commit is contained in:
@@ -10,8 +10,8 @@ The editor is a React route used to inspect and adjust the `public/map.json` sce
|
||||
|
||||
- `/` renders the playable La-Fabrik scene.
|
||||
- `/editor` renders the map editor.
|
||||
- `src/main.tsx` wraps the app with `BrowserRouter`.
|
||||
- `src/App.tsx` defines the route and imports `EditorPage` from `src/pages/editor/EditorPage.tsx`.
|
||||
- `src/App.tsx` mounts TanStack Router through `RouterProvider`.
|
||||
- `src/router.tsx` defines the `/editor` route and imports `EditorPage` from `src/pages/editor/EditorPage.tsx`.
|
||||
|
||||
## File Structure
|
||||
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# Editor User Guide
|
||||
|
||||
The map editor is available at `/editor`. It is a browser-based tool for inspecting and adjusting the objects listed in `public/map.json`.
|
||||
|
||||
## Purpose
|
||||
|
||||
Use the editor when you need to move, rotate, or scale existing map objects without editing JSON by hand.
|
||||
|
||||
The editor reads the same map data as the runtime scene:
|
||||
|
||||
- `public/map.json` contains the object list.
|
||||
- `public/models/{name}/model.gltf` contains the matching 3D model for each object name.
|
||||
- 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]` |
|
||||
|
||||
## 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 |
|
||||
| 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` |
|
||||
|
||||
## 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 side panel includes a raw JSON inspector:
|
||||
|
||||
- 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.
|
||||
|
||||
This is useful for checking numeric transform values before saving or exporting.
|
||||
|
||||
## 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 yet.
|
||||
|
||||
## Current Limitations
|
||||
|
||||
- The editor only modifies existing nodes.
|
||||
- It does not create or delete objects yet.
|
||||
- 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.
|
||||
@@ -256,3 +256,73 @@ Ce document liste les fonctionnalités présentes dans le code actuel.
|
||||
- minimap et HUD de mission
|
||||
- séparation complète production / debug pour les scènes gameplay
|
||||
`;
|
||||
|
||||
export const editorFr = `# Éditeur de carte
|
||||
|
||||
L'éditeur de carte est disponible sur "/editor". Il permet d'inspecter et d'ajuster les objets déclarés dans "/public/map.json" directement depuis le navigateur.
|
||||
|
||||
## Ce qui est édité
|
||||
|
||||
L'éditeur travaille sur la liste de nodes stockée dans "/public/map.json".
|
||||
|
||||
Chaque node décrit un objet de la scène :
|
||||
|
||||
- "name" : nom du dossier modèle dans "/public/models/{name}/model.gltf"
|
||||
- "type" : catégorie de l'objet
|
||||
- "position" : "[x, y, z]"
|
||||
- "rotation" : "[x, y, z]"
|
||||
- "scale" : "[x, y, z]"
|
||||
|
||||
Les modèles sont chargés depuis "/public/models". Si un modèle manque, l'éditeur affiche un cube gris de remplacement pour que le node reste sélectionnable et déplaçable.
|
||||
|
||||
## Workflow de base
|
||||
|
||||
1. Ouvrir "/editor".
|
||||
2. Sélectionner un objet dans la vue 3D.
|
||||
3. Choisir un mode de transformation : translation, rotation ou scale.
|
||||
4. Déplacer la gizmo de transformation.
|
||||
5. Utiliser undo ou redo si nécessaire.
|
||||
6. Exporter le JSON mis à jour ou le sauvegarder sur le serveur de dev.
|
||||
|
||||
## Contrôles
|
||||
|
||||
| Action | Input |
|
||||
| --- | --- |
|
||||
| Sélectionner un objet | Clic sur l'objet |
|
||||
| Désélectionner | "Esc" ou clic dans le vide |
|
||||
| Mode translation | "T" |
|
||||
| Mode rotation | "R" |
|
||||
| Mode scale | "S" |
|
||||
| Undo | "Ctrl+Z" |
|
||||
| Redo | "Ctrl+Y" |
|
||||
| Déplacement en vue verrouillée | "WASD", "ZQSD", flèches |
|
||||
| Monter / descendre | "Space", "Shift" |
|
||||
|
||||
## Actions fichier
|
||||
|
||||
### Export JSON
|
||||
|
||||
"Export JSON" télécharge la liste actuelle des nodes sous le nom "map.json". À utiliser pour remplacer manuellement "/public/map.json".
|
||||
|
||||
### Save to server
|
||||
|
||||
"Save to server" est disponible uniquement en développement local. L'action écrit la carte modifiée dans "/public/map.json" via l'endpoint du serveur de dev Vite.
|
||||
|
||||
Cette action est masquée dans les builds de production car il n'existe pas encore d'API de persistance production.
|
||||
|
||||
## Inspecteur JSON
|
||||
|
||||
Le panneau latéral affiche le JSON brut de la carte :
|
||||
|
||||
- sans sélection, il affiche toute la liste des nodes
|
||||
- avec un objet sélectionné, il met en évidence les lignes du node sélectionné
|
||||
|
||||
Utilise-le pour vérifier les valeurs numériques exactes avant export ou sauvegarde.
|
||||
|
||||
## Limites actuelles
|
||||
|
||||
- L'éditeur modifie uniquement les nodes existants.
|
||||
- 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.
|
||||
`;
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
import editor from "../../../../docs/user/editor.md?raw";
|
||||
import { DocsDocument } from "@/pages/docs/DocsDocument";
|
||||
import { editorFr } from "@/pages/docs/docsTranslations";
|
||||
|
||||
export function DocsEditorPage(): React.JSX.Element {
|
||||
return (
|
||||
<DocsDocument
|
||||
content={editor}
|
||||
frContent={editorFr}
|
||||
meta="06"
|
||||
title="Editor User Guide"
|
||||
/>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
import technicalEditor from "../../../../docs/technical/editor.md?raw";
|
||||
import { DocsDocument } from "@/pages/docs/DocsDocument";
|
||||
|
||||
export function DocsTechnicalEditorPage(): React.JSX.Element {
|
||||
return (
|
||||
<DocsDocument
|
||||
content={technicalEditor}
|
||||
frContent={technicalEditor}
|
||||
meta="04"
|
||||
title="Editor Technical Notes"
|
||||
/>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user