--- name: custom-level-editor description: Use when a LittleJS game needs a level editor or editable levels — "add a level editor", "let me edit levels", "make a map editor", "build a custom editor for my game", "hook my game up to the editor", placing objects or painting tiles while the game runs, saving levels as files, or extending/forking the built-in editor. LittleJS ships a 2D tile and object editor and a 3D level editor in the debug build; make the game load its level from data and customize that editor through the levelEditor object (own object types, keys, buttons, tools, panel, overlays, save) instead of writing an editor from scratch. --- # custom-level-editor LittleJS (1.23+) has two level editors inside the debug build — a 2D one that paints tile layers and places objects in a Tiled map, and a 3D one that places, moves, rotates and scales objects, paints blocks and sculpts terrain. Both are a starting point, meant to be turned into the editor for one particular game. **Do not write a level editor from scratch.** Undo, autosave, selection, copy and paste, snapping, file save and a play/edit toggle are already there. The full API with tested code for every feature is in `${CLAUDE_SKILL_DIR}/EDITOR.md` (the engine's own guide, ~330 lines — read it before writing editor code). Two complete small games that start in the editor are in `${CLAUDE_SKILL_DIR}/examples/`: `editor2D.js` and `editor3D.js`. ## Pick the level of customization Work down this list and stop at the first one that covers what the user asked for. 1. **Use it as is.** Make the game load its level from data, register its object types, set two hooks. This alone gives a working editor. Most of the work is here (see "Making a game editable"). 2. **Customize it through `levelEditor`.** Add the game's own keys, panel buttons, mouse tools, panel controls, overlays and save target. This is what "a custom editor for my game" almost always means. 3. **Fork the editor source.** Only when the user wants to change how the editor's *own* tools behave (how Move snaps, how painting works, the panel's layout), which the API does not expose. See "Forking" — it means building the engine, so confirm that is wanted first. ## Facts that decide whether it works at all - **Debug build only.** The editor's code is in `littlejs.js` and absent from `littlejs.release.js` / `littlejs.min.js`. The page being developed must load the debug build. In a release build `levelEditor` is a stub that accepts every call and does nothing, so editor code needs no `if (debug)` guards and can stay in the shipped game. - **Opening it.** Esc opens the debug overlay, then `0` opens the editor; Esc then switches between editing and playing. Or call `levelEditor.open()` at the end of `gameInit` to start in the editor. It picks the 3D editor when the game loaded a 3D level; `levelEditor.use3D = true/false` forces one. - **The level data is the source of truth.** The editor edits the level object the game loaded (a Tiled map in 2D, a `{littlejs3D: 1, objects: [...]}` object in 3D) and brings the game's objects in line. A level built by code in `gameInit` (`new Wall(...)` in loops) gives the editor nothing to edit. - **Types are named by a string**, never by the class, because minified builds rename classes. - **Engine names are global.** `levelEditor`, `LevelEditor`, `setLevelEditor`, `level3DLoad`, `objectLayersLoad` and friends are engine globals — never declare your own with those names. ## Making a game editable This is the step that turns an existing game into one the editor can work on. 1. **Move the level into data.** One object per level. - 2D: a Tiled map — `{width, height, tilewidth, tileheight, layers: [{type: 'tilelayer', ...}, {type: 'objectgroup', objects: [...]}]}`. Copy the shape from `examples/editor2D.js` (`makeLevel`). Tiled itself can open and save these files. - 3D: `{littlejs3D: 1, objects: [{id, type, pos, rotation, scale, properties}]}` with optional `scene`, `voxels`, `terrain` and `prefabs` blocks. `Box`, `Sphere`, `Cylinder` and `Light` are built-in types, enough to block out a level with no code. Copy the shape from `examples/editor3D.js`. 2. **Register the game's types before loading**, by name, with default properties. Each default that is a number, boolean, string, `Color` or vector becomes an input in the editor's panel, saved per object. - 2D: `objectLayersAddType('Coin', Coin, {value: 1}, tile(6))` — the class is made with `new Coin(pos)`, the defaults are then set on it, and the tile is its icon in the editor. - 3D: `level3DAddType('Spawner', Spawner, {rate: 2, color: hsl(0, 1, .5)})` — the class is made with `new Spawner(pos3D, properties)`, so it needs its **own constructor** taking those two; one that forwards every argument to `EngineObject3D` would pass the properties as the mesh. `level3DAddMesh('Tree', mesh)` is a static prop with no class. - A thing that is not an object (a player start, a camera point) is an arrow function — `objectLayersAddType('PlayerStart', (pos)=> playerStart = pos)`. 3. **Write one `loadLevel()`** that destroys everything and rebuilds from the data, and call it from `gameInit`: - 2D: `engineObjectsDestroy(); tileLayersLoad(level, tile(0, 16), 0, collisionLayerIndex); objectLayersLoad(level);` then make the player. - 3D: `engineObjectsDestroy(); level3DLoad(level);` then make the player. 4. **Set the two hooks** that make the editor useful for playtesting: ```javascript levelEditor.onRestart = loadLevel; // adds a Restart button levelEditor.onPlayFrom = (pos)=> { player.pos = pos.copy(); player.velocity = vec2(); }; // "Play from mouse" ``` In 3D `pos` is a `Vector3` — set `player.pos3D` and `velocity3D`. 5. 2D only — if painted tiles need game logic (collision values, spawning a decoration), set `levelEditor.onTile = (layer, pos, tile)=> {...}` (`tile` is undefined when erased), and `levelEditor.paletteTiles = [0, 1, 10]` to show only the level tiles of the sheet. ### Tile sheets The 2D editor paints tile indices from a tile sheet, so a tile-based game needs one — an image in `engineInit`'s image list, or a texture the game generates. A map of object layers only (`objectLayersLoad` with no tile layer) needs none. A 3D level needs no image at all — its block map (`voxels`) shows the tiles of the sheet given to `level3DVoxelSetup`, or of the game's first image, and in a game that has loaded no image it shows plain colored blocks, one color per block type (engine 1.23.1+; 1.23.0 asserted `tile texture is not loaded` there). ### Where the level file lives The editor autosaves to the browser as you work, and its Save button writes the level as JSON (to a file picked once in Chrome and Edge, a download elsewhere). How the game reads it back depends on how the game is served. - **Opened from `file://`** (no server) — `fetch` cannot read local files, so keep the level in a script — `level.js` containing `var level = {...};`, loaded by a `