littlejsengine 1.24.3 → 1.26.0

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.24.3';
+const engineVersion = '1.26.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -179,7 +179,134 @@ function engineObjectsCollidePairAdd(asker, other, resolve=false)
     others || engineObjectsCollidePairs.set(asker, others = new Map);
     others.set(other, resolve);
 }
+
+// with this many solids or more, a mover finds what is near it through a grid of cells rather than checking every
+// solid, a big game's cost going from every pair to what is close; it resolves the same contacts in the same order,
+// so a game plays the same either way, and a few solids are quicker checked all
+let engineCollideGridMin = 64;
+// the grid for this update, {list, built}: the list of solids, and the grid made from it the first time a 2D mover
+// walks it, so a frame with no 2D mover, as 3D solids alone, makes none; built is each cell's solids, each solid's
+// cells, and each solid's place in the list, which the contacts are taken in; solids too big for cells are near
+// everything
+let engineCollideGrid;
+
+// the grid of a list of solids, its cells about twice a typical solid so most are in one to four
+function engineCollideGridBuild(list)
+{
+    let extent = 0;
+    for (const o of list)
+        extent += min(max(abs(o.size.x), abs(o.size.y)), 16) || 0; // a negative size is a mirrored one
+    const index = new Map;
+    const grid = {size: max(2 * extent / list.length, .5), cells: new Map, at: new Map, index, big: new Set,
+        seen: new Map, stamp: 0, byIndex: (a, b)=> index.get(a) - index.get(b)}; // what a query found, and its order
+    list.forEach((o, i)=> { index.set(o, i); engineCollideGridPlace(grid, o); });
+    return grid;
+}
+
+// the cells an object's box covers, first and last along x and y, in one kept array to read at once; a negative size
+// is a mirrored sprite of that size
+const engineCollideGridBox = [0, 0, 0, 0];
+function engineCollideGridCells(grid, o)
+{
+    const s = grid.size, w = abs(o.size.x) / 2, h = abs(o.size.y) / 2, box = engineCollideGridBox;
+    box[0] = floor((o.pos.x - w) / s), box[1] = floor((o.pos.y - h) / s);
+    box[2] = floor((o.pos.x + w) / s), box[3] = floor((o.pos.y + h) / s);
+    return box;
+}
+
+// whether a box is kept in its cells: not over 1024 of them, and within 2^31 cells of the origin, past which a cell
+// loop would not end, as ++ stops changing a number past 2^53, and the keys would not be exact; one with no finite
+// box does not fit either, and is near every mover
+const engineCollideGridFits = (x0, y0, x1, y1)=> (x1 - x0 + 1) * (y1 - y0 + 1) <= 1024 &&
+    abs(x0) < 2**31 && abs(y0) < 2**31 && abs(x1) < 2**31 && abs(y1) < 2**31;
+
+// put a solid in the cells its box covers now, out of those it was in; a box on a cell's edge is in both cells, so
+// solids that touch share one
+function engineCollideGridPlace(grid, o)
+{
+    if (!grid.index.has(o)) return;
+    const [x0, y0, x1, y1] = engineCollideGridCells(grid, o);
+    const big = !engineCollideGridFits(x0, y0, x1, y1);
+    const was = grid.at.get(o);
+    if (was && was[0] === x0 && was[1] === y0 && was[2] === x1 && was[3] === y1 && was[4] === big) return;
+    if (was && !was[4])
+        for (let x = was[0]; x <= was[2]; ++x)
+        for (let y = was[1]; y <= was[3]; ++y)
+        {
+            const cell = grid.cells.get(x * 1048576 + y);
+            cell.splice(cell.indexOf(o), 1);
+        }
+    grid.big.delete(o);
+    if (big)
+        grid.big.add(o);
+    else
+        for (let x = x0; x <= x1; ++x)
+        for (let y = y0; y <= y1; ++y)
+        {
+            const key = x * 1048576 + y;
+            const cell = grid.cells.get(key);
+            cell ? cell.push(o) : grid.cells.set(key, [o]);
+        }
+    grid.at.set(o, [x0, y0, x1, y1, big]);
+}
+
+// the solids a mover is near, after a place in the list, in list order, filled into near; each found once, by the
+// query's stamp
+function engineCollideGridNear(grid, o, after, near)
+{
+    const [x0, y0, x1, y1] = engineCollideGridCells(grid, o);
+    const stamp = ++grid.stamp;
+    near.length = 0;
+    for (const other of grid.big)
+        engineCollideGridAdd(grid, other, after, stamp, near);
+    if (engineCollideGridFits(x0, y0, x1, y1))
+    {
+        for (let x = x0; x <= x1; ++x)
+        for (let y = y0; y <= y1; ++y)
+        {
+            const cell = grid.cells.get(x * 1048576 + y);
+            if (cell)
+                for (const other of cell)
+                    engineCollideGridAdd(grid, other, after, stamp, near);
+        }
+    }
+    else
+        for (const other of grid.index.keys()) // a mover too big for cells is near everything
+            engineCollideGridAdd(grid, other, after, stamp, near);
+    near.sort(grid.byIndex);
+}
+
+// add a solid to what a query found, once, when it is after the place in the list
+function engineCollideGridAdd(grid, other, after, stamp, near)
+{
+    if (grid.seen.get(other) === stamp) return;
+    grid.seen.set(other, stamp);
+    grid.index.get(other) > after && near.push(other);
+}
+
+// the solids a mover checks, as checking every one would reach them: in list order, and found again from where it is
+// whenever its box has moved, as a push does, so a solid it is pushed into later in the list is still checked
+function* engineCollideGridWalk(o)
+{
+    const grid = engineCollideGrid.built ||= engineCollideGridBuild(engineCollideGrid.list);
+    let after = -1, x, y, w, h, k = 0;
+    const near = [];
+    for (;;)
+    {
+        if (o.pos.x !== x || o.pos.y !== y || o.size.x !== w || o.size.y !== h)
+        {
+            x = o.pos.x, y = o.pos.y, w = o.size.x, h = o.size.y;
+            engineCollideGridNear(grid, o, after, near);
+            k = 0;
+        }
+        if (k >= near.length) return;
+        const other = near[k++];
+        after = grid.index.get(other);
+        yield other;
+    }
+}
 let engineInitialized = false; // engineInit ran, with or without a canvas
