docs: document editor architecture and user features

2026-04-28 09:43:51 +02:00
parent 7b38f04a0d
commit 8f40bb8133
21 changed files with 776 additions and 911 deletions
@@ -0,0 +1,143 @@
+# Editor Technical Notes
+
+This document describes the map editor that exists in the current codebase.
+
+## Purpose
+
+The editor is a React route used to inspect and adjust the `public/map.json` scene data from inside the La-Fabrik app. It shares the same `MapNode` data format as the game scene and uses React Three Fiber for rendering.
+
+## Routing
+
+- `/` 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`.
+
+## File Structure
+
+```txt
+src/
+├── pages/
+│   └── editor/
+│       └── EditorPage.tsx
+├── features/
+│   └── editor/
+│       ├── components/
+│       │   └── EditorControls.tsx
+│       ├── controls/
+│       │   └── FlyController.tsx
+│       ├── hooks/
+│       │   ├── useEditorHistory.ts
+│       │   └── useEditorSceneData.ts
+│       ├── scene/
+│       │   ├── EditorMap.tsx
+│       │   └── EditorScene.tsx
+│       └── utils/
+│           └── loadEditorScene.ts
+├── types/
+│   └── editor.ts
+└── utils/
+    └── loadMapSceneData.ts
+```
+
+## Responsibilities
+
+`src/pages/editor/EditorPage.tsx` is the route-level composition component. It owns route-specific state such as selected object, hovered object, transform mode, and player-mode toggle.
+
+`src/features/editor/hooks/useEditorSceneData.ts` loads the default map data and handles folder uploads.
+
+`src/features/editor/hooks/useEditorHistory.ts` owns editor undo and redo history.
+
+`src/features/editor/scene/EditorScene.tsx` composes the editor canvas scene, camera controls, lights, keyboard shortcuts, and `EditorMap`.
+
+`src/features/editor/scene/EditorMap.tsx` renders map nodes, fallback cubes, selection highlighting, and transform controls.
+
+`src/features/editor/components/EditorControls.tsx` renders the HTML control panel outside the canvas.
+
+`src/features/editor/controls/FlyController.tsx` provides editor movement controls for player-style navigation.
+
+`src/utils/loadMapSceneData.ts` is shared by the game map and editor. It loads `/map.json` and resolves available `public/models/{name}/model.gltf` files.
+
+`src/features/editor/utils/loadEditorScene.ts` contains editor-only upload handling for user-selected folders.
+
+## Data Format
+
+The shared editor type lives in `src/types/editor.ts`.
+
+```ts
+interface MapNode {
+  name: string;
+  type: string;
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+}
+```
+
+`public/map.json` is expected to be a `MapNode[]`.
+
+```json
+[
+  {
+    "name": "pylone",
+    "type": "Mesh",
+    "position": [0, 5, 0],
+    "rotation": [0, 1.57, 0],
+    "scale": [1, 1, 1]
+  }
+]
+```
+
+Each node `name` maps to a model folder:
+
+```txt
+public/
+├── map.json
+└── models/
+    └── pylone/
+        └── model.gltf
+```
+
+If a model is missing, the editor renders a fallback cube so the node can still be selected and transformed.
+
+## Editor Flow
+
+1. `EditorPage` mounts on `/editor`.
+2. `useEditorSceneData` calls `loadMapSceneData()`.
+3. `loadMapSceneData()` loads `/map.json` and available model URLs.
+4. If `/map.json` is missing, the page displays a folder-upload flow.
+5. `EditorScene` renders the grid, lights, camera controls, and map nodes.
+6. `EditorControls` exposes transform mode, history actions, export, save, and selection info.
+
+## Controls
+
+- Click: select a node.
+- `Esc`: clear selection.
+- `T`: translate mode.
+- `R`: rotate mode.
+- `S`: scale mode.
+- `Ctrl+Z` or `Cmd+Z`: undo.
+- `Ctrl+Y` or `Cmd+Y`: redo.
+- `WASD`, `ZQSD`, or arrow keys: move in player-controller mode.
+- `Space`: move upward in player-controller mode.
+- `Shift`: move downward in player-controller mode.
+
+## Saving And Exporting
+
+The editor supports two output paths:
+
+- Export JSON downloads the current `MapNode[]` as `map.json`.
+- Save to Server posts the current `MapNode[]` to `/api/save-map`.
+
+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.
+
+## 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.
+
+## Known Limitations
+
+- Uploaded model object URLs are not currently revoked after replacement or unmount.
+- Large `map.json` files may need virtualization, culling, or LOD support later.
+- There is no snap-to-grid, duplication, material editing, or object creation workflow yet.
+- Save to Server is a Vite dev-server helper, not a production backend API.