littlejsengine 1.24.2 → 1.25.0

package/src/engineAudio.js

@@ -20,6 +20,9 @@
  *  @memberof Audio */
 let audioContext = typeof AudioContext == 'undefined' ? undefined : new AudioContext;
 
+// resume the audio, a refusal caught so it is not an uncaught error in the console, the next gesture tries again
+function audioResume() { audioContext?.resume()?.catch?.(()=> {}); }
+
 /** Master gain node for all audio to pass through, made at load so effects can connect to it any time
  *  @type {GainNode}
  *  @memberof Audio */
@@ -76,6 +79,7 @@ function audioSetSession()
 let audioSuspendedWhenHidden = false;
 function audioVisibilityChange()
 {
+    if (!audioContext) return; // a browser with no audio has none to pause
     if (document.hidden)
     {
         if (!soundPauseWhenHidden || audioContext.state != 'running') return;
@@ -85,7 +89,7 @@ function audioVisibilityChange()
     else if (audioSuspendedWhenHidden)
     {
         audioSuspendedWhenHidden = false;
-        audioContext.resume();
+        audioResume();
     }
 }
 
@@ -224,7 +228,7 @@ function audioParamRamp(param, value, fadeTime=0)
 class Sound
 {
     /** Create a sound object and cache the audio for later use
-     *  @param {string|URL|Array} [asset] - Filename or URL of an audio file, or a zzfx array
+     *  @param {string|URL|Array<number|undefined>} [asset] - Filename or URL of an audio file, or a zzfx array
      *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds it overrides the array's own randomness, which is used if undefined
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
@@ -232,7 +236,7 @@ class Sound
      */
     constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
-        if (!soundEnable || headlessMode)
+        if (!soundEnable || headlessMode || !audioContext) // a browser with no audio makes none either
         {
             // no sound is made: it counts as loaded, so a game that waits for its sounds goes on
             this.loadedPercent = 1;
@@ -302,8 +306,8 @@ class Sound
             // load the audio file, a URL object as bundlers give works like its string;
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
-            engineAddLoad(this.loadSound(filename).catch(e=>
-                LOG('Sound load failed for', filename, '-', e.message))); // startup waits for it
+            engineAddLoad(this.loadSound(filename).catch(e=> // startup waits for it, and a release build says why too
+                console.warn('Sound load failed for', filename, '-', e?.message ?? e)));
         }
     }
 
@@ -795,7 +799,7 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {number}   [rate] - The playback rate to use
  *  @param {number}   [pan] - How much to apply stereo panning
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
- *  @param {number}   [sampleRate=44100] - Sample rate for the sound
+ *  @param {number}   [sampleRate=audioDefaultSampleRate] - Sample rate for the sound
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
  *  @param {number}   [offset] - Where to start in the sound, in its own seconds whatever the rate
  *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
@@ -812,7 +816,7 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
         // fix stalled audio, don't build a buffer that can't be played;
         // but a context suspended because the page is hidden stays suspended until it shows
         if (!audioSuspendedWhenHidden)
-            audioContext.resume();
+            audioResume();
         return;
     }
 
@@ -822,7 +826,7 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
 
 /** Copy arrays of samples into a new audio buffer
  *  @param {Array}  sampleChannels - Array of arrays of samples (for stereo playback)
- *  @param {number} [sampleRate=44100] - Sample rate for the sound
+ *  @param {number} [sampleRate=audioDefaultSampleRate] - Sample rate for the sound
  *  @return {AudioBuffer} - The audio buffer holding the samples
  *  @memberof Audio */
 function createAudioBuffer(sampleChannels, sampleRate=audioDefaultSampleRate)
@@ -857,7 +861,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
         // fix stalled audio, this sound won't be able to play;
         // but a context suspended because the page is hidden stays suspended until it shows
         if (!audioSuspendedWhenHidden)
-            audioContext.resume();
+            audioResume();
         return;
     }
 

package/src/engineBuild.mjs

@@ -289,17 +289,64 @@ function typeScriptBuildStep(filename)
     try
     {
         const tsFilename = join(BUILD_FOLDER, `${ENGINE_NAME}.d.ts`);
-        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --outFile "${tsFilename}"`);
+        // strictNullChecks keeps undefined in the types, where tsc would drop it from accessors and object types
+        // whatever the JSDoc says, so a game in strict mode can set render3D.shader = undefined and is told a
+        // flare may be missing; a game not in strict mode reads the same types as before
+        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --strictNullChecks --outFile "${tsFilename}"`);
 
         // Make declare module part use the package name littlejsengine
         let fileContent = fs.readFileSync(tsFilename, 'utf8');
         fileContent = fileContent.replace(`${ENGINE_NAME}\.esm`, 'littlejsengine')
