littlejsengine 1.25.0 → 1.26.0

package/plugins/medalSystem.js

@@ -4,8 +4,8 @@
  * - Medal class with name, description, icon, and unlock tracking
  * - Automatic saving to local storage, unless a service like Newgrounds holds the medal (see Medal.isLocal)
  * - Visual display queue with slide-in notifications
- * - The Newgrounds plugin extends it with NewgroundsMedal, held on the server while logged in
- * - Setting debugMedals = true in the game code before medalsInit skips the load and the save, and in the debug build logs the Newgrounds traffic; it is not exported, so only a script tag build can set it
+ * - The Newgrounds plugin extends it with NewgroundsMedal, held on the server while logged in, and the Wavedash plugin with WavedashMedal, saved here and sent to Wavedash
+ * - Setting debugMedals = true in the game code before medalsInit skips the load and the save, sends nothing to Wavedash, and in the debug build logs the Newgrounds traffic; it is not exported, so only a script tag build can set it
  * @namespace Medals
  */
 
@@ -54,13 +54,25 @@ let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimeLast, medalsRender
  *  - Call this after creating all medals
  *  - Loads which medals are unlocked from the save, and writes the catalog back
  *  - A medal a service like Newgrounds holds is left as it is, see Medal.isLocal
+ *  - A medal unlocked before the first call stays unlocked and is saved by it
  *  @param {string} saveName - The localStorage key the medals are kept under, a different one from the game's own
  *  readSaveData and writeSaveData, or each would overwrite the other
  *  @memberof Medals */
 function medalsInit(saveName)
 {
+    // unlocks from before the first call, which had nowhere to be saved, are kept: medals favour the player; a call
+    // after that, another player's save, starts from its own
+    const early = [];
+    medalsSaveName || medalsForEach((medal)=> medal.unlocked && medal.isLocal() && early.push(medal));
     medalsSaveName = saveName;
     medalsLoad();
+    if (early.length)
+    {
+        early.forEach((medal)=> medal.unlocked = true);
+        medalsSave();
+    }
+    // the saved unlocks of Wavedash medals go to Wavedash, when that plugin is in the build and started
+    typeof wavedash != 'undefined' && wavedash?.sendAchievements();
 
     // add the medal display once, however often this is called
     if (!medalsRenderAdded)
@@ -130,10 +142,11 @@ function medalsReset()
     medalsForEach(medal=> medal.isLocal() && (medal.unlocked = false));
     if (medalsSaveName && !debugMedals)
     {
-        // the saved unlocks of medals not made yet are cleared too, they are read when those medals are made
+        // the saved unlocks of the local medals and of medals not made yet are cleared too, since a save keeps an
+        // unlock another tab wrote, and those not made yet read theirs when they are made
         const saved = readSaveData(medalsSaveName);
         for (const id in saved)
-            if (!medals[id] && saved[id] && typeof saved[id] === 'object')
+            if ((!medals[id] || medals[id].isLocal()) && saved[id] && typeof saved[id] === 'object')
                 saved[id].unlocked = false;
         writeSaveData(medalsSaveName, saved);
     }
@@ -159,7 +172,7 @@ function medalsSave()
             name: medal.name,
             description: medal.description,
             icon: medal.icon,
-            unlocked: medal.unlocked,
+            unlocked: medal.unlocked || !!saved[medal.id]?.unlocked, // another tab may have unlocked it since
         };
         if (medal.image) entry.src = medal.image.src;
         data[medal.id] = entry;
