@needle-tools/engine 5.1.0-canary.3d7c58a → 5.1.0-canary.40da791

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/SKILL.md +4 -1
  3. package/components.needle.json +1 -1
  4. package/dist/{needle-engine.bundle-D6w6CUmG.js → needle-engine.bundle-Cu2B9CsR.js} +19366 -18579
  5. package/dist/needle-engine.bundle-ZoVUaB89.umd.cjs +1733 -0
  6. package/dist/needle-engine.bundle-hBWUJPxm.min.js +1733 -0
  7. package/dist/needle-engine.d.ts +1481 -350
  8. package/dist/needle-engine.js +558 -556
  9. package/dist/needle-engine.min.js +1 -1
  10. package/dist/needle-engine.umd.cjs +1 -1
  11. package/dist/three.js +1 -0
  12. package/dist/three.min.js +21 -21
  13. package/dist/three.umd.cjs +16 -16
  14. package/lib/engine/api.d.ts +7 -0
  15. package/lib/engine/api.js +6 -0
  16. package/lib/engine/api.js.map +1 -1
  17. package/lib/engine/codegen/register_types.js +10 -18
  18. package/lib/engine/codegen/register_types.js.map +1 -1
  19. package/lib/engine/engine_audio.d.ts +68 -0
  20. package/lib/engine/engine_audio.js +172 -0
  21. package/lib/engine/engine_audio.js.map +1 -1
  22. package/lib/engine/engine_camera.fit.js +16 -4
  23. package/lib/engine/engine_camera.fit.js.map +1 -1
  24. package/lib/engine/engine_components.js +1 -1
  25. package/lib/engine/engine_components.js.map +1 -1
  26. package/lib/engine/engine_context.d.ts +21 -8
  27. package/lib/engine/engine_context.js +32 -16
  28. package/lib/engine/engine_context.js.map +1 -1
  29. package/lib/engine/engine_context_eventbus.d.ts +47 -0
  30. package/lib/engine/engine_context_eventbus.js +47 -0
  31. package/lib/engine/engine_context_eventbus.js.map +1 -0
  32. package/lib/engine/engine_disposable.d.ts +172 -0
  33. package/lib/engine/engine_disposable.js +136 -0
  34. package/lib/engine/engine_disposable.js.map +1 -0
  35. package/lib/engine/engine_gameobject.d.ts +1 -10
  36. package/lib/engine/engine_gameobject.js +22 -120
  37. package/lib/engine/engine_gameobject.js.map +1 -1
  38. package/lib/engine/engine_gltf_builtin_components.js +7 -69
  39. package/lib/engine/engine_gltf_builtin_components.js.map +1 -1
  40. package/lib/engine/engine_init.js +6 -6
  41. package/lib/engine/engine_init.js.map +1 -1
  42. package/lib/engine/engine_input.d.ts +24 -5
  43. package/lib/engine/engine_input.js +3 -2
  44. package/lib/engine/engine_input.js.map +1 -1
  45. package/lib/engine/engine_instantiate_resolve.d.ts +42 -0
  46. package/lib/engine/engine_instantiate_resolve.js +372 -0
  47. package/lib/engine/engine_instantiate_resolve.js.map +1 -0
  48. package/lib/engine/engine_license.js +1 -1
  49. package/lib/engine/engine_license.js.map +1 -1
  50. package/lib/engine/engine_mainloop_utils.js +7 -4
  51. package/lib/engine/engine_mainloop_utils.js.map +1 -1
  52. package/lib/engine/engine_networking.d.ts +51 -37
  53. package/lib/engine/engine_networking.js +132 -82
  54. package/lib/engine/engine_networking.js.map +1 -1
  55. package/lib/engine/engine_networking.transport.websocket.d.ts +15 -0
  56. package/lib/engine/engine_networking.transport.websocket.js +38 -0
  57. package/lib/engine/engine_networking.transport.websocket.js.map +1 -0
  58. package/lib/engine/engine_networking_blob.js +1 -1
  59. package/lib/engine/engine_networking_blob.js.map +1 -1
  60. package/lib/engine/engine_networking_instantiate.js +2 -2
  61. package/lib/engine/engine_networking_instantiate.js.map +1 -1
  62. package/lib/engine/engine_networking_types.d.ts +39 -1
  63. package/lib/engine/engine_networking_types.js +7 -0
  64. package/lib/engine/engine_networking_types.js.map +1 -1
  65. package/lib/engine/engine_physics_rapier.d.ts +21 -3
  66. package/lib/engine/engine_physics_rapier.js +94 -25
  67. package/lib/engine/engine_physics_rapier.js.map +1 -1
  68. package/lib/engine/engine_scenedata.js +2 -2
  69. package/lib/engine/engine_scenedata.js.map +1 -1
  70. package/lib/engine/engine_serialization_builtin_serializer.js +28 -5
  71. package/lib/engine/engine_serialization_builtin_serializer.js.map +1 -1
  72. package/lib/engine/engine_serialization_core.d.ts +1 -0
  73. package/lib/engine/engine_serialization_core.js +7 -0
  74. package/lib/engine/engine_serialization_core.js.map +1 -1
  75. package/lib/engine/engine_types.d.ts +29 -11
  76. package/lib/engine/engine_types.js +1 -1
  77. package/lib/engine/engine_types.js.map +1 -1
  78. package/lib/engine/engine_util_decorator.js +7 -2
  79. package/lib/engine/engine_util_decorator.js.map +1 -1
  80. package/lib/engine/engine_utils.d.ts +1 -1
  81. package/lib/engine/engine_utils.js +19 -5
  82. package/lib/engine/engine_utils.js.map +1 -1
  83. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  84. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js.map +1 -1
  85. package/lib/engine/webcomponents/needle menu/needle-menu.d.ts +1 -1
  86. package/lib/engine/webcomponents/needle menu/needle-menu.js +1 -1
  87. package/lib/engine/webcomponents/needle menu/needle-menu.js.map +1 -1
  88. package/lib/engine/webcomponents/needle-engine.d.ts +10 -4
  89. package/lib/engine/webcomponents/needle-engine.js +1 -1
  90. package/lib/engine/webcomponents/needle-engine.js.map +1 -1
  91. package/lib/engine/xr/NeedleXRSession.d.ts +3 -2
  92. package/lib/engine/xr/NeedleXRSession.js +50 -14
  93. package/lib/engine/xr/NeedleXRSession.js.map +1 -1
  94. package/lib/engine/xr/events.d.ts +1 -1
  95. package/lib/engine/xr/events.js.map +1 -1
  96. package/lib/engine-components/Animation.js +17 -16
  97. package/lib/engine-components/Animation.js.map +1 -1
  98. package/lib/engine-components/AnimationBuilder.d.ts +158 -0
  99. package/lib/engine-components/AnimationBuilder.js +305 -0
  100. package/lib/engine-components/AnimationBuilder.js.map +1 -0
  101. package/lib/engine-components/Animator.d.ts +6 -0
  102. package/lib/engine-components/Animator.js +23 -13
  103. package/lib/engine-components/Animator.js.map +1 -1
  104. package/lib/engine-components/AnimatorController.builder.d.ts +191 -0
  105. package/lib/engine-components/AnimatorController.builder.js +263 -0
  106. package/lib/engine-components/AnimatorController.builder.js.map +1 -0
  107. package/lib/engine-components/AnimatorController.d.ts +2 -119
  108. package/lib/engine-components/AnimatorController.js +33 -232
  109. package/lib/engine-components/AnimatorController.js.map +1 -1
  110. package/lib/engine-components/AudioSource.d.ts +19 -3
  111. package/lib/engine-components/AudioSource.js +121 -68
  112. package/lib/engine-components/AudioSource.js.map +1 -1
  113. package/lib/engine-components/Collider.d.ts +18 -9
  114. package/lib/engine-components/Collider.js +61 -14
  115. package/lib/engine-components/Collider.js.map +1 -1
  116. package/lib/engine-components/Component.d.ts +72 -9
  117. package/lib/engine-components/Component.js +114 -10
  118. package/lib/engine-components/Component.js.map +1 -1
  119. package/lib/engine-components/ContactShadows.d.ts +1 -0
  120. package/lib/engine-components/ContactShadows.js +14 -1
  121. package/lib/engine-components/ContactShadows.js.map +1 -1
  122. package/lib/engine-components/DragControls.d.ts +7 -0
  123. package/lib/engine-components/DragControls.js +19 -7
  124. package/lib/engine-components/DragControls.js.map +1 -1
  125. package/lib/engine-components/DropListener.js +3 -0
  126. package/lib/engine-components/DropListener.js.map +1 -1
  127. package/lib/engine-components/EventList.d.ts +31 -9
  128. package/lib/engine-components/EventList.js +37 -76
  129. package/lib/engine-components/EventList.js.map +1 -1
  130. package/lib/engine-components/Joints.d.ts +4 -2
  131. package/lib/engine-components/Joints.js +19 -3
  132. package/lib/engine-components/Joints.js.map +1 -1
  133. package/lib/engine-components/Light.js +9 -1
  134. package/lib/engine-components/Light.js.map +1 -1
  135. package/lib/engine-components/Networking.d.ts +1 -1
  136. package/lib/engine-components/Networking.js +1 -1
  137. package/lib/engine-components/OrbitControls.d.ts +0 -2
  138. package/lib/engine-components/OrbitControls.js +30 -12
  139. package/lib/engine-components/OrbitControls.js.map +1 -1
  140. package/lib/engine-components/RigidBody.d.ts +12 -4
  141. package/lib/engine-components/RigidBody.js +18 -4
  142. package/lib/engine-components/RigidBody.js.map +1 -1
  143. package/lib/engine-components/SceneSwitcher.js +3 -0
  144. package/lib/engine-components/SceneSwitcher.js.map +1 -1
  145. package/lib/engine-components/SeeThrough.js +2 -2
  146. package/lib/engine-components/SeeThrough.js.map +1 -1
  147. package/lib/engine-components/api.d.ts +2 -1
  148. package/lib/engine-components/api.js +2 -1
  149. package/lib/engine-components/api.js.map +1 -1
  150. package/lib/engine-components/codegen/components.d.ts +7 -13
  151. package/lib/engine-components/codegen/components.js +7 -13
  152. package/lib/engine-components/codegen/components.js.map +1 -1
  153. package/lib/engine-components/postprocessing/Effects/Tonemapping.utils.d.ts +1 -1
  154. package/lib/engine-components/timeline/PlayableDirector.d.ts +21 -11
  155. package/lib/engine-components/timeline/PlayableDirector.js +75 -67
  156. package/lib/engine-components/timeline/PlayableDirector.js.map +1 -1
  157. package/lib/engine-components/timeline/SignalAsset.d.ts +3 -1
  158. package/lib/engine-components/timeline/SignalAsset.js +1 -0
  159. package/lib/engine-components/timeline/SignalAsset.js.map +1 -1
  160. package/lib/engine-components/timeline/TimelineBuilder.d.ts +413 -0
  161. package/lib/engine-components/timeline/TimelineBuilder.js +506 -0
  162. package/lib/engine-components/timeline/TimelineBuilder.js.map +1 -0
  163. package/lib/engine-components/timeline/TimelineModels.d.ts +2 -1
  164. package/lib/engine-components/timeline/TimelineModels.js +3 -0
  165. package/lib/engine-components/timeline/TimelineModels.js.map +1 -1
  166. package/lib/engine-components/timeline/TimelineTracks.d.ts +37 -6
  167. package/lib/engine-components/timeline/TimelineTracks.js +92 -26
  168. package/lib/engine-components/timeline/TimelineTracks.js.map +1 -1
  169. package/lib/engine-components/timeline/index.d.ts +2 -1
  170. package/lib/engine-components/timeline/index.js +2 -0
  171. package/lib/engine-components/timeline/index.js.map +1 -1
  172. package/lib/engine-components/ui/Canvas.d.ts +1 -1
  173. package/lib/engine-components/ui/Canvas.js +2 -8
  174. package/lib/engine-components/ui/Canvas.js.map +1 -1
  175. package/lib/engine-components/ui/Text.d.ts +1 -0
  176. package/lib/engine-components/ui/Text.js +10 -7
  177. package/lib/engine-components/ui/Text.js.map +1 -1
  178. package/lib/engine-components/web/CursorFollow.d.ts +0 -1
  179. package/lib/engine-components/web/CursorFollow.js +21 -13
  180. package/lib/engine-components/web/CursorFollow.js.map +1 -1
  181. package/lib/engine-components/webxr/WebXRImageTracking.js +4 -0
  182. package/lib/engine-components/webxr/WebXRImageTracking.js.map +1 -1
  183. package/package.json +2 -83
  184. package/plugins/common/license.js +5 -2
  185. package/plugins/common/worker.js +9 -4
  186. package/plugins/vite/asap.js +17 -8
  187. package/plugins/vite/dependencies.js +29 -10
  188. package/plugins/vite/dependency-watcher.js +2 -2
  189. package/plugins/vite/editor-connection.js +3 -3
  190. package/plugins/vite/license.js +19 -1
  191. package/plugins/vite/local-files-core.js +3 -3
  192. package/plugins/vite/local-files-utils.d.ts +3 -1
  193. package/plugins/vite/local-files-utils.js +29 -5
  194. package/plugins/vite/reload.js +1 -1
  195. package/plugins/vite/server.js +2 -1
  196. package/src/engine/api.ts +10 -0
  197. package/src/engine/codegen/register_types.ts +10 -18
  198. package/src/engine/engine_audio.ts +184 -0
  199. package/src/engine/engine_camera.fit.ts +15 -4
  200. package/src/engine/engine_components.ts +1 -1
  201. package/src/engine/engine_context.ts +34 -18
  202. package/src/engine/engine_context_eventbus.ts +73 -0
  203. package/src/engine/engine_disposable.ts +214 -0
  204. package/src/engine/engine_gameobject.ts +54 -159
  205. package/src/engine/engine_gltf_builtin_components.ts +7 -76
  206. package/src/engine/engine_init.ts +6 -6
  207. package/src/engine/engine_input.ts +28 -7
  208. package/src/engine/engine_instantiate_resolve.ts +407 -0
  209. package/src/engine/engine_license.ts +1 -1
  210. package/src/engine/engine_mainloop_utils.ts +7 -4
  211. package/src/engine/engine_networking.transport.websocket.ts +45 -0
  212. package/src/engine/engine_networking.ts +161 -137
  213. package/src/engine/engine_networking_blob.ts +1 -1
  214. package/src/engine/engine_networking_instantiate.ts +2 -2
  215. package/src/engine/engine_networking_types.ts +41 -1
  216. package/src/engine/engine_physics_rapier.ts +102 -33
  217. package/src/engine/engine_scenedata.ts +3 -3
  218. package/src/engine/engine_serialization_builtin_serializer.ts +32 -9
  219. package/src/engine/engine_serialization_core.ts +9 -0
  220. package/src/engine/engine_types.ts +46 -27
  221. package/src/engine/engine_util_decorator.ts +7 -2
  222. package/src/engine/engine_utils.ts +16 -5
  223. package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  224. package/src/engine/webcomponents/needle menu/needle-menu.ts +1 -1
  225. package/src/engine/webcomponents/needle-engine.ts +10 -4
  226. package/src/engine/xr/NeedleXRSession.ts +48 -13
  227. package/src/engine/xr/events.ts +1 -1
  228. package/src/engine-components/Animation.ts +19 -16
  229. package/src/engine-components/AnimationBuilder.ts +472 -0
  230. package/src/engine-components/Animator.ts +24 -12
  231. package/src/engine-components/AnimatorController.builder.ts +387 -0
  232. package/src/engine-components/AnimatorController.ts +20 -291
  233. package/src/engine-components/AudioSource.ts +130 -79
  234. package/src/engine-components/Collider.ts +66 -18
  235. package/src/engine-components/Component.ts +118 -20
  236. package/src/engine-components/ContactShadows.ts +15 -1
  237. package/src/engine-components/DragControls.ts +18 -11
  238. package/src/engine-components/DropListener.ts +3 -0
  239. package/src/engine-components/EventList.ts +45 -83
  240. package/src/engine-components/Joints.ts +20 -4
  241. package/src/engine-components/Light.ts +10 -2
  242. package/src/engine-components/Networking.ts +1 -1
  243. package/src/engine-components/OrbitControls.ts +34 -14
  244. package/src/engine-components/RigidBody.ts +18 -4
  245. package/src/engine-components/SceneSwitcher.ts +3 -0
  246. package/src/engine-components/SeeThrough.ts +2 -2
  247. package/src/engine-components/api.ts +2 -1
  248. package/src/engine-components/codegen/components.ts +7 -13
  249. package/src/engine-components/timeline/PlayableDirector.ts +83 -81
  250. package/src/engine-components/timeline/SignalAsset.ts +4 -1
  251. package/src/engine-components/timeline/TimelineBuilder.ts +824 -0
  252. package/src/engine-components/timeline/TimelineModels.ts +5 -1
  253. package/src/engine-components/timeline/TimelineTracks.ts +96 -27
  254. package/src/engine-components/timeline/index.ts +2 -1
  255. package/src/engine-components/ui/Canvas.ts +2 -8
  256. package/src/engine-components/ui/Text.ts +12 -8
  257. package/src/engine-components/web/CursorFollow.ts +21 -14
  258. package/src/engine-components/webxr/WebXRImageTracking.ts +2 -0
  259. package/dist/needle-engine.bundle-Cb806egV.umd.cjs +0 -1732
  260. package/dist/needle-engine.bundle-DyafERqr.min.js +0 -1732
  261. package/lib/engine-components/AvatarLoader.d.ts +0 -80
  262. package/lib/engine-components/AvatarLoader.js +0 -232
  263. package/lib/engine-components/AvatarLoader.js.map +0 -1
  264. package/lib/engine-components/avatar/AvatarBlink_Simple.d.ts +0 -11
  265. package/lib/engine-components/avatar/AvatarBlink_Simple.js +0 -77
  266. package/lib/engine-components/avatar/AvatarBlink_Simple.js.map +0 -1
  267. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.d.ts +0 -14
  268. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js +0 -69
  269. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js.map +0 -1
  270. package/lib/engine-components/avatar/Avatar_Brain_LookAt.d.ts +0 -29
  271. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js +0 -122
  272. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js.map +0 -1
  273. package/lib/engine-components/avatar/Avatar_MouthShapes.d.ts +0 -15
  274. package/lib/engine-components/avatar/Avatar_MouthShapes.js +0 -80
  275. package/lib/engine-components/avatar/Avatar_MouthShapes.js.map +0 -1
  276. package/lib/engine-components/avatar/Avatar_MustacheShake.d.ts +0 -9
  277. package/lib/engine-components/avatar/Avatar_MustacheShake.js +0 -30
  278. package/lib/engine-components/avatar/Avatar_MustacheShake.js.map +0 -1
  279. package/src/engine-components/AvatarLoader.ts +0 -264
  280. package/src/engine-components/avatar/AvatarBlink_Simple.ts +0 -70
  281. package/src/engine-components/avatar/AvatarEyeLook_Rotation.ts +0 -64
  282. package/src/engine-components/avatar/Avatar_Brain_LookAt.ts +0 -140
  283. package/src/engine-components/avatar/Avatar_MouthShapes.ts +0 -84
  284. package/src/engine-components/avatar/Avatar_MustacheShake.ts +0 -32
@@ -40,11 +40,13 @@ import { GLTFLoader } from '../../../node_modules/@types/three/examples/jsm/load
40
40
  import { GLTFLoaderPlugin } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
41
41
  import { GLTFParser } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
42
42
  import { Group } from 'three';
43
+ import { ImpulseJoint } from '@dimforge/rapier3d-compat';
43
44
  import { InstancedMesh } from 'three';
44
45
  import { Intersection } from 'three';
45
46
  import { IParticleSystem as IParticleSystem_2 } from 'three.quarks';
46
47
  import { KeyframeTrack } from 'three';
47
48
  import { Layers } from 'three';
49
+ import { Light as Light_2 } from 'three';
48
50
  import { LightProbe } from 'three';
49
51
  import { Line2 } from '../../../../node_modules/@types/three/examples/jsm/lines/Line2.js';
50
52
  import { Loader } from 'three';
@@ -254,6 +256,31 @@ export declare class ActionModel implements IBehaviorElement {
254
256
  writeTo(document: USDDocument, writer: USDWriter): void;
255
257
  }
256
258
 
259
+ /**
260
+ * Options for an activation clip in the timeline builder
261
+ */
262
+ export declare type ActivationClipOptions = {
263
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
264
+ start?: number;
265
+ /** Duration of the clip in seconds (required) */
266
+ duration: number;
267
+ /** Ease-in duration in seconds (default: 0) */
268
+ easeIn?: number;
269
+ /** Ease-out duration in seconds (default: 0) */
270
+ easeOut?: number;
271
+ };
272
+
273
+ /**
274
+ * Builder for activation tracks. Provides `.clip()` for defining activation windows.
275
+ * @category Animation and Sequencing
276
+ */
277
+ export declare interface ActivationTrackBuilder extends TimelineBuilderBase {
278
+ /** Adds an activation clip that shows/hides the bound object */
279
+ clip(options: ActivationClipOptions): ActivationTrackBuilder;
280
+ /** Mutes this track so it is skipped during playback */
281
+ muted(muted?: boolean): ActivationTrackBuilder;
282
+ }
283
+
257
284
  export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";
258
285
 
259
286
  /**
@@ -487,6 +514,62 @@ declare class Animation_2 extends Component implements IAnimationComponent {
487
514
  }
488
515
  export { Animation_2 as Animation }
489
516
 
517
+ /**
518
+ * A fluent builder for creating `AnimationClip` instances from code.
519
+ *
520
+ * Use {@link AnimationBuilder.create} to start a new builder, chain `.track()` calls
521
+ * to add animation tracks, and call `.build()` to produce the clip.
522
+ *
523
+ * @example Single track
524
+ * ```ts
525
+ * const clip = AnimationBuilder.create()
526
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
527
+ * .build();
528
+ * ```
529
+ *
530
+ * @example Multiple tracks
531
+ * ```ts
532
+ * const clip = AnimationBuilder.create("DoorOpen")
533
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
534
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
535
+ * .build(room);
536
+ * ```
537
+ *
538
+ * @category Animation and Sequencing
539
+ * @group Utilities
540
+ */
541
+ export declare class AnimationBuilder {
542
+ private _name?;
543
+ private _tracks;
544
+ /** Creates a new AnimationBuilder instance */
545
+ static create(name?: string): AnimationBuilder;
546
+ constructor(name?: string);
547
+ /** Adds an animation track for an Object3D's position or scale */
548
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_2<Vec3Value>, options?: TrackOptions): this;
549
+ /** Adds an animation track for an Object3D's quaternion */
550
+ track(target: Object3D, property: "quaternion", keyframes: KF_2<QuatValue>, options?: TrackOptions): this;
551
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
552
+ track(target: Object3D, property: "rotation", keyframes: KF_2<EulerValue>, options?: TrackOptions): this;
553
+ /** Adds an animation track for an Object3D's visibility */
554
+ track(target: Object3D, property: "visible", keyframes: KF_2<boolean>, options?: TrackOptions): this;
555
+ /** Adds an animation track for a material's numeric property */
556
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_2<number>, options?: TrackOptions): this;
557
+ /** Adds an animation track for a material's color property */
558
+ track(target: Material, property: "color" | "emissive", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
559
+ /** Adds an animation track for a light's numeric property */
560
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_2<number>, options?: TrackOptions): this;
561
+ /** Adds an animation track for a light's color */
562
+ track(target: Light_2, property: "color", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
563
+ /** Adds an animation track for a camera's numeric property */
564
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_2<number>, options?: TrackOptions): this;
565
+ /**
566
+ * Builds and returns the `AnimationClip`.
567
+ * @param root - Optional root Object3D for resolving track paths.
568
+ * When provided, tracks targeting a different object use `target.name` for named resolution.
569
+ */
570
+ build(root?: Object3D): AnimationClip;
571
+ }
572
+
490
573
  /**
491
574
  * @category Animation and Sequencing
492
575
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -500,6 +583,34 @@ export declare type AnimationClipModel = {
500
583
  rotation?: Quat | Quaternion;
501
584
  };
502
585
 
586
+ /**
587
+ * Options for an animation clip in the timeline builder
588
+ */
589
+ export declare type AnimationClipOptions = {
590
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
591
+ start?: number;
592
+ /** Duration of the clip in seconds. Defaults to the animation clip duration. */
593
+ duration?: number;
594
+ /** Playback speed multiplier (default: 1) */
595
+ speed?: number;
596
+ /** Whether the animation should loop within the clip (default: false) */
597
+ loop?: boolean;
598
+ /** Ease-in duration in seconds (default: 0) */
599
+ easeIn?: number;
600
+ /** Ease-out duration in seconds (default: 0) */
601
+ easeOut?: number;
602
+ /** Offset into the source animation clip in seconds (default: 0) */
603
+ clipIn?: number;
604
+ /** Whether to remove the start offset of the animation (default: false) */
605
+ removeStartOffset?: boolean;
606
+ /** Pre-extrapolation mode (default: None) */
607
+ preExtrapolation?: ClipExtrapolation;
608
+ /** Post-extrapolation mode (default: None) */
609
+ postExtrapolation?: ClipExtrapolation;
610
+ /** Play the clip in reverse */
611
+ reversed?: boolean;
612
+ };
613
+
503
614
  /**
504
615
  * AnimationCurve is a representation of a curve that can be used to animate values over time.
505
616
  *
@@ -577,6 +688,19 @@ export declare class AnimationExtension implements IUSDExporterExtension {
577
688
 
578
689
  declare type AnimationIdentifier = AnimationClip | number | string | undefined;
579
690
 
691
+ /** User-friendly interpolation mode names */
692
+ export declare type AnimationInterpolation = "linear" | "smooth" | "step";
693
+
694
+ /** A single keyframe: a time and a value */
695
+ export declare type AnimationKeyframe<V> = {
696
+ /** Time in seconds */
697
+ time: number;
698
+ /** The value at this time */
699
+ value: V;
700
+ /** Interpolation mode for this track (default: `"linear"`). Note: Three.js applies one mode per track; the first keyframe's mode is used. */
701
+ interpolation?: AnimationInterpolation;
702
+ };
703
+
580
704
  /**
581
705
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.
582
706
  * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
@@ -597,43 +721,39 @@ declare class AnimationsRegistry {
597
721
  unregisterAnimationMixer(mixer: AnimationMixer | null | undefined): void;
598
722
  }
599
723
 
600
- export declare class AnimationTrackHandler extends TrackHandler {
601
- /* Excluded from this release type: models */
602
- /* Excluded from this release type: trackOffset */
603
- /** The object that is being animated. */
604
- target?: Object3D;
605
- /** The AnimationMixer, should be shared with the animator if an animator is bound */
606
- mixer?: AnimationMixer;
607
- clips: Array<AnimationClip>;
608
- actions: Array<AnimationAction>;
609
- /**
610
- * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
611
- * @default 1
612
- */
613
- weight: number;
614
- /** holds data/info about clips differences */
615
- private _actionOffsets;
616
- private _didBind;
617
- private _animator;
618
- onDisable(): void;
619
- onDestroy(): void;
620
- onStateChanged(): void;
621
- createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
622
- bind(): void;
623
- private ensureTrackOffsets;
624
- private _useclipOffsets;
625
- private _totalOffsetPosition;
626
- private _totalOffsetRotation;
627
- private _totalOffsetPosition2;
628
- private _totalOffsetRotation2;
629
- private _summedPos;
630
- private _tempPos;
631
- private _summedRot;
632
- private _tempRot;
633
- private _clipRotQuat;
634
- evaluate(time: number): void;
635
- private createRotationInterpolant;
636
- private createPositionInterpolant;
724
+ /**
725
+ * Builder for animation tracks.
726
+ * Provides `.clip()` for pre-built AnimationClips and `.track()` for inline animation definition.
727
+ *
728
+ * @category Animation and Sequencing
729
+ */
730
+ export declare interface AnimationTrackBuilder extends TimelineBuilderBase {
731
+ /** Adds a pre-built AnimationClip */
732
+ clip(asset: AnimationClip, options?: AnimationClipOptions): AnimationTrackBuilder;
733
+ /** Adds a clip from a single {@link TrackDescriptor} */
734
+ clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): AnimationTrackBuilder;
735
+ /** Adds a clip from multiple {@link TrackDescriptor}s */
736
+ clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): AnimationTrackBuilder;
737
+ /** Adds an animation track for an Object3D's position or scale */
738
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): AnimationTrackBuilder;
739
+ /** Adds an animation track for an Object3D's quaternion */
740
+ track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): AnimationTrackBuilder;
741
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
742
+ track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): AnimationTrackBuilder;
743
+ /** Adds an animation track for an Object3D's visibility */
744
+ track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): AnimationTrackBuilder;
745
+ /** Adds an animation track for a material's numeric property */
746
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
747
+ /** Adds an animation track for a material's color property */
748
+ track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
749
+ /** Adds an animation track for a light's numeric property */
750
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
751
+ /** Adds an animation track for a light's color */
752
+ track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
753
+ /** Adds an animation track for a camera's numeric property */
754
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
755
+ /** Mutes this track so it is skipped during playback */
756
+ muted(muted?: boolean): AnimationTrackBuilder;
637
757
  }
638
758
 
639
759
  declare class AnimationTriggers {
@@ -726,6 +846,12 @@ export declare class Animator extends Component implements IAnimationComponent {
726
846
  * Identifies this component as an animation component in the engine
727
847
  */
728
848
  get isAnimationComponent(): boolean;
849
+ /**
850
+ * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
851
+ * @returns The current AnimationMixer, or null if no controller is assigned
852
+ * @see AnimatorController.mixer
853
+ */
854
+ get mixer(): AnimationMixer | null;
729
855
  /**
730
856
  * When enabled, animation will affect the root transform position and rotation
731
857
  */
@@ -1102,13 +1228,6 @@ export declare class AnimatorController {
1102
1228
  * @param animator - The animator to bind this controller to
1103
1229
  */
1104
1230
  bind(animator: Animator): void;
1105
- /**
1106
- * Creates a deep copy of this controller.
1107
- * Clones the model data but does not copy runtime state.
1108
- *
1109
- * @returns A new AnimatorController instance with the same configuration
1110
- */
1111
- clone(): AnimatorController | null;
1112
1231
  /**
1113
1232
  * Updates the controller's state machine and animations.
1114
1233
  * Called each frame by the animator component.
@@ -1151,11 +1270,15 @@ export declare class AnimatorController {
1151
1270
  /**
1152
1271
  * A fluent builder for creating {@link AnimatorController} instances from code.
1153
1272
  *
1154
- * Use {@link AnimatorController.build} to create a new builder.
1273
+ * Use {@link AnimatorControllerBuilder.create} or {@link AnimatorController.build} to create a new builder.
1155
1274
  *
1156
- * @example
1275
+ * The builder tracks state names and parameter types through the fluent chain,
1276
+ * providing autocomplete for state names in `.transition()` and type-aware
1277
+ * `.condition()` calls (e.g., trigger parameters don't require a mode argument).
1278
+ *
1279
+ * @example With pre-built AnimationClips
1157
1280
  * ```ts
1158
- * const controller = AnimatorController.build("CharacterController")
1281
+ * const controller = AnimatorControllerBuilder.create("CharacterController")
1159
1282
  * .floatParameter("Speed", 0)
1160
1283
  * .triggerParameter("Jump")
1161
1284
  * .state("Idle", { clip: idleClip, loop: true })
@@ -1166,36 +1289,70 @@ export declare class AnimatorController {
1166
1289
  * .transition("Walk", "Idle", { duration: 0.25 })
1167
1290
  * .condition("Speed", "less", 0.1)
1168
1291
  * .transition("*", "Jump", { duration: 0.1 })
1169
- * .condition("Jump", "if")
1292
+ * .condition("Jump")
1170
1293
  * .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
1171
1294
  * .build();
1172
1295
  * ```
1173
1296
  *
1297
+ * @example With inline tracks (no pre-built clips needed)
1298
+ * ```ts
1299
+ * const controller = AnimatorControllerBuilder.create("Door")
1300
+ * .boolParameter("Open", false)
1301
+ * .state("Closed", { loop: true })
1302
+ * .track(door, "position", { from: [0, 0, 0], to: [0, 0, 0], duration: 1 })
1303
+ * .state("Open", { loop: true })
1304
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
1305
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
1306
+ * .transition("Closed", "Open", { duration: 0.25 })
1307
+ * .condition("Open", "if")
1308
+ * .transition("Open", "Closed", { duration: 0.25 })
1309
+ * .condition("Open", "ifNot")
1310
+ * .build(room);
1311
+ * ```
1312
+ *
1313
+ * @typeParam TStates - Union of state names added via `.state()`. Used for autocomplete and validation in `.transition()` and `.defaultState()`.
1314
+ * @typeParam TParams - Record mapping parameter names to their types (`"trigger"`, `"bool"`, `"float"`, `"int"`). Used for type-aware `.condition()` overloads.
1315
+ *
1174
1316
  * @category Animation and Sequencing
1175
1317
  * @group Utilities
1176
1318
  */
1177
- export declare class AnimatorControllerBuilder {
1319
+ export declare class AnimatorControllerBuilder<TStates extends string = never, TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {}> {
1178
1320
  private _name;
1179
1321
  private _parameters;
1180
1322
  private _states;
1181
1323
  private _anyStateTransitions;
1182
1324
  private _defaultStateName;
1183
1325
  private _lastTransition;
1326
+ private _lastState;
1327
+ /**
1328
+ * Creates a new AnimatorControllerBuilder instance.
1329
+ * @param name - Optional name for the controller
1330
+ */
1331
+ static create(name?: string): AnimatorControllerBuilder;
1184
1332
  constructor(name?: string);
1185
1333
  /** Adds a float parameter */
1186
- floatParameter(name: string, defaultValue?: number): this;
1334
+ floatParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>;
1187
1335
  /** Adds an integer parameter */
1188
- intParameter(name: string, defaultValue?: number): this;
1336
+ intParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>;
1189
1337
  /** Adds a boolean parameter */
1190
- boolParameter(name: string, defaultValue?: boolean): this;
1338
+ boolParameter<N extends string>(name: N, defaultValue?: boolean): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>;
1191
1339
  /** Adds a trigger parameter */
1192
- triggerParameter(name: string): this;
1340
+ triggerParameter<N extends string>(name: N): AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>;
1193
1341
  /**
1194
1342
  * Adds a state to the controller. The first state added becomes the default state.
1343
+ *
1344
+ * When `options.clip` is provided, the state uses that clip directly.
1345
+ * When omitted, chain `.track()` calls to define animation tracks inline:
1346
+ * ```ts
1347
+ * .state("Open", { loop: true })
1348
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
1349
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
1350
+ * ```
1351
+ *
1195
1352
  * @param name - Unique name for the state
1196
- * @param options - State configuration including clip, loop, speed
1353
+ * @param options - State configuration including clip, loop, speed. When omitted, use `.track()` to add animation data.
1197
1354
  */
1198
- state(name: string, options: StateOptions): this;
1355
+ state<N extends string>(name: N, options?: StateOptions): AnimatorControllerBuilder<TStates | N, TParams>;
1199
1356
  /**
1200
1357
  * Adds a transition between two states.
1201
1358
  * Use `"*"` as the source to create a transition from any state.
@@ -1204,26 +1361,52 @@ export declare class AnimatorControllerBuilder {
1204
1361
  * @param to - Destination state name
1205
1362
  * @param options - Transition configuration
1206
1363
  */
1207
- transition(from: string, to: string, options?: TransitionOptions): this;
1364
+ transition(from: TStates | "*", to: TStates, options?: TransitionOptions): AnimatorControllerBuilder<TStates, TParams>;
1208
1365
  /**
1209
1366
  * Adds a condition to the most recently added transition.
1210
1367
  * Multiple conditions on the same transition are AND-ed together.
1368
+ *
1369
+ * The required arguments depend on the parameter type:
1370
+ * - **Trigger**: `.condition("Jump")` — mode defaults to `"if"`, no threshold needed
1371
+ * - **Bool**: `.condition("Open", "if")` or `.condition("Open", "ifNot")`
1372
+ * - **Float/Int**: `.condition("Speed", "greater", 0.1)`
1373
+ *
1211
1374
  * @param parameter - Name of the parameter to evaluate
1212
- * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
1213
- * @param threshold - Comparison threshold for numeric conditions (default: 0)
1214
1375
  */
1215
- condition(parameter: string, mode: ConditionMode, threshold?: number): this;
1376
+ condition(parameter: ParamNamesOfType<TParams, "trigger">, mode?: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
1377
+ condition(parameter: ParamNamesOfType<TParams, "bool">, mode: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
1378
+ condition(parameter: ParamNamesOfType<TParams, "float" | "int">, mode: "greater" | "less" | "equals" | "notEqual", threshold?: number): AnimatorControllerBuilder<TStates, TParams>;
1379
+ /** Adds an animation track for an Object3D's position or scale to the current state */
1380
+ track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): this;
1381
+ /** Adds an animation track for an Object3D's quaternion to the current state */
1382
+ track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): this;
1383
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) to the current state */
1384
+ track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): this;
1385
+ /** Adds an animation track for an Object3D's visibility to the current state */
1386
+ track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): this;
1387
+ /** Adds an animation track for a material's numeric property to the current state */
1388
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): this;
1389
+ /** Adds an animation track for a material's color property to the current state */
1390
+ track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): this;
1391
+ /** Adds an animation track for a light's numeric property to the current state */
1392
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): this;
1393
+ /** Adds an animation track for a light's color to the current state */
1394
+ track(target: Light_2, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): this;
1395
+ /** Adds an animation track for a camera's numeric property to the current state */
1396
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): this;
1216
1397
  /**
1217
1398
  * Sets which state is the default/entry state.
1218
1399
  * If not called, the first added state is used.
1219
1400
  * @param name - Name of the state
1220
1401
  */
