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