-        fs.writeFileSync(tsFilename, fileContent);
+        fs.writeFileSync(tsFilename, typeScriptOptionalTidy(fileContent));
 
     }
     catch (e) { handleError(e, 'Failed to run TypeScript build step!'); }
 };
 
+// strictNullChecks writes an optional parameter or field as x?: T | undefined, which is the same as x?: T, so the
+// redundant | undefined is taken off: each ?: is followed to the end of its type, the first , ; ) or line end outside
+// brackets, and only that type is changed; a required x: T | undefined keeps it
+function typeScriptOptionalTidy(text)
+{
+    let out = '', i = 0;
+    for (let at; (at = text.indexOf('?: ', i)) >= 0;)
+    {
+        const start = at + 3;
+        let end = start, depth = 0;
+        for (; end < text.length; ++end)
+        {
+            const c = text[end];
+            if (c === '=' && text[end + 1] === '>') { ++end; continue; } // an arrow is not a closing bracket
+            if ('([{<'.includes(c)) ++depth;
+            else if (')]}>'.includes(c) && depth) --depth;
+            else if (!depth && (',;)\n'.includes(c))) break;
+        }
+        let type = typeScriptOptionalTidy(text.slice(start, end)); // and the optional fields of a record type in it
+        if (type.endsWith(' | undefined'))
+        {
+            type = type.slice(0, -12);
+            // a function type was wrapped for the union, (() => void) | undefined, and needs it no more
+            if (type[0] === '(' && typeScriptCloseOf(type, 0) === type.length - 1)
+                type = type.slice(1, -1);
+        }
+        out += text.slice(i, start) + type;
+        i = end;
+    }
+    return out + text.slice(i);
+}
+
+// the index of the bracket that closes the one at start
+function typeScriptCloseOf(text, start)
+{
+    let depth = 0;
+    for (let k = start; k < text.length; ++k)
+    {
+        if (text[k] === '(') ++depth;
+        else if (text[k] === ')' && !--depth) return k;
+    }
+    return -1;
+}
+
 // display the error and exit
 function handleError(e,message)
 {

package/src/engineDebug.js

@@ -94,7 +94,7 @@ function LOG(...output) { console.log(...output); }
 
 /** Draw a debug rectangle in world space, or on the screen with screenSpace
  *  @param {Vector2} pos
- *  @param {Vector2} [size=vec2(0)]
+ *  @param {Vector2} [size=vec2()]
  *  @param {Color|string} [color]
  *  @param {number} [time]
  *  @param {number} [angle]
@@ -766,7 +766,8 @@ function debugRenderPost() { debugVideoCaptureIsActive() && debugVideoCaptureUpd
 let debugVideoCapture, debugVideoCaptureIcon;
 
 /** Check if video capture is active
- *  @memberof Debug */
+ *  @memberof Debug
+ *  @return {boolean} */
 function debugVideoCaptureIsActive() { return !!debugVideoCapture; }
 
 /** Start capturing video

package/src/engineDraw.js

@@ -105,7 +105,7 @@ function isBlack(c) { return c.r <= 0 && c.g <= 0 && c.b <= 0 && c.a <= 0; }
  * Create a tile info object using a grid based system
  * - This can take vecs or floats for easier use and conversion
  * - If an index is passed in, the tile size and index will determine the position
- * @param {Vector2|number} [index=0] - Index of the tile in 1d or 2d form
+ * @param {Vector2|number} [index] - Index of the tile in 1d or 2d form
  * @param {Vector2|number} [size] - Size of tile in pixels
  * @param {TextureInfo|number} [texture] - Texture index or info to use
  * @param {number} [padding] - How many pixels padding around tiles
@@ -134,10 +134,13 @@ function tile(index=0, size=tileDefaultSize, texture=0, padding=tileDefaultPaddi
     // create tile info object
     const textureInfo = typeof texture === 'number' ?
         textureInfos[texture] : texture;
-    if (headlessMode && !textureInfo?.size.x)
-        return new TileInfo(new Vector2, size.copy(), textureInfo, padding, bleed); // no image loaded, no place in it
-    ASSERT(textureInfo instanceof TextureInfo, 'tile texture is not loaded');
-    ASSERT(textureInfo.size.x > 0, 'tile texture is not loaded');
+    if (!textureInfo?.size.x)
+    {
+        // no image: headless loads none and keeps the size; an image that failed to load, whose warning named it, gives
+        // a tile of no size, which draws nothing; a slot never given an image is a mistake a debug build points out
+        ASSERT(headlessMode || textureInfo instanceof TextureInfo, 'tile texture is not loaded', texture);
+        return new TileInfo(new Vector2, headlessMode ? size.copy() : new Vector2, textureInfo, padding, bleed);
+    }
 
     // get the position of the tile
     const sizePaddedX = size.x + padding*2;
@@ -586,10 +589,10 @@ class Shader
  *  @param {TileInfo} [tileInfo] - Tile info to use, untextured if undefined
  *  @param {Color}    [color=WHITE] - Color to modulate with
  *  @param {number}   [angle] - Angle to rotate by
- *  @param {boolean}  [mirror] - Is image flipped along the Y axis?
+ *  @param {boolean}  [mirror] - Is the image flipped left to right?
  *  @param {Color}    [additiveColor] - Additive color to be applied if any
  *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
- *  @param {boolean}  [screenSpace=drawScreenSpace] - Are the pos and size are in screen space?
+ *  @param {boolean}  [screenSpace=drawScreenSpace] - Are the pos and size in screen space?
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
  *  @memberof Draw */
 function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
@@ -605,8 +608,8 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
     if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
 
     const textureInfo = tileInfo?.textureInfo;
-    if (textureInfo && !(tileInfo.size.x && tileInfo.size.y))
-        return; // a tile with no area draws nothing, like a sprite still loading
+    if (textureInfo && !(tileInfo.size.x && tileInfo.size.y && textureInfo.size.x))
+        return; // a tile with no area draws nothing, like a sprite still loading, and nor does an image that failed
     const bleed = tileInfo?.bleed ?? 0;
     if (useWebGL && glEnable)
     {
@@ -700,7 +703,7 @@ function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
  *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
+function drawRectGradient(pos, size=vec2(1), colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -759,9 +762,9 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, an
  *  @param {Vector2}  pos          - Center of the rect in world space
  *  @param {Vector2}  size         - Size of the rect in world space
  *  @param {Vector2}  wrapCount    - How many times the texture repeats (x, y)
- *  @param {TextureInfo|number} [texture=0] - TextureInfo or texture index into textureInfos
+ *  @param {TextureInfo|number} [texture] - TextureInfo or texture index into textureInfos
  *  @param {Color}    [color=WHITE] - Color to modulate with
- *  @param {number}   [angle=0] - Angle to rotate by
+ *  @param {number}   [angle] - Angle to rotate by
  *  @param {Color}    [additiveColor] - Additive color to be applied if any
  *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
  *  @param {boolean}  [screenSpace=drawScreenSpace] - Are pos and size in screen space?
@@ -1103,9 +1106,9 @@ function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineC
 
 /** Draw colored circle using passed in point
  *  @param {Vector2} pos
- *  @param {number}  [size=1] - Diameter
+ *  @param {number}  [size] - Diameter
  *  @param {Color}   [color=WHITE]
- *  @param {number}  [lineWidth=0]
+ *  @param {number}  [lineWidth]
  *  @param {Color}   [lineColor=BLACK]
  *  @param {boolean} [useWebGL=glEnable]
  *  @param {boolean} [screenSpace=drawScreenSpace]
@@ -1200,7 +1203,7 @@ function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLE
  *  - If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
  *  - Stacking gradients at the exact same position may show a faint vertical artifact
  *  @param {Vector2} pos
- *  @param {number}  [size=1] - Diameter
+ *  @param {number}  [size] - Diameter
  *  @param {Color}   [colorInner=WHITE]
  *  @param {Color}   [colorOuter=CLEAR_WHITE]
  *  @param {boolean} [useWebGL=glEnable]
@@ -1265,7 +1268,7 @@ function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpac
  *  @param {Color}   [color=WHITE]
  *  @param {number}  [lineWidth]
  *  @param {Color}   [lineColor=BLACK]
- *  @param {'left'|'center'|'right'} [textAlign='center']
+ *  @param {'left'|'center'|'right'} [textAlign]
  *  @param {string}  [font=fontDefault]
  *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
@@ -1695,8 +1698,7 @@ function bakeTintedImage(image, color, additiveColor)
  *  @param {number} dHeight
  *  @param {Color} color
  *  @param {Color} [additiveColor]
- *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding
- *  @memberof Draw */
+ *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding */
 function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight, color, additiveColor, bleed=0)
 {
     const sx2 = bleed;

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);
     }
@@ -1084,6 +1095,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 +1123,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,8 +1205,7 @@ 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);
@@ -1197,11 +1214,11 @@ function editorChanged(stroke)
     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();
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1708,6 +1725,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 +1766,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 +1783,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 +1915,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 +1926,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)}));
     });
 }
 

