# 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
├── types/
│   └── editor.ts
└── utils/
    ├── editor/
    │   └── loadEditorScene.ts
    └── 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/utils/editor/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.