minerender 2.1.0-alpha.54 → 2.1.0-alpha.59

package/dist/browser/index.mjs

@@ -256,7 +256,9 @@ var init_Caching = __esm({
           this.defaultBlockStatesCache,
           this.blockTintCache,
           this.entityModelCache,
-          this.entityTextureCache
+          this.entityTextureCache,
+          this.entityAnimationCache,
+          this.blockEntityIndexCache
         ];
       }
       static clear() {
@@ -301,6 +303,8 @@ var init_Caching = __esm({
     _Caching.blockTintCache = _Caching.createAssetCache();
     _Caching.entityModelCache = _Caching.createAssetCache();
     _Caching.entityTextureCache = _Caching.createAssetCache();
+    _Caching.entityAnimationCache = _Caching.createAssetCache();
+    _Caching.blockEntityIndexCache = _Caching.createAssetCache();
     Caching = _Caching;
   }
 });
@@ -1725,6 +1729,11 @@ function addWireframeToMesh(geo, mesh, color = 16777215, w = 2) {
   mesh.add(wireframe);
   let axes = new AxesHelper(1);
   mesh.add(axes);
+  return () => {
+    wireGeo.dispose();
+    wireMat.dispose();
+    axes.dispose();
+  };
 }
 var init_model = __esm({
   "src/util/model.ts"() {
@@ -3079,7 +3088,7 @@ var init_InstanceReference = __esm({
 });
 
 // src/renderer/SceneObject.ts
-import { Color as Color2, Euler as Euler3, InstancedBufferAttribute, InstancedMesh, MathUtils, Matrix4 as Matrix43, Mesh as Mesh3, Object3D as Object3D2, Quaternion as Quaternion3, Vector3 as Vector35 } from "three";
+import { Color as Color2, Euler as Euler3, InstancedBufferAttribute, InstancedMesh, MathUtils, Matrix4 as Matrix44, Mesh as Mesh3, Object3D as Object3D2, Quaternion as Quaternion3, Vector3 as Vector35 } from "three";
 function isSceneObject(obj) {
   return obj.isSceneObject;
 }
@@ -3287,7 +3296,7 @@ var init_SceneObject = __esm({
           mesh.instanceColor.needsUpdate = true;
         }
         if (this._scene) this._scene.stats.instanceCount++;
-        this.setMatrixAt(index, new Matrix43());
+        this.setMatrixAt(index, new Matrix44());
         return reference;
       }
       /** Returns the live reference for a raycast hit on this object's instance mesh. */
@@ -3300,7 +3309,7 @@ var init_SceneObject = __esm({
       removeInstanceAt(index) {
         if (!this.instanceReferences.has(index)) return;
         const mesh = this.instanceMesh;
-        this.setMatrixAt(index, new Matrix43().makeScale(0, 0, 0));
+        this.setMatrixAt(index, new Matrix44().makeScale(0, 0, 0));
         this.instanceReferences.delete(index);
         this.freeInstanceIndices.push(index);
         this._instanceCounter = this.instanceReferences.size;
@@ -3330,7 +3339,7 @@ var init_SceneObject = __esm({
       }
       //</editor-fold>
       //<editor-fold desc="TRANSFORMATION">
-      getMatrixAt(index, matrix = new Matrix43()) {
+      getMatrixAt(index, matrix = new Matrix44()) {
         if (!this.instanceReferences.has(index)) throw new MineRenderError("Instance is not active");
         this.instanceMesh.getMatrixAt(index, matrix);
         return matrix;
@@ -3349,7 +3358,7 @@ var init_SceneObject = __esm({
         const oldPosition = new Vector35();
         const oldRotation = new Quaternion3();
         const oldScale = new Vector35();
-        const matrix = new Matrix43();
+        const matrix = new Matrix44();
         if (!scale || !rotation || !position) {
           this.getMatrixAt(index, matrix).decompose(oldPosition, oldRotation, oldScale);
         }
@@ -4104,7 +4113,7 @@ var init_ModelCulling = __esm({
 });
 
 // src/model/scene/ModelObject.ts
-import { BoxGeometry as BoxGeometry5, BufferAttribute as BufferAttribute5, Color as Color8, Euler as Euler6, Matrix4 as Matrix47 } from "three";
+import { BoxGeometry as BoxGeometry5, BufferAttribute as BufferAttribute5, Color as Color8, Euler as Euler6, Matrix4 as Matrix48 } from "three";
 function isModelObject(obj) {
   return obj.isModelObject;
 }
@@ -4183,12 +4192,12 @@ var init_ModelObject = __esm({
                 }
                 elGeo.setAttribute("color", new BufferAttribute5(colors, 3));
               }
-              elGeo.applyMatrix4(new Matrix47().makeTranslation((el.to[0] - el.from[0]) / 2, (el.to[1] - el.from[1]) / 2, (el.to[2] - el.from[2]) / 2));
-              elGeo.applyMatrix4(new Matrix47().makeTranslation(el.from[0], el.from[1], el.from[2]));
+              elGeo.applyMatrix4(new Matrix48().makeTranslation((el.to[0] - el.from[0]) / 2, (el.to[1] - el.from[1]) / 2, (el.to[2] - el.from[2]) / 2));
+              elGeo.applyMatrix4(new Matrix48().makeTranslation(el.from[0], el.from[1], el.from[2]));
               if (el.rotation) {
                 applyElementRotation(el.rotation, elGeo);
               }
-              elGeo.applyMatrix4(new Matrix47().makeTranslation(-8, -8, -8));
+              elGeo.applyMatrix4(new Matrix48().makeTranslation(-8, -8, -8));
               if (displayTransform) DisplayTransforms.apply(elGeo, displayTransform);
               if (this.options.mergeMeshes) {
                 allGeos.push(elGeo);
@@ -4797,6 +4806,59 @@ function shutdown() {
 init_AssetKey();
 init_AssetLoader();
 init_Assets();
+
+// src/assets/BlockEntities.ts
+init_AssetKey();
+init_AssetLoader();
+init_source();
+init_Caching();
+import { Matrix4 as Matrix43 } from "three";
+var BlockEntities = class {
+  /**
+   * Loads the block index of a version. Versions and sources without one yield an empty index, and so does
+   * a failed load: the index is optional, and blocks must not retry or fail with it one by one. The empty
+   * result is cached like any other; `Caching.clear()` or `AssetLoader.setVersion()` forces a new attempt.
+   */
+  static async getIndex(root) {
+    const key = new AssetKey("entity-models", "blocks", void 0, void 0, void 0, ".json", root);
+    key.rootType = void 0;
+    const index = await Caching.blockEntityIndexCache.get(key.serialize(), async () => {
+      try {
+        return await AssetLoader.get(key, "json" /* JSON */) ?? {};
+      } catch (error) {
+        console.warn("Could not load the block entity index; block entities are drawn as plain block models", error);
+        return {};
+      }
+    });
+    return index ?? {};
+  }
+  /** The index entry of a block ID such as `minecraft:chest`. */
+  static entry(index, block) {
+    const entry = Object.prototype.hasOwnProperty.call(index, block) ? index[block] : void 0;
+    return Array.isArray(entry?.parts) ? entry : void 0;
+  }
+  /** Selects the parts and placement for a block ID such as `minecraft:chest`; undefined when nothing is drawn. */
+  static resolve(index, block, state = {}) {
+    const entry = this.entry(index, block);
+    if (!entry) return void 0;
+    const value = (property) => String(state[property]).toLowerCase();
+    const parts = entry.parts.filter((part) => Object.entries(part.when ?? {}).every(([property, values]) => String(values).split("|").includes(value(property))));
+    if (!parts.length) return void 0;
+    let rotation = 0;
+    if (entry.rotation) {
+      const selected = value(entry.rotation.property);
+      rotation = "degrees" in entry.rotation ? entry.rotation.degrees[selected] : Number(selected) * entry.rotation.step;
+      if (!Number.isFinite(rotation)) rotation = 0;
+    }
+    return { parts, rotation, translation: entry.translation ?? [0, 0, 0] };
+  }
+  /** Placement in block space (0..16 per axis), applied on top of the model's own transform. */
+  static matrix(resolved, matrix = new Matrix43()) {
+    return matrix.makeTranslation(8, 0, 8).multiply(new Matrix43().makeRotationY(resolved.rotation * Math.PI / 180)).multiply(new Matrix43().makeTranslation(resolved.translation[0] - 8, resolved.translation[1], resolved.translation[2] - 8));
+  }
+};
+
+// src/assets/index.ts
 init_BlockStates();
 
 // src/assets/Entities.ts
@@ -4867,6 +4929,15 @@ var Entities = class {
     })));
     return { ...layers[names[0]], id: model.id, layers, ...model.transform && { transform: model.transform } };
   }
+  /**
+   * Vanilla's keyframe animations of a model by name, or undefined when the model or the selected version has none.
+   */
+  static async getAnimations(modelKey) {
+    const path = isAssetKey(modelKey) ? modelKey.getFullPath() : modelKey.path;
+    const key = new AssetKey(modelKey.namespace, path, void 0, void 0, "entity-models/animations", ".json");
+    const file = await Caching.entityAnimationCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
+    return file?.animations;
+  }
   static async resolveTexture(modelKey) {
     const path = isAssetKey(modelKey) ? modelKey.getFullPath() : modelKey.path;
     const key = new AssetKey(modelKey.namespace, path, void 0, void 0, "entity-models", ".json");
@@ -4943,6 +5014,119 @@ function trimCanvas(source) {
   return canvas;
 }
 
+// src/entity/EntityAnimation.ts
+var ENTITY_ANIMATION_CHANNELS = ["position", "rotation", "scale"];
+function catmullRom(delta, p0, p1, p22, p32) {
+  return 0.5 * (2 * p1 + (p22 - p0) * delta + (2 * p0 - 5 * p1 + 4 * p22 - p32) * delta * delta + (3 * p1 - p0 - 3 * p22 + p32) * delta * delta * delta);
+}
+function sampleEntityKeyframes(keyframes, time) {
+  if (keyframes.length === 0) return [0, 0, 0];
+  let low = 0, high = keyframes.length;
+  while (low < high) {
+    const middle = low + high >>> 1;
+    if (time <= keyframes[middle].time) high = middle;
+    else low = middle + 1;
+  }
+  const a = Math.max(0, low - 1);
+  const b = Math.min(keyframes.length - 1, a + 1);
+  const from = keyframes[a];
+  const to = keyframes[b];
+  const delta = a === b ? 0 : Math.min(1, Math.max(0, (time - from.time) / (to.time - from.time)));
+  if (to.interpolation === "catmullrom") {
+    const before = keyframes[Math.max(0, a - 1)].value;
+    const after = keyframes[Math.min(keyframes.length - 1, b + 1)].value;
+    return [0, 1, 2].map((i) => catmullRom(delta, before[i], from.value[i], to.value[i], after[i]));
+  }
+  const target = to.pre ?? to.value;
+  return [0, 1, 2].map((i) => from.value[i] + (target[i] - from.value[i]) * delta);
+}
+function entityAnimationTime(animation, time, loop = animation.loop) {
+  return loop && animation.length > 0 ? time % animation.length : time;
+}
+function sampleEntityAnimation(animation, time, loop = animation.loop) {
+  const elapsed = entityAnimationTime(animation, time, loop);
+  const pose = {};
+  for (const [name, bone] of Object.entries(animation.bones)) {
+    const sampled = pose[name] = {};
+    for (const channel of ENTITY_ANIMATION_CHANNELS) {
+      const keyframes = bone[channel];
+      if (keyframes?.length) sampled[channel] = sampleEntityKeyframes(keyframes, elapsed);
+    }
+  }
+  return pose;
+}
+
+// src/entity/scene/EntityAnimationPlayer.ts
+var ZERO = [0, 0, 0];
+var EntityAnimationPlayer = class {
+  constructor() {
+    this.parts = [];
+    this._time = 0;
+    this.loop = false;
+    this.speed = 1;
+  }
+  get animation() {
+    return this._animation;
+  }
+  get time() {
+    return this._time;
+  }
+  /**
+   * Starts an animation on the named parts below each layer root. The current pose of a part becomes its default;
+   * bones without a matching part are skipped.
+   */
+  play(layers, animation, options = {}) {
+    this.stop();
+    this._animation = animation;
+    this._time = options.time ?? 0;
+    this.loop = options.loop ?? animation.loop;
+    this.speed = options.speed ?? 1;
+    for (const layer of layers) {
+      for (const bone of Object.keys(animation.bones)) {
+        const object = layer.getObjectByName(`group:${bone}`);
+        if (!object) continue;
+        this.parts.push({ bone, object, position: object.position.clone(), rotation: object.rotation.clone(), scale: object.scale.clone() });
+      }
+    }
+    this.apply();
+  }
+  /** Restores the default poses. Returns whether an animation was active. */
+  stop() {
+    if (!this._animation) return false;
+    for (const part of this.parts) {
+      part.object.position.copy(part.position);
+      part.object.rotation.copy(part.rotation);
+      part.object.scale.copy(part.scale);
+    }
+    this.clear();
+    return true;
+  }
+  /** Forgets the animation without touching the parts, for parts that no longer exist. */
+  clear() {
+    this.parts = [];
+    this._animation = void 0;
+    this._time = 0;
+  }
+  setTime(seconds) {
+    if (!this._animation) return false;
+    this._time = seconds;
+    this.apply();
+    return true;
+  }
+  advance(deltaSeconds) {
+    return this.setTime(this._time + deltaSeconds * this.speed);
+  }
+  apply() {
+    const pose = sampleEntityAnimation(this._animation, this._time, this.loop);
+    for (const part of this.parts) {
+      const { position = ZERO, rotation = ZERO, scale = ZERO } = pose[part.bone];
+      part.object.position.set(part.position.x + position[0], part.position.y + position[1], part.position.z + position[2]);
+      part.object.rotation.set(part.rotation.x + rotation[0], part.rotation.y + rotation[1], part.rotation.z + rotation[2], part.rotation.order);
+      part.object.scale.set(part.scale.x + scale[0], part.scale.y + scale[1], part.scale.z + scale[2]);
+    }
+  }
+};
+
 // src/entity/scene/EntityObject.ts
 init_SceneObject();
 init_Caching();
@@ -4952,7 +5136,7 @@ init_model();
 init_ModelTextures();
 init_AssetKey();
 init_Materials();
-import { Color as Color3, Euler as Euler4, Matrix4 as Matrix44, Object3D as Object3D3 } from "three";
+import { Color as Color3, Euler as Euler4, Matrix4 as Matrix45, Object3D as Object3D3 } from "three";
 init_three();
 var _EntityObject = class _EntityObject extends SceneObject {
   constructor(entity, options) {
@@ -4960,11 +5144,16 @@ var _EntityObject = class _EntityObject extends SceneObject {
     this.entity = entity;
     this.isEntityObject = true;
     this.meshesCreated = false;
+    this.geometries = /* @__PURE__ */ new Set();
+    this.disposeWireframes = [];
     /** Scrolling materials are owned: their texture offset follows this entity's age. */
     this.scrollMaterials = [];
     /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
     this.age = 0;
+    this.animationPlayer = new EntityAnimationPlayer();
     this.options = (0, import_ts_deepmerge4.default)({}, _EntityObject.DEFAULT_OPTIONS, options ?? {});
+    this.addEventListener("added", () => this.updateScrollSubscription());
+    this.addEventListener("removed", () => this.updateScrollSubscription());
   }
   async init() {
     this.createMeshes();
@@ -4975,6 +5164,10 @@ var _EntityObject = class _EntityObject extends SceneObject {
   }
   disposeAndRemoveAllChildren() {
     this.clearScrollMaterials();
+    for (const geometry of this.geometries) geometry.dispose();
+    this.geometries.clear();
+    for (const dispose of this.disposeWireframes.splice(0)) dispose();
+    this.animationPlayer.clear();
     super.disposeAndRemoveAllChildren();
   }
   clearScrollMaterials() {
@@ -4985,6 +5178,19 @@ var _EntityObject = class _EntityObject extends SceneObject {
       material.dispose();
     }
   }
+  updateScrollSubscription() {
+    if (this.parent && this.scrollMaterials.length) {
+      if (this.scrollTicker === void 0) {
+        this.scrollTicker = Ticker.add(() => {
+          this.age++;
+          this.updateScroll();
+        });
+      }
+    } else {
+      Ticker.remove(this.scrollTicker);
+      this.scrollTicker = void 0;
+    }
+  }
   /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
   updateScroll() {
     for (const { offset, speed } of this.scrollMaterials) {
@@ -4992,6 +5198,39 @@ var _EntityObject = class _EntityObject extends SceneObject {
     }
     this.notifyDirty();
   }
+  //<editor-fold desc="ANIMATION">
+  /** The animation started by {@link playAnimation}, until {@link stopAnimation} or disposal. */
+  get animation() {
+    return this.animationPlayer.animation;
+  }
+  /** Seconds since the animation started, before looping. */
+  get animationTime() {
+    return this.animationPlayer.time;
+  }
+  /**
+   * Poses the object from a keyframe animation of {@link Entities.getAnimations}, replacing the current one.
+   * Parts of every layer are matched by name and their current pose is the default the offsets add to.
+   * The object owns no clock: call {@link advanceAnimation} per frame, or {@link setAnimationTime}.
+   */
+  playAnimation(animation, options) {
+    this.createMeshes();
+    const layers = Object.keys(this.entityLayers).map((name) => this.getLayerGroup(name)).filter((layer) => !!layer);
+    this.animationPlayer.play(layers, animation, options);
+    this.notifyDirty();
+  }
+  /** Stops the animation and restores the default pose. */
+  stopAnimation() {
+    if (this.animationPlayer.stop()) this.notifyDirty();
+  }
+  /** Poses the object at an explicit time in seconds. Has no effect without an animation. */
+  setAnimationTime(seconds) {
+    if (this.animationPlayer.setTime(seconds)) this.notifyDirty();
+  }
+  /** Advances the animation by a frame delta in seconds, scaled by its speed. Has no effect without an animation. */
+  advanceAnimation(deltaSeconds) {
+    if (this.animationPlayer.advance(deltaSeconds)) this.notifyDirty();
+  }
+  //</editor-fold>
   getLayerGroup(name) {
     return super.getGroupByName(`layer:${name}`);
   }
@@ -5025,7 +5264,7 @@ var _EntityObject = class _EntityObject extends SceneObject {
     const transform = this.options.flip === void 0 ? this.entity.transform : void 0;
     if (transform) {
       for (const op of transform) {
-        const matrix = new Matrix44();
+        const matrix = new Matrix45();
         if ("scale" in op) matrix.makeScale(...op.scale);
         else if ("translate" in op) matrix.makeTranslation(...op.translate);
         else matrix.makeRotationFromEuler(new Euler4(...op.rotate, "ZYX"));
@@ -5062,6 +5301,7 @@ var _EntityObject = class _EntityObject extends SceneObject {
         depth + growZ * 2,
         uv
       ).clone();
+      this.geometries.add(geometry);
       geometry.translate(cube.origin[0] + width / 2, cube.origin[1] + height / 2, cube.origin[2] + depth / 2);
       if (inward && Math.min(width + growX * 2, height + growY * 2, depth + growZ * 2) > 0) {
         const index = Array.from(geometry.getIndex().array);
@@ -5070,7 +5310,7 @@ var _EntityObject = class _EntityObject extends SceneObject {
       const mesh = this.createMesh(name, geometry, material);
       mesh.renderOrder = renderOrder;
       anchor.add(mesh);
-      if (this.options.wireframe) addWireframeToMesh(geometry, mesh);
+      if (this.options.wireframe) this.disposeWireframes.push(addWireframeToMesh(geometry, mesh));
     }
     for (const [childName, child] of Object.entries(part.children)) {
       this.createPart(childName, child, anchor, size, material, renderOrder, inward);
@@ -5104,11 +5344,8 @@ var _EntityObject = class _EntityObject extends SceneObject {
       this.clearScrollMaterials();
     } else if (this.scrollMaterials.length) {
       this.updateScroll();
-      this.scrollTicker = Ticker.add(() => {
-        this.age++;
-        this.updateScroll();
-      });
     }
+    this.updateScrollSubscription();
     this.notifyDirty();
   }
 };
@@ -5122,7 +5359,7 @@ function isEntityObject(obj) {
 init_MineRenderError();
 
 // src/export/SceneExporter.ts
-import { ClampToEdgeWrapping as ClampToEdgeWrapping2, Color as Color7, Float32BufferAttribute as Float32BufferAttribute3, Matrix4 as Matrix46, Mesh as Mesh5, MeshBasicMaterial as MeshBasicMaterial2, NearestFilter as NearestFilter3, RGBAFormat as RGBAFormat3, Scene as Scene4, Source as Source2, Texture as Texture4, UnsignedByteType } from "three";
+import { ClampToEdgeWrapping as ClampToEdgeWrapping2, Color as Color7, Float32BufferAttribute as Float32BufferAttribute3, Matrix4 as Matrix47, Mesh as Mesh5, MeshBasicMaterial as MeshBasicMaterial2, NearestFilter as NearestFilter3, RGBAFormat as RGBAFormat3, Scene as Scene4, Source as Source2, Texture as Texture4, UnsignedByteType } from "three";
 
 // ../../node_modules/three/examples/jsm/exporters/OBJExporter.js
 import {
@@ -5548,7 +5785,7 @@ import {
   LinearMipmapLinearFilter,
   LinearMipmapNearestFilter,
   MathUtils as MathUtils2,
-  Matrix4 as Matrix45,
+  Matrix4 as Matrix46,
   MirroredRepeatWrapping,
   NearestFilter as NearestFilter2,
   NearestMipmapLinearFilter,
@@ -6838,7 +7075,7 @@ var GLTFWriter = class {
     if (rootJoint === void 0) return null;
     const joints = [];
     const inverseBindMatrices = new Float32Array(skeleton.bones.length * 16);
-    const temporaryBoneInverse = new Matrix45();
+    const temporaryBoneInverse = new Matrix46();
     for (let i = 0; i < skeleton.bones.length; ++i) {
       joints.push(nodeMap.get(skeleton.bones[i]));
       temporaryBoneInverse.copy(skeleton.boneInverses[i]);
@@ -7304,7 +7541,7 @@ var GLTFMeshGpuInstancing = class {
     const translationAttr = new Float32Array(mesh.count * 3);
     const rotationAttr = new Float32Array(mesh.count * 4);
     const scaleAttr = new Float32Array(mesh.count * 3);
-    const matrix = new Matrix45();
+    const matrix = new Matrix46();
     const position = new Vector38();
     const quaternion = new Quaternion4();
     const scale = new Vector38();
@@ -7478,7 +7715,7 @@ var SceneExporter = class {
   }
 };
 function localMatrix(object) {
-  return object.matrixAutoUpdate ? new Matrix46().compose(object.position, object.quaternion, object.scale) : object.matrix.clone();
+  return object.matrixAutoUpdate ? new Matrix47().compose(object.position, object.quaternion, object.scale) : object.matrix.clone();
 }
 function createSnapshot(root, gltf, bakeColors = false) {
   const scene = new Scene4();
@@ -7590,7 +7827,7 @@ function createSnapshot(root, gltf, bakeColors = false) {
       const instanced = mesh;
       if (instanced.isInstancedMesh) {
         for (let i = 0; i < instanced.count; i++) {
-          const matrix = new Matrix46();
+          const matrix = new Matrix47();
           instanced.getMatrixAt(i, matrix);
           const color = instanced.instanceColor ? new Color7().fromBufferAttribute(instanced.instanceColor, i) : void 0;
           addMesh(mesh, world.clone().multiply(matrix), color);
@@ -7604,7 +7841,7 @@ function createSnapshot(root, gltf, bakeColors = false) {
   try {
     const ancestors = [];
     for (let parent = root.parent; parent; parent = parent.parent) ancestors.unshift(parent);
-    const world = new Matrix46();
+    const world = new Matrix47();
     for (const ancestor of ancestors) {
       if (!ancestor.visible) return { scene, dispose };
       world.multiply(localMatrix(ancestor));
@@ -8506,7 +8743,7 @@ var import_ts_deepmerge6 = __toESM(require_dist());
 init_MineRenderError();
 init_InstanceReference();
 init_AssetKey();
-import { Euler as Euler8, Matrix4 as Matrix48, Quaternion as Quaternion5, Vector3 as Vector311 } from "three";
+import { Euler as Euler8, Matrix4 as Matrix49, Quaternion as Quaternion5, Vector3 as Vector311 } from "three";
 init_ModelCulling();
 init_FluidGeometry();
 var _BlockObject = class _BlockObject extends SceneObject {
@@ -8523,6 +8760,9 @@ var _BlockObject = class _BlockObject extends SceneObject {
     this._variants = [];
     this._models = [];
     this._cullMask = 0;
+    this._entities = [];
+    this._entityPlacement = new Matrix49();
+    this._entityGeneration = 0;
     this.options = (0, import_ts_deepmerge6.default)({}, _BlockObject.DEFAULT_OPTIONS, options ?? {});
   }
   async init() {
@@ -8542,6 +8782,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
   }
   clearModels() {
     this.removeModels(this._models.splice(0));
+    this._entityGeneration++;
+    this.removeEntities(this._entities.splice(0));
     this._fluidKey = void 0;
     this._fluidModel = void 0;
     this._isInstanced = false;
@@ -8553,6 +8795,57 @@ var _BlockObject = class _BlockObject extends SceneObject {
       if (!isInstanceReference(model)) model.dispose();
     }
   }
+  removeEntities(entities) {
+    for (const entity of entities) {
+      entity.removeFromScene();
+      entity.dispose();
+    }
+  }
+  /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
+  get blockEntities() {
+    return this._entities;
+  }
+  /**
+   * Draws the block through the dataset's block-entity index. Returns false, leaving nothing behind,
+   * when the block is not listed or one of its models cannot be loaded.
+   */
+  async createBlockEntities() {
+    const key = this.blockState.key;
+    if (!key || this.options.displayPosition) return false;
+    const generation = this._entityGeneration;
+    const created = [];
+    let resolved;
+    try {
+      resolved = BlockEntities.resolve(await BlockEntities.getIndex(key.root), key.toNamespacedString(), this.state);
+      if (!resolved) return false;
+      for (const part of resolved.parts) {
+        const [namespace, path] = part.model.includes(":") ? part.model.split(":") : [key.namespace, part.model];
+        const texture = part.textureLocation === void 0 ? void 0 : AssetKey.parse("textures", part.textureLocation.replace(/^([^:]+:)?textures\//, "$1"));
+        if (texture) texture.root = key.root;
+        const entity = await Entities.getEntity(new BasicAssetKey(namespace, path), texture, { layer: part.layer });
+        if (!entity) throw new MineRenderError(`Missing entity model ${part.model}`);
+        created.push(await this.scene.addEntity(entity, { wireframe: this.options.wireframe }));
+      }
+    } catch (error) {
+      console.warn(`Could not draw block entity ${key.toNamespacedString()}, using its block model`, error);
+      this.removeEntities(created);
+      return false;
+    }
+    if (generation !== this._entityGeneration) {
+      this.removeEntities(created);
+      return true;
+    }
+    BlockEntities.matrix(resolved, this._entityPlacement);
+    this._entities = created;
+    this.placeEntities();
+    return true;
+  }
+  placeEntities() {
+    const matrix = new Matrix49().makeTranslation(this.position.x - 8, this.position.y - 8, this.position.z - 8).multiply(this._entityPlacement);
+    for (const entity of this._entities) {
+      matrix.decompose(entity.position, entity.quaternion, entity.scale);
+    }
+  }
   get isOccluding() {
     return this._models.some((model) => {
       const object = isInstanceReference(model) ? model.instanceable : model;
@@ -8634,7 +8927,7 @@ var _BlockObject = class _BlockObject extends SceneObject {
       () => new FluidModelObject2(kind, surface.sample, this.blockState.key, this.options)
     );
     const previous = this._fluidModel;
-    const matrix = previous ? this.getModelMatrix(previous) : new Matrix48().makeTranslation(...this.position.toArray());
+    const matrix = previous ? this.getModelMatrix(previous) : new Matrix49().makeTranslation(...this.position.toArray());
     if (isInstanceReference(replacement)) replacement.setMatrix(matrix);
     else matrix.decompose(replacement.position, replacement.quaternion, replacement.scale);
     this._models = this._models.filter((model) => model !== previous);
@@ -8664,13 +8957,20 @@ var _BlockObject = class _BlockObject extends SceneObject {
       await this.updateFluid(this._fluidSampler);
       return;
     }
+    const hasEntities = await this.createBlockEntities();
     const variantsToCreate = await this.mapStateToVariant(this.state);
     this._variants = variantsToCreate;
     for (let blockStateVariant of variantsToCreate) {
+      if (hasEntities && !await this.hasGeometry(blockStateVariant)) continue;
       this._models.push(await this.createVariant(blockStateVariant));
     }
     await this.updateFluid(this._fluidSampler);
   }
+  async hasGeometry(variant) {
+    const modelKey = AssetKey.parse("models", variant.model);
+    modelKey.root = this.blockState.key?.root;
+    return !!(await Models.getMerged(modelKey))?.elements?.length;
+  }
   getSingleVariant(variants) {
     return BlockStateResolver.choose(variants);
   }
@@ -8765,7 +9065,7 @@ var _BlockObject = class _BlockObject extends SceneObject {
   setPositionRotationScaleAt(index, position, rotation, scale) {
     super.setPositionRotationScaleAt(index, position, rotation, scale);
   }
-  getMatrixAt(index, matrix = new Matrix48()) {
+  getMatrixAt(index, matrix = new Matrix49()) {
     if (!this.isInstanced) throw new MineRenderError("Object is not instanced");
     const child = this._models[0];
     if (child && isModelObject(child)) {
@@ -8790,6 +9090,7 @@ var _BlockObject = class _BlockObject extends SceneObject {
     for (let model of this._models) {
       model.setPosition(position);
     }
+    this.placeEntities();
     this.notifyDirty();
   }
   //TODO: should override rotation + scale methods
@@ -13329,7 +13630,7 @@ init_CubeFace();
 init_AssetKey();
 init_Models();
 init_CubeFace();
-import { Matrix4 as Matrix49, Vector3 as Vector314 } from "three";
+import { Matrix4 as Matrix410, Vector3 as Vector314 } from "three";
 init_ModelCulling();
 init_ModelObject();
 init_UVMapper();
@@ -13392,7 +13693,7 @@ var SectionModels = class {
         });
         await object.init();
         const geometry = object.children[0].geometry;
-        geometry.applyMatrix4(new Matrix49().makeRotationFromEuler(rotation));
+        geometry.applyMatrix4(new Matrix410().makeRotationFromEuler(rotation));
         object.clear();
         const cullFaces = CUBE_FACES.map((face) => {
           const local = CUBE_FACES.findIndex((name) => name === atlas.model.elements[0].faces[face]?.cullface);
@@ -13804,7 +14105,8 @@ var Chunk = class _Chunk {
         this.data.set(index, void 0);
         return void 0;
       }
-      const template = getFluidKind(blockState.key, stored.properties) ? void 0 : await this.sectionModels?.get(blockState, stored.properties);
+      const perBlock = !this.sectionModels || getFluidKind(blockState.key, stored.properties) || blockState.key && BlockEntities.entry(await BlockEntities.getIndex(blockState.key.root), blockState.key.toNamespacedString());
+      const template = perBlock ? void 0 : await this.sectionModels.get(blockState, stored.properties);
       if (template) {
         this.sectionBlocks.set(index, { index, template, cullMask: 0 });
         this.meshDirty = true;
@@ -13913,6 +14215,7 @@ export {
   BUILTIN_GENERATED,
   BasicAssetKey,
   BatchedExecutor,
+  BlockEntities,
   BlockObject,
   BlockStateResolver,
   BlockStates,
@@ -13936,7 +14239,9 @@ export {
   DefaultBlockStates,
   DisplayPosition,
   DisplayTransforms,
+  ENTITY_ANIMATION_CHANNELS,
   Entities,
+  EntityAnimationPlayer,
   EntityObject,
   Env,
   FluidModelObject,
@@ -14010,6 +14315,7 @@ export {
   createCanvas,
   createFluidGeometry,
   createImage,
+  entityAnimationTime,
   estimateBytesUsed,
   getBlockFluidState,
   getFluidKind,
@@ -14043,6 +14349,8 @@ export {
   prefix,
   probeImageSize,
   registerBrowserEnv,
+  sampleEntityAnimation,
+  sampleEntityKeyframes,
   sampleFluid,
   serializeBoxGeometryKey,
   serializeImageKey,