minerender 2.1.0-beta.0 → 2.1.0-beta.2

package/dist/browser/index.d.mts

@@ -1,5 +1,5 @@
 import * as three 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 { 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, Group, DataTexture, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
 import * as nodeCanvas from 'canvas';
 import { ImageData as ImageData$1, CanvasRenderingContext2D } from 'canvas';
 import { Buffer } from 'buffer';
@@ -11,6 +11,7 @@ export { PLYExporterOptions } from 'three/examples/jsm/exporters/PLYExporter.js'
 import Stats from 'stats.js';
 import { EffectComposer } from 'postprocessing';
 
+/** Advances a texture animation by one tick. Return `false` when its pixels have not changed. */
 interface AnimatorFunction {
     (): boolean | void;
 }
@@ -42,6 +43,7 @@ declare enum CubeFaceIndex {
 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]];
 
+/** An object that can release the resources it owns. */
 interface Disposable {
     dispose(): void;
 }
@@ -49,7 +51,9 @@ declare function isDisposable(obj: any): obj is Disposable;
 
 type CompatImage = HTMLImageElement | nodeCanvas.Image;
 type CompatCanvas = HTMLCanvasElement | nodeCanvas.Canvas;
+/** Creates an image through the active environment provider. Dimensions are in pixels. */
 declare function createImage(width?: number, height?: number): CompatImage;
+/** Creates a browser or Node canvas through the active environment provider, sized in pixels. */
 declare function createCanvas(width: number, height: number): CompatCanvas;
 
 /**
@@ -63,6 +67,7 @@ declare abstract class PersistentCache<B = unknown> {
     readonly backing: B;
     /** Bump to invalidate every persisted entry. */
     static readonly VERSION = 2;
+    /** Opens a named store in the active environment using the current cache schema version. */
     static open(name: string): PersistentCache;
     protected constructor(backing: B);
     abstract get<T>(key: string): Promise<T>;
@@ -115,6 +120,7 @@ declare class Env {
     static get provider(): EnvProvider;
 }
 
+/** A canvas-backed image with dimensions and a context for reading pixel regions. */
 interface ExtractableImageData {
     readonly data: CanvasImageData;
     readonly width: number;
@@ -122,10 +128,12 @@ interface ExtractableImageData {
 }
 
 type CacheKey = string;
+/** Source URL used to identify cached image bytes and pixels. */
 interface RawImageKey {
     src: string;
 }
 declare function serializeImageKey(key: RawImageKey): string;
+/** Box dimensions in scene units and optional normalized UVs in Three.js face order. */
 interface BoxGeometryKey {
     width: number;
     height: number;
@@ -133,32 +141,39 @@ interface BoxGeometryKey {
     uv?: number[];
 }
 declare function serializeBoxGeometryKey(key: BoxGeometryKey): string;
+/** Settings passed to {@link Textures.getImage}. Texture rotation uses radians. */
 interface TextureKey extends RawImageKey {
     format?: PixelFormat;
     rotation?: number;
 }
 declare function serializeTextureKey(key: TextureKey): string;
+/** Texture and transparency settings passed to {@link Materials.getImage}. */
 interface MaterialKey {
     texture: TextureKey;
     transparent?: boolean;
 }
 declare function serializeMaterialKey(key: MaterialKey): string;
+/** Geometry and material settings passed to {@link Meshes.createBox} or {@link Meshes.getBox}. */
 interface MeshKey {
     geometry: BoxGeometryKey;
     material: MaterialKey;
 }
 declare function serializeMeshKey(key: MeshKey): string;
 
+/** Creates box geometry with optional face UVs and caches it by dimensions and UV values. */
 declare class Geometries {
     static createBox(key: BoxGeometryKey): BoxGeometry;
+    /** Returns shared geometry. Use {@link createBox} when the caller needs to modify or dispose it independently. */
     static getBox(key: BoxGeometryKey): BoxGeometry;
 }
 
+/** Produces a string representation, such as an asset cache key. */
 interface Serializable {
     serialize(): string;
 }
 
 type AssetType = "models" | "textures" | "blockstates" | string;
+/** A Minecraft namespace and path, such as `minecraft` and `zombie`. */
 declare class BasicAssetKey implements Serializable {
     readonly namespace: string;
     readonly path: string;
@@ -168,6 +183,7 @@ declare class BasicAssetKey implements Serializable {
     toString(): string;
     serialize(): string;
 }
+/** Locates an asset by namespace, directory, extension, and optional asset root. */
 declare class AssetKey extends BasicAssetKey {
     readonly namespace: string;
     readonly path: string;
@@ -177,44 +193,167 @@ declare class AssetKey extends BasicAssetKey {
     extension: ".json" | ".png" | string;
     root?: string | undefined;
     readonly isAssetKey: true;
+    /**
+     * Creates a key from separate path components. Use {@link parse} for a combined reference.
+     *
+     * @param assetType - Asset directory, such as `models`, `textures`, or `blockstates`.
+     * @param type - Subdirectory, such as `block` or `item`.
+     * @param rootType - Top-level directory, usually `assets` or `data`.
+     * @param root - Base URL override for hosted asset sources.
+     */
     constructor(namespace: string, path: string, assetType?: AssetType | undefined, type?: string | undefined, rootType?: "assets" | "data" | string, extension?: ".json" | ".png" | string, root?: string | undefined);
+    /**
+     * Parses an asset reference such as `minecraft:block/stone`.
+     * A missing namespace defaults to the origin's namespace or `minecraft`.
+     *
+     * @param assetType - Asset category, such as `models` or `textures`.
+     * @param str - Path with an optional namespace and file extension.
+     * @param origin - Supplies the asset root, default namespace, and non-texture extension.
+     * @returns A key with the matching extension removed from its path. Textures use `.png`;
+     * other assets use the origin's extension or `.json`.
+     */
     static parse(assetType: AssetType, str: string, origin?: AssetKey): AssetKey;
     toString(): string;
+    /** Joins the type subdirectory and path without adding a namespace or file extension. */
     getFullPath(): string;
     toNamespacedString(): string;
+    /** Returns a cache identifier that includes the explicit root or {@link AssetLoader.ROOT}. */
     serialize(): string;
 }
 declare function isBasicAssetKey(obj: any): obj is BasicAssetKey;
 declare function isAssetKey(obj: any): obj is AssetKey;
 
+/** Loaded data with an optional namespace-and-path identity. */
 interface BasicMinecraftAsset {
     key?: BasicAssetKey;
 }
+/** Loaded data that can retain its full source key for related asset lookups. */
 interface MinecraftAsset extends BasicMinecraftAsset {
     key?: AssetKey;
 }
 
+/** A hosted `_list.json` directory index used by asset-listing APIs. */
 interface ListAsset extends MinecraftAsset {
     directories: string[];
     files: string[];
 }
 
+/** One selected draw, combining geometry, texture, and material settings. */
+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;
+}
+/** Selected entity data returned by {@link Entities.getEntity} for rendering. */
+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>;
+}
+/** Dataset file containing all geometry layers and optional extra render passes. */
+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" | "no_outline";
+/** An extra draw of a geometry layer, optionally enabled by an entity-state label. */
+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];
+};
+/** A named geometry tree with texture dimensions in pixels and an optional default texture path. */
+interface EntityModelLayer {
+    texture: [number, number];
+    textureLocation?: string;
+    /** Omitted for `cutout`. */
+    render?: EntityRenderMode;
+    root: EntityModelPart;
+}
+/** A named part's baked pose and children. Offsets use model units and rotations use radians. */
+interface EntityModelPart {
+    pose: {
+        offset: [number, number, number];
+        rotation: [number, number, number];
+        scale?: [number, number, number];
+    };
+    texture?: [number, number];
+    cubes: EntityModelCube[];
+    children: Record<string, EntityModelPart>;
+}
+/** A part's cuboid in model units, with a texture origin in pixels and optional per-axis growth. */
+interface EntityModelCube {
+    origin: [number, number, number];
+    size: [number, number, number];
+    uv: [number, number];
+    grow?: [number, number, number];
+    mirror?: boolean;
+}
+
+/** Creates Minecraft model, entity, and GUI materials, with shared caches for image materials. */
 declare class Materials {
-    private static readonly MISSING_TEXTURE_SRC;
+    /** Shared checkerboard material, created on first access. */
     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;
+    /** Creates an unlit, transparent GUI material without depth writes or tone mapping. */
     static createGuiCanvasMaterial(canvas: HTMLCanvasElement): MeshBasicMaterial;
-    static createShadedCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean): Material;
+    static createShadedCanvasMaterial(canvas: HTMLCanvasElement, transparent?: boolean, shade?: boolean, boundUvs?: boolean): Material;
+    /** Returns a shared image material. Use {@link createImage} for a separate material instance. */
     static getImage(key: MaterialKey): Material;
     static needsUpdate(mat: Material): void;
 }
 
+/** Creates box meshes from shared geometry and image materials. */
 declare class Meshes {
     static createBox(key: MeshKey): Mesh;
+    /** Returns a shared Mesh object. Use {@link createBox} for a mesh with its own transform and parent. */
     static getBox(key: MeshKey): Mesh;
 }
 
+/** Texture and culling settings for one cuboid face. Java model UVs use Minecraft's 0–16 texture space. */
 interface ElementFace {
     uv: QuadArray;
     mappedUv?: QuadArray;
@@ -228,6 +367,7 @@ interface FromTo {
     from: TripleArray;
     to: TripleArray;
 }
+/** A cuboid in model units, where 16 units equal one block. */
 interface ModelElement extends FromTo {
     rotation?: ElementRotation;
     shade?: boolean;
@@ -235,6 +375,7 @@ interface ModelElement extends FromTo {
     mappedUv?: number[];
 }
 type ModelFaces = Partial<Record<CubeFace, Partial<ElementFace>>>;
+/** Rotates one cuboid around an origin in model units, using an angle in degrees. */
 interface ElementRotation {
     origin: TripleArray;
     axis: Axis;
@@ -260,14 +401,17 @@ declare enum GuiLight {
     SIDE = "side"
 }
 
+/** Fetch settings passed to {@link Requests.genericRequest} or {@link Requests.mcAssetRequest}. */
 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;
+    /** Response-body decoding. Defaults to `json`. */
     responseType?: "json" | "arraybuffer";
 }
+/** A decoded response body with the HTTP status, native headers, and final URL. */
 interface RequestResponse<T = any> {
     data: T;
     status: number;
@@ -276,16 +420,21 @@ interface RequestResponse<T = any> {
     /** Final URL after redirects. */
     url: string;
 }
+/** An HTTP or network failure, with response details or an underlying cause when available. */
 declare class RequestError extends Error {
     readonly response?: RequestResponse<undefined> | undefined;
     readonly cause?: unknown;
     constructor(message: string, response?: RequestResponse<undefined> | undefined, cause?: unknown);
 }
+/** Shared Fetch queues with concurrency limits, cancellation, timeouts, and bounded retries for GET requests. */
 declare class Requests {
     private static genericQueue;
     private static mcAssetRequestQueue;
+    /** Queues a general request. Set `request.signal` to cancel it and `request.timeout` to limit each attempt. */
     static genericRequest(request: RequestConfig): Promise<RequestResponse>;
+    /** Queues a request separately from general traffic, using the configured asset base URL for relative paths. */
     static mcAssetRequest(request: RequestConfig): Promise<RequestResponse>;
+    /** Sets the base URL for relative asset requests. Use {@link AssetLoader.setVersion} to change Minecraft versions. */
     static setMcAssetRoot(root: string): void;
     /** Counts unsettled calls, including retry delays and requests still running after shutdown. */
     static get queueSizes(): {
@@ -300,6 +449,7 @@ declare class Requests {
     static end(): void;
 }
 
+/** Provides pixel and frame access to a canvas-backed image. Simple frame helpers assume a vertical strip of squares. */
 declare class WrappedImage {
     readonly dta: ExtractableImageData;
     constructor(dta: ExtractableImageData);
@@ -308,6 +458,7 @@ declare class WrappedImage {
     get width(): number;
     get height(): number;
     get hasTransparency(): boolean;
+    /** Whether the dimensions form a vertical strip of square frames, without consulting `.mcmeta`. */
     get animated(): boolean;
     get frameWidth(): number;
     get frameHeight(): number;
@@ -318,6 +469,7 @@ declare class WrappedImage {
     getFrameSectionData(frame: number): ImageData$1;
 }
 
+/** Encoded image bytes with dimensions and format detected from the file header. */
 interface ImageInfo {
     src?: string;
     width: number;
@@ -325,15 +477,21 @@ interface ImageInfo {
     type?: string;
     data: Buffer;
 }
+/** Fetches and decodes images through the active browser or Node environment provider. */
 declare class ImageLoader {
     protected static _createImage(): CompatImage;
+    /** Resolves when an image URL has decoded, or rejects if decoding fails. */
     static loadAsync(src: string): Promise<CompatImage>;
+    /** Returns an image immediately. Use the callbacks to observe loading, or await {@link loadAsync}. */
     static loadElement(src: string, onload?: () => void, onerr?: (err: Error) => void): CompatImage;
     static loadData(src: string): Promise<ImageData>;
     static loadCanvasData(src: string): Promise<ExtractableImageData>;
+    /** Decodes the supplied bytes into a canvas without fetching the source URL again. */
     static infoToCanvasData(info: ImageInfo): Promise<ExtractableImageData>;
     static infoToData(info: ImageInfo): Promise<ImageData>;
+    /** Returns cached RGBA pixels for an image URL or data URL. Failed loads can be retried. */
     static getData(src: string): Promise<ImageData>;
+    /** Returns a cached canvas context and dimensions for an image URL or data URL. */
     static getCanvasData(src: string): Promise<ExtractableImageData>;
     static processResponse(response: Pick<RequestResponse<ArrayBuffer>, "data" | "url">): Promise<ImageInfo>;
     static loadInfo(src: string): Promise<ImageInfo>;
@@ -342,10 +500,51 @@ declare class ImageLoader {
     static getWrapped(src: string): Promise<WrappedImage>;
 }
 
+/** Vanilla dye colors used by banner and shield textures, as sRGB packed values. */
+declare const DYE_COLORS: Readonly<{
+    readonly white: 16383998;
+    readonly orange: 16351261;
+    readonly magenta: 13061821;
+    readonly light_blue: 3847130;
+    readonly yellow: 16701501;
+    readonly lime: 8439583;
+    readonly pink: 15961002;
+    readonly gray: 4673362;
+    readonly light_gray: 10329495;
+    readonly cyan: 1481884;
+    readonly purple: 8991416;
+    readonly blue: 3949738;
+    readonly brown: 8606770;
+    readonly green: 6192150;
+    readonly red: 11546150;
+    readonly black: 1908001;
+}>;
+type DyeColor = keyof typeof DYE_COLORS;
+/** A registry banner pattern or an inline value in a `banner_patterns` component. */
+interface BannerPattern extends MinecraftAsset {
+    asset_id: string;
+    translation_key: string;
+}
+interface BannerPatternDraw {
+    texture: AssetKey;
+    color: number;
+}
+/** Loads banner-pattern registry entries and resolves their banner or shield textures. */
+declare class BannerPatterns {
+    /** Lists namespaced pattern IDs from the selected namespace's data directory. */
+    static getList(namespace?: string, root?: string): Promise<string[]>;
+    /** Returns the named dye's sRGB value, rejecting unknown colors. */
+    static getColor(color: unknown): number;
+    /** Resolves the first 16 layers of a `banner_patterns` component, preserving their order. */
+    static getLayers(value: unknown, target: "banner" | "shield", root?: string): Promise<BannerPatternDraw[]>;
+    private static identifier;
+}
+
 declare const ITEM_GENERATED = "item/generated";
 declare const BUILTIN_GENERATED = "builtin/generated";
 declare const BUILTIN_ENTITY = "builtin/entity";
 declare const DEFAULT_ELEMENTS: ModelElement[];
+/** A Java model definition. {@link Models.getMerged} resolves its parent, textures, and elements. */
 interface Model extends MinecraftAsset {
     textures?: IModelTextures;
     parent?: string;
@@ -353,16 +552,69 @@ interface Model extends MinecraftAsset {
     elements?: ModelElement[];
     hierarchy?: string[];
 }
+/** Java block-model data, including the ambient-occlusion flag. */
 interface BlockModel extends Model {
     textures?: BlockModelTextures;
     ambientocclusion?: boolean;
 }
+/** Item preview data, including GUI lighting, tint sources, and supported special renderers. */
 interface ItemModel extends Model {
     textures?: ItemModelTextures;
     gui_light?: GuiLight;
-}
+    special?: SpecialItemRenderer;
+    tints?: ItemTintSource[];
+    /** Stack-component snapshot with namespaced IDs, used by tint sources and special renderers. */
+    components?: Record<string, unknown>;
+    /** Ordered composite children, each with its own textures, display pose, and tint sources. */
+    parts?: ItemModel[];
+}
+/** An sRGB packed `0xRRGGBB` value or an RGB triple with components from 0 to 1. */
+type ItemTintColor = number | TripleArray;
+/** A vanilla item color source. Missing component values and unsupported gameplay state use the declared default. */
+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;
+};
+/** Supported item definitions that draw entity geometry instead of ordinary model elements. */
+type SpecialItemRenderer = {
+    type: "banner" | "minecraft:banner";
+    color: DyeColor;
+} | {
+    type: "shield" | "minecraft:shield";
+} | {
+    type: "trident" | "minecraft:trident" | "conduit" | "minecraft:conduit";
+} | {
+    type: "chest" | "minecraft:chest";
+    texture: string;
+    openness?: number;
+} | {
+    type: "shulker_box" | "minecraft:shulker_box";
+    texture: string;
+    openness?: number;
+    orientation?: "down" | "up" | "north" | "south" | "west" | "east";
+} | {
+    type: "bed" | "minecraft:bed";
+    texture: string;
+} | {
+    type: "head" | "minecraft:head";
+    kind: string;
+    texture?: string;
+    animation?: number;
+};
 interface TextureAsset extends MinecraftAsset, ImageInfo {
 }
+/** A model display pose: translation in model units, rotation in degrees, and scale factors. */
 interface ModelDisplay {
     translation?: TripleArray;
     rotation?: TripleArray;
@@ -402,9 +654,33 @@ declare class MinecraftCubeTexture {
     toUvArray(w: number, h: number, l: number, mirror?: boolean): number[];
 }
 
+/** Texture animation and GUI scaling metadata read from a `.png.mcmeta` file. */
 interface MinecraftTextureMeta extends MinecraftAsset {
-    animation: AnimationMeta;
+    animation?: AnimationMeta;
+    gui?: {
+        scaling?: GuiSpriteScaling;
+    };
 }
+/** GUI sprite scaling rules. Dimensions and borders use logical GUI pixels, independent of PNG resolution. */
+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;
+};
+/** Texture frame-grid and playback settings. Frame durations use ticks at 20 ticks per second. */
 interface AnimationMeta {
     interpolate: boolean;
     width: number;
@@ -412,17 +688,20 @@ interface AnimationMeta {
     frametime: number;
     frames: Array<number | AnimationFrame>;
 }
+/** A zero-based frame index and its duration in ticks, overriding the animation's default frame time. */
 interface AnimationFrame {
     index: number;
     time: number;
 }
 
+/** Counts direct scene children, Minecraft scene objects, and live instance placements. */
 declare class SceneStats {
     objectCount: number;
     sceneObjectCount: number;
     instanceCount: number;
 }
 
+/** A synchronous callback registered with {@link Ticker.add}. */
 interface TickerFunction {
     (): void;
 }
@@ -444,18 +723,24 @@ declare class Ticker {
     private static fiveSecondTps;
     private static fiveSecondTicks;
     private static schedule;
+    /** Starts or resumes the shared tick loop. Repeated calls have no effect. */
     static start(): void;
+    /** Pauses the loop while retaining callbacks for a later {@link start}. */
     static stop(): void;
+    /** Registers a callback, starts the loop if needed, and returns an ID for {@link remove}. */
     static add(tick: TickerFunction): number;
+    /** Removes a callback by ID and stops the timers when no callbacks remain. */
     static remove(c?: number): void;
     static get tickers(): Map<number, TickerFunction>;
     static get tpsOneSecond(): number;
     static get tpsFiveSeconds(): number;
+    /** Stops the loop and removes all registered callbacks. */
     static dispose(): void;
 }
 
 declare const TintColors: never[];
 
+/** Transform access shared by scene objects and instance references. Positions use scene units and rotations use radians. */
 interface Transformable {
     setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
     setPosition(position: Vector3): void;
@@ -479,22 +764,30 @@ declare function base64encode(str: string): string;
 declare function base64decode(str: string): string;
 declare function toRadians(degrees: number): number;
 declare function toDegrees(radians: number): number;
+/** Resolves after a delay in milliseconds. */
 declare function sleep(timeout: number): Promise<void>;
+/** Reduces an angle modulo 360, retaining a negative sign for negative inputs. */
 declare function clampRotationDegrees(deg: number): number;
 declare function isVector3(obj: any): obj is Vector3;
 type DeepPartial<T> = {
     [P in keyof T]?: DeepPartial<T[P]>;
 };
 
+/** Loads texture pixels and `.mcmeta` files through the active asset sources. */
 declare class ModelTextures {
     private static _persistentMetaCache;
     private static get PERSISTENT_META_CACHE();
+    /** Loads and decodes a texture into a readable canvas, or returns `undefined` when missing. */
     static get(key: AssetKey): Promise<Maybe<ExtractableImageData>>;
+    /** Fetches and caches encoded texture bytes without decoding the pixels. */
     static preload(key: AssetKey): Promise<Maybe<TextureAsset>>;
+    /** Loads a texture's `.mcmeta` file, or returns `undefined` when no metadata file exists. */
     static getMeta(key: AssetKey): Promise<Maybe<MinecraftTextureMeta>>;
+    /** Clears persisted texture metadata. Use {@link Caching.clear} to discard in-memory textures and metadata. */
     static clearCache(): Promise<void>;
 }
 
+/** Wraps a browser or Node canvas for pixel reads and writes. All coordinates and dimensions use pixels. */
 declare class CanvasImage implements Disposable {
     readonly canvas: CompatCanvas;
     readonly context: CanvasRenderingContext2D;
@@ -512,6 +805,7 @@ declare class CanvasImage implements Disposable {
     dispose(): void;
 }
 
+/** A model's combined texture canvas, per-texture rectangles, and shared animation subscriptions. */
 declare class TextureAtlas implements Disposable {
     readonly model: Model;
     readonly image: CanvasImage;
@@ -537,11 +831,13 @@ declare class TextureAtlas implements Disposable {
     }, hasTransparency: boolean);
     /** Calls subscribers when an animation frame changes; unused atlases do not tick. */
     subscribe(callback: () => void): () => void;
+    /** Copies pixels for a texture variable from its current atlas rectangle. */
     getData(texture: string): ImageData$1;
     dispose(): void;
 }
 
 declare const DEFAULT_UV: QuadArray;
+/** Maps Minecraft face coordinates to Three.js UVs and builds per-model texture atlases. */
 declare class UVMapper {
     protected static makeUv(uvCoord: number, originalTextureSize: number, actualTextureSize: number): number;
     protected static makeUvCoords([originalTextureWidth, originalTextureHeight]: DoubleArray, [actualTextureWidth, actualTextureHeight]: DoubleArray, [x1, y1, x2, y2]: QuadArray): QuadArray;
@@ -555,7 +851,10 @@ 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;
+    /** Bounds texture sampling to texel centres without changing cropped face UVs. */
+    static setAtlasUvBounds(geometry: BoxGeometry, faces: ModelFaces, atlas: TextureAtlas): void;
     static lockUvs(geometry: BoxGeometry, faces: ModelFaces, atlas: TextureAtlas, rotation: Euler): void;
+    /** Returns the shared atlas for a keyed, merged model, creating it on first use. */
     static getAtlas(model: Model): Promise<Maybe<TextureAtlas>>;
     static fillMissingTextureKeys<T>(textures: ModelTextures, target: {
         [k: string]: T;
@@ -564,8 +863,14 @@ declare class UVMapper {
     };
     protected static getFallbackUv(element: ModelElement, faceName: CubeFace): QuadArray;
     protected static expandAndRotateMcUvs([u1, v1, u2, v2]: QuadArray, rotation: number | undefined, actualWidth: number, actualHeight: number): QuadArray<Vector2>;
+    /**
+     * Combines model textures and animation metadata into an atlas.
+     * Mapped UVs are stored on copies of the model's elements, available through the returned atlas.
+     * Returns `undefined` for models without a texture map.
+     */
     static createAtlas(originalModel: Model): Promise<Maybe<TextureAtlas>>;
 }
+/** Stores a Minecraft face's UV rectangle and its rotation in degrees. */
 declare class MinecraftFaceUV {
     readonly uv: QuadArray;
     readonly rotation: number;
@@ -587,23 +892,33 @@ declare class MinecraftFaceUV {
  */
 declare function shutdown(): void;
 
+/** Runs queued tasks in bounded batches. Idle executors do not keep a timer running. */
 declare class BatchedExecutor {
     readonly interval: number;
     readonly batch: number;
     private readonly queue;
+    /**
+     * @param interval - Delay between queue runs, in milliseconds.
+     * @param batch - Maximum tasks started per run and maximum tasks active at once.
+     */
     constructor(interval?: number, batch?: number);
+    /** Queues a task and resolves with its result, or rejects with its error. */
     submit<T>(task: Task<T>): Promise<T>;
+    /** Rejects queued and future tasks. Tasks already running are allowed to finish. */
     stop(): void;
 }
 type Task<T = unknown> = () => T | Promise<T>;
 
 declare function prefix(prefix?: string): string;
 
+/** Rotates geometry in place around the element's origin. The supplied angle is in degrees. */
 declare function applyElementRotation(rotation: ElementRotation, geometry: BufferGeometry): void;
+/** Rotates an object around a local axis by an angle in degrees. */
 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;
+/** Adds edge and axis helpers to a mesh and returns a function that disposes their resources. */
+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;
@@ -625,9 +940,13 @@ declare enum AssetParser {
     JSON = "json"
 }
 
+/** An asset provider registered with {@link AssetLoader.addSource}. */
 declare abstract class AssetSource {
     protected constructor();
+    /** Returns a parsed asset, or `undefined` to allow fallback. Load and parse failures should reject. */
     abstract get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
+    /** Whether this source prevents lower-priority sources from supplying the key. Its own assets remain available. */
+    blocks(key: AssetKey): boolean | Promise<boolean>;
     /**
      * Identifies this source's content across sessions for persistent caching. Sources that
      * cannot tell whether their content changed (an unnamed archive, for example) return
@@ -644,12 +963,15 @@ declare class AssetLoadError extends Error {
     constructor(source: AssetSource, key: AssetKey, path: string, cause: unknown);
 }
 
+/** Loads assets from a shared, ordered registry of hosted sources and resource packs. */
 declare class AssetLoader {
+    /** Default asset base URL. Use {@link setVersion} to select a Minecraft version. */
     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;
+    /** Selects an mcasset.cloud version, updates the vanilla source, and clears in-memory caches. */
     static setVersion(version: string): void;
     /**
      * Scope for persistent cache keys. Empty with only the default vanilla sources, so their
@@ -659,8 +981,17 @@ declare class AssetLoader {
     static get persistentScope(): string;
     /** Prefixes a persistent cache key with the current source scope. */
     static persistentKey(key: string): string;
+    /**
+     * Registers a source at the highest priority.
+     * Call {@link Caching.clear} after changing sources to discard previously loaded assets.
+     *
+     * @param key - Name used to replace or remove this source.
+     * @param override - Removes the first source with this name before adding the new one.
+     */
     static addSource(key: string, source: AssetSource, override?: boolean): void;
+    /** Removes and returns the first source with this name. Call {@link Caching.clear} to reload assets. */
     static removeSource(key: string): Maybe<AssetSource>;
+    /** Loads from all sources and returns defined results in priority order. Any source failure rejects the call. */
     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>>;
@@ -671,6 +1002,7 @@ declare class AssetLoader {
     }>>;
 }
 
+/** A Java blockstate file that selects models through variants or multipart conditions. */
 interface BlockState extends MinecraftAsset {
     variants?: BlockStateVariants;
     multipart?: BlockStateMultipart[];
@@ -678,6 +1010,7 @@ interface BlockState extends MinecraftAsset {
 type BlockStateVariants = {
     [key: string]: BlockStateVariant | BlockStateVariant[];
 };
+/** A model selection with optional x/y rotations in degrees, UV locking, and random-selection weight. */
 interface BlockStateVariant {
     model?: string;
     y?: number;
@@ -689,6 +1022,7 @@ interface BlockStateMultipart {
     when?: MultipartCondition;
     apply?: BlockStateVariant | BlockStateVariant[];
 }
+/** Property tests combined with AND or OR. A property value such as `north|south` accepts either value. */
 type MultipartCondition = Record<string, string> | {
     OR: MultipartCondition[];
 } | {
@@ -697,16 +1031,20 @@ type MultipartCondition = Record<string, string> | {
 
 declare const DEFAULT_ROOT = "https://assets.mcasset.cloud/1.21.11";
 declare const DEFAULT_NAMESPACE = "minecraft";
+/** Convenience accessors for model and blockstate loading. */
 declare class Assets {
     /**
      * @deprecated
      */
     static parseAssetKey(assetType: AssetType, str: string, origin?: AssetKey): AssetKey;
+    /** Loads a model with its parent chain resolved. See {@link Models.getMerged}. */
     static getModel(key: AssetKey): Promise<Maybe<Model>>;
+    /** Loads a blockstate definition. See {@link BlockStates.get}. */
     static getBlockState(key: AssetKey): Promise<Maybe<BlockState>>;
 }
 
 type BlockStatePropertyValue = string | boolean | number;
+/** A vanilla block property's default and allowed values, loaded through {@link BlockStates.getDefaultState}. */
 interface BlockStateProperty {
     default: BlockStatePropertyValue;
     type: "boolean" | "int" | "enum";
@@ -716,106 +1054,267 @@ interface BlockStateProperty {
 type BlockStatePropertyDefaults = {
     [key: string]: BlockStateProperty;
 };
+/** Block property values, such as `{ facing: "north", waterlogged: "false" }`. */
 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;
+};
+/** Models and state-dependent placement for one block ID in the block-entity index. */
+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;
+};
+/** Parts and placement selected by {@link BlockEntities.resolve} for a block's properties. */
+interface ResolvedBlockEntity {
+    parts: BlockEntityPart[];
+    /** Degrees counter-clockwise seen from above, about the block's vertical centre axis. */
+    rotation: number;
+    translation: TripleArray;
+}
+/** Resolves blockstate properties into the entity models used to draw chests, beds, and other block entities. */
+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;
+}
+
+/** Loads blockstate definitions and the property defaults used to select block models. */
 declare class BlockStates {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
+    /** Returns blockstate filenames from the selected version's `_list.json`, or an empty list. */
     static getList(): Promise<string[]>;
     static getDefaultStates(): Promise<Maybe<DefaultBlockStates>>;
+    /** Looks up vanilla property definitions for the key's block path, or returns `undefined`. */
     static getDefaultState(key: AssetKey): Promise<Maybe<BlockStatePropertyDefaults>>;
+    /** Loads a cached blockstate definition for {@link MineRenderScene.addBlock}, or returns `undefined`. */
     static get(key: AssetKey): Promise<Maybe<BlockState>>;
     static getAll(keys: AssetKey[] | Iterable<AssetKey>): Promise<Maybe<BlockState>[]>;
+    /** Clears persisted blockstates. Use {@link Caching.clear} to also discard in-memory assets. */
     static clearCache(): Promise<void>;
 }
 declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
-interface EntityLayer {
-    key: BasicAssetKey;
-    texture?: AssetKey;
-    layer: EntityModelLayer;
-}
-interface EntityModel extends EntityLayer {
+/** `entity-models/animations/<namespace>/<model id>.json`: native and sampled vanilla animation clips. */
+interface EntityAnimationFile extends MinecraftAsset {
     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;
-}
+    animations: Record<string, EntityAnimation>;
+}
+/** A clip of pose offsets, played with {@link EntityObject.playAnimation} or sampled directly. */
+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[]>>;
+/** One timed offset for a part's position, rotation, or scale channel. */
+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;
 
+/** Loads entity and block-entity geometry, texture selections, and animation clips from the dataset. */
 declare class Entities {
+    /** Lists model paths in the `minecraft` namespace, including subdirectories and excluding `.json`. */
     static getEntityList(): Promise<string[]>;
     private static getModelFile;
+    /** Returns selectable geometry-layer names, or an empty list when the model is missing. */
     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[]>;
+    /**
+     * Loads the layers and textures to pass to {@link MineRenderScene.addEntity}.
+     * By default, selects `main`, unconditional passes, and passes enabled by `options.when`.
+     *
+     * @param modelKey - Dataset model, such as `new BasicAssetKey("minecraft", "zombie")`.
+     * @param textureKey - Texture override for the first selected layer.
+     * @param options - Layer selection, conditional passes, and per-layer texture overrides.
+     * @returns The selected model, or `undefined` when its dataset file is missing.
+     */
     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>>>;
+    /** Finds a fallback texture using the model path, its directory, and vanilla variant data. */
     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>>;
 }
+/** Selection settings passed as the third argument to {@link Entities.getEntity}. */
 interface EntityModelOptions {
+    /** Selects one geometry layer without dataset passes. `layers` takes precedence when supplied. */
     layer?: string;
-    /** Layer names in draw order; defaults to layer or "main". */
+    /** Layer names in draw order; an explicit selection draws exactly these layers and no dataset passes. */
     layers?: string[];
-    /** Per-layer texture overrides. The positional texture key applies to the first selected layer. */
+    /**
+     * 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>;
 }
 
+/** A glyph's source pixels and layout metrics. Glyphs without an image contribute spacing only. */
+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;
+}
+/** Character-to-glyph lookup assembled from the active resource-pack fonts. */
+interface BitmapFont {
+    glyphs: Map<string, BitmapGlyph>;
+}
+/** Loads Minecraft bitmap, space, and reference font providers for GUI text. */
+declare class Fonts {
+    /** Combines font definitions in source-priority order. Unsupported Unihex and TrueType providers are skipped. */
+    static get(key?: AssetKey | string): Promise<BitmapFont>;
+    private static relatedKey;
+    private static load;
+    private static bitmap;
+}
+
+/** Caller-supplied item-preview state passed to {@link Models.getMerged}. */
+interface ItemModelContext {
+    /** Context used by display-context selectors, overriding `properties`. Defaults to GUI. */
+    displayContext?: DisplayPosition | "none";
+    /** Explicit property overrides. Nodes with the same ID share one override, regardless of their parameters. */
+    properties?: Record<string, boolean | string | number>;
+    /** Supplied component JSON by ID. Item-registry defaults are not added; component selectors compare structural JSON values. */
+    components?: Record<string, unknown>;
+    /** Stack count, as a nonnegative integer. Defaults to 1; absent `max_stack_size` also defaults to 1. */
+    count?: number;
+    /** Item-model keys by reference-node ID, such as `minecraft:bundle/selected_item`. Unset references draw nothing. */
+    itemReferences?: Record<string, AssetKey>;
+}
+/** Loads and caches Java block/item models, including inherited geometry and textures. */
 declare class Models {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
+    /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
     static getItemList(): Promise<string[]>;
-    static loadAndMerge(key: AssetKey): Promise<Maybe<Model>>;
+    static loadAndMerge(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     private static getItemModel;
-    private static defaultItemModel;
+    private static contextIdentifier;
+    private static snapshotContext;
+    private static contextKey;
+    private static snapshotJson;
+    private static propertyValue;
+    private static selectItemModel;
+    /** Loads one model file without resolving its parents. Returns `undefined` when the file is missing. */
     static getRaw(key: AssetKey): Promise<Maybe<Model>>;
-    static getMerged(key: AssetKey): Promise<Maybe<Model>>;
-    static get(key: AssetKey): Promise<Maybe<Model>>;
+    /**
+     * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
+     * Item keys default to GUI context and a stack count of 1. Unresolved conditions are false and numeric properties are zero.
+     * Pass `context` to supply component values, property overrides, and item references for a preview.
+     * Composite items retain independently merged children in `ItemModel.parts`.
+     *
+     * @param key - Model key, for example `AssetKey.parse("models", "minecraft:item/diamond_sword")`.
+     */
+    static getMerged(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
+    /** Alias for {@link getMerged}. */
+    static get(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
+    /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
     static clearCache(): Promise<void>;
 }
 
+/** Resolves Minecraft display poses and applies them to model geometry. */
 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;
+    /** Transforms geometry in place and reverses triangle winding when the matrix reflects it. */
     static apply(geometry: BufferGeometry, matrix: Matrix4): void;
 }
 
+/** Resolves item-preview colors from vanilla tint definitions, stack components, and caller overrides. */
+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 componentField;
+    private static colorOrDefault;
+    private static componentColor;
+    private static rgb;
+}
+
+/** Identifies fully opaque cubes and maps neighbor visibility to model-local face masks. */
 declare class ModelCulling {
+    /** Rotates a world-direction bit mask into model space. Bits follow {@link CUBE_FACES}. */
     static toLocalMask(worldMask: number, rotation: Euler): number;
+    /** Whether a model fills one block with opaque faces and can hide adjacent block faces. */
     static isOpaqueFullCube(atlas: Maybe<TextureAtlas>): boolean;
 }
 
+/** Builds extruded item-model elements from sprite pixels, including edges around transparent regions. */
 declare class ModelGenerator {
     static readonly ITEM_LAYERS: string[];
     /**
@@ -825,37 +1324,66 @@ declare class ModelGenerator {
     static generateItemModel(imageData: Pick<ImageData$1, "width" | "height" | "data">, layer: string): ModelElement[];
 }
 
+/** Resolves Java model inheritance, with child elements and display poses overriding their parents. */
 declare class ModelMerger {
+    /** Loads the parent chain and returns a merged model without modifying the supplied definition. */
     static mergeWithParents(model: Model): Promise<Model>;
     protected static collectAllParents(model: Model): Promise<Model[]>;
 }
 
+/** Entity geometry and placement for a special item preview. Named part rotations use radians. */
+interface SpecialItemPart {
+    model: EntityModel;
+    transform: Matrix4;
+    rotations: Record<string, TripleArray>;
+    /** Absolute named-part positions in the entity model's coordinate system. */
+    positions?: Record<string, TripleArray>;
+    /** Colors for the entity model's named texture passes. */
+    tints?: Record<string, number>;
+}
+/** Loads entity geometry and texture passes for supported special item previews. */
+declare class SpecialItems {
+    /** Resolves the static entity parts drawn by a special item renderer, in model units. */
+    static getParts(special: SpecialItemRenderer, root?: string, components?: Record<string, unknown>): Promise<SpecialItemPart[]>;
+    /** An owned material with model-preview shading; its entity texture remains shared. */
+    static createMaterial(source: MeshBasicMaterial, shade: boolean): MeshBasicMaterial;
+}
+
+/** Block data passed to world setters. `type` is a namespaced ID such as `minecraft:oak_log`. */
 interface Block {
     type: string;
     properties?: BlockStateProperties;
     nbt?: any;
 }
 
+/** Selects block models from property values, including multipart conditions and weighted alternatives. */
 declare class BlockStateResolver {
+    /** Loads vanilla property defaults, falling back to preview values inferred from the blockstate file. */
     static defaults(blockState: BlockState): Promise<BlockStateProperties>;
+    /** Selects matching models. Supply `choose` to control selection within each alternatives array. */
     static select(blockState: BlockState, state: BlockStateProperties, choose?: (variants: BlockStateVariant | BlockStateVariant[]) => BlockStateVariant): BlockStateVariant[];
+    /** Returns matching model groups before choosing weighted alternatives. */
     static matching(blockState: BlockState, state: BlockStateProperties): (BlockStateVariant | BlockStateVariant[])[];
+    /** Selects a random alternative using positive integer weights, each defaulting to 1. */
     static choose(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
+    /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
     static rotation(variant: BlockStateVariant): Euler;
 }
 
+/** Supplies block-preview tint colors from block properties and the active resource pack. */
 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;
 }
 
+/** A model that owns reusable instance slots and exposes per-slot transforms to {@link InstanceReference}. */
 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;
@@ -866,6 +1394,10 @@ interface Instanceable {
 }
 declare function isInstanceable(obj: any): obj is Instanceable;
 
+/**
+ * Controls one placement of a shared model. Transform methods affect only this instance.
+ * After {@link removeFromScene} or {@link dispose}, accessing its transforms throws.
+ */
 declare class InstanceReference<T extends Instanceable> implements Transformable, Disposable {
     readonly instanceable: T;
     readonly index: number;
@@ -873,10 +1405,14 @@ declare class InstanceReference<T extends Instanceable> implements Transformable
     constructor(instanceable: T, index: number);
     nextInstance(): InstanceReference<SceneObject>;
     private get activeInstanceable();
+    /** Releases this placement's slot for reuse. Repeated calls have no effect. */
     removeFromScene(): void;
     dispose(): void;
     getMatrix(matrix?: Matrix4): Matrix4;
     setMatrix(matrix: Matrix4): void;
+    /** Hides or restores this placement while preserving its transform and allocated slot. */
+    setVisible(visible: boolean): void;
+    /** Updates the supplied transform components. Positions use scene units and rotations use radians. */
     setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
     setPosition(position: Vector3): void;
     getPosition(): Vector3;
@@ -887,13 +1423,18 @@ declare class InstanceReference<T extends Instanceable> implements Transformable
 }
 declare function isInstanceReference(obj: any): obj is InstanceReference<any>;
 
+/** Shared settings passed to scene-object constructors or the scene's `addModel` and `addBlock` methods. */
 interface SceneObjectOptions {
     wireframe: boolean;
+    /** Combines compatible model elements into one geometry. */
     mergeMeshes: boolean;
+    /** Allows compatible models to share geometry through instance references. */
     instanceMeshes: boolean;
+    /** Initial instance capacity. Buffers grow when more placements are added. */
     maxInstanceCount: number;
 }
 
+/** Builds render geometry from a merged Java model. Create it through {@link MineRenderScene.addModel}. */
 declare class ModelObject extends SceneObject {
     readonly originalModel: Model;
     readonly isModelObject: true;
@@ -903,6 +1444,8 @@ declare class ModelObject extends SceneObject {
     private atlasMaterial?;
     private atlasTexture?;
     private unsubscribeAtlas?;
+    private readonly specialMaterials;
+    private readonly geometries;
     blockParent: Maybe<BlockObject>;
     private meshesCreated;
     constructor(originalModel: Model, options?: Partial<ModelObjectOptions>);
@@ -917,26 +1460,31 @@ declare class ModelObject extends SceneObject {
     removeInstanceAt(index: number): void;
     disposeAndRemoveAllChildren(): void;
 }
+/** Model settings passed to `scene.addModel(model, options)` or the ModelObject constructor. */
 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. */
+    /** sRGB 0xRRGGBB colors by face tint index, overriding automatic item or block preview colors. */
     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;
 
+/** Shares initialized model objects by cache key and allocates references to their placements. */
 declare class InstanceManager {
     readonly isInstanceManager: true;
     protected readonly instanceCache: {
         [key: string]: Promise<InstanceReference<SceneObject>>;
     };
     constructor();
+    /** Allocates a new placement of a cached model, or returns `undefined` if the key is unknown. */
     get<T extends SceneObject>(key: string): Promise<Maybe<InstanceReference<T>>>;
+    /** Allocates a placement, calling the supplier once when the shared model is first needed. */
     getOrCreate<T extends SceneObject>(key: string, supplier: () => T | Promise<T>): Promise<InstanceReference<T>>;
+    /** Forgets cached models without disposing them or releasing their existing placements. */
     reset(): void;
 }
 declare function isInstanceManager(obj: any): obj is InstanceManager;
@@ -974,6 +1522,14 @@ declare class SkinObject extends SceneObject {
     init(): Promise<void>;
     protected removeMeshes(): void;
     protected createMeshes(): void;
+    /**
+     * Loads a skin texture, detecting slim arms and legacy layouts by default.
+     * To override detection, set `slim` or `legacy` in the options passed to
+     * `new SkinObject(options)` or `scene.addSkin(src, options)`.
+     * Use {@link setSlim} or {@link setLegacy} to change these settings later.
+     *
+     * @param src - URL of the skin texture.
+     */
     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>;
@@ -985,22 +1541,101 @@ declare class SkinObject extends SceneObject {
     dispose(): void;
     protected getBoxGeometry(part: SkinPart): BoxGeometry;
 }
+/** Player settings passed to `new SkinObject(options)` or `scene.addSkin(src, options)`. */
 interface SkinObjectOptions extends SceneObjectOptions {
+    /** Forces slim (`true`) or classic (`false`) arms. Omit it to detect the model from the texture. */
     slim?: boolean;
+    /** Forces the legacy (`true`) or modern (`false`) texture layout. Omit it to detect the layout. */
     legacy?: boolean;
 }
 
+/** Playback settings passed to {@link EntityObject.playAnimation}, {@link EntityObject.playAnimations}, or {@link EntityAnimationPlayer.play}. */
+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;
+    /** Applies the pose at an absolute playback time. Returns `false` when no clip is active. */
+    setTime(seconds: number): boolean;
+    /** Advances playback by elapsed seconds multiplied by the speed passed to {@link play}. */
+    advance(deltaSeconds: number): boolean;
+    private apply;
+}
+
+/** Renders selected entity layers as named part groups. Create it through {@link MineRenderScene.addEntity}. */
 declare class EntityObject extends SceneObject {
     readonly entity: EntityModel;
     readonly isEntityObject: true;
     static readonly DEFAULT_OPTIONS: EntityObjectOptions;
     readonly options: EntityObjectOptions;
     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;
+    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;
+    /** Finds a selected draw by its layer key, such as `main` or `main#2`, or returns `undefined`. */
     getLayerGroup(name: string): Maybe<Object3D>;
+    /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
     getGroupByName(name: string, layerName?: string): Maybe<Object3D>;
+    /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
     getMeshByName(name: string, layerName?: string): Maybe<Mesh>;
     private get entityLayers();
     private getTextureKey;
@@ -1009,23 +1644,99 @@ declare class EntityObject extends SceneObject {
     private createPart;
     protected applyTextures(): Promise<void>;
 }
+/** Render settings passed to `scene.addEntity(entity, options)` or the EntityObject constructor. */
 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;
 
-/** A texture layer in GUI pixels. Later layers draw above earlier layers. */
-interface GuiLayer {
+/** Text appearance set on a GUI text layer or overridden by an individual text run. */
+interface GuiTextStyle {
+    /** sRGB 0xRRGGBB; defaults to white. */
+    color?: number;
+    bold?: boolean;
+    italic?: boolean;
+}
+/** A text segment with optional style overrides within {@link GuiText}. */
+interface GuiTextRun extends GuiTextStyle {
+    text: string;
+}
+/** Literal text, or styled runs. Newlines are preserved. */
+type GuiText = string | readonly GuiTextRun[];
+/** Text layout settings set on a GUI text layer or passed to {@link layoutGuiText}. */
+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;
+}
+/** One measured glyph and its position in GUI pixels, produced by {@link layoutGuiText}. */
+interface PositionedGuiGlyph {
+    character: string;
+    glyph?: BitmapGlyph;
+    x: number;
+    y: number;
+    advance: number;
+    style: Required<GuiTextStyle>;
+}
+/** Measured glyphs, line widths, and overall dimensions in GUI pixels. */
+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;
-    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. */
+    /** Output size; defaults to native texture/text dimensions, and [16, 16] for items. */
     size?: [number, number];
 }
+/** A texture layer for {@link MineRenderScene.addGui}. Uncropped textures use their `.mcmeta` scaling rules. */
+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];
+}
+/** An item preview in a 16×16 GUI slot by default, with optional tint overrides. */
+interface GuiItemLayer extends GuiLayerLayout {
+    /** Model key, such as minecraft:item/stone; uses the model's GUI display pose. */
+    item: AssetKey | string;
+    /** Supplied item state. GUI layers always select models in the GUI display context. */
+    context?: Omit<ItemModelContext, "displayContext">;
+    /** sRGB 0xRRGGBB colors by face tint index, overriding the item's automatic preview colors. */
+    tints?: Record<number, number>;
+}
+/** A bitmap-text layer. Set font, wrapping, and style directly on the layer object. */
+interface GuiTextLayer extends GuiLayerLayout, GuiTextOptions {
+    text: GuiText;
+}
 
+/**
+ * Renders ordered texture, item, and text layers. Create it through {@link MineRenderScene.addGui}.
+ * GUI coordinates grow right and down, with one pixel equal to one scene unit.
+ */
 declare class GuiObject extends SceneObject {
     readonly textureLayers: readonly GuiLayer[];
     readonly isGuiObject: true;
@@ -1033,16 +1744,20 @@ declare class GuiObject extends SceneObject {
     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;
 }
+/** Scene-object settings for `scene.addGui(layers, options)`. GUI objects disable instancing and mesh merging. */
 interface GuiObjectOptions extends SceneObjectOptions {
 }
 declare function isGuiObject(obj: any): obj is GuiObject;
 
+/** A Three.js scene that initializes Minecraft objects and tracks changes that need a redraw. */
 declare class MineRenderScene extends Scene {
     readonly isMineRenderScene: true;
     static readonly DEFAULT_OPTIONS: MineRenderSceneOptions;
@@ -1056,18 +1771,48 @@ declare class MineRenderScene extends Scene {
     add(...objects: Object3D[]): this;
     remove(...objects: Object3D[]): this;
     private updateObjectRegistration;
+    /** Initializes each object before attaching it to the scene. */
     initAndAdd(...object: SceneObject[]): Promise<this>;
     addSceneObject<A extends BasicMinecraftAsset, T extends SceneObject, O extends SceneObjectOptions>(asset: A, objectSupplier: () => T | Promise<T>, _options?: Partial<O>, parent?: Object3D): Promise<T | InstanceReference<T>>;
+    /**
+     * Adds a model loaded with {@link Models.getMerged}.
+     * Set `options.instanceMeshes` to `false` to create a separate ModelObject.
+     *
+     * @param parent - Object to attach the model to. Defaults to this scene.
+     * @returns The model, or a reference to one placement of a shared model.
+     */
     addModel(model: Model, options?: Partial<ModelObjectOptions>, parent?: Object3D): Promise<ModelObject | InstanceReference<ModelObject>>;
+    /**
+     * Adds the models selected by a blockstate loaded with {@link BlockStates.get}.
+     * Set `options.initialState` to choose block properties such as `facing` or `axis`.
+     * Use the returned object's `setPosition` method to move all of its model parts.
+     */
     addBlock(blockState: BlockState, options?: Partial<BlockObjectOptions>, parent?: Object3D): Promise<BlockObject | InstanceReference<BlockObject>>;
+    /**
+     * Loads a skin and adds an initialized player model.
+     *
+     * @param skin - Texture URL, such as one returned by {@link Skins.fromUuidOrUsername}.
+     * Omit it to assign a texture later with {@link SkinObject.setSkinTexture}.
+     * @param options - Player settings, including `slim` and `legacy` detection overrides.
+     * @param parent - Object to attach the player to. Defaults to this scene.
+     */
     addSkin(skin?: string, options?: Partial<SkinObjectOptions>, parent?: Object3D): Promise<SkinObject>;
+    /** Adds an entity loaded with {@link Entities.getEntity}, using its selected layers and textures. */
     addEntity(entity: EntityModel, options?: Partial<EntityObjectOptions>, parent?: Object3D): Promise<EntityObject | InstanceReference<EntityObject>>;
+    /**
+     * Adds GUI layers in draw order. One GUI pixel equals one scene unit.
+     * Layer positions start at the top left, with positive GUI y pointing down.
+     */
     addGui(layers: readonly GuiLayer[], options?: Partial<GuiObjectOptions>, parent?: Object3D): Promise<GuiObject>;
 }
 interface MineRenderSceneOptions {
 }
 declare function isMineRenderScene(obj: any): obj is MineRenderScene;
 
+/**
+ * Base for renderable Minecraft objects, with named parts and optional shared instances.
+ * Use {@link notifyDirty} after changing a part directly so the renderer redraws it.
+ */
 declare class SceneObject extends Object3D<Object3DEventMap & {
     change: {};
 }> implements Disposable, Instanceable, Transformable {
@@ -1081,21 +1826,25 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     protected instanceMesh?: InstancedMesh;
     private readonly instanceReferences;
     private readonly freeInstanceIndices;
+    private readonly hiddenInstanceMatrices;
     constructor(options?: Partial<SceneObjectOptions>);
     set scene(scene: MineRenderScene);
     get scene(): MineRenderScene;
     init(): Promise<void>;
+    /** Marks ancestor scenes for redraw and emits a `change` event. */
     notifyDirty(): void;
     protected createAndAddGroup(name?: string, x?: number, y?: number, z?: number, offsetAxis?: Axis, offset?: number): Object3D;
     protected createGroup(name?: string, x?: number, y?: number, z?: number, offsetAxis?: Axis, offset?: number): Object3D;
     /**
-     * Get a group by its name
+     * Finds a named part, such as `head`, without the internal `group:` prefix.
+     * Returns `undefined` when the group does not exist.
      */
     getGroupByName(name: string): Maybe<Object3D>;
     /**
-     * Toggle visibility of a group
-     * @param name name of the group
-     * @param visible set the visibility directly, if not set toggles it
+     * Changes a named group's visibility and requests a redraw.
+     * @param name - Part name without the `group:` prefix.
+     * @param visible - Visibility to assign. Omit it to toggle the current value.
+     * @returns The resulting visibility, or `false` if the group does not exist.
      */
     toggleGroupVisibility(name: string, visible?: boolean): boolean;
     protected addOrReplaceMesh(mesh: Mesh, parent: Object3D, name?: string): void;
@@ -1103,13 +1852,14 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     protected createMesh(name?: string, geometry?: BufferGeometry, material?: Material | Material[], offsetAxis?: Axis, offset?: number): Mesh;
     protected createInstancedMesh(name: Maybe<string>, geometry: BufferGeometry, material: Material | Material[], count: number): InstancedMesh;
     /**
-     * Get a mesh by its name
+     * Finds a named mesh without the internal `mesh:` prefix, or returns `undefined`.
      */
     getMeshByName(name: string): Maybe<Mesh>;
     /**
-     * Toggle visibility of a mesh
-     * @param name name of the mesh
-     * @param visible set the visibility directly, if not set toggles it
+     * Changes a named mesh's visibility and requests a redraw.
+     * @param name - Mesh name without the `mesh:` prefix.
+     * @param visible - Visibility to assign. Omit it to toggle the current value.
+     * @returns The resulting visibility, or `false` if the mesh does not exist.
      */
     toggleMeshVisibility(name: string, visible?: boolean): boolean;
     iterateAllMeshes(cb: (mesh: Mesh) => void): void;
@@ -1117,8 +1867,10 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     protected _getBoxGeometryFromElement(element: ModelElement): BoxGeometry;
     protected _getBoxGeometryForDimensionsAndUv(width: number, height: number, depth: number, uv: number[]): BoxGeometry;
     get isInstanced(): boolean;
+    /** Number of live placements, excluding released instance slots. */
     get instanceCounter(): number;
     protected constructInstanceReference(i: number): InstanceReference<SceneObject>;
+    /** Allocates a placement of this instanced object, reusing a released slot when available. */
     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>>;
@@ -1128,6 +1880,7 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     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;
@@ -1135,37 +1888,48 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     getRotationAt(index: number, euler?: Euler): Euler;
     setScaleAt(index: number, scale: Vector3): void;
     getScaleAt(index: number, vector?: Vector3): Vector3;
+    /** Updates supplied transform components. For a shared model, affects every live instance. */
     setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
+    /** Sets position in scene units. For a shared model, updates every live instance. */
     setPosition(position: Vector3): void;
     getPosition(): Vector3;
+    /** Sets rotation in radians. For a shared model, updates every live instance. */
     setRotation(rotation: Euler): void;
     getRotation(): Euler;
+    /** Sets scale factors. For a shared model, updates every live instance. */
     setScale(scale: Vector3): void;
     getScale(): Vector3;
     protected toggleObjectVisibility(object?: Object3D, visible?: boolean): boolean;
     dispose(): void;
+    /** Releases instance slots and removes children, disposing children that implement Disposable. */
     disposeAndRemoveAllChildren(): void;
+    /** Detaches the object from its parent and requests a redraw. */
     removeFromScene(): void;
 }
 declare function isSceneObject(obj: any): obj is SceneObject;
 
 type FluidKind = "water" | "lava";
+/** Fluid contained in a block and whether the block's ordinary model is also drawn. */
 interface BlockFluidState {
     kind: FluidKind;
     level: number;
     renderModel: boolean;
 }
+/** Finds water or lava from the block ID and properties, including waterlogged blocks and aquatic plants. */
 declare function getBlockFluidState(key?: AssetKey, state?: BlockStateProperties): BlockFluidState | undefined;
 declare function getFluidKind(key?: AssetKey, state?: BlockStateProperties): FluidKind | undefined;
+/** A neighboring cell's fluid level and full-cube occlusion state. */
 interface FluidSample {
     fluid?: FluidKind;
     level?: number;
     solid?: boolean;
 }
+/** Reads cells at integer block offsets relative to the fluid being rendered, with `(0, 0, 0)` as the center. */
 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;
 
+/** Controls the model parts selected by a blockstate. Create it through {@link MineRenderScene.addBlock}. */
 declare class BlockObject extends SceneObject {
     readonly blockState: BlockState;
     readonly isBlockObject: true;
@@ -1183,16 +1947,31 @@ declare class BlockObject extends SceneObject {
     private _fluidKey?;
     private _fluidSampler?;
     private _fluidModel?;
+    private _entities;
+    private _entityPlacement;
+    private _entityGeneration;
     constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
     removeFromScene(): void;
     private clearModels;
     private removeModels;
+    private removeEntities;
+    /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
+    get blockEntities(): readonly EntityObject[];
+    /** 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>;
+    /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
     get state(): {
         [key: string]: string;
     };
@@ -1203,10 +1982,17 @@ declare class BlockObject extends SceneObject {
     nextInstance(): InstanceReference<SceneObject>;
     protected mapStateToVariant(state: BlockStateProperties): Promise<BlockStateVariant[]>;
     recreateModels(): Promise<void>;
+    private hasGeometry;
     protected getSingleVariant(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
     protected createAVariant(variants: BlockStateVariant | BlockStateVariant[], instanceInfo: Matrix4[]): Promise<void>;
     protected createVariant(variant: BlockStateVariant): Promise<ModelObject | InstanceReference<ModelObject>>;
+    /** Clears selected properties and rebuilds models without reapplying property defaults. */
     resetState(): Promise<void>;
+    /**
+     * Updates properties and rebuilds the selected models.
+     * Accepts `"facing=north,open=true"`, a property object, or a key and value.
+     * Properties omitted from the call keep their current values.
+     */
     setState(string: string): any;
     setState(state: BlockStateProperties): any;
     setState(key: string, value: string): any;
@@ -1216,7 +2002,9 @@ declare class BlockObject extends SceneObject {
     setMatrixAt(index: number, matrix: Matrix4): void;
     setPosition(position: Vector3): void;
 }
+/** Block settings passed to `scene.addBlock(blockState, options)` or the BlockObject constructor. */
 interface BlockObjectOptions extends ModelObjectOptions {
+    /** Loads vanilla property defaults before applying `initialState`. Defaults to `true`. */
     applyDefaultState: boolean;
     /** Properties applied before model creation, overriding defaults when applyDefaultState is enabled. */
     initialState?: BlockStateProperties;
@@ -1228,6 +2016,7 @@ declare function sampleFluid(kind: FluidKind, sample: FluidSampler): {
     key: string;
     sample: FluidSampler;
 };
+/** Renders water or lava with neighbor-dependent surfaces and animated still/flow textures. */
 declare class FluidModelObject extends ModelObject {
     readonly kind: FluidKind;
     private readonly sample;
@@ -1238,28 +2027,50 @@ declare class FluidModelObject extends ModelObject {
     disposeAndRemoveAllChildren(): void;
 }
 
+/** Parsed blocks and entity data for {@link MineRenderWorld.placeMultiBlock}. Dimensions and positions use blocks. */
 interface MultiBlockStructure {
     readonly size: TripleArray;
     readonly blocks: MultiBlockBlock[];
     readonly dataVersion?: number;
     readonly entities?: MultiBlockEntity[];
 }
+/** Preserved entity position and NBT. World placement does not create a render object for it. */
 interface MultiBlockEntity {
     position: TripleArray;
     blockPosition?: TripleArray;
     nbt: unknown;
 }
+/** Block data and its position within a parsed structure. */
 interface MultiBlockBlock extends Block {
     position: TripleArray;
 }
 
+/** Converts legacy Alpha `.schematic` NBT with numeric block IDs into modern block names and properties. */
 declare class SchematicParser {
-    static parse(nbt: NBT): 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>>, options?: SchematicParserOptions): Promise<MultiBlockStructure>;
+}
+interface SchematicParserOptions {
+    /**
+     * Ignores Materials, tries metadata 0 for unmapped states, and skips unknown IDs. Defaults to false.
+     * Dimensions, arrays, and entity data remain validated.
+     */
+    lenient?: boolean;
 }
 
+/** Converts Java structure NBT into blocks and preserved entity data for world placement. */
 declare class StructureParser {
+    /**
+     * Parses decoded NBT, omitting air blocks.
+     * @param _nbt - Structure data decoded by {@link NBTHelper.fromBuffer}.
+     * @param paletteIndex - Palette to select when the structure has several. Defaults to 0.
+     */
     static parse(_nbt: NBT, paletteIndex?: number): Promise<MultiBlockStructure>;
 }
+/** Tagged NBT fields used by Java structure files. */
 interface StructureNBT {
     DataVersion?: {
         type: "int";
@@ -1355,20 +2166,27 @@ interface BlockEntry {
     };
 }
 
+/** Decodes Named Binary Tag (NBT) data for structure and world parsers. */
 declare class NBTHelper {
+    /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
     static fromBuffer(data: Uint8Array | ArrayBuffer, format?: NBTFormat): Promise<NBTAsset>;
 }
+/** Decoded NBT with the source format and parser metadata attached. */
 interface NBTAsset extends MinecraftAsset, NBT {
     format?: NBTFormat;
     metadata?: Metadata;
     compression?: "gzip" | "none";
 }
 
+/** Configures a hosted asset request and converts its response into an asset. */
 interface ResponseParser<T extends MinecraftAsset> {
+    /** Sets response decoding or other request options before the request starts. */
     config(request: RequestConfig): any;
+    /** Returns `undefined` to permit source fallback, or throws to report a parse failure. */
     parse(response: RequestResponse): Maybe<T> | Promise<Maybe<T>>;
 }
 
+/** Loads assets over HTTP from a Minecraft directory tree rooted at the constructor's URL. */
 declare class HostedAssetSource extends AssetSource {
     static readonly MODEL: ResponseParser<Model>;
     static readonly BLOCKSTATE: ResponseParser<BlockState>;
@@ -1378,11 +2196,16 @@ declare class HostedAssetSource extends AssetSource {
     static readonly LIST: ResponseParser<ListAsset>;
     static readonly JSON: ResponseParser<any>;
     static readonly PARSER_MAP: Map<AssetParser, ResponseParser<any>>;
+    /** Retries missing assets with the `minecraft` namespace and default root. Other failures reject. */
     loadOrRetryWithDefaults<T extends MinecraftAsset>(key: AssetKey, parser: ResponseParser<T>): Promise<Maybe<T>>;
     protected load<T extends MinecraftAsset>(key: AssetKey, parser: ResponseParser<T>): Promise<Maybe<T>>;
     assetBasePath(key: AssetKey): string;
     private readonly _root;
     private readonly _options;
+    /**
+     * Creates a hosted source for {@link AssetLoader.addSource}.
+     * Set `options.retryDefaults` to `false` to restrict lookups to the requested namespace and root.
+     */
     constructor(root: string, options?: Partial<HostedAssetSourceOptions>);
     get root(): string;
     get cacheId(): string;
@@ -1393,38 +2216,80 @@ interface HostedAssetSourceOptions {
     retryDefaults: boolean;
 }
 
+/** A resource-pack ZIP entry, with its archive-relative path and lazily extracted bytes. */
 interface ArchiveEntry {
     filename: string;
     directory: boolean;
     getData(): Promise<Blob>;
 }
 
+/** Supplies resource-pack entries to {@link ArchiveAssetSource}. */
 interface ArchiveProxy {
     /** Identifies the archive's content across sessions; undefined when it cannot be identified. */
     readonly id?: string;
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
+/** A resource-pack format; a number selects minor version zero. */
+type PackFormat = number | readonly [number, number];
+declare class PackMetadata {
+    private readonly overlays;
+    private readonly filters;
+    readonly hasOverlays: boolean;
+    private constructor();
+    static parse(value: unknown): PackMetadata;
+    /** Returns applicable directories in lookup order, with the last declared overlay first. */
+    overlayDirectories(target: PackFormat): string[];
+    blocks(namespace: string, path: string): boolean;
+}
+
+interface ArchiveAssetSourceOptions {
+    /** Target resource-pack format. Omit to look up the version selected by AssetLoader.setVersion. */
+    resourcePackFormat?: PackFormat;
+    /** Target data-pack format, used for assets under data/. Omit to look up the selected version. */
+    dataPackFormat?: PackFormat;
+}
+/** Loads assets from resource-pack ZIP entries. Register it with {@link AssetLoader.addSource}. */
 declare class ArchiveAssetSource extends AssetSource implements ArchiveProxy {
     readonly _archiveProxy: ArchiveProxy;
-    constructor(archiveProxy: ArchiveProxy);
-    static blob(blob: Blob): ArchiveAssetSource;
+    private readonly options;
+    private entries?;
+    private metadata?;
+    constructor(archiveProxy: ArchiveProxy, options?: ArchiveAssetSourceOptions);
+    /** Creates a browser ZIP source from a Blob or File. */
+    static blob(blob: Blob, options?: ArchiveAssetSourceOptions): ArchiveAssetSource;
     get cacheId(): Maybe<string>;
     getEntries(): Promise<ArchiveEntry[]>;
     getEntry(path: string): Promise<Maybe<ArchiveEntry>>;
+    private getMetadata;
+    blocks(key: AssetKey): Promise<boolean>;
     get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
     protected load<T extends MinecraftAsset>(key: AssetKey, parser: ResponseParser<T>): Promise<Maybe<T>>;
     assetBasePath(key: AssetKey): string;
 }
 
+/** Reads a resource-pack ZIP from a browser Blob or File for {@link ArchiveAssetSource}. */
 declare class BrowserArchiveProxy implements ArchiveProxy {
     readonly _blob: Blob;
     readonly _reader: ZipReader<Blob>;
     readonly id?: string;
+    /**
+     * Opens a ZIP for asset lookup.
+     * @param id - Cache identity for this content. Change it when the pack changes.
+     * A File supplies an identity from its name, size, and modification time when omitted.
+     */
     constructor(blob: Blob, id?: string);
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
+declare class PackFormats {
+    private static readonly versions;
+    /** Resolves pack formats from Mojang's client metadata hosted on assets.mcasset.cloud. */
+    static get(version: string, type: "assets" | "data"): Promise<PackFormat>;
+    private static load;
+}
+
+/** Bedrock client-entity resource references. This schema does not provide a Bedrock renderer. */
 interface BedrockEntityDescription {
     identifier: string;
     materials: {
@@ -1445,6 +2310,7 @@ interface BedrockEntityDescription {
     enable_attachables?: boolean;
 }
 
+/** Bedrock client-entity JSON schema, provided for typing only. */
 interface BedrockEntityFile {
     format_version: string;
     "minecraft:client_entity": {
@@ -1452,6 +2318,7 @@ interface BedrockEntityFile {
     };
 }
 
+/** Bedrock bone-and-cube geometry schema, provided for typing only. */
 interface BedrockGeometry {
     visible_bounds_width: number;
     visible_bounds_height: number;
@@ -1479,11 +2346,13 @@ interface BedrockCube {
     inflate?: number;
 }
 
+/** A versioned Bedrock JSON container for named geometry definitions. */
 interface BedrockGeometryFile {
     format_version: string;
     [key: string]: BedrockGeometry | any;
 }
 
+/** Shared in-memory caches for loaded assets and render resources. Persistent stores are managed separately. */
 declare class Caching {
     static readonly rawImageCache: AsyncLoadingCache<CacheKey, ImageInfo>;
     static readonly imageDataCache: AsyncLoadingCache<CacheKey, ImageData>;
@@ -1504,9 +2373,14 @@ declare class Caching {
     static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
     static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
     static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
+    static readonly entityAnimationCache: AsyncLoadingCache<CacheKey, EntityAnimationFile>;
+    static readonly blockEntityIndexCache: AsyncLoadingCache<CacheKey, BlockEntityIndex>;
+    static readonly fontCache: AsyncLoadingCache<CacheKey, BitmapFont>;
+    static readonly bannerPatternCache: AsyncLoadingCache<CacheKey, BannerPattern>;
     private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
+    /** Invalidates in-memory entries so later lookups reload them. Persisted entries are retained. */
     static clear(): void;
     /**
      * Clears every cache and stops its expiry timer.
@@ -1521,11 +2395,13 @@ declare class Caching {
 /** Copies the nontransparent bounds without resizing the source; empty images become one transparent pixel. */
 declare function trimCanvas(source: CompatCanvas): CompatCanvas;
 
+/** Reports invalid Minecraft data or an unsupported rendering operation. */
 declare class MineRenderError extends Error {
     constructor(msg: any);
     get name(): string;
 }
 
+/** Settings passed to {@link Renderer.toGLTF} or {@link SceneExporter.toGLTF}. */
 interface SceneGLTFExportOptions {
     /** Returns a GLB ArrayBuffer instead of a glTF object. */
     binary?: boolean;
@@ -1545,10 +2421,116 @@ declare class SceneExporter {
     static toGLTF(root: Object3D, options?: SceneGLTFExportOptions): Promise<Record<string, any> | ArrayBuffer>;
 }
 
+/** Container coordinates in GUI pixels. Crops refer to vanilla's 256×256 sheets; {@link GuiHelper.container} scales them for resource packs. */
+declare const GUI_CONTAINER_LAYOUTS: {
+    readonly generic_54: {
+        readonly texture: "minecraft:gui/container/generic_54";
+        readonly crop: readonly [0, 0, 176, 222];
+        readonly slotOrigin: readonly [8, 18];
+        readonly slotOffset: readonly [18, 18];
+        readonly rowSize: 9;
+        readonly slotCount: 54;
+    };
+    readonly crafting_table: {
+        readonly texture: "minecraft:gui/container/crafting_table";
+        readonly crop: readonly [0, 0, 176, 166];
+        readonly slotOrigin: readonly [30, 17];
+        readonly slotOffset: readonly [18, 18];
+        readonly rowSize: 3;
+        readonly slotCount: 9;
+        readonly resultPosition: readonly [124, 35];
+    };
+};
+type GuiContainerType = keyof typeof GUI_CONTAINER_LAYOUTS;
+type GuiBossBarColor = "pink" | "blue" | "red" | "green" | "yellow" | "purple" | "white";
+type GuiBookButtonState = "hidden" | "normal" | "hover";
+/** Creates GUI positions and layer lists for {@link MineRenderScene.addGui}. */
 declare class GuiHelper {
-    static inventorySlot(slot: number | [number, number], origin?: [number, number], offset?: [number, number], rowSize?: number): [number, number];
+    /**
+     * Creates a 182×5 boss bar using the active resource pack. Finite progress is clamped to 0–1.
+     * The fill crops the source image; explicit crops do not apply `.mcmeta` sprite scaling.
+     */
+    static bossBar(options?: GuiBossBarOptions): Promise<GuiLayer[]>;
+    /**
+     * Creates a 192×192 book page with optional arrows and supplied text. Buttons are hidden by default.
+     * Callers choose the page content and button states; this helper does not paginate or handle clicks.
+     */
+    static book(options?: GuiBookOptions): Promise<GuiLayer[]>;
+    /** Creates a container background. Use {@link GUI_CONTAINER_LAYOUTS} with {@link inventorySlot} to place its items. */
+    static container(type: GuiContainerType, position?: [number, number]): Promise<GuiLayer[]>;
+    private static validatePosition;
+    private static cropTexture;
+    /** Sizes a tooltip around supplied text; the first entry is its title. */
+    static tooltip(lines: readonly GuiText[], options?: GuiTooltipOptions): Promise<GuiLayer[]>;
+    /**
+     * Calculates a slot's top-left position in GUI pixels.
+     * @param slot - Zero-based slot index, or `[column, row]`.
+     * @param origin - Position of the first slot.
+     * @param offset - Horizontal and vertical spacing between slot origins, in pixels.
+     * @param rowSize - Slots per row when `slot` is an index.
+     */
+    static inventorySlot(slot: number | readonly [number, number], origin?: readonly [number, number], offset?: readonly [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[];
+}
+/** Settings passed to {@link GuiHelper.bossBar}. */
+interface GuiBossBarOptions {
+    /** Vanilla sprite color. Defaults to `pink`. */
+    color?: GuiBossBarColor;
+    /** Fill from 0 to 1, rounded to vanilla's discrete pixel width. Defaults to 1. */
+    progress?: number;
+    /** Top-left position in GUI pixels. Defaults to `[0, 0]`. */
+    position?: [number, number];
+}
+/** Settings passed to {@link GuiHelper.book}. Text defaults to black, unshadowed, and wrapped at 114 pixels. */
+interface GuiBookOptions extends GuiTextOptions {
+    /** Top-left position of the book background in GUI pixels. Defaults to `[0, 0]`. */
+    position?: [number, number];
+    previous?: GuiBookButtonState;
+    next?: GuiBookButtonState;
+    /** Content for one page. The caller keeps it within the 128-pixel text height. */
+    text?: GuiText;
+}
+/** Settings passed to {@link GuiHelper.tooltip}. Its default `lineHeight` is 10 GUI pixels. */
+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;
+};
+/** An item, tag, or alternatives list. Tags and alternatives need `GuiRecipeOptions.resolveIngredient`. */
+type GuiRecipeIngredient = GuiRecipeIngredientValue | readonly GuiRecipeIngredientValue[];
+/** Shaped or shapeless crafting data accepted by {@link GuiHelper.recipe}. */
+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;
+    };
+};
+/** Settings passed as the second argument to {@link GuiHelper.recipe}. */
+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);
 
@@ -1626,6 +2608,11 @@ declare class MapControls extends OrbitControls {
     constructor(object: Camera, domElement?: HTMLElement);
 }
 
+/**
+ * Renders a Minecraft scene with a camera and an optional effects composer.
+ * Requires a browser DOM and WebGL. Call {@link appendTo} to attach the canvas,
+ * then {@link start} to render scene changes.
+ */
 declare class Renderer implements Disposable {
     static readonly DEFAULT_OPTIONS: RendererOptions;
     readonly options: RendererOptions;
@@ -1641,7 +2628,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;
@@ -1653,16 +2643,26 @@ declare class Renderer implements Disposable {
     protected createControls(): Maybe<OrbitControls>;
     init(): void;
     get element(): Maybe<HTMLElement>;
+    /** Attaches the canvas to an element and sizes it to that element's dimensions. */
     appendTo(element: HTMLElement): void;
     /**
      * Redraws when the dispatcher emits the selected event. Registering the same pair twice has no effect.
      * The renderer removes its listener on disposal; the caller retains ownership of the dispatcher.
      */
     registerEventDispatcher(dispatcher: EventDispatcher<any>, changeEvent?: string): void;
+    /** Updates the camera and canvas size. Width and height are in CSS pixels. */
     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;
+    /** Starts or resumes the animation loop and registered frame callbacks. */
     start(): void;
+    /** Pauses rendering and frame callbacks. Call {@link start} to resume. */
     stop(): void;
     /**
      * Stops rendering and releases owned resources. Repeated calls have no effect, and a disposed
@@ -1678,8 +2678,11 @@ declare class Renderer implements Disposable {
      * MIME type support and lossy quality (0–1) follow the canvas encoder.
      */
     toImage(trim?: boolean, mime?: string, quality?: number): string;
+    /** Exports visible scene meshes as OBJ text, without texture images. */
     toObj(): string;
+    /** Exports visible scene meshes as PLY. Set `options.binary` for an ArrayBuffer. */
     toPLY(options?: PLYExporterOptions): string | ArrayBuffer;
+    /** Exports a static textured scene in the browser. Set `options.binary` for GLB output. */
     toGLTF(options?: SceneGLTFExportOptions): Promise<Record<string, any> | ArrayBuffer>;
     protected get attachedToBody(): boolean;
     protected get viewWidth(): number;
@@ -1691,6 +2694,16 @@ declare class Renderer implements Disposable {
     /** Renderer-owned controls, or undefined when disabled at construction or after disposal. */
     get controls(): Maybe<OrbitControls>;
 }
+/** Timing passed to callbacks registered with {@link Renderer.onFrame}. */
+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;
+}
+/** A synchronous scene update registered with {@link Renderer.onFrame}. */
+type FrameCallback = (frame: RendererFrame) => void;
+/** Settings for `new Renderer(options)`. Omitted values use {@link Renderer.DEFAULT_OPTIONS}. */
 interface RendererOptions {
     camera: CameraOptions;
     render: RenderOptions;
@@ -1698,12 +2711,14 @@ interface RendererOptions {
     controls?: ControlsOptions;
     debug: DebugOptions;
 }
+/** Camera settings passed as `camera` in the Renderer constructor options. Positions use scene units. */
 interface CameraOptions {
     type: "perspective" | "orthographic";
     near: number;
     far: number;
     perspective: {
         aspect: undefined | number;
+        /** Vertical field of view in degrees. */
         fov: number;
     };
     orthographic: {
@@ -1715,6 +2730,7 @@ interface CameraOptions {
     position: Vector3 | TripleArray;
     lookingAt: Vector3 | TripleArray;
 }
+/** Canvas and draw-loop settings passed as `render` in the Renderer constructor options. */
 interface RenderOptions {
     /** Maximum draw rate (60 by default); zero or a negative value disables the limit. */
     fpsLimit: number;
@@ -1723,20 +2739,29 @@ interface RenderOptions {
     stats: boolean;
     antialias: boolean;
     shade: boolean;
+    /** Resizes to the attached element when the browser window resizes. */
     autoResize: boolean;
+    /** Draws even when the scene is unchanged, while still respecting `fpsLimit`. */
     renderAlways: boolean;
 }
+/** Effects settings passed as `composer` in the Renderer constructor options. */
 interface ComposerOptions {
     enabled: boolean;
 }
+/** Set `controls: { enabled: true }` in the Renderer constructor to create owned OrbitControls. */
 interface ControlsOptions {
     enabled: boolean;
 }
+/** Scene helpers enabled through `debug` in the Renderer constructor options. */
 interface DebugOptions {
     grid: boolean;
     axes: boolean;
 }
 
+/**
+ * Browser controls for inspecting and editing scene objects with Ctrl/Cmd-click selection.
+ * Construct it with a renderer, attach its panels with {@link appendTo}, and call {@link dispose} when finished.
+ */
 declare class SceneInspector {
     readonly renderer: Renderer;
     readonly objectInfoContainer: HTMLDivElement;
@@ -1749,7 +2774,7 @@ declare class SceneInspector {
     constructor(renderer: Renderer);
     protected init(): void;
     dispose(): void;
-    findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry<three.NormalBufferAttributes>, three.Material | three.Material[], three.Object3DEventMap>[];
+    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;
@@ -1766,13 +2791,17 @@ declare class SceneInspector {
     protected separator(name?: string): HTMLElement;
 }
 
-declare class SceneStatsDisplay {
+/** A browser statistics panel refreshed once per second. Dispose it separately from its renderer. */
+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;
+    /** Stops the refresh timer and removes the panel from the page. */
+    dispose(): void;
     add(line?: StatLine): void;
 }
 declare class StatLine {
@@ -1787,10 +2816,130 @@ declare class StatLine {
     update(): void;
 }
 
+/** Portable scene setup. Positions use model units (16 per block); rotations use radians. */
+interface SceneDocument {
+    format: "minerender-scene";
+    version: 1;
+    minecraftVersion?: string;
+    camera?: {
+        position: TripleArray;
+        target: TripleArray;
+    };
+    objects: SceneObjectDefinition[];
+}
+interface SceneObjectDefinitionBase {
+    id: string;
+    name?: string;
+    position?: TripleArray;
+    rotation?: TripleArray;
+    scale?: TripleArray;
+    visible?: boolean;
+}
+type SceneSkinPosePart = "head" | "body" | "rightArm" | "leftArm" | "rightLeg" | "leftLeg" | "cape";
+interface SceneSkinDefinition extends SceneObjectDefinitionBase {
+    type: "skin";
+    /** Texture URL, Minecraft username, or UUID. Omit for Steve, or Alex with slim: true, from the active asset version. */
+    skin?: string;
+    cape?: {
+        texture: string;
+        layout?: CapeLayout;
+    };
+    options?: {
+        slim?: boolean;
+        legacy?: boolean;
+    };
+    /** Mesh names from SkinPart; hiding a base part does not hide its overlay. */
+    hiddenParts?: string[];
+    /** Absolute local XYZ joint rotations in radians; omitted joints keep their default pose. */
+    pose?: Partial<Record<SceneSkinPosePart, TripleArray>>;
+}
+interface SceneBlockDefinition extends SceneObjectDefinitionBase {
+    type: "block";
+    asset: string;
+    state?: Record<string, string>;
+    options?: {
+        wireframe?: boolean;
+        tints?: Record<number, number>;
+    };
+}
+interface SceneModelDefinition extends SceneObjectDefinitionBase {
+    type: "item" | "model";
+    asset: string;
+    options?: {
+        wireframe?: boolean;
+        displayPosition?: DisplayPosition;
+        tints?: Record<number, number>;
+    };
+}
+interface SceneEntityDefinition extends SceneObjectDefinitionBase {
+    type: "entity";
+    asset: string;
+    texture?: string;
+    layers?: string[];
+    when?: string[];
+    textures?: Record<string, string>;
+    options?: {
+        flip?: boolean;
+        wireframe?: boolean;
+        tints?: Record<string, string | number>;
+    };
+    animation?: {
+        name: string;
+        loop?: boolean;
+        speed?: number;
+        time?: number;
+        paused?: boolean;
+    };
+}
+type SceneGuiLayer = (Omit<GuiTextureLayer, "texture"> & {
+    texture: string;
+}) | (Omit<GuiItemLayer, "item"> & {
+    item: string;
+}) | (Omit<GuiTextLayer, "font"> & {
+    font?: string;
+});
+interface SceneGuiDefinition extends SceneObjectDefinitionBase {
+    type: "gui";
+    layers: SceneGuiLayer[];
+}
+type SceneObjectDefinition = SceneSkinDefinition | SceneBlockDefinition | SceneModelDefinition | SceneEntityDefinition | SceneGuiDefinition;
+/** Validates and copies a scene document without requesting assets or changing the active asset version. */
+declare function parseSceneDocument(value: unknown): SceneDocument;
+
+interface LoadedSceneObject {
+    readonly root: Group;
+    readonly object: SceneObject;
+    readonly definition: SceneObjectDefinition;
+    /** Advances entity playback in seconds unless the definition has paused it. */
+    advanceAnimation(delta: number): void;
+    /** Removes this object and releases its owned resources. Safe to call more than once. */
+    dispose(): void;
+}
+interface LoadedSceneDocument {
+    readonly root: Group;
+    readonly objects: LoadedSceneObject[];
+    readonly definition: SceneDocument;
+    advanceAnimations(delta: number): void;
+    dispose(): void;
+}
+/** Loads portable scene documents using the asset sources already configured by the caller. */
+declare class SceneDocumentLoader {
+    static parse(value: unknown): SceneDocument;
+    /**
+     * Loads objects concurrently and attaches them in document order after every load succeeds.
+     * A failure waits for all loads, disposes staged objects, and reports the first error in document order.
+     */
+    static load(scene: MineRenderScene, value: unknown, parent?: Object3D): Promise<LoadedSceneDocument>;
+    /** Loads an independently editable object. Its root owns the document's position, rotation, and scale. */
+    static loadObject(scene: MineRenderScene, value: SceneObjectDefinition, parent?: Object3D): Promise<LoadedSceneObject>;
+    private static loadValidatedObject;
+}
+
 type SkinGeometries = Record<SkinPart, TripleArray>;
 declare const classicSkinGeometries: SkinGeometries;
 declare const slimSkinGeometries: SkinGeometries;
 
+/** Decodes skin pixels while preserving hidden RGB values in transparent PNG pixels. */
 declare class SkinImage {
     static getData(src: string): Promise<ImageData>;
     private static decodePng;
@@ -1800,12 +2949,15 @@ type SkinTextureCoordinates = Record<SkinPart, ModelFaces>;
 declare const classicSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 declare const slimSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 
+/** A prepared shared skin material with detected arm-model and texture-layout flags. */
 interface SkinTexture {
     material: MeshBasicMaterial;
     slim: boolean;
     legacy: boolean;
 }
+/** Prepares shared skin and cape materials, including legacy layout conversion and base-layer opacity. */
 declare class SkinTextures {
+    /** Loads a skin URL. Pass `legacy` to override layout detection from the image dimensions. */
     static get(src: string, legacy?: boolean): Promise<SkinTexture>;
     static getCape(src: string, layout?: CapeLayout): Promise<MeshBasicMaterial>;
     private static createMaterial;
@@ -1814,12 +2966,18 @@ declare class SkinTextures {
     private static makeBaseOpaque;
 }
 
+/** Resolves player names, UUIDs, and service IDs to skin or cape texture URLs. */
 declare class Skins {
+    /** Returns a skin URL for {@link MineRenderScene.addSkin}, or `undefined` if name lookup fails. */
     static fromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
+    /** Builds a proxy URL for a UUID without downloading or checking the skin. */
     static fromUuid(uuid: string): Promise<Maybe<string>>;
     static fromUsername(username: string): Promise<Maybe<string>>;
+    /** Looks up a saved MineSkin skin and returns its texture URL, or `undefined` on lookup failure. */
     static fromMineSkin(mineskinId: string): Promise<Maybe<string>>;
+    /** Resolves a player's Minecraft cape URL for {@link SkinObject.setCapeTexture}. */
     static capeFromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
+    /** Builds a proxy URL without checking whether the player has a cape. */
     static capeFromUuid(uuid: string): Promise<Maybe<string>>;
     static capeFromUsername(username: string): Promise<Maybe<string>>;
     /** Returns a full static cape texture for a username or UUID. */
@@ -1844,20 +3002,34 @@ declare class Skins {
     private static getMcProxyCapeUrl;
 }
 
+/** Samples resource-pack colormaps to produce packed sRGB tint colors. */
+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>;
+}
+
+/** Creates sRGB textures immediately and fills their pixels after asynchronous image loading. */
 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;
+    /** Loads image pixels in the background. `rotation` is in radians. Check {@link hasFailed} for load failures. */
     static load(src: string, format?: PixelFormat, rotation?: number): Texture;
 }
 
+/** Creates and caches Three.js textures with nearest-neighbor sampling for Minecraft artwork. */
 declare class Textures {
+    /** Creates the shared checkerboard from pixels without fetching or decoding an image. */
+    static getMissing(): DataTexture;
+    /** Sets nearest-neighbor filters without changing the texture's color space. Returns the same texture. */
     static initTextureProps<T extends Texture>(texture: T): T;
     static createImage(key: TextureKey): Texture;
     static createAsset(key: AssetKey): Texture;
+    /** Creates an sRGB color texture from a canvas. */
     static createCanvasTexture(canvas: HTMLCanvasElement): CanvasTexture;
+    /** Returns a shared texture immediately and loads its image asynchronously. Failed cached loads are retried. */
     static getImage(key: TextureKey): Texture;
 }
 
@@ -1869,14 +3041,18 @@ declare function mergeVertices(geometry: BufferGeometry, tolerance?: number): Bu
 declare function toTrianglesDrawMode(geometry: BufferGeometry, drawMode: TrianglesDrawModes): BufferGeometry;
 declare function computeMorphedAttributes(object: Mesh | Line | Points): object;
 
+/** Stores 4,096 block cells in a shared state palette, with separate NBT for each cell. */
 declare class ChunkData {
     private readonly indices;
     private readonly palette;
     private readonly paletteIds;
     private readonly freeIds;
     private readonly nbt;
+    /** Returns a detached copy of a cell, or `undefined` for air. Indices range from 0 to 4095. */
     get(index: number): Maybe<Block>;
+    /** Captures a cell's data and returns a copy-producing reader that survives later cell changes. */
     snapshot(index: number): Maybe<() => Block>;
+    /** Copies block data into a cell. An omitted block or an air block clears the cell. */
     set(index: number, block?: Block): void;
     clear(): void;
     static isAir(block: Maybe<Block>): boolean;
@@ -1885,9 +3061,11 @@ declare class ChunkData {
 }
 
 type RegionInput = Uint8Array | ArrayBuffer;
+/** Chunk columns decoded from an Anvil region file. */
 interface AnvilRegion {
     chunks: AnvilChunk[];
 }
+/** A decoded chunk column. `x` and `z` are absolute chunk coordinates, and section `y` is a section coordinate. */
 interface AnvilChunk {
     x: number;
     z: number;
@@ -1898,12 +3076,21 @@ interface AnvilChunk {
     }[];
     entities?: MultiBlockEntity[];
 }
+/** Reads Java 1.13+ paletted `.mca` regions. Entity NBT is preserved without data-version migration. */
 declare class AnvilParser {
+    /** Lists occupied chunk positions within the region, using local coordinates from 0 to 31. */
     static getChunkList(data: RegionInput): {
         x: number;
         z: number;
     }[];
+    /** Decodes all stored chunks. Gzip, zlib, and uncompressed payloads are supported. */
     static parse(data: RegionInput): Promise<AnvilRegion>;
+    /**
+     * Decodes one chunk for {@link MineRenderWorld.placeChunk}.
+     * @param localX - Chunk x within the region, from 0 to 31.
+     * @param localZ - Chunk z within the region, from 0 to 31.
+     * @returns The chunk with absolute coordinates, or `undefined` if the region has no chunk there.
+     */
     static parseChunk(data: RegionInput, localX: number, localZ: number): Promise<AnvilChunk | undefined>;
     private static bytes;
     private static locations;
@@ -1914,6 +3101,7 @@ declare class AnvilParser {
     private static unpack;
 }
 
+/** A placed block's data snapshot and optional render object, returned by world and chunk accessors. */
 interface BlockInfo<SectionMeshing extends boolean = false> {
     /** Detached block data; use world or chunk setters to update stored blocks. */
     readonly block: Block;
@@ -1921,33 +3109,45 @@ interface BlockInfo<SectionMeshing extends boolean = false> {
     object: SectionMeshing extends false ? BlockObject : BlockObject | undefined;
 }
 
+/** Shared cube geometry and atlas data prepared for section merging. */
 interface SectionMeshTemplate {
     geometry: BufferGeometry;
     atlas: TextureAtlas;
     cullFaces: readonly number[];
 }
+/** One block placement in a section, with its storage index and hidden-face mask. */
 interface SectionMeshEntry {
     index: number;
     template: SectionMeshTemplate;
     cullMask: number;
 }
+/** Merged terrain geometry and atlas pages for one 16×16×16 section. Owns its generated render resources. */
 declare class SectionMesh extends Group {
     private readonly ownedMeshes;
+    /** Builds section-local meshes from visible cube faces. `maxAtlasSize` limits each atlas dimension in pixels. */
     static build(entries: readonly SectionMeshEntry[], maxAtlasSize?: number): SectionMesh;
     dispose(): void;
 }
 
+/** Prepares and caches static opaque cube geometry for merged world sections. */
 declare class SectionModels {
     readonly maxAtlasSize: number;
     private states;
     private models;
     private readonly templates;
     constructor(maxAtlasSize?: number);
+    /** Returns a cube template, or `undefined` when the block requires an individual render object. */
     get(blockState: BlockState, properties?: BlockStateProperties): Promise<SectionMeshTemplate | undefined>;
     private prepare;
+    /** Disposes prepared geometry and clears this world's template caches. */
     clear(): void;
 }
 
+/**
+ * A 16×16×16 block section and its render objects.
+ * Constructor coordinates identify the section. Block accessors use world block coordinates
+ * unless their name explicitly refers to positions within the chunk.
+ */
 declare class Chunk<SectionMeshing extends boolean = false> {
     private readonly onBlocksChanged?;
     private readonly sectionModels?;
@@ -1958,6 +3158,7 @@ declare class Chunk<SectionMeshing extends boolean = false> {
     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);
@@ -1965,26 +3166,36 @@ declare class Chunk<SectionMeshing extends boolean = false> {
     getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
     /**
-     * Set block at a _world_ position
+     * Places a block at integer world block coordinates. Pass `undefined` to remove it.
      */
     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 a block at integer chunk-local coordinates from 0 to 15.
+     * Places a block at integer chunk-local coordinates from 0 to 15.
      */
     setBlockInChunkAt(pos: Vector3, block?: Block, worldPos?: Vector3, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    /** Changes visibility at world block coordinates while preserving the block's data. */
+    setBlockVisibleAt(pos: Vector3, visible: boolean): Promise<void>;
+    isBlockVisibleAt(pos: Vector3): boolean;
     isOccludingAt(pos: Vector3): boolean;
     setCullMaskAt(pos: Vector3, mask: number): Promise<void>;
     rebuildSectionMesh(): void;
+    /** Removes stored blocks and their render objects, then notifies the owning world of changed positions. */
     clear(onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<void>;
     dispose(): Promise<void>;
     static isAir(block: Maybe<Block>): boolean;
+    /** Maps chunk-local coordinates from 0 to 15 to a storage index, with x varying fastest, then z, then y. */
     static chunkPosToBlockIndex(pos: Vector3): number;
     worldPosToChunkPos(pos: Vector3): Vector3;
     chunkPosToWorldPos(pos: Vector3): Vector3;
 }
 
+/**
+ * Stores and renders blocks in sparse 16×16×16 chunks.
+ * Positions use integer block coordinates, including negatives. One block is 16 scene units.
+ * Set `options.sectionMeshing` in `new MineRenderWorld(scene, options)` to merge compatible terrain.
+ */
 declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     readonly scene: MineRenderScene;
     private readonly _chunks;
@@ -1992,26 +3203,56 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     private readonly pendingCulling;
     private culling?;
     constructor(scene: MineRenderScene, options?: MineRenderWorldOptions<SectionMeshing>);
+    /** Returns a placed block at world block coordinates, or `undefined` for an empty position. */
     getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
+    /**
+     * Places or replaces a block and refreshes neighboring faces.
+     * Pass `undefined` or an air block to remove the block at these world block coordinates.
+     */
     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>;
+    /**
+     * Places a structure's blocks at their stored positions, then refreshes neighboring faces.
+     * Entity NBT is retained by the structure but is not rendered.
+     *
+     * @param useBatches - Uses bounded batches by default. Set to `false` for sequential placement.
+     * @param executor - Optional queue for batched placement. The caller remains responsible for stopping it.
+     */
     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>;
+    /**
+     * Removes all sections at integer chunk-column coordinates, then refreshes neighboring faces and fluids.
+     * Coordinates match AnvilChunk.x/z, not block positions. Missing columns are ignored.
+     */
+    unloadChunkColumn(x: number, z: number): Promise<void>;
+    private clearChunkColumn;
+    /** Removes all chunks and releases their block placements and section meshes. */
     clear(): Promise<void>;
     private updateCulling;
     private getOrCreateChunkAt;
+    /** Returns the loaded chunk containing a world block position, without creating a chunk. */
     getChunkAt(pos: Vector3): Maybe<Chunk<SectionMeshing>>;
+    /** Converts block coordinates to scene units by multiplying each component by 16. */
     static worldToScenePosition(pos: Vector3): Vector3;
+    /** Converts scene units to block coordinates without rounding to an integer block. */
     static sceneToWorldPosition(pos: Vector3): Vector3;
     worldPosToChunkKey(pos: Vector3): string;
     validatePosBounds(pos: Vector3): void;
 }
+/** Settings passed as the second argument to `new MineRenderWorld(scene, options)`. */
 interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
     /** Merge static opaque cubes into section meshes. Merged blocks have no individual object. */
     sectionMeshing?: SectionMeshing;
@@ -2030,6 +3271,7 @@ declare class BrowserEnv implements EnvProvider {
     imageSize(data: Uint8Array): ImageSizeInfo;
     openCache(name: string, version: number): PersistentCache;
 }
+/** Installs the browser provider. The browser package entry calls this automatically. */
 declare function registerBrowserEnv(): BrowserEnv;
 
 /**
@@ -2055,4 +3297,4 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 
-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 };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, type BannerPattern, type BannerPatternDraw, BannerPatterns, 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, DYE_COLORS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, type DyeColor, 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, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, 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 ItemModelContext, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, 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, type PackFormat, PackFormats, PackMetadata, 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, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, 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, parseSceneDocument, prefix, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };