littlejsengine 1.25.0 → 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

@@ -28,6 +28,20 @@ function tweenActivate(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)
+{
+    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
 // `lerp(other, percent)` method (Vector2, Color, or any future class).
 function tweenIsLerpable(v) { return v && typeof v.lerp === 'function'; }
@@ -102,10 +116,10 @@ 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 running, see isActive
@@ -128,11 +142,11 @@ 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
      *  @return {Tween<T>} */
     setEase(easeFn)
@@ -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,10 +223,10 @@ 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.
+    /** True if this tween is in the active list and not paused
      *  @return {boolean} */
     isActive()
     {
@@ -283,7 +297,7 @@ class Tween
  */
 const Ease =
 {
-    /** Linear (identity) curve.
+    /** Linear (identity) curve
      *  @param {number} x
      *  @return {number}
      *  @memberof TweenSystem.Ease */
@@ -296,31 +310,31 @@ const Ease =
      *  @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
      *  @return {number}
      *  @memberof TweenSystem.Ease */
     SINE: (x) => 1 - cos(x * (PI / 2)),
 
-    /** Circular ease-in curve.
+    /** Circular ease-in curve
      *  @param {number} x
      *  @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
      *  @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
      *  @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
      *  @return {number}
      *  @memberof TweenSystem.Ease */
@@ -387,7 +401,7 @@ const Ease =
      */
     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
      *  @return {function(number):number}
      *  @memberof TweenSystem.Ease */
@@ -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;
 }
 
@@ -600,48 +614,59 @@ function tweenUpdate(gameDelta, realDelta)
     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.

package/plugins/uiSystem.js

@@ -28,6 +28,10 @@ let uiSystem;
  *  @memberof UISystem */
 let uiDebug = 0;
 
+// the active object's press was let go of in the frame it came, a tap, so it is clicked on the next with no release
+// then; a click needs a release, which the mouse let go of by a window losing focus is not
+let uiActiveReleased = false;
+
 /** Enable UI system debug drawing
  *  0=off, 1=normal, 2=show invisible
  *  @param {number|boolean} debugMode
@@ -199,8 +203,10 @@ class UISystemPlugin
 
         // setup recursive update and render
         // update in reverse order to detect mouse enter/leave
+        let updatePass = 0; // marks the objects each update has reached, see updateObject
         function uiUpdate()
         {
+            ++updatePass;
             // a held or focused object that can no longer be used, itself or through a parent, lets go,
             // and one that was hidden or disabled is still released, a destroyed one stays silent
             const activeObject = uiSystem.activeObject;
@@ -345,7 +351,10 @@ class UISystemPlugin
 
             function updateObject(o)
             {
-                if (o.destroyed || !o.visible) return;
+                // once a pass, though a callback may move it under a parent not yet reached, or detach it to the
+                // top level, where the loop reaches it again
+                if (o.destroyed || !o.visible || o.uiUpdatePass === updatePass) return;
+                o.uiUpdatePass = updatePass;
 
                 // update in reverse order to detect mouse enter/leave, from a copy since a child may destroy
                 // siblings mid-update (e.g. dialog close) and the ones after it would shift under the loop
@@ -821,7 +830,7 @@ class UISystemPlugin
         // close menu and clear the input that closed it
         function closeMenu()
         {
-            ASSERT(uiSystem.confirmDialog === confirmMenu);
+            ASSERT(uiSystem.confirmDialog === confirmMenu, 'the confirm dialog closing is not the one open');
             confirmMenu.destroy();
             inputClear();
         }
@@ -961,6 +970,7 @@ class UIObject
         this.textLineWidth = 0;
         /** @property {boolean} - Should this object be drawn */
         this.visible  = true;
+        this.uiUpdatePass = 0; // the UI update that last reached it, so a pass updates it once
         /** @property {Array<UIObject>} - A list of this object's children
          *  @type {Array<UIObject>} */
         this.children = [];
@@ -1023,7 +1033,8 @@ class UIObject
      *  @param {UIObject} child */
     removeChild(child)
     {
-        ASSERT(child.parent === this && this.children.includes(child));
+        ASSERT(child.parent === this && this.children.includes(child), 'removeChild: that object is not a child of this one',
+            child);
         this.children.splice(this.children.indexOf(child), 1);
         child.parent = undefined;
     }
@@ -1095,10 +1106,24 @@ class UIObject
             return;
 
         const wasHover = uiSystem.lastHoverObject === this;
-        const isActive = this.isActiveObject();
+        let isActive = this.isActiveObject();
         const mouseDown = mouseIsDown(0);
         // a press and release in one frame is a press too, as it is for a button that is not drag activated
         const mousePress = mouseWasPressed(0) || this.dragActivate && mouseDown;
+
+        // a new press while this is still active from the one before means that one was let go of in between, by a
+        // second quick tap or a release missed in a hitch: it is clicked and released first, so neither is lost
+        if (isActive && mouseWasPressed(0))
+        {
+            if (!uiSystem.activateOnPress && this.interactive && !disabled)
+                this.click();
+            if (this.destroyed) return;
+            uiSystem.activeObject = undefined;
+            isActive = false;
+            this.onRelease();
+            this.soundRelease && this.soundRelease.play();
+            if (this.destroyed) return;
+        }
         if (this.canBeHover)
         if (!uiSystem.navigationMode) // no mouse hover in navigation mode
         if (mousePress || isActive || (!mouseDown && !isTouchDevice))
@@ -1130,7 +1155,10 @@ class UIObject
                             this.soundRelease && this.soundRelease.play();
                         }
                         else
+                        {
                             uiSystem.activeObject = this;
+                            uiActiveReleased = !mouseDown;
+                        }
 
                         if (newPress && uiSystem.activateOnPress)
                             this.click(!this.soundPress);
@@ -1142,6 +1170,7 @@ class UIObject
                 // frame is clicked on the next, with its release, not on both
                 if (!uiSystem.activateOnPress)
                 if (!mouseDown && isActive && this.isActiveObject() && this.interactive)
+                if (mouseWasReleased(0) || uiActiveReleased)
                     this.click();
                 if (this.destroyed) return;
             }
