littlejsengine 1.19.3 → 1.21.0

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.19.3';
+const engineVersion = '1.21.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -40,11 +40,12 @@ const engineVersion = '1.19.3';
  *  @memberof Engine */
 const frameRate = 60;
 
-/** How many seconds each frame lasts, engine uses a fixed time step
+/** How many seconds the update covers: 1/60 with the fixed time step, or with engineVariableStep the time of the
+ *  display frame it runs on, times timeScale; while paused it keeps the last update's
  *  @type {number}
  *  @default 1/60
  *  @memberof Engine */
-const timeDelta = 1/frameRate;
+let timeDelta = 1/frameRate;
 
 /** Array containing all engine objects
  *  @type {Array<EngineObject>}
@@ -56,6 +57,9 @@ let engineObjects = [];
  *  @memberof Engine */
 let engineObjectsCollide = [];
 
+// the same objects with the static ones last, the order 2D physics checks them in
+let engineObjectsCollideStaticLast = [];
+
 /** Current update frame, used to calculate time
  *  @type {number}
  *  @memberof Engine */
@@ -66,7 +70,7 @@ let frame = 0;
  *  @memberof Engine */
 let time = 0;
 
-/** Actual clock time since start in seconds (not affected by pause, timescale, or frame rate clamping)
+/** Actual clock time since start in seconds (not affected by pause, timescale, or frame rate clamping; the debug speed keys scale it in debug builds)
  *  @type {number}
  *  @memberof Engine */
 let timeReal = 0;
