@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
package/src/engine/api.ts CHANGED
@@ -114,6 +114,9 @@ export * from "./engine_addressables.js";
114
114
  /** Animation playback and control utilities */
115
115
  export { AnimationUtils } from "./engine_animation.js";
116
116
 
117
+ /** Standalone audio clip for playback control */
118
+ export { AudioClip } from "./engine_audio.js";
119
+
117
120
  /** Application-level state and utilities */
118
121
  export { Application } from "./engine_application.js";
119
122
 
@@ -164,6 +167,9 @@ export * from "./engine_constants.js";
164
167
  */
165
168
  export * from "./engine_context.js";
166
169
 
170
+ /** Typed event bus for decoupled component communication via {@link Context.events} */
171
+ export * from "./engine_context_eventbus.js";
172
+
167
173
  /** Registry for managing multiple engine contexts */
168
174
  export * from "./engine_context_registry.js";
169
175
 
@@ -173,6 +179,10 @@ export * from "./engine_context_registry.js";
173
179
  */
174
180
  export * from "./engine_coroutine.js"
175
181
 
182
+ /** DisposableStore for managing lifecycle-bound cleanup in components */
183
+ export { DisposableStore, on, isDisposable } from "./engine_disposable.js";
184
+ export type { DisposeFn, IDisposable } from "./engine_disposable.js";
185
+
176
186
  /** Factory functions for creating primitives and objects */
177
187
  export * from "./engine_create_objects.js";
178
188
 
@@ -220,7 +230,7 @@ export * from "./engine_input.js";
220
230
  export { InstancingUtil } from "./engine_instancing.js";
221
231
 
222
232
  /** License checking utilities */
223
- export { hasCommercialLicense, hasIndieLicense, hasProLicense } from "./engine_license.js";
233
+ export { _$LVgA, lHSx, _kRatU } from "./engine_license.js";
224
234
 
225
235
 
226
236
  // ============================================================================
@@ -7,11 +7,6 @@ import { Animation } from "../../engine-components/Animation.js";
7
7
  import { Animator } from "../../engine-components/Animator.js";
8
8
  import { AudioListener } from "../../engine-components/AudioListener.js";
9
9
  import { AudioSource } from "../../engine-components/AudioSource.js";
10
- import { Avatar_Brain_LookAt } from "../../engine-components/avatar/Avatar_Brain_LookAt.js";
11
- import { Avatar_MouthShapes } from "../../engine-components/avatar/Avatar_MouthShapes.js";
12
- import { Avatar_MustacheShake } from "../../engine-components/avatar/Avatar_MustacheShake.js";
13
- import { AvatarBlink_Simple } from "../../engine-components/avatar/AvatarBlink_Simple.js";
14
- import { AvatarEyeLook_Rotation } from "../../engine-components/avatar/AvatarEyeLook_Rotation.js";
15
10
  import { AxesHelper } from "../../engine-components/AxesHelper.js";
16
11
  import { BasicIKConstraint } from "../../engine-components/BasicIKConstraint.js";
17
12
  import { BoxHelperComponent } from "../../engine-components/BoxHelperComponent.js";
@@ -106,11 +101,12 @@ import { TestRunner } from "../../engine-components/TestRunner.js";
106
101
  import { TestSimulateUserData } from "../../engine-components/TestRunner.js";
107
102
  import { PlayableDirector } from "../../engine-components/timeline/PlayableDirector.js";
108
103
  import { SignalReceiver } from "../../engine-components/timeline/SignalAsset.js";