@@ -1194,7 +1223,7 @@ class UIObject
     getTextSize()
     {
         // text fitted to the size shares its height between its lines, a set textHeight is the height of each line
-        const lines = this.textHeight ? 1 : (this.text + '').split('\n').length;
+        const lines = this.textHeight ? 1 : textLineCount(this.text + '');
         return vec2(
             this.textWidth  || this.textFitScale * this.size.x,
             this.textHeight || this.textFitScale * this.size.y / lines);
@@ -1376,7 +1405,7 @@ class UITextInput extends UIObject
 
         ASSERT(isStringLike(text), 'ui text must be a string');
 
-        /** @property {number} - Max length of input (0 = no limit) */
+        /** @property {number} - Max length of input in characters as a reader counts them (0 = no limit) */
         this.maxLength = 0;
 
         // set properties, as a string, which typing adds to
@@ -1424,7 +1453,7 @@ class UITextInput extends UIObject
             return; // a key held when editing began repeats, it should not type or stop editing
         this.text += ''; // a game may have set a number
         if (key === 'Backspace')
-            this.text = [...this.text].slice(0, -1).join(''); // a whole character, an emoji is two code units
+            this.text = textGraphemes(this.text).slice(0, -1).join(''); // a whole character, an emoji family too
         else if (key === 'Enter' || key === 'Escape')
             this.stopEditing();
         else if (key.length === 1) // printable characters
@@ -1432,7 +1461,7 @@ class UITextInput extends UIObject
             // ctrl and cmd shortcuts do not type, but AltGr reports ctrl and alt and types characters like @
             if ((e.ctrlKey || e.metaKey) && !e.getModifierState?.('AltGraph'))
                 return;
-            if (!this.maxLength || this.text.length < this.maxLength)
+            if (!this.maxLength || textGraphemes(this.text).length < this.maxLength)
                 this.text += key;
         }
     }