illutions 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.34.0
+
+### Added
+
+- Added object-bound `Obj3D.animRotTo()`, `Obj3D.animScaleTo()`, and `Obj3D.animTranslTo()` counterparts to the Scene transformation methods.
+- Added `Obj3D.animVelRotTo()`, `Obj3D.animVelScaleTo()`, and `Obj3D.animVelTranslTo()` with optional `vx`, `vy`, and `vz` targets; omitted axes retain their velocities. Angular velocity uses radians per second and defaults to local space; translation uses coordinate units per second and defaults to parent space; scale velocity is additive in local scale units per second. Defaults are `time: 0` (immediate) and `ease: 'none'` (linear), with `ease` typed as `string`. World-space angular velocity requires uniformly scaled parents. Velocity is applied before `onUpdate()`; `Cam3D.animVelRotTo()` automatically lets angular velocity control camera orientation. Callers coordinate simultaneous transformation and velocity animations affecting the same values.
+- Velocity animations emit `Anim_Start`, `Anim_Complete`, and `Anim_Cancel` when replaced, with the component name in `objName` and the method in `fct`. Completion means the target velocity is reached; motion continues unless the target is zero. Immediate changes emit start and completion synchronously. A new call replaces only the previous animation of the same velocity channel.
+- Exported `CoordinateSpace` with `'parent'`, `'local'`, and `'world'`, plus `degToRad()` and `radToDeg()` through `illutions`.
+
+### Changed
+
+- Replaced `Scene.animTransformTo()` with `Scene.animTranslTo()`, `Scene.animRotTo()`, and `Scene.animScaleTo()`. Each accepts optional `x`, `y`, and `z` targets and has independent duration, easing, and cancellation; a new call cancels only the previous animation of the same transform channel. Defaults are `time: 1` and `ease: 'power2.inOut'`. Rotation uses radians, `path: 'euler'` or `'quat'` (default `'euler'`), and `order: 'XYZ'` by default. Euler interpolation supports full turns; quaternion interpolation follows the shortest orientation path. Rotation and translation support parent/world targets through `space` (default `'parent'`); scale uses local values.
+- Environment rotation and rotation speed now use radians and radians per second in `cfg.envCtrls`, `EnvCtrls.set()`, and `EnvCtrls.get()`. Orbit azimuth and polar limits now use radians in `cfg.orbitCtrls`, `OrbitCtrls.set()`, and `OrbitCtrls.get()`; the default `maxPolarAngle` is `Math.PI` instead of `180`. Convert existing degree values with `degToRad()`. First-Person limits already use radians; camera field of view and audio cone angles remain in degrees, and control speed factors are unchanged.
+- The Inspector displays Orbit and First-Person angle limits and environment rotation in degrees while converting edits to radians. It also provides an environment rotation speed field in degrees per second.
+
 ## 0.33.0
 
 ### Added

package/dist/main.d.ts

@@ -1,6 +1,8 @@
 import { AnyEventObject } from 'xstate';
 import { AnyStateMachine } from 'xstate';