109
- import { AnimationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
110
- import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
111
- import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
104
+ import { TimelineAnimationTrack } from "../../engine-components/timeline/TimelineTracks.js";
105
+ import { TimelineAudioTrack } from "../../engine-components/timeline/TimelineTracks.js";
106
+ import { TimelineMarkerTrack } from "../../engine-components/timeline/TimelineTracks.js";
112
107
  import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
113
- import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
108
+ import { TimelineActivationTrack } from "../../engine-components/timeline/TimelineTracks.js";
109
+ import { TimelineControlTrack } from "../../engine-components/timeline/TimelineTracks.js";
114
110
  import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
115
111
  import { BaseUIComponent } from "../../engine-components/ui/BaseUIComponent.js";
116
112
  import { UIRootComponent } from "../../engine-components/ui/BaseUIComponent.js";
@@ -167,11 +163,6 @@ export function initBuiltinTypes() {
167
163
  TypeStore.add("Animator", Animator);
168
164
  TypeStore.add("AudioListener", AudioListener);
169
165
  TypeStore.add("AudioSource", AudioSource);
170
- TypeStore.add("Avatar_Brain_LookAt", Avatar_Brain_LookAt);
171
- TypeStore.add("Avatar_MouthShapes", Avatar_MouthShapes);
172
- TypeStore.add("Avatar_MustacheShake", Avatar_MustacheShake);
173
- TypeStore.add("AvatarBlink_Simple", AvatarBlink_Simple);
174
- TypeStore.add("AvatarEyeLook_Rotation", AvatarEyeLook_Rotation);
175
166
  TypeStore.add("AxesHelper", AxesHelper);
176
167
  TypeStore.add("BasicIKConstraint", BasicIKConstraint);
177
168
  TypeStore.add("BoxHelperComponent", BoxHelperComponent);
@@ -266,11 +257,12 @@ export function initBuiltinTypes() {
266
257
  TypeStore.add("TestSimulateUserData", TestSimulateUserData);
267
258
  TypeStore.add("PlayableDirector", PlayableDirector);
268
259
  TypeStore.add("SignalReceiver", SignalReceiver);
269
- TypeStore.add("AnimationTrackHandler", AnimationTrackHandler);
270
- TypeStore.add("AudioTrackHandler", AudioTrackHandler);
271
- TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
260
+ TypeStore.add("TimelineAnimationTrack", TimelineAnimationTrack);
261
+ TypeStore.add("TimelineAudioTrack", TimelineAudioTrack);
262
+ TypeStore.add("TimelineMarkerTrack", TimelineMarkerTrack);
272
263
  TypeStore.add("SignalTrackHandler", SignalTrackHandler);
273
- TypeStore.add("ControlTrackHandler", ControlTrackHandler);
264
+ TypeStore.add("TimelineActivationTrack", TimelineActivationTrack);
265
+ TypeStore.add("TimelineControlTrack", TimelineControlTrack);
274
266
  TypeStore.add("TransformGizmo", TransformGizmo);
275
267
  TypeStore.add("BaseUIComponent", BaseUIComponent);
276
268
  TypeStore.add("UIRootComponent", UIRootComponent);
@@ -12,13 +12,16 @@ import { onError } from "./debug_overlay.js";
12
12
 
13
13
  let _isActive = false;
14
14
 
15
- // enable the spatial console if we receive an error while in dev session and in XR
16
- onError((...args: any[]) => {
17
- if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
18
- enableSpatialConsole(true);
19
- onLog("error", ...args);
20
- }
21
- })
15
+ /** @internal */
16
+ export function initSpatialConsole() {
17
+ // enable the spatial console if we receive an error while in dev session and in XR
18
+ onError((...args: any[]) => {
19
+ if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
20
+ enableSpatialConsole(true);
21
+ onLog("error", ...args);
22
+ }
23
+ });
24
+ }
22
25
 
23
26
 
24
27
  /** Enable a spatial debug console that follows the camera */
@@ -567,7 +567,6 @@ class AddressableSerializer extends TypeSerializer {
567
567
  }
568
568
 
569
569
  }
570
- new AddressableSerializer();
571
570
 
572
571
 
573
572
 
@@ -703,7 +702,6 @@ export class ImageReferenceSerializer extends TypeSerializer {
703
702
  return undefined;
704
703
  }
705
704
  }
706
- new ImageReferenceSerializer();
707
705
 
708
706
 
709
707
 
@@ -772,4 +770,9 @@ export class FileReferenceSerializer extends TypeSerializer {
772
770
  return undefined;
773
771
  }
774
772
  }
775
- new FileReferenceSerializer();
773
+ /** @internal */
774
+ export function initAddressableSerializers() {
775
+ new AddressableSerializer();
776
+ new ImageReferenceSerializer();
777
+ new FileReferenceSerializer();
778
+ }
@@ -21,4 +21,188 @@ export function ensureAudioContextIsResumed() {
21
21
  }, 500);
22
22
  });
23
23
  });
24
+ }
25
+
26
+
27
+ /**
28
+ * Represents an audio clip that can be loaded and played independently.
29
+ * The AudioClip class encapsulates the URL of the audio resource and provides
30
+ * methods for playback control (play, pause, stop) and querying duration.
31
+ */
32
+ export class AudioClip {
33
+
34
+ /**
35
+ * Creates a new AudioClip instance with the specified URL.
36
+ * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
37
+ */
38
+ constructor(public readonly url: string) {
39
+ }
40
+
41
+ /** Whether the clip is currently playing.
42
+ * @returns `true` if the clip is actively playing audio.
43
+ */
44
+ get isPlaying(): boolean {
45
+ return this._audioElement !== undefined
46
+ && !this._audioElement.paused
47
+ && !this._audioElement.ended;
48
+ }
49
+
50
+ /**
51
+ * The total duration of the audio clip in seconds.
52
+ * Loads the audio metadata if not already available.
53
+ * @returns A promise that resolves with the duration in seconds.
54
+ */
55
+ getDuration(): Promise<number> {
56
+ if (this._duration !== undefined) {
57
+ return Promise.resolve(this._duration);
58
+ }
59
+ return this.ensureAudioElement().then(audio => {
60
+ this._duration = audio.duration;
61
+ return audio.duration;
62
+ });
63
+ }
64
+
65
+ /**
66
+ * Plays the audio clip from the current position.
67
+ * @returns A promise that resolves when playback finishes, or rejects on error.
68
+ * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
69
+ */
70
+ // #region Play
71
+ play(): Promise<void> {
72
+ return this.ensureAudioElement().then(audio => {
73
+ return new Promise<void>((resolve, reject) => {
74
+ const onEnded = () => {
75
+ cleanup();
76
+ resolve();
77
+ };
78
+ const onError = () => {
79
+ cleanup();
80
+ reject(new Error(`Playback error for ${this.url}`));
81
+ };
82
+ const onPause = () => {
83
+ // pause/stop also resolve the promise
84
+ cleanup();
85
+ resolve();
86
+ };
87
+ const cleanup = () => {
88
+ audio.removeEventListener("ended", onEnded);
89
+ audio.removeEventListener("error", onError);
90
+ audio.removeEventListener("pause", onPause);
91
+ };
92
+ audio.addEventListener("ended", onEnded);
93
+ audio.addEventListener("error", onError);
94
+ audio.addEventListener("pause", onPause);
95
+ audio.play().catch(err => {
96
+ cleanup();
97
+ reject(err);
98
+ });
99
+ });
100
+ });
101
+ }
102
+
103
+ /**
104
+ * Pauses playback at the current position.
105
+ * Call {@link play} to resume.
106
+ */
107
+ // #region Pause/Stop
108
+ pause(): void {
109
+ this._audioElement?.pause();
110
+ }
111
+
112
+ /**
113
+ * Stops playback and resets the position to the beginning.
114
+ */
115
+ stop(): void {
116
+ if (this._audioElement) {
117
+ this._audioElement.pause();
118
+ this._audioElement.currentTime = 0;
119
+ }
120
+ }
121
+
122
+ /** Whether the clip should loop when reaching the end. */
123
+ get loop(): boolean { return this._loop; }
124
+ set loop(value: boolean) {
125
+ this._loop = value;
126
+ if (this._audioElement) this._audioElement.loop = value;
127
+ }
128
+
129
+ /** Playback volume from 0 (silent) to 1 (full). */
130
+ get volume(): number { return this._volume; }
131
+ set volume(value: number) {
132
+ this._volume = value;
133
+ if (this._audioElement) this._audioElement.volume = value;
134
+ }
135
+
136
+ /** Current playback position in seconds. */
137
+ get currentTime(): number { return this._audioElement?.currentTime ?? 0; }
138
+ set currentTime(value: number) {
139
+ if (this._audioElement) this._audioElement.currentTime = value;
140
+ }
141
+
142
+ /** Normalized playback progress from 0 to 1.
143
+ * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
144
+ */
145
+ get progress(): number {
146
+ if (!this._audioElement || !this._duration) return 0;
147
+ return this._audioElement.currentTime / this._duration;
148
+ }
149
+
150
+ /**
151
+ * Seeks to a normalized position (0–1) in the clip.
152
+ * @param position A value between 0 (start) and 1 (end).
153
+ */
154
+ // #region Seek
155
+ seek(position: number): void {
156
+ if (this._audioElement && this._duration) {
157
+ this._audioElement.currentTime = Math.max(0, Math.min(1, position)) * this._duration;
158
+ }
159
+ }
160
+
161
+ /** The underlying HTMLAudioElement, or `undefined` if not yet created.
162
+ * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
163
+ * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
164
+ */
165
+ get audioElement(): HTMLAudioElement | undefined { return this._audioElement; }
166
+
167
+ private _audioElement?: HTMLAudioElement;
168
+ private _duration?: number;
169
+ private _loadPromise?: Promise<HTMLAudioElement>;
170
+ private _loop: boolean = false;
171
+ private _volume: number = 1;
172
+
173
+ /** Lazily creates and loads the shared HTMLAudioElement. */
174
+ private ensureAudioElement(): Promise<HTMLAudioElement> {
175
+ if (this._audioElement && this._loadPromise) {
176
+ return this._loadPromise;
177
+ }
178
+ const audio = this._audioElement ?? new Audio(this.url);
179
+ this._audioElement = audio;
180
+ audio.loop = this._loop;
181
+ audio.volume = this._volume;
182
+
183
+ if (audio.readyState >= HTMLMediaElement.HAVE_METADATA) {
184
+ this._duration = audio.duration;
185
+ this._loadPromise = Promise.resolve(audio);
186
+ return this._loadPromise;
187
+ }
188
+
189
+ this._loadPromise = new Promise<HTMLAudioElement>((resolve, reject) => {
190
+ const onLoaded = () => {
191
+ cleanup();
192
+ this._duration = audio.duration;
193
+ resolve(audio);
194
+ };
195
+ const onError = (e: Event) => {
196
+ cleanup();
197
+ reject(new Error(`Failed to load audio clip from ${this.url}: ${e}`));
198
+ };
199
+ const cleanup = () => {
200
+ audio.removeEventListener("loadedmetadata", onLoaded);
201
+ audio.removeEventListener("error", onError);
202
+ };
203
+ audio.addEventListener("loadedmetadata", onLoaded);
204
+ audio.addEventListener("error", onError);
205
+ });
206
+ return this._loadPromise;
207
+ }
24
208
  }
