littlejsengine 1.22.0 → 1.23.0

package/src/engineEditor.js

@@ -31,32 +31,101 @@
  *  @memberof Editor
  */
 
+/**
+ *  @typedef {Object} EditorToolAt - What the level editor gives the callbacks of a tool of the game's own
+ *  @property {any} pos - Where the mouse is in the level: a Vector2 in the 2D editor; in the 3D one a Vector3 on
+ *    the level or the ground, undefined when the mouse is over the panel
+ *  @property {Vector2|undefined} cell - 2D: the tile cell under the mouse on the selected tile layer
+ *  @property {any} ray - 3D: the mouse's Ray3D
+ *  @property {boolean} shift - Is Shift held
+ *  @property {boolean} ctrl - Is Ctrl held
+ *  @memberof Editor
+ */
+
+/**
+ *  @typedef {Object} EditorTool - A tool of the game's own for the level editor, see LevelEditor.addTool
+ *  @property {string} [key] - The key that picks it, as addKey spells one
+ *  @property {string} [hint] - The hint line while it is on
+ *  @property {function(EditorToolAt): any} [onPress] - The left button went down in the level; returning false
+ *    says the press was not the tool's
+ *  @property {function(EditorToolAt): any} [onDrag] - Each frame it is held
+ *  @property {function(EditorToolAt): any} [onRelease] - It was let go
+ *  @property {function(EditorToolAt): any} [onDraw] - Each frame the tool is on, to draw its cursor or preview
+ *  @memberof Editor
+ */
+
+/**
+ *  @typedef {Object} EditorEdit2D - The 2D level editor's edit functions, levelEditor.edit2D
+ *  @property {Object|undefined} map - The Tiled map of the selected layer
+ *  @property {TileLayer|undefined} layer - The selected tile layer, undefined on an object layer
+ *  @property {Array<Object>} objects - A copy of the selected object layer's objects, as Tiled has them
+ *  @property {Vector2|undefined} hover - The cell under the mouse on the selected tile layer
+ *  @property {Set<number>} selection - The selected objects' ids
+ *  @property {function(Vector2, number, ...any): boolean} paint - Set a cell of the selected tile layer
+ *    to a tile index, -1 erases, with a direction 0 to 3 and a mirror; false off the layer or with none
+ *  @property {function(function(Array<Object>): void): boolean} changeObjects - Edit a copy of the selected object
+ *    layer's objects; false when nothing changed
+ *  @property {function(): void} strokeEnd - End the edit: one undo step, and the autosave
+ *  @property {function(): void} strokeCancel - Take the edit being made back
+ *  @property {function(function(): void): void} bulk - Many paints with one redraw a layer
+ *  @property {function(...any): any} undo - Undo, or redo with true
+ *  @property {function(): string} toJSON - The map as the text Save writes
+ *  @memberof Editor
+ */
+
+/**
+ *  @typedef {Object} EditorEdit3D - The 3D level editor's edit functions, levelEditor.edit3D; a position, a
+ *    rotation and a scale are Vector3, the rotation in degrees
+ *  @property {Object|undefined} level - The level object being edited
+ *  @property {Array<Object>} objects - Its objects, the list in the level: read it, edit through change
+ *  @property {Set<number>} selection - The selected objects' ids
+ *  @property {function(): Array<Object>} selected - The selected objects
+ *  @property {function(number): any} made - What the game made for an object's id
+ *  @property {function(function(Array<Object>): void): boolean} change - Edit a copy of the object list; false
+ *    when nothing changed
+ *  @property {function(string, function(any): any): boolean} changePart - Edit the level's scene, voxels, terrain
+ *    or prefabs block
+ *  @property {function(): void} strokeEnd - End the edit: one undo step, and the autosave
+ *  @property {function(): void} strokeCancel - Take the edit being made back
+ *  @property {function(string, any): number|undefined} place - Add an object of a type at a position, selected;
+ *    its id, undefined when there is no such type or the level can not be edited
+ *  @property {function(Object, ...any): void} setTransform - Write a place, a rotation and a scale on an
+ *    object of the list given to change; one left out is kept
+ *  @property {function(Object, string, any): void} setProperty - Write a property on an object of the list given
+ *    to change, left out of the file when it is the type's default
+ *  @property {function(Object): any} pos - An object's position
+ *  @property {function(Object): any} rotation - Its rotation, in degrees
+ *  @property {function(Object): any} scale - Its scale
+ *  @property {function(): any} mousePoint - Where the mouse is on the level or the ground, undefined over the panel
+ *  @property {function(...any): boolean} undo - Undo, or redo with true
+ *  @property {function(): string} toJSON - The level as the text Save writes
+ *  @memberof Editor
+ */
+
 /**
  * The level editor, open it to pause the game and edit its level, close it to play on with the changes
  * - One of it, levelEditor, 0 on the debug overlay opens and closes it too
- * - In release builds levelEditor is a stub that never opens, and its hooks are never called
+ * - A game makes it its own: it sets the hooks, adds keys, panel buttons and tools, or extends this class and
+ *   gives its own with setLevelEditor; the same calls work in the 2D editor and the 3D one, see EDITOR.md
+ * - In release builds LevelEditor is a stub that never opens: what a game adds is taken and never called
  * @memberof Editor
  * @example
  * levelEditor.onRestart = ()=> loadLevel(); // adds a Restart button that rebuilds the level
  * levelEditor.onTile = (layer, pos, tile)=> layer.setCollisionData(pos, tile === ladderTile ? -1 : tile ? 1 : 0);
+ * levelEditor.addKey('k', ()=> clearEnemies(), 'K: clear the enemies');
+ *
+ * // or as a class of the game's own
+ * class MyEditor extends LevelEditor
+ * {
+ *     onRestart() { loadLevel(); }
+ *     onDraw() { drawSpawnZones(); }
+ * }
+ * setLevelEditor(new MyEditor);
  */
 class LevelEditor
 {
     constructor()
     {
-        /** @property {EditorTileCallback|undefined} - What the game does when the editor paints a tile, like
-         *  setting its collision or its look the way the game does when it loads the level; without one, the
-         *  collision layer gets collision 1 where there is a tile
-         *  @type {EditorTileCallback|undefined} */
-        this.onTile = undefined;
-        /** @property {Function|undefined} - Rebuild the level from the map the editor changed, a Restart button
-         *  calls it after switching to play; without one there is no Restart button
-         *  @type {EditorRestartCallback|undefined} */
-        this.onRestart = undefined;
-        /** @property {Function|undefined} - Put the player at a world position; with it, the editor's Advanced
-         *  section has Play from mouse, which starts play there, Escape at the mouse and Play at the view center
-         *  @type {EditorPlayFromCallback|undefined} */
-        this.onPlayFrom = undefined;
         /** @property {Array<number>|undefined} - The tiles the palette shows, in its order, for a sheet that also holds
          *  sprites and art that are not level tiles; undefined shows every tile of the sheet
          *  @type {Array<number>|undefined} */
@@ -65,15 +134,133 @@ class LevelEditor
          *  3D one when a level was loaded with level3DLoad and there is a Render3DPlugin
          *  @type {boolean|undefined} */
         this.use3D = undefined;
+        /** @property {string|undefined} - The tool of the game's own that is on, one added with addTool, undefined
+         *  while a tool of the editor's is
+         *  @type {string|undefined} */
+        this.tool = undefined;
+        // what the game added: its keys by how they are spelled, its panel buttons and its tools by name
+        /** @type {Object<string, {action: function(boolean): any, help: string|undefined, warned: boolean}>} */
+        this.keys = {};
+        /** @type {Array<{label: string, onClick: Function, title: string}>} */
+        this.buttons = [];
+        /** @type {Object<string, EditorTool>} */
+        this.tools = {};
     }
 
+    /** What the game does when the 2D editor paints a tile, like setting its collision or its look the way the
+     *  game does when it loads the level; set it or override it, without one the collision layer gets collision 1
+     *  where there is a tile
+     *  @param {TileLayer} layer - The layer painted
+     *  @param {Vector2} pos - The cell's position in the layer
+     *  @param {number|undefined} tile - The tile painted, undefined when erased */
+    onTile(layer, pos, tile) {}
+
+    /** Rebuild the level from what the editor changed; set it or override it and the editor has a Restart button,
+     *  which calls it after switching to play */
+    onRestart() {}
+
+    /** Put the player at a position, a Vector2 in the 2D editor and a Vector3 in the 3D one; set it or override it
+     *  and the editor has Play from mouse, which starts play there
+     *  @param {any} pos */
+    onPlayFrom(pos) {}
+
+    /** Called when the editor opens, to set or override */
+    onOpen() {}
+
+    /** Called when the editor closes and the game plays on, to set or override */
+    onClose() {}
+
+    /** Called each frame while the editor is open, to set or override */
+    onUpdate() {}
+
+    /** Called while the editor draws the level, to draw overlays of the game's own in it, to set or override */
+    onDraw() {}
+
+    /** Called once when the editor's panel is made, with a box in it for the game's own controls, to set or override
+     *  @param {HTMLElement} element */
+    onPanel(element) {}
+
+    /** Called by Save with the text of the file and its name; return true when the game kept it itself, and the
+     *  editor writes no file, to set or override
+     *  @param {string} text
+     *  @param {string} fileName
+     *  @return {boolean|void} */
+    onSave(text, fileName) { return false; }
+
     /** True while the editor is open, the game is paused under it
      *  @return {boolean} */
-    get isOpen() { return editorIsOpen; }
+    get isOpen() { return editorIsOpen || !!editorOther?.isOpen(); }
+
+    /** True when the editor in use is the 3D one, as use3D says or since a 3D level was loaded
+     *  @return {boolean} */
+    get is3D() { return !!editorOther?.wanted(); }
+
+    /** The 2D editor's edit functions, for a key, a button or a tool of the game's own: map, the Tiled map; layer,
+     *  the selected TileLayer; objects, a copy of the selected object layer's; hover, the cell under the mouse;
+     *  selection, the selected objects' ids; paint(cell, tile, direction, mirror), a tile index, -1 erases;
+     *  changeObjects((list)=> ...); strokeEnd() and strokeCancel(); bulk(()=> ...); undo(redo); toJSON()
+     *  @return {EditorEdit2D} */
+    get edit2D() { return editorEdit2D; }
+
+    /** The 3D editor's edit functions, undefined without the 3D plugins: level; objects; selection, a Set of ids;
+     *  selected(); made(id); change((list)=> ...); changePart(name, (part)=> ...); strokeEnd() and strokeCancel();
+     *  place(type, pos3D); setTransform(object, pos3D, rotationDegrees, scale3D); setProperty(object, name, value);
+     *  pos(object), rotation(object) and scale(object); mousePoint(); undo(redo); toJSON()
+     *  @return {EditorEdit3D|undefined} */
+    get edit3D() { return editorOther?.edit; }
+
+    /** Add a key of the game's own to the editor, the 2D and the 3D one
+     *  - Escape and 0 are the editor's own, to play and to exit, and Ctrl is the one modifier: Shift is given to
+     *    the action
+     *  @param {string} key - A letter or digit, 'k', or a key's name in any case, 'Delete', 'F2', 'Enter', 'Space';
+     *    'ctrl+k' with Ctrl or Cmd
+     *  @param {function(boolean): any} action - Called with whether Shift is held; returning false says it did
+     *    nothing, and the key is left to the browser
+     *  @param {string} [helpLine] - A line for the editor's help */
+    addKey(key, action, helpLine)
+    {
+        ASSERT(typeof action == 'function', 'a key needs an action');
+        const spelled = editorKeySpelling(key), name = spelled.replace('ctrl+', '');
+        if (name === 'Escape' || name === '0' || name.length > 1 && name.includes('+'))
+        {
+            console.warn(`levelEditor.addKey: ${key} is not taken, ` + (name.includes('+') ?
+                'Ctrl is the one modifier, Shift is given to the action' : 'Escape and 0 are the editor\'s own'));
+            return;
+        }
+        this.keys[spelled] = {action, help: helpLine, warned: false};
+        this === levelEditor && editorKeyClashes();
+    }
+
+    /** Add a button of the game's own to the editor's panel
+     *  @param {string} label
+     *  @param {Function} onClick
+     *  @param {string} [title] - What it says when the mouse is over it */
+    addButton(label, onClick, title='') { this.buttons.push({label, onClick, title}); }
+
+    /** Add a tool of the game's own: a button in the panel by its name, and while it is on the left button in the
+     *  level is its, not the editor's own tools'
+     *  - Each callback is given {pos, cell, ray, shift, ctrl}: pos is where the mouse is in the level, a Vector2 in
+     *    2D and a Vector3 on the level or the ground in 3D; cell is the tile under it in 2D; ray is the mouse's
+     *    in 3D
+     *  - What the callbacks change through edit2D or edit3D is one undo: the editor ends the stroke at the release,
+     *    and takes it back when the right button or Escape ends the press
+     *  @param {string} name
+     *  @param {EditorTool} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
+     *    false says the press was not the tool's */
+    addTool(name, tool)
+    {
+        ASSERT(!!tool && typeof tool == 'object', 'a tool is an object of callbacks');
+        const before = this.tools[name]; // added again, it takes the place of the first, its key too
+        before?.key && delete this.keys[editorKeySpelling(before.key)];
+        this.tools[name] = tool;
+        tool.key && this.addKey(tool.key, ()=> { this.tool = this.tool === name ? undefined : name; });
+    }
 
     /** Open the editor, pausing the game; until close(), Escape (the debug key) switches between playing and editing */
     open()
     {
+        if (editorOther?.wanted())
+            return editorOther.open();
         if (!editorSession)
             editorCameraScale = cameraScale; // a new session starts at the game's zoom, a return keeps the editor's
         editorSession = true;
@@ -84,6 +271,8 @@ class LevelEditor
      *  overlay again */
     close()
     {
+        if (editorOther?.active())
+            return editorOther.close();
         editorSession = false;
         editorSetOpen(false);
     }
@@ -92,7 +281,118 @@ class LevelEditor
 /** The level editor, levelEditor.open() to edit the level, levelEditor.close() to play on with the changes
  *  @type {LevelEditor}
  *  @memberof Editor */
-const levelEditor = new LevelEditor;
+let levelEditor = new LevelEditor;
+
+/** Make a level editor of the game's own the one in use: an instance of a class that extends LevelEditor, with
+ *  the game's hooks as its methods; set it before the editor opens
+ *  @param {LevelEditor} editor
+ *  @memberof Editor */
+function setLevelEditor(editor)
+{
+    ASSERT(editor instanceof LevelEditor, 'a level editor extends LevelEditor');
+    levelEditor.isOpen && console.warn('setLevelEditor: the editor is open, close it first');
+    levelEditor = editor;
+}
+
+// the other editor, the 3D one, when its plugin is there: it says if it is the one wanted and open, opens and
+// closes, and has its edit functions; the 2D editor is this file
+/** @type {{wanted: function(): boolean, isOpen: function(): boolean, active: function(): boolean, open: Function,
+ *      close: Function, hasKey: function(string, boolean): boolean, edit: EditorEdit3D}|undefined} */
+let editorOther;
+
+// if the game gave a hook: set on the editor, or a method of its own class, not the empty one of LevelEditor
+function editorHas(name)
+{
+    const hook = levelEditor[name];
+    return typeof hook == 'function' && hook !== LevelEditor.prototype[name];
+}
+
+// a hook or a moment of the game's, called when it is one: a game may set one to undefined to take it away
+function editorCall(name, ...args)
+{
+    const hook = levelEditor[name];
+    return typeof hook == 'function' ? hook.apply(levelEditor, args) : undefined;
+}
+
+// the names keys have, by their lower case, so a game may spell one in any case
+const editorKeyNames = {};
+for (const name of ['Delete', 'Backspace', 'Enter', 'Tab', 'Escape', 'Space', 'Home', 'End', 'PageUp', 'PageDown',
+    'Insert', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', ...[...Array(12)].map((v, i)=> 'F' + (i + 1))])
+    editorKeyNames[name.toLowerCase()] = name;
+
+// a key as addKey keeps it: a letter in lower case, a name as keys are named, 'ctrl+' in front with Ctrl
+function editorKeySpelling(key)
+{
+    const text = String(key), ctrl = text.trim().toLowerCase().startsWith('ctrl+');
+    let name = ctrl ? text.trim().slice(5) : text;
+    name = name === ' ' ? 'Space' : name.trim();
+    name = name.length === 1 ? name.toLowerCase() : editorKeyNames[name.toLowerCase()] ?? name;
+    return (ctrl ? 'ctrl+' : '') + name;
+}
+
+// say once, for each key of the game's own that is one of the open editor's too, that the game's takes its place:
+// when the editor opens, or when the key is added while it is open, since the 2D and 3D editors' keys differ
+function editorKeyClashes()
+{
+    if (!levelEditor.isOpen) return;
+    for (const [spelled, key] of Object.entries(levelEditor.keys))
+    {
+        const ctrl = spelled.startsWith('ctrl+'), name = spelled.slice(ctrl ? 5 : 0);
+        // in 2D the digits 1 to 9 pick a layer
+        const clash = levelEditor.is3D ? editorOther.hasKey(name, ctrl) :
+            !!(ctrl ? editorCtrlKeys : editorKeys)[name] || !ctrl && name.length === 1 && name >= '1' && name <= '9';
+        if (key.warned || !clash) continue;
+        key.warned = true;
+        console.warn(`levelEditor.addKey: ${spelled} is a key of the editor's, the game's takes its place`);
+    }
+}
+
+// the help lines of the game's own keys
+function editorGameHelpLines()
+{ return Object.values(levelEditor.keys).map((key)=> key.help).filter((line)=> !!line); }
+
+// the tool of the game's own that is on, undefined when there is none
+function editorGameTool() { return levelEditor.tool !== undefined ? levelEditor.tools[levelEditor.tool] : undefined; }
+
+// the game's box of an editor's panel: a row of its tools and its buttons, made again when one was added, the
+// tool that is on lit; and, the first time for a level editor, onPanel is given the box for controls of its own
+const editorGamePanels = new WeakMap;
+function editorGamePanel(box)
+{
+    let state = editorGamePanels.get(box);
+    if (state?.owner !== levelEditor)
+    {
+        box.replaceChildren();
+        state = {owner: levelEditor, row: editorElement('div', box, 'display:flex;gap:4px;margin:4px 0;flex-wrap:wrap'),
+            key: '', buttons: {}};
+        editorGamePanels.set(box, state);
+        editorCall('onPanel', box);
+    }
+    const tools = Object.keys(levelEditor.tools);
+    const key = tools.map((name)=> name + '\t' + (levelEditor.tools[name].hint || '')).join('\n') + '\n\n' +
+        levelEditor.buttons.length;
+    if (state.key !== key)
+    {
+        state.key = key;
+        state.buttons = {};
+        const press = 'padding:3px 6px;cursor:pointer';
+        state.row.replaceChildren(...tools.map((name)=>
+        {
+            const b = state.buttons[name] = editorElement('button', undefined, press, name);
+            b.title = levelEditor.tools[name].hint || '';
+            b.onclick = ()=> { levelEditor.tool = levelEditor.tool === name ? undefined : name; b.blur?.(); };
+            return b;
+        }), ...levelEditor.buttons.map((button)=>
+        {
+            const b = editorElement('button', undefined, press, button.label);
+            b.title = button.title;
+            b.onclick = ()=> { button.onClick.call(levelEditor); b.blur?.(); };
+            return b;
+        }));
+    }
+    for (const name of tools)
+        state.buttons[name].style.outline = name === levelEditor.tool ? '2px solid #4af' : '';
+}
 
 // if the editor is open, and if it was opened and not exited, while Escape switches between playing and editing
 let editorIsOpen = false, editorSession = false;
@@ -104,7 +404,7 @@ let editorPlayFromMouse = false, editorAdvanced = false;
 function editorPlay(pos)
 {
     editorSetOpen(false);
-    editorPlayFromMouse && pos && levelEditor.onPlayFrom?.(pos.copy());
+    editorPlayFromMouse && pos && editorHas('onPlayFrom') && levelEditor.onPlayFrom(pos.copy());
 }
 
 // the game's pause and camera from before the editor opened, handed back when it closes
@@ -156,10 +456,13 @@ function editorSetOpen(open)
             layers.filter((layer)=> !layer.isObjects).at(-1));
         layers.includes(editorObjectLayer) || (editorObjectLayer = editorLayer ? undefined :
             layers.find((layer)=> layer.isObjects)); // a level of objects alone
+        editorCall('onOpen');
+        editorKeyClashes();
     }
     else
     {
         editorStrokeEnd();
+        editorToolHeld = false;
         editorSelection = editorSelectionDrag = editorRightPress = editorObjectDrag = editorObjectBox = undefined;
         editorObjectSelection.clear();
         editorMouseOnPanel = false; // the panel hides, with no mouseleave
@@ -168,6 +471,7 @@ function editorSetOpen(open)
         setCameraPos(state.cameraPos);
         setCameraScale(state.cameraScale);
         setCameraAngle(state.cameraAngle);
+        editorCall('onClose');
     }
 }
 
@@ -438,7 +742,14 @@ async function editorSave(record, pickAgain=false)
     if (!record) return;
     editorStrokeEnd();
     const text = editorMapJSON(record); // the map as it is now, later edits wait for a later save
-    const saved = (async ()=> { await record.saving; return editorSaveText(record, text, pickAgain); })();
+    // its place in line is taken now, and the game's hook is asked when its turn comes, so saves are written in
+    // the order they were asked for however long a hook takes
+    const saved = (async ()=>
+    {
+        await record.saving;
+        if (await editorCall('onSave', text, record.fileName) === true) return 'kept'; // the game kept it itself
+        return editorSaveText(record, text, pickAgain);
+    })();
     record.saving = saved.catch(()=> {});
     return saved;
 }
