@needle-tools/engine 5.1.0-canary.e9062c0 → 5.1.0-canary.f57972c

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 (322) hide show
  1. package/CHANGELOG.md +120 -0
  2. package/SKILL.md +4 -1
  3. package/components.needle.json +1 -1
  4. package/dist/{needle-engine.bundle-CDKcuALa.js → needle-engine.bundle-CAIG39cL.js} +13605 -12680
  5. package/dist/needle-engine.bundle-CFh_isu6.umd.cjs +1734 -0
  6. package/dist/needle-engine.bundle-CtadUKoi.min.js +1734 -0
  7. package/dist/needle-engine.d.ts +1579 -394
  8. package/dist/needle-engine.js +542 -538
  9. package/dist/needle-engine.min.js +1 -1
  10. package/dist/needle-engine.umd.cjs +1 -1
  11. package/dist/three.js +1 -0
  12. package/dist/three.min.js +21 -21
  13. package/dist/three.umd.cjs +16 -16
  14. package/lib/engine/api.d.ts +8 -1
  15. package/lib/engine/api.js +7 -1
  16. package/lib/engine/api.js.map +1 -1
  17. package/lib/engine/codegen/register_types.js +10 -18
  18. package/lib/engine/codegen/register_types.js.map +1 -1
  19. package/lib/engine/debug/debug_spatial_console.d.ts +2 -0
  20. package/lib/engine/debug/debug_spatial_console.js +10 -7
  21. package/lib/engine/debug/debug_spatial_console.js.map +1 -1
  22. package/lib/engine/engine_addressables.d.ts +2 -0
  23. package/lib/engine/engine_addressables.js +6 -3
  24. package/lib/engine/engine_addressables.js.map +1 -1
  25. package/lib/engine/engine_audio.d.ts +68 -0
  26. package/lib/engine/engine_audio.js +172 -0
  27. package/lib/engine/engine_audio.js.map +1 -1
  28. package/lib/engine/engine_camera.fit.js +16 -4
  29. package/lib/engine/engine_camera.fit.js.map +1 -1
  30. package/lib/engine/engine_components.js +1 -1
  31. package/lib/engine/engine_components.js.map +1 -1
  32. package/lib/engine/engine_context.d.ts +37 -27
  33. package/lib/engine/engine_context.js +51 -31
  34. package/lib/engine/engine_context.js.map +1 -1
  35. package/lib/engine/engine_context_eventbus.d.ts +47 -0
  36. package/lib/engine/engine_context_eventbus.js +47 -0
  37. package/lib/engine/engine_context_eventbus.js.map +1 -0
  38. package/lib/engine/engine_disposable.d.ts +172 -0
  39. package/lib/engine/engine_disposable.js +136 -0
  40. package/lib/engine/engine_disposable.js.map +1 -0
  41. package/lib/engine/engine_gameobject.d.ts +1 -10
  42. package/lib/engine/engine_gameobject.js +22 -120
  43. package/lib/engine/engine_gameobject.js.map +1 -1
  44. package/lib/engine/engine_gltf_builtin_components.js +7 -69
  45. package/lib/engine/engine_gltf_builtin_components.js.map +1 -1
  46. package/lib/engine/engine_init.js +14 -4
  47. package/lib/engine/engine_init.js.map +1 -1
  48. package/lib/engine/engine_input.d.ts +24 -5
  49. package/lib/engine/engine_input.js +3 -2
  50. package/lib/engine/engine_input.js.map +1 -1
  51. package/lib/engine/engine_instantiate_resolve.d.ts +42 -0
  52. package/lib/engine/engine_instantiate_resolve.js +372 -0
  53. package/lib/engine/engine_instantiate_resolve.js.map +1 -0
  54. package/lib/engine/engine_license.d.ts +7 -7
  55. package/lib/engine/engine_license.js +186 -58
  56. package/lib/engine/engine_license.js.map +1 -1
  57. package/lib/engine/engine_mainloop_utils.js +7 -4
  58. package/lib/engine/engine_mainloop_utils.js.map +1 -1
  59. package/lib/engine/engine_networking.d.ts +51 -37
  60. package/lib/engine/engine_networking.js +132 -82
  61. package/lib/engine/engine_networking.js.map +1 -1
  62. package/lib/engine/engine_networking.transport.websocket.d.ts +15 -0
  63. package/lib/engine/engine_networking.transport.websocket.js +38 -0
  64. package/lib/engine/engine_networking.transport.websocket.js.map +1 -0
  65. package/lib/engine/engine_networking_blob.js +4 -4
  66. package/lib/engine/engine_networking_blob.js.map +1 -1
  67. package/lib/engine/engine_networking_instantiate.js +2 -2
  68. package/lib/engine/engine_networking_instantiate.js.map +1 -1
  69. package/lib/engine/engine_networking_types.d.ts +39 -1
  70. package/lib/engine/engine_networking_types.js +7 -0
  71. package/lib/engine/engine_networking_types.js.map +1 -1
  72. package/lib/engine/engine_physics_rapier.d.ts +21 -3
  73. package/lib/engine/engine_physics_rapier.js +94 -25
  74. package/lib/engine/engine_physics_rapier.js.map +1 -1
  75. package/lib/engine/engine_scenedata.d.ts +5 -7
  76. package/lib/engine/engine_scenedata.js +16 -13
  77. package/lib/engine/engine_scenedata.js.map +1 -1
  78. package/lib/engine/engine_serialization_builtin_serializer.d.ts +10 -16
  79. package/lib/engine/engine_serialization_builtin_serializer.js +56 -46
  80. package/lib/engine/engine_serialization_builtin_serializer.js.map +1 -1
  81. package/lib/engine/engine_serialization_core.d.ts +1 -0
  82. package/lib/engine/engine_serialization_core.js +7 -0
  83. package/lib/engine/engine_serialization_core.js.map +1 -1
  84. package/lib/engine/engine_types.d.ts +29 -11
  85. package/lib/engine/engine_types.js +1 -1
  86. package/lib/engine/engine_types.js.map +1 -1
  87. package/lib/engine/engine_util_decorator.js +7 -2
  88. package/lib/engine/engine_util_decorator.js.map +1 -1
  89. package/lib/engine/engine_utils.d.ts +1 -1
  90. package/lib/engine/engine_utils.js +19 -5
  91. package/lib/engine/engine_utils.js.map +1 -1
  92. package/lib/engine/engine_utils_qrcode.js +2 -2
  93. package/lib/engine/engine_utils_qrcode.js.map +1 -1
  94. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  95. package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js.map +1 -1
  96. package/lib/engine/webcomponents/jsx.d.ts +9 -2
  97. package/lib/engine/webcomponents/needle menu/needle-menu-spatial.js +2 -2
  98. package/lib/engine/webcomponents/needle menu/needle-menu-spatial.js.map +1 -1
  99. package/lib/engine/webcomponents/needle menu/needle-menu.d.ts +1 -1
  100. package/lib/engine/webcomponents/needle menu/needle-menu.js +6 -6
  101. package/lib/engine/webcomponents/needle menu/needle-menu.js.map +1 -1
  102. package/lib/engine/webcomponents/needle-engine.d.ts +10 -4
  103. package/lib/engine/webcomponents/needle-engine.js +3 -3
  104. package/lib/engine/webcomponents/needle-engine.js.map +1 -1
  105. package/lib/engine/webcomponents/needle-engine.loading.js +2 -2
  106. package/lib/engine/webcomponents/needle-engine.loading.js.map +1 -1
  107. package/lib/engine/xr/NeedleXRSession.d.ts +3 -2
  108. package/lib/engine/xr/NeedleXRSession.js +50 -14
  109. package/lib/engine/xr/NeedleXRSession.js.map +1 -1
  110. package/lib/engine/xr/TempXRContext.js +2 -2
  111. package/lib/engine/xr/TempXRContext.js.map +1 -1
  112. package/lib/engine/xr/events.d.ts +1 -1
  113. package/lib/engine/xr/events.js.map +1 -1
  114. package/lib/engine-components/Animation.js +17 -16
  115. package/lib/engine-components/Animation.js.map +1 -1
  116. package/lib/engine-components/AnimationBuilder.d.ts +158 -0
  117. package/lib/engine-components/AnimationBuilder.js +305 -0
  118. package/lib/engine-components/AnimationBuilder.js.map +1 -0
  119. package/lib/engine-components/Animator.d.ts +6 -0
  120. package/lib/engine-components/Animator.js +23 -13
  121. package/lib/engine-components/Animator.js.map +1 -1
  122. package/lib/engine-components/AnimatorController.builder.d.ts +191 -0
  123. package/lib/engine-components/AnimatorController.builder.js +263 -0
  124. package/lib/engine-components/AnimatorController.builder.js.map +1 -0
  125. package/lib/engine-components/AnimatorController.d.ts +4 -119
  126. package/lib/engine-components/AnimatorController.js +37 -233
  127. package/lib/engine-components/AnimatorController.js.map +1 -1
  128. package/lib/engine-components/AudioSource.d.ts +19 -3
  129. package/lib/engine-components/AudioSource.js +121 -68
  130. package/lib/engine-components/AudioSource.js.map +1 -1
  131. package/lib/engine-components/Collider.d.ts +18 -9
  132. package/lib/engine-components/Collider.js +61 -14
  133. package/lib/engine-components/Collider.js.map +1 -1
  134. package/lib/engine-components/Component.d.ts +72 -9
  135. package/lib/engine-components/Component.js +114 -10
  136. package/lib/engine-components/Component.js.map +1 -1
  137. package/lib/engine-components/ContactShadows.d.ts +1 -0
  138. package/lib/engine-components/ContactShadows.js +14 -1
  139. package/lib/engine-components/ContactShadows.js.map +1 -1
  140. package/lib/engine-components/DragControls.d.ts +7 -0
  141. package/lib/engine-components/DragControls.js +19 -7
  142. package/lib/engine-components/DragControls.js.map +1 -1
  143. package/lib/engine-components/DropListener.js +3 -0
  144. package/lib/engine-components/DropListener.js.map +1 -1
  145. package/lib/engine-components/EventList.d.ts +31 -9
  146. package/lib/engine-components/EventList.js +37 -76
  147. package/lib/engine-components/EventList.js.map +1 -1
  148. package/lib/engine-components/Joints.d.ts +4 -2
  149. package/lib/engine-components/Joints.js +19 -3
  150. package/lib/engine-components/Joints.js.map +1 -1
  151. package/lib/engine-components/Light.js +13 -3
  152. package/lib/engine-components/Light.js.map +1 -1
  153. package/lib/engine-components/Networking.d.ts +1 -1
  154. package/lib/engine-components/Networking.js +1 -1
  155. package/lib/engine-components/OrbitControls.d.ts +0 -2
  156. package/lib/engine-components/OrbitControls.js +30 -12
  157. package/lib/engine-components/OrbitControls.js.map +1 -1
  158. package/lib/engine-components/ReflectionProbe.js +2 -0
  159. package/lib/engine-components/ReflectionProbe.js.map +1 -1
  160. package/lib/engine-components/RigidBody.d.ts +12 -4
  161. package/lib/engine-components/RigidBody.js +18 -4
  162. package/lib/engine-components/RigidBody.js.map +1 -1
  163. package/lib/engine-components/SceneSwitcher.js +3 -0
  164. package/lib/engine-components/SceneSwitcher.js.map +1 -1
  165. package/lib/engine-components/SeeThrough.js +2 -2
  166. package/lib/engine-components/SeeThrough.js.map +1 -1
  167. package/lib/engine-components/api.d.ts +2 -1
  168. package/lib/engine-components/api.js +2 -1
  169. package/lib/engine-components/api.js.map +1 -1
  170. package/lib/engine-components/codegen/components.d.ts +7 -13
  171. package/lib/engine-components/codegen/components.js +7 -13
  172. package/lib/engine-components/codegen/components.js.map +1 -1
  173. package/lib/engine-components/export/usdz/USDZExporter.js +4 -4
  174. package/lib/engine-components/export/usdz/USDZExporter.js.map +1 -1
  175. package/lib/engine-components/postprocessing/Effects/Tonemapping.utils.d.ts +1 -1
  176. package/lib/engine-components/postprocessing/VolumeParameter.d.ts +2 -0
  177. package/lib/engine-components/postprocessing/VolumeParameter.js +4 -1
  178. package/lib/engine-components/postprocessing/VolumeParameter.js.map +1 -1
  179. package/lib/engine-components/timeline/PlayableDirector.d.ts +21 -11
  180. package/lib/engine-components/timeline/PlayableDirector.js +75 -67
  181. package/lib/engine-components/timeline/PlayableDirector.js.map +1 -1
  182. package/lib/engine-components/timeline/SignalAsset.d.ts +3 -1
  183. package/lib/engine-components/timeline/SignalAsset.js +1 -0
  184. package/lib/engine-components/timeline/SignalAsset.js.map +1 -1
  185. package/lib/engine-components/timeline/TimelineBuilder.d.ts +413 -0
  186. package/lib/engine-components/timeline/TimelineBuilder.js +506 -0
  187. package/lib/engine-components/timeline/TimelineBuilder.js.map +1 -0
  188. package/lib/engine-components/timeline/TimelineModels.d.ts +2 -1
  189. package/lib/engine-components/timeline/TimelineModels.js +3 -0
  190. package/lib/engine-components/timeline/TimelineModels.js.map +1 -1
  191. package/lib/engine-components/timeline/TimelineTracks.d.ts +37 -6
  192. package/lib/engine-components/timeline/TimelineTracks.js +92 -26
  193. package/lib/engine-components/timeline/TimelineTracks.js.map +1 -1
  194. package/lib/engine-components/timeline/index.d.ts +2 -1
  195. package/lib/engine-components/timeline/index.js +2 -0
  196. package/lib/engine-components/timeline/index.js.map +1 -1
  197. package/lib/engine-components/ui/Canvas.d.ts +1 -1
  198. package/lib/engine-components/ui/Canvas.js +2 -8
  199. package/lib/engine-components/ui/Canvas.js.map +1 -1
  200. package/lib/engine-components/ui/Text.d.ts +1 -0
  201. package/lib/engine-components/ui/Text.js +10 -7
  202. package/lib/engine-components/ui/Text.js.map +1 -1
  203. package/lib/engine-components/web/CursorFollow.d.ts +0 -1
  204. package/lib/engine-components/web/CursorFollow.js +21 -13
  205. package/lib/engine-components/web/CursorFollow.js.map +1 -1
  206. package/lib/engine-components/webxr/WebXRImageTracking.d.ts +62 -1
  207. package/lib/engine-components/webxr/WebXRImageTracking.js +59 -2
  208. package/lib/engine-components/webxr/WebXRImageTracking.js.map +1 -1
  209. package/package.json +2 -83
  210. package/plugins/common/cloud.js +6 -1
  211. package/plugins/common/license.js +31 -10
  212. package/plugins/common/worker.js +9 -4
  213. package/plugins/vite/asap.js +17 -8
  214. package/plugins/vite/dependencies.js +29 -10
  215. package/plugins/vite/dependency-watcher.js +2 -2
  216. package/plugins/vite/editor-connection.js +3 -3
  217. package/plugins/vite/license.js +42 -7
  218. package/plugins/vite/local-files-core.js +3 -3
  219. package/plugins/vite/local-files-utils.d.ts +3 -1
  220. package/plugins/vite/local-files-utils.js +29 -5
  221. package/plugins/vite/reload.js +19 -18
  222. package/plugins/vite/server.js +2 -1
  223. package/src/engine/api.ts +11 -1
  224. package/src/engine/codegen/register_types.ts +10 -18
  225. package/src/engine/debug/debug_spatial_console.ts +10 -7
  226. package/src/engine/engine_addressables.ts +6 -3
  227. package/src/engine/engine_audio.ts +184 -0
  228. package/src/engine/engine_camera.fit.ts +15 -4
  229. package/src/engine/engine_components.ts +1 -1
  230. package/src/engine/engine_context.ts +63 -39
  231. package/src/engine/engine_context_eventbus.ts +73 -0
  232. package/src/engine/engine_disposable.ts +214 -0
  233. package/src/engine/engine_gameobject.ts +54 -159
  234. package/src/engine/engine_gltf_builtin_components.ts +7 -76
  235. package/src/engine/engine_init.ts +14 -4
  236. package/src/engine/engine_input.ts +28 -7
  237. package/src/engine/engine_instantiate_resolve.ts +407 -0
  238. package/src/engine/engine_license.ts +202 -56
  239. package/src/engine/engine_mainloop_utils.ts +7 -4
  240. package/src/engine/engine_networking.transport.websocket.ts +45 -0
  241. package/src/engine/engine_networking.ts +161 -137
  242. package/src/engine/engine_networking_blob.ts +4 -4
  243. package/src/engine/engine_networking_instantiate.ts +2 -2
  244. package/src/engine/engine_networking_types.ts +41 -1
  245. package/src/engine/engine_physics_rapier.ts +102 -33
  246. package/src/engine/engine_scenedata.ts +16 -13
  247. package/src/engine/engine_serialization_builtin_serializer.ts +64 -52
  248. package/src/engine/engine_serialization_core.ts +9 -0
  249. package/src/engine/engine_types.ts +46 -27
  250. package/src/engine/engine_util_decorator.ts +7 -2
  251. package/src/engine/engine_utils.ts +16 -5
  252. package/src/engine/engine_utils_qrcode.ts +2 -2
  253. package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
  254. package/src/engine/webcomponents/jsx.d.ts +9 -2
  255. package/src/engine/webcomponents/needle menu/needle-menu-spatial.ts +2 -2
  256. package/src/engine/webcomponents/needle menu/needle-menu.ts +6 -6
  257. package/src/engine/webcomponents/needle-engine.loading.ts +6 -6
  258. package/src/engine/webcomponents/needle-engine.ts +12 -6
  259. package/src/engine/xr/NeedleXRSession.ts +48 -13
  260. package/src/engine/xr/TempXRContext.ts +2 -2
  261. package/src/engine/xr/events.ts +1 -1
  262. package/src/engine-components/Animation.ts +19 -16
  263. package/src/engine-components/AnimationBuilder.ts +472 -0
  264. package/src/engine-components/Animator.ts +24 -12
  265. package/src/engine-components/AnimatorController.builder.ts +387 -0
  266. package/src/engine-components/AnimatorController.ts +24 -292
  267. package/src/engine-components/AudioSource.ts +130 -79
  268. package/src/engine-components/Collider.ts +66 -18
  269. package/src/engine-components/Component.ts +118 -20
  270. package/src/engine-components/ContactShadows.ts +15 -1
  271. package/src/engine-components/DragControls.ts +18 -11
  272. package/src/engine-components/DropListener.ts +3 -0
  273. package/src/engine-components/EventList.ts +45 -83
  274. package/src/engine-components/Joints.ts +20 -4
  275. package/src/engine-components/Light.ts +13 -4
  276. package/src/engine-components/Networking.ts +1 -1
  277. package/src/engine-components/OrbitControls.ts +34 -14
  278. package/src/engine-components/ReflectionProbe.ts +2 -0
  279. package/src/engine-components/RigidBody.ts +18 -4
  280. package/src/engine-components/SceneSwitcher.ts +3 -0
  281. package/src/engine-components/SeeThrough.ts +2 -2
  282. package/src/engine-components/api.ts +2 -1
  283. package/src/engine-components/codegen/components.ts +7 -13
  284. package/src/engine-components/export/usdz/USDZExporter.ts +4 -4
  285. package/src/engine-components/postprocessing/VolumeParameter.ts +4 -1
  286. package/src/engine-components/timeline/PlayableDirector.ts +83 -81
  287. package/src/engine-components/timeline/SignalAsset.ts +4 -1
  288. package/src/engine-components/timeline/TimelineBuilder.ts +824 -0
  289. package/src/engine-components/timeline/TimelineModels.ts +5 -1
  290. package/src/engine-components/timeline/TimelineTracks.ts +96 -27
  291. package/src/engine-components/timeline/index.ts +2 -1
  292. package/src/engine-components/ui/Canvas.ts +2 -8
  293. package/src/engine-components/ui/Text.ts +12 -8
  294. package/src/engine-components/web/CursorFollow.ts +21 -14
  295. package/src/engine-components/webxr/WebXRImageTracking.ts +79 -7
  296. package/dist/needle-engine.bundle--q_w7iXI.umd.cjs +0 -1732
  297. package/dist/needle-engine.bundle-w22UkaT_.min.js +0 -1732
  298. package/lib/engine-components/AvatarLoader.d.ts +0 -80
  299. package/lib/engine-components/AvatarLoader.js +0 -232
  300. package/lib/engine-components/AvatarLoader.js.map +0 -1
  301. package/lib/engine-components/avatar/AvatarBlink_Simple.d.ts +0 -11
  302. package/lib/engine-components/avatar/AvatarBlink_Simple.js +0 -77
  303. package/lib/engine-components/avatar/AvatarBlink_Simple.js.map +0 -1
  304. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.d.ts +0 -14
  305. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js +0 -69
  306. package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js.map +0 -1
  307. package/lib/engine-components/avatar/Avatar_Brain_LookAt.d.ts +0 -29
  308. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js +0 -122
  309. package/lib/engine-components/avatar/Avatar_Brain_LookAt.js.map +0 -1
  310. package/lib/engine-components/avatar/Avatar_MouthShapes.d.ts +0 -15
  311. package/lib/engine-components/avatar/Avatar_MouthShapes.js +0 -80
  312. package/lib/engine-components/avatar/Avatar_MouthShapes.js.map +0 -1
  313. package/lib/engine-components/avatar/Avatar_MustacheShake.d.ts +0 -9
  314. package/lib/engine-components/avatar/Avatar_MustacheShake.js +0 -30
  315. package/lib/engine-components/avatar/Avatar_MustacheShake.js.map +0 -1
  316. package/src/engine-components/AvatarLoader.ts +0 -264
  317. package/src/engine-components/avatar/AvatarBlink_Simple.ts +0 -70
  318. package/src/engine-components/avatar/AvatarEyeLook_Rotation.ts +0 -64
  319. package/src/engine-components/avatar/Avatar_Brain_LookAt.ts +0 -140
  320. package/src/engine-components/avatar/Avatar_MouthShapes.ts +0 -84
  321. package/src/engine-components/avatar/Avatar_MustacheShake.ts +0 -32
  322. package/src/vite-env.d.ts +0 -16
