illutions 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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.27.0
 
 ### Added
@@ -132,4 +159,4 @@
 
 ### Changed
 
-- Added `cfg.audio.enable` to the configuration.
+- Added `cfg.audio.enable` to the configuration.

package/README.md

@@ -3,6 +3,11 @@
 illutions is a proprietary Web 3D engine for building interactive browser-based
 3D applications with Three.js, XState, GSAP, Tweakpane and more.
 
+## Gallery
+
+Explore all illutions examples in the GitHub Gallery:
+[https://github.com/illutions](https://github.com/illutions)
+
 ## Highlights
 
 **Advanced post-processing**  
@@ -11,6 +16,9 @@ Add configurable SSAO, SSR, FXAA and SMAA pipelines for WebGL and WebGPU, plus T
 **Advanced animation control**  
 Coordinate GLTF animation clips, GSAP transitions, camera paths and custom dolly-rig camera workflows.
 
+**Progressive model and HDRI loading**  
+Load ordered model levels and environment maps progressively for faster initial presentation and seamless quality upgrades.
+
 **XState-powered application logic**  
 Model complex application flows as predictable and inspectable state machines with integrated XState 5 usage.
 
@@ -32,6 +40,9 @@ Use pointer-based raycasting and distance-aware spatial audio.
 **Flexible environments**  
 Load HDR, EXR and texture environments with configurable rotation, intensity and background controls.
 
+**Intelligent web markers**  
+Keep screen-space markers responsive with optimized occlusion checks, configurable occluders and movement-aware updates.
+
 **Runtime insights and debugging**  
 Inspect runtime properties, FPS, CPU and renderer statistics with detailed state, event and console reporting.
 

package/dist/main.d.ts

@@ -108,6 +108,7 @@ export declare class App<TClasses extends Classes = {}> {
     readonly audio: Audio_2;
     private readonly compCtrls;
     readonly engine: Engine;
+    private readonly lib;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
     readonly orbitCtrls: OrbitCtrls;
@@ -449,7 +450,7 @@ export declare interface CanvasKeyEvent {
 /** @event Fired when the user uses the pointer on the canvas and triggers the corresponding XState event. */
 export declare interface CanvasPointerEvent {
     /** Identifies this event type. */
-    type: 'Canvas_Click' | 'Canvas_Pointer_Down' | 'Canvas_Pointer_Move' | 'Canvas_Pointer_Up';
+    type: 'Canvas_Click' | 'Canvas_Pointer_Enter' | 'Canvas_Pointer_Leave';
     /** Native pointer event from the canvas interaction. */
     event: PointerEvent;
 }
@@ -516,14 +517,24 @@ export declare interface ClipEvent {
     type: 'Clip_Start' | 'Clip_Complete' | 'Clip_Cancel' | 'Clip_Fade_Start' | 'Clip_Fade_Complete' | 'Clip_Speed_Start' | 'Clip_Speed_Complete';
     /** The name of the affected `THREE.AnimationClip`. */
     clipName: string;
-    /** The name of the calling method. */
-    fct: string;
     /** The associated animation action, when available. */
     action?: THREE_TYPE.AnimationAction;
     /** Whether the clip weight is fading in or out. */
     fadeMode?: ActionFadeMode;
 }
 
+/** Defines how a scene object participates in raycasting. */
+export declare interface Collider {
+    /** Scene object or scene-object name used for raycasting. */
+    obj: Obj3D | string;
+    /** Hides the object while it is registered as a collider. */
+    hide?: boolean;
+    /** Allows the object to occlude tracked occludees and pickables. */
+    occluder?: boolean;
+    /** Allows the object to emit pointer events. */
+    pickable?: boolean;
+}
+
 declare type ColorNode = THREE_WEBGPU_TYPE.Node<'vec4'>;
 
 /**
@@ -673,6 +684,7 @@ export declare class Engine {
     /* Excluded from this release type: scene */
     private readonly cam3D;
     private readonly events;
+    private readonly lib;
     private readonly modules;
     private readonly objs3D;
     private readonly cfg;
@@ -705,6 +717,7 @@ export declare class Engine {
     private hemisphereLight;
     private powerMode;
     private postNoise;
+    private postNoiseCheck;
     private dTs;
     private dT;
     private dTFrameMax;
@@ -787,7 +800,7 @@ export declare class Engine {
      *
      * {@link AnimEvent}
      */
-    animMaterialColor({ mesh, duration, ease, ...colorProps }: {
+    animMaterialColor({ mesh, ...params }: {
         mesh: string;
         duration?: number;
         ease?: string;
@@ -803,6 +816,7 @@ export declare class Engine {
      * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
      * @param params.duration - The animation duration in seconds. Default: **0**
      * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
+     * @param params.needsUpdate - Requests one material recompilation when the animation starts. Default: **false**
      *
      * @remarks
      * Additional properties of `params` can specify one or more material numeric fields to animate (e.g. `metalness`, `roughness`, `opacity`, ...) with their target numeric values. Only the **first** provided
@@ -812,12 +826,13 @@ export declare class Engine {
      *
      * {@link AnimFadeEvent}
      */
-    animMaterialNumeric({ mesh, startValue, infinite, duration, ease, ...props }: {
+    animMaterialNumeric({ mesh, needsUpdate, ...params }: {
         mesh: string;
         startValue?: number | null;
         infinite?: boolean;
         duration?: number;
         ease?: string;
+        needsUpdate?: boolean;
         [key: string]: any;
     }): void;
     private calcEaseArea;
@@ -990,13 +1005,15 @@ export declare class Engine {
      *
      * @param params - Parameter object for setting material properties.
      * @param params.obj - The name of the mesh whose material properties should be modified.
+     * @param params.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
      *
      * @remarks
      * Additional properties of `params` can define one or more material fields to update (e.g. `color`, `roughness`, `metalness`, `map`, `emissiveMap`, ...), each with its target value. Texture paths provided
      * as strings are loaded asynchronously and assigned to the corresponding material slots. Unsupported or mismatched property types are ignored with a warning in debug mode.
      */
-    setMaterialProperties({ obj, ...props }: {
+    setMaterialProperties({ obj, needsUpdate, ...props }: {
         obj: string;
+        needsUpdate?: boolean;
         [key: string]: any;
     }): void;
     /* Excluded from this release type: setPostWebGl */
@@ -1204,7 +1221,9 @@ export declare class Events {
     /* Excluded from this release type: audioLoaded */
     /* Excluded from this release type: clip */
     /* Excluded from this release type: modelError */
+    /* Excluded from this release type: modelLoaded */
     /* Excluded from this release type: modelLoading */
+    /* Excluded from this release type: sceneRendered */
     /**
      * Sends an event to the state machine and optionally logs a debug message to the console.
      * @param event - Any XState event object (must include a `type` property) to be dispatched to the actor.
@@ -1392,7 +1411,7 @@ export declare interface FpvCtrlsCfg {
 /** @event Fired when an `FpvCtrls` event occurs and triggers the corresponding XState event. */
 export declare interface FpvCtrlsEvent {
     /** Identifies this event type. */
-    type: 'FpvCtrls_Disabled' | 'FpvCtrls_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
+    type: 'FpvCtrls_Disabled' | 'FpvCtrls_Disposed' | 'FpvCtrls_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
 }
 
 /**
@@ -1522,6 +1541,8 @@ export declare interface InfoBoxCfg {
     logsPerSecond: number;
 }
 
+/* Excluded from this release type: Lib */
+
 /**
  * The `Light3D` class represents a managed light source.
  * @category 3D Objects
@@ -1639,7 +1660,46 @@ 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[];
+    /* Excluded from this release type: lib */
     /* Excluded from this release type: __constructor */
+    /**
+     * Animates one or more color properties of this mesh's material.
+     * @param params - Animation parameters and target material color properties such as `color` or `emissive`.
+     * @param params.duration - Animation duration in seconds. Default: **0**
+     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
+     */
+    animMaterialColor(params: {
+        duration?: number;
+        ease?: string;
+    } & {
+        [key: string]: string | number | THREE_TYPE.Color;
+    }): void;
+    /**
+     * Animates the first numeric material property passed for this mesh.
+     * @param params - Animation parameters and the target numeric material property.
+     * @param params.startValue - Starting value. Defaults to the current material value.
+     * @param params.infinite - Whether the animation repeats indefinitely. Default: **false**
+     * @param params.duration - Animation duration in seconds. Default: **0**
+     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
+     * @param params.needsUpdate - Requests one material recompilation when the animation starts. Default: **false**
+     */
+    animMaterialNumeric({ needsUpdate, ...params }: {
+        startValue?: number | null;
+        infinite?: boolean;
+        duration?: number;
+        ease?: string;
+        needsUpdate?: boolean;
+        [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;
     /**
      * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
      * @param objGltf - The currently traversed mesh.
@@ -1717,14 +1777,24 @@ export declare interface ModelErrorEvent {
     error: Error;
 }
 
+/** @event Fired after a model asset has finished loading and parsing. */
+export declare interface ModelLoadedEvent {
+    /** Identifies the loaded model. */
+    type: 'Model_Loaded' | `Model${number}_Loaded`;
+}
+
 /** @event Fired while model assets are loading and triggers the corresponding XState event. */
 export declare interface ModelLoadingEvent {
-    /** Identifies this event type. */
-    type: 'Model_Loading';
+    /** Identifies the loading model. */
+    type: 'Model_Loading' | `Model${number}_Loading`;
     /** Loading progress in percent (0-100). */
     loading: number;
-    /** One-based index of the model level currently loading. */
-    level: number;
+}
+
+/** @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. */
+    type: 'Model_Ready';
 }
 
 declare class Modules {
@@ -1980,6 +2050,12 @@ export declare interface Obj3DVisibleEvent {
 
 export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
 
+declare interface OccludeeState {
+    obj: THREE_TYPE.Object3D;
+    needsCheck: boolean;
+    visible: boolean;
+}
+
 /**
  * Integrates three.js OrbitControls directly in the engine's render loop, supporting runtime updates and dynamic enabling/disabling.
  * @category Core
@@ -2081,6 +2157,11 @@ export declare interface OrbitCtrlsCfg {
      * @default false
      */
     load: boolean;
+    /**
+     * Maximum allowed horizontal orbit angle in degrees.
+     * @default Infinity
+     */
+    maxAzimuthAngle: number;
     /**
      * Maximum allowed distance between the camera and the target.
      * @default Infinity
@@ -2091,6 +2172,11 @@ export declare interface OrbitCtrlsCfg {
      * @default 180
      */
     maxPolarAngle: number;
+    /**
+     * Minimum allowed horizontal orbit angle in degrees.
+     * @default -Infinity
+     */
+    minAzimuthAngle: number;
     /**
      * Minimum allowed distance between the camera and the target.
      * @default 0
@@ -2168,9 +2254,7 @@ export declare interface ProgressBarHiddenEvent {
 }
 
 /**
- * The Raycast class manages pointer-based raycasting in a `THREE.Scene`. It tracks specified objects, detects cursor intersections with them, and triggers intersection and non-intersection events via
- * the application state. The class dynamically enables or disables pointer listeners depending on the number of tracked objects. It also handles pointer events (click, down, up, move, enter, leave) for the
- * intersected 3D objects.
+ * Manages collider-based occlusion and pointer picking in a `THREE.Scene`. Collider roles determine which objects block rays, emit pointer events, or remain hidden while participating in raycasting.
  * @category Core
  */
 export declare class Raycast {
@@ -2178,19 +2262,23 @@ export declare class Raycast {
     private readonly canvas;
     private readonly cfg;
     private readonly engine;
+    private readonly events;
     private readonly objs3D;
     private raycasterPick;
     private raycasterVisible;
+    private colliders;
+    private objsColliders;
     private objsOccluders;
-    private readonly objsOccls;
-    private readonly objsPickables;
+    private readonly objsOccludees;
+    private hasPickables;
+    private useSceneAsOccluder;
     private objActive;
     private objCandidate;
     private closestObjCounter;
-    private indexOcclNext;
-    private timeOcclNext;
-    private isEnabled;
-    private callbackOccls;
+    private indexOccludeeNext;
+    private pickablesEnabled;
+    private timeOccludeeNext;
+    private callbackOccludees;
     private callbackPointerHover;
     private listenerClick;
     private listenerCancel;
@@ -2205,14 +2293,19 @@ export declare class Raycast {
     private dirCamToObj;
     private posNdcPointer;
     /* Excluded from this release type: __constructor */
-    private checkOcclVisible;
-    /** Enables pointer-based raycasting and adds all necessary pointer event listeners and the frame update callback. */
-    enable(): void;
-    /** Disables pointer-based raycasting and removes all pointer event listeners and the frame update callback. */
-    disable(): void;
+    private checkOccludeeVisible;
+    /** Removes all colliders and restores scene objects hidden by `setColliders()`. */
+    clearColliders(): void;
+    /** Enables pickable raycasting and its pointer event listeners. */
+    enablePickables(): void;
+    /** Disables pickable raycasting without removing the collider configuration. */
+    disablePickables(): void;
+    private getColliderState;
+    private getPickableHit;
     private getObjAtPointer;
-    private getOcclState;
-    /* Excluded from this release type: getOcclVisible */
+    private emitPointerEvent;
+    /* Excluded from this release type: getOccludeeState */
+    /* Excluded from this release type: getOccludeeVisible */
     private onCanvasClick;
     private onCanvasPointerLeave;
     private onCanvasPointerMove;
@@ -2220,49 +2313,20 @@ export declare class Raycast {
     private onCanvasPointerDown;
     private onCanvasPointerExit;
     private onCanvasPointerUp;
-    private onPointerEnter;
-    private onPointerLeave;
-    private onPointerMove;
-    /* Excluded from this release type: resetOcclState */
-    /** Removes the explicit occlusion-object restriction so that all scene objects are checked again. */
-    resetOccluders(): void;
-    /**
-     * Restricts occlusion raycasts to the specified scene objects. Without an explicit restriction, all scene objects are checked.
-     *
-     * @param params - Parameter object.
-     * @param params.objs3D - The `Obj3D` instances that may block visibility.
-     */
-    setOccluders({ objs3D }: {
-        objs3D: Obj3D[];
-    }): void;
-    /* Excluded from this release type: trackOccl */
-    /**
-     * Begins tracking a list of scene objects for pointer intersection detection. If the raycaster is not yet listening for pointer movements, this method automatically attaches pointer event listeners
-     * (`pointermove`, `click`, `pointercancel`, `pointerdown`, `pointerleave`, `pointerup`).
-     *
-     * @param params - Parameter object.
-     * @param params.objs3D - The `Obj3D` instances to track.
-     */
-    trackPickables({ objs3D }: {
-        objs3D: Obj3D[];
-    }): void;
-    /* Excluded from this release type: untrackOccl */
     /**
-     * Stops tracking the specified scene objects for ray intersection detection. It automatically removes the pointer event listeners if no tracked objects remain.
-     *
-     * @param params - Parameter object.
-     * @param params.objs3D - The `Obj3D` instances to untrack.
+     * Replaces the current raycast colliders. The complete scene is used for occlusion until this method or `clearColliders()` is called for the first time.
+     * @param colliders - Scene objects and their occluder, pickable, and visibility roles.
      */
-    untrackPickables({ objs3D }: {
-        objs3D: Obj3D[];
-    }): void;
+    setColliders(colliders: Collider[]): void;
+    /* Excluded from this release type: trackOccludee */
+    /* Excluded from this release type: untrackOccludee */
     /**
      * Registers and executes a low-level extension function with access to the public `Raycast` API.
      * @param extension - Function that receives the current `Raycast` instance and can use its public members and methods.
      * @remarks This method is intended for advanced custom integrations where developers need direct access to the engine instance. The extension is executed once immediately when `use()` is called.
      */
     use(extension: (raycast: Raycast) => void): void;
-    private updateOccls;
+    private updateOccludees;
     private updatePointerHover;
     private updatePointerPosition;
 }
@@ -2272,16 +2336,6 @@ export declare class Raycast {
  * @category Cfg
  */
 export declare interface RaycastCfg {
-    /**
-     * Time in milliseconds over which all pending occlusion checks are distributed once. A value of `0` processes all pending checks in one frame.
-     * @default 0
-     */
-    occlInterval: number;
-    /**
-     * Relative movement threshold used to request a new occlusion check. The value is multiplied by the current distance between the camera and the tracked object. A value of `0` reacts to every position change.
-     * @default 0.01
-     */
-    occlMoveFactor: number;
     /**
      * Circle radius around the pointer in pixels.
      * @default 10
@@ -2297,6 +2351,16 @@ export declare interface RaycastCfg {
      * @default 5
      */
     countClosestObjs: number;
+    /**
+     * Time in milliseconds over which all pending occludee checks are distributed once. A value of `0` processes all pending checks in one frame.
+     * @default 0
+     */
+    occludeeInterval: number;
+    /**
+     * Relative movement threshold used to request a new occlusion check. The value is multiplied by the current distance between the camera and the tracked occludee. A value of `0` reacts to every position change.
+     * @default 0.01
+     */
+    occlusionMoveFactor: number;
 }
 
 /**
@@ -2436,10 +2500,10 @@ export declare interface SceneReadyEvent {
     type: 'Scene_Ready';
 }
 
-/** @event Fired after the scene has been rendered for the first time and triggers the corresponding XState event. */
+/** @event Fired after the scene or a progressive scene variant has been rendered for the first time and triggers the corresponding XState event. */
 export declare interface SceneRenderedEvent {
-    /** Identifies this event type. */
-    type: 'Scene_Rendered';
+    /** Identifies the rendered scene or progressive scene variant. */
+    type: 'Scene_Rendered' | `Scene${number}_Rendered`;
 }
 
 /**