@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e7c2511

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 (303) hide show
  1. package/.needle/generated/needle-bindings.gen.d.ts +5 -0
  2. package/CHANGELOG.md +52 -0
  3. package/components.needle.json +1 -1
  4. package/dist/{needle-engine.bundle-B29kieh0.js → needle-engine.bundle-D-eWNCu1.js} +12287 -11802
  5. package/dist/needle-engine.bundle-D3ZUII8o.min.js +1733 -0
  6. package/dist/needle-engine.bundle-_rOpvUGL.umd.cjs +1733 -0
  7. package/dist/needle-engine.d.ts +833 -231
  8. package/dist/needle-engine.js +584 -582
  9. package/dist/needle-engine.min.js +1 -1
  10. package/dist/needle-engine.umd.cjs +1 -1
  11. package/lib/engine/api.d.ts +6 -1
  12. package/lib/engine/api.js +4 -0
  13. package/lib/engine/api.js.map +1 -1
  14. package/lib/engine/codegen/register_types.js +2 -10
  15. package/lib/engine/codegen/register_types.js.map +1 -1
  16. package/lib/engine/debug/debug_spatial_console.d.ts +2 -0
  17. package/lib/engine/debug/debug_spatial_console.js +10 -7
  18. package/lib/engine/debug/debug_spatial_console.js.map +1 -1
  19. package/lib/engine/engine_addressables.d.ts +2 -0
  20. package/lib/engine/engine_addressables.js +6 -3
  21. package/lib/engine/engine_addressables.js.map +1 -1
  22. package/lib/engine/engine_audio.d.ts +68 -0
  23. package/lib/engine/engine_audio.js +172 -0
  24. package/lib/engine/engine_audio.js.map +1 -1
  25. package/lib/engine/engine_components.js +1 -1
  26. package/lib/engine/engine_components.js.map +1 -1
  27. package/lib/engine/engine_context.d.ts +21 -20
  28. package/lib/engine/engine_context.js +27 -16
  29. package/lib/engine/engine_context.js.map +1 -1
  30. package/lib/engine/engine_disposable.d.ts +171 -0
  31. package/lib/engine/engine_disposable.js +136 -0
  32. package/lib/engine/engine_disposable.js.map +1 -0
  33. package/lib/engine/engine_gameobject.d.ts +1 -10
  34. package/lib/engine/engine_gameobject.js +22 -120
  35. package/lib/engine/engine_gameobject.js.map +1 -1
  36. package/lib/engine/engine_gltf_builtin_components.js +7 -69
  37. package/lib/engine/engine_gltf_builtin_components.js.map +1 -1
  38. package/lib/engine/engine_init.js +16 -1
  39. package/lib/engine/engine_init.js.map +1 -1
  40. package/lib/engine/engine_input.d.ts +1 -1
  41. package/lib/engine/engine_input.js +1 -1
  42. package/lib/engine/engine_input.js.map +1 -1
  43. package/lib/engine/engine_instantiate_resolve.d.ts +42 -0
  44. package/lib/engine/engine_instantiate_resolve.js +372 -0
  45. package/lib/engine/engine_instantiate_resolve.js.map +1 -0
  46. package/lib/engine/engine_license.d.ts +2 -0
  47. package/lib/engine/engine_license.js +14 -6
  48. package/lib/engine/engine_license.js.map +1 -1
  49. package/lib/engine/engine_lifecycle_functions_internal.js +5 -0
  50. package/lib/engine/engine_lifecycle_functions_internal.js.map +1 -1
  51. package/lib/engine/engine_mainloop_utils.js +5 -2
  52. package/lib/engine/engine_mainloop_utils.js.map +1 -1
  53. package/lib/engine/engine_networking.js +3 -1
  54. package/lib/engine/engine_networking.js.map +1 -1
  55. package/lib/engine/engine_networking_blob.js +1 -1
  56. package/lib/engine/engine_networking_blob.js.map +1 -1
  57. package/lib/engine/engine_physics_rapier.d.ts +11 -3
  58. package/lib/engine/engine_physics_rapier.js +88 -25
  59. package/lib/engine/engine_physics_rapier.js.map +1 -1
  60. package/lib/engine/engine_pmrem.js +2 -2
  61. package/lib/engine/engine_pmrem.js.map +1 -1
  62. package/lib/engine/engine_scenedata.d.ts +13 -17
  63. package/lib/engine/engine_scenedata.js +58 -31
  64. package/lib/engine/engine_scenedata.js.map +1 -1
  65. package/lib/engine/engine_serialization_builtin_serializer.d.ts +10 -16
  66. package/lib/engine/engine_serialization_builtin_serializer.js +56 -46
  67. package/lib/engine/engine_serialization_builtin_serializer.js.map +1 -1
  68. package/lib/engine/engine_serialization_core.d.ts +1 -0
  69. package/lib/engine/engine_serialization_core.js +7 -0
  70. package/lib/engine/engine_serialization_core.js.map +1 -1
  71. package/lib/engine/engine_ssr.d.ts +2 -0
  72. package/lib/engine/engine_ssr.js +20 -0
  73. package/lib/engine/engine_ssr.js.map +1 -1
  74. package/lib/engine/engine_types.d.ts +19 -9
  75. package/lib/engine/engine_types.js +1 -1
  76. package/lib/engine/engine_types.js.map +1 -1
  77. package/lib/engine/engine_util_decorator.js +7 -2
  78. package/lib/engine/engine_util_decorator.js.map +1 -1
  79. package/lib/engine/engine_utils.d.ts +1 -1
  80. package/lib/engine/engine_utils.js +19 -5
  81. package/lib/engine/engine_utils.js.map +1 -1
  82. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  83. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js.map +1 -1
  84. package/lib/engine/webcomponents/jsx.d.ts +51 -0
  85. package/lib/engine/webcomponents/logo-element.js.map +1 -1
  86. package/lib/engine/webcomponents/needle menu/needle-menu.d.ts +3 -4
  87. package/lib/engine/webcomponents/needle menu/needle-menu.js +1 -1
  88. package/lib/engine/webcomponents/needle menu/needle-menu.js.map +1 -1
  89. package/lib/engine/webcomponents/needle-button.js.map +1 -1
  90. package/lib/engine/webcomponents/needle-engine.d.ts +10 -4
  91. package/lib/engine/webcomponents/needle-engine.js +1 -1
  92. package/lib/engine/webcomponents/needle-engine.js.map +1 -1
  93. package/lib/engine/xr/NeedleXRSession.d.ts +3 -2
  94. package/lib/engine/xr/NeedleXRSession.js +50 -14
  95. package/lib/engine/xr/NeedleXRSession.js.map +1 -1
  96. package/lib/engine/xr/events.d.ts +1 -1
  97. package/lib/engine/xr/events.js.map +1 -1
  98. package/lib/engine-components/Animation.js +17 -16
  99. package/lib/engine-components/Animation.js.map +1 -1
  100. package/lib/engine-components/Animator.d.ts +6 -0
  101. package/lib/engine-components/Animator.js +17 -12
  102. package/lib/engine-components/Animator.js.map +1 -1
  103. package/lib/engine-components/AnimatorController.builder.d.ts +113 -0
  104. package/lib/engine-components/AnimatorController.builder.js +195 -0
  105. package/lib/engine-components/AnimatorController.builder.js.map +1 -0
  106. package/lib/engine-components/AnimatorController.d.ts +4 -119
  107. package/lib/engine-components/AnimatorController.js +35 -233
  108. package/lib/engine-components/AnimatorController.js.map +1 -1
  109. package/lib/engine-components/AudioSource.d.ts +19 -3
  110. package/lib/engine-components/AudioSource.js +121 -68
  111. package/lib/engine-components/AudioSource.js.map +1 -1
  112. package/lib/engine-components/Collider.d.ts +18 -9
  113. package/lib/engine-components/Collider.js +61 -14
  114. package/lib/engine-components/Collider.js.map +1 -1
  115. package/lib/engine-components/Component.d.ts +58 -6
  116. package/lib/engine-components/Component.js +77 -0
  117. package/lib/engine-components/Component.js.map +1 -1
  118. package/lib/engine-components/DragControls.d.ts +7 -0
  119. package/lib/engine-components/DragControls.js +19 -7
  120. package/lib/engine-components/DragControls.js.map +1 -1
  121. package/lib/engine-components/EventList.d.ts +31 -9
  122. package/lib/engine-components/EventList.js +37 -76
  123. package/lib/engine-components/EventList.js.map +1 -1
  124. package/lib/engine-components/Joints.d.ts +4 -2
  125. package/lib/engine-components/Joints.js +19 -3
  126. package/lib/engine-components/Joints.js.map +1 -1
  127. package/lib/engine-components/Light.d.ts +6 -8
  128. package/lib/engine-components/Light.js +48 -27
  129. package/lib/engine-components/Light.js.map +1 -1
  130. package/lib/engine-components/Networking.d.ts +1 -1
  131. package/lib/engine-components/Networking.js +1 -1
  132. package/lib/engine-components/OrbitControls.js +16 -11
  133. package/lib/engine-components/OrbitControls.js.map +1 -1
  134. package/lib/engine-components/ReflectionProbe.js +2 -0
  135. package/lib/engine-components/ReflectionProbe.js.map +1 -1
  136. package/lib/engine-components/RigidBody.d.ts +12 -4
  137. package/lib/engine-components/RigidBody.js +18 -4
  138. package/lib/engine-components/RigidBody.js.map +1 -1
  139. package/lib/engine-components/SeeThrough.js +2 -2
  140. package/lib/engine-components/SeeThrough.js.map +1 -1
  141. package/lib/engine-components/api.d.ts +1 -1
  142. package/lib/engine-components/api.js +1 -1
  143. package/lib/engine-components/api.js.map +1 -1
  144. package/lib/engine-components/codegen/components.d.ts +3 -9
  145. package/lib/engine-components/codegen/components.js +3 -9
  146. package/lib/engine-components/codegen/components.js.map +1 -1
  147. package/lib/engine-components/postprocessing/Effects/Tonemapping.utils.d.ts +1 -1
  148. package/lib/engine-components/postprocessing/VolumeParameter.d.ts +2 -0
  149. package/lib/engine-components/postprocessing/VolumeParameter.js +4 -1
  150. package/lib/engine-components/postprocessing/VolumeParameter.js.map +1 -1
  151. package/lib/engine-components/timeline/PlayableDirector.d.ts +16 -6
  152. package/lib/engine-components/timeline/PlayableDirector.js +63 -61
  153. package/lib/engine-components/timeline/PlayableDirector.js.map +1 -1
  154. package/lib/engine-components/timeline/SignalAsset.d.ts +3 -1
  155. package/lib/engine-components/timeline/SignalAsset.js +1 -0
  156. package/lib/engine-components/timeline/SignalAsset.js.map +1 -1
  157. package/lib/engine-components/timeline/TimelineBuilder.d.ts +247 -0
  158. package/lib/engine-components/timeline/TimelineBuilder.js +400 -0
  159. package/lib/engine-components/timeline/TimelineBuilder.js.map +1 -0
  160. package/lib/engine-components/timeline/TimelineModels.d.ts +2 -1
  161. package/lib/engine-components/timeline/TimelineModels.js +3 -0
  162. package/lib/engine-components/timeline/TimelineModels.js.map +1 -1
  163. package/lib/engine-components/timeline/TimelineTracks.d.ts +23 -0
  164. package/lib/engine-components/timeline/TimelineTracks.js +71 -13
  165. package/lib/engine-components/timeline/TimelineTracks.js.map +1 -1
  166. package/lib/engine-components/timeline/index.d.ts +2 -1
  167. package/lib/engine-components/timeline/index.js +2 -0
  168. package/lib/engine-components/timeline/index.js.map +1 -1
  169. package/lib/engine-components/ui/Canvas.d.ts +1 -1
  170. package/lib/engine-components/ui/Canvas.js +2 -8
  171. package/lib/engine-components/ui/Canvas.js.map +1 -1
  172. package/lib/engine-components/ui/Text.d.ts +1 -0
  173. package/lib/engine-components/ui/Text.js +10 -7
  174. package/lib/engine-components/ui/Text.js.map +1 -1
  175. package/lib/engine-components/web/CursorFollow.js +21 -12
  176. package/lib/engine-components/web/CursorFollow.js.map +1 -1
  177. package/lib/engine-components/webxr/WebXRImageTracking.js +4 -0
  178. package/lib/engine-components/webxr/WebXRImageTracking.js.map +1 -1
  179. package/lib/needle-engine.d.ts +2 -0
  180. package/lib/needle-engine.js +2 -0
  181. package/lib/needle-engine.js.map +1 -1
  182. package/package.json +4 -84
  183. package/plugins/common/worker.js +9 -4
  184. package/plugins/dts-generator/dts.codegen.js +255 -50
  185. package/plugins/dts-generator/dts.scan.js +37 -9
  186. package/plugins/dts-generator/dts.writer.js +1 -1
  187. package/plugins/dts-generator/glb.discovery.js +140 -23
  188. package/plugins/dts-generator/glb.extractor.js +48 -8
  189. package/plugins/dts-generator/glb.reader.js +80 -27
  190. package/plugins/dts-generator/index.js +1 -1
  191. package/plugins/types/needle-bindings.d.ts +25 -14
  192. package/plugins/types/userconfig.d.ts +12 -0
  193. package/plugins/vite/asap.js +18 -9
  194. package/plugins/vite/dependencies.js +29 -0
  195. package/plugins/vite/dependency-watcher.d.ts +2 -2
  196. package/plugins/vite/dependency-watcher.js +5 -6
  197. package/plugins/vite/drop.d.ts +2 -2
  198. package/plugins/vite/drop.js +3 -4
  199. package/plugins/vite/dts-generator.d.ts +2 -2
  200. package/plugins/vite/dts-generator.js +43 -9
  201. package/plugins/vite/editor-connection.js +3 -3
  202. package/plugins/vite/index.d.ts +9 -3
  203. package/plugins/vite/index.js +23 -10
  204. package/plugins/vite/local-files-core.js +3 -3
  205. package/plugins/vite/local-files-utils.d.ts +3 -1
  206. package/plugins/vite/local-files-utils.js +29 -5
  207. package/plugins/vite/meta.js +4 -2
  208. package/plugins/vite/poster.d.ts +2 -2
  209. package/plugins/vite/poster.js +3 -5
  210. package/plugins/vite/reload.d.ts +2 -2
  211. package/plugins/vite/reload.js +23 -23
  212. package/plugins/vite/server.js +2 -1
  213. package/src/engine/api.ts +8 -1
  214. package/src/engine/codegen/register_types.ts +2 -10
  215. package/src/engine/debug/debug_spatial_console.ts +10 -7
  216. package/src/engine/engine_addressables.ts +6 -3
  217. package/src/engine/engine_audio.ts +184 -0
  218. package/src/engine/engine_components.ts +1 -1
  219. package/src/engine/engine_context.ts +36 -22
  220. package/src/engine/engine_disposable.ts +213 -0
  221. package/src/engine/engine_gameobject.ts +54 -159
  222. package/src/engine/engine_gltf_builtin_components.ts +7 -76
  223. package/src/engine/engine_init.ts +15 -1
  224. package/src/engine/engine_input.ts +1 -1
  225. package/src/engine/engine_instantiate_resolve.ts +407 -0
  226. package/src/engine/engine_license.ts +12 -10
  227. package/src/engine/engine_lifecycle_functions_internal.ts +7 -0
  228. package/src/engine/engine_mainloop_utils.ts +5 -2
  229. package/src/engine/engine_networking.ts +3 -1
  230. package/src/engine/engine_networking_blob.ts +1 -1
  231. package/src/engine/engine_physics_rapier.ts +82 -27
  232. package/src/engine/engine_pmrem.ts +3 -3
  233. package/src/engine/engine_scenedata.ts +56 -30
  234. package/src/engine/engine_serialization_builtin_serializer.ts +64 -52
  235. package/src/engine/engine_serialization_core.ts +9 -0
  236. package/src/engine/engine_ssr.ts +29 -3
  237. package/src/engine/engine_types.ts +24 -13
  238. package/src/engine/engine_util_decorator.ts +7 -2
  239. package/src/engine/engine_utils.ts +16 -5
  240. package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  241. package/src/engine/webcomponents/jsx.d.ts +51 -0
  242. package/src/engine/webcomponents/logo-element.ts +1 -0
  243. package/src/engine/webcomponents/needle menu/needle-menu.ts +3 -2
  244. package/src/engine/webcomponents/needle-button.ts +1 -0
  245. package/src/engine/webcomponents/needle-engine.ts +11 -4
  246. package/src/engine/xr/NeedleXRSession.ts +48 -13
  247. package/src/engine/xr/events.ts +1 -1
  248. package/src/engine-components/Animation.ts +19 -16
  249. package/src/engine-components/Animator.ts +18 -11
  250. package/src/engine-components/AnimatorController.builder.ts +261 -0
  251. package/src/engine-components/AnimatorController.ts +23 -292
  252. package/src/engine-components/AudioSource.ts +130 -79
  253. package/src/engine-components/Collider.ts +66 -18
  254. package/src/engine-components/Component.ts +79 -9
  255. package/src/engine-components/DragControls.ts +18 -11
  256. package/src/engine-components/EventList.ts +45 -83
  257. package/src/engine-components/Joints.ts +20 -4
  258. package/src/engine-components/Light.ts +49 -27
  259. package/src/engine-components/Networking.ts +1 -1
  260. package/src/engine-components/OrbitControls.ts +18 -9
  261. package/src/engine-components/ReflectionProbe.ts +2 -0
  262. package/src/engine-components/RigidBody.ts +18 -4
  263. package/src/engine-components/SeeThrough.ts +2 -2
  264. package/src/engine-components/api.ts +1 -1
  265. package/src/engine-components/codegen/components.ts +3 -9
  266. package/src/engine-components/postprocessing/VolumeParameter.ts +4 -1
  267. package/src/engine-components/timeline/PlayableDirector.ts +61 -64
  268. package/src/engine-components/timeline/SignalAsset.ts +4 -1
  269. package/src/engine-components/timeline/TimelineBuilder.ts +565 -0
  270. package/src/engine-components/timeline/TimelineModels.ts +5 -1
  271. package/src/engine-components/timeline/TimelineTracks.ts +74 -13
  272. package/src/engine-components/timeline/index.ts +2 -1
  273. package/src/engine-components/ui/Canvas.ts +2 -8
  274. package/src/engine-components/ui/Text.ts +12 -8
  275. package/src/engine-components/web/CursorFollow.ts +21 -13
  276. package/src/engine-components/webxr/WebXRImageTracking.ts +2 -0
  277. package/src/needle-engine.ts +3 -0
  278. package/dist/needle-engine.bundle-Dq0Ly8fW.umd.cjs +0 -1732
  279. package/dist/needle-engine.bundle-YnpzzOPL.min.js +0 -1732
  280. package/lib/engine-components/AvatarLoader.d.ts +0 -80
  281. package/lib/engine-components/AvatarLoader.js +0 -232
  282. package/lib/engine-components/AvatarLoader.js.map +0 -1
  283. package/lib/engine-components/avatar/AvatarBlink_Simple.d.ts +0 -11
  284. package/lib/engine-components/avatar/AvatarBlink_Simple.js +0 -77
  285. package/lib/engine-components/avatar/AvatarBlink_Simple.js.map +0 -1
  286. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.d.ts +0 -14
  287. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js +0 -69
  288. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js.map +0 -1
  289. package/lib/engine-components/avatar/Avatar_Brain_LookAt.d.ts +0 -29
  290. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js +0 -122
  291. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js.map +0 -1
  292. package/lib/engine-components/avatar/Avatar_MouthShapes.d.ts +0 -15
  293. package/lib/engine-components/avatar/Avatar_MouthShapes.js +0 -80
  294. package/lib/engine-components/avatar/Avatar_MouthShapes.js.map +0 -1
  295. package/lib/engine-components/avatar/Avatar_MustacheShake.d.ts +0 -9
  296. package/lib/engine-components/avatar/Avatar_MustacheShake.js +0 -30
  297. package/lib/engine-components/avatar/Avatar_MustacheShake.js.map +0 -1
  298. package/src/engine-components/AvatarLoader.ts +0 -264
  299. package/src/engine-components/avatar/AvatarBlink_Simple.ts +0 -70
  300. package/src/engine-components/avatar/AvatarEyeLook_Rotation.ts +0 -64
  301. package/src/engine-components/avatar/Avatar_Brain_LookAt.ts +0 -140
  302. package/src/engine-components/avatar/Avatar_MouthShapes.ts +0 -84
  303. package/src/engine-components/avatar/Avatar_MustacheShake.ts +0 -32
@@ -40,6 +40,7 @@ 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';
@@ -254,6 +255,24 @@ export declare class ActionModel implements IBehaviorElement {
254
255
  writeTo(document: USDDocument, writer: USDWriter): void;
255
256
  }
256
257
 
258
+ /**
259
+ * Options for an activation clip in the timeline builder
260
+ */
261
+ export declare type ActivationClipOptions = {
262
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
263
+ start?: number;
264
+ /** Duration of the clip in seconds (required) */
265
+ duration: number;
266
+ /** Ease-in duration in seconds (default: 0) */
267
+ easeIn?: number;
268
+ /** Ease-out duration in seconds (default: 0) */
269
+ easeOut?: number;
270
+ };
271
+
272
+ export declare class ActivationTrackHandler extends TrackHandler {
273
+ evaluate(time: number): void;
274
+ }
275
+
257
276
  export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";
258
277
 
259
278
  /**
@@ -500,6 +519,34 @@ export declare type AnimationClipModel = {
500
519
  rotation?: Quat | Quaternion;
501
520
  };
502
521
 
522
+ /**
523
+ * Options for an animation clip in the timeline builder
524
+ */
525
+ export declare type AnimationClipOptions = {
526
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
527
+ start?: number;
528
+ /** Duration of the clip in seconds. Defaults to the animation clip duration. */
529
+ duration?: number;
530
+ /** Playback speed multiplier (default: 1) */
531
+ speed?: number;
532
+ /** Whether the animation should loop within the clip (default: false) */
533
+ loop?: boolean;
534
+ /** Ease-in duration in seconds (default: 0) */
535
+ easeIn?: number;
536
+ /** Ease-out duration in seconds (default: 0) */
537
+ easeOut?: number;
538
+ /** Offset into the source animation clip in seconds (default: 0) */
539
+ clipIn?: number;
540
+ /** Whether to remove the start offset of the animation (default: false) */
541
+ removeStartOffset?: boolean;
542
+ /** Pre-extrapolation mode (default: None) */
543
+ preExtrapolation?: ClipExtrapolation;
544
+ /** Post-extrapolation mode (default: None) */
545
+ postExtrapolation?: ClipExtrapolation;
546
+ /** Play the clip in reverse */
547
+ reversed?: boolean;
548
+ };
549
+
503
550
  /**
504
551
  * AnimationCurve is a representation of a curve that can be used to animate values over time.
505
552
  *
@@ -726,6 +773,12 @@ export declare class Animator extends Component implements IAnimationComponent {
726
773
  * Identifies this component as an animation component in the engine
727
774
  */
