minerender 2.1.0-alpha.74 → 2.1.0-alpha.76

package/dist/bundle.js

@@ -4056,6 +4056,7 @@ var MineRender = (() => {
         constructor(backing) {
           this.backing = backing;
         }
+        /** Opens a named store in the active environment using the current cache schema version. */
         static open(name2) {
           return Env.provider.openCache(name2, _PersistentCache.VERSION);
         }
@@ -41425,6 +41426,7 @@ void main() {
             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();
@@ -41493,6 +41495,7 @@ void main() {
           }
           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, (k4) => {
@@ -42047,12 +42050,15 @@ void main() {
         }
       };
       Requests = class {
+        /** 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;
         }
@@ -42110,6 +42116,7 @@ void main() {
           }
           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;
         }
@@ -42159,6 +42166,7 @@ void main() {
         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();
@@ -42167,6 +42175,7 @@ void main() {
             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)
@@ -42194,6 +42203,7 @@ void main() {
             throw err2;
           }
         }
+        /** 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")}`);
@@ -42210,12 +42220,14 @@ void main() {
           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, (k4) => {
             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, (k4) => {
@@ -42315,6 +42327,7 @@ void main() {
           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, format3 = RGBAFormat, rotation = 0) {
           const texture = new Texture();
           texture.colorSpace = SRGBColorSpace;
@@ -42367,6 +42380,7 @@ void main() {
             return this.initTextureProps(texture);
           });
         }
+        /** Sets nearest-neighbor filters without changing the texture's color space. Returns the same texture. */
         static initTextureProps(texture) {
           texture.magFilter = NearestFilter;
           texture.minFilter = NearestFilter;
@@ -42379,11 +42393,13 @@ void main() {
         static createAsset(key) {
           return new Texture();
         }
+        /** Creates an sRGB color texture from a canvas. */
         static createCanvasTexture(canvas) {
           const texture = new CanvasTexture(canvas);
           texture.colorSpace = 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);
@@ -42411,6 +42427,7 @@ void main() {
       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(),
@@ -42514,6 +42531,7 @@ void main() {
           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),
@@ -42680,6 +42698,7 @@ void main() {
           }
           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;
@@ -42863,6 +42882,14 @@ void main() {
         }
       };
       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;
@@ -42874,6 +42901,16 @@ void main() {
           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(":")) {
@@ -42905,6 +42942,7 @@ void main() {
           ];
           return a4.join("/");
         }
+        /** Joins the type subdirectory and path without adding a namespace or file extension. */
         getFullPath() {
           let p13 = [];
           if (this.type) {
@@ -42916,6 +42954,7 @@ void main() {
         toNamespacedString() {
           return this.namespace + ":" + this.getFullPath();
         }
+        /** Returns a cache identifier that includes the explicit root or {@link AssetLoader.ROOT}. */
         serialize() {
           return this.toString();
         }
@@ -42981,6 +43020,7 @@ void main() {
           const scale = new Vector3(...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) {
@@ -43011,6 +43051,7 @@ void main() {
       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 = {};
@@ -43084,6 +43125,7 @@ void main() {
         static get PERSISTENT_CACHE() {
           return this._persistentCache ?? (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");
@@ -43154,6 +43196,7 @@ void main() {
           }
           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";
@@ -43173,6 +43216,12 @@ void main() {
             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";
@@ -43185,9 +43234,11 @@ void main() {
             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();
         }
@@ -43213,6 +43264,7 @@ void main() {
           return this._persistentCache ?? (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,
@@ -43233,6 +43285,7 @@ void main() {
             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) {
@@ -43240,6 +43293,7 @@ void main() {
           }
           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";
@@ -43266,6 +43320,7 @@ void main() {
           }
           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();
         }
@@ -43294,9 +43349,11 @@ void main() {
         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);
         }
@@ -43349,6 +43406,10 @@ void main() {
       init_process2();
       import_jobqu2 = __toESM(require_src());
       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");
@@ -43356,9 +43417,11 @@ void main() {
           this.batch = batch;
           this.queue = new import_jobqu2.JobQueue(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();
         }
@@ -77161,6 +77224,7 @@ return ${compiler2.callType("value", tagType)}
       init_process2();
       init_buffer();
       NBTHelper = class {
+        /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
         static async fromBuffer(data, format3) {
           const buffer2 = Buffer.from(data instanceof Uint8Array ? data : new Uint8Array(data));
           const prismarineNbt = await Promise.resolve().then(() => __toESM(require_nbt2()));
@@ -77247,6 +77311,7 @@ return ${compiler2.callType("value", tagType)}
         retryDefaults: true
       };
       _HostedAssetSource = class _HostedAssetSource extends AssetSource {
+        /** 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") {
@@ -77304,6 +77369,10 @@ return ${compiler2.callType("value", tagType)}
         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;
@@ -87008,6 +87077,11 @@ return ${compiler2.callType("value", tagType)}
       init_process2();
       init_zip();
       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));
@@ -87214,6 +87288,7 @@ return ${compiler2.callType("value", tagType)}
             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);
         }
@@ -87363,6 +87438,7 @@ return ${compiler2.callType("value", tagType)}
         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(version2) {
           this.ROOT = `https://assets.mcasset.cloud/${version2}`;
           const source = new HostedAssetSource(this.ROOT, { retryDefaults: false });
@@ -87396,6 +87472,13 @@ return ${compiler2.callType("value", tagType)}
           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);
@@ -87406,6 +87489,7 @@ ${key}` : key;
           this._SOURCES.unshift({ key, source });
           console.log(p7, "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((s4) => s4.key === key);
           if (index != -1) {
@@ -87416,6 +87500,7 @@ ${key}` : key;
           }
           return void 0;
         }
+        /** 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 = [];
@@ -87460,6 +87545,7 @@ ${key}` : key;
           return void 0;
         }
       };
+      /** Default asset base URL. Use {@link setVersion} to select a Minecraft version. */
       _AssetLoader.ROOT = DEFAULT_ROOT;
       _AssetLoader._SOURCES = [];
       /** Used when a registered source cannot identify its content, so nothing persists past this session. */
@@ -87487,6 +87573,7 @@ ${key}` : key;
         static get PERSISTENT_META_CACHE() {
           return this._persistentMetaCache ?? (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);
@@ -87504,6 +87591,7 @@ ${key}` : key;
             throw err2;
           }
         }
+        /** Fetches and caches encoded texture bytes without decoding the pixels. */
         static async preload(key) {
           const keyStr = key.serialize();
           return Caching.textureAssetCache.get(keyStr, (k4) => {
@@ -87514,6 +87602,7 @@ ${key}` : key;
             });
           });
         }
+        /** 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);
@@ -87530,6 +87619,7 @@ ${key}` : key;
             });
           });
         }
+        /** Clears persisted texture metadata. Use {@link Caching.clear} to discard in-memory textures and metadata. */
         static async clearCache() {
           await this.PERSISTENT_META_CACHE.clear();
         }
@@ -87602,6 +87692,7 @@ ${key}` : key;
           }
           return handle;
         }
+        /** Starts or resumes the shared tick loop. Repeated calls have no effect. */
         static start() {
           if (this.interval) return;
           this.interval = this.schedule(() => {
@@ -87624,6 +87715,7 @@ ${key}` : key;
             _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);
@@ -87632,12 +87724,14 @@ ${key}` : key;
           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 c4 = this.counter++;
           this._tickers.set(c4, tick);
           return c4;
         }
+        /** Removes a callback by ID and stops the timers when no callbacks remain. */
         static remove(c4) {
           if (typeof c4 === "number") this._tickers.delete(c4);
           if (!this._tickers.size) this.stop();
@@ -87651,6 +87745,7 @@ ${key}` : key;
         static get tpsFiveSeconds() {
           return this.fiveSecondTps;
         }
+        /** Stops the loop and removes all registered callbacks. */
         static dispose() {
           this.stop();
           this._tickers.clear();
@@ -87708,6 +87803,7 @@ ${key}` : key;
             }
           };
         }
+        /** Copies pixels for a texture variable from its current atlas rectangle. */
         getData(texture) {
           const pos = this.positions[texture];
           const size = this.sizes[texture];
@@ -87991,6 +88087,7 @@ ${key}` : key;
           }
           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, (k4) => {
@@ -88061,6 +88158,11 @@ ${key}` : key;
           }
           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 = {};
@@ -88434,6 +88536,7 @@ ${key}` : key;
       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}/` : "";
@@ -88451,6 +88554,7 @@ ${key}` : key;
           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 ?? {});
         }
@@ -88458,6 +88562,15 @@ ${key}` : key;
         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;
@@ -88503,6 +88616,7 @@ ${key}` : key;
           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;
@@ -88669,12 +88783,14 @@ ${key}` : key;
           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);
         }
@@ -88715,6 +88831,7 @@ ${key}` : key;
           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);
         }
@@ -88727,9 +88844,11 @@ ${key}` : key;
         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);
         }
@@ -88801,6 +88920,7 @@ ${key}` : key;
         }
         async init() {
         }
+        /** Marks ancestor scenes for redraw and emits a `change` event. */
         notifyDirty() {
           this.traverseAncestors((parent) => {
             const scene = parent;
@@ -88836,15 +88956,17 @@ ${key}` : key;
           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(name2) {
           return this.getObjectByName(`group:${name2}`);
         }
         /**
-         * 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(name2, visible) {
           return this.toggleObjectVisibility(this.getGroupByName(name2), visible);
@@ -88895,15 +89017,16 @@ ${key}` : key;
           return mesh;
         }
         /**
-         * Get a mesh by its name
+         * Finds a named mesh without the internal `mesh:` prefix, or returns `undefined`.
          */
         getMeshByName(name2) {
           return this.getObjectByName(`mesh:${name2}`);
         }
         /**
-         * 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(name2, visible) {
           return this.toggleObjectVisibility(this.getMeshByName(name2), visible);
@@ -88949,12 +89072,14 @@ ${key}` : key;
         get isInstanced() {
           return this._isInstanced;
         }
+        /** Number of live placements, excluding released instance slots. */
         get instanceCounter() {
           return this._instanceCounter;
         }
         constructInstanceReference(i4) {
           return new InstanceReference(this, i4);
         }
+        /** 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");
@@ -89101,6 +89226,7 @@ ${key}` : key;
           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 i4 of this.activeInstanceIndices()) {
@@ -89119,6 +89245,7 @@ ${key}` : key;
           }
           this.notifyDirty();
         }
+        /** Sets position in scene units. For a shared model, updates every live instance. */
         setPosition(position) {
           if (this.isInstanced) {
             for (const i4 of this.activeInstanceIndices()) {
@@ -89136,6 +89263,7 @@ ${key}` : key;
             return this.position;
           }
         }
+        /** Sets rotation in radians. For a shared model, updates every live instance. */
         setRotation(rotation) {
           if (this.isInstanced) {
             for (const i4 of this.activeInstanceIndices()) {
@@ -89153,6 +89281,7 @@ ${key}` : key;
             return this.rotation;
           }
         }
+        /** Sets scale factors. For a shared model, updates every live instance. */
         setScale(scale) {
           if (this.isInstanced) {
             for (const i4 of this.activeInstanceIndices()) {
@@ -89190,6 +89319,7 @@ ${key}` : key;
           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;
@@ -89212,6 +89342,7 @@ ${key}` : key;
           }
           this.notifyDirty();
         }
+        /** Detaches the object from its parent and requests a redraw. */
         removeFromScene() {
           this.notifyDirty();
           this.removeFromParent();
@@ -89370,12 +89501,15 @@ ${key}` : key;
           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(name2) {
           return super.getGroupByName(`layer:${name2}`);
         }
+        /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
         getGroupByName(name2, layerName) {
           return layerName === void 0 ? super.getGroupByName(name2) : this.getLayerGroup(layerName)?.getObjectByName(`group:${name2}`);
         }
+        /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
         getMeshByName(name2, layerName) {
           return layerName === void 0 ? super.getMeshByName(name2) : this.getLayerGroup(layerName)?.getObjectByName(`mesh:${name2}`);
         }
@@ -90044,6 +90178,7 @@ ${key}` : key;
       init_three_module();
       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()) {
@@ -90054,6 +90189,7 @@ ${key}` : key;
           }
           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];
@@ -93935,6 +94071,7 @@ ${shader.fragmentShader}`.replace(
     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, (k4) => {
@@ -94083,6 +94220,7 @@ ${shader.fragmentShader}`.replace(
   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, []));
@@ -97334,6 +97472,13 @@ property list uchar int vertex_index
       });
       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]];
@@ -98018,6 +98163,7 @@ property list uchar int vertex_index
     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;
@@ -98050,6 +98196,7 @@ property list uchar int vertex_index
       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(p12, "key in cache", key);
@@ -98057,6 +98204,7 @@ property list uchar int vertex_index
       }
       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);
@@ -98073,6 +98221,7 @@ property list uchar int vertex_index
         throw error2;
       }
     }
+    /** Forgets cached models without disposing them or releasing their existing placements. */
     reset() {
       for (let instanceCacheKey in this.instanceCache) {
         delete this.instanceCache[instanceCacheKey];
@@ -98161,6 +98310,7 @@ property list uchar int vertex_index
     });
   }
   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 = {};
@@ -98180,9 +98330,11 @@ property list uchar int vertex_index
       }
       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) {
@@ -98206,6 +98358,7 @@ property list uchar int vertex_index
       }
       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");
@@ -98223,6 +98376,7 @@ property list uchar int vertex_index
       }
       return variants[variants.length - 1];
     }
+    /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
     static rotation(variant) {
       const rotation = new Euler();
       if (typeof variant.x !== "undefined") {
@@ -98515,6 +98669,7 @@ property list uchar int vertex_index
       }
       this.notifyDirty();
     }
+    /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
     get state() {
       return this._state;
     }
@@ -98614,6 +98769,7 @@ property list uchar int vertex_index
       obj.setPosition(this.position);
       return obj;
     }
+    /** Clears selected properties and rebuilds models without reapplying property defaults. */
     async resetState() {
       this._previousState = this._state;
       this._state = {};
@@ -100536,6 +100692,11 @@ property list uchar int vertex_index
   init_process2();
   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;
@@ -101399,6 +101560,7 @@ property list uchar int vertex_index
   // 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;
@@ -101575,6 +101737,14 @@ property list uchar int vertex_index
         }
       }
     }
+    /**
+     * 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;
@@ -101723,6 +101893,7 @@ property list uchar int vertex_index
         this.stats.sceneObjectCount += change;
       }
     }
+    /** Initializes each object before attaching it to the scene. */
     async initAndAdd(...object2) {
       this.dirty = true;
       for (let obj of object2) {
@@ -101758,13 +101929,33 @@ property list uchar int vertex_index
         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);
@@ -101776,9 +101967,14 @@ property list uchar int vertex_index
       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;
@@ -104580,6 +104776,7 @@ gl_FragDepth=readDepth(vUv);
     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;
@@ -104607,6 +104804,7 @@ gl_FragDepth=readDepth(vUv);
       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)) {
@@ -104645,12 +104843,14 @@ gl_FragDepth=readDepth(vUv);
         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;
@@ -104759,12 +104959,15 @@ gl_FragDepth=readDepth(vUv);
       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);
     }
@@ -104859,12 +105062,14 @@ gl_FragDepth=readDepth(vUv);
   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);
     }
@@ -104876,6 +105081,7 @@ gl_FragDepth=readDepth(vUv);
         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) {
@@ -104886,12 +105092,14 @@ gl_FragDepth=readDepth(vUv);
     }
     //</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);
     }
@@ -105068,16 +105276,19 @@ gl_FragDepth=readDepth(vUv);
       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;
@@ -105142,15 +105353,23 @@ gl_FragDepth=readDepth(vUv);
 
   // 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: x4, z: z4 }) => ({ x: x4, z: z4 }));
     }
+    /** 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");
@@ -105369,6 +105588,7 @@ gl_FragDepth=readDepth(vUv);
       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);
@@ -105422,6 +105642,7 @@ gl_FragDepth=readDepth(vUv);
       }
       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();
@@ -105472,6 +105693,13 @@ gl_FragDepth=readDepth(vUv);
       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 {
@@ -105523,13 +105751,7 @@ gl_FragDepth=readDepth(vUv);
     async placeChunk(chunk, executor) {
       const changes = /* @__PURE__ */ new Map();
       try {
-        const previous = [...this._chunks.entries()].filter(([, section]) => section.x === chunk.x && section.z === chunk.z);
-        for (const [key, section] of previous) {
-          this._chunks.delete(key);
-          await section.clear(async (positions) => {
-            for (const pos of positions) changes.set(pos.toArray().join(","), pos);
-          });
-        }
+        await this.clearChunkColumn(chunk.x, chunk.z, changes);
         for (const section of chunk.sections) {
           const blocks = [];
           for (let index = 0; index < 4096; index++) {
@@ -105549,6 +105771,32 @@ gl_FragDepth=readDepth(vUv);
         await this.updateCulling([...changes.values()]);
       }
     }
+    /**
+     * Removes all sections at integer chunk-column coordinates, then refreshes neighboring faces and fluids.
+     * Coordinates match AnvilChunk.x/z, not block positions. Missing columns are ignored.
+     */
+    async unloadChunkColumn(x4, z4) {
+      if (!Number.isInteger(x4) || !Number.isInteger(z4)) {
+        throw new RangeError("Chunk column coordinates must be integers");
+      }
+      await this.culling;
+      const changes = /* @__PURE__ */ new Map();
+      try {
+        await this.clearChunkColumn(x4, z4, changes);
+      } finally {
+        await this.updateCulling([...changes.values()]);
+      }
+    }
+    async clearChunkColumn(x4, z4, changes) {
+      const previous = [...this._chunks.entries()].filter(([, section]) => section.x === x4 && section.z === z4);
+      for (const [key, section] of previous) {
+        this._chunks.delete(key);
+        await section.clear(async (positions) => {
+          for (const pos of positions) changes.set(pos.toArray().join(","), pos);
+        });
+      }
+    }
+    /** Removes all chunks and releases their block placements and section meshes. */
     async clear() {
       await this.culling;
       const chunks = [...this._chunks.values()];
@@ -105634,9 +105882,11 @@ gl_FragDepth=readDepth(vUv);
       }
       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 Vector3(
         pos.x * 16,
@@ -105644,6 +105894,7 @@ gl_FragDepth=readDepth(vUv);
         pos.z * 16
       );
     }
+    /** Converts scene units to block coordinates without rounding to an integer block. */
     static sceneToWorldPosition(pos) {
       return new Vector3(
         pos.x / 16,
@@ -105679,6 +105930,7 @@ gl_FragDepth=readDepth(vUv);
       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)));
@@ -105823,7 +106075,7 @@ gl_FragDepth=readDepth(vUv);
       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") {
@@ -105872,6 +106124,7 @@ gl_FragDepth=readDepth(vUv);
         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);
@@ -105925,6 +106178,7 @@ gl_FragDepth=readDepth(vUv);
       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 Vector3(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
@@ -105945,6 +106199,7 @@ gl_FragDepth=readDepth(vUv);
     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");