littlejsengine 1.18.19 → 1.18.22

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.19';
+const engineVersion = '1.18.22';
 
 /** Frames per second to update
  *  @type {number}
@@ -474,6 +474,11 @@ function engineObjectsUpdate()
     // get list of solid objects for physics optimization
     engineObjectsCollide = engineObjects.filter(o=>o.collideSolidObjects);
 
+    // update physics before object update
+    for (const o of engineObjects)
+        if (!o.parent && !o.destroyed)
+            o.updatePhysics();
+
     // recursive object update
     function updateChildObject(o)
     {
@@ -489,7 +494,6 @@ function engineObjectsUpdate()
 
         // update top level objects
         o.update();
-        o.updatePhysics();
         for (const child of o.children)
             updateChildObject(child);
         o.updateTransforms();
@@ -815,7 +819,7 @@ function smoothStep(percent) { return percent * percent * (3 - 2 * percent); }
  *  @param {number} value
  *  @return {boolean}
  *  @memberof Math */
-function isPowerOfTwo(value) { return !(value & (value - 1)); }
+function isPowerOfTwo(value) { return value > 0 && !(value & (value - 1)); }
 
 /** Returns the nearest power of two not less than the value
  *  @param {number} value
@@ -892,7 +896,7 @@ function isIntersecting(start, end, pos, size)
  *  @memberof Math */
 function oscillate(frequency=1, amplitude=1, t=time, offset=0, type=0)
 {
-    const phase = (offset + t*frequency) % 1;
+    const phase = mod(offset + t*frequency, 1);
     let value;
     
     if (type === 1) // triangle
@@ -1828,7 +1832,7 @@ const MAGENTA = debugProtectConstant(rgb(1,0,1));
 class Timer
 {
     /** Create a timer object set time passed in
-     *  @param {number} [timeLeft] - How much time left before the timer 
+     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
      *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
     constructor(timeLeft, useRealTime=false)
     {
@@ -2427,6 +2431,7 @@ let vibrateEnable = true;
 let soundEnable = true;
 
 /** Volume scale to apply to all sound, music and speech
+ *  Use setSoundVolume to also update the audio master gain immediately
  *  @type {number}
  *  @default
  *  @memberof Settings */
@@ -3471,8 +3476,9 @@ class TileInfo
      *  @param {TextureInfo} [textureInfo] - Texture info to use
      *  @param {number} [padding] - How many pixels padding around all sides of each tile (increases grid size, does not affect tile size)
      *  @param {number} [bleed] - How many pixels smaller to shrink UVS of tiles (does not affect grid size, only UVs)
+     *  @param {number} [columns] - How many frames per row for frame(), 0 to keep frames on a single row
      */
-    constructor(pos=vec2(), size=tileDefaultSize, textureInfo=textureInfos[0], padding=tileDefaultPadding, bleed=tileDefaultBleed)
+    constructor(pos=vec2(), size=tileDefaultSize, textureInfo=textureInfos[0], padding=tileDefaultPadding, bleed=tileDefaultBleed, columns=0)
     {
         /** @property {Vector2} - Top left corner of tile in pixels */
         this.pos = pos.copy();
@@ -3484,6 +3490,8 @@ class TileInfo
         this.textureInfo = textureInfo;
         /** @property {number} - Shrinks tile by this many pixels to prevent neighbors bleeding */
         this.bleed = bleed;
+        /** @property {number} - How many frames per row for frame(), 0 to keep frames on a single row */
+        this.columns = columns;
     }
 
     /** Returns a copy of this tile offset by a vector
@@ -3491,9 +3499,10 @@ class TileInfo
     *  @return {TileInfo}
     */
     offset(offset)
-    { return new TileInfo(this.pos.add(offset), this.size, this.textureInfo, this.padding, this.bleed); }
+    { return new TileInfo(this.pos.add(offset), this.size, this.textureInfo, this.padding, this.bleed, this.columns); }
 
     /** Returns a copy of this tile offset by a number of animation frames
+    *  Frames wrap down to the next row if columns is set
     *  @param {number} frame - Offset to apply in animation frames
     *  @return {TileInfo}
     */
@@ -3501,11 +3510,33 @@ class TileInfo
     {
         ASSERT(typeof frame === 'number');
         const w = this.size.x + this.padding*2;
-        const x = frame*w;
-        ASSERT(x + this.size.x <= this.textureInfo.size.x, 'frame extends beyond texture width!');
-        return this.offset(new Vector2(x));
+        const h = this.size.y + this.padding*2;
+        const x = (this.columns ? frame % this.columns : frame) * w;
+        const y = (this.columns ? frame / this.columns | 0 : 0) * h;
+        ASSERT(this.pos.x + x + this.size.x <= this.textureInfo.size.x, 'frame extends beyond texture width!');
+        ASSERT(this.pos.y + y + this.size.y <= this.textureInfo.size.y, 'frame extends beyond texture height!');
+        return this.offset(new Vector2(x, y));
+    }
+
+    /** Set how many frames per row this tile uses, so frame() can wrap
+    *  @param {number} [columns] - Frames per row, 0 to keep frames on a single row
+    *  @return {TileInfo}
+    */
+    setColumns(columns=0)
+    {
+        ASSERT(isNumber(columns) && columns >= 0, 'columns must be a number >= 0');
+        this.columns = columns;
+        return this;
     }
 
+    /**
+     * Returns a tile info for an index using this tile as reference
+     * @param {Vector2|number} [index=0]
+     * @return {TileInfo}
+     */
+    index(index)
+    { return tile(index, this.size, this.textureInfo, this.padding, this.bleed).setColumns(this.columns); }
+
     /**
      * Set this tile to use a full image in a texture info
      * @param {TextureInfo} [textureInfo]
@@ -3516,17 +3547,9 @@ class TileInfo
         this.textureInfo = textureInfo;
         this.pos = new Vector2;
         this.size = textureInfo.size.copy();
-        this.bleed = this.padding = 0;
+        this.bleed = this.padding = this.columns = 0;
         return this;
     }
-
-    /**
-     * Returns a tile info for an index using this tile as reference
-     * @param {Vector2|number} [index=0]
-     * @return {TileInfo}
-     */
-    tile(index)
-    { return tile(index, this.size, this.textureInfo, this.padding, this.bleed); }
 }
 
 /**
@@ -5224,7 +5247,10 @@ function inputInit()
     {
         inputData[0][e.code] = (inputData[0][e.code]&2) | 4;
         if (inputWASDEmulateDirection)
-            inputData[0][remapKey(e.code)] = 4;
+        {
+            const remap = remapKey(e.code);
+            inputData[0][remap] = (inputData[0][remap]&2) | 4;
+        }
     }
     function remapKey(k)
     {
@@ -5299,7 +5325,7 @@ function inputInit()
         document.addEventListener('touchend',   (e)=> handleTouch(e), { passive: false });
 
         // handle all touch events the same way
-        let wasTouching;
+        let wasTouching, touchIdentifier;
         function handleTouch(e)
         {
             if (!touchInputEnable) return;
@@ -5330,10 +5356,11 @@ function inputInit()
                     const pos = vec2(gameTouches[0].clientX, gameTouches[0].clientY);
                     const mousePosScreenLast = mousePosScreen;
                     mousePosScreen = mouseEventToScreen(pos);
-                    if (wasTouching)
+                    if (wasTouching && gameTouches[0].identifier === touchIdentifier)
                         mouseDeltaScreen = mouseDeltaScreen.add(mousePosScreen.subtract(mousePosScreenLast));
-                    else
+                    else if (!wasTouching)
                         inputData[0][button] = 3;
+                    touchIdentifier = gameTouches[0].identifier;
                 }
                 else if (wasTouching)
                     inputData[0][button] = inputData[0][button] & 2 | 4;
@@ -6491,7 +6518,7 @@ class SoundInstance
  *  @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
+ *  @return {SpeechSynthesisUtterance|undefined} - The utterance that was spoken, or undefined if speech is unavailable
  *  @memberof Audio */
 function speak(text, volume=1, rate=1, pitch=1, language='')
 {
@@ -6544,7 +6571,7 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {number}   [pan] - How much to apply stereo panning
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
  *  @param {number}   [sampleRate=44100] - Sample rate for the sound
- *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
+ *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
  *  @param {number}   [offset] - Offset in seconds to start playback from
  *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
  *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
@@ -6786,10 +6813,14 @@ function tileCollisionGetData(pos, solidOnly=true)
     // check all tile collision layers
     for (const layer of tileCollisionLayers)
         if (!solidOnly || layer.isSolid)
-        if (pos.arrayCheck(layer.size))
         {
-            const data = layer.getCollisionData(pos);
-            if (data) return data;
+            // convert world pos to layer local space
+            const layerPos = pos.subtract(layer.pos);
+            if (layerPos.arrayCheck(layer.size))
+            {
+                const data = layer.getCollisionData(layerPos);
+                if (data) return data;
+            }
         }
     return 0;
 }
@@ -7064,7 +7095,7 @@ class TileLayer extends CanvasLayer
         
         /** @property {TileInfo} - Default tile info for layer */
         this.tileInfo = undefined;
-        /** @property {Array<TileLayerData>} - Default tile info for layer */
+        /** @property {Array<TileLayerData>} - Array of tile data for the layer */
         this.data = [];
         /** @property {boolean} - Is this layer using a webgl texture? */
         this.isUsingWebGL = false;
@@ -7149,7 +7180,7 @@ class TileLayer extends CanvasLayer
 
         const size = this.drawSize || this.size;
         const pos = this.pos.add(size.scale(.5));
-        this.draw(pos, this.size, this.color, this.angle, this.mirror, this.additiveColor);
+        this.draw(pos, size, this.color, this.angle, this.mirror, this.additiveColor);
     }
 
     /** Called after this layer is redrawn, does nothing by default */