728
775
  get isAnimationComponent(): boolean;
776
+ /**
777
+ * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
778
+ * @returns The current AnimationMixer, or null if no controller is assigned
779
+ * @see AnimatorController.mixer
780
+ */
781
+ get mixer(): AnimationMixer | null;
729
782
  /**
730
783
  * When enabled, animation will affect the root transform position and rotation
731
784
  */
@@ -1102,13 +1155,6 @@ export declare class AnimatorController {
1102
1155
  * @param animator - The animator to bind this controller to
1103
1156
  */
1104
1157
  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
1158
  /**
1113
1159
  * Updates the controller's state machine and animations.
1114
1160
  * Called each frame by the animator component.
@@ -1472,6 +1518,75 @@ export declare class Attractor extends Component {
1472
1518
 
1473
1519
  declare type AttributeChangeCallback = (value: string | null) => void;
1474
1520
 
1521
+ /**
1522
+ * Represents an audio clip that can be loaded and played independently.
1523
+ * The AudioClip class encapsulates the URL of the audio resource and provides
1524
+ * methods for playback control (play, pause, stop) and querying duration.
1525
+ */
1526
+ export declare class AudioClip {
1527
+ readonly url: string;
1528
+ /**
1529
+ * Creates a new AudioClip instance with the specified URL.
1530
+ * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
1531
+ */
1532
+ constructor(url: string);
1533
+ /** Whether the clip is currently playing.
1534
+ * @returns `true` if the clip is actively playing audio.
1535
+ */
1536
+ get isPlaying(): boolean;
1537
+ /**
1538
+ * The total duration of the audio clip in seconds.
1539
+ * Loads the audio metadata if not already available.
1540
+ * @returns A promise that resolves with the duration in seconds.
1541
+ */
1542
+ getDuration(): Promise<number>;
1543
+ /**
1544
+ * Plays the audio clip from the current position.
1545
+ * @returns A promise that resolves when playback finishes, or rejects on error.
1546
+ * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
1547
+ */
1548
+ play(): Promise<void>;
1549
+ /**
1550
+ * Pauses playback at the current position.
1551
+ * Call {@link play} to resume.
1552
+ */
1553
+ pause(): void;
1554
+ /**
1555
+ * Stops playback and resets the position to the beginning.
1556
+ */
1557
+ stop(): void;
1558
+ /** Whether the clip should loop when reaching the end. */
1559
+ get loop(): boolean;
1560
+ set loop(value: boolean);
1561
+ /** Playback volume from 0 (silent) to 1 (full). */
1562
+ get volume(): number;
1563
+ set volume(value: number);
1564
+ /** Current playback position in seconds. */
1565
+ get currentTime(): number;
1566
+ set currentTime(value: number);
1567
+ /** Normalized playback progress from 0 to 1.
1568
+ * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
1569
+ */
1570
+ get progress(): number;
1571
+ /**
1572
+ * Seeks to a normalized position (0–1) in the clip.
1573
+ * @param position A value between 0 (start) and 1 (end).
1574
+ */
1575
+ seek(position: number): void;
1576
+ /** The underlying HTMLAudioElement, or `undefined` if not yet created.
1577
+ * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
1578
+ * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
1579
+ */
1580
+ get audioElement(): HTMLAudioElement | undefined;
1581
+ private _audioElement?;
1582
+ private _duration?;
1583
+ private _loadPromise?;
1584
+ private _loop;
1585
+ private _volume;
1586
+ /** Lazily creates and loads the shared HTMLAudioElement. */
1587
+ private ensureAudioElement;
1588
+ }
1589
+
1475
1590
  /**
1476
1591
  * @category Animation and Sequencing
1477
1592
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -1486,6 +1601,26 @@ declare type AudioClipModel_2 = Models.ClipModel & {
1486
1601
  _didTriggerPlay: boolean;
1487
1602
  };
1488
1603
 
1604
+ /**
1605
+ * Options for an audio clip in the timeline builder
1606
+ */
1607
+ export declare type AudioClipOptions = {
1608
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
1609
+ start?: number;
1610
+ /** Duration of the clip in seconds (required for audio since we can't infer it) */
1611
+ duration: number;
1612
+ /** Playback speed multiplier (default: 1) */
1613
+ speed?: number;
1614
+ /** Volume multiplier for this clip (default: 1) */
1615
+ volume?: number;
1616
+ /** Whether the audio should loop within the clip (default: false) */
1617
+ loop?: boolean;
1618
+ /** Ease-in duration in seconds (default: 0) */
1619
+ easeIn?: number;
1620
+ /** Ease-out duration in seconds (default: 0) */
1621
+ easeOut?: number;
1622
+ };
1623
+
1489
1624
  export declare class AudioExtension implements IUSDExporterExtension {
1490
1625
  static getName(clip: string): string;
1491
1626
  get extensionName(): string;
@@ -1627,9 +1762,10 @@ export declare class AudioSource extends Component {
1627
1762
  */
1628
1763
  get isPlaying(): boolean;
1629
1764
  /**
1630
- * The total duration of the current audio clip in seconds.
1765
+ * The total duration of the currently loaded audio clip in seconds.
1631
1766
  *
1632
1767
  * @returns Duration in seconds or undefined if no clip is loaded
1768
+ * @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
1769
  */
1634
1770
  get duration(): number | undefined;
1635
1771
  /**
@@ -1654,7 +1790,8 @@ export declare class AudioSource extends Component {
1654
1790
  /**
1655
1791
  * Controls how the audio is positioned in space.
1656
1792
  * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
1657
- * Note: 2D playback is not fully supported in the current implementation.
1793
+ * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
1794
+ * and a non-spatialized (direct) signal path.
1658
1795
  */
1659
1796
  get spatialBlend(): number;
1660
1797
  set spatialBlend(val: number);
@@ -1702,7 +1839,11 @@ export declare class AudioSource extends Component {
1702
1839
  private audioLoader;
1703
1840
  private shouldPlay;
1704
1841
  private _lastClipStartedLoading;
1842
+ private _loadedClip;
1705
1843
  private _audioElement;
1844
+ private _entryNode;
1845
+ private _spatialGain;
1846
+ private _bypassGain;
1706
1847
  /**
1707
1848
  * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
1708
1849
  * The audio source needs a user interaction to be initialized due to browser autoplay policies.
@@ -1730,6 +1871,15 @@ export declare class AudioSource extends Component {
1730
1871
  private onApplicationMuteChanged;
1731
1872
  private createAudio;
1732
1873
  private __onAllowAudioCallback;
1874
+ /**
1875
+ * Sets up the dual-path audio graph for spatial blend crossfading.
1876
+ * Creates two parallel signal paths from source to output:
1877
+ * - 3D path: entry → panner → spatialGain → gain (spatialized)
1878
+ * - 2D path: entry → bypassGain → gain (non-spatialized)
1879
+ */
1880
+ private setupSpatialBlendNodes;
1881
+ /** Updates the spatial/bypass gain values based on the current spatialBlend. */
1882
+ private updateSpatialBlendGains;
1733
1883
  private applySpatialDistanceSettings;
1734
1884
  private onNewClip;
1735
1885
  /**
@@ -1737,8 +1887,9 @@ export declare class AudioSource extends Component {
1737
1887
  * If no argument is provided, plays the currently assigned clip.
1738
1888
  *
1739
1889
  * @param clip - Optional audio clip or {@link MediaStream} to play
1890
+ * @returns A promise that resolves when playback starts successfully, or rejects on error
1740
1891
  */
1741
- play(clip?: string | MediaStream | undefined): void;
1892
+ play(clip?: string | MediaStream | undefined): Promise<boolean>;
1742
1893
  /**
1743
1894
  * Pauses audio playback while maintaining the current position.
1744
1895
  * Use play() to resume from the paused position.
@@ -1755,6 +1906,20 @@ export declare class AudioSource extends Component {
1755
1906
  /* Excluded from this release type: update */
1756
1907
  }
1757
1908
 
1909
+ /**
1910
+ * Handles audio playback for a timeline audio track.
1911
+ *
1912
+ * **Runtime mutation:** The track model is read fresh every frame during `evaluate()`.
1913
+ * You can mutate `track.volume`, `clip.start`, `clip.end`, `clip.asset.volume` etc.
1914
+ * at any time — changes take effect on the next frame without rebuilding the timeline.
1915
+ *
1916
+ * **Audio stopping:** Audio clips are automatically stopped when:
1917
+ * - Timeline time moves outside a clip's `[start, end]` range (e.g. jumping or normal playback advancing past a clip)
1918
+ * - The track is muted (via `muted = true`)
1919
+ * - The director is stopped (`director.stop()`)
1920
+ * - The director is paused (`director.pause()`)
1921
+ * - The director is disabled or destroyed
1922
+ */
1758
1923
  export declare class AudioTrackHandler extends TrackHandler {
1759
1924
  models: Array<AudioClipModel_2>;
1760
1925
  listener: AudioListener_3;
@@ -1762,6 +1927,9 @@ export declare class AudioTrackHandler extends TrackHandler {
1762
1927
  audioContextTimeOffset: Array<number>;
1763
1928
  lastTime: number;
1764
1929
  audioSource?: AudioSource;
1930
+ /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
1931
+ get volume(): number;
1932
+ set volume(val: number);
1765
1933
  private _audioLoader;
1766
1934
  private getAudioFilePath;
1767
1935
  onAllowAudioChanged(allow: boolean): void;
@@ -1811,69 +1979,6 @@ export declare class Avatar extends Component {
1811
1979
  private loadAvatarObjects;
1812
1980
  }
1813
1981
 
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
1982
  /**
1878
1983
  * Marks a GameObject as being controlled or owned by a player in networked XR sessions.
1879
1984
  * This is used internally by the networking system to identify player-controlled objects.
@@ -1934,35 +2039,6 @@ declare type AvatarMarkerEventArgs = {
1934
2039
  gameObject: Object3D;
1935
2040
  };
1936
2041
 
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
2042
  export declare enum Axes {
1967
2043
  None = 0,
1968
2044
  X = 2,
@@ -2326,7 +2402,6 @@ export declare class BoxCollider extends Collider implements IBoxCollider {
2326
2402
  center: Vector3;
2327
2403
  /* Excluded from this release type: onEnable */
2328
2404
  /* Excluded from this release type: onDisable */
2329
- /* Excluded from this release type: onValidate */
2330
2405
  /**
2331
2406
  * Automatically fits the collider to the geometry of the object.
2332
2407
  * Sets the size and center based on the object's bounding box.
@@ -2600,6 +2675,7 @@ declare class CallHandle extends EventDispatcher<any> {
2600
2675
  * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
2601
2676
  */
2602
2677
  export declare class CallInfo {
2678
+ $serializedTypes: Record<string, any>;
2603
2679
  /**
2604
2680
  * When the CallInfo is enabled it will be invoked when the EventList is invoked
2605
2681
  */
@@ -2946,7 +3022,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
2946
3022
  private _receivers;
2947
3023
  registerEventReceiver(receiver: ICanvasEventReceiver): void;
2948
3024
  unregisterEventReceiver(receiver: ICanvasEventReceiver): void;
2949
- onEnterXR(args: NeedleXREventArgs): Promise<void>;
3025
+ onEnterXR(args: NeedleXREventArgs): void;
2950
3026
  onLeaveXR(args: NeedleXREventArgs): void;
2951
3027
  onBeforeRenderRoutine: () => void;
2952
3028
  onAfterRenderRoutine: () => void;
@@ -3522,6 +3598,22 @@ export declare abstract class Collider extends Component implements ICollider {
3522
3598
  * The layers that this collider will interact with. Used for filtering collision detection.
3523
3599
  */
3524
3600
  filter?: number[];
3601
+ /**
3602
+ * The density of the collider, used for automatic mass calculation when the attached {@link Rigidbody} has `autoMass` enabled.
3603
+ * Rapier computes mass from density using the real-world formula: `mass = density × volume`.
3604
+ * The volume is derived from the collider shape (sphere, box, capsule, or convex hull).
3605
+ *
3606
+ * Reference values (relative to water = 1.0):
3607
+ * - Wood: 0.5–0.9
3608
+ * - Water: 1.0 (engine default)
3609
+ * - Rubber: 1.2
3610
+ * - Steel: 7.8
3611
+ *
3612
+ * @default undefined — uses the physics engine default of 1.0
3613
+ */
3614
+ density?: number;
3615
+ /* Excluded from this release type: _propertiesDirty */
3616
+ /* Excluded from this release type: onValidate */
3525
3617
  /* Excluded from this release type: awake */
3526
3618
  /* Excluded from this release type: start */
3527
3619
  /* Excluded from this release type: onEnable */
@@ -3623,7 +3715,7 @@ declare class ColorSerializer extends TypeSerializer {
3623
3715
  onSerialize(data: any): any | void;
3624
3716
  }
3625
3717
 
3626
- export declare const colorSerializer: ColorSerializer;
3718
+ export declare let colorSerializer: ColorSerializer;
3627
3719
 
3628
3720
  /**
3629
3721
  * Utility method to check if two materials were created from the same glTF material
@@ -3707,6 +3799,62 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3707
3799
  * @returns True if the component is enabled and all parent GameObjects are active
3708
3800
  */
3709
3801
  get activeAndEnabled(): boolean;
3802
+ private __disableCleanups?;
3803
+ private __destroyCleanups?;
3804
+ /**
3805
+ * Register a resource for automatic cleanup tied to this component's lifecycle.
3806
+ * Accepts {@link IDisposable} objects, cleanup functions, or event unsubscribe functions.
3807
+ * `null` and `undefined` are safe no-ops (convenient for conditional subscriptions).
3808
+ *
3809
+ * **Lifecycle-aware:** The cleanup store is chosen automatically based on when `autoCleanup` is called:
3810
+ * - Called during {@link onEnable} → cleaned up on {@link onDisable} (and re-registered on re-enable)
3811
+ * - Called during {@link awake} or {@link start} → cleaned up on {@link onDestroy} (survives enable/disable cycles)
3812
+ * - Called at any other time (e.g. from update) → cleaned up on {@link onDisable}
3813
+ *
3814
+ * @param disposable An {@link IDisposable}, a cleanup/unsubscribe function, or `null`/`undefined`
3815
+ *
3816
+ * @example DOM events with on() — fully typed
3817
+ * ```ts
3818
+ * import { Behaviour, on } from "@needle-tools/engine";
3819
+ *
3820
+ * export class JsonLoader extends Behaviour {
3821
+ * onEnable() {
3822
+ * this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
3823
+ * this.autoCleanup(on(document, "keydown", (ev) => this.onKey(ev)));
3824
+ * }
3825
+ * // Listeners removed automatically on disable — no manual cleanup!
3826
+ * }
3827
+ * ```
3828
+ *
3829
+ * @example EventList subscriptions
3830
+ * ```ts
3831
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
3832
+ *
3833
+ * export class MyComponent extends Behaviour {
3834
+ * @serializable(EventList)
3835
+ * onScoreChanged?: EventList<number>;
3836
+ *
3837
+ * onEnable() {
3838
+ * this.autoCleanup(this.onScoreChanged?.on(score => {
3839
+ * console.log("Score:", score);
3840
+ * }));
3841
+ * }
3842
+ * }
3843
+ * ```
3844
+ *
3845
+ * @example Lifetime subscriptions in awake
3846
+ * ```ts
3847
+ * import { Behaviour, on } from "@needle-tools/engine";
3848
+ *
3849
+ * export class Persistent extends Behaviour {
3850
+ * awake() {
3851
+ * // Registered during awake → survives enable/disable, cleaned up on destroy
3852
+ * this.autoCleanup(on(window, "beforeunload", () => this.save()));
3853
+ * }
3854
+ * }
3855
+ * ```
3856
+ */
3857
+ protected autoCleanup(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
3710
3858
  private get __isActive();
3711
3859
  private get __isActiveInHierarchy();
3712
3860
  private set __isActiveInHierarchy(value);
@@ -3725,11 +3873,6 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3725
3873
  * For example, URL to the glTF file this component was loaded from
3726
3874
  */
3727
3875
  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
3876
  /**
3734
3877
  * Called once when the component becomes active for the first time.
3735
3878
  * This is the first lifecycle callback to be invoked
@@ -4097,7 +4240,7 @@ declare class ComponentSerializer extends TypeSerializer {
4097
4240
  findObjectForGuid(guid: string, root: Object3D): any;
4098
4241
  }
4099
4242
 
4100
- export declare const componentSerializer: ComponentSerializer;
4243
+ export declare let componentSerializer: ComponentSerializer;
4101
4244
 
4102
4245
  declare type ComponentType = "button" | "thumbstick" | "squeeze" | "touchpad";
4103
4246
 
@@ -4460,13 +4603,14 @@ export declare class Context implements IContext {
4460
4603
  * Use `setCurrentCamera` for updating the main camera.
4461
4604
  */
4462
4605
  /**
4463
- * Typed proxy providing direct access to scene components by node and component name.
4464
- * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
4465
- * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
4606
+ * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
4607
+ * Types are generated automatically from your GLB files when the dev server starts.
4466
4608
  *
4467
- * Each property access traverses the live scene graph on demand — no caching, always fresh.
4468
- * This is a convenience shorthand for `getComponent` lookups; the same result can be
4469
- * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
4609
+ * You can store references to objects or components for later use.
4610
+ * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
4611
+ * in which case stored references may become stale.
4612
+ *
4613
+ * @experimental This API may change in future versions.
4470
4614
  *
4471
4615
  * @example
4472
4616
  * // Toggle auto-rotate on the orbit camera
@@ -4475,12 +4619,6 @@ export declare class Context implements IContext {
4475
4619
  * @example
4476
4620
  * // Change the background color
4477
4621
  * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
4478
- *
4479
- * @example
4480
- * // Equivalent manual approach (without sceneData)
4481
- * const node = ctx.scene.getObjectByName("Camera");
4482
- * const orbit = getComponent(node, OrbitControls);
4483
- * if (orbit) orbit.autoRotate = true;
4484
4622
  */
4485
4623
  get sceneData(): SceneData;
4486
4624
  get mainCamera(): Camera_2;
@@ -4504,15 +4642,21 @@ export declare class Context implements IContext {
4504
4642
  connection: NetworkConnection;
4505
4643
  /** @deprecated AssetDatabase is deprecated */
4506
4644
  assets: AssetDatabase;
4507
- /** The main light in the scene */
4508
- mainLight: ILight | null;
4645
+ /** All registered lights in the scene, maintained by the Light component.
4646
+ * @see mainLight for accessing the main directional light in the scene
4647
+ */
4648
+ readonly lights: ILight[];
4649
+ /** The brightest registered directional light, or null if none are registered
4650
+ * @see lights
4651
+ */
4652
+ get mainLight(): ILight | null;
4509
4653
  /** @deprecated Use sceneLighting */
4510
- get rendererData(): RendererData;
4654
+ private get rendererData();
4511
4655
  /** Access the scene lighting manager to control lighting settings in the context */
4512
- sceneLighting: RendererData;
4513
- addressables: Addressables;
4514
- lightmaps: ILightDataRegistry;
4515
- players: PlayerViewManager;
4656
+ readonly sceneLighting: RendererData;
4657
+ readonly addressables: Addressables;
4658
+ readonly lightmaps: ILightDataRegistry;
4659
+ readonly players: PlayerViewManager;
4516
4660
  /** Access the LODs manager to control LOD behavior in the context */
4517
4661
  readonly lodsManager: LODsManager;
4518
4662
  /** Access the needle menu to add or remove buttons to the menu element */
@@ -4805,6 +4949,20 @@ export declare type ControlClipModel = {
4805
4949
  updateDirector: boolean;
4806
4950
  };
4807
4951
 
4952
+ /**
4953
+ * Options for a control clip in the timeline builder
4954
+ */
4955
+ export declare type ControlClipOptions = {
4956
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
4957
+ start?: number;
4958
+ /** Duration of the clip in seconds (required) */
4959
+ duration: number;
4960
+ /** Whether to control the activation of the source object (default: true) */
4961
+ controlActivation?: boolean;
4962
+ /** Whether to update a nested PlayableDirector on the source object (default: true) */
4963
+ updateDirector?: boolean;
4964
+ };
4965
+
4808
4966
  /** true when selectstart was ever received.
4809
4967
  * On VisionOS 1.1 we always have select events (as per the spec), so this is always true
4810
4968
  */
@@ -5135,7 +5293,7 @@ export declare function decompressGpuTexture(texture: any, maxTextureSize?: numb
5135
5293
  * return true;
5136
5294
  * });
5137
5295
  * */
5138
- export declare function deepClone(obj: any, predicate?: deepClonePredicate): any;
5296
+ export declare function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any;
5139
5297
 
5140
5298
  declare type deepClonePredicate = (owner: any, propertyName: string, current: any) => boolean;
5141
5299
 
@@ -5363,7 +5521,7 @@ export declare namespace DeviceUtilities {
5363
5521
  * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
5364
5522
  * @see {@link PlayableDirector.extrapolationMode}
5365
5523
  */
5366
- declare enum DirectorWrapMode {
5524
+ export declare enum DirectorWrapMode {
5367
5525
  /** Hold the last frame when playback reaches the end of the timeline. */
5368
5526
  Hold = 0,
5369
5527
  /** Loop back to the start and continue playing indefinitely. */
@@ -5372,6 +5530,101 @@ declare enum DirectorWrapMode {
5372
5530
  None = 2
5373
5531
  }
5374
5532
 
5533
+ /**
5534
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
5535
+ * that should be cleaned up together.
5536
+ *
5537
+ * DisposableStore collects disposables and disposes them all at once when
5538
+ * {@link dispose} is called. After disposal, the store can be reused — new items
5539
+ * can be added and a subsequent {@link dispose} call will clean those up.
5540
+ *
5541
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
5542
+ *
5543
+ * @example Basic usage
5544
+ * ```ts
5545
+ * import { DisposableStore, on } from "@needle-tools/engine";
5546
+ *
5547
+ * const store = new DisposableStore();
5548
+ *
5549
+ * // Register a DOM event listener (typed!)
5550
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
5551
+ *
5552
+ * // Register the return value of EventList.on()
5553
+ * store.add(myEventList.on(data => console.log(data)));
5554
+ *
5555
+ * // Register a raw cleanup function
5556
+ * store.add(() => someSDK.off("event", handler));
5557
+ *
5558
+ * // Later: dispose everything at once
5559
+ * store.dispose();
5560
+ * ```
5561
+ *
5562
+ * @example Use with Needle Engine components
5563
+ * ```ts
5564
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
5565
+ *
5566
+ * export class MyComponent extends Behaviour {
5567
+ * @serializable(EventList)
5568
+ * onClick?: EventList;
5569
+ *
5570
+ * onEnable() {
5571
+ * // DOM events — fully typed
5572
+ * this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
5573
+ *
5574
+ * // EventList — .on() returns a function, autoCleanup accepts it
5575
+ * this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
5576
+ * }
5577
+ * // No onDisable needed — cleaned up automatically!
5578
+ * }
5579
+ * ```
5580
+ *
5581
+ * @category Utilities
5582
+ * @group Lifecycle
5583
+ */
5584
+ export declare class DisposableStore implements IDisposable {
5585
+ private _disposables;
5586
+ /** The number of registered disposables */
5587
+ get size(): number;
5588
+ /**
5589
+ * Register a disposable resource. Accepts:
5590
+ * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
5591
+ * - A cleanup function (e.g. return value of `EventList.on()`)
5592
+ * - `null` or `undefined` (safe no-op for conditional subscriptions)
5593
+ *
5594
+ * When {@link dispose} is called, all registered resources are cleaned up.
5595
+ *
5596
+ * @param disposable The resource to register for disposal
5597
+ *
5598
+ * @example
5599
+ * ```ts
5600
+ * const store = new DisposableStore();
5601
+ *
5602
+ * // IDisposable object from on()
5603
+ * store.add(on(window, "resize", handler));
5604
+ *
5605
+ * // Function returned by EventList.on()
5606
+ * store.add(myEvent.on(handler));
5607
+ *
5608
+ * // Raw cleanup function
5609
+ * store.add(() => connection.close());
5610
+ *
5611
+ * // Conditional — safe with undefined
5612
+ * store.add(this.maybeEvent?.on(handler));
5613
+ * ```
5614
+ */
5615
+ add(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
5616
+ /**
5617
+ * Dispose all registered resources. Each registered disposable is cleaned up,
5618
+ * then the internal list is cleared. The store can be reused after disposal.
5619
+ *
5620
+ * Called automatically by the engine when a component's `onDisable` lifecycle fires.
5621
+ */
5622
+ dispose(): void;
5623
+ }
5624
+
5625
+ /** A function that performs cleanup when called */
5626
+ export declare type DisposeFn = () => void;
5627
+
5375
5628
  /** Recursive disposes all referenced resources by this object. Does not traverse children */
5376
5629
  export declare function disposeObjectResources(obj: object | null | undefined): void;
5377
5630
 
@@ -5479,6 +5732,12 @@ export declare class DragControls extends Component implements IPointerEventHand
5479
5732
  * providing visual feedback about the object's position relative to surfaces below it.
5480
5733
  */
5481
5734
  showGizmo: boolean;
5735
+ /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
5736
+ dragStarted: EventList;
5737
+ /** Invoked every frame while the object is being dragged. */
5738
+ dragUpdated: EventList;
5739
+ /** Invoked once when the last pointer is released and the drag ends. */
5740
+ dragEnded: EventList;
5482
5741
  /**
5483
5742
  * Returns the object currently being dragged by this DragControls component, if any.
5484
5743
  * @returns The object being dragged or null if no object is currently dragged
@@ -5919,19 +6178,6 @@ export declare class EnvironmentScene extends Scene {
5919
6178
  createAreaLightMaterial(intensity: number): MeshBasicMaterial;
5920
6179
  }
5921
6180
 
5922
- export declare const euler: EulerSerializer;
5923
-
5924
- declare class EulerSerializer extends TypeSerializer {
5925
- constructor();
5926
- onDeserialize(data: any, _context: SerializationContext): Euler | undefined;
5927
- onSerialize(data: any, _context: SerializationContext): {
5928
- x: any;
5929
- y: any;
5930
- z: any;
5931
- order: any;
5932
- };
5933
- }
5934
-
5935
6181
  /**
5936
6182
  * EventList manages a list of callbacks that can be invoked together.
5937
6183
  * Used for Unity-style events that can be configured in the editor (Unity or Blender).
@@ -5978,13 +6224,9 @@ declare class EulerSerializer extends TypeSerializer {
5978
6224
  * @see {@link Button} for UI button events
5979
6225
  */
5980
6226
  export declare class EventList<TArgs extends any = any> implements IEventList {
6227
+ $serializedTypes: Record<string, any>;
5981
6228
  /** checked during instantiate to create a new instance */
5982
6229
  readonly isEventList = true;
5983
- /* Excluded from this release type: __internalOnInstantiate */
5984
- private target?;
5985
- private key?;
5986
- /** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
5987
- setEventTarget(key: string, target: object): void;
5988
6230
  /** How many callback methods are subscribed to this event */
5989
6231
  get listenerCount(): number;
5990
6232
  /** If the event is currently being invoked */
@@ -6017,13 +6259,41 @@ export declare class EventList<TArgs extends any = any> implements IEventList {
6017
6259
  invoke(...args: Array<TArgs>): boolean;
6018
6260
  /** Add a new event listener to this event
6019
6261
  * @returns a function to remove the event listener
6262
+ * @see {@link removeEventListener} for more details and return value information
6263
+ * @see {@link off} for an alias with better readability when unsubscribing from events
6264
+ * @example
6265
+ * ```ts
6266
+ * const off = myEvent.addEventListener(args => console.log("Clicked!", args));
6267
+ * // later
6268
+ * off();
6269
+ * ```
6020
6270
  */
6021
6271
  addEventListener(callback: (args: TArgs) => void): Function;
6272
+ /**
6273
+ * Alias for addEventListener for better readability when subscribing to events. You can use it like this:
6274
+ * ```ts
6275
+ * myEvent.on(args => console.log("Clicked!", args));
6276
+ * ```
6277
+ * @returns a function to remove the event listener
6278
+ * @see {@link addEventListener} for more details and return value information
6279
+ */
6280
+ on(callback: (args: TArgs) => void): Function;
6022
6281
  /**
6023
6282
  * Remove an event listener from this event.
6024
6283
  * @returns true if the event listener was found and removed, false otherwise
6025
6284
  */
6026
6285
  removeEventListener(fn: Function | null | undefined): boolean;
6286
+ /**
6287
+ * Alias for removeEventListener for better readability when unsubscribing from events. You can use it like this:
6288
+ * ```ts
6289
+ * const off = myEvent.on(args => console.log("Clicked!", args));
6290
+ * // later
6291
+ * off();
6292
+ * ```
6293
+ *
6294
+ * @see {@link removeEventListener} for more details and return value information
6295
+ */
6296
+ off(callback: Function | null | undefined): boolean;
6027
6297
  /**
6028
6298
  * Remove all event listeners from this event. Use with caution! This will remove all listeners!
6029
6299
  */
@@ -6054,6 +6324,7 @@ declare type EventListenerOptions_2 = {
6054
6324
  signal?: AbortSignal;
6055
6325
  };
6056
6326
 
6327
+ /** @deprecated No longer automatically dispatched. Use `eventList.on()` directly instead. */
6057
6328
  export declare class EventListEvent<TArgs extends any> extends Event {
6058
6329
  args?: TArgs;
6059
6330
  }
@@ -6064,7 +6335,7 @@ declare class EventListSerializer extends TypeSerializer {
6064
6335
  onDeserialize(data: EventListData, context: SerializationContext): EventList<any> | undefined | null;
6065
6336
  }
6066
6337
 
6067
- export declare const eventListSerializer: EventListSerializer;
6338
+ export declare let eventListSerializer: EventListSerializer;
6068
6339
 
6069
6340
  /**
6070
6341
  * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
@@ -6507,7 +6778,7 @@ declare type FitParameters = {
6507
6778
  * @see {@link HingeJoint} for rotating connections
6508
6779
  */
6509
6780
  export declare class FixedJoint extends Joint {
6510
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
6781
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
6511
6782
  }
6512
6783
 
6513
6784
  declare type FocusRect = DOMRect | Element | {
@@ -7159,16 +7430,13 @@ export declare function getResourceUserCount(object: object): number | undefined
7159
7430
  * Returns a lazily-resolved proxy typed as {@link SceneData}.
7160
7431
  * The proxy is cached per context — each context gets exactly one instance.
7161
7432
  *
7162
- * Accessing a property traverses the scene graph on demand:
7163
- * - First level → find Object3D by node name
7164
- * - Second level → getComponent by component name (via TypeStore)
7165
- * - Third level → read/write a field on the real component instance
7433
+ * Shape mirrors the generated `needle-bindings.gen.d.ts`:
7434
+ * ctx.sceneData.MyGlb.Camera.$components.OrbitControls.autoRotate = true;
7435
+ * ctx.sceneData.MyGlb.Camera.$object // → THREE.Camera
7436
+ * ctx.sceneData.MyGlb.UI.Button.$components.Button // → Needle Button component
7166
7437
  *
7167
- * If a node or component is not found, property accesses log a warning
7168
- * instead of throwing, so chained access never crashes.
7169
- *
7170
- * @example
7171
- * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
7438
+ * GLB name is ignored at runtime (scene is already loaded).
7439
+ * Node lookup starts at the scene root.
7172
7440
  */
7173
7441
  export declare function getSceneData(ctx: IContext): SceneData;
7174
7442
 
@@ -7761,7 +8029,7 @@ export declare class HingeJoint extends Joint {
7761
8029
  anchor?: Vector3;
7762
8030
  /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
7763
8031
  axis?: Vector3;
7764
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
8032
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
7765
8033
  }
7766
8034
 
7767
8035
  declare type HitPointObject = Object3D & {
@@ -7984,7 +8252,7 @@ declare const HTMLElementBase: typeof HTMLElement;
7984
8252
 
7985
8253
  export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
7986
8254
  isAnimationComponent: boolean;
7987
- addClip?(clip: AnimationClip): any;
8255
+ addClip?(clip: AnimationClip): void;
7988
8256
  };
7989
8257
 
7990
8258
  /* Excluded from this release type: IApplyPrototypeExtension */
@@ -8058,6 +8326,12 @@ export declare interface ICollider extends IComponent {
8058
8326
  * Default: undefined
8059
8327
  */
8060
8328
  filter?: number[];
8329
+ /** The density of the collider used for automatic mass calculation.
8330
+ * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
8331
+ * Note: Make sure to call updateProperties after having changed this property
8332
+ * Default: undefined (uses physics engine default of 1.0)
8333
+ */
8334
+ density?: number;
8061
8335
  }
8062
8336
 
8063
8337
  export declare type ICollisionContext = {
@@ -8084,7 +8358,6 @@ export declare interface IComponent extends IHasGuid {
8084
8358
  /* Excluded from this release type: __internalEnable */
8085
8359
  /* Excluded from this release type: __internalDisable */
8086
8360
  /* Excluded from this release type: __internalDestroy */
8087
- /* Excluded from this release type: resolveGuids */
8088
8361
  /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
8089
8362
  registering?(): any;
8090
8363
  awake(): any;
@@ -8121,6 +8394,24 @@ export declare interface IConnectionData {
8121
8394
 
8122
8395
  export declare type IContext = Context;
8123
8396
 
8397
+ /**
8398
+ * Interface for objects that hold resources and can be disposed.
8399
+ * Implement this interface on any object that needs deterministic cleanup.
8400
+ *
8401
+ * @example
8402
+ * ```ts
8403
+ * class MyResource implements IDisposable {
8404
+ * dispose() { /* release resources *\/ }
8405
+ * }
8406
+ * ```
8407
+ *
8408
+ * @category Utilities
8409
+ * @group Lifecycle
8410
+ */
8411
+ export declare interface IDisposable {
8412
+ dispose(): void;
8413
+ }
8414
+
8124
8415
  /** Implement to receive callbacks from {@type @needle-tools/editor-sync} package */
8125
8416
  declare interface IEditorModification {
8126
8417
  /**
@@ -8140,7 +8431,6 @@ export declare interface IEffectProvider {
8140
8431
 
8141
8432
  export declare interface IEventList {
8142
8433
  readonly isEventList: true;
8143
- __internalOnInstantiate(map: InstantiateContext): IEventList;
8144
8434
  }
8145
8435
 
8146
8436
  export declare interface IGameObject extends Object3D {
@@ -8241,6 +8531,8 @@ declare interface ILayoutGroup extends IComponent {
8241
8531
  export declare interface ILight extends IComponent {
8242
8532
  intensity: number;
8243
8533
  color: Color;
8534
+ /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
8535
+ readonly type: "directional" | "point" | "spot";
8244
8536
  }
8245
8537
 
8246
8538
  declare interface ILightDataRegistry {
@@ -8457,10 +8749,20 @@ export declare class InheritVelocityModule {
8457
8749
  applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
8458
8750
  }
8459
8751
 
8752
+ /* Excluded from this release type: initAddressableSerializers */
8753
+
8754
+ /** Register all builtin serializers and prototype patches.
8755
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
8756
+ * when the package declares `sideEffects: false`.
8757
+ */
8758
+ export declare function initBuiltinSerializers(): void;
8759
+
8460
8760
  /** Register the Rapier physics backend. Called from {@link initEngine}
8461
8761
  * to ensure it runs regardless of tree-shaking. */
8462
8762
  export declare function initPhysics(): void;
8463
8763
 
8764
+ /* Excluded from this release type: initVolumeParameterSerializer */
8765
+
8464
8766
  /**
8465
8767
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
8466
8768
  * Access via `this.context.input` from any component.
@@ -8984,7 +9286,7 @@ export declare function instantiate(instance: AssetReference, opts?: IInstantiat
8984
9286
  export declare function instantiate(instance: IGameObject | Object3D, opts?: IInstantiateOptions | null): IGameObject;
8985
9287
 
8986
9288
  /**
8987
- * Provides access to the instantiated object and its clone
9289
+ * Provides access to the instantiated object map (used by EventList etc.)
8988
9290
  */
8989
9291
  export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
8990
9292
 
@@ -9024,7 +9326,8 @@ export declare class InstantiateOptions implements IInstantiateOptions {
9024
9326
  cloneAssign(other: InstantiateOptions | IInstantiateOptions): void;
9025
9327
  }
9026
9328
 
9027
- declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9329
+ /** Maps uuid/guid → { original, clone } for Object3D and Component instances */
9330
+ export declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9028
9331
 
9029
9332
  /**
9030
9333
  * An empty component that can be used to mark an object as interactable.
@@ -9095,8 +9398,10 @@ export declare interface IPhysicsEngine {
9095
9398
  postStep(): any;
9096
9399
  /** Indicates whether the physics engine is currently updating */
9097
9400
  get isUpdating(): boolean;
9098
- /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
9099
- clearCaches(): any;
9401
+ /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
9402
+ dispose(): void;
9403
+ /** @deprecated Use {@link dispose} instead. */
9404
+ clearCaches(): void;
9100
9405
  /** Enables or disables the physics engine */
9101
9406
  enabled: boolean;
9102
9407
  /** Returns the underlying physics world object */
@@ -9326,8 +9631,9 @@ export declare interface IPhysicsEngine {
9326
9631
  * @returns The underlying physics body or null if not found
9327
9632
  */
9328
9633
  getBody(obj: ICollider | IRigidbody): null | any;
9329
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): any;
9330
- addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): any;
9634
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
9635
+ addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
9636
+ removeJoint(joint: any): void;
9331
9637
  /** Enable to render collider shapes */
9332
9638
  debugRenderColliders: boolean;
9333
9639
  /** Enable to visualize raycasts in the scene with gizmos */
@@ -9548,6 +9854,18 @@ export declare function isDestroyed(go: Object3D): boolean;
9548
9854
  /** True when the application runs on a local url */
9549
9855
  export declare function isDevEnvironment(): boolean;
9550
9856
 
9857
+ /**
9858
+ * Type guard to check if an object implements {@link IDisposable}.
9859
+ *
9860
+ * @example
9861
+ * ```ts
9862
+ * if (isDisposable(obj)) {
9863
+ * obj.dispose(); // safe to call
9864
+ * }
9865
+ * ```
9866
+ */
9867
+ export declare function isDisposable(value: unknown): value is IDisposable;
9868
+
9551
9869
  export declare function isDisposed(obj: object): boolean;
9552
9870
 
9553
9871
  export declare interface ISerializable {
@@ -9582,6 +9900,10 @@ export declare function isHotReloadEnabled(): boolean;
9582
9900
  /**@returns true if the element is an needle engine icon element */
9583
9901
  export declare function isIconElement(element: Node): boolean;
9584
9902
 
9903
+ export declare interface ISignalReceiver {
9904
+ readonly isSignalReceiver: true;
9905
+ }
9906
+
9585
9907
  /** @deprecated use {@link DeviceUtilities.isiOS} instead */
9586
9908
  export declare function isiOS(): boolean;
9587
9909
 
@@ -9616,6 +9938,8 @@ export declare function isResourceTrackingEnabled(): boolean;
9616
9938
  /** @deprecated use {@link DeviceUtilities.isSafari} instead */
9617
9939
  export declare function isSafari(): boolean;
9618
9940
 
9941
+ export declare function isTrackModel(obj: unknown): obj is TrackModel;
9942
+
9619
9943
  export declare function isUsingInstancing(instance: Object3D): boolean;
9620
9944
 
9621
9945
  export declare interface ITime {
@@ -9740,7 +10064,9 @@ declare abstract class Joint extends Component {
9740
10064
  connectedBody?: Rigidbody;
9741
10065
  get rigidBody(): Rigidbody | null;
9742
10066
  private _rigidBody;
10067
+ private _jointHandle;
9743
10068
  onEnable(): void;
10069
+ onDisable(): void;
9744
10070
  private create;
9745
10071
  protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
9746
10072
  }
@@ -9878,10 +10204,13 @@ declare type LifecycleMethodOptions = {
9878
10204
  */
9879
10205
  export declare class Light extends Component implements ILight {
9880
10206
  /**
9881
- * The type of light (spot, directional, point, etc.)
9882
- * Can not be changed at runtime.
10207
+ * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
10208
+ * Implements {@link ILight.type}. Can not be changed at runtime.
9883
10209
  */
9884
- private type;
10210
+ get type(): ILight["type"];
10211
+ /** Numeric LightType serialized from Unity/Blender — converts to string on write */
10212
+ set type(value: LightType | ILight["type"]);
10213
+ private _type;
9885
10214
  /**
9886
10215
  * The maximum distance the light affects.
9887
10216
  * Only applicable for spot and point lights.
@@ -9987,11 +10316,6 @@ export declare class Light extends Component implements ILight {
9987
10316
  * and applies all settings like shadows, intensity, and color.
9988
10317
  */
9989
10318
  createLight(): void;
9990
- /**
9991
- * Coroutine that updates the main light reference in the context
9992
- * if this directional light should be the main light
9993
- */
9994
- updateMainLightRoutine(): Generator<undefined, void, unknown>;
9995
10319
  /**
9996
10320
  * Controls whether the renderer's shadow map type can be changed when soft shadows are used
9997
10321
  */
@@ -10040,6 +10364,25 @@ declare enum LightShadows {
10040
10364
  Soft = 2
10041
10365
  }
10042
10366
 
10367
+ /**
10368
+ * Defines the type of light in a scene.
10369
+ * @see {@link Light} for configuring light properties and behavior
10370
+ */
10371
+ declare enum LightType {
10372
+ /** Spot light that emits light in a cone shape */
10373
+ Spot = 0,
10374
+ /** Directional light that emits parallel light rays in a specific direction */
10375
+ Directional = 1,
10376
+ /** Point light that emits light in all directions from a single point */
10377
+ Point = 2,
10378
+ /** Area light */
10379
+ Area = 3,
10380
+ /** Rectangle shaped area light that only affects baked lightmaps and light probes */
10381
+ Rectangle = 3,
10382
+ /** Disc shaped area light that only affects baked lightmaps and light probes */
10383
+ Disc = 4
10384
+ }
10385
+
10043
10386
  export declare class LimitVelocityOverLifetimeModule {
10044
10387
  enabled: boolean;
10045
10388
  dampen: number;
@@ -10985,6 +11328,7 @@ export declare type Model = (GLTF | FBX | OBJ | CustomModel);
10985
11328
 
10986
11329
  declare namespace Models {
10987
11330
  export {
11331
+ isTrackModel,
10988
11332
  TimelineAssetModel,
10989
11333
  TrackType,
10990
11334
  ClipExtrapolation,
@@ -11028,15 +11372,13 @@ export declare type MouseButtonName = "left" | "right" | "middle";
11028
11372
  /* Excluded from this release type: nameofFactory */
11029
11373
 
11030
11374
  /**
11031
- * Global proxy for the primary Needle Engine context.
11032
- * Resolves lazily on property access via `ContextRegistry.Current` —
11033
- * safe to import at module level, including in SSR environments
11034
- * (returns a silent error proxy when no context is active).
11375
+ * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
11376
+ * Use it in React/Svelte/Vue components, button handlers, or plain JavaScript.
11035
11377
  *
11036
- * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
11037
- * components, button handlers, or vanilla JS) instead of threading `ctx` around.
11378
+ * Safe to import at module level, including in SSR environments.
11379
+ * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
11038
11380
  *
11039
- * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
11381
+ * @experimental This API may change in future releases.
11040
11382
  *
11041
11383
  * @example
11042
11384
  * import { needle } from "@needle-tools/engine";
@@ -11194,11 +11536,17 @@ export declare interface NeedleEngineAttributes {
11194
11536
  'hash': string;
11195
11537
  /** Set to automatically add OrbitControls to the loaded scene. */
11196
11538
  'camera-controls': string;
11197
- /** Override the default draco decoder path location. */
11539
+ /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
11540
+ * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
11541
+ * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
11542
+ */
11198
11543
  'dracoDecoderPath': string;
11199
- /** Override the default draco library type. */
11544
+ /** Override the default Draco decoder type. */
11200
11545
  'dracoDecoderType': 'wasm' | 'js';
11201
- /** Override the default KTX2 transcoder/decoder path. */
11546
+ /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
11547
+ * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
11548
+ * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
11549
+ */
11202
11550
  'ktx2DecoderPath': string;
11203
11551
  /** Prevent context from being disposed when element is removed from DOM. */
11204
11552
  'keep-alive': 'true' | 'false';
@@ -12152,8 +12500,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
12152
12500
  get referenceSpace(): XRSpace | null;
12153
12501
  /** @returns the XRFrame `viewerpose` using the xr `referenceSpace` */
12154
12502
  get viewerPose(): XRViewerPose | undefined;
12155
- /** @returns `true` if any image is currently being tracked */
12156
- /** returns true if images are currently being tracked */
12503
+ /** @returns `true` if any image is currently being tracked or emulated */
12157
12504
  get isTrackingImages(): boolean;
12158
12505
  /** The currently active XR rig */
12159
12506
  get rig(): IXRRig | null;
@@ -12199,6 +12546,8 @@ export declare class NeedleXRSession implements INeedleXRSession {
12199
12546
  private readonly _xr_update_scripts;
12200
12547
  /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
12201
12548
  private readonly _inactive_scripts;
12549
+ /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
12550
+ private readonly _scripts_in_xr;
12202
12551
  private readonly _controllerAdded;
12203
12552
  private readonly _controllerRemoved;
12204
12553
  private readonly _originalCameraWorldPosition?;
@@ -12818,7 +13167,7 @@ export declare interface NetworkEventMap {
12818
13167
  * @see {@link RoomEvents} for room lifecycle events
12819
13168
  * @see {@link isLocalNetwork} for local network detection
12820
13169
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
12821
- * @summary Networking configuration
13170
+ * @summary Configures the websocket server URL for multiplayer networking
12822
13171
  * @category Networking
12823
13172
  * @group Components
12824
13173
  */
@@ -12955,7 +13304,7 @@ export declare type OBJ = {
12955
13304
  scenes: Object3D[];
12956
13305
  };
12957
13306
 
12958
- declare type ObjectCloneReference = {
13307
+ export declare type ObjectCloneReference = {
12959
13308
  readonly original: object;
12960
13309
  readonly clone: object;
12961
13310
  };
@@ -13039,7 +13388,7 @@ declare class ObjectSerializer extends TypeSerializer {
13039
13388
  onDeserialize(data: ObjectData | string | null, context: SerializationContext): Object3D<Object3DEventMap> | Component | null | undefined;
13040
13389
  }
13041
13390
 
13042
- export declare const objectSerializer: ObjectSerializer;
13391
+ export declare let objectSerializer: ObjectSerializer;
13043
13392
 
13044
13393
  declare type ObjectToNodeMap = {
13045
13394
  [uuid: string]: number;
@@ -13162,6 +13511,60 @@ export declare function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void):
13162
13511
  */
13163
13512
  export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
13164
13513
 
13514
+ /**
13515
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
13516
+ * and return an {@link IDisposable} that removes the listener when disposed.
13517
+ *
13518
+ * Provides full TypeScript event type inference — the callback parameter
13519
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
13520
+ * `"click"` → `MouseEvent`).
13521
+ *
13522
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
13523
+ *
13524
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
13525
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
13526
+ * @param listener The event handler callback
13527
+ * @param options Optional addEventListener options (passive, capture, once, signal)
13528
+ * @returns An {@link IDisposable} that removes the event listener when disposed
13529
+ *
13530
+ * @example Standalone usage
13531
+ * ```ts
13532
+ * import { on } from "@needle-tools/engine";
13533
+ *
13534
+ * const sub = on(window, "resize", (ev) => {
13535
+ * // ev is typed as UIEvent
13536
+ * console.log("resized", ev.target);
13537
+ * });
13538
+ *
13539
+ * // Later: clean up
13540
+ * sub.dispose();
13541
+ * ```
13542
+ *
13543
+ * @example With autoCleanup in a component
13544
+ * ```ts
13545
+ * import { Behaviour, on } from "@needle-tools/engine";
13546
+ *
13547
+ * export class MyComponent extends Behaviour {
13548
+ * onEnable() {
13549
+ * this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
13550
+ * this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
13551
+ * this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
13552
+ * }
13553
+ * // All listeners removed automatically on disable!
13554
+ * }
13555
+ * ```
13556
+ *
13557
+ * @category Utilities
13558
+ * @group Lifecycle
13559
+ */
13560
+ export declare function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13561
+
13562
+ export declare function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13563
+
13564
+ export declare function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13565
+
13566
+ export declare function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
13567
+
13165
13568
  /**
13166
13569
  * Register a callback in the engine onAfterRender event
13167
13570
  * This is called every frame after the main camera has rendered
@@ -14635,13 +15038,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14635
15038
  * The timeline asset containing tracks, clips, and markers that this director will play.
14636
15039
  * Assign a timeline asset exported from Unity or Blender to enable playback.
14637
15040
  */
14638
- playableAsset?: Models.TimelineAssetModel;
15041
+ get playableAsset(): Models.TimelineAssetModel | undefined;
15042
+ set playableAsset(value: Models.TimelineAssetModel | undefined);
15043
+ private _playableAsset?;
14639
15044
  /**
14640
15045
  * When true, the timeline starts playing automatically when the component awakens.
14641
15046
  * Set to false to control playback manually via `play()`.
14642
15047
  * @default false
14643
15048
  */
14644
- playOnAwake?: boolean;
15049
+ playOnAwake: boolean;
14645
15050
  /**
14646
15051
  * Determines how the timeline behaves when it reaches the end of its duration.
14647
15052
  * @default DirectorWrapMode.Loop
@@ -14736,6 +15141,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
14736
15141
  * @returns all marker tracks of the timeline
14737
15142
  */
14738
15143
  get markerTracks(): Tracks.MarkerTrackHandler[];
15144
+ /**
15145
+ * @returns all activation tracks of the timeline
15146
+ */
15147
+ get activationTracks(): Tracks.ActivationTrackHandler[];
15148
+ /**
15149
+ * @returns all tracks of the timeline
15150
+ */
15151
+ get tracks(): ReadonlyArray<Tracks.TrackHandler>;
14739
15152
  /**
14740
15153
  * Iterates over all markers of the timeline, optionally filtering by type
14741
15154
  *
@@ -14749,13 +15162,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
14749
15162
  *
14750
15163
  */
14751
15164
  foreachMarker<T extends Record<string, any>>(type?: string | null): Generator<(T & Models.MarkerModel)>;
14752
- private _guidsMap?;
14753
- /* Excluded from this release type: resolveGuids */
15165
+ private _needsGraphRebuild;
14754
15166
  private _isPlaying;
14755
15167
  private _internalUpdateRoutine;
14756
15168
  private _isPaused;
14757
15169
  /** internal, true during the time stop() is being processed */
14758
15170
  private _isStopping;
15171
+ /* Excluded from this release type: _isUserEvaluation */
14759
15172
  private _time;
14760
15173
  private _duration;
14761
15174
  private _weight;
@@ -14764,6 +15177,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
14764
15177
  private readonly _signalTracks;
14765
15178
  private readonly _markerTracks;
14766
15179
  private readonly _controlTracks;
15180
+ private readonly _activationTracks;
14767
15181
  private readonly _customTracks;
14768
15182
  private readonly _tracksArray;
14769
15183
  private get _allTracks();
@@ -15942,6 +16356,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
15942
16356
  private _gravity;
15943
16357
  get gravity(): Vec3;
15944
16358
  set gravity(value: Vec3);
16359
+ /** Tears down the physics world and frees all WASM resources.
16360
+ * After calling this, the world will be re-created on next use. */
16361
+ dispose(): void;
16362
+ /** @deprecated Use {@link dispose} instead. */
15945
16363
  clearCaches(): void;
15946
16364
  addBoxCollider(collider: ICollider, size: Vector3): Promise<void>;
15947
16365
  addSphereCollider(collider: ICollider): Promise<void>;
@@ -15988,7 +16406,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
15988
16406
  private getRigidbodyRelativeMatrix;
15989
16407
  private static centerConnectionPos;
15990
16408
  private static centerConnectionRot;
15991
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): void;
16409
+ private _jointTempMatrix;
16410
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<ImpulseJoint | null>;
15992
16411
  /** 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. */
15993
16412
  addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: {
15994
16413
  x: number;
@@ -15998,8 +16417,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
15998
16417
  x: number;
15999
16418
  y: number;
16000
16419
  z: number;
16001
- }): void;
16420
+ }): Promise<ImpulseJoint | null>;
16421
+ removeJoint(joint: ImpulseJoint): void;
16422
+ /** Compute the relative transform from body1's local space to body2's local space (W2⁻¹ * W1), ignoring scale. */
16002
16423
  private calculateJointRelativeMatrices;
16424
+ private normalizeMatrixColumns;
16003
16425
  }
16004
16426
 
16005
16427
  /**
@@ -16802,10 +17224,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
16802
17224
  */
16803
17225
  export declare class Rigidbody extends Component implements IRigidbody {
16804
17226
  get isRigidbody(): boolean;
16805
- /** When true the mass will be automatically calculated by the attached colliders */
17227
+ /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
17228
+ * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
17229
+ * Disable to set mass explicitly via the `mass` property.
17230
+ */
16806
17231
  autoMass: boolean;
16807
- /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes
16808
- * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
17232
+ /** The mass of the rigidbody in kg (when `autoMass` is disabled).
17233
+ * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
17234
+ * Setting this property automatically disables `autoMass`.
17235
+ *
17236
+ * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
17237
+ * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
16809
17238
  */
16810
17239
  set mass(value: number);
16811
17240
  get mass(): number;
@@ -16888,7 +17317,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16888
17317
  onEnable(): void;
16889
17318
  onDisable(): void;
16890
17319
  onDestroy(): void;
16891
- onValidate(): void;
17320
+ onValidate(property?: string): void;
17321
+ private static _didWarnAutoMass;
16892
17322
  beforePhysics(): Generator<undefined, void, unknown>;
16893
17323
  /** Teleport the rigidbody to a new position in the world.
16894
17324
  * Will reset forces before setting the object world position
@@ -18544,6 +18974,16 @@ export declare class OrbitControls extends Component implements ICameraControlle
18544
18974
  asset: string;
18545
18975
  }
18546
18976
 
18977
+ /**
18978
+ * Options for a signal marker in the timeline builder
18979
+ */
18980
+ export declare type SignalMarkerOptions = {
18981
+ /** Whether the signal should fire if the playback starts past its time (default: false) */
18982
+ retroActive?: boolean;
18983
+ /** Whether the signal should only fire once (default: false) */
18984
+ emitOnce?: boolean;
18985
+ };
18986
+
18547
18987
  /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received.
18548
18988
  * Signals can be added to a signal track on a {@link PlayableDirector}
18549
18989
  *
@@ -18551,7 +18991,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
18551
18991
  * @category Animation and Sequencing
18552
18992
  * @group Components
18553
18993
  */
18554
- export declare class SignalReceiver extends Component {
18994
+ export declare class SignalReceiver extends Component implements ISignalReceiver {
18995
+ readonly isSignalReceiver = true;
18555
18996
  private static receivers;
18556
18997
  static invoke(guid: string): void;
18557
18998
  events?: SignalReceiverEvent[];
@@ -18574,6 +19015,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
18574
19015
  models: Models.SignalMarkerModel[];
18575
19016
  didTrigger: boolean[];
18576
19017
  receivers: Array<SignalReceiver | null>;
19018
+ private _lastTime;
19019
+ onEnable(): void;
19020
+ onMuteChanged(): void;
18577
19021
  evaluate(time: number): void;
18578
19022
  }
18579
19023
 
@@ -19073,10 +19517,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
19073
19517
  * Removes scale change monitoring when the collider is disabled.
19074
19518
  */
19075
19519
  onDisable(): void;
19076
- /**
19077
- * Updates collider properties when validated in the editor or inspector.
19078
- */
19079
- onValidate(): void;
19080
19520
  }
19081
19521
 
19082
19522
  export declare class SphereIntersection implements Intersection {
@@ -20396,6 +20836,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
20396
20836
  set font(val: string | null);
20397
20837
  get font(): string | null;
20398
20838
  private _font;
20839
+ private _assignedAtRuntime;
20399
20840
  /**
20400
20841
  * 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>`
20401
20842
  * @default false
@@ -20660,6 +21101,166 @@ export declare class OrbitControls extends Component implements ICameraControlle
20660
21101
  tracks: TrackModel[];
20661
21102
  };
20662
21103
 
21104
+ /**
21105
+ * A fluent builder for creating timeline assets ({@link TimelineAssetModel}) from code.
21106
+ *
21107
+ * Use {@link TimelineBuilder.create} to start building a timeline.
21108
+ *
21109
+ * @example Using build() for timelines without signal callbacks
21110
+ * ```ts
21111
+ * const timeline = TimelineBuilder.create("MySequence")
21112
+ * .animationTrack("Character", animator)
21113
+ * .clip(walkClip, { duration: 2, easeIn: 0.3 })
21114
+ * .clip(runClip, { duration: 3, easeIn: 0.5, easeOut: 0.5 })
21115
+ * .activationTrack("FX", particleObject)
21116
+ * .clip({ start: 1, duration: 2 })
21117
+ * .audioTrack("Music", audioSource)
21118
+ * .clip("music.mp3", { start: 0, duration: 5, volume: 0.8 })
21119
+ * .build();
21120
+ *
21121
+ * director.playableAsset = timeline;
21122
+ * director.play();
21123
+ * ```
21124
+ *
21125
+ * @example Using install() with signal callbacks
21126
+ * ```ts
21127
+ * TimelineBuilder.create("WithSignals")
21128
+ * .animationTrack("Character", animator)
21129
+ * .clip(walkClip, { duration: 2 })
21130
+ * .signalTrack("Events")
21131
+ * .signal(1.0, () => console.log("1 second!"))
21132
+ * .signal(2.0, () => spawnParticles())
21133
+ * .install(director);
21134
+ *
21135
+ * director.play();
21136
+ * ```
21137
+ *
21138
+ * @category Animation and Sequencing
21139
+ * @group Utilities
21140
+ */
21141
+ export declare class TimelineBuilder {
21142
+ private _name;
21143
+ private _tracks;
21144
+ private _currentTrack;
21145
+ private _pendingSignals;
21146
+ private _idProvider;
21147
+ private constructor();
21148
+ /**
21149
+ * Creates a new TimelineBuilder instance.
21150
+ * @param name - Name for the timeline asset
21151
+ * @param seed - Optional numeric seed for deterministic guid generation. Defaults to `Date.now()`.
21152
+ */
21153
+ static create(name?: string, seed?: number): TimelineBuilder;
21154
+ /**
21155
+ * Adds an animation track. Subsequent `.clip()` calls add animation clips to this track.
21156
+ * @param name - Display name for the track
21157
+ * @param binding - The Animator or Object3D to animate
21158
+ */
21159
+ animationTrack(name: string, binding?: Animator | Object3D | null): this;
21160
+ /**
21161
+ * Adds an audio track. Subsequent `.clip()` calls add audio clips to this track.
21162
+ * @param name - Display name for the track
21163
+ * @param binding - The AudioSource to play audio on (optional)
21164
+ * @param volume - Track volume multiplier (default: 1)
21165
+ */
21166
+ audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): this;
21167
+ /**
21168
+ * Adds an activation track. Subsequent `.clip()` calls define when the bound object is active.
21169
+ * @param name - Display name for the track
21170
+ * @param binding - The Object3D to show/hide
21171
+ */
21172
+ activationTrack(name: string, binding?: Object3D | null): this;
21173
+ /**
21174
+ * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
21175
+ * @param name - Display name for the track
21176
+ */
21177
+ controlTrack(name: string): this;
21178
+ /**
21179
+ * Adds a signal track. Use `.signal()` or `.marker()` to add signal markers.
21180
+ * @param name - Display name for the track
21181
+ * @param binding - The SignalReceiver component (optional — if using `.signal()` with callbacks, one is created automatically by {@link install})
21182
+ */
21183
+ signalTrack(name: string, binding?: SignalReceiver | Object3D | null): this;
21184
+ /**
21185
+ * Adds a marker track. Use `.marker()` to add markers.
21186
+ * @param name - Display name for the track
21187
+ */
21188
+ markerTrack(name: string): this;
21189
+ /**
21190
+ * Adds a clip to the current track. The clip type must match the track type.
21191
+ *
21192
+ * - On an **animation track**: pass an `AnimationClip` and optional {@link AnimationClipOptions}
21193
+ * - On an **audio track**: pass a clip URL (string) and {@link AudioClipOptions}
21194
+ * - On an **activation track**: pass {@link ActivationClipOptions}
21195
+ * - On a **control track**: pass an Object3D and {@link ControlClipOptions}
21196
+ */
21197
+ clip(asset: AnimationClip, options?: AnimationClipOptions): this;
21198
+ clip(url: string, options: AudioClipOptions): this;
21199
+ clip(options: ActivationClipOptions): this;
21200
+ clip(sourceObject: Object3D, options: ControlClipOptions): this;
21201
+ /**
21202
+ * Adds a signal marker to the current signal or marker track.
21203
+ * @param time - Time in seconds when the signal fires
21204
+ * @param asset - The signal asset identifier (guid string)
21205
+ * @param options - Optional marker configuration
21206
+ */
21207
+ marker(time: number, asset: string, options?: SignalMarkerOptions): this;
21208
+ /**
21209
+ * Adds a signal with a callback to the current signal track.
21210
+ * This is a convenience method that automatically generates a signal asset guid,
21211
+ * adds the marker, and registers the callback so that {@link install} can wire up
21212
+ * the `SignalReceiver` on the director's GameObject.
21213
+ *
21214
+ * @param time - Time in seconds when the signal fires
21215
+ * @param callback - The function to invoke when the signal fires
21216
+ * @param options - Optional marker configuration
21217
+ *
21218
+ * @example
21219
+ * ```ts
21220
+ * const timeline = TimelineBuilder.create("Sequence")
21221
+ * .signalTrack("Events")
21222
+ * .signal(1.0, () => console.log("1 second reached!"))
21223
+ * .signal(3.5, () => console.log("halfway!"), { emitOnce: true })
21224
+ * .install(director);
21225
+ * ```
21226
+ */
21227
+ signal(time: number, callback: Function, options?: SignalMarkerOptions): this;
21228
+ /**
21229
+ * Mutes the current track so it is skipped during playback.
21230
+ */
21231
+ muted(muted?: boolean): this;
21232
+ /**
21233
+ * Builds and returns the {@link TimelineAssetModel}.
21234
+ * Assign the result to `PlayableDirector.playableAsset` to play it.
21235
+ *
21236
+ * If you used `.signal()` with callbacks, use {@link install} instead — it calls `build()`
21237
+ * internally and also wires up the SignalReceiver on the director's GameObject.
21238
+ */
21239
+ build(): TimelineAssetModel;
21240
+ /**
21241
+ * Builds the timeline asset, assigns it to the director, and wires up any
21242
+ * `.signal()` callbacks by creating/configuring a {@link SignalReceiver} on the
21243
+ * director's GameObject.
21244
+ *
21245
+ * @param director - The PlayableDirector to install the timeline on
21246
+ * @returns The built TimelineAssetModel (also assigned to `director.playableAsset`)
21247
+ *
21248
+ * @example
21249
+ * ```ts
21250
+ * TimelineBuilder.create("MyTimeline")
21251
+ * .animationTrack("Anim", animator)
21252
+ * .clip(walkClip, { duration: 2 })
21253
+ * .signalTrack("Events")
21254
+ * .signal(1.0, () => console.log("signal fired!"))
21255
+ * .install(director);
21256
+ *
21257
+ * director.play();
21258
+ * ```
21259
+ */
21260
+ install(director: PlayableDirector): TimelineAssetModel;
21261
+ private pushTrack;
21262
+ }
21263
+
20663
21264
  declare type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
20664
21265
 
20665
21266
  /**
@@ -20741,6 +21342,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
20741
21342
  AudioTrackHandler,
20742
21343
  MarkerTrackHandler,
20743
21344
  SignalTrackHandler,
21345
+ ActivationTrackHandler,
20744
21346
  ControlTrackHandler
20745
21347
  }
20746
21348
  }
@@ -23507,6 +24109,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
23507
24109
  export { }
23508
24110
 
23509
24111
 
24112
+ declare module 'three' {
24113
+ interface SkinnedMesh {
24114
+ staticGenerator?: StaticGeometryGenerator;
24115
+ staticGeometry?: BufferGeometry;
24116
+ staticGeometryLastUpdate?: number;
24117
+ }
24118
+ interface Mesh {
24119
+ acceleratedRaycast?: any;
24120
+ }
24121
+ interface SkinnedMesh {
24122
+ /** @deprecated use autoUpdateMeshBvhInterval */
24123
+ autoUpdateMeshBVH?: boolean;
24124
+ /**
24125
+ * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
24126
+ * @default undefined (disabled)
24127
+ */
24128
+ autoUpdateMeshBvhInterval?: number;
24129
+ bvhNeedsUpdate?: boolean;
24130
+ }
24131
+ }
24132
+
24133
+
23510
24134
  declare module 'three' {
23511
24135
  interface Object3D {
23512
24136
  get guid(): string | undefined;
@@ -23652,25 +24276,3 @@ declare module 'three' {
23652
24276
  slerp(end: Vector3, t: number): Vector3;
23653
24277
  }
23654
24278
  }
23655
-
23656
-
23657
- declare module 'three' {
23658
- interface SkinnedMesh {
23659
- staticGenerator?: StaticGeometryGenerator;
23660
- staticGeometry?: BufferGeometry;
23661
- staticGeometryLastUpdate?: number;
23662
- }
23663
- interface Mesh {
23664
- acceleratedRaycast?: any;
23665
- }
23666
- interface SkinnedMesh {
23667
- /** @deprecated use autoUpdateMeshBvhInterval */
23668
- autoUpdateMeshBVH?: boolean;
23669
- /**
23670
- * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
23671
- * @default undefined (disabled)
23672
- */
23673
- autoUpdateMeshBvhInterval?: number;
23674
- bvhNeedsUpdate?: boolean;
23675
- }
23676
- }