minerender 2.1.0-alpha.142 → 2.1.0-alpha.144

package/README.md

@@ -1,6 +1,6 @@
 # MineRender V2
 
-A TypeScript library for interactive Minecraft skins, models, blocks, entities, and worlds.
+A TypeScript library for interactive Minecraft skins, models, blocks, entities, GUIs, and worlds.
 V2 is in beta. See the [roadmap](https://github.com/InventivetalentDev/MineRender/blob/main/ROADMAP.md) for feature parity and remaining work.
 
 Live examples and usage docs: [beta.minerender.org](https://beta.minerender.org/). API reference: [beta-docs.minerender.org](https://beta-docs.minerender.org/).
@@ -29,6 +29,11 @@ an injected WebGL 2 context or the optional native `gl` backend. See
 
 Requires Node.js 22.12+ or a browser with WebGL 2, Fetch, `AbortSignal.any()`, and `AbortSignal.timeout()`.
 
+The library prints only warnings and errors. To see debug output, call
+`Logging.configure({ level: "debug" })`, or set the `minerender:log` localStorage key
+in a browser or the `MINERENDER_LOG` environment variable in Node. See
+[Logging](https://beta-docs.minerender.org/concepts#logging).
+
 ## Resource-pack ZIPs
 
 Register a browser `File` or `Blob` before loading models or textures:
@@ -123,3 +128,7 @@ Supported object types are `skin`, `block`, `item`, `model`, `entity`, and `gui`
 Positions use model units (16 per block); JSON rotations use radians.
 
 Callers apply the saved camera settings and select the matching asset version.
+
+`encodeSceneDocument` and `decodeSceneDocument` convert a document to and from the compact
+link format used by the editor. To show a scene on another page without bundling the library,
+use the [iframe embed page](https://beta-docs.minerender.org/embeds).

package/dist/browser/esm/index.browser.d.mts

@@ -783,7 +783,10 @@ declare function toRadians(degrees: number): number;
 declare function toDegrees(radians: number): number;
 /** Resolves after a delay in milliseconds. */
 declare function sleep(timeout: number): Promise<void>;
-/** Yields to the next macrotask without timer clamping when the platform supports it. */
+/**
+ * Yields to the next macrotask without timer clamping when the platform supports it.
+ * Not `scheduler.yield()`: Chrome runs its continuations ahead of rendering, so chained yields delay frames.
+ */
 declare function yieldToEventLoop(): Promise<void>;
 /** Reduces an angle modulo 360, retaining a negative sign for negative inputs. */
 declare function clampRotationDegrees(deg: number): number;
@@ -4019,6 +4022,8 @@ declare class SectionModels {
         pick(position?: Readonly<TripleArray>): SectionMeshTemplate[];
         biomeTint?: boolean;
     } | undefined>;
+    /** Starts loading the state's models and atlases so a later `prepareState` with the same properties finds them loaded. */
+    preload(blockState: BlockState, properties?: BlockStateProperties): Promise<void>;
     private state;
     /** Returns the shared still/flow atlas used by per-block fluid objects. */
     fluidAtlas(kind: FluidKind, root?: string): Promise<TextureAtlas>;
@@ -4133,6 +4138,7 @@ declare class Chunk<SectionMeshing extends boolean = false> {
     /** Replaces every cell from parsed section data. The caller refreshes neighbor culling. */
     placeSection(data: ChunkData): Promise<void>;
     private replaceSection;
+    private createBlockObject;
     private positionAt;
     /** Refreshes saved lighting after adjacent columns load or unload, including columns with only light data. */
     refreshLight(indices?: Iterable<number>): Promise<void>;
@@ -4282,6 +4288,12 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     private placeChunkGroups;
     /** Replaces a chunk column's blocks, biomes, and saved light and, with `renderEntities`, its supported saved mobs. */
     placeChunk(chunk: AnvilChunk, executor?: BatchedExecutor): Promise<void>;
+    /**
+     * Replaces parsed columns in input order, then refreshes neighboring geometry once.
+     * Duplicate coordinates retain their order. A failed column stops placement; queued refreshes finish before rejection.
+     */
+    placeChunks(chunks: readonly AnvilChunk[]): Promise<void>;
+    private placeColumn;
     /**
      * Removes blocks and owned entities at chunk-column coordinates, then refreshes neighboring faces and fluids.
      * Coordinates match AnvilChunk.x/z, not block positions. Missing columns are ignored.
@@ -4314,7 +4326,7 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
 interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
     /** Render supported saved mobs at their position and yaw, including supported appearance fields. Defaults to false. */
     renderEntities?: boolean;
-    /** Merge static opaque cubes into section meshes. Merged blocks have no individual object. */
+    /** Merge block models of any shape and fluid surfaces into per-section meshes; block entities keep individual objects. Merged blocks have no individual object. */
     sectionMeshing?: SectionMeshing;
     /** Shade blocks and fluids with saved sky/block light. Missing or invalid data keeps preview brightness. Defaults to false. Requires `sectionMeshing`. */
     savedLighting?: boolean;
@@ -4324,7 +4336,7 @@ interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
     ambientOcclusion?: boolean;
     /** Average neighboring biome colors within this horizontal radius, from 0 to 7 blocks. Defaults to 0 (off). Requires `sectionMeshing`. */
     biomeBlendRadius?: number;
-    /** Maximum width and height of each section atlas page, in pixels. */
+    /** Maximum width and height of each section atlas page, in pixels. Defaults to 2048. */
     maxAtlasSize?: number;
 }
 
@@ -4369,10 +4381,11 @@ declare class WorldStreamer {
     private desired;
     private center?;
     private loading?;
+    private readonly reads;
     private running?;
     private disposal?;
     private disposed;
-    constructor(world: Pick<MineRenderWorld<boolean>, "placeChunk" | "unloadChunkColumns">, source: WorldChunkSource, options?: WorldStreamerOptions);
+    constructor(world: Pick<MineRenderWorld<boolean>, "placeChunk" | "unloadChunkColumns"> & Partial<Pick<MineRenderWorld<boolean>, "placeChunks">>, source: WorldChunkSource, options?: WorldStreamerOptions);
     /** Returns absolute coordinates of successfully placed columns, including retained columns. */
     get loadedChunks(): readonly {
         x: number;
@@ -4405,6 +4418,10 @@ declare class WorldStreamer {
     /** Aborts source reads, waits for active work, then unloads owned columns. The world and source remain caller-owned. */
     dispose(): Promise<void>;
     private drain;
+    private fillReadSlots;
+    /** Places only the ready prefix, so later source reads cannot delay the nearest ready column. */
+    private placeReadyChunks;
+    private placeOwnedColumns;
     private needsLoad;
     private unloadMany;
     private validateChunk;

package/dist/browser/esm/util/util.mjs

@@ -28,8 +28,6 @@ async function sleep(timeout) {
   });
 }
 function yieldToEventLoop() {
-  const scheduler = globalThis.scheduler;
-  if (scheduler?.yield) return scheduler.yield();
   return new Promise((resolve) => {
     if (typeof MessageChannel !== "undefined") {
       const channel = new MessageChannel();

package/dist/browser/esm/util/util.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/util/util.ts"],"sourcesContent":["// Node ESM needs the explicit .js extension for the CommonJS hash module.\nimport MD5 from \"crypto-js/md5.js\";\nimport { Vector3 } from \"three\";\n\nexport const changeEvent = { type: 'change' as const };\n\nexport type Maybe<T> = T | undefined;\n\n// MD5 runs in both environments without pulling Node's crypto into the browser graph.\nexport function md5(str: string): string {\n    return MD5(str).toString();\n}\n\nexport function base64encode(str: string): string {\n    if (typeof btoa !== \"undefined\") {\n        return btoa(str);\n    }\n    return Buffer.from(str).toString(\"base64\");\n}\n\nexport function base64decode(str: string): string {\n    if (typeof atob !== \"undefined\") {\n        return atob(str);\n    }\n    return Buffer.from(str, \"base64\").toString(\"ascii\");\n}\n\nexport function toRadians(degrees: number): number {\n    return degrees * Math.PI / 180;\n}\n\nexport function toDegrees(radians: number): number {\n    return radians * 180 / Math.PI;\n}\n\n/** Resolves after a delay in milliseconds. */\nexport async function sleep(timeout: number): Promise<void> {\n    return new Promise(resolve => {\n        setTimeout(() => resolve(), timeout);\n    });\n}\n\n/** Yields to the next macrotask without timer clamping when the platform supports it. */\nexport function yieldToEventLoop(): Promise<void> {\n    const scheduler = (globalThis as typeof globalThis & { scheduler?: { yield?: () => Promise<void> } }).scheduler;\n    if (scheduler?.yield) return scheduler.yield();\n    return new Promise(resolve => {\n        if (typeof MessageChannel !== \"undefined\") {\n            const channel = new MessageChannel();\n            channel.port1.onmessage = () => {\n                channel.port1.close();\n                channel.port2.close();\n                resolve();\n            };\n            channel.port2.postMessage(undefined);\n        } else {\n            setTimeout(resolve, 0);\n        }\n    });\n}\n\n/** Reduces an angle modulo 360, retaining a negative sign for negative inputs. */\nexport function clampRotationDegrees(deg: number): number {\n    return deg % 360;\n}\n\nexport function isVector3(obj: any): obj is Vector3 {\n    return (<Vector3>obj).isVector3;\n}\n\nexport type DeepPartial<T> = {\n    [P in keyof T]?: DeepPartial<T[P]>;\n};\n"],"mappings":";AACA,OAAO,SAAS;AAGT,IAAM,cAAc,EAAE,MAAM,SAAkB;AAK9C,SAAS,IAAI,KAAqB;AACrC,SAAO,IAAI,GAAG,EAAE,SAAS;AAC7B;AAEO,SAAS,aAAa,KAAqB;AAC9C,MAAI,OAAO,SAAS,aAAa;AAC7B,WAAO,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,OAAO,KAAK,GAAG,EAAE,SAAS,QAAQ;AAC7C;AAEO,SAAS,aAAa,KAAqB;AAC9C,MAAI,OAAO,SAAS,aAAa;AAC7B,WAAO,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,OAAO,KAAK,KAAK,QAAQ,EAAE,SAAS,OAAO;AACtD;AAEO,SAAS,UAAU,SAAyB;AAC/C,SAAO,UAAU,KAAK,KAAK;AAC/B;AAEO,SAAS,UAAU,SAAyB;AAC/C,SAAO,UAAU,MAAM,KAAK;AAChC;AAGA,eAAsB,MAAM,SAAgC;AACxD,SAAO,IAAI,QAAQ,aAAW;AAC1B,eAAW,MAAM,QAAQ,GAAG,OAAO;AAAA,EACvC,CAAC;AACL;AAGO,SAAS,mBAAkC;AAC9C,QAAM,YAAa,WAAmF;AACtG,MAAI,WAAW,MAAO,QAAO,UAAU,MAAM;AAC7C,SAAO,IAAI,QAAQ,aAAW;AAC1B,QAAI,OAAO,mBAAmB,aAAa;AACvC,YAAM,UAAU,IAAI,eAAe;AACnC,cAAQ,MAAM,YAAY,MAAM;AAC5B,gBAAQ,MAAM,MAAM;AACpB,gBAAQ,MAAM,MAAM;AACpB,gBAAQ;AAAA,MACZ;AACA,cAAQ,MAAM,YAAY,MAAS;AAAA,IACvC,OAAO;AACH,iBAAW,SAAS,CAAC;AAAA,IACzB;AAAA,EACJ,CAAC;AACL;AAGO,SAAS,qBAAqB,KAAqB;AACtD,SAAO,MAAM;AACjB;AAEO,SAAS,UAAU,KAA0B;AAChD,SAAiB,IAAK;AAC1B;","names":[]}
+{"version":3,"sources":["../../../../src/util/util.ts"],"sourcesContent":["// Node ESM needs the explicit .js extension for the CommonJS hash module.\nimport MD5 from \"crypto-js/md5.js\";\nimport { Vector3 } from \"three\";\n\nexport const changeEvent = { type: 'change' as const };\n\nexport type Maybe<T> = T | undefined;\n\n// MD5 runs in both environments without pulling Node's crypto into the browser graph.\nexport function md5(str: string): string {\n    return MD5(str).toString();\n}\n\nexport function base64encode(str: string): string {\n    if (typeof btoa !== \"undefined\") {\n        return btoa(str);\n    }\n    return Buffer.from(str).toString(\"base64\");\n}\n\nexport function base64decode(str: string): string {\n    if (typeof atob !== \"undefined\") {\n        return atob(str);\n    }\n    return Buffer.from(str, \"base64\").toString(\"ascii\");\n}\n\nexport function toRadians(degrees: number): number {\n    return degrees * Math.PI / 180;\n}\n\nexport function toDegrees(radians: number): number {\n    return radians * 180 / Math.PI;\n}\n\n/** Resolves after a delay in milliseconds. */\nexport async function sleep(timeout: number): Promise<void> {\n    return new Promise(resolve => {\n        setTimeout(() => resolve(), timeout);\n    });\n}\n\n/**\n * Yields to the next macrotask without timer clamping when the platform supports it.\n * Not `scheduler.yield()`: Chrome runs its continuations ahead of rendering, so chained yields delay frames.\n */\nexport function yieldToEventLoop(): Promise<void> {\n    return new Promise(resolve => {\n        if (typeof MessageChannel !== \"undefined\") {\n            const channel = new MessageChannel();\n            channel.port1.onmessage = () => {\n                channel.port1.close();\n                channel.port2.close();\n                resolve();\n            };\n            channel.port2.postMessage(undefined);\n        } else {\n            setTimeout(resolve, 0);\n        }\n    });\n}\n\n/** Reduces an angle modulo 360, retaining a negative sign for negative inputs. */\nexport function clampRotationDegrees(deg: number): number {\n    return deg % 360;\n}\n\nexport function isVector3(obj: any): obj is Vector3 {\n    return (<Vector3>obj).isVector3;\n}\n\nexport type DeepPartial<T> = {\n    [P in keyof T]?: DeepPartial<T[P]>;\n};\n"],"mappings":";AACA,OAAO,SAAS;AAGT,IAAM,cAAc,EAAE,MAAM,SAAkB;AAK9C,SAAS,IAAI,KAAqB;AACrC,SAAO,IAAI,GAAG,EAAE,SAAS;AAC7B;AAEO,SAAS,aAAa,KAAqB;AAC9C,MAAI,OAAO,SAAS,aAAa;AAC7B,WAAO,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,OAAO,KAAK,GAAG,EAAE,SAAS,QAAQ;AAC7C;AAEO,SAAS,aAAa,KAAqB;AAC9C,MAAI,OAAO,SAAS,aAAa;AAC7B,WAAO,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,OAAO,KAAK,KAAK,QAAQ,EAAE,SAAS,OAAO;AACtD;AAEO,SAAS,UAAU,SAAyB;AAC/C,SAAO,UAAU,KAAK,KAAK;AAC/B;AAEO,SAAS,UAAU,SAAyB;AAC/C,SAAO,UAAU,MAAM,KAAK;AAChC;AAGA,eAAsB,MAAM,SAAgC;AACxD,SAAO,IAAI,QAAQ,aAAW;AAC1B,eAAW,MAAM,QAAQ,GAAG,OAAO;AAAA,EACvC,CAAC;AACL;AAMO,SAAS,mBAAkC;AAC9C,SAAO,IAAI,QAAQ,aAAW;AAC1B,QAAI,OAAO,mBAAmB,aAAa;AACvC,YAAM,UAAU,IAAI,eAAe;AACnC,cAAQ,MAAM,YAAY,MAAM;AAC5B,gBAAQ,MAAM,MAAM;AACpB,gBAAQ,MAAM,MAAM;AACpB,gBAAQ;AAAA,MACZ;AACA,cAAQ,MAAM,YAAY,MAAS;AAAA,IACvC,OAAO;AACH,iBAAW,SAAS,CAAC;AAAA,IACzB;AAAA,EACJ,CAAC;AACL;AAGO,SAAS,qBAAqB,KAAqB;AACtD,SAAO,MAAM;AACjB;AAEO,SAAS,UAAU,KAA0B;AAChD,SAAiB,IAAK;AAC1B;","names":[]}

package/dist/browser/esm/world/Chunk.mjs

@@ -1,4 +1,5 @@
 // src/world/Chunk.ts
+import { BlockObject } from "../model/block/scene/BlockObject.mjs";
 import { Color, Vector3 } from "three";
 import { ChunkData } from "./ChunkData.mjs";
 import { BlockStates } from "../assets/BlockStates.mjs";
@@ -269,8 +270,10 @@ var Chunk = class _Chunk {
       if (rejected?.status === "rejected") throw rejected.reason;
     }
     const positions = [];
-    let failed = false, failure;
-    for (const { index, key, block } of placements) {
+    const jobs = /* @__PURE__ */ new Map();
+    let failureOrder = Infinity, failure;
+    for (const [order, { index, key, block }] of placements.entries()) {
+      jobs.delete(index);
       this.hiddenBlocks.delete(index);
       this.data.assign(index, this.data.intern(block), block?.nbt);
       const readBlock = this.data.snapshot(index);
@@ -286,7 +289,6 @@ var Chunk = class _Chunk {
         this.z * 16 + Math.floor(index / 16) % 16
       );
       positions.push(worldPos);
-      let object;
       try {
         if (!readBlock) continue;
         const resolved = resolutions.get(key);
@@ -308,7 +310,7 @@ var Chunk = class _Chunk {
           this.sectionBlocks.set(index, templates.map((template) => ({ index, template, cullMask: 0, biomeTint: context?.tint })));
           this.meshDirty = true;
         } else {
-          object = await this.scene.addBlock(blockState, {
+          jobs.set(index, { order, readBlock, blockState, position: MineRenderWorld.worldToScenePosition(worldPos), options: {
             mergeMeshes: true,
             instanceMeshes: true,
             maxInstanceCount: 2e3,
@@ -316,13 +318,12 @@ var Chunk = class _Chunk {
             variantPosition,
             biome: context?.biome,
             biomePosition: this.biomePosition(index, blockState, stored)
-          });
-          object.setPosition(MineRenderWorld.worldToScenePosition(worldPos));
+          } });
+          continue;
         }
         this.renderedBlocks.set(index, { get block() {
           return readBlock();
-        }, object });
-        if (object) this.objectBlocks.add(index);
+        }, object: void 0 });
       } catch (error) {
         if (preserveDataOnFailure && readBlock) {
           this.renderedBlocks.set(index, { get block() {
@@ -330,12 +331,35 @@ var Chunk = class _Chunk {
           }, object: void 0 });
         } else this.data.assign(index, 0);
         this.fluidCells[index] = 0;
-        object?.removeFromScene();
-        if (!failed) failure = error;
-        failed = true;
+        if (order < failureOrder) {
+          failureOrder = order;
+          failure = error;
+        }
       }
     }
-    if (failed) throw failure;
+    const pending = [...jobs];
+    const objects = await Promise.allSettled(pending.map(([, job]) => this.createBlockObject(job.blockState, job.position, job.options)));
+    for (const [i, [index, { order, readBlock }]] of pending.entries()) {
+      const result = objects[i];
+      if (result.status === "fulfilled") {
+        this.renderedBlocks.set(index, { get block() {
+          return readBlock();
+        }, object: result.value });
+        this.objectBlocks.add(index);
+      } else {
+        if (preserveDataOnFailure) {
+          this.renderedBlocks.set(index, { get block() {
+            return readBlock();
+          }, object: void 0 });
+        } else this.data.assign(index, 0);
+        this.fluidCells[index] = 0;
+        if (order < failureOrder) {
+          failureOrder = order;
+          failure = result.reason;
+        }
+      }
+    }
+    if (failureOrder < Infinity) throw failure;
     return positions;
   }
   /** Replaces every cell from parsed section data. The caller refreshes neighbor culling. */
@@ -406,37 +430,42 @@ var Chunk = class _Chunk {
         failed = true;
       }
     }
-    for (const { index, blockState, biome } of perBlocks) {
-      let object;
-      try {
-        object = await this.scene.addBlock(blockState, {
-          mergeMeshes: true,
-          instanceMeshes: true,
-          maxInstanceCount: 2e3,
-          initialState: this.data.stateAt(this.data.idAt(index)).properties,
-          variantPosition: this.positionAt(index),
-          biome,
-          biomePosition: this.biomePosition(index, blockState, this.data.stateAt(this.data.idAt(index)))
-        });
-        object.setPosition(new Vector3(
-          this.x * 256 + index % 16 * 16,
-          this.y * 256 + Math.floor(index / 256) * 16,
-          this.z * 256 + Math.floor(index / 16) % 16 * 16
-        ));
-        this.renderedBlocks.get(index).object = object;
+    const objects = await Promise.allSettled(perBlocks.map(({ index, blockState, biome }) => this.createBlockObject(blockState, new Vector3(
+      this.x * 256 + index % 16 * 16,
+      this.y * 256 + Math.floor(index / 256) * 16,
+      this.z * 256 + Math.floor(index / 16) % 16 * 16
+    ), {
+      mergeMeshes: true,
+      instanceMeshes: true,
+      maxInstanceCount: 2e3,
+      initialState: this.data.stateAt(this.data.idAt(index)).properties,
+      variantPosition: this.positionAt(index),
+      biome,
+      biomePosition: this.biomePosition(index, blockState, this.data.stateAt(this.data.idAt(index)))
+    })));
+    for (const [i, { index }] of perBlocks.entries()) {
+      const result = objects[i];
+      if (result.status === "fulfilled") {
+        this.renderedBlocks.get(index).object = result.value;
         this.objectBlocks.add(index);
-      } catch (error) {
+      } else {
         this.data.assign(index, 0);
         this.fluidCells[index] = 0;
         this.renderedBlocks.delete(index);
         this.objectBlocks.delete(index);
-        object?.removeFromScene();
-        if (!failed) failure = error;
+        if (!failed) failure = result.reason;
         failed = true;
       }
     }
     if (failed) throw failure;
   }
+  createBlockObject(blockState, position, options) {
+    return this.scene.addSceneObject(blockState, () => {
+      const object = new BlockObject(blockState, options);
+      object.position.copy(position);
+      return object;
+    }, options);
+  }
   positionAt(index) {
     return [this.x * 16 + index % 16, this.y * 16 + Math.floor(index / 256), this.z * 16 + Math.floor(index / 16) % 16];
   }