@@ -7238,7 +7269,7 @@ class TileLayer extends CanvasLayer
         const d = this.getData(layerPos);
         if (!d || !d.tile) return;
 
-        const tileInfo = this.tileInfo && this.tileInfo.tile(d.tile);
+        const tileInfo = this.tileInfo && this.tileInfo.index(d.tile);
         this.drawLayerTile(drawPos, drawSize, tileInfo, d.color, d.direction*PI/2, d.mirror);
     }
 
@@ -7532,8 +7563,8 @@ class TileCollisionLayer extends TileLayer
  *     rgb(1,1,1,1), rgb(0,0,0,1), // colorStartA, colorStartB
  *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
  *     1, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
- *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate,
- *     .5, 1                // randomness, collide, additive, randomColorLinear, renderOrder
+ *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate
+ *     .5, 1                // randomness, collide
  * );
  */
 class ParticleEmitter extends EngineObject
@@ -7925,13 +7956,12 @@ class Particle
             const hitLayer = tileCollisionTest(this.pos);
             if (!testCollision(oldPos))
             {
-                // testCollision already invoked collideCallback with the
-                // correct (this, data, pos) args; no need to re-check here.
                 // test which side we bounced off (or both if a corner)
                 const isBlockedX = testCollision(vec2(this.pos.x, oldPos.y));
                 const isBlockedY = testCollision(vec2(oldPos.x, this.pos.y));
-                const hitRestitution = max(restitution, hitLayer.restitution);
-                const hitFriction = max(friction, hitLayer.friction);
+                // collide callback may hit where the layer test does not, so hitLayer can be undefined
+                const hitRestitution = hitLayer ? max(restitution, hitLayer.restitution) : restitution;
+                const hitFriction = hitLayer ? max(friction, hitLayer.friction) : friction;
                 if (isBlockedX)
                 {
                     // move to previous X position and bounce
@@ -9580,7 +9610,8 @@ class NewgroundsPlugin
             return;
         }
         debugMedals && LOG(xmlHttp.responseText);
-        return xmlHttp.responseText && JSON.parse(xmlHttp.responseText);
+        try { return xmlHttp.responseText && JSON.parse(xmlHttp.responseText); }
+        catch(e) { debugMedals && LOG('newgrounds response is not valid JSON', e); }
     }
 }
 /**
@@ -9599,8 +9630,8 @@ class NewgroundsPlugin
 let postProcess;
 
 /////////////////////////////////////////////////////////////////////////
-/** 
- * UI System Global Object
+/**
+ * Post Process Plugin - Applies a full screen shader to the rendered output
  * @memberof PostProcess
  */
 class PostProcessPlugin
