littlejsengine 1.26.0 → 1.27.0

package/plugins/wavedash.js

@@ -1,6 +1,7 @@
 /**
  * LittleJS Wavedash Plugin
- * - The Wavedash twin of the Newgrounds plugin: achievements and leaderboards, the same shape so a game can switch
+ * - The Wavedash twin of the Newgrounds plugin: achievements, leaderboards and cloud saves, the same shape so a game
+ *   can switch, and stats and presence of Wavedash's own
  * - 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
@@ -32,17 +33,33 @@ const wavedashDisplayTypes = {number: 0, seconds: 1, milliseconds: 2, ticks: 3};
 // the SDK Wavedash put on the page, read at each call, undefined off Wavedash
 const wavedashSDK = ()=> globalThis['Wavedash'];
 
+// the file a cloud save slot is kept in
+const wavedashSavePath = (slot)=> 'saves/slot' + slot + '.json';
+
 // 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)
+function wavedashWait(name, answer, quiet=false)
 {
     let timer;
-    const limit = new Promise((resolve)=> timer = setTimeout(resolve, wavedashTimeoutMS));
+    const timedOut = {}; // what the time limit gives, told apart from any answer
+    const limit = new Promise((resolve)=> timer = setTimeout(()=> resolve(timedOut), wavedashTimeoutMS));
     return Promise.race([Promise.resolve(answer), limit])
-        .catch((error)=> { console.warn('Wavedash ' + name + ' failed: ' + error); })
+        .then((value)=> value !== timedOut ? value : quiet ? undefined :
+            void console.warn('Wavedash ' + name + ' took over ' + wavedashTimeoutMS / 1e3 + ' seconds'),
+            (error)=> { console.warn('Wavedash ' + name + ' failed: ' + error); })
         .finally(()=> clearTimeout(timer));
 }
 
+// a value as the text a cloud save keeps, undefined with a warning for one JSON can not hold, as a circular object,
+// a BigInt, a function or undefined
+function wavedashSaveText(slot, data)
+{
+    let text;
+    try { text = JSON.stringify(data); } catch (error) {}
+    text === undefined && console.warn('Wavedash cloudSave: slot ' + slot + ' was given a value JSON can not hold');
+    return text;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * WavedashMedal: a medal that is also a Wavedash achievement, unlocked on Wavedash by its identifier
@@ -121,6 +138,14 @@ class WavedashPlugin
         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
+        /** @type {Promise<boolean>|undefined} */
+        this.stats = undefined; // the player's stats loading, asked for the first time a stat is
+        /** @type {Map<string, Promise<*>>} */
+        this.slotQueues = new Map; // each slot's last save or load, the next waits for it, as they share a file
+        /** @type {Map<string, Set<Promise<*>>>} */
+        this.slotCalls = new Map; // each slot's file calls Wavedash has not answered, a timed out one may still change it
+        /** @type {Map<string, 'failed'|'notSave'>} */
+        this.loadFailures = new Map; // why each slot's last load gave undefined, by its file, see loadFailure
 
         // Wavedash keeps its loading screen until init, which is called once
         wavedashWait('init', this.call('init'));
@@ -199,6 +224,212 @@ class WavedashPlugin
         return result?.['success'] ? result['data'] : undefined;
     }
 
+    /** Save a value to one of the player's cloud save slots, kept by Wavedash across devices; off Wavedash it does
+     *  nothing
+     *  - Any value JSON can hold, stored as the file saves/slot#.json
+     *  - Wavedash takes at most 30 saves a minute and 300 an hour from a player, so save at checkpoints, the end of a
+     *    level or when asked, not every frame; one over the limit is refused, said in the console
+     *  @param {number} slot - The slot number, any whole number the game picks
+     *  @param {*} data - The value to save
+     *  @return {Promise<boolean>} - Whether it saved
+     *  @example
+     *  wavedash.cloudSave(1, {level, coins}); */
+    async cloudSave(slot, data)
+    {
+        ASSERT(isNumber(slot), 'Wavedash cloudSave: slot must be a number', slot);
+        if (!this.isActive()) return false;
+        const text = wavedashSaveText(slot, data); // as it is now, the save waits its turn
+        if (text === undefined) return false;
+        return this.slotQueue(slot, false, async (track)=>
+        {
+            // written first, and only a write Wavedash says it made is uploaded, never an older file at that path
+            const path = wavedashSavePath(slot);
+            const written = await wavedashWait('cloudSave', track(this.call('writeLocalFile', path,
+                new TextEncoder().encode(text))));
+            if (written !== true && !written?.['success'])
+            {
+                written && console.warn('Wavedash refused writing slot ' + slot + ': ' +
+                    (written['message'] ?? written['error'] ?? 'no reason given'));
+                return false;
+            }
+            const result = await wavedashWait('cloudSave', track(this.call('uploadRemoteFile', path)));
+            result && !result['success'] && console.warn('Wavedash refused cloudSave of slot ' + slot + ': ' +
+                (result['message'] ?? result['error'] ?? 'no reason given'));
+            return !!result?.['success'];
+        });
+    }
+
+    /** Load the value a cloud save slot holds: null when Wavedash says it holds none, undefined when it could not be
+     *  loaded or off Wavedash, said in the console on Wavedash
+     *  - Do not save over a slot that loaded as undefined, it may hold the player's save; loadFailure(slot) says why
+     *    it did: 'notSave' for a file there that is not a save, where a game may offer to start over, 'failed' otherwise
+     *  - A saved null loads as null, as an empty slot does
+     *  @param {number} slot - The slot number
+     *  @return {Promise<*>} - The value saved, null for none, undefined for a load that failed
+     *  @example
+     *  const save = await wavedash.cloudLoad(1); */
+    async cloudLoad(slot)
+    {
+        ASSERT(isNumber(slot), 'Wavedash cloudLoad: slot must be a number', slot);
+        const failed = {value: undefined, failure: /** @type {'failed'} */ ('failed')};
+        const {value, failure} = this.isActive() ?
+            await this.slotQueue(slot, failed, (track)=> this.loadSlot(slot, track)) : failed;
+        const key = wavedashSavePath(slot);
+        failure ? this.loadFailures.set(key, failure) : this.loadFailures.delete(key);
+        return value;
+    }
+
+    /** Why a slot's last cloudLoad gave undefined: 'notSave' when the slot holds a file that is not a save, where a
+     *  game may offer to start over, 'failed' when it could not be loaded, as off Wavedash or on a timeout, where a
+     *  game must not save over it; undefined when it loaded a save or found the slot empty, or was not loaded
+     *  @param {number} slot - The slot number
+     *  @return {'failed'|'notSave'|undefined} */
+    loadFailure(slot) { return this.loadFailures.get(wavedashSavePath(slot)); }
+
+    /** A slot's load, its value and why it failed, if it did
+     *  @param {number} slot
+     *  @param {function(*): *} track
+     *  @return {Promise<{value: *, failure: 'failed'|'notSave'|undefined}>}
+     *  @ignore */
+    async loadSlot(slot, track)
+    {
+        const path = wavedashSavePath(slot);
+        const failed = (message)=>
+        {
+            console.warn('Wavedash ' + message);
+            return {value: undefined, failure: /** @type {'failed'} */ ('failed')};
+        };
+        const downloaded = await wavedashWait('cloudLoad', track(this.call('downloadRemoteFile', path)));
+        if (downloaded !== true && !downloaded?.['success']) // an answer of true or of {success: true}
+        {
+            // a file Wavedash says is not there is an empty slot, anything else a load that failed; it may answer
+            // false or {success: true, data: false}
+            const exists = await wavedashWait('cloudLoad', track(this.call('remoteFileExists', path)));
+            if (exists === false || exists?.['success'] && exists['data'] === false)
+                return {value: null, failure: undefined};
+            return failed('could not load slot ' + slot);
+        }
+
+        // the file's text, its bytes given as they are or in a response's data; none is a read that failed, as a
+        // save is never empty
+        const answer = await wavedashWait('cloudLoad', track(this.call('readLocalFile', path)));
+        const bytes = answer instanceof Uint8Array || answer instanceof ArrayBuffer || typeof answer == 'string' ?
+            answer : answer?.['data'];
+        const text = !bytes ? '' : typeof bytes == 'string' ? bytes : new TextDecoder().decode(bytes);
+        if (!text) return failed('could not read slot ' + slot);
+        try { return {value: JSON.parse(text), failure: undefined}; }
+        catch (error)
+        {
+            console.warn('Wavedash cloudLoad: slot ' + slot + ' holds a file that is not a save');
+            return {value: undefined, failure: 'notSave'};
+        }
+    }
+
+    /** Run a slot's save or load after the one before it, as they share the slot's local file; other slots go on
+     *  at once, and one that fails does not hold up the next
+     *  - A call that timed out may still change the file when Wavedash gets to it, so the next waits for it to be
+     *    answered too, and gives up with failed when it is not, leaving the file alone
+     *  @param {number} slot
+     *  @param {*} failed - What the task gives when it can not run
+     *  @param {function(function(*): *): Promise<*>} task - Given track, which keeps a call's answer until it is in
+     *  @return {Promise<*>}
+     *  @ignore */
+    slotQueue(slot, failed, task)
+    {
+        const key = wavedashSavePath(slot); // by its file, so a slot given as '1' and as 1 share one
+        const calls = this.slotCalls.get(key) || new Set;
+        this.slotCalls.set(key, calls);
+        const track = (answer)=>
+        {
+            if (typeof answer?.then == 'function') // any promise, one made elsewhere too
+            {
+                calls.add(answer);
+                const done = ()=>
+                {
+                    calls.delete(answer);
+                    // the last of them, answered after the slot was let go of, lets go of its calls too
+                    calls.size || this.slotQueues.has(key) || this.slotCalls.get(key) !== calls ||
+                        this.slotCalls.delete(key);
+                };
+                answer.then(done, done);
+            }
+            return answer;
+        };
+        const start = async ()=>
+        {
+            if (calls.size && !await wavedashWait('slot ' + slot, Promise.allSettled([...calls]).then(()=> true), true))
+            {
+                console.warn('Wavedash slot ' + slot + ' is still busy with a call that timed out, not used');
+                return failed;
+            }
+            return task(track);
+        };
+        const run = (this.slotQueues.get(key) || Promise.resolve()).then(start, start);
+        const done = run.catch(()=> {});
+        this.slotQueues.set(key, done);
+        done.then(()=>
+        {
+            // the slot is let go of once nothing waits on it, and its calls with it once all are answered
+            if (this.slotQueues.get(key) !== done) return;
+            this.slotQueues.delete(key);
+            calls.size || this.slotCalls.get(key) !== calls || this.slotCalls.delete(key);
+        });
+        return run;
+    }
+
+    /** Set one of the player's stats, as made for the game in the Wavedash developer portal, which can unlock an
+     *  achievement set to follow it; Wavedash keeps it about a second later, or at once with storeNow; off Wavedash it
+     *  does nothing
+     *  @param {string} name - The stat's identifier
+     *  @param {number} value
+     *  @param {boolean} [storeNow] - Keep it now, as at the end of a game, not a second later
+     *  @return {Promise<boolean>} - Whether Wavedash took it */
+    async setStat(name, value, storeNow=false)
+    {
+        ASSERT(typeof name === 'string' && name !== '', 'Wavedash setStat: name must be a string', name);
+        ASSERT(isNumber(value), 'Wavedash setStat: value must be a number', value);
+        if (!this.isActive() || !await this.statsLoaded()) return false;
+        return this.call('setStat', name, value, !!storeNow) === true;
+    }
+
+    /** Read one of the player's stats, 0 for one never set or off Wavedash
+     *  @param {string} name - The stat's identifier
+     *  @return {Promise<number>} */
+    async getStat(name)
+    {
+        if (!this.isActive() || !await this.statsLoaded()) return 0;
+        const value = this.call('getStat', name);
+        return isNumber(value) ? value : 0;
+    }
+
+    /** The player's stats loaded from Wavedash, which they must be before they are read or set, asked for the first
+     *  time a stat is
+     *  @return {Promise<boolean>} - Whether they loaded
+     *  @ignore */
+    statsLoaded()
+    {
+        return this.stats ||= wavedashWait('requestStats', this.call('requestStats')).then((result)=>
+        {
+            const loaded = !!result?.['success'];
+            loaded || (this.stats = undefined); // asked for again next time
+            return loaded;
+        });
+    }
+
+    /** Set what the player is doing, kept with their presence on Wavedash; off Wavedash it does nothing
+     *  @param {string} [status] - One line of what they are doing, like 'In a race'
+     *  @param {string} [details] - More about it, like 'Lap 2 of 3'; both left out clears it
+     *  @return {Promise<boolean>} - Whether it was set */
+    async setPresence(status, details)
+    {
+        if (!this.isActive()) return false;
+        const presence = {};
+        status === undefined || (presence['status'] = String(status));
+        details === undefined || (presence['details'] = String(details));
+        const result = await wavedashWait('setPresence', this.call('updateUserPresence', presence));
+        return !!result?.['success'];
+    }
+
     /** 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

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.26.0';
+const engineVersion = '1.27.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -66,6 +66,8 @@ let engineObjectsCollideStaticLast = [];
 let frame = 0;
 
 /** Current engine time since start in seconds
+ *  - Below 20 FPS it falls behind the clock, since a frame catches up at most 50 ms of updates, so a timer in
+ *    real seconds, one that must keep up on a slow device, goes by timeReal
  *  @type {number}
  *  @memberof Engine */
 let time = 0;
@@ -91,8 +93,13 @@ function getPaused() { return paused; }
  *  @memberof Engine */
 function setPaused(isPaused=true) { paused = isPaused; }
 
+/** Frames drawn per second, smoothed over the last few seconds, in release builds too
+ *  @type {number}
+ *  @memberof Engine */
+let averageFPS = 0;
+
 // Engine internal variables
-let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+let frameTimeLastMS = 0, frameTimeBufferMS = 0;
 
 // delta smoothing, after Time Delta Smoothing by Frank Force (2013): a frame is on screen for whole display frames,
 // so each delta is rounded to them and the rest is carried to the next, keeping the total real time; the frame
@@ -190,6 +197,10 @@ let engineCollideGridMin = 64;
 // everything
 let engineCollideGrid;
 
+// where each object that collides with solids was before this frame's moves, kept only when a one way solid is among
+// them, so a one way test goes by where both were whichever of the two updates first
+let engineObjectsOneWayStart;
+
 // the grid of a list of solids, its cells about twice a typical solid so most are in one to four
 function engineCollideGridBuild(list)
 {
@@ -433,7 +444,9 @@ function engineLoadingScreenDraw(elapsed)
  *  @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>|string} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png']), or one path
- *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
+ *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body; it is
+ *                                       styled for a game (no scroll bars or selection, touch-action none),
+ *                                       where its own inline style does not say otherwise
  *    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