@@ -257,12 +257,23 @@ export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnTyp
257
257
  else {
258
258
  direction.sub(camera.worldPosition);
259
259
  }
260
- if (centerCamera === "y")
261
- direction.y = 0;
260
+ if (centerCamera === "y") {
261
+ // Preserve the camera's current elevation angle when it's already above the center,
262
+ // but clamp to a minimum elevation to prevent the camera from ending up at or below
263
+ // the scene center (which causes a "looking up from below" effect).
264
+ // direction points FROM camera TO center, so negative Y = camera is above center.
265
+ const horizontalLen = Math.sqrt(direction.x * direction.x + direction.z * direction.z);
266
+ if (horizontalLen > 0.0001) {
267
+ const minY = -horizontalLen * verticalOffset * 4;
268
+ if (direction.y > minY) direction.y = minY;
269
+ }
270
+ else {
271
+ // Camera is directly above/below center — pick a default slight angle from +Z
272
+ direction.set(0, -verticalOffset * 4, 1);
273
+ }
274
+ }
262
275
  direction.normalize();
263
276
  direction.multiplyScalar(distance);
264
- if (centerCamera === "y")
265
- direction.y += -verticalOffset * 4 * distance;
266
277
 
267
278
  let cameraLocalPosition = center.clone().sub(direction);
