littlejsengine 1.18.7 → 1.18.12

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.7';
+const engineVersion = '1.18.12';
 
 /** Frames per second to update
  *  @type {number}
@@ -207,7 +207,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         const combinedScale = timeScale * debugScale;
         frameTimeDeltaMS *= combinedScale;
         frameTimeBufferMS += paused ? 0 : frameTimeDeltaMS;
-        if (debugScale <= 1)
+        if (combinedScale <= 1)
             frameTimeBufferMS = min(frameTimeBufferMS, 50); // clamp min framerate
 
         let wasUpdated = false;
@@ -294,6 +294,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             glFlush();
             debugRenderPost();
             drawCount = 0;
+            primitiveCount = 0;
         }
     }
 
@@ -900,13 +901,15 @@ function oscillate(frequency=1, amplitude=1, t=time, offset=0, type=0)
 function isNumber(n) { return typeof n === 'number' && !isNaN(n); }
 
 /**
- * Check if object can be converted to a string (has a toString method)
+ * Check if a value is stringifiable — i.e. it has a toString that returns
+ * a string. Use this for ASSERTs and inputs that will be coerced to text;
+ * use `typeof x === 'string'` inline if you need strict-string semantics.
  * - Returns true for strings, numbers, and most objects
  * - Returns false for null and undefined
  * @param {any} s
  * @return {boolean}
  * @memberof Math */
-function isString(s) { return s != null && typeof s?.toString() === 'string'; }
+function isStringLike(s) { return s != null && typeof s?.toString() === 'string'; }
 
 /**
  * Check if object is an array
@@ -1650,7 +1653,7 @@ class Color
      * @return {Color} */
     setHex(hex)
     {
-        ASSERT(isString(hex), 'Color hex code must be a string');
+        ASSERT(isStringLike(hex), 'Color hex code must be a string');
         ASSERT(hex[0] === '#', 'Color hex code must start with #');
         ASSERT([4,5,7,9].includes(hex.length), 'Invalid hex');
 
@@ -1767,6 +1770,7 @@ const MAGENTA = debugProtectConstant(rgb(1,0,1));
  * - File saving (text, canvas, data URLs)
  * - Native share dialog support
  * - Local storage save data management
+ * - Gradient noise (1D and 2D)
  * @namespace Utilities
  */
 
@@ -1914,8 +1918,8 @@ function saveCanvas(canvas, filename='screenshot', type='image/png')
  *  @memberof Utilities */
 function saveDataURL(url, filename='download', revokeTime)
 {
-    ASSERT(isString(url), 'saveDataURL requires url string');
-    ASSERT(isString(filename), 'saveDataURL requires filename string');
+    ASSERT(isStringLike(url), 'saveDataURL requires url string');
+    ASSERT(isStringLike(filename), 'saveDataURL requires filename string');
 
     // create link for saving screenshots
     const link = document.createElement('a');
@@ -1933,8 +1937,8 @@ function saveDataURL(url, filename='download', revokeTime)
  *  @memberof Utilities */
 function shareURL(title, url, callback)
 {
-    ASSERT(isString(title), 'shareURL requires title string');
-    ASSERT(isString(url), 'shareURL requires url string');
+    ASSERT(isStringLike(title), 'shareURL requires title string');
+    ASSERT(isStringLike(url), 'shareURL requires url string');
     navigator.share?.({title, url}).then(()=>callback?.());
 }
 
@@ -1947,7 +1951,7 @@ function shareURL(title, url, callback)
  *  @memberof Utilities */
 function readSaveData(saveName, defaultSaveData)
 {
-    ASSERT(isString(saveName), 'loadData requires saveName string');
+    ASSERT(isStringLike(saveName), 'loadData requires saveName string');
     
     // replace undefined values with defaults; tolerate corrupt JSON
     const data = localStorage[saveName];
@@ -1966,8 +1970,50 @@ function readSaveData(saveName, defaultSaveData)
  *  @memberof Utilities */
 function writeSaveData(saveName, saveData)
 {
-    ASSERT(isString(saveName), 'saveData requires saveName string');
+    ASSERT(isStringLike(saveName), 'saveData requires saveName string');
     localStorage[saveName] = JSON.stringify(saveData);
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+// Deterministic well-distributed hash of an integer lattice index to [0, 1).
+// Murmur3 finalizer — adjacent integers produce uncorrelated outputs.
+function noiseHash(i)
+{
+    let h = (i | 0) ^ 0x9e3779b9;
+    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+    h ^= h >>> 16;
+    return (h >>> 0) / 2**32;
+}
+
+/** 1D gradient noise — returns a smooth value in [0, 1] for any real x.
+ *  Integer inputs land on deterministic lattice values; non-integer inputs
+ *  are interpolated with smoothStep for C1 continuity.
+ *  @param {number} x
+ *  @return {number}
+ *  @memberof Utilities */
+function noise1D(x)
+{
+    const i = floor(x);
+    return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
+}
+
+/** 2D gradient noise — returns a smooth value in [0, 1] for any real (x, y).
+ *  @param {number} x
+ *  @param {number} y
+ *  @return {number}
+ *  @memberof Utilities */
+function noise2D(x, y)
+{
+    const ix = floor(x), iy = floor(y);
+    const fx = smoothStep(x - ix), fy = smoothStep(y - iy);
+    // large prime decorrelates neighboring rows
+    const h = (a, b) => noiseHash(a + b * 374761393);
+    return lerp(
+        lerp(h(ix,     iy    ), h(ix + 1, iy    ), fx),
+        lerp(h(ix,     iy + 1), h(ix + 1, iy + 1), fx),
+        fy);
 }
 /**
  * LittleJS Engine Settings
@@ -3174,6 +3220,12 @@ let textureInfos = [];
  *  @memberof Draw */
 let drawCount;
 
+/** Keeps track of how many primitives were drawn each frame for debugging
+ *  A single draw call can render many primitives (e.g. a WebGL sprite batch).
+ *  @type {number}
+ *  @memberof Draw */
+let primitiveCount;
+
 // 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
@@ -3414,19 +3466,19 @@ function drawTile(pos, size=vec2(1), tileInfo, color=WHITE,
         }
         else
         {
-            // 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.
+            // untextured: glDrawUntextured picks the optimal path (poly
+            // tristrip if already in poly mode, otherwise instanced with
+            // uvs/rgba zeroed). Color+additive are folded together to match
+            // 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());
+            glDrawUntextured(pos.x, pos.y, size.x, size.y, angle, combined.rgbaInt());
         }
     }
     else
     {
         // normal canvas 2D rendering method (slower)
         ++drawCount;
+        ++primitiveCount;
         size = new Vector2(size.x, -size.y); // flip upside down sprites
         drawCanvas2D(pos, size, angle, mirror, (context)=>
         {
@@ -3466,13 +3518,13 @@ function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
  *  @param {Vector2} pos
  *  @param {Vector2} [size=vec2(1)]
  *  @param {Color}   [colorTop=WHITE]
- *  @param {Color}   [colorBottom=BLACK]
+ *  @param {Color}   [colorBottom=CLEAR_WHITE]
  *  @param {number}  [angle]
  *  @param {boolean} [useWebGL=glEnable]
  *  @param {boolean} [screenSpace]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0, useWebGL=glEnable, screenSpace=false, context)
+function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=CLEAR_WHITE, angle=0, useWebGL=glEnable, screenSpace=false, context)
 {
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isVector2(size), 'size must be a vec2');
@@ -3512,6 +3564,7 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0,
     {
         // normal canvas 2D rendering method (slower)
         ++drawCount;
+        ++primitiveCount;
         size = new Vector2(size.x, -size.y); // fix upside down sprites
         drawCanvas2D(pos, size, angle, false, (context)=>
         {
@@ -3574,8 +3627,9 @@ function drawTextureWrapped(pos, size, wrapCount, texture=0, color=WHITE,
         return;
     }
 
-    // Canvas2D path — increment drawCount here (WebGL batch counts via glBatchCount)
+    // Canvas2D path — increment counts here (WebGL counts via glFlush)
     ++drawCount;
+    ++primitiveCount;
 
     if (!screenSpace)
     {
@@ -3649,6 +3703,7 @@ function drawLineList(points, width=.1, color, wrap=false, pos=vec2(), angle=0,
     {
         // normal canvas 2D rendering method (slower)
         ++drawCount;
+        ++primitiveCount;
         drawCanvas2D(pos, vec2(1), angle, false, (context)=>
         {
             context.strokeStyle = color.toString();
@@ -3829,6 +3884,77 @@ function drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, useW
     drawEllipse(pos, vec2(size), color, 0, lineWidth, lineColor, useWebGL, screenSpace, context);
 }
 
+/** Draw a circle filled with a radial gradient from the center to the rim
+ *  - Best when batched with other untextured polys
+ *  - If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
+ *  - Stacking gradients at the exact same position may show a faint vertical artifact
+ *  @param {Vector2} pos
+ *  @param {number}  [size=1] - Diameter
+ *  @param {Color}   [colorInner=WHITE]
+ *  @param {Color}   [colorOuter=CLEAR_WHITE]
+ *  @param {boolean} [useWebGL=glEnable]
+ *  @param {boolean} [screenSpace]
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
+ *  @memberof Draw */
+let drawCircleGradientOffset = 0;
+function drawCircleGradient(pos, size=1, colorInner=WHITE, colorOuter=CLEAR_WHITE, useWebGL=glEnable, screenSpace=false, context)
+{
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isNumber(size), 'size must be a number');
+    ASSERT(isColor(colorInner) && isColor(colorOuter), 'color is invalid');
+    ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
+
+    if (headlessMode) return;
+
+    if (useWebGL && glEnable)
+    {
+        ASSERT(!!glContext, 'WebGL is not enabled!');
+        if (screenSpace)
+        {
+            // convert to world space
+            pos = screenToWorld(pos);
+            size /= cameraScale;
+        }
+        // fan as tristrip; rotate the boundary vertex by one slice per call
+        // so back-to-back gradients at the same position have their hole
+        // (from gpu edge-rule on the boundary line-degen) at different rim
+        // verts and don't visibly stack
+        const sides = glCircleSides;
+        const radius = size/2;
+        const innerInt = colorInner.rgbaInt();
+        const outerInt = colorOuter.rgbaInt();
+        const offset = drawCircleGradientOffset++;
+        const startA = (offset%sides)/sides*PI*2;
+        const points = [vec2(pos.x + sin(startA)*radius, pos.y + cos(startA)*radius)];
+        const colors = [outerInt];
+        for (let i=sides; i--;)
+        {
+            const a = ((i+offset)%sides)/sides*PI*2;
+            points.push(pos);
+            colors.push(innerInt);
+            points.push(vec2(pos.x + sin(a)*radius, pos.y + cos(a)*radius));
+            colors.push(outerInt);
+        }
+        glDrawColoredPoints(points, colors);
+    }
+    else
+    {
+        // normal canvas 2D rendering method (slower)
+        ++drawCount;
+        ++primitiveCount;
+        drawCanvas2D(pos, vec2(size), 0, false, (context)=>
+        {
+            const gradient = context.createRadialGradient(0, 0, 0, 0, 0, .5);
+            gradient.addColorStop(0, colorInner.toString());
+            gradient.addColorStop(1, colorOuter.toString());
+            context.fillStyle = gradient;
+            context.beginPath();
+            context.ellipse(0, 0, .5, .5, 0, 0, 9);
+            context.fill();
+        }, screenSpace, context);
+    }
+}
+
 /**
  * @callback Canvas2DDrawFunction - A function that draws to a 2D canvas context
  * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
@@ -3912,15 +4038,15 @@ function drawText(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, f
  *  @memberof Draw */
 function drawTextScreen(text, pos, size, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font=fontDefault, fontStyle='', maxWidth, angle=0, context=drawContext)
 {
-    ASSERT(isString(text), 'text must be a string');
+    ASSERT(isStringLike(text), 'text must be a string');
     ASSERT(isVector2(pos), 'pos must be a vec2');
     ASSERT(isNumber(size), 'size must be a number');
     ASSERT(isColor(color), 'color must be a color');
     ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
     ASSERT(isColor(lineColor), 'lineColor must be a color');
     ASSERT(['left','center','right'].includes(textAlign), 'align must be left, center, or right');
-    ASSERT(isString(font), 'font must be a string');
-    ASSERT(isString(fontStyle), 'fontStyle must be a string');
+    ASSERT(isStringLike(font), 'font must be a string');
+    ASSERT(isStringLike(fontStyle), 'fontStyle must be a string');
     ASSERT(isNumber(angle), 'angle must be a number');
     
     context.fillStyle = color.toString();
@@ -3957,7 +4083,7 @@ async function loadTexture(textureIndex, src)
 {
     ASSERT(isNumber(textureIndex), 'textureIndex must be a number');
     ASSERT(!textureInfos[textureIndex], 'textureIndex is already loaded!');
-    ASSERT(!src || isString(src), 'image src must be a string');
+    ASSERT(!src || isStringLike(src), 'image src must be a string');
     
     const image = new Image;
     if (src)
@@ -4345,7 +4471,7 @@ class FontImage
      */
     drawTextScreen(text, pos, size, center=true, color=WHITE, useWebGL=glEnable, context)
     {
-        ASSERT(isString(text), 'text must be a string');
+        ASSERT(isStringLike(text), 'text must be a string');
         ASSERT(isVector2(pos), 'pos must be a vec2');
         ASSERT(isVector2(size) || typeof size === 'number', 'size must be a vec2 or number');
         ASSERT(isColor(color), 'color must be a color');
@@ -4506,7 +4632,7 @@ function inputClear()
  *  @memberof Input */
 function keyIsDown(key, device=0)
 {
-    ASSERT(isString(key), 'key must be a number or string');
+    ASSERT(isStringLike(key), 'key must be a number or string');
     ASSERT(device > 0 || typeof key !== 'number' || key < 3, 'use code string for keyboard');
     return !!(inputData[device]?.[key] & 1);
 }
@@ -4518,7 +4644,7 @@ function keyIsDown(key, device=0)
  *  @memberof Input */
 function keyWasPressed(key, device=0)
 {
-    ASSERT(isString(key), 'key must be a number or string');
+    ASSERT(isStringLike(key), 'key must be a number or string');
     ASSERT(device > 0 || typeof key !== 'number' || key < 3, 'use code string for keyboard');
     return !!(inputData[device]?.[key] & 2);
 }
@@ -4530,7 +4656,7 @@ function keyWasPressed(key, device=0)
  *  @memberof Input */
 function keyWasReleased(key, device=0)
 {
-    ASSERT(isString(key), 'key must be a number or string');
+    ASSERT(isStringLike(key), 'key must be a number or string');
     ASSERT(device > 0 || typeof key !== 'number' || key < 3, 'use code string for keyboard');
     return !!(inputData[device]?.[key] & 4);
 }
@@ -4544,10 +4670,10 @@ function keyWasReleased(key, device=0)
  *  @memberof Input */
 function keyDirection(up='ArrowUp', down='ArrowDown', left='ArrowLeft', right='ArrowRight')
 {
-    ASSERT(isString(up),    'up key must be a string');
-    ASSERT(isString(down),  'down key must be a string');
-    ASSERT(isString(left),  'left key must be a string');
-    ASSERT(isString(right), 'right key must be a string');
+    ASSERT(isStringLike(up),    'up key must be a string');
+    ASSERT(isStringLike(down),  'down key must be a string');
+    ASSERT(isStringLike(left),  'left key must be a string');
+    ASSERT(isStringLike(right), 'right key must be a string');
     const k = (key)=> keyIsDown(key) ? 1 : 0;
     return vec2(k(right) - k(left), k(up) - k(down));
 }
@@ -5265,12 +5391,10 @@ function touchGamepadButtonCenter()
  * @namespace Audio
  */
 
-/** Audio context used by the engine. Created lazily in audioInit() to avoid
- *  browser autoplay warnings about constructing an AudioContext before any
- *  user gesture.
+/** Audio context used by the engine
  *  @type {AudioContext}
  *  @memberof Audio */
-let audioContext;
+let audioContext = new AudioContext;
 
 /** Master gain node for all audio to pass through
  *  @type {GainNode}
@@ -5286,13 +5410,12 @@ 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
@@ -5338,7 +5461,7 @@ class Sound
     {
         if (!soundEnable || headlessMode) return;
 
-        ASSERT(!asset || isArray(asset) || isString(asset), 'asset must be a file name or zzfx array');
+        ASSERT(!asset || isArray(asset) || isStringLike(asset), 'asset must be a file name or zzfx array');
         ASSERT(randomness === undefined || isNumber(randomness), 'randomness must be a number');
         ASSERT(randomness === undefined || randomness >= 0 && randomness <=1, 'randomness must be between 0 and 1');
         ASSERT(isNumber(range), 'range must be a number');
@@ -5677,14 +5800,15 @@ class SoundInstance
 
 /** Speak text with passed in settings
  *  @param {string} text - The text to speak
- *  @param {string} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
  *  @param {number} [volume] - How much to scale volume by
  *  @param {number} [rate] - How quickly to speak
  *  @param {number} [pitch] - How much to change the pitch by
+ *  @param {string} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
  *  @return {SpeechSynthesisUtterance} - The utterance that was spoken
  *  @memberof Audio */
-function speak(text, language='', volume=1, rate=1, pitch=1)
+function speak(text, volume=1, rate=1, pitch=1, language='')
 {
+    ASSERT(typeof volume !== 'string', 'speak() signature changed: language is now the last parameter, after pitch');
     if (!soundEnable || headlessMode) return;
     if (!speechSynthesis) return;
 
@@ -7677,7 +7801,8 @@ function glFlush()
             glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, glBatchCount);
         else
             glContext.drawArraysInstanced(glContext.TRIANGLE_STRIP, 0, 4, glBatchCount);
-        drawCount += glBatchCount;
+        ++drawCount;
+        primitiveCount += glBatchCount;
         glBatchCount = 0;
     }
     glBatchAdditive = glAdditive;
@@ -7738,6 +7863,67 @@ function glDraw(x, y, sizeX, sizeY, angle=0, uv0X=0, uv0Y=0, uv1X=1, uv1Y=1, rgb
     glPositionData[offset++] = angle;
 }
 
+/** Add an untextured rect to the gl draw list
+ *  Picks the optimal path: if already in poly mode, emits a tristrip rect
+ *  so it batches with surrounding polys; otherwise uses the instanced path
+ *  with uvs and rgba zeroed so the color falls through the additive slot.
+ *  @param {number} x
+ *  @param {number} y
+ *  @param {number} sizeX
+ *  @param {number} sizeY
+ *  @param {number} angle
+ *  @param {number} rgba - color as 32-bit integer
+ *  @memberof WebGL */
+function glDrawUntextured(x, y, sizeX, sizeY, angle, rgba)
+{
+    if (glPolyMode)
+    {
+        // batch with surrounding polys as a 4-vertex tristrip rect
+        const vertCount = 6; // 4 corners + 2 degenerate verts
+        if (glBatchCount+vertCount >= gl_MAX_POLY_VERTEXES || glBatchAdditive !== glAdditive)
+            glFlush();
+
+        // compute rotated corners in world space (matches glDrawPointsTransform rotation)
+        const hx = sizeX*.5, hy = sizeY*.5;
+        const c = cos(angle), s = sin(angle);
+        const chx = c*hx, shx = s*hx, chy = c*hy, shy = s*hy;
+        const x0 = x - chx - shy, y0 = y + shx - chy; // (-hx,-hy)
+        const x1 = x + chx - shy, y1 = y - shx - chy; // ( hx,-hy)
+        const x2 = x - chx + shy, y2 = y + shx + chy; // (-hx, hy)
+        const x3 = x + chx + shy, y3 = y - shx + chy; // ( hx, hy)
+
+        // write tristrip with leading/trailing degenerate verts
+        let offset = glBatchCount * gl_INDICES_PER_POLY_VERTEX;
+        glPositionData[offset++] = x0; glPositionData[offset++] = y0; glColorData[offset++] = rgba;
+        glPositionData[offset++] = x0; glPositionData[offset++] = y0; glColorData[offset++] = rgba;
+        glPositionData[offset++] = x1; glPositionData[offset++] = y1; glColorData[offset++] = rgba;
+        glPositionData[offset++] = x2; glPositionData[offset++] = y2; glColorData[offset++] = rgba;
+        glPositionData[offset++] = x3; glPositionData[offset++] = y3; glColorData[offset++] = rgba;
+        glPositionData[offset++] = x3; glPositionData[offset++] = y3; glColorData[offset++] = rgba;
+        glBatchCount += vertCount;
+        return;
+    }
+
+    // instanced path: zero uvs and rgba so the texture contribution is killed,
+    // then carry the real color in the additive slot
+    if (glBatchCount >= gl_MAX_INSTANCES || glBatchAdditive !== glAdditive)
+        glFlush();
+    glSetInstancedMode();
+
+    let offset = glBatchCount++ * gl_INDICES_PER_INSTANCE;
+    glPositionData[offset++] = x;
+    glPositionData[offset++] = y;
+    glPositionData[offset++] = sizeX;
+    glPositionData[offset++] = sizeY;
+    glPositionData[offset++] = 0;
+    glPositionData[offset++] = 0;
+    glPositionData[offset++] = 0;
+    glPositionData[offset++] = 0;
+    glColorData[offset++] = 0;
+    glColorData[offset++] = rgba;
+    glPositionData[offset++] = angle;
+}
+
 /** Transform and add a polygon to the gl draw list
  *  @param {Array<Vector2>} points - Array of Vector2 points
  *  @param {number} rgba - Color of the polygon as a 32-bit integer
@@ -8374,7 +8560,8 @@ class Medal
         /** @property {boolean} - Is the medal unlocked? */
         this.unlocked = false;
 
-        // load the source image if provided
+        /** @property {HTMLImageElement|undefined} - Source image for the medal icon, if any */
+        this.image = undefined;
         if (src)
             (this.image = new Image).src = src;
 
@@ -8537,13 +8724,18 @@ class NewgroundsPlugin
         ASSERT(!cipher || cryptoJS, 'must provide cryptojs if there is a cipher');
 
         newgrounds = this; // set global newgrounds object
+        /** @property {string} - The newgrounds App ID */
         this.app_id = app_id;
+        /** @property {string|undefined} - AES-128/Base64 encryption key, if any */
         this.cipher = cipher;
+        /** @property {Object|undefined} - CryptoJS instance used when cipher is set */
         this.cryptoJS = cryptoJS;
+        /** @property {string} - Hostname used when logging views */
         this.host = location ? location.hostname : '';
 
         // get session id from url search params
         const url = new URL(location.href);
+        /** @property {string|null} - Newgrounds session id from the URL (null when not logged in) */
         this.session_id = url.searchParams.get('ngio_session_id');
 
         if (!this.session_id)
@@ -8551,6 +8743,7 @@ class NewgroundsPlugin
 
         // get medals
         const medalsResult = this.call('Medal.getList');
+        /** @property {Array} - Medals fetched from Newgrounds (empty until session is active) */
         this.medals = medalsResult ? medalsResult.result.data['medals'] : [];
         debugMedals && LOG(this.medals);
         for (const newgroundsMedal of this.medals)
@@ -8574,6 +8767,7 @@ class NewgroundsPlugin
     
         // get scoreboards
         const scoreboardResult = this.call('ScoreBoard.getBoards');
+        /** @property {Array} - Scoreboards fetched from Newgrounds */
         this.scoreboards = scoreboardResult ? scoreboardResult.result.data.scoreboards : [];
         debugMedals && LOG(this.scoreboards);
 
@@ -9097,12 +9291,31 @@ class UISystemPlugin
 
         engineAddPlugin(uiUpdate, uiRender);
 
-        // set object position in parent space
+        // set object position based on anchor target (parent box, or canvas for roots),
+        // self-pivot, and localPos offset
         function updateTransforms(o)
         {
-            if (!o.parent) return;
-            o.pos.x = o.localPos.x + o.parent.pos.x;
-            o.pos.y = o.localPos.y + o.parent.pos.y;
+            let targetPos, targetSize;
+            if (o.parent)
+            {
+                targetPos = o.parent.pos;
+                targetSize = o.parent.size;
+            }
+            else
+            {
+                // anchor to canvas in native coords (handles nativeHeight if set)
+                targetPos = uiSystem.screenToNative(mainCanvasSize.scale(.5));
+                targetSize = uiSystem.nativeHeight
+                    ? vec2(mainCanvasSize.x * uiSystem.nativeHeight / mainCanvasSize.y,
+                           uiSystem.nativeHeight)
+                    : mainCanvasSize;
+            }
+
+            const a = o.anchor;
+            o.pos = targetPos
+                .add(targetSize.multiply(a).scale(.5))   // anchor point on target
+                .subtract(o.size.multiply(a).scale(.5))  // pivot shift on self
+                .add(o.localPos);                        // user offset
         }
 
         // setup recursive update and render
@@ -9569,9 +9782,8 @@ class UISystemPlugin
         // confirm menu
         const confirmMenu = new UIObject(vec2(), size);
         uiSystem.confirmDialog = confirmMenu;
-        confirmMenu.onRender = ()=> 
+        confirmMenu.onRender = ()=>
         {
-            confirmMenu.pos = uiSystem.screenToNative(mainCanvasSize.scale(.5));
             const backgroundColor = hsl(0,0,0,.7);
             uiSystem.drawRect(vec2(), vec2(1e9), backgroundColor);
         }
@@ -9704,7 +9916,11 @@ class UIObject
         this.navigationIndex = undefined;
         /** @property {boolean} - Should this be auto selected by navigation? Must also have valid navigation index. */
         this.navigationAutoSelect = false;
-        
+        /** @property {Vector2} - Where on parent (or canvas if no parent) this object is anchored.
+         *  Components in [-1, 1]: (0,0)=center, (-1,-1)=top-left, (1,1)=bottom-right.
+         *  Also acts as self-pivot — e.g. (1,-1) puts your top-right corner at the anchor point. */
+        this.anchor = vec2();
+
         uiSystem.uiObjects.push(this);
     }
 
@@ -9957,9 +10173,9 @@ class UIText extends UIObject
     {
         super(pos, size);
 
-        ASSERT(isString(text), 'ui text must be a string');
+        ASSERT(isStringLike(text), 'ui text must be a string');
         ASSERT(['left','center','right'].includes(align), 'ui text align must be left, center, or right');
-        ASSERT(isString(font), 'ui text font must be a string');
+        ASSERT(isStringLike(font), 'ui text font must be a string');
 
         // set properties
         this.text = text;
@@ -10007,7 +10223,7 @@ class UITextInput extends UIObject
     {
         super(pos, size);
 
-        ASSERT(isString(text), 'ui text must be a string');
+        ASSERT(isStringLike(text), 'ui text must be a string');
 
         /** @property {number} - Max length of input (0 = no limit) */
         this.maxLength = 0;
@@ -10144,7 +10360,7 @@ class UIButton extends UIObject
     {
         super(pos, size);
 
-        ASSERT(isString(text), 'ui button must be a string');
+        ASSERT(isStringLike(text), 'ui button must be a string');
         ASSERT(isColor(color), 'ui button color must be a color');
 
         /** @property {Vector2} - Text offset for the button */
@@ -10185,7 +10401,7 @@ class UICheckbox extends UIObject
     {
         super(pos, size);
 
-        ASSERT(isString(text), 'ui checkbox must be a string');
+        ASSERT(isStringLike(text), 'ui checkbox must be a string');
         ASSERT(isColor(color), 'ui checkbox color must be a color');
 
         /** @property {boolean} - Current percentage value of this slider 0-1 */
@@ -10242,7 +10458,7 @@ class UISlider extends UIObject
         super(pos, size);
 
         ASSERT(isNumber(value), 'ui slider value must be a number');
-        ASSERT(isString(text), 'ui slider must be a string');
+        ASSERT(isStringLike(text), 'ui slider must be a string');
         ASSERT(isColor(color), 'ui slider color must be a color');
         ASSERT(isColor(handleColor), 'ui slider handleColor must be a color');
 
@@ -10360,7 +10576,7 @@ class UIVideo extends UIObject
     {
         super(pos, size || vec2());
         
-        ASSERT(isString(src), 'video src must be a string');
+        ASSERT(isStringLike(src), 'video src must be a string');
         ASSERT(isNumber(volume), 'video volume must be a number');
 
         this.color = BLACK; // default to black background
@@ -12864,13 +13080,21 @@ class Tween
         }
         ASSERT(isNumber(duration) && duration > 0, 'Tween duration must be > 0');
 
+        /** @property {function(number|Vector2|Color):void} - Called with the interpolated value each frame */
         this.callback = callback;
+        /** @property {number|Vector2|Color} - Starting value */
         this.start = start;
+        /** @property {number|Vector2|Color} - Ending value */
         this.end = end;
+        /** @property {number} - Total duration in seconds */
         this.duration = duration;
+        /** @property {number} - Remaining time in seconds (counts down from duration to 0) */
         this.life = duration;
+        /** @property {function(number):number} - Easing curve mapping [0,1] -> [0,1] */
         this.ease = options.ease || Ease.LINEAR;
+        /** @property {boolean} - If true, advance even when the game is paused */
         this.useRealTime = !!options.useRealTime;
+        /** @property {boolean} - If true, stop advancing until cleared */
         this.paused = !!options.paused;
 
         /** @private completion callback set by then(), loop(), pingPong(). */
@@ -13210,7 +13434,7 @@ const Ease =
 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');
+    ASSERT(isStringLike(propertyPath) && propertyPath.length > 0, 'tweenProperty propertyPath must be a non-empty string');
 
     const parts = propertyPath.split('.');
     const lastKey = parts.pop();
@@ -13403,7 +13627,9 @@ class PathFinder
         // .size + .getCollisionData.
         if (isVector2(source))
         {
+            /** @property {Vector2} - Grid dimensions in tiles */
             this.size = source.floor();
+            /** @property {TileCollisionLayer|undefined} - Tile layer driving walkability, if any */
             this.tileLayer = undefined;
         }
         else
@@ -13415,13 +13641,18 @@ class PathFinder
         }
 
         // Tunables (public, freely re-assignable).
+        /** @property {number} - A* heuristic multiplier (1 = admissible, higher = greedier) */
         this.heuristicWeight = 1;
-        this.maxLoop = 500;
+        /** @property {number} - Maximum A* expansions before giving up */
+        this.maxLoop = 1e3;
+        /** @property {boolean} - If true, post-process paths with two-pass smoothing */
         this.smoothPath = true;
+        /** @property {boolean} - If true, draw debug visualization during findPath */
         this.debug = false;
-        this.debugTime = 2;
+        /** @property {number} - Debug primitive lifetime in seconds (0 disables drawing) */
+        this.debugTime = 1;
 
-        // Pre-allocate the node array — one node per tile, reused across calls.
+        /** @property {Array<PathFinderNode>} - Flat row-major array of size.x*size.y nodes */
         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)
@@ -13595,9 +13826,12 @@ class PathFinder
                 // 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;
+                // Octile heuristic — tightest admissible distance for an
+                // 8-connected grid with cardinal cost 1 and diagonal cost √2.
+                const adx = abs(endNode.pos.x - neighbor.pos.x);
+                const ady = abs(endNode.pos.y - neighbor.pos.y);
+                const h = max(adx, ady) + (Math.SQRT2 - 1) * min(adx, ady);
+                neighbor.f = neighbor.g + h * this.heuristicWeight;
             }
         }
 
@@ -13879,6 +14113,24 @@ class PathFinder
         path.push(original[original.length - 1]);
     }
 
+    /** Drop any middle node that lies exactly on the line through its two
+     *  neighbors. Backstop for the smoothing passes — the corners pass
+     *  intentionally keeps truly-straight runs, and the string-pulling pass
+     *  checks collinearity against the original path, not the in-progress
+     *  result, so it can leave 3+ collinear nodes in some edge cases.
+     *  @param {PathFinderNode[]} path
+     *  @private */
+    dropCollinearNodes(path)
+    {
+        for (let i = path.length - 2; i >= 1; --i)
+        {
+            const a = path[i - 1], b = path[i], c = path[i + 1];
+            if ((b.pos.x - a.pos.x) * (c.pos.y - a.pos.y) ===
+                (b.pos.y - a.pos.y) * (c.pos.x - a.pos.x))
+                path.splice(i, 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
@@ -14046,6 +14298,7 @@ class PathFinder
         {
             this.smoothPathCorners(nodePath);
             this.smoothPathStringPull(nodePath);
+            this.dropCollinearNodes(nodePath);
         }
 
         // Convert to world-space Vector2 path. Return copies, not live node