illutions 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,39 +1,51 @@
-# Changelog
-
-## 0.22.1
-
-### Added
-
-- Added `cfg.render.params` for renderer-specific runtime parameters.
-- Added `render.api` output to the infobox.
-- Added `.blend` source files to the public example apps.
-
-### Changed
-
-- Renamed `cfg.webgl` and `cfg.webgpu` parameter groups to `params`.
-
-## 0.22.0
-
-### Changed
-
-- Updated the framework to Three.js r185.
-- Changed the default renderer selection to `render.api = 'auto'`.
-- Added `envCtrls.dataType` to configure environment texture data handling.
-- Replaced `SsrWebGpuCfg.opacity` with `SsrWebGpuCfg.intensity`.
-
-### Fixed
-
-- Clarified the WebGL/WebGPU renderer switch behavior.
+# Changelog
+
+## 0.23.0
+
+### Added
+
+- Added progressive environment map loading.
+- Added `Cam3D` support to `Audio.setListener()` targets.
+- Added support for using the base `Cam3D` class in the `classes.objs3D` registry.
+
+### Fixed
+
+- Fixed WebGL environment maps so PMREM-generated textures are not used for `THREE.Scene.background`.
+
+## 0.22.1
+
+### Added
+
+- Added `cfg.render.params` for renderer-specific runtime parameters.
+- Added `render.api` output to the infobox.
+- Added `.blend` source files to the public example apps.
+
+### Changed
+
+- Renamed `cfg.webgl` and `cfg.webgpu` parameter groups to `params`.
+
+## 0.22.0
+
+### Changed
+
+- Updated the framework to Three.js r185.
+- Changed the default renderer selection to `render.api = 'auto'`.
+- Added `envCtrls.dataType` to configure environment texture data handling.
+- Replaced `SsrWebGpuCfg.opacity` with `SsrWebGpuCfg.intensity`.
+
+### Fixed
+
+- Clarified the WebGL/WebGPU renderer switch behavior.
 - Enabled WebGPU renderer loading even when post-processing is disabled.
 
-## 0.21.9
-
-### Changed
-
-- Removed the `CfgCtrl` class and the related `app.cfgCtrl` access point. Runtime parameters are now updated through the responsible feature APIs, such as `app.audio.set(...)`.
-
-## 0.21.8
-
-### Changed
-
+## 0.21.9
+
+### Changed
+
+- Removed the `CfgCtrl` class and the related `app.cfgCtrl` access point. Runtime parameters are now updated through the responsible feature APIs, such as `app.audio.set(...)`.
+
+## 0.21.8
+
+### Changed
+
 - Added `cfg.audio.enable` to the configuration.

package/dist/main.d.ts

