littlejsengine 1.18.2 → 1.18.4

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; }
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -401,6 +407,96 @@ 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');
+
+    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 +1020,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 +1075,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);

package/src/engineExport.js

@@ -51,6 +51,7 @@ export
     cameraPos,
     cameraAngle,
     cameraScale,
+    timeScale,
     canvasColorTiles,
     canvasClearColor,
     canvasMaxSize,
@@ -98,6 +99,7 @@ export
     setCameraPos,
     setCameraAngle,
     setCameraScale,
+    setTimeScale,
     setCanvasColorTiles,
     setCanvasClearColor,
     setCanvasMaxSize,
@@ -246,6 +248,7 @@ export
     drawTile,
     drawRect,
     drawRectGradient,
+    drawTextureWrapped,
     drawLineList,
     drawLine,
     drawPoly,
@@ -312,6 +315,8 @@ export
     gamepadStick,
     gamepadDpad,
     gamepadConnected,
+    gamepadVibrate,
+    gamepadVibrateStop,
     vibrate,
     vibrateStop,
     pointerLockRequest,

package/src/engineInput.js

@@ -260,6 +260,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

package/src/engineSettings.js

@@ -27,6 +27,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
 
@@ -355,6 +367,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

package/src/engineWebGL.js

@@ -304,9 +304,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;
@@ -314,11 +313,6 @@ function glSetTexture(texture, wrap=false)
     glFlush();
     glActiveTexture = texture;
     glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
-
-    // 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);
 }
 
 /** Compile WebGL shader of the given type, will throw errors if in debug mode
@@ -393,6 +387,8 @@ 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);
+    glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_S, glContext.REPEAT);
+    glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_WRAP_T, glContext.REPEAT);
     if (mipMap)
         glContext.generateMipmap(glContext.TEXTURE_2D);
 

package/test/smoke.test.mjs

@@ -256,3 +256,19 @@ test('TileLayer extends CanvasLayer and stubs render methods in headless', () =>
     assert.doesNotThrow(() => tl.render());
     assert.doesNotThrow(() => tl.redraw());
 });
+
+test('drawTextureWrapped is exported', async () =>
+{
+    const mod = await import('../dist/littlejs.esm.js');
+    assert.equal(typeof mod.drawTextureWrapped, 'function');
+});
+
+test('drawTextureWrapped is callable in headless mode', async () =>
+{
+    const mod = await import('../dist/littlejs.esm.js');
+    const { drawTextureWrapped, vec2 } = mod;
+    // headlessMode short-circuits before texture lookup, so this just
+    // exercises argument-type ASSERTs (which are stripped in release)
+    assert.doesNotThrow(() =>
+        drawTextureWrapped(vec2(), vec2(1, 1), vec2(2, 2)));
+});