littlejsengine 1.24.1 → 1.24.3

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.24.1';
+const engineVersion = '1.24.3';
 
 /** Frames per second to update
  *  @type {number}
@@ -165,6 +165,7 @@ let timeFixedStart = 0, frameFixedStart = 0;
 let windowWidthLast = 0, windowHeightLast = 0, windowPixelRatioLast = 0;
 let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let engineFrameScheduled = false; // a frame of the loop is asked for and has not run yet
+let engineFrameErrorLast; // the last error a release build's loop went on past, as text
 
 // the pairs of objects asked about a collision this update, so the other's own physics does not ask again: each
 // asker's others, with true for a pair both said to resolve, and false for one left overlapping, ignored or only
@@ -418,20 +419,30 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 frameTimeBufferMS = 0;
             }
 
-            // update multiple frames if necessary in case of slow framerate
-            for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+            // update multiple frames if necessary in case of slow framerate; a tick that throws still spends its time
+            // and the smoothing still comes back, so a release build going on past an error each tick keeps its rate
+            try
             {
-                // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
-                const frozenTick = paused || !(timeScale * debugScale);
-
-                // increment frame and update time, frozen does not advance time
-                if (!frozenTick)
-                    time = timeFixedStart + (frame++ - frameFixedStart) / frameRate;
-                engineTick(frozenTick);
+                while (frameTimeBufferMS >= 0)
+                {
+                    try
+                    {
+                        // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
+                        const frozenTick = paused || !(timeScale * debugScale);
+
+                        // increment frame and update time, frozen does not advance time
+                        if (!frozenTick)
+                            time = timeFixedStart + (frame++ - frameFixedStart) / frameRate;
+                        engineTick(frozenTick);
+                    }
+                    finally { frameTimeBufferMS -= 1e3 / frameRate; }
+                }
+            }
+            finally
+            {
+                // add the time smoothing back in
+                frameTimeBufferMS += deltaSmooth;
             }
-
-            // add the time smoothing back in
-            frameTimeBufferMS += deltaSmooth;
         }
 
         // one tick of the loop: update game and objects, when frozen update everything except them
@@ -450,7 +461,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                     o.parent || o.updateTransforms();
 
                 // objects made and destroyed while paused, like a menu's effects, still leave the list
-                engineObjects = engineObjects.filter(o=>!o.destroyed);
+                engineObjects.some(o=>o.destroyed) && (engineObjects = engineObjects.filter(o=>!o.destroyed));
             }
             else
                 engineObjectsUpdate();
@@ -497,7 +508,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             // render the game and objects
             enginePreRender();
             gameRender();
-            engineObjects.sort((a,b)=> a.renderOrder - b.renderOrder);
+            engineObjectsSort();
             for (const o of engineObjects)
             {
                 if (o.destroyed) continue;
@@ -600,7 +611,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     }
 
     // the splash first, the images load under it, then the loading screen for the rest
-    showSplashScreen && await promises.at(-1);
+    showSplashScreen && await promises[promises.length - 1];
     return startEngine(promises);
 
     // gameInit runs once the images are in, and the game loop starts once it and everything loaded while it ran are
@@ -723,7 +734,20 @@ function engineScheduleFrame()
     const next = (frameTimeMS)=>
     {
         engineFrameScheduled = false;
-        engineManualStep || engineUpdateInternal(frameTimeMS);
+        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();
+        }
     };
     if (typeof requestAnimationFrame === 'function')
         requestAnimationFrame(next);
@@ -769,14 +793,18 @@ function engineObjectsUpdate()
     ++engineObjectsUpdateCount;
     engineObjectsCollidePairs.clear();
     // objects update in render order, which rendering keeps them in, so a headless run or a frame that rendered
-    // nothing updates them the same way; the sort is stable, and nearly free on a list that is already sorted
-    engineObjects.sort((a,b)=> a.renderOrder - b.renderOrder);
+    // nothing updates them the same way
+    engineObjectsSort();
     // get list of solid objects for physics optimization, in update order, which 3D collision pairs by;
     // 2D checks the static ones last, so a contact with a moving object can not leave something back inside a static
     // solid it was already pushed out of
-    engineObjectsCollide = engineObjects.filter(o=>o.collideSolidObjects);
-    engineObjectsCollideStaticLast = engineObjectsCollide.filter(o=>o.mass)
-        .concat(engineObjectsCollide.filter(o=>!o.mass));
+    const fixed = [];
+    engineObjectsCollide = [];
+    engineObjectsCollideStaticLast = [];
+    for (const o of engineObjects)
+        o.collideSolidObjects && (engineObjectsCollide.push(o), (o.mass ? engineObjectsCollideStaticLast : fixed).push(o));
+    for (const o of fixed)
+        engineObjectsCollideStaticLast.push(o);
 
     // update physics before object update
     for (const o of engineObjects)
@@ -826,7 +854,16 @@ function engineObjectsUpdate()
         updateTopObject(o);
 
     // remove destroyed objects
-    engineObjects = engineObjects.filter(o=>!o.destroyed);
+    engineObjects.some(o=>o.destroyed) && (engineObjects = engineObjects.filter(o=>!o.destroyed));
+}
+
+// sort the objects by render order, keeping the order of equals, only when one is out of order, as they are kept
+// sorted and most frames change none
+function engineObjectsSort()
+{
+    for (let i = engineObjects.length; --i > 0;)
+        if (engineObjects[i].renderOrder < engineObjects[i-1].renderOrder)
+            return void engineObjects.sort((a,b)=> a.renderOrder - b.renderOrder);
 }
 
 /** Destroy and remove all objects

package/src/engineAudio.js

@@ -58,9 +58,19 @@ function audioInit()
 {
     if (!soundEnable || headlessMode) return;
 
+    audioSetSession();
     document.addEventListener('visibilitychange', audioVisibilityChange);
 }
 
+// on an iPhone the silent switch mutes the page's sound, unless soundIgnoreSilentSwitch has it play as media,
+// Safari 16.4 and up; elsewhere there is no audioSession and nothing changes
+function audioSetSession()
+{
+    const session = typeof navigator != 'undefined' && /** @type {any} */ (navigator).audioSession;
+    if (session)
+        session.type = soundIgnoreSilentSwitch ? 'playback' : 'auto';
+}
+
 // a hidden page stops the game, so its sound stops too, and the audio clock with it so every sound picks up
 // exactly where it was; only a suspend made here is undone, not one the browser holds until the first input
 let audioSuspendedWhenHidden = false;
@@ -203,13 +213,13 @@ function audioParamRamp(param, value, fadeTime=0)
  * @memberof Audio
  * @example
  * // load an audio asset file
- * const sound_example = new Sound('sound.mp3');
+ * const music = new Sound('sound.mp3');
  *
  * // create a zzfx sound
- * const sound_example = new Sound([.5,.5]);
+ * const blip = new Sound([.5,.5]);
  *
  * // play a sound
- * sound_example.play();
+ * blip.play();
  */
 class Sound
 {
@@ -222,7 +232,7 @@ class Sound
      */
     constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
-        if (!soundEnable || headlessMode)
+        if (!soundEnable || headlessMode || !audioContext) // a browser with no audio makes none either
         {
             // no sound is made: it counts as loaded, so a game that waits for its sounds goes on
             this.loadedPercent = 1;
@@ -292,8 +302,8 @@ class Sound
             // load the audio file, a URL object as bundlers give works like its string;
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
-            engineAddLoad(this.loadSound(filename).catch(e=>
-                LOG('Sound load failed for', filename, '-', e.message))); // startup waits for it
+            engineAddLoad(this.loadSound(filename).catch(e=> // startup waits for it, and a release build says why too
+                console.warn('Sound load failed for', filename, '-', e?.message ?? e)));
         }
     }
 

package/src/engineBuild.mjs

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

package/src/engineDebug.js

