minerender 2.1.0-alpha.75 → 2.1.0-alpha.76

package/dist/node/index.mjs

@@ -68,6 +68,7 @@ var init_PersistentCache = __esm({
         /** Bump to invalidate every persisted entry. */
         this.VERSION = 2;
       }
+      /** Opens a named store in the active environment using the current cache schema version. */
       static open(name) {
         return Env.provider.openCache(name, _PersistentCache.VERSION);
       }
@@ -329,6 +330,7 @@ var init_Caching = __esm({
           this.fontCache
         ];
       }
+      /** Invalidates in-memory entries so later lookups reload them. Persisted entries are retained. */
       static clear() {
         for (const cache of this.all) {
           cache.invalidateAll();
@@ -371,6 +373,7 @@ var init_Geometries = __esm({
         }
         return geometry;
       }
+      /** Returns shared geometry. Use {@link createBox} when the caller needs to modify or dispose it independently. */
       static getBox(key) {
         const keyStr = serializeBoxGeometryKey(key);
         return Caching.boxGeometryCache.get(keyStr, (k) => {
@@ -554,12 +557,15 @@ var init_Requests = __esm({
       static {
         this.mcAssetRequestQueue = new RequestQueue();
       }
+      /** Queues a general request. Set `request.signal` to cancel it and `request.timeout` to limit each attempt. */
       static genericRequest(request) {
         return this.genericQueue.request(request);
       }
+      /** Queues a request separately from general traffic, using the configured asset base URL for relative paths. */
       static mcAssetRequest(request) {
         return this.mcAssetRequestQueue.request(request);
       }
+      /** Sets the base URL for relative asset requests. Use {@link AssetLoader.setVersion} to change Minecraft versions. */
       static setMcAssetRoot(root) {
         this.mcAssetRequestQueue.baseURL = root;
       }
@@ -612,6 +618,7 @@ var init_WrappedImage = __esm({
         }
         return false;
       }
+      /** Whether the dimensions form a vertical strip of square frames, without consulting `.mcmeta`. */
       get animated() {
         return this.height > this.width && this.height % this.width === 0;
       }
@@ -658,6 +665,7 @@ var init_ImageLoader = __esm({
       static _createImage() {
         return createImage();
       }
+      /** Resolves when an image URL has decoded, or rejects if decoding fails. */
       static async loadAsync(src) {
         return new Promise((resolve, reject) => {
           const image = this._createImage();
@@ -666,6 +674,7 @@ var init_ImageLoader = __esm({
           image.src = src;
         });
       }
+      /** Returns an image immediately. Use the callbacks to observe loading, or await {@link loadAsync}. */
       static loadElement(src, onload, onerr) {
         const image = this._createImage();
         if (onload)
@@ -693,6 +702,7 @@ var init_ImageLoader = __esm({
           throw err;
         }
       }
+      /** Decodes the supplied bytes into a canvas without fetching the source URL again. */
       static async infoToCanvasData(info) {
         const type = info.type === "jpg" ? "jpeg" : info.type ?? "png";
         const image = await _ImageLoader.loadAsync(`data:image/${type};base64,${info.data.toString("base64")}`);
@@ -709,12 +719,14 @@ var init_ImageLoader = __esm({
         const image = await this.infoToCanvasData(info);
         return image.data.getImageData(0, 0, image.width, image.height);
       }
+      /** Returns cached RGBA pixels for an image URL or data URL. Failed loads can be retried. */
       static async getData(src) {
         const keyStr = serializeImageKey({ src });
         return await Caching.imageDataCache.get(keyStr, (k) => {
           return _ImageLoader.loadData(src);
         });
       }
+      /** Returns a cached canvas context and dimensions for an image URL or data URL. */
       static async getCanvasData(src) {
         const keyStr = serializeImageKey({ src });
         return await Caching.canvasImageDataCache.get(keyStr, (k) => {
@@ -814,6 +826,7 @@ var init_TextureLoader = __esm({
         texture.rotation = rotation;
         return Textures.initTextureProps(texture);
       }
+      /** Loads image pixels in the background. `rotation` is in radians. Check {@link hasFailed} for load failures. */
       static load(src, format2 = RGBAFormat, rotation = 0) {
         const texture = new Texture();
         texture.colorSpace = THREE.SRGBColorSpace;
@@ -862,6 +875,7 @@ var init_Textures = __esm({
           return this.initTextureProps(texture);
         });
       }
+      /** Sets nearest-neighbor filters without changing the texture's color space. Returns the same texture. */
       static initTextureProps(texture) {
         texture.magFilter = THREE2.NearestFilter;
         texture.minFilter = THREE2.NearestFilter;
@@ -874,11 +888,13 @@ var init_Textures = __esm({
       static createAsset(key) {
         return new Texture2();
       }
+      /** Creates an sRGB color texture from a canvas. */
       static createCanvasTexture(canvas) {
         const texture = new CanvasTexture(canvas);
         texture.colorSpace = THREE2.SRGBColorSpace;
         return this.initTextureProps(texture);
       }
+      /** Returns a shared texture immediately and loads its image asynchronously. Failed cached loads are retried. */
       static getImage(key) {
         const keyStr = serializeTextureKey(key);
         const cached2 = Caching.textureCache.peek(keyStr);
@@ -903,6 +919,7 @@ var init_Materials = __esm({
     init_TextureLoader();
     init_Caching();
     Materials = class _Materials {
+      /** Shared checkerboard material, created on first access. */
       static get MISSING_TEXTURE() {
         return Caching.materialCache.get("builtin:missing-texture", () => new MeshBasicMaterial({
           map: Textures.getMissing(),
@@ -1006,6 +1023,7 @@ var init_Materials = __esm({
         if (tint !== void 0) material.color.multiply(new Color(tint));
         return material;
       }
+      /** Creates an unlit, transparent GUI material without depth writes or tone mapping. */
       static createGuiCanvasMaterial(canvas) {
         const material = new MeshBasicMaterial({
           map: Textures.createCanvasTexture(canvas),
@@ -1172,6 +1190,7 @@ var init_Materials = __esm({
         }
         return this.createBasicCanvasMaterial(canvas, transparent, shade);
       }
+      /** Returns a shared image material. Use {@link createImage} for a separate material instance. */
       static getImage(key) {
         const keyStr = serializeMaterialKey(key);
         const map = Caching.materialCache.peek(keyStr)?.map;
@@ -1346,6 +1365,14 @@ var init_AssetKey = __esm({
       }
     };
     AssetKey = class _AssetKey extends BasicAssetKey {
+      /**
+       * 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, path, assetType, type, rootType = "assets", extension = ".json", root) {
         super(namespace, path);
         this.namespace = namespace;
@@ -1357,6 +1384,16 @@ var init_AssetKey = __esm({
         this.root = root;
         this.isAssetKey = true;
       }
+      /**
+       * 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, str, origin) {
         let namespace = origin?.namespace || DEFAULT_NAMESPACE;
         if (str.includes(":")) {
@@ -1388,6 +1425,7 @@ var init_AssetKey = __esm({
         ];
         return a.join("/");
       }
+      /** Joins the type subdirectory and path without adding a namespace or file extension. */
       getFullPath() {
         let p10 = [];
         if (this.type) {
@@ -1399,6 +1437,7 @@ var init_AssetKey = __esm({
       toNamespacedString() {
         return this.namespace + ":" + this.getFullPath();
       }
+      /** Returns a cache identifier that includes the explicit root or {@link AssetLoader.ROOT}. */
       serialize() {
         return this.toString();
       }
@@ -1458,6 +1497,7 @@ var init_DisplayTransforms = __esm({
         const scale = new Vector32(...transform.scale ?? [1, 1, 1]).clampScalar(-4, 4);
         return new Matrix4().compose(translation, rotation, scale);
       }
+      /** Transforms geometry in place and reverses triangle winding when the matrix reflects it. */
       static apply(geometry, matrix) {
         geometry.applyMatrix4(matrix);
         if (matrix.determinant() < 0) {
@@ -1485,6 +1525,7 @@ var init_ModelMerger = __esm({
     init_AssetKey();
     init_DisplayTransforms();
     ModelMerger = class {
+      /** Loads the parent chain and returns a merged model without modifying the supplied definition. */
       static async mergeWithParents(model) {
         const models = await this.collectAllParents(model);
         let merged = {};
@@ -1552,6 +1593,7 @@ var init_Models = __esm({
       static get PERSISTENT_CACHE() {
         return this._persistentCache ??= PersistentCache.open("minerender-models");
       }
+      /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
       static async getItemList() {
         const key = new AssetKey(DEFAULT_NAMESPACE, "_list", "items");
         const legacyKey = new AssetKey(DEFAULT_NAMESPACE, "_list", "models", "item");
@@ -1622,6 +1664,7 @@ var init_Models = __esm({
         }
         throw new Error(`Unsupported item model ${node?.type ?? "definition"} for ${key.toNamespacedString()}`);
       }
+      /** Loads one model file without resolving its parents. Returns `undefined` when the file is missing. */
       static async getRaw(key) {
         if (!key.assetType) {
           key.assetType = "models";
@@ -1641,6 +1684,12 @@ var init_Models = __esm({
           return asset;
         });
       }
+      /**
+       * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
+       * Item keys use GUI context, false conditions, and zero numeric properties.
+       *
+       * @param key - Model key, for example `AssetKey.parse("models", "minecraft:item/diamond_sword")`.
+       */
       static async getMerged(key) {
         if (!key.assetType) {
           key.assetType = "models";
@@ -1653,9 +1702,11 @@ var init_Models = __esm({
           return _Models.loadAndMerge(key);
         });
       }
+      /** Alias for {@link getMerged}. */
       static async get(key) {
         return this.getMerged(key);
       }
+      /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
       static async clearCache() {
         return this.PERSISTENT_CACHE.clear();
       }
@@ -1678,6 +1729,7 @@ var init_BlockStates = __esm({
         return this._persistentCache ??= PersistentCache.open("minerender-blockstates");
       }
       // BlockState names are hardcoded
+      /** Returns blockstate filenames from the selected version's `_list.json`, or an empty list. */
       static async getList() {
         const key = new AssetKey(
           DEFAULT_NAMESPACE,
@@ -1698,6 +1750,7 @@ var init_BlockStates = __esm({
           return AssetLoader.get(key, "json" /* JSON */);
         });
       }
+      /** Looks up vanilla property definitions for the key's block path, or returns `undefined`. */
       static async getDefaultState(key) {
         const defaultStates = await this.getDefaultStates();
         if (!defaultStates) {
@@ -1705,6 +1758,7 @@ var init_BlockStates = __esm({
         }
         return defaultStates["minecraft:" + key.path];
       }
+      /** Loads a cached blockstate definition for {@link MineRenderScene.addBlock}, or returns `undefined`. */
       static async get(key) {
         if (!key.assetType) {
           key.assetType = "blockstates";
@@ -1731,6 +1785,7 @@ var init_BlockStates = __esm({
         }
         return Promise.all(promises);
       }
+      /** Clears persisted blockstates. Use {@link Caching.clear} to also discard in-memory assets. */
       static async clearCache() {
         await this.PERSISTENT_CACHE.clear();
       }
@@ -1756,9 +1811,11 @@ var init_Assets = __esm({
       static parseAssetKey(assetType, str, origin) {
         return AssetKey.parse(assetType, str, origin);
       }
+      /** Loads a model with its parent chain resolved. See {@link Models.getMerged}. */
       static async getModel(key) {
         return Models.getMerged(key);
       }
+      /** Loads a blockstate definition. See {@link BlockStates.get}. */
       static async getBlockState(key) {
         return BlockStates.get(key);
       }
@@ -1805,6 +1862,10 @@ var BatchedExecutor;
 var init_BatchedExecutor = __esm({
   "src/util/BatchedExecutor.ts"() {
     BatchedExecutor = class {
+      /**
+       * @param interval - Delay between queue runs, in milliseconds.
+       * @param batch - Maximum tasks started per run and maximum tasks active at once.
+       */
       constructor(interval = 1, batch = 30) {
         if (!Number.isFinite(interval) || interval < 0) throw new RangeError("Batch interval must be finite and nonnegative");
         if (!Number.isInteger(batch) || batch < 1) throw new RangeError("Batch size must be a positive integer");
@@ -1812,9 +1873,11 @@ var init_BatchedExecutor = __esm({
         this.batch = batch;
         this.queue = new JobQueue2(async (task) => task(), { interval, maxPerRun: batch, maxActive: batch });
       }
+      /** Queues a task and resolves with its result, or rejects with its error. */
       submit(task) {
         return this.queue.add(() => task());
       }
+      /** Rejects queued and future tasks. Tasks already running are allowed to finish. */
       stop() {
         this.queue.end();
       }
@@ -1956,6 +2019,7 @@ var NBTHelper;
 var init_NBTHelper = __esm({
   "src/nbt/NBTHelper.ts"() {
     NBTHelper = class {
+      /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
       static async fromBuffer(data, format2) {
         const buffer = Buffer3.from(data instanceof Uint8Array ? data : new Uint8Array(data));
         const prismarineNbt = await import("prismarine-nbt");
@@ -2100,6 +2164,7 @@ var init_HostedAssetSource = __esm({
           ["json" /* JSON */, _HostedAssetSource.JSON]
         ]);
       }
+      /** Retries missing assets with the `minecraft` namespace and default root. Other failures reject. */
       async loadOrRetryWithDefaults(key, parser) {
         const direct = await this.load(key, parser);
         if (typeof direct !== "undefined") {
@@ -2157,6 +2222,10 @@ var init_HostedAssetSource = __esm({
       assetBasePath(key) {
         return `${key.root ?? this.root ?? AssetLoader.ROOT}/${key.rootType !== void 0 ? key.rootType + "/" : ""}${key.namespace !== void 0 ? key.namespace + "/" : ""}${key.assetType !== void 0 ? key.assetType + "/" : ""}`;
       }
+      /**
+       * Creates a hosted source for {@link AssetLoader.addSource}.
+       * Set `options.retryDefaults` to `false` to restrict lookups to the requested namespace and root.
+       */
       constructor(root, options) {
         super();
         this._root = root;
@@ -2188,6 +2257,11 @@ var BrowserArchiveProxy;
 var init_BrowserArchiveProxy = __esm({
   "src/assets/source/archive/BrowserArchiveProxy.ts"() {
     BrowserArchiveProxy = class {
+      /**
+       * 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, id) {
         this._blob = blob;
         this._reader = new ZipReader(new BlobReader(this._blob));
@@ -2387,6 +2461,7 @@ var init_ArchiveAssetSource = __esm({
           dataPackFormat: copyFormat(options.dataPackFormat)
         };
       }
+      /** Creates a browser ZIP source from a Blob or File. */
       static blob(blob, options) {
         return new _ArchiveAssetSource(new BrowserArchiveProxy(blob), options);
       }
@@ -2519,6 +2594,7 @@ var init_AssetLoader = __esm({
     FALLBACK_ROOT = "https://raw.githubusercontent.com/InventivetalentDev/minerender-fallback-assets/master";
     AssetLoader = class {
       static {
+        /** Default asset base URL. Use {@link setVersion} to select a Minecraft version. */
         this.ROOT = DEFAULT_ROOT;
       }
       static {
@@ -2531,6 +2607,7 @@ var init_AssetLoader = __esm({
       static get version() {
         return this.ROOT.substring(this.ROOT.lastIndexOf("/") + 1);
       }
+      /** Selects an mcasset.cloud version, updates the vanilla source, and clears in-memory caches. */
       static setVersion(version) {
         this.ROOT = `https://assets.mcasset.cloud/${version}`;
         const source = new HostedAssetSource(this.ROOT, { retryDefaults: false });
@@ -2564,6 +2641,13 @@ var init_AssetLoader = __esm({
         return scope ? `${scope}
 ${key}` : key;
       }
+      /**
+       * 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, source, override = true) {
         if (override) {
           const existing = this.removeSource(key);
@@ -2574,6 +2658,7 @@ ${key}` : key;
         this._SOURCES.unshift({ key, source });
         console.log(p4, "Added AssetSource", key);
       }
+      /** Removes and returns the first source with this name. Call {@link Caching.clear} to reload assets. */
       static removeSource(key) {
         const index = this._SOURCES.findIndex((s) => s.key === key);
         if (index != -1) {
@@ -2588,6 +2673,7 @@ ${key}` : key;
         this.addSource("mcassets-fallback", new HostedAssetSource(FALLBACK_ROOT, { retryDefaults: false }));
         this.addSource("mcassets", new HostedAssetSource(this.ROOT, { retryDefaults: false }));
       }
+      /** Loads from all sources and returns defined results in priority order. Any source failure rejects the call. */
       static async getAll(key, parser) {
         const sources = [...this._SOURCES];
         const results = [];
@@ -2649,6 +2735,7 @@ var init_ModelTextures = __esm({
       static get PERSISTENT_META_CACHE() {
         return this._persistentMetaCache ??= PersistentCache.open("minerender-texturemeta");
       }
+      /** Loads and decodes a texture into a readable canvas, or returns `undefined` when missing. */
       static async get(key) {
         const keyStr = key.serialize();
         const pending = this.preload(key);
@@ -2666,6 +2753,7 @@ var init_ModelTextures = __esm({
           throw err;
         }
       }
+      /** Fetches and caches encoded texture bytes without decoding the pixels. */
       static async preload(key) {
         const keyStr = key.serialize();
         return Caching.textureAssetCache.get(keyStr, (k) => {
@@ -2676,6 +2764,7 @@ var init_ModelTextures = __esm({
           });
         });
       }
+      /** Loads a texture's `.mcmeta` file, or returns `undefined` when no metadata file exists. */
       static async getMeta(key) {
         if (!key.extension || !key.extension.endsWith(".mcmeta")) {
           key = Object.assign(new AssetKey("", ""), key);
@@ -2692,6 +2781,7 @@ var init_ModelTextures = __esm({
           });
         });
       }
+      /** Clears persisted texture metadata. Use {@link Caching.clear} to discard in-memory textures and metadata. */
       static async clearCache() {
         await this.PERSISTENT_META_CACHE.clear();
       }
@@ -2779,6 +2869,7 @@ var init_Ticker = __esm({
         }
         return handle;
       }
+      /** Starts or resumes the shared tick loop. Repeated calls have no effect. */
       static start() {
         if (this.interval) return;
         this.interval = this.schedule(() => {
@@ -2801,6 +2892,7 @@ var init_Ticker = __esm({
           _Ticker.fiveSecondTicks = 0;
         }, 1e3 * 5);
       }
+      /** Pauses the loop while retaining callbacks for a later {@link start}. */
       static stop() {
         if (this.interval) clearInterval(this.interval);
         if (this.oneSecondTicksTracker) clearInterval(this.oneSecondTicksTracker);
@@ -2809,12 +2901,14 @@ var init_Ticker = __esm({
         this.oneSecondTicksTracker = void 0;
         this.fiveSecondTicksTracker = void 0;
       }
+      /** Registers a callback, starts the loop if needed, and returns an ID for {@link remove}. */
       static add(tick) {
         this.start();
         const c = this.counter++;
         this._tickers.set(c, tick);
         return c;
       }
+      /** Removes a callback by ID and stops the timers when no callbacks remain. */
       static remove(c) {
         if (typeof c === "number") this._tickers.delete(c);
         if (!this._tickers.size) this.stop();
@@ -2828,6 +2922,7 @@ var init_Ticker = __esm({
       static get tpsFiveSeconds() {
         return this.fiveSecondTps;
       }
+      /** Stops the loop and removes all registered callbacks. */
       static dispose() {
         this.stop();
         this._tickers.clear();
@@ -2874,6 +2969,7 @@ var init_TextureAtlas = __esm({
           }
         };
       }
+      /** Copies pixels for a texture variable from its current atlas rectangle. */
       getData(texture) {
         const pos = this.positions[texture];
         const size = this.sizes[texture];
@@ -3153,6 +3249,7 @@ var init_UVMapper = __esm({
         }
         uv.needsUpdate = true;
       }
+      /** Returns the shared atlas for a keyed, merged model, creating it on first use. */
       static async getAtlas(model) {
         const keyStr = model.key.serialize();
         return Caching.modelTextureAtlasCache.get(keyStr, (k) => {
@@ -3223,6 +3320,11 @@ var init_UVMapper = __esm({
         }
         return [tl, tr, bl, br];
       }
+      /**
+       * 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 async createAtlas(originalModel) {
         const textureMap = {};
         const metaMap = {};
@@ -3587,6 +3689,7 @@ var init_Entities = __esm({
     init_MineRenderError();
     init_ModelTextures();
     Entities = class {
+      /** Lists model paths in the `minecraft` namespace, including subdirectories and excluding `.json`. */
       static async getEntityList() {
         const collect = async (path) => {
           const prefix2 = path ? `${path}/` : "";
@@ -3604,6 +3707,7 @@ var init_Entities = __esm({
         const key = new AssetKey(modelKey.namespace, path, void 0, void 0, "entity-models", ".json", isAssetKey(modelKey) ? modelKey.root : void 0);
         return Caching.entityModelCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
       }
+      /** Returns selectable geometry-layer names, or an empty list when the model is missing. */
       static async getLayerList(modelKey) {
         return Object.keys((await this.getModelFile(modelKey))?.layers ?? {});
       }
@@ -3611,6 +3715,15 @@ var init_Entities = __esm({
       static async getPassList(modelKey) {
         return (await this.getModelFile(modelKey))?.passes ?? [];
       }
+      /**
+       * 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 async getEntity(modelKey, textureKey, options) {
         const model = await this.getModelFile(modelKey);
         if (!model) return void 0;
@@ -3656,6 +3769,7 @@ var init_Entities = __esm({
         const file = await Caching.entityAnimationCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
         return file?.animations;
       }
+      /** Finds a fallback texture using the model path, its directory, and vanilla variant data. */
       static async resolveTexture(modelKey) {
         const path = isAssetKey(modelKey) ? modelKey.getFullPath() : modelKey.path;
         const root = isAssetKey(modelKey) ? modelKey.root : void 0;
@@ -3816,12 +3930,14 @@ var init_EntityAnimationPlayer = __esm({
         this._animation = void 0;
         this._time = 0;
       }
+      /** Applies the pose at an absolute playback time. Returns `false` when no clip is active. */
       setTime(seconds) {
         if (!this._animation) return false;
         this._time = seconds;
         this.apply();
         return true;
       }
+      /** Advances playback by elapsed seconds multiplied by the speed passed to {@link play}. */
       advance(deltaSeconds) {
         return this.setTime(this._time + deltaSeconds * this.speed);
       }
@@ -3859,6 +3975,7 @@ var init_InstanceReference = __esm({
         if (!this.instanceable.isInstanceActive(this.index, this)) throw new MineRenderError("Instance has been removed");
         return this.instanceable;
       }
+      /** Releases this placement's slot for reuse. Repeated calls have no effect. */
       removeFromScene() {
         if (this.instanceable.isInstanceActive(this.index, this)) this.instanceable.removeInstanceAt(this.index);
       }
@@ -3871,9 +3988,11 @@ var init_InstanceReference = __esm({
       setMatrix(matrix) {
         this.activeInstanceable.setMatrixAt(this.index, matrix);
       }
+      /** Hides or restores this placement while preserving its transform and allocated slot. */
       setVisible(visible) {
         this.activeInstanceable.setInstanceVisibleAt(this.index, visible);
       }
+      /** Updates the supplied transform components. Positions use scene units and rotations use radians. */
       setPositionRotationScale(position, rotation, scale) {
         this.activeInstanceable.setPositionRotationScaleAt(this.index, position, rotation, scale);
       }
@@ -3950,6 +4069,7 @@ var init_SceneObject = __esm({
       }
       async init() {
       }
+      /** Marks ancestor scenes for redraw and emits a `change` event. */
       notifyDirty() {
         this.traverseAncestors((parent) => {
           const scene = parent;
@@ -3985,15 +4105,17 @@ var init_SceneObject = __esm({
         return obj;
       }
       /**
-       * 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) {
         return this.getObjectByName(`group:${name}`);
       }
       /**
-       * 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, visible) {
         return this.toggleObjectVisibility(this.getGroupByName(name), visible);
@@ -4044,15 +4166,16 @@ var init_SceneObject = __esm({
         return mesh;
       }
       /**
-       * Get a mesh by its name
+       * Finds a named mesh without the internal `mesh:` prefix, or returns `undefined`.
        */
       getMeshByName(name) {
         return this.getObjectByName(`mesh:${name}`);
       }
       /**
-       * 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, visible) {
         return this.toggleObjectVisibility(this.getMeshByName(name), visible);
@@ -4098,12 +4221,14 @@ var init_SceneObject = __esm({
       get isInstanced() {
         return this._isInstanced;
       }
+      /** Number of live placements, excluding released instance slots. */
       get instanceCounter() {
         return this._instanceCounter;
       }
       constructInstanceReference(i) {
         return new InstanceReference(this, i);
       }
+      /** Allocates a placement of this instanced object, reusing a released slot when available. */
       nextInstance() {
         const mesh = this.instanceMesh;
         if (!mesh) throw new MineRenderError("Object is not instanced");
@@ -4250,6 +4375,7 @@ var init_SceneObject = __esm({
         vector.setFromMatrixScale(matrix);
         return vector;
       }
+      /** Updates supplied transform components. For a shared model, affects every live instance. */
       setPositionRotationScale(position, rotation, scale) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4268,6 +4394,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Sets position in scene units. For a shared model, updates every live instance. */
       setPosition(position) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4285,6 +4412,7 @@ var init_SceneObject = __esm({
           return this.position;
         }
       }
+      /** Sets rotation in radians. For a shared model, updates every live instance. */
       setRotation(rotation) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4302,6 +4430,7 @@ var init_SceneObject = __esm({
           return this.rotation;
         }
       }
+      /** Sets scale factors. For a shared model, updates every live instance. */
       setScale(scale) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4339,6 +4468,7 @@ var init_SceneObject = __esm({
         this.notifyDirty();
         super.dispose();
       }
+      /** Releases instance slots and removes children, disposing children that implement Disposable. */
       disposeAndRemoveAllChildren() {
         if (this.instanceMesh) {
           if (this._scene) this._scene.stats.instanceCount -= this.instanceReferences.size;
@@ -4361,6 +4491,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Detaches the object from its parent and requests a redraw. */
       removeFromScene() {
         this.notifyDirty();
         this.removeFromParent();
@@ -4512,12 +4643,15 @@ var init_EntityObject = __esm({
         if (this.animationPlayers.length) this.notifyDirty();
       }
       //</editor-fold>
+      /** Finds a selected draw by its layer key, such as `main` or `main#2`, or returns `undefined`. */
       getLayerGroup(name) {
         return super.getGroupByName(`layer:${name}`);
       }
+      /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
       getGroupByName(name, layerName) {
         return layerName === void 0 ? super.getGroupByName(name) : this.getLayerGroup(layerName)?.getObjectByName(`group:${name}`);
       }
+      /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
       getMeshByName(name, layerName) {
         return layerName === void 0 ? super.getMeshByName(name) : this.getLayerGroup(layerName)?.getObjectByName(`mesh:${name}`);
       }
@@ -5188,6 +5322,7 @@ var init_ModelCulling = __esm({
   "src/model/ModelCulling.ts"() {
     init_CubeFace();
     ModelCulling = class {
+      /** Rotates a world-direction bit mask into model space. Bits follow {@link CUBE_FACES}. */
       static toLocalMask(worldMask, rotation) {
         let localMask = 0;
         for (const [localFace, offset] of CUBE_FACE_OFFSETS.entries()) {
@@ -5198,6 +5333,7 @@ var init_ModelCulling = __esm({
         }
         return localMask;
       }
+      /** Whether a model fills one block with opaque faces and can hide adjacent block faces. */
       static isOpaqueFullCube(atlas) {
         if (!atlas || atlas.hasTransparency !== false || atlas.model.elements?.length !== 1) return false;
         const element = atlas.model.elements[0];
@@ -5982,6 +6118,7 @@ var Meshes = class _Meshes {
   static createBox(key) {
     return new Mesh(Geometries.getBox(key.geometry), Materials.getImage(key.material));
   }
+  /** Returns a shared Mesh object. Use {@link createBox} for a mesh with its own transform and parent. */
   static getBox(key) {
     const keyStr = serializeMeshKey(key);
     return Caching.boxMeshCache.get(keyStr, (k) => {
@@ -6094,6 +6231,7 @@ init_AssetParsers();
 init_ModelTextures();
 init_Caching();
 var Fonts = class {
+  /** Combines font definitions in source-priority order. Unsupported Unihex and TrueType providers are skipped. */
   static async get(key = "minecraft:default") {
     const fontKey = typeof key === "string" ? AssetKey.parse("font", key) : key;
     return await Caching.fontCache.get(fontKey.serialize(), () => this.load(fontKey, []));
@@ -9310,6 +9448,13 @@ var GuiHelper = class {
     });
     return layers;
   }
+  /**
+   * 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, origin = [0, 0], offset = [18, 18], rowSize = 9) {
     const [column, row] = typeof slot === "number" ? [slot % rowSize, Math.floor(slot / rowSize)] : slot;
     return [origin[0] + column * offset[0], origin[1] + row * offset[1]];
@@ -9967,6 +10112,7 @@ var SceneStatsDisplay = class {
   appendTo(el) {
     el.append(this.statsContainer);
   }
+  /** Stops the refresh timer and removes the panel from the page. */
   dispose() {
     clearInterval(this.interval);
     this.interval = void 0;
@@ -9991,6 +10137,7 @@ var InstanceManager = class {
     this.isInstanceManager = true;
     this.instanceCache = {};
   }
+  /** Allocates a new placement of a cached model, or returns `undefined` if the key is unknown. */
   async get(key) {
     if (key in this.instanceCache) {
       console.debug(p9, "key in cache", key);
@@ -9998,6 +10145,7 @@ var InstanceManager = class {
     }
     return void 0;
   }
+  /** Allocates a placement, calling the supplier once when the shared model is first needed. */
   async getOrCreate(key, supplier) {
     if (key in this.instanceCache) {
       return await this.get(key);
@@ -10014,6 +10162,7 @@ var InstanceManager = class {
       throw error;
     }
   }
+  /** Forgets cached models without disposing them or releasing their existing placements. */
   reset() {
     for (let instanceCacheKey in this.instanceCache) {
       delete this.instanceCache[instanceCacheKey];
@@ -10059,6 +10208,7 @@ function matchesCondition(condition, state) {
   });
 }
 var BlockStateResolver = class {
+  /** Loads vanilla property defaults, falling back to preview values inferred from the blockstate file. */
   static async defaults(blockState) {
     const defaults = blockState.key ? await BlockStates.getDefaultState(blockState.key) : void 0;
     const state = {};
@@ -10078,9 +10228,11 @@ var BlockStateResolver = class {
     }
     return state;
   }
+  /** Selects matching models. Supply `choose` to control selection within each alternatives array. */
   static select(blockState, state, choose = this.choose) {
     return this.matching(blockState, state).map(choose);
   }
+  /** Returns matching model groups before choosing weighted alternatives. */
   static matching(blockState, state) {
     const out = [];
     if (blockState.variants) {
@@ -10104,6 +10256,7 @@ var BlockStateResolver = class {
     }
     return out;
   }
+  /** Selects a random alternative using positive integer weights, each defaulting to 1. */
   static choose(variants) {
     if (!Array.isArray(variants)) return variants;
     if (!variants.length) throw new MineRenderError("Blockstate variant arrays must not be empty");
@@ -10121,6 +10274,7 @@ var BlockStateResolver = class {
     }
     return variants[variants.length - 1];
   }
+  /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
   static rotation(variant) {
     const rotation = new Euler8();
     if (typeof variant.x !== "undefined") {
@@ -10407,6 +10561,7 @@ var BlockObject = class _BlockObject extends SceneObject {
     }
     this.notifyDirty();
   }
+  /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
   get state() {
     return this._state;
   }
@@ -10506,6 +10661,7 @@ var BlockObject = class _BlockObject extends SceneObject {
     obj.setPosition(this.position);
     return obj;
   }
+  /** Clears selected properties and rebuilds models without reapplying property defaults. */
   async resetState() {
     this._previousState = this._state;
     this._state = {};
@@ -12405,6 +12561,11 @@ function compoundList(tags, name) {
 // src/model/multiblock/StructureParser.ts
 init_MineRenderError();
 var StructureParser = class {
+  /**
+   * 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 async parse(_nbt, paletteIndex) {
     const nbt = _nbt.value;
     let palette;
@@ -13239,6 +13400,7 @@ var SkinImage = class {
 // src/skin/SkinTextures.ts
 init_Textures();
 var SkinTextures = class {
+  /** Loads a skin URL. Pass `legacy` to override layout detection from the image dimensions. */
   static async get(src, legacy) {
     const image = await SkinImage.getData(src);
     const scale = image.width / 64;
@@ -13412,6 +13574,14 @@ var SkinObject = class extends SceneObject {
       }
     }
   }
+  /**
+   * 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.
+   */
   async setSkinTexture(src) {
     if (typeof src === "undefined") return;
     this.skinTextureSrc = src;
@@ -13563,6 +13733,7 @@ var MineRenderScene = class _MineRenderScene extends Scene4 {
       this.stats.sceneObjectCount += change;
     }
   }
+  /** Initializes each object before attaching it to the scene. */
   async initAndAdd(...object2) {
     this.dirty = true;
     for (let obj of object2) {
@@ -13598,13 +13769,33 @@ var MineRenderScene = class _MineRenderScene extends Scene4 {
       return obj;
     }
   }
+  /**
+   * 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.
+   */
   async addModel(model, options, parent = this) {
     options = { ...options, tints: await ItemTints.get(model, options?.tints) };
     return this.addSceneObject(model, () => new ModelObject(model, options), options, parent);
   }
+  /**
+   * 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.
+   */
   async addBlock(blockState, options, parent = this) {
     return this.addSceneObject(blockState, () => new BlockObject(blockState, options), options, parent);
   }
+  /**
+   * 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.
+   */
   async addSkin(skin, options, parent = this) {
     this.dirty = true;
     const obj = new SkinObject(options);
@@ -13616,9 +13807,14 @@ var MineRenderScene = class _MineRenderScene extends Scene4 {
     parent.add(obj);
     return obj;
   }
+  /** Adds an entity loaded with {@link Entities.getEntity}, using its selected layers and textures. */
   async addEntity(entity, options, parent = this) {
     return this.addSceneObject(entity, () => new EntityObject(entity, options), options, parent);
   }
+  /**
+   * 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.
+   */
   async addGui(layers, options, parent = this) {
     const obj = new GuiObject(layers, options);
     obj.scene = this;
@@ -14481,6 +14677,7 @@ var Renderer = class _Renderer {
   get element() {
     return this._element;
   }
+  /** Attaches the canvas to an element and sizes it to that element's dimensions. */
   appendTo(element) {
     if (this._disposed) return;
     this._element = element;
@@ -14508,6 +14705,7 @@ var Renderer = class _Renderer {
     events.add(changeEvent2);
     dispatcher.addEventListener(changeEvent2, this._changeListener);
   }
+  /** Updates the camera and canvas size. Width and height are in CSS pixels. */
   resize(width, height) {
     if (this._disposed) return;
     if (isPerspectiveCamera(this.camera)) {
@@ -14546,12 +14744,14 @@ var Renderer = class _Renderer {
       if (this._frameCallbacks.get(callback) === subscription) this._frameCallbacks.delete(callback);
     };
   }
+  /** Starts or resumes the animation loop and registered frame callbacks. */
   start() {
     if (this._disposed) return;
     this.stop();
     this._running = true;
     if (!this._inAnimationLoop) this.renderer.setAnimationLoop(this._animationLoop);
   }
+  /** Pauses rendering and frame callbacks. Call {@link start} to resume. */
   stop() {
     if (this._disposed) return;
     this._running = false;
@@ -14660,12 +14860,15 @@ var Renderer = class _Renderer {
     const canvas = trim ? trimCanvas(this.renderer.domElement) : this.renderer.domElement;
     return canvas.toDataURL(mime, quality);
   }
+  /** Exports visible scene meshes as OBJ text, without texture images. */
   toObj() {
     return SceneExporter.toObj(this.scene);
   }
+  /** Exports visible scene meshes as PLY. Set `options.binary` for an ArrayBuffer. */
   toPLY(options) {
     return SceneExporter.toPLY(this.scene, options);
   }
+  /** Exports a static textured scene in the browser. Set `options.binary` for GLB output. */
   toGLTF(options) {
     return SceneExporter.toGLTF(this.scene, options);
   }
@@ -14708,12 +14911,14 @@ init_request();
 init_Requests();
 var Skins = class {
   //<editor-fold desc="Skins">
+  /** Returns a skin URL for {@link MineRenderScene.addSkin}, or `undefined` if name lookup fails. */
   static async fromUuidOrUsername(uuidOrUsername) {
     if (uuidOrUsername.length === 32 || uuidOrUsername.length === 36) {
       return this.fromUuid(uuidOrUsername);
     }
     return this.fromUsername(uuidOrUsername);
   }
+  /** Builds a proxy URL for a UUID without downloading or checking the skin. */
   static async fromUuid(uuid) {
     return this.getMcProxySkinUrl(uuid);
   }
@@ -14725,6 +14930,7 @@ var Skins = class {
       return void 0;
     });
   }
+  /** Looks up a saved MineSkin skin and returns its texture URL, or `undefined` on lookup failure. */
   static async fromMineSkin(mineskinId) {
     return this.getMineSkin(mineskinId).then((mineskin) => {
       if (mineskin) {
@@ -14735,12 +14941,14 @@ var Skins = class {
   }
   //</editor-fold>
   //<editor-fold desc="Capes">
+  /** Resolves a player's Minecraft cape URL for {@link SkinObject.setCapeTexture}. */
   static async capeFromUuidOrUsername(uuidOrUsername) {
     if (uuidOrUsername.length === 32 || uuidOrUsername.length === 36) {
       return this.capeFromUuid(uuidOrUsername);
     }
     return this.capeFromUsername(uuidOrUsername);
   }
+  /** Builds a proxy URL without checking whether the player has a cape. */
   static async capeFromUuid(uuid) {
     return this.getMcProxyCapeUrl(uuid);
   }
@@ -14895,16 +15103,19 @@ var ChunkData = class _ChunkData {
     this.freeIds = [];
     this.nbt = /* @__PURE__ */ new Map();
   }
+  /** Returns a detached copy of a cell, or `undefined` for air. Indices range from 0 to 4095. */
   get(index) {
     _ChunkData.validateIndex(index);
     const entry = this.palette[this.indices[index]];
     return entry ? _ChunkData.copyBlock(entry.state, this.nbt.get(index)) : void 0;
   }
+  /** Captures a cell's data and returns a copy-producing reader that survives later cell changes. */
   snapshot(index) {
     _ChunkData.validateIndex(index);
     const entry = this.palette[this.indices[index]];
     return entry ? _ChunkData.copyBlock.bind(void 0, entry.state, this.nbt.get(index)) : void 0;
   }
+  /** Copies block data into a cell. An omitted block or an air block clears the cell. */
   set(index, block) {
     _ChunkData.validateIndex(index);
     let state;
@@ -14969,15 +15180,23 @@ var ChunkData = class _ChunkData {
 
 // src/world/AnvilParser.ts
 var AnvilParser = class {
+  /** Lists occupied chunk positions within the region, using local coordinates from 0 to 31. */
   static getChunkList(data) {
     return this.locations(this.bytes(data)).map(({ x, z }) => ({ x, z }));
   }
+  /** Decodes all stored chunks. Gzip, zlib, and uncompressed payloads are supported. */
   static async parse(data) {
     const bytes = this.bytes(data);
     const chunks = [];
     for (const location of this.locations(bytes)) chunks.push(await this.readChunk(bytes, location));
     return { chunks };
   }
+  /**
+   * 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 async parseChunk(data, localX, localZ) {
     if (![localX, localZ].every((value) => Number.isInteger(value) && value >= 0 && value < 32)) {
       throw new RangeError("Region-local chunk coordinates must be integers from 0 to 31");
@@ -15182,6 +15401,7 @@ var SectionModels = class {
     this.templates = /* @__PURE__ */ new Set();
     if (!Number.isInteger(maxAtlasSize) || maxAtlasSize < 1) throw new RangeError("maxAtlasSize must be a positive integer");
   }
+  /** Returns a cube template, or `undefined` when the block requires an individual render object. */
   async get(blockState, properties = {}) {
     if (!blockState.variants || blockState.multipart) return void 0;
     let states = this.states.get(blockState);
@@ -15235,6 +15455,7 @@ var SectionModels = class {
     }
     return { variants, templates };
   }
+  /** Disposes prepared geometry and clears this world's template caches. */
   clear() {
     for (const template of this.templates) template.geometry.dispose();
     this.templates.clear();
@@ -15285,6 +15506,13 @@ var MineRenderWorld = class {
     this.validatePosBounds(posOrX);
     await this.getChunkAt(posOrX)?.setBlockVisibleAt(posOrX, yOrVisible);
   }
+  /**
+   * 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.
+   */
   async placeMultiBlock(multiblock, useBatches = true, executor) {
     const changes = /* @__PURE__ */ new Map();
     try {
@@ -15381,6 +15609,7 @@ var MineRenderWorld = class {
       });
     }
   }
+  /** Removes all chunks and releases their block placements and section meshes. */
   async clear() {
     await this.culling;
     const chunks = [...this._chunks.values()];
@@ -15466,9 +15695,11 @@ var MineRenderWorld = class {
     }
     return chunk;
   }
+  /** Returns the loaded chunk containing a world block position, without creating a chunk. */
   getChunkAt(pos) {
     return this._chunks.get(this.worldPosToChunkKey(pos));
   }
+  /** Converts block coordinates to scene units by multiplying each component by 16. */
   static worldToScenePosition(pos) {
     return new Vector316(
       pos.x * 16,
@@ -15476,6 +15707,7 @@ var MineRenderWorld = class {
       pos.z * 16
     );
   }
+  /** Converts scene units to block coordinates without rounding to an integer block. */
   static sceneToWorldPosition(pos) {
     return new Vector316(
       pos.x / 16,
@@ -15508,6 +15740,7 @@ var SectionMesh = class _SectionMesh extends Group2 {
     super(...arguments);
     this.ownedMeshes = [];
   }
+  /** Builds section-local meshes from visible cube faces. `maxAtlasSize` limits each atlas dimension in pixels. */
   static build(entries, maxAtlasSize = 2048) {
     if (!Number.isInteger(maxAtlasSize) || maxAtlasSize < 1) throw new RangeError("Section atlas size must be a positive integer");
     const visible = entries.filter((entry) => entry.template.cullFaces.some((direction) => !(entry.cullMask & direction)));
@@ -15652,7 +15885,7 @@ var Chunk = class _Chunk {
     return this.setBlockInChunkAt(pos, block, worldPos);
   }
   /**
-   * Set a block at integer chunk-local coordinates from 0 to 15.
+   * Places a block at integer chunk-local coordinates from 0 to 15.
    */
   async setBlockInChunkAt(pos, block, worldPos, onBlocksChanged = this.onBlocksChanged) {
     if (typeof worldPos === "undefined") {
@@ -15701,6 +15934,7 @@ var Chunk = class _Chunk {
       await onBlocksChanged?.([worldPos]);
     }
   }
+  /** Changes visibility at world block coordinates while preserving the block's data. */
   async setBlockVisibleAt(pos, visible) {
     const index = _Chunk.chunkPosToBlockIndex(this.worldPosToChunkPos(pos));
     const block = this.renderedBlocks.get(index);
@@ -15754,6 +15988,7 @@ var Chunk = class _Chunk {
     this.scene.dirty = true;
     this.meshDirty = false;
   }
+  /** Removes stored blocks and their render objects, then notifies the owning world of changed positions. */
   async clear(onBlocksChanged = this.onBlocksChanged) {
     const positions = [...this.renderedBlocks.keys()].map((index) => this.chunkPosToWorldPos(
       new Vector317(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
@@ -15774,6 +16009,7 @@ var Chunk = class _Chunk {
   static isAir(block) {
     return ChunkData.isAir(block);
   }
+  /** Maps chunk-local coordinates from 0 to 15 to a storage index, with x varying fastest, then z, then y. */
   static chunkPosToBlockIndex(pos) {
     if ([pos.x, pos.y, pos.z].some((value) => !Number.isInteger(value) || value < 0 || value >= 16)) {
       throw new RangeError("Block coordinates must be integers from 0 to 15 within a chunk");