illutions 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.32.0
+
+### Added
+
+- Added `Scene.animTransformTo({ obj, pos?, rot?, scale?, duration?, ease? })` for local transformations with rotation in degrees; new calls replace the previous transformation of the same object.
+- Added `Audio.pause({ name, fade?, ease? })` to pause a sound while preserving its playback position; `Audio.play()` resumes it, while `Audio.stop()` resets playing or paused sounds to the beginning.
+- Added the exported `AudioEvent` with `Audio_Start`, `Audio_Complete`, and `Audio_Stop`, each carrying `soundName`; completion indicates a natural playback end, and stopping emits its event immediately or after fade-out finishes.
+- Added the exported `SoundParamsPos` and optional per-sound distance attenuation and directional cone overrides in `SoundParams`; omitted settings inherit the shared audio defaults.
+- Added `Audio.setSoundParams()` to update a loaded sound's volume and positional overrides; volume changes during a fade are stored for subsequent playback without interrupting the fade.
+
+### Renamed
+
+- `cfg.audio.delayPlaySound` → `cfg.audio.delayLoadSound`
+- `SoundParams.object` → `SoundParams.obj`
+- `Audio.setListener({ object })` → `Audio.setListener({ obj })`
+
+### Changed
+
+- Added `Anim_Cancel` to `AnimEvent` for transformations replaced by `Scene.animTransformTo()`.
+- Merged `AudioLoadedEvent` into `AudioEvent`, which now also includes `Audio_Loaded`; removed the separate `AudioLoadedEvent` interface.
+- Extended `SoundParams.obj` to accept a scene object name or an `Obj3D` instance; an empty string still selects global audio. Positional settings are rejected for global sounds during loading and ignored when updating them.
+- Removed `fade` from `SoundParams` and `Audio.load()`; `Audio.loadAndPlay()`, `Audio.play()`, and `Audio.stop()` now accept per-call `fade` and GSAP `ease` options. Fades default to `0` (no fade), with linear easing (`'none'`), instead of a stored two-second fade.
+- Changed `Audio.get()` to return `SoundParamsPos` and `Audio.set()` to accept `Partial<SoundParamsPos>`; loading delay is no longer exposed through these methods, and shared default updates preserve per-sound overrides.
+
+### Fixed
+
+- Fixed `Audio.play()` and `Audio.resume()` to resume interrupted audio contexts in addition to suspended contexts.
+
 ## 0.31.0
 
 ### Added
@@ -33,8 +61,8 @@
 - `Obj3DInsts` → `SceneInsts`
 - `Comp.comps` → `Web.webs`
 
-### Changed
-
+### Changed
+
 - Replaced the `objs3D` and `comps` registry groups with `comps.scene` and `comps.web`; initialized instances are now exposed through `app.comps.scene` and `app.comps.web`.
 - Changed `Raycast.setColliders()` and `Raycast.clearColliders()` to accept arrays of registered `Coll3D` instances and use or reset their persistent collider roles; removed the exported `Collider` interface.
 - Replaced the individual post-processing enable settings with typed `cfg.render.profile.webgl` and `cfg.render.profile.webgpu` settings for MSAA, AA, SSL, and SSR.
@@ -49,8 +77,8 @@
 
 ## 0.30.0
 
-### Changed
-
+### 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.
 
@@ -82,8 +110,8 @@
 - 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
-
+### 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`.
@@ -104,8 +132,8 @@
 
 - Added progressive model loading through ordered model levels in `ModelCfg.file`.
 
-### Changed
-
+### 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`.
@@ -122,8 +150,8 @@
 - Added `Comp.trackOverlap()` and `Comp.untrackOverlap()` to manage component overlaps in screen space through the internal `CompCtrls`.
 - Added `cfg.light.rectArea` to lazily load and initialize renderer-specific LTC data for `RectAreaLight` support.
 
-### Changed
-
+### Changed
+
 - Moved the shared SSR settings `maxDistance`, `thickness`, and `resolutionScale` from `cfg.post.webgl.ssr` and `cfg.post.webgpu.ssr` to `cfg.post.ssr`.
 - Renamed the public `Raycast.trackSelectables()` and `Raycast.untrackSelectable()` methods to `Raycast.trackPickables()` and `Raycast.untrackPickables()`.
 
