littlejsengine 1.21.0 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -45,7 +45,8 @@
     "build": "node src/engineBuild.mjs",
     "build-docs": "node tools/buildDocs.mjs",
     "build-release": "node tools/buildRelease.mjs",
-    "test": "node --test --import ./test/setup.mjs \"test/**/*.test.mjs\""
+    "test": "node --test --import ./test/setup.mjs \"test/**/*.test.mjs\"",
+    "test:browser": "node test/browser/run.mjs"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/plugins/gltf.js

@@ -361,7 +361,13 @@ async function loadGLTF(url)
     const response = await fetch(url);
     if (!response.ok)
         throw new Error('loadGLTF failed: ' + url);
-    return parseGLTF(await response.arrayBuffer(), url.slice(0, url.lastIndexOf('/') + 1));
+    // the files beside it are beside where it came from, after any redirect; a blob or data url has nothing
+    // beside it, and a model in one is whole, or parsed with parseGLTF and a base of its own
+    const from = response.url || url;
+    let base = '';
+    if (!/^(blob|data):/i.test(from))
+        base = response.url ? new URL('.', from).href : from.slice(0, from.lastIndexOf('/') + 1);
+    return parseGLTF(await response.arrayBuffer(), base);
 }
 
 /** Parse a model from GLB bytes or glTF JSON, fetching the buffers and images it refers to

package/plugins/lightSystem.js

@@ -20,6 +20,8 @@
  *   shadow map through renderShadow(), which calls render() by default; obj.castShadow = false keeps it
  *   out (a floor TileLayer, a background), a draw's alpha sets how much light it blocks, and
  *   setShadowTransparent lets its color tint the light
+ * - Set light.glow for a soft hazy glow over a light, like a lamp at night; it is added over the lit scene after the
+ *   lightmap, so it shows in the dark and sits in front of everything there
  * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
  * @namespace LightSystem
  */
@@ -156,6 +158,7 @@ class LightSystemPlugin
             // again on a context restore, the canvas may have changed since
             if (lightSystem.textureSizeAuto)
                 lightSystem.textureSize = mainCanvasSize.copy();
+            lightSystem.clampTextureSizes();
 
             // allocate the lightmap texture with null data at textureSize
             lightSystem.texture = glContext.createTexture();
@@ -347,6 +350,7 @@ class LightSystemPlugin
             const ls = lightSystem;
 
             // make the resources the first time, and again when a size changed
+            ls.clampTextureSizes();
             if (!ls.shadowMap || ls.shadowMapSize !== ls.shadowMapSizeAllocated
                 || ls.shadowTextureSize !== ls.shadowTextureSizeAllocated)
             {
@@ -421,13 +425,13 @@ class LightSystemPlugin
             // an automatic size follows the canvas, so reallocate the lightmap when
             // the canvas changed size, after the flush so the batch keeps its texture
             const size = lightSystem.textureSize;
-            if (lightSystem.textureSizeAuto &&
-                (size.x !== mainCanvasSize.x || size.y !== mainCanvasSize.y))
+            const wantX = glClampTextureSize(mainCanvasSize.x), wantY = glClampTextureSize(mainCanvasSize.y);
+            if (lightSystem.textureSizeAuto && (size.x !== wantX || size.y !== wantY))
             {
-                lightSystem.textureSize = mainCanvasSize.copy();
+                lightSystem.textureSize = vec2(wantX, wantY);
                 glContext.bindTexture(glContext.TEXTURE_2D, lightSystem.texture);
                 glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA,
-                    mainCanvasSize.x, mainCanvasSize.y, 0,
+                    wantX, wantY, 0,
                     glContext.RGBA, glContext.UNSIGNED_BYTE, null);
                 // put back the texture the engine tracks, a draw in renderLight must not sample the lightmap
                 if (glActiveTexture)
@@ -534,8 +538,14 @@ class LightSystemPlugin
             //    is, and any debug text / future draw could sample the lightmap)
             if (glActiveTexture)
                 glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
-            setAdditiveBlendMode(prevAdditive);
             glSetInstancedMode(true);
+
+            // 7. the lights' glows, added over the lit scene so the darkness does not dim them
+            setAdditiveBlendMode();
+            for (const o of engineObjects)
+                o instanceof Light && !o.destroyed && o.renderGlow();
+            glFlush();
+            setAdditiveBlendMode(prevAdditive);
         }
         function lightSystemContextLost()
         {
@@ -554,6 +564,19 @@ class LightSystemPlugin
         }
     }
 