@@ -89,8 +93,97 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+
+// delta smoothing, after Time Delta Smoothing by Frank Force (2013): a frame is on screen for whole display frames,
+// so each delta is rounded to them and the rest is carried to the next, keeping the total real time; the frame
+// length is estimated from recent frames and kept internal, since the browser does not say what it is
+const frameDeltaHistory = [];
+let frameIntervalMS = 1e3 / 60, frameDeltaCarryMS = 0, frameDeltaCarryAverageMS = 0, frameDeltaSmoothing = true;
+function engineSmoothDelta(deltaMS)
+{
+    if (!(deltaMS > 0)) return 0;
+    if (deltaMS < 250) // a gap from a hidden tab is not a display frame
+    {
+        frameDeltaHistory.push(deltaMS);
+        frameDeltaHistory.length > 64 && frameDeltaHistory.shift();
+
+        // the frames each delta held are counted in the last estimate or in the lower quartile of the last 16,
+        // whichever the deltas fit better: the quartile is one frame even when a busy game misses most of them, and
+        // it takes over when the window moves to a display with another refresh rate, or the estimate went wrong
+        const recent = frameDeltaHistory.slice(-16).sort((a, b)=> a - b);
+        const [lastMS, lastOff] = engineFrameFit(frameIntervalMS);
+        const [quartileMS, quartileOff] = engineFrameFit(recent[recent.length >> 2]);
+        frameIntervalMS = lastOff <= quartileOff ? lastMS : quartileMS;
+
+        // deltas far from whole frames mean the display has no fixed refresh, with a margin so it does not flip
+        frameDeltaSmoothing = min(lastOff, quartileOff) < (frameDeltaSmoothing ? .2 : .12);
+    }
+
+    if (!frameDeltaSmoothing)
+    {
+        // deltas that are not whole frames of one length, like a variable refresh display, are the frame times
+        // as they are, with any carry paid, and smoothing starts over once they fit again
+        const rawMS = deltaMS + frameDeltaCarryMS;
+        frameDeltaCarryMS = min(rawMS, 0);
+        frameDeltaCarryAverageMS = 0;
+        return max(rawMS, 0);
+    }
+
+    // whole frames, 0 for one that came early or 2 after one was missed, the carry stays within half a frame; a
+    // little of its slow average is paid each frame, so jitter can not hold it at half a frame and flip every frame
+    const pullMS = frameDeltaCarryAverageMS / 32;
+    frameDeltaCarryMS += deltaMS;
+    const frames = round((frameDeltaCarryMS - pullMS) / frameIntervalMS);
+    if (frames < 1)
+        return 0; // the carry keeps it
+    const smoothMS = frames * frameIntervalMS + pullMS;
+    frameDeltaCarryMS -= smoothMS;
+    frameDeltaCarryAverageMS += (frameDeltaCarryMS - frameDeltaCarryAverageMS) / 32;
+    return smoothMS;
+}
+
+// fit the delta history as whole frames of about unitMS: the frame length is the least squares slope of time over
+// frames held, so jitter and whole ms timestamps average out, with how far the deltas are from whole frames
+function engineFrameFit(unitMS)
+{
+    let timeMS = 0, frames = 0, offMS = 0, sumF = 0, sumT = 0, sumFF = 0, sumFT = 0;
+    const count = frameDeltaHistory.length;
+    for (const d of frameDeltaHistory)
+    {
+        const held = max(1, round(d / unitMS));
+        timeMS += d;
+        frames += held;
+        offMS += abs(d - held * unitMS);
+        sumF += frames, sumT += timeMS, sumFF += frames * frames, sumFT += frames * timeMS;
+    }
+    const spread = count * sumFF - sumF * sumF;
+    return [spread ? (count * sumFT - sumF * sumT) / spread : unitMS, offMS / count / unitMS];
+}
+
+// where the fixed step's time counts from, moved when the variable step hands back so time goes on from there
+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
+
+// 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
+// nudged apart; a map for each asker so the lookup stays quick when many objects pile up on one spot
+const engineObjectsCollidePairs = new Map;
+function engineObjectsCollidePairAnswer(asker, other)
+{ return engineObjectsCollidePairs.get(asker)?.get(other); }
+function engineObjectsCollidePairAdd(asker, other, resolve=false)
+{
+    let others = engineObjectsCollidePairs.get(asker);
+    others || engineObjectsCollidePairs.set(asker, others = new Map);
+    others.set(other, resolve);
+}
+let engineInitialized = false; // engineInit ran, with or without a canvas
+// 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;
+let engineObjectsUpdateCount = 0; // passes of engineObjectsUpdate so far, how a child knows it moved this pass
+const engineChildStack = []; // the children being updated, taken off the live lists so one leaving does not skip the next
 let showEngineVersion = true;
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -115,6 +208,7 @@ class EnginePlugin
  */
 
 /** Add a new update function for a plugin
+ *  - update runs on every fixed tick, paused and timeScale 0 included; a plugin that simulates should skip those
  *  @param {PluginCallback} [update]
  *  @param {PluginCallback} [render]
  *  @param {PluginCallback} [glContextLost]
@@ -137,24 +231,83 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
 ///////////////////////////////////////////////////////////////////////////////
 // Main Engine Functions
 
+/** Add something the game loads to what startup waits for: while engineInit and gameInit run, the game loop starts
+ *  once it is done, and the loading screen counts it; images from loadTexture and sounds from files are added on
+ *  their own, and a load that fails counts as done; after startup it does nothing
+ *  @param {Promise<any>} promise
+ *  @return {Promise<any>} - The same promise
+ *  @example
+ *  async function gameInit() { level = await engineAddLoad(fetchJSON('level.json')); }
+ *  @memberof Engine */
+function engineAddLoad(promise)
+{
+    if (engineLoads)
+    {
+        engineLoads.push(promise);
+        const done = ()=> { ++engineLoadsDone; };
+        promise.then(done, done);
+    }
+    return promise;
+}
+
+// wait for every load, the ones added while waiting too, drawing the loading screen each frame meanwhile
+async function engineWaitForLoads()
+{
+    let waiting = true;
+    const start = performance.now();
+    const drawFrame = ()=>
+    {
+        if (!waiting) return;
+        engineLoadingScreenDraw((performance.now() - start) / 1e3);
+        setTimeout(drawFrame, 16);
+    };
+    headlessMode || drawFrame();
+    try
+    {
+        for (let count; count !== engineLoads.length;)
+        {
+            count = engineLoads.length;
+            await Promise.allSettled(engineLoads);
+        }
+    }
+    finally { waiting = false; }
+}
+
+// one frame of the loading screen, once loading has taken half a second, so a fast load never shows it; input
+// while it shows is dropped, as it is under the splash
+function engineLoadingScreenDraw(elapsed)
+{
+    if (headlessMode || !loadingScreen || elapsed < .5) return;
+    inputClear();
+    engineUpdateCanvas();
+    loadingScreen(engineLoadsDone / engineLoads.length);
+}
+
 /**
  * @callback GameInitCallback - Called after the engine starts, can be async
  * @return {void|Promise<void>}
  * @memberof Engine
  */
