illutions 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,10 +1,27 @@
 # Changelog
 
+## 0.30.0
+
+### Changed
+
+- Replaced `Mesh3D.setTexture()` and `TextureSlot` with `requestImageTexture()` and `getImageTexture()` to separate requesting unused GLTF images from accessing their initialized Three.js textures and assigning them directly to material slots.
+- Textures created from unused GLTF images now remain stable across progressive model levels while their image and mipmap data is updated.
+
+### Fixed
+
+- Fixed the `Obj3D.onStart()` lifecycle so it is called before GLTF model loading begins, as documented.
+
+## 0.29.1
+
+### Fixed
+
+- Fixed progressive model loading so textures belonging to materials not currently assigned to a mesh are updated through all model quality levels.
+
 ## 0.29.0
 
 ### Added
 
-- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
+- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
 - Added the exported `TextureSlot` union for the supported material slots.
 
 ## 0.28.0

package/README.md

@@ -19,6 +19,9 @@ Coordinate GLTF animation clips, GSAP transitions, camera paths and custom dolly
 **Progressive model and HDRI loading**  
 Load ordered model levels and environment maps progressively for faster initial presentation and seamless quality upgrades.
 
+**Flexible baked texture workflows**  
+Assign embedded GLTF textures by name to any object and material as light maps, fully baked combined color maps or alpha maps.
+
 **XState-powered application logic**  
 Model complex application flows as predictable and inspectable state machines with integrated XState 5 usage.
 

package/dist/main.d.ts

@@ -1694,31 +1694,12 @@ export declare class Mesh3D extends Obj3D {
         [key: string]: any;
     }): void;
     /**
-     * Updates one or more material properties of this mesh.
-     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
-     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
-     */
-    setMaterialProperties({ needsUpdate, ...properties }: {
-        needsUpdate?: boolean;
-        [key: string]: any;
-    }): void;
-    /**
-     * Loads an unused texture embedded in the current GLTF and assigns it to a material.
-     * @param options - Unused texture assignment settings.
-     * @param options.name - Name of the GLTF image used by the texture.
-     * @param options.material - Material that receives the unused texture.
-     * @param options.slot - Target material texture slot. See {@link TextureSlot}.
-     * @param options.lightMapIntensity - Light map intensity used for `LightMap`. Default: **1**
-     * @param options.channel - Texture UV channel. Default: **1**
+     * Returns an image texture requested from an unused GLTF image.
+     * @param name - GLTF image name passed to {@link requestImageTexture} during `onStart()`.
+     * @returns The initialized texture shared across progressive model levels.
      * @public
      */
-    protected setTexture({ name, material, slot, lightMapIntensity, channel }: {
-        name: string;
-        material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
-        slot: TextureSlot;
-        lightMapIntensity?: number;
-        channel?: number;
-    }): void;
+    protected getImageTexture(name: string): THREE_TYPE.Texture;
     /**
      * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
      * @param objGltf - The currently traversed mesh.
@@ -1728,6 +1709,21 @@ export declare class Mesh3D extends Obj3D {
      * {@includeCode ../../examples/mesh3D-cube.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Mesh): void;
+    /**
+     * Requests a Three.js texture from an unused GLTF image for initialization before the model is traversed. Call this method from `onStart()` for every unused image that will be accessed later.
+     * @param name - Name of the GLTF image.
+     * @public
+     */
+    protected requestImageTexture(name: string): void;
+    /**
+     * Updates one or more material properties of this mesh.
+     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
+     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
+     */
+    setMaterialProperties({ needsUpdate, ...properties }: {
+        needsUpdate?: boolean;
+        [key: string]: any;
+    }): void;
     /* Excluded from this release type: setModel */
     /* Excluded from this release type: setReflectivesSSR */
     /* Excluded from this release type: traverse */
@@ -1768,26 +1764,28 @@ declare class Model {
     /* Excluded from this release type: sceneReady */
     private resolveSceneReady;
     private rejectSceneReady;
-    private gltf;
     private meshes;
     private scene;
-    private readonly textsUsed;
-    private readonly textsUnused;
-    constructor({ canvas, cfg, events, modules, renderer, rendererReady, initFirstScene: initFirstScene, reportModelReady, waitForRender }: ModelParams);
-    private addMaterials;
-    private addText;
-    private addTextUnused;
-    private loadTextsUnused;
-    private applyTextsUnused;
-    private disposeObsoleteResources;
+    private readonly imageNamesUnused;
+    private readonly imageTexturesUnused;
+    private readonly textures;
+    constructor({ canvas, cfg, events, modules, renderer, rendererReady, initFirstScene, reportModelReady, waitForRender }: ModelParams);
+    /* Excluded from this release type: addImageUnusedName */
+    private addMaterialsFromMesh;
+    private addTexturesFromMaterial;
+    private addTexture;
+    private disposeGeometries;
+    private disposeMaterialsAndTextures;
+    /* Excluded from this release type: getTextureFromImageUnused */
+    private initTextureFromImageUnused;
+    private initTexturesFromImagesUnused;
+    private initTexturesGltf;
     /* Excluded from this release type: load */
     private loadGltf;
-    private loadTextUnused;
+    private prepareTextureImages;
     private reportError;
-    /* Excluded from this release type: setTextUsed */
-    private updateMaterials;
-    private updateMeshes;
-    private updateTextImages;
+    private updateGeometries;
+    private updateTextureImages;
 }
 
 /**
@@ -2845,17 +2843,6 @@ export declare interface StateMachineCfg {
  */
 export declare type StopMode = 'all' | 'last' | 'none';
 
-/**
- * Defines the material texture slots available for unused GLTF images.
- *
- * - `ColorMap` assigns the texture to `map`. Use it with a `MeshBasicMaterial` for a fully baked color texture.
- * - `LightMap` assigns the texture to the `lightMap` slot and requires a `MeshStandardMaterial`.
- * - `AlphaMap` assigns a separate alpha texture to the `alphaMap` slot, which GLTF does not support natively.
- */
-export declare type TextureSlot = 'ColorMap' | 'LightMap' | 'AlphaMap';
-
-/* Excluded from this release type: TextUsed */
-
 /** Function returned by an event subscription. Calling it removes the associated listener. */
 export declare type Unsubscribe = () => void;