illutions 0.28.0 → 0.29.1

package/CHANGELOG.md

@@ -1,32 +1,45 @@
 # Changelog
 
-## 0.28.0
-
-### Added
-
-- Added `Mesh3D.animMaterialColor()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` as object-bound counterparts to the existing `Engine` material methods.
-- Added the optional `needsUpdate` parameter to `Engine.animMaterialNumeric()`, `Engine.setMaterialProperties()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` to request material recompilation.
-- Added degree-based horizontal orbit constraints through `orbitCtrls.minAzimuthAngle` and `orbitCtrls.maxAzimuthAngle`.
-- Added `ModelLoadedEvent` with `Model_Loaded` for a single model and numbered `Model1_Loaded`, `Model2_Loaded`, etc. events for progressive models.
-- Added the `Model_Ready` event after the final progressive model variant has been applied and rendered.
-- Added the exported `Collider` configuration and `Raycast.setColliders()` and `Raycast.clearColliders()` to configure named scene objects or `Obj3D` instances as occluders, pickables, or hidden colliders.
-
-### Changed
-
-- Replaced `Raycast.setOccluders()`, `Raycast.resetOccluders()`, `Raycast.trackPickables()`, and `Raycast.untrackPickables()` with the unified collider API.
-- Renamed `Raycast.enable()` and `Raycast.disable()` to `Raycast.enablePickables()` and `Raycast.disablePickables()`.
-- Renamed `raycast.occlInterval` to `raycast.occludeeInterval` and `raycast.occlMoveFactor` to `raycast.occlusionMoveFactor`.
-- Changed progressive `ModelLoadingEvent` and `SceneRenderedEvent` types to numbered `Model1_Loading`, `Scene1_Rendered`, etc. events; unnumbered events remain available for a single model.
-- Removed the `level` property from `ModelLoadingEvent`; the progressive model level is now identified by the event type.
-- Removed the obsolete `fct` property from `ClipEvent`.
-- Changed pointer raycasts so that registered occluders block pickables behind them.
-
-### Fixed
-
-- Corrected `CanvasPointerEvent` to expose `Canvas_Click`, `Canvas_Pointer_Enter`, and `Canvas_Pointer_Leave`.
-- Added the already emitted `FpvCtrls_Disposed` event to `FpvCtrlsEvent`.
-- Delayed the postprocessing noise check until `Model_Ready` so that postprocessing is not disabled before the final progressive model variant is rendered.
-
+## 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 the exported `TextureSlot` union for the supported material slots.
+
+## 0.28.0
+
+### Added
+
+- Added `Mesh3D.animMaterialColor()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` as object-bound counterparts to the existing `Engine` material methods.
+- Added the optional `needsUpdate` parameter to `Engine.animMaterialNumeric()`, `Engine.setMaterialProperties()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` to request material recompilation.
+- Added degree-based horizontal orbit constraints through `orbitCtrls.minAzimuthAngle` and `orbitCtrls.maxAzimuthAngle`.
+- Added `ModelLoadedEvent` with `Model_Loaded` for a single model and numbered `Model1_Loaded`, `Model2_Loaded`, etc. events for progressive models.
+- Added the `Model_Ready` event after the final progressive model variant has been applied and rendered.
+- Added the exported `Collider` configuration and `Raycast.setColliders()` and `Raycast.clearColliders()` to configure named scene objects or `Obj3D` instances as occluders, pickables, or hidden colliders.
+
+### Changed
+
+- Replaced `Raycast.setOccluders()`, `Raycast.resetOccluders()`, `Raycast.trackPickables()`, and `Raycast.untrackPickables()` with the unified collider API.
+- Renamed `Raycast.enable()` and `Raycast.disable()` to `Raycast.enablePickables()` and `Raycast.disablePickables()`.
+- Renamed `raycast.occlInterval` to `raycast.occludeeInterval` and `raycast.occlMoveFactor` to `raycast.occlusionMoveFactor`.
+- Changed progressive `ModelLoadingEvent` and `SceneRenderedEvent` types to numbered `Model1_Loading`, `Scene1_Rendered`, etc. events; unnumbered events remain available for a single model.
+- Removed the `level` property from `ModelLoadingEvent`; the progressive model level is now identified by the event type.
+- Removed the obsolete `fct` property from `ClipEvent`.
+- Changed pointer raycasts so that registered occluders block pickables behind them.
+
+### Fixed
+
+- Corrected `CanvasPointerEvent` to expose `Canvas_Click`, `Canvas_Pointer_Enter`, and `Canvas_Pointer_Leave`.
+- Added the already emitted `FpvCtrls_Disposed` event to `FpvCtrlsEvent`.
+- Delayed the postprocessing noise check until `Model_Ready` so that postprocessing is not disabled before the final progressive model variant is rendered.
+
 ## 0.27.0
 
 ### Added