@@ -229,8 +242,7 @@ class Medal
     {
         if (!medalsPreventUnlock && !this.unlocked)
         {
-            ASSERT(medalsSaveName, 'save name must be set');
-            this.unlocked = true;
+            this.unlocked = true; // saved now, or by medalsInit when it comes
             medalsSave();
             medalsDisplayQueue.push(this);
         }

package/plugins/newgrounds.js

@@ -157,9 +157,11 @@ class NewgroundsPlugin
         const hasLocation = typeof location != 'undefined';
         /** @property {string} - Hostname sent with the view the plugin logs when it starts */
         this.host = hasLocation ? location.hostname : '';
-        /** @property {Array} - Medals fetched from Newgrounds, empty until ready, with the unlocks only when logged in */
+        /** @property {Array<Object>} - Medals fetched from Newgrounds, empty until ready, with the unlocks only when logged in
+         *  @type {Array<Object>} */
         this.medals = [];
-        /** @property {Array} - Scoreboards fetched from Newgrounds, empty until ready */
+        /** @property {Array<Object>} - Scoreboards fetched from Newgrounds, empty until ready
+         *  @type {Array<Object>} */
         this.scoreboards = [];
         /** @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} */

package/plugins/parallax.js

@@ -47,6 +47,7 @@ class ParallaxLayer extends CanvasLayer
         ASSERT(isNumber(parallax) || isVector2(parallax), 'parallax must be a number or a Vector2');
         ASSERT(typeof drawFunction == 'function', 'drawFunction must be a function');
         super(pos, size, 0, renderOrder, canvasSize);
+        this.castShadow = false; // a backdrop, it would throw huge shadows in the light system, a sun's above all
 
         /** @property {Vector2} - How much of the camera's movement it follows on each axis, 0 stays with the world
          *  and 1 with the screen */

package/plugins/particleEffects.js

@@ -85,9 +85,9 @@ particleEffectAddSetting('randomColorLinear', 'checkbox', true, 0, 0, 0,
 
 particleEffectSettingGroup = 'Motion';
 particleEffectAddSetting('speed', 'number', .1, 0, .5, .005,
-    'Start speed, world units per frame', 0, 1e9);
+    'Start speed, world units per frame', -1e9, 1e9); // negative goes back against the cone, as the emitter takes it
 particleEffectAddSetting('angleSpeed', 'number', .05, 0, .5, .005,
-    'Spin speed, radians per frame', 0, 1e9);
+    'Spin speed, radians per frame', -1e9, 1e9);
 particleEffectAddSetting('damping', 'number', 1, .8, 1, .001,
     'Speed kept each frame, 1 keeps it all', 0, 1);
 particleEffectAddSetting('angleDamping', 'number', 1, .8, 1, .001,
@@ -107,7 +107,7 @@ particleEffectAddSetting('collideLevel', 'checkbox', false, 0, 0, 0,
 particleEffectAddSetting('restitution', 'number', 0, 0, 1, .01,
     'Bounce when hitting tiles');
 particleEffectAddSetting('friction', 'number', .8, 0, 1, .01,
-    'Speed kept sliding along tiles');
+    'Speed kept sliding along tiles, the larger of this and the friction of the layer, as for an object');
 
 particleEffectSettingGroup = 'Texture';
 particleEffectAddSetting('shape', 'shape', 'soft', 0, 0, 0,
@@ -160,7 +160,8 @@ function particleEffectSanitize(raw)
 {
     // one line of text, line breaks and control characters made spaces
     const text = typeof raw?.name === 'string' ? raw.name.replace(/[\x00-\x1f\x7f]+/g, ' ').trim() : '';
-    const name = text ? text.slice(0, 60).trim() : 'Effect'; // no space left where it was cut
+    // whole characters, and no space left where it was cut
+    const name = text ? textGraphemes(text).slice(0, 60).join('').trim() : 'Effect';
     const input = raw?.settings && typeof raw.settings === 'object' ? {...raw.settings} : {};
     // a library saved before shapes names its tile and no shape, it keeps its tile
     if (input.shape === undefined && isNumber(input.tileIndex))
@@ -414,7 +415,7 @@ function particleEffectShapeTile(name)
  *  @param {string} name
  *  @param {function(Particle, number): void} update - Pushes a 2D particle, given the strength
  *  @param {function(Particle3D, number): void} [update3D] - The same for a 3D particle, none leaves 3D alone
- *  @param {number} [min] - Strength range the designer offers
+ *  @param {number} [min] - Strength range the designer offers, and the range a strength is clamped to
  *  @param {number} [max]
  *  @param {number} [value] - Strength when first added
  *  @param {string} [description]
@@ -478,17 +479,45 @@ function particleEffectSet(emitter, effect)
     emitter.particleUpdateCallback = particleEffectUpdateCallback(effect.behaviors);
 }
 
+// the options a play takes besides the settings
+const PARTICLE_EFFECT_OPTIONS = ['hue', 'saturation', 'scale', 'angle', 'tileInfo', 'flatten'];
+
+// whether an option is a value its setting takes, as particleEffectSanitize keeps one
+function particleEffectOptionValid(setting, value)
+{
+    return setting.kind === 'checkbox' ? typeof value === 'boolean' || value === 0 || value === 1 :
+        setting.kind === 'color' ? !!particleEffectColor(value) :
+        setting.kind === 'shape' ? value === '' || particleEffectShapes.includes(value) : isNumber(value);
+}
+
 // an effect from a name or an effect, recolored by the options
 function particleEffectResolve(nameOrEffect, options)
 {
     const found = typeof nameOrEffect == 'string' ? particleEffectsGet(nameOrEffect) : nameOrEffect;
     ASSERT(!!found, 'no particle effect named ' + nameOrEffect);
     if (!found) return;
-    // any setting in the options replaces the effect's own for this play, emitTime for a burst or a loop
+    // a vec2 emitSize is a rectangle, as ParticleEmitter takes one, unless emitRect is false, which makes a circle as
+    // wide as its x
+    if (isVector2(options.emitSize))
+        options = {...options, emitSize: options.emitSize.x, emitHeight: options.emitSize.y,
+            emitRect: options.emitRect ?? true};
+    if (debug)
+        for (const key in options)
+            ASSERT(PARTICLE_EFFECT_OPTIONS.includes(key) || particleEffectSettings.some((setting)=> setting.name === key),
+                'particleEffect: no option named ' + key);
+    // any setting in the options replaces the effect's own for this play, emitTime for a burst or a loop; one that is
+    // not a value of its kind keeps the effect's own, where the sanitizing would put the library's default
     const settings = {...found.settings};
     for (const setting of particleEffectSettings)
-        if (options[setting.name] !== undefined)
-            settings[setting.name] = options[setting.name];
+    {
+        const value = options[setting.name];
+        if (value === undefined) continue;
+        const valid = particleEffectOptionValid(setting, value);
+        ASSERT(valid, `particleEffect: ${setting.name} must be a ${setting.kind === 'checkbox' ? 'boolean' : setting.kind}`,
+            value);
+        if (valid)
+            settings[setting.name] = value;
+    }
     // sanitized each time, an effect may be written by hand or changed after it was added
     const effect = particleEffectSanitize({...found, settings}), {hue=0, saturation=1} = options;
     return hue || saturation != 1 ? particleEffectRecolor(effect, hue, saturation) : effect;
@@ -513,6 +542,7 @@ function particleEffectResolve(nameOrEffect, options)
  *  @memberof ParticleEffects */
 function particleEffect(nameOrEffect, pos=vec2(), options={})
 {
+    options ||= {}; // null is no options too
     const effect = particleEffectResolve(nameOrEffect, options);
     if (!effect) return;
     const emitter = new ParticleEmitter(pos.copy());
@@ -527,8 +557,9 @@ function particleEffect(nameOrEffect, pos=vec2(), options={})
 }
 
 /** An effect with a 2D emitter's settings, to save, build again, or build in 3D with particleEffect3D; its tile is
- *  left out, since a hand made emitter's tile is its own texture and not one an effect can name, and so is its
- *  scale, which an effect does not keep: pass it again with options.scale
+ *  left out, since a hand made emitter's tile is its own texture and not one an effect can name, and so are its
+ *  scale, which an effect does not keep: pass it again with options.scale, and its renderOrder, which an effect takes
+ *  from additive; a finished emitter's emit time is the time it emitted for
  *  @param {ParticleEmitter} emitter
  *  @param {string} [name]
  *  @return {Object}
@@ -539,6 +570,8 @@ function particleEffectFromEmitter(emitter, name='Effect')
     for (const setting of particleEffectSettings)
         if (!particleEffectIndirect.includes(setting.name) && emitter[setting.name] !== undefined)
             settings[setting.name] = emitter[setting.name]; // a Color is taken as its channels by the sanitizer
+    if (emitter.emitTime < 0) // destroyed, its last particles going: as long as it emitted, not 0, for ever
+        settings.emitTime = emitter.emitElapsed;
     settings.emitRect = !emitter.emitCircle;
     settings.emitSize = emitter.emitSize.x;
     settings.emitHeight = emitter.emitSize.y;
@@ -629,6 +662,7 @@ function particleEffectSet3D(emitter, effect)
  *  @memberof ParticleEffects */
 function particleEffect3D(nameOrEffect, pos3D=vec3(), options={})
 {
+    options ||= {}; // null is no options too
     const effect = particleEffectResolve(nameOrEffect, options);
     if (!effect) return;
     const e = new ParticleEmitter3D(pos3D.copy());

package/plugins/pathFinder.js

@@ -64,10 +64,10 @@ class PathFinderNode
         this.isOpen = this.isClosed = false;
     }
 
-    /** Reset per-search state and walkability (called by buildNodeData). */
+    /** Reset per-search state and walkability (called by buildNodeData) */
     reset() { this.walkable = false; this.cost = 0; this.resetSearch(); }
 
-    /** True if walkable and not blocked by cost.
+    /** True if walkable and not blocked by cost
      *  @return {boolean} */
     isClear()
     {
@@ -77,7 +77,7 @@ class PathFinderNode
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** Grid pathfinder using A* with two optional smoothing passes.
+/** Grid pathfinder using A* with two optional smoothing passes
  *  @memberof PathFinding
  *  @example
  *  // Tile-layer driven (most common):
@@ -177,7 +177,7 @@ class PathFinder
         return 0;
     }
 
-    /** Get the node at tile coords, or null if out of bounds.
+    /** Get the node at tile coords, or null if out of bounds
      *  @param {number} x
      *  @param {number} y
      *  @return {PathFinderNode|null} */
@@ -187,7 +187,7 @@ class PathFinder
         return this.nodes[x + y * this.size.x];
     }
 
-    /** Convert a world-space position to integer tile coords (no clamping).
+    /** Convert a world-space position to integer tile coords (no clamping)
      *  @param {Vector2} worldPos
      *  @return {Vector2} */
     worldToTile(worldPos)
@@ -197,7 +197,7 @@ class PathFinder
         return vec2(floor(worldPos.x - ox), floor(worldPos.y - oy));
     }
 
-    /** Convert integer tile coords to the world-space center of that tile.
+    /** Convert integer tile coords to the world-space center of that tile
      *  @param {number} x
      *  @param {number} y
      *  @return {Vector2} */
@@ -822,13 +822,11 @@ function pathFinderNearestNode(finder, worldPos, searchRange, test)
         const bound = max(0, offset - .5);
         if (nearest && bound * bound >= nearestDistSq) break;
 
+        // only the ring itself, the inside was searched already: its top and bottom rows whole, its two ends between,
+        // in the same row by row order a full walk of the square visits them in, so ties pick the same node
         for (let dy = -offset; dy <= offset; ++dy)
-        for (let dx = -offset; dx <= offset; ++dx)
+        for (let dx = -offset, step = abs(dy) === offset ? 1 : 2*offset; dx <= offset; dx += step)
         {
-            // only the ring itself, the inside was searched already
-            if (offset > 0 && abs(dx) !== offset && abs(dy) !== offset)
-                continue;
-
             const node = finder.getNode(centerX + dx, centerY + dy);
             if (!node || !test(node)) continue;
 

package/plugins/pluginExport.js

@@ -24,6 +24,11 @@ export
     NewgroundsPlugin,
     NewgroundsMedal,
 
+    // Wavedash
+    wavedash,
+    WavedashPlugin,
+    WavedashMedal,
+
     // Post Process
     postProcess,
     PostProcessPlugin,
@@ -45,6 +50,7 @@ export
     lightSystem,
     LightSystemPlugin,
     Light,
+    DirectionalLight,
 
     // Audio Effects
     AudioEffect,
@@ -151,6 +157,9 @@ export
     // Render3D
     render3D,
     Render3DPlugin,
+    CubeMap,
+    makeCubeMap,
+    loadCubeMap,
     Camera3D,
     EngineObject3D,
     Mesh,

package/plugins/postProcess.js

@@ -310,11 +310,13 @@ function postProcessFragmentSource(shaderCode, values={})
         'return iDepthRange.z>0.?(d*(f-n)+f+n)/2.:f>0.?2.*n*f/(f+n-d*(f-n)):2.*n/max(1.-d,1e-7);}'+
         // whether there is depth to read: a range of all 0 is none, an orthographic near plane may be behind
         '\n#define LJS_HAS_DEPTH (iDepthRange != vec3(0))\n'+ // a define needs a line of its own
-        '\n' + shaderCode + '\n'+        // insert custom shader code
+        // main first, the code's mainImage declared for it, so a define in the code can not reach main
+        'void mainImage(out vec4,vec2);'+
         'void main(){'+                  // shader entry point
         'mainImage(c,gl_FragCoord.xy);'+ // call post process function
         'c.a=1.;'+                       // always use full alpha
-        '}';                             // end of shader
+        '}'+                             // end of shader
+        '\n' + shaderCode + '\n';        // insert custom shader code
 }
 
 /**