268
279
  if (options.cameraOffset) {
@@ -8,9 +8,9 @@ import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
8
8
  import { Context, registerComponent } from "./engine_setup.js";
9
9
  import type { ComponentInit, Constructor, ConstructorConcrete, IComponent, IGameObject } from "./engine_types.js";
10
10
  import { $componentName } from "./engine_types.js";
11
+ import { TypeStore } from "./engine_typestore.js";
11
12
  import { getParam } from "./engine_utils.js";
12
13
  import { apply } from "./js-extensions/index.js";
13
- import { TypeStore } from "./engine_typestore.js";
14
14
 
15
15
  const COMPONENT_GUID_NAMESPACE = 'eff8ba80-635d-11ec-90d6-0242ac120003';
16
16
 
@@ -1,5 +1,6 @@
1
1
  import 'three/examples/jsm/renderers/webgl-legacy/nodes/WebGLNodes.js';
2
2
 
3
+ import type { SceneData } from 'needle-bindings';
3
4
  import type { EffectComposer } from "postprocessing";
4
5
  import {
5
6
  BufferGeometry, Camera, Color, DepthTexture, Group,
@@ -22,6 +23,7 @@ import { Application } from './engine_application.js';
22
23
  import { AssetDatabase } from './engine_assetdatabase.js';
23
24
  import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
24
25
  import { VERSION } from './engine_constants.js';
26
+ import { EventBus } from './engine_context_eventbus.js';
25
27
  import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
26
28
  import { WaitForPromise } from './engine_coroutine.js';
27
29
  import { ObjectUtils } from "./engine_create_objects.js";
@@ -36,9 +38,8 @@ import * as looputils from './engine_mainloop_utils.js';
36
38
  import { NetworkConnection } from './engine_networking.js';
37
39
  import { Physics } from './engine_physics.js';
38
40
  import { PlayerViewManager } from './engine_playerview.js';
39
- import { RendererData as SceneLighting } from './engine_scenelighting.js';
40
41
  import { getSceneData } from './engine_scenedata.js';
41
- import type { SceneData } from 'needle-bindings';
42
+ import { RendererData as SceneLighting } from './engine_scenelighting.js';
42
43
  import { getTempColor, logHierarchy } from './engine_three_utils.js';
43
44
  import { Time } from './engine_time.js';
44
45
  import { patchTonemapping } from './engine_tonemapping.js';
@@ -151,7 +152,7 @@ export function registerComponent(script: IComponent, context?: Context) {
151
152
  }
152
153
 
153
154
  /**
154
- * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
155
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
155
156
  * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
156
157
  *
157
158
  * The context is automatically created when using the `<needle-engine>` web component.
@@ -478,13 +479,14 @@ export class Context implements IContext {
478
479
  * Use `setCurrentCamera` for updating the main camera.
479
480
  */
480
481
  /**
481
- * Typed proxy providing direct access to scene components by node and component name.
482
- * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
483
- * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
482
+ * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
483
+ * Types are generated automatically from your GLB files when the dev server starts.
484
484
  *
485
- * Each property access traverses the live scene graph on demand — no caching, always fresh.
486
- * This is a convenience shorthand for `getComponent` lookups; the same result can be
487
- * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
485
+ * You can store references to objects or components for later use.
486
+ * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
487
+ * in which case stored references may become stale.
488
+ *
489
+ * @experimental This API may change in future versions.
488
490
  *
489
491
  * @example
490
492
  * // Toggle auto-rotate on the orbit camera
@@ -493,12 +495,6 @@ export class Context implements IContext {
493
495
  * @example
494
496
  * // Change the background color
495
497
  * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
496
- *
497
- * @example
498
- * // Equivalent manual approach (without sceneData)
499
- * const node = ctx.scene.getObjectByName("Camera");
500
- * const orbit = getComponent(node, OrbitControls);
501
- * if (orbit) orbit.autoRotate = true;
502
498
  */
503
499
  get sceneData(): SceneData {
504
500
  return getSceneData(this);
@@ -527,24 +523,38 @@ export class Context implements IContext {
527
523
  private _fallbackCamera: PerspectiveCamera | null = null;
528
524
 
529
525
  /** access application state (e.g. if all audio should be muted) */
530
- application: Application;
526
+ get application(): Application { return this._application; }
527
+ private _application!: Application;
531
528
  /** access animation mixer used by components in the scene */
532
- animations: AnimationsRegistry;
529
+ get animations(): AnimationsRegistry { return this._animations; }
530
+ private _animations!: AnimationsRegistry;
533
531
  /** access timings (current frame number, deltaTime, timeScale, ...) */
534
- time: Time;
532
+ get time(): Time { return this._time; }
533
+ private _time!: Time;
535
534
  /** access input data (e.g. click or touch events) */
536
- input: Input;
535
+ get input(): Input { return this._input; }
536
+ private _input!: Input;
537
537
  /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
538
- physics: Physics;
538
+ get physics(): Physics { return this._physics; }
539
+ private _physics!: Physics;
539
540
  /** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
540
- postprocessing: PostProcessing;
541
+ get postprocessing(): PostProcessing { return this._postprocessing; }
542
+ private _postprocessing!: PostProcessing;
541
543
  /** access networking methods (use it to send or listen to messages or join a networking backend) */
542
- connection: NetworkConnection;
544
+ get connection(): NetworkConnection { return this._connection; }
545
+ private _connection!: NetworkConnection;
546
+ /** context-level event bus for decoupled component communication
547
+ * @see {@link ContextEventMap} for known event types
548
+ */
549
+ get events(): EventBus { return this._events; }
550
+ private _events = new EventBus();
543
551
  /** @deprecated AssetDatabase is deprecated */
544
552
  assets: AssetDatabase;
545
553
 
546
- /** All registered lights in the scene, maintained by the Light component */
547
- readonly lights: Set<ILight> = new Set();
554
+ /** All registered lights in the scene, maintained by the Light component.
555
+ * @see mainLight for accessing the main directional light in the scene
556
+ */
557
+ readonly lights = new Array<ILight>();
548
558
 
549
559
  /** The brightest registered directional light, or null if none are registered
550
560
  * @see lights
@@ -559,12 +569,13 @@ export class Context implements IContext {
559
569
  }
560
570
 
561
571
  /** @deprecated Use sceneLighting */
562
- get rendererData() { return this.sceneLighting }
572
+ private get rendererData() { return this.sceneLighting }
573
+
563
574
  /** Access the scene lighting manager to control lighting settings in the context */
564
- sceneLighting: SceneLighting;
565
- addressables: Addressables;
566
- lightmaps: ILightDataRegistry;
567
- players: PlayerViewManager;
575
+ readonly sceneLighting: SceneLighting;
576
+ readonly addressables: Addressables;
577
+ readonly lightmaps: ILightDataRegistry;
578
+ readonly players: PlayerViewManager;
568
579
 
569
580
  /** Access the LODs manager to control LOD behavior in the context */
570
581
  readonly lodsManager: LODsManager;
@@ -608,12 +619,12 @@ export class Context implements IContext {
608
619
  else this.scene = new Scene();
609
620
  if (args?.camera) this._mainCamera = args.camera;
610
621
 
611
- this.application = new Application(this);
612
- this.time = new Time();
613
- this.input = new Input(this);
614
- this.physics = new Physics(this);
615
- this.postprocessing = new PostProcessing(this);
616
- this.connection = new NetworkConnection(this);
622
+ this._application = new Application(this);
623
+ this._time = new Time();
624
+ this._input = new Input(this);
625
+ this._physics = new Physics(this);
626
+ this._postprocessing = new PostProcessing(this);
627
+ this._connection = new NetworkConnection(this);
617
628
  // eslint-disable-next-line @typescript-eslint/no-deprecated
618
629
  this.assets = new AssetDatabase();
619
630
  this.sceneLighting = new SceneLighting(this);
@@ -622,7 +633,7 @@ export class Context implements IContext {
622
633
  this.players = new PlayerViewManager(this);
623
634
  this.menu = new NeedleMenu(this);
624
635
  this.lodsManager = new LODsManager(this);
625
- this.animations = new AnimationsRegistry(this);
636
+ this._animations = new AnimationsRegistry(this);
626
637
  this.accessibility = new AccessibilityManager(this);
627
638
 
628
639
 
@@ -865,14 +876,16 @@ export class Context implements IContext {
865
876
  this.scene = new Scene();
866
877
  this.addressables?.dispose();
867
878
  this.lightmaps?.clear();
868
- this.physics?.engine?.clearCaches();
879
+ this.physics?.engine?.dispose();
869
880
  this.lodsManager.disable();
870
881
  this.accessibility?.clear();
871
882
 
872
883
  this._onBeforeRenderListeners.clear();
873
884
  this._onAfterRenderListeners.clear();
885
+ this._events.clear();
886
+ this._events = new EventBus();
874
887
 
875
- this.lights.clear();
888
+ this.lights.length = 0;
876
889
 
877
890
  if (!this.isManagedExternally) {
878
891
  if (this.renderer) {
@@ -914,6 +927,7 @@ export class Context implements IContext {
914
927
  this.scene = null!;
915
928
  this.renderer = null!;
916
929
  this.input.dispose();
930
+ this.connection.dispose();
917
931
  this.menu.onDestroy();
918
932
  this.animations.onDestroy();
919
933
  for (const cb of this._disposeCallbacks) {
@@ -1794,6 +1808,7 @@ export class Context implements IContext {
1794
1808
  ? (`${((window.performance as any).memory.usedJSHeapSize / 1024 / 1024).toFixed(2)} MB`)
1795
1809
  : "n/a";
1796
1810
 
1811
+ const gl = this.renderer.getContext();
1797
1812
  console.log(this.renderer.info.render.calls + " DrawCalls", "\nRender:",
1798
1813
  {
1799
1814
  shaders: this.renderer.info.programs?.length,
@@ -1803,7 +1818,16 @@ export class Context implements IContext {
1803
1818
  {
1804
1819
  usedMemory: usedJSHeapSize,
1805
1820
  ...this.renderer.info.memory
1806
- }, "\nTarget Framerate: " + this.targetFrameRate);
1821
+ },
1822
+ "\nRenderer:",
1823
+ {
1824
+ dpr: this.renderer.getPixelRatio(),
1825
+ windowDpr: window.devicePixelRatio,
1826
+ antialias: gl.getContextAttributes()?.antialias,
1827
+ samples: gl.getParameter(gl.SAMPLES),
1828
+ resolution: `${this.renderer.domElement.width}x${this.renderer.domElement.height}`,
1829
+ },
1830
+ "\nTarget Framerate: " + this.targetFrameRate);
1807
1831
  }
1808
1832
  }
1809
1833
 
@@ -0,0 +1,73 @@
1
+ import type { Object3D } from "three";
2
+
3
+ import type { IComponent } from "./engine_types.js";
4
+
5
+ /** Typed event map for {@link Context.events}.
6
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
7
+ */
8
+ export interface ContextEventMap {
9
+ "scene-content-changed": {
10
+ /** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
11
+ readonly source: IComponent;
12
+ /** The root object that was added/loaded */
13
+ readonly object: Object3D;
14
+ };
15
+ }
16
+
17
+ /** Options for {@link EventBus.on}. */
18
+ export interface EventBusListenerOptions {
19
+ /** If true the listener is automatically removed after the first invocation. */
20
+ once?: boolean;
21
+ }
22
+
23
+ /** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
24
+ * Custom events can be typed at the call site via generic parameter.
25
+ * @example Known events
26
+ * ```ts
27
+ * context.events.on("scene-content-changed", e => e.object);
28
+ * ```
29
+ * @example Custom events — type at call site
30
+ * ```ts
31
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
32
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
33
+ * ```
34
+ * @example Once
35
+ * ```ts
36
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
37
+ * ```
38
+ */
39
+ export class EventBus {
40
+ private _listeners = new Map<string, Function[]>();
41
+
42
+ /** Emit a known {@link ContextEventMap} event */
43
+ emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
44
+ /** Emit a custom event with user-provided type */
45
+ emit<T>(type: string, detail?: T): void;
46
+ emit(type: string, detail?: unknown): void {
47
+ const arr = this._listeners.get(type);
48
+ if (arr) for (const cb of [...arr]) cb(detail);
49
+ }
50
+
51
+ /** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
52
+ on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
53
+ /** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
54
+ on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
55
+ on(type: string, callback: Function, options?: EventBusListenerOptions): () => void {
56
+ let arr = this._listeners.get(type);
57
+ if (!arr) { arr = []; this._listeners.set(type, arr); }
58
+ const unsub = () => {
59
+ const i = arr.indexOf(wrapped);
60
+ if (i >= 0) arr.splice(i, 1);
61
+ };
62
+ const wrapped = options?.once
63
+ ? (...args: unknown[]) => { unsub(); callback(...args); }
64
+ : callback;
65
+ arr.push(wrapped);
66
+ return unsub;
67
+ }
68
+
69
+ /** Remove all listeners. Called when the context is cleared or destroyed. */
70
+ clear(): void {
71
+ this._listeners.clear();
72
+ }
73
+ }