@@ -40,11 +40,13 @@ import { GLTFLoader } from '../../../node_modules/@types/three/examples/jsm/load
40
40
  import { GLTFLoaderPlugin } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
41
41
  import { GLTFParser } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
42
42
  import { Group } from 'three';
43
+ import { ImpulseJoint } from '@dimforge/rapier3d-compat';
43
44
  import { InstancedMesh } from 'three';
44
45
  import { Intersection } from 'three';
45
46
  import { IParticleSystem as IParticleSystem_2 } from 'three.quarks';
46
47
  import { KeyframeTrack } from 'three';
47
48
  import { Layers } from 'three';
49
+ import { Light as Light_2 } from 'three';
48
50
  import { LightProbe } from 'three';
49
51
  import { Line2 } from '../../../../node_modules/@types/three/examples/jsm/lines/Line2.js';
50
52
  import { Loader } from 'three';
@@ -115,6 +117,8 @@ import { XRHandSpace } from 'three';
115
117
 
116
118
  export declare const $componentName: unique symbol;
117
119
 
120
+ /* Excluded from this release type: _$LVgA */
121
+
118
122
  export declare const $physicsKey: unique symbol;
119
123
 
120
124
  export declare class __Ignore {
@@ -254,6 +258,31 @@ export declare class ActionModel implements IBehaviorElement {
254
258
  writeTo(document: USDDocument, writer: USDWriter): void;
255
259
  }
256
260
 
261
+ /**
262
+ * Options for an activation clip in the timeline builder
263
+ */
264
+ export declare type ActivationClipOptions = {
265
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
266
+ start?: number;
267
+ /** Duration of the clip in seconds (required) */
268
+ duration: number;
269
+ /** Ease-in duration in seconds (default: 0) */
270
+ easeIn?: number;
271
+ /** Ease-out duration in seconds (default: 0) */
272
+ easeOut?: number;
273
+ };
274
+
275
+ /**
276
+ * Builder for activation tracks. Provides `.clip()` for defining activation windows.
277
+ * @category Animation and Sequencing
278
+ */
279
+ export declare interface ActivationTrackBuilder extends TimelineBuilderBase {
280
+ /** Adds an activation clip that shows/hides the bound object */
281
+ clip(options: ActivationClipOptions): ActivationTrackBuilder;
282
+ /** Mutes this track so it is skipped during playback */
283
+ muted(muted?: boolean): ActivationTrackBuilder;
284
+ }
285
+
257
286
  export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";
258
287
 
259
288
  /**
@@ -487,6 +516,62 @@ declare class Animation_2 extends Component implements IAnimationComponent {
487
516
  }
488
517
  export { Animation_2 as Animation }
489
518
 
519
+ /**
520
+ * A fluent builder for creating `AnimationClip` instances from code.
521
+ *
522
+ * Use {@link AnimationBuilder.create} to start a new builder, chain `.track()` calls
523
+ * to add animation tracks, and call `.build()` to produce the clip.
524
+ *
525
+ * @example Single track
526
+ * ```ts
527
+ * const clip = AnimationBuilder.create()
528
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
529
+ * .build();
530
+ * ```
531
+ *
532
+ * @example Multiple tracks
533
+ * ```ts
534
+ * const clip = AnimationBuilder.create("DoorOpen")
535
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
536
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
537
+ * .build(room);
538
+ * ```
539
+ *
540
+ * @category Animation and Sequencing
541
+ * @group Utilities
542
+ */
543
+ export declare class AnimationBuilder {
544
+ private _name?;
545
+ private _tracks;
546
+ /** Creates a new AnimationBuilder instance */
547
+ static create(name?: string): AnimationBuilder;
548
+ constructor(name?: string);
549
+ /** Adds an animation track for an Object3D's position or scale */
550
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_2<Vec3Value>, options?: TrackOptions): this;
551
+ /** Adds an animation track for an Object3D's quaternion */
552
+ track(target: Object3D, property: "quaternion", keyframes: KF_2<QuatValue>, options?: TrackOptions): this;
553
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
554
+ track(target: Object3D, property: "rotation", keyframes: KF_2<EulerValue>, options?: TrackOptions): this;
555
+ /** Adds an animation track for an Object3D's visibility */
556
+ track(target: Object3D, property: "visible", keyframes: KF_2<boolean>, options?: TrackOptions): this;
557
+ /** Adds an animation track for a material's numeric property */
558
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_2<number>, options?: TrackOptions): this;
559
+ /** Adds an animation track for a material's color property */
560
+ track(target: Material, property: "color" | "emissive", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
561
+ /** Adds an animation track for a light's numeric property */
562
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_2<number>, options?: TrackOptions): this;
563
+ /** Adds an animation track for a light's color */
564
+ track(target: Light_2, property: "color", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
565
+ /** Adds an animation track for a camera's numeric property */
566
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_2<number>, options?: TrackOptions): this;
567
+ /**
568
+ * Builds and returns the `AnimationClip`.
569
+ * @param root - Optional root Object3D for resolving track paths.
570
+ * When provided, tracks targeting a different object use `target.name` for named resolution.
571
+ */
572
+ build(root?: Object3D): AnimationClip;
573
+ }
574
+
490
575
  /**
491
576
  * @category Animation and Sequencing
492
577
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -500,6 +585,34 @@ export declare type AnimationClipModel = {
500
585
  rotation?: Quat | Quaternion;
501
586
  };
502
587
 
588
+ /**
589
+ * Options for an animation clip in the timeline builder
590
+ */
591
+ export declare type AnimationClipOptions = {
592
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
593
+ start?: number;
594
+ /** Duration of the clip in seconds. Defaults to the animation clip duration. */
595
+ duration?: number;
596
+ /** Playback speed multiplier (default: 1) */
597
+ speed?: number;
598
+ /** Whether the animation should loop within the clip (default: false) */
599
+ loop?: boolean;
600
+ /** Ease-in duration in seconds (default: 0) */
601
+ easeIn?: number;
602
+ /** Ease-out duration in seconds (default: 0) */
603
+ easeOut?: number;
604
+ /** Offset into the source animation clip in seconds (default: 0) */
605
+ clipIn?: number;
606
+ /** Whether to remove the start offset of the animation (default: false) */
607
+ removeStartOffset?: boolean;
608
+ /** Pre-extrapolation mode (default: None) */
609
+ preExtrapolation?: ClipExtrapolation;
610
+ /** Post-extrapolation mode (default: None) */
611
+ postExtrapolation?: ClipExtrapolation;
612
+ /** Play the clip in reverse */
613
+ reversed?: boolean;
614
+ };
615
+
503
616
  /**
504
617
  * AnimationCurve is a representation of a curve that can be used to animate values over time.
505
618
  *
@@ -577,6 +690,19 @@ export declare class AnimationExtension implements IUSDExporterExtension {
577
690
 
578
691
  declare type AnimationIdentifier = AnimationClip | number | string | undefined;
579
692
 
693
+ /** User-friendly interpolation mode names */
694
+ export declare type AnimationInterpolation = "linear" | "smooth" | "step";
695
+
696
+ /** A single keyframe: a time and a value */
697
+ export declare type AnimationKeyframe<V> = {
698
+ /** Time in seconds */
699
+ time: number;
700
+ /** The value at this time */
701
+ value: V;
702
+ /** Interpolation mode for this track (default: `"linear"`). Note: Three.js applies one mode per track; the first keyframe's mode is used. */
703
+ interpolation?: AnimationInterpolation;
704
+ };
705
+
580
706
  /**
581
707
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.
582
708
  * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
@@ -597,43 +723,39 @@ declare class AnimationsRegistry {
597
723
  unregisterAnimationMixer(mixer: AnimationMixer | null | undefined): void;
598
724
  }
599
725
 
600
- export declare class AnimationTrackHandler extends TrackHandler {
601
- /* Excluded from this release type: models */
602
- /* Excluded from this release type: trackOffset */
603
- /** The object that is being animated. */
604
- target?: Object3D;
605
- /** The AnimationMixer, should be shared with the animator if an animator is bound */
606
- mixer?: AnimationMixer;
607
- clips: Array<AnimationClip>;
608
- actions: Array<AnimationAction>;
609
- /**
610
- * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
611
- * @default 1
612
- */
613
- weight: number;
614
- /** holds data/info about clips differences */
615
- private _actionOffsets;
616
- private _didBind;
617
- private _animator;
618
- onDisable(): void;
619
- onDestroy(): void;
620
- onStateChanged(): void;
621
- createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
622
- bind(): void;
623
- private ensureTrackOffsets;
624
- private _useclipOffsets;
625
- private _totalOffsetPosition;
626
- private _totalOffsetRotation;
627
- private _totalOffsetPosition2;
628
- private _totalOffsetRotation2;
629
- private _summedPos;
630
- private _tempPos;
631
- private _summedRot;
632
- private _tempRot;
633
- private _clipRotQuat;
634
- evaluate(time: number): void;
635
- private createRotationInterpolant;
636
- private createPositionInterpolant;
726
+ /**
727
+ * Builder for animation tracks.
728
+ * Provides `.clip()` for pre-built AnimationClips and `.track()` for inline animation definition.
729
+ *
730
+ * @category Animation and Sequencing
731
+ */
732
+ export declare interface AnimationTrackBuilder extends TimelineBuilderBase {
733
+ /** Adds a pre-built AnimationClip */
734
+ clip(asset: AnimationClip, options?: AnimationClipOptions): AnimationTrackBuilder;
735
+ /** Adds a clip from a single {@link TrackDescriptor} */
736
+ clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): AnimationTrackBuilder;
737
+ /** Adds a clip from multiple {@link TrackDescriptor}s */
738
+ clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): AnimationTrackBuilder;
739
+ /** Adds an animation track for an Object3D's position or scale */
740
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): AnimationTrackBuilder;
741
+ /** Adds an animation track for an Object3D's quaternion */
742
+ track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): AnimationTrackBuilder;
743
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
744
+ track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): AnimationTrackBuilder;
745
+ /** Adds an animation track for an Object3D's visibility */
746
+ track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): AnimationTrackBuilder;
747
+ /** Adds an animation track for a material's numeric property */
748
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
749
+ /** Adds an animation track for a material's color property */
750
+ track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
751
+ /** Adds an animation track for a light's numeric property */
752
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
753
+ /** Adds an animation track for a light's color */
754
+ track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
755
+ /** Adds an animation track for a camera's numeric property */
756
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
757
+ /** Mutes this track so it is skipped during playback */
758
+ muted(muted?: boolean): AnimationTrackBuilder;
637
759
  }
638
760
 
639
761
  declare class AnimationTriggers {
@@ -726,6 +848,12 @@ export declare class Animator extends Component implements IAnimationComponent {
726
848
  * Identifies this component as an animation component in the engine
727
849
  */
728
850
  get isAnimationComponent(): boolean;
851
+ /**
852
+ * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
853
+ * @returns The current AnimationMixer, or null if no controller is assigned
854
+ * @see AnimatorController.mixer
855
+ */
856
+ get mixer(): AnimationMixer | null;
729
857
  /**
730
858
  * When enabled, animation will affect the root transform position and rotation
731
859
  */
@@ -1102,13 +1230,6 @@ export declare class AnimatorController {
1102
1230
  * @param animator - The animator to bind this controller to
1103
1231
  */
1104
1232
  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
1233
  /**
1113
1234
  * Updates the controller's state machine and animations.
1114
1235
  * Called each frame by the animator component.
@@ -1151,11 +1272,15 @@ export declare class AnimatorController {
1151
1272
  /**
1152
1273
  * A fluent builder for creating {@link AnimatorController} instances from code.
1153
1274
  *
1154
- * Use {@link AnimatorController.build} to create a new builder.
1275
+ * Use {@link AnimatorControllerBuilder.create} or {@link AnimatorController.build} to create a new builder.
1155
1276
  *
1156
- * @example
1277
+ * The builder tracks state names and parameter types through the fluent chain,
1278
+ * providing autocomplete for state names in `.transition()` and type-aware
1279
+ * `.condition()` calls (e.g., trigger parameters don't require a mode argument).
1280
+ *
1281
+ * @example With pre-built AnimationClips
1157
1282
  * ```ts
1158
- * const controller = AnimatorController.build("CharacterController")
1283
+ * const controller = AnimatorControllerBuilder.create("CharacterController")
1159
1284
  * .floatParameter("Speed", 0)
1160
1285
  * .triggerParameter("Jump")
1161
1286
  * .state("Idle", { clip: idleClip, loop: true })
@@ -1166,36 +1291,70 @@ export declare class AnimatorController {
1166
1291
  * .transition("Walk", "Idle", { duration: 0.25 })
1167
1292
  * .condition("Speed", "less", 0.1)
1168
1293
  * .transition("*", "Jump", { duration: 0.1 })
1169
- * .condition("Jump", "if")
1294
+ * .condition("Jump")
1170
1295
  * .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
1171
1296
  * .build();
1172
1297
  * ```
1173
1298
  *
1299
+ * @example With inline tracks (no pre-built clips needed)
1300
+ * ```ts
1301
+ * const controller = AnimatorControllerBuilder.create("Door")
1302
+ * .boolParameter("Open", false)
1303
+ * .state("Closed", { loop: true })
1304
+ * .track(door, "position", { from: [0, 0, 0], to: [0, 0, 0], duration: 1 })
1305
+ * .state("Open", { loop: true })
1306
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
1307
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
1308
+ * .transition("Closed", "Open", { duration: 0.25 })
1309
+ * .condition("Open", "if")
1310
+ * .transition("Open", "Closed", { duration: 0.25 })
1311
+ * .condition("Open", "ifNot")
1312
+ * .build(room);
1313
+ * ```
1314
+ *
1315
+ * @typeParam TStates - Union of state names added via `.state()`. Used for autocomplete and validation in `.transition()` and `.defaultState()`.
1316
+ * @typeParam TParams - Record mapping parameter names to their types (`"trigger"`, `"bool"`, `"float"`, `"int"`). Used for type-aware `.condition()` overloads.
1317
+ *
1174
1318
  * @category Animation and Sequencing
1175
1319
  * @group Utilities
1176
1320
  */
1177
- export declare class AnimatorControllerBuilder {
1321
+ export declare class AnimatorControllerBuilder<TStates extends string = never, TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {}> {
1178
1322
  private _name;
1179
1323
  private _parameters;
1180
1324
  private _states;
1181
1325
  private _anyStateTransitions;
1182
1326
  private _defaultStateName;
1183
1327
  private _lastTransition;
1328
+ private _lastState;
1329
+ /**
1330
+ * Creates a new AnimatorControllerBuilder instance.
1331
+ * @param name - Optional name for the controller
1332
+ */
1333
+ static create(name?: string): AnimatorControllerBuilder;
1184
1334
  constructor(name?: string);
1185
1335
  /** Adds a float parameter */
1186
- floatParameter(name: string, defaultValue?: number): this;
1336
+ floatParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>;
1187
1337
  /** Adds an integer parameter */
1188
- intParameter(name: string, defaultValue?: number): this;
1338
+ intParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>;
1189
1339
  /** Adds a boolean parameter */
1190
- boolParameter(name: string, defaultValue?: boolean): this;
1340
+ boolParameter<N extends string>(name: N, defaultValue?: boolean): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>;
1191
1341
  /** Adds a trigger parameter */
1192
- triggerParameter(name: string): this;
1342
+ triggerParameter<N extends string>(name: N): AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>;
1193
1343
  /**
1194
1344
  * Adds a state to the controller. The first state added becomes the default state.
1345
+ *
1346
+ * When `options.clip` is provided, the state uses that clip directly.
1347
+ * When omitted, chain `.track()` calls to define animation tracks inline:
1348
+ * ```ts
1349
+ * .state("Open", { loop: true })
1350
+ * .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
1351
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
1352
+ * ```
1353
+ *
1195
1354
  * @param name - Unique name for the state
1196
- * @param options - State configuration including clip, loop, speed
1355
+ * @param options - State configuration including clip, loop, speed. When omitted, use `.track()` to add animation data.
1197
1356
  */
1198
- state(name: string, options: StateOptions): this;
1357
+ state<N extends string>(name: N, options?: StateOptions): AnimatorControllerBuilder<TStates | N, TParams>;
1199
1358
  /**
1200
1359
  * Adds a transition between two states.
1201
1360
  * Use `"*"` as the source to create a transition from any state.
@@ -1204,26 +1363,52 @@ export declare class AnimatorControllerBuilder {
1204
1363
  * @param to - Destination state name
1205
1364
  * @param options - Transition configuration
1206
1365
  */
1207
- transition(from: string, to: string, options?: TransitionOptions): this;
1366
+ transition(from: TStates | "*", to: TStates, options?: TransitionOptions): AnimatorControllerBuilder<TStates, TParams>;
1208
1367
  /**
1209
1368
  * Adds a condition to the most recently added transition.
1210
1369
  * Multiple conditions on the same transition are AND-ed together.
1370
+ *
1371
+ * The required arguments depend on the parameter type:
1372
+ * - **Trigger**: `.condition("Jump")` — mode defaults to `"if"`, no threshold needed
1373
+ * - **Bool**: `.condition("Open", "if")` or `.condition("Open", "ifNot")`
1374
+ * - **Float/Int**: `.condition("Speed", "greater", 0.1)`
1375
+ *
1211
1376
  * @param parameter - Name of the parameter to evaluate
1212
- * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
1213
- * @param threshold - Comparison threshold for numeric conditions (default: 0)
1214
1377
  */
1215
- condition(parameter: string, mode: ConditionMode, threshold?: number): this;
1378
+ condition(parameter: ParamNamesOfType<TParams, "trigger">, mode?: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
1379
+ condition(parameter: ParamNamesOfType<TParams, "bool">, mode: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
1380
+ condition(parameter: ParamNamesOfType<TParams, "float" | "int">, mode: "greater" | "less" | "equals" | "notEqual", threshold?: number): AnimatorControllerBuilder<TStates, TParams>;
1381
+ /** Adds an animation track for an Object3D's position or scale to the current state */
1382
+ track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): this;
1383
+ /** Adds an animation track for an Object3D's quaternion to the current state */
1384
+ track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): this;
1385
+ /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) to the current state */
1386
+ track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): this;
1387
+ /** Adds an animation track for an Object3D's visibility to the current state */
1388
+ track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): this;
1389
+ /** Adds an animation track for a material's numeric property to the current state */
1390
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): this;
1391
+ /** Adds an animation track for a material's color property to the current state */
1392
+ track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): this;
1393
+ /** Adds an animation track for a light's numeric property to the current state */
1394
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): this;
1395
+ /** Adds an animation track for a light's color to the current state */
1396
+ track(target: Light_2, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): this;
1397
+ /** Adds an animation track for a camera's numeric property to the current state */
1398
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): this;
1216
1399
  /**
1217
1400
  * Sets which state is the default/entry state.
1218
1401
  * If not called, the first added state is used.
1219
1402
  * @param name - Name of the state
1220
1403
  */