@@ -562,7 +873,7 @@ function editorPaintData(record, data, objects, width=record.map.width, height=r
     editorStrokeEnd();
     if (width !== record.map.width || height !== record.map.height)
     {
-        if (!levelEditor.onRestart) return;
+        if (!editorHas('onRestart')) return;
         const before = editorMapSnapshot(record);
         editorSetMapSnapshot(record, {width, height, layers: data, objects});
         editorMapChanged(record, before);
@@ -607,7 +918,7 @@ function editorPendingFits(record, saved)
 {
     const map = record.map, data = editorTileLayerData(map.layers), groups = editorObjectGroups(map.layers).length;
     const width = saved.width ?? map.width, height = saved.height ?? map.height;
-    return (width === map.width && height === map.height || !!levelEditor.onRestart) &&
+    return (width === map.width && height === map.height || editorHas('onRestart')) &&
         saved.layers?.length === data.length && saved.layers.every((layer)=> layer.length === width * height) &&
         (saved.objects ?? []).every((objects, i)=> i < groups || !objects.length);
 }
@@ -711,7 +1022,7 @@ function editorMapChanged(record, before)
 function editorResize(record, width, height)
 {
     const map = record?.map;
-    if (!map || record.synthetic || record.pending || !levelEditor.onRestart) return false;
+    if (!map || record.synthetic || record.pending || !editorHas('onRestart')) return false;
     if (width === map.width && height === map.height) return false;
     editorStrokeEnd();
     const before = editorMapSnapshot(record);
@@ -765,7 +1076,7 @@ function editorSetCell(layer, pos, gid)
     }
     const t = editorGidToTile(gid);
     live.setData(pos, t ? new TileLayerData(t.tile, t.direction, t.mirror, color) : new TileLayerData, true);
-    if (levelEditor.onTile)
+    if (editorHas('onTile'))
         levelEditor.onTile(live, pos.copy(), t?.tile);
     else if (live instanceof TileCollisionLayer && live.isSolid)
         live.setCollisionData(pos, gid ? 1 : 0); // as tileLayersLoad gives it
@@ -834,7 +1145,7 @@ function editorChanged(stroke)
     editorRedraw(stroke);
     for (const record of new Set(stroke.map(editorEntryRecord)))
         editorAutosave(record);
-    stroke.some((entry)=> entry.resize) && levelEditor.onRestart?.();
+    stroke.some((entry)=> entry.resize) && editorHas('onRestart') && levelEditor.onRestart();
 }
 
 // the tile layers a stroke touched draw again whole
@@ -1027,6 +1338,7 @@ let editorObjectDrag, editorObjectBox;
 function editorSelectLayer(layer)
 {
     editorStrokeEnd();
+    levelEditor.tool = undefined; // a tool of the game's own is put down
     editorLastCell = editorObjectDrag = editorRightPress = editorObjectBox = undefined; // presses stay on their layer
     editorSelectionDrag = undefined; // a move so far is kept, the stroke ended
     editorObjectSelection.clear();
@@ -1654,6 +1966,7 @@ const editorHelpLines =
 function editorHint()
 {
     if (keyIsDown('Space')) return 'Drag to pan';
+    if (editorGameTool()) return editorGameTool().hint || levelEditor.tool;
     if (editorObjectLayer)
         return editorObjectSelection.size ? 'Selection: drag moves · Delete removes · Ctrl+C copy · Ctrl+X cut · click to clear' :
             'Left place / select · drag moves · Right pick / drag select · Delete removes';
@@ -1722,6 +2035,8 @@ function editorPanelInit()
     button(undo, 'Undo', ()=> editorUndo(), 'Ctrl+Z');
     button(undo, 'Redo', ()=> editorUndo(true), 'Ctrl+Y');
     button(undo, 'Keys', ()=> editorHelp = !editorHelp, 'Every control, ?');
+    // the game's own tools, buttons and controls, near the top where the tools are
+    const game = editorElement('div', editorPanel);
 
     // a file that changed under its autosave
     const pending = editorElement('div', editorPanel, 'padding:4px;margin:4px 0;background:#630;border-radius:3px');
@@ -1808,9 +2123,10 @@ function editorPanelInit()
     const help = editorElement('div', editorPanel, 'color:#aaa;margin-top:4px;border-top:1px solid #444;padding-top:4px');
     for (const line of editorHelpLines)
         editorElement('div', help, 'margin:2px 0', line);
+    const gameHelp = editorElement('div', help);
     button(help, 'Close', ()=> editorHelp = false, '?');
 
-    editorPanelParts = {pendingUnfit, reset, advancedToggle, advanced, playFromLabel, playFrom, sizeRow, sizeX, sizeY, resize, restart, pending, layerRow, allLayers, turns, palette, brush, properties, status, storage, hint, help, layers: undefined};
+    editorPanelParts = {game, gameHelp, pendingUnfit, reset, advancedToggle, advanced, playFromLabel, playFrom, sizeRow, sizeX, sizeY, resize, restart, pending, layerRow, allLayers, turns, palette, brush, properties, status, storage, hint, help, layers: undefined};
 }
 
 // the palette's cell size in pixels and how many to a row
@@ -1969,15 +2285,15 @@ function editorPanelUpdate()
     p.hint.textContent = editorHint();
     p.help.style.display = editorHelp ? '' : 'none';
     p.storage.style.display = editorSaveFailed ? '' : 'none';
-    p.restart.style.display = levelEditor.onRestart ? '' : 'none';
+    p.restart.style.display = editorHas('onRestart') ? '' : 'none';
     p.advancedToggle.textContent = editorAdvanced ? 'Advanced ▾' : 'Advanced ▸';
     p.advanced.style.display = editorAdvanced ? '' : 'none';
-    p.playFromLabel.style.display = levelEditor.onPlayFrom ? 'flex' : 'none';
+    p.playFromLabel.style.display = editorHas('onPlayFrom') ? 'flex' : 'none';
     p.playFrom.checked = editorPlayFromMouse;
 
     // the level's size, shown until a field is being typed in; without the Restart hook it can not change
     const record = editorRecord(), map = record?.map;
-    const canResize = !!levelEditor.onRestart && !record?.synthetic && !record?.pending;
+    const canResize = editorHas('onRestart') && !record?.synthetic && !record?.pending;
     p.sizeRow.style.display = map ? 'flex' : 'none';
     if (map && !p.sizeRow.contains(document.activeElement))
     {
@@ -2047,6 +2363,7 @@ function editorIsTextField(target)
 function editorOnKeyDown(e)
 {
     if (!editorIsOpen || e.repeat || e.altKey || editorIsTextField(e.target)) return;
+    if (editorToolHeld) return; // the keys wait for a tool of the game's own to let go
     if (editorSelectionDrag && !(debugKey && e.code === debugKey))
     {
         // a key ends a selection drag where it is, an undo of its own, so Delete or undo acts on what is there;
@@ -2054,10 +2371,12 @@ function editorOnKeyDown(e)
         editorStrokeEnd();
         editorSelectionDrag = undefined;
     }
-    let key = e.key.length === 1 ? e.key.toLowerCase() : e.key;
-    if (key.length === 1 && !/[a-z?]/.test(key))
+    let key = e.key === ' ' ? 'Space' : e.key.length === 1 ? e.key.toLowerCase() : e.key;
+    if (key.length === 1 && !/[a-z?]/.test(key) && !levelEditor.keys[key])
         key = e.code?.match(/^Key([A-Z])$/)?.[1].toLowerCase() ?? key;
-    const action = (e.ctrlKey || e.metaKey ? editorCtrlKeys : editorKeys)[key];
+    // a key of the game's own first, it takes the place of one of the editor's
+    const ctrl = e.ctrlKey || e.metaKey, own = levelEditor.keys[(ctrl ? 'ctrl+' : '') + key];
+    const action = own ? (shift)=> own.action.call(levelEditor, shift) : (ctrl ? editorCtrlKeys : editorKeys)[key];
     if (action && action(e.shiftKey) !== false)
         e.preventDefault();
 }
@@ -2251,6 +2570,15 @@ function editorUpdate()
         return;
     }
 
+    // Escape while a tool of the game's own is held takes its press back, and stays in the editor
+    if (editorToolHeld && debugKey && keyWasPressed(debugKey))
+    {
+        inputClearKey(debugKey);
+        editorStrokeCancel();
+        editorToolHeld = false;
+        return;
+    }
+
     // in an editing session Escape, the debug key, switches between playing and editing; taken, so the debug
     // overlay waits till the session ends
     if (editorSession && debugKey && keyWasPressed(debugKey))
@@ -2281,7 +2609,7 @@ function editorUpdate()
     // keeps them while it is open
     for (let i = 1; !debugOverlay && i <= 9; ++i)
     {
-        if (!keyWasPressed('Digit' + i)) continue;
+        if (!keyWasPressed('Digit' + i) || levelEditor.keys[i]) continue; // a digit of the game's own is its
         inputClearKey('Digit' + i);
         const layer = editorLayers()[i - 1];
         layer && layer !== (editorObjectLayer ?? editorLayer) && editorSelectLayer(layer); // a drag does not carry across
@@ -2294,6 +2622,8 @@ function editorUpdate()
     editorApplyCamera();
 
     editorMouseOnPanel || (editorMouseScreen = mousePosScreen.copy());
+    editorCall('onUpdate');
+    if (editorToolUpdate(space)) return; // a tool of the game's own has the mouse
     if (editorObjectLayer)
         return editorUpdateObjects(space);
     const layer = editorLayer?.live.destroyed ? undefined : editorLayer, mouse = screenToWorld(editorMouseScreen);
@@ -2363,10 +2693,87 @@ function editorUpdate()
     }
 }
 
+// a tool of the game's own: if its press is held, and what was picked in the editor when it was turned on, since
+// picking a layer, a tile or an object type puts the game's tool down
+let editorToolHeld = false, editorToolName, editorToolPicked = [];
+
+// what a tool's callbacks are given: where the mouse is in the level, the cell under it on the selected tile
+// layer, and the keys held
+function editorToolAt()
+{
+    const layer = editorObjectLayer || editorLayer?.live.destroyed ? undefined : editorLayer;
+    const pos = screenToWorld(editorMouseScreen);
+    return {pos, cell: layer && !editorMouseOnPanel ? editorCellAt(layer.live, pos) || undefined : undefined,
+        ray: undefined, shift: keyIsDown('ShiftLeft') || keyIsDown('ShiftRight'),
+        ctrl: keyIsDown('ControlLeft') || keyIsDown('ControlRight')};
+}
+
+// the game's tool, when one is on: the left button is its, a press, a drag and a release one undo, the right
+// button takes a held press back; true when it has the mouse
+function editorToolUpdate(space)
+{
+    const picked = [editorLayer, editorObjectLayer, editorBrush, editorObjectBrush];
+    if (levelEditor.tool !== editorToolName)
+        editorToolName = levelEditor.tool, editorToolPicked = picked; // turned on, or off, by its key or button
+    else if (picked.some((value, i)=> value !== editorToolPicked[i]))
+        levelEditor.tool = editorToolName = undefined; // something of the editor's was picked
+    const tool = editorGameTool();
+    if (!tool)
+    {
+        editorToolHeld = false;
+        return false;
+    }
+    const at = editorToolAt();
+    editorHover = at.cell;
+    editorRightPress = undefined; // a right press from before the tool was on is not the editor's to finish
+    if (editorToolHeld && mouseWasPressed(2))
+    {
+        inputClearKey(2);
+        editorStrokeCancel();
+        editorToolHeld = false;
+    }
+    else if (mouseWasPressed(0) && !space && !editorMouseOnPanel)
+        editorToolHeld = tool.onPress?.(at) !== false;
+    else if (editorToolHeld && mouseIsDown(0))
+        tool.onDrag?.(at);
+    if (editorToolHeld && !mouseIsDown(0))
+    {
+        tool.onRelease?.(at);
+        editorStrokeEnd();
+        editorToolHeld = false;
+    }
+    return true;
+}
+
+// the 2D editor's edit functions, what levelEditor.edit2D gives a game's own keys, buttons and tools
+const editorEdit2D =
+{
+    get map() { return editorRecord()?.map; },
+    get layer() { return editorObjectLayer ? undefined : editorLayer?.live; },
+    get objects() { return editorObjectLayer ? editorObjectsCopy(editorObjectList(editorObjectLayer)) : []; },
+    get hover() { return editorHover && !editorObjectLayer ? editorHover.copy() : undefined; },
+    get selection() { return editorObjectSelection; },
+    paint(cell, tile, direction=0, mirror=false)
+    {
+        const layer = editorObjectLayer ? undefined : editorLayer, size = layer?.live.size;
+        if (!layer || layer.live.destroyed || layer.record.pending || !isVector2(cell)) return false;
+        const x = floor(cell.x), y = floor(cell.y);
+        if (x < 0 || y < 0 || x >= size.x || y >= size.y) return false;
+        editorPaint(layer, vec2(x, y), tile < 0 ? 0 : editorTileToGid(tile, direction & 3, mirror));
+        return true;
+    },
+    changeObjects(change) { return editorChangeObjects(editorObjectLayer, change); },
+    strokeEnd() { editorStrokeEnd(); },
+    strokeCancel() { editorStrokeCancel(); },
+    bulk(edit) { editorBulkEdit(edit); },
+    undo(redo=false) { return editorUndo(redo); },
+    toJSON() { const record = editorRecord(); return record ? editorMapJSON(record) : ''; },
+};
+
 // switch to play and have the game rebuild its level from the changed map, when it has a hook for that
 function editorRestart()
 {
-    if (!levelEditor.onRestart) return;
+    if (!editorHas('onRestart')) return;
     editorSetOpen(false); // ends a held stroke, and hands back the game's pause and camera, Escape comes back
     levelEditor.onRestart();
 }
@@ -2380,6 +2787,11 @@ function editorPreRender() { editorIsOpen && editorApplyCamera(); }
 function editorRender()
 {
     headlessMode || editorPanelUpdate();
+    if (!headlessMode && editorIsOpen && editorPanelParts)
+    {
+        editorGamePanel(editorPanelParts.game);
+        editorGameHelp(editorPanelParts.gameHelp);
+    }
     if (!editorIsOpen || headlessMode) return;
     const layer = editorLayer?.live.destroyed ? undefined : editorLayer;
     if (!layer && !editorObjectLayer) return;
@@ -2428,12 +2840,12 @@ function editorRender()
     if (editorSelection && !editorObjectLayer)
         outline(editorSelection.min, editorSelection.max.add(vec2(1)), hsl(.15, 1, .6), thin * 3);
     const last = editorLastPlaced, shift = keyIsDown('ShiftLeft') || keyIsDown('ShiftRight');
-    if (shift && editorHover && last?.layer === layer && !mouseIsDown(0))
+    if (shift && editorHover && last?.layer === layer && !mouseIsDown(0) && !editorGameTool())
         drawLine(live.pos.add(last.pos).add(vec2(.5)), live.pos.add(editorHover).add(vec2(.5)), thin * 2,
             hsl(.55, 1, .6, .6), undefined, 0, glEnable, false);
 
-    // the brush where it would paint, the Erase brush's cells in red
-    if (editorHover)
+    // the brush where it would paint, the Erase brush's cells in red; a tool of the game's own draws its own
+    if (editorHover && !editorGameTool())
     {
         const grid = editorStampGrid(layer, editorBrush), {width: w, height: h} = editorBrush;
         for (let y = h; y--;)
@@ -2451,7 +2863,24 @@ function editorRender()
     editorObjectLayer && editorRenderObjects(thin);
 }
 
-debug && engineAddPlugin(editorUpdate, editorRender);
+// the game's own drawing in the level, over the editor's: the editor's onDraw, and its tool's while one is on
+function editorRenderGame()
+{
+    if (!editorIsOpen) return;
+    editorCall('onDraw');
+    editorGameTool()?.onDraw?.(editorToolAt());
+}
+
+// the lines of the game's own keys in a panel's help, made again when they change
+function editorGameHelp(element)
+{
+    const lines = editorGameHelpLines(), key = lines.join('\n');
+    if (element.dataset.key === key) return;
+    element.dataset.key = key;
+    element.replaceChildren(...lines.map((line)=> editorElement('div', undefined, 'margin:2px 0', line)));
+}
+
+debug && engineAddPlugin(editorUpdate, ()=> { editorRender(); editorRenderGame(); });
 
 // the editor's own listeners for letter shortcuts and the wheel, the engine's input reads keys by position
 if (debug && globalThis.document?.addEventListener)