+/**
+ * @callback LoadingScreenCallback - Draws the loading screen on mainContext, each frame while the game loads
+ * @param {number} progress - The part of the loads done, 0 to 1
+ * @memberof Engine
+ */
 /**
  * @callback GameCallback - Update or render function for the game
  * @memberof Engine
  */
 
 /** Startup LittleJS engine with your callback functions
- *  @param {GameInitCallback} gameInit - Called once after the engine starts up, can be async for loading
- *  @param {GameCallback} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
- *  @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 {GameInitCallback} [gameInit] - Called once after the engine starts up, can be async for loading
+ *  @param {GameCallback} [gameUpdate] - Called every frame before objects are updated (60fps), use for game logic
+ *  @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 {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
  *  @example
  *  // Basic engine startup
  *  engineInit(
@@ -169,17 +322,14 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
 async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement)
 {
     showEngineVersion && console.log(`${engineName} Engine v${engineVersion}`);
-    ASSERT(!mainContext, 'engine already initialized');
+    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 (mainContext) return;
+    if (engineInitialized) return;
+    engineInitialized = true;
+    engineLoads = [], engineLoadsDone = 0;
     ASSERT(isArray(imageSources), 'pass in images as array');
 
-    // ensure body exists for minimal HTML where the script runs before <body> is parsed
-    if (!document.body)
-        document.documentElement.appendChild(document.createElement('body'));
-    rootElement ||= document.body;
-
     // allow passing in empty functions
     gameInit       ||= ()=>{};
     gameUpdate     ||= ()=>{};
@@ -190,14 +340,15 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     // Called automatically by engine to setup render system
     function enginePreRender()
     {
-        // mainCanvasSize is set by engineUpdateCanvas which always runs first,
-        // it is css pixels so it does not match the canvas backing store
+        // the level editor's own view while it is open, in debug builds, before the camera goes to WebGL
+        editorPreRender();
 
         // disable smoothing for pixel art
         mainContext.imageSmoothingEnabled = !tilesPixelated;
 
         // setup gl rendering if enabled
         glPreRender();
+        setShader(); // a shader left set last frame does not carry into this one
 
         // plugins that draw underneath the 2D layer
         pluginList.forEach(plugin=>plugin.preRender?.());
@@ -206,6 +357,8 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     // internal update loop for engine
     function engineUpdate(frameTimeMS=0)
     {
+        const manualStepAtStart = engineManualStep;
+
         // update time keeping
         let frameTimeDeltaMS = frameTimeMS - frameTimeLastMS;
         // skip delta on the very first frame so timeReal doesn't jump
@@ -214,8 +367,14 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         frameTimeLastMS = frameTimeMS;
         if (debug || debugWatermark)
             averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
-        const debugSpeedUp   = debug && keyIsDown('Equal'); // +
-        const debugSpeedDown = debug && keyIsDown('Minus'); // -
+        // the time the frame will be on screen, in whole display frames; engineStep's steps are exact already
+        if (!manualStepAtStart)
+            frameTimeDeltaMS = engineSmoothDelta(frameTimeDeltaMS);
+        audioUpdateVolume();
+        // the time keys work while the debug overlay is open, or always when debugKeysAlways is set
+        const debugKeys = debug && (debugOverlay || debugKeysAlways);
+        const debugSpeedUp   = debugKeys && keyIsDown('Equal'); // +
+        const debugSpeedDown = debugKeys && keyIsDown('Minus'); // -
         const debugScale = debugSpeedUp ? 10 : debugSpeedDown ? .1 : 1;
 
         // apply time deltas
@@ -223,40 +382,75 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         timeReal += frameTimeDeltaMS * debugScale / 1e3;
         const combinedScale = timeScale * debugScale;
         frameTimeDeltaMS *= combinedScale;
-        // 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
-
-        // apply time delta smoothing, improves smoothness of framerate in some browsers
-        let wasUpdated = false, deltaSmooth = 0;
-        if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
+        let wasUpdated = false;
+        if (engineVariableStep)
         {
-            // force at least one update each frame since it is waiting for refresh
-            deltaSmooth = frameTimeBufferMS;
-            frameTimeBufferMS = 0;
+            // one update for the frame with timeDelta the time it covers, per-frame values are the game's to scale;
+            // engineStep's frames are exactly 1/60, its first too, which has no frame before it to take a delta from
+            if (frameTimeDeltaUnscaledMS > 0 || manualStepAtStart)
+            {
+                // frozen stands still as in the fixed step, and timeDelta keeps the last update's
+                const frozenTick = paused || !combinedScale;
+                if (!frozenTick)
+                {
+                    timeDelta = manualStepAtStart ? combinedScale / frameRate :
+                        min(frameTimeDeltaUnscaledMS, 50) * combinedScale / 1e3; // clamp min framerate
+                    time += timeDelta;
+                    ++frame;
+                }
+                engineTick(frozenTick);
+            }
         }
-
-        // update multiple frames if necessary in case of slow framerate
-        for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+        else
         {
-            // increment frame and update time, paused does not advance time
-            if (!paused)
-                time = frame++ / frameRate;
+            // paused or a time scale of 0 is frozen: it ticks on unscaled time, so the update rate stays fixed instead
+            // of following however fast the display refreshes, and gameUpdatePost and input still run to leave it
+            const frozen = paused || !combinedScale;
+            frameTimeBufferMS += frozen ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
+            frameTimeBufferMS = min(frameTimeBufferMS, 50 * (frozen ? 1 : max(1, combinedScale))); // clamp min framerate
+
+            // 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)
+            {
+                // 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);
+            }
 
-            // update game and objects, when paused update everything except them
+            // add the time smoothing back in
+            frameTimeBufferMS += deltaSmooth;
+        }
+
+        // one tick of the loop: update game and objects, when frozen update everything except them
+        function engineTick(frozenTick)
+        {
             wasUpdated = true;
             engineUpdateCanvas();
             inputUpdate();
-            if (!paused)
+            if (!frozenTick)
                 gameUpdate();
             pluginList.forEach(plugin=>plugin.update?.());
-            if (paused)
+            if (frozenTick)
             {
                 // update object transforms even when paused
                 for (const o of engineObjects)
                     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);
             }
             else
                 engineObjectsUpdate();
@@ -269,8 +463,9 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 renderFrame();
         }
 
-        // add the time smoothing back in
-        frameTimeBufferMS += deltaSmooth;
+        // manual step turned on by this frame's updates, set the buffer the loop and smoothing just moved again
+        if (engineManualStep && !manualStepAtStart)
+            frameTimeBufferMS = -.5e3 / frameRate;
 
         // check if the window changed so a resize is picked up even when
         // the game is not updating, for example when timeScale is 0
@@ -289,8 +484,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         // than the fixed update rate would otherwise redraw identical frames
         if (!debugVideoCaptureIsActive() && (wasUpdated || windowChanged))
             renderFrame();
-        if (!engineManualStep)
-            requestAnimationFrame(engineUpdate);
+        engineManualStep || engineScheduleFrame();
 
         function renderFrame()
         {
@@ -314,6 +508,8 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
             // post rendering
             gameRenderPost();
+            setShader(); // plugin, input and debug draws start from the engine's state
+            setAdditiveBlendMode(false);
             pluginList.forEach(plugin=>plugin.render?.());
             inputRender();
             debugRender();
@@ -323,24 +519,32 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             primitiveCount = 0;
         }
     }
-    engineUpdateInternal = engineUpdate;
 
     // skip setup if headless
-    if (headlessMode) return startEngine();
+    if (headlessMode) return startEngine([]);
+
+    // ensure body exists for minimal HTML where the script runs before <body> is parsed
+    if (!document.body)
+        document.documentElement.appendChild(document.createElement('body'));
+    rootElement ||= document.body;
 
     // setup webgl
     glInit(rootElement);
 
     // setup html
-    const styleRoot =
+    let styleRoot =
         'margin:0;' +                 // fill the window
         'overflow:hidden;' +          // no scroll bars
         'background:#000;' +          // set background color
         'user-select:none;' +         // prevent hold to select
         '-webkit-user-select:none;' + // compatibility for ios
         'touch-action:none;' +        // prevent mobile pinch to resize
-        '-webkit-touch-callout:none'; // compatibility for ios
-    rootElement.style.cssText = styleRoot;
+        '-webkit-touch-callout:none;'; // compatibility for ios
+    // the canvases center on a root element with a height of its own, not the page; one sized only by its
+    // children has none, since the canvases are placed apart from it, and would clip them all away
+    if (rootElement !== document.body && rootElement.clientHeight && getComputedStyle(rootElement).position === 'static')
+        styleRoot += 'position:relative;';
+    rootElement.style.cssText = styleRoot + rootElement.style.cssText; // its own inline styles come after and win
     mainCanvas = rootElement.appendChild(document.createElement('canvas'));
     drawContext = mainContext = mainCanvas.getContext('2d');
 
@@ -367,6 +571,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     workReadCanvas = workReadContext.canvas;
 
     // create promises for loading images
+    /** @type {Array<Promise<any>>} */
     const promises = imageSources.map((src, i)=> loadTexture(i, src));
 
     // no images to load
@@ -379,7 +584,8 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     if (showSplashScreen)
     {
         // draw splash screen
-        promises.push(new Promise(resolve =>
+        /** @type {Promise<void>} */
+        const splash = new Promise(resolve =>
         {
             let t = 0;
             updateSplash();
@@ -389,17 +595,24 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 drawEngineLogo(t+=.01);
                 t>1 ? resolve() : setTimeout(updateSplash, 16);
             }
-        }));
+        });
+        promises.push(splash);
     }
 
-    // wait for all the promises to finish
-    await Promise.all(promises);
-    return startEngine();
+    // the splash first, the images load under it, then the loading screen for the rest
+    showSplashScreen && await promises.at(-1);
+    return startEngine(promises);
 
-    async function startEngine()
+    // 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
+    async function startEngine(images)
     {
-        // wait for gameInit to load
-        await gameInit();
+        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();
     }
 }
@@ -440,9 +653,9 @@ function engineUpdateCanvas()
         mainCanvasSize.x = min(innerWidth,  canvasMaxSize.x) | 0;
         mainCanvasSize.y = min(innerHeight, canvasMaxSize.y) | 0;
 
-        // responsive aspect ratio
-        const innerAspect = innerWidth / innerHeight;
-        ASSERT(canvasMinAspect <= canvasMaxAspect);
+        // responsive aspect ratio, of the size after canvasMaxSize, which can change its shape
+        const innerAspect = mainCanvasSize.x / mainCanvasSize.y;
+        ASSERT(!canvasMaxAspect || canvasMinAspect <= canvasMaxAspect);
         if (canvasMaxAspect && innerAspect > canvasMaxAspect)
         {
             // full height
@@ -495,19 +708,38 @@ function engineUpdateCanvas()
         mainContext.fillStyle = BLACK.toString();
     }
 
-    // set default line join and cap
+    // set default line join and cap, round on purpose: it looks better, suits text and keeps sharp corners from
+    // spiking far out; WebGL outlines are square and mitered for speed, the two are not meant to match
     mainContext.lineJoin = 'round';
     mainContext.lineCap  = 'round';
 }
 
+// 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()
+{
+    if (engineFrameScheduled) return;
+    engineFrameScheduled = true;
+    const next = (frameTimeMS)=>
+    {
+        engineFrameScheduled = false;
+        engineManualStep || engineUpdateInternal(frameTimeMS);
+    };
+    if (typeof requestAnimationFrame === 'function')
+        requestAnimationFrame(next);
+    else // a headless server in Node has no display to wait for, a timer keeps the pace
+        setTimeout(()=> next(performance.now()), 1e3 / frameRate);
+}
+
 // 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;
 
 /** Advance the engine by a number of frames
- *  Requires setEngineManualStep(true) before engineInit
+ *  Requires setEngineManualStep(true), before engineInit or while running; it stops early if an update turns it off
  *  Respects paused exactly as the normal update loop does
- *  @param {number} [frames] - number of engine update ticks, max 36000, each running one fixed update at timeScale 1
+ *  @param {number} [frames] - frames of 1/60 of a second to advance, max 36000; timeScale sets how many fixed
+ *  updates they run, as in the normal loop, one each at timeScale 1
  *  @example
  *  setHeadlessMode(true);
  *  setEngineManualStep(true);
@@ -517,7 +749,7 @@ const engineStepMaxFrames = 36000;
 function engineStep(frames=1)
 {
     ASSERT(engineManualStep,
-        'engineStep requires setEngineManualStep(true) before engineInit');
+        'engineStep requires setEngineManualStep(true)');
     ASSERT(engineUpdateInternal, 'engineStep requires engineInit to complete');
     // runtime guard so release builds (where the asserts are stripped) can't
     // start a second requestAnimationFrame chain or call an undefined update
@@ -525,42 +757,73 @@ function engineStep(frames=1)
     ASSERT(Number.isInteger(frames) && frames >= 0 && frames <= engineStepMaxFrames,
         'engineStep requires a whole frame count from 0 to ' + engineStepMaxFrames);
     frames = min(frames, engineStepMaxFrames); // release has no asserts, don't freeze
-    for (let i = frames; i > 0; --i)
+    for (let i = frames; i > 0 && engineManualStep; --i) // an update that turns manual step off hands back the loop
         engineUpdateInternal(frameTimeLastMS + 1e3 / frameRate);
 }
 
-/** Update each engine object, remove destroyed objects, and update time
- * can be called manually if objects need to be updated outside of main loop
+/** Update each engine object and remove destroyed objects; time and frame are advanced by the engine loop, not here
+ *  - Can be called manually if objects need to be updated outside of main loop
  *  @memberof Engine */
 function engineObjectsUpdate()
 {
-    // get list of solid objects for physics optimization
+    ++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);
+    // 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));
 
     // update physics before object update
     for (const o of engineObjects)
         if (!o.parent && !o.destroyed)
             o.updatePhysics();
 
-    // recursive object update
+    // 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
+    function updateChildObjects(children)
+    {
+        if (!children.length) return; // most objects have none, and this runs for every one
+        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;
+    }
+    const pass = engineObjectsUpdateCount;
     function updateChildObject(o)
     {
-        if (o.destroyed) return;
+        if (o.destroyed || o.updatePass === pass) return;
 
+        // its parent is up to date, so it updates from where it is now, and its children from where it is after
+        o.updatePass = pass;
+        o.updateTransforms(false);
         o.update();
-        for (const child of o.children)
-            updateChildObject(child);
+        o.children.length && o.updateTransforms(false);
+        updateChildObjects(o.children);
     }
-    for (const o of engineObjects)
+    function updateTopObject(o)
     {
-        if (o.parent || o.destroyed) continue;
+        if (o.parent || o.destroyed || o.updatePass === pass) return; // a child that let go is not updated twice
 
-        // update top level objects
+        // update top level objects, each child places itself before it updates so it sees this frame's position,
+        // then the whole tree is placed again so what the children changed in their localPos lands before render
+        o.updatePass = pass;
         o.update();
-        for (const child of o.children)
-            updateChildObject(child);
+        updateChildObjects(o.children);
         o.updateTransforms();
     }
+    for (const o of engineObjects)
+        updateTopObject(o);
+
+    // a child let go during the update from a place in the list already walked is on its own now, updated here
+    for (const o of engineObjects)
+        updateTopObject(o);
 
     // remove destroyed objects
     engineObjects = engineObjects.filter(o=>!o.destroyed);
@@ -570,7 +833,7 @@ function engineObjectsUpdate()
  *  - 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?
+ *  @param {boolean} [immediate] - true removes attached effects like particle emitters at once, false lets them finish first
  *  @memberof Engine */
 function engineObjectsDestroy(immediate=true)
 {
@@ -580,32 +843,43 @@ function engineObjectsDestroy(immediate=true)
 }
 
 /** Collects all object within a given area
+ *  - An object is collected when its box overlaps the area, or with testCenters when its center is inside it
+ *  - Objects destroyed this frame are left out, they are only in the list until the frame ends
  *  @param {Vector2} [pos] - Center of test area, or undefined for all objects
- *  @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
+ *  @param {Vector2|number} [size] - Diameter of a circle if a number, full size of a rectangle if a Vector2,
+ *                                   left out or 0 the objects that overlap the point at pos
  *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
+ *  @param {boolean} [testCenters] - Test only each object's center, a little faster, and ignores object sizes
  *  @return {Array<EngineObject>} - List of collected objects
  *  @memberof Engine */
-function engineObjectsCollect(pos, size, objects=engineObjects)
+function engineObjectsCollect(pos, size, objects=engineObjects, testCenters=false)
 {
     const collectedObjects = [];
     if (!pos)
     {
         // all objects
         for (const o of objects)
-            collectedObjects.push(o);
+            o.destroyed || collectedObjects.push(o);
     }
-    else if (size instanceof Vector2)
+    else if (!size || size instanceof Vector2)
     {
-        // bounding box test
+        // bounding box test, a point when there is no size or a size of 0
+        const boxSize = size instanceof Vector2 ? size : vec2();
         for (const o of objects)
-            o.isOverlapping(pos, size) && collectedObjects.push(o);
+            o.destroyed || (testCenters ? isOverlapping(pos, boxSize, o.pos) : o.isOverlapping(pos, boxSize))
+                && collectedObjects.push(o);
     }
     else
     {
-        // circle test
-        const sizeSquared = size*size;
+        // circle test, a diameter like every other size, against the nearest point of each box
+        const radiusSquared = (size/2)**2;
         for (const o of objects)
-            pos.distanceSquared(o.pos) < sizeSquared && collectedObjects.push(o);
+        {
+            if (o.destroyed) continue;
+            const dx = testCenters ? pos.x - o.pos.x : max(abs(pos.x - o.pos.x) - o.size.x/2, 0);
+            const dy = testCenters ? pos.y - o.pos.y : max(abs(pos.y - o.pos.y) - o.size.y/2, 0);
+            dx*dx + dy*dy < radiusSquared && collectedObjects.push(o);
+        }
     }
     return collectedObjects;
 }
@@ -616,16 +890,23 @@ function engineObjectsCollect(pos, size, objects=engineObjects)
  *  @memberof Engine
  */
 
-/** Triggers a callback for each object within a given area
+/** Triggers a callback for each object within a given area, objects destroyed this frame left out
  *  @param {Vector2} [pos] - Center of test area, or undefined for all objects
- *  @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
- *  @param {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test
+ *  @param {Vector2|number} [size] - Diameter of a circle if a number, full size of a rectangle if a Vector2
+ *  @param {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test, needed
+ *                                                     (marked optional only because the area before it is)
  *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
+ *  @param {boolean} [testCenters] - Test only each object's center, see engineObjectsCollect
  *  @memberof Engine */
-function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)
-{ engineObjectsCollect(pos, size, objects).forEach(o => callbackFunction(o)); }
+function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects, testCenters=false)
+{
+    // an object an earlier callback destroyed is skipped
+    for (const o of engineObjectsCollect(pos, size, objects, testCenters))
+        o.destroyed || callbackFunction(o);
+}
 
-/** Return a list of objects intersecting a ray
+/** Return a list of objects intersecting a ray, objects destroyed this frame left out
+ *  - Only objects with collideRaycast set are hit, which setCollision turns on
  *  @param {Vector2} start
  *  @param {Vector2} end
  *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
@@ -636,13 +917,13 @@ function engineObjectsRaycast(start, end, objects=engineObjects)
     const hitObjects = [];
     for (const o of objects)
     {
-        if (o.collideRaycast && isIntersecting(start, end, o.pos, o.size))
+        if (o.collideRaycast && !o.destroyed && isIntersecting(start, end, o.pos, o.size))
         {
-            debugRaycast && debugRect(o.pos, o.size, '#f00');
+            debugRaycast && debugRect(o.pos, o.size, '#f00', 0, 0, false, false);
             hitObjects.push(o);
         }
     }
 
-    debugRaycast && debugLine(start, end, hitObjects.length ? '#f00' : '#00f', .02);
+    debugRaycast && debugLine(start, end, hitObjects.length ? '#f00' : '#00f', .02, 0, false);
     return hitObjects;
 }