littlejsengine 1.18.2 → 1.18.7

package/dist/littlejs.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.2';
+const engineVersion = '1.18.7';
 
 /** Frames per second to update
  *  @type {number}
@@ -69,7 +69,7 @@ let frame = 0;
  *  @memberof Engine */
 let time = 0;
 
-/** Actual clock time since start in seconds (not affected by pause or frame rate clamping)
+/** Actual clock time since start in seconds (not affected by pause, timescale, or frame rate clamping)
  *  @type {number}
  *  @memberof Engine */
 let timeReal = 0;
@@ -200,11 +200,14 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
         const debugSpeedUp   = debug && keyIsDown('Equal'); // +
         const debugSpeedDown = debug && keyIsDown('Minus'); // -
-        if (debug) // +/- to speed/slow time
-            frameTimeDeltaMS *= debugSpeedUp ? 10 : debugSpeedDown ? .1 : 1;
-        timeReal += frameTimeDeltaMS / 1e3;
+        const debugScale = debugSpeedUp ? 10 : debugSpeedDown ? .1 : 1;
+
+        // apply time deltas
+        timeReal += frameTimeDeltaMS * debugScale / 1e3;
+        const combinedScale = timeScale * debugScale;
+        frameTimeDeltaMS *= combinedScale;
         frameTimeBufferMS += paused ? 0 : frameTimeDeltaMS;
-        if (!debugSpeedUp)
+        if (debugScale <= 1)
             frameTimeBufferMS = min(frameTimeBufferMS, 50); // clamp min framerate
 
         let wasUpdated = false;
@@ -562,145 +565,6 @@ function engineObjectsRaycast(start, end, objects=engineObjects)
 
     debugRaycast && debugLine(start, end, hitObjects.length ? '#f00' : '#00f', .02);
     return hitObjects;
-}
-
-///////////////////////////////////////////////////////////////////////////////
-function drawEngineLogo(t)
-{
-    const blackAndWhite = 0;
-    const showName = 1;
-
-    // LittleJS Logo and Splash Screen
-    const x = mainContext;
-    const dpr = canvasPixelRatio ?? (devicePixelRatio || 1);
-    const w = mainCanvas.width = innerWidth * dpr;
-    const h = mainCanvas.height = innerHeight * dpr;
-    {
-        // background
-        const p3 = percent(t, 1, .8);
-        const p4 = percent(t, 0, .5);
-        const g = x.createRadialGradient(w/2,h/2,0,w/2,h/2,hypot(w,h)*.6);
-        g.addColorStop(0,hsl(0,0,lerp(0,p3/2,p4),p3).toString());
-        g.addColorStop(1,hsl(0,0,0,p3).toString());
-        x.save();
-        x.fillStyle = g;
-        x.fillRect(0,0,w,h);
-    }
-    const gradient = (X1,Y1,X2,Y2,C,S=1)=>
-    {
-        if (C >= 0)
-        {
-            if (blackAndWhite)
-                x.fillStyle = '#fff';
-            else
-            {
-                const g = x.fillStyle = x.createLinearGradient(X1,Y1,X2,Y2);
-                g.addColorStop(0,color(C,2));
-                g.addColorStop(1,color(C,1));
-            }
-        }
-        else
-            x.fillStyle = '#000';
-        C >= -1 ? (x.fill(), S && x.stroke()) : x.stroke();
-    }
-    const circle = (X,Y,R,A=0,B=2*PI,C,S)=>
-    {
-        x.beginPath();
-        x.arc(X,Y,R,p*A,p*B);
-        gradient(X,Y-R,X,Y+R,C,S);
-    }
-    const rect = (X,Y,W,H,C)=>
-    {
-        x.beginPath();
-        x.rect(X,Y,W,H*p);
-        gradient(X,Y+H,X+W,Y,C);
-    }
-    const poly = (points,C,Y,H)=>
-    {
-        x.beginPath();
-        for (const p of points)
-            x.lineTo(p.x, p.y);
-        x.closePath();
-        gradient(0, Y, 0, Y+H,C);
-    }
-    const color = (c,l)=> l?`hsl(${[.95,.56,.13][c%3]*360} 99%${[0,50,75][l]}%`:'#000';
-
-    // center and fit tos screen
-    const alpha = oscillate(1,1,t);
-    const p = percent(alpha, .1, .5);
-    const size = min(6, min(w,h)/99);
-    x.translate(w/2,h/2);
-    x.scale(size,size);
-    x.translate(-40,-35);
-    p < 1 && x.setLineDash([99*p,99]);
-    x.lineJoin = x.lineCap = 'round';
-    x.lineWidth = .1 + p*1.9;
-    //x.strokeStyle='#fff7';
-
-    if (showName)
-    {
-        // engine name text
-        const Y = 54;
-        const s = 'LittleJS';
-        x.font = '900 15.5px arial';
-        x.lineWidth = .1+p*3.9;
-        x.textAlign = 'center';
-        x.textBaseline = 'top';
-        rect(11,Y+1,59,8*p,-1);
-        x.beginPath();
-
-        let w2 = 0;
-        for (let i=0;i<s.length;++i)
-            w2 += x.measureText(s[i]).width;
-        for (let j=2;j--;)
-        for (let i=0,X=40-w2/2;i<s.length;++i)
-        {
-            const w = x.measureText(s[i]).width, X2 = X+w/2;
-            gradient(X2,Y,X2+2,Y+13,i>5?1:0);
-            x[j?'strokeText':'fillText'](s[i],X2,Y+.5,17*p);
-            X += w;
-        }
-
-        x.lineWidth = .1 + p*1.9;
-        rect(3,Y,73,0); // bottom
-    }
-
-    rect(7,15,26,-7,0);   // cab top
-    rect(25,15,8,25,-1);  // cab front
-    rect(10,40,15,-25,1); // cab back
-    rect(14,21,7,9,2);    // cab window
-    rect(38,20,6,-6,2);   // little stack
-    
-    // big stack
-    rect(49,20,10,-6,0);
-    const stackPoints = [vec2(44,8),vec2(64,8),vec2(59,8+6*p),vec2(49,8+6*p)];
-    poly(stackPoints,2,8,6*p);
-    rect(44,8,20,-7,0);
-
-    // engine
-    for (let i=5;i--;) circle(59-i*6*p,30,10,0,2*PI,1,0);
-    circle(59,30,4,0,7,2); // light
-
-    // engine outline
-    rect(35,20,24,0);  // top
-    circle(59,30,10);  // front
-    circle(47,30,10,PI/2,PI*3/2); // middle
-    circle(35,30,10,PI/2,PI*3/2); // back
-    rect(7,40,13,7,-1);   // bottom back
-    rect(17,40,43,14,-1); // bottom center
-
-    // wheels
-    for (let i=3;i--;) for (let j=2;j--;) circle(17+15*i,47,j?7:1,0,2*PI,2);
-    
-    // cowcatcher
-    for (let i=2;i--;)
-    {
-        let w=6, s=7, o=53+w*p*i
-        const points = [vec2(o+s,54),vec2(o,40),vec2(o+w*p,40),vec2(o+s+w*p,54)];
-        poly(points,0,40,14);
-    }
-
-    x.restore();
 }
 /**
  * LittleJS Debug System
@@ -746,7 +610,7 @@ let debugKey = 'Escape';
 let debugOverlay = false;
 
 // Engine internal variables not exposed to documentation
-let debugPrimitives = [], debugPhysics = false, debugRaycast = false, debugParticles = false, debugGamepads = false, debugMedals = false, debugTakeScreenshot;
+let debugPrimitives = [], debugPhysics = false, debugRaycast = false, debugParticles = false, debugGamepads = false, debugTakeScreenshot;
 
 ///////////////////////////////////////////////////////////////////////////////
 // Debug helper functions
@@ -1577,7 +1441,11 @@ function percentLerp(value, percentA, percentB, lerpA, lerpB)
  *  @return {number}
  *  @memberof Math */
 function distanceWrap(valueA, valueB, wrapSize=1)
-{ const d = (valueA - valueB) % wrapSize; return d*2 % wrapSize - d; }
+{
+    ASSERT(wrapSize > 0, 'distanceWrap wrapSize must be > 0');
+    const d = (valueA - valueB) % wrapSize;
+    return d*2 % wrapSize - d;
+}
 
 /** Linearly interpolates between values passed in with wrapping
  *  @param {number} valueA
@@ -1894,6 +1762,7 @@ class RandomGenerator
      *  @param {number} [seed] - Starting seed or engine default seed */
     constructor(seed = 123456789)
     {
+        ASSERT(seed !== 0, 'RandomGenerator seed must be non-zero (xorshift is fixed at 0)');
         /** @property {number} - random seed */
         this.seed = seed;
     }
@@ -2187,8 +2056,10 @@ class Vector2
      * @return {Vector2} */
     floor() { return new Vector2(floor(this.x), floor(this.y)); }
 
-    /** Returns a copy of this vector snapped to a grid
-     *  @param {number} grid - grid size to snap to
+    /** Returns a copy of this vector snapped to a grid. Note that `grid` is
+     *  the number of snap steps per unit (so `grid=2` snaps to halves and
+     *  `grid=0.5` snaps to twos), not the cell size.
+     *  @param {number} grid - snap steps per unit
      *  @return {Vector2} */
     snap(grid)
     {
@@ -2758,9 +2629,14 @@ function readSaveData(saveName, defaultSaveData)
 {
     ASSERT(isString(saveName), 'loadData requires saveName string');
     
-    // replace undefined values with defaults
+    // replace undefined values with defaults; tolerate corrupt JSON
     const data = localStorage[saveName];
-    const loadedData = data ? JSON.parse(data) : {};
+    let loadedData = {};
+    if (data)
+    {
+        try { loadedData = JSON.parse(data); }
+        catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
+    }
     return { ...defaultSaveData, ...loadedData };
 }
 
@@ -2800,6 +2676,18 @@ let cameraAngle = 0;
  *  @memberof Settings */
 let cameraScale = 32;
 
+///////////////////////////////////////////////////////////////////////////////
+// Time settings
+
+/** Scale applied to engine time, can be used for slow motion or fast forward
+ *  - 1 is normal speed, 2 is double speed, 0.5 is half speed
+ *  - 0 freezes the simulation without setting the paused flag
+ *  - Should be >= 0; stacks multiplicatively with the debug +/- shortcut
+ *  @type {number}
+ *  @default
+ *  @memberof Settings */
+let timeScale = 1;
+
 ///////////////////////////////////////////////////////////////////////////////
 // Display settings
 
@@ -3083,33 +2971,6 @@ let soundDefaultRange = 40;
  *  @memberof Settings */
 let soundDefaultTaper = .7;
 
-///////////////////////////////////////////////////////////////////////////////
-// Medals settings
-
-/** How long to show medals for in seconds
- *  @type {number}
- *  @default
- *  @memberof Settings */
-let medalDisplayTime = 5;
-
-/** How quickly to slide on/off medals in seconds
- *  @type {number}
- *  @default
- *  @memberof Settings */
-let medalDisplaySlideTime = .5;
-
-/** Size of medal display
- *  @type {Vector2}
- *  @default Vector2(640,80)
- *  @memberof Settings */
-let medalDisplaySize = vec2(640, 80);
-
-/** Set to stop medals from being unlockable (like if cheats are enabled)
- *  @type {boolean}
- *  @default
- *  @memberof Settings */
-let medalsPreventUnlock = false;
-
 ///////////////////////////////////////////////////////////////////////////////
 // Setters for global variables
 
@@ -3128,6 +2989,11 @@ function setCameraAngle(angle) { cameraAngle = angle; }
  *  @memberof Settings */
 function setCameraScale(scale) { cameraScale = scale; }
 
+/** Set scale applied to engine time
+ *  @param {number} scale
+ *  @memberof Settings */
+function setTimeScale(scale) { timeScale = scale; }
+
 /** Set if tiles should be colorized when using canvas2d
  *  This can be slower but results should look nearly identical to WebGL rendering
  *  It can be enabled/disabled at any time
@@ -3366,26 +3232,6 @@ function setSoundDefaultRange(range) { soundDefaultRange = range; }
  *  @memberof Settings */
 function setSoundDefaultTaper(taper) { soundDefaultTaper = taper; }
 
-/** Set how long to show medals for in seconds
- *  @param {number} time
- *  @memberof Settings */
-function setMedalDisplayTime(time) { medalDisplayTime = time; }
-
-/** Set how quickly to slide on/off medals in seconds
- *  @param {number} time
- *  @memberof Settings */
-function setMedalDisplaySlideTime(time) { medalDisplaySlideTime = time; }
-
-/** Set size of medal display
- *  @param {Vector2} size
- *  @memberof Settings */
-function setMedalDisplaySize(size) { medalDisplaySize = size.copy(); }
-
-/** Set to stop medals from being unlockable
- *  @param {boolean} preventUnlock
- *  @memberof Settings */
-function setMedalsPreventUnlock(preventUnlock) { medalsPreventUnlock = preventUnlock; }
-
 /** Set if watermark with FPS should be shown
  *  @param {boolean} show
  *  @memberof Debug */
@@ -3527,10 +3373,18 @@ class EngineObject
         const parent = this.parent;
         if (parent)
         {
-            // copy parent pos/angle
+            // compose with parent transform inline to avoid intermediate vector allocs
             const mirror = parent.getMirrorSign();
-            this.pos = this.localPos.multiply(vec2(mirror,1)).rotate(parent.angle).add(parent.pos);
-            this.angle = mirror*this.localAngle + parent.angle;
+            const lp = this.localPos, pp = parent.pos;
+            const lx = lp.x*mirror, ly = lp.y, pa = parent.angle;
+            if (pa)
+            {
+                const c = cos(-pa), s = sin(-pa);
+                this.pos = new Vector2(lx*c - ly*s + pp.x, lx*s + ly*c + pp.y);
+            }
+            else
+                this.pos = new Vector2(lx + pp.x, ly + pp.y);
+            this.angle = mirror*this.localAngle + pa;
         }
 
         // update children
@@ -3896,8 +3750,6 @@ class EngineObject
      *  @return {string} */
     toString()
     {
-        if (!debug) return;
-        
         let text = 'type = ' + this.constructor.name;
         if (this.pos.x || this.pos.y)
             text += '\npos = ' + this.pos;
@@ -4002,6 +3854,12 @@ let textureInfos = [];
  *  @memberof Draw */
 let drawCount;
 
+// internal predicates for tint short-circuiting in canvas2D draw paths
+// isWhite ignores alpha because alpha is applied via globalAlpha, not multiply
+// isBlack includes alpha so additive colors that only contribute alpha are not skipped
+/** @param {Color} c */ function isWhite(c) { return c.r >= 1 && c.g >= 1 && c.b >= 1; }
+/** @param {Color} c */ function isBlack(c) { return c.r <= 0 && c.g <= 0 && c.b <= 0 && c.a <= 0; }
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -4141,8 +3999,9 @@ class TextureInfo
      * Create a TextureInfo, called automatically by the engine
      * @param {HTMLImageElement|OffscreenCanvas} image
      * @param {boolean} [useWebGL] - Should use WebGL if available?
+     * @param {boolean} [wrap] - Should the texture wrap (REPEAT) or clamp (CLAMP_TO_EDGE)?
      */
-    constructor(image, useWebGL=true)
+    constructor(image, useWebGL=true, wrap=false)
     {
         /** @property {HTMLImageElement|OffscreenCanvas} - image source */
         this.image = image;
@@ -4152,6 +4011,8 @@ class TextureInfo
         this.sizeInverse = image ? vec2(1/image.width, 1/image.height) : vec2();
         /** @property {WebGLTexture} - WebGL texture */
         this.glTexture = undefined;
+        /** @property {boolean} - true for REPEAT wrap mode, false for CLAMP_TO_EDGE */
+        this.wrap = wrap;
         useWebGL && this.createWebGLTexture();
     }
 
@@ -4164,6 +4025,14 @@ class TextureInfo
     /** Check if the texture is webgl enabled
      * @return {boolean} */
     hasWebGL() { return !!this.glTexture; }
+
+    /** Set the wrap mode for this texture
+     *  @param {boolean} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE */
+    setWrap(wrap=true)
+    {
+        this.wrap = wrap;
+        glSetTextureWrap(this.glTexture, wrap);
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4225,8 +4094,13 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
         }
         else
         {
-            // if no tile info, force untextured
-            glDraw(pos.x, pos.y, size.x, size.y, angle, 0, 0, 0, 0, 0, color.rgbaInt());
+            // if no tile info, force untextured by zeroing rgba (so whatever
+            // texture is bound doesn't leak in) and folding color+additive
+            // into the additive slot — matches the Canvas2D path's
+            // color.add(additiveColor) on line ~337.
+            const combined = additiveColor ? color.add(additiveColor) : color;
+            glDraw(pos.x, pos.y, size.x, size.y, angle, 0, 0, 0, 0,
+                0, combined.rgbaInt());
         }
     }
     else
@@ -4331,6 +4205,98 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0,
     }
 }
 
+/** Draw a texture tiled (wrapped) across a rectangle in world space.
+ *  Useful for backgrounds, repeating patterns, and seamless fills.
+ *  The whole texture is tiled — sub-region (TileInfo) wrapping is not supported.
+ *  @param {Vector2}  pos          - Center of the rect in world space
+ *  @param {Vector2}  size         - Size of the rect in world space
+ *  @param {Vector2}  wrapCount    - How many times the texture repeats (x, y)
+ *  @param {TextureInfo|number} [texture=0] - TextureInfo or texture index into textureInfos
+ *  @param {Color}    [color=WHITE] - Color to modulate with
+ *  @param {number}   [angle=0] - Angle to rotate by
+ *  @param {Color}    [additiveColor] - Additive color to be applied if any
+ *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
+ *  @param {boolean}  [screenSpace=false] - Are pos and size in screen space?
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
+ *  @memberof Draw */
+function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
+    angle=0, additiveColor, useWebGL=glEnable, screenSpace=false, context)
+{
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isVector2(wrapCount), 'wrapCount must be a vec2');
+    ASSERT(isColor(color), 'color is invalid');
+    ASSERT(isNumber(angle), 'angle must be a number');
+    ASSERT(!additiveColor || isColor(additiveColor), 'additiveColor must be a color');
+    ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
+    ASSERT(!(texture instanceof TileInfo),
+        'pass a TextureInfo or texture index, not a TileInfo — use tileInfo.textureInfo');
+
+    // short-circuit before texture lookup — textureInfos[0] is undefined in headless mode
+    if (headlessMode) return;
+
+    // resolve texture argument: TextureInfo or index
+    const textureInfo = typeof texture === 'number' ? textureInfos[texture] : texture;
+    ASSERT(textureInfo instanceof TextureInfo, 'texture not loaded');
+    ASSERT(textureInfo.size.x > 0, 'texture not loaded');
+    ASSERT(textureInfo.wrap,
+        'drawTextureWrapped requires a wrap-enabled texture; call textureInfo.setWrap(true) first');
+
+    if (useWebGL && glEnable)
+    {
+        ASSERT(!!glContext, 'WebGL is not enabled!');
+        if (screenSpace)
+            [pos, size, angle] = screenToWorldTransform(pos, size, angle);
+        glSetTexture(textureInfo.glTexture);
+        glDraw(pos.x, pos.y, size.x, size.y, angle,
+            0, 0, wrapCount.x, wrapCount.y,
+            color.rgbaInt(), additiveColor && additiveColor.rgbaInt());
+        return;
+    }
+
+    // Canvas2D path — increment drawCount here (WebGL batch counts via glBatchCount)
+    ++drawCount;
+
+    if (!screenSpace)
+    {
+        pos = worldToScreen(pos);
+        size = size.scale(cameraScale);
+        angle -= cameraAngle;
+    }
+
+    // pick image source: raw, or tinted bake. Match drawImageColor's
+    // "no tint needed" predicate so behavior stays consistent.
+    const noTint = !canvasColorTiles ||
+        (additiveColor
+            ? isWhite(color.add(additiveColor)) && additiveColor.a <= 0
+            : isWhite(color));
+    // alpha is baked into pixels by bakeTintedImage's additive branch;
+    // in that case globalAlpha must NOT also apply color.a
+    const alphaBaked = !noTint && additiveColor && !isBlack(additiveColor);
+    const source = noTint
+        ? textureInfo.image
+        : bakeTintedImage(textureInfo.image, color, additiveColor);
+
+    context = context || drawContext;
+    context.save();
+    context.translate(pos.x + .5, pos.y + .5);
+    context.rotate(angle);
+    context.globalAlpha = alphaBaked ? 1 : color.a;
+
+    const pattern = context.createPattern(source, 'repeat');
+    // map pattern-source pixels into user space so the rect contains
+    // wrapCount.x × wrapCount.y repeats
+    const m = new DOMMatrix()
+        .translate(-size.x/2, -size.y/2)
+        .scale(size.x / (wrapCount.x * source.width),
+               size.y / (wrapCount.y * source.height));
+    pattern.setTransform(m);
+    context.fillStyle = pattern;
+    context.fillRect(-size.x/2, -size.y/2, size.x, size.y);
+    context.globalAlpha = 1;
+    context.restore();
+}
+
 /** Draw connected lines between a series of points
  *  @param {Array<Vector2>} points
  *  @param {number}  [width]
@@ -4854,6 +4820,43 @@ function combineCanvases()
     mainContext.drawImage(workCanvas, 0, 0);
 }
 
+// Internal: bake a color/additive-color tint into workReadCanvas at the
+// image's native resolution. Returns the work canvas, suitable for
+// passing to context.createPattern. Used by drawTextureWrapped's
+// Canvas2D path. Caller is responsible for short-circuiting when no
+// tint is needed (i.e. color is white and additiveColor is black/none).
+function bakeTintedImage(image, color, additiveColor)
+{
+    const w = image.width|0, h = image.height|0;
+    workReadCanvas.width = w;
+    workReadCanvas.height = h;
+    workReadContext.drawImage(image, 0, 0);
+
+    const imageData = workReadContext.getImageData(0, 0, w, h);
+    const data = imageData.data;
+    if (additiveColor && !isBlack(additiveColor))
+    {
+        // multiply + additive (slower)
+        const colorMultiply = [color.r, color.g, color.b, color.a];
+        const colorAdd = [additiveColor.r * 255, additiveColor.g * 255,
+                          additiveColor.b * 255, additiveColor.a * 255];
+        for (let i = 0; i < data.length; ++i)
+            data[i] = data[i] * colorMultiply[i&3] + colorAdd[i&3] |0;
+    }
+    else
+    {
+        // RGB only, faster — alpha left intact for the caller
+        for (let i = 0; i < data.length; i+=4)
+        {
+            data[i  ] *= color.r;
+            data[i+1] *= color.g;
+            data[i+2] *= color.b;
+        }
+    }
+    workReadContext.putImageData(imageData, 0, 0);
+    return workReadCanvas;
+}
+
 /** Helper function to draw an image with color and additive color applied
  *  This is slower then normal drawImage when color is applied
     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
@@ -4872,8 +4875,6 @@ function combineCanvases()
  *  @memberof Draw */
 function drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight, color, additiveColor, bleed=0)
 {
-    function isWhite(c) { return c.r >= 1 && c.g >= 1 && c.b >= 1; }
-    function isBlack(c) { return c.r <= 0 && c.g <= 0 && c.b <= 0 && c.a <= 0; }
     const sx2 = bleed;
     const sy2 = bleed;
     sWidth  = max(1,sWidth|0);
@@ -5148,7 +5149,7 @@ const isTouchDevice = !headlessMode && window.ontouchstart !== undefined;
  *  This is useful to disable for html menus so the browser can handle input normally
  *  @param {boolean} preventDefault
  *  @memberof Input */
-function setInputPreventDefault(preventDefault) { inputPreventDefault = preventDefault; }
+function setInputPreventDefault(preventDefault=true) { inputPreventDefault = preventDefault; }
 
 /** Clears an input key state
  *  @param {string|number} key
@@ -5342,6 +5343,32 @@ function gamepadStickCount(gamepad=gamepadPrimary)
     return gamepadStickData[gamepad]?.length ?? 0;
 }
 
+/** Pulse a gamepad's vibration hardware using the dual-rumble effect if it exists
+ *  Strong magnitude is usually the left side motor, weak magnitude is usually the right side motor
+ *  @param {number} [gamepad] - gamepad index
+ *  @param {number} [duration] - effect duration in ms
+ *  @param {number} [strongMagnitude] - strong (left) motor intensity, 0 to 1
+ *  @param {number} [weakMagnitude] - weak (right) motor intensity, 0 to 1
+ *  @param {number} [startDelay] - delay in ms before the effect starts
+ *  @memberof Input */
+function gamepadVibrate(gamepad=gamepadPrimary, duration=200, strongMagnitude=1, weakMagnitude=1, startDelay=0)
+{
+    ASSERT(isNumber(gamepad), 'gamepad must be a number');
+    if (!vibrateEnable || headlessMode) return;
+    const pad = navigator?.getGamepads?.()[gamepad];
+    pad?.vibrationActuator?.playEffect?.('dual-rumble', {duration, strongMagnitude, weakMagnitude, startDelay});
+}
+
+/** Stop vibration on a gamepad
+ *  @memberof Input */
+function gamepadVibrateStop(gamepad=gamepadPrimary)
+{
+    ASSERT(isNumber(gamepad), 'gamepad must be a number');
+    if (!vibrateEnable || headlessMode) return;
+    const pad = navigator?.getGamepads?.()[gamepad];
+    pad?.vibrationActuator?.reset?.();
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Pulse the vibration hardware if it exists
@@ -5918,10 +5945,12 @@ function touchGamepadButtonCenter()
  * @namespace Audio
  */
 
-/** Audio context used by the engine
+/** Audio context used by the engine. Created lazily in audioInit() to avoid
+ *  browser autoplay warnings about constructing an AudioContext before any
+ *  user gesture.
  *  @type {AudioContext}
  *  @memberof Audio */
-let audioContext = new AudioContext;
+let audioContext;
 
 /** Master gain node for all audio to pass through
  *  @type {GainNode}
@@ -5937,12 +5966,13 @@ const audioDefaultSampleRate = 44100;
  *  @return {boolean} - True if the audio context is running
  *  @memberof Audio */
 function audioIsRunning()
-{ return audioContext.state === 'running'; }
+{ return audioContext?.state === 'running'; }
 
 function audioInit()
 {
     if (!soundEnable || headlessMode) return;
 
+    audioContext = new AudioContext;
     audioMasterGain = audioContext.createGain();
     audioMasterGain.connect(audioContext.destination);
     audioMasterGain.gain.value = soundVolume; // set starting value
@@ -6009,8 +6039,8 @@ class Sound
 
         if (Array.isArray(asset))
         {
-            // generate zzfx sound
-            const zzfxSound = asset;
+            // generate zzfx sound — copy so we don't mutate the caller's array
+            const zzfxSound = asset.slice();
 
             // remove randomness so it can be applied on playback
             const defaultRandomness = randomness ?? .05;
@@ -7608,11 +7638,14 @@ class ParticleEmitter extends EngineObject
 }
 
 ///////////////////////////////////////////////////////////////////////////////
+// scratch vector reused by Particle.render to avoid per-frame allocations
+const particleDrawPos = new Vector2;
+
 /**
  * Particle Object - Created automatically by Particle Emitters
  * @memberof Particles
  */
-class Particle 
+class Particle
 {
     /**
      * Create a particle with the passed in settings
@@ -7787,14 +7820,14 @@ class Particle
         additive && setBlendMode(true);
 
         // update the position and angle for drawing
-        const pos = this.pos.copy();
+        const pos = particleDrawPos.set(this.pos.x, this.pos.y);
         let angle = this.angle;
         if (localSpace)
         {
             // in local space of emitter
             const a = emitter.angle;
             const c = cos(a), s = sin(a);
-            pos.set(emitter.pos.x + pos.x*c - pos.y*s, 
+            pos.set(emitter.pos.x + pos.x*c - pos.y*s,
                 emitter.pos.y + pos.x*s + pos.y*c);
             angle += a;
         }
@@ -7819,200 +7852,6 @@ class Particle
         debugParticles && debugRect(pos, size, '#f005', 0, angle);
     }
 }
-/**
- * LittleJS Medal System
- * - Achievement/trophy system for games
- * - Medal class with name, description, icon, and unlock tracking
- * - Automatic saving to local storage
- * - Visual display queue with slide-in notifications
- * - Newgrounds API integration for online achievements
- * - Debug mode to unlock/reset medals during development
- * @namespace Medals
- */
-
-/** List of all medals
- *  @type {Object}
- *  @memberof Medals */
-const medals = {};
-
-// Engine internal variables not exposed to documentation
-let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimeLast;
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Initialize medals with a save name used for storage
- *  - Call this after creating all medals
- *  - Checks if medals are unlocked
- *  @param {string} saveName
- *  @memberof Medals */
-function medalsInit(saveName)
-{
-    // check if medals are unlocked
-    medalsSaveName = saveName;
-    if (!debugMedals)
-        medalsForEach(medal=> medal.unlocked = !!localStorage[medal.storageKey()]);
-
-    // engine automatically renders medals
-    engineAddPlugin(undefined, medalsRender);
-
-    // plugin functions
-    function medalsRender()
-    {
-        if (!medalsDisplayQueue.length) return;
-
-        // update first medal in queue
-        const medal = medalsDisplayQueue[0];
-        const time = timeReal - medalsDisplayTimeLast;
-        if (!medalsDisplayTimeLast)
-            medalsDisplayTimeLast = timeReal;
-        else if (time > medalDisplayTime)
-        {
-            medalsDisplayTimeLast = 0;
-            medalsDisplayQueue.shift();
-        }
-        else
-        {
-            // slide on/off medals
-            const slideOffTime = medalDisplayTime - medalDisplaySlideTime;
-            const hidePercent =
-                time < medalDisplaySlideTime ? 1 - time / medalDisplaySlideTime :
-                time > slideOffTime ? (time - slideOffTime) / medalDisplaySlideTime : 0;
-            medal.render(hidePercent);
-        }
-    }
-}
-
-/**
- *  @callback MedalCallbackFunction - Function that processes a medal
- *  @param {Medal} medal
- *  @memberof Medals
- */
-
-/** Calls a function for each medal
- *  @param {MedalCallbackFunction} callback
- *  @memberof Medals */
-function medalsForEach(callback)
-{ Object.values(medals).forEach(medal=>callback(medal)); }
-
-///////////////////////////////////////////////////////////////////////////////
-
-/**
- * Medal - Tracks an unlockable medal
- * @memberof Medals
- * @example
- * // create a medal
- * const medal_example = new Medal(0, 'Example Medal', 'More info about the medal goes here.', '🎖️');
- *
- * // initialize medals
- * medalsInit('Example Game');
- *
- * // unlock the medal
- * medal_example.unlock();
- */
-class Medal
-{
-    /** Create a medal object and adds it to the list of medals
-     *  @param {number} id            - The unique identifier of the medal
-     *  @param {string} name          - Name of the medal
-     *  @param {string} [description] - Description of the medal
-     *  @param {string} [icon]        - Icon for the medal
-     *  @param {string} [src]         - Image location for the medal
-     */
-    constructor(id, name, description='', icon='🏆', src)
-    {
-        ASSERT(id >= 0 && !medals[id]);
-
-        /** @property {number} - The unique identifier of the medal */
-        this.id = id;
-
-        /** @property {string} - Name of the medal */
-        this.name = name;
-
-        /** @property {string} - Description of the medal */
-        this.description = description;
-
-        /** @property {string} - Icon for the medal */
-        this.icon = icon;
-
-        /** @property {boolean} - Is the medal unlocked? */
-        this.unlocked = false;
-
-        // load the source image if provided
-        if (src)
-            (this.image = new Image).src = src;
-
-        // add this to list of medals
-        medals[id] = this;
-    }
-
-    /** Unlocks a medal if not already unlocked */
-    unlock()
-    {
-        if (medalsPreventUnlock || this.unlocked) return;
-
-        // save the medal
-        ASSERT(medalsSaveName, 'save name must be set');
-        localStorage[this.storageKey()] = this.unlocked = true;
-        medalsDisplayQueue.push(this);
-    }
-
-    /** Render a medal
-     *  @param {number} [hidePercent] - How much to slide the medal off screen
-     */
-    render(hidePercent=0)
-    {
-        const context = mainContext;
-        const width = min(medalDisplaySize.x, mainCanvas.width);
-        const height = medalDisplaySize.y;
-        const x = mainCanvas.width - width;
-        const y = -height*hidePercent;
-        const backgroundColor = hsl(0,0,.9);
-
-        // draw containing rect and clip to that region
-        context.save();
-        context.beginPath();
-        context.fillStyle = backgroundColor.toString();
-        context.strokeStyle = BLACK.toString();
-        context.lineWidth = 3;
-        context.rect(x, y, width, height);
-        context.fill();
-        context.stroke();
-        context.clip();
-
-        // draw the icon
-        const gap = vec2(.1, .05).scale(height);
-        const medalDisplayIconSize = height - 2*gap.x;
-        this.renderIcon(vec2(x + gap.x + medalDisplayIconSize/2, y + height/2), medalDisplayIconSize);
-
-        // draw the name
-        const nameSize = height*.5;
-        const descriptionSize = height*.3;
-        const pos = vec2(x + medalDisplayIconSize + 2*gap.x, y + gap.y*2 + nameSize/2);
-        const textWidth = width - medalDisplayIconSize - 3*gap.x;
-        drawTextScreen(this.name, pos, nameSize, BLACK, 0, undefined, 'left', undefined, undefined, textWidth);
-
-        // draw the description
-        pos.y = y + height - gap.y*2 - descriptionSize/2;
-        drawTextScreen(this.description, pos, descriptionSize, BLACK, 0, undefined, 'left', undefined, undefined, textWidth);
-        context.restore();
-    }
-
-    /** Render the icon for a medal
-     *  @param {Vector2} pos - Screen space position
-     *  @param {number} size - Screen space size
-     */
-    renderIcon(pos, size)
-    {
-        // draw the image or icon
-        if (this.image)
-            mainContext.drawImage(this.image, pos.x-size/2, pos.y-size/2, size, size);
-        else
-            drawTextScreen(this.icon, pos, size*.7, BLACK);
-    }
-
-    // Get local storage key used by the medal
-    storageKey() { return medalsSaveName + '_' + this.id; }
-}
 /**
  * LittleJS WebGL Interface
  * - WebGL2 rendering engine for high-performance graphics
@@ -8112,7 +7951,7 @@ function glInit(rootElement)
         // reinit WebGL and restore textures
         initWebGL();
         for (const info of glTextureInfos)
-            info.glTexture = glCreateTexture(info.image);
+            info.glTexture = glCreateTexture(info.image, info.wrap);
         pluginList.forEach(plugin=>plugin.glContextRestored?.());
     });
 
@@ -8317,9 +8156,8 @@ function glClearCanvas()
 /** Set the WebGL texture, called automatically if using multiple textures
  *  - This may also flush the gl buffer resulting in more draw calls and worse performance
  *  @param {WebGLTexture} texture
- *  @param {boolean} [wrap] - Should the texture wrap or clamp
  *  @memberof WebGL */
-function glSetTexture(texture, wrap=false)
+function glSetTexture(texture)
 {
     // must flush cache with the old texture to set a new one
     if (!glContext || texture === glActiveTexture) return;
@@ -8327,11 +8165,30 @@ function glSetTexture(texture, wrap=false)
     glFlush();
     glActiveTexture = texture;
     glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
+}
+
+/** Set the wrap mode (REPEAT or CLAMP_TO_EDGE) on an existing WebGL texture
+ *  Flushes the current batch only if the texture is the active one
+ *  @param {WebGLTexture} texture
+ *  @param {boolean} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE
+ *  @memberof WebGL */
+function glSetTextureWrap(texture, wrap=true)
+{
+    if (!glContext || !texture) return;
+
+    // flush only if changing wrap on the currently bound texture
+    const isCurrent = texture === glActiveTexture;
+    if (isCurrent)
+        glFlush();
+    else
+        glContext.bindTexture(glContext.TEXTURE_2D, texture);
 
-    // set wrap mode
     const wrapMode = wrap ? glContext.REPEAT : glContext.CLAMP_TO_EDGE;
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_S, wrapMode);
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_T, wrapMode);
+
+    if (!isCurrent && glActiveTexture)
+        glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
 }
 
 /** Compile WebGL shader of the given type, will throw errors if in debug mode
@@ -8378,9 +8235,10 @@ function glCreateProgram(vsSource, fsSource)
 /** Create WebGL texture from an image and init the texture settings
  *  Restores the active texture when done
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas} [image]
+ *  @param {boolean} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE
  *  @return {WebGLTexture}
  *  @memberof WebGL */
-function glCreateTexture(image)
+function glCreateTexture(image, wrap=false)
 {
     if (!glContext) return;
 
@@ -8406,6 +8264,9 @@ function glCreateTexture(image)
     const minFilter = mipMap ? glContext.LINEAR_MIPMAP_LINEAR : magFilter;
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MAG_FILTER, magFilter);
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MIN_FILTER, minFilter);
+    const wrapMode = wrap ? glContext.REPEAT : glContext.CLAMP_TO_EDGE;
+    glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_S, wrapMode);
+    glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_T, wrapMode);
     if (mipMap)
         glContext.generateMipmap(glContext.TEXTURE_2D);
 
@@ -8457,7 +8318,7 @@ function glRegisterTextureInfo(textureInfo)
     if (textureInfo.glTexture)
         glSetTextureData(textureInfo.glTexture, textureInfo.image);
     else
-        textureInfo.glTexture = glCreateTexture(textureInfo.image);
+        textureInfo.glTexture = glCreateTexture(textureInfo.image, textureInfo.wrap);
 }
 
 /** Tells WebGL to destroy the glTexture and stop tracking it
@@ -8676,6 +8537,7 @@ function glSetRenderTarget(texture, clear=false)
         glFlush();
         glRenderTarget = undefined;
         glContext.bindFramebuffer(glContext.FRAMEBUFFER, null);
+        glContext.viewport(0, 0, mainCanvasSize.x, mainCanvasSize.y);
     }
 }
 
@@ -8798,9 +8660,9 @@ function glPolyStrip(points)
         return area;
     }
 
-    // ensure counter-clockwise winding
+    // ensure counter-clockwise winding (slice first so we don't mutate caller's array)
     if (signedArea(points) < 0)
-        points = points.reverse();
+        points = points.slice().reverse();
 
     // check if point is inside triangle
     const e = 1e-9;
@@ -8900,46 +8762,438 @@ function glPolyStrip(points)
     }
     return strip;
 }
-/** 
- * LittleJS Newgrounds Plugin
- * - NewgroundsMedal extends Medal with Newgrounds API functionality
- * - Call new NewgroundsPlugin(app_id) to setup Newgrounds
- * - Uses CryptoJS for encryption if optional cipher is provided
- * - provides functions to interact with medals scoreboards
- * - Keeps connection alive and logs views
- * @namespace Newgrounds
- */
-
-/** Global Newgrounds object
- *  @type {NewgroundsPlugin}
- *  @memberof Newgrounds */
-let newgrounds;
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * Newgrounds medal auto unlocks in newgrounds API
- * @extends Medal
- * @memberof Newgrounds
- */
-class NewgroundsMedal extends Medal
-{
-    /** Create a newgrounds medal object and adds it to the list of medals
-     *  @param {number} id            - The unique identifier of the medal
-     *  @param {string} name          - Name of the medal
-     *  @param {string} [description] - Description of the medal
-     *  @param {string} [icon]        - Icon for the medal
-     *  @param {string} [src]         - Image location for the medal
-     */
-    constructor(id, name, description, icon, src)
-    { super(id, name, description, icon, src); }
-
-    /** Unlocks a medal if not already unlocked */
-    unlock()
-    {
-        super.unlock();
-        newgrounds && newgrounds.unlockMedal(this.id);
-    }
-}
+/**
+ * LittleJS Engine Logo
+ * - Draws the LittleJS splash screen logo
+ * - Used internally during engine startup
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+function drawEngineLogo(t)
+{
+    const blackAndWhite = 0;
+    const showName = 1;
+
+    // LittleJS Logo and Splash Screen
+    const x = mainContext;
+    const dpr = canvasPixelRatio ?? (devicePixelRatio || 1);
+    const w = mainCanvas.width = innerWidth * dpr;
+    const h = mainCanvas.height = innerHeight * dpr;
+    {
+        // background
+        const p3 = percent(t, 1, .8);
+        const p4 = percent(t, 0, .5);
+        const g = x.createRadialGradient(w/2,h/2,0,w/2,h/2,hypot(w,h)*.6);
+        g.addColorStop(0,hsl(0,0,lerp(0,p3/2,p4),p3).toString());
+        g.addColorStop(1,hsl(0,0,0,p3).toString());
+        x.save();
+        x.fillStyle = g;
+        x.fillRect(0,0,w,h);
+    }
+    const gradient = (X1,Y1,X2,Y2,C,S=1)=>
+    {
+        if (C >= 0)
+        {
+            if (blackAndWhite)
+                x.fillStyle = '#fff';
+            else
+            {
+                const g = x.fillStyle = x.createLinearGradient(X1,Y1,X2,Y2);
+                g.addColorStop(0,color(C,2));
+                g.addColorStop(1,color(C,1));
+            }
+        }
+        else
+            x.fillStyle = '#000';
+        C >= -1 ? (x.fill(), S && x.stroke()) : x.stroke();
+    }
+    const circle = (X,Y,R,A=0,B=2*PI,C,S)=>
+    {
+        x.beginPath();
+        x.arc(X,Y,R,p*A,p*B);
+        gradient(X,Y-R,X,Y+R,C,S);
+    }
+    const rect = (X,Y,W,H,C)=>
+    {
+        x.beginPath();
+        x.rect(X,Y,W,H*p);
+        gradient(X,Y+H,X+W,Y,C);
+    }
+    const poly = (points,C,Y,H)=>
+    {
+        x.beginPath();
+        for (const p of points)
+            x.lineTo(p.x, p.y);
+        x.closePath();
+        gradient(0, Y, 0, Y+H,C);
+    }
+    const color = (c,l)=> l?`hsl(${[.95,.56,.13][c%3]*360} 99%${[0,50,75][l]}%`:'#000';
+
+    // center and fit to screen
+    const alpha = oscillate(1,1,t);
+    const p = percent(alpha, .1, .5);
+    const size = min(6, min(w,h)/99);
+    x.translate(w/2,h/2);
+    x.scale(size,size);
+    x.translate(-40,-35);
+    p < 1 && x.setLineDash([99*p,99]);
+    x.lineJoin = x.lineCap = 'round';
+    x.lineWidth = .1 + p*1.9;
+    //x.strokeStyle='#fff7';
+
+    if (showName)
+    {
+        // engine name text
+        const Y = 54;
+        const s = 'LittleJS';
+        x.font = '900 15.5px arial';
+        x.lineWidth = .1+p*3.9;
+        x.textAlign = 'center';
+        x.textBaseline = 'top';
+        rect(11,Y+1,59,8*p,-1);
+        x.beginPath();
+
+        let w2 = 0;
+        for (let i=0;i<s.length;++i)
+            w2 += x.measureText(s[i]).width;
+        for (let j=2;j--;)
+        for (let i=0,X=40-w2/2;i<s.length;++i)
+        {
+            const w = x.measureText(s[i]).width, X2 = X+w/2;
+            gradient(X2,Y,X2+2,Y+13,i>5?1:0);
+            x[j?'strokeText':'fillText'](s[i],X2,Y+.5,17*p);
+            X += w;
+        }
+
+        x.lineWidth = .1 + p*1.9;
+        rect(3,Y,73,0); // bottom
+    }
+
+    rect(7,15,26,-7,0);   // cab top
+    rect(25,15,8,25,-1);  // cab front
+    rect(10,40,15,-25,1); // cab back
+    rect(14,21,7,9,2);    // cab window
+    rect(38,20,6,-6,2);   // little stack
+
+    // big stack
+    rect(49,20,10,-6,0);
+    const stackPoints = [vec2(44,8),vec2(64,8),vec2(59,8+6*p),vec2(49,8+6*p)];
+    poly(stackPoints,2,8,6*p);
+    rect(44,8,20,-7,0);
+
+    // engine
+    for (let i=5;i--;) circle(59-i*6*p,30,10,0,2*PI,1,0);
+    circle(59,30,4,0,7,2); // light
+
+    // engine outline
+    rect(35,20,24,0);  // top
+    circle(59,30,10);  // front
+    circle(47,30,10,PI/2,PI*3/2); // middle
+    circle(35,30,10,PI/2,PI*3/2); // back
+    rect(7,40,13,7,-1);   // bottom back
+    rect(17,40,43,14,-1); // bottom center
+
+    // wheels
+    for (let i=3;i--;) for (let j=2;j--;) circle(17+15*i,47,j?7:1,0,2*PI,2);
+
+    // cowcatcher
+    for (let i=2;i--;)
+    {
+        let w=6, s=7, o=53+w*p*i
+        const points = [vec2(o+s,54),vec2(o,40),vec2(o+w*p,40),vec2(o+s+w*p,54)];
+        poly(points,0,40,14);
+    }
+
+    x.restore();
+}
+
+/**
+ * LittleJS Medal System
+ * - Achievement/trophy system for games
+ * - Medal class with name, description, icon, and unlock tracking
+ * - Automatic saving to local storage
+ * - Visual display queue with slide-in notifications
+ * - Newgrounds API integration for online achievements
+ * - Debug mode to unlock/reset medals during development
+ * @namespace Medals
+ */
+
+let debugMedals = false;
+
+///////////////////////////////////////////////////////////////////////////////
+// Medals settings
+
+/** How long to show medals for in seconds
+ *  @type {number}
+ *  @default
+ *  @memberof Settings */
+let medalDisplayTime = 5;
+
+/** How quickly to slide on/off medals in seconds
+ *  @type {number}
+ *  @default
+ *  @memberof Settings */
+let medalDisplaySlideTime = .5;
+
+/** Size of medal display
+ *  @type {Vector2}
+ *  @default Vector2(640,80)
+ *  @memberof Settings */
+let medalDisplaySize = vec2(640, 80);
+
+/** Set to stop medals from being unlockable (like if cheats are enabled)
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let medalsPreventUnlock = false;
+
+/** List of all medals
+ *  @type {Object}
+ *  @memberof Medals */
+const medals = {};
+
+// Engine internal variables not exposed to documentation
+let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimeLast;
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Initialize medals with a save name used for storage
+ *  - Call this after creating all medals
+ *  - Checks if medals are unlocked
+ *  @param {string} saveName
+ *  @memberof Medals */
+function medalsInit(saveName)
+{
+    // check if medals are unlocked
+    medalsSaveName = saveName;
+    if (!debugMedals)
+        medalsForEach(medal=> medal.unlocked = !!localStorage[medal.storageKey()]);
+
+    // engine automatically renders medals
+    engineAddPlugin(undefined, medalsRender);
+
+    // plugin functions
+    function medalsRender()
+    {
+        if (!medalsDisplayQueue.length) return;
+
+        // update first medal in queue
+        const medal = medalsDisplayQueue[0];
+        const time = timeReal - medalsDisplayTimeLast;
+        if (!medalsDisplayTimeLast)
+            medalsDisplayTimeLast = timeReal;
+        else if (time > medalDisplayTime)
+        {
+            medalsDisplayTimeLast = 0;
+            medalsDisplayQueue.shift();
+        }
+        else
+        {
+            // slide on/off medals
+            const slideOffTime = medalDisplayTime - medalDisplaySlideTime;
+            const hidePercent =
+                time < medalDisplaySlideTime ? 1 - time / medalDisplaySlideTime :
+                time > slideOffTime ? (time - slideOffTime) / medalDisplaySlideTime : 0;
+            medal.render(hidePercent);
+        }
+    }
+}
+
+/**
+ *  @callback MedalCallbackFunction - Function that processes a medal
+ *  @param {Medal} medal
+ *  @memberof Medals
+ */
+
+/** Calls a function for each medal
+ *  @param {MedalCallbackFunction} callback
+ *  @memberof Medals */
+function medalsForEach(callback)
+{ Object.values(medals).forEach(medal=>callback(medal)); }
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Medal - Tracks an unlockable medal
+ * @memberof Medals
+ * @example
+ * // create a medal
+ * const medal_example = new Medal(0, 'Example Medal', 'More info about the medal goes here.', '🎖️');
+ *
+ * // initialize medals
+ * medalsInit('Example Game');
+ *
+ * // unlock the medal
+ * medal_example.unlock();
+ */
+class Medal
+{
+    /** Create a medal object and adds it to the list of medals
+     *  @param {number} id            - The unique identifier of the medal
+     *  @param {string} name          - Name of the medal
+     *  @param {string} [description] - Description of the medal
+     *  @param {string} [icon]        - Icon for the medal
+     *  @param {string} [src]         - Image location for the medal
+     */
+    constructor(id, name, description='', icon='🏆', src)
+    {
+        ASSERT(id >= 0 && !medals[id]);
+
+        /** @property {number} - The unique identifier of the medal */
+        this.id = id;
+
+        /** @property {string} - Name of the medal */
+        this.name = name;
+
+        /** @property {string} - Description of the medal */
+        this.description = description;
+
+        /** @property {string} - Icon for the medal */
+        this.icon = icon;
+
+        /** @property {boolean} - Is the medal unlocked? */
+        this.unlocked = false;
+
+        // load the source image if provided
+        if (src)
+            (this.image = new Image).src = src;
+
+        // add this to list of medals
+        medals[id] = this;
+    }
+
+    /** Unlocks a medal if not already unlocked */
+    unlock()
+    {
+        if (medalsPreventUnlock || this.unlocked) return;
+
+        // save the medal
+        ASSERT(medalsSaveName, 'save name must be set');
+        localStorage[this.storageKey()] = this.unlocked = true;
+        medalsDisplayQueue.push(this);
+    }
+
+    /** Render a medal
+     *  @param {number} [hidePercent] - How much to slide the medal off screen
+     */
+    render(hidePercent=0)
+    {
+        const context = mainContext;
+        const width = min(medalDisplaySize.x, mainCanvas.width);
+        const height = medalDisplaySize.y;
+        const x = mainCanvas.width - width;
+        const y = -height*hidePercent;
+        const backgroundColor = hsl(0,0,.9);
+
+        // draw containing rect and clip to that region
+        context.save();
+        context.beginPath();
+        context.fillStyle = backgroundColor.toString();
+        context.strokeStyle = BLACK.toString();
+        context.lineWidth = 3;
+        context.rect(x, y, width, height);
+        context.fill();
+        context.stroke();
+        context.clip();
+
+        // draw the icon
+        const gap = vec2(.1, .05).scale(height);
+        const medalDisplayIconSize = height - 2*gap.x;
+        this.renderIcon(vec2(x + gap.x + medalDisplayIconSize/2, y + height/2), medalDisplayIconSize);
+
+        // draw the name
+        const nameSize = height*.5;
+        const descriptionSize = height*.3;
+        const pos = vec2(x + medalDisplayIconSize + 2*gap.x, y + gap.y*2 + nameSize/2);
+        const textWidth = width - medalDisplayIconSize - 3*gap.x;
+        drawTextScreen(this.name, pos, nameSize, BLACK, 0, undefined, 'left', undefined, undefined, textWidth);
+
+        // draw the description
+        pos.y = y + height - gap.y*2 - descriptionSize/2;
+        drawTextScreen(this.description, pos, descriptionSize, BLACK, 0, undefined, 'left', undefined, undefined, textWidth);
+        context.restore();
+    }
+
+    /** Render the icon for a medal
+     *  @param {Vector2} pos - Screen space position
+     *  @param {number} size - Screen space size
+     */
+    renderIcon(pos, size)
+    {
+        // draw the image or icon
+        if (this.image)
+            mainContext.drawImage(this.image, pos.x-size/2, pos.y-size/2, size, size);
+        else
+            drawTextScreen(this.icon, pos, size*.7, BLACK);
+    }
+
+    // Get local storage key used by the medal
+    storageKey() { return medalsSaveName + '_' + this.id; }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Medals setting setters
+
+/** Set how long to show medals for in seconds
+ *  @param {number} time
+ *  @memberof Settings */
+function setMedalDisplayTime(time) { medalDisplayTime = time; }
+
+/** Set how quickly to slide on/off medals in seconds
+ *  @param {number} time
+ *  @memberof Settings */
+function setMedalDisplaySlideTime(time) { medalDisplaySlideTime = time; }
+
+/** Set size of medal display
+ *  @param {Vector2} size
+ *  @memberof Settings */
+function setMedalDisplaySize(size) { medalDisplaySize = size.copy(); }
+
+/** Set to stop medals from being unlockable
+ *  @param {boolean} preventUnlock
+ *  @memberof Settings */
+function setMedalsPreventUnlock(preventUnlock) { medalsPreventUnlock = preventUnlock; }
+
+/** 
+ * LittleJS Newgrounds Plugin
+ * - NewgroundsMedal extends Medal with Newgrounds API functionality
+ * - Call new NewgroundsPlugin(app_id) to setup Newgrounds
+ * - Uses CryptoJS for encryption if optional cipher is provided
+ * - provides functions to interact with medals scoreboards
+ * - Keeps connection alive and logs views
+ * @namespace Newgrounds
+ */
+
+/** Global Newgrounds object
+ *  @type {NewgroundsPlugin}
+ *  @memberof Newgrounds */
+let newgrounds;
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Newgrounds medal auto unlocks in newgrounds API
+ * @extends Medal
+ * @memberof Newgrounds
+ */
+class NewgroundsMedal extends Medal
+{
+    /** Create a newgrounds medal object and adds it to the list of medals
+     *  @param {number} id            - The unique identifier of the medal
+     *  @param {string} name          - Name of the medal
+     *  @param {string} [description] - Description of the medal
+     *  @param {string} [icon]        - Icon for the medal
+     *  @param {string} [src]         - Image location for the medal
+     */
+    constructor(id, name, description, icon, src)
+    { super(id, name, description, icon, src); }
+
+    /** Unlocks a medal if not already unlocked */
+    unlock()
+    {
+        super.unlock();
+        newgrounds && newgrounds.unlockMedal(this.id);
+    }
+}
 
 ///////////////////////////////////////////////////////////////////////////////
 /** 
@@ -9516,16 +9770,13 @@ class UISystemPlugin
         this.lastHoverObject = undefined;
         /** @property {UIObject} - Current confirm menu being shown */
         this.confirmDialog = undefined;
-        /** @property {UIObject} - Object to send keyboard input to */
-        this.keyInputObject = undefined;
+        /** @private */
+        this._keyInputObject = undefined;
+        /** @private */
+        this._onKeyDown = (e) => this._keyInputObject?.onKeyDown(e);
 
         engineAddPlugin(uiUpdate, uiRender);
 
-        // key down handler
-        function onKeyDown(e)
-        { uiSystem.keyInputObject?.onKeyDown(e); }
-        document.addEventListener('keydown', onKeyDown);
-
         // set object position in parent space
         function updateTransforms(o)
         {
@@ -9867,8 +10118,23 @@ class UISystemPlugin
         return p;
     }
 
+    /** Object to send keyboard input to (typically a UITextInput).
+     *  The document keydown listener is only attached while this is set,
+     *  so games that never use text input pay no event-handling cost.
+     *  @type {UIObject} */
+    get keyInputObject() { return this._keyInputObject; }
+    set keyInputObject(obj)
+    {
+        const had = !!this._keyInputObject;
+        this._keyInputObject = obj;
+        if (!had && obj)
+            document.addEventListener('keydown', this._onKeyDown);
+        else if (had && !obj)
+            document.removeEventListener('keydown', this._onKeyDown);
+    }
+
     /** Destroy and remove all objects
-    *  @memberof Engine */
+    *  @memberof UISystem */
     destroyObjects()
     {
         for (const o of this.uiObjects)
@@ -10291,15 +10557,13 @@ class UIObject
      *  @return {string} */
     toString()
     {
-        if (!debug) return;
-        
         let text = 'type = ' + this.constructor.name;
         if (this.text)
             text += '\ntext = ' + this.text;
         if (this.pos.x || this.pos.y)
             text += '\npos = ' + this.pos;
         if (this.localPos.x || this.localPos.y)
-            text += '\localPos = ' + this.localPos;
+            text += '\nlocalPos = ' + this.localPos;
         if (this.size.x || this.size.y)
             text += '\nsize = ' + this.size;
         if (this.color)
@@ -10322,7 +10586,7 @@ class UIObject
 
     /** Internal function called when object is clicked
      *  @param {boolean} [playSound] */
-    click(playSound)
+    click(playSound=true)
     {
         this.onClick(); 
         if (playSound && this.soundClick)
@@ -10893,6 +11157,135 @@ class UIVideo extends UIObject
         this.video.remove();
         super.destroy();
     }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * UILayout - A container that auto-arranges children in a vertical list, horizontal list, or grid
+ * - Set columns to 1 for a vertical list (default)
+ * - Set columns to children.length for a horizontal list
+ * - Set columns to N (1 < N < children.length) for a grid with N columns
+ * - Per-child sizing: each row's height = max child.size.y in that row, each column's width = max child.size.x in that column
+ * - Children are positioned centered in their cell
+ * - Container auto-sizes to fit children plus padding
+ * @extends UIObject
+ * @memberof UISystem
+ */
+class UILayout extends UIObject
+{
+    /** Create a UILayout container that auto-arranges children
+     *  @param {Vector2} [pos]
+     *  @param {number}  [columns=1]     - Number of columns (1 = vertical list)
+     *  @param {number}  [gap=10]        - Space between children
+     *  @param {number}  [padding=10]    - Space between container border and children
+     *  @param {boolean} [transparent=false] - If true, draws no background, outline, or shadow
+     */
+    constructor(pos, columns=1, gap=10, padding=10, transparent=false)
+    {
+        super(pos);
+
+        ASSERT(isNumber(columns) && columns >= 1, 'ui layout columns must be a number >= 1');
+        ASSERT(isNumber(gap), 'ui layout gap must be a number');
+        ASSERT(isNumber(padding), 'ui layout padding must be a number');
+
+        /** @property {number} - Number of columns in the layout */
+        this.columns = columns;
+        /** @property {number} - Space between children */
+        this.gap = gap;
+        /** @property {number} - Space between container border and children */
+        this.padding = padding;
+
+        if (transparent)
+        {
+            // pure positioning helper - skip background, outline, and shadow
+            this.color = CLEAR_BLACK;
+            this.gradientColor = undefined;
+            this.lineWidth = 0;
+            this.shadowColor = CLEAR_BLACK;
+        }
+        this.relayout();
+    }
+
+    /** Add a child UIObject and re-layout
+     *  @param {UIObject} child
+     *  @return {UIObject} The child object added */
+    addChild(child)
+    {
+        super.addChild(child);
+        this.relayout();
+        return child;
+    }
+
+    /** Remove a child UIObject and re-layout
+     *  @param {UIObject} child */
+    removeChild(child)
+    {
+        super.removeChild(child);
+        this.relayout();
+    }
+
+    /** Recompute child positions and container size based on per-child sizes.
+     *  Called automatically by addChild and removeChild. Call manually if you
+     *  mutate a child's size or change columns, gap, or padding. */
+    relayout()
+    {
+        const n = this.children.length;
+        if (!n)
+        {
+            this.size = vec2(this.padding * 2);
+            return;
+        }
+
+        const cols = this.columns;
+        const rows = ceil(n / cols);
+        const colWidths = new Array(cols).fill(0);
+        const rowHeights = new Array(rows).fill(0);
+
+        // first pass: compute column widths and row heights from child sizes
+        for (let i = 0; i < n; ++i)
+        {
+            const col = i % cols;
+            const row = floor(i / cols);
+            const child = this.children[i];
+            colWidths[col] = max(colWidths[col], child.size.x);
+            rowHeights[row] = max(rowHeights[row], child.size.y);
+        }
+
+        // total content size (sum of column widths/row heights plus gaps between them)
+        let contentWidth = this.gap * (cols - 1);
+        for (const w of colWidths) contentWidth += w;
+        let contentHeight = this.gap * (rows - 1);
+        for (const h of rowHeights) contentHeight += h;
+
+        // cumulative column/row offsets so positioning is O(n) not O(n^2)
+        const colOffsets = new Array(cols);
+        let xAcc = 0;
+        for (let c = 0; c < cols; ++c)
+        {
+            colOffsets[c] = xAcc;
+            xAcc += colWidths[c];
+        }
+        const rowOffsets = new Array(rows);
+        let yAcc = 0;
+        for (let r = 0; r < rows; ++r)
+        {
+            rowOffsets[r] = yAcc;
+            yAcc += rowHeights[r];
+        }
+
+        // second pass: position each child centered in its cell
+        for (let i = 0; i < n; ++i)
+        {
+            const col = i % cols;
+            const row = floor(i / cols);
+            const x = -contentWidth/2 + colOffsets[col] + this.gap * col + colWidths[col] / 2;
+            const y = -contentHeight/2 + rowOffsets[row] + this.gap * row + rowHeights[row] / 2;
+            this.children[i].localPos = vec2(x, y);
+        }
+
+        // container size = content + padding on all sides
+        this.size = vec2(contentWidth + this.padding * 2, contentHeight + this.padding * 2);
+    }
 }
 /**
  * LittleJS Box2D Physics Plugin
@@ -11295,7 +11688,8 @@ class Box2dObject extends EngineObject
     {
         this.pos = pos;
         this.angle = angle;
-        this.body.SetTransform(box2d.vec2dTo(pos), angle);
+        // box2d uses reverse angle
+        this.body.SetTransform(box2d.vec2dTo(pos), -angle);
     }
     
     /** Sets the position
@@ -11306,7 +11700,7 @@ class Box2dObject extends EngineObject
     /** Sets the angle
      *  @param {number} angle */
     setAngle(angle)
-    { this.setTransform(box2d.vec2From(this.body.GetPosition()), -angle); }
+    { this.setTransform(box2d.vec2From(this.body.GetPosition()), angle); }
 
     /** Sets the linear velocity
      *  @param {Vector2} velocity */
@@ -11418,14 +11812,29 @@ class Box2dObject extends EngineObject
         this.body.ApplyForce(box2d.vec2dTo(force), box2d.vec2dTo(pos));
     }
 
-    /** Apply acceleration to this object
+    /** Apply acceleration to this object (changes velocity by acceleration,
+     *  mass-independent — matches EngineObject.applyAcceleration semantics).
+     *  Use applyImpulse if you want the mass-dependent velocity change
+     *  Δv = impulse / mass, or applyForce for a Newton-style sustained force.
      *  @param {Vector2} acceleration
      *  @param {Vector2} [pos] */
     applyAcceleration(acceleration, pos)
-    { 
+    {
         pos ||= this.getCenterOfMass();
         this.setAwake();
-        this.body.ApplyLinearImpulse(box2d.vec2dTo(acceleration), box2d.vec2dTo(pos));
+        const impulse = acceleration.scale(this.getMass());
+        this.body.ApplyLinearImpulse(box2d.vec2dTo(impulse), box2d.vec2dTo(pos));
+    }
+
+    /** Apply an instantaneous linear impulse. Changes velocity immediately by
+     *  impulse / mass (so heavier bodies move less for the same impulse).
+     *  @param {Vector2} impulse
+     *  @param {Vector2} [pos] */
+    applyImpulse(impulse, pos)
+    {
+        pos ||= this.getCenterOfMass();
+        this.setAwake();
+        this.body.ApplyLinearImpulse(box2d.vec2dTo(impulse), box2d.vec2dTo(pos));
     }
 
     /** Apply torque to this object
@@ -11435,13 +11844,23 @@ class Box2dObject extends EngineObject
         this.setAwake();
         this.body.ApplyTorque(torque);
     }
-    
-    /** Apply angular acceleration to this object
+
+    /** Apply angular acceleration to this object (changes angular velocity by
+     *  acceleration, mass-independent — matches EngineObject semantics).
      *  @param {number} acceleration */
     applyAngularAcceleration(acceleration)
     {
         this.setAwake();
-        this.body.ApplyAngularImpulse(acceleration);
+        this.body.ApplyAngularImpulse(acceleration * this.getInertia());
+    }
+
+    /** Apply an instantaneous angular impulse. Changes angular velocity by
+     *  impulse / inertia immediately.
+     *  @param {number} impulse */
+    applyAngularImpulse(impulse)
+    {
+        this.setAwake();
+        this.body.ApplyAngularImpulse(impulse);
     }
 
     ///////////////////////////////////////////////////////////////////////////////
@@ -11687,7 +12106,7 @@ class Box2dJoint
     
     /** Check if the connected bodies should collide
      *  @return {boolean} */
-    getCollideConnected()   { return this.box2dJoint.getCollideConnected();}
+    getCollideConnected()   { return this.box2dJoint.GetCollideConnected();}
 
     /** Check if either connected body is active
      *  @return {boolean} */
@@ -12851,6 +13270,7 @@ async function box2dInit()
         {
             if (o.body)
             {
+                // box2d uses reverse angle
                 o.pos = box2d.vec2From(o.body.GetPosition());
                 o.angle = -o.body.GetAngle();
             }
@@ -13061,3 +13481,1268 @@ function drawThreeSlice(pos, size, startTile, color, borderSize=1, additiveColor
         drawTile(pos.add(cornerPos.rotate(rotateAngle)), cornerSize, cornerTile, color, a, false, additiveColor, useWebGL, screenSpace, context);
     }
 }
+/**
+ * LittleJS Tween System Plugin
+ * - Lightweight tweens for numbers, Vector2, Color, or any .lerp-able type
+ * - Chainable easing, looping, and ping-pong
+ * - Property-path helper for the common case of animating an object field
+ * - Auto-updates via engineAddPlugin; pauses with the game by default
+ * @namespace TweenSystem
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+
+// Module-private list of tweens currently running.
+const tweenActive = [];
+
+// Time tracking for delta computation between engine plugin calls.
+let lastTime = 0;
+let lastTimeReal = 0;
+
+// True if the value is an instance of a class that exposes a numeric-percent
+// `lerp(other, percent)` method (Vector2, Color, or any future class).
+function isLerpable(v) { return v && typeof v.lerp === 'function'; }
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** A numeric tween: drives a callback with a value interpolated between
+ *  `start` and `end` over `duration` seconds. Pauses with the game by default.
+ *  @memberof TweenSystem
+ *  @example
+ *  // Animate a fade-out over 2 seconds with an ease-out sine curve.
+ *  new Tween((v) => obj.alpha = v, 1, 0, 2, { ease: Ease.OUT(Ease.SINE) });
+ */
+class Tween
+{
+    /** Create a new tween. The callback fires immediately with `start` so the
+     *  target snaps to the start value on the same frame the tween is created.
+     *
+     *  `start` and `end` may be numbers, Vector2 instances, Color instances, or
+     *  any object exposing a `lerp(other, percent) => sameType` method. The
+     *  callback receives the interpolated value (a number, or a fresh instance
+     *  for lerp-able types). Both endpoints must be the same type.
+     *  @param {function(number|Vector2|Color):void} callback - Called with the interpolated value each frame
+     *  @param {number|Vector2|Color} [start=0] - Starting value
+     *  @param {number|Vector2|Color} [end=1] - Ending value
+     *  @param {number} [duration=1] - Duration in seconds
+     *  @param {Object} [options]
+     *  @param {function(number):number} [options.ease] - Easing function (defaults to LINEAR)
+     *  @param {boolean} [options.useRealTime=false] - Advance even when the game is paused (matches Timer's useRealTime)
+     *  @param {boolean} [options.paused=false] - Start in paused state */
+    constructor(callback, start = 0, end = 1, duration = 1, options = {})
+    {
+        ASSERT(typeof callback === 'function', 'Tween callback must be a function');
+        if (isLerpable(start))
+        {
+            ASSERT(start.constructor === end.constructor,
+                'Tween start and end must be the same type');
+        }
+        else
+        {
+            ASSERT(isNumber(start), 'Tween start must be a number or have a .lerp method');
+            ASSERT(isNumber(end),   'Tween end must be a number when start is a number');
+        }
+        ASSERT(isNumber(duration) && duration > 0, 'Tween duration must be > 0');
+
+        this.callback = callback;
+        this.start = start;
+        this.end = end;
+        this.duration = duration;
+        this.life = duration;
+        this.ease = options.ease || Ease.LINEAR;
+        this.useRealTime = !!options.useRealTime;
+        this.paused = !!options.paused;
+
+        /** @private completion callback set by then(), loop(), pingPong(). */
+        this.thenCallback = undefined;
+        /** @private remaining iterations including the current run (loop/pingPong only). */
+        this.loopRemaining = 0;
+
+        tweenActive.push(this);
+        // Snap target to start immediately.
+        callback(this.interp(duration));
+    }
+
+    /** Set the easing curve and return this for chaining.
+     *  @param {function(number):number} easeFn
+     *  @returns {Tween}
+     *  @memberof TweenSystem */
+    setEase(easeFn)
+    {
+        this.ease = easeFn;
+        return this;
+    }
+
+    /** Set a single completion callback. Calling `then` again replaces the
+     *  previous callback. Returns this for chaining.
+     *
+     *  Calling `then` after `loop` or `pingPong` overrides the loop chain
+     *  (last call wins).
+     *  @param {function():void} callback
+     *  @returns {Tween}
+     *  @memberof TweenSystem */
+    then(callback)
+    {
+        this.thenCallback = callback;
+        this.loopRemaining = 0;
+        return this;
+    }
+
+    /** Repeat this tween `n` total times. After each iteration finishes, a
+     *  fresh tween with the same parameters takes over via the `then` slot.
+     *  `loop()` with no argument loops forever.
+     *
+     *  Mutually exclusive with `pingPong`; calling either replaces the other,
+     *  and calling `then` after either clears the loop (last call wins).
+     *  @param {number} [count=Infinity]
+     *  @returns {Tween}
+     *  @memberof TweenSystem */
+    loop(count = Infinity)
+    {
+        this.loopRemaining = count;
+        this.thenCallback = () => loopContinuation(this);
+        return this;
+    }
+
+    /** Like `loop`, but swap `start` and `end` between iterations so the value
+     *  bounces back and forth. `pingPong()` with no argument bounces forever.
+     *
+     *  Mutually exclusive with `loop`; calling either replaces the other, and
+     *  calling `then` after either clears the loop (last call wins).
+     *  @param {number} [count=Infinity]
+     *  @returns {Tween}
+     *  @memberof TweenSystem */
+    pingPong(count = Infinity)
+    {
+        this.loopRemaining = count;
+        this.thenCallback = () => pingPongContinuation(this);
+        return this;
+    }
+
+    /** Pause this tween. While paused, tweenUpdate skips it.
+     *  @memberof TweenSystem */
+    pause() { this.paused = true; }
+
+    /** Resume a paused tween.
+     *  @memberof TweenSystem */
+    resume() { this.paused = false; }
+
+    /** Reset this tween to the start: life back to duration, pause cleared,
+     *  re-added to the active list if previously stopped, and the callback
+     *  re-fired with the start value.
+     *  @memberof TweenSystem */
+    restart()
+    {
+        this.life = this.duration;
+        this.paused = false;
+        if (tweenActive.indexOf(this) < 0) tweenActive.push(this);
+        this.callback(this.interp(this.duration));
+    }
+
+    /** True if this tween is in the active list and not paused.
+     *  @returns {boolean}
+     *  @memberof TweenSystem */
+    isActive()
+    {
+        return !this.paused && tweenActive.indexOf(this) >= 0;
+    }
+
+    /** Get how far this tween has progressed, from 0 (just started) to 1
+     *  (completed). Clamped — overshoot past completion still reads 1.
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    getPercent()
+    {
+        return percent(this.duration - this.life, 0, this.duration);
+    }
+
+    /** Get the current interpolated value (the value most recently passed to
+     *  the callback). Returns a number, Vector2, or Color depending on the
+     *  tween's start/end types.
+     *  @returns {number|Vector2|Color}
+     *  @memberof TweenSystem */
+    getValue()
+    {
+        return this.interp(this.life);
+    }
+
+    /** Compute the interpolated value at the given remaining `life`.
+     *  At life === duration the result is `start`; at life === 0 it is `end`.
+     *  @param {number} life
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    interp(life)
+    {
+        const x = this.ease((this.duration - life) / this.duration);
+        if (isLerpable(this.start))
+            return this.start.lerp(this.end, x);
+        return this.start + (this.end - this.start) * x;
+    }
+
+    /** Remove this tween from the active list and prevent any pending then-callback.
+     *  @memberof TweenSystem */
+    stop()
+    {
+        const i = tweenActive.indexOf(this);
+        if (i >= 0) tweenActive.splice(i, 1);
+        this.thenCallback = undefined;
+    }
+}
+
+/** Library of named easing curves and direction modifiers.
+ *  All curves accept `x` in [0,1] and return [0,1] (with possible overshoot
+ *  for ELASTIC/BACK/SPRING/BOUNCE). Curves are values you pass to `setEase`
+ *  or compose via the IN/OUT/IN_OUT/PIECEWISE/BEZIER modifiers.
+ *  @memberof TweenSystem
+ *  @example
+ *  // Use a basic curve
+ *  new Tween(callback, 0, 10, 1).setEase(Ease.SINE);
+ *  // Use a modifier on a curve
+ *  new Tween(callback, 0, 10, 1).setEase(Ease.OUT(Ease.BACK));
+ */
+const Ease =
+{
+    /** Linear (identity) curve.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    LINEAR: (x) => x,
+
+    /** Power curve factory: `Ease.POWER(n)` returns `x => x**n`.
+     *  Use n=2 for quadratic, n=3 for cubic, etc.
+     *  @param {number} n
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem */
+    POWER: (n) => (x) => x ** n,
+
+    /** Sine ease-in curve: starts slow, ends fast.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    SINE: (x) => 1 - cos(x * (PI / 2)),
+
+    /** Circular ease-in curve.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    CIRC: (x) => 1 - (1 - x * x)**.5,
+
+    /** Exponential ease-in curve (`2^(10x-10)`).
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    EXPO: (x) => 2 ** (10 * x - 10),
+
+    /** Back ease-in: overshoots backward at the start before snapping forward.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    BACK: (x) => x * x * (2.70158 * x - 1.70158),
+
+    /** Elastic ease-in: oscillates with decreasing amplitude.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    ELASTIC: (x) =>
+        -(2 ** (10 * x - 10)) * sin(((37 - 40 * x) * PI) / 6),
+
+    /** Spring-like ease-out: oscillates outward after passing the target.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem */
+    SPRING: (x) =>
+        1 -
+        (sin(PI * (1 - x) * (0.2 + 2.5 * (1 - x) ** 3)) *
+            x ** 2.2 +
+            (1 - x)) *
+            (1.0 + 1.2 * x),
+
+    /** Bouncing ease-in: slow ramp with bouncing impacts near the end.
+     *  Symmetric with the other base curves, which are all ease-in. To get the
+     *  classic "object falls and hits the ground" shape (bounces near x=1),
+     *  wrap with `Ease.OUT`: `Ease.OUT(Ease.BOUNCE)`.
+     *  @param {number} x
+     *  @returns {number}
+     *  @memberof TweenSystem
+     *  @example
+     *  Ease.BOUNCE                  // ease-in bounce (slow, then bouncy at end)
+     *  Ease.OUT(Ease.BOUNCE)        // ease-out bounce (object hits ground)
+     *  Ease.IN_OUT(Ease.BOUNCE)     // bounces at both ends
+     */
+    BOUNCE: (x) =>
+    {
+        // Inverted form of the standard easeOutBounce: 1 - bounceOut(1 - x).
+        let t = 1 - x, f;
+        if (t < 4 / 11) f = 7.5625 * t * t;
+        else if (t < 8 / 11) f = 7.5625 * (t -= 6 / 11) * t + 0.75;
+        else if (t < 10 / 11) f = 7.5625 * (t -= 9 / 11) * t + 0.9375;
+        else f = 7.5625 * (t -= 10.5 / 11) * t + 0.984375;
+        return 1 - f;
+    },
+
+    /** Ease-in direction modifier: returns the curve unchanged. Symmetric
+     *  with `OUT` and `IN_OUT`. Base curves are already ease-in by
+     *  convention, so wrapping a curve in `IN` is a no-op — useful when
+     *  picking the direction programmatically.
+     *  @param {function(number):number} f - Curve to use as ease-in (returned unchanged)
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem
+     *  @example
+     *  // Pick direction at runtime
+     *  const dir = bouncyMode ? Ease.OUT : Ease.IN;
+     *  new Tween(cb, 0, 10, 1).setEase(dir(Ease.BACK));
+     */
+    IN: (f) => f,
+
+    /** Reverse a curve so it eases out instead of in: `x => 1 - f(1 - x)`.
+     *  @param {function(number):number} f
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem
+     *  @example
+     *  Ease.OUT(Ease.POWER(2)) // ease-out quadratic
+     */
+    OUT: (f) => (x) => 1 - f(1 - x),
+
+    /** Combine the first half of `f` with `Ease.OUT(f)` for a symmetric curve.
+     *  Bug-fix vs the original library: the original referenced an undefined
+     *  global `Piecewise`; this implementation routes through `Ease.PIECEWISE`.
+     *  @param {function(number):number} f
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem */
+    IN_OUT: (f) => Ease.PIECEWISE(f, Ease.OUT(f)),
+
+    /** Split [0,1] into N equal sections and run a different curve in each.
+     *  Each curve is mapped to its section: section i runs over [i/n, (i+1)/n]
+     *  and its output is mapped to [i/n, (i+1)/n] of the overall range.
+     *  @param {...function(number):number} fns
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem */
+    PIECEWISE: (...fns) =>
+    {
+        const n = fns.length;
+        return (x) =>
+        {
+            const i = (x * n - 1e-9) >> 0;
+            return (fns[i]((x - i / n) * n) + i) / n;
+        };
+    },
+
+    /** Cubic Bezier curve solver in the style of CSS `cubic-bezier`.
+     *  Control points (0,0), (x1,y1), (x2,y2), (1,1).
+     *  @param {number} x1
+     *  @param {number} y1
+     *  @param {number} x2
+     *  @param {number} y2
+     *  @returns {function(number):number}
+     *  @memberof TweenSystem
+     *  @example
+     *  Ease.BEZIER(0.25, 0.1, 0.25, 1) // CSS "ease"
+     */
+    BEZIER: (x1, y1, x2, y2) =>
+    {
+        // Parametric cubic Bezier with implicit (0,0) and (1,1) endpoints.
+        const curve = (t) =>
+        {
+            const u = 1 - t;
+            const c1 = 3 * u * u * t;
+            const c2 = 3 * u * t * t;
+            const t3 = t ** 3;
+            return [c1 * x1 + c2 * x2 + t3, c1 * y1 + c2 * y2 + t3];
+        };
+        return (x) =>
+        {
+            // Binary search for t such that curve(t).x ≈ x, then return curve(t).y.
+            let t0 = 0, t1 = 1;
+            for (let i = 0; i < 128; i++)
+            {
+                const tMid = (t0 + t1) / 2;
+                const [bx, by] = curve(tMid);
+                if (abs(bx - x) < 1e-5) return by;
+                if (bx < x) t0 = tMid; else t1 = tMid;
+            }
+            return curve((t0 + t1) / 2)[1];
+        };
+    },
+};
+
+/** Tween a property on an object by dot-path. Returns the underlying Tween
+ *  so all chaining methods (`setEase`, `then`, `loop`, `pingPong`, etc.)
+ *  remain available.
+ *
+ *  `start` and `end` may be numbers, Vector2 instances, Color instances, or
+ *  any object with a `lerp(other, percent) => sameType` method.
+ *  @param {Object} target - The object whose property is being animated
+ *  @param {string} propertyPath - Dot-separated path, e.g. `'pos.x'` or `'color'`
+ *  @param {number|Vector2|Color} start - Starting value
+ *  @param {number|Vector2|Color} end - Ending value
+ *  @param {number} [duration=1] - Duration in seconds
+ *  @param {Object} [options] - Same options as the Tween constructor
+ *  @returns {Tween}
+ *  @memberof TweenSystem
+ *  @example
+ *  // Numeric: slide an object's x with an ease-out sine curve
+ *  tweenProperty(player, 'pos.x', 0, 10, 2).setEase(Ease.OUT(Ease.SINE));
+ *  // Vector2: animate a position diagonally
+ *  tweenProperty(player, 'pos', vec2(-5, 0), vec2(5, 3), 2);
+ *  // Color: pulse between two colors
+ *  tweenProperty(sprite, 'color', RED, BLUE, 1).pingPong();
+ */
+function tweenProperty(target, propertyPath, start, end, duration = 1, options = {})
+{
+    ASSERT(target != null && typeof target === 'object', 'tweenProperty target must be an object');
+    ASSERT(isString(propertyPath) && propertyPath.length > 0, 'tweenProperty propertyPath must be a non-empty string');
+
+    const parts = propertyPath.split('.');
+    const lastKey = parts.pop();
+    const callback = (value) =>
+    {
+        let obj = target;
+        for (const k of parts) obj = obj[k];
+        obj[lastKey] = value;
+    };
+    return new Tween(callback, start, end, duration, options);
+}
+
+// Continuation that schedules the next loop iteration when one finishes.
+// Called from the completed tween's `then` slot. Decrements the counter and
+// only spawns a new tween if more iterations remain.
+function loopContinuation(prev)
+{
+    if (prev.loopRemaining !== Infinity && prev.loopRemaining <= 1) return;
+    const next = new Tween(prev.callback, prev.start, prev.end, prev.duration,
+        { ease: prev.ease, useRealTime: prev.useRealTime });
+    next.loopRemaining = prev.loopRemaining === Infinity
+        ? Infinity
+        : prev.loopRemaining - 1;
+    next.thenCallback = () => loopContinuation(next);
+}
+
+// Continuation for pingPong: spawns a new tween with start and end swapped.
+function pingPongContinuation(prev)
+{
+    if (prev.loopRemaining !== Infinity && prev.loopRemaining <= 1) return;
+    const next = new Tween(prev.callback, prev.end, prev.start, prev.duration,
+        { ease: prev.ease, useRealTime: prev.useRealTime });
+    next.loopRemaining = prev.loopRemaining === Infinity
+        ? Infinity
+        : prev.loopRemaining - 1;
+    next.thenCallback = () => pingPongContinuation(next);
+}
+
+/** Engine plugin hook: advance every active tween by the appropriate delta.
+ *  Called once per render frame by the engine (no arguments). May also be
+ *  called explicitly with `(gameDelta, realDelta)` to drive tweens manually
+ *  — useful for headless tests or custom replay/scrubbing systems.
+ *  @param {number} [gameDelta] - Game-time delta in seconds; default: time - lastTime
+ *  @param {number} [realDelta] - Real-time delta in seconds; default: timeReal - lastTimeReal
+ *  @memberof TweenSystem */
+function tweenUpdate(gameDelta, realDelta)
+{
+    if (gameDelta === undefined)
+    {
+        // Engine path: compute deltas from engine time globals.
+        gameDelta = time - lastTime;
+        realDelta = timeReal - lastTimeReal;
+        lastTime = time;
+        lastTimeReal = timeReal;
+    }
+    else if (realDelta === undefined)
+    {
+        // Manual path with one arg: real and game advance together.
+        realDelta = gameDelta;
+    }
+
+    // Iterate in reverse so removals don't disturb iteration.
+    for (let i = tweenActive.length; i--;)
+    {
+        const t = tweenActive[i];
+        if (t.paused) continue;
+        const dt = t.useRealTime ? realDelta : gameDelta;
+        if (dt <= 0) continue;
+
+        t.life -= dt;
+        if (t.life > 0)
+        {
+            t.callback(t.interp(t.life));
+        }
+        else
+        {
+            // Completion: fire end value, remove from active, fire then-callback.
+            t.callback(t.interp(0));
+            tweenActive.splice(i, 1);
+            const cb = t.thenCallback;
+            t.thenCallback = undefined;
+            if (cb) cb();
+        }
+    }
+}
+
+/** Stop every active tween and clear their then-callbacks. Useful for resets
+ *  on level transitions or when changing scenes.
+ *  @memberof TweenSystem */
+function tweenStopAll()
+{
+    for (const t of tweenActive) t.thenCallback = undefined;
+    tweenActive.length = 0;
+}
+
+// Register with the engine so tweens auto-advance.
+engineAddPlugin(tweenUpdate);
+
+/**
+ * LittleJS PathFinder Plugin
+ * - Grid-based A* pathfinder with two-pass smoothing for natural-looking paths
+ * - Works directly on a TileCollisionLayer, or override isWalkable/getCost for any grid
+ * - Debug visualization via engine debug primitives (stripped in release builds)
+ * - Port of frankforce.com pathFindingBase.cpp (2018)
+ * @namespace PathFinding
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+
+// Diagonal step cost — pre-computed for the A* expansion inner loop.
+const PATHFINDER_DIAGONAL_COST = Math.SQRT2;
+
+// Shared 1x1 size vector for per-tile debugRect calls. debugRect copies the
+// argument internally, so reusing one instance is safe.
+const PATHFINDER_TILE_VEC = vec2(1);
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** A single grid cell tracked by the pathfinder. Allocated once per cell at
+ *  PathFinder construction; reset (not reallocated) at the start of every
+ *  findPath call.
+ *  @memberof PathFinding */
+class PathFinderNode
+{
+    /** @param {number} x - Tile x
+     *  @param {number} y - Tile y */
+    constructor(x, y)
+    {
+        /** @property {Vector2} - Tile coords (integer) */
+        this.pos = vec2(x, y);
+        /** @property {Vector2} - World-space center of this tile (set by buildNodeData) */
+        this.posWorld = vec2();
+        /** @property {boolean} - True if this cell is passable (cleared each findPath call) */
+        this.walkable = false;
+        /** @property {number} - Extra cost added to A* G-score for stepping on this cell */
+        this.cost = 0;
+        /** @property {number} - A* G-score: actual cost from start to this node */
+        this.g = 0;
+        /** @property {number} - A* F-score: G + heuristic */
+        this.f = 0;
+        /** @property {PathFinderNode|null} - Parent for path reconstruction */
+        this.parent = null;
+        /** @property {boolean} - In the A* open list */
+        this.isOpen = false;
+        /** @property {boolean} - In the A* closed list */
+        this.isClosed = false;
+    }
+
+    /** Reset per-search state (called at the start of buildNodeData). */
+    reset()
+    {
+        this.walkable = false;
+        this.cost = 0;
+        this.g = 0;
+        this.f = 0;
+        this.parent = null;
+        this.isOpen = false;
+        this.isClosed = false;
+    }
+
+    /** True if walkable and not blocked by cost. */
+    isClear()
+    {
+        return this.walkable && this.cost === 0;
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Grid pathfinder using A* with two optional smoothing passes.
+ *  @memberof PathFinding
+ *  @example
+ *  // Tile-layer driven (most common):
+ *  const pf = new PathFinder(myTileCollisionLayer);
+ *  const path = pf.findPath(player.pos, mousePos);
+ *
+ *  // Bare grid with custom walkability:
+ *  const pf = new PathFinder(vec2(50, 50));
+ *  pf.isWalkable = (x, y) => myGrid[y*50 + x] === 0;
+ */
+class PathFinder
+{
+    /** @param {TileCollisionLayer|Vector2} source - Either a TileCollisionLayer
+     *  (size and walkability auto-derived) or a Vector2 grid size (user
+     *  overrides isWalkable). */
+    constructor(source)
+    {
+        // Accept either a Vector2 size or a TileCollisionLayer (which has a .size).
+        // We don't import TileCollisionLayer to avoid coupling; we duck-type on
+        // .size + .getCollisionData.
+        if (isVector2(source))
+        {
+            this.size = source.floor();
+            this.tileLayer = undefined;
+        }
+        else
+        {
+            ASSERT(source && isVector2(source.size) && typeof source.getCollisionData === 'function',
+                'PathFinder requires a Vector2 size or a TileCollisionLayer');
+            this.size = source.size;
+            this.tileLayer = source;
+        }
+
+        // Tunables (public, freely re-assignable).
+        this.heuristicWeight = 1;
+        this.maxLoop = 500;
+        this.smoothPath = true;
+        this.debug = false;
+        this.debugTime = 2;
+
+        // Pre-allocate the node array — one node per tile, reused across calls.
+        this.nodes = new Array(this.size.x * this.size.y);
+        for (let y = 0; y < this.size.y; ++y)
+        for (let x = 0; x < this.size.x; ++x)
+            this.nodes[x + y * this.size.x] = new PathFinderNode(x, y);
+
+        // Scratch Vector2 reused to avoid allocations in the isWalkable hot path.
+        this.collisionScratch = vec2();
+    }
+
+    /** Default walkability: if a tile layer was provided, returns true when the
+     *  cell has no solid collision data; otherwise returns true. Override on
+     *  the instance or via a subclass.
+     *  @param {number} x - Tile x
+     *  @param {number} y - Tile y
+     *  @returns {boolean} */
+    isWalkable(x, y)
+    {
+        if (!this.tileLayer) return true;
+        return !this.tileLayer.getCollisionData(this.collisionScratch.set(x, y));
+    }
+
+    /** Default extra cost for stepping on a cell. Returns 0 (free) by default.
+     *  Override to add cost-weighted terrain (mud, swamp, etc).
+     *  @param {number} x - Tile x
+     *  @param {number} y - Tile y
+     *  @returns {number} */
+    getCost(x, y)
+    {
+        return 0;
+    }
+
+    /** Get the node at tile coords, or null if out of bounds.
+     *  @param {number} x
+     *  @param {number} y
+     *  @returns {PathFinderNode|null} */
+    getNode(x, y)
+    {
+        if (x < 0 || y < 0 || x >= this.size.x || y >= this.size.y) return null;
+        return this.nodes[x + y * this.size.x];
+    }
+
+    /** Convert a world-space position to integer tile coords (no clamping).
+     *  @param {Vector2} worldPos
+     *  @returns {Vector2}
+     *  @memberof PathFinding */
+    worldToTile(worldPos)
+    {
+        const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
+        const oy = this.tileLayer ? this.tileLayer.pos.y : 0;
+        return vec2(floor(worldPos.x - ox), floor(worldPos.y - oy));
+    }
+
+    /** Convert integer tile coords to the world-space center of that tile.
+     *  @param {number} x
+     *  @param {number} y
+     *  @returns {Vector2}
+     *  @memberof PathFinding */
+    tileToWorld(x, y)
+    {
+        const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
+        const oy = this.tileLayer ? this.tileLayer.pos.y : 0;
+        return vec2(x + 0.5 + ox, y + 0.5 + oy);
+    }
+
+    /** Reset all nodes and re-populate walkable / cost / posWorld from the
+     *  current isWalkable / getCost overrides. Called at the start of
+     *  findPath; exposed so tests and tooling can drive it directly.
+     *  @private */
+    buildNodeData()
+    {
+        const w = this.size.x;
+        const h = this.size.y;
+        const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
+        const oy = this.tileLayer ? this.tileLayer.pos.y : 0;
+        for (let y = 0; y < h; ++y)
+        for (let x = 0; x < w; ++x)
+        {
+            const node = this.nodes[x + y * w];
+            node.reset();
+            const walkable = !!this.isWalkable(x, y);
+            const cost = walkable ? max(0, this.getCost(x, y)) : 0;
+            node.walkable = walkable;
+            node.cost = cost;
+            node.posWorld.set(x + 0.5 + ox, y + 0.5 + oy);
+
+            if (this.debug && this.debugTime > 0)
+            {
+                if (!walkable)
+                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, 0.25), this.debugTime);
+                else if (cost > 0)
+                    debugRect(node.posWorld, PATHFINDER_TILE_VEC, rgb(1, 0, 0, min(0.2, cost * 0.05)), this.debugTime);
+            }
+        }
+    }
+
+    /** Core A* search loop. Expects buildNodeData() to have been called first.
+     *  Marks node.parent for path reconstruction. Returns true if endNode was
+     *  reached; false on disconnected goal or maxLoop exhaustion.
+     *  @param {PathFinderNode} startNode
+     *  @param {PathFinderNode} endNode
+     *  @returns {boolean}
+     *  @private */
+    aStarSearch(startNode, endNode)
+    {
+        ASSERT(startNode && endNode, 'aStarSearch needs both endpoints');
+        ASSERT(startNode !== endNode, 'aStarSearch: start and end must differ — caller should handle trivial case');
+        ASSERT(startNode.walkable && endNode.walkable, 'aStarSearch: endpoints must be walkable');
+
+        const openList = [startNode];
+        startNode.isOpen = true;
+        let loopCount = 0;
+
+        while (openList.length > 0)
+        {
+            // Find the open node with the smallest f score (linear scan).
+            // Same as the C++ — fine up to a few thousand nodes.
+            let bestIndex = 0;
+            let bestF = openList[0].f;
+            for (let i = 1; i < openList.length; ++i)
+            {
+                if (openList[i].f < bestF)
+                {
+                    bestF = openList[i].f;
+                    bestIndex = i;
+                }
+            }
+            const current = openList[bestIndex];
+
+            if (current === endNode) break;
+            if (++loopCount > this.maxLoop) break;
+
+            // Move current from open to closed.
+            current.isOpen = false;
+            openList.splice(bestIndex, 1);
+            current.isClosed = true;
+
+            if (this.debug && this.debugTime > 0)
+                debugRect(current.posWorld, PATHFINDER_TILE_VEC, rgb(1, 1, 1, 0.05), this.debugTime);
+
+            // Expand all 8 neighbors.
+            for (let dy = -1; dy <= 1; ++dy)
+            for (let dx = -1; dx <= 1; ++dx)
+            {
+                if (dx === 0 && dy === 0) continue;
+                const neighbor = this.getNode(current.pos.x + dx, current.pos.y + dy);
+                if (!neighbor || !neighbor.walkable || neighbor.isClosed) continue;
+
+                let stepCost = 1;
+                if (dx !== 0 && dy !== 0)
+                {
+                    // Diagonal step: refuse if either cardinal neighbor is
+                    // blocked or has cost. Prevents cutting through corners.
+                    const card1 = this.getNode(current.pos.x + dx, current.pos.y);
+                    if (!card1 || card1.cost > 0 || !card1.walkable) continue;
+                    const card2 = this.getNode(current.pos.x, current.pos.y + dy);
+                    if (!card2 || card2.cost > 0 || !card2.walkable) continue;
+                    stepCost = PATHFINDER_DIAGONAL_COST;
+                }
+
+                const tentativeG = current.g + stepCost + neighbor.cost;
+                if (!neighbor.isOpen)
+                {
+                    neighbor.isOpen = true;
+                    openList.push(neighbor);
+                }
+                else if (tentativeG >= neighbor.g)
+                {
+                    continue;
+                }
+
+                // Best path so far through neighbor — record it.
+                neighbor.parent = current;
+                neighbor.g = tentativeG;
+                const gdx = endNode.pos.x - neighbor.pos.x;
+                const gdy = endNode.pos.y - neighbor.pos.y;
+                neighbor.f = neighbor.g + (gdx * gdx + gdy * gdy) * this.heuristicWeight;
+            }
+        }
+
+        return endNode.parent !== null;
+    }
+
+    /** Find the clear (walkable, zero-cost) node closest to the given world
+     *  position. Spirals outward in expanding boxes until a clear node is
+     *  found or the search range is exhausted. Useful for snapping a click
+     *  or NPC spawn position to the nearest open tile.
+     *
+     *  By default, calls `buildNodeData()` first so it works correctly on a
+     *  fresh PathFinder. If you're calling it many times in a row with
+     *  unchanged walkability, pass `rebuild=false` and call `buildNodeData()`
+     *  once externally to avoid redundant work.
+     *  @param {Vector2} worldPos
+     *  @param {number} [searchRange=10] - Max box-radius in tiles
+     *  @param {boolean} [rebuild=true] - Whether to call buildNodeData first
+     *  @returns {PathFinderNode|null}
+     *  @memberof PathFinding */
+    getNearestClearNode(worldPos, searchRange = 10, rebuild = true)
+    {
+        ASSERT(isVector2(worldPos), 'worldPos must be a Vector2');
+        if (rebuild) this.buildNodeData();
+
+        // Inline worldToTile to avoid a Vector2 allocation per call.
+        const ox = this.tileLayer ? this.tileLayer.pos.x : 0;
+        const oy = this.tileLayer ? this.tileLayer.pos.y : 0;
+        const centerX = floor(worldPos.x - ox);
+        const centerY = floor(worldPos.y - oy);
+
+        for (let offset = 0; offset <= searchRange; ++offset)
+        {
+            let nearest = null;
+            let nearestDistSq = 0;
+
+            for (let dy = -offset; dy <= offset; ++dy)
+            for (let dx = -offset; dx <= offset; ++dx)
+            {
+                // Only scan the perimeter of the current ring (skip the
+                // interior we've already searched in earlier iterations).
+                if (offset > 0 && abs(dx) !== offset && abs(dy) !== offset)
+                    continue;
+
+                const node = this.getNode(centerX + dx, centerY + dy);
+                if (!node || !node.isClear()) continue;
+
+                const ddx = node.posWorld.x - worldPos.x;
+                const ddy = node.posWorld.y - worldPos.y;
+                const distSq = ddx * ddx + ddy * ddy;
+                if (!nearest || distSq < nearestDistSq)
+                {
+                    nearest = node;
+                    nearestDistSq = distSq;
+                }
+            }
+            if (nearest) return nearest;
+        }
+        return null;
+    }
+
+    /** Smooth a node path by removing redundant turns and tightening corners
+     *  where a grid-aligned diagonal is clear. Modifies the path in place.
+     *  Stays on the grid — does not introduce off-tile-center points.
+     *  Port of ShortenPath() in pathFinding.cpp.
+     *  @param {PathFinderNode[]} path
+     *  @private */
+    smoothPathCorners(path)
+    {
+        if (path.length <= 2) return;
+
+        let i = 1;
+        while (i < path.length - 1)
+        {
+            const prev = path[i - 1];
+            const node = path[i];
+            const next = path[i + 1];
+
+            const dx = next.pos.x - prev.pos.x;
+            const dy = next.pos.y - prev.pos.y;
+            const lenSq = dx * dx + dy * dy;
+
+            // dx,dy is the prev-to-current step direction; needed for the
+            // 135° "mostly vertical/horizontal" disambiguation.
+            const stepDx = node.pos.x - prev.pos.x;
+            const stepDy = node.pos.y - prev.pos.y;
+            const stepDxNext = next.pos.x - node.pos.x;
+            const stepDyNext = next.pos.y - node.pos.y;
+
+            if (lenSq === 1)
+            {
+                // 45° angle — middle node is off the straight line. Drop it.
+                if (this.debug && this.debugTime > 0)
+                    debugCircle(node.posWorld, 0.3, rgb(0.5, 0, 0.5, 0.5), this.debugTime);
+                path.splice(i, 1);
+                i = max(1, i - 1);
+                continue;
+            }
+            else if (lenSq === 2)
+            {
+                // 90° corner. Check the alternative-diagonal cell.
+                if (this.debug && this.debugTime > 0)
+                    debugCircle(node.posWorld, 0.3, rgb(1, 0, 0, 0.5), this.debugTime);
+
+                let sx, sy;
+                if (prev.pos.y === node.pos.y && next.pos.x === node.pos.x)
+                { sx = prev.pos.x; sy = next.pos.y; }
+                else
+                { sx = next.pos.x; sy = prev.pos.y; }
+
+                const shortcut = this.getNode(sx, sy);
+                if (shortcut && shortcut.isClear())
+                {
+                    path.splice(i, 1);
+                    i = max(1, i - 1);
+                    continue;
+                }
+            }
+            else if (lenSq === 5)
+            {
+                // 135° angle (a knight's-move offset). Try to relocate the
+                // middle node to whichever of two candidate cells is closer
+                // to prev-of-prev, and only if the corner cut is also clear.
+                if (this.debug && this.debugTime > 0)
+                    debugCircle(node.posWorld, 0.3, rgb(1, 1, 0, 0.5), this.debugTime);
+
+                const prevPrev = i >= 2 ? path[i - 2] : prev;
+                let s1x, s1y, s2x, s2y;
+                if (stepDx === 0 || stepDxNext === 0)
+                {
+                    // mostly vertical
+                    s1x = next.pos.x; s1y = node.pos.y;
+                    s2x = prev.pos.x; s2y = node.pos.y;
+                }
+                else
+                {
+                    // mostly horizontal
+                    s1x = node.pos.x; s1y = next.pos.y;
+                    s2x = node.pos.x; s2y = prev.pos.y;
+                }
+                const dd1x = s1x - prevPrev.pos.x;
+                const dd1y = s1y - prevPrev.pos.y;
+                const dd2x = s2x - prevPrev.pos.x;
+                const dd2y = s2y - prevPrev.pos.y;
+                const dist1Sq = dd1x * dd1x + dd1y * dd1y;
+                const dist2Sq = dd2x * dd2x + dd2y * dd2y;
+                const sx = dist1Sq < dist2Sq ? s1x : s1x === s2x && s1y === s2y ? s1x : s2x;
+                const sy = dist1Sq < dist2Sq ? s1y : s1x === s2x && s1y === s2y ? s1y : s2y;
+
+                const shortcut = this.getNode(sx, sy);
+                if (shortcut && shortcut !== node && shortcut.isClear())
+                {
+                    // Also check the cut-corner cell is clear.
+                    const ccx = next.pos.x + s2x - s1x;
+                    const ccy = next.pos.y + s2y - s1y;
+                    const cutCorner = this.getNode(ccx, ccy);
+                    if (cutCorner && cutCorner.isClear())
+                    {
+                        path[i] = shortcut;
+                        i = max(1, i - 1);
+                        continue;
+                    }
+                }
+            }
+            else if (lenSq === 4 || lenSq === 8)
+            {
+                // Straight line or a 1-cell bump.
+                if (this.debug && this.debugTime > 0)
+                    debugCircle(node.posWorld, 0.3, rgb(0, 1, 0, 0.5), this.debugTime);
+
+                if (stepDx === stepDxNext && stepDy === stepDyNext)
+                {
+                    // Truly straight — nothing to do, advance.
+                    ++i;
+                    continue;
+                }
+                else
+                {
+                    // Bump — try to flatten via the in-line cell.
+                    let sx, sy;
+                    if (prev.pos.y === next.pos.y)
+                    { sx = node.pos.x; sy = prev.pos.y; }
+                    else
+                    { sx = prev.pos.x; sy = node.pos.y; }
+                    const shortcut = this.getNode(sx, sy);
+                    if (shortcut && shortcut.isClear())
+                    {
+                        path[i] = shortcut;
+                        i = max(1, i - 1);
+                        continue;
+                    }
+                }
+            }
+
+            ++i;
+        }
+    }
+
+    /** Smooth a node path via line-of-sight ("string pulling"). Walks the
+     *  input path collapsing runs of nodes into straight segments whenever
+     *  isLineClear permits, so the result can leave grid centers and cut
+     *  cleanly across open spaces.
+     *
+     *  Bails (leaves the path unchanged) if any node has nonzero cost — a
+     *  straight geometric shortcut can't be trusted to be the lowest-cost
+     *  route when cost-weighted terrain is in play.
+     *
+     *  Port of ShortenPath2() in pathFinding.cpp.
+     *  @param {PathFinderNode[]} path
+     *  @private */
+    smoothPathStringPull(path)
+    {
+        if (path.length <= 2) return;
+        for (const n of path)
+        {
+            if (!n.isClear()) return;
+        }
+
+        const original = path.slice();
+        path.length = 0;
+        path.push(original[0]);
+        let searchIndex = 0;
+
+        for (let i = 1; i < original.length; ++i)
+        {
+            const node = original[i];
+
+            // Skip if node is collinear with the search-window start and the
+            // previous node — it adds no information. Note: a == b is the
+            // degenerate i=1, searchIndex=0 case; skip the test then.
+            {
+                const a = original[searchIndex];
+                const b = original[i - 1];
+                if (a !== b)
+                {
+                    const cross =
+                        (b.pos.x - a.pos.x) * (node.pos.y - a.pos.y) -
+                        (b.pos.y - a.pos.y) * (node.pos.x - a.pos.x);
+                    if (cross === 0) continue;
+                }
+            }
+
+            if (!this.isLineClear(node.pos, path[path.length - 1].pos))
+            {
+                // Look ahead — if any later node has a clear shot to the
+                // back of our new path, skip this node and try later.
+                let foundClearAfter = false;
+                for (let j = i + 1; j < original.length; ++j)
+                {
+                    if (this.isLineClear(original[j].pos, path[path.length - 1].pos))
+                    {
+                        foundClearAfter = true;
+                        break;
+                    }
+                }
+                if (foundClearAfter)
+                {
+                    if (this.debug && this.debugTime > 0)
+                        debugLine(node.posWorld, path[path.length - 1].posWorld, rgb(0, 0, 1, 0.3), 0.02, this.debugTime);
+                    continue;
+                }
+
+                // No clear line ahead — fall back to the last waypoint we did
+                // have a clear line to. searchIndex tracks our scan position.
+                for (; searchIndex < original.length; ++searchIndex)
+                {
+                    const cand = original[searchIndex];
+                    if (this.isLineClear(node.pos, cand.pos))
+                    {
+                        path.push(cand);
+                        i = searchIndex;
+                        break;
+                    }
+                }
+                ASSERT(searchIndex < original.length, 'smoothPathStringPull: ran out of candidates');
+            }
+        }
+
+        path.push(original[original.length - 1]);
+    }
+
+    /** Lookup helper: true when the node at tile coords (x, y) is in-bounds
+     *  and clear (walkable, zero-cost). Used by isLineClear's hot path.
+     *  @param {number} x
+     *  @param {number} y
+     *  @returns {boolean}
+     *  @private */
+    isNodeClear(x, y)
+    {
+        const n = this.getNode(x, y);
+        return n !== null && n.isClear();
+    }
+
+    /** Check that the line between two tile-coord endpoints stays entirely
+     *  inside walkable, zero-cost cells. Stricter than just sampling along
+     *  the line — it also checks the diagonal-corner-adjacent cells so the
+     *  line can never "scrape past" a wall corner.
+     *
+     *  Both endpoints must themselves be clear (asserted in debug). Port of
+     *  CheckLine() in pathFinding.cpp.
+     *  @param {Vector2} startPos - Tile coords
+     *  @param {Vector2} endPos - Tile coords
+     *  @returns {boolean}
+     *  @private */
+    isLineClear(startPos, endPos)
+    {
+        ASSERT(isVector2(startPos) && isVector2(endPos), 'isLineClear needs Vector2 endpoints');
+        ASSERT(this.isNodeClear(startPos.x, startPos.y) && this.isNodeClear(endPos.x, endPos.y),
+            'isLineClear endpoints must be in-bounds and clear');
+
+        const dx = endPos.x - startPos.x;
+        const dy = endPos.y - startPos.y;
+        const adx = abs(dx);
+        const ady = abs(dy);
+        const sx = sign(dx);
+        const sy = sign(dy);
+        let x = startPos.x;
+        let y = startPos.y;
+
+        if (ady === adx)
+        {
+            // Pure diagonal.
+            while (x !== endPos.x)
+            {
+                if (x !== startPos.x)
+                {
+                    if (!this.isNodeClear(x, y)) return false;
+                    if (!this.isNodeClear(x, y - sy)) return false;
+                }
+                if (!this.isNodeClear(x, y + sy)) return false;
+                x += sx;
+                y += sy;
+            }
+            if (!this.isNodeClear(endPos.x, endPos.y - sy)) return false;
+        }
+        else if (ady < adx)
+        {
+            // Mostly horizontal.
+            if (dy === 0)
+            {
+                // Purely horizontal.
+                x += sx;
+                while (x !== endPos.x)
+                {
+                    if (!this.isNodeClear(x, y)) return false;
+                    x += sx;
+                }
+            }
+            else
+            {
+                let lastY = startPos.y;
+                while (x !== endPos.x)
+                {
+                    y = startPos.y + Math.trunc((dy * (x - startPos.x)) / dx);
+                    if (lastY !== y)
+                    {
+                        if (!this.isNodeClear(x - sx, y + sy)) return false;
+                        if (!this.isNodeClear(x, y - sy)) return false;
+                    }
+                    lastY = y;
+                    if (x !== startPos.x)
+                    {
+                        if (!this.isNodeClear(x, y)) return false;
+                    }
+                    y += sy;
+                    if (!this.isNodeClear(x, y)) return false;
+                    x += sx;
+                }
+                const finalY = endPos.y - sy;
+                if (!this.isNodeClear(endPos.x, finalY)) return false;
+            }
+        }
+        else
+        {
+            // Mostly vertical.
+            if (dx === 0)
+            {
+                y += sy;
+                while (y !== endPos.y)
+                {
+                    if (!this.isNodeClear(x, y)) return false;
+                    y += sy;
+                }
+            }
+            else
+            {
+                let lastX = startPos.x;
+                while (y !== endPos.y)
+                {
+                    x = startPos.x + Math.trunc((dx * (y - startPos.y)) / dy);
+                    if (lastX !== x)
+                    {
+                        if (!this.isNodeClear(x + sx, y - sy)) return false;
+                        if (!this.isNodeClear(x - sx, y)) return false;
+                    }
+                    lastX = x;
+                    if (y !== startPos.y)
+                    {
+                        if (!this.isNodeClear(x, y)) return false;
+                    }
+                    x += sx;
+                    if (!this.isNodeClear(x, y)) return false;
+                    y += sy;
+                }
+                const finalX = endPos.x - sx;
+                if (!this.isNodeClear(finalX, endPos.y)) return false;
+            }
+        }
+        return true;
+    }
+
+    /** Find a path from startPos to endPos in world space. Returns an array
+     *  of world-space Vector2 points; empty array if no path exists.
+     *
+     *  Start and end are snapped to the nearest walkable tile via
+     *  getNearestClearNode. Intermediate points are tile centers unless the
+     *  string-pulling smoothing pass moves them off-grid.
+     *  @param {Vector2} startPos - World-space start
+     *  @param {Vector2} endPos - World-space end
+     *  @returns {Vector2[]}
+     *  @memberof PathFinding */
+    findPath(startPos, endPos)
+    {
+        ASSERT(isVector2(startPos) && isVector2(endPos), 'findPath needs Vector2 endpoints');
+
+        this.buildNodeData();
+
+        // rebuild=false because we just built — avoid redundant work per snap.
+        const startNode = this.getNearestClearNode(startPos, 10, false);
+        const endNode = this.getNearestClearNode(endPos, 10, false);
+        if (!startNode || !endNode) return [];
+
+        // Trivial case: start and end snapped to the same tile.
+        if (startNode === endNode) return [startNode.posWorld.copy()];
+
+        if (!this.aStarSearch(startNode, endNode)) return [];
+
+        // Walk back from endNode via parent pointers, then reverse — cheaper
+        // than unshifting on every step.
+        const nodePath = [];
+        for (let n = endNode; n; n = n.parent)
+            nodePath.push(n);
+        nodePath.reverse();
+
+        if (this.smoothPath)
+        {
+            this.smoothPathCorners(nodePath);
+            this.smoothPathStringPull(nodePath);
+        }
+
+        // Convert to world-space Vector2 path. Return copies, not live node
+        // references — callers shouldn't be able to mutate the grid.
+        const result = nodePath.map(n => n.posWorld.copy());
+
+        if (this.debug && this.debugTime > 0 && result.length > 0)
+        {
+            for (let i = 1; i < result.length; ++i)
+                debugLine(result[i - 1], result[i], RED, 0.1, this.debugTime);
+            for (const p of result)
+                debugCircle(p, 0.5, rgb(1, 0, 0, 0.3), this.debugTime);
+            debugCircle(result[0], 0.5, rgb(0, 1, 0, 0.5), this.debugTime);
+            debugCircle(result[result.length - 1], 0.5, rgb(0, 1, 0, 0.5), this.debugTime);
+        }
+
+        return result;
+    }
+}
+