littlejsengine 1.18.12 → 1.18.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.18.12",
+  "version": "1.18.17",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -40,6 +40,9 @@
     "build": "node src/engineBuild.mjs",
     "test": "node --test --import ./test/setup.mjs \"test/**/*.test.mjs\""
   },
+  "engines": {
+    "node": ">=18"
+  },
   "devDependencies": {
     "bestzip": "^2.2.1",
     "electron": "^38.2.0",

package/plugins/box2d.js

@@ -83,6 +83,11 @@ class Box2dObject extends EngineObject
         // destroy physics body, fixtures, and joints
         ASSERT(this.body, 'Box2dObject has no body to destroy');
         box2d.world.DestroyBody(this.body);
+
+        // remove from tracked list so paused / headless sessions don't leak
+        const i = box2d.objects.indexOf(this);
+        if (i >= 0)
+            box2d.objects.splice(i, 1);
         super.destroy();
     }
 
@@ -171,7 +176,9 @@ class Box2dObject extends EngineObject
     /** Add a box shape to the body
      *  @param {Vector2} [size]
      *  @param {Vector2} [offset]
-     *  @param {number}  [angle]
+     *  @param {number}  [angle] - LittleJS convention (clockwise positive).
+     *      Negated internally to match Box2D's CCW-positive convention so the
+     *      fixture aligns with the same angle passed to drawRect/drawTile.
      *  @param {number}  [density]
      *  @param {number}  [friction]
      *  @param {number}  [restitution]
@@ -184,7 +191,7 @@ class Box2dObject extends EngineObject
         ASSERT(isNumber(angle), 'angle must be a number');
 
         const shape = new box2d.instance.b2PolygonShape();
-        shape.SetAsBox(size.x/2, size.y/2, box2d.vec2dTo(offset), angle);
+        shape.SetAsBox(size.x/2, size.y/2, box2d.vec2dTo(offset), -angle);
         return this.addShape(shape, density, friction, restitution, isSensor);
     }
 
@@ -200,23 +207,19 @@ class Box2dObject extends EngineObject
 
         function box2dCreatePolygonShape(points)
         {
-            function box2dCreatePointList(points)
+            ASSERT(3 <= points.length && points.length <= 8);
+            const buffer = box2d.instance._malloc(points.length * 8);
+            for (let i=0, offset=0; i<points.length; ++i)
             {
-                const buffer = box2d.instance._malloc(points.length * 8);
-                for (let i=0, offset=0; i<points.length; ++i)
-                {
-                    box2d.instance.HEAPF32[buffer + offset >> 2] = points[i].x;
-                    offset += 4;
-                    box2d.instance.HEAPF32[buffer + offset >> 2] = points[i].y;
-                    offset += 4;
-                }
-                return box2d.instance.wrapPointer(buffer, box2d.instance.b2Vec2);
+                box2d.instance.HEAPF32[buffer + offset >> 2] = points[i].x;
+                offset += 4;
+                box2d.instance.HEAPF32[buffer + offset >> 2] = points[i].y;
+                offset += 4;
             }
-
-            ASSERT(3 <= points.length && points.length <= 8);
+            const box2dPoints = box2d.instance.wrapPointer(buffer, box2d.instance.b2Vec2);
             const shape = new box2d.instance.b2PolygonShape();
-            const box2dPoints = box2dCreatePointList(points);
             shape.Set(box2dPoints, points.length);
+            box2d.instance._free(buffer);
             return shape;
         }
 
@@ -486,9 +489,10 @@ class Box2dObject extends EngineObject
     {
         const data = new box2d.instance.b2MassData();
         this.body.GetMassData(data);
-        localCenter && data.set_center(box2d.vec2dTo(localCenter));
-        mass && data.set_mass(mass);
-        momentOfInertia && data.set_I(momentOfInertia);
+        // use !== undefined so setMass(0) (static-equivalent) isn't silently ignored
+        if (localCenter !== undefined) data.set_center(box2d.vec2dTo(localCenter));
+        if (mass !== undefined) data.set_mass(mass);
+        if (momentOfInertia !== undefined) data.set_I(momentOfInertia);
         this.body.SetMassData(data);
     }
 
@@ -1660,6 +1664,8 @@ class Box2dPlugin
             const fixtureB = contact.GetFixtureB();
             const objectA  = fixtureA.GetBody().object;
             const objectB  = fixtureB.GetBody().object;
+            // raw user-created b2Bodies may have no .object — skip those
+            if (!objectA || !objectB) return;
             objectA.beginContact(objectB);
             objectB.beginContact(objectA);
         }
@@ -1670,6 +1676,7 @@ class Box2dPlugin
             const fixtureB = contact.GetFixtureB();
             const objectA  = fixtureA.GetBody().object;
             const objectB  = fixtureB.GetBody().object;
+            if (!objectA || !objectB) return;
             objectA.endContact(objectB);
             objectB.endContact(objectA);
         };
@@ -2048,7 +2055,7 @@ async function box2dInit()
         debugDraw.DrawTransform = function(transform)
         {
             transform = box2d.instance.wrapPointer(transform, box2d.instance.b2Transform);
-            const pos = vec2(transform.get_p());
+            const pos = box2d.vec2From(transform.get_p());
             const angle = -transform.get_q().GetAngle();
             const p1 = vec2(1,0), c1 = rgb(.75,0,0,.8);
             const p2 = vec2(0,1), c2 = rgb(0,.75,0,.8);

package/plugins/drawUtilities.js

@@ -129,4 +129,67 @@ function drawThreeSlice(pos, size, startTile, color, borderSize=1, additiveColor
         const cornerPos = cornerOffset.multiply(vec2(flipX?-1:1, flipY?-flip:flip));
         drawTile(pos.add(cornerPos.rotate(rotateAngle)), cornerSize, cornerTile, color, a, false, additiveColor, useWebGL, screenSpace, context);
     }
+}
+
+/** Draw a crescent / moon-phase shape built from a polygon
+ *  Routes through drawPoly, so it supports WebGL, screen space, color, and outlines
+ *  @param {Vector2} pos - Center position
+ *  @param {number}  [size] - Diameter
+ *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
+ *  @param {Color}   [color] - Fill color
+ *  @param {number}  [angle] - Angle to rotate by
+ *  @param {boolean} [invert] - Flip which side is illuminated
+ *  @param {number}  [lineWidth] - Outline width, 0 for no outline
+ *  @param {Color}   [lineColor] - Outline color
+ *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
+ *  @param {boolean} [screenSpace] - Use screen space coordinates
+ *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
+ *  @memberof DrawUtilities */
+function drawCrescent(pos, size=1, percent=0, color=WHITE, angle=0, invert=false, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
+{
+    const points = getCrescentPoints(pos, size, percent, angle, invert);
+    drawPoly(points, color, lineWidth, lineColor, vec2(), 0, useWebGL, screenSpace, context);
+}
+
+/** Get the list of points that make up a crescent / moon-phase shape
+ *  Returns world-space points with pos and angle baked in, ready for drawPoly or other use
+ *  @param {Vector2} pos - Center position
+ *  @param {number}  [size] - Diameter
+ *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
+ *  @param {number}  [angle] - Angle to rotate by
+ *  @param {boolean} [invert] - Flip which side is illuminated
+ *  @param {number}  [sides=glCircleSides] - Number of sides for a full circle (halved per arc)
+ *  @return {Array<Vector2>} - List of points making up the crescent
+ *  @memberof DrawUtilities */
+function getCrescentPoints(pos, size=1, percent=0, angle=0, invert=false, sides=glCircleSides)
+{
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isNumber(size) && isNumber(percent), 'size and percent must be numbers');
+
+    // map phase to a signed terminator curve: -1 new, 0 half, 1 full
+    let p = mod(percent*4, 4); // quarter phase 0..4
+    if (p >= 2)                // second half of cycle flips orientation
+        angle += PI;
+    p = p <= 2 ? p-1 : 3-p;
+    if (invert)                // flip the illuminated side
+    {
+        p = -p;
+        angle += PI;
+    }
+
+    // build the crescent: outer semicircle, then inner half-ellipse traced back
+    const points = [];
+    const segs = max(3, sides>>1);
+    const radius = size/2;
+    for (let i=0; i<=segs; i++)
+    {
+        const t = i/segs*PI;
+        points.push(vec2(radius*cos(t), radius*sin(t)).rotate(angle).add(pos));
+    }
+    for (let i=segs; i>=0; i--)
+    {
+        const t = i/segs*PI;
+        points.push(vec2(radius*cos(t), -radius*p*sin(t)).rotate(angle).add(pos));
+    }
+    return points;
 }

package/plugins/lightSystem.js

@@ -0,0 +1,330 @@
+/**
+ * LittleJS Light System Plugin
+ * - Adds 2D dynamic lighting to the scene
+ * - Lights are first-class EngineObjects (the Light class)
+ * - Each Light draws a soft falloff blob of its color into a shared lightmap
+ * - Lights accumulate ADDITIVELY in the lightmap (red + blue = magenta)
+ * - The lightmap is then MULTIPLIED with the scene during composite, so unlit
+ *   areas go to the ambient color and lit areas show the scene tinted by the
+ *   accumulated light color
+ * - Draw the world at full brightness — the lightmap does the darkening
+ * - Any EngineObject may override renderLight() to additively contribute to the
+ *   lightmap (e.g. emissive lava tiles, weapon flashes, glowing crystals)
+ * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
+ * @namespace LightSystem
+ */
+
+'use strict';
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Global Light System plugin object
+ *  @type {LightSystemPlugin}
+ *  @memberof LightSystem */
+let lightSystem;
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * LightSystemPlugin
+ * - Owns the offscreen lightmap texture, falloff/composite shaders, and the
+ *   per-frame render pass that multiplies the lightmap onto the WebGL scene
+ * - The composite is MULTIPLICATIVE: unlit areas get the ambient color, lit
+ *   areas show the scene tinted by the accumulated light color. So you should
+ *   draw your world at full brightness — the lightmap handles the darkening.
+ * @memberof LightSystem
+ */
+class LightSystemPlugin
+{
+    /** Create the global light system plugin.
+     *  @param {Vector2} [textureSize]  - Size of the lightmap texture (defaults to mainCanvasSize)
+     *  @param {Color}   [ambientColor] - Color applied to unlit areas of the scene (defaults to BLACK = pitch dark). Set a small RGB like rgb(0.1,0.1,0.15) for a faint "moonlight" baseline so unlit areas aren't fully black.
+     *  @example
+     *  // simplest usage
+     *  new LightSystemPlugin();
+     */
+    constructor(textureSize, ambientColor)
+    {
+        ASSERT(!lightSystem, 'LightSystemPlugin already initialized');
+        ASSERT(!postProcess, 'LightSystemPlugin must be created before PostProcessPlugin');
+        lightSystem = this;
+
+        /** @property {boolean} - When false, the render pass is skipped entirely */
+        this.enabled = true;
+        /** @property {Color} - Baseline color applied to unlit areas of the scene. Defaults to BLACK (pitch dark). Set to a small RGB for a faint ambient. The lightmap is cleared to this color each frame, then lights add on top, then the result multiplies the scene. */
+        this.ambientColor = (ambientColor || BLACK).copy();
+        /** @property {Vector2} - Size of the lightmap texture (set at construction; falls back to mainCanvasSize at init time) */
+        this.textureSize = textureSize ? textureSize.copy() : undefined;
+
+        /** @property {WebGLTexture} - The lightmap texture */
+        this.texture = undefined;
+        /** @property {WebGLProgram} - Shader for drawing per-Light falloff blobs into the lightmap */
+        this.lightShader = undefined;
+        /** @property {WebGLProgram} - Shader for compositing the lightmap over the main scene */
+        this.compositeShader = undefined;
+        /** @property {WebGLVertexArrayObject} - Vertex array object for the light shader */
+        this.lightVAO = undefined;
+        /** @property {WebGLVertexArrayObject} - Vertex array object for the composite shader */
+        this.compositeVAO = undefined;
+
+        initLightSystem();
+        engineAddPlugin(undefined, lightSystemRender,
+            lightSystemContextLost, lightSystemContextRestored);
+
+        function initLightSystem()
+        {
+            if (headlessMode) return;
+            if (!glEnable)
+            {
+                console.warn('LightSystemPlugin: WebGL not enabled!');
+                return;
+            }
+
+            // resolve texture size default at init time (mainCanvasSize may
+            // not be set yet at the moment the constructor first ran)
+            if (!lightSystem.textureSize)
+                lightSystem.textureSize = mainCanvasSize.copy();
+
+            // allocate the lightmap texture with null data at textureSize
+            lightSystem.texture = glContext.createTexture();
+            glContext.bindTexture(glContext.TEXTURE_2D, lightSystem.texture);
+            glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA,
+                lightSystem.textureSize.x, lightSystem.textureSize.y, 0,
+                glContext.RGBA, glContext.UNSIGNED_BYTE, null);
+            glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MAG_FILTER, glContext.LINEAR);
+            glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MIN_FILTER, glContext.LINEAR);
+            glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_S, glContext.CLAMP_TO_EDGE);
+            glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_T, glContext.CLAMP_TO_EDGE);
+
+            // light falloff shader: one quad per Light, fragment computes radial falloff
+            lightSystem.lightShader = glCreateProgram(
+                '#version 300 es\n' +
+                'precision highp float;'+
+                'uniform mat4 m;'+
+                'uniform vec2 lightPos;'+
+                'uniform float radius;'+
+                'in vec2 g;'+              // unit quad geometry [0..1]
+                'out vec2 vWorldPos;'+
+                'void main(){'+
+                'vec2 worldP=lightPos+(g-.5)*2.*radius;'+
+                'gl_Position=m*vec4(worldP,1,1);'+
+                'vWorldPos=worldP;'+
+                '}'
+                ,
+                '#version 300 es\n' +
+                'precision highp float;'+
+                'uniform vec2 lightPos;'+
+                'uniform float radius;'+
+                'uniform float fadeRange;'+
+                'uniform vec4 color;'+
+                'in vec2 vWorldPos;'+
+                'out vec4 c;'+
+                'void main(){'+
+                'float dist=distance(vWorldPos,lightPos);'+
+                'float t=clamp((radius-dist)/max(fadeRange,1e-6),0.,1.);'+
+                'c=vec4(color.rgb*t*color.a,1.);'+
+                '}'
+            );
+
+            // composite shader: fullscreen quad, samples the lightmap
+            lightSystem.compositeShader = glCreateProgram(
+                '#version 300 es\n' +
+                'precision highp float;'+
+                'in vec2 p;'+
+                'void main(){'+
+                'gl_Position=vec4(p+p-1.,1,1);'+
+                '}'
+                ,
+                '#version 300 es\n' +
+                'precision highp float;'+
+                'uniform sampler2D s;'+
+                'uniform vec3 iResolution;'+
+                'out vec4 c;'+
+                'void main(){'+
+                'vec2 uv=gl_FragCoord.xy/iResolution.xy;'+
+                'c=vec4(texture(s,uv).rgb,1.);'+
+                '}'
+            );
+
+            // VAO for the per-Light quad — reuses the engine unit triangle-strip
+            lightSystem.lightVAO = glContext.createVertexArray();
+            glContext.bindVertexArray(lightSystem.lightVAO);
+            glContext.bindBuffer(glContext.ARRAY_BUFFER, glGeometryBuffer);
+            const gLight = glContext.getAttribLocation(lightSystem.lightShader, 'g');
+            glContext.enableVertexAttribArray(gLight);
+            glContext.vertexAttribPointer(gLight, 2, glContext.FLOAT, false, 8, 0);
+
+            // VAO for the composite fullscreen quad — same buffer, attribute named 'p'
+            lightSystem.compositeVAO = glContext.createVertexArray();
+            glContext.bindVertexArray(lightSystem.compositeVAO);
+            glContext.bindBuffer(glContext.ARRAY_BUFFER, glGeometryBuffer);
+            const pComp = glContext.getAttribLocation(lightSystem.compositeShader, 'p');
+            glContext.enableVertexAttribArray(pComp);
+            glContext.vertexAttribPointer(pComp, 2, glContext.FLOAT, false, 8, 0);
+        }
+        function lightSystemRender()
+        {
+            if (headlessMode || !glEnable) return;
+            if (!lightSystem.enabled) return;
+            if (!lightSystem.texture) return;     // init failed or context lost
+
+            // 1. flush any in-flight sprite batch from earlier render passes
+            glFlush();
+            const prevAdditive = glAdditive;
+
+            // 2. bind lightmap as render target, clear to ambientColor
+            const ac = lightSystem.ambientColor;
+            glContext.bindFramebuffer(glContext.FRAMEBUFFER, glFramebuffer);
+            glContext.framebufferTexture2D(glContext.FRAMEBUFFER,
+                glContext.COLOR_ATTACHMENT0, glContext.TEXTURE_2D, lightSystem.texture, 0);
+            glContext.viewport(0, 0, lightSystem.textureSize.x, lightSystem.textureSize.y);
+            glContext.clearColor(ac.r, ac.g, ac.b, ac.a);
+            glContext.clear(glContext.COLOR_BUFFER_BIT);
+
+            // 3. walk engineObjects calling renderLight() — additive blend
+            //    (lightmap accumulates raw additive color contributions)
+            setBlendMode(true);
+            glContext.enable(glContext.BLEND);
+            glContext.blendFunc(glContext.ONE, glContext.ONE);
+
+            for (const o of engineObjects)
+                o.destroyed || o.renderLight();
+
+            // 4. drain any sprite-batched draws (e.g. drawTile inside a
+            //    custom renderLight override) so they hit the FBO, not the
+            //    canvas after we unbind
+            glFlush();
+            glContext.bindFramebuffer(glContext.FRAMEBUFFER, null);
+            glContext.viewport(0, 0, mainCanvasSize.x, mainCanvasSize.y);
+
+            // 5. composite: fullscreen quad, multiplicative blend onto glCanvas
+            //    (scene * lightmap — unlit areas go to black, lit areas are
+            //    the scene tinted by the accumulated light color)
+            glContext.useProgram(lightSystem.compositeShader);
+            glContext.bindVertexArray(lightSystem.compositeVAO);
+            glContext.activeTexture(glContext.TEXTURE0);
+            glContext.bindTexture(glContext.TEXTURE_2D, lightSystem.texture);
+            const cs = lightSystem.compositeShader;
+            glContext.uniform1i(glContext.getUniformLocation(cs, 's'), 0);
+            glContext.uniform3f(glContext.getUniformLocation(cs, 'iResolution'),
+                mainCanvas.width, mainCanvas.height, 1);
+            glContext.blendFunc(glContext.DST_COLOR, glContext.ZERO);
+            glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, 4);
+
+            // 6. restore engine state so subsequent draws use the engine's
+            //    tracked texture binding (otherwise glSetTexture would think
+            //    the prior texture was still bound when actually the lightmap
+            //    is, and any debug text / future draw could sample the lightmap)
+            if (glActiveTexture)
+                glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
+            setBlendMode(prevAdditive);
+            glSetInstancedMode(true);
+        }
+        function lightSystemContextLost()
+        {
+            lightSystem.texture = undefined;
+            lightSystem.lightShader = undefined;
+            lightSystem.compositeShader = undefined;
+            lightSystem.lightVAO = undefined;
+            lightSystem.compositeVAO = undefined;
+            LOG('LightSystemPlugin: WebGL context lost');
+        }
+        function lightSystemContextRestored()
+        {
+            initLightSystem();
+            LOG('LightSystemPlugin: WebGL context restored');
+        }
+    }
+
+    /** Draw a single Light's falloff blob into the currently bound lightmap.
+     *  Called by Light.renderLight() during the plugin's render pass.
+     *  @param {Light} light */
+    drawLight(light)
+    {
+        if (headlessMode || !glEnable || !this.lightShader) return;
+
+        // drain any sprite-batched draws queued by a previous custom
+        // renderLight() override (e.g. drawRect inside a LavaTile). They were
+        // queued in the engine's instanced-vertex format and must flush with
+        // the engine's shader+VAO bound — NOT this plugin's light shader.
+        glFlush();
+
+        glContext.useProgram(this.lightShader);
+        glContext.bindVertexArray(this.lightVAO);
+
+        // re-apply the engine camera transform onto this shader. Divide by
+        // mainCanvasSize (not textureSize) so world→NDC matches the main
+        // pass; the viewport handles the lightmap's actual resolution.
+        // No y-flip here: the composite samples this FBO with
+        // gl_FragCoord/iResolution (origin bottom-left), so storing world
+        // +Y at the top of the texture lines up with the canvas convention.
+        const s = vec2(2*cameraScale).divide(mainCanvasSize);
+        const rotatedCam = cameraPos.rotate(-cameraAngle);
+        const p = vec2(-1).subtract(rotatedCam.multiply(s));
+        const ca = cos(cameraAngle);
+        const sa = sin(cameraAngle);
+        const transform = [
+            s.x  * ca,  s.y * sa, 0, 0,
+            -s.x * sa,  s.y * ca, 0, 0,
+            1,          1,        1, 0,
+            p.x,        p.y,      0, 1];
+
+        const ls = this.lightShader;
+        glContext.uniformMatrix4fv(glContext.getUniformLocation(ls, 'm'), false, transform);
+        glContext.uniform2f(glContext.getUniformLocation(ls, 'lightPos'), light.pos.x, light.pos.y);
+        glContext.uniform1f(glContext.getUniformLocation(ls, 'radius'), light.radius);
+        glContext.uniform1f(glContext.getUniformLocation(ls, 'fadeRange'), light.fadeRange);
+        const c = light.color;
+        glContext.uniform4f(glContext.getUniformLocation(ls, 'color'), c.r, c.g, c.b, c.a);
+
+        glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, 4);
+
+        // restore engine's instanced shader+VAO so subsequent renderLight()
+        // overrides that batch through drawRect/drawTile work correctly
+        glSetInstancedMode(true);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A Light is an EngineObject that contributes a soft additive blob of color
+ * to the LightSystem plugin's lightmap.
+ * @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
+ */
+class Light extends EngineObject
+{
+    /** Create a light object and add it to the engine object list
+     *  @param {Vector2} pos - World space position
+     *  @param {number} radius - Total extent of the light in world units
+     *  @param {Color} [color] - Color of the light; alpha modulates intensity
+     *  @param {number} [fadeRange] - Width of the soft edge in world units (defaults to radius) */
+    constructor(pos, radius, color, fadeRange)
+    {
+        super(pos, vec2(1), undefined, 0, color);
+        ASSERT(isNumber(radius) && radius >= 0, 'Light radius must be a non-negative number');
+        ASSERT(fadeRange === undefined || (isNumber(fadeRange) && fadeRange >= 0),
+            'Light fadeRange must be a non-negative number when provided');
+
+        /** @property {number} - Total extent of the light in world units */
+        this.radius = radius;
+        /** @property {number} - Width of the soft edge in world units */
+        this.fadeRange = fadeRange === undefined ? radius : fadeRange;
+    }
+
+    /** Lights are invisible in the main render pass — they only contribute
+     *  to the lightmap via renderLight(). */
+    render() {}
+
+    /** Draw this light's falloff blob into the lightmap.
+     *  Called by LightSystemPlugin during its render pass. No-op when the
+     *  plugin or WebGL is unavailable. */
+    renderLight()
+    {
+        lightSystem && lightSystem.drawLight(this);
+    }
+}

package/plugins/medalSystem.js

@@ -60,7 +60,15 @@ function medalsInit(saveName)
     // check if medals are unlocked
     medalsSaveName = saveName;
     if (!debugMedals)
-        medalsForEach(medal=> medal.unlocked = !!localStorage[medal.storageKey()]);
+    {
+        let saved = {};
+        try { saved = JSON.parse(localStorage[saveName] || '{}'); }
+        catch (e) { saved = {}; }
+        medalsForEach(medal => {
+            medal.unlocked = !!(saved[medal.id] && saved[medal.id].unlocked);
+        });
+        medalsSave();
+    }
 
     // engine automatically renders medals
     engineAddPlugin(undefined, medalsRender);
@@ -104,6 +112,31 @@ function medalsInit(saveName)
 function medalsForEach(callback)
 { Object.values(medals).forEach(medal=>callback(medal)); }
 
+/** Reset all medals to locked and persist the cleared catalog
+ *  @memberof Medals */
+function medalsReset()
+{
+    medalsForEach(medal => medal.unlocked = false);
+    medalsSave();
+}
+
+function medalsSave()
+{
+    if (!medalsSaveName) return;
+    const data = {};
+    medalsForEach(medal => {
+        const entry = {
+            name: medal.name,
+            description: medal.description,
+            icon: medal.icon,
+            unlocked: medal.unlocked,
+        };
+        if (medal.image) entry.src = medal.image.src;
+        data[medal.id] = entry;
+    });
+    localStorage[medalsSaveName] = JSON.stringify(data);
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -161,9 +194,9 @@ class Medal
     {
         if (medalsPreventUnlock || this.unlocked) return;
 
-        // save the medal
         ASSERT(medalsSaveName, 'save name must be set');
-        localStorage[this.storageKey()] = this.unlocked = true;
+        this.unlocked = true;
+        medalsSave();
         medalsDisplayQueue.push(this);
     }
 
@@ -221,8 +254,6 @@ class Medal
             drawTextScreen(this.icon, pos, size*.7, BLACK);
     }
 
-    // Get local storage key used by the medal
-    storageKey() { return medalsSaveName + '_' + this.id; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////

package/plugins/newgrounds.js

@@ -82,8 +82,20 @@ class NewgroundsPlugin
 
         // get medals
         const medalsResult = this.call('Medal.getList');
+
+        // bail early if the first call failed (offline / bad session /
+        // server error) so we don't block the main thread on more sync
+        // XHRs that are guaranteed to also fail
+        if (!medalsResult || !medalsResult.result || medalsResult.result.error)
+        {
+            debugMedals && LOG('Newgrounds session unavailable; skipping plugin init');
+            this.medals = [];
+            this.scoreboards = [];
+            return;
+        }
+
         /** @property {Array} - Medals fetched from Newgrounds (empty until session is active) */
-        this.medals = medalsResult ? medalsResult.result.data['medals'] : [];
+        this.medals = medalsResult.result.data?.['medals'] || [];
         debugMedals && LOG(this.medals);
         for (const newgroundsMedal of this.medals)
         {
@@ -103,11 +115,11 @@ class NewgroundsPlugin
                     medal.description = medal.description + ` (${ medal.value })`;
             }
         }
-    
+
         // get scoreboards
         const scoreboardResult = this.call('ScoreBoard.getBoards');
         /** @property {Array} - Scoreboards fetched from Newgrounds */
-        this.scoreboards = scoreboardResult ? scoreboardResult.result.data.scoreboards : [];
+        this.scoreboards = scoreboardResult?.result?.data?.scoreboards || [];
         debugMedals && LOG(this.scoreboards);
 
         // keep the session alive with a ping every minute

package/plugins/pathFinder.js

@@ -271,11 +271,13 @@ class PathFinder
                 if (dx !== 0 && dy !== 0)
                 {
                     // Diagonal step: refuse if either cardinal neighbor is
-                    // blocked or has cost. Prevents cutting through corners.
+                    // blocked. Prevents cutting through walls at corners.
+                    // (Costed-but-walkable cardinals do not block — diagonal
+                    // movement around expensive terrain is standard A*.)
                     const card1 = this.getNode(current.pos.x + dx, current.pos.y);
-                    if (!card1 || card1.cost > 0 || !card1.walkable) continue;
+                    if (!card1 || !card1.walkable) continue;
                     const card2 = this.getNode(current.pos.x, current.pos.y + dy);
-                    if (!card2 || card2.cost > 0 || !card2.walkable) continue;
+                    if (!card2 || !card2.walkable) continue;
                     stepCost = PATHFINDER_DIAGONAL_COST;
                 }