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

package/dist/browser/index.js

@@ -65,6 +65,7 @@ var init_PersistentCache = __esm({
       constructor(backing) {
         this.backing = backing;
       }
+      /** Opens a named store in the active environment using the current cache schema version. */
       static open(name) {
         return Env.provider.openCache(name, _PersistentCache.VERSION);
       }
@@ -263,6 +264,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();
@@ -328,6 +330,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) => {
@@ -505,12 +508,15 @@ var init_Requests = __esm({
       }
     };
     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;
       }
@@ -565,6 +571,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;
       }
@@ -611,6 +618,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();
@@ -619,6 +627,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)
@@ -646,6 +655,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")}`);
@@ -662,12 +672,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) => {
@@ -764,6 +776,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 = import_three3.RGBAFormat, rotation = 0) {
         const texture = new import_three3.Texture();
         texture.colorSpace = THREE.SRGBColorSpace;
@@ -813,6 +826,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;
@@ -825,11 +839,13 @@ var init_Textures = __esm({
       static createAsset(key) {
         return new import_three4.Texture();
       }
+      /** Creates an sRGB color texture from a canvas. */
       static createCanvasTexture(canvas) {
         const texture = new import_three4.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);
@@ -854,6 +870,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 import_three5.MeshBasicMaterial({
           map: Textures.getMissing(),
@@ -957,6 +974,7 @@ var init_Materials = __esm({
         if (tint !== void 0) material.color.multiply(new import_three5.Color(tint));
         return material;
       }
+      /** Creates an unlit, transparent GUI material without depth writes or tone mapping. */
       static createGuiCanvasMaterial(canvas) {
         const material = new import_three5.MeshBasicMaterial({
           map: Textures.createCanvasTexture(canvas),
@@ -1123,6 +1141,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;
@@ -1297,6 +1316,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;
@@ -1308,6 +1335,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(":")) {
@@ -1339,6 +1376,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) {
@@ -1350,6 +1388,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();
       }
@@ -1409,6 +1448,7 @@ var init_DisplayTransforms = __esm({
         const scale = new import_three7.Vector3(...transform.scale ?? [1, 1, 1]).clampScalar(-4, 4);
         return new import_three7.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) {
@@ -1436,6 +1476,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 = {};
@@ -1503,6 +1544,7 @@ var init_Models = __esm({
       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");
@@ -1573,6 +1615,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";
@@ -1592,6 +1635,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";
@@ -1604,9 +1653,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();
       }
@@ -1629,6 +1680,7 @@ var init_BlockStates = __esm({
         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,
@@ -1649,6 +1701,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) {
@@ -1656,6 +1709,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";
@@ -1682,6 +1736,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();
       }
@@ -1707,9 +1762,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);
       }
@@ -1756,6 +1813,10 @@ var init_BatchedExecutor = __esm({
   "src/util/BatchedExecutor.ts"() {
     import_jobqu2 = require("jobqu");
     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");
@@ -1763,9 +1824,11 @@ var init_BatchedExecutor = __esm({
         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();
       }
@@ -1908,6 +1971,7 @@ var init_NBTHelper = __esm({
   "src/nbt/NBTHelper.ts"() {
     import_buffer2 = require("buffer");
     NBTHelper = class {
+      /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
       static async fromBuffer(data, format2) {
         const buffer = import_buffer2.Buffer.from(data instanceof Uint8Array ? data : new Uint8Array(data));
         const prismarineNbt = await import("prismarine-nbt");
@@ -1976,6 +2040,7 @@ var init_HostedAssetSource = __esm({
       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") {
@@ -2033,6 +2098,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;
@@ -2125,6 +2194,11 @@ var init_BrowserArchiveProxy = __esm({
   "src/assets/source/archive/BrowserArchiveProxy.ts"() {
     import_zip = require("@zip.js/zip.js");
     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 import_zip.ZipReader(new import_zip.BlobReader(this._blob));
@@ -2322,6 +2396,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);
       }
@@ -2456,6 +2531,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 });
@@ -2489,6 +2565,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);
@@ -2499,6 +2582,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) {
@@ -2509,6 +2593,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 = [];
@@ -2553,6 +2638,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. */
@@ -2577,6 +2663,7 @@ var init_ModelTextures = __esm({
       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);
@@ -2594,6 +2681,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) => {
@@ -2604,6 +2692,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);
@@ -2620,6 +2709,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();
       }
@@ -2686,6 +2776,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(() => {
@@ -2708,6 +2799,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);
@@ -2716,12 +2808,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();
@@ -2735,6 +2829,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();
@@ -2789,6 +2884,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];
@@ -3066,6 +3162,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) => {
@@ -3136,6 +3233,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 = {};
@@ -3500,6 +3602,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}/` : "";
@@ -3517,6 +3620,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 ?? {});
       }
@@ -3524,6 +3628,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;
@@ -3569,6 +3682,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;
@@ -3729,12 +3843,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);
       }
@@ -3772,6 +3888,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);
       }
@@ -3784,9 +3901,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);
       }
@@ -3855,6 +3974,7 @@ var init_SceneObject = __esm({
       }
       async init() {
       }
+      /** Marks ancestor scenes for redraw and emits a `change` event. */
       notifyDirty() {
         this.traverseAncestors((parent) => {
           const scene = parent;
@@ -3890,15 +4010,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);
@@ -3949,15 +4071,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);
@@ -4003,12 +4126,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");
@@ -4155,6 +4280,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()) {
@@ -4173,6 +4299,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()) {
@@ -4190,6 +4317,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()) {
@@ -4207,6 +4335,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()) {
@@ -4244,6 +4373,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;
@@ -4266,6 +4396,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Detaches the object from its parent and requests a redraw. */
       removeFromScene() {
         this.notifyDirty();
         this.removeFromParent();
@@ -4421,12 +4552,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}`);
       }
@@ -5090,6 +5224,7 @@ var init_ModelCulling = __esm({
     import_three23 = require("three");
     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()) {
@@ -5100,6 +5235,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];
@@ -6105,6 +6241,7 @@ var Meshes = class _Meshes {
   static createBox(key) {
     return new import_three6.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) => {
@@ -6217,6 +6354,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, []));
@@ -9392,6 +9530,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]];
@@ -10049,6 +10194,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;
@@ -10073,6 +10219,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);
@@ -10080,6 +10227,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);
@@ -10096,6 +10244,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];
@@ -10141,6 +10290,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 = {};
@@ -10160,9 +10310,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) {
@@ -10186,6 +10338,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");
@@ -10203,6 +10356,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 import_three29.Euler();
     if (typeof variant.x !== "undefined") {
@@ -10484,6 +10638,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;
   }
@@ -10583,6 +10738,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 = {};
@@ -12486,6 +12642,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;
@@ -13320,6 +13481,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;
@@ -13493,6 +13655,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;
@@ -13641,6 +13811,7 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
       this.stats.sceneObjectCount += change;
     }
   }
+  /** Initializes each object before attaching it to the scene. */
   async initAndAdd(...object2) {
     this.dirty = true;
     for (let obj of object2) {
@@ -13676,13 +13847,33 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
       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);
@@ -13694,9 +13885,14 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
     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;
@@ -14513,6 +14709,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;
@@ -14540,6 +14737,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)) {
@@ -14578,12 +14776,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;
@@ -14692,12 +14892,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);
   }
@@ -14779,12 +14982,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);
   }
@@ -14796,6 +15001,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) {
@@ -14806,12 +15012,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);
   }
@@ -14966,16 +15174,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;
@@ -15040,15 +15251,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");
@@ -15253,6 +15472,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);
@@ -15306,6 +15526,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();
@@ -15356,6 +15577,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 {
@@ -15452,6 +15680,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()];
@@ -15537,9 +15766,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 import_three39.Vector3(
       pos.x * 16,
@@ -15547,6 +15778,7 @@ var MineRenderWorld = class {
       pos.z * 16
     );
   }
+  /** Converts scene units to block coordinates without rounding to an integer block. */
   static sceneToWorldPosition(pos) {
     return new import_three39.Vector3(
       pos.x / 16,
@@ -15579,6 +15811,7 @@ var SectionMesh = class _SectionMesh extends import_three40.Group {
     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)));
@@ -15723,7 +15956,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") {
@@ -15772,6 +16005,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);
@@ -15825,6 +16059,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 import_three41.Vector3(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
@@ -15845,6 +16080,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");