@@ -194,13 +194,13 @@ declare class Audio_2 {
     private setAttribute;
     private setAudioContext;
     /**
-     * Creates a `THREE.AudioListener` and attaches it to the specified object.
+     * Creates a `THREE.AudioListener` and attaches it to a named scene object or the active camera managed by `Cam3D`.
      *
      * @param params - Parameter object.
-     * @param params.object - The name of the scene object to attach the listener to.
+     * @param params.object - The name of a scene object or the `Cam3D` instance to attach the listener to.
      */
-    setListener({ object: name }: {
-        object: string;
+    setListener({ object }: {
+        object: string | Cam3D;
     }): void;
     private setAllPositionalSoundsCfg;
     private setPositionalSoundCfg;
@@ -253,7 +253,7 @@ export declare interface AudioCfg {
     refDistance: number;
     /**
      * Determines how quickly the volume falls off with distance.
-     * @default 5
+     * @default 1
      */
     rolloffFactor: number;
     /**
@@ -263,7 +263,7 @@ export declare interface AudioCfg {
     maxDistance: number;
     /**
      * The distance attenuation model used.
-     * @default 'exponential'
+     * @default 'inverse'
      */
     distanceModel: 'linear' | 'inverse' | 'exponential';
     /**
@@ -602,7 +602,7 @@ export declare class Engine {
     private composer;
     /* Excluded from this release type: renderer */
     private renderPipeline;
-    /* Excluded from this release type: modelReady */
+    /* Excluded from this release type: sceneReady */
     /* Excluded from this release type: rendererReady */
     private callbacks;
     private canvas;
@@ -754,7 +754,7 @@ export declare class Engine {
     private isPostCfg;
     /* Excluded from this release type: isPostEnabled */
     private isPostGpu;
-    private loadModel;
+    private loadScene;
     private pauseObjActions;
     /**
      * The method finds a Three.js animation clip by name, validates that it exists within the loaded GLTF and plays it via the `THREE.AnimationMixer`. It supports fade-in/out speed transitions, reverse playback,
@@ -942,7 +942,9 @@ export declare class Engine {
 }
 
 /**
- * This class controls and manages `THREE.Scene.environment` and `THREE.Scene.background` textures (HDRI, EXR, standard textures), including environment lighting and optional animated rotation.
+ * Controls `THREE.Scene.environment` and `THREE.Scene.background` textures, including environment lighting and optional rotation.
+ * The first configured map is used for environment lighting and the initial background. Additional maps replace only the visible background after loading.
+ * WebGL uses a PMREM-processed texture for environment lighting while keeping the loaded texture for the visible background.
  * @category Core
  */
 export declare class EnvCtrls {
@@ -950,25 +952,36 @@ export declare class EnvCtrls {
     private engine;
     private modules;
     /* Excluded from this release type: envReady */
-    /* Excluded from this release type: textureReady */
+    /* Excluded from this release type: textReady */
+    /* Excluded from this release type: bgdReady */
     private envEnabled;
     private envInit;
+    private envLoadId;
     private envIntensity;
-    private bgIntensity;
-    private bgBlurriness;
+    private bgdIntensity;
+    private bgdBlurriness;
     private rotation;
     private rotationSpeed;
-    private timeBgRot;
+    private envType;
+    private envMaps;
+    private envText;
+    private bgdText;
     private callback;
+    private frameWaiters;
+    private timeBgdRot;
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: init */
+    private applyBgds;
     private applyEnv;
+    private disposePrevBgd;
+    private disposeText;
     /**
-     * Enables the environment system. Loads an environment texture and applies it to `THREE.Scene.environment` and `THREE.Scene.background`.
-
+     * Enables environment and background handling.
+     * The first map is applied to `THREE.Scene.environment` and `THREE.Scene.background`; additional maps load in order and replace only `THREE.Scene.background`.
+     * WebGL uses a PMREM-processed texture for `THREE.Scene.environment` and the loaded texture for `THREE.Scene.background`.
      * @param params - Optional environment loading parameters. If provided, both `type` and `map` are required.
-     * @param params.type - Environment map type. Defaults to `cfg.envCtrls.type`.
-     * @param params.map - Environment map path or URL. Defaults to `cfg.envCtrls.map`.
+     * @param params.type - Environment map file type. Defaults to `cfg.envCtrls.type`.
+     * @param params.map - Ordered environment map paths. Defaults to `cfg.envCtrls.map`.
      */
     enable(params?: {
         type: EnvCtrlsCfg["type"];
@@ -976,21 +989,27 @@ export declare class EnvCtrls {
     }): void;
     /** Disables the environment system and resets all values. */
     disable(): void;
-    /** Returns the current environment controls parameters. */
+    /**
+     * Returns the current runtime environment control values.
+     * @returns A snapshot of the mutable runtime settings.
+     */
     get(): Partial<EnvCtrlsCfg>;
     /**
      * Returns whether the environment system is currently enabled.
      * @returns `true` if `EnvCtrls` is currently enabled, otherwise `false`.
      */
     isEnabled(): boolean;
-    private loadTexture;
+    private loadText;
     /**
-     * Sets one or multiple environment control parameters at runtime.
-     * @param params - Object containing any subset of environment control parameters.
+     * Updates supported environment control values at runtime.
+     * @param params - Runtime values to update: rotation speed, intensities, background blurriness or rotation.
      */
     set(params: Partial<EnvCtrlsCfg>): void;
     private setEnv;
+    private setBgd;
     private startEnv;
+    private waitFrames;
+    private resolveFrameWaiters;
     private update;
 }
 
@@ -1030,10 +1049,12 @@ export declare interface EnvCtrlsCfg {
      */
     load: boolean;
     /**
-     * Path to the environment map.
-     * @default ''
+     * Ordered paths to the environment map.
+     * The first map is used for `THREE.Scene.environment` and `THREE.Scene.background`.
+     * Additional maps are loaded sequentially and replace only `THREE.Scene.background`.
+     * @default []
      */
-    map: string;
+    map: string[];
     /**
      * Environment and background rotation values in degrees.
      * @default { x: 0, y: 0, z: 0 }
@@ -1277,7 +1298,7 @@ export declare interface GuiCfg {
     inspector: {
         /**
          * Activates the inspector for runtime property control via lazy loading.
-         * @default true
+         * @default false
          */
         enable: boolean;
     };
@@ -1319,9 +1340,9 @@ export declare interface HemisphereCfg {
 export declare interface InfoBoxCfg {
     /**
      * Enables or disables infobox data collection.
-     * @default true
+     * @default false
      */
-    enabled: boolean;
+    enable: boolean;
     /**
      * Shows the FPS value.
      * @default true
@@ -1453,7 +1474,7 @@ export declare interface MenuBarCfg {
     enable: boolean;
     /**
      * Background color of the menu bar.
-     * @default '#F40B5780'
+     * @default '#ffffff29'
      */
     backgroundColor: THREE_TYPE.ColorRepresentation;
     /**
@@ -1518,7 +1539,7 @@ export declare interface MeshCfg {
  * @category Cfg
  */
 export declare interface ModelCfg {
-    compression: {
+    compress: {
         /**
          * Mesh compression used by the GLTF/GLB file.
          * @default 'none'