illutions 0.26.0 → 0.27.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.27.0
+
+### Added
+
+- Added progressive model loading through ordered model levels in `ModelCfg.file`.
+
+### Changed
+
+- Changed `ModelCfg.file` from `string | null` to `string[]`; use an empty array when no model should be loaded.
+- Added the one-based `level` parameter to `ModelLoadingEvent` to identify the model level currently loading.
+- Changed state names to `snake_case` and event names to `Pascal_Snake_Case`.
+- Updated debug console output to use `State:` and `Event:` labels and the new naming conventions.
+
 ## 0.26.0
 
 ### Added
@@ -24,19 +37,19 @@
 
 ### Added
 
-- Added `CanvasPointerLeave` handling to the `OBJ3D_POINTER_LEAVE` event.
+- Added `CanvasPointerLeave` handling to the `Obj3D_Pointer_Leave` event.
 - Added `ActionCtrls` for centralized animation action lifecycle, layer grouping, and interruptible fades.
-- Extended `ClipEvent` with `CLIP_CANCEL`, `CLIP_FADE_START`, `CLIP_FADE_COMPLETE`, `CLIP_SPEED_START`, and `CLIP_SPEED_COMPLETE` events.
+- Extended `ClipEvent` with `Clip_Cancel`, `Clip_Fade_Start`, `Clip_Fade_Complete`, `Clip_Speed_Start`, and `Clip_Speed_Complete` events.
 
 ### Fixed
 
-- Fixed `OBJ3D_POINTER_LEAVE` being emitted during pointer movement with a pressed mouse button and ensured touch pointers emit it after `OBJ3D_POINTER_UP` when contact ends.
+- Fixed `Obj3D_Pointer_Leave` being emitted during pointer movement with a pressed mouse button and ensured touch pointers emit it after `Obj3D_Pointer_Up` when contact ends.
 
 ## 0.24.1
 
 ### Added
 
-- Added the `PROGRESSBAR_HIDDEN` event.
+- Added the `ProgressBar_Hidden` event.
 
 ### Changed
 
@@ -53,7 +66,7 @@
 - Added animation modes `BlendMode`, `FinishMode`, `LoopMode`, `StopMode`
 - Added `fadeDuration` to `playClip()` and `playClipCam()`.
 - Added `Audio.load()` to load audio without starting playback.
-- Added the `AudioLoadedEvent` (`AUDIO_LOADED`) event for handling completed audio loading.
+- Added the `AudioLoadedEvent` (`Audio_Loaded`) event for handling completed audio loading.
 
 ### Changed
 

package/README.md

@@ -3,14 +3,22 @@
 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**  
-Add SSAO, SSR, FXAA and SMAA through configurable pipelines for WebGL and WebGPU.
+Add configurable SSAO, SSR, FXAA and SMAA pipelines for WebGL and WebGPU, plus TRAA for WebGPU.
 
 **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