package/src/engineInput.js

@@ -248,7 +248,6 @@ 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 */
@@ -259,7 +258,6 @@ function mouseIsDown(button)
 }
 
 /** Returns true if mouse button was pressed
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
@@ -270,7 +268,6 @@ function mouseWasPressed(button)
 }
 
 /** Returns true if mouse button was released
- *  @function
  *  @param {number} button
  *  @return {boolean}
  *  @memberof Input */
@@ -498,7 +495,7 @@ 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
@@ -584,10 +581,11 @@ 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
-        if (!inCanvas(e.x, e.y))
+        // 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;
 
@@ -683,7 +681,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
@@ -1004,9 +1002,11 @@ function inputUpdate()
                     (gamepadIsDown(12,i)&&1) - (gamepadIsDown(13,i)&&1));
             }
 
-            // copy dpad to left analog stick when pressed
+            // copy dpad to left analog stick when pressed; a gamepad with no sticks has that one, at rest when not
             if (gamepadDirectionEmulateStick && (dpad.x || dpad.y))
                 sticks[0] = dpad.clampLength();
+            else if (gamepadDirectionEmulateStick && !sticks.length)
+                sticks[0] = vec2();
         }
 
         // disable touch gamepad if using real gamepad
@@ -1446,7 +1446,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