@@ -496,8 +509,10 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         // by ~page-load-time when RAF starts handing real timestamps
         if (!frameTimeLastMS) frameTimeDeltaMS = 0;
         frameTimeLastMS = frameTimeMS;
-        if (debug || debugWatermark)
-            averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
+        // the first frame's rate seeds the average, so it does not start out climbing from 0; a gap of over a
+        // second, a hidden tab coming back, is not a frame
+        if (frameTimeDeltaMS && frameTimeDeltaMS < 1e3)
+            averageFPS = averageFPS ? lerp(averageFPS, 1e3/frameTimeDeltaMS, .05) : 1e3/frameTimeDeltaMS;
         // the time the frame will be on screen, in whole display frames; engineStep's steps are exact already
         if (!manualStepAtStart)
             frameTimeDeltaMS = engineSmoothDelta(frameTimeDeltaMS);
@@ -946,19 +961,36 @@ function engineObjectsUpdate()
     // every frame makes this function deoptimize again and again in a game with no grid
     if (engineObjectsCollideStaticLast.length >= engineCollideGridMin)
         engineCollideGrid = {list: engineObjectsCollideStaticLast, built: undefined};
+    // written only when there is a one way solid, as the grid is
+    if (engineObjectsCollide.some((o)=> o.oneWay))
+        engineObjectsOneWayStart = new Map(engineObjectsCollide.map((o)=> [o, o.pos.copy()]));
 
     // update physics before object update, each solid put where it moved to in the grid, for the movers after it;
     // the grid is let go even when a callback throws, so an updatePhysics called before the next update checks all