+let engineInitDone; // the promise the first engineInit hands back, which a second call hands back too
 // the loads startup waits for, each counted for the loading screen, and how many are done; undefined once the game
 // loop starts
 let engineLoads, engineLoadsDone = 0;
@@ -223,7 +350,7 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
         p.update === update && p.render === render &&
         p.glContextLost === glContextLost &&
         p.glContextRestored === glContextRestored &&
-        p.preRender === preRender));
+        p.preRender === preRender), 'engineAddPlugin: this plugin was already added');
 
     const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored, preRender);
     pluginList.push(plugin);
@@ -305,7 +432,7 @@ function engineLoadingScreenDraw(elapsed)
  *  @param {GameCallback} [gameUpdatePost] - Called after physics and objects are updated, even when paused, use for UI updates
  *  @param {GameCallback} [gameRender] - Called before objects are rendered, use for drawing backgrounds/world elements
  *  @param {GameCallback} [gameRenderPost] - Called after objects are rendered, use for drawing UI/overlays
- *  @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
+ *  @param {Array<string>|string} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png']), or one path
  *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
  *    It keeps its own inline styles and the canvas centers inside it, but the canvas is still sized from the window,
  *    so set canvasFixedSize or canvasMaxSize to fit a smaller element
@@ -319,16 +446,19 @@ function engineLoadingScreenDraw(elapsed)
  *    ()=> { drawHUD(); },                 // gameRenderPost
  *    ['tiles.png', 'tilesLevel.png']       // images to load
  *  );
- *  @memberof Engine */
+ *  @memberof Engine
+ *  @return {Promise<void>} - Done when the images have loaded and gameInit has run */
 async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement)
 {
-    showEngineVersion && console.log(`${engineName} Engine v${engineVersion}`);
     ASSERT(!engineInitialized, 'engine already initialized');
     // runtime guard so release builds (where the assert is stripped) don't
-    // double-register listeners / double-add canvases on a second call
-    if (engineInitialized) return;
+    // double-register listeners / double-add canvases on a second call, which is done when the first is
+    if (engineInitialized) return engineInitDone;
     engineInitialized = true;
+    showEngineVersion && console.log(`${engineName} Engine v${engineVersion}`);
     engineLoads = [], engineLoadsDone = 0;
+    if (typeof imageSources === 'string')
+        imageSources = [imageSources]; // one image given alone
     ASSERT(isArray(imageSources), 'pass in images as array');
 
     // allow passing in empty functions
@@ -470,8 +600,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             debugUpdate();
             gameUpdatePost();
             inputUpdatePost();
-            if (debugVideoCaptureIsActive())
-                renderFrame();
         }
 
         // manual step turned on by this frame's updates, set the buffer the loop and smoothing just moved again
@@ -493,7 +621,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
         // render only when something changed, displays that refresh faster
         // than the fixed update rate would otherwise redraw identical frames
-        if (!debugVideoCaptureIsActive() && (wasUpdated || windowChanged))
+        if (wasUpdated || windowChanged)
             renderFrame();
         engineManualStep || engineScheduleFrame();
 
@@ -525,14 +653,13 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             inputRender();
             debugRender();
             glFlush();
-            debugRenderPost();
             drawCount = 0;
             primitiveCount = 0;
         }
     }
 
     // skip setup if headless
-    if (headlessMode) return startEngine([]);
+    if (headlessMode) return engineInitDone = startEngine([]);
 
     // ensure body exists for minimal HTML where the script runs before <body> is parsed
     if (!document.body)
@@ -610,21 +737,25 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(splash);
     }
 
-    // the splash first, the images load under it, then the loading screen for the rest
-    showSplashScreen && await promises[promises.length - 1];
-    return startEngine(promises);
+    // kept before anything is awaited, so a second call has it
+    return engineInitDone = startEngine(promises);
 
-    // gameInit runs once the images are in, and the game loop starts once it and everything loaded while it ran are
-    // done, the loading screen showing in the meantime; an error in gameInit reaches the caller
+    // the splash first, the images load under it, then gameInit runs once they are in, and the game loop starts once
+    // it and everything loaded while it ran are done, the loading screen showing in the meantime; an error in gameInit
+    // reaches the caller
     async function startEngine(images)
     {
+        showSplashScreen && !headlessMode && await images[images.length - 1]; // headless has no splash
         const init = (async ()=> { await Promise.all(images); await gameInit(); })();
         engineAddLoad(init);
         await engineWaitForLoads();
         engineLoads = undefined;
         await init;
         engineUpdateInternal = engineUpdate; // engineStep only runs once the game is set up
-        engineManualStep || engineUpdate();
+        if (engineManualStep) return;
+        if (debug) return engineUpdate(); // a debug build stops at an error, the first frame's as any
+        try { engineUpdate(); }
+        catch (error) { engineFrameFailed(error); } // a release build goes on past it, as on any later frame
     }
 }
 
