illutions 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.35.0
+
+### Added
+
+- Added the extensible `Clip` class and `assets.clips` registration as a class or `{ class, params }`, with typed instances under `app.clip`. `ClipParams` accepts `name`, `modeLoop`, `modeBlend`, `reverse`, `cam`, and `layer`; the model animation name defaults to the registration key and is matched without regard to case. Instances expose the assigned animation through `obj`, playback controls, persistent event listeners, and `onReady()` before `Scene_Ready`. Exported registration types are `ClipClass`, `ClipEntry`, `ClipInsts`, and `ClipsInsts`.
+- Added `Clips` through `app.clips`, with `start()`, `change()`, `pause()`, `resume()`, and `stop()` for loaded model animations selected by `clip` name without asset registration. Playback supports layers, camera following, loop and blend modes, reverse playback, and crossfades. `ClipTween` defines weight and speed transitions; `ClipMarker` defines timeline markers. `start()` restarts playback, `change()` preserves the current position and markers, and finite clips hold their final pose.
+- Added the extensible `Sound` class and `assets.sounds` registration as a class or `{ class, params }`, with typed instances under `app.sound`. Basic registration parameters are `url`, `parent`, `volume`, and `loop`; the sound name is always the registration key. Instances provide loading, playback, status checks, and persistent event listeners. `obj` is null until loading completes; `onReady()` runs before `Audio_Loaded`. Registration does not load or start sounds. Exported types are `SoundClass`, `SoundEntry`, `SoundInsts`, `SoundsInsts`, and `SoundInstParams`.
+- Added `Audio.change({ name, volume?, speed?, loop?, fade? })`, per-sound `Audio.resume({ name, fadeIn? })`, and `SoundTween` for volume and speed transitions. Changing a paused sound resumes it; changing a stopped or finished sound does not restart it.
+- Added `Clip_Stop`, `Clip_Pause`, `Clip_Resume`, `Clip_Loop`, `Clip_Marker`, `Audio_Pause`, and `Audio_Resume` events. `ClipEvent` includes optional `loopCount` and `markerName` fields.
+
+### Renamed
+
+- `Comps` → `Assets`; pass registrations as the second argument to `App.run()` and use `App<typeof assets>`. Scene and Web instances remain under `app.comps.scene` and `app.comps.web`.
+- `Audio.play()` → `Audio.start()` and `Audio.loadAndPlay()` → `Audio.loadAndStart()`. `start()` always starts from the beginning; use per-sound `resume()` to continue paused playback.
+- The former parameterless `Audio.resume()` → `Audio.resumeContext()` for resuming the Web Audio context.
+- `SoundParams.obj` → `SoundParams.parent` for sound attachment in `Audio.load()`, `Audio.loadAndStart()`, and registered sounds.
+- `Audio_Complete` → `Audio_Finished` and `Clip_Complete` → `Clip_Finished`.
+
+### Changed
+
+- Scene registrations accept `Obj3DParams.name` to select a model object independently of the application key, with the key as fallback. Model object names are matched without regard to case; `app.comps.scene` preserves the registration keys. Scene and Web registration keys that differ only in case are rejected.
+- `Cam3D` now adopts only a model camera matching its configured `name` or registration key, instead of adopting any compatible model camera.
+- String targets in `Scene.animCamTo()`, `Scene.animCamCurveTo()`, and `Coll3DParams.target` now resolve registered Scene Components by key without regard to case. Component references and the curve method's `Vector3` targets remain supported.
+- `Scene.animRotTo()`, `animScaleTo()`, `animTranslTo()`, `animMaterialsTo()`, and `setMaterialsProps()` now accept only exact Three.js object names through `obj`, including case. Use the corresponding `Obj3D` or `Mesh3D` instance methods when working with component references.
+- `Web` accepts an optional scene registration type through `Web<typeof assets.scene>` and exposes typed instances through `this.comps.scene` using the original Assets keys. `Web.objs3D` is replaced by this access; `Web.follow()` now accepts only an `Obj3D` instance. Use component references from `onReady()` onward.
+- Transformation events now report the actual Three.js object name in `objName`, including velocity and camera animation events. `Obj3D.name` is no longer part of the supported subclass API; use `this.obj.name` for the assigned object's name.
+- `Audio.pause()` now accepts `{ name, fadeOut?: SoundTween }` instead of `{ name, time?, ease? }`. Transition durations default to zero. `Audio.start()`, `loadAndStart()`, and `stop()` retain `time` and `ease`.
+- Sound looping now defaults to `false` instead of `true`. Set `loop: true` explicitly for repeating sounds.
+
+### Removed
+
+- Removed `Scene.playClip()`, `Scene.playClipCam()`, and `Scene.stopClip()`; use `app.clips` or registered `app.clip` instances. Removed `ActionFadeMode`, `FinishMode`, `StopMode`, and `Clip_Cancel`.
+- Removed `Audio.setSoundParams()`; use `Audio.change()` for volume, speed, and loop. Supply per-sound spatial settings when loading; shared positional defaults remain available through `Audio.set()` and `Audio.get()`.
+
+## 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