littlejsengine 1.24.3 → 1.26.0

package/plugins/render3dVoxels.js

@@ -88,9 +88,11 @@ class VoxelMap extends EngineObject3D
         this.chunkTransparentMeshes = []; // each chunk's transparent blocks, drawn blended
         /** @type {Array<Vector3>} */
         this.chunkCenters = []; // a chunk mesh's points are around its center, which it is drawn at
+        /** @type {Set<number>} */
         this.chunksChanged = new Set;
         /** @type {Array<{faces: Array<number>, seeThrough: boolean, transparent: boolean, doubleSided: boolean}|undefined>} */
         this.blockTypes = [];
+        /** @type {Map<number, Array<Vector2>>} */
         this.tiles = new Map; // tile index to the uvs of its corners
 
         // the transparent blocks draw in the transparent stage, blended and sorted, through a child that draws them
@@ -98,6 +100,7 @@ class VoxelMap extends EngineObject3D
         glass.size3D = vec3(); // not a thing to collect either
         glass.transparent = true;
         glass.render3D = ()=> this.renderChunks(true);
+        render3DShareSettings(glass, this); // it draws as the map does, its material, stage and render order
         this.addChild(glass);
         render3DLevel.push(this);
     }
@@ -473,15 +476,24 @@ class VoxelMap extends EngineObject3D
     levelRaycast3D(ray) { return this.raycast(ray)?.distance; }
 
     /** Where a short move goes into a block, for a particle's move in one frame: the part of the move made before it,
-     *  0 to 1, and the normal of the face it comes in through; undefined when it hits none, or starts inside one
+     *  0 to 1, and the normal of the face it comes in through; undefined when it hits none, or starts inside one; a
+     *  move that starts on a block's face, coming in, hits it at 0
      *  @param {Vector3} from
      *  @param {Vector3} to
      *  @return {{distance: number, normal: Vector3}|undefined}
      *  @ignore */
     levelSegment3D(from, to)
     {
-        const hit = this.raycast(new Ray3D(from, to.subtract(from)), 1);
-        return hit && hit.distance > 0 ? {distance: hit.distance, normal: hit.normal} : undefined;
+        const move = to.subtract(from), hit = this.raycast(new Ray3D(from, move), 1);
+        if (!hit) return;
+        if (!hit.distance)
+        {
+            // met at its start: on a face when the point just behind the start is clear, inside a block when not
+            const behind = from.subtract(move.normalize(1e-6)).subtract(this.pos3D);
+            if (this.voxelAt(floor(behind.x), floor(behind.y), floor(behind.z)))
+                return;
+        }
+        return {distance: hit.distance, normal: hit.normal};
     }
 
     /** Keeps an eye on its placement, called automatically each frame */

package/plugins/textureSheet.js

@@ -263,7 +263,7 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
             console.warn('loadSprite failed to load image:', src);
             textureSheetLoadFailed(key, tileInfo);
         }
-    });
+    }, ()=> textureSheetLoadFailed(key, tileInfo));
 
     return tileInfo;
 }
@@ -329,7 +329,7 @@ function loadTiles(sources, tileSize=tileDefaultSize, padding=textureSheetPaddin
             added.sheet.drawImage(image, added.tile, false); // upload once per batch
             for (let k = 0; k < count; ++k)
                 set.tiles.push(added.tile.frame(k));
-        });
+        }, ()=> textureSheetLoadFailed(key, set));
     }
     return set;
 }
@@ -434,20 +434,21 @@ function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
             console.warn('loadAtlas failed to load:', imageSrc, jsonSrc);
             textureSheetLoadFailed(key, atlas);
         }
-    });
+    }, ()=> textureSheetLoadFailed(key, atlas));
 
     return atlas;
 }
 
-// run a load in the queue: a load that throws is reported and the loads after it carry on, the pending count
-// always comes back down, and the sheets upload to webgl once per batch, when the last pending load finishes
-function textureSheetQueueJob(name, job)
+// run a load in the queue: a load that throws is reported, let go of so the next call loads it again (failed), as
+// one whose file did not load is, and the loads after it carry on; the pending count always comes back down, and the
+// sheets upload to webgl once per batch, when the last pending load finishes
+function textureSheetQueueJob(name, job, failed)
 {
     ++textureSheetPendingCount;
     textureSheetQueue = textureSheetQueue.then(async ()=>
     {
         try { await job(); }
-        catch (e) { console.error(name + ' failed:', e); }
+        catch (e) { console.error(name + ' failed:', e); failed?.(); }
         finally
         {
             if (!--textureSheetPendingCount)
@@ -464,7 +465,7 @@ function textureSheetQueueJob(name, job)
  *  - Accepts TexturePacker json (hash and array) and Aseprite json
  *  - Frames tagged in Aseprite or named like run_0, run_1 group into animations
  *  @param {Object} data - Parsed atlas json data
- *  @return {Array<Object>} List of {name, frames} groups in atlas order
+ *  @return {Array<{name: string, frames: Array<Object>}>} List of {name, frames} groups in atlas order
  *  @memberof TextureSheets */
 function parseAtlas(data)
 {

package/plugins/threejs.js

@@ -65,7 +65,7 @@ class ThreeJSPlugin
         rootElement.insertBefore(threeCanvas, rootElement.firstChild);
         threeCanvas.style.cssText = mainCanvas.style.cssText;
 
-        // composite the 3D canvas into screenshots and video capture
+        // composite the 3D canvas into screenshots
         setBackgroundCanvas(threeCanvas);
 
         // render automatically each frame after the engine renders

package/plugins/tweenSystem.js

@@ -11,7 +11,8 @@
 
 ///////////////////////////////////////////////////////////////////////////////
 
-// Module-private list of tweens currently running, each with its active flag set while it is in it.
+// Module-private list of tweens currently running, each with its active flag set while it is in it; a stopped
+// one stays listed, inactive, until the next update takes it out, so stopping many is not a search for each
 const tweenActive = [];
 const tweenUpdateList = []; // the tweens an update moves, the ones active when it began
 let tweenUpdatePass = 0; // counts the updates, a tween started during one waits for the next
@@ -22,13 +23,23 @@ function tweenActivate(tween)
     tween.activePass = tweenUpdatePass; // started again, even while active, so this update leaves it alone
     if (tween.active) return;
     tween.active = true;
-    tweenActive.push(tween);
+    tween.listed || tweenActive.push(tween); // one stopped this update is still listed, in its place
+    tween.listed = true;
 }
-function tweenDeactivate(tween)
+function tweenDeactivate(tween) { tween.active = false; }
+
+// call a tween's callback with its value at life; one that throws, its easing too, is ended, or it would be called and
+// throw at every update, unless the callback itself started it again, which is its own new run (pass, the update it
+// is in, undefined outside one)
+function tweenCall(tween, life, pass)
 {
-    if (!tween.active) return;
-    tween.active = false;
-    tweenActive.splice(tweenActive.indexOf(tween), 1);
+    try { tween.callback(tween.interp(life)); }
+    catch (error)
+    {
+        if (tween.active && (pass === undefined || tween.activePass < pass))
+            tweenDeactivate(tween);
+        throw error;
+    }
 }
 
 // True if the value is an instance of a class that exposes a numeric-percent
@@ -57,9 +68,9 @@ class Tween
      *  callback receives the interpolated value (a number, or a fresh instance
      *  for lerp-able types). Both endpoints must be the same type.
      *  @param {function(NonNullable<T>):void} callback - Called with the interpolated value each frame
-     *  @param {T} [start=0] - Starting value
-     *  @param {T} [end=1] - Ending value
-     *  @param {number} [duration=1] - Duration in seconds
+     *  @param {T} [start] - Starting value
+     *  @param {T} [end] - Ending value
+     *  @param {number} [duration] - Duration in seconds
      *  @param {Object} [options]
      *  @param {function(number):number} [options.ease] - Easing function (defaults to LINEAR)
      *  @param {boolean} [options.useRealTime=false] - Advance even when the game is paused (matches Timer's useRealTime)
@@ -105,15 +116,18 @@ class Tween
          *  @type {undefined|function():void} */
         this.onComplete = undefined;
 
-        /** Continuation when a pass ends, set by loop() and pingPong() to start the next iteration.
+        /** Continuation when a pass ends, set by loop() and pingPong() to start the next iteration
          *  @private */
         this.thenCallback = undefined;
-        /** Remaining iterations including the current run (loop/pingPong only).
+        /** Remaining iterations including the current run (loop/pingPong only)
          *  @private */
         this.loopRemaining = 0;
-        /** Whether it is in the active list, see isActive
+        /** Whether it is running, see isActive
          *  @private */
         this.active = false;
+        /** Whether it is in the active list, which a stopped one leaves at the next update
+         *  @private */
+        this.listed = false;
         /** The update it was started in, it first moves on the one after
          *  @private */
         this.activePass = 0;
@@ -128,13 +142,13 @@ class Tween
         this.target = undefined;
 
         tweenActivate(this);
-        // Snap target to start immediately.
-        callback(this.interp(duration));
+        // Snap target to start immediately; one that throws here is no tween, the game never gets it to stop
+        tweenCall(this, duration);
     }
 
-    /** Set the easing curve and return this for chaining.
+    /** Set the easing curve and return this for chaining
      *  @param {function(number):number} easeFn
-     *  @returns {Tween<T>} */
+     *  @return {Tween<T>} */
     setEase(easeFn)
     {
         this.ease = easeFn;
@@ -149,7 +163,7 @@ class Tween
      *  - It is kept by `restart`, so a restarted tween calls it again when it completes
      *  - `stop` and `tweenStopAll` end a tween without calling it
      *  @param {function():void} callback
-     *  @returns {Tween<T>} */
+     *  @return {Tween<T>} */
     then(callback)
     {
         this.onComplete = callback;
@@ -165,7 +179,7 @@ class Tween
      *  A `then` callback, set before or after, is called when the last
      *  iteration ends.
      *  @param {number} [count=Infinity]
-     *  @returns {Tween<T>} */
+     *  @return {Tween<T>} */
     loop(count = Infinity)
     {
         this.loopRemaining = count;
@@ -180,7 +194,7 @@ class Tween
      *  A `then` callback, set before or after, is called when the last
      *  iteration ends.
      *  @param {number} [count=Infinity]
-     *  @returns {Tween<T>} */
+     *  @return {Tween<T>} */
     pingPong(count = Infinity)
     {
         this.loopRemaining = count;
@@ -188,10 +202,10 @@ class Tween
         return this;
     }
 
-    /** Pause this tween. While paused, tweenUpdate skips it. */
+    /** Pause this tween. While paused, tweenUpdate skips it */
     pause() { this.paused = true; }
 
-    /** Resume a paused tween. */
+    /** Resume a paused tween */
     resume() { this.paused = false; }
 
     /** Reset this tween to the start: life back to duration, pause cleared,
@@ -209,11 +223,11 @@ class Tween
         this.lastTime = time;
         this.lastTimeReal = timeReal;
         tweenActivate(this);
-        this.callback(this.interp(this.duration));
+        tweenCall(this, this.duration);
     }
 
-    /** True if this tween is in the active list and not paused.
-     *  @returns {boolean} */
+    /** True if this tween is in the active list and not paused
+     *  @return {boolean} */
     isActive()
     {
         return !this.paused && this.active;
@@ -221,7 +235,7 @@ class Tween
 
     /** Get how far this tween has progressed, from 0 (just started) to 1
      *  (completed). Clamped — overshoot past completion still reads 1.
-     *  @returns {number} */
+     *  @return {number} */
     getPercent()
     {
         return percent(this.duration - this.life, 0, this.duration);
@@ -230,7 +244,7 @@ class Tween
     /** Get the current interpolated value (the value most recently passed to
      *  the callback). Returns a number, Vector2, Vector3 or Color depending on the
      *  tween's start/end types.
-     *  @returns {T} */
+     *  @return {T} */
     getValue()
     {
         return this.interp(this.life);
@@ -242,7 +256,7 @@ class Tween
      *  - A vector goes past its ends as far as the easing does, as a number does; a Color stays between them,
      *    so its channels stay in range, and any other type goes as far as its own lerp takes it
      *  @param {number} life
-     *  @returns {T} */
+     *  @return {T} */
     interp(life)
     {
         // the ends of whatever type it tweens, each kind is handled below
@@ -283,46 +297,46 @@ class Tween
  */
 const Ease =
 {
-    /** Linear (identity) curve.
+    /** Linear (identity) curve
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     LINEAR: (x) => x,
 
     /** Power curve factory: `Ease.POWER(n)` returns `x => x**n`.
      *  Use n=2 for quadratic, n=3 for cubic, etc.
      *  @param {number} n
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease */
     POWER: (n) => (x) => x ** n,
 
-    /** Sine ease-in curve: starts slow, ends fast.
+    /** Sine ease-in curve: starts slow, ends fast
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     SINE: (x) => 1 - cos(x * (PI / 2)),
 
-    /** Circular ease-in curve.
+    /** Circular ease-in curve
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     CIRC: (x) => 1 - (1 - x * x)**.5,
 
-    /** Exponential ease-in curve (`2^(10x-10)`).
+    /** Exponential ease-in curve (`2^(10x-10)`)
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     EXPO: (x) => x === 0 ? 0 : 2 ** (10 * x - 10),
 
-    /** Back ease-in: overshoots backward at the start before snapping forward.
+    /** Back ease-in: overshoots backward at the start before snapping forward
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     BACK: (x) => x * x * (2.70158 * x - 1.70158),
 
-    /** Elastic ease-in: oscillations that grow toward the end.
+    /** Elastic ease-in: oscillations that grow toward the end
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     ELASTIC: (x) =>
         x === 0 ? 0 :
@@ -332,7 +346,7 @@ const Ease =
     /** Spring ease-in: wobbles around the start before springing to the end;
      *  `Ease.OUT(Ease.SPRING)` overshoots and settles on the target.
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease */
     SPRING: (x) =>
         1 -
@@ -346,7 +360,7 @@ const Ease =
      *  classic "object falls and hits the ground" shape (bounces near x=1),
      *  wrap with `Ease.OUT`: `Ease.OUT(Ease.BOUNCE)`.
      *  @param {number} x
-     *  @returns {number}
+     *  @return {number}
      *  @memberof TweenSystem.Ease
      *  @example
      *  Ease.BOUNCE                  // ease-in bounce (bouncy at start)
@@ -369,7 +383,7 @@ const Ease =
      *  convention, so wrapping a curve in `IN` is a no-op — useful when
      *  picking the direction programmatically.
      *  @param {function(number):number} f - Curve to use as ease-in (returned unchanged)
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease
      *  @example
      *  // Pick direction at runtime
@@ -380,16 +394,16 @@ const Ease =
 
     /** Reverse a curve so it eases out instead of in: `x => 1 - f(1 - x)`.
      *  @param {function(number):number} f
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease
      *  @example
      *  Ease.OUT(Ease.POWER(2)) // ease-out quadratic
      */
     OUT: (f) => (x) => 1 - f(1 - x),
 
-    /** Combine the first half of `f` with `Ease.OUT(f)` for a symmetric curve.
+    /** Combine the first half of `f` with `Ease.OUT(f)` for a symmetric curve
      *  @param {function(number):number} f
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease */
     IN_OUT: (f) => Ease.PIECEWISE(f, Ease.OUT(f)),
 
@@ -397,7 +411,7 @@ const Ease =
      *  Each curve is mapped to its section: section i runs over [i/n, (i+1)/n]
      *  and its output is mapped to [i/n, (i+1)/n] of the overall range.
      *  @param {...function(number):number} fns
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease */
     PIECEWISE: (...fns) =>
     {
@@ -415,7 +429,7 @@ const Ease =
      *  @param {number} y1
      *  @param {number} x2
      *  @param {number} y2
-     *  @returns {function(number):number}
+     *  @return {function(number):number}
      *  @memberof TweenSystem.Ease
      *  @example
      *  Ease.BEZIER(0.25, 0.1, 0.25, 1) // CSS "ease"
@@ -465,12 +479,12 @@ const Ease =
  *  @param {string} propertyPath - Dot-separated path, e.g. `'pos.x'` or `'color'`
  *  @param {T} start - Starting value
  *  @param {T} end - Ending value
- *  @param {number} [duration=1] - Duration in seconds
+ *  @param {number} [duration] - Duration in seconds
  *  @param {Object} [options] - Same options as the Tween constructor
  *  @param {function(number):number} [options.ease] - Easing function (defaults to LINEAR)
  *  @param {boolean} [options.useRealTime=false] - Advance even when the game is paused
  *  @param {boolean} [options.paused=false] - Start in paused state
- *  @returns {Tween<T>}
+ *  @return {Tween<T>}
  *  @memberof TweenSystem
  *  @example
  *  // Numeric: slide an object's x with an ease-out sine curve
@@ -527,7 +541,7 @@ function tweenNextIteration(tween, passed, continuation)
     tweenCarryOvershoot(tween);
     tween.thenCallback = continuation;
     tweenActivate(tween);
-    tween.callback(tween.interp(tween.life)); // snap to where the new iteration is
+    tweenCall(tween, tween.life); // snap to where the new iteration is
     return true;
 }
 
@@ -591,52 +605,68 @@ function tweenUpdate(gameDelta, realDelta)
     // from the next update. Newest first, as the list has always been walked.
     // a callback that calls tweenUpdate itself gets a list of its own, the outer update is still walking this one
     const list = tweenUpdateList.length ? [] : tweenUpdateList, pass = ++tweenUpdatePass;
+    let kept = 0;
     for (const t of tweenActive)
-        list.push(t);
+        if (t.active)
+            list.push(tweenActive[kept++] = t);
+        else
+            t.listed = false; // stopped since the last update, out of the list now
+    tweenActive.length = kept;
     // the list is let go however the walk ends: a callback that throws must not leave it held, or every
     // update after would take it for an update still going and make a list of its own
+    let failed;
     try
     {
         for (let i = list.length; i--;)
         {
             const t = list[i];
-            // stopped, or started again by a callback this update, or during an update a callback ran inside it, which
-            // counts on from this one
-            if (!t.active || t.activePass >= pass) continue;
-            let dt;
-            if (enginePath)
-            {
-                // a paused tween keeps count too, so it does not jump when resumed
-                dt = t.useRealTime ? timeReal - t.lastTimeReal : time - t.lastTime;
-                t.lastTime = time;
-                t.lastTimeReal = timeReal;
-            }
-            else
-                dt = t.useRealTime ? realDelta : gameDelta;
-            if (t.target?.destroyed) { t.stop(); continue; } // its object is gone, paused or not
-            if (t.paused || dt <= 0) continue;
-
-            t.life -= dt;
-            if (t.life > 1e-9) // the engine's deltas add up a rounding error short of the duration
-            {
-                t.callback(t.interp(t.life));
-            }
-            else
-            {
-                // Completion: fire end value, remove from active, start the next iteration
-                // of a loop or pingPong, or when there is none it has completed, fire onComplete
-                t.callback(t.interp(0));
-                if (!t.active || t.activePass >= pass)
-                    continue; // stopped or restarted by its own callback, the run it was on ends without completing
-                tweenDeactivate(t);
-                const next = t.thenCallback;
-                t.thenCallback = undefined;
-                if (!(next && next()) && t.onComplete)
-                    t.onComplete();
-            }
+            // one that throws does not stop the others: its error comes out once they have all moved
+            try { tweenStep(t, pass, enginePath, gameDelta, realDelta); }
+            catch (error) { failed ??= {error}; }
         }
     }
     finally { list.length = 0; }
+    if (failed)
+        throw failed.error;
+}
+
+// move one tween by an update, as tweenUpdate walks them
+function tweenStep(t, pass, enginePath, gameDelta, realDelta)
+{
+    // stopped, or started again by a callback this update, or during an update a callback ran inside it, which
+    // counts on from this one
+    if (!t.active || t.activePass >= pass) return;
+    let dt;
+    if (enginePath)
+    {
+        // a paused tween keeps count too, so it does not jump when resumed
+        dt = t.useRealTime ? timeReal - t.lastTimeReal : time - t.lastTime;
+        t.lastTime = time;
+        t.lastTimeReal = timeReal;
+    }
+    else
+        dt = t.useRealTime ? realDelta : gameDelta;
+    if (t.target?.destroyed) { t.stop(); return; } // its object is gone, paused or not
+    if (t.paused || dt <= 0) return;
+
+    t.life -= dt;
+    if (t.life > 1e-9) // the engine's deltas add up a rounding error short of the duration
+    {
+        tweenCall(t, t.life, pass);
+    }
+    else
+    {
+        // Completion: fire end value, remove from active, start the next iteration
+        // of a loop or pingPong, or when there is none it has completed, fire onComplete
+        tweenCall(t, 0, pass); // one whose last call throws is ended all the same
+        if (!t.active || t.activePass >= pass)
+            return; // stopped or restarted by its own callback, the run it was on ends without completing
+        tweenDeactivate(t);
+        const next = t.thenCallback;
+        t.thenCallback = undefined;
+        if (!(next && next()) && t.onComplete)
+            t.onComplete();
+    }
 }
 
 /** Stop every active tween, ending loops too, without calling their then-callbacks.
@@ -645,7 +675,7 @@ function tweenUpdate(gameDelta, realDelta)
 function tweenStopAll()
 {
     for (const t of tweenActive)
-        t.thenCallback = undefined, t.active = false;
+        t.thenCallback = undefined, t.active = t.listed = false;
     tweenActive.length = 0;
 }