littlejsengine 1.24.3 → 1.26.0

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
@@ -35,8 +39,14 @@ let uiDebug = 0;
 function uiSetDebug(debugMode)
 { uiDebug = typeof debugMode === 'boolean' ? (debugMode ? 1 : 0) : debugMode; }
 
+/**
+ * @callback DragAndDropCallback - Callback for drag and drop events
+ * @param {DragEvent} event - The drag event
+ * @memberof UISystem
+ */
+
 ///////////////////////////////////////////////////////////////////////////////
-/** 
+/**
  * UI System Global Object
  * @memberof UISystem
  */
@@ -193,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;
@@ -339,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
@@ -513,7 +528,7 @@ class UISystemPlugin
     *  @param {'left'|'center'|'right'} [align]
     *  @param {string}  [font=uiSystem.defaultFont]
     *  @param {string}  [fontStyle]
-    *  @param {boolean} [applyMaxWidth=true]
+    *  @param {boolean} [applyMaxWidth]
     *  @param {Vector2} [textShadow]
     *  @param {Color}   [shadowColor]
     *  @param {number}  [shadowBlur]
@@ -528,12 +543,6 @@ class UISystemPlugin
         context.shadowColor = '#0000';
     }
 
-    /**
-     * @callback DragAndDropCallback - Callback for drag and drop events
-     * @param {DragEvent} event - The drag event
-     * @memberof UISystem
-     */
-
     /** Setup drag and drop event handlers
     *  Automatically prevents defaults and calls the given functions
     *  @param {DragAndDropCallback} [onDrop] - when a file is dropped
@@ -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);
@@ -1212,19 +1241,24 @@ class UIObject
     /** Called when the navigation button is pressed on this object */
     navigatePressed() { this.click(); }
 
-    /** @return {boolean} - Is the mouse hovering over this element */
+    /** Is the mouse hovering over this element
+     *  @return {boolean} */
     isHoverObject() { return uiSystem.hoverObject === this; }
 
-    /** @return {boolean} - Is the mouse held onto this element */
+    /** Is the mouse held onto this element
+     *  @return {boolean} */
     isActiveObject() { return uiSystem.activeObject === this; }
 
-    /** @return {boolean} - Is the gamepad or keyboard navigation object */
+    /** Is the gamepad or keyboard navigation object
+     *  @return {boolean} */
     isNavigationObject() { return uiSystem.navigationObject === this; }
 
-    /** @return {boolean} - Is this object in keyboard input mode */
+    /** Is this object in keyboard input mode
+     *  @return {boolean} */
     isKeyInputObject() { return uiSystem.keyInputObject === this; }
 