@@ -149,8 +177,8 @@
 
 - Added the `ProgressBar_Hidden` event.
 
-### Changed
-
+### Changed
+
 - Renamed the `aaCfg` interface to `AaCfg`.
 
 ### Fixed
@@ -166,8 +194,8 @@
 - Added `Audio.load()` to load audio without starting playback.
 - Added the `AudioLoadedEvent` (`Audio_Loaded`) event for handling completed audio loading.
 
-### Changed
-
+### Changed
+
 - Replaced `pauseActions` with `stopMode` and `infinite` with `loop` in animation clip playback.
 - Renamed `Raycast.trackSelectable()` to `Raycast.trackSelectables()`.
 - Changed the `LightCfg` shadow defaults to match the corresponding Three.js defaults, while keeping `castShadow` enabled by default.
@@ -202,14 +230,14 @@
 - Added `render.api` output to the infobox.
 - Added `.blend` source files to the public example apps.
 
-### Changed
-
+### Changed
+
 - Renamed `cfg.webgl` and `cfg.webgpu` parameter groups to `params`.
 
 ## 0.22.0
 
-### Changed
-
+### 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.
@@ -222,12 +250,12 @@
 
 ## 0.21.9
 
-### Changed
-
+### 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
-
+### Changed
+
 - Added `cfg.audio.enable` to the configuration.

package/dist/main.d.ts

@@ -50,9 +50,9 @@ export declare interface AmbientlightCfg {
     intensity: number;
 }
 
