minerender 2.1.0-alpha.54 → 2.1.0-alpha.55

package/dist/node/index.d.mts

@@ -808,6 +808,55 @@ type BlockStateProperties = {
     [key: string]: string;
 };
 
+/** One model drawn by a block-entity renderer. */
+interface BlockEntityPart {
+    model: string;
+    /** Model layer; defaults to "main". */
+    layer?: string;
+    /** Set only when the texture differs from the layer's default. */
+    textureLocation?: string;
+    /** Blockstate multipart syntax: every property must match, and "a|b" matches either value. */
+    when?: Record<string, string>;
+}
+/** Degrees per property value, or degrees per unit of a numeric property. */
+type BlockEntityRotation = {
+    property: string;
+    degrees: Record<string, number>;
+} | {
+    property: string;
+    step: number;
+};
+interface BlockEntityEntry {
+    parts: BlockEntityPart[];
+    rotation?: BlockEntityRotation;
+    /** Offset in model units, applied before the rotation. */
+    translation?: TripleArray;
+}
+/** The dataset's `blocks.json`: block ID to the models its block-entity renderer draws. */
+type BlockEntityIndex = MinecraftAsset & {
+    [block: string]: BlockEntityEntry;
+};
+interface ResolvedBlockEntity {
+    parts: BlockEntityPart[];
+    /** Degrees counter-clockwise seen from above, about the block's vertical centre axis. */
+    rotation: number;
+    translation: TripleArray;
+}
+declare class BlockEntities {
+    /**
+     * 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 getIndex(root?: string): Promise<BlockEntityIndex>;
+    /** The index entry of a block ID such as `minecraft:chest`. */
+    static entry(index: BlockEntityIndex, block: string): Maybe<BlockEntityEntry>;
+    /** Selects the parts and placement for a block ID such as `minecraft:chest`; undefined when nothing is drawn. */
+    static resolve(index: BlockEntityIndex, block: string, state?: BlockStateProperties): Maybe<ResolvedBlockEntity>;
+    /** Placement in block space (0..16 per axis), applied on top of the model's own transform. */
+    static matrix(resolved: ResolvedBlockEntity, matrix?: Matrix4): Matrix4;
+}
+
 declare class BlockStates {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
@@ -822,6 +871,44 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
+/** `entity-models/animations/<namespace>/<model id>.json`: vanilla's keyframe animations of one model. */
+interface EntityAnimationFile extends MinecraftAsset {
+    id: string;
+    animations: Record<string, EntityAnimation>;
+}
+interface EntityAnimation {
+    /** Seconds. */
+    length: number;
+    loop: boolean;
+    /** Part name anywhere in a layer; `root` is the layer's root part. */
+    bones: Record<string, EntityAnimationBone>;
+}
+type EntityAnimationChannel = "position" | "rotation" | "scale";
+/** Keyframes in time order per channel. */
+type EntityAnimationBone = Partial<Record<EntityAnimationChannel, EntityAnimationKeyframe[]>>;
+interface EntityAnimationKeyframe {
+    /** Seconds. */
+    time: number;
+    /** Offset from the default pose: model units, radians, or scale minus one. */
+    value: TripleArray;
+    /** Value to arrive at when it differs from `value`; linear interpolation only. */
+    pre?: TripleArray;
+    /** Applies between the previous keyframe and this one. */
+    interpolation: "linear" | "catmullrom";
+}
+/** Sampled offsets from the default pose, per bone and channel. */
+type EntityAnimationPose = Record<string, Partial<Record<EntityAnimationChannel, TripleArray>>>;
+declare const ENTITY_ANIMATION_CHANNELS: readonly EntityAnimationChannel[];
+/**
+ * Samples one channel like vanilla's `KeyframeAnimation.Entry`: the first value holds before the
+ * first keyframe and the last value after the last one; in between, the later keyframe selects the interpolation.
+ */
+declare function sampleEntityKeyframes(keyframes: readonly EntityAnimationKeyframe[], time: number): TripleArray;
+/** Elapsed seconds within the animation: modulo `length` when looping, as vanilla does. */
+declare function entityAnimationTime(animation: EntityAnimation, time: number, loop?: boolean): number;
+/** Samples every bone and channel of an animation at `time` seconds. */
+declare function sampleEntityAnimation(animation: EntityAnimation, time: number, loop?: boolean): EntityAnimationPose;
+
 declare class Entities {
     static getEntityList(): Promise<string[]>;
     private static getModelFile;
@@ -829,6 +916,10 @@ declare class Entities {
     /** The dataset's extra draws on top of `main`; their `when` labels are the states `EntityModelOptions.when` can enable. */
     static getPassList(modelKey: BasicAssetKey): Promise<EntityModelPass[]>;
     static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
+    /**
+     * Vanilla's keyframe animations of a model by name, or undefined when the model or the selected version has none.
+     */
+    static getAnimations(modelKey: BasicAssetKey): Promise<Maybe<Record<string, EntityAnimation>>>;
     static resolveTexture(modelKey: BasicAssetKey): Promise<Maybe<AssetKey>>;
     /** @deprecated Use getEntityList(); block entities share the entity dataset. */
     static getBlockList(): Promise<string[]>;
@@ -1048,6 +1139,41 @@ interface SkinObjectOptions extends SceneObjectOptions {
     legacy?: boolean;
 }
 
+interface EntityAnimationOptions {
+    /** Overrides the animation's own `loop` flag. */
+    loop?: boolean;
+    /** Playback rate applied to advanced time; defaults to 1. */
+    speed?: number;
+    /** Start time in seconds; defaults to 0. */
+    time?: number;
+}
+/**
+ * Poses part groups from a keyframe animation the way vanilla does: every update restores the
+ * default pose of each animated part, then adds the sampled offsets to its position, Euler angles and scale.
+ * It owns no timer; the owner advances it.
+ */
+declare class EntityAnimationPlayer {
+    private parts;
+    private _animation?;
+    private _time;
+    private loop;
+    private speed;
+    get animation(): EntityAnimation | undefined;
+    get time(): number;
+    /**
+     * 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: Object3D[], animation: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Restores the default poses. Returns whether an animation was active. */
+    stop(): boolean;
+    /** Forgets the animation without touching the parts, for parts that no longer exist. */
+    clear(): void;
+    setTime(seconds: number): boolean;
+    advance(deltaSeconds: number): boolean;
+    private apply;
+}
+
 declare class EntityObject extends SceneObject {
     readonly entity: EntityModel;
     readonly isEntityObject: true;
@@ -1059,6 +1185,7 @@ declare class EntityObject extends SceneObject {
     private scrollTicker;
     /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
     age: number;
+    private readonly animationPlayer;
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
@@ -1066,6 +1193,22 @@ declare class EntityObject extends SceneObject {
     private clearScrollMaterials;
     /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
     private updateScroll;
+    /** The animation started by {@link playAnimation}, until {@link stopAnimation} or disposal. */
+    get animation(): Maybe<EntityAnimation>;
+    /** Seconds since the animation started, before looping. */
+    get animationTime(): number;
+    /**
+     * 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: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Stops the animation and restores the default pose. */
+    stopAnimation(): void;
+    /** Poses the object at an explicit time in seconds. Has no effect without an animation. */
+    setAnimationTime(seconds: number): void;
+    /** Advances the animation by a frame delta in seconds, scaled by its speed. Has no effect without an animation. */
+    advanceAnimation(deltaSeconds: number): void;
     getLayerGroup(name: string): Maybe<Object3D>;
     getGroupByName(name: string, layerName?: string): Maybe<Object3D>;
     getMeshByName(name: string, layerName?: string): Maybe<Mesh>;
@@ -1266,12 +1409,24 @@ declare class BlockObject extends SceneObject {
     private _fluidKey?;
     private _fluidSampler?;
     private _fluidModel?;
+    private _entities;
+    private _entityPlacement;
+    private _entityGeneration;
     constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
     removeFromScene(): void;
     private clearModels;
     private removeModels;
+    private removeEntities;
+    /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
+    get blockEntities(): readonly EntityObject[];
+    /**
+     * 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.
+     */
+    private createBlockEntities;
+    private placeEntities;
     get isOccluding(): boolean;
     private getModelMatrix;
     private getModelCullMask;
@@ -1286,6 +1441,7 @@ declare class BlockObject extends SceneObject {
     nextInstance(): InstanceReference<SceneObject>;
     protected mapStateToVariant(state: BlockStateProperties): Promise<BlockStateVariant[]>;
     recreateModels(): Promise<void>;
+    private hasGeometry;
     protected getSingleVariant(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
     protected createAVariant(variants: BlockStateVariant | BlockStateVariant[], instanceInfo: Matrix4[]): Promise<void>;
     protected createVariant(variant: BlockStateVariant): Promise<ModelObject | InstanceReference<ModelObject>>;
@@ -1587,6 +1743,8 @@ declare class Caching {
     static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
     static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
     static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
+    static readonly entityAnimationCache: AsyncLoadingCache<CacheKey, EntityAnimationFile>;
+    static readonly blockEntityIndexCache: AsyncLoadingCache<CacheKey, BlockEntityIndex>;
     private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
@@ -2186,4 +2344,4 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Block, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, type ElementFace, type ElementRotation, Entities, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, type FrameCallback, type FromTo, Geometries, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiTextureLayer, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResponseParser, SKIN_PARTS, SceneExporter, type SceneGLTFExportOptions, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createImage, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, type FrameCallback, type FromTo, Geometries, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiTextureLayer, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, SceneExporter, type SceneGLTFExportOptions, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };

package/dist/node/index.d.ts

@@ -808,6 +808,55 @@ type BlockStateProperties = {
     [key: string]: string;
 };
 
+/** One model drawn by a block-entity renderer. */
+interface BlockEntityPart {
+    model: string;
+    /** Model layer; defaults to "main". */
+    layer?: string;
+    /** Set only when the texture differs from the layer's default. */
+    textureLocation?: string;
+    /** Blockstate multipart syntax: every property must match, and "a|b" matches either value. */
+    when?: Record<string, string>;
+}
+/** Degrees per property value, or degrees per unit of a numeric property. */
+type BlockEntityRotation = {
+    property: string;
+    degrees: Record<string, number>;
+} | {
+    property: string;
+    step: number;
+};
+interface BlockEntityEntry {
+    parts: BlockEntityPart[];
+    rotation?: BlockEntityRotation;
+    /** Offset in model units, applied before the rotation. */
+    translation?: TripleArray;
+}
+/** The dataset's `blocks.json`: block ID to the models its block-entity renderer draws. */
+type BlockEntityIndex = MinecraftAsset & {
+    [block: string]: BlockEntityEntry;
+};
+interface ResolvedBlockEntity {
+    parts: BlockEntityPart[];
+    /** Degrees counter-clockwise seen from above, about the block's vertical centre axis. */
+    rotation: number;
+    translation: TripleArray;
+}
+declare class BlockEntities {
+    /**
+     * 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 getIndex(root?: string): Promise<BlockEntityIndex>;
+    /** The index entry of a block ID such as `minecraft:chest`. */
+    static entry(index: BlockEntityIndex, block: string): Maybe<BlockEntityEntry>;
+    /** Selects the parts and placement for a block ID such as `minecraft:chest`; undefined when nothing is drawn. */
+    static resolve(index: BlockEntityIndex, block: string, state?: BlockStateProperties): Maybe<ResolvedBlockEntity>;
+    /** Placement in block space (0..16 per axis), applied on top of the model's own transform. */
+    static matrix(resolved: ResolvedBlockEntity, matrix?: Matrix4): Matrix4;
+}
+
 declare class BlockStates {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
@@ -822,6 +871,44 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
+/** `entity-models/animations/<namespace>/<model id>.json`: vanilla's keyframe animations of one model. */
+interface EntityAnimationFile extends MinecraftAsset {
+    id: string;
+    animations: Record<string, EntityAnimation>;
+}
+interface EntityAnimation {
+    /** Seconds. */
+    length: number;
+    loop: boolean;
+    /** Part name anywhere in a layer; `root` is the layer's root part. */
+    bones: Record<string, EntityAnimationBone>;
+}
+type EntityAnimationChannel = "position" | "rotation" | "scale";
+/** Keyframes in time order per channel. */
+type EntityAnimationBone = Partial<Record<EntityAnimationChannel, EntityAnimationKeyframe[]>>;
+interface EntityAnimationKeyframe {
+    /** Seconds. */
+    time: number;
+    /** Offset from the default pose: model units, radians, or scale minus one. */
+    value: TripleArray;
+    /** Value to arrive at when it differs from `value`; linear interpolation only. */
+    pre?: TripleArray;
+    /** Applies between the previous keyframe and this one. */
+    interpolation: "linear" | "catmullrom";
+}
+/** Sampled offsets from the default pose, per bone and channel. */
+type EntityAnimationPose = Record<string, Partial<Record<EntityAnimationChannel, TripleArray>>>;
+declare const ENTITY_ANIMATION_CHANNELS: readonly EntityAnimationChannel[];
+/**
+ * Samples one channel like vanilla's `KeyframeAnimation.Entry`: the first value holds before the
+ * first keyframe and the last value after the last one; in between, the later keyframe selects the interpolation.
+ */
+declare function sampleEntityKeyframes(keyframes: readonly EntityAnimationKeyframe[], time: number): TripleArray;
+/** Elapsed seconds within the animation: modulo `length` when looping, as vanilla does. */
+declare function entityAnimationTime(animation: EntityAnimation, time: number, loop?: boolean): number;
+/** Samples every bone and channel of an animation at `time` seconds. */
+declare function sampleEntityAnimation(animation: EntityAnimation, time: number, loop?: boolean): EntityAnimationPose;
+
 declare class Entities {
     static getEntityList(): Promise<string[]>;
     private static getModelFile;
@@ -829,6 +916,10 @@ declare class Entities {
     /** The dataset's extra draws on top of `main`; their `when` labels are the states `EntityModelOptions.when` can enable. */
     static getPassList(modelKey: BasicAssetKey): Promise<EntityModelPass[]>;
     static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
+    /**
+     * Vanilla's keyframe animations of a model by name, or undefined when the model or the selected version has none.
+     */
+    static getAnimations(modelKey: BasicAssetKey): Promise<Maybe<Record<string, EntityAnimation>>>;
     static resolveTexture(modelKey: BasicAssetKey): Promise<Maybe<AssetKey>>;
     /** @deprecated Use getEntityList(); block entities share the entity dataset. */
     static getBlockList(): Promise<string[]>;
@@ -1048,6 +1139,41 @@ interface SkinObjectOptions extends SceneObjectOptions {
     legacy?: boolean;
 }
 
+interface EntityAnimationOptions {
+    /** Overrides the animation's own `loop` flag. */
+    loop?: boolean;
+    /** Playback rate applied to advanced time; defaults to 1. */
+    speed?: number;
+    /** Start time in seconds; defaults to 0. */
+    time?: number;
+}
+/**
+ * Poses part groups from a keyframe animation the way vanilla does: every update restores the
+ * default pose of each animated part, then adds the sampled offsets to its position, Euler angles and scale.
+ * It owns no timer; the owner advances it.
+ */
+declare class EntityAnimationPlayer {
+    private parts;
+    private _animation?;
+    private _time;
+    private loop;
+    private speed;
+    get animation(): EntityAnimation | undefined;
+    get time(): number;
+    /**
+     * 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: Object3D[], animation: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Restores the default poses. Returns whether an animation was active. */
+    stop(): boolean;
+    /** Forgets the animation without touching the parts, for parts that no longer exist. */
+    clear(): void;
+    setTime(seconds: number): boolean;
+    advance(deltaSeconds: number): boolean;
+    private apply;
+}
+
 declare class EntityObject extends SceneObject {
     readonly entity: EntityModel;
     readonly isEntityObject: true;
@@ -1059,6 +1185,7 @@ declare class EntityObject extends SceneObject {
     private scrollTicker;
     /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
     age: number;
+    private readonly animationPlayer;
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
@@ -1066,6 +1193,22 @@ declare class EntityObject extends SceneObject {
     private clearScrollMaterials;
     /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
     private updateScroll;
+    /** The animation started by {@link playAnimation}, until {@link stopAnimation} or disposal. */
+    get animation(): Maybe<EntityAnimation>;
+    /** Seconds since the animation started, before looping. */
+    get animationTime(): number;
+    /**
+     * 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: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Stops the animation and restores the default pose. */
+    stopAnimation(): void;
+    /** Poses the object at an explicit time in seconds. Has no effect without an animation. */
+    setAnimationTime(seconds: number): void;
+    /** Advances the animation by a frame delta in seconds, scaled by its speed. Has no effect without an animation. */
+    advanceAnimation(deltaSeconds: number): void;
     getLayerGroup(name: string): Maybe<Object3D>;
     getGroupByName(name: string, layerName?: string): Maybe<Object3D>;
     getMeshByName(name: string, layerName?: string): Maybe<Mesh>;
@@ -1266,12 +1409,24 @@ declare class BlockObject extends SceneObject {
     private _fluidKey?;
     private _fluidSampler?;
     private _fluidModel?;
+    private _entities;
+    private _entityPlacement;
+    private _entityGeneration;
     constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
     removeFromScene(): void;
     private clearModels;
     private removeModels;
+    private removeEntities;
+    /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
+    get blockEntities(): readonly EntityObject[];
+    /**
+     * 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.
+     */
+    private createBlockEntities;
+    private placeEntities;
     get isOccluding(): boolean;
     private getModelMatrix;
     private getModelCullMask;
@@ -1286,6 +1441,7 @@ declare class BlockObject extends SceneObject {
     nextInstance(): InstanceReference<SceneObject>;
     protected mapStateToVariant(state: BlockStateProperties): Promise<BlockStateVariant[]>;
     recreateModels(): Promise<void>;
+    private hasGeometry;
     protected getSingleVariant(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
     protected createAVariant(variants: BlockStateVariant | BlockStateVariant[], instanceInfo: Matrix4[]): Promise<void>;
     protected createVariant(variant: BlockStateVariant): Promise<ModelObject | InstanceReference<ModelObject>>;
@@ -1587,6 +1743,8 @@ declare class Caching {
     static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
     static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
     static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
+    static readonly entityAnimationCache: AsyncLoadingCache<CacheKey, EntityAnimationFile>;
+    static readonly blockEntityIndexCache: AsyncLoadingCache<CacheKey, BlockEntityIndex>;
     private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
@@ -2186,4 +2344,4 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Block, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, type ElementFace, type ElementRotation, Entities, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, type FrameCallback, type FromTo, Geometries, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiTextureLayer, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResponseParser, SKIN_PARTS, SceneExporter, type SceneGLTFExportOptions, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createImage, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, type FrameCallback, type FromTo, Geometries, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiTextureLayer, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, SceneExporter, type SceneGLTFExportOptions, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };