littlejsengine 1.18.28 → 1.19.3

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.28';
+const engineVersion = '1.19.3';
 
 /** Frames per second to update
  *  @type {number}
@@ -89,6 +89,7 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+let windowWidthLast = 0, windowHeightLast = 0, windowPixelRatioLast = 0;
 let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let showEngineVersion = true;
 
@@ -98,12 +99,13 @@ let showEngineVersion = true;
 const pluginList = [];
 class EnginePlugin
 {
-    constructor(update, render, glContextLost, glContextRestored)
+    constructor(update, render, glContextLost, glContextRestored, preRender)
     {
         this.update = update;
         this.render = render;
         this.glContextLost = glContextLost;
         this.glContextRestored = glContextRestored;
+        this.preRender = preRender;
     }
 }
 
@@ -117,16 +119,18 @@ class EnginePlugin
  *  @param {PluginCallback} [render]
  *  @param {PluginCallback} [glContextLost]
  *  @param {PluginCallback} [glContextRestored]
+ *  @param {PluginCallback} [preRender] - Called after the canvas is cleared and before gameRender
  *  @memberof Engine */
-function engineAddPlugin(update, render, glContextLost, glContextRestored)
+function engineAddPlugin(update, render, glContextLost, glContextRestored, preRender)
 {
     // make sure plugin functions are unique
     ASSERT(!pluginList.find(p=>
         p.update === update && p.render === render &&
         p.glContextLost === glContextLost &&
-        p.glContextRestored === glContextRestored));
+        p.glContextRestored === glContextRestored &&
+        p.preRender === preRender));
 
-    const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored);
+    const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored, preRender);
     pluginList.push(plugin);
 }
 
@@ -186,14 +190,17 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     // Called automatically by engine to setup render system
     function enginePreRender()
     {
-        // save canvas size
-        mainCanvasSize = vec2(mainCanvas.width, mainCanvas.height);
+        // mainCanvasSize is set by engineUpdateCanvas which always runs first,
+        // it is css pixels so it does not match the canvas backing store
 
         // disable smoothing for pixel art
         mainContext.imageSmoothingEnabled = !tilesPixelated;
 
         // setup gl rendering if enabled
         glPreRender();
+
+        // plugins that draw underneath the 2D layer
+        pluginList.forEach(plugin=>plugin.preRender?.());
     }
 
     // internal update loop for engine
@@ -212,25 +219,47 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         const debugScale = debugSpeedUp ? 10 : debugSpeedDown ? .1 : 1;
 
         // apply time deltas
+        const frameTimeDeltaUnscaledMS = frameTimeDeltaMS;
         timeReal += frameTimeDeltaMS * debugScale / 1e3;
         const combinedScale = timeScale * debugScale;
         frameTimeDeltaMS *= combinedScale;
-        frameTimeBufferMS += paused ? 0 : frameTimeDeltaMS;
-        if (combinedScale <= 1)
+        // when paused tick on unscaled time so the pause update rate stays
+        // fixed instead of following however fast the display refreshes
+        frameTimeBufferMS += paused ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
+        if (paused || combinedScale <= 1)
             frameTimeBufferMS = min(frameTimeBufferMS, 50); // clamp min framerate
 
-        let wasUpdated = false;
-        if (paused)
+        // apply time delta smoothing, improves smoothness of framerate in some browsers
+        let wasUpdated = false, deltaSmooth = 0;
+        if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
         {
-            // update everything except the game and objects
+            // force at least one update each frame since it is waiting for refresh
+            deltaSmooth = frameTimeBufferMS;
+            frameTimeBufferMS = 0;
+        }
+
+        // update multiple frames if necessary in case of slow framerate
+        for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+        {
+            // increment frame and update time, paused does not advance time
+            if (!paused)
+                time = frame++ / frameRate;
+
+            // update game and objects, when paused update everything except them
             wasUpdated = true;
-            updateCanvas();
+            engineUpdateCanvas();
             inputUpdate();
+            if (!paused)
+                gameUpdate();
             pluginList.forEach(plugin=>plugin.update?.());
-
-            // update object transforms even when paused
-            for (const o of engineObjects)
-                o.parent || o.updateTransforms();
+            if (paused)
+            {
+                // update object transforms even when paused
+                for (const o of engineObjects)
+                    o.parent || o.updateTransforms();
+            }
+            else
+                engineObjectsUpdate();
 
             // do post update
             debugUpdate();
@@ -239,44 +268,26 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             if (debugVideoCaptureIsActive())
                 renderFrame();
         }