@@ -159,4 +172,4 @@
 
 ### Changed
 
-- Added `cfg.audio.enable` to the configuration.
+- Added `cfg.audio.enable` to the configuration.

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

@@ -8,6 +8,7 @@ import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { FXAAShader } from 'three/addons/shaders/FXAAShader.js';
+import { GLTF } from 'three/addons/loaders/GLTFLoader.js';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
@@ -1474,6 +1475,14 @@ export declare interface HemisphereCfg {
     intensity: number;
 }
 
+declare interface ImageTexture {
+    name: string;
+    material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
+    slot: TextureSlot;
+    lightMapIntensity: number;
+    channel: number;
+}
+
 /**
  * Defines the built-in engine infobox settings used to display FPS, CPU/frame timing and renderer.info values.
  * @category Cfg
@@ -1660,6 +1669,7 @@ export declare class Mesh3D extends Obj3D {
     groundReflector: ReflectorForSSRPass | null;
     /** Objects that participate in the screen-space reflection (SSR) effect. These objects are used for reflective rendering in the scene. */
     reflectivesSSR: THREE_TYPE.Object3D[];
+    private model;
     /* Excluded from this release type: lib */
     /* Excluded from this release type: __constructor */
     /**
@@ -1700,6 +1710,23 @@ export declare class Mesh3D extends Obj3D {
         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**
+     * @public
+     */
+    protected setTexture({ name, material, slot, lightMapIntensity, channel }: {
+        name: string;
+        material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
+        slot: TextureSlot;
+        lightMapIntensity?: number;
+        channel?: number;
+    }): void;
     /**
      * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
      * @param objGltf - The currently traversed mesh.
@@ -1709,6 +1736,7 @@ export declare class Mesh3D extends Obj3D {
      * {@includeCode ../../examples/mesh3D-cube.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Mesh): void;
+    /* Excluded from this release type: setModel */
     /* Excluded from this release type: setReflectivesSSR */
     /* Excluded from this release type: traverse */
 }
@@ -1735,6 +1763,44 @@ export declare interface MeshCfg {
     frustumCulled: boolean;
 }
 
+declare class Model {
+    private readonly canvas;
+    private readonly cfg;
+    private readonly events;
+    private readonly modules;
+    private readonly renderer;
+    private readonly initFirstScene;
+    private readonly reportModelReady;
+    private readonly rendererReady;
+    private readonly waitForRender;
+    /* Excluded from this release type: sceneReady */
+    private resolveSceneReady;
+    private rejectSceneReady;
+    private gltf;
+    private meshes;
+    private scene;
+    private readonly imageTextures;
+    private readonly imageTextureInits;
+    private readonly textures;
+    constructor({ canvas, cfg, events, modules, renderer, rendererReady, initFirstScene, reportModelReady, waitForRender }: ModelParams);
+    private addMaterialsFromMesh;
+    private addTexturesFromMaterial;
+    private addTexture;
+    private applyImageTexturesToMaterials;
+    private disposeGeometries;
+    private disposeSourceMaterials;
+    private initImageTexture;
+    private initImageTextures;
+    private initTextures;
+    /* Excluded from this release type: load */
+    private loadGltf;
+    private prepareImageTextures;
+    /* Excluded from this release type: prepareImageTextureForMaterial */
+    private reportError;
+    private updateGeometries;
+    private updateTextureImages;
+}
+
 /**
  * Defines the GLTF/GLB model loading settings used to fetch models and configure optional Draco decoding.
  * @category Cfg
@@ -1791,6 +1857,18 @@ export declare interface ModelLoadingEvent {
     loading: number;
 }
 
+declare interface ModelParams {
+    canvas: HTMLElement;
+    cfg: Cfg;
+    events: Events;
+    modules: Modules;
+    renderer: Renderer_2;
+    rendererReady: Promise<void> | null;
+    initFirstScene: (gltf: GLTF) => Map<string, THREE_TYPE.Mesh>;
+    reportModelReady: () => void;
+    waitForRender: () => Promise<void>;
+}
+
 /** @event Fired after the final progressive model variant has been applied and rendered and triggers the corresponding XState event. */
 export declare interface ModelReadyEvent {
     /** Identifies this event type. */
@@ -2471,6 +2549,8 @@ export declare interface RenderCfg {
 /** Defines the available renderer backends. */
 export declare type Renderer = 'webgl' | 'webgpu' | 'auto';
 
+declare type Renderer_2 = THREE_TYPE.WebGLRenderer | THREE_WEBGPU_TYPE.WebGPURenderer;
+
 /**
  * Defines the scene settings used to configure background, environment, model, fog and lights.
  * @category Cfg
@@ -2776,6 +2856,15 @@ 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';
+
 /** Function returned by an event subscription. Calling it removes the associated listener. */
 export declare type Unsubscribe = () => void;