minerender 2.1.0-alpha.9 → 2.1.0-beta.1

package/dist/browser/index.d.mts

@@ -1,21 +1,22 @@
 import * as three from 'three';
-import { Vector3, PixelFormat, BoxGeometry, Material, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Scene, Object3DEventMap, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
+import { Vector3, PixelFormat, BoxGeometry, Material, ColorRepresentation, MeshBasicMaterial, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Box2, Scene, Object3DEventMap, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, DataTexture, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points, Group } from 'three';
 import * as nodeCanvas from 'canvas';
 import { ImageData as ImageData$1, CanvasRenderingContext2D } from 'canvas';
-import { AxiosResponse, AxiosRequestConfig } from 'axios';
-import { Buffer as Buffer$1 } from 'buffer';
-import { NBT } from 'prismarine-nbt';
+import { Buffer } from 'buffer';
+import { NBT, NBTFormat, Metadata } from 'prismarine-nbt';
 import { ZipReader } from '@zip.js/zip.js';
 import { AsyncLoadingCache, SimpleCache } from '@inventivetalent/loading-cache';
+import { PLYExporterOptions } from 'three/examples/jsm/exporters/PLYExporter.js';
+export { PLYExporterOptions } from 'three/examples/jsm/exporters/PLYExporter.js';
 import Stats from 'stats.js';
 import { EffectComposer } from 'postprocessing';
 
 interface AnimatorFunction {
-    (): void;
+    (): boolean | void;
 }
 
 declare enum Axis {
-    X = "X",
+    X = "x",
     Y = "y",
     Z = "z"
 }
@@ -39,6 +40,7 @@ declare enum CubeFaceIndex {
     NORTH = 5
 }
 declare const CUBE_FACES: CubeFace[];
+declare const CUBE_FACE_OFFSETS: readonly [readonly [1, 0, 0], readonly [-1, 0, 0], readonly [0, 1, 0], readonly [0, -1, 0], readonly [0, 0, 1], readonly [0, 0, -1]];
 
 interface Disposable {
     dispose(): void;
@@ -174,6 +176,7 @@ declare class AssetKey extends BasicAssetKey {
     rootType: "assets" | "data" | string;
     extension: ".json" | ".png" | string;
     root?: string | undefined;
+    readonly isAssetKey: true;
     constructor(namespace: string, path: string, assetType?: AssetType | undefined, type?: string | undefined, rootType?: "assets" | "data" | string, extension?: ".json" | ".png" | string, root?: string | undefined);
     static parse(assetType: AssetType, str: string, origin?: AssetKey): AssetKey;
     toString(): string;
@@ -196,11 +199,98 @@ interface ListAsset extends MinecraftAsset {
     files: string[];
 }
 
+interface EntityLayer {
+    key: BasicAssetKey;
+    texture?: AssetKey;
+    layer: EntityModelLayer;
+    /** How this draw is rendered; defaults to the geometry layer's own mode, then `cutout`. */
+    render?: EntityRenderMode;
+    /** Label of the state colour that multiplies the texture, from the pass that selected this draw. */
+    tint?: string;
+}
+interface EntityModel extends EntityLayer {
+    id: string;
+    /** Root transform from the dataset; see {@link EntityTransformOp}. */
+    transform?: EntityTransformOp[];
+    /**
+     * Selected draws in draw order; the top-level fields describe the first selection.
+     * A key is the geometry layer's name; a further draw of the same geometry (a pass with another texture) is keyed `<layer>#<n>`, from 2.
+     */
+    layers?: Record<string, EntityLayer>;
+}
+interface EntityModelFile extends MinecraftAsset {
+    id: string;
+    transform?: EntityTransformOp[];
+    layers: Record<string, EntityModelLayer>;
+    /** Extra draws vanilla adds on top of `main`, in draw order. */
+    passes?: EntityModelPass[];
+}
+/** Vanilla render type of a draw; see the dataset README for the mode table. */
+type EntityRenderMode = "cutout" | "cutout_cull" | "cutout_z_offset" | "solid" | "translucent" | "translucent_emissive" | "eyes" | "energy_swirl" | "breeze_wind" | "water_mask";
+interface EntityModelPass {
+    /** Geometry layer of the same file; a pass on `main` draws that geometry again. */
+    layer: string;
+    /** Present only when it differs from the layer's own. */
+    textureLocation?: string;
+    /** Present only when it differs from the layer's own. */
+    render?: EntityRenderMode;
+    /** Entity state that enables the draw, e.g. `powered`; without it the pass is always drawn. */
+    when?: string;
+    /** State colour that multiplies the texture, e.g. `wool_color`. */
+    tint?: string;
+}
+/**
+ * One operation vanilla's renderer applies before drawing a model, in call order:
+ * each one is applied on top of the previous, so the last reaches the vertices first.
+ * Translations use model units and rotations use radians, like part poses.
+ */
+type EntityTransformOp = {
+    scale: [number, number, number];
+} | {
+    translate: [number, number, number];
+} | {
+    rotate: [number, number, number];
+};
+interface EntityModelLayer {
+    texture: [number, number];
+    textureLocation?: string;
+    /** Omitted for `cutout`. */
+    render?: EntityRenderMode;
+    root: EntityModelPart;
+}
+interface EntityModelPart {
+    pose: {
+        offset: [number, number, number];
+        rotation: [number, number, number];
+        scale?: [number, number, number];
+    };
+    texture?: [number, number];
+    cubes: EntityModelCube[];
+    children: Record<string, EntityModelPart>;
+}
+interface EntityModelCube {
+    origin: [number, number, number];
+    size: [number, number, number];
+    uv: [number, number];
+    grow?: [number, number, number];
+    mirror?: boolean;
+}
+
 declare class Materials {
-    private static readonly MISSING_TEXTURE_SRC;
     static get MISSING_TEXTURE(): Material;
     static createImage(key: MaterialKey): Material;
     static createBasicCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean): Material;
+    /** Whether vanilla's render type for the mode culls back faces. */
+    static entityModeCulls(mode?: EntityRenderMode): boolean;
+    /** UV offset per tick of entity age for the scrolling modes, as vanilla's texture matrix applies it. */
+    static entityModeScroll(mode?: EntityRenderMode): [number, number] | undefined;
+    /**
+     * Entity material for one of vanilla's render types. Entities are unlit here, so the lit and full-bright modes
+     * differ only in blending and depth state. Culling is not a material property: {@link entityModeCulls} decides
+     * whether the geometry gets inward faces.
+     */
+    static createEntityCanvasMaterial(canvas: HTMLCanvasElement, mode?: EntityRenderMode, tint?: ColorRepresentation): MeshBasicMaterial;
+    static createGuiCanvasMaterial(canvas: HTMLCanvasElement): MeshBasicMaterial;
     static createShadedCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean): Material;
     static getImage(key: MaterialKey): Material;
     static needsUpdate(mat: Material): void;
@@ -246,7 +336,8 @@ declare enum DisplayPosition {
     GUI = "gui",
     HEAD = "head",
     GROUND = "ground",
-    FIXED = "fixed"
+    FIXED = "fixed",
+    ON_SHELF = "on_shelf"
 }
 declare const DISPLAY_POSITIONS: DisplayPosition[];
 
@@ -255,6 +346,46 @@ declare enum GuiLight {
     SIDE = "side"
 }
 
+interface RequestConfig extends RequestInit {
+    url: string;
+    /** Prepended to relative URLs, preserving any path in the base URL. */
+    baseURL?: string;
+    /** Timeout per attempt in milliseconds, including body reading. Defaults to 5000; 0 disables it. */
+    timeout?: number;
+    responseType?: "json" | "arraybuffer";
+}
+interface RequestResponse<T = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    /** Final URL after redirects. */
+    url: string;
+}
+declare class RequestError extends Error {
+    readonly response?: RequestResponse<undefined> | undefined;
+    readonly cause?: unknown;
+    constructor(message: string, response?: RequestResponse<undefined> | undefined, cause?: unknown);
+}
+declare class Requests {
+    private static genericQueue;
+    private static mcAssetRequestQueue;
+    static genericRequest(request: RequestConfig): Promise<RequestResponse>;
+    static mcAssetRequest(request: RequestConfig): Promise<RequestResponse>;
+    static setMcAssetRoot(root: string): void;
+    /** Counts unsettled calls, including retry delays and requests still running after shutdown. */
+    static get queueSizes(): {
+        generic: number;
+        mcAsset: number;
+    };
+    /**
+     * Permanently stops both queues and rejects waiting, retrying, and future requests.
+     * Requests already running can finish. Idle queues hold no timer, so Node can exit without
+     * this cleanup. See {@link shutdown}.
+     */
+    static end(): void;
+}
+
 declare class WrappedImage {
     readonly dta: ExtractableImageData;
     constructor(dta: ExtractableImageData);
@@ -278,7 +409,7 @@ interface ImageInfo {
     width: number;
     height: number;
     type?: string;
-    data: Buffer$1;
+    data: Buffer;
 }
 declare class ImageLoader {
     protected static _createImage(): CompatImage;
@@ -290,7 +421,7 @@ declare class ImageLoader {
     static infoToData(info: ImageInfo): Promise<ImageData>;
     static getData(src: string): Promise<ImageData>;
     static getCanvasData(src: string): Promise<ExtractableImageData>;
-    static processResponse(response: Partial<AxiosResponse>): Promise<ImageInfo>;
+    static processResponse(response: Pick<RequestResponse<ArrayBuffer>, "data" | "url">): Promise<ImageInfo>;
     static loadInfo(src: string): Promise<ImageInfo>;
     static getInfo(src: string): Promise<ImageInfo>;
     static loadWrapped(src: string): Promise<WrappedImage>;
@@ -304,7 +435,7 @@ declare const DEFAULT_ELEMENTS: ModelElement[];
 interface Model extends MinecraftAsset {
     textures?: IModelTextures;
     parent?: string;
-    display?: ModelDisplay;
+    display?: Partial<Record<DisplayPosition, ModelDisplay>>;
     elements?: ModelElement[];
     hierarchy?: string[];
 }
@@ -315,11 +446,41 @@ interface BlockModel extends Model {
 interface ItemModel extends Model {
     textures?: ItemModelTextures;
     gui_light?: GuiLight;
-}
+    special?: SpecialItemRenderer;
+    tints?: ItemTintSource[];
+}
+type ItemTintColor = number | TripleArray;
+type ItemTintSource = {
+    type: "constant" | "minecraft:constant";
+    value: ItemTintColor;
+} | {
+    type: "grass" | "minecraft:grass";
+    temperature: number;
+    downfall: number;
+} | {
+    type: "dye" | "minecraft:dye" | "potion" | "minecraft:potion" | "map_color" | "minecraft:map_color" | "firework" | "minecraft:firework" | "team" | "minecraft:team";
+    default: ItemTintColor;
+} | {
+    type: "custom_model_data" | "minecraft:custom_model_data";
+    index?: number;
+    default: ItemTintColor;
+};
+type SpecialItemRenderer = {
+    type: "chest" | "minecraft:chest";
+    texture: string;
+    openness?: number;
+} | {
+    type: "bed" | "minecraft:bed";
+    texture: string;
+} | {
+    type: "head" | "minecraft:head";
+    kind: string;
+    texture?: string;
+    animation?: number;
+};
 interface TextureAsset extends MinecraftAsset, ImageInfo {
 }
 interface ModelDisplay {
-    position?: DisplayPosition;
     translation?: TripleArray;
     rotation?: TripleArray;
     scale?: TripleArray;
@@ -339,13 +500,7 @@ declare function isDoubleArray(obj: any): obj is DoubleArray;
 declare function isTripleArray(obj: any): obj is TripleArray;
 declare function isQuadArray(obj: any): obj is QuadArray;
 
-/**
- *          down  up
- *  east    north    west    south
- *
- *  bottom-left to top-right
- *  [bl, br, tl, tr]
- */
+/** Vanilla Minecraft cube UVs in Three.js BoxGeometry face and vertex order. */
 declare class MinecraftCubeTexture {
     readonly u: number;
     readonly v: number;
@@ -361,12 +516,33 @@ declare class MinecraftCubeTexture {
     getUvSouth(w: number, h: number, l: number): QuadArray<DoubleArray>;
     getUvNorth(w: number, h: number, l: number): QuadArray<DoubleArray>;
     getFaceUv(face: CubeFace, w: number, h: number, l: number): QuadArray<DoubleArray>;
-    toUvArray(w: number, h: number, l: number): number[];
+    toUvArray(w: number, h: number, l: number, mirror?: boolean): number[];
 }
 
 interface MinecraftTextureMeta extends MinecraftAsset {
-    animation: AnimationMeta;
+    animation?: AnimationMeta;
+    gui?: {
+        scaling?: GuiSpriteScaling;
+    };
 }
+type GuiSpriteScaling = {
+    type: "stretch";
+} | {
+    type: "tile";
+    width: number;
+    height: number;
+} | {
+    type: "nine_slice";
+    width: number;
+    height: number;
+    border: number | {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    stretch_inner?: boolean;
+};
 interface AnimationMeta {
     interpolate: boolean;
     width: number;
@@ -489,6 +665,7 @@ declare class TextureAtlas implements Disposable {
     };
     readonly hasTransparency: boolean;
     ticker?: number;
+    private readonly subscribers;
     constructor(model: Model, image: CanvasImage, sizes: {
         [texture: string]: DoubleArray;
     }, positions: {
@@ -496,6 +673,8 @@ declare class TextureAtlas implements Disposable {
     }, hasAnimation: boolean, animatorFunctions: {
         [p: string]: AnimatorFunction;
     }, hasTransparency: boolean);
+    /** Calls subscribers when an animation frame changes; unused atlases do not tick. */
+    subscribe(callback: () => void): () => void;
     getData(texture: string): ImageData$1;
     dispose(): void;
 }
@@ -514,6 +693,7 @@ declare class UVMapper {
     static setCubeUvs(geometry: BoxGeometry, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray, faces: ModelFaces): void;
     static facesToUvArray(faces: ModelFaces, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray): number[];
     static facesToUv(faces: ModelFaces, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray): Float32BufferAttribute;
+    static lockUvs(geometry: BoxGeometry, faces: ModelFaces, atlas: TextureAtlas, rotation: Euler): void;
     static getAtlas(model: Model): Promise<Maybe<TextureAtlas>>;
     static fillMissingTextureKeys<T>(textures: ModelTextures, target: {
         [k: string]: T;
@@ -540,8 +720,8 @@ declare class MinecraftFaceUV {
  * Idle Node processes can exit without calling this: cache and Ticker timers are unref'd,
  * and idle request queues hold no timer. Pending requests keep their normal timer references.
  *
- * Call this only when finished with MineRender. Waiting and future requests reject; requests
- * already running can finish. Queue shutdown is permanent, and cache expiry timers do not restart.
+ * Call this only when finished with MineRender. Queued, retrying, and future requests reject;
+ * HTTP requests already running can finish. Queue shutdown is permanent, and cache expiry timers do not restart.
  */
 declare function shutdown(): void;
 
@@ -549,46 +729,19 @@ declare class BatchedExecutor {
     readonly interval: number;
     readonly batch: number;
     private readonly queue;
-    private readonly task;
     constructor(interval?: number, batch?: number);
-    submit(task: Task): void;
-    private run;
-    private runNext;
+    submit<T>(task: Task<T>): Promise<T>;
+    stop(): void;
 }
-type Task = () => any | Promise<any>;
+type Task<T = unknown> = () => T | Promise<T>;
 
 declare function prefix(prefix?: string): string;
 
-interface ModelPart {
-    textureWidth: number;
-    textureHeight: number;
-    textureOffsetU: number;
-    textureOffsetV: number;
-    pivotX: number;
-    pivotY: number;
-    pivotZ: number;
-    pitch: number;
-    yaw: number;
-    roll: number;
-    mirror: boolean;
-    cubes: Cube[];
-    children: ModelPart[];
-}
-interface Cube {
-    minX: number;
-    minY: number;
-    minZ: number;
-    maxX: number;
-    maxY: number;
-    maxZ: number;
-}
-
 declare function applyElementRotation(rotation: ElementRotation, geometry: BufferGeometry): void;
-declare function applyModelPartRotation(modelPart: ModelPart, geometry: BufferGeometry): void;
 declare function applyGenericRotation(axis: Axis, rotation: number, obj: Object3D): void;
 declare function addBox3WireframeToObject(box: Box3, obj: Object3D, color?: number, w?: number): void;
 declare function addWireframeToObject(obj: Object3D, color?: number, w?: number): void;
-declare function addWireframeToMesh(geo: BufferGeometry, mesh: Mesh, color?: number, w?: number): void;
+declare function addWireframeToMesh(geo: BufferGeometry, mesh: Mesh, color?: number, w?: number): () => void;
 
 declare function captureException(e: any, ...extra: any[]): void;
 declare function timingStart(marker: string): void;
@@ -613,16 +766,47 @@ declare enum AssetParser {
 declare abstract class AssetSource {
     protected constructor();
     abstract get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
+    /**
+     * Identifies this source's content across sessions for persistent caching. Sources that
+     * cannot tell whether their content changed (an unnamed archive, for example) return
+     * undefined, which keeps their results out of long-lived caches.
+     */
+    get cacheId(): Maybe<string>;
+}
+/** A source failed to load or parse an asset; cause retains the original failure. */
+declare class AssetLoadError extends Error {
+    readonly source: AssetSource;
+    readonly key: AssetKey;
+    readonly path: string;
+    readonly cause: unknown;
+    constructor(source: AssetSource, key: AssetKey, path: string, cause: unknown);
 }
 
 declare class AssetLoader {
     static ROOT: string;
     private static _SOURCES;
+    /** Used when a registered source cannot identify its content, so nothing persists past this session. */
+    private static readonly SESSION_SCOPE;
+    static get version(): string;
+    static setVersion(version: string): void;
+    /**
+     * Scope for persistent cache keys. Empty with only the default vanilla sources, so their
+     * entries stay valid across sessions; otherwise it names every added source (resource packs,
+     * mirrors) so their results never masquerade as vanilla assets after a reload.
+     */
+    static get persistentScope(): string;
+    /** Prefixes a persistent cache key with the current source scope. */
+    static persistentKey(key: string): string;
     static addSource(key: string, source: AssetSource, override?: boolean): void;
     static removeSource(key: string): Maybe<AssetSource>;
     static getAll<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<T[]>;
     /** Returns the first defined result in source-priority order, without merging assets. */
     static get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
+    /** Tries each path within a source before considering lower-priority sources. */
+    static getFirst<T extends MinecraftAsset>(keys: readonly AssetKey[], parser: AssetParser | string): Promise<Maybe<{
+        key: AssetKey;
+        asset: T;
+    }>>;
 }
 
 interface BlockState extends MinecraftAsset {
@@ -637,18 +821,19 @@ interface BlockStateVariant {
     y?: number;
     x?: number;
     uvlock?: boolean;
+    weight?: number;
 }
 interface BlockStateMultipart {
-    when?: MultipartCondition | {
-        OR: MultipartCondition[];
-    };
-    apply?: BlockStateVariant;
-}
-interface MultipartCondition {
-    [key: string]: string;
+    when?: MultipartCondition;
+    apply?: BlockStateVariant | BlockStateVariant[];
 }
+type MultipartCondition = Record<string, string> | {
+    OR: MultipartCondition[];
+} | {
+    AND: MultipartCondition[];
+};
 
-declare const DEFAULT_ROOT = "https://assets.mcasset.cloud/1.17.1";
+declare const DEFAULT_ROOT = "https://assets.mcasset.cloud/1.21.11";
 declare const DEFAULT_NAMESPACE = "minecraft";
 declare class Assets {
     /**
@@ -673,6 +858,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();
@@ -687,25 +921,95 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
-interface EntityModel extends BasicMinecraftAsset {
-    parts?: {
-        [p: string]: ModelPart;
-    };
-}
+/** `entity-models/animations/<namespace>/<model id>.json`: native and sampled vanilla animation clips. */
+interface EntityAnimationFile extends MinecraftAsset {
+    id: string;
+    animations: Record<string, EntityAnimation>;
+}
+interface EntityAnimation {
+    /** Seconds. */
+    length: number;
+    loop: boolean;
+    /** Geometry layer targeted by this clip; defaults to `main`. */
+    layer?: string;
+    /** 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 getBlockEntityModels(): Promise<Maybe<BlockEntityModels>>;
-    static getEntityModels(): Promise<Maybe<EntityModels>>;
-    static getBlockList(): Promise<string[]>;
     static getEntityList(): Promise<string[]>;
-    static getBlock(modelKey: BasicAssetKey, textureKey?: BasicAssetKey): Promise<Maybe<EntityModel>>;
-    static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey): Promise<Maybe<EntityModel>>;
+    private static getModelFile;
+    static getLayerList(modelKey: BasicAssetKey): Promise<string[]>;
+    /** 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>>;
+    /**
+     * Native and sampled vanilla clips by name, or undefined when the model or 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[]>;
+    /** @deprecated Use getEntity(); block entities share the entity dataset. */
+    static getBlock(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
+}
+interface EntityModelOptions {
+    layer?: string;
+    /** Layer names in draw order; an explicit selection draws exactly these layers and no dataset passes. */
+    layers?: string[];
+    /**
+     * Entity states that enable the dataset's conditional passes, e.g. `["powered"]` for a charged creeper.
+     * Without `layer`/`layers`, `main` and every unconditional pass are always drawn.
+     */
+    when?: string[];
+    /** Per-layer texture overrides, keyed like `EntityModel.layers`. The positional texture key applies to the first selected layer. */
+    textures?: Record<string, BasicAssetKey>;
 }
-declare class EntityModels implements MinecraftAsset {
-    [k: string]: any;
+
+interface BitmapGlyph {
+    image?: CompatCanvas;
+    /** Source rectangle in the bitmap sheet, before applying scale. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+    ascent: number;
+    advance: number;
 }
-declare class BlockEntityModels implements MinecraftAsset {
-    [k: string]: any;
+interface BitmapFont {
+    glyphs: Map<string, BitmapGlyph>;
+}
+declare class Fonts {
+    static get(key?: AssetKey | string): Promise<BitmapFont>;
+    private static relatedKey;
+    private static load;
+    private static bitmap;
 }
 
 declare class Models {
@@ -713,15 +1017,40 @@ declare class Models {
     private static get PERSISTENT_CACHE();
     static getItemList(): Promise<string[]>;
     static loadAndMerge(key: AssetKey): Promise<Maybe<Model>>;
+    private static getItemModel;
+    private static defaultItemModel;
     static getRaw(key: AssetKey): Promise<Maybe<Model>>;
     static getMerged(key: AssetKey): Promise<Maybe<Model>>;
     static get(key: AssetKey): Promise<Maybe<Model>>;
     static clearCache(): Promise<void>;
 }
 
+declare class DisplayTransforms {
+    /** Resolve hand fallbacks within one model, before inheriting parent display entries. */
+    static withHandFallbacks(display: Model["display"]): Model["display"];
+    /** Build a display pose for geometry already centered at the model's [8, 8, 8] pivot. */
+    static getMatrix(display: Model["display"], position: DisplayPosition): Matrix4;
+    static apply(geometry: BufferGeometry, matrix: Matrix4): void;
+}
+
+declare class ItemTints {
+    /** Resolves preview colors from item definitions; explicit per-index colors take precedence. */
+    static get(model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
+    private static rgb;
+}
+
+declare class ModelCulling {
+    static toLocalMask(worldMask: number, rotation: Euler): number;
+    static isOpaqueFullCube(atlas: Maybe<TextureAtlas>): boolean;
+}
+
 declare class ModelGenerator {
     static readonly ITEM_LAYERS: string[];
-    static generateItemModel(imageData: ImageData$1, layer: string): ModelElement[];
+    /**
+     * 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: Pick<ImageData$1, "width" | "height" | "data">, layer: string): ModelElement[];
 }
 
 declare class ModelMerger {
@@ -729,16 +1058,44 @@ declare class ModelMerger {
     protected static collectAllParents(model: Model): Promise<Model[]>;
 }
 
+interface SpecialItemPart {
+    model: EntityModel;
+    transform: Matrix4;
+    rotations: Record<string, TripleArray>;
+}
+declare class SpecialItems {
+    /** Resolves the static entity parts drawn by a special item renderer, in model units. */
+    static getParts(special: SpecialItemRenderer, root?: string): Promise<SpecialItemPart[]>;
+    /** An owned material with model-preview shading; its entity texture remains shared. */
+    static createMaterial(source: MeshBasicMaterial, shade: boolean): MeshBasicMaterial;
+}
+
 interface Block {
     type: string;
     properties?: BlockStateProperties;
     nbt?: any;
 }
 
+declare class BlockStateResolver {
+    static defaults(blockState: BlockState): Promise<BlockStateProperties>;
+    static select(blockState: BlockState, state: BlockStateProperties, choose?: (variants: BlockStateVariant | BlockStateVariant[]) => BlockStateVariant): BlockStateVariant[];
+    static matching(blockState: BlockState, state: BlockStateProperties): (BlockStateVariant | BlockStateVariant[])[];
+    static choose(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
+    static rotation(variant: BlockStateVariant): Euler;
+}
+
+declare class BlockTints {
+    /** Resolves block preview colors without biome context; explicit tints take precedence. */
+    static get(key: AssetKey | undefined, state: BlockStateProperties, model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
+}
+
 interface Instanceable {
     nextInstance(): InstanceReference<SceneObject>;
+    removeInstanceAt(index: number): void;
+    isInstanceActive(index: number, reference: InstanceReference<Instanceable>): boolean;
     getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
     setMatrixAt(index: number, matrix: Matrix4): void;
+    setInstanceVisibleAt(index: number, visible: boolean): void;
     setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
     setPositionAt(index: number, position: Vector3): void;
     getPositionAt(index: number, vector?: Vector3): Vector3;
@@ -749,14 +1106,18 @@ interface Instanceable {
 }
 declare function isInstanceable(obj: any): obj is Instanceable;
 
-declare class InstanceReference<T extends Instanceable> implements Transformable {
+declare class InstanceReference<T extends Instanceable> implements Transformable, Disposable {
     readonly instanceable: T;
     readonly index: number;
     readonly isInstanceReference: true;
     constructor(instanceable: T, index: number);
     nextInstance(): InstanceReference<SceneObject>;
+    private get activeInstanceable();
+    removeFromScene(): void;
+    dispose(): void;
     getMatrix(matrix?: Matrix4): Matrix4;
     setMatrix(matrix: Matrix4): void;
+    setVisible(visible: boolean): void;
     setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
     setPosition(position: Vector3): void;
     getPosition(): Vector3;
@@ -779,18 +1140,34 @@ declare class ModelObject extends SceneObject {
     readonly isModelObject: true;
     static readonly DEFAULT_OPTIONS: ModelObjectOptions;
     readonly options: ModelObjectOptions;
-    private atlas?;
+    protected atlas?: TextureAtlas;
+    private atlasMaterial?;
+    private atlasTexture?;
+    private unsubscribeAtlas?;
+    private readonly specialMaterials;
     blockParent: Maybe<BlockObject>;
     private meshesCreated;
     constructor(originalModel: Model, options?: Partial<ModelObjectOptions>);
     init(): Promise<void>;
-    dispose(): void;
     get textureAtlas(): Maybe<TextureAtlas>;
+    get isOpaqueFullCube(): boolean;
     protected loadTextures(): Promise<void>;
     protected createMeshes(force?: boolean): void;
     protected applyTextures(): void;
+    private updateAnimationSubscription;
+    nextInstance(): InstanceReference<SceneObject>;
+    removeInstanceAt(index: number): void;
+    disposeAndRemoveAllChildren(): void;
 }
 interface ModelObjectOptions extends SceneObjectOptions {
+    /** Minecraft display pose applied around the model center, before scene transforms. */
+    displayPosition?: DisplayPosition;
+    /** Quarter-turn block rotation in radians to compensate when locking UVs. */
+    uvLockRotation?: TripleArray;
+    /** sRGB 0xRRGGBB colors by face tint index; omitted indices stay white. */
+    tints?: Record<number, number>;
+    /** Hidden neighbor directions in CUBE_FACES order, before the model's block rotation. */
+    cullMask?: number;
 }
 declare function isModelObject(obj: any): obj is ModelObject;
 
@@ -823,24 +1200,71 @@ declare enum SkinPart {
 }
 declare const SKIN_PARTS: SkinPart[];
 
+type CapeLayout = "minecraft" | "optifine" | "labymod";
+declare const capeTextureSizes: Record<CapeLayout, DoubleArray>;
+
+/** A player model facing +Z. Left and right parts are the player's own: left is +X, right is -X. */
 declare class SkinObject extends SceneObject {
     readonly options: SkinObjectOptions;
     private slim;
-    private legacy;
+    private detectedSlim;
     private skinTextureSrc?;
-    private skinTextureWidth;
-    private skinTextureHeight;
-    private capeTextureSrc?;
+    private skinMaterial?;
+    private skinLoad;
+    private capeLoad;
     constructor(options?: DeepPartial<SkinObjectOptions>);
     init(): Promise<void>;
     protected removeMeshes(): void;
     protected createMeshes(): void;
-    setSkinTexture(src: string): void;
-    setSlim(slim: boolean): void;
-    setLegacy(legacy: boolean): void;
+    setSkinTexture(src: string): Promise<void>;
+    /** Load a cape texture in the selected layout, or pass undefined to remove the cape. */
+    setCapeTexture(src?: string, layout?: CapeLayout): Promise<void>;
+    /** Select the arm model, or pass undefined to use texture detection. */
+    setSlim(slim?: boolean): void;
+    private updateSlim;
+    /** Select the texture layout, or pass undefined to detect it from image dimensions. */
+    setLegacy(legacy?: boolean): Promise<void>;
+    dispose(): void;
     protected getBoxGeometry(part: SkinPart): BoxGeometry;
 }
 interface SkinObjectOptions extends SceneObjectOptions {
+    slim?: boolean;
+    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 matching named parts. Supplied baked poses are the baseline for offsets;
+     * without them, the current pose is used. Stopping restores the pose from before playback.
+     */
+    play(layers: Object3D[], animation: EntityAnimation, options?: EntityAnimationOptions, poses?: ReadonlyMap<Object3D, EntityModelPart["pose"]>): void;
+    /** Restores the poses from before playback. 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 {
@@ -848,20 +1272,151 @@ declare class EntityObject extends SceneObject {
     readonly isEntityObject: true;
     static readonly DEFAULT_OPTIONS: EntityObjectOptions;
     readonly options: EntityObjectOptions;
-    private imageData?;
     private meshesCreated;
+    private readonly geometries;
+    private readonly disposeWireframes;
+    /** Scrolling materials are owned: their texture offset follows this entity's age. */
+    private readonly scrollMaterials;
+    private scrollTicker;
+    /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
+    age: number;
+    private readonly animationPlayers;
+    private readonly partPoses;
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
-    private get textureKey();
-    protected loadTextures(): Promise<void>;
+    disposeAndRemoveAllChildren(): void;
+    private clearScrollMaterials;
+    private updateScrollSubscription;
+    /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
+    private updateScroll;
+    /** The first active clip, until playback is stopped or the object is disposed. */
+    get animation(): Maybe<EntityAnimation>;
+    /** Clips playing together, each targeting a separate geometry layer. */
+    get activeAnimations(): readonly EntityAnimation[];
+    /** Seconds since the animation started, before looping. */
+    get animationTime(): number;
+    /**
+     * Plays a clip from {@link Entities.getAnimations}, replacing all active clips.
+     * Offsets apply to the baked pose in the clip's layer (`main` by default), including repeated draws of that layer.
+     * The object owns no clock: call {@link advanceAnimation} per frame, or {@link setAnimationTime}.
+     */
+    playAnimation(animation: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Plays one clip per selected geometry layer, with a shared clock and no blending between clips. */
+    playAnimations(animations: readonly EntityAnimation[], options?: EntityAnimationOptions): void;
+    /** Stops all clips and restores the poses from before playback. */
+    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>;
+    private get entityLayers();
+    private getTextureKey;
+    protected loadTextures(layer?: EntityLayer): Promise<Maybe<ExtractableImageData>>;
     protected createMeshes(force?: boolean): void;
+    private createPart;
     protected applyTextures(): Promise<void>;
 }
 interface EntityObjectOptions extends SceneObjectOptions {
+    /**
+     * `true` applies only vanilla's entity flip, scale (-1, -1, 1); `false` keeps raw model space.
+     * By default the model's dataset transform is used, or the flip for models without one.
+     */
+    flip?: boolean;
+    /** Colours for the dataset's tint labels, e.g. `{ wool_color: 0xf9801d }`; a pass whose label is absent stays untinted. */
+    tints?: Record<string, ColorRepresentation>;
 }
 declare function isEntityObject(obj: any): obj is EntityObject;
 
+interface GuiTextStyle {
+    /** sRGB 0xRRGGBB; defaults to white. */
+    color?: number;
+    bold?: boolean;
+    italic?: boolean;
+}
+interface GuiTextRun extends GuiTextStyle {
+    text: string;
+}
+/** Literal text, or styled runs. Newlines are preserved. */
+type GuiText = string | readonly GuiTextRun[];
+interface GuiTextOptions extends GuiTextStyle {
+    /** Font resource ID; defaults to minecraft:default. */
+    font?: AssetKey | string;
+    /** Draws a one-pixel shadow; defaults to true. */
+    shadow?: boolean;
+    /** Wrap width in GUI pixels. Long words break at glyph boundaries. */
+    maxWidth?: number;
+    /** Distance between line origins; defaults to 9 GUI pixels. */
+    lineHeight?: number;
+}
+interface PositionedGuiGlyph {
+    character: string;
+    glyph?: BitmapGlyph;
+    x: number;
+    y: number;
+    advance: number;
+    style: Required<GuiTextStyle>;
+}
+interface GuiTextLayout {
+    glyphs: PositionedGuiGlyph[];
+    lineWidths: number[];
+    width: number;
+    height: number;
+}
+/** Measures and wraps text using the same glyph advances used for rendering. */
+declare function layoutGuiText(text: GuiText, options?: GuiTextOptions): Promise<GuiTextLayout>;
+/** Creates glyph batches in painter order. Unsupported characters use an outlined missing glyph. */
+declare function createGuiTextGeometry(layout: GuiTextLayout, shadow?: boolean): {
+    image?: CompatCanvas;
+    geometry: BufferGeometry;
+}[];
+
+/** GUI layers use pixel coordinates. Later layers draw above earlier layers. */
+type GuiLayer = GuiTextureLayer | GuiItemLayer | GuiTextLayer;
+interface GuiLayerLayout {
+    name?: string;
+    /** Top-left position; x grows right and y grows down. Defaults to [0, 0]. */
+    position?: [number, number];
+    /** Output size; defaults to native texture/text dimensions, and [16, 16] for items. */
+    size?: [number, number];
+}
+interface GuiTextureLayer extends GuiLayerLayout {
+    texture: AssetKey | string;
+    /** Source-image pixels: [x, y, width, height], measured from the top left. Crops ignore sprite scaling. */
+    crop?: [number, number, number, number];
+}
+interface GuiItemLayer extends GuiLayerLayout {
+    /** Model key, such as minecraft:item/stone; uses the model's GUI display pose. */
+    item: AssetKey | string;
+    /** sRGB 0xRRGGBB colors by face tint index; omitted indices stay white. */
+    tints?: Record<number, number>;
+}
+interface GuiTextLayer extends GuiLayerLayout, GuiTextOptions {
+    text: GuiText;
+}
+
+declare class GuiObject extends SceneObject {
+    readonly textureLayers: readonly GuiLayer[];
+    readonly isGuiObject: true;
+    /** Local bounds in GUI pixels, with y growing down from the origin. */
+    readonly bounds: Box2;
+    private readonly geometries;
+    private readonly ownedMaterials;
+    private readonly textMaterials;
+    private initialized;
+    constructor(textureLayers: readonly GuiLayer[], options?: Partial<GuiObjectOptions>);
+    init(): Promise<void>;
+    private createItem;
+    private loadMaterial;
+    disposeAndRemoveAllChildren(): void;
+}
+interface GuiObjectOptions extends SceneObjectOptions {
+}
+declare function isGuiObject(obj: any): obj is GuiObject;
+
 declare class MineRenderScene extends Scene {
     readonly isMineRenderScene: true;
     static readonly DEFAULT_OPTIONS: MineRenderSceneOptions;
@@ -881,6 +1436,7 @@ declare class MineRenderScene extends Scene {
     addBlock(blockState: BlockState, options?: Partial<BlockObjectOptions>, parent?: Object3D): Promise<BlockObject | InstanceReference<BlockObject>>;
     addSkin(skin?: string, options?: Partial<SkinObjectOptions>, parent?: Object3D): Promise<SkinObject>;
     addEntity(entity: EntityModel, options?: Partial<EntityObjectOptions>, parent?: Object3D): Promise<EntityObject | InstanceReference<EntityObject>>;
+    addGui(layers: readonly GuiLayer[], options?: Partial<GuiObjectOptions>, parent?: Object3D): Promise<GuiObject>;
 }
 interface MineRenderSceneOptions {
 }
@@ -896,6 +1452,10 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     private materialCallbacks;
     protected _isInstanced: boolean;
     _instanceCounter: number;
+    protected instanceMesh?: InstancedMesh;
+    private readonly instanceReferences;
+    private readonly freeInstanceIndices;
+    private readonly hiddenInstanceMatrices;
     constructor(options?: Partial<SceneObjectOptions>);
     set scene(scene: MineRenderScene);
     get scene(): MineRenderScene;
@@ -935,8 +1495,15 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     get instanceCounter(): number;
     protected constructInstanceReference(i: number): InstanceReference<SceneObject>;
     nextInstance(): InstanceReference<SceneObject>;
+    /** Returns the live reference for a raycast hit on this object's instance mesh. */
+    getInstanceReference(mesh: Object3D, index: number): Maybe<InstanceReference<SceneObject>>;
+    isInstanceActive(index: number, reference: InstanceReference<Instanceable>): boolean;
+    removeInstanceAt(index: number): void;
+    private growInstances;
+    protected activeInstanceIndices(): Iterable<number>;
     getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
     setMatrixAt(index: number, matrix: Matrix4): void;
+    setInstanceVisibleAt(index: number, visible: boolean): void;
     setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
     setPositionAt(index: number, position: Vector3): void;
     getPositionAt(index: number, vector?: Vector3): Vector3;
@@ -958,6 +1525,23 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
 }
 declare function isSceneObject(obj: any): obj is SceneObject;
 
+type FluidKind = "water" | "lava";
+interface BlockFluidState {
+    kind: FluidKind;
+    level: number;
+    renderModel: boolean;
+}
+declare function getBlockFluidState(key?: AssetKey, state?: BlockStateProperties): BlockFluidState | undefined;
+declare function getFluidKind(key?: AssetKey, state?: BlockStateProperties): FluidKind | undefined;
+interface FluidSample {
+    fluid?: FluidKind;
+    level?: number;
+    solid?: boolean;
+}
+type FluidSampler = (x: number, y: number, z: number) => FluidSample;
+/** Builds centered fluid faces with material groups 0 (still) and 1 (flowing). */
+declare function createFluidGeometry(kind: FluidKind, sample: FluidSampler): BufferGeometry;
+
 declare class BlockObject extends SceneObject {
     readonly blockState: BlockState;
     readonly isBlockObject: true;
@@ -971,16 +1555,45 @@ declare class BlockObject extends SceneObject {
     private _instanceModel;
     private _variants;
     private _models;
+    private _cullMask;
+    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[];
+    /** Sets visibility for this block's model instances and block entities. */
+    setVisible(visible: boolean): void;
+    /**
+     * 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;
+    setCullMask(worldMask: number): Promise<void>;
     get state(): {
         [key: string]: string;
     };
+    get fluidKind(): FluidKind | undefined;
+    get fluidLevel(): number;
+    /** Refreshes fluid surfaces from relative neighbors; standalone previews use air around the block. */
+    updateFluid(sample?: FluidSampler): Promise<void>;
     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>>;
@@ -996,26 +1609,54 @@ declare class BlockObject extends SceneObject {
 }
 interface BlockObjectOptions extends ModelObjectOptions {
     applyDefaultState: boolean;
+    /** Properties applied before model creation, overriding defaults when applyDefaultState is enabled. */
+    initialState?: BlockStateProperties;
 }
 declare function isBlockObject(obj: any): obj is BlockObject;
 
+/** Saved fluid levels and solid neighbors determine the geometry shared by an instance pool. */
+declare function sampleFluid(kind: FluidKind, sample: FluidSampler): {
+    key: string;
+    sample: FluidSampler;
+};
+declare class FluidModelObject extends ModelObject {
+    readonly kind: FluidKind;
+    private readonly sample;
+    private geometry?;
+    constructor(kind: FluidKind, sample: FluidSampler, origin?: AssetKey, options?: Partial<ModelObjectOptions>);
+    protected createMeshes(): void;
+    protected applyTextures(): void;
+    disposeAndRemoveAllChildren(): void;
+}
+
 interface MultiBlockStructure {
     readonly size: TripleArray;
     readonly blocks: MultiBlockBlock[];
+    readonly dataVersion?: number;
+    readonly entities?: MultiBlockEntity[];
+}
+interface MultiBlockEntity {
+    position: TripleArray;
+    blockPosition?: TripleArray;
+    nbt: unknown;
 }
 interface MultiBlockBlock extends Block {
     position: TripleArray;
 }
 
 declare class SchematicParser {
-    static parse(): Promise<MultiBlockStructure>;
+    /**
+     * Parses a legacy schematic using custom mappings before the bundled defaults.
+     * Keys are `id:metadata`; values are block states such as `minecraft:oak_log[axis=x]`.
+     */
+    static parse(nbt: NBT, customMappings?: Readonly<Record<string, string>>): Promise<MultiBlockStructure>;
 }
 
 declare class StructureParser {
     static parse(_nbt: NBT, paletteIndex?: number): Promise<MultiBlockStructure>;
 }
 interface StructureNBT {
-    DataVersion: {
+    DataVersion?: {
         type: "int";
         value: number;
     };
@@ -1027,7 +1668,13 @@ interface StructureNBT {
         };
     };
     palette?: Palette;
-    palettes?: Palette[];
+    palettes?: {
+        type: "list";
+        value: {
+            type: "list";
+            value: Palette["value"][];
+        };
+    };
     blocks: {
         type: "list";
         value: {
@@ -1035,7 +1682,32 @@ interface StructureNBT {
             value: BlockEntry[];
         };
     };
-    entities: {};
+    entities?: {
+        type: "list";
+        value: {
+            type: "compound";
+            value: {
+                pos: {
+                    type: "list";
+                    value: {
+                        type: "double";
+                        value: TripleArray;
+                    };
+                };
+                blockPos: {
+                    type: "list";
+                    value: {
+                        type: "int";
+                        value: TripleArray;
+                    };
+                };
+                nbt: {
+                    type: "compound";
+                    value: any;
+                };
+            }[];
+        };
+    };
 }
 interface Palette {
     type: "list";
@@ -1079,14 +1751,17 @@ interface BlockEntry {
 }
 
 declare class NBTHelper {
-    static fromBuffer(buffer: Buffer): Promise<NBTAsset>;
+    static fromBuffer(data: Uint8Array | ArrayBuffer, format?: NBTFormat): Promise<NBTAsset>;
 }
 interface NBTAsset extends MinecraftAsset, NBT {
+    format?: NBTFormat;
+    metadata?: Metadata;
+    compression?: "gzip" | "none";
 }
 
 interface ResponseParser<T extends MinecraftAsset> {
-    config(request: AxiosRequestConfig): any;
-    parse(response: AxiosResponse): Maybe<T> | Promise<Maybe<T>>;
+    config(request: RequestConfig): any;
+    parse(response: RequestResponse): Maybe<T> | Promise<Maybe<T>>;
 }
 
 declare class HostedAssetSource extends AssetSource {
@@ -1105,6 +1780,7 @@ declare class HostedAssetSource extends AssetSource {
     private readonly _options;
     constructor(root: string, options?: Partial<HostedAssetSourceOptions>);
     get root(): string;
+    get cacheId(): string;
     get options(): HostedAssetSourceOptions;
     get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser): Promise<Maybe<T>>;
 }
@@ -1119,6 +1795,8 @@ interface ArchiveEntry {
 }
 
 interface ArchiveProxy {
+    /** Identifies the archive's content across sessions; undefined when it cannot be identified. */
+    readonly id?: string;
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
@@ -1126,6 +1804,7 @@ declare class ArchiveAssetSource extends AssetSource implements ArchiveProxy {
     readonly _archiveProxy: ArchiveProxy;
     constructor(archiveProxy: ArchiveProxy);
     static blob(blob: Blob): ArchiveAssetSource;
+    get cacheId(): Maybe<string>;
     getEntries(): Promise<ArchiveEntry[]>;
     getEntry(path: string): Promise<Maybe<ArchiveEntry>>;
     get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
@@ -1136,7 +1815,8 @@ declare class ArchiveAssetSource extends AssetSource implements ArchiveProxy {
 declare class BrowserArchiveProxy implements ArchiveProxy {
     readonly _blob: Blob;
     readonly _reader: ZipReader<Blob>;
-    constructor(blob: Blob);
+    readonly id?: string;
+    constructor(blob: Blob, id?: string);
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
@@ -1216,7 +1896,12 @@ declare class Caching {
     static readonly blockStateCache: AsyncLoadingCache<CacheKey, BlockState>;
     static readonly listAssetCache: AsyncLoadingCache<CacheKey, ListAsset>;
     static readonly defaultBlockStatesCache: AsyncLoadingCache<CacheKey, DefaultBlockStates>;
-    static readonly entityModelsCache: AsyncLoadingCache<CacheKey, EntityModels>;
+    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>;
+    static readonly fontCache: AsyncLoadingCache<CacheKey, BitmapFont>;
     private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
@@ -1231,16 +1916,76 @@ declare class Caching {
     static get cacheSizes(): {};
 }
 
+/** Copies the nontransparent bounds without resizing the source; empty images become one transparent pixel. */
+declare function trimCanvas(source: CompatCanvas): CompatCanvas;
+
 declare class MineRenderError extends Error {
     constructor(msg: any);
     get name(): string;
 }
 
-declare class GuiObject extends SceneObject {
+interface SceneGLTFExportOptions {
+    /** Returns a GLB ArrayBuffer instead of a glTF object. */
+    binary?: boolean;
+    /** Maximum width and height of each exported texture, in pixels. */
+    maxTextureSize?: number;
 }
-interface GuiObjectOptions extends SceneObjectOptions {
+/** Exports the visible meshes at their current poses without changing the source scene. */
+declare class SceneExporter {
+    /** Returns OBJ geometry with normals and UVs; material files and textures are not included. */
+    static toObj(root: Object3D): string;
+    /** Returns PLY geometry with vertex colors and UVs; texture images are not included. */
+    static toPLY(root: Object3D, options?: PLYExporterOptions): string | ArrayBuffer;
+    /**
+     * Exports a static glTF/GLB snapshot in a browser. Atlas textures and vertex tints are retained;
+     * MineRender's custom directional lighting is not baked into the exported materials.
+     */
+    static toGLTF(root: Object3D, options?: SceneGLTFExportOptions): Promise<Record<string, any> | ArrayBuffer>;
+}
+
+declare class GuiHelper {
+    /** Sizes a tooltip around supplied text; the first entry is its title. */
+    static tooltip(lines: readonly GuiText[], options?: GuiTooltipOptions): Promise<GuiLayer[]>;
+    static inventorySlot(slot: number | [number, number], origin?: [number, number], offset?: [number, number], rowSize?: number): [number, number];
+    /** Creates crafting-table layers for ingredients and the result; stack counts are not drawn. */
+    static recipe(recipe: GuiRecipe, options?: GuiRecipeOptions): GuiLayer[];
+}
+interface GuiTooltipOptions extends GuiTextOptions {
+    /** Top-left text position, inside the tooltip's padding. */
+    position?: [number, number];
+    /** Extra space after the title, in pixels. Defaults to 2. */
+    titleGap?: number;
+}
+type GuiRecipeIngredientValue = string | {
+    item: string;
+} | {
+    tag: string;
+};
+type GuiRecipeIngredient = GuiRecipeIngredientValue | readonly GuiRecipeIngredientValue[];
+type GuiRecipe = ({
+    type: "minecraft:crafting_shaped" | "crafting_shaped";
+    pattern: readonly string[];
+    key: Readonly<Record<string, GuiRecipeIngredient>>;
+} | {
+    type: "minecraft:crafting_shapeless" | "crafting_shapeless";
+    ingredients: readonly GuiRecipeIngredient[];
+}) & {
+    result: {
+        id: string;
+        count?: number;
+    } | {
+        item: string;
+        count?: number;
+    };
+};
+interface GuiRecipeOptions {
+    /** Selects a concrete item ID or model AssetKey for a tag or alternatives array. */
+    resolveIngredient?: (ingredient: GuiRecipeIngredient) => string | AssetKey;
 }
 
+/** Builds one centered mesh; explicit source-pixel crops always stretch. */
+declare function createGuiTextureGeometry(width: number, height: number, imageWidth: number, imageHeight: number, crop?: [number, number, number, number], scaling?: GuiSpriteScaling): BufferGeometry;
+
 declare class OrbitControls {
     constructor(object: Camera, domElement?: HTMLElement);
 
@@ -1333,7 +2078,10 @@ declare class Renderer implements Disposable {
     protected _frameInterval?: number;
     protected _resizeListener?: () => void;
     private _nextFrameTime?;
+    private _running;
+    private _inAnimationLoop;
     private _disposed;
+    private readonly _frameCallbacks;
     private readonly _debugHelpers;
     private readonly _eventDispatchers;
     private readonly _changeListener;
@@ -1354,6 +2102,12 @@ declare class Renderer implements Disposable {
     resize(width: number, height: number): void;
     get dirty(): boolean;
     set dirty(dirty: boolean);
+    /**
+     * 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: FrameCallback): () => void;
     start(): void;
     stop(): void;
     /**
@@ -1363,7 +2117,16 @@ declare class Renderer implements Disposable {
      */
     dispose(): void;
     private animate;
-    toImage(): string;
+    private drawFrame;
+    /**
+     * Renders a fresh frame and returns an image data URL, including while the animation loop is stopped.
+     * Trimming removes transparent borders; an empty image becomes one transparent pixel.
+     * MIME type support and lossy quality (0–1) follow the canvas encoder.
+     */
+    toImage(trim?: boolean, mime?: string, quality?: number): string;
+    toObj(): string;
+    toPLY(options?: PLYExporterOptions): string | ArrayBuffer;
+    toGLTF(options?: SceneGLTFExportOptions): Promise<Record<string, any> | ArrayBuffer>;
     protected get attachedToBody(): boolean;
     protected get viewWidth(): number;
     protected get viewHeight(): number;
@@ -1374,6 +2137,13 @@ declare class Renderer implements Disposable {
     /** Renderer-owned controls, or undefined when disabled at construction or after disposal. */
     get controls(): Maybe<OrbitControls>;
 }
+interface RendererFrame {
+    /** Animation-loop timestamp in seconds, relative to the browser's performance time origin. */
+    readonly time: number;
+    /** Seconds since this callback's previous update; zero on its first update after subscribing or starting. */
+    readonly delta: number;
+}
+type FrameCallback = (frame: RendererFrame) => void;
 interface RendererOptions {
     camera: CameraOptions;
     render: RenderOptions;
@@ -1401,6 +2171,8 @@ interface CameraOptions {
 interface RenderOptions {
     /** Maximum draw rate (60 by default); zero or a negative value disables the limit. */
     fpsLimit: number;
+    /** Drawing-buffer pixels per CSS pixel (default 1); also scales toImage() output. */
+    pixelRatio?: number;
     stats: boolean;
     antialias: boolean;
     shade: boolean;
@@ -1425,17 +2197,21 @@ declare class SceneInspector {
     protected readonly raycaster: Raycaster;
     private readonly mouse;
     private selectedObject?;
+    private pointer?;
+    private readonly listeners;
     constructor(renderer: Renderer);
     protected init(): void;
-    findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry<three.NormalBufferAttributes>, three.Material | three.Material[], three.Object3DEventMap>[];
-    onClick(event: any): void;
+    dispose(): void;
+    findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry<three.NormalBufferAttributes, three.BufferGeometryEventMap>, three.Material<three.MaterialEventMap> | three.Material<three.MaterialEventMap>[], three.Object3DEventMap>[];
+    onClick(event: MouseEvent): void;
     appendTo(el: HTMLElement): void;
     protected handleRaycasterObjects(intersections: Intersection[]): void;
-    selectObject(targetObject: Object3D, targetIntersection?: Intersection): void;
-    protected redraw(targetObject: Object3D, targetIntersection?: Intersection): void;
-    protected addControls(object: Object3D, intersection?: Intersection): void;
+    private getIntersectionInstance;
+    selectObject(targetObject: Object3D, targetIntersection?: Intersection, instance?: Maybe<InstanceReference<SceneObject>>): void;
+    protected redraw(targetObject: Object3D, targetIntersection?: Intersection, instance?: InstanceReference<SceneObject>): void;
+    protected addControls(object: Object3D, intersection?: Intersection, instance?: InstanceReference<SceneObject>): void;
     protected addInfoLine(name: string, id: string, value: any): HTMLElement;
-    protected addObjectControls(target: Object3D, intersection: Maybe<Intersection>, container: HTMLElement): void;
+    protected addObjectControls(target: Object3D, intersection: Maybe<Intersection>, container: HTMLElement, instance?: InstanceReference<SceneObject>): void;
     protected buttonControl(name: string, id: string, click: () => void): HTMLElement;
     protected selectControl(name: string, id: string, options: string[], change: (v: string) => void): HTMLElement;
     protected toggleControl(name: string, id: string, val: boolean, change: (v: boolean) => void): HTMLElement;
@@ -1443,13 +2219,15 @@ declare class SceneInspector {
     protected separator(name?: string): HTMLElement;
 }
 
-declare class SceneStatsDisplay {
+declare class SceneStatsDisplay implements Disposable {
     readonly renderer: Renderer;
     readonly statsContainer: HTMLDivElement;
     private readonly lines;
+    private interval?;
     constructor(renderer: Renderer);
     protected init(): void;
     appendTo(el: HTMLElement): void;
+    dispose(): void;
     add(line?: StatLine): void;
 }
 declare class StatLine {
@@ -1464,35 +2242,33 @@ declare class StatLine {
     update(): void;
 }
 
-declare class Requests {
-    private static axiosInstance;
-    private static mcAssetInstance;
-    private static genericQueue;
-    private static mcAssetRequestQueue;
-    static genericRequest(request: AxiosRequestConfig): Promise<AxiosResponse>;
-    static mcAssetRequest(request: AxiosRequestConfig): Promise<AxiosResponse>;
-    private static shouldRetry;
-    static setMcAssetRoot(root: string): void;
-    static get queueSizes(): {
-        generic: number;
-        mcAsset: number;
-    };
-    /**
-     * Permanently stops both queues and rejects waiting and future requests.
-     * Requests already running can finish. Idle queues hold no timer, so Node can exit without
-     * this cleanup. See {@link shutdown}.
-     */
-    static end(): void;
-}
-
 type SkinGeometries = Record<SkinPart, TripleArray>;
 declare const classicSkinGeometries: SkinGeometries;
 declare const slimSkinGeometries: SkinGeometries;
 
+declare class SkinImage {
+    static getData(src: string): Promise<ImageData>;
+    private static decodePng;
+}
+
 type SkinTextureCoordinates = Record<SkinPart, ModelFaces>;
 declare const classicSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 declare const slimSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 
+interface SkinTexture {
+    material: MeshBasicMaterial;
+    slim: boolean;
+    legacy: boolean;
+}
+declare class SkinTextures {
+    static get(src: string, legacy?: boolean): Promise<SkinTexture>;
+    static getCape(src: string, layout?: CapeLayout): Promise<MeshBasicMaterial>;
+    private static createMaterial;
+    private static isSlim;
+    private static normalizeLegacy;
+    private static makeBaseOpaque;
+}
+
 declare class Skins {
     static fromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
     static fromUuid(uuid: string): Promise<Maybe<string>>;
@@ -1501,8 +2277,11 @@ declare class Skins {
     static capeFromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
     static capeFromUuid(uuid: string): Promise<Maybe<string>>;
     static capeFromUsername(username: string): Promise<Maybe<string>>;
-    static capeFromCapesDev(uuid: string, capeType?: string): Promise<Maybe<string>>;
+    /** Returns a full static cape texture for a username or UUID. */
+    static capeFromCapesDev(player: string, capeType?: string): Promise<Maybe<string>>;
     private static usernameToUuid;
+    private static usernameToUuidMcProxy;
+    /** @deprecated **/
     private static usernameToUuidSkinProxy;
     private static usernameToUuidMineTools;
     private static getProfileFromMinetools;
@@ -1512,8 +2291,17 @@ declare class Skins {
     private static getCrafatarCapeUrl;
     private static getMcHeadsSkinUrl;
     private static getMineSkinPlayerSkinUrl;
+    /** @deprecated **/
     private static getSkinProxySkinUrl;
+    /** @deprecated **/
     private static getSkinProxyCapeUrl;
+    private static getMcProxySkinUrl;
+    private static getMcProxyCapeUrl;
+}
+
+declare class Colormaps {
+    /** Samples the selected resource pack's grass colormap using Minecraft's climate coordinates. */
+    static grassColor(origin?: AssetKey, temperature?: number, downfall?: number): Promise<number>;
 }
 
 declare class TextureLoader {
@@ -1526,6 +2314,8 @@ declare class TextureLoader {
 }
 
 declare class Textures {
+    /** Creates the shared checkerboard from pixels without fetching or decoding an image. */
+    static getMissing(): DataTexture;
     static initTextureProps<T extends Texture>(texture: T): T;
     static createImage(key: TextureKey): Texture;
     static createAsset(key: AssetKey): Texture;
@@ -1541,61 +2331,165 @@ declare function mergeVertices(geometry: BufferGeometry, tolerance?: number): Bu
 declare function toTrianglesDrawMode(geometry: BufferGeometry, drawMode: TrianglesDrawModes): BufferGeometry;
 declare function computeMorphedAttributes(object: Mesh | Line | Points): object;
 
-interface BlockInfo {
-    block: Block;
-    object: BlockObject;
+declare class ChunkData {
+    private readonly indices;
+    private readonly palette;
+    private readonly paletteIds;
+    private readonly freeIds;
+    private readonly nbt;
+    get(index: number): Maybe<Block>;
+    snapshot(index: number): Maybe<() => Block>;
+    set(index: number, block?: Block): void;
+    clear(): void;
+    static isAir(block: Maybe<Block>): boolean;
+    private static copyBlock;
+    private static validateIndex;
+}
+
+type RegionInput = Uint8Array | ArrayBuffer;
+interface AnvilRegion {
+    chunks: AnvilChunk[];
+}
+interface AnvilChunk {
+    x: number;
+    z: number;
+    dataVersion?: number;
+    sections: {
+        y: number;
+        data: ChunkData;
+    }[];
+    entities?: MultiBlockEntity[];
+}
+declare class AnvilParser {
+    static getChunkList(data: RegionInput): {
+        x: number;
+        z: number;
+    }[];
+    static parse(data: RegionInput): Promise<AnvilRegion>;
+    static parseChunk(data: RegionInput, localX: number, localZ: number): Promise<AnvilChunk | undefined>;
+    private static bytes;
+    private static locations;
+    private static readChunk;
+    private static compounds;
+    private static integer;
+    private static block;
+    private static unpack;
+}
+
+interface BlockInfo<SectionMeshing extends boolean = false> {
+    /** Detached block data; use world or chunk setters to update stored blocks. */
+    readonly block: Block;
+    /** Merged terrain has no individual render object in section-meshing mode. */
+    object: SectionMeshing extends false ? BlockObject : BlockObject | undefined;
+}
+
+interface SectionMeshTemplate {
+    geometry: BufferGeometry;
+    atlas: TextureAtlas;
+    cullFaces: readonly number[];
+}
+interface SectionMeshEntry {
+    index: number;
+    template: SectionMeshTemplate;
+    cullMask: number;
+}
+declare class SectionMesh extends Group {
+    private readonly ownedMeshes;
+    static build(entries: readonly SectionMeshEntry[], maxAtlasSize?: number): SectionMesh;
+    dispose(): void;
+}
+
+declare class SectionModels {
+    readonly maxAtlasSize: number;
+    private states;
+    private models;
+    private readonly templates;
+    constructor(maxAtlasSize?: number);
+    get(blockState: BlockState, properties?: BlockStateProperties): Promise<SectionMeshTemplate | undefined>;
+    private prepare;
+    clear(): void;
 }
 
-declare class Chunk {
+declare class Chunk<SectionMeshing extends boolean = false> {
+    private readonly onBlocksChanged?;
+    private readonly sectionModels?;
     readonly scene: MineRenderScene;
     readonly x: number;
     readonly y: number;
     readonly z: number;
-    private readonly _blocks;
-    private readonly _anchor;
-    constructor(scene: MineRenderScene, x: number, y: number, z: number);
-    getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo>;
-    getBlockAt(pos: Vector3): Maybe<BlockInfo>;
-    getBlockAt(pos: TripleArray): Maybe<BlockInfo>;
+    private readonly data;
+    private readonly renderedBlocks;
+    private readonly sectionBlocks;
+    private readonly hiddenBlocks;
+    private sectionMesh?;
+    private meshDirty;
+    constructor(scene: MineRenderScene, x: number, y: number, z: number, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined, sectionModels?: SectionModels | undefined);
+    getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo<SectionMeshing>>;
+    getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
+    getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
     /**
      * Set block at a _world_ position
      */
-    setBlockAt(x: number, y: number, z: number, block: Maybe<Block>): Promise<Maybe<BlockInfo>>;
-    setBlockAt(pos: Vector3, block: Maybe<Block>): Promise<Maybe<BlockInfo>>;
-    setBlockAt(pos: TripleArray, block: Maybe<Block>): Promise<Maybe<BlockInfo>>;
+    setBlockAt(x: number, y: number, z: number, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    setBlockAt(pos: Vector3, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    setBlockAt(pos: TripleArray, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
     /**
-     * Set block at a _chunk_ position (0-16)
+     * Set a block at integer chunk-local coordinates from 0 to 15.
      */
-    setBlockInChunkAt(pos: Vector3, block?: Block, worldPos?: Vector3): Promise<Maybe<BlockInfo>>;
-    clear(): Promise<void>;
+    setBlockInChunkAt(pos: Vector3, block?: Block, worldPos?: Vector3, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    setBlockVisibleAt(pos: Vector3, visible: boolean): Promise<void>;
+    isBlockVisibleAt(pos: Vector3): boolean;
+    isOccludingAt(pos: Vector3): boolean;
+    setCullMaskAt(pos: Vector3, mask: number): Promise<void>;
+    rebuildSectionMesh(): void;
+    clear(onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<void>;
     dispose(): Promise<void>;
+    static isAir(block: Maybe<Block>): boolean;
     static chunkPosToBlockIndex(pos: Vector3): number;
     worldPosToChunkPos(pos: Vector3): Vector3;
     chunkPosToWorldPos(pos: Vector3): Vector3;
 }
 
-declare class MineRenderWorld {
+declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     readonly scene: MineRenderScene;
-    private _size;
-    private _blockSize;
     private readonly _chunks;
-    constructor(scene: MineRenderScene);
-    getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo>;
-    getBlockAt(pos: Vector3): Maybe<BlockInfo>;
-    getBlockAt(pos: TripleArray): Maybe<BlockInfo>;
-    setBlockAt(x: number, y: number, z: number, block: Block): Promise<Maybe<BlockInfo>>;
-    setBlockAt(pos: Vector3, block: Block): Promise<Maybe<BlockInfo>>;
-    setBlockAt(pos: TripleArray, block: Block): Promise<Maybe<BlockInfo>>;
+    private readonly sectionModels?;
+    private readonly pendingCulling;
+    private culling?;
+    constructor(scene: MineRenderScene, options?: MineRenderWorldOptions<SectionMeshing>);
+    getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo<SectionMeshing>>;
+    getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
+    getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
+    setBlockAt(x: number, y: number, z: number, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    setBlockAt(pos: Vector3, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    setBlockAt(pos: TripleArray, block: Maybe<Block>): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    private placeBlock;
+    /**
+     * Shows or hides a placed block without changing its data. Hidden blocks do not occlude neighbors.
+     * Missing blocks are ignored; replacing or removing a block resets its visibility.
+     */
+    setBlockVisibleAt(x: number, y: number, z: number, visible: boolean): Promise<void>;
+    setBlockVisibleAt(pos: Vector3, visible: boolean): Promise<void>;
+    setBlockVisibleAt(pos: TripleArray, visible: boolean): Promise<void>;
     placeMultiBlock(multiblock: MultiBlockStructure, useBatches?: boolean, executor?: BatchedExecutor): Promise<void>;
+    private placeBlocks;
+    /** Replaces one chunk column's blocks. Entity NBT remains available on the parsed chunk. */
+    placeChunk(chunk: AnvilChunk, executor?: BatchedExecutor): Promise<void>;
     clear(): Promise<void>;
+    private updateCulling;
     private getOrCreateChunkAt;
-    getChunkAt(pos: Vector3): Maybe<Chunk>;
+    getChunkAt(pos: Vector3): Maybe<Chunk<SectionMeshing>>;
     static worldToScenePosition(pos: Vector3): Vector3;
     static sceneToWorldPosition(pos: Vector3): Vector3;
-    worldPosToChunkIndex(pos: Vector3): number;
     worldPosToChunkKey(pos: Vector3): string;
     validatePosBounds(pos: Vector3): void;
 }
+interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
+    /** Merge static opaque cubes into section meshes. Merged blocks have no individual object. */
+    sectionMeshing?: SectionMeshing;
+    /** Maximum width and height of each section atlas page, in pixels. */
+    maxAtlasSize?: number;
+}
 
 /**
  * {@link EnvProvider} backed by the DOM. Uses nothing outside of standard browser APIs and
@@ -1633,4 +2527,4 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, 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, BlockEntityModels, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, type BlockStateVariant, type BlockStateVariants, BlockStates, type BoxGeometryKey, BrowserArchiveProxy, BrowserCache, BrowserEnv, CUBE_FACES, type CacheKey, Caching, type CameraOptions, CanvasImage, Chunk, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, type Cube, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, type Disposable, type DoubleArray, type ElementFace, type ElementRotation, Entities, type EntityModel, EntityModels, EntityObject, type EntityObjectOptions, Env, type EnvProvider, type ExtractableImageData, type FromTo, Geometries, GuiLight, GuiObject, type GuiObjectOptions, 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 MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, type ModelPart, ModelTextures, Models, type MultiBlockBlock, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererOptions, Requests, type ResponseParser, SKIN_PARTS, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, type Serializable, type SkinGeometries, SkinObject, type SkinObjectOptions, SkinPart, type SkinTextureCoordinates, 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, applyModelPartRotation, axisToVec3, base64decode, base64encode, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createImage, estimateBytesUsed, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, probeImageSize, registerBrowserEnv, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode };
+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 BitmapFont, type BitmapGlyph, 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, BrowserCache, BrowserEnv, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, 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, Fonts, type FrameCallback, type FromTo, Geometries, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, 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, OrbitControls, PersistentCache, type PositionedGuiGlyph, 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 SpecialItemPart, type SpecialItemRenderer, SpecialItems, 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, createGuiTextGeometry, createGuiTextureGeometry, 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, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };