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

package/src/engine-components/Light.ts

@@ -1,12 +1,12 @@
 import { CameraHelper, Color, DirectionalLight, DirectionalLightHelper, Light as ThreeLight, OrthographicCamera, PointLight, SpotLight, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { FrameEvent } from "../engine/engine_setup.js";
 import { setWorldPositionXYZ } from "../engine/engine_three_utils.js";
 import type { ILight } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js";
 import type { NeedleXREventArgs } from "../engine/xr/api.js";
 import { Behaviour, GameObject } from "./Component.js";
+import { isDevEnvironment } from "../engine/debug/index.js";
 
 // https://threejs.org/examples/webgl_shadowmap_csm.html
 
@@ -135,7 +135,10 @@ export class Light extends Behaviour implements ILight {
                 this._type = value;
                 break;
             default:
-                throw new Error("Invalid light type: " + value);
+                if (debug || isDevEnvironment())
+                    console.warn(`[Light] Unsupported light type: ${LightType[value]} (${value}) on '${this.name}'`);
+                this._type = "unsupported" as any;
+                break;
         }
     }
     private _type: ILight["type"] = "point";
@@ -474,6 +477,11 @@ export class Light extends Behaviour implements ILight {
                     // const pointHelper = new PointLightHelper(pointLight, this.range, this.color);
                     // scene.add(pointHelper);
                     break;
+
+                default:
+                    if (debug) console.warn(`[Light] Unsupported light type: ${LightType[this.type as any]} (${this.type}) on '${this.name}'`);
+                    break;
+
             }
         }
 

package/src/engine-components/RigidBody.ts