1221
- defaultState(name: string): this;
1402
+ defaultState(name: TStates): AnimatorControllerBuilder<TStates, TParams>;
1222
1403
  /**
1223
1404
  * Builds and returns the {@link AnimatorController}.
1224
1405
  * Resolves all state name references to indices.
1406
+ * @param root - Optional root Object3D for resolving {@link TrackDescriptor} track paths.
1407
+ * When provided, tracks targeting a different object use `target.name` for named resolution.
1225
1408
  */
1226
- build(): AnimatorController;
1409
+ build(root?: Object3D): AnimatorController;
1227
1410
  }
1228
1411
 
1229
1412
  export declare type AnimatorControllerModel = {
@@ -1472,6 +1655,75 @@ export declare class Attractor extends Component {
1472
1655
 
1473
1656
  declare type AttributeChangeCallback = (value: string | null) => void;
1474
1657
 
1658
+ /**
1659
+ * Represents an audio clip that can be loaded and played independently.
1660
+ * The AudioClip class encapsulates the URL of the audio resource and provides
1661
+ * methods for playback control (play, pause, stop) and querying duration.
1662
+ */
1663
+ export declare class AudioClip {
1664
+ readonly url: string;
1665
+ /**
1666
+ * Creates a new AudioClip instance with the specified URL.
1667
+ * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
1668
+ */
1669
+ constructor(url: string);
1670
+ /** Whether the clip is currently playing.
1671
+ * @returns `true` if the clip is actively playing audio.
1672
+ */
1673
+ get isPlaying(): boolean;
1674
+ /**
1675
+ * The total duration of the audio clip in seconds.
1676
+ * Loads the audio metadata if not already available.
1677
+ * @returns A promise that resolves with the duration in seconds.
1678
+ */
1679
+ getDuration(): Promise<number>;
1680
+ /**
1681
+ * Plays the audio clip from the current position.
1682
+ * @returns A promise that resolves when playback finishes, or rejects on error.
1683
+ * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
1684
+ */
1685
+ play(): Promise<void>;
1686
+ /**
1687
+ * Pauses playback at the current position.
1688
+ * Call {@link play} to resume.
1689
+ */
1690
+ pause(): void;
1691
+ /**
1692
+ * Stops playback and resets the position to the beginning.
1693
+ */
1694
+ stop(): void;
1695
+ /** Whether the clip should loop when reaching the end. */
1696
+ get loop(): boolean;
1697
+ set loop(value: boolean);
1698
+ /** Playback volume from 0 (silent) to 1 (full). */
1699
+ get volume(): number;
1700
+ set volume(value: number);
1701
+ /** Current playback position in seconds. */
1702
+ get currentTime(): number;
1703
+ set currentTime(value: number);
1704
+ /** Normalized playback progress from 0 to 1.
1705
+ * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
1706
+ */
1707
+ get progress(): number;
1708
+ /**
1709
+ * Seeks to a normalized position (0–1) in the clip.
1710
+ * @param position A value between 0 (start) and 1 (end).
1711
+ */
1712
+ seek(position: number): void;
1713
+ /** The underlying HTMLAudioElement, or `undefined` if not yet created.
1714
+ * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
1715
+ * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
1716
+ */
1717
+ get audioElement(): HTMLAudioElement | undefined;
1718
+ private _audioElement?;
1719
+ private _duration?;
1720
+ private _loadPromise?;
1721
+ private _loop;
1722
+ private _volume;
1723
+ /** Lazily creates and loads the shared HTMLAudioElement. */
1724
+ private ensureAudioElement;
1725
+ }
1726
+
1475
1727
  /**
1476
1728
  * @category Animation and Sequencing
1477
1729
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -1486,6 +1738,26 @@ declare type AudioClipModel_2 = Models.ClipModel & {
1486
1738
  _didTriggerPlay: boolean;
1487
1739
  };
1488
1740
 
1741
+ /**
1742
+ * Options for an audio clip in the timeline builder
1743
+ */
1744
+ export declare type AudioClipOptions = {
1745
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
1746
+ start?: number;
1747
+ /** Duration of the clip in seconds (required for audio since we can't infer it) */
1748
+ duration: number;
1749
+ /** Playback speed multiplier (default: 1) */
1750
+ speed?: number;
1751
+ /** Volume multiplier for this clip (default: 1) */
1752
+ volume?: number;
1753
+ /** Whether the audio should loop within the clip (default: false) */
1754
+ loop?: boolean;
1755
+ /** Ease-in duration in seconds (default: 0) */
1756
+ easeIn?: number;
1757
+ /** Ease-out duration in seconds (default: 0) */
1758
+ easeOut?: number;
1759
+ };
1760
+
1489
1761
  export declare class AudioExtension implements IUSDExporterExtension {
1490
1762
  static getName(clip: string): string;
1491
1763
  get extensionName(): string;
@@ -1627,9 +1899,10 @@ export declare class AudioSource extends Component {
1627
1899
  */
1628
1900
  get isPlaying(): boolean;
1629
1901
  /**
1630
- * The total duration of the current audio clip in seconds.
1902
+ * The total duration of the currently loaded audio clip in seconds.
1631
1903
  *
1632
1904
  * @returns Duration in seconds or undefined if no clip is loaded
1905
+ * @remarks For MediaStream clips, duration is not directly available and will return undefined. If the audio clip has not started loading or is still loading, duration may also be undefined until the audio buffer is ready.
1633
1906
  */
1634
1907
  get duration(): number | undefined;
1635
1908
  /**
@@ -1654,7 +1927,8 @@ export declare class AudioSource extends Component {
1654
1927
  /**
1655
1928
  * Controls how the audio is positioned in space.
1656
1929
  * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
1657
- * Note: 2D playback is not fully supported in the current implementation.
1930
+ * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
1931
+ * and a non-spatialized (direct) signal path.
1658
1932
  */
1659
1933
  get spatialBlend(): number;
1660
1934
  set spatialBlend(val: number);
@@ -1702,7 +1976,11 @@ export declare class AudioSource extends Component {
1702
1976
  private audioLoader;
1703
1977
  private shouldPlay;
1704
1978
  private _lastClipStartedLoading;
1979
+ private _loadedClip;
1705
1980
  private _audioElement;
1981
+ private _entryNode;
1982
+ private _spatialGain;
1983
+ private _bypassGain;
1706
1984
  /**
1707
1985
  * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
1708
1986
  * The audio source needs a user interaction to be initialized due to browser autoplay policies.
@@ -1730,6 +2008,15 @@ export declare class AudioSource extends Component {
1730
2008
  private onApplicationMuteChanged;
1731
2009
  private createAudio;
1732
2010
  private __onAllowAudioCallback;
2011
+ /**
2012
+ * Sets up the dual-path audio graph for spatial blend crossfading.
2013
+ * Creates two parallel signal paths from source to output:
2014
+ * - 3D path: entry → panner → spatialGain → gain (spatialized)
2015
+ * - 2D path: entry → bypassGain → gain (non-spatialized)
2016
+ */
2017
+ private setupSpatialBlendNodes;
2018
+ /** Updates the spatial/bypass gain values based on the current spatialBlend. */
2019
+ private updateSpatialBlendGains;
1733
2020
  private applySpatialDistanceSettings;
1734
2021
  private onNewClip;
1735
2022
  /**
@@ -1737,8 +2024,9 @@ export declare class AudioSource extends Component {
1737
2024
  * If no argument is provided, plays the currently assigned clip.
1738
2025
  *
1739
2026
  * @param clip - Optional audio clip or {@link MediaStream} to play
2027
+ * @returns A promise that resolves when playback starts successfully, or rejects on error
1740
2028
  */
1741
- play(clip?: string | MediaStream | undefined): void;
2029
+ play(clip?: string | MediaStream | undefined): Promise<boolean>;
1742
2030
  /**
1743
2031
  * Pauses audio playback while maintaining the current position.
1744
2032
  * Use play() to resume from the paused position.
@@ -1755,30 +2043,15 @@ export declare class AudioSource extends Component {
1755
2043
  /* Excluded from this release type: update */
1756
2044
  }
1757
2045
 
1758
- export declare class AudioTrackHandler extends TrackHandler {
1759
- models: Array<AudioClipModel_2>;
1760
- listener: AudioListener_3;
1761
- audio: Array<Audio_2>;
1762
- audioContextTimeOffset: Array<number>;
1763
- lastTime: number;
1764
- audioSource?: AudioSource;
1765
- private _audioLoader;
1766
- private getAudioFilePath;
1767
- onAllowAudioChanged(allow: boolean): void;
1768
- addModel(model: Models.ClipModel): void;
1769
- onDisable(): void;
1770
- onDestroy(): void;
1771
- onMuteChanged(): void;
1772
- stop(): void;
1773
- private _playableDirectorResumed;
1774
- onPauseChanged(): void;
1775
- evaluate(time: number): void;
1776
- /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
1777
- loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
1778
- private isInTimeRange;
1779
- private static _audioBuffers;
1780
- static dispose(): void;
1781
- private handleAudioLoading;
2046
+ /**
2047
+ * Builder for audio tracks. Provides `.clip()` for adding audio clips by URL.
2048
+ * @category Animation and Sequencing
2049
+ */
2050
+ export declare interface AudioTrackBuilder extends TimelineBuilderBase {
2051
+ /** Adds an audio clip by URL */
2052
+ clip(url: string, options: AudioClipOptions): AudioTrackBuilder;
2053
+ /** Mutes this track so it is skipped during playback */
2054
+ muted(muted?: boolean): AudioTrackBuilder;
1782
2055
  }
1783
2056
 
1784
2057
  /* Excluded from this release type: AuralMode */
@@ -1811,69 +2084,6 @@ export declare class Avatar extends Component {
1811
2084
  private loadAvatarObjects;
1812
2085
  }
1813
2086
 
1814
- /* Excluded from this release type: Avatar_Brain_LookAt */
1815
-
1816
- /* Excluded from this release type: Avatar_MouthShapes */
1817
-
1818
- /* Excluded from this release type: Avatar_MustacheShake */
1819
-
1820
- /* Excluded from this release type: Avatar_POI */
1821
-
1822
- /* Excluded from this release type: AvatarBlink_Simple */
1823
-
1824
- /* Excluded from this release type: AvatarEyeLook_Rotation */
1825
-
1826
- /**
1827
- * Handles loading and instantiating avatar models from various sources.
1828
- * Provides functionality to find and extract important parts of an avatar (head, hands).
1829
- *
1830
- * Debug mode can be enabled with the URL parameter `?debugavatar`,
1831
- * which will log detailed information about avatar loading and configuration.
1832
- */
1833
- export declare class AvatarLoader {
1834
- private readonly avatarRegistryUrl;
1835
- /**
1836
- * Retrieves or creates a new avatar instance from an ID or existing Object3D.
1837
- * @param context The application context
1838
- * @param avatarId Either a string ID to load an avatar or an existing Object3D to use as avatar
1839
- * @returns Promise resolving to an AvatarModel if successful, or null if failed
1840
- */
1841
- getOrCreateNewAvatarInstance(context: Context, avatarId: string | Object3D): Promise<AvatarModel | null>;
1842
- /**
1843
- * Loads an avatar model from a file or registry using the provided ID.
1844
- * @param context The engine context
1845
- * @param avatarId The ID of the avatar to load
1846
- * @returns Promise resolving to the loaded avatar's Object3D, or null if failed
1847
- */
1848
- private loadAvatar;
1849
- /**
1850
- * Caches an avatar model for reuse.
1851
- * @param _id The ID to associate with the model
1852
- * @param _model The avatar model to cache
1853
- */
1854
- private cacheModel;
1855
- /**
1856
- * Analyzes an Object3D to find avatar parts (head, hands) based on naming conventions.
1857
- * @param obj The Object3D to search for avatar parts
1858
- * @returns A structured AvatarModel with references to found parts
1859
- */
1860
- private findAvatar;
1861
- /**
1862
- * Recursively searches for an avatar part by name within an Object3D hierarchy.
1863
- * @param obj The Object3D to search within
1864
- * @param searchString Array of strings that should all be present in the object name
1865
- * @returns The found Object3D part or null if not found
1866
- */
1867
- private findAvatarPart;
1868
- /**
1869
- * Handles HTTP response errors from avatar loading operations.
1870
- * @param response The fetch API response to check
1871
- * @returns The response if it was ok
1872
- * @throws Error with status text if response was not ok
1873
- */
1874
- private handleCustomAvatarErrors;
1875
- }
1876
-
1877
2087
  /**
1878
2088
  * Marks a GameObject as being controlled or owned by a player in networked XR sessions.
1879
2089
  * This is used internally by the networking system to identify player-controlled objects.
@@ -1934,35 +2144,6 @@ declare type AvatarMarkerEventArgs = {
1934
2144
  gameObject: Object3D;
1935
2145
  };
1936
2146
 
1937
- /**
1938
- * Represents an avatar model with head and hands references.
1939
- * Used for representing characters in 3D space.
1940
- */
1941
- export declare class AvatarModel {
1942
- /** The root object of the avatar model */
1943
- root: Object3D;
1944
- /** The head object of the avatar model */
1945
- head: Object3D;
1946
- /** The left hand object of the avatar model, if available */
1947
- leftHand: Object3D | null;
1948
- /** The right hand object of the avatar model, if available */
1949
- rigthHand: Object3D | null;
1950
- /**
1951
- * Checks if the avatar model has a valid configuration.
1952
- * An avatar is considered valid if it has a head.
1953
- * @returns Whether the avatar has a valid setup
1954
- */
1955
- get isValid(): boolean;
1956
- /**
1957
- * Creates a new avatar model.
1958
- * @param root The root object of the avatar
1959
- * @param head The head object of the avatar
1960
- * @param leftHand The left hand object of the avatar
1961
- * @param rigthHand The right hand object of the avatar
1962
- */
1963
- constructor(root: Object3D, head: Object3D, leftHand: Object3D | null, rigthHand: Object3D | null);
1964
- }
1965
-
1966
2147
  export declare enum Axes {
1967
2148
  None = 0,
1968
2149
  X = 2,
@@ -2326,7 +2507,6 @@ export declare class BoxCollider extends Collider implements IBoxCollider {
2326
2507
  center: Vector3;
2327
2508
  /* Excluded from this release type: onEnable */
2328
2509
  /* Excluded from this release type: onDisable */
2329
- /* Excluded from this release type: onValidate */
2330
2510
  /**
2331
2511
  * Automatically fits the collider to the geometry of the object.
2332
2512
  * Sets the size and center based on the object's bounding box.
@@ -2600,6 +2780,7 @@ declare class CallHandle extends EventDispatcher<any> {
2600
2780
  * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
2601
2781
  */
2602
2782
  export declare class CallInfo {
2783
+ $serializedTypes: Record<string, any>;
2603
2784
  /**
2604
2785
  * When the CallInfo is enabled it will be invoked when the EventList is invoked
2605
2786
  */
@@ -2946,7 +3127,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
2946
3127
  private _receivers;
2947
3128
  registerEventReceiver(receiver: ICanvasEventReceiver): void;
2948
3129
  unregisterEventReceiver(receiver: ICanvasEventReceiver): void;
2949
- onEnterXR(args: NeedleXREventArgs): Promise<void>;
3130
+ onEnterXR(args: NeedleXREventArgs): void;
2950
3131
  onLeaveXR(args: NeedleXREventArgs): void;
2951
3132
  onBeforeRenderRoutine: () => void;
2952
3133
  onAfterRenderRoutine: () => void;
@@ -3522,6 +3703,22 @@ export declare abstract class Collider extends Component implements ICollider {
3522
3703
  * The layers that this collider will interact with. Used for filtering collision detection.
3523
3704
  */
3524
3705
  filter?: number[];
3706
+ /**
3707
+ * The density of the collider, used for automatic mass calculation when the attached {@link Rigidbody} has `autoMass` enabled.
3708
+ * Rapier computes mass from density using the real-world formula: `mass = density × volume`.
3709
+ * The volume is derived from the collider shape (sphere, box, capsule, or convex hull).
3710
+ *
3711
+ * Reference values (relative to water = 1.0):
3712
+ * - Wood: 0.5–0.9
3713
+ * - Water: 1.0 (engine default)
3714
+ * - Rubber: 1.2
3715
+ * - Steel: 7.8
3716
+ *
3717
+ * @default undefined — uses the physics engine default of 1.0
3718
+ */
3719
+ density?: number;
3720
+ /* Excluded from this release type: _propertiesDirty */
3721
+ /* Excluded from this release type: onValidate */
3525
3722
  /* Excluded from this release type: awake */
3526
3723
  /* Excluded from this release type: start */
3527
3724
  /* Excluded from this release type: onEnable */
@@ -3625,6 +3822,9 @@ declare class ColorSerializer extends TypeSerializer {
3625
3822
 
3626
3823
  export declare let colorSerializer: ColorSerializer;
3627
3824
 
3825
+ /** A Color value, either as a Three.js Color or as an `[r, g, b]` tuple (0–1) */
3826
+ declare type ColorValue = Color | [number, number, number];
3827
+
3628
3828
  /**
3629
3829
  * Utility method to check if two materials were created from the same glTF material
3630
3830
  */
@@ -3644,7 +3844,7 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
3644
3844
  * **Input event methods:**
3645
3845
  * {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
3646
3846
  *
3647
- * @example
3847
+ * @example Basic component
3648
3848
  * ```typescript
3649
3849
  * import { Behaviour } from "@needle-tools/engine";
3650
3850
  * export class MyComponent extends Behaviour {
@@ -3657,6 +3857,25 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
3657
3857
  * }
3658
3858
  * ```
3659
3859
  *
3860
+ * @example Automatic cleanup with autoCleanup
3861
+ * ```typescript
3862
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
3863
+ * export class ScoreTracker extends Behaviour {
3864
+ * @serializable(EventList)
3865
+ * onScoreChanged?: EventList<number>;
3866
+ *
3867
+ * start() {
3868
+ * // Registered during start → survives enable/disable, cleaned up on destroy
3869
+ * this.autoCleanup(this.onScoreChanged?.on(score => console.log("Score:", score)));
3870
+ * }
3871
+ *
3872
+ * onEnable() {
3873
+ * // Registered during onEnable → cleaned up on disable
3874
+ * this.autoCleanup(() => this.cleanupResources());
3875
+ * }
3876
+ * }
3877
+ * ```
3878
+ *
3660
3879
  * @group Components
3661
3880
  */
3662
3881
  declare abstract class Component implements IComponent, EventTarget, Partial<INeedleXRSessionEventReceiver>, Partial<IPointerEventHandler> {
@@ -3707,6 +3926,50 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3707
3926
  * @returns True if the component is enabled and all parent GameObjects are active
3708
3927
  */
3709
3928
  get activeAndEnabled(): boolean;
3929
+ private __disableCleanups?;
3930
+ private __destroyCleanups?;
3931
+ /**
3932
+ * @experimental
3933
+ * Register a resource for automatic cleanup tied to this component's lifecycle.
3934
+ * Accepts {@link IDisposable} objects, cleanup functions, or event unsubscribe functions.
3935
+ * `null` and `undefined` are safe no-ops (convenient for conditional subscriptions).
3936
+ *
3937
+ * **Lifecycle-aware:** The cleanup store is chosen automatically based on when `autoCleanup` is called:
3938
+ * - Called during {@link onEnable} → cleaned up on {@link onDisable} (and re-registered on re-enable)
3939
+ * - Called during {@link awake} or {@link start} → cleaned up on {@link onDestroy} (survives enable/disable cycles)
3940
+ * - Called at any other time (e.g. from update) → cleaned up on {@link onDisable}
3941
+ *
3942
+ * @param disposable An {@link IDisposable}, a cleanup/unsubscribe function, or `null`/`undefined`
3943
+ *
3944
+ * @example EventList subscriptions
3945
+ * ```ts
3946
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
3947
+ *
3948
+ * export class MyComponent extends Behaviour {
3949
+ * @serializable(EventList)
3950
+ * onScoreChanged?: EventList<number>;
3951
+ *
3952
+ * onEnable() {
3953
+ * this.autoCleanup(this.onScoreChanged?.on(score => {
3954
+ * console.log("Score:", score);
3955
+ * }));
3956
+ * }
3957
+ * }
3958
+ * ```
3959
+ *
3960
+ * @example Lifetime subscriptions in awake
3961
+ * ```ts
3962
+ * import { Behaviour } from "@needle-tools/engine";
3963
+ *
3964
+ * export class Persistent extends Behaviour {
3965
+ * awake() {
3966
+ * // Registered during awake → survives enable/disable, cleaned up on destroy
3967
+ * this.autoCleanup(() => this.save());
3968
+ * }
3969
+ * }
3970
+ * ```
3971
+ */
3972
+ protected autoCleanup(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
3710
3973
  private get __isActive();
3711
3974
  private get __isActiveInHierarchy();
3712
3975
  private set __isActiveInHierarchy(value);
@@ -3725,11 +3988,6 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3725
3988
  * For example, URL to the glTF file this component was loaded from
3726
3989
  */
3727
3990
  sourceId?: SourceIdentifier;
3728
- /**
3729
- * Called when this component needs to remap guids after an instantiate operation.
3730
- * @param guidsMap Mapping from old guids to newly generated guids
3731
- */
3732
- resolveGuids?(guidsMap: GuidsMap): void;
3733
3991
  /**
3734
3992
  * Called once when the component becomes active for the first time.
3735
3993
  * This is the first lifecycle callback to be invoked
@@ -3942,6 +4200,10 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3942
4200
  destroy(): void;
3943
4201
  /* Excluded from this release type: __didAwake */
3944
4202
  /* Excluded from this release type: __didStart */
4203
+ /** True while start() has finished executing (used by autoCleanup to distinguish start from update) */
4204
+ private __didCompleteStart;
4205
+ /** True while onEnable() is executing (used by autoCleanup to route to disable store) */
4206
+ private __inEnableOrDisableCallback;
3945
4207
  /* Excluded from this release type: __didEnable */
3946
4208
  /* Excluded from this release type: __isEnabled */
3947
4209
  /* Excluded from this release type: __destroyed */
@@ -4231,6 +4493,7 @@ export declare class ContactShadows extends Component {
4231
4493
  set needsUpdate(val: boolean);
4232
4494
  get needsUpdate(): boolean;
4233
4495
  private _needsUpdate;
4496
+ private _needsFit;
4234
4497
  /** All shadow objects are parented to this object.
4235
4498
  * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
4236
4499
  * in which case ContactShadows scale would affect the projection
@@ -4484,19 +4747,31 @@ export declare class Context implements IContext {
4484
4747
  private _mainCamera;
4485
4748
  private _fallbackCamera;
4486
4749
  /** access application state (e.g. if all audio should be muted) */
4487
- application: Application;
4750
+ get application(): Application;
4751
+ private _application;
4488
4752
  /** access animation mixer used by components in the scene */
4489
- animations: AnimationsRegistry;
4753
+ get animations(): AnimationsRegistry;
4754
+ private _animations;
4490
4755
  /** access timings (current frame number, deltaTime, timeScale, ...) */
4491
- time: Time;
4756
+ get time(): Time;
4757
+ private _time;
4492
4758
  /** access input data (e.g. click or touch events) */
4493
- input: Input;
4759
+ get input(): Input;
4760
+ private _input;
4494
4761
  /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
4495
- physics: Physics;
4762
+ get physics(): Physics;
4763
+ private _physics;
4496
4764
  /** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
4497
- postprocessing: PostProcessing;
4765
+ get postprocessing(): PostProcessing;
4766
+ private _postprocessing;
4498
4767
  /** access networking methods (use it to send or listen to messages or join a networking backend) */
4499
- connection: NetworkConnection;
4768
+ get connection(): NetworkConnection;
4769
+ private _connection;
4770
+ /** context-level event bus for decoupled component communication
4771
+ * @see {@link ContextEventMap} for known event types
4772
+ */
4773
+ get events(): EventBus;
4774
+ private _events;
4500
4775
  /** @deprecated AssetDatabase is deprecated */
4501
4776
  assets: AssetDatabase;
4502
4777
  /** All registered lights in the scene, maintained by the Light component.
@@ -4755,6 +5030,18 @@ export declare type ContextEventArgs = {
4755
5030
  files?: LoadedModel[];
4756
5031
  };
4757
5032
 
5033
+ /** Typed event map for {@link Context.events}.
5034
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
5035
+ */
5036
+ export declare interface ContextEventMap {
5037
+ "scene-content-changed": {
5038
+ /** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
5039
+ readonly source: IComponent;
5040
+ /** The root object that was added/loaded */
5041
+ readonly object: Object3D;
5042
+ };
5043
+ }
5044
+
4758
5045
  /** Use to register to various Needle Engine context events and to get access to all current instances
4759
5046
  * e.g. when being created in the DOM
4760
5047
  * @example
@@ -4806,6 +5093,20 @@ export declare type ControlClipModel = {
4806
5093
  updateDirector: boolean;
4807
5094
  };
4808
5095
 
5096
+ /**
5097
+ * Options for a control clip in the timeline builder
5098
+ */
5099
+ export declare type ControlClipOptions = {
5100
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
5101
+ start?: number;
5102
+ /** Duration of the clip in seconds (required) */
5103
+ duration: number;
5104
+ /** Whether to control the activation of the source object (default: true) */
5105
+ controlActivation?: boolean;
5106
+ /** Whether to update a nested PlayableDirector on the source object (default: true) */
5107
+ updateDirector?: boolean;
5108
+ };
5109
+
4809
5110
  /** true when selectstart was ever received.
4810
5111
  * On VisionOS 1.1 we always have select events (as per the spec), so this is always true
4811
5112
  */
@@ -4816,12 +5117,15 @@ declare type ControllerAxes = "xr-standard-thumbstick" | "xr-standard-touchpad";
4816
5117
  */
4817
5118
  export declare type ControllerChangedEvt = (args: NeedleXRControllerEventArgs) => void;
4818
5119
 
4819
- export declare class ControlTrackHandler extends TrackHandler {
4820
- models: Array<Models.ClipModel>;
4821
- timelines: Array<PlayableDirector | null>;
4822
- resolveSourceObjects(_context: Context): void;
4823
- private _previousActiveModel;
4824
- evaluate(time: number): void;
5120
+ /**
5121
+ * Builder for control tracks. Provides `.clip()` for controlling nested objects/timelines.
5122
+ * @category Animation and Sequencing
5123
+ */
5124
+ export declare interface ControlTrackBuilder extends TimelineBuilderBase {
5125
+ /** Adds a control clip for a source object */
5126
+ clip(sourceObject: Object3D, options: ControlClipOptions): ControlTrackBuilder;
5127
+ /** Mutes this track so it is skipped during playback */
5128
+ muted(muted?: boolean): ControlTrackBuilder;
4825
5129
  }
4826
5130
 
4827
5131
  /**@obsolete use Graphics.copyTexture */
@@ -5009,7 +5313,6 @@ export declare class CursorFollow extends Component {
5009
5313
  * - Cursor that follows terrain or mesh surfaces
5010
5314
  *
5011
5315
  * **Important notes:**
5012
- * - Requires objects in the scene to have colliders for raycasting to work
5013
5316
  * - Works best with {@link keepDistance} set to `false` to allow depth changes
5014
5317
  * - Can be combined with {@link damping} for smooth surface following
5015
5318
  * - The raycast uses the physics system's raycast functionality
@@ -5136,7 +5439,7 @@ export declare function decompressGpuTexture(texture: any, maxTextureSize?: numb
5136
5439
  * return true;
5137
5440
  * });
5138
5441
  * */
5139
- export declare function deepClone(obj: any, predicate?: deepClonePredicate): any;
5442
+ export declare function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any;
5140
5443
 
5141
5444
  declare type deepClonePredicate = (owner: any, propertyName: string, current: any) => boolean;
5142
5445
 
@@ -5364,7 +5667,7 @@ export declare namespace DeviceUtilities {
5364
5667
  * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
5365
5668
  * @see {@link PlayableDirector.extrapolationMode}
5366
5669
  */
5367
- declare enum DirectorWrapMode {
5670
+ export declare enum DirectorWrapMode {
5368
5671
  /** Hold the last frame when playback reaches the end of the timeline. */
5369
5672
  Hold = 0,
5370
5673
  /** Loop back to the start and continue playing indefinitely. */
@@ -5373,6 +5676,101 @@ declare enum DirectorWrapMode {
5373
5676
  None = 2
5374
5677
  }
5375
5678
 
5679
+ /**
5680
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
5681
+ * that should be cleaned up together.
5682
+ *
5683
+ * DisposableStore collects disposables and disposes them all at once when
5684
+ * {@link dispose} is called. After disposal, the store can be reused — new items
5685
+ * can be added and a subsequent {@link dispose} call will clean those up.
5686
+ *
5687
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
5688
+ *
5689
+ * @example Basic usage
5690
+ * ```ts
5691
+ * import { DisposableStore, on } from "@needle-tools/engine";
5692
+ *
5693
+ * const store = new DisposableStore();
5694
+ *
5695
+ * // Register a DOM event listener (typed!)
5696
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
5697
+ *
5698
+ * // Register the return value of EventList.on()
5699
+ * store.add(myEventList.on(data => console.log(data)));
5700
+ *
5701
+ * // Register a raw cleanup function
5702
+ * store.add(() => someSDK.off("event", handler));
5703
+ *
5704
+ * // Later: dispose everything at once
5705
+ * store.dispose();
5706
+ * ```
5707
+ *
5708
+ * @example Use with Needle Engine components
5709
+ * ```ts
5710
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
5711
+ *
5712
+ * export class MyComponent extends Behaviour {
5713
+ * @serializable(EventList)
5714
+ * onClick?: EventList;
5715
+ *
5716
+ * onEnable() {
5717
+ * // DOM events — fully typed
5718
+ * this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
5719
+ *
5720
+ * // EventList — .on() returns a function, autoCleanup accepts it
5721
+ * this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
5722
+ * }
5723
+ * // No onDisable needed — cleaned up automatically!
5724
+ * }
5725
+ * ```
5726
+ *
5727
+ * @category Utilities
5728
+ * @group Lifecycle
5729
+ */
5730
+ export declare class DisposableStore implements IDisposable {
5731
+ private _disposables;
5732
+ /** The number of registered disposables */
5733
+ get size(): number;
5734
+ /**
5735
+ * Register a disposable resource. Accepts:
5736
+ * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
5737
+ * - A cleanup function (e.g. return value of `EventList.on()`)
5738
+ * - `null` or `undefined` (safe no-op for conditional subscriptions)
5739
+ *
5740
+ * When {@link dispose} is called, all registered resources are cleaned up.
5741
+ *
5742
+ * @param disposable The resource to register for disposal
5743
+ *
5744
+ * @example
5745
+ * ```ts
5746
+ * const store = new DisposableStore();
5747
+ *
5748
+ * // IDisposable object from on()
5749
+ * store.add(on(window, "resize", handler));
5750
+ *
5751
+ * // Function returned by EventList.on()
5752
+ * store.add(myEvent.on(handler));
5753
+ *
5754
+ * // Raw cleanup function
5755
+ * store.add(() => connection.close());
5756
+ *
5757
+ * // Conditional — safe with undefined
5758
+ * store.add(this.maybeEvent?.on(handler));
5759
+ * ```
5760
+ */
5761
+ add(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
5762
+ /**
5763
+ * Dispose all registered resources. Each registered disposable is cleaned up,
5764
+ * then the internal list is cleared. The store can be reused after disposal.
5765
+ *
5766
+ * Called automatically by the engine when a component's `onDisable` lifecycle fires.
5767
+ */
5768
+ dispose(): void;
5769
+ }
5770
+
5771
+ /** A function that performs cleanup when called */
5772
+ export declare type DisposeFn = () => void;
5773
+
5376
5774
  /** Recursive disposes all referenced resources by this object. Does not traverse children */
5377
5775
  export declare function disposeObjectResources(obj: object | null | undefined): void;
5378
5776
 
@@ -5480,6 +5878,12 @@ export declare class DragControls extends Component implements IPointerEventHand
5480
5878
  * providing visual feedback about the object's position relative to surfaces below it.
5481
5879
  */
5482
5880
  showGizmo: boolean;
5881
+ /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
5882
+ dragStarted: EventList;
5883
+ /** Invoked every frame while the object is being dragged. */
5884
+ dragUpdated: EventList;
5885
+ /** Invoked once when the last pointer is released and the drag ends. */
5886
+ dragEnded: EventList;
5483
5887
  /**
5484
5888
  * Returns the object currently being dragged by this DragControls component, if any.
5485
5889
  * @returns The object being dragged or null if no object is currently dragged
@@ -5920,6 +6324,45 @@ export declare class EnvironmentScene extends Scene {
5920
6324
  createAreaLightMaterial(intensity: number): MeshBasicMaterial;
5921
6325
  }
5922
6326
 
6327
+ /** An Euler value, either as a Three.js Euler or as a `[x, y, z]` tuple (radians) */
6328
+ declare type EulerValue = Euler | [number, number, number];
6329
+
6330
+ /** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
6331
+ * Custom events can be typed at the call site via generic parameter.
6332
+ * @example Known events
6333
+ * ```ts
6334
+ * context.events.on("scene-content-changed", e => e.object);
6335
+ * ```
6336
+ * @example Custom events — type at call site
6337
+ * ```ts
6338
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
6339
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
6340
+ * ```
6341
+ * @example Once
6342
+ * ```ts
6343
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
6344
+ * ```
6345
+ */
6346
+ export declare class EventBus {
6347
+ private _listeners;
6348
+ /** Emit a known {@link ContextEventMap} event */
6349
+ emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
6350
+ /** Emit a custom event with user-provided type */
6351
+ emit<T>(type: string, detail?: T): void;
6352
+ /** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
6353
+ on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
6354
+ /** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
6355
+ on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
6356
+ /** Remove all listeners. Called when the context is cleared or destroyed. */
6357
+ clear(): void;
6358
+ }
6359
+
6360
+ /** Options for {@link EventBus.on}. */
6361
+ export declare interface EventBusListenerOptions {
6362
+ /** If true the listener is automatically removed after the first invocation. */
6363
+ once?: boolean;
6364
+ }
6365
+
5923
6366
  /**
5924
6367
  * EventList manages a list of callbacks that can be invoked together.
5925
6368
  * Used for Unity-style events that can be configured in the editor (Unity or Blender).
@@ -5966,13 +6409,9 @@ export declare class EnvironmentScene extends Scene {
5966
6409
  * @see {@link Button} for UI button events
5967
6410
  */
5968
6411
  export declare class EventList<TArgs extends any = any> implements IEventList {
6412
+ $serializedTypes: Record<string, any>;
5969
6413
  /** checked during instantiate to create a new instance */
5970
6414
  readonly isEventList = true;
5971
- /* Excluded from this release type: __internalOnInstantiate */
5972
- private target?;
5973
- private key?;
5974
- /** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
5975
- setEventTarget(key: string, target: object): void;
5976
6415
  /** How many callback methods are subscribed to this event */
5977
6416
  get listenerCount(): number;
5978
6417
  /** If the event is currently being invoked */
@@ -6005,13 +6444,41 @@ export declare class EventList<TArgs extends any = any> implements IEventList {
6005
6444
  invoke(...args: Array<TArgs>): boolean;
6006
6445
  /** Add a new event listener to this event
6007
6446
  * @returns a function to remove the event listener
6447
+ * @see {@link removeEventListener} for more details and return value information
6448
+ * @see {@link off} for an alias with better readability when unsubscribing from events
6449
+ * @example
6450
+ * ```ts
6451
+ * const off = myEvent.addEventListener(args => console.log("Clicked!", args));
6452
+ * // later
6453
+ * off();
6454
+ * ```
6008
6455
  */
6009
6456
  addEventListener(callback: (args: TArgs) => void): Function;
6457
+ /**
6458
+ * Alias for addEventListener for better readability when subscribing to events. You can use it like this:
6459
+ * ```ts
6460
+ * myEvent.on(args => console.log("Clicked!", args));
6461
+ * ```
6462
+ * @returns a function to remove the event listener
6463
+ * @see {@link addEventListener} for more details and return value information
6464
+ */
6465
+ on(callback: (args: TArgs) => void): Function;
6010
6466
  /**
6011
6467
  * Remove an event listener from this event.
6012
6468
  * @returns true if the event listener was found and removed, false otherwise
6013
6469
  */
6014
6470
  removeEventListener(fn: Function | null | undefined): boolean;
6471
+ /**
6472
+ * Alias for removeEventListener for better readability when unsubscribing from events. You can use it like this:
6473
+ * ```ts
6474
+ * const off = myEvent.on(args => console.log("Clicked!", args));
6475
+ * // later
6476
+ * off();
6477
+ * ```
6478
+ *
6479
+ * @see {@link removeEventListener} for more details and return value information
6480
+ */
6481
+ off(callback: Function | null | undefined): boolean;
6015
6482
  /**
6016
6483
  * Remove all event listeners from this event. Use with caution! This will remove all listeners!
6017
6484
  */
@@ -6042,6 +6509,7 @@ declare type EventListenerOptions_2 = {
6042
6509
  signal?: AbortSignal;
6043
6510
  };
6044
6511
 
6512
+ /** @deprecated No longer automatically dispatched. Use `eventList.on()` directly instead. */
6045
6513
  export declare class EventListEvent<TArgs extends any> extends Event {
6046
6514
  args?: TArgs;
6047
6515
  }
@@ -6495,7 +6963,7 @@ declare type FitParameters = {
6495
6963
  * @see {@link HingeJoint} for rotating connections
6496
6964
  */
6497
6965
  export declare class FixedJoint extends Joint {
6498
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
6966
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
6499
6967
  }
6500
6968
 
6501
6969
  declare type FocusRect = DOMRect | Element | {
@@ -7746,7 +8214,7 @@ export declare class HingeJoint extends Joint {
7746
8214
  anchor?: Vector3;
7747
8215
  /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
7748
8216
  axis?: Vector3;
7749
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
8217
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
7750
8218
  }
7751
8219
 
7752
8220
  declare type HitPointObject = Object3D & {
@@ -7969,7 +8437,7 @@ declare const HTMLElementBase: typeof HTMLElement;
7969
8437
 
7970
8438
  export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
7971
8439
  isAnimationComponent: boolean;
7972
- addClip?(clip: AnimationClip): any;
8440
+ addClip?(clip: AnimationClip): void;
7973
8441
  };
7974
8442
 
7975
8443
  /* Excluded from this release type: IApplyPrototypeExtension */
@@ -8043,6 +8511,12 @@ export declare interface ICollider extends IComponent {
8043
8511
  * Default: undefined
8044
8512
  */
8045
8513
  filter?: number[];
8514
+ /** The density of the collider used for automatic mass calculation.
8515
+ * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
8516
+ * Note: Make sure to call updateProperties after having changed this property
8517
+ * Default: undefined (uses physics engine default of 1.0)
8518
+ */
8519
+ density?: number;
8046
8520
  }
8047
8521
 
8048
8522
  export declare type ICollisionContext = {
@@ -8069,7 +8543,6 @@ export declare interface IComponent extends IHasGuid {
8069
8543
  /* Excluded from this release type: __internalEnable */
8070
8544
  /* Excluded from this release type: __internalDisable */
8071
8545
  /* Excluded from this release type: __internalDestroy */
8072
- /* Excluded from this release type: resolveGuids */
8073
8546
  /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
8074
8547
  registering?(): any;
8075
8548
  awake(): any;
@@ -8106,6 +8579,24 @@ export declare interface IConnectionData {
8106
8579
 
8107
8580
  export declare type IContext = Context;
8108
8581
 
8582
+ /**
8583
+ * Interface for objects that hold resources and can be disposed.
8584
+ * Implement this interface on any object that needs deterministic cleanup.
8585
+ *
8586
+ * @example
8587
+ * ```ts
8588
+ * class MyResource implements IDisposable {
8589
+ * dispose() { /* release resources *\/ }
8590
+ * }
8591
+ * ```
8592
+ *
8593
+ * @category Utilities
8594
+ * @group Lifecycle
8595
+ */
8596
+ export declare interface IDisposable {
8597
+ dispose(): void;
8598
+ }
8599
+
8109
8600
  /** Implement to receive callbacks from {@type @needle-tools/editor-sync} package */
8110
8601
  declare interface IEditorModification {
8111
8602
  /**
@@ -8125,7 +8616,6 @@ export declare interface IEffectProvider {
8125
8616
 
8126
8617
  export declare interface IEventList {
8127
8618
  readonly isEventList: true;
8128
- __internalOnInstantiate(map: InstantiateContext): IEventList;
8129
8619
  }
8130
8620
 
8131
8621
  export declare interface IGameObject extends Object3D {
@@ -8418,13 +8908,45 @@ export declare interface INeedleXRSessionEventReceiver extends Pick<IComponent,
8418
8908
  export declare interface INetworkConnection {
8419
8909
  get isConnected(): boolean;
8420
8910
  get isInRoom(): boolean;
8421
- send(key: string, data: IModel | object | boolean | null | string | number, queue: SendQueue): unknown;
8911
+ send(key: string, data?: IModel | object | boolean | string | number, queue?: SendQueue): unknown;
8422
8912
  }
8423
8913
 
8424
8914
  export declare interface INetworkingWebsocketUrlProvider {
8425
8915
  getWebsocketUrl(): string | null;
8426
8916
  }
8427
8917
 
8918
+ /**
8919
+ * @experimental
8920
+ * Interface for a network transport layer used by {@link NetworkConnection}.
8921
+ * The default implementation wraps a websocket via `websocket-ts`.
8922
+ * Custom implementations can be injected into {@link NetworkConnection.connect}
8923
+ * for testing or alternative transports.
8924
+ *
8925
+ * **Lifecycle:** After creating a transport and passing it to `connect()`,
8926
+ * `NetworkConnection` sets the four event callbacks (`onOpen`, `onClose`,
8927
+ * `onError`, `onMessage`) and then calls {@link start}. The transport
8928
+ * should call `onOpen` when the connection is ready.
8929
+ */
8930
+ export declare interface INetworkTransport {
8931
+ /** Start the connection. Called by NetworkConnection after event callbacks are set.
8932
+ * May return a promise if setup is async (e.g. dynamic imports). */
8933
+ start(): void | Promise<void>;
8934
+ /** Send data (string for JSON messages, Uint8Array for binary) */
8935
+ send(data: string | Uint8Array): void;
8936
+ /** Close the transport */
8937
+ close(): void | Promise<void>;
8938
+ /** The URL this transport is connected to, if applicable */
8939
+ readonly url: string | undefined;
8940
+ /** Called when the transport connection opens */
8941
+ onOpen: (() => void) | null;
8942
+ /** Called when the transport connection closes */
8943
+ onClose: (() => void) | null;
8944
+ /** Called when an error occurs */
8945
+ onError: ((err: any) => void) | null;
8946
+ /** Called when a message is received. Data is either a string (JSON) or Blob (binary). */
8947
+ onMessage: ((data: string | Blob) => void) | null;
8948
+ }
8949
+
8428
8950
  export declare class InheritVelocityModule {
8429
8951
  enabled: boolean;
8430
8952
  curve: MinMaxCurve;
@@ -8511,14 +9033,33 @@ export declare class Input implements IInput {
8511
9033
  */
8512
9034
  private readonly _eventListeners;
8513
9035
  /** Adds an event listener for the specified event type. The callback will be called when the event is triggered.
9036
+ *
9037
+ * Returns an unsubscribe function — call it to remove the listener.
9038
+ * Pass it to {@link Behaviour.autoCleanup} for automatic lifecycle management.
9039
+ *
8514
9040
  * @param type The event type to listen for
8515
9041
  * @param callback The callback to call when the event is triggered
8516
9042
  * @param options The options for adding the event listener.
8517
- * @example Basic usage
9043
+ * @returns A function that removes the event listener when called.
9044
+ *
9045
+ * @example With autoCleanup (recommended)
8518
9046
  * ```ts
8519
- * input.addEventListener("pointerdown", (evt) => {
9047
+ * export class MyComponent extends Behaviour {
9048
+ * onEnable() {
9049
+ * this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => {
9050
+ * console.log("Pointer down", evt.pointerId, evt.pointerType);
9051
+ * }));
9052
+ * }
9053
+ * // Listener is automatically removed on disable — no manual cleanup needed!
9054
+ * }
9055
+ * ```
9056
+ * @example Manual unsubscribe
9057
+ * ```ts
9058
+ * const off = input.addEventListener("pointerdown", (evt) => {
8520
9059
  * console.log("Pointer down", evt.pointerId, evt.pointerType);
8521
9060
  * });
9061
+ * // later
9062
+ * off();
8522
9063
  * ```
8523
9064
  * @example Adding a listener that is called after all other listeners
8524
9065
  * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
@@ -8534,8 +9075,8 @@ export declare class Input implements IInput {
8534
9075
  * }, { once: true });
8535
9076
  * ```
8536
9077
  */
8537
- addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): any;
8538
- addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): any;
9078
+ addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): () => void;
9079
+ addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): () => void;
8539
9080
  /** Removes the event listener from the specified event type. If no queue is specified the listener will be removed from all queues.
8540
9081
  * @param type The event type to remove the listener from
8541
9082
  * @param callback The callback to remove
@@ -8981,7 +9522,7 @@ export declare function instantiate(instance: AssetReference, opts?: IInstantiat
8981
9522
  export declare function instantiate(instance: IGameObject | Object3D, opts?: IInstantiateOptions | null): IGameObject;
8982
9523
 
8983
9524
  /**
8984
- * Provides access to the instantiated object and its clone
9525
+ * Provides access to the instantiated object map (used by EventList etc.)
8985
9526
  */
8986
9527
  export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
8987
9528
 
@@ -9021,7 +9562,8 @@ export declare class InstantiateOptions implements IInstantiateOptions {
9021
9562
  cloneAssign(other: InstantiateOptions | IInstantiateOptions): void;
9022
9563
  }
9023
9564
 
9024
- declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9565
+ /** Maps uuid/guid → { original, clone } for Object3D and Component instances */
9566
+ export declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9025
9567
 
9026
9568
  /**
9027
9569
  * An empty component that can be used to mark an object as interactable.
@@ -9092,8 +9634,10 @@ export declare interface IPhysicsEngine {
9092
9634
  postStep(): any;
9093
9635
  /** Indicates whether the physics engine is currently updating */
9094
9636
  get isUpdating(): boolean;
9095
- /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
9096
- clearCaches(): any;
9637
+ /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
9638
+ dispose(): void;
9639
+ /** @deprecated Use {@link dispose} instead. */
9640
+ clearCaches(): void;
9097
9641
  /** Enables or disables the physics engine */
9098
9642
  enabled: boolean;
9099
9643
  /** Returns the underlying physics world object */
@@ -9140,6 +9684,11 @@ export declare interface IPhysicsEngine {
9140
9684
  * @returns False to ignore this collider, true to include it
9141
9685
  */
9142
9686
  filterPredicate?: (collider: ICollider) => boolean;
9687
+ /** When true, trigger/sensor colliders will be included in the raycast results.
9688
+ * By default trigger colliders are skipped.
9689
+ * @default false
9690
+ */
9691
+ includeTriggers?: boolean;
9143
9692
  }): RaycastResult;
9144
9693
  /**
9145
9694
  * Performs a raycast that also returns the normal vector at the hit point
@@ -9167,6 +9716,11 @@ export declare interface IPhysicsEngine {
9167
9716
  * @returns False to ignore this collider, true to include it
9168
9717
  */
9169
9718
  filterPredicate?: (collider: ICollider) => boolean;
9719
+ /** When true, trigger/sensor colliders will be included in the raycast results.
9720
+ * By default trigger colliders are skipped.
9721
+ * @default false
9722
+ */
9723
+ includeTriggers?: boolean;
9170
9724
  }): RaycastResult;
9171
9725
  /**
9172
9726
  * Finds all colliders within a sphere
@@ -9323,8 +9877,9 @@ export declare interface IPhysicsEngine {
9323
9877
  * @returns The underlying physics body or null if not found
9324
9878
  */
9325
9879
  getBody(obj: ICollider | IRigidbody): null | any;
9326
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): any;
9327
- addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): any;
9880
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
9881
+ addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
9882
+ removeJoint(joint: any): void;
9328
9883
  /** Enable to render collider shapes */
9329
9884
  debugRenderColliders: boolean;
9330
9885
  /** Enable to visualize raycasts in the scene with gizmos */
@@ -9545,6 +10100,18 @@ export declare function isDestroyed(go: Object3D): boolean;
9545
10100
  /** True when the application runs on a local url */
9546
10101
  export declare function isDevEnvironment(): boolean;
9547
10102
 
10103
+ /**
10104
+ * Type guard to check if an object implements {@link IDisposable}.
10105
+ *
10106
+ * @example
10107
+ * ```ts
10108
+ * if (isDisposable(obj)) {
10109
+ * obj.dispose(); // safe to call
10110
+ * }
10111
+ * ```
10112
+ */
10113
+ export declare function isDisposable(value: unknown): value is IDisposable;
10114
+
9548
10115
  export declare function isDisposed(obj: object): boolean;
9549
10116
 
9550
10117
  export declare interface ISerializable {
@@ -9579,6 +10146,10 @@ export declare function isHotReloadEnabled(): boolean;
9579
10146
  /**@returns true if the element is an needle engine icon element */
9580
10147
  export declare function isIconElement(element: Node): boolean;
9581
10148
 
10149
+ export declare interface ISignalReceiver {
10150
+ readonly isSignalReceiver: true;
10151
+ }
10152
+
9582
10153
  /** @deprecated use {@link DeviceUtilities.isiOS} instead */
9583
10154
  export declare function isiOS(): boolean;
9584
10155
 
@@ -9613,6 +10184,8 @@ export declare function isResourceTrackingEnabled(): boolean;
9613
10184
  /** @deprecated use {@link DeviceUtilities.isSafari} instead */
9614
10185
  export declare function isSafari(): boolean;
9615
10186
 
10187
+ export declare function isTrackModel(obj: unknown): obj is TrackModel;
10188
+
9616
10189
  export declare function isUsingInstancing(instance: Object3D): boolean;
9617
10190
 
9618
10191
  export declare interface ITime {
@@ -9737,7 +10310,9 @@ declare abstract class Joint extends Component {
9737
10310
  connectedBody?: Rigidbody;
9738
10311
  get rigidBody(): Rigidbody | null;
9739
10312
  private _rigidBody;
10313
+ private _jointHandle;
9740
10314
  onEnable(): void;
10315
+ onDisable(): void;
9741
10316
  private create;
9742
10317
  protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
9743
10318
  }
@@ -9779,6 +10354,15 @@ declare class Keyframe_2 {
9779
10354
  }
9780
10355
  export { Keyframe_2 as Keyframe }
9781
10356
 
10357
+ /** Keyframe array or tween shorthand */
10358
+ declare type KF<V> = AnimationKeyframe<V>[] | Tween<V>;
10359
+
10360
+ /** Keyframe array or tween shorthand */
10361
+ declare type KF_2<V> = AnimationKeyframe<V>[] | Tween<V>;
10362
+
10363
+ /** Keyframe array or tween shorthand */
10364
+ declare type KF_3<V> = AnimationKeyframe<V>[] | Tween<V>;
10365
+
9782
10366
  declare type LabelHandle = {
9783
10367
  setText(str: string): any;
9784
10368
  };
@@ -10447,13 +11031,15 @@ export declare function markAsInstancedRendered(go: Object3D, instanced: boolean
10447
11031
  time: number;
10448
11032
  }
10449
11033
 
10450
- export declare class MarkerTrackHandler extends TrackHandler {
10451
- models: Array<Models.MarkerModel & Record<string, any>>;
10452
- needsSorting: boolean;
10453
- foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
10454
- onEnable(): void;
10455
- evaluate(_time: number): void;
10456
- private sort;
11034
+ /**
11035
+ * Builder for marker tracks. Provides `.marker()` for adding markers.
11036
+ * @category Animation and Sequencing
11037
+ */
11038
+ export declare interface MarkerTrackBuilder extends TimelineBuilderBase {
11039
+ /** Adds a marker referencing a signal asset by guid */
11040
+ marker(time: number, asset: string, options?: SignalMarkerOptions): MarkerTrackBuilder;
11041
+ /** Mutes this track so it is skipped during playback */
11042
+ muted(muted?: boolean): MarkerTrackBuilder;
10457
11043
  }
10458
11044
 
10459
11045
  export declare enum MarkerType {
@@ -10999,6 +11585,7 @@ export declare type Model = (GLTF | FBX | OBJ | CustomModel);
10999
11585
 
11000
11586
  declare namespace Models {
11001
11587
  export {
11588
+ isTrackModel,
11002
11589
  TimelineAssetModel,
11003
11590
  TrackType,
11004
11591
  ClipExtrapolation,
@@ -11206,11 +11793,17 @@ export declare interface NeedleEngineAttributes {
11206
11793
  'hash': string;
11207
11794
  /** Set to automatically add OrbitControls to the loaded scene. */
11208
11795
  'camera-controls': string;
11209
- /** Override the default draco decoder path location. */
11796
+ /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
11797
+ * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
11798
+ * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
11799
+ */
11210
11800
  'dracoDecoderPath': string;
11211
- /** Override the default draco library type. */
11801
+ /** Override the default Draco decoder type. */
11212
11802
  'dracoDecoderType': 'wasm' | 'js';
11213
- /** Override the default KTX2 transcoder/decoder path. */
11803
+ /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
11804
+ * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
11805
+ * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
11806
+ */
11214
11807
  'ktx2DecoderPath': string;
11215
11808
  /** Prevent context from being disposed when element is removed from DOM. */
11216
11809
  'keep-alive': 'true' | 'false';
@@ -12164,8 +12757,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
12164
12757
  get referenceSpace(): XRSpace | null;
12165
12758
  /** @returns the XRFrame `viewerpose` using the xr `referenceSpace` */
12166
12759
  get viewerPose(): XRViewerPose | undefined;
12167
- /** @returns `true` if any image is currently being tracked */
12168
- /** returns true if images are currently being tracked */
12760
+ /** @returns `true` if any image is currently being tracked or emulated */
12169
12761
  get isTrackingImages(): boolean;
12170
12762
  /** The currently active XR rig */
12171
12763
  get rig(): IXRRig | null;
@@ -12211,6 +12803,8 @@ export declare class NeedleXRSession implements INeedleXRSession {
12211
12803
  private readonly _xr_update_scripts;
12212
12804
  /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
12213
12805
  private readonly _inactive_scripts;
12806
+ /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
12807
+ private readonly _scripts_in_xr;
12214
12808
  private readonly _controllerAdded;
12215
12809
  private readonly _controllerRemoved;
12216
12810
  private readonly _originalCameraWorldPosition?;
@@ -12598,7 +13192,7 @@ export declare class NetworkConnection implements INetworkConnection {
12598
13192
  /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
12599
13193
  leaveRoom(room?: string | null): boolean;
12600
13194
  /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
12601
- send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType) | null, queue?: SendQueue): void;
13195
+ send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType), queue?: SendQueue): void;
12602
13196
  /**
12603
13197
  * Deletes the network state for a specific object on the server.
12604
13198
  * This removes the object's state from the room, preventing it from being sent to newly joining users.
@@ -12620,61 +13214,69 @@ export declare class NetworkConnection implements INetworkConnection {
12620
13214
  private _defaultMessagesBufferArray;
12621
13215
  sendBufferedMessagesNow(): void;
12622
13216
  /** Use to start listening to networking events.
12623
- * To unsubscribe from events use the `{@link stopListen}` method.
13217
+ * Returns an unsubscribe function that removes the listener when called.
13218
+ * The returned function can also be passed to {@link stopListen} or {@link Component.autoCleanup} for automatic lifecycle management.
12624
13219
  *
12625
- * @example Custom event example
13220
+ * @example With autoCleanup (recommended)
12626
13221
  * ```ts
12627
- * // Listen to a custom event sent by the server
12628
- * this.context.connection.beginListen<MyDataType>("my-custom-event", (data) => {
12629
- * console.log("Received custom event:", data);
12630
- * });
13222
+ * export class MyComponent extends Behaviour {
13223
+ * onEnable() {
13224
+ * this.autoCleanup(this.context.connection.beginListen("joined-room", () => {
13225
+ * console.log("I joined a networked room");
13226
+ * }));
13227
+ * }
13228
+ * // Automatically unsubscribed on disable — no manual cleanup needed!
13229
+ * }
13230
+ * ```
13231
+ *
13232
+ * @example Manual unsubscribe
13233
+ * ```ts
13234
+ * const unsub = this.context.connection.beginListen("joined-room", () => { });
13235
+ * // Later:
13236
+ * unsub(); // removes the listener
12631
13237
  * ```
12632
13238
  *
12633
- * @example Listening to room events
13239
+ * @example With stopListen (legacy pattern, still supported)
12634
13240
  * ```ts
12635
- * // Make sure to unsubscribe from events when the component is disabled
12636
13241
  * export class MyComponent extends Behaviour {
12637
13242
  * onEnable() {
12638
- * this.connection.beginListen("joined-room", this.onJoinedRoom)
13243
+ * this.context.connection.beginListen("joined-room", this.onJoinedRoom);
12639
13244
  * }
12640
13245
  * onDisable() {
12641
- * this.connection.stopListen("joined-room", this.onJoinedRoom)
13246
+ * this.context.connection.stopListen("joined-room", this.onJoinedRoom);
12642
13247
  * }
12643
13248
  * onJoinedRoom = () => {
12644
- * console.log("I joined a networked room")
13249
+ * console.log("I joined a networked room");
12645
13250
  * }
12646
13251
  * }
12647
13252
  * ```
12648
13253
  * @link https://engine.needle.tools/docs/networking.html
12649
13254
  *
12650
13255
  */
12651
- beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void;
13256
+ beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): DisposeFn;
12652
13257
  /**@deprecated please use stopListen instead (2.65.2-pre) */
12653
13258
  stopListening<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
12654
- /** Use to stop listening to networking events
13259
+ /** Use to stop listening to networking events.
13260
+ * Accepts either the original callback or the unsubscribe function returned by {@link beginListen}.
12655
13261
  * To subscribe to events use the `{@link beginListen}` method.
12656
- * See the example below for typical usage:
12657
13262
  *
12658
- * ### Component Example
12659
- * ```ts
12660
- * // Make sure to unsubscribe from events when the component is disabled
12661
- * export class MyComponent extends Behaviour {
12662
- * onEnable() {
12663
- * this.connection.beginListen("joined-room", this.onJoinedRoom)
12664
- * }
12665
- * onDisable() {
12666
- * this.connection.stopListen("joined-room", this.onJoinedRoom)
12667
- * }
12668
- * onJoinedRoom = () => {
12669
- * console.log("I joined a networked room")
12670
- * }
12671
- * }
13263
+ * @example
13264
+ * ```ts
13265
+ * // Both patterns work:
13266
+ * this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
13267
+ * this.context.connection.stopListen("joined-room", unsub); // unsubscribe fn from beginListen
12672
13268
  * ```
12673
13269
  */
12674
- stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
12675
- /** Use to start listening to networking binary events */
12676
- beginListenBinary(identifier: string, callback: BinaryCallback): BinaryCallback;
12677
- /** Use to stop listening to networking binary events */
13270
+ private static _didLogStopListenHint;
13271
+ stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | Function | null): void;
13272
+ /** Use to start listening to networking binary events.
13273
+ * Returns an unsubscribe function that removes the listener when called.
13274
+ * The returned function can also be passed to {@link stopListenBinary} or {@link Component.autoCleanup}.
13275
+ */
13276
+ beginListenBinary(identifier: string, callback: BinaryCallback): DisposeFn;
13277
+ /** Use to stop listening to networking binary events.
13278
+ * Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
13279
+ */
12678
13280
  stopListenBinary(identifier: string, callback: any): void;
12679
13281
  private netWebSocketUrlProvider?;
12680
13282
  /** Use to override the networking server backend url.
@@ -12683,16 +13285,19 @@ export declare class NetworkConnection implements INetworkConnection {
12683
13285
  registerProvider(prov: INetworkingWebsocketUrlProvider): void;
12684
13286
  /** Used to connect to the networking server
12685
13287
  * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
13288
+ * @param transport Optional custom transport to use instead of the default websocket. Useful for testing or alternative transports.
12686
13289
  */
12687
- connect(url?: string): Promise<boolean>;
13290
+ connect(url?: string, transport?: INetworkTransport): Promise<boolean>;
12688
13291
  /** Disconnect from the networking backend + reset internal state */
12689
13292
  disconnect(): void;
13293
+ /** Full teardown: disconnect, clear all listeners, and release all resources.
13294
+ * Called when the owning Context is destroyed. After dispose(), this instance should not be reused. */
13295
+ dispose(): void;
12690
13296
  private _listeners;
12691
13297
  private _listenersBinary;
12692
13298
  private connected;
12693
- private channelId;
12694
13299
  private _connectionId;
12695
- private _ws;
13300
+ private _transport;
12696
13301
  private _waitingForSocket;
12697
13302
  private _isInRoom;
12698
13303
  private _currentRoomName;
@@ -12702,6 +13307,8 @@ export declare class NetworkConnection implements INetworkConnection {
12702
13307
  private _state;
12703
13308
  private _currentDelay;
12704
13309
  private _connectingToWebsocketPromise;
13310
+ /** Wire up a transport's event callbacks and start it */
13311
+ private connectTransport;
12705
13312
  private connectWebsocket;
12706
13313
  private onMessage;
12707
13314
  private handleIncomingBinaryMessage;
@@ -12830,7 +13437,7 @@ export declare interface NetworkEventMap {
12830
13437
  * @see {@link RoomEvents} for room lifecycle events
12831
13438
  * @see {@link isLocalNetwork} for local network detection
12832
13439
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
12833
- * @summary Networking configuration
13440
+ * @summary Configures the websocket server URL for multiplayer networking
12834
13441
  * @category Networking
12835
13442
  * @group Components
12836
13443
  */
@@ -12967,7 +13574,7 @@ export declare type OBJ = {
12967
13574
  scenes: Object3D[];
12968
13575
  };
12969
13576
 
12970
- declare type ObjectCloneReference = {
13577
+ export declare type ObjectCloneReference = {
12971
13578
  readonly original: object;
12972
13579
  readonly clone: object;
12973
13580
  };
@@ -13174,6 +13781,61 @@ export declare function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void):
13174
13781
  */
13175
13782
  export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
13176
13783
 
13784
+ /**
13785
+ * @experimental
13786
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
13787
+ * and return an {@link IDisposable} that removes the listener when disposed.
13788
+ *
13789
+ * Provides full TypeScript event type inference — the callback parameter
13790
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
13791
+ * `"click"` → `MouseEvent`).
13792
+ *
13793
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
13794
+ *
13795
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
13796
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
13797
+ * @param listener The event handler callback
13798
+ * @param options Optional addEventListener options (passive, capture, once, signal)
13799
+ * @returns An {@link IDisposable} that removes the event listener when disposed
13800
+ *
13801
+ * @example Standalone usage
13802
+ * ```ts
13803
+ * import { on } from "@needle-tools/engine";
13804
+ *
13805
+ * const sub = on(window, "resize", (ev) => {
13806
+ * // ev is typed as UIEvent
13807
+ * console.log("resized", ev.target);
13808
+ * });
13809
+ *
13810
+ * // Later: clean up
13811
+ * sub.dispose();
13812
+ * ```
13813
+ *
13814
+ * @example With autoCleanup in a component
13815
+ * ```ts
13816
+ * import { Behaviour, on } from "@needle-tools/engine";
13817
+ *
13818
+ * export class MyComponent extends Behaviour {
13819
+ * onEnable() {
13820
+ * this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
13821
+ * this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
13822
+ * this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
13823
+ * }
13824
+ * // All listeners removed automatically on disable!
13825
+ * }
13826
+ * ```
13827
+ *
13828
+ * @category Utilities
13829
+ * @group Lifecycle
13830
+ */
13831
+ export declare function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13832
+
13833
+ export declare function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13834
+
13835
+ export declare function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13836
+
13837
+ export declare function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
13838
+
13177
13839
  /**
13178
13840
  * Register a callback in the engine onAfterRender event
13179
13841
  * This is called every frame after the main camera has rendered
@@ -13814,8 +14476,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
13814
14476
  * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
13815
14477
  */
13816
14478
  fitCamera(options?: OrbitFitCameraOptions): any;
13817
- /** @deprecated Use fitCamera(options) */
13818
- fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">): any;
13819
14479
  private _haveAttachedKeyboardEvents;
13820
14480
  }
13821
14481
 
@@ -14016,6 +14676,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
14016
14676
  value: number | boolean | string;
14017
14677
  };
14018
14678
 
14679
+ /** Extracts parameter names of a given type from the builder's tracked parameter map */
14680
+ declare type ParamNamesOfType<TParams, PType extends string> = {
14681
+ [K in keyof TParams & string]: TParams[K] extends PType ? K : never;
14682
+ }[keyof TParams & string];
14683
+
14019
14684
  declare type ParseNumber<T> = T extends `${infer U extends number}` ? U : never;
14020
14685
 
14021
14686
  /** Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.
@@ -14647,13 +15312,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14647
15312
  * The timeline asset containing tracks, clips, and markers that this director will play.
14648
15313
  * Assign a timeline asset exported from Unity or Blender to enable playback.
14649
15314
  */
14650
- playableAsset?: Models.TimelineAssetModel;
15315
+ get playableAsset(): Models.TimelineAssetModel | undefined;
15316
+ set playableAsset(value: Models.TimelineAssetModel | undefined);
15317
+ private _playableAsset?;
14651
15318
  /**
14652
15319
  * When true, the timeline starts playing automatically when the component awakens.
14653
15320
  * Set to false to control playback manually via `play()`.
14654
15321
  * @default false
14655
15322
  */
14656
- playOnAwake?: boolean;
15323
+ playOnAwake: boolean;
14657
15324
  /**
14658
15325
  * Determines how the timeline behaves when it reaches the end of its duration.
14659
15326
  * @default DirectorWrapMode.Loop
@@ -14731,15 +15398,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14731
15398
  /** Iterates over all tracks of the timeline
14732
15399
  * @returns all tracks of the timeline
14733
15400
  */
14734
- forEachTrack(): Generator<Tracks.TrackHandler, void, unknown>;
15401
+ forEachTrack(): Generator<Tracks.TimelineTrackHandler, void, unknown>;
14735
15402
  /**
14736
15403
  * @returns all animation tracks of the timeline
14737
15404
  */
14738
- get animationTracks(): Tracks.AnimationTrackHandler[];
15405
+ get animationTracks(): Tracks.TimelineAnimationTrack[];
14739
15406
  /**
14740
15407
  * @returns all audio tracks of the timeline
14741
15408
  */
14742
- get audioTracks(): Tracks.AudioTrackHandler[];
15409
+ get audioTracks(): Tracks.TimelineAudioTrack[];
14743
15410
  /**
14744
15411
  * @returns all signal tracks of the timeline
14745
15412
  */
@@ -14747,7 +15414,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14747
15414
  /**
14748
15415
  * @returns all marker tracks of the timeline
14749
15416
  */
14750
- get markerTracks(): Tracks.MarkerTrackHandler[];
15417
+ get markerTracks(): Tracks.TimelineMarkerTrack[];
15418
+ /**
15419
+ * @returns all activation tracks of the timeline
15420
+ */
15421
+ get activationTracks(): Tracks.TimelineActivationTrack[];
15422
+ /**
15423
+ * @returns all tracks of the timeline
15424
+ */
15425
+ get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler>;
14751
15426
  /**
14752
15427
  * Iterates over all markers of the timeline, optionally filtering by type
14753
15428
  *
@@ -14761,13 +15436,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
14761
15436
  *
14762
15437
  */
14763
15438
  foreachMarker<T extends Record<string, any>>(type?: string | null): Generator<(T & Models.MarkerModel)>;
14764
- private _guidsMap?;
14765
- /* Excluded from this release type: resolveGuids */
15439
+ private _needsGraphRebuild;
14766
15440
  private _isPlaying;
14767
15441
  private _internalUpdateRoutine;
14768
15442
  private _isPaused;
14769
15443
  /** internal, true during the time stop() is being processed */
14770
15444
  private _isStopping;
15445
+ /* Excluded from this release type: _isUserEvaluation */
14771
15446
  private _time;
14772
15447
  private _duration;
14773
15448
  private _weight;
@@ -14776,6 +15451,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
14776
15451
  private readonly _signalTracks;
14777
15452
  private readonly _markerTracks;
14778
15453
  private readonly _controlTracks;
15454
+ private readonly _activationTracks;
14779
15455
  private readonly _customTracks;
14780
15456
  private readonly _tracksArray;
14781
15457
  private get _allTracks();
@@ -15767,6 +16443,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
15767
16443
  w: number;
15768
16444
  };
15769
16445
 
16446
+ /** A Quaternion value, either as a Three.js Quaternion or as a `[x, y, z, w]` tuple */
16447
+ declare type QuatValue = Quaternion | [number, number, number, number];
16448
+
15770
16449
  /** Generates a random number
15771
16450
  * @deprecated use Mathf.random(min, max)
15772
16451
  */
@@ -15892,6 +16571,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
15892
16571
  * @default undefined
15893
16572
  */
15894
16573
  useIgnoreRaycastLayer?: boolean;
16574
+ /** When true, trigger/sensor colliders will be included in the raycast results.
16575
+ * By default trigger colliders are skipped.
16576
+ * @default false
16577
+ */
16578
+ includeTriggers?: boolean;
15895
16579
  }): null | {
15896
16580
  point: Vector3;
15897
16581
  collider: ICollider;
@@ -15909,6 +16593,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
15909
16593
  * @default undefined
15910
16594
  */
15911
16595
  useIgnoreRaycastLayer?: boolean;
16596
+ /** When true, trigger/sensor colliders will be included in the raycast results.
16597
+ * By default trigger colliders are skipped.
16598
+ * @default false
16599
+ */
16600
+ includeTriggers?: boolean;
15912
16601
  }): null | {
15913
16602
  point: Vector3;
15914
16603
  normal: Vector3;
@@ -15954,6 +16643,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
15954
16643
  private _gravity;
15955
16644
  get gravity(): Vec3;
15956
16645
  set gravity(value: Vec3);
16646
+ /** Tears down the physics world and frees all WASM resources.
16647
+ * After calling this, the world will be re-created on next use. */
16648
+ dispose(): void;
16649
+ /** @deprecated Use {@link dispose} instead. */
15957
16650
  clearCaches(): void;
15958
16651
  addBoxCollider(collider: ICollider, size: Vector3): Promise<void>;
15959
16652
  addSphereCollider(collider: ICollider): Promise<void>;
@@ -16000,7 +16693,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16000
16693
  private getRigidbodyRelativeMatrix;
16001
16694
  private static centerConnectionPos;
16002
16695
  private static centerConnectionRot;
16003
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): void;
16696
+ private _jointTempMatrix;
16697
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<ImpulseJoint | null>;
16004
16698
  /** The joint prevents any relative movement between two rigid-bodies, except for relative rotations along one axis. This is typically used to simulate wheels, fans, etc. They are characterized by one local anchor as well as one local axis on each rigid-body. */
16005
16699
  addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: {
16006
16700
  x: number;
@@ -16010,8 +16704,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
16010
16704
  x: number;
16011
16705
  y: number;
16012
16706
  z: number;
16013
- }): void;
16707
+ }): Promise<ImpulseJoint | null>;
16708
+ removeJoint(joint: ImpulseJoint): void;
16709
+ /** Compute the relative transform from body1's local space to body2's local space (W2⁻¹ * W1), ignoring scale. */
16014
16710
  private calculateJointRelativeMatrices;
16711
+ private normalizeMatrixColumns;
16015
16712
  }
16016
16713
 
16017
16714
  /**
@@ -16814,10 +17511,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
16814
17511
  */
16815
17512
  export declare class Rigidbody extends Component implements IRigidbody {
16816
17513
  get isRigidbody(): boolean;
16817
- /** When true the mass will be automatically calculated by the attached colliders */
17514
+ /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
17515
+ * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
17516
+ * Disable to set mass explicitly via the `mass` property.
17517
+ */
16818
17518
  autoMass: boolean;
16819
- /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes
16820
- * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
17519
+ /** The mass of the rigidbody in kg (when `autoMass` is disabled).
17520
+ * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
17521
+ * Setting this property automatically disables `autoMass`.
17522
+ *
17523
+ * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
17524
+ * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
16821
17525
  */
16822
17526
  set mass(value: number);
16823
17527
  get mass(): number;
@@ -16900,7 +17604,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16900
17604
  onEnable(): void;
16901
17605
  onDisable(): void;
16902
17606
  onDestroy(): void;
16903
- onValidate(): void;
17607
+ onValidate(property?: string): void;
17608
+ private static _didWarnAutoMass;
16904
17609
  beforePhysics(): Generator<undefined, void, unknown>;
16905
17610
  /** Teleport the rigidbody to a new position in the world.
16906
17611
  * Will reset forces before setting the object world position
@@ -18120,10 +18825,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
18120
18825
 
18121
18826
  export declare function sendDestroyed(guid: string, con: INetworkConnection, opts?: SyncDestroyOptions): void;
18122
18827
 
18828
+ /** Controls when a network message is actually sent to the server.
18829
+ * @see {@link NetworkConnection.send}
18830
+ */
18123
18831
  export declare enum SendQueue {
18832
+ /** Hold the message until the transport connection opens, then send it. Use for messages that must arrive as soon as the socket is ready (e.g. join-room). */
18124
18833
  OnConnection = 0,
18834
+ /** Hold the message until the client has joined a room, then send it. Use for messages that require room context. */
18125
18835
  OnRoomJoin = 1,
18836
+ /** Buffer the message and send it on the next `sendBufferedMessagesNow()` call (typically once per frame). This is the default for `send()`. */
18126
18837
  Queued = 2,
18838
+ /** Send the message to the server immediately without buffering. */
18127
18839
  Immediate = 3
18128
18840
  }
18129
18841
 
@@ -18556,6 +19268,16 @@ export declare class OrbitControls extends Component implements ICameraControlle
18556
19268
  asset: string;
18557
19269
  }
18558
19270
 
19271
+ /**
19272
+ * Options for a signal marker in the timeline builder
19273
+ */
19274
+ export declare type SignalMarkerOptions = {
19275
+ /** Whether the signal should fire if the playback starts past its time (default: false) */
19276
+ retroActive?: boolean;
19277
+ /** Whether the signal should only fire once (default: false) */
19278
+ emitOnce?: boolean;
19279
+ };
19280
+
18559
19281
  /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received.
18560
19282
  * Signals can be added to a signal track on a {@link PlayableDirector}
18561
19283
  *
@@ -18563,7 +19285,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
18563
19285
  * @category Animation and Sequencing
18564
19286
  * @group Components
18565
19287
  */
18566
- export declare class SignalReceiver extends Component {
19288
+ export declare class SignalReceiver extends Component implements ISignalReceiver {
19289
+ readonly isSignalReceiver = true;
18567
19290
  private static receivers;
18568
19291
  static invoke(guid: string): void;
18569
19292
  events?: SignalReceiverEvent[];
@@ -18582,10 +19305,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
18582
19305
  reaction: EventList<void>;
18583
19306
  }
18584
19307
 
18585
- export declare class SignalTrackHandler extends TrackHandler {
19308
+ /**
19309
+ * Builder for signal tracks. Provides `.signal()` for callback-based signals and `.marker()` for asset-based markers.
19310
+ * @category Animation and Sequencing
19311
+ */
19312
+ export declare interface SignalTrackBuilder extends TimelineBuilderBase {
19313
+ /** Adds a signal with a callback that fires at the given time */
19314
+ signal(time: number, callback: Function, options?: SignalMarkerOptions): SignalTrackBuilder;
19315
+ /** Adds a signal marker referencing a signal asset by guid */
19316
+ marker(time: number, asset: string, options?: SignalMarkerOptions): SignalTrackBuilder;
19317
+ /** Mutes this track so it is skipped during playback */
19318
+ muted(muted?: boolean): SignalTrackBuilder;
19319
+ }
19320
+
19321
+ export declare class SignalTrackHandler extends TimelineTrackHandler {
18586
19322
  models: Models.SignalMarkerModel[];
18587
19323
  didTrigger: boolean[];
18588
19324
  receivers: Array<SignalReceiver | null>;
19325
+ private _lastTime;
19326
+ onEnable(): void;
19327
+ onMuteChanged(): void;
18589
19328
  evaluate(time: number): void;
18590
19329
  }
18591
19330
 
@@ -19085,10 +19824,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
19085
19824
  * Removes scale change monitoring when the collider is disabled.
19086
19825
  */
19087
19826
  onDisable(): void;
19088
- /**
19089
- * Updates collider properties when validated in the editor or inspector.
19090
- */
19091
- onValidate(): void;
19092
19827
  }
19093
19828
 
19094
19829
  export declare class SphereIntersection implements Intersection {
@@ -19841,8 +20576,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
19841
20576
  * Configuration for an animation state in the builder
19842
20577
  */
19843
20578
  export declare type StateOptions = {
19844
- /** The animation clip for this state */
19845
- clip: AnimationClip;
20579
+ /**
20580
+ * The animation clip for this state. Accepts:
20581
+ * - A pre-built `AnimationClip`
20582
+ * - A single {@link TrackDescriptor} from {@link track}
20583
+ * - An array of {@link TrackDescriptor}s (multiple tracks combined into one clip)
20584
+ *
20585
+ * When omitted, use {@link AnimatorControllerBuilder.track .track()} to define animation tracks inline.
20586
+ */
20587
+ clip?: AnimationClip | TrackDescriptor | TrackDescriptor[];
19846
20588
  /** Whether the animation should loop (default: false) */
19847
20589
  loop?: boolean;
19848
20590
  /** Base speed multiplier (default: 1) */
@@ -20408,6 +21150,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
20408
21150
  set font(val: string | null);
20409
21151
  get font(): string | null;
20410
21152
  private _font;
21153
+ private _assignedAtRuntime;
20411
21154
  /**
20412
21155
  * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
20413
21156
  * @default false
@@ -20663,6 +21406,57 @@ export declare class OrbitControls extends Component implements ICameraControlle
20663
21406
  /* Excluded from this release type: update */
20664
21407
  }
20665
21408
 
21409
+ /**
21410
+ * Handles activation (visibility) of bound objects for a timeline activation track.
21411
+ *
21412
+ * Each clip on the track defines a time range during which the bound objects should be active (visible).
21413
+ * @see TimelineTrackHandler for details on how tracks and clips work in general, and how to mutate them at runtime.
21414
+ * @see PlayableDirector for how to control timeline playback and time.
21415
+ * @see TimelineBuilder for how to create and configure timelines and tracks in the editor.
21416
+ */
21417
+ export declare class TimelineActivationTrack extends TimelineTrackHandler {
21418
+ evaluate(time: number): void;
21419
+ }
21420
+
21421
+ export declare class TimelineAnimationTrack extends TimelineTrackHandler {
21422
+ /* Excluded from this release type: models */
21423
+ /* Excluded from this release type: trackOffset */
21424
+ /** The object that is being animated. */
21425
+ target?: Object3D;
21426
+ /** The AnimationMixer, should be shared with the animator if an animator is bound */
21427
+ mixer?: AnimationMixer;
21428
+ clips: Array<AnimationClip>;
21429
+ actions: Array<AnimationAction>;
21430
+ /**
21431
+ * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
21432
+ * @default 1
21433
+ */
21434
+ weight: number;
21435
+ /** holds data/info about clips differences */
21436
+ private _actionOffsets;
21437
+ private _didBind;
21438
+ private _animator;
21439
+ onDisable(): void;
21440
+ onDestroy(): void;
21441
+ onStateChanged(): void;
21442
+ createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
21443
+ bind(): void;
21444
+ private ensureTrackOffsets;
21445
+ private _useclipOffsets;
21446
+ private _totalOffsetPosition;
21447
+ private _totalOffsetRotation;
21448
+ private _totalOffsetPosition2;
21449
+ private _totalOffsetRotation2;
21450
+ private _summedPos;
21451
+ private _tempPos;
21452
+ private _summedRot;
21453
+ private _tempRot;
21454
+ private _clipRotQuat;
21455
+ evaluate(time: number): void;
21456
+ private createRotationInterpolant;
21457
+ private createPositionInterpolant;
21458
+ }
21459
+
20666
21460
  /**
20667
21461
  * @category Animation and Sequencing
20668
21462
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -20672,6 +21466,325 @@ export declare class OrbitControls extends Component implements ICameraControlle
20672
21466
  tracks: TrackModel[];
20673
21467
  };
20674
21468
 
21469
+ /**
21470
+ * Handles audio playback for a timeline audio track.
21471
+ *
21472
+ * **Runtime mutation:** The track model is read fresh every frame during `evaluate()`.
21473
+ * You can mutate `track.volume`, `clip.start`, `clip.end`, `clip.asset.volume` etc.
21474
+ * at any time — changes take effect on the next frame without rebuilding the timeline.
21475
+ *
21476
+ * **Audio stopping:** Audio clips are automatically stopped when:
21477
+ * - Timeline time moves outside a clip's `[start, end]` range (e.g. jumping or normal playback advancing past a clip)
21478
+ * - The track is muted (via `muted = true`)
21479
+ * - The director is stopped (`director.stop()`)
21480
+ * - The director is paused (`director.pause()`)
21481
+ * - The director is disabled or destroyed
21482
+ */
21483
+ export declare class TimelineAudioTrack extends TimelineTrackHandler {
21484
+ models: Array<AudioClipModel_2>;
21485
+ listener: AudioListener_3;
21486
+ audio: Array<Audio_2>;
21487
+ audioContextTimeOffset: Array<number>;
21488
+ lastTime: number;
21489
+ audioSource?: AudioSource;
21490
+ /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
21491
+ get volume(): number;
21492
+ set volume(val: number);
21493
+ private _audioLoader;
21494
+ private getAudioFilePath;
21495
+ onAllowAudioChanged(allow: boolean): void;
21496
+ addModel(model: Models.ClipModel): void;
21497
+ onDisable(): void;
21498
+ onDestroy(): void;
21499
+ onMuteChanged(): void;
21500
+ stop(): void;
21501
+ private _playableDirectorResumed;
21502
+ onPauseChanged(): void;
21503
+ evaluate(time: number): void;
21504
+ /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
21505
+ loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
21506
+ private isInTimeRange;
21507
+ private static _audioBuffers;
21508
+ static dispose(): void;
21509
+ private handleAudioLoading;
21510
+ }
21511
+
21512
+ /**
21513
+ * A fluent builder for creating timeline assets ({@link TimelineAssetModel}) from code.
21514
+ *
21515
+ * Use {@link TimelineBuilder.create} to start building a timeline.
21516
+ *
21517
+ * @example Using build() for timelines without signal callbacks
21518
+ * ```ts
21519
+ * const timeline = TimelineBuilder.create("MySequence")
21520
+ * .animationTrack("Character", animator)
21521
+ * .clip(walkClip, { duration: 2, easeIn: 0.3 })
21522
+ * .clip(runClip, { duration: 3, easeIn: 0.5, easeOut: 0.5 })
21523
+ * .activationTrack("FX", particleObject)
21524
+ * .clip({ start: 1, duration: 2 })
21525
+ * .audioTrack("Music", audioSource)
21526
+ * .clip("music.mp3", { start: 0, duration: 5, volume: 0.8 })
21527
+ * .build();
21528
+ *
21529
+ * director.playableAsset = timeline;
21530
+ * director.play();
21531
+ * ```
21532
+ *
21533
+ * @example With inline tracks (no pre-built clips needed)
21534
+ * ```ts
21535
+ * TimelineBuilder.create("DoorSequence")
21536
+ * .animationTrack("Door", door)
21537
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
21538
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
21539
+ * .signalTrack("Events")
21540
+ * .signal(0.5, () => playSound("creak"))
21541
+ * .install(director);
21542
+ *
21543
+ * director.play();
21544
+ * ```
21545
+ *
21546
+ * @example Using install() with signal callbacks
21547
+ * ```ts
21548
+ * TimelineBuilder.create("WithSignals")
21549
+ * .animationTrack("Character", animator)
21550
+ * .clip(walkClip, { duration: 2 })
21551
+ * .signalTrack("Events")
21552
+ * .signal(1.0, () => console.log("1 second!"))
21553
+ * .signal(2.0, () => spawnParticles())
21554
+ * .install(director);
21555
+ *
21556
+ * director.play();
21557
+ * ```
21558
+ *
21559
+ * @category Animation and Sequencing
21560
+ * @group Utilities
21561
+ */
21562
+ export declare class TimelineBuilder {
21563
+ private _name;
21564
+ private _tracks;
21565
+ private _currentTrack;
21566
+ private _pendingSignals;
21567
+ private _idProvider;
21568
+ private constructor();
21569
+ /**
21570
+ * Creates a new TimelineBuilder instance.
21571
+ * @param name - Name for the timeline asset
21572
+ * @param seed - Optional numeric seed for deterministic guid generation. Defaults to `Date.now()`.
21573
+ */
21574
+ static create(name?: string, seed?: number): TimelineBuilderBase;
21575
+ /**
21576
+ * Adds an animation track. Chain `.clip()` calls to add pre-built clips,
21577
+ * or chain `.track()` calls to define animation data inline:
21578
+ *
21579
+ * @example With pre-built AnimationClip
21580
+ * ```ts
21581
+ * .animationTrack("Character", animator)
21582
+ * .clip(walkClip, { duration: 2, easeIn: 0.3 })
21583
+ * .clip(runClip, { duration: 3 })
21584
+ * ```
21585
+ *
21586
+ * @example With inline tracks
21587
+ * ```ts
21588
+ * .animationTrack("Door", door)
21589
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
21590
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
21591
+ * ```
21592
+ *
21593
+ * @param name - Display name for the track
21594
+ * @param binding - The Animator or Object3D to animate
21595
+ */
21596
+ animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
21597
+ /**
21598
+ * Adds an audio track. Subsequent `.clip()` calls add audio clips to this track.
21599
+ * @param name - Display name for the track
21600
+ * @param binding - The AudioSource to play audio on (optional)
21601
+ * @param volume - Track volume multiplier (default: 1)
21602
+ */
21603
+ audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
21604
+ /**
21605
+ * Adds an activation track. Subsequent `.clip()` calls define when the bound object is active.
21606
+ * @param name - Display name for the track
21607
+ * @param binding - The Object3D to show/hide
21608
+ */
21609
+ activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
21610
+ /**
21611
+ * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
21612
+ * @param name - Display name for the track
21613
+ */
21614
+ controlTrack(name: string): ControlTrackBuilder;
21615
+ /**
21616
+ * Adds a signal track. Use `.signal()` or `.marker()` to add signal markers.
21617
+ * @param name - Display name for the track
21618
+ * @param binding - The SignalReceiver component (optional — if using `.signal()` with callbacks, one is created automatically by {@link install})
21619
+ */
21620
+ signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
21621
+ /**
21622
+ * Adds a marker track. Use `.marker()` to add markers.
21623
+ * @param name - Display name for the track
21624
+ */
21625
+ markerTrack(name: string): MarkerTrackBuilder;
21626
+ /**
21627
+ * Adds a clip to the current track. The clip type must match the track type.
21628
+ *
21629
+ * - On an **animation track**: pass an `AnimationClip`, a {@link TrackDescriptor}, or a `TrackDescriptor[]` — and optional {@link AnimationClipOptions}
21630
+ * - On an **audio track**: pass a clip URL (string) and {@link AudioClipOptions}
21631
+ * - On an **activation track**: pass {@link ActivationClipOptions}
21632
+ * - On a **control track**: pass an Object3D and {@link ControlClipOptions}
21633
+ */
21634
+ clip(asset: AnimationClip, options?: AnimationClipOptions): this;
21635
+ clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): this;
21636
+ clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): this;
21637
+ clip(url: string, options: AudioClipOptions): this;
21638
+ clip(options: ActivationClipOptions): this;
21639
+ clip(sourceObject: Object3D, options: ControlClipOptions): this;
21640
+ /**
21641
+ * Adds a signal marker to the current signal or marker track.
21642
+ * @param time - Time in seconds when the signal fires
21643
+ * @param asset - The signal asset identifier (guid string)
21644
+ * @param options - Optional marker configuration
21645
+ */
21646
+ marker(time: number, asset: string, options?: SignalMarkerOptions): this;
21647
+ /**
21648
+ * Adds a signal with a callback to the current signal track.
21649
+ * This is a convenience method that automatically generates a signal asset guid,
21650
+ * adds the marker, and registers the callback so that {@link install} can wire up
21651
+ * the `SignalReceiver` on the director's GameObject.
21652
+ *
21653
+ * @param time - Time in seconds when the signal fires
21654
+ * @param callback - The function to invoke when the signal fires
21655
+ * @param options - Optional marker configuration
21656
+ *
21657
+ * @example
21658
+ * ```ts
21659
+ * const timeline = TimelineBuilder.create("Sequence")
21660
+ * .signalTrack("Events")
21661
+ * .signal(1.0, () => console.log("1 second reached!"))
21662
+ * .signal(3.5, () => console.log("halfway!"), { emitOnce: true })
21663
+ * .install(director);
21664
+ * ```
21665
+ */
21666
+ signal(time: number, callback: Function, options?: SignalMarkerOptions): this;
21667
+ /**
21668
+ * Mutes the current track so it is skipped during playback.
21669
+ */
21670
+ muted(muted?: boolean): this;
21671
+ /** Adds an animation track descriptor for an Object3D's position or scale to the current animation track */
21672
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): this;
21673
+ /** Adds an animation track descriptor for an Object3D's quaternion to the current animation track */
21674
+ track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): this;
21675
+ /** Adds an animation track descriptor for an Object3D's rotation (Euler, converted to quaternion) to the current animation track */
21676
+ track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): this;
21677
+ /** Adds an animation track descriptor for an Object3D's visibility to the current animation track */
21678
+ track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): this;
21679
+ /** Adds an animation track descriptor for a material's numeric property to the current animation track */
21680
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): this;
21681
+ /** Adds an animation track descriptor for a material's color property to the current animation track */
21682
+ track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
21683
+ /** Adds an animation track descriptor for a light's numeric property to the current animation track */
21684
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): this;
21685
+ /** Adds an animation track descriptor for a light's color to the current animation track */
21686
+ track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
21687
+ /** Adds an animation track descriptor for a camera's numeric property to the current animation track */
21688
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): this;
21689
+ /**
21690
+ * Builds and returns the {@link TimelineAssetModel}.
21691
+ * Assign the result to `PlayableDirector.playableAsset` to play it.
21692
+ *
21693
+ * If you used `.signal()` with callbacks, use {@link install} instead — it calls `build()`
21694
+ * internally and also wires up the SignalReceiver on the director's GameObject.
21695
+ */
21696
+ build(): TimelineAssetModel;
21697
+ /**
21698
+ * Builds the timeline asset, assigns it to the director, and wires up any
21699
+ * `.signal()` callbacks by creating/configuring a {@link SignalReceiver} on the
21700
+ * director's GameObject.
21701
+ *
21702
+ * @param director - The PlayableDirector to install the timeline on
21703
+ * @returns The built TimelineAssetModel (also assigned to `director.playableAsset`)
21704
+ *
21705
+ * @example
21706
+ * ```ts
21707
+ * TimelineBuilder.create("MyTimeline")
21708
+ * .animationTrack("Anim", animator)
21709
+ * .clip(walkClip, { duration: 2 })
21710
+ * .signalTrack("Events")
21711
+ * .signal(1.0, () => console.log("signal fired!"))
21712
+ * .install(director);
21713
+ *
21714
+ * director.play();
21715
+ * ```
21716
+ */
21717
+ install(director: PlayableDirector): TimelineAssetModel;
21718
+ private pushTrack;
21719
+ /** Commits any pending `.track()` descriptors on the current animation track into a clip */
21720
+ private commitInlineTracks;
21721
+ }
21722
+
21723
+ /**
21724
+ * Shared methods available on all track builders and the TimelineBuilder entry point.
21725
+ * Provides track creation, build, and install methods.
21726
+ *
21727
+ * @category Animation and Sequencing
21728
+ */
21729
+ export declare interface TimelineBuilderBase {
21730
+ /** Adds an animation track. Chain `.clip()` or `.track()` to add content. */
21731
+ animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
21732
+ /** Adds an audio track. Chain `.clip()` to add audio clips. */
21733
+ audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
21734
+ /** Adds an activation track. Chain `.clip()` to define activation windows. */
21735
+ activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
21736
+ /** Adds a control track. Chain `.clip()` to control nested objects/timelines. */
21737
+ controlTrack(name: string): ControlTrackBuilder;
21738
+ /** Adds a signal track. Chain `.signal()` or `.marker()` to add events. */
21739
+ signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
21740
+ /** Adds a marker track. Chain `.marker()` to add markers. */
21741
+ markerTrack(name: string): MarkerTrackBuilder;
21742
+ /** Builds and returns the {@link TimelineAssetModel}. */
21743
+ build(): TimelineAssetModel;
21744
+ /** Builds the timeline, assigns it to the director, and wires up signal callbacks. */
21745
+ install(director: PlayableDirector): TimelineAssetModel;
21746
+ }
21747
+
21748
+ export declare class TimelineControlTrack extends TimelineTrackHandler {
21749
+ models: Array<Models.ClipModel>;
21750
+ timelines: Array<PlayableDirector | null>;
21751
+ resolveSourceObjects(_context: Context): void;
21752
+ private _previousActiveModel;
21753
+ evaluate(time: number): void;
21754
+ }
21755
+
21756
+ export declare class TimelineMarkerTrack extends TimelineTrackHandler {
21757
+ models: Array<Models.MarkerModel & Record<string, any>>;
21758
+ needsSorting: boolean;
21759
+ foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
21760
+ onEnable(): void;
21761
+ evaluate(_time: number): void;
21762
+ private sort;
21763
+ }
21764
+
21765
+ /**
21766
+ * A TrackHandler is responsible for evaluating a specific type of timeline track.
21767
+ * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
21768
+ */
21769
+ export declare abstract class TimelineTrackHandler {
21770
+ director: PlayableDirector;
21771
+ track: Models.TrackModel;
21772
+ get muted(): boolean;
21773
+ set muted(val: boolean);
21774
+ forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
21775
+ onEnable?(): any;
21776
+ onDisable?(): any;
21777
+ onDestroy?(): any;
21778
+ abstract evaluate(time: number): any;
21779
+ onMuteChanged?(): any;
21780
+ onPauseChanged?(): any;
21781
+ /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
21782
+ onStateChanged?(isPlaying: boolean): any;
21783
+ getClipTime(time: number, model: Models.ClipModel): number;
21784
+ getClipTimeNormalized(time: number, model: Models.ClipModel): number;
21785
+ evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
21786
+ }
21787
+
20675
21788
  declare type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
20676
21789
 
20677
21790
  /**
@@ -20700,27 +21813,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
20700
21813
  export declare function toSourceId(src: string | null): SourceIdentifier | undefined;
20701
21814
 
20702
21815
  /**
20703
- * A TrackHandler is responsible for evaluating a specific type of timeline track.
20704
- * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
21816
+ * An opaque descriptor for a single animation track.
21817
+ * Created by {@link track} and resolved into a Three.js KeyframeTrack
21818
+ * when passed to {@link createAnimation}, or inline to
21819
+ * {@link AnimatorControllerBuilder.state} / {@link TimelineBuilder.clip}.
21820
+ *
21821
+ * @category Animation and Sequencing
20705
21822
  */
20706
- export declare abstract class TrackHandler {
20707
- director: PlayableDirector;
20708
- track: Models.TrackModel;
20709
- get muted(): boolean;
20710
- set muted(val: boolean);
20711
- forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
20712
- onEnable?(): any;
20713
- onDisable?(): any;
20714
- onDestroy?(): any;
20715
- abstract evaluate(time: number): any;
20716
- onMuteChanged?(): any;
20717
- onPauseChanged?(): any;
20718
- /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
20719
- onStateChanged?(isPlaying: boolean): any;
20720
- getClipTime(time: number, model: Models.ClipModel): number;
20721
- getClipTimeNormalized(time: number, model: Models.ClipModel): number;
20722
- evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
20723
- }
21823
+ declare type TrackDescriptor = {
21824
+ readonly __isTrackDescriptor: true;
21825
+ /* Excluded from this release type: _target */
21826
+ /* Excluded from this release type: _property */
21827
+ /* Excluded from this release type: _keyframes */
21828
+ /* Excluded from this release type: _root */
21829
+ };
20724
21830
 
20725
21831
  /**
20726
21832
  * @category Animation and Sequencing
@@ -20746,14 +21852,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
20746
21852
  rotation: Quat | Quaternion;
20747
21853
  };
20748
21854
 
21855
+ /** Options for a single track */
21856
+ declare type TrackOptions = {
21857
+ /**
21858
+ * Root object for resolving the track path.
21859
+ * - If `root === target` → self-targeting (`.property`)
21860
+ * - If `root !== target` → named targeting (`"targetName.property"` using `target.name`)
21861
+ * - If omitted → self-targeting by default
21862
+ */
21863
+ root?: Object3D;
21864
+ };
21865
+
20749
21866
  declare namespace Tracks {
20750
21867
  export {
20751
- TrackHandler,
20752
- AnimationTrackHandler,
20753
- AudioTrackHandler,
20754
- MarkerTrackHandler,
21868
+ TimelineTrackHandler,
21869
+ TimelineAnimationTrack,
21870
+ TimelineAudioTrack,
21871
+ TimelineMarkerTrack,
20755
21872
  SignalTrackHandler,
20756
- ControlTrackHandler
21873
+ TimelineActivationTrack,
21874
+ TimelineControlTrack
20757
21875
  }
20758
21876
  }
20759
21877
 
@@ -20959,10 +22077,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
20959
22077
  export declare type TransitionOptions = {
20960
22078
  /** Duration of the crossfade in seconds (default: 0) */
20961
22079
  duration?: number;
20962
- /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
22080
+ /** Normalized exit time 0-1. When set, the transition waits until the source animation reaches this point before transitioning. */
20963
22081
  exitTime?: number;
20964
- /** Whether the transition waits for exitTime before transitioning (default: false) */
20965
- hasExitTime?: boolean;
20966
22082
  /** Normalized offset into the destination state's animation (default: 0) */
20967
22083
  offset?: number;
20968
22084
  /** Whether duration is in seconds (true) or normalized (false) (default: false) */
@@ -21032,6 +22148,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
21032
22148
 
21033
22149
  export declare function tryGetGuid(obj: any): string | undefined | null;
21034
22150
 
22151
+ /** Shorthand for a simple two-keyframe animation (start → end) */
22152
+ export declare type Tween<V> = {
22153
+ /** Start value (at time 0) */
22154
+ from: V;
22155
+ /** End value (at time = duration) */
22156
+ to: V;
22157
+ /** Duration in seconds (default: 1) */
22158
+ duration?: number;
22159
+ /** Interpolation mode (default: `"linear"`) */
22160
+ interpolation?: AnimationInterpolation;
22161
+ };
22162
+
21035
22163
  declare type Type = new (...args: any[]) => any;
21036
22164
 
21037
22165
  declare type TypeResolver<T> = (data: any) => Constructor<T> | null;
@@ -21555,6 +22683,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
21555
22683
  z: number;
21556
22684
  };
21557
22685
 
22686
+ /** A Vector3 value, either as a Three.js Vector3 or as a `[x, y, z]` tuple */
22687
+ declare type Vec3Value = Vector3 | [number, number, number];
22688
+
21558
22689
  export declare type Vec4 = {
21559
22690
  x: number;
21560
22691
  y: number;
@@ -22476,7 +23607,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
22476
23607
  private onApplyPose;
22477
23608
  }
22478
23609
 
22479
- declare type WebsocketSendType = IModel | object | boolean | null | string | number;
23610
+ declare type WebsocketSendType = IModel | object | boolean | string | number;
22480
23611
 
22481
23612
  /**
22482
23613
  * Use the [WebXR](https://engine.needle.tools/docs/api/WebXR) component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
@@ -23519,28 +24650,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
23519
24650
  export { }
23520
24651
 
23521
24652
 
23522
- declare module 'three' {
23523
- interface SkinnedMesh {
23524
- staticGenerator?: StaticGeometryGenerator;
23525
- staticGeometry?: BufferGeometry;
23526
- staticGeometryLastUpdate?: number;
23527
- }
23528
- interface Mesh {
23529
- acceleratedRaycast?: any;
23530
- }
23531
- interface SkinnedMesh {
23532
- /** @deprecated use autoUpdateMeshBvhInterval */
23533
- autoUpdateMeshBVH?: boolean;
23534
- /**
23535
- * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
23536
- * @default undefined (disabled)
23537
- */
23538
- autoUpdateMeshBvhInterval?: number;
23539
- bvhNeedsUpdate?: boolean;
23540
- }
23541
- }
23542
-
23543
-
23544
24653
  declare module 'three' {
23545
24654
  interface Object3D {
23546
24655
  get guid(): string | undefined;
@@ -23686,3 +24795,25 @@ declare module 'three' {
23686
24795
  slerp(end: Vector3, t: number): Vector3;
23687
24796
  }
23688
24797
  }
24798
+
24799
+
24800
+ declare module 'three' {
24801
+ interface SkinnedMesh {
24802
+ staticGenerator?: StaticGeometryGenerator;
24803
+ staticGeometry?: BufferGeometry;
24804
+ staticGeometryLastUpdate?: number;
24805
+ }
24806
+ interface Mesh {
24807
+ acceleratedRaycast?: any;
24808
+ }
24809
+ interface SkinnedMesh {
24810
+ /** @deprecated use autoUpdateMeshBvhInterval */
24811
+ autoUpdateMeshBVH?: boolean;
24812
+ /**
24813
+ * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
24814
+ * @default undefined (disabled)
24815
+ */
24816
+ autoUpdateMeshBvhInterval?: number;
24817
+ bvhNeedsUpdate?: boolean;
24818
+ }
24819
+ }