littlejsengine 1.26.1 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.26.1",
+  "version": "1.27.0",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",

package/plugins/lightSystem.js

@@ -228,20 +228,34 @@ class LightSystemPlugin
                 'uniform vec4 color;'+
                 'uniform sampler2D shadowTexture;'+ // this light's shadow, white where its rays reach
                 'uniform bool useShadow;'+
+                'uniform vec2 forward;'+   // the light's up, the way its cone and gel look
+                'uniform vec2 cone;'+      // the cone's factor and its edge times it, (0, -1) for none
+                'uniform sampler2D gelTexture;'+
+                'uniform vec4 gelRect;'+   // the gel's tile in its texture, corner and size
+                'uniform bool useGel;'+
                 'in vec2 vWorldPos;'+
                 'in vec2 vUV;'+
                 'out vec4 c;'+
                 'void main(){'+
-                'float dist=distance(vWorldPos,lightPos);'+
+                'vec2 d=vWorldPos-lightPos;'+
+                'float dist=length(d);'+
                 'float t=clamp((radius-dist)/max(fadeRange,1e-6),0.,1.);'+
                 'c=vec4(color.rgb*t*color.a,1.);'+
                 'if(useShadow)c.rgb*=texture(shadowTexture,vUV).rgb;'+
+                // the cone: full where its fade starts, nothing at its edge, smooth between, as a 3D spotlight's
+                'float k=clamp(dot(forward,d/max(dist,1e-6))*cone.x-cone.y,0.,1.);'+
+                'c.rgb*=k*k*(3.-2.*k);'+
+                // the gel across the light's square, turned with it, its top the way the light looks
+                'if(useGel){'+
+                'vec2 g=clamp(vec2(dot(d,vec2(forward.y,-forward.x)),dot(d,forward))/(radius*2.)+.5,0.,1.);'+
+                'c.rgb*=texture(gelTexture,gelRect.xy+vec2(g.x,1.-g.y)*gelRect.zw).rgb;}'+
                 '}'
             );
             if (lightSystemShadersFailed(lightSystem.lightShader)) return;
-            // the shadow texture is on unit 1, the engine's tracked texture stays on unit 0
+            // the shadow texture is on unit 1 and the gel on 2, the engine's tracked texture stays on unit 0
             glContext.useProgram(lightSystem.lightShader);
             glContext.uniform1i(glUniformLocation(lightSystem.lightShader, 'shadowTexture'), 1);
+            glContext.uniform1i(glUniformLocation(lightSystem.lightShader, 'gelTexture'), 2);
 
             // composite shader: fullscreen quad, samples the lightmap
             lightSystem.compositeShader = glCreateProgram(
@@ -814,6 +828,19 @@ class LightSystemPlugin
                     [drawContext, glCustomShader] = saved;
                 }
             }
+            catch (error)
+            {
+                // a renderLight or renderEmissive threw: what it queued goes to the lightmap, then the screen is the
+                // target again with its viewport and blend, so a game that catches the error draws to the screen; a
+                // flush that throws too is let go of, the first error is the one that counts
+                try { glFlush(); } catch (e) {}
+                glContext.bindFramebuffer(glContext.FRAMEBUFFER, null);
+                glContext.viewport(0, 0, glCanvas.width, glCanvas.height);
+                glActiveTexture && glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
+                glSetInstancedMode(true);
+                setAdditiveBlendMode(prevAdditive);
+                throw error;
+            }
             finally
             {
                 glRenderTargetBase = undefined;
@@ -927,6 +954,18 @@ class LightSystemPlugin
         const c = light.color;
         glContext.uniform4f(glUniformLocation(ls, 'color'), c.r, c.g, c.b, c.a);
 
+        // the cone and the gel look along the light's up
+        const forward = light.getUp();
+        glContext.uniform2f(glUniformLocation(ls, 'forward'), forward.x, forward.y);
+        const [coneFactor, coneEdge] = lightSystemCone(light);
+        glContext.uniform2f(glUniformLocation(ls, 'cone'), coneFactor, coneEdge);
+        const gel = lightSystemGel(light);
+        glContext.uniform1i(glUniformLocation(ls, 'useGel'), gel ? 1 : 0);
+        glContext.activeTexture(glContext.TEXTURE2);
+        glContext.bindTexture(glContext.TEXTURE_2D, gel ? gel.texture : null);
+        glContext.activeTexture(glContext.TEXTURE0);
+        gel && glContext.uniform4fv(glUniformLocation(ls, 'gelRect'), gel.rect);
+
         glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, 4);
 
         // restore engine's instanced shader+VAO so subsequent renderLight()
@@ -1004,6 +1043,31 @@ class LightSystemPlugin
 
 ///////////////////////////////////////////////////////////////////////////////
 
