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

package/dist/node/index.js

@@ -2498,30 +2498,69 @@ var init_TextureAtlas = __esm({
 var ModelGenerator;
 var init_ModelGenerator = __esm({
   "src/model/ModelGenerator.ts"() {
+    init_CubeFace();
     ModelGenerator = class {
       static {
         this.ITEM_LAYERS = ["layer0", "layer1", "layer2", "layer3", "layer4"];
       }
+      /**
+       * 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 = (x, y) => x >= 0 && y >= 0 && x < width && y < height && data[(y * width + x) * 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 = (i) => horizontal ? opaque(i, line) && !opaque(i, line + dy) : opaque(line, i) && !opaque(line + dx, i);
+              if (!exposed(start)) continue;
+              let end = start + 1;
+              while (end < length && exposed(end)) end++;
+              let uv, from, to;
+              if (horizontal) {
+                const y = 16 - (line + (dy > 0 ? 1 : 0)) * sy;
+                uv = [start * sx, line * sy, end * sx, (line + 1) * sy];
+                from = [start * sx, y, 7.5];
+                to = [end * sx, y, 8.5];
+              } else {
+                const x = (line + (dx > 0 ? 1 : 0)) * sx;
+                uv = [line * sx, start * sy, (line + 1) * sx, end * sy];
+                from = [x, 16 - end * sy, 7.5];
+                to = [x, 16 - start * sy, 8.5];
+              }
+              elements.push({ from, to, faces: { [face]: { uv, texture, tintindex } }, shade: true });
+              start = end;
+            }
+          }
+        }
+        return elements;
       }
     };
   }
@@ -2888,7 +2927,15 @@ var init_UVMapper = __esm({
             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(p5, "Item model elements", model.elements);
@@ -4096,7 +4143,6 @@ var init_ModelObject = __esm({
         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);
       }
       static {
         this.DEFAULT_OPTIONS = (0, import_ts_deepmerge5.default)({}, SceneObject.DEFAULT_OPTIONS, {});
@@ -5113,6 +5159,10 @@ var EntityObject = class _EntityObject extends SceneObject {
         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(name, geometry, material);
       mesh.renderOrder = renderOrder;
       anchor.add(mesh);
@@ -8083,7 +8133,7 @@ var SceneStatsDisplay = class {
   }
   init() {
     this.statsContainer.classList.add("minerender-stats");
-    setInterval(() => {
+    this.interval = setInterval(() => {
       for (let line of this.lines) {
         line.update();
       }
@@ -8092,6 +8142,13 @@ var SceneStatsDisplay = class {
   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);
@@ -10530,7 +10587,7 @@ var SKIN_PARTS = Object.values(SkinPart);
 // src/skin/SkinTextureCoordinates.ts
 var baseSkinCoordinates = {
   head: {
-    east: {
+    west: {
       // left
       uv: [
         0,
@@ -10539,7 +10596,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    west: {
+    east: {
       // right
       uv: [
         16,
@@ -10548,7 +10605,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    north: {
+    south: {
       // front
       uv: [
         8,
@@ -10557,7 +10614,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    south: {
+    north: {
       // back
       uv: [
         24,
@@ -10569,24 +10626,24 @@ var baseSkinCoordinates = {
     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,
@@ -10594,7 +10651,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         28,
         20,
@@ -10602,7 +10659,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         20,
@@ -10610,7 +10667,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         32,
         20,
@@ -10620,23 +10677,23 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        28,
-        20,
         20,
-        16
+        16,
+        28,
+        20
       ]
     },
     down: {
       uv: [
-        36,
-        16,
         28,
-        20
+        20,
+        36,
+        16
       ]
     }
   },
   leftArm: {
-    east: {
+    west: {
       uv: [
         32,
         52,
@@ -10644,7 +10701,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         40,
         52,
@@ -10652,7 +10709,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         36,
         52,
@@ -10660,7 +10717,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         44,
         52,
@@ -10670,23 +10727,23 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        40,
-        52,
         36,
-        48
+        48,
+        40,
+        52
       ]
     },
     down: {
       uv: [
-        44,
-        48,
         40,
-        52
+        52,
+        44,
+        48
       ]
     }
   },
   rightArm: {
-    east: {
+    west: {
       uv: [
         40,
         20,
@@ -10694,7 +10751,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         20,
@@ -10702,7 +10759,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         44,
         20,
@@ -10710,7 +10767,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         52,
         20,
@@ -10720,23 +10777,23 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        48,
-        20,
         44,
-        16
+        16,
+        48,
+        20
       ]
     },
     down: {
       uv: [
-        52,
-        16,
         48,
-        20
+        20,
+        52,
+        16
       ]
     }
   },
   leftLeg: {
-    east: {
+    west: {
       uv: [
         16,
         52,
@@ -10744,7 +10801,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         24,
         52,
@@ -10752,7 +10809,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         52,
@@ -10760,7 +10817,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         28,
         52,
@@ -10770,24 +10827,24 @@ var baseSkinCoordinates = {
     },
     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,
@@ -10795,7 +10852,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         20,
@@ -10803,7 +10860,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         20,
@@ -10811,7 +10868,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         20,
@@ -10821,23 +10878,23 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        8,
-        20,
         4,
-        16
+        16,
+        8,
+        20
       ]
     },
     down: {
       uv: [
-        12,
-        16,
         8,
-        20
+        20,
+        12,
+        16
       ]
     }
   },
   hat: {
-    east: {
+    west: {
       uv: [
         32,
         8,
@@ -10845,7 +10902,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         8,
@@ -10853,7 +10910,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    north: {
+    south: {
       uv: [
         40,
         8,
@@ -10861,7 +10918,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    south: {
+    north: {
       uv: [
         56,
         8,
@@ -10871,24 +10928,24 @@ var baseSkinCoordinates = {
     },
     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,
@@ -10896,7 +10953,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         28,
         36,
@@ -10904,7 +10961,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         36,
@@ -10912,7 +10969,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         32,
         36,
@@ -10922,24 +10979,24 @@ var baseSkinCoordinates = {
     },
     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,
@@ -10947,7 +11004,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         56,
         52,
@@ -10955,7 +11012,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         52,
         52,
@@ -10963,7 +11020,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         60,
         52,
@@ -10973,24 +11030,24 @@ var baseSkinCoordinates = {
     },
     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,
@@ -10998,7 +11055,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         36,
@@ -11006,7 +11063,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         44,
         36,
@@ -11014,7 +11071,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         52,
         36,
@@ -11024,24 +11081,24 @@ var baseSkinCoordinates = {
     },
     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,
@@ -11049,7 +11106,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         52,
@@ -11057,7 +11114,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         52,
@@ -11065,7 +11122,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         52,
@@ -11075,23 +11132,23 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        8,
-        52,
         4,
-        48
+        48,
+        8,
+        52
       ]
     },
     down: {
       uv: [
-        12,
-        48,
         8,
-        52
+        52,
+        12,
+        48
       ]
     }
   },
   rightTrousers: {
-    east: {
+    west: {
       uv: [
         0,
         36,
@@ -11099,7 +11156,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         36,
@@ -11107,7 +11164,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         36,
@@ -11115,7 +11172,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         36,
@@ -11125,18 +11182,18 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        8,
-        36,
         4,
-        32
+        32,
+        8,
+        36
       ]
     },
     down: {
       uv: [
-        12,
-        32,
         8,
-        36
+        36,
+        12,
+        32
       ],
       rotation: 180
     }
@@ -11157,35 +11214,35 @@ var slimSkinTextureCoordinates = {
   ...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 }
   }
 };
 
@@ -11425,34 +11482,34 @@ var SkinObject = class extends SceneObject {
     }
     {
       {
-        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 */);
@@ -11502,9 +11559,10 @@ var SkinObject = class extends SceneObject {
       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);
     }
@@ -11518,7 +11576,7 @@ var SkinObject = class extends SceneObject {
   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) {
@@ -11615,13 +11673,9 @@ var MineRenderScene = class _MineRenderScene extends import_three30.Scene {
     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;
@@ -11638,7 +11692,6 @@ var MineRenderScene = class _MineRenderScene extends import_three30.Scene {
         return obj;
       });
     } else {
-      console.log("!instanceMeshes | !key");
       obj.scene = this;
       await obj.init();
       if (!isBlockObject(obj)) {
@@ -12335,7 +12388,10 @@ var Renderer = class _Renderer {
   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 = () => {
@@ -12346,7 +12402,14 @@ var Renderer = class _Renderer {
     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();
@@ -12561,15 +12624,39 @@ var Renderer = class _Renderer {
     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
@@ -12580,6 +12667,7 @@ var Renderer = class _Renderer {
     if (this._disposed) return;
     this.stop();
     this._disposed = true;
+    this._frameCallbacks.clear();
     if (this._resizeListener) {
       window.removeEventListener("resize", this._resizeListener);
       this._resizeListener = void 0;
@@ -12614,18 +12702,25 @@ var Renderer = class _Renderer {
     this.renderer.forceContextLoss();
   }
   animate(t = 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 && t + 0.1 < next) return;
       this._nextFrameTime = next !== void 0 && t - next < interval ? next + interval : t + interval;
     }
+    for (const [callback, subscription] of [...this._frameCallbacks]) {
+      if (this._frameCallbacks.get(callback) !== subscription) continue;
+      const previous = subscription.previous;
+      subscription.previous = t;
+      callback({ time: t / 1e3, delta: previous === void 0 ? 0 : (t - previous) / 1e3 });
+      if (!this._running) return;
+    }
     this.drawFrame();
   }
   drawFrame() {