minerender 2.1.0-alpha.6 → 2.1.0-alpha.8

package/dist/browser/index.d.mts

@@ -534,14 +534,13 @@ declare class MinecraftFaceUV {
 }
 
 /**
- * Releases every long-lived timer MineRender holds, so a Node process can exit.
+ * Stops the shared Ticker and request queues, and clears the in-memory caches.
  *
- * Both `@inventivetalent/loading-cache` (cache expiry) and `jobqu` (request queue draining) use
- * self-rescheduling timers that are not unref'd, which keeps the event loop alive for as long as
- * the library is loaded. Browsers don't care, but anything headless - a render server, a CLI, a
- * test run - has to call this when it's done.
+ * Idle Node processes can exit without calling this: cache and Ticker timers are unref'd,
+ * and idle request queues hold no timer. Pending requests keep their normal timer references.
  *
- * The library stays usable afterwards; the caches and queues simply start over.
+ * Call this only when finished with MineRender. Waiting and future requests reject; requests
+ * already running can finish. Queue shutdown is permanent, and cache expiry timers do not restart.
  */
 declare function shutdown(): void;
 
@@ -853,6 +852,7 @@ declare class EntityObject extends SceneObject {
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
+    private get textureKey();
     protected loadTextures(): Promise<void>;
     protected createMeshes(force?: boolean): void;
     protected applyTextures(): Promise<void>;
@@ -1219,8 +1219,8 @@ declare class Caching {
     /**
      * Clears every cache and stops its expiry timer.
      *
-     * loading-cache reschedules that timer indefinitely, so a Node process will not exit until
-     * this is called - see {@link shutdown}.
+     * Expiry timers are unref'd in Node, so idle processes can exit without this cleanup.
+     * Use {@link shutdown} to also stop requests and the shared Ticker.
      */
     static end(): void;
     static get cacheSizes(): {};
@@ -1473,8 +1473,9 @@ declare class Requests {
         mcAsset: number;
     };
     /**
-     * Stops both queue timers. jobqu reschedules itself indefinitely, so a Node process will not
-     * exit until this is called - see {@link shutdown}.
+     * Permanently stops both queues and rejects waiting and future requests.
+     * Requests already running can finish. Idle queues hold no timer, so Node can exit without
+     * this cleanup. See {@link shutdown}.
      */
     static end(): void;
 }
@@ -1511,6 +1512,9 @@ declare class Skins {
 }
 
 declare class TextureLoader {
+    private static readonly failedTextures;
+    /** Reports whether image loading failed, so cached textures can be retried. */
+    static hasFailed(texture: Texture): boolean;
     protected static createTexture(): Texture;
     static loadInBackground(src: string, format?: PixelFormat, rotation?: number): Texture;
     static load(src: string, format?: PixelFormat, rotation?: number): Texture;
@@ -1620,7 +1624,7 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  *
  * `image-size` pulls in `fs`/`path` at module scope, so it can only live in the Node build.
  * Everything MineRender loads is a PNG in practice; GIF and JPEG are handled as a courtesy and
- * anything else falls through to an empty result (callers treat that as 0x0).
+ * anything else falls through to an empty result, which ImageLoader rejects.
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 

package/dist/browser/index.d.ts

@@ -534,14 +534,13 @@ declare class MinecraftFaceUV {
 }
 
 /**
- * Releases every long-lived timer MineRender holds, so a Node process can exit.
+ * Stops the shared Ticker and request queues, and clears the in-memory caches.
  *
- * Both `@inventivetalent/loading-cache` (cache expiry) and `jobqu` (request queue draining) use
- * self-rescheduling timers that are not unref'd, which keeps the event loop alive for as long as
- * the library is loaded. Browsers don't care, but anything headless - a render server, a CLI, a
- * test run - has to call this when it's done.
+ * Idle Node processes can exit without calling this: cache and Ticker timers are unref'd,
+ * and idle request queues hold no timer. Pending requests keep their normal timer references.
  *
- * The library stays usable afterwards; the caches and queues simply start over.
+ * Call this only when finished with MineRender. Waiting and future requests reject; requests
+ * already running can finish. Queue shutdown is permanent, and cache expiry timers do not restart.
  */
 declare function shutdown(): void;
 
@@ -853,6 +852,7 @@ declare class EntityObject extends SceneObject {
     constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
     init(): Promise<void>;
     dispose(): void;
+    private get textureKey();
     protected loadTextures(): Promise<void>;
     protected createMeshes(force?: boolean): void;
     protected applyTextures(): Promise<void>;
@@ -1219,8 +1219,8 @@ declare class Caching {
     /**
      * Clears every cache and stops its expiry timer.
      *
-     * loading-cache reschedules that timer indefinitely, so a Node process will not exit until
-     * this is called - see {@link shutdown}.
+     * Expiry timers are unref'd in Node, so idle processes can exit without this cleanup.
+     * Use {@link shutdown} to also stop requests and the shared Ticker.
      */
     static end(): void;
     static get cacheSizes(): {};
@@ -1473,8 +1473,9 @@ declare class Requests {
         mcAsset: number;
     };
     /**
-     * Stops both queue timers. jobqu reschedules itself indefinitely, so a Node process will not
-     * exit until this is called - see {@link shutdown}.
+     * Permanently stops both queues and rejects waiting and future requests.
+     * Requests already running can finish. Idle queues hold no timer, so Node can exit without
+     * this cleanup. See {@link shutdown}.
      */
     static end(): void;
 }
@@ -1511,6 +1512,9 @@ declare class Skins {
 }
 
 declare class TextureLoader {
+    private static readonly failedTextures;
+    /** Reports whether image loading failed, so cached textures can be retried. */
+    static hasFailed(texture: Texture): boolean;
     protected static createTexture(): Texture;
     static loadInBackground(src: string, format?: PixelFormat, rotation?: number): Texture;
     static load(src: string, format?: PixelFormat, rotation?: number): Texture;
@@ -1620,7 +1624,7 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  *
  * `image-size` pulls in `fs`/`path` at module scope, so it can only live in the Node build.
  * Everything MineRender loads is a PNG in practice; GIF and JPEG are handled as a courtesy and
- * anything else falls through to an empty result (callers treat that as 0x0).
+ * anything else falls through to an empty result, which ImageLoader rejects.
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 

package/dist/browser/index.js

@@ -576,8 +576,8 @@ var Caching = class {
   /**
    * Clears every cache and stops its expiry timer.
    *
-   * loading-cache reschedules that timer indefinitely, so a Node process will not exit until
-   * this is called - see {@link shutdown}.
+   * Expiry timers are unref'd in Node, so idle processes can exit without this cleanup.
+   * Use {@link shutdown} to also stop requests and the shared Ticker.
    */
   static end() {
     for (const cache of this.all) {
@@ -825,13 +825,14 @@ var _Requests = class _Requests {
   }
   static get queueSizes() {
     return {
-      generic: this.genericQueue.size,
-      mcAsset: this.mcAssetRequestQueue.size
+      generic: this.genericQueue.size + this.genericQueue.activeSize,
+      mcAsset: this.mcAssetRequestQueue.size + this.mcAssetRequestQueue.activeSize
     };
   }
   /**
-   * Stops both queue timers. jobqu reschedules itself indefinitely, so a Node process will not
-   * exit until this is called - see {@link shutdown}.
+   * Permanently stops both queues and rejects waiting and future requests.
+   * Requests already running can finish. Idle queues hold no timer, so Node can exit without
+   * this cleanup. See {@link shutdown}.
    */
   static end() {
     this.genericQueue.end();
@@ -911,29 +912,41 @@ var ImageLoader = class _ImageLoader {
   static async loadAsync(src) {
     return new Promise((resolve, reject) => {
       const image = this._createImage();
-      image.src = src;
       image.onload = () => resolve(image);
-      image.onerror = (err) => reject(err);
+      image.onerror = (err) => reject(err instanceof Error ? err : new Error("Failed to decode image"));
+      image.src = src;
     });
   }
   static loadElement(src, onload, onerr) {
     const image = this._createImage();
-    image.src = src;
     if (onload)
       image.onload = onload;
     if (onerr)
       image.onerror = onerr;
+    image.src = src;
     return image;
   }
   static async loadData(src) {
     console.debug(p2, "loadData", src);
-    return await this.infoToData(await this.getInfo(src));
+    const image = await this.loadCanvasData(src);
+    return image.data.getImageData(0, 0, image.width, image.height);
   }
   static async loadCanvasData(src) {
-    return await this.infoToCanvasData(await this.getInfo(src));
+    const keyStr = serializeImageKey({ src });
+    const info = this.getInfo(src);
+    const cached = Caching.rawImageCache.getIfPresent(keyStr);
+    try {
+      return await this.infoToCanvasData(await info);
+    } catch (err) {
+      if (cached && Caching.rawImageCache.getIfPresent(keyStr) === cached) {
+        Caching.rawImageCache.invalidate(keyStr);
+      }
+      throw err;
+    }
   }
   static async infoToCanvasData(info) {
-    const image = await _ImageLoader.loadAsync(info.src);
+    const type = info.type === "jpg" ? "jpeg" : info.type ?? "png";
+    const image = await _ImageLoader.loadAsync(`data:image/${type};base64,${info.data.toString("base64")}`);
     const canvas = createCanvas(info.width, info.height);
     const context = canvas.getContext("2d");
     context.drawImage(image, 0, 0);
@@ -944,11 +957,8 @@ var ImageLoader = class _ImageLoader {
     };
   }
   static async infoToData(info) {
-    const image = await _ImageLoader.loadAsync(info.src);
-    const canvas = createCanvas(info.width, info.height);
-    const context = canvas.getContext("2d");
-    context.drawImage(image, 0, 0);
-    return context.getImageData(0, 0, canvas.width, canvas.height);
+    const image = await this.infoToCanvasData(info);
+    return image.data.getImageData(0, 0, image.width, image.height);
   }
   static async getData(src) {
     const keyStr = serializeImageKey({ src });
@@ -963,13 +973,16 @@ var ImageLoader = class _ImageLoader {
     });
   }
   static async processResponse(response) {
-    const src = response.config.url;
+    const src = response.config?.url;
     const data = import_buffer.Buffer.from(response.data);
     const { width, height, type } = Env.provider.imageSize(data);
+    if (!width || !height) {
+      throw new Error("Invalid or unsupported image dimensions");
+    }
     return {
       src,
-      width: width || 0,
-      height: height || 0,
+      width,
+      height,
       type,
       data
     };
@@ -986,15 +999,7 @@ var ImageLoader = class _ImageLoader {
     return Requests.genericRequest({
       url: src,
       responseType: "arraybuffer"
-    }).then(this.processResponse).catch((err) => {
-      return {
-        src,
-        width: 0,
-        height: 0,
-        type: void 0,
-        data: import_buffer.Buffer.from([0])
-      };
-    });
+    }).then(this.processResponse);
   }
   static async getInfo(src) {
     const keyStr = serializeImageKey({ src });
@@ -1016,16 +1021,22 @@ var ImageLoader = class _ImageLoader {
 
 // src/texture/TextureLoader.ts
 var TextureLoader = class {
+  /** Reports whether image loading failed, so cached textures can be retried. */
+  static hasFailed(texture) {
+    return this.failedTextures.has(texture);
+  }
   static createTexture() {
     return new import_three4.Texture();
   }
   static loadInBackground(src, format = import_three4.RGBAFormat, rotation = 0) {
     const texture = this.createTexture();
     texture.colorSpace = THREE.SRGBColorSpace;
-    const image = ImageLoader.loadElement(src);
-    image.onload = function() {
+    const image = ImageLoader.loadElement(src, () => {
       texture.needsUpdate = true;
-    };
+    }, (error) => {
+      this.failedTextures.add(texture);
+      console.warn("Failed to load texture", src, error);
+    });
     texture.image = image;
     texture.format = format;
     texture.rotation = rotation;
@@ -1035,14 +1046,18 @@ var TextureLoader = class {
     const texture = new import_three4.Texture();
     texture.colorSpace = THREE.SRGBColorSpace;
     ImageLoader.getData(src).then((image) => {
-      texture.needsUpdate = true;
       texture.image = image;
+      texture.needsUpdate = true;
+    }).catch((error) => {
+      this.failedTextures.add(texture);
+      console.warn("Failed to load texture", src, error);
     });
     texture.format = format;
     texture.rotation = rotation;
     return Textures.initTextureProps(texture);
   }
 };
+TextureLoader.failedTextures = /* @__PURE__ */ new WeakSet();
 
 // src/texture/Textures.ts
 var THREE2 = __toESM(require("three"));
@@ -1066,6 +1081,10 @@ var Textures = class _Textures {
   }
   static getImage(key) {
     const keyStr = serializeTextureKey(key);
+    const cached = Caching.textureCache.peek(keyStr);
+    if (cached && TextureLoader.hasFailed(cached)) {
+      Caching.textureCache.invalidate(keyStr);
+    }
     return Caching.textureCache.get(keyStr, (k) => {
       return _Textures.createImage(key);
     });
@@ -1210,6 +1229,10 @@ var _Materials = class _Materials {
   }
   static getImage(key) {
     const keyStr = serializeMaterialKey(key);
+    const map = Caching.materialCache.peek(keyStr)?.map;
+    if (map && TextureLoader.hasFailed(map)) {
+      Caching.materialCache.invalidate(keyStr);
+    }
     return Caching.materialCache.get(keyStr, (k) => {
       return _Materials.createImage(key);
     });
@@ -1867,11 +1890,21 @@ var ModelTextures = class {
     return this._persistentMetaCache ?? (this._persistentMetaCache = PersistentCache.open("minerender-texturemeta"));
   }
   static async get(key) {
-    const asset = await this.preload(key);
-    if (asset) {
-      return ImageLoader.infoToCanvasData(asset);
+    const keyStr = key.serialize();
+    const pending = this.preload(key);
+    const cached = Caching.textureAssetCache.getIfPresent(keyStr);
+    try {
+      const asset = await pending;
+      if (asset) {
+        return await ImageLoader.infoToCanvasData(asset);
+      }
+      return void 0;
+    } catch (err) {
+      if (cached && Caching.textureAssetCache.getIfPresent(keyStr) === cached) {
+        Caching.textureAssetCache.invalidate(keyStr);
+      }
+      throw err;
     }
-    return void 0;
   }
   static async preload(key) {
     const keyStr = key.serialize();
@@ -3062,8 +3095,8 @@ var EntityObject = class extends SceneObject {
   dispose() {
     super.dispose();
   }
-  async loadTextures() {
-    this.imageData = await ModelTextures.get(new AssetKey(
+  get textureKey() {
+    return new AssetKey(
       this.entity.key?.namespace ?? DEFAULT_NAMESPACE,
       this.entity.key.path,
       //TODO: texture may differ from entity name; most of them are in subdirectories for multiple variants etc.
@@ -3071,7 +3104,10 @@ var EntityObject = class extends SceneObject {
       "entity",
       "assets",
       ".png"
-    ));
+    );
+  }
+  async loadTextures() {
+    this.imageData = await ModelTextures.get(this.textureKey);
   }
   //TODO: abstract this, since extracted model data can be used for entities, blocks, players
   createMeshes(force = false) {
@@ -3104,20 +3140,23 @@ var EntityObject = class extends SceneObject {
     this.meshesCreated = true;
   }
   async applyTextures() {
-    const textureAsset = await ModelTextures.preload(new AssetKey(
-      this.entity.key?.namespace ?? DEFAULT_NAMESPACE,
-      this.entity.key.path,
-      "textures",
-      "entity",
-      "assets",
-      ".png"
-    ));
-    if (textureAsset) {
-      let mat = Materials.getImage({ texture: { src: textureAsset.src } });
-      this.iterateAllMeshes((mesh) => {
-        mesh.material = mat;
-      });
-    }
+    const assetKeyStr = this.textureKey.serialize();
+    const keyStr = `entity:${assetKeyStr}`;
+    let mat = Caching.materialCache.getIfPresent(keyStr);
+    if (!mat) {
+      const pending = this.loadTextures();
+      const cachedAsset = Caching.textureAssetCache.getIfPresent(assetKeyStr);
+      await pending;
+      if (!this.imageData) return;
+      const canvas = this.imageData.data.canvas;
+      const createMaterial = () => Materials.createBasicCanvasMaterial(canvas);
+      mat = cachedAsset && Caching.textureAssetCache.getIfPresent(assetKeyStr) === cachedAsset ? Caching.materialCache.get(keyStr, createMaterial) : createMaterial();
+      this.imageData = void 0;
+    }
+    this.iterateAllMeshes((mesh) => {
+      mesh.material = mat;
+    });
+    this.notifyDirty();
   }
 };
 EntityObject.DEFAULT_OPTIONS = (0, import_ts_deepmerge4.default)({}, SceneObject.DEFAULT_OPTIONS, {});