+// a light's cone for its shader, the factor and its edge times it: the dot of its up and a direction times the factor,
+// less the edge, is 1 where the fade starts and 0 at the edge; (0, -1) for no cone, which leaves the light as it was
+function lightSystemCone(light)
+{
+    const angle = min(light.coneAngle, PI);
+    if (!(angle > 0)) return [0, -1];
+    const outer = cos(angle), inner = cos(angle * (1 - clamp(light.coneSoftness)));
+    const k = 1 / max(inner - outer, 1e-4);
+    return [k, outer * k];
+}
+
+// a light's gel for its shader, its texture and its tile's corner and size in it, a half texel in so the tiles beside
+// it do not bleed in; undefined for none or one not loaded yet
+function lightSystemGel(light)
+{
+    const gel = light.gel;
+    if (!gel) return;
+    const isTile = gel instanceof TileInfo, textureInfo = isTile ? gel.textureInfo : gel;
+    const texture = textureInfo?.glTexture, size = textureInfo?.size;
+    if (!texture || !(size?.x > 0)) return;
+    const pos = isTile ? gel.pos : vec2(), tileSize = isTile ? gel.size : size;
+    return {texture, rect: [(pos.x + .5) / size.x, (pos.y + .5) / size.y,
+        (tileSize.x - 1) / size.x, (tileSize.y - 1) / size.y]};
+}
+
 /**
  * A Light is an EngineObject that contributes a soft additive blob of color
  * to the LightSystem plugin's lightmap.
@@ -1012,11 +1076,16 @@ class LightSystemPlugin
  * - A light inside a caster is blocked entirely, so the object that holds it, its lamp, a torch, the player
  *   carrying it, needs a shadowCore that reaches past it, castShadow = false, or a renderShadow that leaves
  *   the light's spot out
+ * - A coneAngle makes it a cone along its up, turned by its angle, and a gel is a picture it shines through; both
+ *   are applied over the round light with its shadows, so they cost next to nothing
  * @extends EngineObject
  * @memberof LightSystem
  * @example
  * new Light(vec2(5, 5), 4, rgb(1, 0.5, 0));        // orange light, full soft blob
  * new Light(vec2(0, 0), 8, rgb(1, 1, 1), 2);       // white core with 2-unit soft halo
+ * const flashlight = new Light(vec2(), 10);        // a flashlight looking right, its beam 60 degrees across
+ * flashlight.coneAngle = PI/6;
+ * flashlight.angle = PI/2;
  */
 class Light extends EngineObject
 {
@@ -1049,6 +1118,19 @@ class Light extends EngineObject
         this.glowFalloff = 1;
         /** @type {TileInfo|undefined} */
         this.glowTileInfo = undefined; // the whole glow texture, kept for the falloff it was made for
+        /** @property {number} - Makes it a cone, like a flashlight or headlight: the angle in radians from its up out
+         *  to the edge of the cone, so the beam is twice this across; it looks along getUp(), turned by its angle and
+         *  by what it is attached to; 0 for a light that shines every way */
+        this.coneAngle = 0;
+        /** @property {number} - How much of the cone is its fading edge: 0 a hard edge, .2 by default, the outer
+         *  fifth, 1 fading all the way from the middle of the beam */
+        this.coneSoftness = .2;
+        /** @property {TileInfo|TextureInfo|undefined} - A gel, a picture the light shines through, called a cookie in
+         *  some engines: stretched across the light's square, twice its radius, its top the way the light looks,
+         *  turned with it, and multiplied into its color, so one light can be a car's headlights and tail lights;
+         *  a TileInfo's own tile, or a whole TextureInfo; shadows still fall through it
+         *  @type {TileInfo|TextureInfo|undefined} */
+        this.gel = undefined;
     }
 
     /** Lights are invisible in the main render pass — they only contribute

package/plugins/newgrounds.js

@@ -163,6 +163,8 @@ class NewgroundsPlugin
         /** @property {Array<Object>} - Scoreboards fetched from Newgrounds, empty until ready
          *  @type {Array<Object>} */
         this.scoreboards = [];
+        /** @type {Map<number, 'failed'|'notSave'>} */
+        this.loadFailures = new Map; // why each slot's last load gave undefined, see loadFailure
         /** @property {{id: number, name: string, url: string, supporter: boolean}|null} - The logged in player once ready, null when not logged in
          *  @type {{id: number, name: string, url: string, supporter: boolean}|null} */
         this.user = null;
@@ -332,6 +334,96 @@ class NewgroundsPlugin
         return this.call('ScoreBoard.getScores', parameters, session_id);
     }
 
+    /** Save a value to one of the player's cloud save slots, which needs a logged in player
+     *  - Any value JSON can hold; the slots are numbered from 1, as many as the app's Newgrounds settings give it
+     *  @param {number} slot - The slot number
+     *  @param {*} data - The value to save
+     *  @return {Promise<boolean>} - Whether it saved, false when not logged in
+     *  @example
+     *  newgrounds.cloudSave(1, {level, coins}); */
+    async cloudSave(slot, data)
+    {
+        ASSERT(isNumber(slot), 'Newgrounds cloudSave: slot must be a number', slot);
+        if (!this.session_id) return false;
+        let text;
+        try { text = JSON.stringify(data); } catch (error) {}
+        if (text === undefined)
+            return console.warn('Newgrounds cloudSave: slot ' + slot + ' was given a value JSON can not hold'), false;
+        const response = await this.call('CloudSave.setData', {'id':slot, 'data':text});
+        newgroundsSessionLost(response) && this.dropSession();
+        return !!response?.result?.data?.['success'];
+    }
+
+    /** Load the value a cloud save slot holds: null when Newgrounds says it holds none, undefined when it could not be
+     *  loaded or the player is not logged in, said in the console when logged in
+     *  - 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 newgrounds.cloudLoad(1); */
+    async cloudLoad(slot)
+    {
+        ASSERT(isNumber(slot), 'Newgrounds cloudLoad: slot must be a number', slot);
+        const {value, failure} = await this.loadSlot(slot);
+        failure ? this.loadFailures.set(+slot, failure) : this.loadFailures.delete(+slot);
+        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 when not logged in, 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(+slot); }
+
+    /** A slot's load, its value and why it failed, if it did
+     *  @param {number} slot
+     *  @return {Promise<{value: *, failure: 'failed'|'notSave'|undefined}>}
+     *  @ignore */
+    async loadSlot(slot)
+    {
+        const failed = (message)=>
+        {
+            message && console.warn('Newgrounds could not load slot ' + slot + message);
+            return {value: undefined, failure: /** @type {'failed'} */ ('failed')};
+        };
+        if (!this.session_id) return failed('');
+        const response = await this.call('CloudSave.loadSlot', {'id':slot});
+        newgroundsSessionLost(response) && this.dropSession();
+        const slotData = response?.result?.data?.['slot'];
+        if (!slotData) return failed('.');
+        const url = slotData['url']; // where the saved text is, none for an empty slot
+        if (!url) return {value: null, failure: undefined};
+        let text;
+        try
+        {
+            const signal = globalThis.AbortSignal?.timeout?.(newgroundsTimeoutMS);
+            const saved = await fetch(url, {'cache':'no-store', 'signal':signal});
+            if (!saved.ok) // an error page is not the save, even one that is JSON
+                return failed(': ' + saved.status);
+            text = await saved.text();
+        }
+        catch(e) { return failed(': ' + e); }
+        if (!text) return failed(', it came back empty'); // a save is never empty
+        try { return {value: JSON.parse(text), failure: undefined}; }
+        catch(e)
+        {
+            console.warn('Newgrounds cloudLoad: slot ' + slot + ' holds a file that is not a save');
+            return {value: undefined, failure: 'notSave'};
+        }
+    }
+
+    /** Count an event of the game's own on its Newgrounds stats page, like a level finished or a button pressed
+     *  @param {string} name - The event's name
+     *  @return {Promise<Object>} - The response JSON object, undefined when the call failed */
+    logEvent(name)
+    {
+        ASSERT(typeof name === 'string' && name !== '', 'Newgrounds logEvent: name must be a string', name);
+        return this.call('Event.logEvent', {'event_name':name, 'host':this.host});
+    }
+
     /** Encrypt text the way the Newgrounds gateway expects, AES-128 CBC with a random iv in front, as Base64
      *  @param {string} text
      *  @return {Promise<string>} */

package/plugins/parallax.js

@@ -39,7 +39,9 @@ class ParallaxLayer extends CanvasLayer
      *    and 1 with the screen, a Vector2 to follow x and y by different amounts
      *  @param {number} [renderOrder] - Low to draw behind the game, far layers lowest
      *  @param {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} [drawFunction] - Draws
-     *    the image, given the canvas context, its size in pixels and the layer; mountains when not given
+     *    the image, given the canvas context, its size in pixels and the layer; mountains when not given; called
+     *    once when the layer is made and on redraw(), not each frame, so it draws with the canvas 2D context, not
+     *    the engine's draws like drawTile
      *  @param {Vector2} [canvasSize] - Size of the image in pixels */
     constructor(pos=vec2(), size=vec2(32, 16), parallax=.5, renderOrder=-1e3, drawFunction=parallaxMountains(),
         canvasSize=vec2(512, 256))

package/plugins/render3dEditor.js

@@ -36,8 +36,9 @@ function editor3DCameraStart()
     camera.pos = from.pos.copy();
     camera.rotation = vec3(from.rotation.x, from.rotation.y, 0);
     camera.fov = from.fov;
-    camera.near = from.near;
     camera.far = from.far;