-        else
-        {
-            // apply time delta smoothing, improves smoothness of framerate in some browsers
-            let deltaSmooth = 0;
-            if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
-            {
-                // force at least one update each frame since it is waiting for refresh
-                deltaSmooth = frameTimeBufferMS;
-                frameTimeBufferMS = 0;
-            }
-
-            // update multiple frames if necessary in case of slow framerate
-            for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
-            {
-                // increment frame and update time
-                time = frame++ / frameRate;
-
-                // update game and objects
-                wasUpdated = true;
-                updateCanvas();
-                inputUpdate();
-                gameUpdate();
-                pluginList.forEach(plugin=>plugin.update?.());
-                engineObjectsUpdate();
 
-                // do post update
-                debugUpdate();
-                gameUpdatePost();
-                inputUpdatePost();
-                if (debugVideoCaptureIsActive())
-                    renderFrame();
-            }
+        // add the time smoothing back in
+        frameTimeBufferMS += deltaSmooth;
 
-            // add the time smoothing back in
-            frameTimeBufferMS += deltaSmooth;
+        // check if the window changed so a resize is picked up even when
+        // the game is not updating, for example when timeScale is 0
+        let windowChanged = false;
+        if (!headlessMode)
+        {
+            const dpr = devicePixelRatio;
+            windowChanged = windowWidthLast !== innerWidth ||
+                windowHeightLast !== innerHeight || windowPixelRatioLast !== dpr;
+            windowWidthLast = innerWidth;
+            windowHeightLast = innerHeight;
+            windowPixelRatioLast = dpr;
         }
 
-        if (!debugVideoCaptureIsActive())
+        // render only when something changed, displays that refresh faster
+        // than the fixed update rate would otherwise redraw identical frames
+        if (!debugVideoCaptureIsActive() && (wasUpdated || windowChanged))
             renderFrame();
         if (!engineManualStep)
             requestAnimationFrame(engineUpdate);
@@ -287,14 +298,19 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
             // canvas must be updated before rendering
             if (!wasUpdated)
-                updateCanvas();
+                engineUpdateCanvas();
 
             // render the game and objects
             enginePreRender();
             gameRender();
             engineObjects.sort((a,b)=> a.renderOrder - b.renderOrder);
             for (const o of engineObjects)
-                o.destroyed || o.render();
+            {
+                if (o.destroyed) continue;
+                setShader(o.shader); // each object draws with its own shader, or none
+                o.render();
+            }
+            setShader(); // back to the engine's for gameRenderPost
 
             // post rendering
             gameRenderPost();
@@ -309,84 +325,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     }
     engineUpdateInternal = engineUpdate;
 
-    function updateCanvas()
-    {
-        if (headlessMode) return;
-
-        if (canvasFixedSize.x)
-        {
-            // set canvas fixed size
-            mainCanvasSize = canvasFixedSize.copy();
-
-            // fit to window using css width and height
-            const innerAspect = innerWidth / innerHeight;
-            const fixedAspect = canvasFixedSize.x / canvasFixedSize.y;
-            const w = innerAspect < fixedAspect ? '100%' : '';
-            const h = innerAspect < fixedAspect ? '' : '100%';
-            mainCanvas.style.width  = w;
-            mainCanvas.style.height = h;
-            if (glCanvas)
-            {
-                glCanvas.style.width  = w;
-                glCanvas.style.height = h;
-            }
-        }
-        else
-        {
-            // apply device pixel ratio for crisp rendering
-            const dpr = canvasPixelRatio ?? (devicePixelRatio || 1);
-            const viewWidth = innerWidth * dpr | 0;
-            const viewHeight = innerHeight * dpr | 0;
-            
-            // get main canvas size based on window size
-            mainCanvasSize.x = min(viewWidth,  canvasMaxSize.x);
-            mainCanvasSize.y = min(viewHeight, canvasMaxSize.y);
-            
-            // responsive aspect ratio with native resolution
-            const innerAspect = viewWidth / viewHeight;
-            ASSERT(canvasMinAspect <= canvasMaxAspect);
-            if (canvasMaxAspect && innerAspect > canvasMaxAspect)
-            {
-                // full height
-                const w = mainCanvasSize.y * canvasMaxAspect | 0;
-                mainCanvasSize.x = min(w,  canvasMaxSize.x);
-            }
-            else if (innerAspect < canvasMinAspect)
-            {
-                // full width
-                const h = mainCanvasSize.x / canvasMinAspect | 0;
-                mainCanvasSize.y = min(h, canvasMaxSize.y);
-            }
-
-            // set CSS display size so backing store renders at viewport size
-            const cssW = (mainCanvasSize.x / dpr | 0) + 'px';
-            const cssH = (mainCanvasSize.y / dpr | 0) + 'px';
-            mainCanvas.style.width  = cssW;
-            mainCanvas.style.height = cssH;
-            if (glCanvas)
-            {
-                glCanvas.style.width  = cssW;
-                glCanvas.style.height = cssH;
-            }
-        }
-
-        // clear main canvas and set size
-        mainCanvas.width  = mainCanvasSize.x;
-        mainCanvas.height = mainCanvasSize.y;
-
-        // apply the clear color to main canvas
-        if (canvasClearColor.a > 0 && !glEnable)
-        {
-            mainContext.fillStyle = canvasClearColor.toString();
-            mainContext.fillRect(0, 0, mainCanvasSize.x, mainCanvasSize.y);
-            mainContext.fillStyle = BLACK.toString();
-        }
-
-        // set default line join and cap
-        mainContext.lineJoin = 'round';
-        mainContext.lineCap  = 'round';
-    }
-    
     // skip setup if headless
     if (headlessMode) return startEngine();
 
@@ -419,14 +357,14 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     if (glCanvas)
         glCanvas.style.cssText = styleCanvas;
     setCanvasPixelated(canvasPixelated);
-    updateCanvas();
+    engineUpdateCanvas();
     glPreRender();
 
     // create offscreen canvases for image processing
-    workCanvas = new OffscreenCanvas(64, 64);
-    workContext = workCanvas.getContext('2d');
-    workReadCanvas = new OffscreenCanvas(64, 64);
-    workReadContext = workReadCanvas.getContext('2d', { willReadFrequently: true });
+    workContext = createCanvasContext(64);
+    workCanvas = workContext.canvas;
+    workReadContext = createCanvasContext(64, 64, true);
+    workReadCanvas = workReadContext.canvas;
 
     // create promises for loading images
     const promises = imageSources.map((src, i)=> loadTexture(i, src));
@@ -466,6 +404,102 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     }
 }
 
+// Resize the canvas to fit the window and prepare it for a new frame
+// Called automatically each frame and by the splash screen before the loop starts
+// mainCanvasSize is css pixels and the backing store is that scaled by the
+// pixel ratio, so the ratio only changes sharpness, never how big things look
+function engineUpdateCanvas()
+{
+    if (headlessMode) return;
+
+    // the backing store is scaled by this, every size below is css pixels
+    const dpr = getCanvasPixelRatio();
+
+    if (canvasFixedSize.x)
+    {
+        // set canvas fixed size
+        mainCanvasSize = canvasFixedSize.copy();
+
+        // fit to window using css width and height
+        const innerAspect = innerWidth / innerHeight;
+        const fixedAspect = canvasFixedSize.x / canvasFixedSize.y;
+        const w = innerAspect < fixedAspect ? '100%' : '';
+        const h = innerAspect < fixedAspect ? '' : '100%';
+        mainCanvas.style.width  = w;
+        mainCanvas.style.height = h;
+        if (glCanvas)
+        {
+            glCanvas.style.width  = w;
+            glCanvas.style.height = h;
+        }
+    }
+    else
+    {
+        // get main canvas size based on window size, in css pixels so
+        // canvasMaxSize caps how big the canvas looks, not its resolution
+        mainCanvasSize.x = min(innerWidth,  canvasMaxSize.x) | 0;
+        mainCanvasSize.y = min(innerHeight, canvasMaxSize.y) | 0;
+
+        // responsive aspect ratio
+        const innerAspect = innerWidth / innerHeight;
+        ASSERT(canvasMinAspect <= canvasMaxAspect);
+        if (canvasMaxAspect && innerAspect > canvasMaxAspect)
+        {
+            // full height
+            const w = mainCanvasSize.y * canvasMaxAspect | 0;
+            mainCanvasSize.x = min(w, canvasMaxSize.x);
+        }
+        else if (innerAspect < canvasMinAspect)
+        {
+            // full width
+            const h = mainCanvasSize.x / canvasMinAspect | 0;
+            mainCanvasSize.y = min(h, canvasMaxSize.y);
+        }
+
+        // css size is the canvas size, the backing store is scaled up below
+        mainCanvas.style.width  = mainCanvasSize.x + 'px';
+        mainCanvas.style.height = mainCanvasSize.y + 'px';
+        if (glCanvas)
+        {
+            glCanvas.style.width  = mainCanvasSize.x + 'px';
+            glCanvas.style.height = mainCanvasSize.y + 'px';
+        }
+    }
+
+    // clear main canvas and set size
+    // only set the size when it changes, setting it invalidates the canvas
+    // frame which makes the browser rebuild the display list for the page
+    const bufferSizeX = mainCanvasSize.x * dpr | 0;
+    const bufferSizeY = mainCanvasSize.y * dpr | 0;
+    if (mainCanvas.width !== bufferSizeX || mainCanvas.height !== bufferSizeY)
+    {
+        mainCanvas.width  = bufferSizeX;
+        mainCanvas.height = bufferSizeY;
+    }
+    else
+    {
+        // setting the size also resets the context state, match that
+        mainContext.setTransform(1, 0, 0, 1, 0, 0);
+        mainContext.globalCompositeOperation = 'source-over';
+        mainContext.clearRect(0, 0, bufferSizeX, bufferSizeY);
+    }
+
+    // scale the context so 2d drawing is in css pixels
+    mainContext.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+    // apply the clear color to main canvas
+    if (canvasClearColor.a > 0 && !glEnable)
+    {
+        mainContext.fillStyle = canvasClearColor.toString();
+        mainContext.fillRect(0, 0, mainCanvasSize.x, mainCanvasSize.y);
+        mainContext.fillStyle = BLACK.toString();
+    }
+
+    // set default line join and cap
+    mainContext.lineJoin = 'round';
+    mainContext.lineCap  = 'round';
+}
+
 // max frames engineStep can advance in one call, 10 minutes at 60fps
 // large counts block until they finish, so this catches runaway values
 const engineStepMaxFrames = 36000;
@@ -534,13 +568,14 @@ function engineObjectsUpdate()
 
 /** Destroy and remove all objects
  *  - This can be used to clear out all objects when restarting a level
+ *  - Objects with the persistent flag set are left alone, for things that outlive a level
  *  - Objects can override their destroy function to do cleanup or stick around
  *  @param {boolean} [immediate] - should attached effects be allowed to die off?
  *  @memberof Engine */
 function engineObjectsDestroy(immediate=true)
 {
     for (const o of engineObjects)
-        o.parent || o.destroy(immediate);
+        o.parent || o.persistent || o.destroy(immediate);
     engineObjects = engineObjects.filter(o=>!o.destroyed);
 }