-/** @event Fired when an object or material color animation starts or completes. */
+/** @event Fired when an object or material color animation starts, completes, or is canceled. */
 export declare interface AnimEvent {
-    type: 'Anim_Complete' | 'Anim_Start';
+    type: 'Anim_Complete' | 'Anim_Start' | 'Anim_Cancel';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
     /** The name of the calling method. */
@@ -90,7 +90,6 @@ export declare class App<TComps extends Comps = {}> {
     readonly stateMachine: StateMachine;
     private readonly webCtrls;
     private cam3D;
-    private readonly inspector;
     readonly comps: CompsInsts<TComps>;
     private objs3DMap;
     private websMap;
@@ -114,17 +113,18 @@ export declare class App<TComps extends Comps = {}> {
  */
 declare class Audio_2 {
     private readonly ctx;
+    private listener;
     private readonly loader;
-    private readonly scene;
     private readonly events;
-    private readonly loadedSounds;
     private readonly params;
-    private listener;
+    private readonly scene;
+    private readonly sounds;
     private attachSoundTo;
+    private fadeSound;
     /**
-     * Returns a snapshot of playback timing and positional audio settings.
+     * Returns the shared positional sound defaults.
      */
-    get(): Partial<AudioCfg>;
+    get(): SoundParamsPos;
     /**
      * Checks whether a named sound is loaded.
      * @param params - Sound selection.
@@ -146,52 +146,84 @@ declare class Audio_2 {
      * 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;
+    load(params: 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.
      * @param params - The sound options.
+     * @param params.fade - Fade-in duration for this start in seconds. Defaults to 0 (no fade).
+     * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
      */
-    loadAndPlay({ name, url, object, volume, fade, loop }: SoundParams): void;
+    loadAndPlay({ fade, ease, ...params }: {
+        fade?: number;
+        ease?: string;
+    } & SoundParams): void;
     /**
-     * Plays a loaded sound with a volume fade-in.
+     * Plays or resumes a loaded sound, optionally fading in from zero.
      * 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 - Sound selection.
      * @param params.name - Loaded sound name.
+     * @param params.fade - Fade-in duration in seconds. Defaults to 0 (no fade).
+     * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
+     */
+    play({ name, fade, ease }: {
+        name: string;
+        fade?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Pauses a playing sound and keeps its position for the next play().
+     * @param params - Sound selection and optional fade-out settings.
+     * @param params.name - Sound name.
+     * @param params.fade - Fade-out duration in seconds. Defaults to 0 (no fade).
+     * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
      */
-    play({ name }: {
+    pause({ name, fade, ease }: {
         name: string;
+        fade?: number;
+        ease?: string;
     }): void;
     /**
      * Resumes the Web Audio context after a user gesture.
      */
     resume(): void;
-    private setAttribute;
+    /**
+     * Updates shared positional defaults without replacing individual sound overrides.
+     * @param params - Positional defaults to update; omitted values remain unchanged.
+     */
+    set(params: Partial<SoundParamsPos>): void;
     private setAudioContext;
     /**
      * Attaches an audio listener to a scene object or camera. Set a listener before loading sounds.
      *
      * @param params - Listener target.
-     * @param params.object - Scene object name or camera to attach the listener to.
+     * @param params.obj - Scene object name or camera to attach the listener to.
      */
-    setListener({ object }: {
-        object: string | Cam3D;
+    setListener({ obj }: {
+        obj: string | Cam3D;
     }): void;
-    private setAllPositionalSoundsCfg;
-    private setPositionalSoundCfg;
     /**
-     * Updates one or more audio parameters at runtime.
-     * @param params - Audio parameters to update.
+     * Updates the volume and positional overrides of a loaded sound immediately.
+     * Volume is stored during a fade without interrupting it.
+     * @param params - Sound name and settings to change; omitted settings remain unchanged.
      */
-    set(params: Partial<AudioCfg>): void;
+    setSoundParams({ name, volume, ...positional }: {
+        name: string;
+        volume?: number;
+    } & Partial<SoundParamsPos>): void;
+    private setSoundParamsPos;
     /**
-     * Fades out a playing sound and stops it.
+     * Stops a playing or paused sound and resets its position, optionally fading out.
      * @param params - Sound selection.
      * @param params.name - Sound name.
+     * @param params.fade - Fade-out duration in seconds. Defaults to 0 (no fade).
+     * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
      */
-    stop({ name }: {
+    stop({ name, fade, ease }: {
         name: string;
+        fade?: number;
+        ease?: string;
     }): void;
     /**
      * Runs an extension callback immediately with access to the public API.
@@ -205,7 +237,7 @@ export { Audio_2 as Audio }
  * Controls playback timing and how positional sound fades with distance.
  * @category Cfg
  */
-export declare interface AudioCfg {
+export declare interface AudioCfg extends SoundParamsPos {
     /**
      * Whether audio support is initialized when the application starts.
      * @default false
@@ -220,48 +252,13 @@ export declare interface AudioCfg {
      * Delay in milliseconds before loading audio for automatic playback.
      * @default 200
      */
-    delayPlaySound: number;
-    /**
-     * The reference distance after which the attenuation begins.
-     * @default 1
-     */
-    refDistance: number;
-    /**
-     * Determines how quickly the volume falls off with distance.
-     * @default 1
-     */
-    rolloffFactor: number;
-    /**
-     * Distance beyond which linear attenuation stops reducing volume.
-     * @default 1000
-     */
-    maxDistance: number;
-    /**
-     * The distance attenuation model used.
-     * @default 'inverse'
-     */
-    distanceModel: 'linear' | 'inverse' | 'exponential';
-    /**
-     * Inner cone angle in degrees, within which sound is not attenuated.
-     * @default 360
-     */
-    coneInnerAngle: number;
-    /**
-     * Outer cone angle in degrees, beyond which `coneOuterGain` applies.
-     * @default 360
-     */
-    coneOuterAngle: number;
-    /**
-     * The gain factor outside the cone.
-     * @default 0
-     */
-    coneOuterGain: number;
+    delayLoadSound: number;
 }
 
-/** @event Fired when an audio file has finished loading and is ready for playback. */
-export declare interface AudioLoadedEvent {
-    type: 'Audio_Loaded';
-    /** The unique name assigned to the loaded sound. */
+/** @event Fired when a sound finishes loading, starts playback, completes naturally, or is stopped. */
+export declare interface AudioEvent {
+    type: 'Audio_Loaded' | 'Audio_Start' | 'Audio_Complete' | 'Audio_Stop';
+    /** The unique name assigned to the sound. */
     soundName: string;
 }
 
@@ -580,9 +577,8 @@ export declare class Engine {
     private rttNode;
     private traaWarmupContext;
     private ecoButtonActive;
-    private gfxChanging;
-    private gfxIndex;
-    private gfxLevels;
+    private gfxLevelChanges;
+    private gfxLevel;
     private gfxMode;
     private readonly gfxPostProfiles;
     private gfxState;
@@ -1565,7 +1561,6 @@ export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
  */
 export declare class OrbitCtrls {
     private readonly cam3D;
-    private readonly canvas;
     private readonly engine;
     private readonly events;
     private readonly modules;
@@ -2070,8 +2065,12 @@ export declare class Scene {
     private readonly cam3D;
     private readonly events;
     private readonly objs3D;
+    private readonly tweens;
     private ambientLight;
     private hemisphereLight;
+    /**
+     * The underlying Three.js scene.
+     */
     readonly obj: THREE_TYPE.Scene;
     /**
      * Moves the camera along a curved path, optionally turning it toward a new target.
@@ -2148,7 +2147,44 @@ export declare class Scene {
         needsUpdate?: boolean;
         [key: string]: any;
     }): void;
-    private calcEaseArea;
+    /**
+     * Animates selected local position, rotation, and scale components from their current values.
+     * @param params - Target object and transformation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @param params.pos - Target local position; omitted axes remain unchanged.
+     * @param params.rot - Target local Euler angles in degrees, using the object's Euler order.
+     * @param params.scale - Target local scale; omitted axes remain unchanged.
+     * @param params.duration - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
+     *
+     * @remarks
+     * Rotation uses quaternion interpolation along the shortest path and does not support full turns.
+     * Omitted rotation axes keep their current target angles, but may change during interpolation.
+     * Cameras switch to free look mode. The caller coordinates other animations and controls.
+     * A new call cancels the entire previous transformation of the same object.
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     */
+    animTransformTo({ obj, pos, rot, scale, duration, ease }: {
+        obj: string | Obj3D;
+        pos?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        rot?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        scale?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        duration?: number;
+        ease?: string;
+    }): void;
+    private getObjectName;
     /**
      * Plays a named animation clip with blending, looping, and speed control.
      *
@@ -2392,21 +2428,76 @@ export declare interface SmaaCfg {
     guiOpened: boolean;
 }
 
-/** Parameters used to load a global or positional audio source. */
-export declare type SoundParams = {
-    /** Unique name used to identify the audio source. */
+/**
+ * Parameters used to load a global or positional audio source.
+ * @category Cfg
+ */
+export declare interface SoundParams extends Partial<SoundParamsPos> {
+    /**
+     * Whether playback should loop.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Unique name used to identify the audio source.
+     */
     name: string;
-    /** Path or URL to the audio file. */
+    /**
+     * Scene object name or Obj3D component for positional audio. Use an empty string for global audio.
+     */
+    obj: string | Obj3D;
+    /**
+     * Path or URL to the audio file.
+     */
     url: string;
-    /** Name of the scene object for positional audio. Use an empty string for global audio. */
-    object: string;
-    /** Target playback volume. Default: `0`. */
+    /**
+     * Target playback volume.
+     * @default 0
+     */
     volume?: number;
-    /** Fade-in duration in seconds. Default: `2`. */
-    fade?: number;
-    /** Whether playback should loop. Default: `true`. */
-    loop?: boolean;
-};
+}
+
+/**
+ * Controls distance attenuation and directional cones for positional sounds.
+ * @category Cfg
+ */
+export declare interface SoundParamsPos {
+    /**
+     * The reference distance after which the attenuation begins.
+     * @default 1
+     */
+    refDistance: number;
+    /**
+     * Determines how quickly the volume falls off with distance.
+     * @default 1
+     */
+    rolloffFactor: number;
+    /**
+     * Distance beyond which linear attenuation stops reducing volume.
+     * @default 1000
+     */
+    maxDistance: number;
+    /**
+     * The distance attenuation model used.
+     * @default 'inverse'
+     */
+    distanceModel: 'linear' | 'inverse' | 'exponential';
+    /**
+     * Inner cone angle in degrees, within which sound is not attenuated.
+     * @default 360
+     */
+    coneInnerAngle: number;
+    /**
+     * Outer cone angle in degrees, beyond which `coneOuterGain` applies.
+     * @default 360
+     */
+    coneOuterAngle: number;
+    /**
+     * The gain factor outside the cone.
+     * @default 0
+     */
+    coneOuterGain: number;
+}
 
 /**
  * Controls contact shading with WebGL SSAO.