littlejsengine 1.23.0 → 1.23.1

package/dist/littlejs.esm.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.23.0';
+const engineVersion = '1.23.1';
 
 /** Frames per second to update
  *  @type {number}
@@ -3169,295 +3169,295 @@ const PURPLE = debugProtectConstant(rgb(.5,0,1));
  *  @type {Color}
  *  @memberof Math */
 const MAGENTA = debugProtectConstant(rgb(1,0,1));
-/**
- * LittleJS Utility Classes and Functions
- * - Timer - tracks time automatically with support for pause and real-time modes
- * - Time formatting helper
- * - JSON file fetching
- * - File saving (text, canvas, data URLs)
- * - Native share dialog support
- * - Local storage save data management
- * - Value noise (1D and 2D)
- * @namespace Utilities
- */
-
-/**
- * Timer object tracks how long has passed since it was set
- * @memberof Engine
- * @example
- * let a = new Timer;    // creates a timer that is not set
- * a.set(3);             // sets the timer to 3 seconds
- *
- * let b = new Timer(1); // creates a timer with 1 second left
- * b.unset();            // unset the timer
- */
-class Timer
-{
-    /** Create a timer object set time passed in
-     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
-     *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
-    constructor(timeLeft, useRealTime=false)
-    {
-        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
-        this.useRealTime = useRealTime;
-        const globalTime = this.getGlobalTime();
-        /** @type {number|undefined} */
-        this.time = timeLeft === undefined ? undefined : globalTime + timeLeft;
-        /** @type {number|undefined} */
-        this.setTime = timeLeft;
-    }
-
-    /** Set the timer with seconds passed in
-     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
-    set(timeLeft=0)
-    {
-        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
-        const globalTime = this.getGlobalTime();
-        this.time = globalTime + timeLeft;
-        this.setTime = timeLeft;
-    }
-
-    /** Set if the timer should keep running even when the game is paused
-     *  @param {boolean} [useRealTime] */
-    setUseRealTime(useRealTime=true)
-    {
-        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
-        this.useRealTime = useRealTime;
-    }
-
-    /** Unset the timer */
-    unset() { this.time = undefined; }
-
-    /** Returns true if set
-     * @return {boolean} */
-    isSet() { return this.time !== undefined; }
-
-    /** Returns true if set and has not elapsed
-     * @return {boolean} */
-    active() { return this.getGlobalTime() < this.time; }
-
-    /** Returns true if set and elapsed
-     * @return {boolean} */
-    elapsed() { return this.getGlobalTime() >= this.time; }
-
-    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
-     * @return {number} */
-    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
-
-    /** Get percentage elapsed based on time it was set to, returns 0 if not set.
-     *  Zero-duration timers report 1 (already elapsed).
-     * @return {number} */
-    getPercent()
-    {
-        if (!this.isSet()) return 0;
-        if (!this.setTime) return 1;
-        return 1 - percent(this.time - this.getGlobalTime(), 0, this.setTime);
-    }
-
-    /** Get the time this timer was set to, returns 0 if not set
-     * @return {number} */
-    getSetTime() { return this.isSet() ? this.setTime : 0; }
-
-    /** Get the current global time this timer is based on
-     * @return {number} */
-    getGlobalTime() { return this.useRealTime ? timeReal : time; }
-
-    /** Returns this timer expressed as a string
-     * @return {string} */
-    toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
-
-    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
-     * @return {number} */
-    valueOf() { return this.get(); }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Formats seconds to mm:ss style for display purposes
- *  @param {number} t - time in seconds
- *  @return {string}
- *  @memberof Utilities */
-function formatTime(t)
-{
-    const signStr = t <= -1 ? '-' : ''; // no sign when it shows 0:00
-    t = abs(t)|0;
-    return signStr + (t/60|0) + ':' + (t%60<10?'0':'') + t%60;
-}
-
-/** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
- *  @param {string} url - URL of JSON file
- *  @return {Promise<object>}
- *  @memberof Utilities */
-async function fetchJSON(url)
-{
-    const response = await fetch(url);
-    if (!response.ok)
-        throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
-    const json = await response.json();
-    editorJSONFetched(url, json); // debug builds remember the file a level came from, to save it by that name
-    return json;
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Save a text file to disk
- *  @param {string} text
- *  @param {string} [filename]
- *  @param {string} [type]
- *  @memberof Utilities */
-function saveText(text, filename='text', type='text/plain')
-{ saveDataURL(URL.createObjectURL(new Blob([text], {'type':type})), filename, 1e3); } // freed once the download has it
-
-/** Create an offscreen canvas to draw into, and return its 2D context
- *  - The canvas is context.canvas, which is what TextureInfo and the like take
- *  @param {number} width - In pixels
- *  @param {number} [height] - In pixels, defaults to the width for a square
- *  @param {boolean} [willReadFrequently] - Keep it in software, faster when getImageData is called on it often
- *  @return {OffscreenCanvasRenderingContext2D}
- *  @memberof Utilities */
-function createCanvasContext(width, height=width, willReadFrequently=false)
-{
-    ASSERT(isNumber(width) && isNumber(height), 'canvas width and height must be numbers', width, height);
-    return new OffscreenCanvas(width, height).getContext('2d', {willReadFrequently});
-}
-
-/** Save a canvas to disk
- *  @param {HTMLCanvasElement|OffscreenCanvas} canvas
- *  @param {string} [filename]
- *  @param {string} [type]
- *  @memberof Utilities */
-function saveCanvas(canvas, filename='screenshot', type='image/png')
-{
-    if (canvas instanceof OffscreenCanvas)
-    {
-        // copy to temporary canvas and save
-        const saveCanvas = document.createElement('canvas');
-        saveCanvas.width = canvas.width;
-        saveCanvas.height = canvas.height;
-        saveCanvas.getContext('2d').drawImage(canvas, 0, 0);
-        saveDataURL(saveCanvas.toDataURL(type), filename);
-    }
-    else
-        saveDataURL(canvas.toDataURL(type), filename);
-}
-
-/** Save a data url to disk
- *  @param {string} url
- *  @param {string} [filename]
- *  @param {number} [revokeTime] - how long before revoking the url
- *  @memberof Utilities */
-function saveDataURL(url, filename='download', revokeTime)
-{
-    ASSERT(isStringLike(url), 'saveDataURL requires url string');
-    ASSERT(isStringLike(filename), 'saveDataURL requires filename string');
-
-    // create link for saving screenshots
-    const link = document.createElement('a');
-    link.download = filename;
-    link.href = url;
-    link.click();
-    if (revokeTime !== undefined)
-        setTimeout(()=> URL.revokeObjectURL(url), revokeTime);
-}
-
-/** Share content using the native share dialog if available
- *  @param {string} title - title of the share
- *  @param {string} url - url to share
- *  @param {Function} [callback] - Called when share is complete
- *  @memberof Utilities */
-function shareURL(title, url, callback)
-{
-    ASSERT(isStringLike(title), 'shareURL requires title string');
-    ASSERT(isStringLike(url), 'shareURL requires url string');
-    navigator.share?.({title, url}).then(()=>callback?.(), ()=>{}); // a player who cancels is not an error
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Read save data from local storage
- *  - The result has the type of defaultSaveData, or any when there is none
- *  @template {Object<string, any>} [T=any]
- *  @param {string} saveName - unique name for the game/save
- *  @param {T} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
- *  @return {T}
- *  @memberof Utilities */
-function readSaveData(saveName, defaultSaveData)
-{
-    ASSERT(isStringLike(saveName), 'readSaveData requires saveName string');
-    ASSERT(defaultSaveData === undefined ||
-        (typeof defaultSaveData === 'object' && defaultSaveData !== null),
-        'readSaveData: default must be an object - the result is ' +
-        '{...default, ...loaded}, so a scalar default yields {}. ' +
-        'Use readSaveData(key, {best:0}).best');
-
-    // tolerate localStorage being unavailable (iOS private mode, sandboxed
-    // iframes) and corrupt JSON in stored data
-    let loadedData = {};
-    try
-    {
-        const data = localStorage.getItem(saveName); // not the brackets, a name like 'key' or 'length' is a Storage member
-        if (data)
-        {
-            try { loadedData = JSON.parse(data); }
-            catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
-        }
-    }
-    catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
-    return { .../** @type {object} */ (defaultSaveData), ...loadedData };
-}
-
-/** Write save data to local storage
- *  @param {string} saveName - unique name for the game/save
- *  @param {object} saveData - object containing data to be saved
- *  @memberof Utilities */
-function writeSaveData(saveName, saveData)
-{
-    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
-    // tolerate localStorage being unavailable or quota exceeded
-    try { localStorage.setItem(saveName, JSON.stringify(saveData)); }
-    catch { LOG('writeSaveData: failed to write', saveName); }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-// Deterministic well-distributed hash of an integer lattice index to [0, 1).
-// Murmur3 finalizer — adjacent integers produce uncorrelated outputs.
-function noiseHash(i)
-{
-    let h = (i | 0) ^ 0x9e3779b9;
-    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
-    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
-    h ^= h >>> 16;
-    return (h >>> 0) / 2**32;
-}
-
-/** 1D value noise — returns a smooth value in [0, 1] for any real x.
- *  Integer inputs land on deterministic lattice values; non-integer inputs
- *  are interpolated with smoothStep for C1 continuity.
- *  @param {number} x
- *  @return {number}
- *  @memberof Utilities */
-function noise1D(x)
-{
-    const i = floor(x);
-    return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
-}
-
-/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
- *  @param {number} x
- *  @param {number} y
- *  @return {number}
- *  @memberof Utilities */
-function noise2D(x, y)
-{
-    const ix = floor(x), iy = floor(y);
-    const fx = smoothStep(x - ix), fy = smoothStep(y - iy);
-    // large prime decorrelates neighboring rows
-    const h = (a, b) => noiseHash(a + b * 374761393);
-    return lerp(
-        lerp(h(ix,     iy    ), h(ix + 1, iy    ), fx),
-        lerp(h(ix,     iy + 1), h(ix + 1, iy + 1), fx),
-        fy);
+/**
+ * LittleJS Utility Classes and Functions
+ * - Timer - tracks time automatically with support for pause and real-time modes
+ * - Time formatting helper
+ * - JSON file fetching
+ * - File saving (text, canvas, data URLs)
+ * - Native share dialog support
+ * - Local storage save data management
+ * - Value noise (1D and 2D)
+ * @namespace Utilities
+ */
+
+/**
+ * Timer object tracks how long has passed since it was set
+ * @memberof Engine
+ * @example
+ * let a = new Timer;    // creates a timer that is not set
+ * a.set(3);             // sets the timer to 3 seconds
+ *
+ * let b = new Timer(1); // creates a timer with 1 second left
+ * b.unset();            // unset the timer
+ */
+class Timer
+{
+    /** Create a timer object set time passed in
+     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
+     *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
+    constructor(timeLeft, useRealTime=false)
+    {
+        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
+        this.useRealTime = useRealTime;
+        const globalTime = this.getGlobalTime();
+        /** @type {number|undefined} */
+        this.time = timeLeft === undefined ? undefined : globalTime + timeLeft;
+        /** @type {number|undefined} */
+        this.setTime = timeLeft;
+    }
+
+    /** Set the timer with seconds passed in
+     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
+    set(timeLeft=0)
+    {
+        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
+        const globalTime = this.getGlobalTime();
+        this.time = globalTime + timeLeft;
+        this.setTime = timeLeft;
+    }
+
+    /** Set if the timer should keep running even when the game is paused
+     *  @param {boolean} [useRealTime] */
+    setUseRealTime(useRealTime=true)
+    {
+        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
+        this.useRealTime = useRealTime;
+    }
+
+    /** Unset the timer */
+    unset() { this.time = undefined; }
+
+    /** Returns true if set
+     * @return {boolean} */
+    isSet() { return this.time !== undefined; }
+
+    /** Returns true if set and has not elapsed
+     * @return {boolean} */
+    active() { return this.getGlobalTime() < this.time; }
+
+    /** Returns true if set and elapsed
+     * @return {boolean} */
+    elapsed() { return this.getGlobalTime() >= this.time; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
+
+    /** Get percentage elapsed based on time it was set to, returns 0 if not set.
+     *  Zero-duration timers report 1 (already elapsed).
+     * @return {number} */
+    getPercent()
+    {
+        if (!this.isSet()) return 0;
+        if (!(this.setTime > 0)) return 1;
+        return 1 - percent(this.time - this.getGlobalTime(), 0, this.setTime);
+    }
+
+    /** Get the time this timer was set to, returns 0 if not set
+     * @return {number} */
+    getSetTime() { return this.isSet() ? this.setTime : 0; }
+
+    /** Get the current global time this timer is based on
+     * @return {number} */
+    getGlobalTime() { return this.useRealTime ? timeReal : time; }
+
+    /** Returns this timer expressed as a string
+     * @return {string} */
+    toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    valueOf() { return this.get(); }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Formats seconds to mm:ss style for display purposes
+ *  @param {number} t - time in seconds
+ *  @return {string}
+ *  @memberof Utilities */
+function formatTime(t)
+{
+    const signStr = t <= -1 ? '-' : ''; // no sign when it shows 0:00
+    t = abs(t)|0;
+    return signStr + (t/60|0) + ':' + (t%60<10?'0':'') + t%60;
+}
+
+/** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
+ *  @param {string} url - URL of JSON file
+ *  @return {Promise<object>}
+ *  @memberof Utilities */
+async function fetchJSON(url)
+{
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
+    const json = await response.json();
+    editorJSONFetched(url, json); // debug builds remember the file a level came from, to save it by that name
+    return json;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Save a text file to disk
+ *  @param {string} text
+ *  @param {string} [filename]
+ *  @param {string} [type]
+ *  @memberof Utilities */
+function saveText(text, filename='text', type='text/plain')
+{ saveDataURL(URL.createObjectURL(new Blob([text], {'type':type})), filename, 1e3); } // freed once the download has it
+
+/** Create an offscreen canvas to draw into, and return its 2D context
+ *  - The canvas is context.canvas, which is what TextureInfo and the like take
+ *  @param {number} width - In pixels
+ *  @param {number} [height] - In pixels, defaults to the width for a square
+ *  @param {boolean} [willReadFrequently] - Keep it in software, faster when getImageData is called on it often
+ *  @return {OffscreenCanvasRenderingContext2D}
+ *  @memberof Utilities */
+function createCanvasContext(width, height=width, willReadFrequently=false)
+{
+    ASSERT(isNumber(width) && isNumber(height), 'canvas width and height must be numbers', width, height);
+    return new OffscreenCanvas(width, height).getContext('2d', {willReadFrequently});
+}
+
+/** Save a canvas to disk
+ *  @param {HTMLCanvasElement|OffscreenCanvas} canvas
+ *  @param {string} [filename]
+ *  @param {string} [type]
+ *  @memberof Utilities */
+function saveCanvas(canvas, filename='screenshot', type='image/png')
+{
+    if (canvas instanceof OffscreenCanvas)
+    {
+        // copy to temporary canvas and save
+        const saveCanvas = document.createElement('canvas');
+        saveCanvas.width = canvas.width;
+        saveCanvas.height = canvas.height;
+        saveCanvas.getContext('2d').drawImage(canvas, 0, 0);
+        saveDataURL(saveCanvas.toDataURL(type), filename);
+    }
+    else
+        saveDataURL(canvas.toDataURL(type), filename);
+}
+
+/** Save a data url to disk
+ *  @param {string} url
+ *  @param {string} [filename]
+ *  @param {number} [revokeTime] - how long before revoking the url
+ *  @memberof Utilities */
+function saveDataURL(url, filename='download', revokeTime)
+{
+    ASSERT(isStringLike(url), 'saveDataURL requires url string');
+    ASSERT(isStringLike(filename), 'saveDataURL requires filename string');
+
+    // create link for saving screenshots
+    const link = document.createElement('a');
+    link.download = filename;
+    link.href = url;
+    link.click();
+    if (revokeTime !== undefined)
+        setTimeout(()=> URL.revokeObjectURL(url), revokeTime);
+}
+
+/** Share content using the native share dialog if available
+ *  @param {string} title - title of the share
+ *  @param {string} url - url to share
+ *  @param {Function} [callback] - Called when share is complete
+ *  @memberof Utilities */
+function shareURL(title, url, callback)
+{
+    ASSERT(isStringLike(title), 'shareURL requires title string');
+    ASSERT(isStringLike(url), 'shareURL requires url string');
+    navigator.share?.({title, url}).then(()=>callback?.(), ()=>{}); // a player who cancels is not an error
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Read save data from local storage
+ *  - The result has the type of defaultSaveData, or any when there is none
+ *  @template {Object<string, any>} [T=any]
+ *  @param {string} saveName - unique name for the game/save
+ *  @param {T} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
+ *  @return {T}
+ *  @memberof Utilities */
+function readSaveData(saveName, defaultSaveData)
+{
+    ASSERT(isStringLike(saveName), 'readSaveData requires saveName string');
+    ASSERT(defaultSaveData === undefined ||
+        (typeof defaultSaveData === 'object' && defaultSaveData !== null),
+        'readSaveData: default must be an object - the result is ' +
+        '{...default, ...loaded}, so a scalar default yields {}. ' +
+        'Use readSaveData(key, {best:0}).best');
+
+    // tolerate localStorage being unavailable (iOS private mode, sandboxed
+    // iframes) and corrupt JSON in stored data
+    let loadedData = {};
+    try
+    {
+        const data = localStorage.getItem(saveName); // not the brackets, a name like 'key' or 'length' is a Storage member
+        if (data)
+        {
+            try { loadedData = JSON.parse(data); }
+            catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
+        }
+    }
+    catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
+    return { .../** @type {object} */ (defaultSaveData), ...loadedData };
+}
+
+/** Write save data to local storage
+ *  @param {string} saveName - unique name for the game/save
+ *  @param {object} saveData - object containing data to be saved
+ *  @memberof Utilities */
+function writeSaveData(saveName, saveData)
+{
+    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
+    // tolerate localStorage being unavailable or quota exceeded
+    try { localStorage.setItem(saveName, JSON.stringify(saveData)); }
+    catch { LOG('writeSaveData: failed to write', saveName); }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+// Deterministic well-distributed hash of an integer lattice index to [0, 1).
+// Murmur3 finalizer — adjacent integers produce uncorrelated outputs.
+function noiseHash(i)
+{
+    let h = (i | 0) ^ 0x9e3779b9;
+    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+    h ^= h >>> 16;
+    return (h >>> 0) / 2**32;
+}
+
+/** 1D value noise — returns a smooth value in [0, 1] for any real x.
+ *  Integer inputs land on deterministic lattice values; non-integer inputs
+ *  are interpolated with smoothStep for C1 continuity.
+ *  @param {number} x
+ *  @return {number}
+ *  @memberof Utilities */
+function noise1D(x)
+{
+    const i = floor(x);
+    return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
+}
+
+/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
+ *  @param {number} x
+ *  @param {number} y
+ *  @return {number}
+ *  @memberof Utilities */
+function noise2D(x, y)
+{
+    const ix = floor(x), iy = floor(y);
+    const fx = smoothStep(x - ix), fy = smoothStep(y - iy);
+    // large prime decorrelates neighboring rows
+    const h = (a, b) => noiseHash(a + b * 374761393);
+    return lerp(
+        lerp(h(ix,     iy    ), h(ix + 1, iy    ), fx),
+        lerp(h(ix,     iy + 1), h(ix + 1, iy + 1), fx),
+        fy);
 }
 /**
  * LittleJS Engine Settings
@@ -4317,679 +4317,679 @@ function setDebugKeysAlways(enable=true) { debugKeysAlways = enable; }
  *  @param {boolean} [show]
  *  @memberof Debug */
 function setDebugTweakables(show=true) { debugTweakables = show; }
-/**
- * LittleJS Object System
- * - EngineObject is the base class for all game objects
- * - Handles automatic updating, rendering, physics, and collision
- * - Supports parent-child hierarchies with transform inheritance
- * - 2D physics with velocity, acceleration, damping, and gravity
- * - Collision system with tiles and other objects
- * - Renders sprites from tile sheets with color and rotation
- * - Objects sorted by renderOrder for layered rendering
- */
-
-/**
- * LittleJS Object Base Object Class
- * - Top level object class used by the engine
- * - Automatically adds self to object list
- * - Will be updated and rendered each frame
- * - Renders as a sprite from a tilesheet by default
- * - Can have color and additive color applied
- * - 2D Physics and collision system
- * - Sorted by renderOrder
- * - Objects can have children attached
- * - Parents are updated before children, and set child transform
- * - Call destroy() to get rid of objects
- *
- * The physics system used by objects is simple and fast with some caveats...
- * - Collision uses the axis aligned size, the object's rotation angle is only for rendering
- * - Objects are guaranteed to not intersect tile collision from physics
- * - If an object starts or is moved inside tile collision, it will not collide with that tile
- * - Collision for objects can be set to be solid to block other objects
- * - Objects may get pushed into overlapping other solid objects, if so they will push away
- * - A static solid (mass 0) moved by its velocity, like a door or an elevator, pushes objects out of its way
- * - Solid objects are more performance intensive and should be used sparingly
- * @memberof Engine
- * @example
- * // create an engine object, normally you would first extend the class with your own
- * const pos = vec2(2,3);
- * const object = new EngineObject(pos);
- */
-class EngineObject
-{
-    /** Create an engine object and adds it to the list of objects
-     *  @param {Vector2}  [pos=vec2()] - World space position of the object
-     *  @param {Vector2}  [size=vec2(1)] - World space size of the object
-     *  @param {TileInfo} [tileInfo] - Tile info to render object (undefined is untextured)
-     *  @param {number}   [angle] - Angle the object is rotated by
-     *  @param {Color}    [color=WHITE] - Color to apply to tile when rendered
-     *  @param {number}   [renderOrder] - Objects sorted by renderOrder before being rendered
-     */
-    constructor(pos=vec2(), size=vec2(1), tileInfo, angle=0, color=WHITE, renderOrder=0)
-    {
-        // check passed in params
-        ASSERT(isVector2(pos), 'object pos must be a vec2');
-        ASSERT(isVector2(size), 'object size must be a vec2');
-        ASSERT(!tileInfo || tileInfo instanceof TileInfo, 'object tileInfo should be a TileInfo or undefined');
-        ASSERT(typeof angle === 'number' && isFinite(angle), 'object angle should be a number');
-        ASSERT(isColor(color), 'object color should be a valid rgba color');
-        ASSERT(typeof renderOrder === 'number', 'object renderOrder should be a number');
-
-        /** @property {Vector2} - World space position of the object */
-        this.pos = pos.copy();
-        /** @property {Vector2} - World space width and height of the object */
-        this.size = size.copy();
-        /** @property {Vector2|undefined} - Size of object used for drawing, uses size if not set
-         *  @type {Vector2|undefined} */
-        this.drawSize = undefined;
-        /** @property {TileInfo|undefined} - Tile info to render object (undefined is untextured)
-         *  @type {TileInfo|undefined} */
-        this.tileInfo = tileInfo;
-        /** @property {number} - Angle to rotate the object */
-        this.angle = angle;
-        /** @property {Color} - Color to apply when rendered */
-        this.color = color.copy();
-        /** @property {Color|undefined} - Additive color to apply when rendered
-         *  @type {Color|undefined} */
-        this.additiveColor = undefined;
-        /** @property {Shader|undefined} - Custom shader to render with, undefined for the engine's own
-         *  @type {Shader|undefined} */
-        this.shader = undefined;
-        /** @property {boolean} - Does this object draw into the light system's shadow map; false for a floor layer, a background, a pickup */
-        this.castShadow = true;
-        /** @property {number} - With the light system, how much it lights itself: 0 lit only by the lights, 1 full
-         *  brightness in its own colors whatever the lights do, between partly; drawn into the lightmap through
-         *  renderEmissive, as 3D's emissive. Exact for solid pixels; a partly transparent one is self lit by its alpha
-         *  too, so a half alpha pixel shows at a quarter and a fading emissive sprite fades a little faster */
-        this.emissive = 0;
-        /** @property {boolean} - Should the rendered tile flip along the y axis. Affects rendering and the local→world transform of attached children (a mirrored parent flips its children's localPos.x and localAngle). Does not affect this object's own physics, collision, or localToWorld/worldToLocal. */
-        this.mirror = false;
-        /** @property {boolean} - Has object been destroyed? */
-        this.destroyed = false;
-        this.updatePass = 0; // the engine update pass it was last updated in, so nothing updates twice in one
-
-        // physical properties
-        /** @property {number} - How heavy the object is, static if 0: a static object moves by its velocity but does not
-         *  collide on its own, the moving ones collide with it */
-        this.mass = objectDefaultMass;
-        /** @property {number} - Fraction of velocity kept each frame, 1 keeps all of it, 0 stops at once */
-        this.damping = objectDefaultDamping;
-        /** @property {number} - Fraction of angular velocity kept each frame, 1 keeps all of it, 0 stops at once */
-        this.angleDamping = objectDefaultAngleDamping;
-        /** @property {number} - How bouncy the object is when colliding (0-1) */
-        this.restitution = objectDefaultRestitution;
-        /** @property {number} - Fraction of sliding speed kept each frame on the ground, 1 is no friction, 0 stops at
-         *  once, the more slippery of the object and its ground is used */
-        this.friction  = objectDefaultFriction;
-        /** @property {number} - How much to scale gravity by for this object */
-        this.gravityScale = 1;
-        /** @property {number} - Objects are sorted by render order */
-        this.renderOrder = renderOrder;
-        /** @property {Vector2} - Velocity of the object, in world units per frame */
-        this.velocity = vec2();
-        /** @property {number} - Angular velocity of the object, in radians per frame */
-        this.angleVelocity = 0;
-        /** @property {number} - Track when object was created  */
-        this.spawnTime = time;
-        /** @property {Array<EngineObject>} - List of children of this object
-         *  @type {Array<EngineObject>} */
-        this.children = [];
-        /** @property {boolean} - Limit object speed along x and y axis */
-        this.clampSpeed = true;
-        /** @property {EngineObject|undefined} - Object we are standing on, if any
-         *  @type {EngineObject|undefined} */
-        this.groundObject = undefined;
-
-        // parent child system
-        /** @property {EngineObject|undefined} - Parent of object if in local space
-         *  @type {EngineObject|undefined} */
-        this.parent = undefined;
-        /** @property {Vector2|undefined} - Position relative to the parent, only while attached to one
-         *  @type {Vector2|undefined} */
-        this.localPos = undefined;
-        /** @property {number} - Local angle if child  */
-        this.localAngle = 0;
-
-        // collision flags
-        /** @property {boolean} - Object collides with the level, its tile collision layers
-         *  @type {boolean} */
-        this.collideLevel = false;
-        /** @property {boolean} - Object collides with solid objects */
-        this.collideSolidObjects = false;
-        /** @property {boolean} - Object collides with and blocks other objects */
-        this.isSolid = false;
-        /** @property {boolean} - Object collides with raycasts */
-        this.collideRaycast = false;
-
-        /** @property {boolean} - Object is skipped by engineObjectsDestroy, for things that outlive a level like a camera
-         *  - Calling destroy on it still destroys it, and its children go with it either way */
-        this.persistent = false;
-
-        // add to list of objects
-        engineObjects.push(this);
-    }
-
-    /** Update the object transform, called automatically by engine even when paused
-     *  @param {boolean} [updateChildren] - Also update the children's transforms */
-    updateTransforms(updateChildren=true)
-    {
-        const parent = this.parent;
-        if (parent)
-        {
-            // compose with parent transform inline to avoid intermediate vector allocs
-            const mirror = parent.getMirrorSign();
-            const lp = this.localPos, pp = parent.pos;
-            const lx = lp.x*mirror, ly = lp.y, pa = parent.angle;
-            if (pa)
-            {
-                const c = cos(-pa), s = sin(-pa);
-                this.pos.set(lx*c - ly*s + pp.x, lx*s + ly*c + pp.y);
-            }
-            else
-                this.pos.set(lx + pp.x, ly + pp.y);
-            this.angle = mirror*this.localAngle + pa;
-        }
-
-        // update children
-        if (updateChildren)
-            for (const child of this.children)
-                child.updateTransforms();
-    }
-
-    /** Update the object physics, called automatically by engine once each frame. Can be overridden to stop or change how physics works for an object. */
-    updatePhysics()
-    {
-        // child objects do not have physics
-        ASSERT(!this.parent);
-
-        // bail if a collision callback destroyed us mid-frame
-        if (this.destroyed) return;
-
-        // limit max speed to prevent missing collisions, only for what collides: with solids, or with tiles while it
-        // has a mass, which tile collision needs; anything else moves as fast as it is told
-        if (this.clampSpeed && enablePhysicsSolver && (this.collideSolidObjects || this.collideLevel && this.mass))
-        {
-            this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
-            this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
-        }
-
-        // physics sanity checks
-        ASSERT(this.angleDamping >= 0 && this.angleDamping <= 1, 'angleDamping must be 0 to 1, the fraction kept each frame');
-        ASSERT(this.damping >= 0 && this.damping <= 1, 'damping must be 0 to 1, the fraction of velocity kept each frame');
-
-        // apply physics; only the solver needs where the object was, so only then is it copied
-        const solve = enablePhysicsSolver && this.mass;
-        const oldPos = solve ? this.pos.copy() : undefined;
-        this.velocity.x *= this.damping;
-        this.velocity.y *= this.damping;
-        if (this.mass)
-        {
-            // apply gravity only if it has mass
-            this.velocity.x += gravity.x * this.gravityScale;
-            this.velocity.y += gravity.y * this.gravityScale;
-        }
-        this.pos.x += this.velocity.x;
-        this.pos.y += this.velocity.y;
-        this.angle += this.angleVelocity *= this.angleDamping;
-
-        // don't do collision for static objects or if solver disabled
-        if (!solve) return;
-
-        // which way is down for this object, a negative gravityScale falls up and lands on ceilings
-        const gravityY = this.gravityScale < 0 ? -gravity.y : gravity.y;
-        const wasFalling = this.velocity.y < 0 && gravityY < 0 || this.velocity.y > 0 && gravityY > 0;
-        if (this.groundObject)
-        {
-            // apply friction in local space of ground object
-            const friction = max(this.friction, this.groundObject.friction);
-            const groundSpeed = this.groundObject.velocity.x;
-            this.velocity.x = groundSpeed + (this.velocity.x - groundSpeed) * friction;
-            this.groundObject = undefined;
-        }
-
-        // an object with no width or height has no box to push out of, or to be pushed out of
-        if (this.collideSolidObjects && this.size.x && this.size.y)
-        {
-            // check collisions against solid objects
-            const epsilon = .001; // necessary to push slightly outside of the collision
-            for (const o of engineObjectsCollideStaticLast)
-            {
-                // skip destroyed, child objects, self collision, or objects with no box
-                if (o.destroyed || o.parent || o === this || !o.size.x || !o.size.y) continue;
-
-                // non solid objects don't collide with each other
-                if (!this.isSolid && !o.isSolid) continue;
-
-                // check collision
-                if (!this.isOverlappingObject(o)) continue;
-
-                // each moving object checks its own contacts, so a pair the other one already asked about this frame
-                // is not asked twice: left overlapping, ignored or only nudged apart it is skipped, and one both said
-                // to resolve, pushed back together since, is resolved again
-                const answer = engineObjectsCollidePairAnswer(o, this);
-                if (answer === false) continue;
-                if (!answer)
-                {
-                    // notify objects of collision and check if should be resolved
-                    const collide1 = this.collideWithObject(o);
-                    const collide2 = o.collideWithObject(this);
-                    if (!collide1 || !collide2)
-                    {
-                        engineObjectsCollidePairAdd(this, o);
-                        continue;
-                    }
-                }
-
-                const wasOverlapping = isOverlapping(oldPos, this.size, o.pos, o.size);
-                if (wasOverlapping && (!o.mass || o.groundObject))
-                {
-                    // a static solid that moved into it, like a door or an elevator, pushes it out the shortest way
-                    // at once and carries it along, it would only drift out slowly and the solid would pass through;
-                    // an object standing on something counts as fixed too, so a stack on an elevator rides together;
-                    // it bounces off relative to the mover, a paddle moved by setting pos bounces a ball as a wall does
-                    const push = collideBoxBox(this.pos, this.size, o.pos, o.size);
-                    if (push)
-                    {
-                        this.pos.x += push.x + sign(push.x) * epsilon;
-                        this.pos.y += push.y + sign(push.y) * epsilon;
-                        const restitution = max(this.restitution, o.restitution);
-                        if (push.x)
-                        {
-                            const v = this.velocity.x - o.velocity.x;
-                            if (v * push.x < 0) // moving into it
-                                this.velocity.x = o.velocity.x - v * restitution;
-                        }
-                        else
-                        {
-                            const v = this.velocity.y - o.velocity.y;
-                            if (v * push.y < 0) // moving into it
-                                this.velocity.y = o.velocity.y - v * restitution;
-                            if (push.y * gravityY < 0) // pushed up against gravity, it stands on it
-                                this.groundObject = o;
-                        }
-                    }
-                    engineObjectsCollidePairAdd(this, o);
-
-                    debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f00', undefined, false);
-                    continue;
-                }
-                if (wasOverlapping)
-                {
-                    // if already was touching, try to push away
-                    const deltaPos = oldPos.subtract(o.pos);
-                    const length = deltaPos.length();
-                    const pushAwayAccel = .001;
-                    const velocity = length < .001 ? vec2(0, pushAwayAccel) : deltaPos.scale(pushAwayAccel/length);
-                    this.velocity = this.velocity.add(velocity);
-                    if (o.mass) // push away other object if not fixed
-                        o.velocity = o.velocity.subtract(velocity);
-                    engineObjectsCollidePairAdd(this, o);
-
-                    debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f00', undefined, false);
-                    continue;
-                }
-
-                // check for collision
-                const sizeBoth = this.size.add(o.size);
-                // prefer to push up if small delta, up away from this object's own gravity
-                const smallStepUp = (gravityY > 0 ? o.pos.y - oldPos.y : oldPos.y - o.pos.y)*2 > sizeBoth.y - abs(gravityY);
-                const isBlockedX = abs(oldPos.y - o.pos.y)*2 < sizeBoth.y;
-                const isBlockedY = abs(oldPos.x - o.pos.x)*2 < sizeBoth.x;
-                const restitution = max(this.restitution, o.restitution);
-
-                if (smallStepUp || isBlockedY || !isBlockedX) // resolve y collision
-                {
-                    // push outside object collision
-                    this.pos.y = o.pos.y + (sizeBoth.y/2 + epsilon) * sign(oldPos.y - o.pos.y);
-                    if ((o.groundObject && wasFalling) || !o.mass)
-                    {
-                        // set ground object if landed on something
-                        if (wasFalling)
-                            this.groundObject = o;
-
-                        // bounce if other object is fixed or grounded, relative to it so a rider keeps up with a
-                        // platform moving down instead of landing on it again every few frames
-                        this.velocity.y = o.velocity.y - (this.velocity.y - o.velocity.y) * restitution;
-                    }
-                    else // o has mass here, the other branch already handled the massless case
-                    {
-                        // inelastic collision
-                        const inelastic = (this.mass * this.velocity.y + o.mass * o.velocity.y) / (this.mass + o.mass);
-
-                        // elastic collision
-                        const elastic0 = this.velocity.y * (this.mass - o.mass) / (this.mass + o.mass)
-                            + o.velocity.y * 2 * o.mass / (this.mass + o.mass);
-                        const elastic1 = o.velocity.y * (o.mass - this.mass) / (this.mass + o.mass)
-                            + this.velocity.y * 2 * this.mass / (this.mass + o.mass);
-
-                        // lerp between elastic or inelastic based on restitution
-                        this.velocity.y = lerp(inelastic, elastic0, restitution);
-                        o.velocity.y = lerp(inelastic, elastic1, restitution);
-                    }
-                }
-                if (!smallStepUp && isBlockedX) // resolve x collision
-                {
-                    // push outside collision
-                    this.pos.x = o.pos.x + (sizeBoth.x/2 + epsilon) * sign(oldPos.x - o.pos.x);
-                    if (o.mass)
-                    {
-                        // inelastic collision
-                        const inelastic = (this.mass * this.velocity.x + o.mass * o.velocity.x) / (this.mass + o.mass);
-
-                        // elastic collision
-                        const elastic0 = this.velocity.x * (this.mass - o.mass) / (this.mass + o.mass)
-                            + o.velocity.x * 2 * o.mass / (this.mass + o.mass);
-                        const elastic1 = o.velocity.x * (o.mass - this.mass) / (this.mass + o.mass)
-                            + this.velocity.x * 2 * this.mass / (this.mass + o.mass);
-
-                        // lerp between elastic or inelastic based on restitution
-                        this.velocity.x = lerp(inelastic, elastic0, restitution);
-                        o.velocity.x = lerp(inelastic, elastic1, restitution);
-                    }
-                    else // bounce if other object is fixed, relative to it as a landing is
-                        this.velocity.x = o.velocity.x - (this.velocity.x - o.velocity.x) * restitution;
-                }
-                engineObjectsCollidePairAdd(this, o, true);
-                debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f0f', undefined, false);
-            }
-        }
-        if (this.collideLevel)
-        {
-            // check collision against tiles
-            const hitLayer = tileCollisionTest(this.pos, this.size, this);
-            if (hitLayer)
-            {
-                // if already was stuck in collision, don't do anything
-                // this should not happen unless something starts in collision
-                if (!tileCollisionTest(oldPos, this.size, this))
-                {
-                    // test which side we bounced off (or both if a corner)
-                    const isBlockedX = tileCollisionTest(vec2(this.pos.x, oldPos.y), this.size, this);
-                    const isBlockedY = tileCollisionTest(vec2(oldPos.x, this.pos.y), this.size, this);
-                    const restitution = max(this.restitution, hitLayer.restitution);
-                    if (isBlockedX)
-                    {
-                        // a ledge caught less than maxMove below its top lifts the object onto it instead of stopping it,
-                        // down off a ceiling ledge when gravity points up; zero gravity counts as down
-                        const epsilon = 1e-3;
-                        const maxMove = .1;
-                        const y = gravityY > 0 ?
-                            ceil( oldPos.y+this.size.y/2-1) - this.size.y/2 - epsilon :
-                            floor(oldPos.y-this.size.y/2+1) + this.size.y/2 + epsilon;
-                        if (abs(y - this.pos.y) < maxMove && !tileCollisionTest(vec2(this.pos.x, y), this.size, this))
-                        {
-                            this.pos.y = y;
-                            debugPhysics && debugRect(this.pos, this.size, '#ff0', 0, 0, false, false);
-                            return;
-                        }
-
-                        // move to previous X position and bounce
-                        this.pos.x = oldPos.x;
-                        this.velocity.x *= -restitution;
-                    }
-                    if (isBlockedY || !isBlockedX)
-                    {
-                        if (wasFalling)
-                        {
-                            // adjust position to slightly away from nearest tile
-                            // this prevents gap between object and ground
-                            const epsilon = .0001;
-                            const offset = this.size.y/2 + epsilon;
-                            // rounded in the layer's space as its collision test is, or a bottom a hair below a
-                            // grid line would round to the row under it, inside the floor, and fall through
-                            const layerY = hitLayer.pos.y;
-                            this.pos.y = layerY + (gravityY < 0 ?
-                                floor(oldPos.y - layerY - this.size.y/2) + offset :
-                                ceil( oldPos.y - layerY + this.size.y/2) - offset);
-
-                            // set ground object for tile collision
-                            this.groundObject = hitLayer;
-                        }
-                        else
-                        {
-                            // move to previous Y position
-                            this.pos.y = oldPos.y;
-                            this.groundObject = undefined;
-                        }
-                        // bounce velocity
-                        this.velocity.y *= -restitution;
-                    }
-                    debugPhysics && debugRect(this.pos, this.size, '#f00', 0, 0, false, false);
-                }
-            }
-        }
-    }
-
-    /** Update the object, called automatically by engine once each frame. Does nothing by default. */
-    update() {}
-
-    /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
-    render()
-    {
-        // default object render
-        drawTile(this.pos, this.drawSize || this.size, this.tileInfo, this.color, this.angle, this.mirror, this.additiveColor, glEnable, false);
-    }
-
-    /** Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default. */
-    renderLight() {}
-
-    /** Draw this object into the light system's shadow map, called during its shadow pass when castShadow is set.
-     *  Calls render() by default so the object casts its own shape; override to cast a different one, like a blob at a character's feet so its body stays lit;
-     *  screen space WebGL draws in render() are skipped during the pass */
-    renderShadow() { this.render(); }
-
-    /** Draw this object's shape into the light system's lightmap, called during its light pass when emissive is above
-     *  0; what it draws shows in its own colors that much brighter. Calls render() by default so the whole object
-     *  glows; override to glow a part, like a robot's eyes */
-    renderEmissive() { this.render(); }
-
-    /** Destroy this object, destroy its children, detach its parent, and mark it for removal
-     *  @param {boolean} [immediate] - true removes attached effects like particle emitters at once, false lets them finish first */
-    destroy(immediate=false)
-    {
-        if (this.destroyed) return;
-
-        // disconnect from parent and destroy children
-        this.destroyed = true;
-        this.parent?.removeChild(this);
-        for (const child of this.children)
-        {
-            child.parent = undefined;
-            child.destroy(immediate);
-        }
-    }
-
-    /** Convert from local space to world space
-     *  @param {Vector2} pos - local space point */
-    localToWorld(pos) { return this.pos.add(pos.rotate(this.angle)); }
-
-    /** Convert from world space to local space
-     *  @param {Vector2} pos - world space point */
-    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 */
-    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 */
-    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.
-     *  - Called for each solid tile the physics tests, which can be several times a frame for the same tile, and for
-     *    positions it only tries, so keep it free of side effects or guard them to once a frame
-     *  - this.pos has already moved, so a check on where it came from, like a one way platform, needs the position
-     *    saved in update, as the platformer example does
-     *  @param {number}  tileData - the value of the tile at the position
-     *  @param {Vector2} pos - the tile's bottom left corner in world space
-     *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity */
-    collideWithTile(tileData, pos) { return tileData > 0; }
-
-    /** Called by the engine to check if an object collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.
-     *  - Both objects of a touching pair are asked once a frame, whichever order they update in; an object that
-     *    destroys itself here is gone at the end of the frame and is still asked about the pairs left this frame, so a
-     *    bullet that should hit one thing checks its own destroyed flag first
-     *  @param {EngineObject} object - the object to test against
-     *  @param {Vector3} [push] - what it would take to move this object clear, a Vector3 from the 3D plugin, undefined in 2D
-     *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity
-     */
-    collideWithObject(object, push) { return true; }
-
-    /** Get this object's up vector
-     *  @param {number} [scale] - length of the vector
-     *  @return {Vector2} */
-    getUp(scale=1) { return vec2().setAngle(this.angle, scale); }
-
-    /** Get this object's right vector
-     *  @param {number} [scale] - length of the vector
-     *  @return {Vector2} */
-    getRight(scale=1) { return vec2().setAngle(this.angle+PI/2, scale); }
-
-    /** How long since the object was created
-     *  @return {number} */
-    getAliveTime() { return time - this.spawnTime; }
-
-    /** Get the speed of this object
-     *  @return {number} */
-    getSpeed() { return this.velocity.length(); }
-
-    /** Apply acceleration to this object (adjust velocity, not affected by mass)
-     *  - Does nothing on a static object (mass 0), set its velocity instead
-     *  @param {Vector2} acceleration */
-    applyAcceleration(acceleration)
-    { if (this.mass) this.velocity = this.velocity.add(acceleration); }
-
-    /** Apply angular acceleration to this object
-     *  - Does nothing on a static object (mass 0), set its angleVelocity instead
-     *  @param {number} acceleration */
-    applyAngularAcceleration(acceleration)
-    { if (this.mass) this.angleVelocity += acceleration; }
-
-    /** Apply force to this object (adjust velocity, affected by mass)
-     *  - Does nothing on a static object (mass 0), set its velocity instead
-     *  @param {Vector2} force */
-    applyForce(force)
-    { if (this.mass) this.applyAcceleration(force.scale(1/this.mass)); }
-
-    /** Get the direction of the mirror
-     *  @return {number} -1 if this.mirror is true, or 1 if not mirrored */
-    getMirrorSign() { return this.mirror ? -1 : 1; }
-
-    /** Attaches a child to this with a local transform, returns child for chaining
-     *  @param {EngineObject} child
-     *  @param {Vector2}      [localPos=vec2()]
-     *  @param {number}       [localAngle]
-     *  @return {EngineObject} The child object added */
-    addChild(child, localPos=vec2(), localAngle=0)
-    {
-        ASSERT(!this.destroyed, 'cannot add child to destroyed object');
-        if (this.destroyed) return child;
-        ASSERT(!child.parent && !this.children.includes(child), 'child already has a parent, removeChild it first or use attach');
-        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
-        ASSERT(!child.destroyed, 'cannot add a destroyed child');
-        for (let p = /** @type {EngineObject} */ (this); p; p = p.parent)
-            ASSERT(p !== child, 'cannot add an object as a child of itself or of its own child');
-        this.children.push(child);
-        child.parent = this;
-        child.localPos = localPos.copy();
-        child.localAngle = localAngle;
-        child.updateTransforms();
-        return child;
-    }
-
-    /** Attaches a child to this without moving it: the local transform is worked out from where the child is now,
-     *  where addChild takes one; a child of something else is moved over, returns child for chaining
-     *  @param {EngineObject} child
-     *  @return {EngineObject} The child object attached */
-    attach(child)
-    {
-        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
-        ASSERT(child !== this, 'cannot attach self');
-        child.parent?.removeChild(child);
-        // the local values that updateTransforms turns back into the child's current pos and angle
-        const mirror = this.getMirrorSign(), local = this.worldToLocal(child.pos);
-        local.x *= mirror;
-        return this.addChild(child, local, mirror * (child.angle - this.angle));
-    }
-
-    /** Removes a child from this one, it stays where it is in the world
-     *  @param {EngineObject} child */
-    removeChild(child)
-    {
-        ASSERT(child.parent === this && this.children.includes(child));
-        const i = this.children.indexOf(child);
-        if (i < 0) return; // not a child of this one, release has no assert
-        this.children.splice(i, 1);
-        child.parent = child.localPos = undefined;
-    }
-
-    /** Check if this object's box overlaps another object's box
-     *  @param {EngineObject} object
-     *  @return {boolean} */
-    isOverlappingObject(object)
-    { return this.isOverlapping(object.pos, object.size); }
-
-    /** Check if overlapping a point or aligned bounding box
-     *  @param {Vector2} pos          - Center of box
-     *  @param {Vector2} [size=vec2()] - Size of box, uses a point if undefined
-     *  @return {boolean} */
-    isOverlapping(pos, size=vec2())
-    { return isOverlapping(this.pos, this.size, pos, size); }
-
-    /** Set how this object collides
-     *  @param {boolean} [collideSolidObjects] - Does it collide with solid objects?
-     *  @param {boolean} [isSolid]             - Does it collide with and block other objects? (expensive in large numbers)
-     *  @param {boolean} [collideLevel]        - Does it collide with the level, its tile collision layers?
-     *  @param {boolean} [collideRaycast]      - Does it collide with raycasts? */
-    setCollision(collideSolidObjects=true, isSolid=true, collideLevel=true, collideRaycast=true)
-    {
-        ASSERT(collideSolidObjects || !isSolid, 'solid objects must be set to collide');
-
-        this.collideSolidObjects = collideSolidObjects;
-        this.isSolid = isSolid;
-        this.collideLevel = collideLevel;
-        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()
-    {
-        let text = 'type = ' + this.constructor.name;
-        if (this.pos.x || this.pos.y)
-            text += '\npos = ' + this.pos;
-        if (this.velocity.x || this.velocity.y)
-            text += '\nvelocity = ' + this.velocity;
-        if (this.size.x || this.size.y)
-            text += '\nsize = ' + this.size;
-        if (this.angle)
-            text += '\nangle = ' + this.angle.toFixed(3);
-        text += '\ncolor = ' + this.color;
-        return text;
-    }
-
-    /** Render debug info for this object  */
-    renderDebugInfo()
-    {
-        if (!debug) return;
-
-        // check if there is anything to show
-        const hasPhysics = this.collideLevel || this.collideSolidObjects || this.isSolid;
-        if (!hasPhysics && !this.parent) return;
-
-        // show object info for debugging
-        const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
-        const color = rgb(this.collideLevel?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, .5);
-        debugRect(this.pos, size, color, 0, hasPhysics ? 0 : this.angle, hasPhysics, false); // collision ignores the angle
-        if (this.parent)
-            debugRect(this.pos, size.scale(.8), rgb(1,1,1,.5), 0, this.angle, false, false);
-        this.parent && debugLine(this.pos, this.parent.pos, rgb(1,1,1,.5), .5, 0, false);
-    }
+/**
+ * LittleJS Object System
+ * - EngineObject is the base class for all game objects
+ * - Handles automatic updating, rendering, physics, and collision
+ * - Supports parent-child hierarchies with transform inheritance
+ * - 2D physics with velocity, acceleration, damping, and gravity
+ * - Collision system with tiles and other objects
+ * - Renders sprites from tile sheets with color and rotation
+ * - Objects sorted by renderOrder for layered rendering
+ */
+
+/**
+ * LittleJS Object Base Object Class
+ * - Top level object class used by the engine
+ * - Automatically adds self to object list
+ * - Will be updated and rendered each frame
+ * - Renders as a sprite from a tilesheet by default
+ * - Can have color and additive color applied
+ * - 2D Physics and collision system
+ * - Sorted by renderOrder
+ * - Objects can have children attached
+ * - Parents are updated before children, and set child transform
+ * - Call destroy() to get rid of objects
+ *
+ * The physics system used by objects is simple and fast with some caveats...
+ * - Collision uses the axis aligned size, the object's rotation angle is only for rendering
+ * - Objects are guaranteed to not intersect tile collision from physics
+ * - If an object starts or is moved inside tile collision, it will not collide with that tile
+ * - Collision for objects can be set to be solid to block other objects
+ * - Objects may get pushed into overlapping other solid objects, if so they will push away
+ * - A static solid (mass 0) moved by its velocity, like a door or an elevator, pushes objects out of its way
+ * - Solid objects are more performance intensive and should be used sparingly
+ * @memberof Engine
+ * @example
+ * // create an engine object, normally you would first extend the class with your own
+ * const pos = vec2(2,3);
+ * const object = new EngineObject(pos);
+ */
+class EngineObject
+{
+    /** Create an engine object and adds it to the list of objects
+     *  @param {Vector2}  [pos=vec2()] - World space position of the object
+     *  @param {Vector2}  [size=vec2(1)] - World space size of the object
+     *  @param {TileInfo} [tileInfo] - Tile info to render object (undefined is untextured)
+     *  @param {number}   [angle] - Angle the object is rotated by
+     *  @param {Color}    [color=WHITE] - Color to apply to tile when rendered
+     *  @param {number}   [renderOrder] - Objects sorted by renderOrder before being rendered
+     */
+    constructor(pos=vec2(), size=vec2(1), tileInfo, angle=0, color=WHITE, renderOrder=0)
+    {
+        // check passed in params
+        ASSERT(isVector2(pos), 'object pos must be a vec2');
+        ASSERT(isVector2(size), 'object size must be a vec2');
+        ASSERT(!tileInfo || tileInfo instanceof TileInfo, 'object tileInfo should be a TileInfo or undefined');
+        ASSERT(typeof angle === 'number' && isFinite(angle), 'object angle should be a number');
+        ASSERT(isColor(color), 'object color should be a valid rgba color');
+        ASSERT(typeof renderOrder === 'number', 'object renderOrder should be a number');
+
+        /** @property {Vector2} - World space position of the object */
+        this.pos = pos.copy();
+        /** @property {Vector2} - World space width and height of the object */
+        this.size = size.copy();
+        /** @property {Vector2|undefined} - Size of object used for drawing, uses size if not set
+         *  @type {Vector2|undefined} */
+        this.drawSize = undefined;
+        /** @property {TileInfo|undefined} - Tile info to render object (undefined is untextured)
+         *  @type {TileInfo|undefined} */
+        this.tileInfo = tileInfo;
+        /** @property {number} - Angle to rotate the object */
+        this.angle = angle;
+        /** @property {Color} - Color to apply when rendered */
+        this.color = color.copy();
+        /** @property {Color|undefined} - Additive color to apply when rendered
+         *  @type {Color|undefined} */
+        this.additiveColor = undefined;
+        /** @property {Shader|undefined} - Custom shader to render with, undefined for the engine's own
+         *  @type {Shader|undefined} */
+        this.shader = undefined;
+        /** @property {boolean} - Does this object draw into the light system's shadow map; false for a floor layer, a background, a pickup */
+        this.castShadow = true;
+        /** @property {number} - With the light system, how much it lights itself: 0 lit only by the lights, 1 full
+         *  brightness in its own colors whatever the lights do, between partly; drawn into the lightmap through
+         *  renderEmissive, as 3D's emissive. Exact for solid pixels; a partly transparent one is self lit by its alpha
+         *  too, so a half alpha pixel shows at a quarter and a fading emissive sprite fades a little faster */
+        this.emissive = 0;
+        /** @property {boolean} - Should the rendered tile flip along the y axis. Affects rendering and the local→world transform of attached children (a mirrored parent flips its children's localPos.x and localAngle). Does not affect this object's own physics, collision, or localToWorld/worldToLocal. */
+        this.mirror = false;
+        /** @property {boolean} - Has object been destroyed? */
+        this.destroyed = false;
+        this.updatePass = 0; // the engine update pass it was last updated in, so nothing updates twice in one
+
+        // physical properties
+        /** @property {number} - How heavy the object is, static if 0: a static object moves by its velocity but does not
+         *  collide on its own, the moving ones collide with it */
+        this.mass = objectDefaultMass;
+        /** @property {number} - Fraction of velocity kept each frame, 1 keeps all of it, 0 stops at once */
+        this.damping = objectDefaultDamping;
+        /** @property {number} - Fraction of angular velocity kept each frame, 1 keeps all of it, 0 stops at once */
+        this.angleDamping = objectDefaultAngleDamping;
+        /** @property {number} - How bouncy the object is when colliding (0-1) */
+        this.restitution = objectDefaultRestitution;
+        /** @property {number} - Fraction of sliding speed kept each frame on the ground, 1 is no friction, 0 stops at
+         *  once, the more slippery of the object and its ground is used */
+        this.friction  = objectDefaultFriction;
+        /** @property {number} - How much to scale gravity by for this object */
+        this.gravityScale = 1;
+        /** @property {number} - Objects are sorted by render order */
+        this.renderOrder = renderOrder;
+        /** @property {Vector2} - Velocity of the object, in world units per frame */
+        this.velocity = vec2();
+        /** @property {number} - Angular velocity of the object, in radians per frame */
+        this.angleVelocity = 0;
+        /** @property {number} - Track when object was created  */
+        this.spawnTime = time;
+        /** @property {Array<EngineObject>} - List of children of this object
+         *  @type {Array<EngineObject>} */
+        this.children = [];
+        /** @property {boolean} - Limit object speed along x and y axis */
+        this.clampSpeed = true;
+        /** @property {EngineObject|undefined} - Object we are standing on, if any
+         *  @type {EngineObject|undefined} */
+        this.groundObject = undefined;
+
+        // parent child system
+        /** @property {EngineObject|undefined} - Parent of object if in local space
+         *  @type {EngineObject|undefined} */
+        this.parent = undefined;
+        /** @property {Vector2|undefined} - Position relative to the parent, only while attached to one
+         *  @type {Vector2|undefined} */
+        this.localPos = undefined;
+        /** @property {number} - Local angle if child  */
+        this.localAngle = 0;
+
+        // collision flags
+        /** @property {boolean} - Object collides with the level, its tile collision layers
+         *  @type {boolean} */
+        this.collideLevel = false;
+        /** @property {boolean} - Object collides with solid objects */
+        this.collideSolidObjects = false;
+        /** @property {boolean} - Object collides with and blocks other objects */
+        this.isSolid = false;
+        /** @property {boolean} - Object collides with raycasts */
+        this.collideRaycast = false;
+
+        /** @property {boolean} - Object is skipped by engineObjectsDestroy, for things that outlive a level like a camera
+         *  - Calling destroy on it still destroys it, and its children go with it either way */
+        this.persistent = false;
+
+        // add to list of objects
+        engineObjects.push(this);
+    }
+
+    /** Update the object transform, called automatically by engine even when paused
+     *  @param {boolean} [updateChildren] - Also update the children's transforms */
+    updateTransforms(updateChildren=true)
+    {
+        const parent = this.parent;
+        if (parent)
+        {
+            // compose with parent transform inline to avoid intermediate vector allocs
+            const mirror = parent.getMirrorSign();
+            const lp = this.localPos, pp = parent.pos;
+            const lx = lp.x*mirror, ly = lp.y, pa = parent.angle;
+            if (pa)
+            {
+                const c = cos(-pa), s = sin(-pa);
+                this.pos.set(lx*c - ly*s + pp.x, lx*s + ly*c + pp.y);
+            }
+            else
+                this.pos.set(lx + pp.x, ly + pp.y);
+            this.angle = mirror*this.localAngle + pa;
+        }
+
+        // update children
+        if (updateChildren)
+            for (const child of this.children)
+                child.updateTransforms();
+    }
+
+    /** Update the object physics, called automatically by engine once each frame. Can be overridden to stop or change how physics works for an object. */
+    updatePhysics()
+    {
+        // child objects do not have physics
+        ASSERT(!this.parent);
+
+        // bail if a collision callback destroyed us mid-frame
+        if (this.destroyed) return;
+
+        // limit max speed to prevent missing collisions, only for what collides: with solids, or with tiles while it
+        // has a mass, which tile collision needs; anything else moves as fast as it is told
+        if (this.clampSpeed && enablePhysicsSolver && (this.collideSolidObjects || this.collideLevel && this.mass))
+        {
+            this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
+            this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
+        }
+
+        // physics sanity checks
+        ASSERT(this.angleDamping >= 0 && this.angleDamping <= 1, 'angleDamping must be 0 to 1, the fraction kept each frame');
+        ASSERT(this.damping >= 0 && this.damping <= 1, 'damping must be 0 to 1, the fraction of velocity kept each frame');
+
+        // apply physics; only the solver needs where the object was, so only then is it copied
+        const solve = enablePhysicsSolver && this.mass;
+        const oldPos = solve ? this.pos.copy() : undefined;
+        this.velocity.x *= this.damping;
+        this.velocity.y *= this.damping;
+        if (this.mass)
+        {
+            // apply gravity only if it has mass
+            this.velocity.x += gravity.x * this.gravityScale;
+            this.velocity.y += gravity.y * this.gravityScale;
+        }
+        this.pos.x += this.velocity.x;
+        this.pos.y += this.velocity.y;
+        this.angle += this.angleVelocity *= this.angleDamping;
+
+        // don't do collision for static objects or if solver disabled
+        if (!solve) return;
+
+        // which way is down for this object, a negative gravityScale falls up and lands on ceilings
+        const gravityY = this.gravityScale < 0 ? -gravity.y : gravity.y;
+        const wasFalling = this.velocity.y < 0 && gravityY < 0 || this.velocity.y > 0 && gravityY > 0;
+        if (this.groundObject)
+        {
+            // apply friction in local space of ground object
+            const friction = max(this.friction, this.groundObject.friction);
+            const groundSpeed = this.groundObject.velocity.x;
+            this.velocity.x = groundSpeed + (this.velocity.x - groundSpeed) * friction;
+            this.groundObject = undefined;
+        }
+
+        // an object with no width or height has no box to push out of, or to be pushed out of
+        if (this.collideSolidObjects && this.size.x && this.size.y)
+        {
+            // check collisions against solid objects
+            const epsilon = .001; // necessary to push slightly outside of the collision
+            for (const o of engineObjectsCollideStaticLast)
+            {
+                // skip destroyed, child objects, self collision, or objects with no box
+                if (o.destroyed || o.parent || o === this || !o.size.x || !o.size.y) continue;
+
+                // non solid objects don't collide with each other
+                if (!this.isSolid && !o.isSolid) continue;
+
+                // check collision
+                if (!this.isOverlappingObject(o)) continue;
+
+                // each moving object checks its own contacts, so a pair the other one already asked about this frame
+                // is not asked twice: left overlapping, ignored or only nudged apart it is skipped, and one both said
+                // to resolve, pushed back together since, is resolved again
+                const answer = engineObjectsCollidePairAnswer(o, this);
+                if (answer === false) continue;
+                if (!answer)
+                {
+                    // notify objects of collision and check if should be resolved
+                    const collide1 = this.collideWithObject(o);
+                    const collide2 = o.collideWithObject(this);
+                    if (!collide1 || !collide2)
+                    {
+                        engineObjectsCollidePairAdd(this, o);
+                        continue;
+                    }
+                }
+
+                const wasOverlapping = isOverlapping(oldPos, this.size, o.pos, o.size);
+                if (wasOverlapping && (!o.mass || o.groundObject))
+                {
+                    // a static solid that moved into it, like a door or an elevator, pushes it out the shortest way
+                    // at once and carries it along, it would only drift out slowly and the solid would pass through;
+                    // an object standing on something counts as fixed too, so a stack on an elevator rides together;
+                    // it bounces off relative to the mover, a paddle moved by setting pos bounces a ball as a wall does
+                    const push = collideBoxBox(this.pos, this.size, o.pos, o.size);
+                    if (push)
+                    {
+                        this.pos.x += push.x + sign(push.x) * epsilon;
+                        this.pos.y += push.y + sign(push.y) * epsilon;
+                        const restitution = max(this.restitution, o.restitution);
+                        if (push.x)
+                        {
+                            const v = this.velocity.x - o.velocity.x;
+                            if (v * push.x < 0) // moving into it
+                                this.velocity.x = o.velocity.x - v * restitution;
+                        }
+                        else
+                        {
+                            const v = this.velocity.y - o.velocity.y;
+                            if (v * push.y < 0) // moving into it
+                                this.velocity.y = o.velocity.y - v * restitution;
+                            if (push.y * gravityY < 0) // pushed up against gravity, it stands on it
+                                this.groundObject = o;
+                        }
+                    }
+                    engineObjectsCollidePairAdd(this, o);
+
+                    debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f00', undefined, false);
+                    continue;
+                }
+                if (wasOverlapping)
+                {
+                    // if already was touching, try to push away
+                    const deltaPos = oldPos.subtract(o.pos);
+                    const length = deltaPos.length();
+                    const pushAwayAccel = .001;
+                    const velocity = length < .001 ? vec2(0, pushAwayAccel) : deltaPos.scale(pushAwayAccel/length);
+                    this.velocity = this.velocity.add(velocity);
+                    if (o.mass) // push away other object if not fixed
+                        o.velocity = o.velocity.subtract(velocity);
+                    engineObjectsCollidePairAdd(this, o);
+
+                    debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f00', undefined, false);
+                    continue;
+                }
+
+                // check for collision
+                const sizeBoth = this.size.add(o.size);
+                // prefer to push up if small delta, up away from this object's own gravity
+                const smallStepUp = (gravityY > 0 ? o.pos.y - oldPos.y : oldPos.y - o.pos.y)*2 > sizeBoth.y - abs(gravityY);
+                const isBlockedX = abs(oldPos.y - o.pos.y)*2 < sizeBoth.y;
+                const isBlockedY = abs(oldPos.x - o.pos.x)*2 < sizeBoth.x;
+                const restitution = max(this.restitution, o.restitution);
+
+                if (smallStepUp || isBlockedY || !isBlockedX) // resolve y collision
+                {
+                    // push outside object collision
+                    this.pos.y = o.pos.y + (sizeBoth.y/2 + epsilon) * sign(oldPos.y - o.pos.y);
+                    if ((o.groundObject && wasFalling) || !o.mass)
+                    {
+                        // set ground object if landed on something
+                        if (wasFalling)
+                            this.groundObject = o;
+
+                        // bounce if other object is fixed or grounded, relative to it so a rider keeps up with a
+                        // platform moving down instead of landing on it again every few frames
+                        this.velocity.y = o.velocity.y - (this.velocity.y - o.velocity.y) * restitution;
+                    }
+                    else // o has mass here, the other branch already handled the massless case
+                    {
+                        // inelastic collision
+                        const inelastic = (this.mass * this.velocity.y + o.mass * o.velocity.y) / (this.mass + o.mass);
+
+                        // elastic collision
+                        const elastic0 = this.velocity.y * (this.mass - o.mass) / (this.mass + o.mass)
+                            + o.velocity.y * 2 * o.mass / (this.mass + o.mass);
+                        const elastic1 = o.velocity.y * (o.mass - this.mass) / (this.mass + o.mass)
+                            + this.velocity.y * 2 * this.mass / (this.mass + o.mass);
+
+                        // lerp between elastic or inelastic based on restitution
+                        this.velocity.y = lerp(inelastic, elastic0, restitution);
+                        o.velocity.y = lerp(inelastic, elastic1, restitution);
+                    }
+                }
+                if (!smallStepUp && isBlockedX) // resolve x collision
+                {
+                    // push outside collision
+                    this.pos.x = o.pos.x + (sizeBoth.x/2 + epsilon) * sign(oldPos.x - o.pos.x);
+                    if (o.mass)
+                    {
+                        // inelastic collision
+                        const inelastic = (this.mass * this.velocity.x + o.mass * o.velocity.x) / (this.mass + o.mass);
+
+                        // elastic collision
+                        const elastic0 = this.velocity.x * (this.mass - o.mass) / (this.mass + o.mass)
+                            + o.velocity.x * 2 * o.mass / (this.mass + o.mass);
+                        const elastic1 = o.velocity.x * (o.mass - this.mass) / (this.mass + o.mass)
+                            + this.velocity.x * 2 * this.mass / (this.mass + o.mass);
+
+                        // lerp between elastic or inelastic based on restitution
+                        this.velocity.x = lerp(inelastic, elastic0, restitution);
+                        o.velocity.x = lerp(inelastic, elastic1, restitution);
+                    }
+                    else // bounce if other object is fixed, relative to it as a landing is
+                        this.velocity.x = o.velocity.x - (this.velocity.x - o.velocity.x) * restitution;
+                }
+                engineObjectsCollidePairAdd(this, o, true);
+                debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f0f', undefined, false);
+            }
+        }
+        if (this.collideLevel)
+        {
+            // check collision against tiles
+            const hitLayer = tileCollisionTest(this.pos, this.size, this);
+            if (hitLayer)
+            {
+                // if already was stuck in collision, don't do anything
+                // this should not happen unless something starts in collision
+                if (!tileCollisionTest(oldPos, this.size, this))
+                {
+                    // test which side we bounced off (or both if a corner)
+                    const isBlockedX = tileCollisionTest(vec2(this.pos.x, oldPos.y), this.size, this);
+                    const isBlockedY = tileCollisionTest(vec2(oldPos.x, this.pos.y), this.size, this);
+                    const restitution = max(this.restitution, hitLayer.restitution);
+                    if (isBlockedX)
+                    {
+                        // a ledge caught less than maxMove below its top lifts the object onto it instead of stopping it,
+                        // down off a ceiling ledge when gravity points up; zero gravity counts as down
+                        const epsilon = 1e-3;
+                        const maxMove = .1;
+                        const y = gravityY > 0 ?
+                            ceil( oldPos.y+this.size.y/2-1) - this.size.y/2 - epsilon :
+                            floor(oldPos.y-this.size.y/2+1) + this.size.y/2 + epsilon;
+                        if (abs(y - this.pos.y) < maxMove && !tileCollisionTest(vec2(this.pos.x, y), this.size, this))
+                        {
+                            this.pos.y = y;
+                            debugPhysics && debugRect(this.pos, this.size, '#ff0', 0, 0, false, false);
+                            return;
+                        }
+
+                        // move to previous X position and bounce
+                        this.pos.x = oldPos.x;
+                        this.velocity.x *= -restitution;
+                    }
+                    if (isBlockedY || !isBlockedX)
+                    {
+                        if (wasFalling)
+                        {
+                            // adjust position to slightly away from nearest tile
+                            // this prevents gap between object and ground
+                            const epsilon = .0001;
+                            const offset = this.size.y/2 + epsilon;
+                            // rounded in the layer's space as its collision test is, or a bottom a hair below a
+                            // grid line would round to the row under it, inside the floor, and fall through
+                            const layerY = hitLayer.pos.y;
+                            this.pos.y = layerY + (gravityY < 0 ?
+                                floor(oldPos.y - layerY - this.size.y/2) + offset :
+                                ceil( oldPos.y - layerY + this.size.y/2) - offset);
+
+                            // set ground object for tile collision
+                            this.groundObject = hitLayer;
+                        }
+                        else
+                        {
+                            // move to previous Y position
+                            this.pos.y = oldPos.y;
+                            this.groundObject = undefined;
+                        }
+                        // bounce velocity
+                        this.velocity.y *= -restitution;
+                    }
+                    debugPhysics && debugRect(this.pos, this.size, '#f00', 0, 0, false, false);
+                }
+            }
+        }
+    }
+
+    /** Update the object, called automatically by engine once each frame. Does nothing by default. */
+    update() {}
+
+    /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
+    render()
+    {
+        // default object render
+        drawTile(this.pos, this.drawSize || this.size, this.tileInfo, this.color, this.angle, this.mirror, this.additiveColor, glEnable, false);
+    }
+
+    /** Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default. */
+    renderLight() {}
+
+    /** Draw this object into the light system's shadow map, called during its shadow pass when castShadow is set.
+     *  Calls render() by default so the object casts its own shape; override to cast a different one, like a blob at a character's feet so its body stays lit;
+     *  screen space WebGL draws in render() are skipped during the pass */
+    renderShadow() { this.render(); }
+
+    /** Draw this object's shape into the light system's lightmap, called during its light pass when emissive is above
+     *  0; what it draws shows in its own colors that much brighter. Calls render() by default so the whole object
+     *  glows; override to glow a part, like a robot's eyes */
+    renderEmissive() { this.render(); }
+
+    /** Destroy this object, destroy its children, detach its parent, and mark it for removal
+     *  @param {boolean} [immediate] - true removes attached effects like particle emitters at once, false lets them finish first */
+    destroy(immediate=false)
+    {
+        if (this.destroyed) return;
+
+        // disconnect from parent and destroy children
+        this.destroyed = true;
+        this.parent?.removeChild(this);
+        for (const child of this.children)
+        {
+            child.parent = undefined;
+            child.destroy(immediate);
+        }
+    }
+
+    /** Convert from local space to world space
+     *  @param {Vector2} pos - local space point */
+    localToWorld(pos) { return this.pos.add(pos.rotate(this.angle)); }
+
+    /** Convert from world space to local space
+     *  @param {Vector2} pos - world space point */
+    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 */
+    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 */
+    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.
+     *  - Called for each solid tile the physics tests, which can be several times a frame for the same tile, and for
+     *    positions it only tries, so keep it free of side effects or guard them to once a frame
+     *  - this.pos has already moved, so a check on where it came from, like a one way platform, needs the position
+     *    saved in update, as the platformer example does
+     *  @param {number}  tileData - the value of the tile at the position
+     *  @param {Vector2} pos - the tile's bottom left corner in world space
+     *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity */
+    collideWithTile(tileData, pos) { return tileData > 0; }
+
+    /** Called by the engine to check if an object collision should be resolved. Return true for physics to resolve the collision or false to ignore and resolve it manually.
+     *  - Both objects of a touching pair are asked once a frame, whichever order they update in; an object that
+     *    destroys itself here is gone at the end of the frame and is still asked about the pairs left this frame, so a
+     *    bullet that should hit one thing checks its own destroyed flag first
+     *  @param {EngineObject} object - the object to test against
+     *  @param {Vector3} [push] - what it would take to move this object clear, a Vector3 from the 3D plugin, undefined in 2D
+     *  @return {boolean} - true if the collision should be resolved by modifying it's position and velocity
+     */
+    collideWithObject(object, push) { return true; }
+
+    /** Get this object's up vector
+     *  @param {number} [scale] - length of the vector
+     *  @return {Vector2} */
+    getUp(scale=1) { return vec2().setAngle(this.angle, scale); }
+
+    /** Get this object's right vector
+     *  @param {number} [scale] - length of the vector
+     *  @return {Vector2} */
+    getRight(scale=1) { return vec2().setAngle(this.angle+PI/2, scale); }
+
+    /** How long since the object was created
+     *  @return {number} */
+    getAliveTime() { return time - this.spawnTime; }
+
+    /** Get the speed of this object
+     *  @return {number} */
+    getSpeed() { return this.velocity.length(); }
+
+    /** Apply acceleration to this object (adjust velocity, not affected by mass)
+     *  - Does nothing on a static object (mass 0), set its velocity instead
+     *  @param {Vector2} acceleration */
+    applyAcceleration(acceleration)
+    { if (this.mass) this.velocity = this.velocity.add(acceleration); }
+
+    /** Apply angular acceleration to this object
+     *  - Does nothing on a static object (mass 0), set its angleVelocity instead
+     *  @param {number} acceleration */
+    applyAngularAcceleration(acceleration)
+    { if (this.mass) this.angleVelocity += acceleration; }
+
+    /** Apply force to this object (adjust velocity, affected by mass)
+     *  - Does nothing on a static object (mass 0), set its velocity instead
+     *  @param {Vector2} force */
+    applyForce(force)
+    { if (this.mass) this.applyAcceleration(force.scale(1/this.mass)); }
+
+    /** Get the direction of the mirror
+     *  @return {number} -1 if this.mirror is true, or 1 if not mirrored */
+    getMirrorSign() { return this.mirror ? -1 : 1; }
+
+    /** Attaches a child to this with a local transform, returns child for chaining
+     *  @param {EngineObject} child
+     *  @param {Vector2}      [localPos=vec2()]
+     *  @param {number}       [localAngle]
+     *  @return {EngineObject} The child object added */
+    addChild(child, localPos=vec2(), localAngle=0)
+    {
+        ASSERT(!this.destroyed, 'cannot add child to destroyed object');
+        if (this.destroyed) return child;
+        ASSERT(!child.parent && !this.children.includes(child), 'child already has a parent, removeChild it first or use attach');
+        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
+        ASSERT(!child.destroyed, 'cannot add a destroyed child');
+        for (let p = /** @type {EngineObject} */ (this); p; p = p.parent)
+            ASSERT(p !== child, 'cannot add an object as a child of itself or of its own child');
+        this.children.push(child);
+        child.parent = this;
+        child.localPos = localPos.copy();
+        child.localAngle = localAngle;
+        child.updateTransforms();
+        return child;
+    }
+
+    /** Attaches a child to this without moving it: the local transform is worked out from where the child is now,
+     *  where addChild takes one; a child of something else is moved over, returns child for chaining
+     *  @param {EngineObject} child
+     *  @return {EngineObject} The child object attached */
+    attach(child)
+    {
+        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
+        ASSERT(child !== this, 'cannot attach self');
+        child.parent?.removeChild(child);
+        // the local values that updateTransforms turns back into the child's current pos and angle
+        const mirror = this.getMirrorSign(), local = this.worldToLocal(child.pos);
+        local.x *= mirror;
+        return this.addChild(child, local, mirror * (child.angle - this.angle));
+    }
+
+    /** Removes a child from this one, it stays where it is in the world
+     *  @param {EngineObject} child */
+    removeChild(child)
+    {
+        ASSERT(child.parent === this && this.children.includes(child));
+        const i = this.children.indexOf(child);
+        if (i < 0) return; // not a child of this one, release has no assert
+        this.children.splice(i, 1);
+        child.parent = child.localPos = undefined;
+    }
+
+    /** Check if this object's box overlaps another object's box
+     *  @param {EngineObject} object
+     *  @return {boolean} */
+    isOverlappingObject(object)
+    { return this.isOverlapping(object.pos, object.size); }
+
+    /** Check if overlapping a point or aligned bounding box
+     *  @param {Vector2} pos          - Center of box
+     *  @param {Vector2} [size=vec2()] - Size of box, uses a point if undefined
+     *  @return {boolean} */
+    isOverlapping(pos, size=vec2())
+    { return isOverlapping(this.pos, this.size, pos, size); }
+
+    /** Set how this object collides
+     *  @param {boolean} [collideSolidObjects] - Does it collide with solid objects?
+     *  @param {boolean} [isSolid]             - Does it collide with and block other objects? (expensive in large numbers)
+     *  @param {boolean} [collideLevel]        - Does it collide with the level, its tile collision layers?
+     *  @param {boolean} [collideRaycast]      - Does it collide with raycasts? */
+    setCollision(collideSolidObjects=true, isSolid=true, collideLevel=true, collideRaycast=true)
+    {
+        ASSERT(collideSolidObjects || !isSolid, 'solid objects must be set to collide');
+
+        this.collideSolidObjects = collideSolidObjects;
+        this.isSolid = isSolid;
+        this.collideLevel = collideLevel;
+        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()
+    {
+        let text = 'type = ' + this.constructor.name;
+        if (this.pos.x || this.pos.y)
+            text += '\npos = ' + this.pos;
+        if (this.velocity.x || this.velocity.y)
+            text += '\nvelocity = ' + this.velocity;
+        if (this.size.x || this.size.y)
+            text += '\nsize = ' + this.size;
+        if (this.angle)
+            text += '\nangle = ' + this.angle.toFixed(3);
+        text += '\ncolor = ' + this.color;
+        return text;
+    }
+
+    /** Render debug info for this object  */
+    renderDebugInfo()
+    {
+        if (!debug) return;
+
+        // check if there is anything to show
+        const hasPhysics = this.collideLevel || this.collideSolidObjects || this.isSolid;
+        if (!hasPhysics && !this.parent) return;
+
+        // show object info for debugging
+        const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
+        const color = rgb(this.collideLevel?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, .5);
+        debugRect(this.pos, size, color, 0, hasPhysics ? 0 : this.angle, hasPhysics, false); // collision ignores the angle
+        if (this.parent)
+            debugRect(this.pos, size.scale(.8), rgb(1,1,1,.5), 0, this.angle, false, false);
+        this.parent && debugLine(this.pos, this.parent.pos, rgb(1,1,1,.5), .5, 0, false);
+    }
 }
 /**
  * LittleJS Drawing System
@@ -5934,7 +5934,7 @@ function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, l
     // build regular polygon points
     const points = [];
     const sizeX = size.x/2, sizeY = size.y/2;
-    for (let i=sides; i--;)
+    for (let i=sides; i-- > 0;) // a count that is not whole, or below zero, still ends
     {
         const a = (i/sides)*PI*2;
         points.push(vec2(sin(a)*sizeX, cos(a)*sizeY));
@@ -6045,7 +6045,7 @@ function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineC
         if (!ring)
         {
             const points = [];
-            for (let i=sides; i--;)
+            for (let i=sides; i-- > 0;)
             {
                 const a = (i/sides)*PI*2;
                 points.push(vec2(sin(a), cos(a)));
@@ -6145,7 +6145,7 @@ function drawEllipseGradient(pos, size=vec2(1), colorInner=WHITE, colorOuter=CLE
         const startA = (offset%sides)/sides*PI*2;
         const points = [rim(startA)];
         const colors = [outerInt];
-        for (let i=sides; i--;)
+        for (let i=sides; i-- > 0;)
         {
             const a = ((i+offset)%sides)/sides*PI*2;
             points.push(pos);
@@ -6568,7 +6568,8 @@ function isOnScreen(pos, size=0)
 function setAdditiveBlendMode(additive=true)
 {
     glAdditive = additive;
-    drawContext.globalCompositeOperation = additive ? 'lighter' : 'source-over';
+    if (drawContext) // none headless
+        drawContext.globalCompositeOperation = additive ? 'lighter' : 'source-over';
 }
 
 /** Set the Shader that 2D draws use from now on, none for the engine's own
@@ -6691,9 +6692,12 @@ function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth,
     }
     else
     {
-        // copy to offscreen canvas
-        workReadCanvas.width = sWidth;
-        workReadCanvas.height = sHeight;
+        // copy to offscreen canvas, sized again only when the size changes: setting a size remakes the canvas even
+        // to the same one, and a game's tinted tiles are mostly of one size
+        if (workReadCanvas.width !== sWidth || workReadCanvas.height !== sHeight)
+            workReadCanvas.width = sWidth, workReadCanvas.height = sHeight;
+        else
+            workReadContext.clearRect(0, 0, sWidth, sHeight);
         workReadContext.drawImage(image, sx|0, sy|0, sWidth, sHeight, 0, 0, sWidth, sHeight);
 
         // tint image using offscreen work context
@@ -8639,7 +8643,13 @@ class Sound
      */
     constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
-        if (!soundEnable || headlessMode) return;
+        if (!soundEnable || headlessMode)
+        {
+            // no sound is made: it counts as loaded, so a game that waits for its sounds goes on
+            this.loadedPercent = 1;
+            onloadCallback?.(this);
+            return;
+        }
         const rangeIsDefault = range === undefined;
         if (rangeIsDefault)
             range = soundDefaultRange;
@@ -9786,7 +9796,8 @@ function objectLayersMake(tileMapData, object)
     const name = object.type || object.class, type = objectLayersTypes.get(name);
     if (!type)
     {
-        debug && console.warn(`objectLayersLoad: no type added for ${name}, skipped`);
+        // an object with no type, a shape or a text someone drew in Tiled, is not one a game makes
+        debug && name && console.warn(`objectLayersLoad: no type added for ${name}, skipped`);
         return;
     }
     const {height=0, tilewidth=1, tileheight=1} = tileMapData;
@@ -11870,6 +11881,9 @@ function glDrawUntextured(x, y, sizeX, sizeY, angle, rgba)
     glDraw(x, y, sizeX, sizeY, angle, 0, 0, 0, 0, 0, rgba);
 }
 
+// the list and the vectors glDrawPointsTransform writes its points into
+const glPointsOut = [], glPointsPool = [];
+
 /** Transform and add a polygon to the gl draw list
  *  @param {Array<Vector2>} points - Array of Vector2 points
  *  @param {number} rgba - Color of the polygon as a 32-bit integer
@@ -11882,15 +11896,21 @@ function glDrawUntextured(x, y, sizeX, sizeY, angle, rgba)
  *  @memberof WebGL */
 function glDrawPointsTransform(points, rgba, x, y, sx, sy, angle, tristrip=true)
 {
-    const pointsOut = [];
+    // written into vectors kept for this, a circle would make one for each of its sides at every draw; they are
+    // read into the batch before this returns
+    const pointsOut = glPointsOut, pool = glPointsPool, count = points.length;
+    pointsOut.length = count;
     const sa = sin(-angle);
     const ca = cos(-angle);
-    for (const p of points)
+    for (let i = 0; i < count; ++i)
     {
         // transform the point
+        const p = points[i], out = pool[i] ||= vec2();
         const px = p.x*sx;
         const py = p.y*sy;
-        pointsOut.push(vec2(x + ca*px - sa*py, y + sa*px + ca*py));
+        out.x = x + ca*px - sa*py;
+        out.y = y + sa*px + ca*py;
+        pointsOut[i] = out;
     }
     const drawPoints = tristrip ? glPolyStrip(pointsOut) : pointsOut;
     glDrawPoints(drawPoints, rgba);
@@ -13325,8 +13345,11 @@ class PostProcessPlugin
             {
                 // copy main canvas to work canvas at the backing store size,
                 // mainCanvasSize is css pixels so it would lose resolution
-                workCanvas.width = mainCanvas.width;
-                workCanvas.height = mainCanvas.height;
+                // sized again only when the canvas changed, setting a size remakes the canvas even to the same one
+                if (workCanvas.width !== mainCanvas.width || workCanvas.height !== mainCanvas.height)
+                    workCanvas.width = mainCanvas.width, workCanvas.height = mainCanvas.height;
+                else
+                    workContext.clearRect(0, 0, workCanvas.width, workCanvas.height);
                 glCopyToContext(workContext);
                 workContext.drawImage(mainCanvas, 0, 0);
                 // clear the main canvas with clearRect, resizing it would also
@@ -14420,163 +14443,165 @@ class Light extends EngineObject
     }
 }
 
-/**
- * LittleJS ZzFXM Plugin
- * @namespace ZzFXM
- */
-
-/**
- * Music Object - Stores a zzfx music track for later use
- * 
- * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
- * @extends Sound
- * @memberof ZzFXM
- * @example
- * // create some music
- * const music_example = new ZzFXMusic(
- * [
- *     [                         // instruments
- *       [,0,400]                // simple note
- *     ], 
- *     [                         // patterns
- *         [                     // pattern 1
- *             [                 // channel 0
- *                 0, -1,        // instrument 0, left speaker
- *                 1, 0, 9, 1    // channel notes
- *             ], 
- *             [                 // channel 1
- *                 0, 1,         // instrument 0, right speaker
- *                 0, 12, 17, -1 // channel notes
- *             ]
- *         ],
- *     ],
- *     [0, 0, 0, 0], // sequence, play pattern 0 four times
- *     90            // BPM
- * ]);
- * 
- * // play the music on a loop
- * music_example.playMusic();
- */
-class ZzFXMusic extends Sound
-{
-    /** Create a music object and cache the zzfx music samples for later use
-     *  @param {[Array, Array, Array, number?, ...any[]]} zzfxMusic - Array of zzfx music parameters: instruments, patterns, sequence, and an optional BPM; anything after it, like the tracker's metadata, is ignored
-     */
-    constructor(zzfxMusic)
-    {
-        super(undefined);
-
-        if (!soundEnable || headlessMode) return;
-        const [instruments, patterns, sequence, BPM] = zzfxMusic;
-        super.sampleChannels = zzfxM(instruments, patterns, sequence, BPM); // the setter, without declaring a field that hides it in the typings
-        this.buildSampleBuffer(); // hand the samples to an audio buffer now, like a zzfx sound, so the arrays are released
-        this.loadedPercent = 1; // generated in place, so it is loaded like a zzfx sound
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-// ZzFX Music Renderer v2.0.3 by Keith Clark and Frank Force
-
-/** Generate samples for a ZzFM song with given parameters
- *  @param {Array} instruments - Array of ZzFX sound parameters
- *  @param {Array} patterns - Array of pattern data
- *  @param {Array} sequence - Array of pattern indexes
- *  @param {number} [BPM] - Playback speed of the song in BPM
- *  @return {Array} - Left and right channel sample data
- *  @memberof ZzFXM */
-function zzfxM(instruments, patterns, sequence, BPM = 125) 
-{
-  let i, j, k;
-  let instrumentParameters;
-  let note;
-  let sample;
-  let patternChannel;
-  let notFirstBeat;
-  let stop;
-  let instrument;
-  let attenuation;
-  let outSampleOffset;
-  let isSequenceEnd;
-  let sampleOffset = 0;
-  let nextSampleOffset;
-  let sampleBuffer = [];
-  let leftChannelBuffer = [];
-  let rightChannelBuffer = [];
-  let channelIndex = 0;
-  let panning = 0;
-  let hasMore = 1;
-  let sampleCache = {};
-  let beatLength = audioDefaultSampleRate / BPM * 60 >> 2;
-
-  // for each channel in order until there are no more
-  for (; hasMore; channelIndex++) {
-
-    // reset current values
-    sampleBuffer = [hasMore = notFirstBeat = outSampleOffset = 0];
-
-    // for each pattern in sequence
-    sequence.forEach((patternIndex, sequenceIndex)=> {
-      // get pattern for current channel, use empty 1 note pattern if none found
-      patternChannel = patterns[patternIndex][channelIndex] || [0, 0, 0];
-
-      // check if there are more channels
-      hasMore |= patterns[patternIndex][channelIndex]&&1;
-
-      // get next offset, use the length of first channel
-      nextSampleOffset = outSampleOffset + (patterns[patternIndex][0].length - 2 - (notFirstBeat?0:1)) * beatLength;
-      // for each beat in pattern, plus one extra if end of sequence
-      isSequenceEnd = sequenceIndex === sequence.length - 1;
-      for (i = 2, k = outSampleOffset; i < patternChannel.length + isSequenceEnd; notFirstBeat = ++i) {
-
-        // <channel-note>
-        note = patternChannel[i];
-
-        // stop if end, different instrument or new note
-        stop = i === patternChannel.length + isSequenceEnd - 1 && isSequenceEnd ||
-            instrument !== (patternChannel[0] || 0) || note | 0;
-
-        // fill buffer with samples for previous beat, most cpu intensive part
-        for (j = 0; j < beatLength && notFirstBeat;
-
-            // fade off attenuation at end of beat if stopping note, prevents clicking
-            j++ > beatLength - 99 && stop && attenuation < 1? attenuation += 1 / 99 : 0
-        ) {
-          // copy sample to stereo buffers with panning
-          sample = (1 - attenuation) * sampleBuffer[sampleOffset++] / 2 || 0;
-          leftChannelBuffer[k] = (leftChannelBuffer[k] || 0) - sample * panning + sample;
-          rightChannelBuffer[k] = (rightChannelBuffer[k++] || 0) + sample * panning + sample;
-        }
-
-        // set up for next note
-        if (note) {
-          // set attenuation
-          attenuation = note % 1;
-          panning = patternChannel[1] || 0;
-          if (note |= 0) {
-            // get cached sample
-            sampleBuffer = sampleCache[
-              [
-                instrument = patternChannel[sampleOffset = 0] || 0,
-                note
-              ]
-            ] = sampleCache[[instrument, note]] || (
-                // add sample to cache
-                instrumentParameters = [...instruments[instrument]],
-                instrumentParameters[2] = (instrumentParameters[2] || 220) * 2**(note / 12 - 1),
-
-                // allow negative values to stop notes
-                note > 0 ? zzfxG(...instrumentParameters) : []
-            );
-          }
-        }
-      }
-
-      // update the sample offset
-      outSampleOffset = nextSampleOffset;
-    });
-  }
-
-  return [leftChannelBuffer, rightChannelBuffer];
+/**
+ * LittleJS ZzFXM Plugin
+ * - A port of ZzFXM, the Zuper Zmall Zound Zynth music player, by Keith Clark and Frank Force, MIT licensed,
+ *   https://github.com/keithclark/ZzFXM; its notice is in COPYRIGHT.txt
+ * @namespace ZzFXM
+ */
+
+/**
+ * Music Object - Stores a zzfx music track for later use
+ * 
+ * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
+ * @extends Sound
+ * @memberof ZzFXM
+ * @example
+ * // create some music
+ * const music_example = new ZzFXMusic(
+ * [
+ *     [                         // instruments
+ *       [,0,400]                // simple note
+ *     ], 
+ *     [                         // patterns
+ *         [                     // pattern 1
+ *             [                 // channel 0
+ *                 0, -1,        // instrument 0, left speaker
+ *                 1, 0, 9, 1    // channel notes
+ *             ], 
+ *             [                 // channel 1
+ *                 0, 1,         // instrument 0, right speaker
+ *                 0, 12, 17, -1 // channel notes
+ *             ]
+ *         ],
+ *     ],
+ *     [0, 0, 0, 0], // sequence, play pattern 0 four times
+ *     90            // BPM
+ * ]);
+ * 
+ * // play the music on a loop
+ * music_example.playMusic();
+ */
+class ZzFXMusic extends Sound
+{
+    /** Create a music object and cache the zzfx music samples for later use
+     *  @param {[Array, Array, Array, number?, ...any[]]} zzfxMusic - Array of zzfx music parameters: instruments, patterns, sequence, and an optional BPM; anything after it, like the tracker's metadata, is ignored
+     */
+    constructor(zzfxMusic)
+    {
+        super(undefined);
+
+        if (!soundEnable || headlessMode) return;
+        const [instruments, patterns, sequence, BPM] = zzfxMusic;
+        super.sampleChannels = zzfxM(instruments, patterns, sequence, BPM); // the setter, without declaring a field that hides it in the typings
+        this.buildSampleBuffer(); // hand the samples to an audio buffer now, like a zzfx sound, so the arrays are released
+        this.loadedPercent = 1; // generated in place, so it is loaded like a zzfx sound
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// ZzFX Music Renderer v2.0.3 by Keith Clark and Frank Force
+
+/** Generate samples for a ZzFM song with given parameters
+ *  @param {Array} instruments - Array of ZzFX sound parameters
+ *  @param {Array} patterns - Array of pattern data
+ *  @param {Array} sequence - Array of pattern indexes
+ *  @param {number} [BPM] - Playback speed of the song in BPM
+ *  @return {Array} - Left and right channel sample data
+ *  @memberof ZzFXM */
+function zzfxM(instruments, patterns, sequence, BPM = 125) 
+{
+  let i, j, k;
+  let instrumentParameters;
+  let note;
+  let sample;
+  let patternChannel;
+  let notFirstBeat;
+  let stop;
+  let instrument;
+  let attenuation;
+  let outSampleOffset;
+  let isSequenceEnd;
+  let sampleOffset = 0;
+  let nextSampleOffset;
+  let sampleBuffer = [];
+  let leftChannelBuffer = [];
+  let rightChannelBuffer = [];
+  let channelIndex = 0;
+  let panning = 0;
+  let hasMore = 1;
+  let sampleCache = {};
+  let beatLength = audioDefaultSampleRate / BPM * 60 >> 2;
+
+  // for each channel in order until there are no more
+  for (; hasMore; channelIndex++) {
+
+    // reset current values
+    sampleBuffer = [hasMore = notFirstBeat = outSampleOffset = 0];
+
+    // for each pattern in sequence
+    sequence.forEach((patternIndex, sequenceIndex)=> {
+      // get pattern for current channel, use empty 1 note pattern if none found
+      patternChannel = patterns[patternIndex][channelIndex] || [0, 0, 0];
+
+      // check if there are more channels
+      hasMore |= patterns[patternIndex][channelIndex]&&1;
+
+      // get next offset, use the length of first channel
+      nextSampleOffset = outSampleOffset + (patterns[patternIndex][0].length - 2 - (notFirstBeat?0:1)) * beatLength;
+      // for each beat in pattern, plus one extra if end of sequence
+      isSequenceEnd = sequenceIndex === sequence.length - 1;
+      for (i = 2, k = outSampleOffset; i < patternChannel.length + isSequenceEnd; notFirstBeat = ++i) {
+
+        // <channel-note>
+        note = patternChannel[i];
+
+        // stop if end, different instrument or new note
+        stop = i === patternChannel.length + isSequenceEnd - 1 && isSequenceEnd ||
+            instrument !== (patternChannel[0] || 0) || note | 0;
+
+        // fill buffer with samples for previous beat, most cpu intensive part
+        for (j = 0; j < beatLength && notFirstBeat;
+
+            // fade off attenuation at end of beat if stopping note, prevents clicking
+            j++ > beatLength - 99 && stop && attenuation < 1? attenuation += 1 / 99 : 0
+        ) {
+          // copy sample to stereo buffers with panning
+          sample = (1 - attenuation) * sampleBuffer[sampleOffset++] / 2 || 0;
+          leftChannelBuffer[k] = (leftChannelBuffer[k] || 0) - sample * panning + sample;
+          rightChannelBuffer[k] = (rightChannelBuffer[k++] || 0) + sample * panning + sample;
+        }
+
+        // set up for next note
+        if (note) {
+          // set attenuation
+          attenuation = note % 1;
+          panning = patternChannel[1] || 0;
+          if (note |= 0) {
+            // get cached sample
+            sampleBuffer = sampleCache[
+              [
+                instrument = patternChannel[sampleOffset = 0] || 0,
+                note
+              ]
+            ] = sampleCache[[instrument, note]] || (
+                // add sample to cache
+                instrumentParameters = [...instruments[instrument]],
+                instrumentParameters[2] = (instrumentParameters[2] || 220) * 2**(note / 12 - 1),
+
+                // allow negative values to stop notes
+                note > 0 ? zzfxG(...instrumentParameters) : []
+            );
+          }
+        }
+      }
+
+      // update the sample offset
+      outSampleOffset = nextSampleOffset;
+    });
+  }
+
+  return [leftChannelBuffer, rightChannelBuffer];
 }
 /**
  * LittleJS Audio Effects Plugin
@@ -15567,8 +15592,7 @@ class UISystemPlugin
         }
     }
 
-    /** Destroy and remove all objects
-    *  @memberof UISystem */
+    /** Destroy and remove all objects */
     destroyObjects()
     {
         for (const o of this.uiObjects)
@@ -16089,8 +16113,10 @@ class UIObject
                             return void inputClearKey(0, 0, false, true, false);
                     }
                 }
+                // the object that was the active one going into this update: one pressed and let go inside a
+                // frame is clicked on the next, with its release, not on both
                 if (!uiSystem.activateOnPress)
-                if (!mouseDown && this.isActiveObject() && this.interactive)
+                if (!mouseDown && isActive && this.isActiveObject() && this.interactive)
                     this.click();
                 if (this.destroyed) return;
             }
@@ -16833,7 +16859,10 @@ class UIVideo extends UIObject
         if (this.destroyed)
             return;
 
+        // let go of the media too, a paused video keeps what it has loaded
         this.video.pause();
+        this.video.removeAttribute?.('src');
+        this.video.load?.();
         this.video.remove();
         super.destroy();
     }
@@ -20172,6 +20201,7 @@ function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
             for (const group of parseAtlas(data))
             {
                 // reserve a block of full size cells, one per frame
+                if (!group.frames.length) continue; // a tag with no frames, the groups after it still load
                 const sourceSize = group.frames[0].sourceSize;
                 const blockSize = vec2(sourceSize.x*group.frames.length, sourceSize.y);
                 const added = textureSheetAdd(blockSize, sourceSize, padding);
@@ -20957,45 +20987,50 @@ function tweenUpdate(gameDelta, realDelta)
     const list = tweenUpdateList.length ? [] : tweenUpdateList, pass = ++tweenUpdatePass;
     for (const t of tweenActive)
         list.push(t);
-    for (let i = list.length; i--;)
+    // the list is let go however the walk ends: a callback that throws must not leave it held, or every
+    // update after would take it for an update still going and make a list of its own
+    try
     {
-        const t = list[i];
-        // stopped, or started again by a callback this update, or during an update a callback ran inside it, which
-        // counts on from this one
-        if (!t.active || t.activePass >= pass) continue;
-        let dt;
-        if (enginePath)
+        for (let i = list.length; i--;)
         {
-            // a paused tween keeps count too, so it does not jump when resumed
-            dt = t.useRealTime ? timeReal - t.lastTimeReal : time - t.lastTime;
-            t.lastTime = time;
-            t.lastTimeReal = timeReal;
-        }
-        else
-            dt = t.useRealTime ? realDelta : gameDelta;
-        if (t.target?.destroyed) { t.stop(); continue; } // its object is gone, paused or not
-        if (t.paused || dt <= 0) continue;
+            const t = list[i];
+            // stopped, or started again by a callback this update, or during an update a callback ran inside it, which
+            // counts on from this one
+            if (!t.active || t.activePass >= pass) continue;
+            let dt;
+            if (enginePath)
+            {
+                // a paused tween keeps count too, so it does not jump when resumed
+                dt = t.useRealTime ? timeReal - t.lastTimeReal : time - t.lastTime;
+                t.lastTime = time;
+                t.lastTimeReal = timeReal;
+            }
+            else
+                dt = t.useRealTime ? realDelta : gameDelta;
+            if (t.target?.destroyed) { t.stop(); continue; } // its object is gone, paused or not
+            if (t.paused || dt <= 0) continue;
 
-        t.life -= dt;
-        if (t.life > 1e-9) // the engine's deltas add up a rounding error short of the duration
-        {
-            t.callback(t.interp(t.life));
-        }
-        else
-        {
-            // Completion: fire end value, remove from active, start the next iteration
-            // of a loop or pingPong, or when there is none it has completed, fire onComplete
-            t.callback(t.interp(0));
-            if (!t.active || t.activePass >= pass)
-                continue; // stopped or restarted by its own callback, the run it was on ends without completing
-            tweenDeactivate(t);
-            const next = t.thenCallback;
-            t.thenCallback = undefined;
-            if (!(next && next()) && t.onComplete)
-                t.onComplete();
+            t.life -= dt;
+            if (t.life > 1e-9) // the engine's deltas add up a rounding error short of the duration
+            {
+                t.callback(t.interp(t.life));
+            }
+            else
+            {
+                // Completion: fire end value, remove from active, start the next iteration
+                // of a loop or pingPong, or when there is none it has completed, fire onComplete
+                t.callback(t.interp(0));
+                if (!t.active || t.activePass >= pass)
+                    continue; // stopped or restarted by its own callback, the run it was on ends without completing
+                tweenDeactivate(t);
+                const next = t.thenCallback;
+                t.thenCallback = undefined;
+                if (!(next && next()) && t.onComplete)
+                    t.onComplete();
+            }
         }
     }
-    list.length = 0;
+    finally { list.length = 0; }
 }
 
 /** Stop every active tween, ending loops too, without calling their then-callbacks.
@@ -23377,17 +23412,19 @@ function render3DInstance(mesh, matrix, tileInfo, color)
 // make room for one more instance of a mesh under a texture and the current draw state, flushing a batch that
 // differs first, and return where its 24 floats go in mesh.instanceData: the matrix, the tint and the uv rect
 // drawMesh passes whether its matrix mirrors, and its batch then culls by the mesh and winds by that at the flush,
-// so it never sets the draw state for them, which would move the state's version at every draw
-function render3DInstanceSlot(mesh, textureInfo, mirrored)
+// so it never sets the draw state for them, which would move the state's version at every draw; drawBillboard
+// passes that its batch is unlit, for the same reason
+function render3DInstanceSlot(mesh, textureInfo, mirrored, unlit=false)
 {
     const r = render3D;
     if (mesh.instanceCount && (mesh.instanceTextureInfo !== textureInfo || mesh.instanceMirrored !== mirrored
-        || render3DStateChanged(mesh.instanceState)))
+        || mesh.instanceUnlit !== unlit || render3DStateChanged(mesh.instanceState)))
         render3DFlushInstances(mesh);
     if (!mesh.instanceCount)
     {
         mesh.instanceTextureInfo = textureInfo;
         mesh.instanceMirrored = mirrored;
+        mesh.instanceUnlit = unlit;
         mesh.instanceState = render3DCaptureBatchState();
         r.instanceMeshes.push(mesh);
     }
@@ -23421,6 +23458,8 @@ function render3DFlushInstances(only)
         const state = mesh.instanceState;
         if (mesh.instanceMirrored !== undefined) // a drawMesh batch: culled by its mesh, wound by its matrices
             state.cullBackFaces = !mesh.doubleSided, state.mirrored = mesh.instanceMirrored;
+        if (mesh.instanceUnlit) // a batch of sprites
+            state.lighting = false;
         render3DDrawInstanced(mesh, buffer, count, mesh.instanceTextureInfo, state);
     }
     if (!only)
@@ -23777,6 +23816,7 @@ class Render3DPlugin
         /** @type {TextureInfo|undefined} */
         this.streamTileInfo = undefined;
         this.streamState = undefined; // captured state the pending batch was drawn under
+        this.streamUnlit = false;     // the pending batch is drawn unlit whatever that state says, billboards are
         /** @type {Mesh|undefined} */
         this.capture = undefined;     // the mesh a bake is filling
         /** @type {Array<{distance: number, state: Object, draw: function(): void}>|undefined} */
@@ -24167,6 +24207,8 @@ class Render3DPlugin
     {
         if (!this.streamCount || !render3DCanDraw()) return;
         const gl = glContext;
+        if (this.streamUnlit)
+            this.streamState.lighting = false; // its own copy of the state
         render3DSetDrawUniforms(RENDER3D_IDENTITY, this.streamTileInfo, WHITE, RENDER3D_FULL_UV_RECT, this.streamState);
         render3DBindVertexBuffer(this.streamBuffer);
         gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.streamFloats, 0, this.streamCount * RENDER3D_VERTEX_FLOATS);
@@ -24401,13 +24443,34 @@ class Render3DPlugin
             return this.queueTransparent(p, ()=> this.drawBillboard(p, s, tileInfo, c, angle, upright));
         }
 
-        // the quad's six stream vertices written straight in with no vectors made, unlit, for sprites, and for
-        // particles when instancing is off
-        const lit = this.lighting;
-        this.lighting = this.shadowPass && lit; // unlit on screen, in the shadow map the object's flag decides
-        let uvRect;
-        try { uvRect = render3DBeginStrip(6, tileInfo); }
-        finally { this.lighting = lit; }
+        // unlit on screen, in the shadow map the object's flag decides; the batch is told, the draw state is not
+        // set, which would move its version at every sprite
+        const unlit = !this.shadowPass;
+        if (!this.blend && this.depthTest && this.instancing)
+        {
+            // an opaque sprite is one more instance of the shared quad, as a mesh's uses are: every sprite of a
+            // sheet is one instanced draw at the end of the stage, with nothing written per corner; the shader
+            // drops its see through texels, so it needs no sorting
+            if (!render3DCanDraw() || this.shadowPass && !this.lighting) return; // unlit things cast no shadow
+            if (this.frustumCulling && !render3DSphereVisible(pos.x, pos.y, pos.z, hypot(size.x, size.y) / 2))
+                return;
+            const quad = this.billboardMesh, cb = this.cameraBack, uv = render3DGetTileUVs(tileInfo);
+            render3DMeshUpload(quad);
+            // the quad's half axes, doubled for its unit square
+            const a = render3DBillboardAxes(size, angle, upright);
+            const k = render3DInstanceSlot(quad, render3DTextureOf(tileInfo), false, unlit), data = quad.instanceData;
+            data[k]    = a[0] * 2; data[k+1]  = a[1] * 2; data[k+2]  = a[2] * 2; data[k+3]  = 0;
+            data[k+4]  = a[3] * 2; data[k+5]  = a[4] * 2; data[k+6]  = a[5] * 2; data[k+7]  = 0;
+            data[k+8]  = cb.x;     data[k+9]  = cb.y;     data[k+10] = cb.z;     data[k+11] = 0;
+            data[k+12] = pos.x;    data[k+13] = pos.y;    data[k+14] = pos.z;    data[k+15] = 1;
+            data[k+16] = color.r;  data[k+17] = color.g;  data[k+18] = color.b;  data[k+19] = color.a;
+            data[k+20] = uv.x;     data[k+21] = uv.y;     data[k+22] = uv.w;     data[k+23] = uv.h;
+            return;
+        }
+
+        // one that blends is drawn in its sorted place: the quad's six stream vertices written straight in with no
+        // vectors made, for sprites that blend, and for particles when instancing is off
+        const uvRect = render3DBeginStrip(6, tileInfo, unlit);
         if (!uvRect) return;
         const a = render3DBillboardAxes(size, angle, upright);
         const rx = a[0], ry = a[1], rz = a[2], ux = a[3], uy = a[4], uz = a[5];
@@ -25519,8 +25582,9 @@ function render3DRenderDepth()
 // which way they face, so keeping the count even keeps every strip facing out.
 
 // make room in the stream for a strip of count vertices under the current state and texture, flushing a batch that
-// differs first; returns the uv rect to map the vertices with, or undefined when nothing can be drawn
-function render3DBeginStrip(count, tileInfo)
+// differs first; returns the uv rect to map the vertices with, or undefined when nothing can be drawn; unlit draws
+// the batch unlit whatever the state says, so a billboard does not set the state and set it back at every draw
+function render3DBeginStrip(count, tileInfo, unlit=false)
 {
     const r = render3D;
     if (!render3DCanDraw()) return;
@@ -25528,12 +25592,13 @@ function render3DBeginStrip(count, tileInfo)
     ASSERT(count <= RENDER3D_MAX_STREAM_VERTS, 'strip is too large for the stream, bake it into a mesh');
     if (count > RENDER3D_MAX_STREAM_VERTS) return;
     const textureInfo = render3DTextureOf(tileInfo);
-    if (r.streamCount && (textureInfo !== r.streamTileInfo || render3DStateChanged(r.streamState)
-        || r.streamCount + count > RENDER3D_MAX_STREAM_VERTS))
+    if (r.streamCount && (textureInfo !== r.streamTileInfo || r.streamUnlit !== unlit
+        || render3DStateChanged(r.streamState) || r.streamCount + count > RENDER3D_MAX_STREAM_VERTS))
         r.flush();
     render3DFlushBeforeOverlay();
     if (!r.streamCount)
         r.streamState = render3DCaptureBatchState();
+    r.streamUnlit = unlit;
     r.streamTileInfo = textureInfo;
     return render3DGetTileUVs(tileInfo);
 }
@@ -30671,7 +30736,8 @@ let level3DVoxelTiles, level3DVoxelSetupMap, level3DVoxelMap;
 
 /** How a level's block map is made: the sheet its blocks show tiles of, and a function to set it up
  *  - A level's voxels block makes a VoxelMap when the level loads, with texture 0 and the default tile size unless
- *    a sheet is given here; a block's type shows that tile of the sheet on every face
+ *    a sheet is given here; a block's type shows that tile of the sheet on every face; a game that has loaded no
+ *    image gets plain blocks, a color for each type
  *  - setup is called with each map a level makes, to give block types their own faces or make them see-through
  *  - Call it before level3DLoad; with no arguments the defaults are back
  *  @param {TileInfo} [tileInfo] - The sheet's first tile, as for a VoxelMap
@@ -30733,7 +30799,7 @@ function level3DVoxelsMake(voxels)
 {
     const shape = level3DVoxelsShape(voxels);
     if (!shape || typeof VoxelMap == 'undefined') return;
-    const map = new VoxelMap(shape.pos, shape.size, level3DVoxelTiles || tile());
+    const map = new VoxelMap(shape.pos, shape.size, level3DVoxelTiles || level3DVoxelPlainTiles());
     level3DVoxelsDecode(voxels.blocks, map.data);
     level3DVoxelSetupMap?.(map);
     map.rebuild();
@@ -30795,6 +30861,31 @@ function level3DTerrainSetColors(map, terrain, paint=level3DTerrainPaint(terrain
     map.colors = map.heights.map((row, r)=> row.map((v, c)=> palette[paint.cells[r * map.columns + c]] || base));
 }
 
+// the sheet a level's blocks show when the game gave none with level3DVoxelSetup: the game's first image, as a
+// VoxelMap takes it, or, for a game that has loaded no image, plain tiles made here, a color for each type, so a
+// block map in a game with no art can still be seen and painted
+let level3DVoxelPlain;
+function level3DVoxelPlainTiles()
+{
+    if (textureInfos[0]?.size.x || headlessMode || typeof OffscreenCanvas == 'undefined')
+        return tile();
+    if (!level3DVoxelPlain)
+    {
+        // 16 by 16 tiles of 16 pixels, each a color of its own with a darker edge, so the blocks read as blocks
+        const context = createCanvasContext(256);
+        for (let i = 0; i < 256; ++i)
+        {
+            const x = i % 16 * 16, y = (i / 16 | 0) * 16, hue = i * .618 % 1;
+            context.fillStyle = hsl(hue, .45, .4).toString();
+            context.fillRect(x, y, 16, 16);
+            context.fillStyle = hsl(hue, .5, .55).toString();
+            context.fillRect(x + 1, y + 1, 14, 14);
+        }
+        level3DVoxelPlain = new TextureInfo(context.canvas);
+    }
+    return tile(0, 16, level3DVoxelPlain, 0);
+}
+
 // the HeightMap of a level's terrain block, undefined when it has none or it is wrong
 function level3DTerrainMake(terrain)
 {
@@ -32364,6 +32455,11 @@ async function parseGLTF(data, baseUrl='')
     for (const name of json.extensionsRequired || [])
         if (name === 'KHR_draco_mesh_compression' || name === 'EXT_meshopt_compression')
             throw new Error(`glTF with ${name} is not read, export it uncompressed`);
+        else if (name === 'KHR_texture_basisu')
+            throw new Error('glTF with KHR_texture_basisu textures is not read, export them as png or jpeg');
+    // one that only may use them has other images to fall back on, or none: said, since it loads with them left out
+    if (json.extensionsUsed?.includes('KHR_texture_basisu') && !json.extensionsRequired?.includes('KHR_texture_basisu'))
+        console.warn('glTF: KHR_texture_basisu textures are not read and are left out, export them as png or jpeg');
 
     // the buffers: the GLB's own, a data uri, or a file beside the model
     const buffers = await Promise.all((json.buffers || []).map((buffer, i)=>
@@ -32406,7 +32502,8 @@ async function parseGLTF(data, baseUrl='')
             const bitmap = normalTextures.has(index) ?
                 await createImageBitmap(blob, {colorSpaceConversion: 'none', premultiplyAlpha: 'none'}) :
                 opaque ? await createImageBitmap(blob, {premultiplyAlpha: 'none'}).then(gltfOpaqueImage) : await createImageBitmap(blob);
-            return new TextureInfo(bitmap, true, [sampler.wrapS ?? 10497, sampler.wrapT ?? 10497]); // REPEAT by default
+            // REPEAT by default, and hard edged only when its sampler says NEAREST, not as the game's tiles are
+            return new TextureInfo(bitmap, true, [sampler.wrapS ?? 10497, sampler.wrapT ?? 10497], sampler.magFilter === 9728);
         }
         catch (e) { LOG('glTF image not loaded', e); }
     }));
@@ -32516,17 +32613,25 @@ function gltfOpaqueImage(image)
 {
     const gl = glContext, {width, height} = image;
     if (gl.isContextLost()) return image; // nothing to read back through, it keeps its alpha
-    const texture = gl.createTexture(), framebuffer = gl.createFramebuffer(), bound = gl.getParameter(gl.FRAMEBUFFER_BINDING);
-    gl.bindTexture(gl.TEXTURE_2D, texture);
-    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
-    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
-    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+    // the room to read into first: for a huge image it can fail, and must not with the framebuffer bound
     const data = new Uint8ClampedArray(width * height * 4);
-    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, data); // row 0 is the image's first row, as uploaded
-    gl.bindFramebuffer(gl.FRAMEBUFFER, bound);
-    gl.bindTexture(gl.TEXTURE_2D, glActiveTexture);
-    gl.deleteFramebuffer(framebuffer);
-    gl.deleteTexture(texture);
+    const texture = gl.createTexture(), framebuffer = gl.createFramebuffer(), bound = gl.getParameter(gl.FRAMEBUFFER_BINDING);
+    try
+    {
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+        gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, data); // row 0 is the image's first row, as uploaded
+    }
+    finally
+    {
+        // the 2D renderer's own bindings back, whatever happened
+        gl.bindFramebuffer(gl.FRAMEBUFFER, bound);
+        gl.bindTexture(gl.TEXTURE_2D, glActiveTexture);
+        gl.deleteFramebuffer(framebuffer);
+        gl.deleteTexture(texture);
+    }
     for (let i = 3; i < data.length; i += 4)
         data[i] = 255;
     image.close();
@@ -32663,7 +32768,7 @@ function gltfAccessor(json, buffers, index)
     }
     if (scale !== 1)
         for (let i = 0; i < out.length; ++i)
-            out[i] /= scale;
+            out[i] = max(out[i] / scale, -1); // a signed type's lowest value is -1 too, as the format says
     return {data: out, components, count: a.count};
 }
 
@@ -32727,8 +32832,10 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
     const [er, eg, eb] = material.emissiveFactor || [0, 0, 0];
     if (er || eg || eb)
     {
+        // KHR_materials_emissive_strength makes it that many times brighter, emission above 1 in Blender
+        const strength = material.extensions?.KHR_materials_emissive_strength?.emissiveStrength ?? 1;
         part.emissiveMap = emissiveRef ? textures[emissiveRef.index] : gltfWhiteTexture();
-        part.emissiveMapColor = rgb(gltfSRGB(er), gltfSRGB(eg), gltfSRGB(eb));
+        part.emissiveMapColor = rgb(gltfSRGB(er) * strength, gltfSRGB(eg) * strength, gltfSRGB(eb) * strength);
     }
     return part;
 }
@@ -33632,10 +33739,10 @@ class LevelEditor
     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
+     *  editor writes no file, to set or override; it may be async
      *  @param {string} text
      *  @param {string} fileName
-     *  @return {boolean|void} */
+     *  @return {boolean|void|Promise<boolean|void>} */
     onSave(text, fileName) { return false; }
 
     /** True while the editor is open, the game is paused under it
@@ -34002,7 +34109,7 @@ function editorMapRestore(map)
     if (!map.layers || data.some((layer)=> !Array.isArray(layer))) return map;
     const objects = editorObjectGroups(map.layers).map((group)=> group.objects ?? []);
     const url = editorFetchedURLs.get(map), hash = editorMapHash(data, objects, editorMapLayout(map));
-    const fileName = url?.split(/[?#]/)[0].split('/').pop() || 'level.json';
+    const fileName = editorFileName(url, 'level.json');
     const record = {map, url, fileName, key: editorMapKey(map, url, hash), hash,
         original: data.map((layer)=> [...layer]), originalObjects: editorObjectsCopy(objects),
         originalSize: {width: map.width, height: map.height}, layers: []};
@@ -34033,6 +34140,8 @@ function editorMapRestore(map)
         editorRestoreObjects(map, saved);
         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}, ` +
+            'which storage had no room for');
     }
     return map;
 }
@@ -34234,6 +34343,7 @@ async function editorSaveText(record, text, pickAgain)
             if (error?.name === 'AbortError') return; // the picker was closed, nothing saved
             record.fileHandle = undefined; // a file it could not write, a download instead, and not kept
             editorFileStore.set(editorFileKey(record), undefined);
+            console.warn(`LittleJS editor: ${record.fileName} could not be written, downloaded instead`, error);
         }
     }
     saveText(text, record.fileName, 'application/json');
@@ -34250,15 +34360,35 @@ const editorSaves = ()=> readSaveData(editorSaveName(), {});
 // if the last autosave did not fit in storage, the panel says so
 let editorSaveFailed = false;
 
-// write the autosaves, noting whether storage took them
-function editorWriteSaves(saves)
+// write the autosaves, noting whether storage took them; when it did not, the autosave it still has of this map
+// is an older one, and is marked so, for the reload that brings it back to say so
+function editorWriteSaves(saves, key, name=editorSaveName())
 {
     try
     {
-        localStorage.setItem(editorSaveName(), JSON.stringify(saves));
-        editorSaveFailed = false;
+        localStorage.setItem(name, JSON.stringify(saves));
+        return editorSaveFailed = false;
     }
     catch { editorSaveFailed = true; }
+    try
+    {
+        const kept = readSaveData(name, {});
+        if (!kept[key] || kept[key].stale) return true;
+        kept[key].stale = true;
+        localStorage.setItem(name, JSON.stringify(kept));
+    }
+    catch {} // no room for the mark either
+    return true;
+}
+
+// the name of the file a level was fetched from, as it is on disk: without its folder and query, and with what
+// the url spells with a percent as it is written, so it is the name a picked file has
+function editorFileName(url, fallback)
+{
+    const name = url?.split(/[?#]/)[0].split('/').pop();
+    if (!name) return fallback;
+    try { return decodeURIComponent(name); }
+    catch { return name; }
 }
 
 // a map's name for its autosave, the file it was fetched from without a query, or its size, layer names and data as loaded; a map with
@@ -34314,12 +34444,12 @@ function editorAutosave(record)
     else
         saves[record.key] = {hash: record.hash, savedHash: record.savedHash, width: map.width, height: map.height,
             layers: data, objects, nextobjectid: map.nextobjectid};
-    editorWriteSaves(saves);
+    editorWriteSaves(saves, record.key);
 }
 
 // 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)
+function editorPaintData(record, data, objects, width=record.map.width, height=record.map.height, keepUnknown=false)
 {
     editorStrokeEnd();
     if (width !== record.map.width || height !== record.map.height)
@@ -34339,7 +34469,9 @@ function editorPaintData(record, data, objects, width=record.map.width, height=r
             if (gids?.length === width * height)
                 gids.forEach((gid, i)=> editorPaint(layer, vec2(i % width, height - 1 - (i / width | 0)), gid));
         }
-        editorObjectLayers(record).forEach((layer, i)=> objects &&
+        // an autosave from before the file had an object layer leaves that layer as the file has it; Reset to file
+        // empties a layer the file did not have
+        editorObjectLayers(record).forEach((layer, i)=> objects && !(keepUnknown && i >= objects.length) &&
             editorChangeObjects(layer, (list)=> list.splice(0, list.length, ...editorObjectsCopy(objects[i] ?? []))));
     });
     editorStroke ? editorStrokeEnd() : editorAutosave(record);
@@ -34359,7 +34491,7 @@ function editorApplyPending(record)
         return false;
     }
     record.pending = record.pendingUnfit = undefined;
-    editorPaintData(record, saved.layers, saved.objects, saved.width, saved.height);
+    editorPaintData(record, saved.layers, saved.objects, saved.width, saved.height, true);
     return true;
 }
 
@@ -34464,8 +34596,7 @@ function editorClearSelections()
 function editorMapChanged(record, before)
 {
     const stroke = [{resize: record, before, after: editorMapSnapshot(record)}];
-    editorUndoList.push(stroke);
-    editorRedoList.length = 0;
+    editorUndoPush(stroke);
     editorChanged(stroke);
 }
 
@@ -34542,12 +34673,20 @@ function editorPaint(layer, pos, gid)
     (editorStroke ||= []).push({layer, pos: pos.copy(), before, after: gid});
 }
 
+// an edit goes on the undo list, which keeps the last 100, as the 3D editor's does: a fill of a large layer is
+// an entry for every cell, and a session of them would hold millions
+function editorUndoPush(stroke)
+{
+    editorUndoList.push(stroke);
+    editorUndoList.length > 100 && editorUndoList.shift();
+    editorRedoList.length = 0;
+}
+
 // the stroke is done, it can be undone as one
 function editorStrokeEnd()
 {
     if (!editorStroke) return;
-    editorUndoList.push(editorStroke);
-    editorRedoList.length = 0;
+    editorUndoPush(editorStroke);
     editorChanged(editorStroke);
     editorStroke = undefined;
 }
@@ -34957,7 +35096,7 @@ function editorUpdateObjects(space)
             if (!editorObjectSelection.has(hit.id))
                 editorObjectSelection = new Set([hit.id]);
             editorObjectDrag = {start: snap(mouse), from: new Map(editorSelectedObjects().map((object)=>
-                [object.id, editorObjectPos(record, object)]))};
+                [object.id, {x: object.x, y: object.y}]))};
         }
         else if (editorObjectSelection.size)
             editorObjectSelection.clear();
@@ -34972,8 +35111,10 @@ function editorUpdateObjects(space)
         {
             for (const object of list)
             {
-                const from = drag.from.get(object.id);
-                from && editorObjectSetPos(record, object, from.add(delta));
+                // from the numbers it had, in the map's own units: through cells and back they pick up a hair
+                const from = drag.from.get(object.id), {tilewidth=1, tileheight=1} = record.map;
+                if (from)
+                    object.x = from.x + delta.x * tilewidth, object.y = from.y - delta.y * tileheight;
             }
         });
     }
@@ -36868,7 +37009,7 @@ function editor3DLevelLoaded(level)
     const original = editor3DCopy(editor3DObjects()), originalParts = editor3DLevelParts();
     const hash = editor3DContentHash(original, originalParts);
     // sceneBase is the scene the game set, taken before the level's own block is applied
-    const record = {fileName: url ? url.split('/').pop() : 'level3D.json', key: url ?? 'level #' + hash, original,
+    const record = {fileName: editorFileName(url, 'level3D.json'), key: url ?? 'level #' + hash, original,
         originalParts, sceneBase: render3D ? editor3DSceneState() : undefined, hash, pending: undefined,
         fileHandle: undefined, undo: [], redo: []};
     editor3DRecords.set(level, record);
@@ -36969,6 +37110,7 @@ function editor3DChange(change)
     const before = editor3DCopy(editor3DObjects()), after = editor3DCopy(before);
     change(after);
     if (editor3DSame(before, after)) return false;
+    editor3DFixIds(after); // an object added with no id, or with one in use, gets one of its own
     editor3DSetObjects(after);
     editor3DStroke ||= {before, parts: editor3DLevelParts()};
     return true;
@@ -37742,7 +37884,7 @@ function editor3DPrefabJSON(name)
 
 // the prefabs opened one inside the other, each with the level it was opened from, its name, the selection there
 // and the ids of that level's objects that had something made for them
-/** @type {Array<{level: Object, name: string, selection: Array<number>, made: Set<number>, entered?: string, saved?: string}>} */
+/** @type {Array<{level: Object, name: string, selection: Array<number>, made: Set<number>, entered?: string}>} */
 const editor3DPrefabStack = [];
 // the levels that are a prefab being edited, they have no autosave of their own
 const editor3DPrefabLevels = new WeakSet;
@@ -37751,6 +37893,28 @@ const editor3DPrefabLevels = new WeakSet;
 let editor3DPrefabEdits = {};
 // the prefabs of the game's own that were edited and are not in a file yet
 const editor3DPrefabDirty = new Set;
+// what is known of each prefab's file, by its name, so it outlasts the prefab being closed and opened again: the
+// save being written, for the next to wait on, what the file has since a Save, and what the prefab holds now
+/** @type {Map<string, {saving?: Promise<any>, saved?: string, content?: string}>} */
+const editor3DPrefabFiles = new Map;
+function editor3DPrefabFile(name)
+{
+    editor3DPrefabFiles.has(name) || editor3DPrefabFiles.set(name, {});
+    return editor3DPrefabFiles.get(name);
+}
+
+// say if a prefab of the game's own is in its file, now that it holds this: once a Save has written it, it is
+// when what it holds is what was written; before any Save it is not once it was edited
+function editor3DPrefabFileCheck(name, content, edited=false)
+{
+    const file = editor3DPrefabFile(name);
+    file.content = content;
+    if (level3DPrefabs.get(name)?.fromLevel) return; // one of the level's own is saved with the level
+    if (file.saved !== undefined)
+        content === file.saved ? editor3DPrefabDirty.delete(name) : editor3DPrefabDirty.add(name);
+    else if (edited)
+        editor3DPrefabDirty.add(name);
+}
 
 // destroy what the level being edited has in the world, its objects' and its maps'
 function editor3DPrefabClear()
@@ -37804,9 +37968,10 @@ function editor3DPrefabBack()
         level3DPrefabSet(frame.name, prefab, fromLevel);
         if (fromLevel)
             editor3DPrefabEdits[frame.name] = prefab;
-        else if (JSON.stringify(objects) !== frame.saved)
-            editor3DPrefabDirty.add(frame.name); // not what Save wrote while it was open
     }
+    // one of the game's own is in its file or not by what it holds now, edited here or not: undone back to how it
+    // was opened after a Save, it is not what the file has
+    editor3DPrefabFileCheck(frame.name, JSON.stringify(objects), changed);
 
     // the level it was opened from is the editor's again, with its own undo
     const level = editor3DLevel = frame.level, record = editor3DRecords.get(level);
@@ -38134,8 +38299,10 @@ function editor3DAutosave(level=editor3DLevel, known)
             if (known?.fromLevel && JSON.stringify(objects) !== frame.entered)
                 edits[frame.name] = known.attached ? {attached: true, objects} : {objects};
         });
-        if (root && Object.keys(edits).length)
-            editor3DAutosave({...root, prefabs: {...editor3DLevelPart('prefabs', root), ...edits}}, editor3DRecords.get(root));
+        // with nothing edited any more, an undo back to how the prefab was, the level's autosave is the level's own
+        // again, which takes away one of an edit that was undone and keeps the level's other edits
+        const prefabs = {...editor3DLevelPart('prefabs', root), ...edits};
+        root && editor3DAutosave(Object.keys(prefabs).length ? {...root, prefabs} : root, editor3DRecords.get(root));
         return;
     }
     const record = known ?? editor3DRecords.get(level);
@@ -38149,12 +38316,9 @@ function editor3DAutosave(level=editor3DLevel, known)
     else
         saves[record.key] = {hash: record.hash, savedHash: record.savedHash, objects: editor3DCopy(objects),
             ...parts};
-    try
-    {
-        localStorage.setItem(editor3DSaveName(), JSON.stringify(saves));
-        editor3DSaveFailed = false;
-    }
-    catch { editor3DSaveFailed = true; }
+    const failed = editorSaveFailed; // the 2D editor's own flag is its own
+    editor3DSaveFailed = editorWriteSaves(saves, record.key, editor3DSaveName());
+    editorSaveFailed = failed;
 }
 
 // put the autosaved edits of a file that changed into the level, as one undo
@@ -38211,16 +38375,23 @@ async function editor3DSave(pickAgain=false)
         // inside a prefab, Save writes the prefab as a file of its own, or the game keeps it itself
         const text = editor3DLevelJSON(level), name = open.name + '.json';
         const written = JSON.stringify(editor3DObjects()); // as the file has it
+        // its place in line is the prefab's, by its name: closed and opened again it is a new level here, and its
+        // saves still go in the order they were asked for
+        const file = editor3DPrefabFile(open.name), before = file.saving;
         const saved = (async ()=>
         {
-            await record.saving; // in the order asked for, as a level's saves are
+            await before;
             const kept = await editorCall('onSave', text, name) === true;
             kept || saveText(text, name, 'application/json');
-            editor3DPrefabDirty.delete(open.name);
-            open.saved = written;
+            file.saved = written;
+            // it is in its file when what it holds now is what was written: edited again while the save was
+            // kept, or gone back from with more edits, it still waits
+            const at = editor3DPrefabStack.indexOf(open);
+            const now = at < 0 ? file.content : JSON.stringify((editor3DPrefabStack[at + 1]?.level ?? editor3DLevel).objects);
+            editor3DPrefabFileCheck(open.name, now ?? written);
             return kept ? 'kept' : 'downloaded';
         })();
-        record.saving = saved.catch(()=> {});
+        file.saving = saved.catch(()=> {});
         return saved;
     }
     // what is written, kept as it is now: the level can change while the file is picked and written, and those