-    /** @return {boolean} - Can it be interacted with, it and every parent visible and enabled */
+    /** Can it be interacted with, it and every parent visible and enabled
+     *  @return {boolean} */
     isInteractive() { return this.interactive && uiObjectIsUsable(this); }
 
     /** Returns string containing info about this object for debugging
@@ -1371,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
@@ -1419,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
@@ -1427,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;
         }
     }
@@ -1755,9 +1789,9 @@ class UIVideo extends UIObject
      *  @param {Vector2} pos
      *  @param {Vector2} size
      *  @param {string} src - Video file path or URL
-     *  @param {boolean} [autoplay=false] - Start playing immediately?
-     *  @param {boolean} [loop=false] - Loop the video?
-     *  @param {number} [volume=1] - Volume percent scaled by global volume (0-1)
+     *  @param {boolean} [autoplay] - Start playing immediately?
+     *  @param {boolean} [loop] - Loop the video?
+     *  @param {number} [volume] - Volume percent scaled by global volume (0-1)
      */
     constructor(pos, size, src, autoplay=false, loop=false, volume=1)
     {
@@ -1912,10 +1946,10 @@ class UILayout extends UIObject
 {
     /** Create a UILayout container that auto-arranges children
      *  @param {Vector2} [pos]
-     *  @param {number}  [columns=1]     - Number of columns (1 = vertical list)
-     *  @param {number}  [gap=10]        - Space between children
-     *  @param {number}  [padding=10]    - Space between container border and children
-     *  @param {boolean} [transparent=false] - If true, draws no background, outline, or shadow
+     *  @param {number}  [columns]     - Number of columns (1 = vertical list)
+     *  @param {number}  [gap]        - Space between children
+     *  @param {number}  [padding]    - Space between container border and children
+     *  @param {boolean} [transparent] - If true, draws no background, outline, or shadow
      */
     constructor(pos, columns=1, gap=10, padding=10, transparent=false)
     {

package/plugins/wavedash.js

@@ -0,0 +1,229 @@
+/**
+ * LittleJS Wavedash Plugin
+ * - The Wavedash twin of the Newgrounds plugin: achievements and leaderboards, the same shape so a game can switch
+ * - Wavedash serves the game's page and puts its SDK in window.Wavedash before the game runs, so nothing is bundled;
+ *   off Wavedash (local, itch, GitHub Pages) there is none, and every call does nothing
+ * - Make the plugin when the game can draw, at the end of gameInit: Wavedash.init is called then, and until it is
+ *   Wavedash keeps its loading screen over the game
+ * - WavedashMedal is a Medal with the identifier of its Wavedash achievement; on Wavedash an unlock is sent as that
+ *   achievement and Wavedash shows its own toast in place of the engine's popup, off it the medal unlocks as any does
+ * - Wavedash refuses an achievement until it has loaded the player's, a moment after launch, so refused and earlier
+ *   unlocks are sent again every two seconds until it takes them; medals unlocked before, in the save, are sent too
+ * - Leaderboards are made from code: give the plugin a table of them, each with how it sorts and shows its scores,
+ *   and they are made at once, so each one exists from the first launch
+ * - The SDK checks its arguments' types and throws on a wrong one, so every call passes real booleans and whole
+ *   numbers and is caught; a game built with its own minifier keeps the SDK's names, see REFERENCE
+ * @namespace Wavedash
+ */
+
+'use strict';
+
+/** Global Wavedash plugin object
+ *  @type {WavedashPlugin}
+ *  @memberof Wavedash */
+let wavedash;
+
+// Engine internal variables not exposed to documentation
+const wavedashRetryMS = 2e3; // how long to wait before sending refused achievements again
+const wavedashRetries = 30;   // how many times one is sent before it is taken as never to be, about a minute
+const wavedashTimeoutMS = 15e3; // how long a leaderboard call may take, as the Newgrounds plugin waits
+const wavedashDisplayTypes = {number: 0, seconds: 1, milliseconds: 2, ticks: 3}; // the SDK's display types
+
+// the SDK Wavedash put on the page, read at each call, undefined off Wavedash
+const wavedashSDK = ()=> globalThis['Wavedash'];
+
+// a call's answer, or undefined if it does not come in time or fails, with a warning; the time limit is let go of once
+// the answer is in, so nothing waits on it after
+function wavedashWait(name, answer)
+{
+    let timer;
+    const limit = new Promise((resolve)=> timer = setTimeout(resolve, wavedashTimeoutMS));
+    return Promise.race([Promise.resolve(answer), limit])
+        .catch((error)=> { console.warn('Wavedash ' + name + ' failed: ' + error); })
+        .finally(()=> clearTimeout(timer));
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * WavedashMedal: a medal that is also a Wavedash achievement, unlocked on Wavedash by its identifier
+ * @extends Medal
+ * @memberof Wavedash
+ * @example
+ * const medal_finish = new WavedashMedal(0, 'ACH_01_FINISH', 'Finish', 'Finish a level');
+ * medal_finish.unlock(); // Wavedash's toast on Wavedash, the engine's popup anywhere else
+ */
+class WavedashMedal extends Medal
+{
+    /** Create a WavedashMedal and add it to the list of medals
+     *  @param {number} id            - The unique identifier of the medal, as for any Medal
+     *  @param {string} achievement   - The identifier of its Wavedash achievement, as made with the Wavedash CLI
+     *  @param {string} name          - Name of the medal
+     *  @param {string} [description] - Description of the medal
+     *  @param {string} [icon]        - Icon for the medal
+     *  @param {string} [src]         - Image location for the medal
+     */
+    constructor(id, achievement, name, description, icon, src)
+    {
+        ASSERT(typeof achievement === 'string' && achievement !== '', 'WavedashMedal: achievement must be the identifier of a Wavedash achievement', achievement);
+        super(id, name, description, icon, src);
+
+        /** @property {string} - The identifier of its Wavedash achievement */
+        this.achievement = achievement;
+    }
+
+    /** Unlocks the medal if not already unlocked, saved as any medal is; on Wavedash its achievement is sent, until
+     *  Wavedash takes it, and Wavedash shows its own toast in place of the engine's popup; one unlocked before the
+     *  plugin is made is sent when it is
+     *  @return {Promise<boolean>} - Whether the medal is unlocked */
+    unlock()
+    {
+        // off Wavedash, or testing medals with debugMedals, the engine's own popup and nothing sent
+        if (medalsPreventUnlock || this.unlocked || !wavedashSDK() || debugMedals)
+            return super.unlock();
+        this.unlocked = true;
+        medalsSave();
+        wavedash?.sendAchievements();
+        return Promise.resolve(true);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Wavedash plugin: starts the Wavedash SDK, sends achievements and posts and reads leaderboards
+ * @memberof Wavedash
+ * @example
+ * // at the end of gameInit, with the leaderboards the game posts to
+ * new WavedashPlugin({LEVEL_1: {lowerWins: true, display: 'milliseconds'}, HIGH_SCORE: {}});
+ * wavedash.postScore('LEVEL_1', timeMs);
+ */
+class WavedashPlugin
+{
+    /** Start the Wavedash SDK when the game is on Wavedash, and make its leaderboards
+     *  @param {Object<string, {lowerWins?: boolean, display?: string}>} [leaderboards] - The game's leaderboards by
+     *    name: lowerWins for times and golf, where a lower score is better, higher wins when left out; display how
+     *    Wavedash shows a score, 'number', 'seconds', 'milliseconds' or 'ticks' (60 a second), 'number' when left out
+     */
+    constructor(leaderboards={})
+    {
+        ASSERT(!wavedash, 'WavedashPlugin already initialized');
+        ASSERT(!!leaderboards && typeof leaderboards === 'object', 'WavedashPlugin: leaderboards is an object of them by name');
+        wavedash = this;
+
+        /** @property {Object<string, Promise<string|undefined>>} - Each leaderboard's id by its name, once Wavedash
+         *  has made or found it, undefined when it could not
+         *  @type {Object<string, Promise<string|undefined>>} */
+        this.leaderboards = Object.create(null); // no inherited names, a board may be called constructor
+        /** @type {Object<string, {lowerWins?: boolean, display?: string}>} */
+        this.leaderboardSettings = leaderboards; // how each one sorts and shows its scores, read as its own entries
+        /** @type {Set<string>} */
+        this.achievementsSent = new Set; // the achievements Wavedash took this visit, or refused for good
+        /** @type {Object<string, number>} */
+        this.achievementTries = Object.create(null); // how many times each one not taken yet was sent
+        /** @type {number|undefined} */
+        this.achievementRetry = undefined; // the timer that sends refused ones again
+
+        // Wavedash keeps its loading screen until init, which is called once
+        wavedashWait('init', this.call('init'));
+        for (const name in leaderboards)
+            this.leaderboard(name);
+        this.sendAchievements(); // the medals the save already has, unlocked before or off Wavedash
+    }
+
+    /** Whether the game is on Wavedash, its SDK on the page
+     *  @return {boolean} */
+    isActive() { return !!wavedashSDK(); }
+
+    /** Call the SDK, undefined off Wavedash; a call that throws, as on an argument of the wrong type, says so in
+     *  the console and gives undefined
+     *  @param {string} name - The SDK function
+     *  @param {...*} args
+     *  @return {*}
+     *  @ignore */
+    call(name, ...args)
+    {
+        const sdk = wavedashSDK();
+        if (!sdk) return;
+        try { return sdk[name](...args); }
+        catch (error) { console.warn('Wavedash ' + name + ' failed: ' + error); }
+    }
+
+    /** A leaderboard's id by its name, made on Wavedash the first time it is asked for, with the settings it was given
+     *  @param {string} name
+     *  @return {Promise<string|undefined>}
+     *  @ignore */
+    leaderboard(name)
+    {
+        ASSERT(typeof name === 'string' && name !== '', 'Wavedash: a leaderboard name must be a string', name);
+        if (this.leaderboards[name]) return this.leaderboards[name];
+        const settings = Object.prototype.hasOwnProperty.call(this.leaderboardSettings, name) ?
+            this.leaderboardSettings[name] : undefined; // its own entry, not an inherited one
+        const {lowerWins=false, display='number'} = settings || {};
+        const known = wavedashDisplayTypes.hasOwnProperty(display);
+        ASSERT(known, 'Wavedash: a leaderboard display is number, seconds, milliseconds or ticks', display);
+        const made = this.call('getOrCreateLeaderboard', name, lowerWins ? 0 : 1, known ? wavedashDisplayTypes[display] : 0);
+        const id = wavedashWait('leaderboard ' + name, made).then((result)=>
+            result?.['success'] ? result['data']?.['id'] : undefined);
+        // one that could not be made is asked for again next time
+        id.then((value)=> value === undefined && this.leaderboards[name] === id && delete this.leaderboards[name]);
+        return this.leaderboards[name] = id;
+    }
+
+    /** Post a score to a leaderboard, Wavedash keeping the player's best; off Wavedash it does nothing
+     *  - A leaderboard not in the table given to the plugin is made the first time, higher wins and shown as a number
+     *  @param {string} name - The leaderboard's name
+     *  @param {number} score - A whole number, milliseconds for a time
+     *  @return {Promise<boolean>} - Whether it was posted */
+    async postScore(name, score)
+    {
+        ASSERT(isNumber(score), 'Wavedash postScore: score must be a number', score);
+        if (!this.isActive()) return false;
+        const id = await this.leaderboard(name);
+        if (id === undefined) return false;
+        const result = await wavedashWait('postScore', this.call('uploadLeaderboardScore', id, round(score), true));
+        return !!result?.['success'];
+    }
+
+    /** Read a leaderboard's entries, undefined off Wavedash or when it could not be read
+     *  @param {string} name - The leaderboard's name
+     *  @param {number} [offset] - How many entries to skip over
+     *  @param {number} [limit] - How many entries to read
+     *  @param {boolean} [friendsOnly] - Only the player and their friends
+     *  @return {Promise<Array<Object>|undefined>} - The entries, as Wavedash gives them */
+    async getScores(name, offset=0, limit=10, friendsOnly=false)
+    {
+        if (!this.isActive()) return;
+        const id = await this.leaderboard(name);
+        if (id === undefined) return;
+        const result = await wavedashWait('getScores',
+            this.call('listLeaderboardEntries', id, offset|0, limit|0, !!friendsOnly));
+        return result?.['success'] ? result['data'] : undefined;
+    }
+
+    /** Send every unlocked WavedashMedal's achievement Wavedash has not taken yet, again every two seconds while it
+     *  refuses some, as it does until it has loaded the player's achievements; one refused for about a minute is
+     *  taken as an identifier Wavedash does not have, said once in the console, and not sent again this visit
+     *  @ignore */
+    sendAchievements()
+    {
+        if (!this.isActive() || debugMedals) return;
+        let refused = false;
+        medalsForEach((medal)=>
+        {
+            const achievement = medal instanceof WavedashMedal && medal.unlocked && medal.achievement;
+            if (!achievement || this.achievementsSent.has(achievement)) return;
+            const result = this.call('setAchievement', achievement, true);
+            if (result === true || result?.['success'] === true)
+                this.achievementsSent.add(achievement);
+            else if ((this.achievementTries[achievement] = (this.achievementTries[achievement] || 0) + 1) < wavedashRetries)
+                refused = true;
+            else
+            {
+                console.warn('Wavedash refused achievement ' + achievement + ' ' + wavedashRetries +
+                    ' times; is it made, with that identifier?');
+                this.achievementsSent.add(achievement); // not sent again this visit
+            }
+        });
+        clearTimeout(this.achievementRetry);
+        this.achievementRetry = refused ? setTimeout(()=> this.sendAchievements(), wavedashRetryMS) : undefined;
+    }
+}