@@ -642,7 +773,7 @@ function engineUpdateCanvas()
     if (canvasFixedSize.x)
     {
         // set canvas fixed size
-        mainCanvasSize = canvasFixedSize.copy();
+        mainCanvasSize.set(canvasFixedSize.x, canvasFixedSize.y);
 
         // fit to window using css width and height
         const innerAspect = innerWidth / innerHeight;
@@ -666,7 +797,8 @@ function engineUpdateCanvas()
 
         // responsive aspect ratio, of the size after canvasMaxSize, which can change its shape
         const innerAspect = mainCanvasSize.x / mainCanvasSize.y;
-        ASSERT(!canvasMaxAspect || canvasMinAspect <= canvasMaxAspect);
+        ASSERT(!canvasMaxAspect || canvasMinAspect <= canvasMaxAspect,
+            'canvasMinAspect must not be above canvasMaxAspect', canvasMinAspect, canvasMaxAspect);
         if (canvasMaxAspect && innerAspect > canvasMaxAspect)
         {
             // full height
@@ -702,9 +834,12 @@ function engineUpdateCanvas()
     }
     else
     {
-        // setting the size also resets the context state, match that
+        // setting the size also resets the context state, match that, what a game may have left on it too
         mainContext.setTransform(1, 0, 0, 1, 0, 0);
         mainContext.globalCompositeOperation = 'source-over';
+        mainContext.globalAlpha = 1;
+        mainContext.filter = 'none';
+        mainContext.shadowColor = 'rgba(0,0,0,0)';
         mainContext.clearRect(0, 0, bufferSizeX, bufferSizeY);
     }
 
@@ -725,6 +860,18 @@ function engineUpdateCanvas()
     mainContext.lineCap  = 'round';
 }
 
+// a release build goes on past an error in a frame, a frozen game is the worst a player can get; an error is logged
+// when it is not the last one again, one every frame would flood the console
+function engineFrameFailed(error)
+{
+    const text = String(error);
+    text === engineFrameErrorLast || console.error(error);
+    engineFrameErrorLast = text;
+    // the frame's input is cleared as its tick would have, or a key press that threw would be pressed again
+    inputUpdatePost();
+    engineScheduleFrame();
+}
+
 // ask for the next frame of the loop, once however often it is called before that frame, and skip it if manual
 // step was turned on since, so turning it off and on again within a frame can not start a second loop
 function engineScheduleFrame()
@@ -737,17 +884,7 @@ function engineScheduleFrame()
         if (engineManualStep) return;
         if (debug) return engineUpdateInternal(frameTimeMS); // a debug build stops at an error, where it shows it
         try { engineUpdateInternal(frameTimeMS); }
-        catch (error)
-        {
-            // a release build goes on past an error in a frame, a frozen game is the worst a player can get; an error
-            // is logged when it is not the last one again, one every frame would flood the console
-            const text = String(error);
-            text === engineFrameErrorLast || console.error(error);
-            engineFrameErrorLast = text;
-            // the frame's input is cleared as its tick would have, or a key press that threw would be pressed again
-            inputUpdatePost();
-            engineScheduleFrame();
-        }
+        catch (error) { engineFrameFailed(error); }
     };
     if (typeof requestAnimationFrame === 'function')
         requestAnimationFrame(next);
@@ -768,7 +905,7 @@ const engineStepMaxFrames = 36000;
  *  setHeadlessMode(true);
  *  setEngineManualStep(true);
  *  await engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