@@ -269,7 +269,10 @@ function debugShowErrors()
     {
         // replace entire page with error message
         document.body.style.cssText = 'background-color:#111;margin:8px';
-        document.body.innerHTML = `<pre style=color:#f00;font-size:28px;white-space:pre-wrap>` + message;
+        const pre = document.createElement('pre'); // the message as text, a file name in it never markup
+        pre.style.cssText = 'color:#f00;font-size:28px;white-space:pre-wrap';
+        pre.textContent = String(message);
+        document.body.replaceChildren(pre);
     }
     
     const originalAssert = console.assert;

package/src/engineDraw.js

@@ -134,10 +134,13 @@ function tile(index=0, size=tileDefaultSize, texture=0, padding=tileDefaultPaddi
     // create tile info object
     const textureInfo = typeof texture === 'number' ?
         textureInfos[texture] : texture;
-    if (headlessMode && !textureInfo?.size.x)
-        return new TileInfo(new Vector2, size.copy(), textureInfo, padding, bleed); // no image loaded, no place in it
-    ASSERT(textureInfo instanceof TextureInfo, 'tile texture is not loaded');
-    ASSERT(textureInfo.size.x > 0, 'tile texture is not loaded');
+    if (!textureInfo?.size.x)
+    {
+        // no image: headless loads none and keeps the size; an image that failed to load, whose warning named it, gives
+        // a tile of no size, which draws nothing; a slot never given an image is a mistake a debug build points out
+        ASSERT(headlessMode || textureInfo instanceof TextureInfo, 'tile texture is not loaded', texture);
+        return new TileInfo(new Vector2, headlessMode ? size.copy() : new Vector2, textureInfo, padding, bleed);
+    }
 
     // get the position of the tile
     const sizePaddedX = size.x + padding*2;
@@ -182,6 +185,10 @@ class TileInfo
         this.padding = padding;
         /** @property {TextureInfo} - The texture info for this tile */
         this.textureInfo = textureInfo;
+        /** @property {Array<TileInfo>|undefined} - A tile set's tiles, each wherever it was packed, as loadTiles makes
+         *  them: a tile layer given this tile info draws its tile n from tiles[n] and not from a grid on one sheet
+         *  @type {Array<TileInfo>|undefined} */
+        this.tiles = undefined;
         /** @property {number} - Shrinks tile by this many pixels to prevent neighbors bleeding */
         this.bleed = bleed;
         /** @property {number} - How many frames per row for frame(), 0 to keep frames on a single row */
@@ -601,8 +608,8 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
     if (headlessMode && !context) return; // headless has no canvas, only a context passed in is drawn to
 
     const textureInfo = tileInfo?.textureInfo;
-    if (textureInfo && !(tileInfo.size.x && tileInfo.size.y))
-        return; // a tile with no area draws nothing, like a sprite still loading
+    if (textureInfo && !(tileInfo.size.x && tileInfo.size.y && textureInfo.size.x))
+        return; // a tile with no area draws nothing, like a sprite still loading, and nor does an image that failed
     const bleed = tileInfo?.bleed ?? 0;
     if (useWebGL && glEnable)
     {
@@ -696,7 +703,7 @@ function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
  *  @param {boolean} [screenSpace=drawScreenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
+function drawRectGradient(pos, size=vec2(1), colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=drawScreenSpace, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -868,13 +875,15 @@ function drawLineList(points, width=.1, color=WHITE, wrap=false, pos=vec2(), ang
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
-        let size = vec2(1);
+        let sx = 1, sy = 1;
         if (screenSpace)
         {
             if (glSkipScreenSpace) return;
-            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+            let size;
+            [pos, size, angle] = screenToWorldTransform(pos, vec2(1), angle);
+            sx = size.x, sy = size.y;
         }
-        glDrawOutlineTransform(points, color.rgbaInt(), width, pos.x, pos.y, size.x, size.y, angle, wrap);
+        glDrawOutlineTransform(points, color.rgbaInt(), width, pos.x, pos.y, sx, sy, angle, wrap);
     }
     else
     {
@@ -940,17 +949,22 @@ function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, l
     ASSERT(isVector2(size), 'size must be a vec2');
     ASSERT(isNumber(sides), 'sides must be a number');
 
-    // build regular polygon points
-    const points = [];
+    // build regular polygon points, into vectors kept for the next, as drawPoly is done with them when it returns
+    const points = drawRegularPolyPoints, pool = drawRegularPolyPool;
+    points.length = 0;
     const sizeX = size.x/2, sizeY = size.y/2;
     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));
+        const a = (i/sides)*PI*2, point = pool[points.length] ||= vec2();
+        point.x = sin(a)*sizeX, point.y = cos(a)*sizeY;
+        points.push(point);
     }
     drawPoly(points, color, lineWidth, lineColor, pos, angle, useWebGL, screenSpace, context);
 }
 
+// the points drawRegularPoly draws and the vectors it writes them into
+const drawRegularPolyPoints = [], drawRegularPolyPool = [];
+
 /** Draw colored polygon using passed in points
  *  - WebGL fills a polygon whose edges do not cross, concave or not; a self crossing one, like a star through its
  *    outer points, fills wrong there, so draw it as its simple outline or in parts
@@ -978,15 +992,17 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
     if (useWebGL && glEnable)
     {
         ASSERT(!!glContext, 'WebGL is not enabled!');
-        let size = vec2(1);
+        let sx = 1, sy = 1;
         if (screenSpace)
         {
             if (glSkipScreenSpace) return;
-            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+            let size;
+            [pos, size, angle] = screenToWorldTransform(pos, vec2(1), angle);
+            sx = size.x, sy = size.y;
         }
-        glDrawPointsTransform(points, color.rgbaInt(), pos.x, pos.y, size.x, size.y, angle);
+        glDrawPointsTransform(points, color.rgbaInt(), pos.x, pos.y, sx, sy, angle);
         if (lineWidth > 0)
-            glDrawOutlineTransform(points, lineColor.rgbaInt(), lineWidth, pos.x, pos.y, size.x, size.y, angle);
+            glDrawOutlineTransform(points, lineColor.rgbaInt(), lineWidth, pos.x, pos.y, sx, sy, angle);
     }
     else
     {
@@ -1631,7 +1647,7 @@ function tintImageData(data, color, additiveColor)
     if (additiveColor && !isBlack(additiveColor))
     {
         // multiply + additive (slower), color.a is baked into the alpha channel here
-        const colorMultiply = [color.r, color.g, color.b, color.a];
+        const colorMultiply = [clamp(color.r), clamp(color.g), clamp(color.b), clamp(color.a)];
         const colorAdd = [additiveColor.r * 255, additiveColor.g * 255,
                           additiveColor.b * 255, additiveColor.a * 255];
         for (let i = 0; i < data.length; ++i)
@@ -1642,9 +1658,9 @@ function tintImageData(data, color, additiveColor)
     // RGB only, faster — alpha left intact for the caller
     for (let i = 0; i < data.length; i+=4)
     {
-        data[i  ] *= color.r;
-        data[i+1] *= color.g;
-        data[i+2] *= color.b;
+        data[i  ] *= clamp(color.r);
+        data[i+1] *= clamp(color.g);
+        data[i+2] *= clamp(color.b);
     }
     return false;
 }
@@ -1682,8 +1698,7 @@ function bakeTintedImage(image, color, additiveColor)
  *  @param {number} dHeight
  *  @param {Color} color
  *  @param {Color} [additiveColor]
- *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding
- *  @memberof Draw */
+ *  @param {number} [bleed] - How many pixels to shrink the source, used to fix bleeding */
 function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight, color, additiveColor, bleed=0)
 {
     const sx2 = bleed;
@@ -1896,7 +1911,7 @@ function engineGlowTexture(falloff=1)
     ASSERT(isNumber(falloff) && falloff > 0, 'glowFalloff must be a number above 0');
     const key = max(round(falloff * 10), 1) / 10;
     let texture = engineGlowTextures.get(key);
-    if (texture || !glContext || typeof OffscreenCanvas == 'undefined') return texture;
+    if (texture || !glContext || !canvasAvailable()) return texture;
     const size = 64, context = createCanvasContext(size), steps = 16;
     const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
     for (let i = 0; i <= steps; ++i)