minerender 2.1.0-alpha.3 → 2.1.0-alpha.30

package/dist/node/index.d.ts

@@ -1,14 +1,11 @@
 import * as three from 'three';
-import { Vector3, PixelFormat, BoxGeometry, Material, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Scene, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, CanvasTexture, BufferGeometry as BufferGeometry$1, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
+import { Vector3, PixelFormat, BoxGeometry, Material, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Scene, Object3DEventMap, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, MeshBasicMaterial, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
 import * as nodeCanvas from 'canvas';
 import { ImageData as ImageData$1, CanvasRenderingContext2D } from 'canvas';
-import { AxiosResponse, AxiosRequestConfig } from 'axios';
 import { Buffer as Buffer$1 } from 'buffer';
 import { NBT } from 'prismarine-nbt';
 import { ZipReader } from '@zip.js/zip.js';
 import { AsyncLoadingCache, SimpleCache } from '@inventivetalent/loading-cache';
-import { BufferGeometry } from 'three/src/core/BufferGeometry';
-import { Material as Material$1 } from 'three/src/materials/Material';
 import Stats from 'stats.js';
 import { EffectComposer } from 'postprocessing';
 import { LocalStorage } from 'node-persist';
@@ -18,7 +15,7 @@ interface AnimatorFunction {
 }
 
 declare enum Axis {
-    X = "X",
+    X = "x",
     Y = "y",
     Z = "z"
 }
@@ -63,10 +60,11 @@ declare function createCanvas(width: number, height: number): CompatCanvas;
 declare abstract class PersistentCache<B = unknown> {
     readonly backing: B;
     /** Bump to invalidate every persisted entry. */
-    static readonly VERSION = 1;
+    static readonly VERSION = 2;
     static open(name: string): PersistentCache;
     protected constructor(backing: B);
     abstract get<T>(key: string): Promise<T>;
+    /** Loads a missing entry and stores only non-nullish results. */
     getOrLoad<T>(key: string, loader: (key: string) => Promise<T>): Promise<T>;
     abstract put<T>(key: string, value: T): Promise<T>;
     abstract delete<T>(key: string): Promise<void>;
@@ -176,6 +174,7 @@ declare class AssetKey extends BasicAssetKey {
     rootType: "assets" | "data" | string;
     extension: ".json" | ".png" | string;
     root?: string | undefined;
+    readonly isAssetKey: true;
     constructor(namespace: string, path: string, assetType?: AssetType | undefined, type?: string | undefined, rootType?: "assets" | "data" | string, extension?: ".json" | ".png" | string, root?: string | undefined);
     static parse(assetType: AssetType, str: string, origin?: AssetKey): AssetKey;
     toString(): string;
@@ -248,7 +247,8 @@ declare enum DisplayPosition {
     GUI = "gui",
     HEAD = "head",
     GROUND = "ground",
-    FIXED = "fixed"
+    FIXED = "fixed",
+    ON_SHELF = "on_shelf"
 }
 declare const DISPLAY_POSITIONS: DisplayPosition[];
 
@@ -257,6 +257,46 @@ declare enum GuiLight {
     SIDE = "side"
 }
 
+interface RequestConfig extends RequestInit {
+    url: string;
+    /** Prepended to relative URLs, preserving any path in the base URL. */
+    baseURL?: string;
+    /** Timeout per attempt in milliseconds, including body reading. Defaults to 5000; 0 disables it. */
+    timeout?: number;
+    responseType?: "json" | "arraybuffer";
+}
+interface RequestResponse<T = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    /** Final URL after redirects. */
+    url: string;
+}
+declare class RequestError extends Error {
+    readonly response?: RequestResponse<undefined> | undefined;
+    readonly cause?: unknown;
+    constructor(message: string, response?: RequestResponse<undefined> | undefined, cause?: unknown);
+}
+declare class Requests {
+    private static genericQueue;
+    private static mcAssetRequestQueue;
+    static genericRequest(request: RequestConfig): Promise<RequestResponse>;
+    static mcAssetRequest(request: RequestConfig): Promise<RequestResponse>;
+    static setMcAssetRoot(root: string): void;
+    /** Counts unsettled calls, including retry delays and requests still running after shutdown. */
+    static get queueSizes(): {
+        generic: number;
+        mcAsset: number;
+    };
+    /**
+     * Permanently stops both queues and rejects waiting, retrying, and future requests.
+     * Requests already running can finish. Idle queues hold no timer, so Node can exit without
+     * this cleanup. See {@link shutdown}.
+     */
+    static end(): void;
+}
+
 declare class WrappedImage {
     readonly dta: ExtractableImageData;
     constructor(dta: ExtractableImageData);
@@ -292,7 +332,7 @@ declare class ImageLoader {
     static infoToData(info: ImageInfo): Promise<ImageData>;
     static getData(src: string): Promise<ImageData>;
     static getCanvasData(src: string): Promise<ExtractableImageData>;
-    static processResponse(response: Partial<AxiosResponse>): Promise<ImageInfo>;
+    static processResponse(response: Pick<RequestResponse<ArrayBuffer>, "data" | "url">): Promise<ImageInfo>;
     static loadInfo(src: string): Promise<ImageInfo>;
     static getInfo(src: string): Promise<ImageInfo>;
     static loadWrapped(src: string): Promise<WrappedImage>;
@@ -306,7 +346,7 @@ declare const DEFAULT_ELEMENTS: ModelElement[];
 interface Model extends MinecraftAsset {
     textures?: IModelTextures;
     parent?: string;
-    display?: ModelDisplay;
+    display?: Partial<Record<DisplayPosition, ModelDisplay>>;
     elements?: ModelElement[];
     hierarchy?: string[];
 }
@@ -321,7 +361,6 @@ interface ItemModel extends Model {
 interface TextureAsset extends MinecraftAsset, ImageInfo {
 }
 interface ModelDisplay {
-    position?: DisplayPosition;
     translation?: TripleArray;
     rotation?: TripleArray;
     scale?: TripleArray;
@@ -341,13 +380,7 @@ declare function isDoubleArray(obj: any): obj is DoubleArray;
 declare function isTripleArray(obj: any): obj is TripleArray;
 declare function isQuadArray(obj: any): obj is QuadArray;
 
-/**
- *          down  up
- *  east    north    west    south
- *
- *  bottom-left to top-right
- *  [bl, br, tl, tr]
- */
+/** Vanilla Minecraft cube UVs in Three.js BoxGeometry face and vertex order. */
 declare class MinecraftCubeTexture {
     readonly u: number;
     readonly v: number;
@@ -363,7 +396,7 @@ declare class MinecraftCubeTexture {
     getUvSouth(w: number, h: number, l: number): QuadArray<DoubleArray>;
     getUvNorth(w: number, h: number, l: number): QuadArray<DoubleArray>;
     getFaceUv(face: CubeFace, w: number, h: number, l: number): QuadArray<DoubleArray>;
-    toUvArray(w: number, h: number, l: number): number[];
+    toUvArray(w: number, h: number, l: number, mirror?: boolean): number[];
 }
 
 interface MinecraftTextureMeta extends MinecraftAsset {
@@ -432,7 +465,7 @@ interface Transformable {
 declare function isTransformable(obj: any): obj is Transformable;
 
 declare const changeEvent: {
-    type: string;
+    type: "change";
 };
 type Maybe<T> = T | undefined;
 declare function md5(str: string): string;
@@ -516,6 +549,7 @@ declare class UVMapper {
     static setCubeUvs(geometry: BoxGeometry, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray, faces: ModelFaces): void;
     static facesToUvArray(faces: ModelFaces, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray): number[];
     static facesToUv(faces: ModelFaces, originalTextureSize: DoubleArray, actualTextureSize: DoubleArray): Float32BufferAttribute;
+    static lockUvs(geometry: BoxGeometry, faces: ModelFaces, atlas: TextureAtlas, rotation: Euler): void;
     static getAtlas(model: Model): Promise<Maybe<TextureAtlas>>;
     static fillMissingTextureKeys<T>(textures: ModelTextures, target: {
         [k: string]: T;
@@ -537,14 +571,13 @@ declare class MinecraftFaceUV {
 }
 
 /**
- * Releases every long-lived timer MineRender holds, so a Node process can exit.
+ * Stops the shared Ticker and request queues, and clears the in-memory caches.
  *
- * Both `@inventivetalent/loading-cache` (cache expiry) and `jobqu` (request queue draining) use
- * self-rescheduling timers that are not unref'd, which keeps the event loop alive for as long as
- * the library is loaded. Browsers don't care, but anything headless - a render server, a CLI, a
- * test run - has to call this when it's done.
+ * Idle Node processes can exit without calling this: cache and Ticker timers are unref'd,
+ * and idle request queues hold no timer. Pending requests keep their normal timer references.
  *
- * The library stays usable afterwards; the caches and queues simply start over.
+ * Call this only when finished with MineRender. Queued, retrying, and future requests reject;
+ * HTTP requests already running can finish. Queue shutdown is permanent, and cache expiry timers do not restart.
  */
 declare function shutdown(): void;
 
@@ -562,32 +595,7 @@ type Task = () => any | Promise<any>;
 
 declare function prefix(prefix?: string): string;
 
-interface ModelPart {
-    textureWidth: number;
-    textureHeight: number;
-    textureOffsetU: number;
-    textureOffsetV: number;
-    pivotX: number;
-    pivotY: number;
-    pivotZ: number;
-    pitch: number;
-    yaw: number;
-    roll: number;
-    mirror: boolean;
-    cubes: Cube[];
-    children: ModelPart[];
-}
-interface Cube {
-    minX: number;
-    minY: number;
-    minZ: number;
-    maxX: number;
-    maxY: number;
-    maxZ: number;
-}
-
 declare function applyElementRotation(rotation: ElementRotation, geometry: BufferGeometry): void;
-declare function applyModelPartRotation(modelPart: ModelPart, geometry: BufferGeometry): void;
 declare function applyGenericRotation(axis: Axis, rotation: number, obj: Object3D): void;
 declare function addBox3WireframeToObject(box: Box3, obj: Object3D, color?: number, w?: number): void;
 declare function addWireframeToObject(obj: Object3D, color?: number, w?: number): void;
@@ -616,15 +624,47 @@ declare enum AssetParser {
 declare abstract class AssetSource {
     protected constructor();
     abstract get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
+    /**
+     * Identifies this source's content across sessions for persistent caching. Sources that
+     * cannot tell whether their content changed (an unnamed archive, for example) return
+     * undefined, which keeps their results out of long-lived caches.
+     */
+    get cacheId(): Maybe<string>;
+}
+/** A source failed to load or parse an asset; cause retains the original failure. */
+declare class AssetLoadError extends Error {
+    readonly source: AssetSource;
+    readonly key: AssetKey;
+    readonly path: string;
+    readonly cause: unknown;
+    constructor(source: AssetSource, key: AssetKey, path: string, cause: unknown);
 }
 
 declare class AssetLoader {
     static ROOT: string;
     private static _SOURCES;
+    /** Used when a registered source cannot identify its content, so nothing persists past this session. */
+    private static readonly SESSION_SCOPE;
+    static get version(): string;
+    static setVersion(version: string): void;
+    /**
+     * Scope for persistent cache keys. Empty with only the default vanilla sources, so their
+     * entries stay valid across sessions; otherwise it names every added source (resource packs,
+     * mirrors) so their results never masquerade as vanilla assets after a reload.
+     */
+    static get persistentScope(): string;
+    /** Prefixes a persistent cache key with the current source scope. */
+    static persistentKey(key: string): string;
     static addSource(key: string, source: AssetSource, override?: boolean): void;
     static removeSource(key: string): Maybe<AssetSource>;
     static getAll<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<T[]>;
+    /** Returns the first defined result in source-priority order, without merging assets. */
     static get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
+    /** Tries each path within a source before considering lower-priority sources. */
+    static getFirst<T extends MinecraftAsset>(keys: readonly AssetKey[], parser: AssetParser | string): Promise<Maybe<{
+        key: AssetKey;
+        asset: T;
+    }>>;
 }
 
 interface BlockState extends MinecraftAsset {
@@ -639,18 +679,19 @@ interface BlockStateVariant {
     y?: number;
     x?: number;
     uvlock?: boolean;
+    weight?: number;
 }
 interface BlockStateMultipart {
-    when?: MultipartCondition | {
-        OR: MultipartCondition[];
-    };
-    apply?: BlockStateVariant;
-}
-interface MultipartCondition {
-    [key: string]: string;
+    when?: MultipartCondition;
+    apply?: BlockStateVariant | BlockStateVariant[];
 }
+type MultipartCondition = Record<string, string> | {
+    OR: MultipartCondition[];
+} | {
+    AND: MultipartCondition[];
+};
 
-declare const DEFAULT_ROOT = "https://assets.mcasset.cloud/1.17.1";
+declare const DEFAULT_ROOT = "https://assets.mcasset.cloud/1.21.11";
 declare const DEFAULT_NAMESPACE = "minecraft";
 declare class Assets {
     /**
@@ -689,25 +730,50 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
-interface EntityModel extends BasicMinecraftAsset {
-    parts?: {
-        [p: string]: ModelPart;
+interface EntityModel {
+    key: BasicAssetKey;
+    texture?: AssetKey;
+    layer: EntityModelLayer;
+    id: string;
+}
+interface EntityModelFile extends MinecraftAsset {
+    id: string;
+    layers: Record<string, EntityModelLayer>;
+}
+interface EntityModelLayer {
+    texture: [number, number];
+    textureLocation?: string;
+    root: EntityModelPart;
+}
+interface EntityModelPart {
+    pose: {
+        offset: [number, number, number];
+        rotation: [number, number, number];
+        scale?: [number, number, number];
     };
+    texture?: [number, number];
+    cubes: EntityModelCube[];
+    children: Record<string, EntityModelPart>;
+}
+interface EntityModelCube {
+    origin: [number, number, number];
+    size: [number, number, number];
+    uv: [number, number];
+    grow?: [number, number, number];
+    mirror?: boolean;
 }
 
 declare class Entities {
-    static getBlockEntityModels(): Promise<Maybe<BlockEntityModels>>;
-    static getEntityModels(): Promise<Maybe<EntityModels>>;
-    static getBlockList(): Promise<string[]>;
     static getEntityList(): Promise<string[]>;
-    static getBlock(modelKey: BasicAssetKey, textureKey?: BasicAssetKey): Promise<Maybe<EntityModel>>;
-    static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey): Promise<Maybe<EntityModel>>;
-}
-declare class EntityModels implements MinecraftAsset {
-    [k: string]: any;
+    static getEntity(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
+    static resolveTexture(modelKey: BasicAssetKey): Promise<Maybe<AssetKey>>;
+    /** @deprecated Use getEntityList(); block entities share the entity dataset. */
+    static getBlockList(): Promise<string[]>;
+    /** @deprecated Use getEntity(); block entities share the entity dataset. */
+    static getBlock(modelKey: BasicAssetKey, textureKey?: BasicAssetKey, options?: EntityModelOptions): Promise<Maybe<EntityModel>>;
 }
-declare class BlockEntityModels implements MinecraftAsset {
-    [k: string]: any;
+interface EntityModelOptions {
+    layer?: string;
 }
 
 declare class Models {
@@ -715,12 +781,22 @@ declare class Models {
     private static get PERSISTENT_CACHE();
     static getItemList(): Promise<string[]>;
     static loadAndMerge(key: AssetKey): Promise<Maybe<Model>>;
+    private static getItemModel;
+    private static defaultItemModel;
     static getRaw(key: AssetKey): Promise<Maybe<Model>>;
     static getMerged(key: AssetKey): Promise<Maybe<Model>>;
     static get(key: AssetKey): Promise<Maybe<Model>>;
     static clearCache(): Promise<void>;
 }
 
+declare class DisplayTransforms {
+    /** Resolve hand fallbacks within one model, before inheriting parent display entries. */
+    static withHandFallbacks(display: Model["display"]): Model["display"];
+    /** Build a display pose for geometry already centered at the model's [8, 8, 8] pivot. */
+    static getMatrix(display: Model["display"], position: DisplayPosition): Matrix4;
+    static apply(geometry: BufferGeometry, matrix: Matrix4): void;
+}
+
 declare class ModelGenerator {
     static readonly ITEM_LAYERS: string[];
     static generateItemModel(imageData: ImageData$1, layer: string): ModelElement[];
@@ -737,6 +813,12 @@ interface Block {
     nbt?: any;
 }
 
+declare class BlockTints {
+    /** Resolves block preview colors without biome context; explicit tints take precedence. */
+    static get(key: AssetKey | undefined, state: BlockStateProperties, model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
+    private static grassColor;
+}
+
 interface Instanceable {
     nextInstance(): InstanceReference<SceneObject>;
     getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
@@ -793,6 +875,12 @@ declare class ModelObject extends SceneObject {
     protected applyTextures(): void;
 }
 interface ModelObjectOptions extends SceneObjectOptions {
+    /** Minecraft display pose applied around the model center, before scene transforms. */
+    displayPosition?: DisplayPosition;
+    /** Quarter-turn block rotation in radians to compensate when locking UVs. */
+    uvLockRotation?: TripleArray;
+    /** sRGB 0xRRGGBB colors by face tint index; omitted indices stay white. */
+    tints?: Record<number, number>;
 }
 declare function isModelObject(obj: any): obj is ModelObject;
 
@@ -825,24 +913,35 @@ declare enum SkinPart {
 }
 declare const SKIN_PARTS: SkinPart[];
 
+type CapeLayout = "minecraft" | "optifine" | "labymod";
+declare const capeTextureSizes: Record<CapeLayout, DoubleArray>;
+
 declare class SkinObject extends SceneObject {
     readonly options: SkinObjectOptions;
     private slim;
-    private legacy;
+    private detectedSlim;
     private skinTextureSrc?;
-    private skinTextureWidth;
-    private skinTextureHeight;
-    private capeTextureSrc?;
+    private skinMaterial?;
+    private skinLoad;
+    private capeLoad;
     constructor(options?: DeepPartial<SkinObjectOptions>);
     init(): Promise<void>;
     protected removeMeshes(): void;
     protected createMeshes(): void;
-    setSkinTexture(src: string): void;
-    setSlim(slim: boolean): void;
-    setLegacy(legacy: boolean): void;
+    setSkinTexture(src: string): Promise<void>;
+    /** Load a cape texture in the selected layout, or pass undefined to remove the cape. */
+    setCapeTexture(src?: string, layout?: CapeLayout): Promise<void>;
+    /** Select the arm model, or pass undefined to use texture detection. */
+    setSlim(slim?: boolean): void;
+    private updateSlim;
+    /** Select the texture layout, or pass undefined to detect it from image dimensions. */
+    setLegacy(legacy?: boolean): Promise<void>;
+    dispose(): void;
     protected getBoxGeometry(part: SkinPart): BoxGeometry;
 }
 interface SkinObjectOptions extends SceneObjectOptions {
+    slim?: boolean;
+    legacy?: boolean;
 }
 
 declare class EntityObject extends SceneObject {
@@ -855,11 +954,14 @@ declare class EntityObject extends SceneObject {
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
+    private get textureKey();
     protected loadTextures(): Promise<void>;
     protected createMeshes(force?: boolean): void;
+    private createPart;
     protected applyTextures(): Promise<void>;
 }
 interface EntityObjectOptions extends SceneObjectOptions {
+    flip?: boolean;
 }
 declare function isEntityObject(obj: any): obj is EntityObject;
 
@@ -887,7 +989,9 @@ interface MineRenderSceneOptions {
 }
 declare function isMineRenderScene(obj: any): obj is MineRenderScene;
 
-declare class SceneObject extends Object3D implements Disposable, Instanceable, Transformable {
+declare class SceneObject extends Object3D<Object3DEventMap & {
+    change: {};
+}> implements Disposable, Instanceable, Transformable {
     readonly isSceneObject: true;
     static readonly DEFAULT_OPTIONS: SceneObjectOptions;
     readonly options: SceneObjectOptions;
@@ -913,9 +1017,9 @@ declare class SceneObject extends Object3D implements Disposable, Instanceable,
      */
     toggleGroupVisibility(name: string, visible?: boolean): boolean;
     protected addOrReplaceMesh(mesh: Mesh, parent: Object3D, name?: string): void;
-    protected createAndAddMesh(name?: string, group?: Object3D, geometry?: BufferGeometry, material?: Material$1 | Material$1[], offsetAxis?: Axis, offset?: number): Mesh;
-    protected createMesh(name?: string, geometry?: BufferGeometry, material?: Material$1 | Material$1[], offsetAxis?: Axis, offset?: number): Mesh;
-    protected createInstancedMesh(name: Maybe<string>, geometry: BufferGeometry, material: Material$1 | Material$1[], count: number): InstancedMesh;
+    protected createAndAddMesh(name?: string, group?: Object3D, geometry?: BufferGeometry, material?: Material | Material[], offsetAxis?: Axis, offset?: number): Mesh;
+    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
      */
@@ -1084,8 +1188,8 @@ interface NBTAsset extends MinecraftAsset, NBT {
 }
 
 interface ResponseParser<T extends MinecraftAsset> {
-    config(request: AxiosRequestConfig): any;
-    parse(response: AxiosResponse): Maybe<T> | Promise<Maybe<T>>;
+    config(request: RequestConfig): any;
+    parse(response: RequestResponse): Maybe<T> | Promise<Maybe<T>>;
 }
 
 declare class HostedAssetSource extends AssetSource {
@@ -1104,6 +1208,7 @@ declare class HostedAssetSource extends AssetSource {
     private readonly _options;
     constructor(root: string, options?: Partial<HostedAssetSourceOptions>);
     get root(): string;
+    get cacheId(): string;
     get options(): HostedAssetSourceOptions;
     get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser): Promise<Maybe<T>>;
 }
@@ -1118,6 +1223,8 @@ interface ArchiveEntry {
 }
 
 interface ArchiveProxy {
+    /** Identifies the archive's content across sessions; undefined when it cannot be identified. */
+    readonly id?: string;
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
@@ -1125,6 +1232,7 @@ declare class ArchiveAssetSource extends AssetSource implements ArchiveProxy {
     readonly _archiveProxy: ArchiveProxy;
     constructor(archiveProxy: ArchiveProxy);
     static blob(blob: Blob): ArchiveAssetSource;
+    get cacheId(): Maybe<string>;
     getEntries(): Promise<ArchiveEntry[]>;
     getEntry(path: string): Promise<Maybe<ArchiveEntry>>;
     get<T extends MinecraftAsset>(key: AssetKey, parser: AssetParser | string): Promise<Maybe<T>>;
@@ -1135,7 +1243,8 @@ declare class ArchiveAssetSource extends AssetSource implements ArchiveProxy {
 declare class BrowserArchiveProxy implements ArchiveProxy {
     readonly _blob: Blob;
     readonly _reader: ZipReader<Blob>;
-    constructor(blob: Blob);
+    readonly id?: string;
+    constructor(blob: Blob, id?: string);
     getEntries(): Promise<ArchiveEntry[]>;
 }
 
@@ -1213,14 +1322,20 @@ declare class Caching {
     static readonly mergedModelCache: AsyncLoadingCache<CacheKey, Model>;
     static readonly modelTextureAtlasCache: AsyncLoadingCache<CacheKey, TextureAtlas>;
     static readonly blockStateCache: AsyncLoadingCache<CacheKey, BlockState>;
+    static readonly listAssetCache: AsyncLoadingCache<CacheKey, ListAsset>;
+    static readonly defaultBlockStatesCache: AsyncLoadingCache<CacheKey, DefaultBlockStates>;
+    static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
+    static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
+    static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
+    private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
     static clear(): void;
     /**
      * Clears every cache and stops its expiry timer.
      *
-     * loading-cache reschedules that timer indefinitely, so a Node process will not exit until
-     * this is called - see {@link shutdown}.
+     * Expiry timers are unref'd in Node, so idle processes can exit without this cleanup.
+     * Use {@link shutdown} to also stop requests and the shared Ticker.
      */
     static end(): void;
     static get cacheSizes(): {};
@@ -1320,15 +1435,14 @@ declare class Renderer implements Disposable {
     protected _scene: MineRenderScene;
     protected _camera: Camera;
     protected _renderer: WebGLRenderer;
-    protected _composer: EffectComposer;
+    protected _composer?: EffectComposer;
     protected _controls?: OrbitControls;
     protected _stats?: Stats;
     protected _dirty: boolean;
     protected _animationLoop: any;
-    protected _fpsTimer: any;
-    protected _animationTimer?: NodeJS.Timeout;
-    protected _animationFrame?: number;
+    protected _frameInterval?: number;
     protected _resizeListener?: () => void;
+    private _nextFrameTime?;
     private _disposed;
     private readonly _debugHelpers;
     private readonly _eventDispatchers;
@@ -1337,7 +1451,7 @@ declare class Renderer implements Disposable {
     protected createScene(): MineRenderScene;
     protected createCamera(): Camera;
     protected createRenderer(): WebGLRenderer;
-    protected createComposer(): EffectComposer;
+    protected createComposer(): Maybe<EffectComposer>;
     protected createControls(): Maybe<OrbitControls>;
     init(): void;
     get element(): Maybe<HTMLElement>;
@@ -1346,7 +1460,7 @@ declare class Renderer implements Disposable {
      * 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, changeEvent?: string): void;
+    registerEventDispatcher(dispatcher: EventDispatcher<any>, changeEvent?: string): void;
     resize(width: number, height: number): void;
     get dirty(): boolean;
     set dirty(dirty: boolean);
@@ -1366,7 +1480,7 @@ declare class Renderer implements Disposable {
     get scene(): MineRenderScene;
     get camera(): Camera;
     get renderer(): WebGLRenderer;
-    get composer(): EffectComposer;
+    get composer(): Maybe<EffectComposer>;
     /** Renderer-owned controls, or undefined when disabled at construction or after disposal. */
     get controls(): Maybe<OrbitControls>;
 }
@@ -1395,6 +1509,7 @@ interface CameraOptions {
     lookingAt: Vector3 | TripleArray;
 }
 interface RenderOptions {
+    /** Maximum draw rate (60 by default); zero or a negative value disables the limit. */
     fpsLimit: number;
     stats: boolean;
     antialias: boolean;
@@ -1422,7 +1537,7 @@ declare class SceneInspector {
     private selectedObject?;
     constructor(renderer: Renderer);
     protected init(): void;
-    findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry, three.Material | three.Material[]>[];
+    findMeshChildren(from: Object3D, out?: Mesh[]): Mesh<three.BufferGeometry<three.NormalBufferAttributes>, three.Material | three.Material[], three.Object3DEventMap>[];
     onClick(event: any): void;
     appendTo(el: HTMLElement): void;
     protected handleRaycasterObjects(intersections: Intersection[]): void;
@@ -1459,26 +1574,6 @@ declare class StatLine {
     update(): void;
 }
 
-declare class Requests {
-    private static axiosInstance;
-    private static mcAssetInstance;
-    private static genericQueue;
-    private static mcAssetRequestQueue;
-    static genericRequest(request: AxiosRequestConfig): Promise<AxiosResponse>;
-    static mcAssetRequest(request: AxiosRequestConfig): Promise<AxiosResponse>;
-    private static shouldRetry;
-    static setMcAssetRoot(root: string): void;
-    static get queueSizes(): {
-        generic: number;
-        mcAsset: number;
-    };
-    /**
-     * Stops both queue timers. jobqu reschedules itself indefinitely, so a Node process will not
-     * exit until this is called - see {@link shutdown}.
-     */
-    static end(): void;
-}
-
 type SkinGeometries = Record<SkinPart, TripleArray>;
 declare const classicSkinGeometries: SkinGeometries;
 declare const slimSkinGeometries: SkinGeometries;
@@ -1487,6 +1582,19 @@ type SkinTextureCoordinates = Record<SkinPart, ModelFaces>;
 declare const classicSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 declare const slimSkinTextureCoordinates: Readonly<SkinTextureCoordinates>;
 
+interface SkinTexture {
+    material: MeshBasicMaterial;
+    slim: boolean;
+    legacy: boolean;
+}
+declare class SkinTextures {
+    static get(src: string, legacy?: boolean): Promise<SkinTexture>;
+    static getCape(src: string, layout?: CapeLayout): Promise<MeshBasicMaterial>;
+    private static createMaterial;
+    private static isSlim;
+    private static normalizeLegacy;
+}
+
 declare class Skins {
     static fromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
     static fromUuid(uuid: string): Promise<Maybe<string>>;
@@ -1495,8 +1603,11 @@ declare class Skins {
     static capeFromUuidOrUsername(uuidOrUsername: string): Promise<Maybe<string>>;
     static capeFromUuid(uuid: string): Promise<Maybe<string>>;
     static capeFromUsername(username: string): Promise<Maybe<string>>;
-    static capeFromCapesDev(uuid: string, capeType?: string): Promise<Maybe<string>>;
+    /** Returns a full static cape texture for a username or UUID. */
+    static capeFromCapesDev(player: string, capeType?: string): Promise<Maybe<string>>;
     private static usernameToUuid;
+    private static usernameToUuidMcProxy;
+    /** @deprecated **/
     private static usernameToUuidSkinProxy;
     private static usernameToUuidMineTools;
     private static getProfileFromMinetools;
@@ -1506,11 +1617,18 @@ declare class Skins {
     private static getCrafatarCapeUrl;
     private static getMcHeadsSkinUrl;
     private static getMineSkinPlayerSkinUrl;
+    /** @deprecated **/
     private static getSkinProxySkinUrl;
+    /** @deprecated **/
     private static getSkinProxyCapeUrl;
+    private static getMcProxySkinUrl;
+    private static getMcProxyCapeUrl;
 }
 
 declare class TextureLoader {
+    private static readonly failedTextures;
+    /** Reports whether image loading failed, so cached textures can be retried. */
+    static hasFailed(texture: Texture): boolean;
     protected static createTexture(): Texture;
     static loadInBackground(src: string, format?: PixelFormat, rotation?: number): Texture;
     static load(src: string, format?: PixelFormat, rotation?: number): Texture;
@@ -1524,12 +1642,12 @@ declare class Textures {
     static getImage(key: TextureKey): Texture;
 }
 
-declare function mergeBufferGeometries(geometries: BufferGeometry$1[], useGroups?: boolean): BufferGeometry$1;
+declare function mergeBufferGeometries(geometries: BufferGeometry[], useGroups?: boolean): BufferGeometry;
 declare function mergeBufferAttributes(attributes: BufferAttribute[]): BufferAttribute;
 declare function interleaveAttributes(attributes: BufferAttribute[]): InterleavedBufferAttribute;
-declare function estimateBytesUsed(geometry: BufferGeometry$1): number;
-declare function mergeVertices(geometry: BufferGeometry$1, tolerance?: number): BufferGeometry$1;
-declare function toTrianglesDrawMode(geometry: BufferGeometry$1, drawMode: TrianglesDrawModes): BufferGeometry$1;
+declare function estimateBytesUsed(geometry: BufferGeometry): number;
+declare function mergeVertices(geometry: BufferGeometry, tolerance?: number): BufferGeometry;
+declare function toTrianglesDrawMode(geometry: BufferGeometry, drawMode: TrianglesDrawModes): BufferGeometry;
 declare function computeMorphedAttributes(object: Mesh | Line | Points): object;
 
 interface BlockInfo {
@@ -1626,4 +1744,4 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, ArchiveAssetSource, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Block, BlockEntityModels, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, type BlockStateVariant, type BlockStateVariants, BlockStates, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, type CacheKey, Caching, type CameraOptions, CanvasImage, Chunk, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, type Cube, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, type Disposable, type DoubleArray, type ElementFace, type ElementRotation, Entities, type EntityModel, EntityModels, EntityObject, type EntityObjectOptions, Env, type EnvProvider, type ExtractableImageData, type FromTo, Geometries, GuiLight, GuiObject, type GuiObjectOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, type ModelPart, ModelTextures, Models, type MultiBlockBlock, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererOptions, Requests, type ResponseParser, SKIN_PARTS, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, type Serializable, type SkinGeometries, SkinObject, type SkinObjectOptions, SkinPart, type SkinTextureCoordinates, Skins, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, applyModelPartRotation, axisToVec3, base64decode, base64encode, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createImage, estimateBytesUsed, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, 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 BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, 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 EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, EntityObject, type EntityObjectOptions, Env, type EnvProvider, type ExtractableImageData, type FromTo, Geometries, GuiLight, GuiObject, type GuiObjectOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ListAsset, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, PersistentCache, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResponseParser, SKIN_PARTS, SceneInspector, SceneObject, type SceneObjectOptions, SceneStats, SceneStatsDisplay, SchematicParser, type Serializable, type SkinGeometries, 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, createImage, estimateBytesUsed, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, prefix, registerNodeEnv, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode };