littlejsengine 1.18.2 → 1.18.7

package/plugins/uiSystem.js

@@ -118,16 +118,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)
         {
@@ -469,8 +466,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)
@@ -893,15 +905,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)
@@ -924,7 +934,7 @@ class UIObject
 
     /** Internal function called when object is clicked
      *  @param {boolean} [playSound] */
-    click(playSound)
+    click(playSound=true)
     {
         this.onClick(); 
         if (playSound && this.soundClick)
@@ -1495,4 +1505,133 @@ 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);
+    }
 }

package/src/engine.js

@@ -32,7 +32,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}
@@ -66,7 +66,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;
@@ -197,11 +197,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;
@@ -559,143 +562,4 @@ 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();
 }

package/src/engineAudio.js

@@ -14,10 +14,12 @@
 
 'use strict';
 
-/** 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}
@@ -33,12 +35,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
@@ -105,8 +108,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;

package/src/engineBuild.mjs

@@ -33,17 +33,20 @@ const engineSourceFiles =
     `${SOURCE_FOLDER}/engineAudio.js`,
     `${SOURCE_FOLDER}/engineTileLayer.js`,
     `${SOURCE_FOLDER}/engineParticles.js`,
-    `${SOURCE_FOLDER}/engineMedals.js`,
     `${SOURCE_FOLDER}/engineWebGL.js`,
+    `${SOURCE_FOLDER}/engineLogo.js`,
 ];
 const enginePluginFiles =
 [
+    `${PLUGIN_FOLDER}/medalSystem.js`,
     `${PLUGIN_FOLDER}/newgrounds.js`,
     `${PLUGIN_FOLDER}/postProcess.js`,
     `${PLUGIN_FOLDER}/zzfxm.js`,
     `${PLUGIN_FOLDER}/uiSystem.js`,
     `${PLUGIN_FOLDER}/box2d.js`,
     `${PLUGIN_FOLDER}/drawUtilities.js`,
+    `${PLUGIN_FOLDER}/tweenSystem.js`,
+    `${PLUGIN_FOLDER}/pathFinder.js`,
 ];
 const engineExtraFiles =
 [

package/src/engineDebug.js

@@ -44,7 +44,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

package/src/engineDraw.js

@@ -72,6 +72,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; }
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -211,8 +217,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;
@@ -222,6 +229,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();
     }
 
@@ -234,6 +243,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);
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -295,8 +312,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
@@ -401,6 +423,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]
@@ -924,6 +1038,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
@@ -942,8 +1093,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);