+    /** Bring the sizes of the textures it makes down to what the device can make: shadowMapSize, shadowTextureSize
+     *  and a textureSize given by hand; called before they are made, so a size too big falls back instead of failing */
+    clampTextureSizes()
+    {
+        this.shadowMapSize = glClampTextureSize(this.shadowMapSize);
+        this.shadowTextureSize = glClampTextureSize(this.shadowTextureSize);
+        const size = this.textureSize;
+        if (!size) return;
+        const x = glClampTextureSize(size.x), y = glClampTextureSize(size.y);
+        if (x !== size.x || y !== size.y)
+            this.textureSize = vec2(x, y); // only when it is too large, this runs every frame
+    }
+
     /** Draw a single Light's falloff blob into the currently bound lightmap.
      *  Called by Light.renderLight() during the plugin's render pass.
      *  @param {Light} light */
@@ -703,6 +726,14 @@ class Light extends EngineObject
          *  or torch that holds it, or the player carrying it, does not block it; it has to reach past that object's
          *  corners, about half its diagonal and a little more, or dark rays run out from them */
         this.shadowCore = 0;
+        /** @property {number} - Size across of a soft hazy glow drawn over the light, like a lamp at night, 0 for
+         *  none; it is added over the lit scene, in front of everything there */
+        this.glow = 0;
+        /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
+         *  bright core */
+        this.glowFalloff = 1;
+        /** @type {TileInfo|undefined} */
+        this.glowTileInfo = undefined; // the whole glow texture, kept for the falloff it was made for
     }
 
     /** Lights are invisible in the main render pass — they only contribute
@@ -716,4 +747,18 @@ class Light extends EngineObject
     {
         lightSystem && lightSystem.drawLight(this);
     }
+
+    /** Draw this light's glow, soft and round, its glow size across and in its color, added over the lit scene;
+     *  called by LightSystemPlugin after the lightmap is applied */
+    renderGlow()
+    {
+        if (!(this.glow > 0)) return;
+        const size = vec2(this.glow);
+        if (!isOnScreen(this.pos, size)) return;
+        const texture = engineGlowTexture(this.glowFalloff);
+        if (!texture) return;
+        if (this.glowTileInfo?.textureInfo !== texture)
+            this.glowTileInfo = new TileInfo(vec2(), texture.size, texture);
+        drawTile(this.pos, size, this.glowTileInfo, this.color, 0, false, undefined, true, false);
+    }
 }

package/plugins/math3d.js

@@ -338,15 +338,7 @@ class Matrix4
     static rotation(euler, matrix=new Matrix4)
     {
         ASSERT_VECTOR3_VALID(euler);
-        const cx = cos(euler.x), sx = sin(euler.x);
-        const cy = cos(euler.y), sy = sin(euler.y);
-        const cz = cos(euler.z), sz = sin(euler.z);
-        const m = matrix.m;
-        // R = Ry * Rx * Rz written out, column major, every element set so a reused matrix comes out clean
-        m[0] = cy*cz + sy*sx*sz;  m[1] = cx*sz;  m[2]  = -sy*cz + cy*sx*sz; m[3] = 0;
-        m[4] = -cy*sz + sy*sx*cz; m[5] = cx*cz;  m[6]  = sy*sz + cy*sx*cz;  m[7] = 0;
-        m[8] = sy*cx;             m[9] = -sx;    m[10] = cy*cx;             m[11] = 0;
-        m[12] = m[13] = m[14] = 0; m[15] = 1;
+        matrix4RotationAt(matrix.m, 0, euler);
         return matrix;
     }
 
@@ -594,24 +586,54 @@ class Matrix4
  * @memberof Math3D
  */
 function buildMatrix(pos, rotation, scale, matrix=new Matrix4)