+    // a one way solid with no mass moves first, nothing pushes it, so what lands on it or passes up through it sees it
+    // where it is now and where it was, whatever the render order
+    const oneWayFirst = (o)=> o.oneWay && !o.mass;
     try
     {
+        if (engineObjectsOneWayStart)
+            for (const o of engineObjects)
+                if (!o.parent && !o.destroyed && oneWayFirst(o))
+                {
+                    o.updatePhysics();
+                    engineCollideGrid?.built && engineCollideGridPlace(engineCollideGrid.built, o);
+                }
         for (const o of engineObjects)
-            if (!o.parent && !o.destroyed)
+            if (!o.parent && !o.destroyed && !(engineObjectsOneWayStart && oneWayFirst(o)))
             {
                 o.updatePhysics();
                 engineCollideGrid?.built && engineCollideGridPlace(engineCollideGrid.built, o);
             }
     }
-    finally { engineCollideGrid && (engineCollideGrid = undefined); }
+    finally
+    {
+        engineCollideGrid && (engineCollideGrid = undefined);
+        engineObjectsOneWayStart && (engineObjectsOneWayStart = undefined);
+    }
 
     // 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

package/src/engineDraw.js

@@ -548,6 +548,9 @@ class SpriteAnimator
  *   across the sprite or the mesh's own uv
  * - Names in 3D only: worldPos, worldNormal, cameraPos, sunDirection, sunColor, ambientColor, ambientGroundColor,
  *   lightCount, lights[i], lightColors[i] and shadow()
+ * - In 3D the snippet may also define void mainNormal(inout vec3 n), given the normal facing the camera after the
+ *   normal map, in world space, to bend it per pixel for waves or ripples; the lighting, specular, reflection and
+ *   fog then all use it, as they use a normal map
  * - In 3D the shadow map is drawn without the Shader, cut only by the texture's alpha, so a snippet that removes
  *   parts of a surface still shadows with the whole of it
  * @example

package/src/engineExport.js

@@ -15,6 +15,7 @@ export
     frame,
     time,
     timeReal,
+    averageFPS,
     paused,
     getPaused,
     setPaused,

package/src/engineInput.js

@@ -656,8 +656,9 @@ function inputInit()
     }
     function onContextMenu(e)
     {
-        // prevent right click menu, but a text field keeps its copy and paste menu
-        if (inputPreventDefault && !isTextInput(e.target))
+        // prevent right click menu, but a text field keeps its copy and paste menu and a link its open in new tab
+        const target = /** @type {HTMLElement} */ (e.target);
+        if (inputPreventDefault && !isTextInput(target) && !target?.closest?.('a[href]'))
             e.preventDefault();
     }
     function onBlur()
@@ -678,6 +679,10 @@ function inputInit()
         // handle all touch events the same way
         function handleTouch(e)
         {
+            // fix stalled audio requiring user interaction, with touch input off too since the page's sound needs it
+            if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
+                audioResume();
+
             if (!touchInputEnable)
             {
                 // turned off mid touch, the finger that drove the mouse lets go of it
@@ -688,10 +693,6 @@ function inputInit()
             }
             inputLastTouchTime = performance.now();
 
-            // fix stalled audio requiring user interaction
-            if (soundEnable && !headlessMode && audioContext && !audioIsRunning())
-                audioResume();
-
             // when the touch gamepad is enabled it owns touch input: suppress the
             // touch->mouse passthrough entirely unless touchGamepadPassthrough is set
             // (its own zones drive gameplay via pointer events)