1221
- defaultState(name: string): this;
1404
+ defaultState(name: TStates): AnimatorControllerBuilder<TStates, TParams>;
1222
1405
  /**
1223
1406
  * Builds and returns the {@link AnimatorController}.
1224
1407
  * Resolves all state name references to indices.
1408
+ * @param root - Optional root Object3D for resolving {@link TrackDescriptor} track paths.
1409
+ * When provided, tracks targeting a different object use `target.name` for named resolution.
1225
1410
  */
1226
- build(): AnimatorController;
1411
+ build(root?: Object3D): AnimatorController;
1227
1412
  }
1228
1413
 
1229
1414
  export declare type AnimatorControllerModel = {
@@ -1472,6 +1657,75 @@ export declare class Attractor extends Component {
1472
1657
 
1473
1658
  declare type AttributeChangeCallback = (value: string | null) => void;
1474
1659
 
1660
+ /**
1661
+ * Represents an audio clip that can be loaded and played independently.
1662
+ * The AudioClip class encapsulates the URL of the audio resource and provides
1663
+ * methods for playback control (play, pause, stop) and querying duration.
1664
+ */
1665
+ export declare class AudioClip {
1666
+ readonly url: string;
1667
+ /**
1668
+ * Creates a new AudioClip instance with the specified URL.
1669
+ * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
1670
+ */
1671
+ constructor(url: string);
1672
+ /** Whether the clip is currently playing.
1673
+ * @returns `true` if the clip is actively playing audio.
1674
+ */
1675
+ get isPlaying(): boolean;
1676
+ /**
1677
+ * The total duration of the audio clip in seconds.
1678
+ * Loads the audio metadata if not already available.
1679
+ * @returns A promise that resolves with the duration in seconds.
1680
+ */
1681
+ getDuration(): Promise<number>;
1682
+ /**
1683
+ * Plays the audio clip from the current position.
1684
+ * @returns A promise that resolves when playback finishes, or rejects on error.
1685
+ * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
1686
+ */
1687
+ play(): Promise<void>;
1688
+ /**
1689
+ * Pauses playback at the current position.
1690
+ * Call {@link play} to resume.
1691
+ */
1692
+ pause(): void;
1693
+ /**
1694
+ * Stops playback and resets the position to the beginning.
1695
+ */
1696
+ stop(): void;
1697
+ /** Whether the clip should loop when reaching the end. */
1698
+ get loop(): boolean;
1699
+ set loop(value: boolean);
1700
+ /** Playback volume from 0 (silent) to 1 (full). */
1701
+ get volume(): number;
1702
+ set volume(value: number);
1703
+ /** Current playback position in seconds. */
1704
+ get currentTime(): number;
1705
+ set currentTime(value: number);
1706
+ /** Normalized playback progress from 0 to 1.
1707
+ * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
1708
+ */
1709
+ get progress(): number;
1710
+ /**
1711
+ * Seeks to a normalized position (0–1) in the clip.
1712
+ * @param position A value between 0 (start) and 1 (end).
1713
+ */
1714
+ seek(position: number): void;
1715
+ /** The underlying HTMLAudioElement, or `undefined` if not yet created.
1716
+ * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
1717
+ * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
1718
+ */
1719
+ get audioElement(): HTMLAudioElement | undefined;
1720
+ private _audioElement?;
1721
+ private _duration?;
1722
+ private _loadPromise?;
1723
+ private _loop;
1724
+ private _volume;
1725
+ /** Lazily creates and loads the shared HTMLAudioElement. */
1726
+ private ensureAudioElement;
1727
+ }
1728
+
1475
1729
  /**
1476
1730
  * @category Animation and Sequencing
1477
1731
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -1486,6 +1740,26 @@ declare type AudioClipModel_2 = Models.ClipModel & {
1486
1740
  _didTriggerPlay: boolean;
1487
1741
  };
1488
1742
 
1743
+ /**
1744
+ * Options for an audio clip in the timeline builder
1745
+ */
1746
+ export declare type AudioClipOptions = {
1747
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
1748
+ start?: number;
1749
+ /** Duration of the clip in seconds (required for audio since we can't infer it) */
1750
+ duration: number;
1751
+ /** Playback speed multiplier (default: 1) */
1752
+ speed?: number;
1753
+ /** Volume multiplier for this clip (default: 1) */
1754
+ volume?: number;
1755
+ /** Whether the audio should loop within the clip (default: false) */
1756
+ loop?: boolean;
1757
+ /** Ease-in duration in seconds (default: 0) */
1758
+ easeIn?: number;
1759
+ /** Ease-out duration in seconds (default: 0) */
1760
+ easeOut?: number;
1761
+ };
1762
+
1489
1763
  export declare class AudioExtension implements IUSDExporterExtension {
1490
1764
  static getName(clip: string): string;
1491
1765
  get extensionName(): string;
@@ -1627,9 +1901,10 @@ export declare class AudioSource extends Component {
1627
1901
  */
1628
1902
  get isPlaying(): boolean;
1629
1903
  /**
1630
- * The total duration of the current audio clip in seconds.
1904
+ * The total duration of the currently loaded audio clip in seconds.
1631
1905
  *
1632
1906
  * @returns Duration in seconds or undefined if no clip is loaded
1907
+ * @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
1908
  */
1634
1909
  get duration(): number | undefined;
1635
1910
  /**
@@ -1654,7 +1929,8 @@ export declare class AudioSource extends Component {
1654
1929
  /**
1655
1930
  * Controls how the audio is positioned in space.
1656
1931
  * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
1657
- * Note: 2D playback is not fully supported in the current implementation.
1932
+ * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
1933
+ * and a non-spatialized (direct) signal path.
1658
1934
  */
1659
1935
  get spatialBlend(): number;
1660
1936
  set spatialBlend(val: number);
@@ -1702,7 +1978,11 @@ export declare class AudioSource extends Component {
1702
1978
  private audioLoader;
1703
1979
  private shouldPlay;
1704
1980
  private _lastClipStartedLoading;
1981
+ private _loadedClip;
1705
1982
  private _audioElement;
1983
+ private _entryNode;
1984
+ private _spatialGain;
1985
+ private _bypassGain;
1706
1986
  /**
1707
1987
  * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
1708
1988
  * The audio source needs a user interaction to be initialized due to browser autoplay policies.
@@ -1730,6 +2010,15 @@ export declare class AudioSource extends Component {
1730
2010
  private onApplicationMuteChanged;
1731
2011
  private createAudio;
1732
2012
  private __onAllowAudioCallback;
2013
+ /**
2014
+ * Sets up the dual-path audio graph for spatial blend crossfading.
2015
+ * Creates two parallel signal paths from source to output:
2016
+ * - 3D path: entry → panner → spatialGain → gain (spatialized)
2017
+ * - 2D path: entry → bypassGain → gain (non-spatialized)
2018
+ */
2019
+ private setupSpatialBlendNodes;
2020
+ /** Updates the spatial/bypass gain values based on the current spatialBlend. */
2021
+ private updateSpatialBlendGains;
1733
2022
  private applySpatialDistanceSettings;
1734
2023
  private onNewClip;
1735
2024
  /**
@@ -1737,8 +2026,9 @@ export declare class AudioSource extends Component {
1737
2026
  * If no argument is provided, plays the currently assigned clip.
1738
2027
  *
1739
2028
  * @param clip - Optional audio clip or {@link MediaStream} to play
2029
+ * @returns A promise that resolves when playback starts successfully, or rejects on error
1740
2030
  */
1741
- play(clip?: string | MediaStream | undefined): void;
2031
+ play(clip?: string | MediaStream | undefined): Promise<boolean>;
1742
2032
  /**
1743
2033
  * Pauses audio playback while maintaining the current position.
1744
2034
  * Use play() to resume from the paused position.
@@ -1755,30 +2045,15 @@ export declare class AudioSource extends Component {
1755
2045
  /* Excluded from this release type: update */
1756
2046
  }
1757
2047
 
1758
- export declare class AudioTrackHandler extends TrackHandler {
1759
- models: Array<AudioClipModel_2>;
1760
- listener: AudioListener_3;
1761
- audio: Array<Audio_2>;
1762
- audioContextTimeOffset: Array<number>;
1763
- lastTime: number;
1764
- audioSource?: AudioSource;
1765
- private _audioLoader;
1766
- private getAudioFilePath;
1767
- onAllowAudioChanged(allow: boolean): void;
1768
- addModel(model: Models.ClipModel): void;
1769
- onDisable(): void;
1770
- onDestroy(): void;
1771
- onMuteChanged(): void;
1772
- stop(): void;
1773
- private _playableDirectorResumed;
1774
- onPauseChanged(): void;
1775
- evaluate(time: number): void;
1776
- /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
1777
- loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
1778
- private isInTimeRange;
1779
- private static _audioBuffers;
1780
- static dispose(): void;
1781
- private handleAudioLoading;
2048
+ /**
2049
+ * Builder for audio tracks. Provides `.clip()` for adding audio clips by URL.
2050
+ * @category Animation and Sequencing
2051
+ */
2052
+ export declare interface AudioTrackBuilder extends TimelineBuilderBase {
2053
+ /** Adds an audio clip by URL */
2054
+ clip(url: string, options: AudioClipOptions): AudioTrackBuilder;
2055
+ /** Mutes this track so it is skipped during playback */
2056
+ muted(muted?: boolean): AudioTrackBuilder;
1782
2057
  }
1783
2058
 
1784
2059
  /* Excluded from this release type: AuralMode */
@@ -1811,69 +2086,6 @@ export declare class Avatar extends Component {
1811
2086
  private loadAvatarObjects;
1812
2087
  }
1813
2088
 
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
2089
  /**
1878
2090
  * Marks a GameObject as being controlled or owned by a player in networked XR sessions.
1879
2091
  * This is used internally by the networking system to identify player-controlled objects.
@@ -1934,35 +2146,6 @@ declare type AvatarMarkerEventArgs = {
1934
2146
  gameObject: Object3D;
1935
2147
  };
1936
2148
 
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
2149
  export declare enum Axes {
1967
2150
  None = 0,
1968
2151
  X = 2,
@@ -2326,7 +2509,6 @@ export declare class BoxCollider extends Collider implements IBoxCollider {
2326
2509
  center: Vector3;
2327
2510
  /* Excluded from this release type: onEnable */
2328
2511
  /* Excluded from this release type: onDisable */
2329
- /* Excluded from this release type: onValidate */
2330
2512
  /**
2331
2513
  * Automatically fits the collider to the geometry of the object.
2332
2514
  * Sets the size and center based on the object's bounding box.
@@ -2600,6 +2782,7 @@ declare class CallHandle extends EventDispatcher<any> {
2600
2782
  * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
2601
2783
  */
2602
2784
  export declare class CallInfo {
2785
+ $serializedTypes: Record<string, any>;
2603
2786
  /**
2604
2787
  * When the CallInfo is enabled it will be invoked when the EventList is invoked
2605
2788
  */
@@ -2946,7 +3129,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
2946
3129
  private _receivers;
2947
3130
  registerEventReceiver(receiver: ICanvasEventReceiver): void;
2948
3131
  unregisterEventReceiver(receiver: ICanvasEventReceiver): void;
2949
- onEnterXR(args: NeedleXREventArgs): Promise<void>;
3132
+ onEnterXR(args: NeedleXREventArgs): void;
2950
3133
  onLeaveXR(args: NeedleXREventArgs): void;
2951
3134
  onBeforeRenderRoutine: () => void;
2952
3135
  onAfterRenderRoutine: () => void;
@@ -3522,6 +3705,22 @@ export declare abstract class Collider extends Component implements ICollider {
3522
3705
  * The layers that this collider will interact with. Used for filtering collision detection.
3523
3706
  */
3524
3707
  filter?: number[];
3708
+ /**
3709
+ * The density of the collider, used for automatic mass calculation when the attached {@link Rigidbody} has `autoMass` enabled.
3710
+ * Rapier computes mass from density using the real-world formula: `mass = density × volume`.
3711
+ * The volume is derived from the collider shape (sphere, box, capsule, or convex hull).
3712
+ *
3713
+ * Reference values (relative to water = 1.0):
3714
+ * - Wood: 0.5–0.9
3715
+ * - Water: 1.0 (engine default)
3716
+ * - Rubber: 1.2
3717
+ * - Steel: 7.8
3718
+ *
3719
+ * @default undefined — uses the physics engine default of 1.0
3720
+ */
3721
+ density?: number;
3722
+ /* Excluded from this release type: _propertiesDirty */
3723
+ /* Excluded from this release type: onValidate */
3525
3724
  /* Excluded from this release type: awake */
3526
3725
  /* Excluded from this release type: start */
3527
3726
  /* Excluded from this release type: onEnable */
@@ -3623,7 +3822,10 @@ declare class ColorSerializer extends TypeSerializer {
3623
3822
  onSerialize(data: any): any | void;
3624
3823
  }
3625
3824
 
3626
- export declare const colorSerializer: ColorSerializer;
3825
+ export declare let colorSerializer: ColorSerializer;
3826
+
3827
+ /** A Color value, either as a Three.js Color or as an `[r, g, b]` tuple (0–1) */
3828
+ declare type ColorValue = Color | [number, number, number];
3627
3829
 
3628
3830
  /**
3629
3831
  * Utility method to check if two materials were created from the same glTF material
@@ -3644,7 +3846,7 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
3644
3846
  * **Input event methods:**
3645
3847
  * {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
3646
3848
  *
3647
- * @example
3849
+ * @example Basic component
3648
3850
  * ```typescript
3649
3851
  * import { Behaviour } from "@needle-tools/engine";
3650
3852
  * export class MyComponent extends Behaviour {
@@ -3657,6 +3859,25 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
3657
3859
  * }
3658
3860
  * ```
3659
3861
  *
3862
+ * @example Automatic cleanup with autoCleanup
3863
+ * ```typescript
3864
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
3865
+ * export class ScoreTracker extends Behaviour {
3866
+ * @serializable(EventList)
3867
+ * onScoreChanged?: EventList<number>;
3868
+ *
3869
+ * start() {
3870
+ * // Registered during start → survives enable/disable, cleaned up on destroy
3871
+ * this.autoCleanup(this.onScoreChanged?.on(score => console.log("Score:", score)));
3872
+ * }
3873
+ *
3874
+ * onEnable() {
3875
+ * // Registered during onEnable → cleaned up on disable
3876
+ * this.autoCleanup(() => this.cleanupResources());
3877
+ * }
3878
+ * }
3879
+ * ```
3880
+ *
3660
3881
  * @group Components
3661
3882
  */
3662
3883
  declare abstract class Component implements IComponent, EventTarget, Partial<INeedleXRSessionEventReceiver>, Partial<IPointerEventHandler> {
@@ -3707,6 +3928,50 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3707
3928
  * @returns True if the component is enabled and all parent GameObjects are active
3708
3929
  */
3709
3930
  get activeAndEnabled(): boolean;
3931
+ private __disableCleanups?;
3932
+ private __destroyCleanups?;
3933
+ /**
3934
+ * @experimental
3935
+ * Register a resource for automatic cleanup tied to this component's lifecycle.
3936
+ * Accepts {@link IDisposable} objects, cleanup functions, or event unsubscribe functions.
3937
+ * `null` and `undefined` are safe no-ops (convenient for conditional subscriptions).
3938
+ *
3939
+ * **Lifecycle-aware:** The cleanup store is chosen automatically based on when `autoCleanup` is called:
3940
+ * - Called during {@link onEnable} → cleaned up on {@link onDisable} (and re-registered on re-enable)
3941
+ * - Called during {@link awake} or {@link start} → cleaned up on {@link onDestroy} (survives enable/disable cycles)
3942
+ * - Called at any other time (e.g. from update) → cleaned up on {@link onDisable}
3943
+ *
3944
+ * @param disposable An {@link IDisposable}, a cleanup/unsubscribe function, or `null`/`undefined`
3945
+ *
3946
+ * @example EventList subscriptions
3947
+ * ```ts
3948
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
3949
+ *
3950
+ * export class MyComponent extends Behaviour {
3951
+ * @serializable(EventList)
3952
+ * onScoreChanged?: EventList<number>;
3953
+ *
3954
+ * onEnable() {
3955
+ * this.autoCleanup(this.onScoreChanged?.on(score => {
3956
+ * console.log("Score:", score);
3957
+ * }));
3958
+ * }
3959
+ * }
3960
+ * ```
3961
+ *
3962
+ * @example Lifetime subscriptions in awake
3963
+ * ```ts
3964
+ * import { Behaviour } from "@needle-tools/engine";
3965
+ *
3966
+ * export class Persistent extends Behaviour {
3967
+ * awake() {
3968
+ * // Registered during awake → survives enable/disable, cleaned up on destroy
3969
+ * this.autoCleanup(() => this.save());
3970
+ * }
3971
+ * }
3972
+ * ```
3973
+ */
3974
+ protected autoCleanup(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
3710
3975
  private get __isActive();
3711
3976
  private get __isActiveInHierarchy();
3712
3977
  private set __isActiveInHierarchy(value);
@@ -3725,11 +3990,6 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3725
3990
  * For example, URL to the glTF file this component was loaded from
3726
3991
  */
3727
3992
  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
3993
  /**
3734
3994
  * Called once when the component becomes active for the first time.
3735
3995
  * This is the first lifecycle callback to be invoked
@@ -3942,6 +4202,10 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
3942
4202
  destroy(): void;
3943
4203
  /* Excluded from this release type: __didAwake */
3944
4204
  /* Excluded from this release type: __didStart */
4205
+ /** True while start() has finished executing (used by autoCleanup to distinguish start from update) */
4206
+ private __didCompleteStart;
4207
+ /** True while onEnable() is executing (used by autoCleanup to route to disable store) */
4208
+ private __inEnableOrDisableCallback;
3945
4209
  /* Excluded from this release type: __didEnable */
3946
4210
  /* Excluded from this release type: __isEnabled */
3947
4211
  /* Excluded from this release type: __destroyed */
@@ -4097,7 +4361,7 @@ declare class ComponentSerializer extends TypeSerializer {
4097
4361
  findObjectForGuid(guid: string, root: Object3D): any;
4098
4362
  }
4099
4363
 
4100
- export declare const componentSerializer: ComponentSerializer;
4364
+ export declare let componentSerializer: ComponentSerializer;
4101
4365
 
4102
4366
  declare type ComponentType = "button" | "thumbstick" | "squeeze" | "touchpad";
4103
4367
 
@@ -4231,6 +4495,7 @@ export declare class ContactShadows extends Component {
4231
4495
  set needsUpdate(val: boolean);
4232
4496
  get needsUpdate(): boolean;
4233
4497
  private _needsUpdate;
4498
+ private _needsFit;
4234
4499
  /** All shadow objects are parented to this object.
4235
4500
  * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
4236
4501
  * in which case ContactShadows scale would affect the projection
@@ -4460,13 +4725,14 @@ export declare class Context implements IContext {
4460
4725
  * Use `setCurrentCamera` for updating the main camera.
4461
4726
  */
4462
4727
  /**
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.
4728
+ * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
4729
+ * Types are generated automatically from your GLB files when the dev server starts.
4730
+ *
4731
+ * You can store references to objects or components for later use.
4732
+ * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
4733
+ * in which case stored references may become stale.
4466
4734
  *
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)`.
4735
+ * @experimental This API may change in future versions.
4470
4736
  *
4471
4737
  * @example
4472
4738
  * // Toggle auto-rotate on the orbit camera
@@ -4475,12 +4741,6 @@ export declare class Context implements IContext {
4475
4741
  * @example
4476
4742
  * // Change the background color
4477
4743
  * 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
4744
  */
4485
4745
  get sceneData(): SceneData;
4486
4746
  get mainCamera(): Camera_2;
@@ -4489,34 +4749,48 @@ export declare class Context implements IContext {
4489
4749
  private _mainCamera;
4490
4750
  private _fallbackCamera;
4491
4751
  /** access application state (e.g. if all audio should be muted) */
4492
- application: Application;
4752
+ get application(): Application;
4753
+ private _application;
4493
4754
  /** access animation mixer used by components in the scene */
4494
- animations: AnimationsRegistry;
4755
+ get animations(): AnimationsRegistry;
4756
+ private _animations;
4495
4757
  /** access timings (current frame number, deltaTime, timeScale, ...) */
4496
- time: Time;
4758
+ get time(): Time;
4759
+ private _time;
4497
4760
  /** access input data (e.g. click or touch events) */
4498
- input: Input;
4761
+ get input(): Input;
4762
+ private _input;
4499
4763
  /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
4500
- physics: Physics;
4764
+ get physics(): Physics;
4765
+ private _physics;
4501
4766
  /** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
4502
- postprocessing: PostProcessing;
4767
+ get postprocessing(): PostProcessing;
4768
+ private _postprocessing;
4503
4769
  /** access networking methods (use it to send or listen to messages or join a networking backend) */
4504
- connection: NetworkConnection;
4770
+ get connection(): NetworkConnection;
4771
+ private _connection;
4772
+ /** context-level event bus for decoupled component communication
4773
+ * @see {@link ContextEventMap} for known event types
4774
+ */
4775
+ get events(): EventBus;
4776
+ private _events;
4505
4777
  /** @deprecated AssetDatabase is deprecated */
4506
4778
  assets: AssetDatabase;
4507
- /** All registered lights in the scene, maintained by the Light component */
4508
- readonly lights: Set<ILight>;
4779
+ /** All registered lights in the scene, maintained by the Light component.
4780
+ * @see mainLight for accessing the main directional light in the scene
4781
+ */
4782
+ readonly lights: ILight[];
4509
4783
  /** The brightest registered directional light, or null if none are registered
4510
4784
  * @see lights
4511
4785
  */
4512
4786
  get mainLight(): ILight | null;
4513
4787
  /** @deprecated Use sceneLighting */
4514
- get rendererData(): RendererData;
4788
+ private get rendererData();
4515
4789
  /** Access the scene lighting manager to control lighting settings in the context */
4516
- sceneLighting: RendererData;
4517
- addressables: Addressables;
4518
- lightmaps: ILightDataRegistry;
4519
- players: PlayerViewManager;
4790
+ readonly sceneLighting: RendererData;
4791
+ readonly addressables: Addressables;
4792
+ readonly lightmaps: ILightDataRegistry;
4793
+ readonly players: PlayerViewManager;
4520
4794
  /** Access the LODs manager to control LOD behavior in the context */
4521
4795
  readonly lodsManager: LODsManager;
4522
4796
  /** Access the needle menu to add or remove buttons to the menu element */
@@ -4758,6 +5032,18 @@ export declare type ContextEventArgs = {
4758
5032
  files?: LoadedModel[];
4759
5033
  };
4760
5034
 
5035
+ /** Typed event map for {@link Context.events}.
5036
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
5037
+ */
5038
+ export declare interface ContextEventMap {
5039
+ "scene-content-changed": {
5040
+ /** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
5041
+ readonly source: IComponent;
5042
+ /** The root object that was added/loaded */
5043
+ readonly object: Object3D;
5044
+ };
5045
+ }
5046
+
4761
5047
  /** Use to register to various Needle Engine context events and to get access to all current instances
4762
5048
  * e.g. when being created in the DOM
4763
5049
  * @example
@@ -4809,6 +5095,20 @@ export declare type ControlClipModel = {
4809
5095
  updateDirector: boolean;
4810
5096
  };
4811
5097
 
5098
+ /**
5099
+ * Options for a control clip in the timeline builder
5100
+ */
5101
+ export declare type ControlClipOptions = {
5102
+ /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
5103
+ start?: number;
5104
+ /** Duration of the clip in seconds (required) */
5105
+ duration: number;
5106
+ /** Whether to control the activation of the source object (default: true) */
5107
+ controlActivation?: boolean;
5108
+ /** Whether to update a nested PlayableDirector on the source object (default: true) */
5109
+ updateDirector?: boolean;
5110
+ };
5111
+
4812
5112
  /** true when selectstart was ever received.
4813
5113
  * On VisionOS 1.1 we always have select events (as per the spec), so this is always true
4814
5114
  */
@@ -4819,12 +5119,15 @@ declare type ControllerAxes = "xr-standard-thumbstick" | "xr-standard-touchpad";
4819
5119
  */
4820
5120
  export declare type ControllerChangedEvt = (args: NeedleXRControllerEventArgs) => void;
4821
5121
 
4822
- export declare class ControlTrackHandler extends TrackHandler {
4823
- models: Array<Models.ClipModel>;
4824
- timelines: Array<PlayableDirector | null>;
4825
- resolveSourceObjects(_context: Context): void;
4826
- private _previousActiveModel;
4827
- evaluate(time: number): void;
5122
+ /**
5123
+ * Builder for control tracks. Provides `.clip()` for controlling nested objects/timelines.
5124
+ * @category Animation and Sequencing
5125
+ */
5126
+ export declare interface ControlTrackBuilder extends TimelineBuilderBase {
5127
+ /** Adds a control clip for a source object */
5128
+ clip(sourceObject: Object3D, options: ControlClipOptions): ControlTrackBuilder;
5129
+ /** Mutes this track so it is skipped during playback */
5130
+ muted(muted?: boolean): ControlTrackBuilder;
4828
5131
  }
4829
5132
 
4830
5133
  /**@obsolete use Graphics.copyTexture */
@@ -5012,7 +5315,6 @@ export declare class CursorFollow extends Component {
5012
5315
  * - Cursor that follows terrain or mesh surfaces
5013
5316
  *
5014
5317
  * **Important notes:**
5015
- * - Requires objects in the scene to have colliders for raycasting to work
5016
5318
  * - Works best with {@link keepDistance} set to `false` to allow depth changes
5017
5319
  * - Can be combined with {@link damping} for smooth surface following
5018
5320
  * - The raycast uses the physics system's raycast functionality
@@ -5139,7 +5441,7 @@ export declare function decompressGpuTexture(texture: any, maxTextureSize?: numb
5139
5441
  * return true;
5140
5442
  * });
5141
5443
  * */
5142
- export declare function deepClone(obj: any, predicate?: deepClonePredicate): any;
5444
+ export declare function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any;
5143
5445
 
5144
5446
  declare type deepClonePredicate = (owner: any, propertyName: string, current: any) => boolean;
5145
5447
 
@@ -5367,7 +5669,7 @@ export declare namespace DeviceUtilities {
5367
5669
  * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
5368
5670
  * @see {@link PlayableDirector.extrapolationMode}
5369
5671
  */
5370
- declare enum DirectorWrapMode {
5672
+ export declare enum DirectorWrapMode {
5371
5673
  /** Hold the last frame when playback reaches the end of the timeline. */
5372
5674
  Hold = 0,
5373
5675
  /** Loop back to the start and continue playing indefinitely. */
@@ -5376,6 +5678,101 @@ declare enum DirectorWrapMode {
5376
5678
  None = 2
5377
5679
  }
5378
5680
 
5681
+ /**
5682
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
5683
+ * that should be cleaned up together.
5684
+ *
5685
+ * DisposableStore collects disposables and disposes them all at once when
5686
+ * {@link dispose} is called. After disposal, the store can be reused — new items
5687
+ * can be added and a subsequent {@link dispose} call will clean those up.
5688
+ *
5689
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
5690
+ *
5691
+ * @example Basic usage
5692
+ * ```ts
5693
+ * import { DisposableStore, on } from "@needle-tools/engine";
5694
+ *
5695
+ * const store = new DisposableStore();
5696
+ *
5697
+ * // Register a DOM event listener (typed!)
5698
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
5699
+ *
5700
+ * // Register the return value of EventList.on()
5701
+ * store.add(myEventList.on(data => console.log(data)));
5702
+ *
5703
+ * // Register a raw cleanup function
5704
+ * store.add(() => someSDK.off("event", handler));
5705
+ *
5706
+ * // Later: dispose everything at once
5707
+ * store.dispose();
5708
+ * ```
5709
+ *
5710
+ * @example Use with Needle Engine components
5711
+ * ```ts
5712
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
5713
+ *
5714
+ * export class MyComponent extends Behaviour {
5715
+ * @serializable(EventList)
5716
+ * onClick?: EventList;
5717
+ *
5718
+ * onEnable() {
5719
+ * // DOM events — fully typed
5720
+ * this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
5721
+ *
5722
+ * // EventList — .on() returns a function, autoCleanup accepts it
5723
+ * this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
5724
+ * }
5725
+ * // No onDisable needed — cleaned up automatically!
5726
+ * }
5727
+ * ```
5728
+ *
5729
+ * @category Utilities
5730
+ * @group Lifecycle
5731
+ */
5732
+ export declare class DisposableStore implements IDisposable {
5733
+ private _disposables;
5734
+ /** The number of registered disposables */
5735
+ get size(): number;
5736
+ /**
5737
+ * Register a disposable resource. Accepts:
5738
+ * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
5739
+ * - A cleanup function (e.g. return value of `EventList.on()`)
5740
+ * - `null` or `undefined` (safe no-op for conditional subscriptions)
5741
+ *
5742
+ * When {@link dispose} is called, all registered resources are cleaned up.
5743
+ *
5744
+ * @param disposable The resource to register for disposal
5745
+ *
5746
+ * @example
5747
+ * ```ts
5748
+ * const store = new DisposableStore();
5749
+ *
5750
+ * // IDisposable object from on()
5751
+ * store.add(on(window, "resize", handler));
5752
+ *
5753
+ * // Function returned by EventList.on()
5754
+ * store.add(myEvent.on(handler));
5755
+ *
5756
+ * // Raw cleanup function
5757
+ * store.add(() => connection.close());
5758
+ *
5759
+ * // Conditional — safe with undefined
5760
+ * store.add(this.maybeEvent?.on(handler));
5761
+ * ```
5762
+ */
5763
+ add(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
5764
+ /**
5765
+ * Dispose all registered resources. Each registered disposable is cleaned up,
5766
+ * then the internal list is cleared. The store can be reused after disposal.
5767
+ *
5768
+ * Called automatically by the engine when a component's `onDisable` lifecycle fires.
5769
+ */
5770
+ dispose(): void;
5771
+ }
5772
+
5773
+ /** A function that performs cleanup when called */
5774
+ export declare type DisposeFn = () => void;
5775
+
5379
5776
  /** Recursive disposes all referenced resources by this object. Does not traverse children */
5380
5777
  export declare function disposeObjectResources(obj: object | null | undefined): void;
5381
5778
 
@@ -5483,6 +5880,12 @@ export declare class DragControls extends Component implements IPointerEventHand
5483
5880
  * providing visual feedback about the object's position relative to surfaces below it.
5484
5881
  */
5485
5882
  showGizmo: boolean;
5883
+ /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
5884
+ dragStarted: EventList;
5885
+ /** Invoked every frame while the object is being dragged. */
5886
+ dragUpdated: EventList;
5887
+ /** Invoked once when the last pointer is released and the drag ends. */
5888
+ dragEnded: EventList;
5486
5889
  /**
5487
5890
  * Returns the object currently being dragged by this DragControls component, if any.
5488
5891
  * @returns The object being dragged or null if no object is currently dragged
@@ -5923,17 +6326,43 @@ export declare class EnvironmentScene extends Scene {
5923
6326
  createAreaLightMaterial(intensity: number): MeshBasicMaterial;
5924
6327
  }
5925
6328
 
5926
- export declare const euler: EulerSerializer;
6329
+ /** An Euler value, either as a Three.js Euler or as a `[x, y, z]` tuple (radians) */
6330
+ declare type EulerValue = Euler | [number, number, number];
5927
6331
 
5928
- declare class EulerSerializer extends TypeSerializer {
5929
- constructor();
5930
- onDeserialize(data: any, _context: SerializationContext): Euler | undefined;
5931
- onSerialize(data: any, _context: SerializationContext): {
5932
- x: any;
5933
- y: any;
5934
- z: any;
5935
- order: any;
5936
- };
6332
+ /** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
6333
+ * Custom events can be typed at the call site via generic parameter.
6334
+ * @example Known events
6335
+ * ```ts
6336
+ * context.events.on("scene-content-changed", e => e.object);
6337
+ * ```
6338
+ * @example Custom events — type at call site
6339
+ * ```ts
6340
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
6341
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
6342
+ * ```
6343
+ * @example Once
6344
+ * ```ts
6345
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
6346
+ * ```
6347
+ */
6348
+ export declare class EventBus {
6349
+ private _listeners;
6350
+ /** Emit a known {@link ContextEventMap} event */
6351
+ emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
6352
+ /** Emit a custom event with user-provided type */
6353
+ emit<T>(type: string, detail?: T): void;
6354
+ /** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
6355
+ on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
6356
+ /** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
6357
+ on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
6358
+ /** Remove all listeners. Called when the context is cleared or destroyed. */
6359
+ clear(): void;
6360
+ }
6361
+
6362
+ /** Options for {@link EventBus.on}. */
6363
+ export declare interface EventBusListenerOptions {
6364
+ /** If true the listener is automatically removed after the first invocation. */
6365
+ once?: boolean;
5937
6366
  }
5938
6367
 
5939
6368
  /**
@@ -5982,13 +6411,9 @@ declare class EulerSerializer extends TypeSerializer {
5982
6411
  * @see {@link Button} for UI button events
5983
6412
  */
5984
6413
  export declare class EventList<TArgs extends any = any> implements IEventList {
6414
+ $serializedTypes: Record<string, any>;
5985
6415
  /** checked during instantiate to create a new instance */
5986
6416
  readonly isEventList = true;
5987
- /* Excluded from this release type: __internalOnInstantiate */
5988
- private target?;
5989
- private key?;
5990
- /** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
5991
- setEventTarget(key: string, target: object): void;
5992
6417
  /** How many callback methods are subscribed to this event */
5993
6418
  get listenerCount(): number;
5994
6419
  /** If the event is currently being invoked */
@@ -6021,13 +6446,41 @@ export declare class EventList<TArgs extends any = any> implements IEventList {
6021
6446
  invoke(...args: Array<TArgs>): boolean;
6022
6447
  /** Add a new event listener to this event
6023
6448
  * @returns a function to remove the event listener
6449
+ * @see {@link removeEventListener} for more details and return value information
6450
+ * @see {@link off} for an alias with better readability when unsubscribing from events
6451
+ * @example
6452
+ * ```ts
6453
+ * const off = myEvent.addEventListener(args => console.log("Clicked!", args));
6454
+ * // later
6455
+ * off();
6456
+ * ```
6024
6457
  */
6025
6458
  addEventListener(callback: (args: TArgs) => void): Function;
6459
+ /**
6460
+ * Alias for addEventListener for better readability when subscribing to events. You can use it like this:
6461
+ * ```ts
6462
+ * myEvent.on(args => console.log("Clicked!", args));
6463
+ * ```
6464
+ * @returns a function to remove the event listener
6465
+ * @see {@link addEventListener} for more details and return value information
6466
+ */
6467
+ on(callback: (args: TArgs) => void): Function;
6026
6468
  /**
6027
6469
  * Remove an event listener from this event.
6028
6470
  * @returns true if the event listener was found and removed, false otherwise
6029
6471
  */
6030
6472
  removeEventListener(fn: Function | null | undefined): boolean;
6473
+ /**
6474
+ * Alias for removeEventListener for better readability when unsubscribing from events. You can use it like this:
6475
+ * ```ts
6476
+ * const off = myEvent.on(args => console.log("Clicked!", args));
6477
+ * // later
6478
+ * off();
6479
+ * ```
6480
+ *
6481
+ * @see {@link removeEventListener} for more details and return value information
6482
+ */
6483
+ off(callback: Function | null | undefined): boolean;
6031
6484
  /**
6032
6485
  * Remove all event listeners from this event. Use with caution! This will remove all listeners!
6033
6486
  */
@@ -6058,6 +6511,7 @@ declare type EventListenerOptions_2 = {
6058
6511
  signal?: AbortSignal;
6059
6512
  };
6060
6513
 
6514
+ /** @deprecated No longer automatically dispatched. Use `eventList.on()` directly instead. */
6061
6515
  export declare class EventListEvent<TArgs extends any> extends Event {
6062
6516
  args?: TArgs;
6063
6517
  }
@@ -6068,7 +6522,7 @@ declare class EventListSerializer extends TypeSerializer {
6068
6522
  onDeserialize(data: EventListData, context: SerializationContext): EventList<any> | undefined | null;
6069
6523
  }
6070
6524
 
6071
- export declare const eventListSerializer: EventListSerializer;
6525
+ export declare let eventListSerializer: EventListSerializer;
6072
6526
 
6073
6527
  /**
6074
6528
  * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
@@ -6511,7 +6965,7 @@ declare type FitParameters = {
6511
6965
  * @see {@link HingeJoint} for rotating connections
6512
6966
  */
6513
6967
  export declare class FixedJoint extends Joint {
6514
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
6968
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
6515
6969
  }
6516
6970
 
6517
6971
  declare type FocusRect = DOMRect | Element | {
@@ -7695,14 +8149,8 @@ export declare type GuidsMap = {
7695
8149
  [key: string]: string;
7696
8150
  };
7697
8151
 
7698
- /* Excluded from this release type: hasCommercialLicense */
7699
-
7700
- /* Excluded from this release type: hasIndieLicense */
7701
-
7702
8152
  /* Excluded from this release type: hasPointerEventComponent */
7703
8153
 
7704
- /* Excluded from this release type: hasProLicense */
7705
-
7706
8154
  export declare function hideDebugConsole(): void;
7707
8155
 
7708
8156
  export declare enum HideFlags {
@@ -7762,7 +8210,7 @@ export declare class HingeJoint extends Joint {
7762
8210
  anchor?: Vector3;
7763
8211
  /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
7764
8212
  axis?: Vector3;
7765
- protected createJoint(self: Rigidbody, other: Rigidbody): void;
8213
+ protected createJoint(self: Rigidbody, other: Rigidbody): any;
7766
8214
  }
7767
8215
 
7768
8216
  declare type HitPointObject = Object3D & {
@@ -7985,7 +8433,7 @@ declare const HTMLElementBase: typeof HTMLElement;
7985
8433
 
7986
8434
  export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
7987
8435
  isAnimationComponent: boolean;
7988
- addClip?(clip: AnimationClip): any;
8436
+ addClip?(clip: AnimationClip): void;
7989
8437
  };
7990
8438
 
7991
8439
  /* Excluded from this release type: IApplyPrototypeExtension */
@@ -8059,6 +8507,12 @@ export declare interface ICollider extends IComponent {
8059
8507
  * Default: undefined
8060
8508
  */
8061
8509
  filter?: number[];
8510
+ /** The density of the collider used for automatic mass calculation.
8511
+ * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
8512
+ * Note: Make sure to call updateProperties after having changed this property
8513
+ * Default: undefined (uses physics engine default of 1.0)
8514
+ */
8515
+ density?: number;
8062
8516
  }
8063
8517
 
8064
8518
  export declare type ICollisionContext = {
@@ -8085,7 +8539,6 @@ export declare interface IComponent extends IHasGuid {
8085
8539
  /* Excluded from this release type: __internalEnable */
8086
8540
  /* Excluded from this release type: __internalDisable */
8087
8541
  /* Excluded from this release type: __internalDestroy */
8088
- /* Excluded from this release type: resolveGuids */
8089
8542
  /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
8090
8543
  registering?(): any;
8091
8544
  awake(): any;
@@ -8122,6 +8575,24 @@ export declare interface IConnectionData {
8122
8575
 
8123
8576
  export declare type IContext = Context;
8124
8577
 
8578
+ /**
8579
+ * Interface for objects that hold resources and can be disposed.
8580
+ * Implement this interface on any object that needs deterministic cleanup.
8581
+ *
8582
+ * @example
8583
+ * ```ts
8584
+ * class MyResource implements IDisposable {
8585
+ * dispose() { /* release resources *\/ }
8586
+ * }
8587
+ * ```
8588
+ *
8589
+ * @category Utilities
8590
+ * @group Lifecycle
8591
+ */
8592
+ export declare interface IDisposable {
8593
+ dispose(): void;
8594
+ }
8595
+
8125
8596
  /** Implement to receive callbacks from {@type @needle-tools/editor-sync} package */
8126
8597
  declare interface IEditorModification {
8127
8598
  /**
@@ -8141,7 +8612,6 @@ export declare interface IEffectProvider {
8141
8612
 
8142
8613
  export declare interface IEventList {
8143
8614
  readonly isEventList: true;
8144
- __internalOnInstantiate(map: InstantiateContext): IEventList;
8145
8615
  }
8146
8616
 
8147
8617
  export declare interface IGameObject extends Object3D {
@@ -8434,13 +8904,45 @@ export declare interface INeedleXRSessionEventReceiver extends Pick<IComponent,
8434
8904
  export declare interface INetworkConnection {
8435
8905
  get isConnected(): boolean;
8436
8906
  get isInRoom(): boolean;
8437
- send(key: string, data: IModel | object | boolean | null | string | number, queue: SendQueue): unknown;
8907
+ send(key: string, data?: IModel | object | boolean | string | number, queue?: SendQueue): unknown;
8438
8908
  }
8439
8909
 
8440
8910
  export declare interface INetworkingWebsocketUrlProvider {
8441
8911
  getWebsocketUrl(): string | null;
8442
8912
  }
8443
8913
 
8914
+ /**
8915
+ * @experimental
8916
+ * Interface for a network transport layer used by {@link NetworkConnection}.
8917
+ * The default implementation wraps a websocket via `websocket-ts`.
8918
+ * Custom implementations can be injected into {@link NetworkConnection.connect}
8919
+ * for testing or alternative transports.
8920
+ *
8921
+ * **Lifecycle:** After creating a transport and passing it to `connect()`,
8922
+ * `NetworkConnection` sets the four event callbacks (`onOpen`, `onClose`,
8923
+ * `onError`, `onMessage`) and then calls {@link start}. The transport
8924
+ * should call `onOpen` when the connection is ready.
8925
+ */
8926
+ export declare interface INetworkTransport {
8927
+ /** Start the connection. Called by NetworkConnection after event callbacks are set.
8928
+ * May return a promise if setup is async (e.g. dynamic imports). */
8929
+ start(): void | Promise<void>;
8930
+ /** Send data (string for JSON messages, Uint8Array for binary) */
8931
+ send(data: string | Uint8Array): void;
8932
+ /** Close the transport */
8933
+ close(): void | Promise<void>;
8934
+ /** The URL this transport is connected to, if applicable */
8935
+ readonly url: string | undefined;
8936
+ /** Called when the transport connection opens */
8937
+ onOpen: (() => void) | null;
8938
+ /** Called when the transport connection closes */
8939
+ onClose: (() => void) | null;
8940
+ /** Called when an error occurs */
8941
+ onError: ((err: any) => void) | null;
8942
+ /** Called when a message is received. Data is either a string (JSON) or Blob (binary). */
8943
+ onMessage: ((data: string | Blob) => void) | null;
8944
+ }
8945
+
8444
8946
  export declare class InheritVelocityModule {
8445
8947
  enabled: boolean;
8446
8948
  curve: MinMaxCurve;
@@ -8460,10 +8962,20 @@ export declare class InheritVelocityModule {
8460
8962
  applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
8461
8963
  }
8462
8964
 
8965
+ /* Excluded from this release type: initAddressableSerializers */
8966
+
8967
+ /** Register all builtin serializers and prototype patches.
8968
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
8969
+ * when the package declares `sideEffects: false`.
8970
+ */
8971
+ export declare function initBuiltinSerializers(): void;
8972
+
8463
8973
  /** Register the Rapier physics backend. Called from {@link initEngine}
8464
8974
  * to ensure it runs regardless of tree-shaking. */
8465
8975
  export declare function initPhysics(): void;
8466
8976
 
8977
+ /* Excluded from this release type: initVolumeParameterSerializer */
8978
+
8467
8979
  /**
8468
8980
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
8469
8981
  * Access via `this.context.input` from any component.
@@ -8517,14 +9029,33 @@ export declare class Input implements IInput {
8517
9029
  */
8518
9030
  private readonly _eventListeners;
8519
9031
  /** Adds an event listener for the specified event type. The callback will be called when the event is triggered.
9032
+ *
9033
+ * Returns an unsubscribe function — call it to remove the listener.
9034
+ * Pass it to {@link Behaviour.autoCleanup} for automatic lifecycle management.
9035
+ *
8520
9036
  * @param type The event type to listen for
8521
9037
  * @param callback The callback to call when the event is triggered
8522
9038
  * @param options The options for adding the event listener.
8523
- * @example Basic usage
9039
+ * @returns A function that removes the event listener when called.
9040
+ *
9041
+ * @example With autoCleanup (recommended)
8524
9042
  * ```ts
8525
- * input.addEventListener("pointerdown", (evt) => {
9043
+ * export class MyComponent extends Behaviour {
9044
+ * onEnable() {
9045
+ * this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => {
9046
+ * console.log("Pointer down", evt.pointerId, evt.pointerType);
9047
+ * }));
9048
+ * }
9049
+ * // Listener is automatically removed on disable — no manual cleanup needed!
9050
+ * }
9051
+ * ```
9052
+ * @example Manual unsubscribe
9053
+ * ```ts
9054
+ * const off = input.addEventListener("pointerdown", (evt) => {
8526
9055
  * console.log("Pointer down", evt.pointerId, evt.pointerType);
8527
9056
  * });
9057
+ * // later
9058
+ * off();
8528
9059
  * ```
8529
9060
  * @example Adding a listener that is called after all other listeners
8530
9061
  * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
@@ -8540,8 +9071,8 @@ export declare class Input implements IInput {
8540
9071
  * }, { once: true });
8541
9072
  * ```
8542
9073
  */
8543
- addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): any;
8544
- addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): any;
9074
+ addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): () => void;
9075
+ addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): () => void;
8545
9076
  /** Removes the event listener from the specified event type. If no queue is specified the listener will be removed from all queues.
8546
9077
  * @param type The event type to remove the listener from
8547
9078
  * @param callback The callback to remove
@@ -8987,7 +9518,7 @@ export declare function instantiate(instance: AssetReference, opts?: IInstantiat
8987
9518
  export declare function instantiate(instance: IGameObject | Object3D, opts?: IInstantiateOptions | null): IGameObject;
8988
9519
 
8989
9520
  /**
8990
- * Provides access to the instantiated object and its clone
9521
+ * Provides access to the instantiated object map (used by EventList etc.)
8991
9522
  */
8992
9523
  export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
8993
9524
 
@@ -9027,7 +9558,8 @@ export declare class InstantiateOptions implements IInstantiateOptions {
9027
9558
  cloneAssign(other: InstantiateOptions | IInstantiateOptions): void;
9028
9559
  }
9029
9560
 
9030
- declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9561
+ /** Maps uuid/guid → { original, clone } for Object3D and Component instances */
9562
+ export declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
9031
9563
 
9032
9564
  /**
9033
9565
  * An empty component that can be used to mark an object as interactable.
@@ -9098,8 +9630,10 @@ export declare interface IPhysicsEngine {
9098
9630
  postStep(): any;
9099
9631
  /** Indicates whether the physics engine is currently updating */
9100
9632
  get isUpdating(): boolean;
9101
- /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
9102
- clearCaches(): any;
9633
+ /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
9634
+ dispose(): void;
9635
+ /** @deprecated Use {@link dispose} instead. */
9636
+ clearCaches(): void;
9103
9637
  /** Enables or disables the physics engine */
9104
9638
  enabled: boolean;
9105
9639
  /** Returns the underlying physics world object */
@@ -9146,6 +9680,11 @@ export declare interface IPhysicsEngine {
9146
9680
  * @returns False to ignore this collider, true to include it
9147
9681
  */
9148
9682
  filterPredicate?: (collider: ICollider) => boolean;
9683
+ /** When true, trigger/sensor colliders will be included in the raycast results.
9684
+ * By default trigger colliders are skipped.
9685
+ * @default false
9686
+ */
9687
+ includeTriggers?: boolean;
9149
9688
  }): RaycastResult;
9150
9689
  /**
9151
9690
  * Performs a raycast that also returns the normal vector at the hit point
@@ -9173,6 +9712,11 @@ export declare interface IPhysicsEngine {
9173
9712
  * @returns False to ignore this collider, true to include it
9174
9713
  */
9175
9714
  filterPredicate?: (collider: ICollider) => boolean;
9715
+ /** When true, trigger/sensor colliders will be included in the raycast results.
9716
+ * By default trigger colliders are skipped.
9717
+ * @default false
9718
+ */
9719
+ includeTriggers?: boolean;
9176
9720
  }): RaycastResult;
9177
9721
  /**
9178
9722
  * Finds all colliders within a sphere
@@ -9329,8 +9873,9 @@ export declare interface IPhysicsEngine {
9329
9873
  * @returns The underlying physics body or null if not found
9330
9874
  */
9331
9875
  getBody(obj: ICollider | IRigidbody): null | any;
9332
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): any;
9333
- addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): any;
9876
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
9877
+ addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
9878
+ removeJoint(joint: any): void;
9334
9879
  /** Enable to render collider shapes */
9335
9880
  debugRenderColliders: boolean;
9336
9881
  /** Enable to visualize raycasts in the scene with gizmos */
@@ -9551,6 +10096,18 @@ export declare function isDestroyed(go: Object3D): boolean;
9551
10096
  /** True when the application runs on a local url */
9552
10097
  export declare function isDevEnvironment(): boolean;
9553
10098
 
10099
+ /**
10100
+ * Type guard to check if an object implements {@link IDisposable}.
10101
+ *
10102
+ * @example
10103
+ * ```ts
10104
+ * if (isDisposable(obj)) {
10105
+ * obj.dispose(); // safe to call
10106
+ * }
10107
+ * ```
10108
+ */
10109
+ export declare function isDisposable(value: unknown): value is IDisposable;
10110
+
9554
10111
  export declare function isDisposed(obj: object): boolean;
9555
10112
 
9556
10113
  export declare interface ISerializable {
@@ -9585,6 +10142,10 @@ export declare function isHotReloadEnabled(): boolean;
9585
10142
  /**@returns true if the element is an needle engine icon element */
9586
10143
  export declare function isIconElement(element: Node): boolean;
9587
10144
 
10145
+ export declare interface ISignalReceiver {
10146
+ readonly isSignalReceiver: true;
10147
+ }
10148
+
9588
10149
  /** @deprecated use {@link DeviceUtilities.isiOS} instead */
9589
10150
  export declare function isiOS(): boolean;
9590
10151
 
@@ -9619,6 +10180,8 @@ export declare function isResourceTrackingEnabled(): boolean;
9619
10180
  /** @deprecated use {@link DeviceUtilities.isSafari} instead */
9620
10181
  export declare function isSafari(): boolean;
9621
10182
 
10183
+ export declare function isTrackModel(obj: unknown): obj is TrackModel;
10184
+
9622
10185
  export declare function isUsingInstancing(instance: Object3D): boolean;
9623
10186
 
9624
10187
  export declare interface ITime {
@@ -9743,7 +10306,9 @@ declare abstract class Joint extends Component {
9743
10306
  connectedBody?: Rigidbody;
9744
10307
  get rigidBody(): Rigidbody | null;
9745
10308
  private _rigidBody;
10309
+ private _jointHandle;
9746
10310
  onEnable(): void;
10311
+ onDisable(): void;
9747
10312
  private create;
9748
10313
  protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
9749
10314
  }
@@ -9785,6 +10350,17 @@ declare class Keyframe_2 {
9785
10350
  }
9786
10351
  export { Keyframe_2 as Keyframe }
9787
10352
 
10353
+ /** Keyframe array or tween shorthand */
10354
+ declare type KF<V> = AnimationKeyframe<V>[] | Tween<V>;
10355
+
10356
+ /** Keyframe array or tween shorthand */
10357
+ declare type KF_2<V> = AnimationKeyframe<V>[] | Tween<V>;
10358
+
10359
+ /** Keyframe array or tween shorthand */
10360
+ declare type KF_3<V> = AnimationKeyframe<V>[] | Tween<V>;
10361
+
10362
+ /* Excluded from this release type: _kRatU */
10363
+
9788
10364
  declare type LabelHandle = {
9789
10365
  setText(str: string): any;
9790
10366
  };
@@ -9824,6 +10400,8 @@ export declare class LeftRoomResponse {
9824
10400
  room: string;
9825
10401
  }
9826
10402
 
10403
+ /* Excluded from this release type: lHSx */
10404
+
9827
10405
  declare type LifecycleHookContext = {
9828
10406
  context: Context;
9829
10407
  };
@@ -10453,13 +11031,15 @@ export declare function markAsInstancedRendered(go: Object3D, instanced: boolean
10453
11031
  time: number;
10454
11032
  }
10455
11033
 
10456
- export declare class MarkerTrackHandler extends TrackHandler {
10457
- models: Array<Models.MarkerModel & Record<string, any>>;
10458
- needsSorting: boolean;
10459
- foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
10460
- onEnable(): void;
10461
- evaluate(_time: number): void;
10462
- private sort;
11034
+ /**
11035
+ * Builder for marker tracks. Provides `.marker()` for adding markers.
11036
+ * @category Animation and Sequencing
11037
+ */
11038
+ export declare interface MarkerTrackBuilder extends TimelineBuilderBase {
11039
+ /** Adds a marker referencing a signal asset by guid */
11040
+ marker(time: number, asset: string, options?: SignalMarkerOptions): MarkerTrackBuilder;
11041
+ /** Mutes this track so it is skipped during playback */
11042
+ muted(muted?: boolean): MarkerTrackBuilder;
10463
11043
  }
10464
11044
 
10465
11045
  export declare enum MarkerType {
@@ -11005,6 +11585,7 @@ export declare type Model = (GLTF | FBX | OBJ | CustomModel);
11005
11585
 
11006
11586
  declare namespace Models {
11007
11587
  export {
11588
+ isTrackModel,
11008
11589
  TimelineAssetModel,
11009
11590
  TrackType,
11010
11591
  ClipExtrapolation,
@@ -11048,15 +11629,13 @@ export declare type MouseButtonName = "left" | "right" | "middle";
11048
11629
  /* Excluded from this release type: nameofFactory */
11049
11630
 
11050
11631
  /**
11051
- * Global proxy for the primary Needle Engine context.
11052
- * Resolves lazily on property access via `ContextRegistry.Current` —
11053
- * safe to import at module level, including in SSR environments
11054
- * (returns a silent error proxy when no context is active).
11632
+ * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
11633
+ * Use it in React/Svelte/Vue components, button handlers, or plain JavaScript.
11055
11634
  *
11056
- * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
11057
- * components, button handlers, or vanilla JS) instead of threading `ctx` around.
11635
+ * Safe to import at module level, including in SSR environments.
11636
+ * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
11058
11637
  *
11059
- * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
11638
+ * @experimental This API may change in future releases.
11060
11639
  *
11061
11640
  * @example
11062
11641
  * import { needle } from "@needle-tools/engine";
@@ -11214,11 +11793,17 @@ export declare interface NeedleEngineAttributes {
11214
11793
  'hash': string;
11215
11794
  /** Set to automatically add OrbitControls to the loaded scene. */
11216
11795
  'camera-controls': string;
11217
- /** Override the default draco decoder path location. */
11796
+ /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
11797
+ * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
11798
+ * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
11799
+ */
11218
11800
  'dracoDecoderPath': string;
11219
- /** Override the default draco library type. */
11801
+ /** Override the default Draco decoder type. */
11220
11802
  'dracoDecoderType': 'wasm' | 'js';
11221
- /** Override the default KTX2 transcoder/decoder path. */
11803
+ /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
11804
+ * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
11805
+ * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
11806
+ */
11222
11807
  'ktx2DecoderPath': string;
11223
11808
  /** Prevent context from being disposed when element is removed from DOM. */
11224
11809
  'keep-alive': 'true' | 'false';
@@ -12172,8 +12757,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
12172
12757
  get referenceSpace(): XRSpace | null;
12173
12758
  /** @returns the XRFrame `viewerpose` using the xr `referenceSpace` */
12174
12759
  get viewerPose(): XRViewerPose | undefined;
12175
- /** @returns `true` if any image is currently being tracked */
12176
- /** returns true if images are currently being tracked */
12760
+ /** @returns `true` if any image is currently being tracked or emulated */
12177
12761
  get isTrackingImages(): boolean;
12178
12762
  /** The currently active XR rig */
12179
12763
  get rig(): IXRRig | null;
@@ -12219,6 +12803,8 @@ export declare class NeedleXRSession implements INeedleXRSession {
12219
12803
  private readonly _xr_update_scripts;
12220
12804
  /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
12221
12805
  private readonly _inactive_scripts;
12806
+ /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
12807
+ private readonly _scripts_in_xr;
12222
12808
  private readonly _controllerAdded;
12223
12809
  private readonly _controllerRemoved;
12224
12810
  private readonly _originalCameraWorldPosition?;
@@ -12606,7 +13192,7 @@ export declare class NetworkConnection implements INetworkConnection {
12606
13192
  /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
12607
13193
  leaveRoom(room?: string | null): boolean;
12608
13194
  /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
12609
- send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType) | null, queue?: SendQueue): void;
13195
+ send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType), queue?: SendQueue): void;
12610
13196
  /**
12611
13197
  * Deletes the network state for a specific object on the server.
12612
13198
  * This removes the object's state from the room, preventing it from being sent to newly joining users.
@@ -12628,61 +13214,69 @@ export declare class NetworkConnection implements INetworkConnection {
12628
13214
  private _defaultMessagesBufferArray;
12629
13215
  sendBufferedMessagesNow(): void;
12630
13216
  /** Use to start listening to networking events.
12631
- * To unsubscribe from events use the `{@link stopListen}` method.
13217
+ * Returns an unsubscribe function that removes the listener when called.
13218
+ * The returned function can also be passed to {@link stopListen} or {@link Component.autoCleanup} for automatic lifecycle management.
12632
13219
  *
12633
- * @example Custom event example
13220
+ * @example With autoCleanup (recommended)
12634
13221
  * ```ts
12635
- * // Listen to a custom event sent by the server
12636
- * this.context.connection.beginListen<MyDataType>("my-custom-event", (data) => {
12637
- * console.log("Received custom event:", data);
12638
- * });
13222
+ * export class MyComponent extends Behaviour {
13223
+ * onEnable() {
13224
+ * this.autoCleanup(this.context.connection.beginListen("joined-room", () => {
13225
+ * console.log("I joined a networked room");
13226
+ * }));
13227
+ * }
13228
+ * // Automatically unsubscribed on disable — no manual cleanup needed!
13229
+ * }
13230
+ * ```
13231
+ *
13232
+ * @example Manual unsubscribe
13233
+ * ```ts
13234
+ * const unsub = this.context.connection.beginListen("joined-room", () => { });
13235
+ * // Later:
13236
+ * unsub(); // removes the listener
12639
13237
  * ```
12640
13238
  *
12641
- * @example Listening to room events
13239
+ * @example With stopListen (legacy pattern, still supported)
12642
13240
  * ```ts
12643
- * // Make sure to unsubscribe from events when the component is disabled
12644
13241
  * export class MyComponent extends Behaviour {
12645
13242
  * onEnable() {
12646
- * this.connection.beginListen("joined-room", this.onJoinedRoom)
13243
+ * this.context.connection.beginListen("joined-room", this.onJoinedRoom);
12647
13244
  * }
12648
13245
  * onDisable() {
12649
- * this.connection.stopListen("joined-room", this.onJoinedRoom)
13246
+ * this.context.connection.stopListen("joined-room", this.onJoinedRoom);
12650
13247
  * }
12651
13248
  * onJoinedRoom = () => {
12652
- * console.log("I joined a networked room")
13249
+ * console.log("I joined a networked room");
12653
13250
  * }
12654
13251
  * }
12655
13252
  * ```
12656
13253
  * @link https://engine.needle.tools/docs/networking.html
12657
13254
  *
12658
13255
  */
12659
- beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void;
13256
+ beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): DisposeFn;
12660
13257
  /**@deprecated please use stopListen instead (2.65.2-pre) */
12661
13258
  stopListening<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
12662
- /** Use to stop listening to networking events
13259
+ /** Use to stop listening to networking events.
13260
+ * Accepts either the original callback or the unsubscribe function returned by {@link beginListen}.
12663
13261
  * To subscribe to events use the `{@link beginListen}` method.
12664
- * See the example below for typical usage:
12665
13262
  *
12666
- * ### Component Example
13263
+ * @example
12667
13264
  * ```ts
12668
- * // Make sure to unsubscribe from events when the component is disabled
12669
- * export class MyComponent extends Behaviour {
12670
- * onEnable() {
12671
- * this.connection.beginListen("joined-room", this.onJoinedRoom)
12672
- * }
12673
- * onDisable() {
12674
- * this.connection.stopListen("joined-room", this.onJoinedRoom)
12675
- * }
12676
- * onJoinedRoom = () => {
12677
- * console.log("I joined a networked room")
12678
- * }
12679
- * }
13265
+ * // Both patterns work:
13266
+ * this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
13267
+ * this.context.connection.stopListen("joined-room", unsub); // unsubscribe fn from beginListen
12680
13268
  * ```
12681
13269
  */
12682
- stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
12683
- /** Use to start listening to networking binary events */
12684
- beginListenBinary(identifier: string, callback: BinaryCallback): BinaryCallback;
12685
- /** Use to stop listening to networking binary events */
13270
+ private static _didLogStopListenHint;
13271
+ stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | Function | null): void;
13272
+ /** Use to start listening to networking binary events.
13273
+ * Returns an unsubscribe function that removes the listener when called.
13274
+ * The returned function can also be passed to {@link stopListenBinary} or {@link Component.autoCleanup}.
13275
+ */
13276
+ beginListenBinary(identifier: string, callback: BinaryCallback): DisposeFn;
13277
+ /** Use to stop listening to networking binary events.
13278
+ * Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
13279
+ */
12686
13280
  stopListenBinary(identifier: string, callback: any): void;
12687
13281
  private netWebSocketUrlProvider?;
12688
13282
  /** Use to override the networking server backend url.
@@ -12691,16 +13285,19 @@ export declare class NetworkConnection implements INetworkConnection {
12691
13285
  registerProvider(prov: INetworkingWebsocketUrlProvider): void;
12692
13286
  /** Used to connect to the networking server
12693
13287
  * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
13288
+ * @param transport Optional custom transport to use instead of the default websocket. Useful for testing or alternative transports.
12694
13289
  */
12695
- connect(url?: string): Promise<boolean>;
13290
+ connect(url?: string, transport?: INetworkTransport): Promise<boolean>;
12696
13291
  /** Disconnect from the networking backend + reset internal state */
12697
13292
  disconnect(): void;
13293
+ /** Full teardown: disconnect, clear all listeners, and release all resources.
13294
+ * Called when the owning Context is destroyed. After dispose(), this instance should not be reused. */
13295
+ dispose(): void;
12698
13296
  private _listeners;
12699
13297
  private _listenersBinary;
12700
13298
  private connected;
12701
- private channelId;
12702
13299
  private _connectionId;
12703
- private _ws;
13300
+ private _transport;
12704
13301
  private _waitingForSocket;
12705
13302
  private _isInRoom;
12706
13303
  private _currentRoomName;
@@ -12710,6 +13307,8 @@ export declare class NetworkConnection implements INetworkConnection {
12710
13307
  private _state;
12711
13308
  private _currentDelay;
12712
13309
  private _connectingToWebsocketPromise;
13310
+ /** Wire up a transport's event callbacks and start it */
13311
+ private connectTransport;
12713
13312
  private connectWebsocket;
12714
13313
  private onMessage;
12715
13314
  private handleIncomingBinaryMessage;
@@ -12838,7 +13437,7 @@ export declare interface NetworkEventMap {
12838
13437
  * @see {@link RoomEvents} for room lifecycle events
12839
13438
  * @see {@link isLocalNetwork} for local network detection
12840
13439
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
12841
- * @summary Networking configuration
13440
+ * @summary Configures the websocket server URL for multiplayer networking
12842
13441
  * @category Networking
12843
13442
  * @group Components
12844
13443
  */
@@ -12975,7 +13574,7 @@ export declare type OBJ = {
12975
13574
  scenes: Object3D[];
12976
13575
  };
12977
13576
 
12978
- declare type ObjectCloneReference = {
13577
+ export declare type ObjectCloneReference = {
12979
13578
  readonly original: object;
12980
13579
  readonly clone: object;
12981
13580
  };
@@ -13059,7 +13658,7 @@ declare class ObjectSerializer extends TypeSerializer {
13059
13658
  onDeserialize(data: ObjectData | string | null, context: SerializationContext): Object3D<Object3DEventMap> | Component | null | undefined;
13060
13659
  }
13061
13660
 
13062
- export declare const objectSerializer: ObjectSerializer;
13661
+ export declare let objectSerializer: ObjectSerializer;
13063
13662
 
13064
13663
  declare type ObjectToNodeMap = {
13065
13664
  [uuid: string]: number;
@@ -13180,7 +13779,62 @@ export declare function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void):
13180
13779
  * offXRSessionStart(myFunction);
13181
13780
  * ```
13182
13781
  */
13183
- export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
13782
+ export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
13783
+
13784
+ /**
13785
+ * @experimental
13786
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
13787
+ * and return an {@link IDisposable} that removes the listener when disposed.
13788
+ *
13789
+ * Provides full TypeScript event type inference — the callback parameter
13790
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
13791
+ * `"click"` → `MouseEvent`).
13792
+ *
13793
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
13794
+ *
13795
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
13796
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
13797
+ * @param listener The event handler callback
13798
+ * @param options Optional addEventListener options (passive, capture, once, signal)
13799
+ * @returns An {@link IDisposable} that removes the event listener when disposed
13800
+ *
13801
+ * @example Standalone usage
13802
+ * ```ts
13803
+ * import { on } from "@needle-tools/engine";
13804
+ *
13805
+ * const sub = on(window, "resize", (ev) => {
13806
+ * // ev is typed as UIEvent
13807
+ * console.log("resized", ev.target);
13808
+ * });
13809
+ *
13810
+ * // Later: clean up
13811
+ * sub.dispose();
13812
+ * ```
13813
+ *
13814
+ * @example With autoCleanup in a component
13815
+ * ```ts
13816
+ * import { Behaviour, on } from "@needle-tools/engine";
13817
+ *
13818
+ * export class MyComponent extends Behaviour {
13819
+ * onEnable() {
13820
+ * this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
13821
+ * this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
13822
+ * this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
13823
+ * }
13824
+ * // All listeners removed automatically on disable!
13825
+ * }
13826
+ * ```
13827
+ *
13828
+ * @category Utilities
13829
+ * @group Lifecycle
13830
+ */
13831
+ export declare function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13832
+
13833
+ export declare function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13834
+
13835
+ export declare function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
13836
+
13837
+ export declare function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
13184
13838
 
13185
13839
  /**
13186
13840
  * Register a callback in the engine onAfterRender event
@@ -13822,8 +14476,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
13822
14476
  * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
13823
14477
  */
13824
14478
  fitCamera(options?: OrbitFitCameraOptions): any;
13825
- /** @deprecated Use fitCamera(options) */
13826
- fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">): any;
13827
14479
  private _haveAttachedKeyboardEvents;
13828
14480
  }
13829
14481
 
@@ -14024,6 +14676,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
14024
14676
  value: number | boolean | string;
14025
14677
  };
14026
14678
 
14679
+ /** Extracts parameter names of a given type from the builder's tracked parameter map */
14680
+ declare type ParamNamesOfType<TParams, PType extends string> = {
14681
+ [K in keyof TParams & string]: TParams[K] extends PType ? K : never;
14682
+ }[keyof TParams & string];
14683
+
14027
14684
  declare type ParseNumber<T> = T extends `${infer U extends number}` ? U : never;
14028
14685
 
14029
14686
  /** Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.
@@ -14655,13 +15312,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14655
15312
  * The timeline asset containing tracks, clips, and markers that this director will play.
14656
15313
  * Assign a timeline asset exported from Unity or Blender to enable playback.
14657
15314
  */
14658
- playableAsset?: Models.TimelineAssetModel;
15315
+ get playableAsset(): Models.TimelineAssetModel | undefined;
15316
+ set playableAsset(value: Models.TimelineAssetModel | undefined);
15317
+ private _playableAsset?;
14659
15318
  /**
14660
15319
  * When true, the timeline starts playing automatically when the component awakens.
14661
15320
  * Set to false to control playback manually via `play()`.
14662
15321
  * @default false
14663
15322
  */
14664
- playOnAwake?: boolean;
15323
+ playOnAwake: boolean;
14665
15324
  /**
14666
15325
  * Determines how the timeline behaves when it reaches the end of its duration.
14667
15326
  * @default DirectorWrapMode.Loop
@@ -14739,15 +15398,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14739
15398
  /** Iterates over all tracks of the timeline
14740
15399
  * @returns all tracks of the timeline
14741
15400
  */
14742
- forEachTrack(): Generator<Tracks.TrackHandler, void, unknown>;
15401
+ forEachTrack(): Generator<Tracks.TimelineTrackHandler, void, unknown>;
14743
15402
  /**
14744
15403
  * @returns all animation tracks of the timeline
14745
15404
  */
14746
- get animationTracks(): Tracks.AnimationTrackHandler[];
15405
+ get animationTracks(): Tracks.TimelineAnimationTrack[];
14747
15406
  /**
14748
15407
  * @returns all audio tracks of the timeline
14749
15408
  */
14750
- get audioTracks(): Tracks.AudioTrackHandler[];
15409
+ get audioTracks(): Tracks.TimelineAudioTrack[];
14751
15410
  /**
14752
15411
  * @returns all signal tracks of the timeline
14753
15412
  */
@@ -14755,7 +15414,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
14755
15414
  /**
14756
15415
  * @returns all marker tracks of the timeline
14757
15416
  */
14758
- get markerTracks(): Tracks.MarkerTrackHandler[];
15417
+ get markerTracks(): Tracks.TimelineMarkerTrack[];
15418
+ /**
15419
+ * @returns all activation tracks of the timeline
15420
+ */
15421
+ get activationTracks(): Tracks.TimelineActivationTrack[];
15422
+ /**
15423
+ * @returns all tracks of the timeline
15424
+ */
15425
+ get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler>;
14759
15426
  /**
14760
15427
  * Iterates over all markers of the timeline, optionally filtering by type
14761
15428
  *
@@ -14769,13 +15436,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
14769
15436
  *
14770
15437
  */
14771
15438
  foreachMarker<T extends Record<string, any>>(type?: string | null): Generator<(T & Models.MarkerModel)>;
14772
- private _guidsMap?;
14773
- /* Excluded from this release type: resolveGuids */
15439
+ private _needsGraphRebuild;
14774
15440
  private _isPlaying;
14775
15441
  private _internalUpdateRoutine;
14776
15442
  private _isPaused;
14777
15443
  /** internal, true during the time stop() is being processed */
14778
15444
  private _isStopping;
15445
+ /* Excluded from this release type: _isUserEvaluation */
14779
15446
  private _time;
14780
15447
  private _duration;
14781
15448
  private _weight;
@@ -14784,6 +15451,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
14784
15451
  private readonly _signalTracks;
14785
15452
  private readonly _markerTracks;
14786
15453
  private readonly _controlTracks;
15454
+ private readonly _activationTracks;
14787
15455
  private readonly _customTracks;
14788
15456
  private readonly _tracksArray;
14789
15457
  private get _allTracks();
@@ -15775,6 +16443,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
15775
16443
  w: number;
15776
16444
  };
15777
16445
 
16446
+ /** A Quaternion value, either as a Three.js Quaternion or as a `[x, y, z, w]` tuple */
16447
+ declare type QuatValue = Quaternion | [number, number, number, number];
16448
+
15778
16449
  /** Generates a random number
15779
16450
  * @deprecated use Mathf.random(min, max)
15780
16451
  */
@@ -15900,6 +16571,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
15900
16571
  * @default undefined
15901
16572
  */
15902
16573
  useIgnoreRaycastLayer?: boolean;
16574
+ /** When true, trigger/sensor colliders will be included in the raycast results.
16575
+ * By default trigger colliders are skipped.
16576
+ * @default false
16577
+ */
16578
+ includeTriggers?: boolean;
15903
16579
  }): null | {
15904
16580
  point: Vector3;
15905
16581
  collider: ICollider;
@@ -15917,6 +16593,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
15917
16593
  * @default undefined
15918
16594
  */
15919
16595
  useIgnoreRaycastLayer?: boolean;
16596
+ /** When true, trigger/sensor colliders will be included in the raycast results.
16597
+ * By default trigger colliders are skipped.
16598
+ * @default false
16599
+ */
16600
+ includeTriggers?: boolean;
15920
16601
  }): null | {
15921
16602
  point: Vector3;
15922
16603
  normal: Vector3;
@@ -15962,6 +16643,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
15962
16643
  private _gravity;
15963
16644
  get gravity(): Vec3;
15964
16645
  set gravity(value: Vec3);
16646
+ /** Tears down the physics world and frees all WASM resources.
16647
+ * After calling this, the world will be re-created on next use. */
16648
+ dispose(): void;
16649
+ /** @deprecated Use {@link dispose} instead. */
15965
16650
  clearCaches(): void;
15966
16651
  addBoxCollider(collider: ICollider, size: Vector3): Promise<void>;
15967
16652
  addSphereCollider(collider: ICollider): Promise<void>;
@@ -16008,7 +16693,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16008
16693
  private getRigidbodyRelativeMatrix;
16009
16694
  private static centerConnectionPos;
16010
16695
  private static centerConnectionRot;
16011
- addFixedJoint(body1: IRigidbody, body2: IRigidbody): void;
16696
+ private _jointTempMatrix;
16697
+ addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<ImpulseJoint | null>;
16012
16698
  /** The joint prevents any relative movement between two rigid-bodies, except for relative rotations along one axis. This is typically used to simulate wheels, fans, etc. They are characterized by one local anchor as well as one local axis on each rigid-body. */
16013
16699
  addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: {
16014
16700
  x: number;
@@ -16018,8 +16704,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
16018
16704
  x: number;
16019
16705
  y: number;
16020
16706
  z: number;
16021
- }): void;
16707
+ }): Promise<ImpulseJoint | null>;
16708
+ removeJoint(joint: ImpulseJoint): void;
16709
+ /** Compute the relative transform from body1's local space to body2's local space (W2⁻¹ * W1), ignoring scale. */
16022
16710
  private calculateJointRelativeMatrices;
16711
+ private normalizeMatrixColumns;
16023
16712
  }
16024
16713
 
16025
16714
  /**
@@ -16822,10 +17511,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
16822
17511
  */
16823
17512
  export declare class Rigidbody extends Component implements IRigidbody {
16824
17513
  get isRigidbody(): boolean;
16825
- /** When true the mass will be automatically calculated by the attached colliders */
17514
+ /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
17515
+ * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
17516
+ * Disable to set mass explicitly via the `mass` property.
17517
+ */
16826
17518
  autoMass: boolean;
16827
- /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes
16828
- * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
17519
+ /** The mass of the rigidbody in kg (when `autoMass` is disabled).
17520
+ * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
17521
+ * Setting this property automatically disables `autoMass`.
17522
+ *
17523
+ * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
17524
+ * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
16829
17525
  */
16830
17526
  set mass(value: number);
16831
17527
  get mass(): number;
@@ -16908,7 +17604,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
16908
17604
  onEnable(): void;
16909
17605
  onDisable(): void;
16910
17606
  onDestroy(): void;
16911
- onValidate(): void;
17607
+ onValidate(property?: string): void;
17608
+ private static _didWarnAutoMass;
16912
17609
  beforePhysics(): Generator<undefined, void, unknown>;
16913
17610
  /** Teleport the rigidbody to a new position in the world.
16914
17611
  * Will reset forces before setting the object world position
@@ -18128,10 +18825,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
18128
18825
 
18129
18826
  export declare function sendDestroyed(guid: string, con: INetworkConnection, opts?: SyncDestroyOptions): void;
18130
18827
 
18828
+ /** Controls when a network message is actually sent to the server.
18829
+ * @see {@link NetworkConnection.send}
18830
+ */
18131
18831
  export declare enum SendQueue {
18832
+ /** Hold the message until the transport connection opens, then send it. Use for messages that must arrive as soon as the socket is ready (e.g. join-room). */
18132
18833
  OnConnection = 0,
18834
+ /** Hold the message until the client has joined a room, then send it. Use for messages that require room context. */
18133
18835
  OnRoomJoin = 1,
18836
+ /** Buffer the message and send it on the next `sendBufferedMessagesNow()` call (typically once per frame). This is the default for `send()`. */
18134
18837
  Queued = 2,
18838
+ /** Send the message to the server immediately without buffering. */
18135
18839
  Immediate = 3
18136
18840
  }
18137
18841
 
@@ -18564,6 +19268,16 @@ export declare class OrbitControls extends Component implements ICameraControlle
18564
19268
  asset: string;
18565
19269
  }
18566
19270
 
19271
+ /**
19272
+ * Options for a signal marker in the timeline builder
19273
+ */
19274
+ export declare type SignalMarkerOptions = {
19275
+ /** Whether the signal should fire if the playback starts past its time (default: false) */
19276
+ retroActive?: boolean;
19277
+ /** Whether the signal should only fire once (default: false) */
19278
+ emitOnce?: boolean;
19279
+ };
19280
+
18567
19281
  /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received.
18568
19282
  * Signals can be added to a signal track on a {@link PlayableDirector}
18569
19283
  *
@@ -18571,7 +19285,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
18571
19285
  * @category Animation and Sequencing
18572
19286
  * @group Components
18573
19287
  */
18574
- export declare class SignalReceiver extends Component {
19288
+ export declare class SignalReceiver extends Component implements ISignalReceiver {
19289
+ readonly isSignalReceiver = true;
18575
19290
  private static receivers;
18576
19291
  static invoke(guid: string): void;
18577
19292
  events?: SignalReceiverEvent[];
@@ -18590,10 +19305,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
18590
19305
  reaction: EventList<void>;
18591
19306
  }
18592
19307
 
18593
- export declare class SignalTrackHandler extends TrackHandler {
19308
+ /**
19309
+ * Builder for signal tracks. Provides `.signal()` for callback-based signals and `.marker()` for asset-based markers.
19310
+ * @category Animation and Sequencing
19311
+ */
19312
+ export declare interface SignalTrackBuilder extends TimelineBuilderBase {
19313
+ /** Adds a signal with a callback that fires at the given time */
19314
+ signal(time: number, callback: Function, options?: SignalMarkerOptions): SignalTrackBuilder;
19315
+ /** Adds a signal marker referencing a signal asset by guid */
19316
+ marker(time: number, asset: string, options?: SignalMarkerOptions): SignalTrackBuilder;
19317
+ /** Mutes this track so it is skipped during playback */
19318
+ muted(muted?: boolean): SignalTrackBuilder;
19319
+ }
19320
+
19321
+ export declare class SignalTrackHandler extends TimelineTrackHandler {
18594
19322
  models: Models.SignalMarkerModel[];
18595
19323
  didTrigger: boolean[];
18596
19324
  receivers: Array<SignalReceiver | null>;
19325
+ private _lastTime;
19326
+ onEnable(): void;
19327
+ onMuteChanged(): void;
18597
19328
  evaluate(time: number): void;
18598
19329
  }
18599
19330
 
@@ -19093,10 +19824,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
19093
19824
  * Removes scale change monitoring when the collider is disabled.
19094
19825
  */
19095
19826
  onDisable(): void;
19096
- /**
19097
- * Updates collider properties when validated in the editor or inspector.
19098
- */
19099
- onValidate(): void;
19100
19827
  }
19101
19828
 
19102
19829
  export declare class SphereIntersection implements Intersection {
@@ -19849,8 +20576,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
19849
20576
  * Configuration for an animation state in the builder
19850
20577
  */
19851
20578
  export declare type StateOptions = {
19852
- /** The animation clip for this state */
19853
- clip: AnimationClip;
20579
+ /**
20580
+ * The animation clip for this state. Accepts:
20581
+ * - A pre-built `AnimationClip`
20582
+ * - A single {@link TrackDescriptor} from {@link track}
20583
+ * - An array of {@link TrackDescriptor}s (multiple tracks combined into one clip)
20584
+ *
20585
+ * When omitted, use {@link AnimatorControllerBuilder.track .track()} to define animation tracks inline.
20586
+ */
20587
+ clip?: AnimationClip | TrackDescriptor | TrackDescriptor[];
19854
20588
  /** Whether the animation should loop (default: false) */
19855
20589
  loop?: boolean;
19856
20590
  /** Base speed multiplier (default: 1) */
@@ -20416,6 +21150,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
20416
21150
  set font(val: string | null);
20417
21151
  get font(): string | null;
20418
21152
  private _font;
21153
+ private _assignedAtRuntime;
20419
21154
  /**
20420
21155
  * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
20421
21156
  * @default false
@@ -20671,6 +21406,57 @@ export declare class OrbitControls extends Component implements ICameraControlle
20671
21406
  /* Excluded from this release type: update */
20672
21407
  }
20673
21408
 
21409
+ /**
21410
+ * Handles activation (visibility) of bound objects for a timeline activation track.
21411
+ *
21412
+ * Each clip on the track defines a time range during which the bound objects should be active (visible).
21413
+ * @see TimelineTrackHandler for details on how tracks and clips work in general, and how to mutate them at runtime.
21414
+ * @see PlayableDirector for how to control timeline playback and time.
21415
+ * @see TimelineBuilder for how to create and configure timelines and tracks in the editor.
21416
+ */
21417
+ export declare class TimelineActivationTrack extends TimelineTrackHandler {
21418
+ evaluate(time: number): void;
21419
+ }
21420
+
21421
+ export declare class TimelineAnimationTrack extends TimelineTrackHandler {
21422
+ /* Excluded from this release type: models */
21423
+ /* Excluded from this release type: trackOffset */
21424
+ /** The object that is being animated. */
21425
+ target?: Object3D;
21426
+ /** The AnimationMixer, should be shared with the animator if an animator is bound */
21427
+ mixer?: AnimationMixer;
21428
+ clips: Array<AnimationClip>;
21429
+ actions: Array<AnimationAction>;
21430
+ /**
21431
+ * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
21432
+ * @default 1
21433
+ */
21434
+ weight: number;
21435
+ /** holds data/info about clips differences */
21436
+ private _actionOffsets;
21437
+ private _didBind;
21438
+ private _animator;
21439
+ onDisable(): void;
21440
+ onDestroy(): void;
21441
+ onStateChanged(): void;
21442
+ createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
21443
+ bind(): void;
21444
+ private ensureTrackOffsets;
21445
+ private _useclipOffsets;
21446
+ private _totalOffsetPosition;
21447
+ private _totalOffsetRotation;
21448
+ private _totalOffsetPosition2;
21449
+ private _totalOffsetRotation2;
21450
+ private _summedPos;
21451
+ private _tempPos;
21452
+ private _summedRot;
21453
+ private _tempRot;
21454
+ private _clipRotQuat;
21455
+ evaluate(time: number): void;
21456
+ private createRotationInterpolant;
21457
+ private createPositionInterpolant;
21458
+ }
21459
+
20674
21460
  /**
20675
21461
  * @category Animation and Sequencing
20676
21462
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -20680,6 +21466,325 @@ export declare class OrbitControls extends Component implements ICameraControlle
20680
21466
  tracks: TrackModel[];
20681
21467
  };
20682
21468
 
21469
+ /**
21470
+ * Handles audio playback for a timeline audio track.
21471
+ *
21472
+ * **Runtime mutation:** The track model is read fresh every frame during `evaluate()`.
21473
+ * You can mutate `track.volume`, `clip.start`, `clip.end`, `clip.asset.volume` etc.
21474
+ * at any time — changes take effect on the next frame without rebuilding the timeline.
21475
+ *
21476
+ * **Audio stopping:** Audio clips are automatically stopped when:
21477
+ * - Timeline time moves outside a clip's `[start, end]` range (e.g. jumping or normal playback advancing past a clip)
21478
+ * - The track is muted (via `muted = true`)
21479
+ * - The director is stopped (`director.stop()`)
21480
+ * - The director is paused (`director.pause()`)
21481
+ * - The director is disabled or destroyed
21482
+ */
21483
+ export declare class TimelineAudioTrack extends TimelineTrackHandler {
21484
+ models: Array<AudioClipModel_2>;
21485
+ listener: AudioListener_3;
21486
+ audio: Array<Audio_2>;
21487
+ audioContextTimeOffset: Array<number>;
21488
+ lastTime: number;
21489
+ audioSource?: AudioSource;
21490
+ /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
21491
+ get volume(): number;
21492
+ set volume(val: number);
21493
+ private _audioLoader;
21494
+ private getAudioFilePath;
21495
+ onAllowAudioChanged(allow: boolean): void;
21496
+ addModel(model: Models.ClipModel): void;
21497
+ onDisable(): void;
21498
+ onDestroy(): void;
21499
+ onMuteChanged(): void;
21500
+ stop(): void;
21501
+ private _playableDirectorResumed;
21502
+ onPauseChanged(): void;
21503
+ evaluate(time: number): void;
21504
+ /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
21505
+ loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
21506
+ private isInTimeRange;
21507
+ private static _audioBuffers;
21508
+ static dispose(): void;
21509
+ private handleAudioLoading;
21510
+ }
21511
+
21512
+ /**
21513
+ * A fluent builder for creating timeline assets ({@link TimelineAssetModel}) from code.
21514
+ *
21515
+ * Use {@link TimelineBuilder.create} to start building a timeline.
21516
+ *
21517
+ * @example Using build() for timelines without signal callbacks
21518
+ * ```ts
21519
+ * const timeline = TimelineBuilder.create("MySequence")
21520
+ * .animationTrack("Character", animator)
21521
+ * .clip(walkClip, { duration: 2, easeIn: 0.3 })
21522
+ * .clip(runClip, { duration: 3, easeIn: 0.5, easeOut: 0.5 })
21523
+ * .activationTrack("FX", particleObject)
21524
+ * .clip({ start: 1, duration: 2 })
21525
+ * .audioTrack("Music", audioSource)
21526
+ * .clip("music.mp3", { start: 0, duration: 5, volume: 0.8 })
21527
+ * .build();
21528
+ *
21529
+ * director.playableAsset = timeline;
21530
+ * director.play();
21531
+ * ```
21532
+ *
21533
+ * @example With inline tracks (no pre-built clips needed)
21534
+ * ```ts
21535
+ * TimelineBuilder.create("DoorSequence")
21536
+ * .animationTrack("Door", door)
21537
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
21538
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
21539
+ * .signalTrack("Events")
21540
+ * .signal(0.5, () => playSound("creak"))
21541
+ * .install(director);
21542
+ *
21543
+ * director.play();
21544
+ * ```
21545
+ *
21546
+ * @example Using install() with signal callbacks
21547
+ * ```ts
21548
+ * TimelineBuilder.create("WithSignals")
21549
+ * .animationTrack("Character", animator)
21550
+ * .clip(walkClip, { duration: 2 })
21551
+ * .signalTrack("Events")
21552
+ * .signal(1.0, () => console.log("1 second!"))
21553
+ * .signal(2.0, () => spawnParticles())
21554
+ * .install(director);
21555
+ *
21556
+ * director.play();
21557
+ * ```
21558
+ *
21559
+ * @category Animation and Sequencing
21560
+ * @group Utilities
21561
+ */
21562
+ export declare class TimelineBuilder {
21563
+ private _name;
21564
+ private _tracks;
21565
+ private _currentTrack;
21566
+ private _pendingSignals;
21567
+ private _idProvider;
21568
+ private constructor();
21569
+ /**
21570
+ * Creates a new TimelineBuilder instance.
21571
+ * @param name - Name for the timeline asset
21572
+ * @param seed - Optional numeric seed for deterministic guid generation. Defaults to `Date.now()`.
21573
+ */
21574
+ static create(name?: string, seed?: number): TimelineBuilderBase;
21575
+ /**
21576
+ * Adds an animation track. Chain `.clip()` calls to add pre-built clips,
21577
+ * or chain `.track()` calls to define animation data inline:
21578
+ *
21579
+ * @example With pre-built AnimationClip
21580
+ * ```ts
21581
+ * .animationTrack("Character", animator)
21582
+ * .clip(walkClip, { duration: 2, easeIn: 0.3 })
21583
+ * .clip(runClip, { duration: 3 })
21584
+ * ```
21585
+ *
21586
+ * @example With inline tracks
21587
+ * ```ts
21588
+ * .animationTrack("Door", door)
21589
+ * .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
21590
+ * .track(light, "intensity", { from: 0, to: 5, duration: 1 })
21591
+ * ```
21592
+ *
21593
+ * @param name - Display name for the track
21594
+ * @param binding - The Animator or Object3D to animate
21595
+ */
21596
+ animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
21597
+ /**
21598
+ * Adds an audio track. Subsequent `.clip()` calls add audio clips to this track.
21599
+ * @param name - Display name for the track
21600
+ * @param binding - The AudioSource to play audio on (optional)
21601
+ * @param volume - Track volume multiplier (default: 1)
21602
+ */
21603
+ audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
21604
+ /**
21605
+ * Adds an activation track. Subsequent `.clip()` calls define when the bound object is active.
21606
+ * @param name - Display name for the track
21607
+ * @param binding - The Object3D to show/hide
21608
+ */
21609
+ activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
21610
+ /**
21611
+ * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
21612
+ * @param name - Display name for the track
21613
+ */
21614
+ controlTrack(name: string): ControlTrackBuilder;
21615
+ /**
21616
+ * Adds a signal track. Use `.signal()` or `.marker()` to add signal markers.
21617
+ * @param name - Display name for the track
21618
+ * @param binding - The SignalReceiver component (optional — if using `.signal()` with callbacks, one is created automatically by {@link install})
21619
+ */
21620
+ signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
21621
+ /**
21622
+ * Adds a marker track. Use `.marker()` to add markers.
21623
+ * @param name - Display name for the track
21624
+ */
21625
+ markerTrack(name: string): MarkerTrackBuilder;
21626
+ /**
21627
+ * Adds a clip to the current track. The clip type must match the track type.
21628
+ *
21629
+ * - On an **animation track**: pass an `AnimationClip`, a {@link TrackDescriptor}, or a `TrackDescriptor[]` — and optional {@link AnimationClipOptions}
21630
+ * - On an **audio track**: pass a clip URL (string) and {@link AudioClipOptions}
21631
+ * - On an **activation track**: pass {@link ActivationClipOptions}
21632
+ * - On a **control track**: pass an Object3D and {@link ControlClipOptions}
21633
+ */
21634
+ clip(asset: AnimationClip, options?: AnimationClipOptions): this;
21635
+ clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): this;
21636
+ clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): this;
21637
+ clip(url: string, options: AudioClipOptions): this;
21638
+ clip(options: ActivationClipOptions): this;
21639
+ clip(sourceObject: Object3D, options: ControlClipOptions): this;
21640
+ /**
21641
+ * Adds a signal marker to the current signal or marker track.
21642
+ * @param time - Time in seconds when the signal fires
21643
+ * @param asset - The signal asset identifier (guid string)
21644
+ * @param options - Optional marker configuration
21645
+ */
21646
+ marker(time: number, asset: string, options?: SignalMarkerOptions): this;
21647
+ /**
21648
+ * Adds a signal with a callback to the current signal track.
21649
+ * This is a convenience method that automatically generates a signal asset guid,
21650
+ * adds the marker, and registers the callback so that {@link install} can wire up
21651
+ * the `SignalReceiver` on the director's GameObject.
21652
+ *
21653
+ * @param time - Time in seconds when the signal fires
21654
+ * @param callback - The function to invoke when the signal fires
21655
+ * @param options - Optional marker configuration
21656
+ *
21657
+ * @example
21658
+ * ```ts
21659
+ * const timeline = TimelineBuilder.create("Sequence")
21660
+ * .signalTrack("Events")
21661
+ * .signal(1.0, () => console.log("1 second reached!"))
21662
+ * .signal(3.5, () => console.log("halfway!"), { emitOnce: true })
21663
+ * .install(director);
21664
+ * ```
21665
+ */
21666
+ signal(time: number, callback: Function, options?: SignalMarkerOptions): this;
21667
+ /**
21668
+ * Mutes the current track so it is skipped during playback.
21669
+ */
21670
+ muted(muted?: boolean): this;
21671
+ /** Adds an animation track descriptor for an Object3D's position or scale to the current animation track */
21672
+ track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): this;
21673
+ /** Adds an animation track descriptor for an Object3D's quaternion to the current animation track */
21674
+ track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): this;
21675
+ /** Adds an animation track descriptor for an Object3D's rotation (Euler, converted to quaternion) to the current animation track */
21676
+ track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): this;
21677
+ /** Adds an animation track descriptor for an Object3D's visibility to the current animation track */
21678
+ track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): this;
21679
+ /** Adds an animation track descriptor for a material's numeric property to the current animation track */
21680
+ track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): this;
21681
+ /** Adds an animation track descriptor for a material's color property to the current animation track */
21682
+ track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
21683
+ /** Adds an animation track descriptor for a light's numeric property to the current animation track */
21684
+ track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): this;
21685
+ /** Adds an animation track descriptor for a light's color to the current animation track */
21686
+ track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
21687
+ /** Adds an animation track descriptor for a camera's numeric property to the current animation track */
21688
+ track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): this;
21689
+ /**
21690
+ * Builds and returns the {@link TimelineAssetModel}.
21691
+ * Assign the result to `PlayableDirector.playableAsset` to play it.
21692
+ *
21693
+ * If you used `.signal()` with callbacks, use {@link install} instead — it calls `build()`
21694
+ * internally and also wires up the SignalReceiver on the director's GameObject.
21695
+ */
21696
+ build(): TimelineAssetModel;
21697
+ /**
21698
+ * Builds the timeline asset, assigns it to the director, and wires up any
21699
+ * `.signal()` callbacks by creating/configuring a {@link SignalReceiver} on the
21700
+ * director's GameObject.
21701
+ *
21702
+ * @param director - The PlayableDirector to install the timeline on
21703
+ * @returns The built TimelineAssetModel (also assigned to `director.playableAsset`)
21704
+ *
21705
+ * @example
21706
+ * ```ts
21707
+ * TimelineBuilder.create("MyTimeline")
21708
+ * .animationTrack("Anim", animator)
21709
+ * .clip(walkClip, { duration: 2 })
21710
+ * .signalTrack("Events")
21711
+ * .signal(1.0, () => console.log("signal fired!"))
21712
+ * .install(director);
21713
+ *
21714
+ * director.play();
21715
+ * ```
21716
+ */
21717
+ install(director: PlayableDirector): TimelineAssetModel;
21718
+ private pushTrack;
21719
+ /** Commits any pending `.track()` descriptors on the current animation track into a clip */
21720
+ private commitInlineTracks;
21721
+ }
21722
+
21723
+ /**
21724
+ * Shared methods available on all track builders and the TimelineBuilder entry point.
21725
+ * Provides track creation, build, and install methods.
21726
+ *
21727
+ * @category Animation and Sequencing
21728
+ */
21729
+ export declare interface TimelineBuilderBase {
21730
+ /** Adds an animation track. Chain `.clip()` or `.track()` to add content. */
21731
+ animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
21732
+ /** Adds an audio track. Chain `.clip()` to add audio clips. */
21733
+ audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
21734
+ /** Adds an activation track. Chain `.clip()` to define activation windows. */
21735
+ activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
21736
+ /** Adds a control track. Chain `.clip()` to control nested objects/timelines. */
21737
+ controlTrack(name: string): ControlTrackBuilder;
21738
+ /** Adds a signal track. Chain `.signal()` or `.marker()` to add events. */
21739
+ signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
21740
+ /** Adds a marker track. Chain `.marker()` to add markers. */
21741
+ markerTrack(name: string): MarkerTrackBuilder;
21742
+ /** Builds and returns the {@link TimelineAssetModel}. */
21743
+ build(): TimelineAssetModel;
21744
+ /** Builds the timeline, assigns it to the director, and wires up signal callbacks. */
21745
+ install(director: PlayableDirector): TimelineAssetModel;
21746
+ }
21747
+
21748
+ export declare class TimelineControlTrack extends TimelineTrackHandler {
21749
+ models: Array<Models.ClipModel>;
21750
+ timelines: Array<PlayableDirector | null>;
21751
+ resolveSourceObjects(_context: Context): void;
21752
+ private _previousActiveModel;
21753
+ evaluate(time: number): void;
21754
+ }
21755
+
21756
+ export declare class TimelineMarkerTrack extends TimelineTrackHandler {
21757
+ models: Array<Models.MarkerModel & Record<string, any>>;
21758
+ needsSorting: boolean;
21759
+ foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
21760
+ onEnable(): void;
21761
+ evaluate(_time: number): void;
21762
+ private sort;
21763
+ }
21764
+
21765
+ /**
21766
+ * A TrackHandler is responsible for evaluating a specific type of timeline track.
21767
+ * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
21768
+ */
21769
+ export declare abstract class TimelineTrackHandler {
21770
+ director: PlayableDirector;
21771
+ track: Models.TrackModel;
21772
+ get muted(): boolean;
21773
+ set muted(val: boolean);
21774
+ forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
21775
+ onEnable?(): any;
21776
+ onDisable?(): any;
21777
+ onDestroy?(): any;
21778
+ abstract evaluate(time: number): any;
21779
+ onMuteChanged?(): any;
21780
+ onPauseChanged?(): any;
21781
+ /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
21782
+ onStateChanged?(isPlaying: boolean): any;
21783
+ getClipTime(time: number, model: Models.ClipModel): number;
21784
+ getClipTimeNormalized(time: number, model: Models.ClipModel): number;
21785
+ evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
21786
+ }
21787
+
20683
21788
  declare type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
20684
21789
 
20685
21790
  /**
@@ -20708,27 +21813,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
20708
21813
  export declare function toSourceId(src: string | null): SourceIdentifier | undefined;
20709
21814
 
20710
21815
  /**
20711
- * A TrackHandler is responsible for evaluating a specific type of timeline track.
20712
- * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
21816
+ * An opaque descriptor for a single animation track.
21817
+ * Created by {@link track} and resolved into a Three.js KeyframeTrack
21818
+ * when passed to {@link createAnimation}, or inline to
21819
+ * {@link AnimatorControllerBuilder.state} / {@link TimelineBuilder.clip}.
21820
+ *
21821
+ * @category Animation and Sequencing
20713
21822
  */
20714
- export declare abstract class TrackHandler {
20715
- director: PlayableDirector;
20716
- track: Models.TrackModel;
20717
- get muted(): boolean;
20718
- set muted(val: boolean);
20719
- forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
20720
- onEnable?(): any;
20721
- onDisable?(): any;
20722
- onDestroy?(): any;
20723
- abstract evaluate(time: number): any;
20724
- onMuteChanged?(): any;
20725
- onPauseChanged?(): any;
20726
- /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
20727
- onStateChanged?(isPlaying: boolean): any;
20728
- getClipTime(time: number, model: Models.ClipModel): number;
20729
- getClipTimeNormalized(time: number, model: Models.ClipModel): number;
20730
- evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
20731
- }
21823
+ declare type TrackDescriptor = {
21824
+ readonly __isTrackDescriptor: true;
21825
+ /* Excluded from this release type: _target */
21826
+ /* Excluded from this release type: _property */
21827
+ /* Excluded from this release type: _keyframes */
21828
+ /* Excluded from this release type: _root */
21829
+ };
20732
21830
 
20733
21831
  /**
20734
21832
  * @category Animation and Sequencing
@@ -20754,14 +21852,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
20754
21852
  rotation: Quat | Quaternion;
20755
21853
  };
20756
21854
 
21855
+ /** Options for a single track */
21856
+ declare type TrackOptions = {
21857
+ /**
21858
+ * Root object for resolving the track path.
21859
+ * - If `root === target` → self-targeting (`.property`)
21860
+ * - If `root !== target` → named targeting (`"targetName.property"` using `target.name`)
21861
+ * - If omitted → self-targeting by default
21862
+ */
21863
+ root?: Object3D;
21864
+ };
21865
+
20757
21866
  declare namespace Tracks {
20758
21867
  export {
20759
- TrackHandler,
20760
- AnimationTrackHandler,
20761
- AudioTrackHandler,
20762
- MarkerTrackHandler,
21868
+ TimelineTrackHandler,
21869
+ TimelineAnimationTrack,
21870
+ TimelineAudioTrack,
21871
+ TimelineMarkerTrack,
20763
21872
  SignalTrackHandler,
20764
- ControlTrackHandler
21873
+ TimelineActivationTrack,
21874
+ TimelineControlTrack
20765
21875
  }
20766
21876
  }
20767
21877
 
@@ -20967,10 +22077,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
20967
22077
  export declare type TransitionOptions = {
20968
22078
  /** Duration of the crossfade in seconds (default: 0) */
20969
22079
  duration?: number;
20970
- /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
22080
+ /** Normalized exit time 0-1. When set, the transition waits until the source animation reaches this point before transitioning. */
20971
22081
  exitTime?: number;
20972
- /** Whether the transition waits for exitTime before transitioning (default: false) */
20973
- hasExitTime?: boolean;
20974
22082
  /** Normalized offset into the destination state's animation (default: 0) */
20975
22083
  offset?: number;
20976
22084
  /** Whether duration is in seconds (true) or normalized (false) (default: false) */
@@ -21040,6 +22148,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
21040
22148
 
21041
22149
  export declare function tryGetGuid(obj: any): string | undefined | null;
21042
22150
 
22151
+ /** Shorthand for a simple two-keyframe animation (start → end) */
22152
+ export declare type Tween<V> = {
22153
+ /** Start value (at time 0) */
22154
+ from: V;
22155
+ /** End value (at time = duration) */
22156
+ to: V;
22157
+ /** Duration in seconds (default: 1) */
22158
+ duration?: number;
22159
+ /** Interpolation mode (default: `"linear"`) */
22160
+ interpolation?: AnimationInterpolation;
22161
+ };
22162
+
21043
22163
  declare type Type = new (...args: any[]) => any;
21044
22164
 
21045
22165
  declare type TypeResolver<T> = (data: any) => Constructor<T> | null;
@@ -21563,6 +22683,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
21563
22683
  z: number;
21564
22684
  };
21565
22685
 
22686
+ /** A Vector3 value, either as a Three.js Vector3 or as a `[x, y, z]` tuple */
22687
+ declare type Vec3Value = Vector3 | [number, number, number];
22688
+
21566
22689
  export declare type Vec4 = {
21567
22690
  x: number;
21568
22691
  y: number;
@@ -22484,7 +23607,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
22484
23607
  private onApplyPose;
22485
23608
  }
22486
23609
 
22487
- declare type WebsocketSendType = IModel | object | boolean | null | string | number;
23610
+ declare type WebsocketSendType = IModel | object | boolean | string | number;
22488
23611
 
22489
23612
  /**
22490
23613
  * Use the [WebXR](https://engine.needle.tools/docs/api/WebXR) component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
@@ -22878,6 +24001,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
22878
24001
  * @link https://github.com/immersive-web/marker-tracking/blob/main/explainer.md - WebXR Marker Tracking Specification
22879
24002
  */
22880
24003
  export declare class WebXRImageTracking extends Component {
24004
+ /**
24005
+ * Event invoked every frame when images are being tracked.
24006
+ * @example
24007
+ * ```ts
24008
+ * const tracker = this.gameObject.getComponent(WebXRImageTracking);
24009
+ * tracker?.imageTracked.addEventListener(evt => {
24010
+ * for (const img of evt.trackedImages) {
24011
+ * console.log(img.url, img.state);
24012
+ * }
24013
+ * });
24014
+ * ```
24015
+ */
24016
+ imageTracked: EventList<WebXRImageTrackingEvent>;
24017
+ /** @inheritdoc */
24018
+ addEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
24019
+ addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
24020
+ /** @inheritdoc */
24021
+ removeEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
24022
+ removeEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
22881
24023
  /**
22882
24024
  * Set which marker should be primary (first in the list).
22883
24025
  * Useful when deploying to QuickLook mode where one marker is tracked at a time.
@@ -22964,6 +24106,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
22964
24106
  private onImageTrackingUpdate;
22965
24107
  }
22966
24108
 
24109
+ /** Data passed to image tracking event listeners. */
24110
+ export declare interface WebXRImageTrackingEvent {
24111
+ /** The images currently being tracked this frame. */
24112
+ readonly trackedImages: readonly WebXRTrackedImage[];
24113
+ }
24114
+
24115
+ /** Event map for {@link WebXRImageTracking} events. Use with `addEventListener` for typed event handling. */
24116
+ export declare interface WebXRImageTrackingEventMap {
24117
+ /** Dispatched every frame when images are being tracked. The event detail contains the tracking data for the current frame. */
24118
+ "image-tracking": CustomEvent<WebXRImageTrackingEvent>;
24119
+ }
24120
+
22967
24121
  /**
22968
24122
  * Configuration model for a tracked image marker.
22969
24123
  * Defines which image to track, its physical size, and which 3D content to display when detected.
@@ -23162,8 +24316,39 @@ export declare class OrbitControls extends Component implements ICameraControlle
23162
24316
  get widthInMeters(): number;
23163
24317
  /** The ImageBitmap used for tracking */
23164
24318
  get bitmap(): ImageBitmap;
23165
- /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
24319
+ /**
24320
+ * The {@link WebXRImageTrackingModel} configuration for this tracked image.
24321
+ * Use this to access the assigned 3D object, marker settings, and other image tracking configuration.
24322
+ * Available on each {@link WebXRTrackedImage} received from the `image-tracking` {@link CustomEvent} (`event.detail`).
24323
+ * @example
24324
+ * ```ts
24325
+ * tracker.addEventListener("image-tracking", event => {
24326
+ * for (const img of event.detail.trackedImages) {
24327
+ * const model = img.model;
24328
+ * // Access the assigned 3D object
24329
+ * const obj = model.object;
24330
+ * // Access other settings
24331
+ * console.log(model.widthInMeters, model.hideWhenTrackingIsLost);
24332
+ * }
24333
+ * });
24334
+ * ```
24335
+ */
23166
24336
  get model(): WebXRImageTrackingModel;
24337
+ /**
24338
+ * The 3D object or prefab assigned to this tracked image marker in the {@link WebXRImageTrackingModel}.
24339
+ * Use this to access the object associated with an AR image tracking marker from the `image-tracking` {@link CustomEvent}.
24340
+ * Shorthand for `this.model.object`.
24341
+ * @example
24342
+ * ```ts
24343
+ * tracker.addEventListener("image-tracking", event => {
24344
+ * for (const img of event.detail.trackedImages) {
24345
+ * const obj = img.trackedModel;
24346
+ * // verbose alternative: img.model.object
24347
+ * }
24348
+ * });
24349
+ * ```
24350
+ */
24351
+ get trackedModel(): AssetReference | undefined;
23167
24352
  /**
23168
24353
  * The measured size of the detected image in the real world.
23169
24354
  * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
@@ -23528,23 +24713,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
23528
24713
 
23529
24714
 
23530
24715
  declare module 'three' {
23531
- interface SkinnedMesh {
23532
- staticGenerator?: StaticGeometryGenerator;
23533
- staticGeometry?: BufferGeometry;
23534
- staticGeometryLastUpdate?: number;
23535
- }
23536
- interface Mesh {
23537
- acceleratedRaycast?: any;
23538
- }
23539
- interface SkinnedMesh {
23540
- /** @deprecated use autoUpdateMeshBvhInterval */
23541
- autoUpdateMeshBVH?: boolean;
23542
- /**
23543
- * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
23544
- * @default undefined (disabled)
23545
- */
23546
- autoUpdateMeshBvhInterval?: number;
23547
- bvhNeedsUpdate?: boolean;
24716
+ interface Vector3 {
24717
+ slerp(end: Vector3, t: number): Vector3;
23548
24718
  }
23549
24719
  }
23550
24720
 
@@ -23690,7 +24860,22 @@ declare module 'three' {
23690
24860
 
23691
24861
 
23692
24862
  declare module 'three' {
23693
- interface Vector3 {
23694
- slerp(end: Vector3, t: number): Vector3;
24863
+ interface SkinnedMesh {
24864
+ staticGenerator?: StaticGeometryGenerator;
24865
+ staticGeometry?: BufferGeometry;
24866
+ staticGeometryLastUpdate?: number;
24867
+ }
24868
+ interface Mesh {
24869
+ acceleratedRaycast?: any;
24870
+ }
24871
+ interface SkinnedMesh {
24872
+ /** @deprecated use autoUpdateMeshBvhInterval */
24873
+ autoUpdateMeshBVH?: boolean;
24874
+ /**
24875
+ * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
24876
+ * @default undefined (disabled)
24877
+ */
24878
+ autoUpdateMeshBvhInterval?: number;
24879
+ bvhNeedsUpdate?: boolean;
23695
24880
  }
23696
24881
  }