littlejsengine 1.19.3 → 1.20.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.20.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -56,6 +56,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 +69,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;
@@ -91,6 +94,23 @@ function setPaused(isPaused=true) { paused = isPaused; }
 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 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
+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 +135,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]
@@ -148,13 +169,15 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
  */
 
 /** 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 +192,13 @@ 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;
     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 +209,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 +226,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 +236,11 @@ 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'); // -
+        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,11 +248,11 @@ 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
+        // 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 wasUpdated = false, deltaSmooth = 0;
@@ -241,22 +266,28 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         // 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)
+            // 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 = frame++ / frameRate;
 
-            // update game and objects, when paused update everything except them
+            // update game and objects, when frozen update everything except them
             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();
@@ -272,6 +303,10 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         // 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
         let windowChanged = false;
@@ -289,8 +324,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 +348,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 +359,32 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             primitiveCount = 0;
         }
     }
-    engineUpdateInternal = engineUpdate;
 
     // skip setup if headless
     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 +411,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 +424,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,7 +435,8 @@ 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
@@ -400,6 +447,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     {
         // wait for gameInit to load
         await gameInit();
+        engineUpdateInternal = engineUpdate; // engineStep only runs once the game is set up
         engineManualStep || engineUpdate();
     }
 }
@@ -440,9 +488,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 +543,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 +584,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 +592,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 +668,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 +678,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 +725,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 +752,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;
 }