@@ -78,7 +78,7 @@ export declare interface AmbientlightCfg {
 /** @event Fired when an object animation starts or finishes and triggers the corresponding XState event. */
 export declare interface AnimEvent {
     /** Identifies this event type. */
-    type: 'ANIM_COMPLETE' | 'ANIM_START';
+    type: 'Anim_Complete' | 'Anim_Start';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
     /** The name of the calling method. */
@@ -88,7 +88,7 @@ export declare interface AnimEvent {
 /** @event Fired when a material fade animation starts or finishes and triggers the corresponding XState event. */
 export declare interface AnimFadeEvent {
     /** Identifies this event type. */
-    type: 'ANIM_FADE_COMPLETE' | 'ANIM_FADE_START';
+    type: 'Anim_Fade_Complete' | 'Anim_Fade_Start';
     /** The name of the `THREE.Mesh` whose material fade changed state. */
     objName: string;
     /** The name of the calling method. */
@@ -176,19 +176,19 @@ declare class Audio_2 {
     }): boolean;
     private loadSound;
     /**
-     * Loads an audio file without playing it and sends an `AUDIO_LOADED` event when the sound is ready.
+     * Loads an audio file without playing it and sends an `Audio_Loaded` event when the sound is ready.
      * @param params - The sound options.
      */
     load({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
      * Loads an audio file and plays it automatically when loading is complete.
-     * Use this method when no separate `AUDIO_LOADED` handling is required.
+     * Use this method when no separate `Audio_Loaded` handling is required.
      * @param params - The sound options.
      */
     loadAndPlay({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
      * Plays an audio that has finished loading, with a smooth fade-in.
-     * When using {@link load}, call this method after receiving the matching `AUDIO_LOADED` event.
+     * When using {@link load}, call this method after receiving the matching `Audio_Loaded` event.
      * This method does not wait for an audio file that is still loading.
      * @param params - Parameter object.
      * @param params.name - The name of the loaded audio to play.
@@ -295,7 +295,7 @@ export declare interface AudioCfg {
 /** @event Fired when an audio file has finished loading and is ready for playback. */
 export declare interface AudioLoadedEvent {
     /** Identifies this event type. */
-    type: 'AUDIO_LOADED';
+    type: 'Audio_Loaded';
     /** The unique name assigned to the loaded sound. */
     soundName: string;
 }
@@ -441,7 +441,7 @@ export declare interface CamPerspectiveCfg extends CamBaseCfg {
 /** @event Fired when the user uses keys while the canvas has focus and triggers the corresponding XState event. */
 export declare interface CanvasKeyEvent {
     /** Identifies this event type. */
-    type: 'CANVAS_KEY_DOWN' | 'CANVAS_KEY_UP';
+    type: 'Canvas_Key_Down' | 'Canvas_Key_Up';
     /** Native keyboard event from the canvas interaction. */
     event: KeyboardEvent;
 }
@@ -449,7 +449,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_Down' | 'Canvas_Pointer_Move' | 'Canvas_Pointer_Up';
     /** Native pointer event from the canvas interaction. */
     event: PointerEvent;
 }
@@ -513,7 +513,7 @@ export declare type Classes<TObj3DClasses extends Record<string, Obj3DClass> = {
 /** @event Fired when a clip starts, completes, is canceled, fades its weight, or changes its playback speed. */
 export declare interface ClipEvent {
     /** Identifies this event type. */
-    type: 'CLIP_START' | 'CLIP_COMPLETE' | 'CLIP_CANCEL' | 'CLIP_FADE_START' | 'CLIP_FADE_COMPLETE' | 'CLIP_SPEED_START' | 'CLIP_SPEED_COMPLETE';
+    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. */
@@ -609,7 +609,7 @@ export declare type CompInsts<T extends Record<string, CompClass>> = {
 /** @event Fired when the overlap state of a web component changes and triggers the corresponding XState event. */
 export declare interface CompOverlapEvent {
     /** Identifies this event type. */
-    type: 'COMP_OVERLAP_CHANGED';
+    type: 'Comp_Overlap_Changed';
     /** The affected web component. */
     comp: Comp;
     /** Whether the component is overlapped by a nearer component. */
@@ -640,7 +640,7 @@ export declare interface CompsOverlapCfg {
 /** @event Fired when the combined 3D-object and overlap visibility of a web component changes and triggers the corresponding XState event. */
 export declare interface CompVisibleEvent {
     /** Identifies this event type. */
-    type: 'COMP_VISIBLE_CHANGED';
+    type: 'Comp_Visible_Changed';
     /** The affected web component. */
     comp: Comp;
     /** Whether the component is visible after combining all visibility conditions. */
@@ -677,10 +677,12 @@ export declare class Engine {
     private readonly objs3D;
     private readonly cfg;
     private readonly infoBox;
+    private readonly model;
     private actionCtrls;
     private gltf;
     private mixer;
     private callbacks;
+    private resolveWaitForRender;
     private canvas;
     private composer;
     /* Excluded from this release type: renderer */
@@ -714,6 +716,7 @@ export declare class Engine {
     private resizeDelay;
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: init */
+    private initFirstScene;
     private initWebGpuRenderer;
     /**
      * Registers a callback that is executed on every requestAnimationFrame update.
@@ -836,7 +839,6 @@ export declare class Engine {
     private isPostCfg;
     /* Excluded from this release type: isPostEnabled */
     private isPostGpu;
-    private loadScene;
     /**
      * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
@@ -1009,7 +1011,7 @@ export declare class Engine {
      * @param params.ease - The easing function name for the fade-out transition. Default: **'power1.inOut'**
      *
      * @remarks
-     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero. It emits `CLIP_SPEED_START`, `CLIP_SPEED_COMPLETE`, and finally `CLIP_CANCEL`.
+     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero. It emits `Clip_Speed_Start`, `Clip_Speed_Complete`, and finally `Clip_Cancel`.
      * If no speed transition is specified, the clip is canceled immediately.
      *
      * **Events**
@@ -1169,6 +1171,22 @@ export declare interface EnvCtrlsCfg {
     type: 'hdr' | 'exr' | 'texture';
 }
 
+declare type EventByType<TEvent extends {
+    type: string;
+}, TType extends EventType<TEvent>> = Extract<TEvent, {
+    type: TType;
+}>;
+
+declare class EventDispatcher<TEvent extends {
+    type: string;
+}> {
+    private readonly listeners;
+    addEventListener<TType extends EventType<TEvent>>(type: TType, listener: Listener<EventByType<TEvent, TType>>): Unsubscribe;
+    removeEventListener<TType extends EventType<TEvent>>(type: TType, listener: Listener<EventByType<TEvent, TType>>): void;
+    emit(event: TEvent): void;
+    listenerCount<TType extends EventType<TEvent>>(type: TType): number;
+}
+
 /**
  * Internal event dispatcher for the engine.
  * @category Core
@@ -1179,7 +1197,7 @@ export declare class Events {
     private eventQueue;
     private isProcessingEvents;
     /* Excluded from this release type: __constructor */
-    /** Queues callbacks and processes them sequentially to prevent re-entrant or simultaneous access to send(). */
+    /** A nested snapshot.can() is only evaluated after the current event callback has completed. */
     private enqueue;
     /* Excluded from this release type: anim */
     /* Excluded from this release type: animFade */
@@ -1196,6 +1214,10 @@ export declare class Events {
     /* Excluded from this release type: windowResize */
 }
 
+declare type EventType<TEvent extends {
+    type: string;
+}> = TEvent['type'];
+
 /**
  * Defines how an animation action behaves after its final loop.
  * - 'hold': Keeps the action enabled and holds its final pose.
@@ -1370,7 +1392,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_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
 }
 
 /**
@@ -1572,6 +1594,8 @@ export declare interface LightCfg {
     far: number;
 }
 
+declare type Listener<TEvent> = (event: TEvent) => void;
+
 /**
  * Defines how often an animation action is played.
  * - number: Plays the action the specified positive number of times.
@@ -1669,10 +1693,10 @@ export declare interface ModelCfg {
         texture: 'none' | 'webp' | 'ktx2';
     };
     /**
-     * The file path of your GLTF/GLB scene model. Set to `null` if no model should be loaded.
-     * @default null
+     * An ordered list of non-empty, progressively higher-quality GLTF/GLB scene paths. The first file initializes the scene, subsequent files replace matching mesh geometries and textured materials in order.
+     * @default []
      */
-    file: string | null;
+    file: string[];
     /**
      * Public path to the Draco decoder files.
      * @default 'draco/'
@@ -1688,7 +1712,7 @@ export declare interface ModelCfg {
 /** @event Fired when an error occurs while loading model assets and triggers the corresponding XState event. */
 export declare interface ModelErrorEvent {
     /** Identifies this event type. */
-    type: 'MODEL_ERROR';
+    type: 'Model_Error';
     /** The caught error object. */
     error: Error;
 }
@@ -1696,9 +1720,11 @@ export declare interface ModelErrorEvent {
 /** @event Fired while model assets are loading and triggers the corresponding XState event. */
 export declare interface ModelLoadingEvent {
     /** Identifies this event type. */
-    type: 'MODEL_LOADING';
+    type: 'Model_Loading';
     /** Loading progress in percent (0-100). */
     loading: number;
+    /** One-based index of the model level currently loading. */
+    level: number;
 }
 
 declare class Modules {
@@ -1800,7 +1826,7 @@ export declare class Obj3D {
      * @public
      */
     protected scene: Readonly<THREE_TYPE.Scene>;
-    private readonly eventDispatcher;
+    /* Excluded from this release type: eventDispatcher */
     private posNdc;
     private posScreen;
     private posScreenLast;
@@ -1890,7 +1916,7 @@ export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3
 /** @event Fired when the frustum visibility of a 3D object changes. */
 export declare interface Obj3DFrustumEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_FRUSTUM_CHANGED';
+    type: 'Obj3D_Frustum_Changed';
     /** Whether the object's world position is inside the camera frustum. */
     visibleFrustum: boolean;
 }
@@ -1907,7 +1933,7 @@ export declare type Obj3DInsts<T extends Record<string, Obj3DClass>> = {
 /** @event Fired when the user uses the pointer on an active object and triggers the corresponding XState event. */
 export declare interface Obj3DPointerEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_CLICK' | 'OBJ3D_POINTER_ENTER' | 'OBJ3D_POINTER_DOWN' | 'OBJ3D_POINTER_LEAVE' | 'OBJ3D_POINTER_MOVE' | 'OBJ3D_POINTER_UP';
+    type: 'Obj3D_Click' | 'Obj3D_Pointer_Enter' | 'Obj3D_Pointer_Down' | 'Obj3D_Pointer_Leave' | 'Obj3D_Pointer_Move' | 'Obj3D_Pointer_Up';
     /** Native pointer event from the active object interaction. */
     event: PointerEvent;
     /** The name of the object receiving the pointer event. */
@@ -1919,7 +1945,7 @@ export declare interface Obj3DPointerEvent {
  */
 export declare interface Obj3DPosScreenEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_POS_SCREEN_CHANGED';
+    type: 'Obj3D_Pos_Screen_Changed';
     /** The object's position projected into screen space. */
     posScreen: THREE_TYPE.Vector2;
 }
@@ -1929,7 +1955,7 @@ export declare interface Obj3DPosScreenEvent {
  */
 export declare interface Obj3DPosWorldEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_POS_WORLD_CHANGED';
+    type: 'Obj3D_Pos_World_Changed';
     /** The object's position in world coordinates. */
     posWorld: THREE_TYPE.Vector3;
 }
@@ -1939,7 +1965,7 @@ export declare interface Obj3DPosWorldEvent {
  */
 export declare interface Obj3DRotWorldEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_ROT_WORLD_CHANGED';
+    type: 'Obj3D_Rot_World_Changed';
     /** The object's rotation in world coordinates. */
     rotWorld: THREE_TYPE.Euler;
 }
@@ -1947,7 +1973,7 @@ export declare interface Obj3DRotWorldEvent {
 /** @event Fired when the combined frustum and occlusion visibility of a 3D object changes and triggers the corresponding XState event. */
 export declare interface Obj3DVisibleEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_VISIBLE_CHANGED';
+    type: 'Obj3D_Visible_Changed';
     /** Whether the object is inside the camera frustum and not occluded. */
     visible: boolean;
 }
@@ -2095,7 +2121,7 @@ export declare interface OrbitCtrlsCfg {
 /** @event Fired when an OrbitControls event occurs and triggers the corresponding XState event. */
 export declare interface OrbitCtrlsEvent {
     /** Identifies this event type. */
-    type: 'ORBITCTRLS_CHANGED' | 'ORBITCTRLS_DISABLED' | 'ORBITCTRLS_ENABLED' | 'ORBITCTRLS_END' | 'ORBITCTRLS_START' | 'ORBITCTRLS_DISPOSED';
+    type: 'OrbitCtrls_Changed' | 'OrbitCtrls_Disabled' | 'OrbitCtrls_Enabled' | 'OrbitCtrls_End' | 'OrbitCtrls_Start' | 'OrbitCtrls_Disposed';
 }
 
 /**
@@ -2138,7 +2164,7 @@ export declare interface PostCfg {
 /** @event Fired after the progress bar has finished hiding and triggers the corresponding XState event. */
 export declare interface ProgressBarHiddenEvent {
     /** Identifies this event type. */
-    type: 'PROGRESSBAR_HIDDEN';
+    type: 'ProgressBar_Hidden';
 }
 
 /**
@@ -2407,13 +2433,13 @@ export declare interface SceneCfg {
 /** @event Fired when the scene is set up and ready and triggers the corresponding XState event. */
 export declare interface SceneReadyEvent {
     /** Identifies this event type. */
-    type: 'SCENE_READY';
+    type: 'Scene_Ready';
 }
 
 /** @event Fired after the scene has been rendered for the first time and triggers the corresponding XState event. */
 export declare interface SceneRenderedEvent {
     /** Identifies this event type. */
-    type: 'SCENE_RENDERED';
+    type: 'Scene_Rendered';
 }
 
 /**
@@ -2694,7 +2720,7 @@ export declare type WebGpuRendererParams = NonNullable<ConstructorParameters<typ
 /** @event Fired when the window size changes and triggers the corresponding XState event. */
 export declare interface WindowResizeEvent {
     /** Identifies this event type. */
-    type: 'WINDOW_RESIZE';
+    type: 'Window_Resize';
 }
 
 export { }