- *  engineStep(600); // advance 10 seconds of game time
+ *  engineStep(600); // 600 updates of 1/60 second; the first is at time 0, so time is then 599/60
  *  @memberof Engine */
 function engineStep(frames=1)
 {
@@ -805,11 +942,23 @@ function engineObjectsUpdate()
         o.collideSolidObjects && (engineObjectsCollide.push(o), (o.mass ? engineObjectsCollideStaticLast : fixed).push(o));
     for (const o of fixed)
         engineObjectsCollideStaticLast.push(o);
+    // written only when there is a grid: V8 keeps a variable that is never written as a constant, and writing it
+    // every frame makes this function deoptimize again and again in a game with no grid
+    if (engineObjectsCollideStaticLast.length >= engineCollideGridMin)
+        engineCollideGrid = {list: engineObjectsCollideStaticLast, built: undefined};
 
-    // update physics before object update
-    for (const o of engineObjects)
-        if (!o.parent && !o.destroyed)
-            o.updatePhysics();
+    // update physics before object update, each solid put where it moved to in the grid, for the movers after it;
+    // the grid is let go even when a callback throws, so an updatePhysics called before the next update checks all
+    try
+    {
+        for (const o of engineObjects)
+            if (!o.parent && !o.destroyed)
+            {
+                o.updatePhysics();
+                engineCollideGrid?.built && engineCollideGridPlace(engineCollideGrid.built, o);
+            }
+    }
+    finally { engineCollideGrid && (engineCollideGrid = undefined); }
 
     // recursive object update: the children are walked from a copy on a shared stack, since a child that
     // destroys itself leaves its parent's list on the spot and the next child would slide past the loop
@@ -819,9 +968,12 @@ function engineObjectsUpdate()
         const start = engineChildStack.length;
         for (const child of children)
             engineChildStack.push(child);
-        for (let i = start; i < engineChildStack.length; ++i)
-            updateChildObject(engineChildStack[i]);
-        engineChildStack.length = start;
+        try
+        {
+            for (let i = start; i < engineChildStack.length; ++i)
+                updateChildObject(engineChildStack[i]);
+        }
+        finally { engineChildStack.length = start; } // put back when an update throws too, or it keeps them
     }
     const pass = engineObjectsUpdateCount;
     function updateChildObject(o)

package/src/engineAudio.js

@@ -20,6 +20,9 @@
  *  @memberof Audio */
 let audioContext = typeof AudioContext == 'undefined' ? undefined : new AudioContext;
 
+// resume the audio, a refusal caught so it is not an uncaught error in the console, the next gesture tries again
+function audioResume() { audioContext?.resume()?.catch?.(()=> {}); }
+
 /** Master gain node for all audio to pass through, made at load so effects can connect to it any time
  *  @type {GainNode}
  *  @memberof Audio */
@@ -35,7 +38,8 @@ if (audioMasterGain)
 // soundVolume can be set directly, so the master gain follows it each frame
 function audioUpdateVolume()
 {
-    if (audioMasterGain && soundVolume !== audioMasterVolume)
+    // a volume that is not a number, from a slider's text say, is not handed on, where every frame it would throw
+    if (audioMasterGain && soundVolume !== audioMasterVolume && isFinite(soundVolume))
         audioMasterGain.gain.value = audioMasterVolume = soundVolume;
 }
 
@@ -76,6 +80,7 @@ function audioSetSession()
 let audioSuspendedWhenHidden = false;
 function audioVisibilityChange()
 {
+    if (!audioContext) return; // a browser with no audio has none to pause
     if (document.hidden)
     {
         if (!soundPauseWhenHidden || audioContext.state != 'running') return;
@@ -85,7 +90,7 @@ function audioVisibilityChange()
     else if (audioSuspendedWhenHidden)
     {
         audioSuspendedWhenHidden = false;
-        audioContext.resume();
+        audioResume();
     }
 }
 
@@ -122,7 +127,6 @@ function audioStateChange()
  *  - The output node is disconnected from everything else first, so it only feeds the speakers
  *  - The two ends of a chain must already be connected to each other, like effectA.connect(effectB)
  *  - Call with no arguments to remove the effect, an effect that was the master goes back to feeding the master gain
- *  - Debug video capture records the end of the master chain, but loses its tap if the effect changes mid-capture
  *  @param {AudioNode|AudioEffectNodes} [input] - Node or effect the master gain connects to
  *  @param {AudioNode|AudioEffectNodes} [output] - Node or effect that connects to the audio destination, defaults to the input's output
  *  @memberof Audio */
@@ -177,11 +181,16 @@ function audioEffectNode(effectOrNode, key)
     return /** @type {AudioNode} */ (effectOrNode);
 }
 
+// a value for an audio param, which throws on one that is not finite, so a release build, with no asserts to stop it,
+// takes NaN or Infinity as the value given in its place: silent, centered or the normal rate
+const audioFinite = (value, otherwise)=> isFinite(value) ? value : otherwise;
+
 // ramp an audio param to a value, cancelling anything already scheduled so stacked calls don't fight;
 // returns when the ramp ends
 function audioParamRamp(param, value, fadeTime=0)
 {
     ASSERT(fadeTime >= 0, 'fadeTime must be positive or zero');
+    value = audioFinite(value, 0), fadeTime = audioFinite(fadeTime, 0);
     const startTime = audioContext.currentTime;
     param.cancelScheduledValues(startTime);
     if (fadeTime)
@@ -197,7 +206,7 @@ function audioParamRamp(param, value, fadeTime=0)
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * @callback SoundLoadCallback - Function called when sound is loaded
+ * @callback SoundLoadCallback - Function called once a sound has loaded, or failed to, which sound.isLoaded() tells
  * @param {Sound} sound
  * @memberof Audio
  */
@@ -224,11 +233,12 @@ function audioParamRamp(param, value, fadeTime=0)
 class Sound
 {
     /** Create a sound object and cache the audio for later use
-     *  @param {string|URL|Array} [asset] - Filename or URL of an audio file, or a zzfx array
+     *  @param {string|URL|Array<number|undefined>} [asset] - Filename or URL of an audio file, or a zzfx array
      *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds it overrides the array's own randomness, which is used if undefined
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
-     *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
+     *  @param {SoundLoadCallback} [onloadCallback] - Called once the sound has loaded, or its file failed to, so a
+     *    game counting its sounds goes on; isLoaded says which
      */
     constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
@@ -287,7 +297,7 @@ class Sound
 
             // remove randomness so it can be applied on playback, a value passed in wins over the array's
             const randomnessIndex = 1;
-            this.randomness = randomness ?? zzfxSound[randomnessIndex] ?? .05;
+            this.randomness = randomness ?? clamp(zzfxSound[randomnessIndex] ?? .05); // 0 to 1, as one passed in
             zzfxSound[randomnessIndex] = 0;
 
             // generate the zzfx samples, then hand them to an audio buffer so
@@ -303,7 +313,12 @@ class Sound
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
             engineAddLoad(this.loadSound(filename).catch(e=> // startup waits for it, and a release build says why too
-                console.warn('Sound load failed for', filename, '-', e?.message ?? e)));
+            {
+                console.warn('Sound load failed for', filename, '-', e?.message ?? e);
+                // failed, not loaded and its callback threw; one that throws here says so, a load is no place to stop
+                try { this.loadedPercent === 1 || this.onloadCallback?.(this); }
+                catch (callbackError) { console.warn('Sound onloadCallback failed for', filename, '-', callbackError); }
+            }));
         }
     }
 
@@ -386,8 +401,8 @@ class Sound
             {
                 // apply range based fade
                 const lengthSquared = cameraPos.distanceSquared(pos);
-                if (lengthSquared > range*range)
-                    return; // out of range
+                if (lengthSquared >= range*range)
+                    return; // out of range, at it too, where the fade is silent
 
                 // attenuate volume by distance, full volume out to the taper and a fade past it,
                 // so a taper of 1 plays at full volume right up to the range
@@ -463,14 +478,14 @@ class Sound
      */
     isLoaded() { return this.loadedPercent === 1; }
     
-    /** Loads a sound from a URL and decodes it into sample data.
+    /** Loads a sound from a URL and decodes it into sample data
     *  @param {string} filename
     *  @return {Promise} */
     async loadSound(filename)
     {
-        const response = await fetch(filename);
+        const response = await loadFetch(filename, 'loadSound'); // named, with the hint for a page opened from disk
         if (!response.ok)
-            throw new Error(`Failed to load sound from ${filename}: ${response.status} ${response.statusText}`);
+            throw new Error(`loadSound: could not load ${filename}, HTTP ${response.status} ${response.statusText}`);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         
@@ -521,11 +536,11 @@ class SoundInstance
         /** @property {Sound} - The sound object */
         this.sound = sound;
         /** @property {number} - How much to scale volume by */
-        this.volume = volume;
+        this.volume = audioFinite(volume, 0);
         /** @property {number} - The playback rate to use */
-        this.rate = rate;
+        this.rate = audioFinite(rate, 1);
         /** @property {number} - How much to apply stereo panning */
-        this.pan = pan;
+        this.pan = audioFinite(pan, 0);
         /** @property {boolean} - Should the sound loop */
         this.loop = loop;
         /** @property {number|undefined} - Where it is in the sound while not playing, in the sound's own seconds, undefined while playing
@@ -617,7 +632,7 @@ class SoundInstance
     {
         ASSERT(volume >= 0, 'Sound volume must be positive or zero');
         ASSERT(fadeTime >= 0, 'Sound fade time must be positive or zero');
-        this.volume = volume;
+        this.volume = volume = audioFinite(volume, 0);
         this.gainNode && audioParamRamp(this.gainNode.gain, volume, fadeTime);
     }
 
@@ -627,7 +642,7 @@ class SoundInstance
     setPan(pan)
     {
         ASSERT(isNumber(pan), 'Sound pan must be a number');
-        this.pan = pan;
+        this.pan = pan = audioFinite(pan, 0);
         if (this.pannerNode)
             this.pannerNode.pan.value = clamp(pan, -1, 1);
     }
@@ -645,7 +660,7 @@ class SoundInstance
             this.startOffset = this.getCurrentTime();
             this.startTime = audioContext.currentTime;
         }
-        this.rate = rate;
+        this.rate = rate = audioFinite(rate, 1);
         if (this.source)
             this.source.playbackRate.value = rate;
     }
@@ -721,7 +736,9 @@ class SoundInstance
         if (!this.isPlaying()) return this.pausedTime;
         const duration = this.getDuration();
         const place = this.startOffset + (audioContext.currentTime - this.startTime) * this.rate;
-        return duration ? mod(place, duration) : 0; // a sound still loading has no length yet
+        // a sound still loading has no length yet; a loop goes around, a one shot past its end, before its ended
+        // event, stays at its end, so a pause there does not play it again on resume
+        return !duration ? 0 : this.loop ? mod(place, duration) : min(place, duration);
     }
 
     /** Get the length of the sound in its own seconds, the same at any rate; divide by the rate for how long it takes to play
@@ -795,7 +812,7 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {number}   [rate] - The playback rate to use
  *  @param {number}   [pan] - How much to apply stereo panning
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
- *  @param {number}   [sampleRate=44100] - Sample rate for the sound
+ *  @param {number}   [sampleRate=audioDefaultSampleRate] - Sample rate for the sound
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
  *  @param {number}   [offset] - Where to start in the sound, in its own seconds whatever the rate
  *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
@@ -812,7 +829,7 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
         // fix stalled audio, don't build a buffer that can't be played;
         // but a context suspended because the page is hidden stays suspended until it shows
         if (!audioSuspendedWhenHidden)
-            audioContext.resume();
+            audioResume();
         return;
     }
 
@@ -822,7 +839,7 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
 
 /** Copy arrays of samples into a new audio buffer
  *  @param {Array}  sampleChannels - Array of arrays of samples (for stereo playback)
- *  @param {number} [sampleRate=44100] - Sample rate for the sound
+ *  @param {number} [sampleRate=audioDefaultSampleRate] - Sample rate for the sound
  *  @return {AudioBuffer} - The audio buffer holding the samples
  *  @memberof Audio */
 function createAudioBuffer(sampleChannels, sampleRate=audioDefaultSampleRate)
@@ -857,10 +874,12 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
         // fix stalled audio, this sound won't be able to play;
         // but a context suspended because the page is hidden stays suspended until it shows
         if (!audioSuspendedWhenHidden)
-            audioContext.resume();
+            audioResume();
         return;
     }
 
+    volume = audioFinite(volume, 0), rate = audioFinite(rate, 1), pan = audioFinite(pan, 0);
+
     // setup source, many sources can share one buffer
     const source = audioContext.createBufferSource();
     source.buffer = buffer;
@@ -916,8 +935,8 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @param {number}  [release] - Release time, how fast sound fades out (seconds)
  *  @param {number}  [shape] - Shape of the sound wave
  *  @param {number}  [shapeCurve] - Squareness of wave (0=square, 1=normal, 2=pointy)
- *  @param {number}  [slide] - How much to slide frequency (kHz/s)
- *  @param {number}  [deltaSlide] - How much to change slide (kHz/s/s)
+ *  @param {number}  [slide] - How much to slide frequency, 1 is about 500 Hz a second, as ZzFX has it
+ *  @param {number}  [deltaSlide] - How much to change slide each second, in the units of slide
  *  @param {number}  [pitchJump] - Frequency of pitch jump (Hz)
  *  @param {number}  [pitchJumpTime] - Time of pitch jump (seconds)
  *  @param {number}  [repeatTime] - Resets some parameters periodically (seconds)
@@ -928,7 +947,8 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @param {number}  [sustainVolume] - Volume level for sustain (percent)
  *  @param {number}  [decay] - Decay time, how long to reach sustain after attack (seconds)
  *  @param {number}  [tremolo] - Trembling effect, rate controlled by repeat time (percent)
- *  @param {number}  [filter] - Filter cutoff frequency, positive for HPF, negative for LPF (Hz)
+ *  @param {number}  [filter] - Filter cutoff, positive for HPF, negative for LPF; the cutoff is about twice this in
+ *    Hz, as ZzFX has it, and its resonance can take the samples past 1
  *  @return {Float32Array} - The audio samples
  *  @memberof Audio */
 function zzfxG

package/src/engineBuild.mjs

@@ -42,6 +42,7 @@ const enginePluginFiles =
 [
     `${PLUGIN_FOLDER}/medalSystem.js`,
     `${PLUGIN_FOLDER}/newgrounds.js`,
+    `${PLUGIN_FOLDER}/wavedash.js`,
     `${PLUGIN_FOLDER}/postProcess.js`,
     `${PLUGIN_FOLDER}/lightSystem.js`,
     `${PLUGIN_FOLDER}/audioEffects.js`,
@@ -55,6 +56,8 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/pathFinder.js`,
     `${PLUGIN_FOLDER}/math3d.js`,
     `${PLUGIN_FOLDER}/render3d.js`,
+    `${PLUGIN_FOLDER}/render3dMesh.js`,
+    `${PLUGIN_FOLDER}/render3dObject.js`,
     `${PLUGIN_FOLDER}/render3dExtras.js`,
     `${PLUGIN_FOLDER}/render3dVoxels.js`,
     `${PLUGIN_FOLDER}/render3dLevel.js`,
@@ -292,7 +295,9 @@ function typeScriptBuildStep(filename)
         // strictNullChecks keeps undefined in the types, where tsc would drop it from accessors and object types
         // whatever the JSDoc says, so a game in strict mode can set render3D.shader = undefined and is told a
         // flare may be missing; a game not in strict mode reads the same types as before
-        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --strictNullChecks --outFile "${tsFilename}"`);
+        // the target names the library tsc types with: without it tsc takes ES5's, where Map and Set do not resolve
+        // and come out as any, which went unseen while a dependency brought @types/node, which declares them
+        execSync(`npx -p typescript tsc "${filename}" --declaration --allowJs --emitDeclarationOnly --strictNullChecks --target es2022 --outFile "${tsFilename}"`);
 
         // Make declare module part use the package name littlejsengine
         let fileContent = fs.readFileSync(tsFilename, 'utf8');