package/src/engineMath.js

@@ -413,8 +413,10 @@ function lineTest(posStart, posEnd, testFunction, normal)
     const totalLength = (dx*dx + dy*dy)**.5;
     if (!totalLength) return;
 
-    // current integer cell we are in
+    // current integer cell we are in, the one below a whole start heading down the grid, which it goes into
     const pos = posStart.floor();
+    if (dx < 0 && pos.x === posStart.x) --pos.x;
+    if (dy < 0 && pos.y === posStart.y) --pos.y;
 
     // normalize ray direction
     const dirX = dx / totalLength;
@@ -687,11 +689,6 @@ function isVector2(v) { return v instanceof Vector2 && v.isValid(); }
 // vector2 asserts
 function ASSERT_VECTOR2_VALID(v) { ASSERT(isVector2(v), 'Vector2 is invalid.', v); }
 function ASSERT_NUMBER_VALID(n) { ASSERT(isNumber(n), 'Number is invalid.', n); }
-function ASSERT_VECTOR2_NORMAL(v)
-{
-    ASSERT_VECTOR2_VALID(v);
-    ASSERT(abs(v.lengthSquared()-1) < .01, 'Vector2 is not normal.', v);
-}
 
 /**
  * 2D Vector object with vector math library

package/src/engineObject.js

@@ -483,19 +483,23 @@ class EngineObject
     }
 
     /** Convert from local space to world space
-     *  @param {Vector2} pos - local space point */
+     *  @param {Vector2} pos - local space point
+     *  @return {Vector2} */
     localToWorld(pos) { return this.pos.add(pos.rotate(this.angle)); }
 
     /** Convert from world space to local space
-     *  @param {Vector2} pos - world space point */
+     *  @param {Vector2} pos - world space point
+     *  @return {Vector2} */
     worldToLocal(pos) { return pos.subtract(this.pos).rotate(-this.angle); }
 
     /** Convert from local space to world space for a vector (rotation only)
-     *  @param {Vector2} vec - local space vector */
+     *  @param {Vector2} vec - local space vector
+     *  @return {Vector2} */
     localToWorldVector(vec) { return vec.rotate(this.angle); }
 
     /** Convert from world space to local space for a vector (rotation only)
-     *  @param {Vector2} vec - world space vector */
+     *  @param {Vector2} vec - world space vector
+     *  @return {Vector2} */
     worldToLocalVector(vec) { return vec.rotate(-this.angle); }
 
     /** Called to check if a tile collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.
@@ -634,11 +638,6 @@ class EngineObject
         this.collideRaycast = collideRaycast;
     }
 
-    /** @deprecated since 1.20, use collideLevel
-     *  @type {boolean} */
-    get collideTiles() { return this.collideLevel; }
-    set collideTiles(collide) { this.collideLevel = collide; }
-
     /** Returns string containing info about this object for debugging
      *  @return {string} */
     toString()