@@ -9714,8 +9745,9 @@ class PostProcessPlugin
                 workCanvas.height = mainCanvasSize.y;
                 glCopyToContext(workContext);
                 workContext.drawImage(mainCanvas, 0, 0);
-                mainCanvas.width |= 0
-                
+                mainCanvas.width |= 0; // setting size clears the main canvas
+
+
                 // copy work canvas to texture
                 glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, workCanvas);
             }
@@ -10820,7 +10852,7 @@ class UISystemPlugin
     }
 
     /** Get other axis navigation direction from gamepad or keyboard
-     *  @return {Vector2} */
+     *  @return {number} */
     getNavigationOtherDirection()
     {
         if (uiSystem.navigationDirection === 2)
@@ -10909,6 +10941,7 @@ class UISystemPlugin
             uiSystem.navigationDirection = savedNavigationDirection;
             inputClear();
         }
+        return confirmMenu;
     }
 }
 
@@ -11342,7 +11375,7 @@ class UITextInput extends UIObject
         this.onClick();
     }
 
-    /** Stop editing the text edited */
+    /** Stop editing the text */
     stopEditing()
     {
         if (!this.isKeyInputObject())
@@ -11505,7 +11538,7 @@ class UICheckbox extends UIObject
         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 */
+        /** @property {boolean} - Is the checkbox currently checked? */
         this.checked = checked;
         // set properties
         this.text = text;
@@ -12270,7 +12303,7 @@ class Box2dObject extends EngineObject
             shape.set_m_vertex3(box2d.vec2dTo(getPoint(i+2)));
             const f = this.addShape(shape, density, friction, restitution, isSensor);
             fixtures.push(f);
-            i < points.length && edgePoints.push(points[i].copy());
+            edgePoints.push(points[i].copy());
         }
         this.edgeLoops.push(edgePoints);
         return fixtures;
@@ -12336,7 +12369,7 @@ class Box2dObject extends EngineObject
     /** Sets the position
      *  @param {Vector2} pos */
     setPosition(pos)
-    { this.setTransform(pos, this.body.GetAngle()); }
+    { this.setTransform(pos, -this.body.GetAngle()); }
 
     /** Sets the angle
      *  @param {number} angle */
@@ -12433,6 +12466,7 @@ class Box2dObject extends EngineObject
             filter.set_categoryBits(categoryBits);
             filter.set_maskBits(0xffff & ~ignoreCategoryBits);
             filter.set_groupIndex(groupIndex);
+            fixture.SetFilterData(filter); // applies and refilters contacts
         });
     }
 
@@ -12968,7 +13002,7 @@ class Box2dRevoluteJoint extends Box2dJoint
         jointDef.set_bodyB(objectB.body);
         jointDef.set_localAnchorA(box2d.vec2dTo(localAnchorA));
         jointDef.set_localAnchorB(box2d.vec2dTo(localAnchorB));
-        jointDef.set_referenceAngle(objectA.body.GetAngle() - objectB.body.GetAngle());
+        jointDef.set_referenceAngle(objectB.body.GetAngle() - objectA.body.GetAngle());
         jointDef.set_collideConnected(collide);
         super(jointDef);
     }
@@ -13115,14 +13149,14 @@ class Box2dPrismaticJoint extends Box2dJoint
         anchor ||= box2d.vec2From(objectB.body.GetPosition());
         const localAnchorA = objectA.worldToLocal(anchor);
         const localAnchorB = objectB.worldToLocal(anchor);
-        const localAxisA = objectB.worldToLocalVector(worldAxis);
+        const localAxisA = objectA.worldToLocalVector(worldAxis);
         const jointDef = new box2d.instance.b2PrismaticJointDef();
         jointDef.set_bodyA(objectA.body);
         jointDef.set_bodyB(objectB.body);
         jointDef.set_localAnchorA(box2d.vec2dTo(localAnchorA));
         jointDef.set_localAnchorB(box2d.vec2dTo(localAnchorB));
         jointDef.set_localAxisA(box2d.vec2dTo(localAxisA));
-        jointDef.set_referenceAngle(objectA.body.GetAngle() - objectB.body.GetAngle());
+        jointDef.set_referenceAngle(objectB.body.GetAngle() - objectA.body.GetAngle());
         jointDef.set_collideConnected(collide);
         super(jointDef);
     }
@@ -13225,7 +13259,7 @@ class Box2dWheelJoint extends Box2dJoint
         anchor ||= box2d.vec2From(objectB.body.GetPosition());
         const localAnchorA = objectA.worldToLocal(anchor);
         const localAnchorB = objectB.worldToLocal(anchor);
-        const localAxisA = objectB.worldToLocalVector(worldAxis);
+        const localAxisA = objectA.worldToLocalVector(worldAxis);
         const jointDef = new box2d.instance.b2WheelJointDef();
         jointDef.set_bodyA(objectA.body);
         jointDef.set_bodyB(objectB.body);
@@ -13325,7 +13359,7 @@ class Box2dWeldJoint extends Box2dJoint
         jointDef.set_bodyB(objectB.body);
         jointDef.set_localAnchorA(box2d.vec2dTo(localAnchorA));
         jointDef.set_localAnchorB(box2d.vec2dTo(localAnchorB));
-        jointDef.set_referenceAngle(objectA.body.GetAngle() - objectB.body.GetAngle());
+        jointDef.set_referenceAngle(objectB.body.GetAngle() - objectA.body.GetAngle());
         jointDef.set_collideConnected(collide);
         super(jointDef);
     }
@@ -13772,7 +13806,7 @@ class Box2dPlugin
      *  @param {number} [lineWidth]
      *  @param {boolean} [useWebGL=glEnable]
      *  @param {CanvasRenderingContext2D} [context] */
-    drawFixture(fixture, pos, angle, color=WHITE, lineColor=BLACK, lineWidth=.1, useWebgl, context)
+    drawFixture(fixture, pos, angle, color=WHITE, lineColor=BLACK, lineWidth=.1, useWebGL, context)
     {
         const shape = box2d.castShapeObject(fixture.GetShape());
         switch (shape.GetType())
@@ -13782,20 +13816,20 @@ class Box2dPlugin
                 let points = [];
                 for (let i=shape.GetVertexCount(); i--;)
                     points.push(box2d.vec2From(shape.GetVertex(i)));
-                drawPoly(points, color, lineWidth, lineColor, pos, angle, useWebgl, false, context);
+                drawPoly(points, color, lineWidth, lineColor, pos, angle, useWebGL, false, context);
                 break;
             }
             case box2d.instance.b2Shape.e_circle:
             {
                 const radius = shape.get_m_radius();
-                drawCircle(pos, radius*2, color, lineWidth, lineColor, useWebgl, false, context);
+                drawCircle(pos, radius*2, color, lineWidth, lineColor, useWebGL, false, context);
                 break;
             }
             case box2d.instance.b2Shape.e_edge:
             {
                 const v1 = box2d.vec2From(shape.get_m_vertex1());
                 const v2 = box2d.vec2From(shape.get_m_vertex2());
-                drawLine(v1, v2, lineWidth, lineColor, pos, angle, useWebgl, false, context);
+                drawLine(v1, v2, lineWidth, lineColor, pos, angle, useWebGL, false, context);
                 break;
             }
         }
@@ -14200,6 +14234,444 @@ function getCrescentPoints(pos, size=1, percent=0, angle=0, invert=false, sides=
     }
     return points;
 }
+/**
+ * LittleJS Texture Sheet Plugin
+ * - Packs images into texture sheets as they are loaded
+ * - Sprites are placed automatically, callers get a TileInfo
+ * - Sheets are created and filled as needed
+ * - Sheets fill in call order, images decode in parallel
+ * - Animation frames keep layout and wrap across rows as needed
+ * - WebGL textures upload once per batch of loads
+ * - loadAtlas imports pre-packed atlases (TexturePacker and Aseprite json)
+ * @namespace TextureSheets
+ */
+
+/** Width and height in pixels of texture sheets created by loadSprite
+ *  @type {number}
+ *  @default
+ *  @memberof Settings */
+let textureSheetSize = 2048;
+
+/** Default padding pixels around each frame packed by loadSprite
+ *  @type {number}
+ *  @default
+ *  @memberof Settings */
+let textureSheetPadding = 1;
+
+/** Array of texture sheets created by loadSprite
+ *  @type {Array<TextureSheet>}
+ *  @memberof TextureSheets */
+let textureSheets = [];
+
+// pending loads pack through a queue so sheets fill in call order
+let textureSheetQueue = Promise.resolve();
+let textureSheetPendingCount = 0;
+
+/**
+ * Texture Sheet - A texture that images are packed into as they load
+ * Uses shelf packing, images are placed left to right then wrap to a new row
+ * @memberof TextureSheets
+ */
+class TextureSheet
+{
+    /** Create a texture sheet, called automatically by loadSprite
+     *  @param {number} [size] - Width and height of the sheet in pixels */
+    constructor(size=textureSheetSize)
+    {
+        ASSERT(size > 0, 'texture sheet size must be positive');
+
+        /** @property {number} - Width and height of the sheet in pixels */
+        this.size = size;
+        /** @property {OffscreenCanvas} - Canvas holding the packed images */
+        this.canvas = headlessMode ? undefined : new OffscreenCanvas(size, size);
+        /** @property {OffscreenCanvasRenderingContext2D} - 2d context for the canvas */
+        this.context = this.canvas?.getContext('2d');
+        /** @property {TextureInfo} - The texture info for this sheet */
+        this.textureInfo = new TextureInfo(this.canvas);
+        /** @property {Vector2} - Where the next image will be packed */
+        this.cursor = vec2();
+        /** @property {number} - Height of the row being packed */
+        this.rowHeight = 0;
+        /** @property {boolean} - Has the canvas changed since the last webgl upload? */
+        this.glDirty = false;
+
+        if (headlessMode)
+        {
+            // tiles still need bounds when there is no canvas to measure
+            this.textureInfo.size = vec2(size);
+            this.textureInfo.sizeInverse = vec2(1/size);
+        }
+    }
+
+    /** Find a spot for an image on this sheet without drawing it
+     *  @param {Vector2} imageSize - Size of the source image in pixels
+     *  @param {Vector2} [frameSize] - Size of each frame, or the whole image if not passed
+     *  @param {number} [padding] - How many pixels padding around each frame
+     *  @return {TileInfo} Tile for the packed image, or undefined if the sheet is full */
+    tryAdd(imageSize, frameSize=imageSize, padding=textureSheetPadding)
+    {
+        ASSERT(isVector2(imageSize) && isVector2(frameSize), 'sizes must be vec2');
+        ASSERT(frameSize.x > 0 && frameSize.y > 0, 'frame size must be positive');
+        ASSERT(imageSize.x % frameSize.x === 0 && imageSize.y % frameSize.y === 0,
+            'image size must be a multiple of the frame size');
+
+        const cellWidth = frameSize.x + padding*2;
+        const cellHeight = frameSize.y + padding*2;
+        const maxColumns = this.size / cellWidth | 0;
+        ASSERT(maxColumns > 0, 'frame is too wide to fit on a texture sheet');
+
+        // keep the layout of the source image, but narrow it if a row is too wide
+        // frames wrap down to the next row, which TileInfo.frame handles via columns
+        const sourceColumns = imageSize.x / frameSize.x;
+        const frameCount = sourceColumns * (imageSize.y / frameSize.y);
+        const columns = min(sourceColumns, maxColumns);
+        const blockWidth = columns * cellWidth;
+        const blockHeight = ceil(frameCount / columns) * cellHeight;
+
+        // probe the placement using locals so a failed try leaves the sheet unchanged
+        let x = this.cursor.x, y = this.cursor.y, rowHeight = this.rowHeight;
+        if (x + blockWidth > this.size)
+        {
+            // start a new row if this one does not have enough space left
+            x = 0;
+            y += rowHeight;
+            rowHeight = 0;
+        }
+
+        // out of space, the caller needs to use a different sheet
+        if (y + blockHeight > this.size)
+            return undefined;
+
+        // commit the placement, tile pos points inside the padding to match how tile() works
+        this.cursor.x = x + blockWidth;
+        this.cursor.y = y;
+        this.rowHeight = max(rowHeight, blockHeight);
+        return new TileInfo(vec2(x + padding, y + padding), frameSize, this.textureInfo, padding, 0, columns);
+    }
+
+    /** Draw an image into this sheet at a tile returned by tryAdd
+     *  @param {HTMLImageElement} image - Source image to copy from
+     *  @param {TileInfo} tileInfo - Where to put it, from tryAdd
+     *  @param {boolean} [update] - Upload to webgl now, pass false when batching */
+    drawImage(image, tileInfo, update=true)
+    {
+        ASSERT(!!this.context, 'texture sheet has no canvas');
+
+        // copy frames in order, reading the source left to right, top to bottom
+        // the destination wraps at tileInfo.columns which may be narrower than the source
+        const frameSize = tileInfo.size;
+        const sourceColumns = image.width / frameSize.x;
+        const frameCount = sourceColumns * (image.height / frameSize.y);
+        const columns = tileInfo.columns || frameCount;
+        const cellWidth = frameSize.x + tileInfo.padding*2;
+        const cellHeight = frameSize.y + tileInfo.padding*2;
+        for (let i = frameCount; i--;)
+        {
+            const sourceX = (i % sourceColumns) * frameSize.x;
+            const sourceY = (i / sourceColumns | 0) * frameSize.y;
+            this.context.drawImage(image,
+                sourceX, sourceY, frameSize.x, frameSize.y,
+                tileInfo.pos.x + (i % columns) * cellWidth,
+                tileInfo.pos.y + (i / columns | 0) * cellHeight,
+                frameSize.x, frameSize.y);
+        }
+
+        // upload now unless the caller is batching more images
+        this.glDirty = true;
+        update && this.updateTexture();
+    }
+
+    /** Upload the canvas to webgl if it has changed since the last upload
+     *  Only needed after batching, drawImage uploads automatically by default */
+    updateTexture()
+    {
+        if (!this.glDirty) return;
+        this.glDirty = false;
+        this.textureInfo.createWebGLTexture();
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Load an image and pack it into a texture sheet
+ *  - Returns a TileInfo immediately which is filled in when the image loads
+ *  - Nothing is visible until it loads, use spritesReady to wait for it
+ *  - Pass frameSize for animations, then step through them with TileInfo.frame
+ *  - Grid images keep their layout and frames wrap down to the next row
+ *  @param {string} src - Image source path
+ *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels
+ *  @param {number} [padding] - How many pixels padding around each frame
+ *  @return {TileInfo}
+ *  @example
+ *  const playerTile = loadSprite('player.png');     // a single sprite
+ *  const runTile = loadSprite('run.png', vec2(16)); // a 16x16 frame animation
+ *  @memberof TextureSheets */
+function loadSprite(src, frameSize, padding=textureSheetPadding)
+{
+    ASSERT(isStringLike(src), 'image src must be a string');
+    ASSERT(!frameSize || isVector2(frameSize) || isNumber(frameSize), 'frameSize must be a vec2 or number');
+    ASSERT(isNumber(padding), 'padding must be a number');
+
+    if (isNumber(frameSize))
+        frameSize = vec2(frameSize);
+
+    // start with an empty tile that gets filled in when the image loads
+    const tileInfo = new TileInfo(vec2(), vec2(), undefined, padding, 0);
+    if (headlessMode) return tileInfo;
+
+    // point at a sheet right away so drawing before it loads picks up empty pixels
+    tileInfo.textureInfo = (textureSheets[0] || textureSheetCreate()).textureInfo;
+
+    // start decoding right away, images decode in parallel
+    const image = new Image;
+    const imagePromise = new Promise(resolve =>
+    {
+        image.onerror = image.onload = resolve;
+        image.crossOrigin = 'anonymous';
+        image.src = src;
+    });
+
+    // pack through a queue so sheets fill in call order, not decode order
+    ++textureSheetPendingCount;
+    textureSheetQueue = textureSheetQueue.then(async ()=>
+    {
+        await imagePromise;
+        if (image.width)
+        {
+            // pack onto a sheet, then fill in the tile that was already handed out,
+            // copying every field so nothing is missed if TileInfo gains more of them
+            const imageSize = vec2(image.width, image.height);
+            const {sheet, tile} = textureSheetAdd(imageSize, frameSize, padding);
+            Object.assign(tileInfo, tile);
+            sheet.drawImage(image, tileInfo, false); // upload once per batch below
+        }
+        else
+        {
+            // leave the tile empty if the image failed to load
+            LOG('loadSprite failed to load image:', src);
+        }
+
+        // upload to webgl once per batch, when the last pending load finishes
+        if (!--textureSheetPendingCount)
+            textureSheets.forEach(s=> s.updateTexture());
+    });
+
+    return tileInfo;
+}
+
+/** Load a pre-packed texture atlas and repack it onto texture sheets
+ *  - Supports TexturePacker json (hash and array) and Aseprite json
+ *  - Returns an empty object which is filled with TileInfos when loaded
+ *  - Frames are named by the json, animations are grouped automatically
+ *  - Aseprite frame tags become animations, so do names like run_0, run_1
+ *  - Trimmed frames are restored to their full source size when packed
+ *  - Rotated frames are rotated back upright when packed
+ *  @param {string} imageSrc - Atlas image path
+ *  @param {string|Object} jsonSrc - Atlas json path, or already parsed json data
+ *  @param {number} [padding] - How many pixels padding around each frame
+ *  @return {Object} Object mapping frame and animation names to TileInfos
+ *  @example
+ *  const atlas = loadAtlas('sprites.png', 'sprites.json');
+ *  await spritesReady();
+ *  drawTile(pos, size, atlas.player);          // a single frame
+ *  drawTile(pos, size, atlas.run.frame(2));    // frame 2 of the run animation
+ *  @memberof TextureSheets */
+function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
+{
+    ASSERT(isStringLike(imageSrc), 'atlas image src must be a string');
+    ASSERT(isStringLike(jsonSrc) || typeof jsonSrc === 'object', 'atlas json must be a path or object');
+    ASSERT(isNumber(padding), 'padding must be a number');
+
+    const atlas = {};
+    if (headlessMode) return atlas;
+
+    // start fetching the json and decoding the image right away, in parallel
+    const jsonPromise = typeof jsonSrc === 'object' ? Promise.resolve(jsonSrc) :
+        fetch(jsonSrc).then(r=> r.ok && r.json()).catch(()=> undefined);
+    const image = new Image;
+    const imagePromise = new Promise(resolve =>
+    {
+        image.onerror = image.onload = resolve;
+        image.crossOrigin = 'anonymous';
+        image.src = imageSrc;
+    });
+
+    // pack through a queue so sheets fill in call order, not decode order
+    ++textureSheetPendingCount;
+    textureSheetQueue = textureSheetQueue.then(async ()=>
+    {
+        const data = await jsonPromise;
+        await imagePromise;
+        if (image.width && data)
+        {
+            for (const group of parseAtlas(data))
+            {
+                // reserve a block of full size cells, one per frame
+                const sourceSize = group.frames[0].sourceSize;
+                const blockSize = vec2(sourceSize.x*group.frames.length, sourceSize.y);
+                const {sheet, tile} = textureSheetAdd(blockSize, sourceSize, padding);
+
+                // draw each frame untrimmed into its cell
+                const context = sheet.context;
+                const cellWidth = sourceSize.x + padding*2;
+                const cellHeight = sourceSize.y + padding*2;
+                group.frames.forEach((f, i)=>
+                {
+                    const x = tile.pos.x + (i % tile.columns)*cellWidth + f.offset.x;
+                    const y = tile.pos.y + (i / tile.columns |0)*cellHeight + f.offset.y;
+                    if (f.rotated)
+                    {
+                        // stored rotated 90 degrees clockwise, draw it back upright
+                        context.save();
+                        context.translate(x, y);
+                        context.rotate(-PI/2);
+                        context.drawImage(image, f.pos.x, f.pos.y, f.size.y, f.size.x,
+                            -f.size.y, 0, f.size.y, f.size.x);
+                        context.restore();
+                    }
+                    else
+                        context.drawImage(image, f.pos.x, f.pos.y, f.size.x, f.size.y,
+                            x, y, f.size.x, f.size.y);
+                });
+                sheet.glDirty = true;
+                atlas[group.name] = tile;
+            }
+        }
+        else
+        {
+            // leave the atlas empty if either file failed to load
+            LOG('loadAtlas failed to load:', imageSrc, jsonSrc);
+        }
+
+        // upload to webgl once per batch, when the last pending load finishes
+        if (!--textureSheetPendingCount)
+            textureSheets.forEach(s=> s.updateTexture());
+    });
+
+    return atlas;
+}
+
+/** Parse atlas json into a list of named frame groups, used by loadAtlas
+ *  - Accepts TexturePacker json (hash and array) and Aseprite json
+ *  - Frames tagged in Aseprite or named like run_0, run_1 group into animations
+ *  @param {Object} data - Parsed atlas json data
+ *  @return {Array<Object>} List of {name, frames} groups in atlas order
+ *  @memberof TextureSheets */
+function parseAtlas(data)
+{
+    ASSERT(!!data?.frames, 'unrecognized atlas format, expected TexturePacker or Aseprite json');
+
+    // normalize both hash and array frame layouts into a single list
+    const frames = (isArray(data.frames) ?
+        data.frames.map(f=> [f.filename, f]) : Object.entries(data.frames))
+        .map(([name, f])=> ({
+            name: name.replace(/\.[^.\\/]+$/, ''), // strip file extension
+            pos:        vec2(f.frame.x, f.frame.y),
+            size:       vec2(f.frame.w, f.frame.h),
+            offset:     vec2(f.spriteSourceSize?.x ?? 0, f.spriteSourceSize?.y ?? 0),
+            sourceSize: vec2(f.sourceSize?.w ?? f.frame.w, f.sourceSize?.h ?? f.frame.h),
+            rotated:    !!f.rotated,
+        }));
+
+    const groups = [];
+    const tags = data.meta?.frameTags;
+    if (tags?.length)
+    {
+        // aseprite tags are authoritative, untagged frames stay individual
+        const tagged = new Set;
+        for (const tag of tags)
+        {
+            groups.push({name: tag.name, frames: frames.slice(tag.from, tag.to + 1)});
+            for (let i = tag.from; i <= tag.to; ++i)
+                tagged.add(i);
+        }
+        frames.forEach((f, i)=> tagged.has(i) || groups.push({name: f.name, frames: [f]}));
+        return groups;
+    }
+
+    // group frames that share a name stem with contiguous trailing numbers
+    // run_0.png and run_1.png become a 2 frame animation named run
+    const stems = new Map;
+    for (const f of frames)
+    {
+        let match = f.name.match(/^(.+?)([-_ ])?(\d+)$/);
+        if (match && !match[2] && /\d$/.test(match[1]))
+            match = undefined; // all digit tails like 10 are a name, not frame 0 of 1
+        const stem = match ? match[1] : f.name;
+        f.groupIndex = match ? Number(match[3]) : undefined;
+        stems.has(stem) || stems.set(stem, []);
+        stems.get(stem).push(f);
+    }
+    for (const [stem, list] of stems)
+    {
+        // only group 2 or more frames with contiguous indices and matching sizes
+        list.sort((a, b)=> a.groupIndex - b.groupIndex);
+        const grouped = list.length > 1 &&
+            list.every((f, i)=> f.groupIndex === list[0].groupIndex + i) &&
+            list.every(f=> f.sourceSize.x === list[0].sourceSize.x &&
+                           f.sourceSize.y === list[0].sourceSize.y);
+        if (grouped)
+            groups.push({name: stem, frames: list});
+        else
+            list.forEach(f=> groups.push({name: f.name, frames: [f]}));
+    }
+    return groups;
+}
+
+/** Wait for everything started by loadSprite and loadAtlas to finish packing
+ *  @return {Promise}
+ *  @example
+ *  async function gameInit()
+ *  {
+ *      playerTile = loadSprite('player.png');
+ *      runTile = loadSprite('run.png', vec2(16));
+ *      await spritesReady();
+ *  }
+ *  @memberof TextureSheets */
+async function spritesReady()
+{
+    // keep waiting until the queue drains, more sprites may load while waiting
+    while (textureSheetPendingCount)
+        await textureSheetQueue;
+}
+
+// create a new texture sheet and add it to the list
+function textureSheetCreate()
+{
+    const sheet = new TextureSheet;
+    textureSheets.push(sheet);
+    return sheet;
+}
+
+// use the first sheet with enough space, or make a new one
+function textureSheetAdd(imageSize, frameSize, padding)
+{
+    let sheet, tile;
+    for (sheet of textureSheets)
+        if (tile = sheet.tryAdd(imageSize, frameSize, padding))
+            break;
+    if (!tile)
+    {
+        sheet = textureSheetCreate();
+        tile = sheet.tryAdd(imageSize, frameSize, padding);
+        ASSERT(!!tile, 'image is too large to fit on a texture sheet');
+    }
+    return {sheet, tile};
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Texture sheet setting setters
+
+/** Set width and height in pixels of texture sheets created by loadSprite
+ *  @param {number} size
+ *  @memberof Settings */
+function setTextureSheetSize(size) { textureSheetSize = size; }
+
+/** Set default padding pixels around each frame packed by loadSprite
+ *  @param {number} padding
+ *  @memberof Settings */
+function setTextureSheetPadding(padding) { textureSheetPadding = padding; }
+
 /**
  * LittleJS Tween System Plugin
  * - Lightweight tweens for numbers, Vector2, Color, or any .lerp-able type
@@ -14626,7 +15098,11 @@ function tweenProperty(target, propertyPath, start, end, duration = 1, options =
     const callback = (value) =>
     {
         let obj = target;
-        for (const k of parts) obj = obj[k];
+        for (const k of parts)
+        {
+            obj = obj[k];
+            ASSERT(obj != null, 'tweenProperty path does not resolve: ' + propertyPath);
+        }
         obj[lastKey] = value;
     };
     return new Tween(callback, start, end, duration, options);
@@ -15509,3 +15985,157 @@ class PathFinder
     }
 }
 
+/**
+ * LittleJS Three.js Plugin
+ * - Renders a three.js scene on a canvas behind the LittleJS canvases
+ * - The three.js module is passed in by the user, nothing is bundled
+ * - Keep canvasClearColor transparent so the 3D scene shows through
+ * - Aligned camera mode locks the 3D camera to the LittleJS 2D camera
+ * - ThreeJSObject lets LittleJS physics drive a three.js mesh
+ * - Call new ThreeJSPlugin(THREE) in gameInit to set up
+ * @namespace ThreeJS
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Global ThreeJS plugin object
+ *  @type {ThreeJSPlugin}
+ *  @memberof ThreeJS */
+let threeJS;
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * ThreeJS Plugin - Renders a three.js scene behind the LittleJS canvas
+ * @example
+ * // in gameInit, with three.js loaded by the user
+ * new ThreeJSPlugin(THREE);
+ * threeJS.scene.add(new THREE.AmbientLight);
+ * @memberof ThreeJS
+ */
+class ThreeJSPlugin
+{
+    /** Set up the three.js rendering layer, call in gameInit
+     *  @param {Object} THREE - The three.js module, supplied by the user
+     *  @param {number} [cameraFOV] - Vertical field of view in degrees */
+    constructor(THREE, cameraFOV=60)
+    {
+        ASSERT(!threeJS, 'ThreeJS plugin already initialized');
+        threeJS = this;
+        if (headlessMode) return;
+        ASSERT(mainCanvas, 'ThreeJS plugin must be created after engineInit, call in gameInit');
+        ASSERT(THREE && THREE.WebGLRenderer, 'three.js module must be passed in');
+
+        /** @property {Object} - The three.js module passed into the constructor */
+        this.THREE = THREE;
+        /** @property {Object} - The three.js renderer */
+        this.renderer = new THREE.WebGLRenderer({antialias: true});
+        /** @property {Object} - The three.js scene, add lights and meshes here */
+        this.scene = new THREE.Scene();
+        /** @property {Object} - The three.js perspective camera */
+        this.camera = new THREE.PerspectiveCamera(cameraFOV, 1, .1, 1e3);
+        /** @property {boolean} - Lock the camera to the LittleJS 2D camera so the z=0 plane matches world space */
+        this.cameraAlign2D = true;
+
+        // insert the canvas below the engine canvases and match the layout
+        const threeCanvas = this.renderer.domElement;
+        const rootElement = mainCanvas.parentElement;
+        rootElement.insertBefore(threeCanvas, rootElement.firstChild);
+        threeCanvas.style.cssText = mainCanvas.style.cssText;
+
+        // render automatically each frame after the engine renders
+        engineAddPlugin(undefined, ()=> this.render());
+    }
+
+    /** Position the camera so the z=0 plane exactly matches LittleJS world space,
+     *  called automatically when cameraAlign2D is set */
+    alignCamera2D()
+    {
+        const halfHeight = mainCanvasSize.y / 2 / cameraScale; // half visible height in world units
+        const distance = halfHeight / tan(this.camera.fov/2 * PI/180);
+        this.camera.position.set(cameraPos.x, cameraPos.y, distance);
+        // reset all axes in case a free camera was used, littlejs angles are clockwise
+        this.camera.rotation.set(0, 0, -cameraAngle);
+    }
+
+    /** Sync the canvas layout and render the scene, called automatically each frame */
+    render()
+    {
+        if (!this.renderer) return; // headless mode
+
+        // keep renderer size and css in sync with the LittleJS canvas
+        const threeCanvas = this.renderer.domElement;
+        if (threeCanvas.width != mainCanvasSize.x || threeCanvas.height != mainCanvasSize.y)
+        {
+            this.renderer.setSize(mainCanvasSize.x, mainCanvasSize.y, false);
+            this.camera.aspect = mainCanvasSize.x / mainCanvasSize.y;
+            this.camera.updateProjectionMatrix();
+        }
+        if (threeCanvas.style.cssText != mainCanvas.style.cssText)
+            threeCanvas.style.cssText = mainCanvas.style.cssText;
+
+        if (this.cameraAlign2D)
+            this.alignCamera2D();
+        this.renderer.render(this.scene, this.camera);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * ThreeJS Object - EngineObject that drives a three.js mesh
+ * - LittleJS physics moves the object and the mesh follows automatically
+ * - Destroying the object removes the mesh from the scene
+ * @extends EngineObject
+ * @memberof ThreeJS
+ */
+class ThreeJSObject extends EngineObject
+{
+    /** Create an engine object that drives a three.js mesh
+     *  @param {Vector2} [pos] - World space position
+     *  @param {Vector2} [size] - World space size
+     *  @param {Object} [mesh] - The three.js object3d to drive
+     *  @param {number} [z] - Mesh height above the 2D plane */
+    constructor(pos, size, mesh, z=0)
+    {
+        super(pos, size);
+        ASSERT(threeJS, 'ThreeJS plugin must be initialized first');
+
+        /** @property {Object} - The three.js object3d this object drives */
+        this.mesh = mesh;
+        /** @property {number} - Mesh height above the 2D plane */
+        this.z = z;
+        if (mesh)
+        {
+            threeJS.scene.add(mesh);
+            this.syncMesh();
+        }
+    }
+
+    /** Update the object and sync the mesh to its transform */
+    update()
+    {
+        super.update();
+        this.syncMesh();
+    }
+
+    /** Copy this object's transform to the mesh */
+    syncMesh()
+    {
+        if (!this.mesh) return;
+        this.mesh.position.set(this.pos.x, this.pos.y, this.z);
+        this.mesh.rotation.z = -this.angle; // littlejs angles are clockwise
+    }
+
+    /** The mesh is this object's visual, the default 2D rendering is skipped */
+    render() {}
+
+    /** Destroy this object and remove its mesh from the scene
+     *  @param {boolean} [immediate] */
+    destroy(immediate)
+    {
+        if (this.destroyed) return;
+        // note: frequently destroyed objects should also dispose geometry and material
+        this.mesh && threeJS.scene.remove(this.mesh);
+        super.destroy(immediate);
+    }
+}
+