@@ -204,12 +204,19 @@ export class Rigidbody extends Behaviour implements IRigidbody {
 
     get isRigidbody() { return true; }
 
-    /** When true the mass will be automatically calculated by the attached colliders */
+    /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
+     * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
+     * Disable to set mass explicitly via the `mass` property.
+     */
     @validate()
     autoMass: boolean = true;
 
-    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
-     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+    /** The mass of the rigidbody in kg (when `autoMass` is disabled).
+     * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
+     * Setting this property automatically disables `autoMass`.
+     *
+     * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
+     * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
      */
     @serializable()
     set mass(value: number) {
@@ -403,9 +410,16 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this.context.physics.engine?.removeBody(this);
     }
 
-    onValidate() {
+    onValidate(property?: string) {
         this._propertiesChanged = true;
+        if (property === "autoMass" && !this.autoMass) {
+            if (isDevEnvironment() && !Rigidbody._didWarnAutoMass) {
+                Rigidbody._didWarnAutoMass = true;
+                console.warn("[Rigidbody] autoMass disabled — consider using Collider.density instead of setting mass explicitly. Density scales naturally with collider size.");
+            }
+        }
     }
+    private static _didWarnAutoMass = false;
 
     // need to do this right before updating physics to prevent rendered object glitching through physical bodies
     * beforePhysics() {

package/src/engine-components/api.ts

@@ -34,7 +34,7 @@
  * @module Built-in Components
  */
 
-export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 export * from "./codegen/components.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";

package/src/engine-components/codegen/components.ts

@@ -6,18 +6,10 @@ export { Animation } from "../Animation.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.js";
+export { AnimatorControllerBuilder } from "../AnimatorController.builder.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";
-export { Avatar_POI } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_Brain_LookAt } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_MouthShapes } from "../avatar/Avatar_MouthShapes.js";
-export { Avatar_MustacheShake } from "../avatar/Avatar_MustacheShake.js";
-export { AvatarBlink_Simple } from "../avatar/AvatarBlink_Simple.js";
-export { AvatarEyeLook_Rotation } from "../avatar/AvatarEyeLook_Rotation.js";
-export { AvatarModel } from "../AvatarLoader.js";
-export { AvatarLoader } from "../AvatarLoader.js";
 export { AxesHelper } from "../AxesHelper.js";
 export { BasicIKConstraint } from "../BasicIKConstraint.js";
 export { BoxHelperComponent } from "../BoxHelperComponent.js";
@@ -168,10 +160,12 @@ export { PlayableDirector } from "../timeline/PlayableDirector.js";
 export { SignalAsset } from "../timeline/SignalAsset.js";
 export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
+export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
 export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
 export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
 export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
+export { ActivationTrackHandler } from "../timeline/TimelineTracks.js";
 export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";

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

@@ -4,7 +4,6 @@ import { isDevEnvironment } from '../../engine/debug/index.js';
 import { FrameEvent } from '../../engine/engine_context.js';
 import { isLocalNetwork } from '../../engine/engine_networking_utils.js';
 import { serializable } from '../../engine/engine_serialization.js';
-import type { GuidsMap } from '../../engine/engine_types.js';
 import { deepClone, delay, getParam } from '../../engine/engine_utils.js';
 import { Animator } from '../Animator.js';
 import { AudioListener } from '../AudioListener.js';
@@ -115,7 +114,15 @@ export class PlayableDirector extends Behaviour {
      * The timeline asset containing tracks, clips, and markers that this director will play.
      * Assign a timeline asset exported from Unity or Blender to enable playback.
      */
-    playableAsset?: Models.TimelineAssetModel;
+    @serializable()
+    get playableAsset(): Models.TimelineAssetModel | undefined { return this._playableAsset; }
+    set playableAsset(value: Models.TimelineAssetModel | undefined) {
+        if (this._playableAsset !== value) {
+            this._playableAsset = value;
+            this._needsGraphRebuild = true;
+        }
+    }
+    private _playableAsset?: Models.TimelineAssetModel;
 
     /**
      * When true, the timeline starts playing automatically when the component awakens.
@@ -123,7 +130,7 @@ export class PlayableDirector extends Behaviour {
      * @default false
      */
     @serializable()
-    playOnAwake?: boolean;
+    playOnAwake: boolean = false;
 
     /**
      * Determines how the timeline behaves when it reaches the end of its duration.
@@ -207,14 +214,10 @@ export class PlayableDirector extends Behaviour {
     onEnable() {
         if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
 
-        for (const track of this._audioTracks) {
-            track.onEnable?.();
-        }
-        for (const track of this._customTracks) {
-            track.onEnable?.();
-        }
-        for (const track of this._animationTracks) {
-            track.onEnable?.();
+        for (const tracks of this._allTracks) {
+            for (const track of tracks) {
+                track.onEnable?.();
+            }
         }
         if (this.playOnAwake) {
             this.play();
@@ -265,6 +268,7 @@ export class PlayableDirector extends Behaviour {
         this.resolveBindings();
         this.updateTimelineDuration();
         this.setupAndCreateTrackHandlers();
+        this._needsGraphRebuild = false;
     }
 
     /**
@@ -273,6 +277,8 @@ export class PlayableDirector extends Behaviour {
      */
     async play() {
         if (!this.isValid()) return;
+        // Ensure graph is built (handles the case where playableAsset is assigned after awake)
+        if (this._needsGraphRebuild) this.rebuildGraph();
         const pauseChanged = this._isPaused == true;
         this._isPaused = false;
         if (this._isPlaying) return;
@@ -290,8 +296,13 @@ export class PlayableDirector extends Behaviour {
                 await Promise.all(promises);
                 if (!this._isPlaying) return;
             }
-            while (this._audioTracks.length > 0 && this._isPlaying && !AudioSource.userInteractionRegistered && this.waitForAudio)
+            let ticks = 0;
+            while (this._audioTracks.length > 0 && this._isPlaying && !AudioSource.userInteractionRegistered && this.waitForAudio) {
+                if (ticks++ <= 0) {
+                    if (isDevEnvironment() || debug) console.warn(`[Timeline] Waiting for user interaction to play audio... (timeline '${this.name}' will start as soon as user interacts with the page). To start the timeline immediately without waiting for user interaction, set 'waitForAudio' to false on the PlayableDirector component.`);
+                }
                 await delay(200);
+            }
         }
         this.invokeStateChangedMethodsOnTracks();
         // Update timeline in LateUpdate to give other scripts time to react to the updated state  
@@ -343,6 +354,7 @@ export class PlayableDirector extends Behaviour {
      * Evaluate the timeline at the current time. This is useful when you want to manually update the timeline e.g. when the timeline is paused and you set `time` to a new value.
      */
     evaluate() {
+        if (this._needsGraphRebuild) this.rebuildGraph();
         this.internalEvaluate(true);
     }
 
@@ -391,6 +403,20 @@ export class PlayableDirector extends Behaviour {
         return this._markerTracks;
     }
 
+    /**
+     * @returns all activation tracks of the timeline
+     */
+    get activationTracks(): Tracks.ActivationTrackHandler[] {
+        return this._activationTracks;
+    }
+
+    /**
+     * @returns all tracks of the timeline
+     */
+    get tracks(): ReadonlyArray<Tracks.TrackHandler> {
+        return this._allTracks.flat();
+    }
+
     /**
      * Iterates over all markers of the timeline, optionally filtering by type
      * 
@@ -412,19 +438,17 @@ export class PlayableDirector extends Behaviour {
     }
 
 
-    private _guidsMap?: GuidsMap;
-    /** @internal */
-    resolveGuids(map: GuidsMap) {
-        this._guidsMap = map;
-    }
 
     // INTERNALS
 
+    private _needsGraphRebuild: boolean = false;
     private _isPlaying: boolean = false;
     private _internalUpdateRoutine: any;
     private _isPaused: boolean = false;
     /** internal, true during the time stop() is being processed */
     private _isStopping: boolean = false;
+    /** @internal Whether the current evaluate() was triggered by user code (not the internal update loop or stop/pause). */
+    _isUserEvaluation: boolean = false;
     private _time: number = 0;
     private _duration: number = 0;
     private _weight: number = 1;
@@ -433,6 +457,7 @@ export class PlayableDirector extends Behaviour {
     private readonly _signalTracks: Array<Tracks.SignalTrackHandler> = [];
     private readonly _markerTracks: Array<Tracks.MarkerTrackHandler> = [];
     private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
+    private readonly _activationTracks: Array<Tracks.ActivationTrackHandler> = [];
     private readonly _customTracks: Array<Tracks.TrackHandler> = [];
 
     private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
@@ -443,6 +468,7 @@ export class PlayableDirector extends Behaviour {
         this._tracksArray.push(this._signalTracks);
         this._tracksArray.push(this._markerTracks);
         this._tracksArray.push(this._controlTracks);
+        this._tracksArray.push(this._activationTracks);
         this._tracksArray.push(this._customTracks);
         return this._tracksArray;
     }
@@ -503,60 +529,32 @@ export class PlayableDirector extends Behaviour {
 
         const time = this._time;
 
-        for (const track of this.playableAsset!.tracks) {
-            if (track.muted) continue;
-            switch (track.type) {
-                case Models.TrackType.Activation:
-                    // when the timeline is being disabled or stopped 
-                    // then we want to leave objects active state as they were
-                    // see NE-3241
-                    // TODO: support all "post-playback-state" settings an activation track has, this is just "Leave as is"
-                    if (!called_by_user && !this._isPlaying) continue;
-
-                    for (let i = 0; i < track.outputs.length; i++) {
-                        const binding = track.outputs[i];
-                        if (typeof binding === "object") {
-                            let isActive: boolean = false;
-                            if (track.clips) {
-                                for (const clip of track.clips) {
-                                    if (clip.start <= time && time <= clip.end) {
-                                        isActive = true;
-                                    }
-                                }
-                            }
-                            const obj = binding as Object3D;
-                            if (obj.visible !== undefined) {
-                                if (obj.visible !== isActive) {
-                                    obj.visible = isActive;
-                                    if (debug)
-                                        console.warn(this.name, "set ActivationTrack-" + i, obj.name, isActive, time);
-                                }
-                            }
-                        }
-                    }
-                    break;
-
-            }
-        }
-
+        this._isUserEvaluation = called_by_user;
         for (const track of this._allTracks) {
             for (const handler of track) {
                 // When timeline reaches the end "stop()" is called which is evaluating with time 0
                 // We don't want to re-evaluate the animation then in case the timeline is blended with the Animator
                 // e.g then the timeline animation at time 0 is 100% applied on top of the animator animation
-
                 if (this._isStopping && handler instanceof Tracks.AnimationTrackHandler) {
                     continue;
                 }
                 handler.evaluate(time);
             }
         }
+        this._isUserEvaluation = false;
     }
 
     private resolveBindings() {
         if (!this._clonedPlayableAsset) {
             this._clonedPlayableAsset = true;
-            this.playableAsset = deepClone(this.playableAsset);
+            // Deep clone so each director owns its own copy of the asset data.
+            // Needed because NEEDLE_persistent_assets returns the same shared object for all references —
+            // without this, resolving guid strings below would mutate shared data.
+            // On instantiated clones this is skipped (_clonedPlayableAsset is copied as true)
+            // because the instantiate resolve system already created an independent copy.
+            this.playableAsset = deepClone(this.playableAsset, (_obj, _key, val) => {
+                return !(val?.isObject3D === true);
+            });
         }
 
         if (!this.playableAsset || !this.playableAsset.tracks) return;
@@ -569,15 +567,13 @@ export class PlayableDirector extends Behaviour {
 
         for (const track of this.playableAsset.tracks) {
             for (let i = track.outputs.length - 1; i >= 0; i--) {
-                let binding = track.outputs[i];
+                const binding = track.outputs[i];
                 if (typeof binding === "string") {
-                    if (this._guidsMap && this._guidsMap[binding])
-                        binding = this._guidsMap[binding];
                     const obj = GameObject.findByGuid(binding, root);
                     if (obj === null || typeof obj !== "object") {
                         // if the binding is missing remove it to avoid unnecessary loops
                         track.outputs.splice(i, 1);
-                        console.warn("Failed to resolve binding", binding, track.name, track.type);
+                        console.warn(`[Timeline] Failed to resolve binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' ('${binding}' not found in scene)`);
                     }
                     else {
                         if (debug)
@@ -592,21 +588,20 @@ export class PlayableDirector extends Behaviour {
                         continue;
                     }
                     // if the binding is missing remove it to avoid unnecessary loops
-                    if (track.type !== Models.TrackType.Audio && track.type !== Models.TrackType.Control && track.type !== Models.TrackType.Marker && track.type !== Models.TrackType.Signal)
-                        console.warn("Missing binding", binding, track.name, track.type, this.name, this.playableAsset.name);
+                    if (track.type !== Models.TrackType.Audio && track.type !== Models.TrackType.Control && track.type !== Models.TrackType.Marker && track.type !== Models.TrackType.Signal) {
+                        console.warn(`[Timeline] Missing binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' (null binding)`);
+                    }
                 }
             }
             if (track.type === Models.TrackType.Control) {
                 if (track.clips) {
                     for (let i = 0; i < track.clips.length; i++) {
                         const clip = track.clips[i];
-                        let binding = clip.asset.sourceObject;
+                        const binding = clip.asset.sourceObject;
                         if (typeof binding === "string") {
-                            if (this._guidsMap && this._guidsMap[binding])
-                                binding = this._guidsMap[binding];
                             const obj = GameObject.findByGuid(binding, root);
                             if (obj === null || typeof obj !== "object") {
-                                console.warn("Failed to resolve sourceObject binding", binding, track.name, clip);
+                                console.warn(`[Timeline] Failed to resolve sourceObject binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' ('${binding}' not found in scene)`);
                             }
                             else {
                                 if (debug)
@@ -649,6 +644,7 @@ export class PlayableDirector extends Behaviour {
         this._animationTracks.length = 0;
         this._audioTracks.length = 0;
         this._signalTracks.length = 0;
+        this._activationTracks.length = 0;
 
         if (!this.playableAsset) return;
         let audioListener: AudioListener | null = GameObject.findObjectOfType(AudioListener, this.context);
@@ -810,6 +806,12 @@ export class PlayableDirector extends Behaviour {
                 handler.resolveSourceObjects(this.context);
                 this._controlTracks.push(handler);
             }
+            else if (track.type === Models.TrackType.Activation) {
+                const handler = new Tracks.ActivationTrackHandler();
+                handler.director = this;
+                handler.track = track;
+                this._activationTracks.push(handler);
+            }
         }
     }
 

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

@@ -1,4 +1,5 @@
 import { serializable } from "../../engine/engine_serialization_decorator.js";
+import { ISignalReceiver } from "../../engine/engine_types.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
@@ -33,7 +34,9 @@ export class SignalReceiverEvent {
  * @category Animation and Sequencing
  * @group Components
  */
-export class SignalReceiver extends Behaviour {
+export class SignalReceiver extends Behaviour implements ISignalReceiver {
+
+    readonly isSignalReceiver = true;
 
     private static receivers: { [key: string]: SignalReceiver[] } = {};