littlejsengine 1.24.3 → 1.26.0

package/src/engineEditor.js

@@ -14,7 +14,7 @@
 
 /**
  *  @callback EditorPlayFromCallback - Puts the player at a world position, for the level editor's Play from mouse
- *  @param {Vector2} pos - Where to start playing
+ *  @param {any} pos - Where to start playing, a Vector2 from the 2D editor and a Vector3 from the 3D one
  *  @memberof Editor
  */
 
@@ -32,25 +32,29 @@
  */
 
 /**
- *  @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
+ *  @template [P=Vector2]
+ *  @typedef {Object} EditorToolAt - What the level editor gives the callbacks of a tool of the game's own; P is
+ *    the type of pos, a Vector2 for a 2D tool, the default, and Vector3|undefined for a 3D one
+ *  @property {P} 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 {Ray3D|undefined} 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
+ *  @template [P=Vector2]
+ *  @typedef {Object} EditorTool - A tool of the game's own for the level editor, see LevelEditor.addTool; P is the
+ *    type of its pos, as EditorToolAt has it
  *  @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
+ *  @property {function(EditorToolAt<P>): 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
+ *  @property {function(EditorToolAt<P>): any} [onDrag] - Each frame it is held
+ *  @property {function(EditorToolAt<P>): any} [onRelease] - It was let go
+ *  @property {function(EditorToolAt<P>): any} [onDraw] - Each frame the tool is on, to draw its cursor or preview
  *  @memberof Editor
  */
 
@@ -143,7 +147,7 @@ class LevelEditor
         this.keys = {};
         /** @type {Array<{label: string, onClick: Function, title: string}>} */
         this.buttons = [];
-        /** @type {Object<string, EditorTool>} */
+        /** @type {Object<string, EditorTool<any>>} */
         this.tools = {};
     }
 
@@ -161,7 +165,7 @@ class LevelEditor
 
     /** 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 */
+     *  @param {any} pos - A Vector2 from the 2D editor, a Vector3 from the 3D one */
     onPlayFrom(pos) {}
 
     /** Called when the editor opens, to set or override */
@@ -244,8 +248,9 @@ class LevelEditor
      *    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
+     *  @template [P=Vector2]
      *  @param {string} name
