@needle-tools/engine 5.1.0-alpha.4 → 5.1.0-alpha.6

package/src/engine-components/timeline/TimelineTracks.ts

@@ -4,13 +4,14 @@ import { isDevEnvironment } from "../../engine/debug/index.js";
 import { Context } from "../../engine/engine_setup.js";
 import type { Constructor } from "../../engine/engine_types.js";
 import { getParam, resolveUrl } from "../../engine/engine_utils.js";
-import { setObjectAnimated } from "../AnimationUtils.js";
 import { Animator } from "../Animator.js"
 import { AudioSource } from "../AudioSource.js";
 import { GameObject } from "../Component.js";
 import type { PlayableDirector } from "./PlayableDirector.js";
 import { SignalReceiver } from "./SignalAsset.js";
 import * as Models from "./TimelineModels.js";
+import type { TimelineBuilder } from "./TimelineBuilder.js";
+import { AnimationUtils } from "../../engine/engine_animation.js";
 
 const debug = getParam("debugtimeline");
 
@@ -18,7 +19,7 @@ const debug = getParam("debugtimeline");
  * A TrackHandler is responsible for evaluating a specific type of timeline track.  
  * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
  */
-export abstract class TrackHandler {
+export abstract class TimelineTrackHandler {
     director!: PlayableDirector;
     track!: Models.TrackModel;
 
@@ -136,7 +137,7 @@ class AnimationClipOffsetData {
 }
 
 // TODO: add support for clip clamp modes (loop, pingpong, clamp)
-export class AnimationTrackHandler extends TrackHandler {
+export class TimelineAnimationTrack extends TimelineTrackHandler {
     /** @internal */
     models: Array<Models.ClipModel> = [];
     /** @internal */
@@ -178,7 +179,7 @@ export class AnimationTrackHandler extends TrackHandler {
     onStateChanged() {
         if (this._animator) {
             // We can not check the *isPlaying* state here because the timeline might be paused and evaluated by e.g. ScrollFollow
-            setObjectAnimated(this._animator.gameObject, this, this.director.enabled && this.director.weight > 0);
+            AnimationUtils.setObjectAnimated(this._animator.gameObject, this, this.director.enabled && this.director.weight > 0);
         }
     }
 
@@ -262,7 +263,7 @@ export class AnimationTrackHandler extends TrackHandler {
             // which overrides the timeline
             this._animator = GameObject.getComponent(this.target, Animator) ?? null;
             if (this._animator) {
-                setObjectAnimated(this._animator.gameObject, this, true);
+                AnimationUtils.setObjectAnimated(this._animator.gameObject, this, true);
             }
         }
 
@@ -605,7 +606,7 @@ declare type AudioClipModel = Models.ClipModel & { _didTriggerPlay: boolean };
  * - The director is paused (`director.pause()`)
  * - The director is disabled or destroyed
  */
-export class AudioTrackHandler extends TrackHandler {
+export class TimelineAudioTrack extends TimelineTrackHandler {
 
     models: Array<AudioClipModel> = [];
     listener!: AudioListener;
@@ -814,7 +815,7 @@ export class AudioTrackHandler extends TrackHandler {
     private static _audioBuffers: Map<string, Promise<AudioBuffer | null>> = new Map();
 
     public static dispose() {
-        AudioTrackHandler._audioBuffers.clear();
+        TimelineAudioTrack._audioBuffers.clear();
     }
 
     private handleAudioLoading(model: Models.ClipModel, audio: Audio): Promise<AudioBuffer | null> | null {
@@ -824,8 +825,8 @@ export class AudioTrackHandler extends TrackHandler {
         // TODO: maybe we should cache the loaders / buffers here by path
         const path = this.getAudioFilePath(model.asset.clip);
 
-        if (AudioTrackHandler._audioBuffers.get(path)) {
-            const promise = AudioTrackHandler._audioBuffers.get(path)!
+        if (TimelineAudioTrack._audioBuffers.get(path)) {
+            const promise = TimelineAudioTrack._audioBuffers.get(path)!
             promise.then((buffer) => {
                 if (buffer) audio.setBuffer(buffer);
             });
@@ -845,17 +846,17 @@ export class AudioTrackHandler extends TrackHandler {
                     resolve(null);
                 });
         });
-        AudioTrackHandler._audioBuffers.set(path, loadingPromise);
+        TimelineAudioTrack._audioBuffers.set(path, loadingPromise);
         return loadingPromise;
     }
 }
 
-export class MarkerTrackHandler extends TrackHandler {
+export class TimelineMarkerTrack extends TimelineTrackHandler {
     models: Array<Models.MarkerModel & Record<string, any>> = [];
     needsSorting = true;
 
     *foreachMarker<T>(type: string | null = null) {
-        if(this.needsSorting) this.sort();
+        if (this.needsSorting) this.sort();
         for (const model of this.models) {
             if (model && model.type === type) yield model as T;
         }
@@ -876,7 +877,7 @@ export class MarkerTrackHandler extends TrackHandler {
     }
 }
 
-export class SignalTrackHandler extends TrackHandler {
+export class SignalTrackHandler extends TimelineTrackHandler {
     models: Models.SignalMarkerModel[] = [];
     didTrigger: boolean[] = [];
     receivers: Array<SignalReceiver | null> = [];
@@ -954,8 +955,15 @@ export class SignalTrackHandler extends TrackHandler {
     }
 }
 
-
-export class ActivationTrackHandler extends TrackHandler {
+/**
+ * Handles activation (visibility) of bound objects for a timeline activation track.
+ *
+ * Each clip on the track defines a time range during which the bound objects should be active (visible).
+ * @see TimelineTrackHandler for details on how tracks and clips work in general, and how to mutate them at runtime.
+ * @see PlayableDirector for how to control timeline playback and time.
+ * @see TimelineBuilder for how to create and configure timelines and tracks in the editor.
+ */
+export class TimelineActivationTrack extends TimelineTrackHandler {
 
     evaluate(time: number) {
         if (this.track.muted) return;
@@ -987,7 +995,7 @@ export class ActivationTrackHandler extends TrackHandler {
 }
 
 
-export class ControlTrackHandler extends TrackHandler {
+export class TimelineControlTrack extends TimelineTrackHandler {
     models: Array<Models.ClipModel> = [];
     timelines: Array<PlayableDirector | null> = [];
 

package/src/engine-components/web/CursorFollow.ts

@@ -178,7 +178,6 @@ export class CursorFollow extends Behaviour {
      * - Cursor that follows terrain or mesh surfaces
      *
      * **Important notes:**
-     * - Requires objects in the scene to have colliders for raycasting to work
      * - Works best with {@link keepDistance} set to `false` to allow depth changes
      * - Can be combined with {@link damping} for smooth surface following
      * - The raycast uses the physics system's raycast functionality

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -12,6 +12,7 @@ import { IUSDExporterExtension } from "../../engine-components/export/usdz/Exten
 import { imageToCanvas, USDObject, USDWriter, USDZExporterContext } from "../../engine-components/export/usdz/ThreeUSDZExporter.js";
 import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.js";
 import { Behaviour, GameObject } from "../Component.js";
+import { EventList } from "../EventList.js";
 import { Renderer } from "../Renderer.js";
 
 // https://github.com/immersive-web/marker-tracking/blob/main/explainer.md
@@ -41,8 +42,41 @@ export class WebXRTrackedImage {
     get widthInMeters() { return this._trackedImage.widthInMeters ?? undefined; }
     /** The ImageBitmap used for tracking */
     get bitmap(): ImageBitmap { return this._bitmap; }
-    /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
+    /**
+     * The {@link WebXRImageTrackingModel} configuration for this tracked image.
+     * Use this to access the assigned 3D object, marker settings, and other image tracking configuration.
+     * Available on each {@link WebXRTrackedImage} received from the `image-tracking` {@link CustomEvent} (`event.detail`).
+     * @example
+     * ```ts
+     * tracker.addEventListener("image-tracking", event => {
+     *   for (const img of event.detail.trackedImages) {
+     *     const model = img.model;
+     *     // Access the assigned 3D object
+     *     const obj = model.object;
+     *     // Access other settings
+     *     console.log(model.widthInMeters, model.hideWhenTrackingIsLost);
+     *   }
+     * });
+     * ```
+     */
     get model(): WebXRImageTrackingModel { return this._trackedImage; }
+
+    /**
+     * The 3D object or prefab assigned to this tracked image marker in the {@link WebXRImageTrackingModel}.
+     * Use this to access the object associated with an AR image tracking marker from the `image-tracking` {@link CustomEvent}.
+     * Shorthand for `this.model.object`.
+     * @example
+     * ```ts
+     * tracker.addEventListener("image-tracking", event => {
+     *   for (const img of event.detail.trackedImages) {
+     *     const obj = img.trackedModel;
+     *     // verbose alternative: img.model.object
+     *   }
+     * });
+     * ```
+     */
+    get trackedModel(): AssetReference | undefined { return this._trackedImage.object; }
+
     /**
      * The measured size of the detected image in the real world.
      * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
@@ -133,11 +167,6 @@ export class WebXRTrackedImage {
 
 }
 
-/**
- * Event callback type for image tracking updates.
- * @param images Array of currently tracked images
- */
-declare type WebXRImageTrackingEvent = (images: WebXRImageTrackingEvent[]) => void;
 
 /**
  * Initial state of tracked image objects before entering an XR session.
@@ -293,6 +322,17 @@ export class WebXRImageTrackingModel {
     }
 }
 
+/** Data passed to image tracking event listeners. */
+export interface WebXRImageTrackingEvent {
+    /** The images currently being tracked this frame. */
+    readonly trackedImages: readonly WebXRTrackedImage[];
+}
+
+/** Event map for {@link WebXRImageTracking} events. Use with `addEventListener` for typed event handling. */
+export interface WebXRImageTrackingEventMap {
+    /** Dispatched every frame when images are being tracked. The event detail contains the tracking data for the current frame. */
+    "image-tracking": CustomEvent<WebXRImageTrackingEvent>;
+}
 
 // #region USDZ Extension
 class ImageTrackingExtension implements IUSDExporterExtension {
@@ -515,6 +555,34 @@ class ImageTrackingExtension implements IUSDExporterExtension {
  */
 export class WebXRImageTracking extends Behaviour {
 
+    /**
+     * Event invoked every frame when images are being tracked.
+     * @example
+     * ```ts
+     * const tracker = this.gameObject.getComponent(WebXRImageTracking);
+     * tracker?.imageTracked.addEventListener(evt => {
+     *   for (const img of evt.trackedImages) {
+     *     console.log(img.url, img.state);
+     *   }
+     * });
+     * ```
+     */
+    imageTracked: EventList<WebXRImageTrackingEvent> = new EventList();
+
+    /** @inheritdoc */
+    addEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+    addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+    addEventListener(type: string, listener: (evt: any) => any): void {
+        super.addEventListener(type, listener);
+    }
+
+    /** @inheritdoc */
+    removeEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+    removeEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+    removeEventListener(type: string, listener: (evt: any) => any): void {
+        super.removeEventListener(type, listener);
+    }
+
     /**
      * Set which marker should be primary (first in the list).
      * Useful when deploying to QuickLook mode where one marker is tracked at a time.
@@ -763,7 +831,9 @@ export class WebXRImageTracking extends Behaviour {
                     }
                     if (this.currentImages.length > 0) {
                         try {
-                            this.dispatchEvent(new CustomEvent("image-tracking", { detail: this.currentImages }));
+                            const eventData: WebXRImageTrackingEvent = { trackedImages: this.currentImages };
+                            this.dispatchEvent(new CustomEvent("image-tracking", { detail: eventData }));
+                            this.imageTracked.invoke(eventData);
                             this.onImageTrackingUpdate(this.currentImages);
                         }
                         catch (e) {

package/src/vite-env.d.ts

@@ -1,16 +0,0 @@
-// Vite global defines — see plugins/vite/defines.js
-// declare const entries here are picked up globally (ambient, no import/export).
-// Vite sets these as globals in dev and statically replaces them at build time.
-// Webpack DefinePlugin replaces them at build time too.
-// The globalThis fallbacks for vanilla JS are in engine_constants.ts.
-
-declare const NEEDLE_ENGINE_VERSION: string;
-declare const NEEDLE_ENGINE_GENERATOR: string;
-declare const NEEDLE_PROJECT_BUILD_TIME: string;
-declare const NEEDLE_PUBLIC_KEY: string;
-
-// #region treeshake flags
-// declare var (not const) so globalThis["NEEDLE_USE_*"] access is also type-safe
-declare var NEEDLE_USE_RAPIER: boolean;
-declare var NEEDLE_USE_POSTPROCESSING: boolean;
-// #endregion treeshake flags