+{
+    ASSERT(matrix instanceof Matrix4, 'the matrix to write into must be a Matrix4');
+    matrix4Compose(matrix.m, 0, pos, rotation, scale);
+    return matrix;
+}
+
+// the rotation matrix of euler angles written into 16 floats of an array at k
+function matrix4RotationAt(m, k, euler)
+{
+    const cx = cos(euler.x), sx = sin(euler.x);
+    const cy = cos(euler.y), sy = sin(euler.y);
+    const cz = cos(euler.z), sz = sin(euler.z);
+    // R = Ry * Rx * Rz written out, column major, every element set so a reused matrix comes out clean
+    m[k]   = cy*cz + sy*sx*sz;  m[k+1] = cx*sz;  m[k+2]  = -sy*cz + cy*sx*sz; m[k+3] = 0;
+    m[k+4] = -cy*sz + sy*sx*cz; m[k+5] = cx*cz;  m[k+6]  = sy*sz + cy*sx*cz;  m[k+7] = 0;
+    m[k+8] = sy*cx;             m[k+9] = -sx;    m[k+10] = cy*cx;             m[k+11] = 0;
+    m[k+12] = m[k+13] = m[k+14] = 0; m[k+15] = 1;
+}
+
+// the transform buildMatrix makes, written into 16 floats of an array at k, so an instance buffer takes it straight in
+// the rotation columns are scaled and the position dropped in, instead of multiplying three matrices, each value
+// worked out whole and stored once; InstancedMesh3D.setTransforms writes the same expressions for many at a time
+function matrix4Compose(m, k, pos, rotation, scale)
 {
     ASSERT(!pos || isVector3(pos), 'pos must be a Vector3', pos);
     ASSERT(!scale || isVector3(scale), 'scale must be a Vector3', scale);
-    ASSERT(matrix instanceof Matrix4, 'the matrix to write into must be a Matrix4');
-    // scale the rotation columns and drop the position in, instead of multiplying three matrices
+    const scaleX = scale ? scale.x : 1, scaleY = scale ? scale.y : 1, scaleZ = scale ? scale.z : 1;
     // an object that is not turned at all is most of a big scene, and identity is what the six
     // trig calls would have worked out to anyway
-    const turned = rotation && (rotation.x || rotation.y || rotation.z), m = matrix.m;
-    turned ? Matrix4.rotation(rotation, matrix) : m.set(matrix4Identity);
-    if (scale)
+    if (rotation && (rotation.x || rotation.y || rotation.z))
     {
-        m[0] *= scale.x; m[1] *= scale.x; m[2]  *= scale.x;
-        m[4] *= scale.y; m[5] *= scale.y; m[6]  *= scale.y;
-        m[8] *= scale.z; m[9] *= scale.z; m[10] *= scale.z;
+        ASSERT_VECTOR3_VALID(rotation);
+        const cx = cos(rotation.x), sx = sin(rotation.x);
+        const cy = cos(rotation.y), sy = sin(rotation.y);
+        const cz = cos(rotation.z), sz = sin(rotation.z);
+        // R = Ry * Rx * Rz written out, column major, as matrix4RotationAt, each column times its scale
+        m[k]   = (cy*cz + sy*sx*sz) * scaleX;  m[k+1] = cx*sz * scaleX; m[k+2]  = (-sy*cz + cy*sx*sz) * scaleX;
+        m[k+4] = (-cy*sz + sy*sx*cz) * scaleY; m[k+5] = cx*cz * scaleY; m[k+6]  = (sy*sz + cy*sx*cz) * scaleY;
+        m[k+8] = sy*cx * scaleZ;               m[k+9] = -sx * scaleZ;   m[k+10] = cy*cx * scaleZ;
     }
-    if (pos)
-        m[12] = pos.x, m[13] = pos.y, m[14] = pos.z;
-    return matrix;
+    else
+    {
+        m[k]   = scaleX; m[k+1] = 0;      m[k+2]  = 0;
+        m[k+4] = 0;      m[k+5] = scaleY; m[k+6]  = 0;
+        m[k+8] = 0;      m[k+9] = 0;      m[k+10] = scaleZ;
+    }
+    m[k+3] = m[k+7] = m[k+11] = 0; m[k+15] = 1;
+    m[k+12] = pos ? pos.x : 0, m[k+13] = pos ? pos.y : 0, m[k+14] = pos ? pos.z : 0;
 }
 
 ///////////////////////////////////////////////////////////////////////////////

package/plugins/parallax.js

