docs: document editor architecture and user features
This commit is contained in:
@@ -4,13 +4,16 @@ This document describes the code that exists today in the repository.
|
||||
|
||||
## Runtime Structure
|
||||
|
||||
- `src/App.tsx` mounts the `Canvas`, the 3D `World`, the debug perf overlay, and the HTML overlays.
|
||||
- `src/main.tsx` mounts React and wraps the app in `BrowserRouter`.
|
||||
- `src/App.tsx` declares the top-level routes:
|
||||
- `/` mounts the playable 3D scene, debug perf overlay, and HTML overlays.
|
||||
- `/editor` mounts the map editor page.
|
||||
- `src/world/World.tsx` composes the active scene, including:
|
||||
- environment and lighting
|
||||
- debug helpers and debug camera mode
|
||||
- either the map scene or the debug physics test scene
|
||||
- the player rig when the active camera mode is `player`
|
||||
- `src/world/Map.tsx` loads the main map model and builds the collision octree.
|
||||
- `src/components/game/GameMap.tsx` loads map nodes from `public/map.json`, resolves available models, and builds the collision octree.
|
||||
- `src/world/debug/TestScene.tsx` provides a debug-oriented interaction and physics scene.
|
||||
- `src/world/player/PlayerComponent.tsx` mounts the camera and controller.
|
||||
- `src/world/player/PlayerController.tsx` owns pointer lock movement, jump handling, and interaction input.
|
||||
@@ -38,6 +41,26 @@ This document describes the code that exists today in the repository.
|
||||
- `src/utils/debug/scene/DebugHelpers.tsx` mounts debug helpers.
|
||||
- `src/utils/debug/scene/DebugCameraControls.tsx` mounts the free debug camera.
|
||||
|
||||
## Editor System
|
||||
|
||||
- `src/pages/editor/EditorPage.tsx` is the route-level editor page for `/editor`.
|
||||
- `src/features/editor/components/EditorControls.tsx` renders the HTML editor control panel.
|
||||
- `src/features/editor/scene/EditorScene.tsx` composes the editor canvas scene, camera controls, lights, shortcuts, and map rendering.
|
||||
- `src/features/editor/scene/EditorMap.tsx` renders map nodes, fallback cubes, selection highlighting, and transform controls.
|
||||
- `src/features/editor/controls/FlyController.tsx` provides player-style editor navigation.
|
||||
- `src/features/editor/hooks/useEditorSceneData.ts` loads scene data and handles folder upload fallback.
|
||||
- `src/features/editor/hooks/useEditorHistory.ts` owns editor undo and redo state.
|
||||
- `src/features/editor/utils/loadEditorScene.ts` handles editor-only folder upload parsing.
|
||||
- `src/utils/loadMapSceneData.ts` is shared by the game scene and editor to load `public/map.json` and resolve model URLs.
|
||||
- `src/types/editor.ts` contains the shared `MapNode`, `SceneData`, and `TransformMode` types.
|
||||
|
||||
## Map Data
|
||||
|
||||
- `public/map.json` is expected to be a `MapNode[]`.
|
||||
- Each map node `name` maps to `public/models/{name}/model.gltf`.
|
||||
- The editor renders a fallback cube for missing models.
|
||||
- The game scene filters out nodes whose model cannot be resolved.
|
||||
|
||||
## Current Limitations
|
||||
|
||||
- The repository is still a prototype, not the full intended game runtime.
|
||||
@@ -45,3 +68,4 @@ This document describes the code that exists today in the repository.
|
||||
- There is no central gameplay orchestrator such as `GameManager` yet.
|
||||
- Missions, zones, cinematics, and dialogue systems are not implemented.
|
||||
- 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.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user