@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.
- package/CHANGELOG.md +120 -0
- package/SKILL.md +4 -1
- package/components.needle.json +1 -1
- package/dist/{needle-engine.bundle-CDKcuALa.js → needle-engine.bundle-CAIG39cL.js} +13605 -12680
- package/dist/needle-engine.bundle-CFh_isu6.umd.cjs +1734 -0
- package/dist/needle-engine.bundle-CtadUKoi.min.js +1734 -0
- package/dist/needle-engine.d.ts +1579 -394
- package/dist/needle-engine.js +542 -538
- package/dist/needle-engine.min.js +1 -1
- package/dist/needle-engine.umd.cjs +1 -1
- package/dist/three.js +1 -0
- package/dist/three.min.js +21 -21
- package/dist/three.umd.cjs +16 -16
- package/lib/engine/api.d.ts +8 -1
- package/lib/engine/api.js +7 -1
- package/lib/engine/api.js.map +1 -1
- package/lib/engine/codegen/register_types.js +10 -18
- package/lib/engine/codegen/register_types.js.map +1 -1
- package/lib/engine/debug/debug_spatial_console.d.ts +2 -0
- package/lib/engine/debug/debug_spatial_console.js +10 -7
- package/lib/engine/debug/debug_spatial_console.js.map +1 -1
- package/lib/engine/engine_addressables.d.ts +2 -0
- package/lib/engine/engine_addressables.js +6 -3
- package/lib/engine/engine_addressables.js.map +1 -1
- package/lib/engine/engine_audio.d.ts +68 -0
- package/lib/engine/engine_audio.js +172 -0
- package/lib/engine/engine_audio.js.map +1 -1
- package/lib/engine/engine_camera.fit.js +16 -4
- package/lib/engine/engine_camera.fit.js.map +1 -1
- package/lib/engine/engine_components.js +1 -1
- package/lib/engine/engine_components.js.map +1 -1
- package/lib/engine/engine_context.d.ts +37 -27
- package/lib/engine/engine_context.js +51 -31
- package/lib/engine/engine_context.js.map +1 -1
- package/lib/engine/engine_context_eventbus.d.ts +47 -0
- package/lib/engine/engine_context_eventbus.js +47 -0
- package/lib/engine/engine_context_eventbus.js.map +1 -0
- package/lib/engine/engine_disposable.d.ts +172 -0
- package/lib/engine/engine_disposable.js +136 -0
- package/lib/engine/engine_disposable.js.map +1 -0
- package/lib/engine/engine_gameobject.d.ts +1 -10
- package/lib/engine/engine_gameobject.js +22 -120
- package/lib/engine/engine_gameobject.js.map +1 -1
- package/lib/engine/engine_gltf_builtin_components.js +7 -69
- package/lib/engine/engine_gltf_builtin_components.js.map +1 -1
- package/lib/engine/engine_init.js +14 -4
- package/lib/engine/engine_init.js.map +1 -1
- package/lib/engine/engine_input.d.ts +24 -5
- package/lib/engine/engine_input.js +3 -2
- package/lib/engine/engine_input.js.map +1 -1
- package/lib/engine/engine_instantiate_resolve.d.ts +42 -0
- package/lib/engine/engine_instantiate_resolve.js +372 -0
- package/lib/engine/engine_instantiate_resolve.js.map +1 -0
- package/lib/engine/engine_license.d.ts +7 -7
- package/lib/engine/engine_license.js +186 -58
- package/lib/engine/engine_license.js.map +1 -1
- package/lib/engine/engine_mainloop_utils.js +7 -4
- package/lib/engine/engine_mainloop_utils.js.map +1 -1
- package/lib/engine/engine_networking.d.ts +51 -37
- package/lib/engine/engine_networking.js +132 -82
- package/lib/engine/engine_networking.js.map +1 -1
- package/lib/engine/engine_networking.transport.websocket.d.ts +15 -0
- package/lib/engine/engine_networking.transport.websocket.js +38 -0
- package/lib/engine/engine_networking.transport.websocket.js.map +1 -0
- package/lib/engine/engine_networking_blob.js +4 -4
- package/lib/engine/engine_networking_blob.js.map +1 -1
- package/lib/engine/engine_networking_instantiate.js +2 -2
- package/lib/engine/engine_networking_instantiate.js.map +1 -1
- package/lib/engine/engine_networking_types.d.ts +39 -1
- package/lib/engine/engine_networking_types.js +7 -0
- package/lib/engine/engine_networking_types.js.map +1 -1
- package/lib/engine/engine_physics_rapier.d.ts +21 -3
- package/lib/engine/engine_physics_rapier.js +94 -25
- package/lib/engine/engine_physics_rapier.js.map +1 -1
- package/lib/engine/engine_scenedata.d.ts +5 -7
- package/lib/engine/engine_scenedata.js +16 -13
- package/lib/engine/engine_scenedata.js.map +1 -1
- package/lib/engine/engine_serialization_builtin_serializer.d.ts +10 -16
- package/lib/engine/engine_serialization_builtin_serializer.js +56 -46
- package/lib/engine/engine_serialization_builtin_serializer.js.map +1 -1
- package/lib/engine/engine_serialization_core.d.ts +1 -0
- package/lib/engine/engine_serialization_core.js +7 -0
- package/lib/engine/engine_serialization_core.js.map +1 -1
- package/lib/engine/engine_types.d.ts +29 -11
- package/lib/engine/engine_types.js +1 -1
- package/lib/engine/engine_types.js.map +1 -1
- package/lib/engine/engine_util_decorator.js +7 -2
- package/lib/engine/engine_util_decorator.js.map +1 -1
- package/lib/engine/engine_utils.d.ts +1 -1
- package/lib/engine/engine_utils.js +19 -5
- package/lib/engine/engine_utils.js.map +1 -1
- package/lib/engine/engine_utils_qrcode.js +2 -2
- package/lib/engine/engine_utils_qrcode.js.map +1 -1
- package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
- package/lib/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js.map +1 -1
- package/lib/engine/webcomponents/jsx.d.ts +9 -2
- package/lib/engine/webcomponents/needle menu/needle-menu-spatial.js +2 -2
- package/lib/engine/webcomponents/needle menu/needle-menu-spatial.js.map +1 -1
- package/lib/engine/webcomponents/needle menu/needle-menu.d.ts +1 -1
- package/lib/engine/webcomponents/needle menu/needle-menu.js +6 -6
- package/lib/engine/webcomponents/needle menu/needle-menu.js.map +1 -1
- package/lib/engine/webcomponents/needle-engine.d.ts +10 -4
- package/lib/engine/webcomponents/needle-engine.js +3 -3
- package/lib/engine/webcomponents/needle-engine.js.map +1 -1
- package/lib/engine/webcomponents/needle-engine.loading.js +2 -2
- package/lib/engine/webcomponents/needle-engine.loading.js.map +1 -1
- package/lib/engine/xr/NeedleXRSession.d.ts +3 -2
- package/lib/engine/xr/NeedleXRSession.js +50 -14
- package/lib/engine/xr/NeedleXRSession.js.map +1 -1
- package/lib/engine/xr/TempXRContext.js +2 -2
- package/lib/engine/xr/TempXRContext.js.map +1 -1
- package/lib/engine/xr/events.d.ts +1 -1
- package/lib/engine/xr/events.js.map +1 -1
- package/lib/engine-components/Animation.js +17 -16
- package/lib/engine-components/Animation.js.map +1 -1
- package/lib/engine-components/AnimationBuilder.d.ts +158 -0
- package/lib/engine-components/AnimationBuilder.js +305 -0
- package/lib/engine-components/AnimationBuilder.js.map +1 -0
- package/lib/engine-components/Animator.d.ts +6 -0
- package/lib/engine-components/Animator.js +23 -13
- package/lib/engine-components/Animator.js.map +1 -1
- package/lib/engine-components/AnimatorController.builder.d.ts +191 -0
- package/lib/engine-components/AnimatorController.builder.js +263 -0
- package/lib/engine-components/AnimatorController.builder.js.map +1 -0
- package/lib/engine-components/AnimatorController.d.ts +4 -119
- package/lib/engine-components/AnimatorController.js +37 -233
- package/lib/engine-components/AnimatorController.js.map +1 -1
- package/lib/engine-components/AudioSource.d.ts +19 -3
- package/lib/engine-components/AudioSource.js +121 -68
- package/lib/engine-components/AudioSource.js.map +1 -1
- package/lib/engine-components/Collider.d.ts +18 -9
- package/lib/engine-components/Collider.js +61 -14
- package/lib/engine-components/Collider.js.map +1 -1
- package/lib/engine-components/Component.d.ts +72 -9
- package/lib/engine-components/Component.js +114 -10
- package/lib/engine-components/Component.js.map +1 -1
- package/lib/engine-components/ContactShadows.d.ts +1 -0
- package/lib/engine-components/ContactShadows.js +14 -1
- package/lib/engine-components/ContactShadows.js.map +1 -1
- package/lib/engine-components/DragControls.d.ts +7 -0
- package/lib/engine-components/DragControls.js +19 -7
- package/lib/engine-components/DragControls.js.map +1 -1
- package/lib/engine-components/DropListener.js +3 -0
- package/lib/engine-components/DropListener.js.map +1 -1
- package/lib/engine-components/EventList.d.ts +31 -9
- package/lib/engine-components/EventList.js +37 -76
- package/lib/engine-components/EventList.js.map +1 -1
- package/lib/engine-components/Joints.d.ts +4 -2
- package/lib/engine-components/Joints.js +19 -3
- package/lib/engine-components/Joints.js.map +1 -1
- package/lib/engine-components/Light.js +13 -3
- package/lib/engine-components/Light.js.map +1 -1
- package/lib/engine-components/Networking.d.ts +1 -1
- package/lib/engine-components/Networking.js +1 -1
- package/lib/engine-components/OrbitControls.d.ts +0 -2
- package/lib/engine-components/OrbitControls.js +30 -12
- package/lib/engine-components/OrbitControls.js.map +1 -1
- package/lib/engine-components/ReflectionProbe.js +2 -0
- package/lib/engine-components/ReflectionProbe.js.map +1 -1
- package/lib/engine-components/RigidBody.d.ts +12 -4
- package/lib/engine-components/RigidBody.js +18 -4
- package/lib/engine-components/RigidBody.js.map +1 -1
- package/lib/engine-components/SceneSwitcher.js +3 -0
- package/lib/engine-components/SceneSwitcher.js.map +1 -1
- package/lib/engine-components/SeeThrough.js +2 -2
- package/lib/engine-components/SeeThrough.js.map +1 -1
- package/lib/engine-components/api.d.ts +2 -1
- package/lib/engine-components/api.js +2 -1
- package/lib/engine-components/api.js.map +1 -1
- package/lib/engine-components/codegen/components.d.ts +7 -13
- package/lib/engine-components/codegen/components.js +7 -13
- package/lib/engine-components/codegen/components.js.map +1 -1
- package/lib/engine-components/export/usdz/USDZExporter.js +4 -4
- package/lib/engine-components/export/usdz/USDZExporter.js.map +1 -1
- package/lib/engine-components/postprocessing/Effects/Tonemapping.utils.d.ts +1 -1
- package/lib/engine-components/postprocessing/VolumeParameter.d.ts +2 -0
- package/lib/engine-components/postprocessing/VolumeParameter.js +4 -1
- package/lib/engine-components/postprocessing/VolumeParameter.js.map +1 -1
- package/lib/engine-components/timeline/PlayableDirector.d.ts +21 -11
- package/lib/engine-components/timeline/PlayableDirector.js +75 -67
- package/lib/engine-components/timeline/PlayableDirector.js.map +1 -1
- package/lib/engine-components/timeline/SignalAsset.d.ts +3 -1
- package/lib/engine-components/timeline/SignalAsset.js +1 -0
- package/lib/engine-components/timeline/SignalAsset.js.map +1 -1
- package/lib/engine-components/timeline/TimelineBuilder.d.ts +413 -0
- package/lib/engine-components/timeline/TimelineBuilder.js +506 -0
- package/lib/engine-components/timeline/TimelineBuilder.js.map +1 -0
- package/lib/engine-components/timeline/TimelineModels.d.ts +2 -1
- package/lib/engine-components/timeline/TimelineModels.js +3 -0
- package/lib/engine-components/timeline/TimelineModels.js.map +1 -1
- package/lib/engine-components/timeline/TimelineTracks.d.ts +37 -6
- package/lib/engine-components/timeline/TimelineTracks.js +92 -26
- package/lib/engine-components/timeline/TimelineTracks.js.map +1 -1
- package/lib/engine-components/timeline/index.d.ts +2 -1
- package/lib/engine-components/timeline/index.js +2 -0
- package/lib/engine-components/timeline/index.js.map +1 -1
- package/lib/engine-components/ui/Canvas.d.ts +1 -1
- package/lib/engine-components/ui/Canvas.js +2 -8
- package/lib/engine-components/ui/Canvas.js.map +1 -1
- package/lib/engine-components/ui/Text.d.ts +1 -0
- package/lib/engine-components/ui/Text.js +10 -7
- package/lib/engine-components/ui/Text.js.map +1 -1
- package/lib/engine-components/web/CursorFollow.d.ts +0 -1
- package/lib/engine-components/web/CursorFollow.js +21 -13
- package/lib/engine-components/web/CursorFollow.js.map +1 -1
- package/lib/engine-components/webxr/WebXRImageTracking.d.ts +62 -1
- package/lib/engine-components/webxr/WebXRImageTracking.js +59 -2
- package/lib/engine-components/webxr/WebXRImageTracking.js.map +1 -1
- package/package.json +2 -83
- package/plugins/common/cloud.js +6 -1
- package/plugins/common/license.js +31 -10
- package/plugins/common/worker.js +9 -4
- package/plugins/vite/asap.js +17 -8
- package/plugins/vite/dependencies.js +29 -10
- package/plugins/vite/dependency-watcher.js +2 -2
- package/plugins/vite/editor-connection.js +3 -3
- package/plugins/vite/license.js +42 -7
- package/plugins/vite/local-files-core.js +3 -3
- package/plugins/vite/local-files-utils.d.ts +3 -1
- package/plugins/vite/local-files-utils.js +29 -5
- package/plugins/vite/reload.js +19 -18
- package/plugins/vite/server.js +2 -1
- package/src/engine/api.ts +11 -1
- package/src/engine/codegen/register_types.ts +10 -18
- package/src/engine/debug/debug_spatial_console.ts +10 -7
- package/src/engine/engine_addressables.ts +6 -3
- package/src/engine/engine_audio.ts +184 -0
- package/src/engine/engine_camera.fit.ts +15 -4
- package/src/engine/engine_components.ts +1 -1
- package/src/engine/engine_context.ts +63 -39
- package/src/engine/engine_context_eventbus.ts +73 -0
- package/src/engine/engine_disposable.ts +214 -0
- package/src/engine/engine_gameobject.ts +54 -159
- package/src/engine/engine_gltf_builtin_components.ts +7 -76
- package/src/engine/engine_init.ts +14 -4
- package/src/engine/engine_input.ts +28 -7
- package/src/engine/engine_instantiate_resolve.ts +407 -0
- package/src/engine/engine_license.ts +202 -56
- package/src/engine/engine_mainloop_utils.ts +7 -4
- package/src/engine/engine_networking.transport.websocket.ts +45 -0
- package/src/engine/engine_networking.ts +161 -137
- package/src/engine/engine_networking_blob.ts +4 -4
- package/src/engine/engine_networking_instantiate.ts +2 -2
- package/src/engine/engine_networking_types.ts +41 -1
- package/src/engine/engine_physics_rapier.ts +102 -33
- package/src/engine/engine_scenedata.ts +16 -13
- package/src/engine/engine_serialization_builtin_serializer.ts +64 -52
- package/src/engine/engine_serialization_core.ts +9 -0
- package/src/engine/engine_types.ts +46 -27
- package/src/engine/engine_util_decorator.ts +7 -2
- package/src/engine/engine_utils.ts +16 -5
- package/src/engine/engine_utils_qrcode.ts +2 -2
- package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js +1 -1
- package/src/engine/webcomponents/jsx.d.ts +9 -2
- package/src/engine/webcomponents/needle menu/needle-menu-spatial.ts +2 -2
- package/src/engine/webcomponents/needle menu/needle-menu.ts +6 -6
- package/src/engine/webcomponents/needle-engine.loading.ts +6 -6
- package/src/engine/webcomponents/needle-engine.ts +12 -6
- package/src/engine/xr/NeedleXRSession.ts +48 -13
- package/src/engine/xr/TempXRContext.ts +2 -2
- package/src/engine/xr/events.ts +1 -1
- package/src/engine-components/Animation.ts +19 -16
- package/src/engine-components/AnimationBuilder.ts +472 -0
- package/src/engine-components/Animator.ts +24 -12
- package/src/engine-components/AnimatorController.builder.ts +387 -0
- package/src/engine-components/AnimatorController.ts +24 -292
- package/src/engine-components/AudioSource.ts +130 -79
- package/src/engine-components/Collider.ts +66 -18
- package/src/engine-components/Component.ts +118 -20
- package/src/engine-components/ContactShadows.ts +15 -1
- package/src/engine-components/DragControls.ts +18 -11
- package/src/engine-components/DropListener.ts +3 -0
- package/src/engine-components/EventList.ts +45 -83
- package/src/engine-components/Joints.ts +20 -4
- package/src/engine-components/Light.ts +13 -4
- package/src/engine-components/Networking.ts +1 -1
- package/src/engine-components/OrbitControls.ts +34 -14
- package/src/engine-components/ReflectionProbe.ts +2 -0
- package/src/engine-components/RigidBody.ts +18 -4
- package/src/engine-components/SceneSwitcher.ts +3 -0
- package/src/engine-components/SeeThrough.ts +2 -2
- package/src/engine-components/api.ts +2 -1
- package/src/engine-components/codegen/components.ts +7 -13
- package/src/engine-components/export/usdz/USDZExporter.ts +4 -4
- package/src/engine-components/postprocessing/VolumeParameter.ts +4 -1
- package/src/engine-components/timeline/PlayableDirector.ts +83 -81
- package/src/engine-components/timeline/SignalAsset.ts +4 -1
- package/src/engine-components/timeline/TimelineBuilder.ts +824 -0
- package/src/engine-components/timeline/TimelineModels.ts +5 -1
- package/src/engine-components/timeline/TimelineTracks.ts +96 -27
- package/src/engine-components/timeline/index.ts +2 -1
- package/src/engine-components/ui/Canvas.ts +2 -8
- package/src/engine-components/ui/Text.ts +12 -8
- package/src/engine-components/web/CursorFollow.ts +21 -14
- package/src/engine-components/webxr/WebXRImageTracking.ts +79 -7
- package/dist/needle-engine.bundle--q_w7iXI.umd.cjs +0 -1732
- package/dist/needle-engine.bundle-w22UkaT_.min.js +0 -1732
- package/lib/engine-components/AvatarLoader.d.ts +0 -80
- package/lib/engine-components/AvatarLoader.js +0 -232
- package/lib/engine-components/AvatarLoader.js.map +0 -1
- package/lib/engine-components/avatar/AvatarBlink_Simple.d.ts +0 -11
- package/lib/engine-components/avatar/AvatarBlink_Simple.js +0 -77
- package/lib/engine-components/avatar/AvatarBlink_Simple.js.map +0 -1
- package/lib/engine-components/avatar/AvatarEyeLook_Rotation.d.ts +0 -14
- package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js +0 -69
- package/lib/engine-components/avatar/AvatarEyeLook_Rotation.js.map +0 -1
- package/lib/engine-components/avatar/Avatar_Brain_LookAt.d.ts +0 -29
- package/lib/engine-components/avatar/Avatar_Brain_LookAt.js +0 -122
- package/lib/engine-components/avatar/Avatar_Brain_LookAt.js.map +0 -1
- package/lib/engine-components/avatar/Avatar_MouthShapes.d.ts +0 -15
- package/lib/engine-components/avatar/Avatar_MouthShapes.js +0 -80
- package/lib/engine-components/avatar/Avatar_MouthShapes.js.map +0 -1
- package/lib/engine-components/avatar/Avatar_MustacheShake.d.ts +0 -9
- package/lib/engine-components/avatar/Avatar_MustacheShake.js +0 -30
- package/lib/engine-components/avatar/Avatar_MustacheShake.js.map +0 -1
- package/src/engine-components/AvatarLoader.ts +0 -264
- package/src/engine-components/avatar/AvatarBlink_Simple.ts +0 -70
- package/src/engine-components/avatar/AvatarEyeLook_Rotation.ts +0 -64
- package/src/engine-components/avatar/Avatar_Brain_LookAt.ts +0 -140
- package/src/engine-components/avatar/Avatar_MouthShapes.ts +0 -84
- package/src/engine-components/avatar/Avatar_MustacheShake.ts +0 -32
- package/src/vite-env.d.ts +0 -16
package/dist/needle-engine.d.ts
CHANGED
|
@@ -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
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
/**
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
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
|
-
*
|
|
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 =
|
|
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"
|
|
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:
|
|
1336
|
+
floatParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>;
|
|
1187
1337
|
/** Adds an integer parameter */
|
|
1188
|
-
intParameter(name:
|
|
1338
|
+
intParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>;
|
|
1189
1339
|
/** Adds a boolean parameter */
|
|
1190
|
-
boolParameter(name:
|
|
1340
|
+
boolParameter<N extends string>(name: N, defaultValue?: boolean): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>;
|
|
1191
1341
|
/** Adds a trigger parameter */
|
|
1192
|
-
triggerParameter(name:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
*
|
|
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):
|
|
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
|
-
|
|
1759
|
-
|
|
1760
|
-
|
|
1761
|
-
|
|
1762
|
-
|
|
1763
|
-
|
|
1764
|
-
|
|
1765
|
-
|
|
1766
|
-
|
|
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):
|
|
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
|
|
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
|
|
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
|
-
*
|
|
4464
|
-
* Types are
|
|
4465
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
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()
|
|
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
|
-
|
|
4823
|
-
|
|
4824
|
-
|
|
4825
|
-
|
|
4826
|
-
|
|
4827
|
-
|
|
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
|
-
|
|
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
|
-
|
|
5929
|
-
|
|
5930
|
-
|
|
5931
|
-
|
|
5932
|
-
|
|
5933
|
-
|
|
5934
|
-
|
|
5935
|
-
|
|
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
|
|
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):
|
|
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):
|
|
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):
|
|
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
|
|
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
|
-
* @
|
|
9039
|
+
* @returns A function that removes the event listener when called.
|
|
9040
|
+
*
|
|
9041
|
+
* @example With autoCleanup (recommended)
|
|
8524
9042
|
* ```ts
|
|
8525
|
-
*
|
|
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):
|
|
8544
|
-
addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2):
|
|
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
|
|
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
|
-
|
|
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
|
-
/**
|
|
9102
|
-
|
|
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
|
-
|
|
10457
|
-
|
|
10458
|
-
|
|
10459
|
-
|
|
10460
|
-
|
|
10461
|
-
|
|
10462
|
-
|
|
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
|
-
*
|
|
11052
|
-
*
|
|
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
|
-
*
|
|
11057
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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)
|
|
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
|
-
*
|
|
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
|
|
13220
|
+
* @example With autoCleanup (recommended)
|
|
12634
13221
|
* ```ts
|
|
12635
|
-
*
|
|
12636
|
-
*
|
|
12637
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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):
|
|
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
|
-
*
|
|
13263
|
+
* @example
|
|
12667
13264
|
* ```ts
|
|
12668
|
-
* //
|
|
12669
|
-
*
|
|
12670
|
-
*
|
|
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
|
-
|
|
12683
|
-
|
|
12684
|
-
|
|
12685
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
15401
|
+
forEachTrack(): Generator<Tracks.TimelineTrackHandler, void, unknown>;
|
|
14743
15402
|
/**
|
|
14744
15403
|
* @returns all animation tracks of the timeline
|
|
14745
15404
|
*/
|
|
14746
|
-
get animationTracks(): Tracks.
|
|
15405
|
+
get animationTracks(): Tracks.TimelineAnimationTrack[];
|
|
14747
15406
|
/**
|
|
14748
15407
|
* @returns all audio tracks of the timeline
|
|
14749
15408
|
*/
|
|
14750
|
-
get audioTracks(): Tracks.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
}):
|
|
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
|
|
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
|
-
/**
|
|
16828
|
-
*
|
|
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
|
-
|
|
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
|
-
/**
|
|
19853
|
-
|
|
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
|
-
*
|
|
20712
|
-
*
|
|
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
|
-
|
|
20715
|
-
|
|
20716
|
-
|
|
20717
|
-
|
|
20718
|
-
|
|
20719
|
-
|
|
20720
|
-
|
|
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
|
-
|
|
20760
|
-
|
|
20761
|
-
|
|
20762
|
-
|
|
21868
|
+
TimelineTrackHandler,
|
|
21869
|
+
TimelineAnimationTrack,
|
|
21870
|
+
TimelineAudioTrack,
|
|
21871
|
+
TimelineMarkerTrack,
|
|
20763
21872
|
SignalTrackHandler,
|
|
20764
|
-
|
|
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
|
|
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 |
|
|
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
|
-
/**
|
|
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
|
|
23532
|
-
|
|
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
|
|
23694
|
-
|
|
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
|
}
|