@@ -0,0 +1,174 @@
+/**
+ * LittleJS Parallax Plugin
+ * - A background layer that follows the camera by a part of its movement, so it looks far away
+ * - Repeats across the view, so a level of any width has a background
+ * - Draws mountains by default, or anything a game draws into it
+ * @namespace Parallax
+ */
+
+'use strict';
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A background layer with parallax: an image that follows the camera by a part of its movement and repeats across
+ * the view, drawn once into a canvas by a function, mountains when none is given
+ * - A far layer has a parallax near 1 and a low renderOrder, a near one a smaller parallax and a higher renderOrder
+ * - The image should meet itself at its left and right edges to repeat without a seam, as the mountains do
+ * @memberof Parallax
+ * @extends CanvasLayer
+ * @example
+ * // three ranges of mountains, the far ones lighter and slower
+ * for (let i = 3; i--;)
+ *     new ParallaxLayer(vec2(0, i*2), vec2(40, 20), .9 - i*.2, -1e3 + i,
+ *         parallaxMountains(hsl(.6, .3, .7 - i*.2), hsl(.6, .5, .2), i));
+ *
+ * // or draw your own image into the layer
+ * new ParallaxLayer(vec2(), vec2(40, 20), .5, -1e3, (context, size)=>
+ * {
+ *     context.fillStyle = '#fff';
+ *     context.fillRect(size.x/2 - 20, size.y/2 - 20, 40, 40);
+ * });
+ */
+class ParallaxLayer extends CanvasLayer
+{
+    /** Create a parallax layer and draw its image
+     *  @param {Vector2} [pos] - Where the middle of the image is in the world when the camera is there too
+     *  @param {Vector2} [size] - World size of one copy of the image
+     *  @param {number|Vector2} [parallax] - How much of the camera's movement it follows, 0 stays with the world
+     *    and 1 with the screen, a Vector2 to follow x and y by different amounts
+     *  @param {number} [renderOrder] - Low to draw behind the game, far layers lowest
+     *  @param {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} [drawFunction] - Draws
+     *    the image, given the canvas context, its size in pixels and the layer; mountains when not given
+     *  @param {Vector2} [canvasSize] - Size of the image in pixels */
+    constructor(pos=vec2(), size=vec2(32, 16), parallax=.5, renderOrder=-1e3, drawFunction=parallaxMountains(),
+        canvasSize=vec2(512, 256))
+    {
+        ASSERT(isNumber(parallax) || isVector2(parallax), 'parallax must be a number or a Vector2');
+        ASSERT(typeof drawFunction == 'function', 'drawFunction must be a function');
+        super(pos, size, 0, renderOrder, canvasSize);
+
+        /** @property {Vector2} - How much of the camera's movement it follows on each axis, 0 stays with the world
+         *  and 1 with the screen */
+        this.parallax = isVector2(parallax) ? /** @type {Vector2} */ (parallax).copy() :
+            vec2(/** @type {number} */ (parallax));
+        /** @property {boolean} - Repeat the image across the view, left and right */
+        this.wrapX = true;
+        /** @property {boolean} - Repeat the image up and down the view */
+        this.wrapY = false;
+        /** @property {number} - How much the camera's zoom changes its size on the screen: 1 like the world, 0 not
+         *  at all, the same on the screen at any zoom as it is at zoomScale */
+        this.zoomFollow = 1;
+        /** @property {number} - The camera scale its size is given for, used when zoomFollow is under 1 */
+        this.zoomScale = cameraScale;
+        /** @property {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} - Draws the
+         *  image, redraw() after changing it */
+        this.drawFunction = drawFunction;
+        this.redraw();
+    }
+
+    /** Draw the image again with drawFunction, after changing it or what it draws from */
+    redraw()
+    {
+        const context = this.context;
+        if (!context) return; // headless
+        const size = vec2(this.canvas.width, this.canvas.height);
+        context.clearRect(0, 0, size.x, size.y);
+        this.drawFunction(context, size, this);
+        this.updateWebGL();
+    }
+
+    // how much smaller it is drawn than its size, from the camera's zoom and how much of it the layer follows
+    zoomFactor()
+    { return this.zoomFollow < 1 && cameraScale > 0 ? (this.zoomScale / cameraScale) ** (1 - this.zoomFollow) : 1; }
+
+    /** World size one copy of the image is drawn at now, its size unless zoomFollow is under 1
+     *  @return {Vector2} */
+    getDrawSize() { return this.size.scale(this.zoomFactor()); }
+
+    /** Where each copy of the image is drawn now, in the world: one place, or with wrapping every place that
+     *  shows in the view
+     *  @return {Array<Vector2>} */
+    getDrawPositions()
+    {
+        // its place seen from the camera is cut down by the parallax, and by the zoom it does not follow
+        const zoom = this.zoomFactor(), size = this.size.scale(zoom), p = this.parallax;
+        const offset = this.pos.subtract(cameraPos);
+        const center = cameraPos.add(vec2(offset.x * (1 - p.x) * zoom, offset.y * (1 - p.y) * zoom));
+
+        // the copies that reach into the view; a turned camera sees as far as its corner each way
+        const view = mainCanvasSize.scale(.5 / (cameraScale || 1));
+        const reach = cameraAngle ? vec2(view.length()) : view;
+        const range = (wrap, axis)=>
+        {
+            if (!wrap || !(size[axis] > 0)) return [0, 0];
+            const from = cameraPos[axis] - reach[axis] - size[axis] / 2 - center[axis];
+            const to = cameraPos[axis] + reach[axis] + size[axis] / 2 - center[axis];
+            const first = ceil(from / size[axis]);
+            return [first, min(floor(to / size[axis]), first + 99)]; // a tiny image does not draw without end
+        };
+        const [x0, x1] = range(this.wrapX, 'x'), [y0, y1] = range(this.wrapY, 'y'), positions = [];
+        for (let y = y0; y <= y1; ++y)
+        for (let x = x0; x <= x1; ++x)
+            positions.push(vec2(center.x + x * size.x, center.y + y * size.y));
+        return positions;
+    }
+
+    // Render the layer, called automatically by the engine
+    render()
+    {
+        const size = this.getDrawSize();
+        for (const pos of this.getDrawPositions())
+            this.draw(pos, size, this.color, 0, this.mirror, this.additiveColor, false);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+// the ridge of a range of mountains: a height for each column of an image and one more, the last the same as the
+// first so the image repeats with no step; it wanders about the middle, turning now and then
+function parallaxRidge(width, height, random)
+{
+    const pointiness = .2, levelness = .005, slopeRange = height / 256; // how often it turns, how hard it is
+    const ridge = new Float32Array(width + 1), middle = height / 2;     // pulled level, how steep it gets
+    let y = middle, slope = random.float(-slopeRange, slopeRange);
+    for (let x = 0; x <= width; ++x)
+    {
+        ridge[x] = y;
+        y += slope -= (y - middle) * levelness;
+        if (random.float() < pointiness)
+            slope = random.float(-slopeRange, slopeRange);
+    }
+    // take out the difference between its ends, a little from each column, and keep it inside the image
+    const drift = ridge[width] - ridge[0];
+    for (let x = 0; x <= width; ++x)
+        ridge[x] = clamp(ridge[x] - drift * x / width, 0, height);
+    return ridge;
+}
+
+/** A draw function for a ParallaxLayer: a range of mountains across the image, shaded from the color of their
+ *  peaks down to the color of their feet, that repeats with no seam
+ *  @param {Color} [topColor] - Color at the peaks
+ *  @param {Color} [bottomColor] - Color at the bottom of the image
+ *  @param {number} [seed] - The same seed gives the same mountains, random when not given
+ *  @return {function(OffscreenCanvasRenderingContext2D, Vector2): void}
+ *  @memberof Parallax */
+function parallaxMountains(topColor=hsl(.6, .2, .6), bottomColor=hsl(.6, .3, .25), seed)
+{
+    return (context, size)=>
+    {
+        const w = size.x, h = size.y;
+        const random = new RandomGenerator(seed === undefined ? randInt(1e9) + 1 : seed * 7919 + 1);
+        const ridge = parallaxRidge(w, h, random);
+
+        // a strip one pixel wide with the shading, stretched down each column from its peak
+        const strip = createCanvasContext(1, h);
+        for (let i = h; i--;)
+        {
+            strip.fillStyle = topColor.lerp(bottomColor, i / h).toString();
+            strip.fillRect(0, i, 1, 1);
+        }
+        for (let x = w; x--;)
+            ridge[x] < h && context.drawImage(strip.canvas, 0, 0, 1, h, x, ridge[x], 1, h - ridge[x]);
+    };
+}