+    // an orthographic camera's near may sit behind it, which a perspective view can not use, so it keeps its own
+    from.orthographic || (camera.near = from.near);
 }
 
 // turn the free camera on or off, it needs a Render3DPlugin and takes the keyboard and mouse while it is on
@@ -92,6 +93,7 @@ function editor3DWithView(fn)
 // called by the 3D pass before it works out its matrices: the frame is drawn with the editor's camera
 function editor3DCameraBegin()
 {
+    editor3DCameraEnd(); // a frame that threw before its End gives the game its camera back first, not the editor's
     if (!editor3DViewOn() || !editor3DCamera) return;
     const r = render3D, camera = editor3DGameCamera = r.camera;
     r.camera = editor3DCamera;
@@ -424,8 +426,17 @@ function editor3DSize(object)
     const made = editor3DInstances.get(object.id), box = editor3DPrefabBox(made);
     if (box) return box.size;
     if (!(made instanceof EngineObject3D) || !(made.mesh || made.tileInfo)) return vec3(1);
-    const s = made.size3D, k = made.scale3D;
-    return vec3(s.x * abs(k.x), s.y * abs(k.y), s.z * abs(k.z));
+    const s = made.size3D, k = made.scale3D, size = vec3(s.x * abs(k.x), s.y * abs(k.y), s.z * abs(k.z));
+    if (!editor3DTurned(object)) return size;
+
+    // a turned one's box is the box around it turned, so it lands, drops and pastes by what it covers
+    const matrix = buildMatrix(vec3(), editor3DRotation(object).scale(PI / 180), size), high = vec3();
+    for (let i = 8; i--;)
+    {
+        const p = matrix.transformPoint(vec3(i & 1 ? .5 : -.5, i & 2 ? .5 : -.5, i & 4 ? .5 : -.5));
+        high.x = max(high.x, p.x), high.y = max(high.y, p.y), high.z = max(high.z, p.z);
+    }
+    return vec3(editor3DRound(high.x * 2), editor3DRound(high.y * 2), editor3DRound(high.z * 2));
 }
 
 // the box around a prefab's instance in the world, the boxes of its parts together, as its middle and its size;
@@ -1637,6 +1648,7 @@ function editor3DSetOpen(open)
     if (open)
     {
         editor3DSetFreeCamera(false);
+        pointerLockIsActive() && pointerLockExit(); // the game's captured mouse is let go, the editor needs it
         editor3DLevel || editor3DLevelLoaded({}); // a new level, with nothing loaded
         editor3DCamera || editor3DCameraStart();
         editor3DGamePaused = paused;
@@ -2334,10 +2346,11 @@ function editor3DDragTo(drag, mouse, ray, snap)
             }
             if (factor)
             {
+                // snapped and kept from nothing by its size, its sign kept, so a mirrored axis stays mirrored
                 const size = snap ? editor3DScaleStep : 0, least = size || .01;
+                const fit = (v)=> (v < 0 ? -1 : 1) * max(editor3DSnap(abs(v), size), least);
                 const scale = s.scale.multiply(factor);
-                editor3DSetTransform(object, undefined, undefined, vec3(max(editor3DSnap(scale.x, size), least),
-                    max(editor3DSnap(scale.y, size), least), max(editor3DSnap(scale.z, size), least)));
+                editor3DSetTransform(object, undefined, undefined, vec3(fit(scale.x), fit(scale.y), fit(scale.z)));
             }
         }
     });
@@ -2858,8 +2871,9 @@ function editor3DDrawLabels()
     const drag = editor3DDrag;
     if (drag?.kind === 'box')
     {
+        // on the main canvas, over the WebGL one, so a 3D pass drawn after the 2D scene does not cover it
         const {from: a, to: b} = drag, corners = [a, vec2(b.x, a.y), b, vec2(a.x, b.y)];
-        corners.forEach((c, i)=> drawLine(c, corners[(i + 1) % 4], 2, EDITOR3D_SELECT_COLOR, undefined, 0, glEnable, true));
+        corners.forEach((c, i)=> drawLine(c, corners[(i + 1) % 4], 2, EDITOR3D_SELECT_COLOR, undefined, 0, false, true));
     }
 }
 

package/plugins/render3dExtras.js

@@ -1307,6 +1307,7 @@ class ParticleEmitter3D extends EngineObject3D
         const out = this.particleData;
         out[k] = view.pos.x, out[k+1] = view.pos.y, out[k+2] = view.pos.z;
         out[k+3] = view.velocity.x, out[k+4] = view.velocity.y, out[k+5] = view.velocity.z;
+        out[k+16] = view.lifeTime, out[k+17] = view.age;
         if (view.destroyed)
             out[k+17] = max(out[k+17], out[k+16]); // its life lived: a step short of it can round to just under
         return result;

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