minerender 2.1.0-alpha.50 → 2.1.0-alpha.52

package/dist/bundle.js

@@ -78088,27 +78088,66 @@ ${key}` : key;
       init_dirname();
       init_buffer2();
       init_process2();
+      init_CubeFace();
       ModelGenerator = class {
+        /**
+         * Front and back faces plus one zero-thickness side face per run of texels that border a transparent texel,
+         * like vanilla's ItemModelGenerator. Pass the pixels of a single (first) animation frame.
+         */
         static generateItemModel(imageData, layer) {
           const tintindex = this.ITEM_LAYERS.indexOf(layer);
+          const texture = `#${layer}`;
           const mainElement = {
             from: [0, 0, 7.5],
             to: [16, 16, 8.5],
             faces: {
               "south": {
                 uv: [0, 0, 16, 16],
-                texture: `#${layer}`,
+                texture,
                 tintindex
               },
               "north": {
                 uv: [16, 0, 0, 16],
-                texture: `#${layer}`,
+                texture,
                 tintindex
               }
             },
             shade: true
           };
-          return [mainElement];
+          const elements = [mainElement];
+          const { width, height, data } = imageData;
+          const opaque = (x4, y5) => x4 >= 0 && y5 >= 0 && x4 < width && y5 < height && data[(y5 * width + x4) * 4 + 3] !== 0;
+          const sx = 16 / width;
+          const sy = 16 / height;
+          const sides = [["up" /* UP */, 0, -1], ["down" /* DOWN */, 0, 1], ["west" /* WEST */, -1, 0], ["east" /* EAST */, 1, 0]];
+          for (const [face, dx, dy] of sides) {
+            const horizontal = dx === 0;
+            const lines = horizontal ? height : width;
+            const length = horizontal ? width : height;
+            for (let line = 0; line < lines; line++) {
+              for (let start = 0; start < length; start++) {
+                const exposed = (i4) => horizontal ? opaque(i4, line) && !opaque(i4, line + dy) : opaque(line, i4) && !opaque(line + dx, i4);
+                if (!exposed(start)) continue;
+                let end = start + 1;
+                while (end < length && exposed(end)) end++;
+                let uv, from, to;
+                if (horizontal) {
+                  const y5 = 16 - (line + (dy > 0 ? 1 : 0)) * sy;
+                  uv = [start * sx, line * sy, end * sx, (line + 1) * sy];
+                  from = [start * sx, y5, 7.5];
+                  to = [end * sx, y5, 8.5];
+                } else {
+                  const x4 = (line + (dx > 0 ? 1 : 0)) * sx;
+                  uv = [line * sx, start * sy, (line + 1) * sx, end * sy];
+                  from = [x4, 16 - end * sy, 7.5];
+                  to = [x4, 16 - start * sy, 8.5];
+                }
+                elements.push({ from, to, faces: { [face]: { uv, texture, tintindex } }, shade: true });
+                start = end;
+              }
+            }
+          }
+          return elements;
         }
       };
       ModelGenerator.ITEM_LAYERS = ["layer0", "layer1", "layer2", "layer3", "layer4"];
@@ -78479,7 +78518,15 @@ ${key}` : key;
               for (let layerName of ModelGenerator.ITEM_LAYERS) {
                 const textureImage = textureMap[layerName];
                 if (textureImage) {
-                  model.elements.push(...ModelGenerator.generateItemModel(textureImage.data, layerName));
+                  const [width, height] = sizes[layerName];
+                  const frame = frames[layerName]?.[0].index ?? 0;
+                  const columns = textureImage.width / width;
+                  model.elements.push(...ModelGenerator.generateItemModel(textureImage.getSectionData(
+                    frame % columns * width,
+                    Math.floor(frame / columns) * height,
+                    width,
+                    height
+                  ), layerName));
                 }
               }
               console.debug(p8, "Item model elements", model.elements);
@@ -79703,7 +79750,6 @@ ${key}` : key;
           if (this.options.tints) this.options.tints = { ...this.options.tints };
           this.addEventListener("added", () => this.updateAnimationSubscription());
           this.addEventListener("removed", () => this.updateAnimationSubscription());
-          console.log("ModelObject options", this.options);
         }
         async init() {
           await this.loadTextures();
@@ -83704,6 +83750,10 @@ ${key}` : key;
           uv
         ).clone();
         geometry.translate(cube.origin[0] + width / 2, cube.origin[1] + height / 2, cube.origin[2] + depth / 2);
+        if (Math.min(width + growX * 2, height + growY * 2, depth + growZ * 2) > 0) {
+          const index = Array.from(geometry.getIndex().array);
+          geometry.setIndex(index.concat(index.slice().reverse()));
+        }
         const mesh = this.createMesh(name2, geometry, material);
         mesh.renderOrder = renderOrder;
         anchor.add(mesh);
@@ -86731,7 +86781,7 @@ property list uchar int vertex_index
     }
     init() {
       this.statsContainer.classList.add("minerender-stats");
-      setInterval(() => {
+      this.interval = setInterval(() => {
         for (let line of this.lines) {
           line.update();
         }
@@ -86740,6 +86790,13 @@ property list uchar int vertex_index
     appendTo(el) {
       el.append(this.statsContainer);
     }
+    dispose() {
+      clearInterval(this.interval);
+      this.interval = void 0;
+      this.lines.length = 0;
+      this.statsContainer.replaceChildren();
+      this.statsContainer.remove();
+    }
     add(line) {
       if (typeof line !== "undefined") {
         this.lines.push(line);
@@ -89282,7 +89339,7 @@ property list uchar int vertex_index
   init_process2();
   var baseSkinCoordinates = {
     head: {
-      east: {
+      west: {
         // left
         uv: [
           0,
@@ -89291,7 +89348,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      west: {
+      east: {
         // right
         uv: [
           16,
@@ -89300,7 +89357,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      north: {
+      south: {
         // front
         uv: [
           8,
@@ -89309,7 +89366,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      south: {
+      north: {
         // back
         uv: [
           24,
@@ -89321,24 +89378,24 @@ property list uchar int vertex_index
       up: {
         // top
         uv: [
-          16,
           8,
-          8,
-          0
+          0,
+          16,
+          8
         ]
       },
       down: {
         // bottom
         uv: [
-          24,
-          0,
           16,
-          8
+          8,
+          24,
+          0
         ]
       }
     },
     body: {
-      east: {
+      west: {
         uv: [
           16,
           20,
@@ -89346,7 +89403,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      west: {
+      east: {
         uv: [
           28,
           20,
@@ -89354,7 +89411,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      north: {
+      south: {
         uv: [
           20,
           20,
@@ -89362,7 +89419,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      south: {
+      north: {
         uv: [
           32,
           20,
@@ -89372,23 +89429,23 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          28,
-          20,
           20,
-          16
+          16,
+          28,
+          20
         ]
       },
       down: {
         uv: [
-          36,
-          16,
           28,
-          20
+          20,
+          36,
+          16
         ]
       }
     },
     leftArm: {
-      east: {
+      west: {
         uv: [
           32,
           52,
@@ -89396,7 +89453,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      west: {
+      east: {
         uv: [
           40,
           52,
@@ -89404,7 +89461,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      north: {
+      south: {
         uv: [
           36,
           52,
@@ -89412,7 +89469,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      south: {
+      north: {
         uv: [
           44,
           52,
@@ -89422,23 +89479,23 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          40,
-          52,
           36,
-          48
+          48,
+          40,
+          52
         ]
       },
       down: {
         uv: [
-          44,
-          48,
           40,
-          52
+          52,
+          44,
+          48
         ]
       }
     },
     rightArm: {
-      east: {
+      west: {
         uv: [
           40,
           20,
@@ -89446,7 +89503,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      west: {
+      east: {
         uv: [
           48,
           20,
@@ -89454,7 +89511,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      north: {
+      south: {
         uv: [
           44,
           20,
@@ -89462,7 +89519,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      south: {
+      north: {
         uv: [
           52,
           20,
@@ -89472,23 +89529,23 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          48,
-          20,
           44,
-          16
+          16,
+          48,
+          20
         ]
       },
       down: {
         uv: [
-          52,
-          16,
           48,
-          20
+          20,
+          52,
+          16
         ]
       }
     },
     leftLeg: {
-      east: {
+      west: {
         uv: [
           16,
           52,
@@ -89496,7 +89553,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      west: {
+      east: {
         uv: [
           24,
           52,
@@ -89504,7 +89561,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      north: {
+      south: {
         uv: [
           20,
           52,
@@ -89512,7 +89569,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      south: {
+      north: {
         uv: [
           28,
           52,
@@ -89522,24 +89579,24 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          24,
-          52,
           20,
-          48
+          48,
+          24,
+          52
         ]
       },
       down: {
         uv: [
-          28,
-          48,
           24,
-          52
+          52,
+          28,
+          48
         ],
         rotation: 180
       }
     },
     rightLeg: {
-      east: {
+      west: {
         uv: [
           0,
           20,
@@ -89547,7 +89604,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      west: {
+      east: {
         uv: [
           8,
           20,
@@ -89555,7 +89612,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      north: {
+      south: {
         uv: [
           4,
           20,
@@ -89563,7 +89620,7 @@ property list uchar int vertex_index
           32
         ]
       },
-      south: {
+      north: {
         uv: [
           12,
           20,
@@ -89573,23 +89630,23 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          8,
-          20,
           4,
-          16
+          16,
+          8,
+          20
         ]
       },
       down: {
         uv: [
-          12,
-          16,
           8,
-          20
+          20,
+          12,
+          16
         ]
       }
     },
     hat: {
-      east: {
+      west: {
         uv: [
           32,
           8,
@@ -89597,7 +89654,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      west: {
+      east: {
         uv: [
           48,
           8,
@@ -89605,7 +89662,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      north: {
+      south: {
         uv: [
           40,
           8,
@@ -89613,7 +89670,7 @@ property list uchar int vertex_index
           16
         ]
       },
-      south: {
+      north: {
         uv: [
           56,
           8,
@@ -89623,24 +89680,24 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          48,
-          8,
           40,
-          0
+          0,
+          48,
+          8
         ]
       },
       down: {
         uv: [
-          56,
-          0,
           48,
-          8
+          8,
+          56,
+          0
         ],
         rotation: 180
       }
     },
     jacket: {
-      east: {
+      west: {
         uv: [
           16,
           36,
@@ -89648,7 +89705,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      west: {
+      east: {
         uv: [
           28,
           36,
@@ -89656,7 +89713,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      north: {
+      south: {
         uv: [
           20,
           36,
@@ -89664,7 +89721,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      south: {
+      north: {
         uv: [
           32,
           36,
@@ -89674,24 +89731,24 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          28,
-          36,
           20,
-          32
+          32,
+          28,
+          36
         ]
       },
       down: {
         uv: [
-          36,
-          32,
           28,
-          36
+          36,
+          36,
+          32
         ],
         rotation: 180
       }
     },
     leftSleeve: {
-      east: {
+      west: {
         uv: [
           48,
           52,
@@ -89699,7 +89756,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      west: {
+      east: {
         uv: [
           56,
           52,
@@ -89707,7 +89764,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      north: {
+      south: {
         uv: [
           52,
           52,
@@ -89715,7 +89772,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      south: {
+      north: {
         uv: [
           60,
           52,
@@ -89725,24 +89782,24 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          56,
-          52,
           52,
-          48
+          48,
+          56,
+          52
         ]
       },
       down: {
         uv: [
-          60,
-          48,
           56,
-          52
+          52,
+          60,
+          48
         ],
         rotation: 180
       }
     },
     rightSleeve: {
-      east: {
+      west: {
         uv: [
           40,
           36,
@@ -89750,7 +89807,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      west: {
+      east: {
         uv: [
           48,
           36,
@@ -89758,7 +89815,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      north: {
+      south: {
         uv: [
           44,
           36,
@@ -89766,7 +89823,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      south: {
+      north: {
         uv: [
           52,
           36,
@@ -89776,24 +89833,24 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          48,
-          36,
           44,
-          32
+          32,
+          48,
+          36
         ]
       },
       down: {
         uv: [
-          52,
-          32,
           48,
-          36
+          36,
+          52,
+          32
         ],
         rotation: 180
       }
     },
     leftTrousers: {
-      east: {
+      west: {
         uv: [
           0,
           52,
@@ -89801,7 +89858,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      west: {
+      east: {
         uv: [
           8,
           52,
@@ -89809,7 +89866,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      north: {
+      south: {
         uv: [
           4,
           52,
@@ -89817,7 +89874,7 @@ property list uchar int vertex_index
           64
         ]
       },
-      south: {
+      north: {
         uv: [
           12,
           52,
@@ -89827,23 +89884,23 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          8,
-          52,
           4,
-          48
+          48,
+          8,
+          52
         ]
       },
       down: {
         uv: [
-          12,
-          48,
           8,
-          52
+          52,
+          12,
+          48
         ]
       }
     },
     rightTrousers: {
-      east: {
+      west: {
         uv: [
           0,
           36,
@@ -89851,7 +89908,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      west: {
+      east: {
         uv: [
           8,
           36,
@@ -89859,7 +89916,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      north: {
+      south: {
         uv: [
           4,
           36,
@@ -89867,7 +89924,7 @@ property list uchar int vertex_index
           48
         ]
       },
-      south: {
+      north: {
         uv: [
           12,
           36,
@@ -89877,18 +89934,18 @@ property list uchar int vertex_index
       },
       up: {
         uv: [
-          8,
-          36,
           4,
-          32
+          32,
+          8,
+          36
         ]
       },
       down: {
         uv: [
-          12,
-          32,
           8,
-          36
+          36,
+          12,
+          32
         ],
         rotation: 180
       }
@@ -89909,35 +89966,35 @@ property list uchar int vertex_index
     ...baseSkinCoordinates,
     leftArm: {
       ...baseSkinCoordinates.leftArm,
-      west: { uv: [39, 52, 43, 64] },
-      north: { uv: [36, 52, 39, 64] },
-      south: { uv: [43, 52, 46, 64] },
-      up: { uv: [39, 52, 36, 48] },
-      down: { uv: [42, 48, 39, 52] }
+      east: { uv: [39, 52, 43, 64] },
+      south: { uv: [36, 52, 39, 64] },
+      north: { uv: [43, 52, 46, 64] },
+      up: { uv: [36, 48, 39, 52] },
+      down: { uv: [39, 52, 42, 48] }
     },
     rightArm: {
       ...baseSkinCoordinates.rightArm,
-      west: { uv: [47, 20, 51, 32] },
-      north: { uv: [44, 20, 47, 32] },
-      south: { uv: [51, 20, 54, 32] },
-      up: { uv: [47, 20, 44, 16] },
-      down: { uv: [50, 16, 47, 20] }
+      east: { uv: [47, 20, 51, 32] },
+      south: { uv: [44, 20, 47, 32] },
+      north: { uv: [51, 20, 54, 32] },
+      up: { uv: [44, 16, 47, 20] },
+      down: { uv: [47, 20, 50, 16] }
     },
     leftSleeve: {
       ...baseSkinCoordinates.leftSleeve,
-      west: { uv: [55, 52, 59, 64] },
-      north: { uv: [52, 52, 55, 64] },
-      south: { uv: [59, 52, 62, 64] },
-      up: { uv: [55, 52, 52, 48] },
-      down: { uv: [58, 48, 55, 52], rotation: 180 }
+      east: { uv: [55, 52, 59, 64] },
+      south: { uv: [52, 52, 55, 64] },
+      north: { uv: [59, 52, 62, 64] },
+      up: { uv: [52, 48, 55, 52] },
+      down: { uv: [55, 52, 58, 48], rotation: 180 }
     },
     rightSleeve: {
       ...baseSkinCoordinates.rightSleeve,
-      west: { uv: [47, 36, 51, 48] },
-      north: { uv: [44, 36, 47, 48] },
-      south: { uv: [51, 36, 54, 48] },
-      up: { uv: [47, 36, 44, 32] },
-      down: { uv: [50, 32, 47, 36], rotation: 180 }
+      east: { uv: [47, 36, 51, 48] },
+      south: { uv: [44, 36, 47, 48] },
+      north: { uv: [51, 36, 54, 48] },
+      up: { uv: [44, 32, 47, 36] },
+      down: { uv: [47, 36, 50, 32], rotation: 180 }
     }
   };
 
@@ -90189,34 +90246,34 @@ property list uchar int vertex_index
       }
       {
         {
-          const leftArmGroup = this.createAndAddGroup("leftArm", -5, 22, 0);
+          const leftArmGroup = this.createAndAddGroup("leftArm", 5, 22, 0);
           const leftArmGeo = this.getBoxGeometry("leftArm" /* LEFT_ARM */);
           const leftArm = this.createAndAddMesh("leftArm", leftArmGroup, leftArmGeo, mat, "y" /* Y */, -4);
-          leftArm.position.x = this.slim ? -0.5 : -1;
+          leftArm.position.x = this.slim ? 0.5 : 1;
           const leftSleeveGeo = this.getBoxGeometry("leftSleeve" /* LEFT_SLEEVE */);
           const leftSleeve = this.createAndAddMesh("leftSleeve", leftArmGroup, leftSleeveGeo, mat, "y" /* Y */, -4);
-          leftSleeve.position.x = this.slim ? -0.5 : -1;
+          leftSleeve.position.x = this.slim ? 0.5 : 1;
         }
         {
-          const rightArmGroup = this.createAndAddGroup("rightArm", 5, 22, 0);
+          const rightArmGroup = this.createAndAddGroup("rightArm", -5, 22, 0);
           const rightArmGeo = this.getBoxGeometry("rightArm" /* RIGHT_ARM */);
           const rightArm = this.createAndAddMesh("rightArm", rightArmGroup, rightArmGeo, mat, "y" /* Y */, -4);
-          rightArm.position.x = this.slim ? 0.5 : 1;
+          rightArm.position.x = this.slim ? -0.5 : -1;
           const rightSleeveGeo = this.getBoxGeometry("rightSleeve" /* RIGHT_SLEEVE */);
           const rightSleeve = this.createAndAddMesh("rightSleeve", rightArmGroup, rightSleeveGeo, mat, "y" /* Y */, -4);
-          rightSleeve.position.x = this.slim ? 0.5 : 1;
+          rightSleeve.position.x = this.slim ? -0.5 : -1;
         }
       }
       {
         {
-          const leftLegGroup = this.createAndAddGroup("leftLeg", -1.9, 12, 0);
+          const leftLegGroup = this.createAndAddGroup("leftLeg", 1.9, 12, 0);
           const leftLegGeo = this.getBoxGeometry("leftLeg" /* LEFT_LEG */);
           const leftLeg = this.createAndAddMesh("leftLeg", leftLegGroup, leftLegGeo, mat, "y" /* Y */, -6);
           const leftTrousersGeo = this.getBoxGeometry("leftTrousers" /* LEFT_TROUSERS */);
           const leftTrousers = this.createAndAddMesh("leftTrousers", leftLegGroup, leftTrousersGeo, mat, "y" /* Y */, -6);
         }
         {
-          const rightLegGroup = this.createAndAddGroup("rightLeg", 1.9, 12, 0);
+          const rightLegGroup = this.createAndAddGroup("rightLeg", -1.9, 12, 0);
           const rightLegGeo = this.getBoxGeometry("rightLeg" /* RIGHT_LEG */);
           const rightLeg = this.createAndAddMesh("rightLeg", rightLegGroup, rightLegGeo, mat, "y" /* Y */, -6);
           const rightTrousersGeo = this.getBoxGeometry("rightTrousers" /* RIGHT_TROUSERS */);
@@ -90266,9 +90323,10 @@ property list uchar int vertex_index
         mesh.geometry = geometry;
       } else {
         const body = this.getGroupByName("body" /* BODY */);
-        const group = this.createGroup("cape" /* CAPE */, 0, body ? 0 : 24, 2);
+        const group = this.createGroup("cape" /* CAPE */);
+        group.position.set(0, body ? 0 : 24, -2);
         (body ?? this).add(group);
-        group.rotation.set(toRadians(-6), Math.PI, 0);
+        group.rotation.x = toRadians(6);
         const cape = this.createAndAddMesh("cape" /* CAPE */, group, geometry, material);
         cape.position.set(0, -8, -0.5);
       }
@@ -90282,7 +90340,7 @@ property list uchar int vertex_index
     updateSlim(slim) {
       if (slim === this.slim) return;
       this.slim = slim;
-      const offset = slim ? 0.5 : -0.5;
+      const offset = slim ? -0.5 : 0.5;
       for (const part of ["leftArm" /* LEFT_ARM */, "leftSleeve" /* LEFT_SLEEVE */, "rightArm" /* RIGHT_ARM */, "rightSleeve" /* RIGHT_SLEEVE */]) {
         const mesh = this.getMeshByName(part);
         if (mesh) {
@@ -90376,13 +90434,9 @@ property list uchar int vertex_index
       return this.add(...object);
     }
     async addSceneObject(asset, objectSupplier, _options, parent = this) {
-      console.log("addSceneObject", asset);
-      console.log("parent", parent);
-      console.log(_options);
       this.dirty = true;
       const obj = await objectSupplier();
       if (obj?.options?.instanceMeshes && asset.key && asset.key?.assetType === "models") {
-        console.log("instanceMeshes + key");
         let key = asset.key.serialize();
         if (isModelObject(obj)) {
           const { displayPosition, uvLockRotation, tints, cullMask } = obj.options;
@@ -90399,7 +90453,6 @@ property list uchar int vertex_index
           return obj;
         });
       } else {
-        console.log("!instanceMeshes | !key");
         obj.scene = this;
         await obj.init();
         if (!isBlockObject(obj)) {
@@ -92875,7 +92928,10 @@ uniform float opacity;varying vec2 vUv;void main(){vec4 texel=texture2D(inputBuf
     constructor(options) {
       this._dirty = true;
       this._resizeListener = void 0;
+      this._running = false;
+      this._inAnimationLoop = false;
       this._disposed = false;
+      this._frameCallbacks = /* @__PURE__ */ new Map();
       this._debugHelpers = [];
       this._eventDispatchers = /* @__PURE__ */ new Map();
       this._changeListener = () => {
@@ -92886,7 +92942,14 @@ uniform float opacity;varying vec2 vUv;void main(){vec4 texel=texture2D(inputBuf
       if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
         throw new RangeError("render.pixelRatio must be a finite positive number");
       }
-      this._animationLoop = this.animate.bind(this);
+      this._animationLoop = (time) => {
+        this._inAnimationLoop = true;
+        try {
+          this.animate(time);
+        } finally {
+          this._inAnimationLoop = false;
+        }
+      };
       this._frameInterval = this.options.render.fpsLimit > 0 ? 1e3 / this.options.render.fpsLimit : void 0;
       this._scene = this.createScene();
       this._camera = this.createCamera();
@@ -93061,15 +93124,39 @@ uniform float opacity;varying vec2 vUv;void main(){vec4 texel=texture2D(inputBuf
       this._dirty = dirty;
       this.scene.dirty = dirty;
     }
+    /**
+     * Calls a synchronous animation update before each FPS-limited draw while started.
+     * Subscriptions keep the scene drawing without manual dirty flags. Returns an unsubscribe function.
+     * Registering the same callback twice has no effect. Image exports do not invoke callbacks.
+     */
+    onFrame(callback) {
+      if (this._disposed) return () => {
+      };
+      const subscription = this._frameCallbacks.get(callback) ?? {};
+      this._frameCallbacks.set(callback, subscription);
+      return () => {
+        if (this._frameCallbacks.get(callback) === subscription) this._frameCallbacks.delete(callback);
+      };
+    }
     start() {
       if (this._disposed) return;
       this.stop();
-      this.renderer.setAnimationLoop(this._animationLoop);
+      this._running = true;
+      if (!this._inAnimationLoop) this.renderer.setAnimationLoop(this._animationLoop);
     }
     stop() {
       if (this._disposed) return;
-      this.renderer.setAnimationLoop(null);
+      this._running = false;
+      if (this._inAnimationLoop) {
+        queueMicrotask(() => {
+          this.renderer.setAnimationLoop(null);
+          if (this._running) this.renderer.setAnimationLoop(this._animationLoop);
+        });
+      } else {
+        this.renderer.setAnimationLoop(null);
+      }
       this._nextFrameTime = void 0;
+      for (const subscription of this._frameCallbacks.values()) subscription.previous = void 0;
     }
     /**
      * Stops rendering and releases owned resources. Repeated calls have no effect, and a disposed
@@ -93080,6 +93167,7 @@ uniform float opacity;varying vec2 vUv;void main(){vec4 texel=texture2D(inputBuf
       if (this._disposed) return;
       this.stop();
       this._disposed = true;
+      this._frameCallbacks.clear();
       if (this._resizeListener) {
         window.removeEventListener("resize", this._resizeListener);
         this._resizeListener = void 0;
@@ -93114,18 +93202,25 @@ uniform float opacity;varying vec2 vUv;void main(){vec4 texel=texture2D(inputBuf
       this.renderer.forceContextLoss();
     }
     animate(t5 = performance.now()) {
-      if (this._disposed) return;
+      if (!this._running) return;
       if (this._controls?.enabled) {
         this._controls.update();
       }
-      if (this._disposed) return;
-      if (!this.dirty && !this.options.render.renderAlways) return;
+      if (!this._running) return;
+      if (!this.dirty && !this.options.render.renderAlways && !this._frameCallbacks.size) return;
       const interval = this._frameInterval;
       if (interval) {
         const next = this._nextFrameTime;
         if (next !== void 0 && t5 + 0.1 < next) return;
         this._nextFrameTime = next !== void 0 && t5 - next < interval ? next + interval : t5 + interval;
       }
+      for (const [callback, subscription] of [...this._frameCallbacks]) {
+        if (this._frameCallbacks.get(callback) !== subscription) continue;
+        const previous = subscription.previous;
+        subscription.previous = t5;
+        callback({ time: t5 / 1e3, delta: previous === void 0 ? 0 : (t5 - previous) / 1e3 });
+        if (!this._running) return;
+      }
       this.drawFrame();
     }
     drawFrame() {