-     *  @param {EditorTool} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
+     *  @param {EditorTool<P>} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
      *    false says the press was not the tool's */
     addTool(name, tool)
     {
@@ -260,7 +265,10 @@ class LevelEditor
     open()
     {
         if (editorOther?.wanted())
-            return editorOther.open();
+        {
+            editorOther.open();
+            return;
+        }
         if (!editorSession)
             editorCameraScale = cameraScale; // a new session starts at the game's zoom, a return keeps the editor's
         editorSession = true;
@@ -272,7 +280,10 @@ class LevelEditor
     close()
     {
         if (editorOther?.active())
-            return editorOther.close();
+        {
+            editorOther.close();
+            return;
+        }
         editorSession = false;
         editorSetOpen(false);
     }
@@ -462,6 +473,7 @@ function editorSetOpen(open)
     else
     {
         editorStrokeEnd();
+        editorAutosaveFlush(); // the game plays on with what the editor has kept, the stroke just ended too
         editorToolHeld = false;
         editorSelection = editorSelectionDrag = editorRightPress = editorObjectDrag = editorObjectBox = undefined;
         editorObjectSelection.clear();
@@ -533,6 +545,7 @@ const editorTileLayerData = (layers)=> editorTileLayers(layers).map((layer)=> la
 // panel to apply or drop, and one that already has the autosaved data, saved from the editor, drops it
 function editorMapRestore(map)
 {
+    editorAutosaveFlush(); // what an earlier map has waiting is written before this one reads the autosaves
     if (editorMapList.some((record)=> record.map === map)) return map; // loaded again, it has the changes
 
     // a map object seen before, its record retired when its layers went, gets it back as it was, its data has the
@@ -568,7 +581,8 @@ function editorMapRestore(map)
     const sameFile = saved.hash === record.hash || saved.savedHash === record.hash || !saved.width &&
         (saved.hash === editorMapHash(data, objects) || !saved.objects && saved.hash === editorMapHash(data));
     if ((saved.width ?? map.width) === map.width && (saved.height ?? map.height) === map.height &&
-        editorSameData(saved.layers, data) && editorSameData(saved.objects ?? [], objects))
+        editorSameData(saved.layers, data) && editorSameData(editorObjectsKept(saved.objects ?? [], objects.length), objects)
+        && !(saved.nextobjectid > (map.nextobjectid ?? 1)))
         editorDiscardPending(record);
     else if (!sameFile || !editorSavedFits(saved, data.length, saved.width ?? map.width, saved.height ?? map.height) ||
         !editorResizeMap(map, saved.width ?? map.width, saved.height ?? map.height) || !editorCopyData(data, saved.layers))
@@ -579,7 +593,7 @@ function editorMapRestore(map)
     }
     else
     {
-        editorRestoreObjects(map, saved);
+        editorRestoreObjects(map, saved, true);
         console.warn(`LittleJS editor: brought back unsaved edits to ${record.fileName}, ` +
             'Save in the editor (Esc then 0) writes them to the file');
         saved.stale && console.warn(`LittleJS editor: they are older than the last edits to ${record.fileName}, ` +
@@ -646,6 +660,8 @@ function editorLayerRecord(live)
     const record = {map, synthetic: true, fileName: 'level.json', layers: []};
     const layer = {record, source, live, color: WHITE};
     record.layers.push(layer);
+    // the records of layers made in code that are gone, as a game that makes them again on a restart leaves them
+    editorRetire((other)=> other.synthetic && other.layers.every((l)=> l.live.destroyed));
     editorMapList.push(record);
     return layer;
 }
@@ -742,6 +758,10 @@ function editorSetBaseline(record, written)
     const objects = editorObjectGroups(written.layers).map((group)=> group.objects ?? []);
     Object.assign(record, {original: data, originalObjects: objects, savedHash: editorMapHash(data, objects,
         editorMapLayout(written)), originalSize: {width: written.width, height: written.height}});
+    // an Objects layer the editor made is the file's own once a Save wrote it, so it stays when emptied after
+    const writtenIds = new Set(editorObjectGroups(written.layers).map((group)=> group.id));
+    for (const group of editorObjectGroups(record.map.layers))
+        writtenIds.has(group.id) && editorMadeGroups.delete(group);
     record.pending || editorAutosave(record); // edits waiting to be applied keep their autosave
 }
 
@@ -753,6 +773,7 @@ async function editorSave(record, pickAgain=false)
 {
     if (!record) return;
     editorStrokeEnd();
+    editorAutosaveFlush();
     const text = editorMapJSON(record); // the map as it is now, later edits wait for a later save
     // 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
@@ -770,6 +791,7 @@ async function editorSave(record, pickAgain=false)
 async function editorSaveText(record, text, pickAgain)
 {
     const picker = /** @type {any} */ (globalThis).showSaveFilePicker;
+    let written = false;
     if (picker)
     {
         try
@@ -785,10 +807,7 @@ async function editorSaveText(record, text, pickAgain)
             const writable = await record.fileHandle.createWritable();
             await writable.write(text);
             await writable.close();
-            // the browser gives the picked file's name but not its folder, so the name is what says it is the map's
-            if (record.fileHandle.name === record.fileName)
-                editorSetBaseline(record, JSON.parse(text));
-            return 'written';
+            written = true;
         }
         catch (error)
         {
@@ -798,6 +817,14 @@ async function editorSaveText(record, text, pickAgain)
             console.warn(`LittleJS editor: ${record.fileName} could not be written, downloaded instead`, error);
         }
     }
+    if (written)
+    {
+        // outside the write's catch, so an error here is its own and not a failed write that downloads a copy;
+        // the browser gives the picked file's name but not its folder, so the name is what says it is the map's
+        if (record.fileHandle.name === record.fileName)
+            editorSetBaseline(record, JSON.parse(text));
+        return 'written';
+    }
     saveText(text, record.fileName, 'application/json');
     return 'downloaded';
 }
@@ -818,7 +845,9 @@ function editorWriteSaves(saves, key, name=editorSaveName())
 {
     try
     {
-        localStorage.setItem(name, JSON.stringify(saves));
+        const text = JSON.stringify(saves);
+        editorAutosaveSize = text.length; // how much an autosave writes, which says whether the next one waits
+        localStorage.setItem(name, text);
         return editorSaveFailed = false;
     }
     catch { editorSaveFailed = true; }
@@ -888,22 +917,54 @@ const editorSavedFits = (saved, count, width, height)=> isArray(saved.layers) &&
 // remember a map's tile data and objects, or forget them when they are back to the file
 function editorAutosave(record)
 {
+    editorAutosaveWaiting.delete(record); // written now
     if (record.synthetic) return; // a layer made in code has no load to bring it back in, save it to a file
     const saves = editorSaves(), map = record.map, data = editorTileLayerData(map.layers);
     const objects = editorObjectGroups(map.layers).map((group)=> group.objects ?? []);
-    const original = record.originalObjects ?? [], kept = objects.slice();
-    while (kept.length > original.length && !kept[kept.length - 1].length)
-        kept.pop(); // an Objects layer the editor made, empty again, is not an edit
+    const original = record.originalObjects ?? [], kept = editorObjectsKept(objects, original.length);
     const size = record.originalSize, sameSize = map.width === size.width && map.height === size.height;
     // the map as it was loaded has nothing to keep; one a Save wrote is kept until a reload shows the file has it
     if (sameSize && editorSameData(data, record.original) && editorSameData(kept, original) && !record.savedHash)
         delete saves[record.key];
     else
         saves[record.key] = {hash: record.hash, savedHash: record.savedHash, width: map.width, height: map.height,
-            layers: data, objects, nextobjectid: map.nextobjectid};
+            layers: data, objects: kept, nextobjectid: map.nextobjectid};
     editorWriteSaves(saves, record.key);
 }
 
+// a map's lists of objects with the empty ones past count left off: an Objects layer the editor made, empty again,
+// is not an edit, and a Save leaves it out of the file too
+function editorObjectsKept(objects, count)
+{
+    const kept = objects.slice();
+    while (kept.length > count && !kept[kept.length - 1]?.length)
+        kept.pop();
+    return kept;
+}
+
+// an autosave writing more than this many characters, a big map's, waits until the edits stop for a moment, since
+// writing it after every stroke would cost more than the stroke; a small map's is written at once, as always
+const EDITOR_AUTOSAVE_WAIT_SIZE = 1e5;
+let editorAutosaveSize = 0, editorAutosaveTimer;
+const editorAutosaveWaiting = new Set;
+
+// autosave a map after an edit: at once when its autosave is small, or a second after the last of a run of edits
+function editorAutosaveSoon(record)
+{
+    if (editorAutosaveSize < EDITOR_AUTOSAVE_WAIT_SIZE)
+        return editorAutosave(record);
+    editorAutosaveWaiting.add(record);
+    clearTimeout(editorAutosaveTimer);
+    editorAutosaveTimer = setTimeout(editorAutosaveFlush, 1e3);
+}
+
+// write every autosave that is waiting, as the editor closes, the page hides, a map is saved or another loads
+function editorAutosaveFlush()
+{
+    clearTimeout(editorAutosaveTimer);
+    [...editorAutosaveWaiting].forEach(editorAutosave);
+}
+
 // paint every cell of a map's layers from a list of tile data, the tile layers of the map in order, and set its
 // object layers' objects from a list of them; data of another size resizes the map, which needs the Restart hook
 function editorPaintData(record, data, objects, width=record.map.width, height=record.map.height, keepUnknown=false)
@@ -1008,7 +1069,9 @@ function editorResizeMap(map, width, height)
     }
     // an object on the map before and off it after is dropped, one that was already off it stays
     const {tilewidth=1, tileheight=1} = map, oldHeight = map.height;
-    const inside = (object, w, h)=> object.x >= 0 && object.x < w * tilewidth && object.y > 0 && object.y <= h * tileheight;
+    // a tile object's y is its bottom, a point's or a rectangle's its top
+    const inside = (object, w, h)=> object.x >= 0 && object.x < w * tilewidth && (object.gid === undefined ?
+        object.y >= 0 && object.y < h * tileheight : object.y > 0 && object.y <= h * tileheight);
     for (const group of editorObjectGroups(map.layers))
     {
         group.objects &&= group.objects.filter((object)=>
@@ -1084,6 +1147,8 @@ let editorStroke;
 
 // during a big edit, the layers whose cell by cell redraws are held off, with the redraw each had of its own
 let editorHeldRedraws;
+// the live layers a change can only show by drawing them again whole, drawn when it is done
+const editorRedrawWhole = new Set;
 
 // make a big edit, a fill, clear, undo, apply or revert, with each layer's cell by cell redraws held off, a game's
 // tile callback's included; the stroke's end draws each layer it touched again whole
@@ -1110,6 +1175,11 @@ function editorSetCell(layer, pos, gid)
     source.data[index] = gid;
     if (live.destroyed) return before; // a layer the game let go of, the map still has the change
 
+    // a plain cell draws itself here; held draws, a game's onTile, which may change the cells around, and its own
+    // drawing over the layer show only when the whole layer draws again, once the change is done
+    if (editorHeldRedraws || editorHas('onTile') || live.onRedraw !== TileLayer.prototype.onRedraw)
+        editorRedrawWhole.add(live);
+
     if (editorHeldRedraws && !editorHeldRedraws.has(live))
     {
         editorHeldRedraws.set(live, live.hasOwnProperty('redrawTileData') ? live.redrawTileData : undefined);
@@ -1187,21 +1257,21 @@ function editorUndo(redo=false)
     editorChanged(stroke);
 }
 
-// after a change the tile layers it touched draw again whole, so a game's onRedraw decoration sees the new tiles,
-// and the maps it touched are autosaved; a resized map is made again by the game, with the editor staying open
+// after a change the tile layers it touched that need it draw again whole, and the maps it touched are autosaved;
+// a resized map is made again by the game, with the editor staying open
 function editorChanged(stroke)
 {
     editorRedraw(stroke);
     for (const record of new Set(stroke.map(editorEntryRecord)))
-        editorAutosave(record);
+        editorAutosaveSoon(record);
     stroke.some((entry)=> entry.resize) && editorHas('onRestart') && levelEditor.onRestart();
 }
 
-// the tile layers a stroke touched draw again whole
+// the tile layers a stroke touched that need it draw again whole
 function editorRedraw(stroke)
 {
     for (const layer of new Set(stroke.filter((entry)=> entry.layer).map((entry)=> entry.layer)))
-        layer.live.destroyed || layer.live.redraw();
+        editorRedrawWhole.delete(layer.live) && !layer.live.destroyed && layer.live.redraw();
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1370,13 +1440,17 @@ function editorObjectSetProperty(object, name, value, defaultValue)
         delete object.properties;
 }
 
-// copy saved objects into a map's object layers, making an Objects layer for any it saved that the map lacks
-function editorRestoreObjects(map, saved)
+// copy saved objects into a map's object layers, making an Objects layer for any it saved that the map lacks; from
+// an autosave, which keeps no empty list of a layer the editor made and no Save wrote, an empty one is of a layer a
+// Save wrote, the file's own, which stays when empty; an undo's snapshot keeps every list, so it does not say that
+function editorRestoreObjects(map, saved, fromAutosave=false)
 {
     const groups = editorObjectGroups(map.layers);
     (saved.objects ?? []).forEach((objects, i)=>
     {
-        (groups[i] ?? editorNewObjectGroup(map)).objects = editorObjectsCopy(objects);
+        const group = groups[i] ?? editorNewObjectGroup(map);
+        group.objects = editorObjectsCopy(objects);
+        fromAutosave && !objects.length && editorMadeGroups.delete(group);
     });
     if (saved.nextobjectid > (map.nextobjectid ?? 1))
         map.nextobjectid = saved.nextobjectid;
@@ -1708,6 +1782,40 @@ function editorGidMirror(gid)
     return t ? editorTileToGid(t.tile, (4 - t.direction) % 4, !t.mirror) : gid;
 }
 
+// a stamp's object turned a quarter clockwise with it: its place by the stamp, its body by its own rotation, which
+// Tiled turns clockwise about the object's place, so the place needs no other move
+function editorStampObjectTurn(entry, width)
+{
+    const offset = vec2(entry.offset.y, width - entry.offset.x), object = entry.object;
+    return {...entry, offset, ...(object && {object: {...object, rotation: ((object.rotation || 0) + 90) % 360}})};
+}
+
+// a stamp's object mirrored left to right with it: its rotation the other way, a polygon's points mirrored about its
+// place, a tile object's image flipped, and a box, ellipse, text or tile, placed by a corner, placed by the corner
+// that becomes it, its width along its turn from the mirrored place; mirrored twice it is as it was
+function editorStampObjectMirror(entry, width)
+{
+    const offset = vec2(width - entry.offset.x, entry.offset.y), object = entry.object;
+    if (!object) return {...entry, offset};
+    const mirrored = {...object, rotation: object.rotation ? -object.rotation : 0};
+    const points = (list)=> list.map((p)=> ({...p, x: -p.x}));
+    if (object.polygon || object.polyline)
+    {
+        object.polygon && (mirrored.polygon = points(object.polygon));
+        object.polyline && (mirrored.polyline = points(object.polyline));
+    }
+    else
+    {
+        // Tiled's pixels run down, the stamp's cells up
+        const angle = (object.rotation || 0) * PI / 180, w = object.width || 0, {x: tw, y: th} = entry.tileSize ?? vec2(1);
+        offset.x -= w * cos(angle) / tw;
+        offset.y -= w * sin(angle) / th;
+    }
+    if (object.gid)
+        mirrored.gid = (object.gid ^ 0x80000000) >>> 0; // Tiled's flip across
+    return {...entry, offset, object: mirrored};
+}
+
 // a stamp turned a quarter turn clockwise on screen, or back, its cells, their tiles and its objects together; cell
 // (x, y) goes to (y, width - 1 - x), so the bottom row becomes the left column, its left end at the top
 function editorStampTurn(stamp, back=false)
@@ -1715,7 +1823,7 @@ function editorStampTurn(stamp, back=false)
     for (let turns = back ? 3 : 1; turns--;)
     {
         const {width, height} = stamp;
-        const objects = stamp.objects?.map((object)=> ({...object, offset: vec2(object.offset.y, width - object.offset.x)}));
+        const objects = stamp.objects?.map((entry)=> editorStampObjectTurn(entry, width));
         stamp = {width: height, height: width, grids: stamp.grids.map((grid)=>
         {
             const turned = [];
@@ -1732,7 +1840,7 @@ function editorStampTurn(stamp, back=false)
 function editorStampMirror(stamp)
 {
     const {width, height} = stamp;
-    const objects = stamp.objects?.map((object)=> ({...object, offset: vec2(width - object.offset.x, object.offset.y)}));
+    const objects = stamp.objects?.map((entry)=> editorStampObjectMirror(entry, width));
     return {width, height, grids: stamp.grids.map((grid)=>
     {
         const mirrored = [];
@@ -1864,8 +1972,9 @@ function editorClear()
     editorStrokeEnd();
 }
 
-// the objects of a map's object layers inside a tile area, each {group, type, offset, object}: the index of its
-// object layer, its offset from the area's bottom left corner, and a copy of it, as a stamp keeps them
+// the objects of a map's object layers inside a tile area, each {group, type, offset, object, tileSize}: the index of
+// its object layer, its offset from the area's bottom left corner, a copy of it, and the map's tile size in pixels,
+// which a mirror reads its width in cells by, as a stamp keeps them
 function editorAreaObjects(layer, area)
 {
     const corner = layer.live.pos.add(area.min), far = layer.live.pos.add(area.max).add(vec2(1));
@@ -1874,7 +1983,7 @@ function editorAreaObjects(layer, area)
         const ids = new Set(editorObjectsIn(objectLayer, corner, far));
         return (objectLayer.group?.objects ?? []).filter((object)=> ids.has(object.id)).map((object)=>
             ({group, type: object.type || object.class, offset: editorObjectPos(layer.record, object).subtract(corner),
-            object: editorObjectsCopy(object)}));
+            object: editorObjectsCopy(object), tileSize: vec2(layer.record.map.tilewidth || 1, layer.record.map.tileheight || 1)}));
     });
 }
 
@@ -2266,7 +2375,8 @@ function editorPaletteDrawObjects(canvas)
         else
         {
             context.fillStyle = '#ccc';
-            context.fillText(name.slice(0, 4), x + cell / 2, y + cell / 2);
+            const label = textGraphemes(name).slice(0, 4).join(''); // whole characters, never half an emoji
+            context.fillText(label, x + cell / 2, y + cell / 2);
         }
         if (editorObjectBrush?.length !== 1 || editorObjectBrush[0].type !== name) return;
         context.strokeStyle = '#4af';
@@ -2963,5 +3073,8 @@ debug && engineAddPlugin(editorUpdate, ()=> { editorRender(); editorRenderGame()
 if (debug && globalThis.document?.addEventListener)
 {
     document.addEventListener('keydown', editorOnKeyDown);
+    // a page going away writes what is waiting, the last event it is sure to get
+    document.addEventListener('visibilitychange', ()=> document.hidden && editorAutosaveFlush());
+    globalThis.addEventListener?.('pagehide', editorAutosaveFlush);
     document.addEventListener('wheel', editorOnWheel, {passive: true});
 }

package/src/engineExport.js

@@ -53,9 +53,6 @@ export
     debugClear,
     debugScreenshot,
     debugShowErrors,
-    debugVideoCaptureStart,
-    debugVideoCaptureStop,
-    debugVideoCaptureIsActive,
 
     // Settings
     cameraPos,

package/src/engineInput.js

@@ -198,9 +198,11 @@ function inputClear()
  *  @memberof Input */
 function keyIsDown(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyIsDown: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyIsDown: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyIsDown: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 1) && !inputCaptureHides(device);
 }
 
@@ -211,9 +213,11 @@ function keyIsDown(key, device=0)
  *  @memberof Input */
 function keyWasPressed(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyWasPressed: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyWasPressed: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyWasPressed: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 2) && !inputCaptureHides(device);
 }
 
@@ -224,9 +228,11 @@ function keyWasPressed(key, device=0)
  *  @memberof Input */
 function keyWasReleased(key, device=0)
 {
-    ASSERT(isStringLike(key), 'key must be a number or string');
-    ASSERT(typeof key !== 'string' || key.length > 1, "keys are codes like 'KeyW' or 'Space', not characters");
-    ASSERT(device > 0 || typeof key !== 'number' || key < 5, 'use code string for keyboard');
+    ASSERT(isStringLike(key), 'keyWasReleased: key must be a code like \'KeyA\' or a number', key);
+    ASSERT(typeof key !== 'string' || key.length > 1,
+        "keyWasReleased: keys are codes like 'KeyW' or 'Space', not characters", key);
+    ASSERT(device > 0 || typeof key !== 'number' || key < 5,
+        "keyWasReleased: keyboard keys are codes like 'KeyA' or 'Space', the numbers 0 to 4 are mouse buttons", key);
     return !!(inputData[device]?.[key] & 4) && !inputCaptureHides(device);
 }
 
@@ -248,35 +254,32 @@ function keyDirection(up='ArrowUp', down='ArrowDown', left='ArrowLeft', right='A
 }
 
 /** Returns true if mouse button is down
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
 function mouseIsDown(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseIsDown: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyIsDown(button);
 }
 
 /** Returns true if mouse button was pressed
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
 function mouseWasPressed(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseWasPressed: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyWasPressed(button);
 }
 
 /** Returns true if mouse button was released
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
 function mouseWasReleased(button)
 {
-    ASSERT(isNumber(button), 'mouse button must be a number');
+    ASSERT(isNumber(button), 'mouseWasReleased: button is 0 (left), 1 (middle) or 2 (right)', button);
     return keyWasReleased(button);
 }
 
@@ -498,21 +501,24 @@ function inputInit()
     {
         // fix stalled audio requiring user interaction, a keyboard only game has no other gesture
         if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-            audioContext.resume();
+            audioResume();
 
         // keys typed into an html text field are the player's typing, not game input;
         // a key already down still releases on keyup, which only lets go of keys that are down
         const typing = isTextInput(e.target) || isTextInput(document.activeElement);
-        if (!e.repeat && !typing)
+        // a key already held, a keydown the browser did not mark as a repeat, is not pressed again, but with Cmd down
+        // it is: a Mac sends no keyup for a key let go while Cmd is held, so each tap of Cmd+Z comes as a keydown alone
+        if (!e.repeat && !typing && (!inputKeysHeld.has(e.code) || e.metaKey))
         {
             inputKeysHeld.add(e.code);
-            // an arrow its alias already holds down is not pressed again, like its release waits for both
+            // an arrow its alias already holds down is not pressed again, like its release waits for both; a release
+            // earlier this frame is kept, so a quick release and press reads as both
             if (!(inputWASDEmulateDirection && inputKeysHeld.has(inputArrowToWASD[e.code]) && inputData[0][e.code] & 1))
-                inputData[0][e.code] = 3;
+                inputData[0][e.code] = 3 | inputData[0][e.code] & 4;
             // an alias presses its arrow's slot too, unless the arrow itself already holds it down
             const remap = remapKey(e.code);
             if (remap !== e.code && !(inputData[0][remap] & 1))
-                inputData[0][remap] = 3;
+                inputData[0][remap] = 3 | inputData[0][remap] & 4;
         }
 
         // try to prevent default browser handling of input
@@ -584,13 +590,13 @@ function inputInit()
 
         // fix stalled audio requiring user interaction
         if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-            audioContext.resume();
+            audioResume();
 
         // a press in the bars around a letterboxed canvas is not one on its edge; a drag out of it still moves; under
         // pointer lock the mouse stays where the lock began, which may be in a bar, and every click is the game's
         if (!pointerLockIsActive() && !inCanvas(e.x, e.y))
             return;
-        inputData[0][e.button] = 3;
+        inputData[0][e.button] = 3 | inputData[0][e.button] & 4; // a release earlier this frame is kept
 
         const mousePosScreenLast = mousePosScreen;
         mousePosScreen = mouseEventToScreen(vec2(e.x,e.y));
@@ -684,7 +690,7 @@ function inputInit()
 
             // fix stalled audio requiring user interaction
             if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-                audioContext.resume();
+                audioResume();
 
             // when the touch gamepad is enabled it owns touch input: suppress the
             // touch->mouse passthrough entirely unless touchGamepadPassthrough is set
@@ -744,7 +750,7 @@ function inputInit()
                     else if (inputWasTouching && touch.identifier === inputTouchIdentifier)
                         mouseDeltaScreen = mouseDeltaScreen.add(mousePosScreen.subtract(mousePosScreenLast));
                     else if (pressTouch && inCanvas(pressTouch.clientX, pressTouch.clientY))
-                        inputData[0][button] = 3; // a tap in the bars around the canvas is not a press
+                        inputData[0][button] = 3 | inputData[0][button] & 4; // a tap in the bars is not a press
                     // the finger left after a pinch moves the mouse from where it is, with no jump and no press
                     inputTouchIdentifier = pinching ? undefined : touch.identifier;
                 }
@@ -1449,7 +1455,7 @@ function touchGamepadPointerDown(e, zone)
 
     // resume audio on first interaction
     if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-        audioContext.resume();
+        audioResume();
 
     // while paused, any touch is the start button; a control belongs to the first finger on it until that
     // finger lifts, so a second finger landing on the same one neither takes it over nor lets it go