minerender 2.1.0-alpha.5 → 2.1.0-alpha.50

package/dist/browser/index.d.ts

@@ -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, MeshBasicMaterial, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Box2, Scene, Object3DEventMap, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, 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;
@@ -60,10 +62,11 @@ declare function createCanvas(width: number, height: number): CompatCanvas;
 declare abstract class PersistentCache<B = unknown> {
     readonly backing: B;
     /** Bump to invalidate every persisted entry. */
-    static readonly VERSION = 1;
+    static readonly VERSION = 2;
     static open(name: string): PersistentCache;
     protected constructor(backing: B);
     abstract get<T>(key: string): Promise<T>;
+    /** Loads a missing entry and stores only non-nullish results. */
     getOrLoad<T>(key: string, loader: (key: string) => Promise<T>): Promise<T>;
     abstract put<T>(key: string, value: T): Promise<T>;
     abstract delete<T>(key: string): Promise<void>;
@@ -173,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;
@@ -200,6 +204,7 @@ declare class Materials {
     static get MISSING_TEXTURE(): Material;
     static createImage(key: MaterialKey): Material;
     static createBasicCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean): Material;
+    static createGuiCanvasMaterial(canvas: HTMLCanvasElement): MeshBasicMaterial;
     static createShadedCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean): Material;
     static getImage(key: MaterialKey): Material;
     static needsUpdate(mat: Material): void;
@@ -245,7 +250,8 @@ declare enum DisplayPosition {
     GUI = "gui",
     HEAD = "head",
     GROUND = "ground",
-    FIXED = "fixed"
+    FIXED = "fixed",
+    ON_SHELF = "on_shelf"
 }
 declare const DISPLAY_POSITIONS: DisplayPosition[];
 
@@ -254,6 +260,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);
@@ -277,7 +323,7 @@ interface ImageInfo {
     width: number;
     height: number;
     type?: string;
-    data: Buffer$1;
+    data: Buffer;
 }
 declare class ImageLoader {
     protected static _createImage(): CompatImage;
@@ -289,7 +335,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>;
@@ -303,7 +349,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[];
 }
@@ -318,7 +364,6 @@ interface ItemModel extends Model {
 interface TextureAsset extends MinecraftAsset, ImageInfo {
 }
 interface ModelDisplay {
-    position?: DisplayPosition;
     translation?: TripleArray;
     rotation?: TripleArray;
     scale?: TripleArray;
@@ -338,13 +383,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;
@@ -360,7 +399,7 @@ 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 {
@@ -488,6 +527,7 @@ declare class TextureAtlas implements Disposable {
     };
     readonly hasTransparency: boolean;
     ticker?: number;
+    private readonly subscribers;
     constructor(model: Model, image: CanvasImage, sizes: {
         [texture: string]: DoubleArray;
     }, positions: {
@@ -495,6 +535,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;
 }
@@ -513,6 +555,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;
@@ -534,14 +577,13 @@ declare class MinecraftFaceUV {
 }
 
 /**
- * Releases every long-lived timer MineRender holds, so a Node process can exit.
+ * Stops the shared Ticker and request queues, and clears the in-memory caches.
  *
- * Both `@inventivetalent/loading-cache` (cache expiry) and `jobqu` (request queue draining) use
- * self-rescheduling timers that are not unref'd, which keeps the event loop alive for as long as
- * the library is loaded. Browsers don't care, but anything headless - a render server, a CLI, a
- * test run - has to call this when it's done.
+ * 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.
  *
- * The library stays usable afterwards; the caches and queues simply start over.
+ * 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,42 +591,15 @@ 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;
@@ -613,15 +628,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 {
@@ -636,18 +683,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 {
     /**
@@ -686,25 +734,60 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
-interface EntityModel extends BasicMinecraftAsset {
-    parts?: {
-        [p: string]: ModelPart;
+interface EntityLayer {
+    key: BasicAssetKey;
+    texture?: AssetKey;
+    layer: EntityModelLayer;
+}
+interface EntityModel extends EntityLayer {
+    id: string;
+    /** Selected layers; the top-level fields describe the first selection. */
+    layers?: Record<string, EntityLayer>;
+}
+interface EntityModelFile extends MinecraftAsset {
+    id: string;
+    layers: Record<string, EntityModelLayer>;
+}
+interface EntityModelLayer {
+    texture: [number, number];
+    textureLocation?: string;
+    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 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>>;
-}
-declare class EntityModels implements MinecraftAsset {
-    [k: string]: any;
+    private static getModelFile;
+    static getLayerList(modelKey: BasicAssetKey): Promise<string[]>;
+    static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
+    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>>;
 }
-declare class BlockEntityModels implements MinecraftAsset {
-    [k: string]: any;
+interface EntityModelOptions {
+    layer?: string;
+    /** Layer names in draw order; defaults to layer or "main". */
+    layers?: string[];
+    /** Per-layer texture overrides. The positional texture key applies to the first selected layer. */
+    textures?: Record<string, BasicAssetKey>;
 }
 
 declare class Models {
@@ -712,12 +795,27 @@ 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 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[];
@@ -734,8 +832,24 @@ interface Block {
     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>;
+    private static grassColor;
+}
+
 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;
     setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
@@ -748,12 +862,15 @@ 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;
     setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
@@ -778,18 +895,33 @@ 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?;
     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;
 
@@ -822,24 +954,35 @@ declare enum SkinPart {
 }
 declare const SKIN_PARTS: SkinPart[];
 
+type CapeLayout = "minecraft" | "optifine" | "labymod";
+declare const capeTextureSizes: Record<CapeLayout, DoubleArray>;
+
 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;
 }
 
 declare class EntityObject extends SceneObject {
@@ -847,19 +990,54 @@ declare class EntityObject extends SceneObject {
     readonly isEntityObject: true;
     static readonly DEFAULT_OPTIONS: EntityObjectOptions;
     readonly options: EntityObjectOptions;
-    private imageData?;
     private meshesCreated;
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
-    protected loadTextures(): Promise<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 {
+    flip?: boolean;
 }
 declare function isEntityObject(obj: any): obj is EntityObject;
 
+/** A texture layer in GUI pixels. Later layers draw above earlier layers. */
+interface GuiLayer {
+    name?: string;
+    texture: AssetKey | string;
+    /** Source-image pixels: [x, y, width, height], measured from the top left. */
+    crop?: [number, number, number, number];
+    /** Top-left position; x grows right and y grows down. Defaults to [0, 0]. */
+    position?: [number, number];
+    /** Output width and height. Defaults to the crop or full image size. */
+    size?: [number, number];
+}
+
+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 initialized;
+    constructor(textureLayers: readonly GuiLayer[], options?: Partial<GuiObjectOptions>);
+    init(): Promise<void>;
+    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;
@@ -879,6 +1057,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 {
 }
@@ -894,6 +1073,9 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     private materialCallbacks;
     protected _isInstanced: boolean;
     _instanceCounter: number;
+    protected instanceMesh?: InstancedMesh;
+    private readonly instanceReferences;
+    private readonly freeInstanceIndices;
     constructor(options?: Partial<SceneObjectOptions>);
     set scene(scene: MineRenderScene);
     get scene(): MineRenderScene;
@@ -933,6 +1115,12 @@ 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;
     setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
@@ -956,6 +1144,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;
@@ -969,13 +1174,27 @@ declare class BlockObject extends SceneObject {
     private _instanceModel;
     private _variants;
     private _models;
+    private _cullMask;
+    private _fluidKey?;
+    private _fluidSampler?;
+    private _fluidModel?;
     constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
     removeFromScene(): void;
+    private clearModels;
+    private removeModels;
+    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>;
@@ -994,26 +1213,50 @@ 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>;
+    static parse(nbt: NBT): Promise<MultiBlockStructure>;
 }
 
 declare class StructureParser {
     static parse(_nbt: NBT, paletteIndex?: number): Promise<MultiBlockStructure>;
 }
 interface StructureNBT {
-    DataVersion: {
+    DataVersion?: {
         type: "int";
         value: number;
     };
@@ -1025,7 +1268,13 @@ interface StructureNBT {
         };
     };
     palette?: Palette;
-    palettes?: Palette[];
+    palettes?: {
+        type: "list";
+        value: {
+            type: "list";
+            value: Palette["value"][];
+        };
+    };
     blocks: {
         type: "list";
         value: {
@@ -1033,7 +1282,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";
@@ -1077,14 +1351,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 {
@@ -1103,6 +1380,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>>;
 }
@@ -1117,6 +1395,8 @@ interface ArchiveEntry {
 }
 
 interface ArchiveProxy {
+    /** Identifies the archive's content across sessions; undefined when it cannot be identified. */
+    readonly id?: string;
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
@@ -1124,6 +1404,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>>;
@@ -1134,7 +1415,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[]>;
 }
 
@@ -1212,27 +1494,54 @@ declare class Caching {
     static readonly mergedModelCache: AsyncLoadingCache<CacheKey, Model>;
     static readonly modelTextureAtlasCache: AsyncLoadingCache<CacheKey, TextureAtlas>;
     static readonly blockStateCache: AsyncLoadingCache<CacheKey, BlockState>;
+    static readonly listAssetCache: AsyncLoadingCache<CacheKey, ListAsset>;
+    static readonly defaultBlockStatesCache: AsyncLoadingCache<CacheKey, DefaultBlockStates>;
+    static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
+    static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
+    static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
+    private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
     static clear(): void;
     /**
      * Clears every cache and stops its expiry timer.
      *
-     * loading-cache reschedules that timer indefinitely, so a Node process will not exit until
-     * this is called - see {@link shutdown}.
+     * Expiry timers are unref'd in Node, so idle processes can exit without this cleanup.
+     * Use {@link shutdown} to also stop requests and the shared Ticker.
      */
     static end(): void;
     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 {
+    static inventorySlot(slot: number | [number, number], origin?: [number, number], offset?: [number, number], rowSize?: number): [number, number];
 }
 
 declare class OrbitControls {
@@ -1357,7 +1666,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;
@@ -1395,6 +1713,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;
@@ -1419,17 +1739,21 @@ declare class SceneInspector {
     protected readonly raycaster: Raycaster;
     private readonly mouse;
     private selectedObject?;
+    private pointer?;
+    private readonly listeners;
     constructor(renderer: Renderer);
     protected init(): void;
+    dispose(): void;
     findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry<three.NormalBufferAttributes>, three.Material | three.Material[], three.Object3DEventMap>[];
-    onClick(event: any): void;
+    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;
@@ -1458,34 +1782,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;
-    };
-    /**
-     * Stops both queue timers. jobqu reschedules itself indefinitely, so a Node process will not
-     * exit until this is called - 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>>;
@@ -1494,8 +1817,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;
@@ -1505,11 +1831,18 @@ 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 TextureLoader {
+    private static readonly failedTextures;
+    /** Reports whether image loading failed, so cached textures can be retried. */
+    static hasFailed(texture: Texture): boolean;
     protected static createTexture(): Texture;
     static loadInBackground(src: string, format?: PixelFormat, rotation?: number): Texture;
     static load(src: string, format?: PixelFormat, rotation?: number): Texture;
@@ -1531,61 +1864,155 @@ 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 Chunk {
+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<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 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>>>;
+    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;
     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
@@ -1619,8 +2046,8 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  *
  * `image-size` pulls in `fs`/`path` at module scope, so it can only live in the Node build.
  * Everything MineRender loads is a PNG in practice; GIF and JPEG are handled as a courtesy and
- * anything else falls through to an empty result (callers treat that as 0x0).
+ * anything else falls through to an empty result, which ImageLoader rejects.
  */
 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 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, BrowserCache, BrowserEnv, 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, EntityObject, type EntityObjectOptions, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, type FromTo, Geometries, GuiHelper, type GuiLayer, 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 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 QuadArray, type RawImageKey, type RenderOptions, Renderer, 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, probeImageSize, registerBrowserEnv, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };