littlejsengine 1.18.29 → 1.20.0

package/plugins/textureSheet.js

@@ -48,10 +48,10 @@ class TextureSheet
 
         /** @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');
+        this.context = headlessMode ? undefined : createCanvasContext(size);
+        /** @property {OffscreenCanvas} - Canvas holding the packed images */
+        this.canvas = this.context?.canvas;
         /** @property {TextureInfo} - The texture info for this sheet */
         this.textureInfo = new TextureInfo(this.canvas);
         /** @property {Vector2} - Where the next image will be packed */
@@ -71,23 +71,25 @@ class TextureSheet
 
     /** 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 {Vector2} [frameSize] - Size of each frame, or the whole image less its source padding if not passed
      *  @param {number} [padding] - How many pixels padding around each frame
      *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
-     *  @return {TileInfo} Tile for the packed image, or undefined if the sheet is full */
-    tryAdd(imageSize, frameSize=imageSize, padding=textureSheetPadding, sourcePadding=0)
+     *  @return {TileInfo|undefined} Tile for the packed image, or undefined if the sheet is full */
+    tryAdd(imageSize, frameSize, padding=textureSheetPadding, sourcePadding=0)
     {
-        ASSERT(isVector2(imageSize) && isVector2(frameSize), 'sizes must be vec2');
-        ASSERT(frameSize.x > 0 && frameSize.y > 0, 'frame size must be positive');
-
-        if (isNumber(sourcePadding))
-            sourcePadding = vec2(sourcePadding);
-        ASSERT(isVector2(sourcePadding) && sourcePadding.x >= 0 && sourcePadding.y >= 0,
+        // a number pads both axes the same
+        const sourcePad = isNumber(sourcePadding) ?
+            vec2(/** @type {number} */ (sourcePadding)) : /** @type {Vector2} */ (sourcePadding);
+        ASSERT(isVector2(sourcePad) && sourcePad.x >= 0 && sourcePad.y >= 0,
             'sourcePadding must be a number or vec2 >= 0');
+        ASSERT(isVector2(imageSize), 'sizes must be vec2');
+        frameSize ||= imageSize.subtract(sourcePad.scale(2)); // the whole image, less the padding baked into it
+        ASSERT(isVector2(frameSize), 'sizes must be vec2');
+        ASSERT(frameSize.x > 0 && frameSize.y > 0, 'frame size must be positive');
 
         // the source may have its own padding baked in around each frame
-        const sourceCellWidth = frameSize.x + sourcePadding.x*2;
-        const sourceCellHeight = frameSize.y + sourcePadding.y*2;
+        const sourceCellWidth = frameSize.x + sourcePad.x*2;
+        const sourceCellHeight = frameSize.y + sourcePad.y*2;
         ASSERT(imageSize.x % sourceCellWidth === 0 && imageSize.y % sourceCellHeight === 0,
             'image size must be a multiple of the padded frame size');
 
@@ -98,8 +100,11 @@ class TextureSheet
 
         // 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 / sourceCellWidth;
-        const frameCount = sourceColumns * (imageSize.y / sourceCellHeight);
+        // whole frames only, a partial one left over at an edge is ignored
+        const sourceColumns = imageSize.x / sourceCellWidth | 0;
+        const frameCount = sourceColumns * (imageSize.y / sourceCellHeight | 0);
+        if (!frameCount)
+            return undefined; // smaller than a frame, there is nothing to pack
         const columns = min(sourceColumns, maxColumns);
         const blockWidth = columns * cellWidth;
         const blockHeight = ceil(frameCount / columns) * cellHeight;
@@ -126,7 +131,7 @@ class TextureSheet
     }
 
     /** Draw an image into this sheet at a tile returned by tryAdd
-     *  @param {HTMLImageElement} image - Source image to copy from
+     *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} 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
      *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image */
@@ -134,23 +139,25 @@ class TextureSheet
     {
         ASSERT(!!this.context, 'texture sheet has no canvas');
 
-        if (isNumber(sourcePadding))
-            sourcePadding = vec2(sourcePadding);
+        // a number pads both axes the same
+        const sourcePad = isNumber(sourcePadding) ?
+            vec2(/** @type {number} */ (sourcePadding)) : /** @type {Vector2} */ (sourcePadding);
 
         // 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 sourceCellWidth = frameSize.x + sourcePadding.x*2;
-        const sourceCellHeight = frameSize.y + sourcePadding.y*2;
-        const sourceColumns = image.width / sourceCellWidth;
-        const frameCount = sourceColumns * (image.height / sourceCellHeight);
+        const sourceCellWidth = frameSize.x + sourcePad.x*2;
+        const sourceCellHeight = frameSize.y + sourcePad.y*2;
+        // whole frames only as tryAdd packed them, a fractional count would never end the loop
+        const sourceColumns = image.width / sourceCellWidth | 0;
+        const frameCount = sourceColumns * (image.height / sourceCellHeight | 0);
         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) * sourceCellWidth + sourcePadding.x;
-            const sourceY = (i / sourceColumns | 0) * sourceCellHeight + sourcePadding.y;
+            const sourceX = (i % sourceColumns) * sourceCellWidth + sourcePad.x;
+            const sourceY = (i / sourceColumns | 0) * sourceCellHeight + sourcePad.y;
             this.context.drawImage(image,
                 sourceX, sourceY, frameSize.x, frameSize.y,
                 tileInfo.pos.x + (i % columns) * cellWidth,
@@ -182,7 +189,8 @@ class TextureSheet
  *  - Grid images keep their layout and frames wrap down to the next row
  *  - Pass sourcePadding if the source image has padding baked in around frames
  *  @param {string} src - Image source path
- *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels
+ *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels, or the whole image less its
+ *  source padding if not passed
  *  @param {number} [padding] - How many pixels padding around each frame
  *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
  *  @return {TileInfo}
@@ -196,9 +204,10 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
     ASSERT(!frameSize || isVector2(frameSize) || isNumber(frameSize), 'frameSize must be a vec2 or number');
     ASSERT(isNumber(padding), 'padding must be a number');
     ASSERT(isNumber(sourcePadding) || isVector2(sourcePadding), 'sourcePadding must be a number or vec2');
+    ASSERT(engineInitialized || headlessMode, 'call loadSprite after engineInit, e.g. in gameInit');
 
     if (isNumber(frameSize))
-        frameSize = vec2(frameSize);
+        frameSize = vec2(/** @type {number} */ (frameSize));
 
     // start with an empty tile that gets filled in when the image loads
     const tileInfo = new TileInfo(vec2(), vec2(), undefined, padding, 0);
@@ -217,8 +226,7 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
     });
 
     // pack through a queue so sheets fill in call order, not decode order
-    ++textureSheetPendingCount;
-    textureSheetQueue = textureSheetQueue.then(async ()=>
+    textureSheetQueueJob('loadSprite ' + src, async ()=>
     {
         await imagePromise;
         if (image.width)
@@ -226,19 +234,21 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
             // 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, sourcePadding);
-            Object.assign(tileInfo, tile);
-            sheet.drawImage(image, tileInfo, false, sourcePadding); // upload once per batch below
+            const added = textureSheetAdd(imageSize, frameSize, padding, sourcePadding);
+            if (!added)
+            {
+                // leave the tile empty, no sheet can hold it
+                LOG('loadSprite image is too large to fit on a texture sheet:', src);
+                return;
+            }
+            Object.assign(tileInfo, added.tile);
+            added.sheet.drawImage(image, tileInfo, false, sourcePadding); // 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;
@@ -254,7 +264,7 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
  *  @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
+ *  @return {Object<string, TileInfo>} Object mapping frame and animation names to TileInfos
  *  @example
  *  const atlas = loadAtlas('sprites.png', 'sprites.json');
  *  await spritesReady();
@@ -266,7 +276,9 @@ 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');
+    ASSERT(engineInitialized || headlessMode, 'call loadAtlas after engineInit, e.g. in gameInit');
 
+    /** @type {Object<string, TileInfo>} */
     const atlas = {};
     if (headlessMode) return atlas;
 
@@ -282,8 +294,7 @@ function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
     });
 
     // pack through a queue so sheets fill in call order, not decode order
-    ++textureSheetPendingCount;
-    textureSheetQueue = textureSheetQueue.then(async ()=>
+    textureSheetQueueJob('loadAtlas ' + imageSrc, async ()=>
     {
         const data = await jsonPromise;
         await imagePromise;
@@ -294,7 +305,13 @@ function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
                 // 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);
+                const added = textureSheetAdd(blockSize, sourceSize, padding);
+                if (!added)
+                {
+                    LOG('loadAtlas frames are too large to fit on a texture sheet:', group.name);
+                    continue;
+                }
+                const {sheet, tile} = added;
 
                 // draw each frame untrimmed into its cell
                 const context = sheet.context;
@@ -327,15 +344,32 @@ function loadAtlas(imageSrc, jsonSrc, padding=textureSheetPadding)
             // 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;
 }
 
+// run a load in the queue: a load that throws is reported and the loads after it carry on, the pending count
+// always comes back down, and the sheets upload to webgl once per batch, when the last pending load finishes
+function textureSheetQueueJob(name, job)
+{
+    ++textureSheetPendingCount;
+    textureSheetQueue = textureSheetQueue.then(async ()=>
+    {
+        try { await job(); }
+        catch (e) { console.error(name + ' failed:', e); }
+        finally
+        {
+            if (!--textureSheetPendingCount)
+                for (const sheet of textureSheets)
+                {
+                    try { sheet.updateTexture(); }
+                    catch (e) { console.error('texture sheet upload failed:', e); }
+                }
+        }
+    });
+}
+
 /** 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
@@ -375,11 +409,11 @@ function parseAtlas(data)
     }
 
     // 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
+    // run_0.png and run_1.png become a 2 frame animation named run, and so do the folder style run/0.png and run/1.png
     const stems = new Map;
     for (const f of frames)
     {
-        let match = f.name.match(/^(.+?)([-_ ])?(\d+)$/);
+        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;
@@ -428,7 +462,8 @@ function textureSheetCreate()
     return sheet;
 }
 
-// use the first sheet with enough space, or make a new one
+// use the first sheet with enough space, or make a new one,
+// returns undefined if it would not fit even on an empty sheet
 function textureSheetAdd(imageSize, frameSize, padding, sourcePadding)
 {
     let sheet, tile;
@@ -437,9 +472,12 @@ function textureSheetAdd(imageSize, frameSize, padding, sourcePadding)
             break;
     if (!tile)
     {
+        // probe an empty sheet first, a new one is a canvas and a texture kept for good
+        const emptySheet = {size: textureSheetSize, cursor: vec2(), rowHeight: 0};
+        if (!TextureSheet.prototype.tryAdd.call(emptySheet, imageSize, frameSize, padding, sourcePadding))
+            return;
         sheet = textureSheetCreate();
         tile = sheet.tryAdd(imageSize, frameSize, padding, sourcePadding);
-        ASSERT(!!tile, 'image is too large to fit on a texture sheet');
     }
     return {sheet, tile};
 }

package/plugins/threejs.js

@@ -1,158 +1,183 @@
-/**
- * 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
- */
-
-'use strict';
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** 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;
-
-        // composite the 3D canvas into screenshots and video capture
-        setBackgroundCanvas(threeCanvas);
-
-        // 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);
-    }
-}
+/**
+ * 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
+ */
+
+'use strict';
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** 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;
+        /** @property {number|undefined} - Near plane of the aligned camera before any zoom out, from camera.near on the
+         *  first aligned frame; while aligned, change this rather than camera.near
+         *  @type {number|undefined} */
+        this.cameraNear = undefined;
+        /** @property {number|undefined} - Far plane of the aligned camera before any zoom out, from camera.far on the
+         *  first aligned frame; while aligned, change this rather than camera.far
+         *  @type {number|undefined} */
+        this.cameraFar = undefined;
+
+        // 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;
+
+        // composite the 3D canvas into screenshots and video capture
+        setBackgroundCanvas(threeCanvas);
+
+        // 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);
+
+        // zoomed out far enough that the z=0 plane would be past the far plane, push both planes out together
+        // so the depth precision stays what it was, and bring them back from where they began when zoomed in again
+        const baseNear = this.cameraNear ??= this.camera.near, baseFar = this.cameraFar ??= this.camera.far;
+        const scale = max(1, distance * 2 / baseFar), near = baseNear * scale, far = baseFar * scale;
+        if (near != this.camera.near || far != this.camera.far)
+        {
+            this.camera.near = near;
+            this.camera.far = far;
+            this.camera.updateProjectionMatrix();
+        }
+        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
+        // mainCanvasSize is css pixels, three scales it by the pixel ratio
+        const threeCanvas = this.renderer.domElement;
+        const dpr = getCanvasPixelRatio();
+        const bufferSizeX = mainCanvasSize.x * dpr | 0;
+        const bufferSizeY = mainCanvasSize.y * dpr | 0;
+        if (threeCanvas.width != bufferSizeX || threeCanvas.height != bufferSizeY)
+        {
+            this.renderer.setPixelRatio(dpr);
+            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); // no scene in headless mode
+            this.syncMesh();
+        }
+    }
+
+    /** Update the transform and sync the mesh to it, after the parent has placed a child, and while paused too
+     *  @param {boolean} [updateChildren] - Also update the children's transforms */
+    updateTransforms(updateChildren=true)
+    {
+        super.updateTransforms(updateChildren);
+        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);
+    }
+}