+import { degToRad } from 'three/src/math/MathUtils.js';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { radToDeg } from 'three/src/math/MathUtils.js';
 import { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
 import type * as THREE_TYPE from 'three';
 import type * as THREE_WEBGPU_TYPE from 'three/webgpu';
@@ -284,6 +286,7 @@ export declare class Cam3D extends Obj3D {
     /** Reference to the original target `THREE.Object3D` loaded from the GLTF scene. */
     targetGltf: THREE_TYPE.Object3D | null;
     private readonly tmpVec;
+    animVelRotTo(params: Parameters<Obj3D['animVelRotTo']>[0]): void;
     /**
      * Called when a matching GLTF camera is found. Adopts its projection and world transform when the camera types match.
      * @param objGltf - The GLTF `THREE.Camera` object.
@@ -524,6 +527,9 @@ export declare interface CompsOverlapCfg {
     padding: number;
 }
 
+/** Coordinate space used for transformations. */
+export declare type CoordinateSpace = 'parent' | 'local' | 'world';
+
 /**
  * Controls diagnostic console output.
  * @category Cfg
@@ -547,6 +553,8 @@ declare type DeepPartial<T> = T extends readonly unknown[] ? T : T extends objec
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
+export { degToRad }
+
 /**
  * Renders the scene and controls post-processing and adaptive performance.
  * @category Core
@@ -674,7 +682,7 @@ export declare class EnvCtrls {
     /** Removes environment lighting and background maps, cancels pending updates, and stops rotation. */
     disable(): void;
     /**
-     * Returns a snapshot of environment rotation, intensity, and background blurriness.
+     * Returns a snapshot of environment rotation in radians, rotation speed in radians per second, intensity, and background blurriness.
      */
     get(): Partial<EnvCtrlsCfg>;
     /**
@@ -685,7 +693,7 @@ export declare class EnvCtrls {
     private loadText;
     /**
      * Updates supported environment control values at runtime.
-     * @param params - Runtime values to update: rotation speed, intensities, background blurriness or rotation.
+     * @param params - Runtime values to update: rotation speed in radians per second, intensities, background blurriness or rotation in radians.
      */
     set(params: Partial<EnvCtrlsCfg>): void;
     private setEnv;
@@ -739,7 +747,7 @@ export declare interface EnvCtrlsCfg {
      */
     map: string[];
     /**
-     * Environment and background rotation values in degrees.
+     * Environment and background rotation values in radians.
      * @default { x: 0, y: 0, z: 0 }
      */
     rotation: {
@@ -748,7 +756,7 @@ export declare interface EnvCtrlsCfg {
         z: number;
     };
     /**
-     * Environment and background rotation speed in degrees per second.
+     * Environment and background rotation speed in radians per second.
      * @default 0
      */
     rotationSpeed: number;
@@ -1409,23 +1417,31 @@ export declare class Obj3D {
      * @public
      */
     scene: Scene;
-    private posNdc;
-    private posScreen;
+    private coordTransl;
+    private coordRot;
+    private readonly tweensVel;
+    private readonly posNdc;
+    private readonly posScreen;
     private posScreenLast;
-    private posWorld;
+    private readonly posWorld;
     private posWorldLast;
-    private posCamWorld;
+    private readonly posCamWorld;
     private posWorldOccl;
     private posCamWorldOccl;
-    private quatWorld;
-    private quatWorldLast;
-    private rotWorld;
-    private visible;
+    private readonly orientWorld;
+    private orientWorldLast;
+    private readonly orientAnglesWorld;
+    private readonly velQuat;
+    private readonly velRotAxis;
+    private readonly velRotWorldToParent;
+    private readonly velTranslFrame;
+    private readonly velTranslWorldToParent;
     private inFrustum;
     private inFrustumLast;
-    private visibleLast;
     private occluded;
     private objHidden;
+    private visible;
+    private visibleLast;
     private visibleBeforeHidden;
     /**
      * Subscribes to an object event.
@@ -1436,11 +1452,90 @@ export declare class Obj3D {
     addEventListener<TType extends Obj3DEvent['type']>(type: TType, listener: (event: Extract<Obj3DEvent, {
         type: TType;
     }>) => void): Unsubscribe;
-    private calcFrustumVisibility;
-    private calcPosScreen;
-    private calcPosOccl;
-    private calcRotWorld;
-    private calcVisibility;
+    /**
+     * Animates this object's orientation in radians through {@link Scene.animRotTo}.
+     * @param params - Target orientation and animation settings, without an object parameter.
+     */
+    animRotTo(params: Omit<Parameters<Scene['animRotTo']>[0], 'obj'>): void;
+    /**
+     * Animates this object's scale through {@link Scene.animScaleTo}.
+     * @param params - Target scale and animation settings, without an object parameter.
+     */
+    animScaleTo(params: Omit<Parameters<Scene['animScaleTo']>[0], 'obj'>): void;
+    /**
+     * Animates this object's position through {@link Scene.animTranslTo}.
+     * @param params - Target position and animation settings, without an object parameter.
+     */
+    animTranslTo(params: Omit<Parameters<Scene['animTranslTo']>[0], 'obj'>): void;
+    /**
+     * Animates angular velocity in radians per second. World rotation requires uniformly scaled parents.
+     * @param params - Target angular velocity and animation settings.
+     * @param params.vx - Target velocity around X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity around Y.
+     * @param params.vz - Target velocity around Z.
+     * @param params.space - Coordinate space. Default: **'local'**
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelRotTo({ vx, vy, vz, space, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        space?: CoordinateSpace;
+        time?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Animates additive local scale velocity in scale units per second.
+     * @param params - Target scale velocity and animation settings.
+     * @param params.vx - Target velocity along X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity along Y.
+     * @param params.vz - Target velocity along Z.
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelScaleTo({ vx, vy, vz, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        time?: number;
+        ease?: string;
+    }): void;
+    private animVelTo;
+    /**
+     * Animates translation velocity in coordinate units per second. Parent scaling affects parent and local movement.
+     * @param params - Target translation velocity and animation settings.
+     * @param params.vx - Target velocity along X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity along Y.
+     * @param params.vz - Target velocity along Z.
+     * @param params.space - Coordinate space. Default: **'parent'**
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelTranslTo({ vx, vy, vz, space, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        space?: CoordinateSpace;
+        time?: number;
+        ease?: string;
+    }): void;
+    private checkFrustumVisible;
+    private checkPosOccl;
+    private checkPosScreen;
+    private checkRotWorld;
     /**
      * Returns the object's screen position in canvas coordinates.
      * @param cam3D - Camera used for projection to canvas coordinates.
@@ -1481,6 +1576,7 @@ export declare class Obj3D {
         type: TType;
     }>) => void): void;
     private resetEventState;
+    private updVisible;
 }
 
 /** Object events available to registered listeners. */
@@ -1648,7 +1744,7 @@ export declare interface OrbitCtrlsCfg {
      */
     load: boolean;
     /**
-     * Maximum allowed horizontal orbit angle in degrees.
+     * Maximum allowed horizontal orbit angle in radians.
      * @default Infinity
      */
     maxAzimuthAngle: number;
@@ -1658,12 +1754,12 @@ export declare interface OrbitCtrlsCfg {
      */
     maxDistance: number;
     /**
-     * Maximum allowed vertical orbit angle in degrees.
-     * @default 180
+     * Maximum allowed vertical orbit angle in radians.
+     * @default Math.PI
      */
     maxPolarAngle: number;
     /**
-     * Minimum allowed horizontal orbit angle in degrees.
+     * Minimum allowed horizontal orbit angle in radians.
      * @default -Infinity
      */
     minAzimuthAngle: number;
@@ -1673,7 +1769,7 @@ export declare interface OrbitCtrlsCfg {
      */
     minDistance: number;
     /**
-     * Minimum allowed vertical orbit angle in degrees.
+     * Minimum allowed vertical orbit angle in radians.
      * @default 0
      */
     minPolarAngle: number;
@@ -1743,6 +1839,8 @@ export declare interface ProgressBarHiddenEvent {
     type: 'ProgressBar_Hidden';
 }
 
+export { radToDeg }
+
 /**
  * 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
@@ -2144,44 +2242,83 @@ export declare class Scene {
         [key: string]: any;
     }): void;
     /**
-     * Animates selected local position, rotation, and scale components from their current values.
-     * @param params - Target object and transformation settings.
+     * Animates orientation from its current value using Euler angles in radians.
+     * @param params - Target object, orientation, and animation 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.x - Target X angle in radians; omitted axes keep their starting target angles.
+     * @param params.y - Target Y angle in radians.
+     * @param params.z - Target Z angle in radians.
+     * @param params.path - Rotation interpolation. Default: **'euler'**; **'quat'** takes the shortest orientation path.
+     * @param params.order - Euler order for interpreting angles in both paths. Default: **'XYZ'**
+     * @param params.space - Orientation space. Default: **'parent'**
      * @param params.time - 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.
+     * Euler interpolation supports full turns. Each call starts from the current orientation without retaining previous turns.
+     * Quaternion interpolation takes the shortest path; omitted Euler axes may change during interpolation.
+     * World targets account for moving parents. The caller is responsible for non-uniform parent scaling.
      * 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.
+     * A new call cancels only the previous orientation animation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animTransformTo({ obj, pos, rot, scale, time, ease }: {
+    animRotTo({ obj, x, y, z, path, order, space, time, 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;
-        };
+        x?: number;
+        y?: number;
+        z?: number;
+        path?: 'euler' | 'quat';
+        order?: THREE_TYPE.EulerOrder;
+        space?: 'parent' | 'world';
+        time?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Animates selected local scale axes from their current values.
+     * @param params - Target object, scale, and animation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @param params.x - Target X scale; omitted axes remain unchanged.
+     * @param params.y - Target Y scale.
+     * @param params.z - Target Z scale.
+     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
+     * @remarks
+     * A new call cancels only the previous scale animation of the same object.
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     */
+    animScaleTo({ obj, x, y, z, time, ease }: {
+        obj: string | Obj3D;
+        x?: number;
+        y?: number;
+        z?: number;
+        time?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Animates selected position axes from their current values in parent or world space.
+     * @param params - Target object, position, and animation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @param params.x - Target X position; omitted axes keep their starting values.
+     * @param params.y - Target Y position.
+     * @param params.z - Target Z position.
+     * @param params.space - Position space. Default: **'parent'**
+     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
+     * @remarks
+     * World targets account for moving parents. Cameras switch to free look mode.
+     * A new call cancels only the previous position animation of the same object.
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     */
+    animTranslTo({ obj, x, y, z, space, time, ease }: {
+        obj: string | Obj3D;
+        x?: number;
+        y?: number;
+        z?: number;
+        space?: 'parent' | 'world';
         time?: number;
         ease?: string;
     }): void;
     private getMtrls;
-    private getObjectName;
+    private getObj;
     /**
      * Plays a named animation clip with blending, looping, and speed control.
      *