illutions 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # 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