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

package/dist/browser/index.mjs

@@ -2416,27 +2416,66 @@ var init_TextureAtlas = __esm({
 var ModelGenerator;
 var init_ModelGenerator = __esm({
   "src/model/ModelGenerator.ts"() {
+    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 = (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;
       }
     };
     ModelGenerator.ITEM_LAYERS = ["layer0", "layer1", "layer2", "layer3", "layer4"];
@@ -2804,7 +2843,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);
@@ -4020,7 +4067,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);
       }
       async init() {
         await this.loadTextures();
@@ -4903,6 +4949,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);
@@ -7920,7 +7970,7 @@ var SceneStatsDisplay = class {
   }
   init() {
     this.statsContainer.classList.add("minerender-stats");
-    setInterval(() => {
+    this.interval = setInterval(() => {
       for (let line of this.lines) {
         line.update();
       }
@@ -7929,6 +7979,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);
@@ -10366,7 +10423,7 @@ var SKIN_PARTS = Object.values(SkinPart);
 // src/skin/SkinTextureCoordinates.ts
 var baseSkinCoordinates = {
   head: {
-    east: {
+    west: {
       // left
       uv: [
         0,
@@ -10375,7 +10432,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    west: {
+    east: {
       // right
       uv: [
         16,
@@ -10384,7 +10441,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    north: {
+    south: {
       // front
       uv: [
         8,
@@ -10393,7 +10450,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    south: {
+    north: {
       // back
       uv: [
         24,
@@ -10405,24 +10462,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,
@@ -10430,7 +10487,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         28,
         20,
@@ -10438,7 +10495,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         20,
@@ -10446,7 +10503,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         32,
         20,
@@ -10456,23 +10513,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,
@@ -10480,7 +10537,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         40,
         52,
@@ -10488,7 +10545,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         36,
         52,
@@ -10496,7 +10553,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         44,
         52,
@@ -10506,23 +10563,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,
@@ -10530,7 +10587,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         20,
@@ -10538,7 +10595,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         44,
         20,
@@ -10546,7 +10603,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         52,
         20,
@@ -10556,23 +10613,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,
@@ -10580,7 +10637,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         24,
         52,
@@ -10588,7 +10645,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         52,
@@ -10596,7 +10653,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         28,
         52,
@@ -10606,24 +10663,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,
@@ -10631,7 +10688,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         20,
@@ -10639,7 +10696,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         20,
@@ -10647,7 +10704,7 @@ var baseSkinCoordinates = {
         32
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         20,
@@ -10657,23 +10714,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,
@@ -10681,7 +10738,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         8,
@@ -10689,7 +10746,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    north: {
+    south: {
       uv: [
         40,
         8,
@@ -10697,7 +10754,7 @@ var baseSkinCoordinates = {
         16
       ]
     },
-    south: {
+    north: {
       uv: [
         56,
         8,
@@ -10707,24 +10764,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,
@@ -10732,7 +10789,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         28,
         36,
@@ -10740,7 +10797,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         20,
         36,
@@ -10748,7 +10805,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         32,
         36,
@@ -10758,24 +10815,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,
@@ -10783,7 +10840,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         56,
         52,
@@ -10791,7 +10848,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         52,
         52,
@@ -10799,7 +10856,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         60,
         52,
@@ -10809,24 +10866,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,
@@ -10834,7 +10891,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         48,
         36,
@@ -10842,7 +10899,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         44,
         36,
@@ -10850,7 +10907,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         52,
         36,
@@ -10860,24 +10917,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,
@@ -10885,7 +10942,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         52,
@@ -10893,7 +10950,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         52,
@@ -10901,7 +10958,7 @@ var baseSkinCoordinates = {
         64
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         52,
@@ -10911,23 +10968,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,
@@ -10935,7 +10992,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    west: {
+    east: {
       uv: [
         8,
         36,
@@ -10943,7 +11000,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    north: {
+    south: {
       uv: [
         4,
         36,
@@ -10951,7 +11008,7 @@ var baseSkinCoordinates = {
         48
       ]
     },
-    south: {
+    north: {
       uv: [
         12,
         36,
@@ -10961,18 +11018,18 @@ var baseSkinCoordinates = {
     },
     up: {
       uv: [
-        8,
-        36,
         4,
-        32
+        32,
+        8,
+        36
       ]
     },
     down: {
       uv: [
-        12,
-        32,
         8,
-        36
+        36,
+        12,
+        32
       ],
       rotation: 180
     }
@@ -10993,35 +11050,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 }
   }
 };
 
@@ -11261,34 +11318,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 */);
@@ -11338,9 +11395,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);
     }
@@ -11354,7 +11412,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) {
@@ -11448,13 +11506,9 @@ var _MineRenderScene = class _MineRenderScene extends Scene5 {
     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;
@@ -11471,7 +11525,6 @@ var _MineRenderScene = class _MineRenderScene extends Scene5 {
         return obj;
       });
     } else {
-      console.log("!instanceMeshes | !key");
       obj.scene = this;
       await obj.init();
       if (!isBlockObject(obj)) {
@@ -12178,7 +12231,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 = () => {
@@ -12189,7 +12245,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();
@@ -12364,15 +12427,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
@@ -12383,6 +12470,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;
@@ -12417,18 +12505,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() {