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

package/src/engine-components/AnimatorController.builder.ts

@@ -0,0 +1,261 @@
+import { AnimationClip } from "three";
+
+import { AnimatorConditionMode, AnimatorControllerParameterType } from "../engine/extensions/NEEDLE_animator_controller_model.js";
+import type { AnimatorControllerModel, Condition, Parameter, State, Transition } from "../engine/extensions/NEEDLE_animator_controller_model.js";
+import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
+import { AnimatorController } from "./AnimatorController.js";
+
+
+/**
+ * Configuration for an animation state in the builder
+ */
+export declare type StateOptions = {
+    /** The animation clip for this state */
+    clip: AnimationClip;
+    /** Whether the animation should loop (default: false) */
+    loop?: boolean;
+    /** Base speed multiplier (default: 1) */
+    speed?: number;
+    /** Name of a float parameter to multiply with speed */
+    speedParameter?: string;
+    /** Normalized cycle offset 0-1 (default: 0) */
+    cycleOffset?: number;
+    /** Name of a float parameter to use as cycle offset */
+    cycleOffsetParameter?: string;
+}
+
+/**
+ * Configuration for a transition in the builder
+ */
+export declare type TransitionOptions = {
+    /** Duration of the crossfade in seconds (default: 0) */
+    duration?: number;
+    /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
+    exitTime?: number;
+    /** Whether the transition waits for exitTime before transitioning (default: false) */
+    hasExitTime?: boolean;
+    /** Normalized offset into the destination state's animation (default: 0) */
+    offset?: number;
+    /** Whether duration is in seconds (true) or normalized (false) (default: false) */
+    hasFixedDuration?: boolean;
+}
+
+/** String condition modes for the builder, mapped to {@link AnimatorConditionMode} */
+export type ConditionMode = "if" | "ifNot" | "greater" | "less" | "equals" | "notEqual";
+
+function conditionModeToEnum(mode: ConditionMode): AnimatorConditionMode {
+    switch (mode) {
+        case "if": return AnimatorConditionMode.If;
+        case "ifNot": return AnimatorConditionMode.IfNot;
+        case "greater": return AnimatorConditionMode.Greater;
+        case "less": return AnimatorConditionMode.Less;
+        case "equals": return AnimatorConditionMode.Equals;
+        case "notEqual": return AnimatorConditionMode.NotEqual;
+    }
+}
+
+type BuilderTransition = {
+    to: string;
+    options: TransitionOptions;
+    conditions: Array<{ parameter: string; mode: ConditionMode; threshold: number }>;
+};
+
+type BuilderState = {
+    name: string;
+    options: StateOptions;
+    transitions: BuilderTransition[];
+};
+
+/**
+ * A fluent builder for creating {@link AnimatorController} instances from code.
+ *
+ * Use {@link AnimatorController.build} to create a new builder.
+ *
+ * @example
+ * ```ts
+ * const controller = AnimatorController.build("CharacterController")
+ *     .floatParameter("Speed", 0)
+ *     .triggerParameter("Jump")
+ *     .state("Idle", { clip: idleClip, loop: true })
+ *     .state("Walk", { clip: walkClip, loop: true })
+ *     .state("Jump", { clip: jumpClip })
+ *     .transition("Idle", "Walk", { duration: 0.25 })
+ *         .condition("Speed", "greater", 0.1)
+ *     .transition("Walk", "Idle", { duration: 0.25 })
+ *         .condition("Speed", "less", 0.1)
+ *     .transition("*", "Jump", { duration: 0.1 })
+ *         .condition("Jump", "if")
+ *     .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
+ *     .build();
+ * ```
+ *
+ * @category Animation and Sequencing
+ * @group Utilities
+ */
+export class AnimatorControllerBuilder {
+    private _name: string;
+    private _parameters: Parameter[] = [];
+    private _states: BuilderState[] = [];
+    private _anyStateTransitions: BuilderTransition[] = [];
+    private _defaultStateName: string | null = null;
+    private _lastTransition: BuilderTransition | null = null;
+
+    constructor(name?: string) {
+        this._name = name ?? "AnimatorController";
+    }
+
+    /** Adds a float parameter */
+    floatParameter(name: string, defaultValue: number = 0): this {
+        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Float, value: defaultValue });
+        return this;
+    }
+
+    /** Adds an integer parameter */
+    intParameter(name: string, defaultValue: number = 0): this {
+        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Int, value: defaultValue });
+        return this;
+    }
+
+    /** Adds a boolean parameter */
+    boolParameter(name: string, defaultValue: boolean = false): this {
+        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Bool, value: defaultValue });
+        return this;
+    }
+
+    /** Adds a trigger parameter */
+    triggerParameter(name: string): this {
+        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Trigger, value: false });
+        return this;
+    }
+
+    /**
+     * Adds a state to the controller. The first state added becomes the default state.
+     * @param name - Unique name for the state
+     * @param options - State configuration including clip, loop, speed
+     */
+    state(name: string, options: StateOptions): this {
+        this._states.push({ name, options, transitions: [] });
+        return this;
+    }
+
+    /**
+     * Adds a transition between two states.
+     * Use `"*"` as the source to create a transition from any state.
+     * Chain `.condition()` calls after this to add conditions.
+     * @param from - Source state name, or `"*"` for any-state transition
+     * @param to - Destination state name
+     * @param options - Transition configuration
+     */
+    transition(from: string, to: string, options?: TransitionOptions): this {
+        const t: BuilderTransition = { to, options: options ?? {}, conditions: [] };
+        if (from === "*") {
+            this._anyStateTransitions.push(t);
+        }
+        else {
+            const state = this._states.find(s => s.name === from);
+            if (!state) throw new Error(`AnimatorControllerBuilder: source state "${from}" not found. Add it with .state() first.`);
+            state.transitions.push(t);
+        }
+        this._lastTransition = t;
+        return this;
+    }
+
+    /**
+     * Adds a condition to the most recently added transition.
+     * Multiple conditions on the same transition are AND-ed together.
+     * @param parameter - Name of the parameter to evaluate
+     * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
+     * @param threshold - Comparison threshold for numeric conditions (default: 0)
+     */
+    condition(parameter: string, mode: ConditionMode, threshold: number = 0): this {
+        if (!this._lastTransition) throw new Error("AnimatorControllerBuilder: .condition() must be called after .transition()");
+        this._lastTransition.conditions.push({ parameter, mode, threshold });
+        return this;
+    }
+
+    /**
+     * Sets which state is the default/entry state.
+     * If not called, the first added state is used.
+     * @param name - Name of the state
+     */
+    defaultState(name: string): this {
+        this._defaultStateName = name;
+        return this;
+    }
+
+    /**
+     * Builds and returns the {@link AnimatorController}.
+     * Resolves all state name references to indices.
+     */
+    build(): AnimatorController {
+        const stateIndexMap = new Map<string, number>();
+        this._states.forEach((s, i) => stateIndexMap.set(s.name, i));
+
+        let defaultStateIndex = 0;
+        if (this._defaultStateName !== null) {
+            const idx = stateIndexMap.get(this._defaultStateName);
+            if (idx === undefined) throw new Error(`AnimatorControllerBuilder: default state "${this._defaultStateName}" not found`);
+            defaultStateIndex = idx;
+        }
+
+        const resolveTransition = (t: BuilderTransition): Transition => {
+            const destIndex = stateIndexMap.get(t.to);
+            if (destIndex === undefined) throw new Error(`AnimatorControllerBuilder: transition target "${t.to}" not found`);
+            return {
+                exitTime: t.options.exitTime ?? 1,
+                hasExitTime: t.options.hasExitTime ?? false,
+                duration: t.options.duration ?? 0,
+                offset: t.options.offset ?? 0,
+                hasFixedDuration: t.options.hasFixedDuration ?? false,
+                destinationState: destIndex,
+                conditions: t.conditions.map(c => ({
+                    parameter: c.parameter,
+                    mode: conditionModeToEnum(c.mode),
+                    threshold: c.threshold,
+                })),
+            };
+        };
+
+        const states: State[] = this._states.map((s, index) => {
+            const transitions: Transition[] = s.transitions.map(resolveTransition);
+
+            // Replicate any-state transitions onto every state (except self-targeting)
+            for (const anyT of this._anyStateTransitions) {
+                const destIndex = stateIndexMap.get(anyT.to);
+                if (destIndex === index) continue;
+                transitions.push(resolveTransition(anyT));
+            }
+
+            return {
+                name: s.name,
+                hash: index,
+                motion: {
+                    name: s.options.clip.name,
+                    clip: s.options.clip,
+                    isLooping: s.options.loop ?? false,
+                },
+                transitions,
+                behaviours: [],
+                speed: s.options.speed,
+                speedParameter: s.options.speedParameter,
+                cycleOffset: s.options.cycleOffset,
+                cycleOffsetParameter: s.options.cycleOffsetParameter,
+            };
+        });
+
+        const model: AnimatorControllerModel = {
+            name: this._name,
+            guid: new InstantiateIdProvider(Date.now()).generateUUID(),
+            parameters: this._parameters,
+            layers: [{
+                name: "Base Layer",
+                stateMachine: {
+                    defaultState: defaultStateIndex,
+                    states,
+                }
+            }],
+        };
+
+        return new AnimatorController(model);
+    }
+}

package/src/engine-components/AnimatorController.ts

@@ -5,6 +5,7 @@ import { AnimationUtils } from "../engine/engine_animation.js";
 import { Mathf } from "../engine/engine_math.js";
 import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
 import { assign, SerializationContext, TypeSerializer } from "../engine/engine_serialization_core.js";
+import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Context } from "../engine/engine_setup.js";
 import { isAnimationAction } from "../engine/engine_three_utils.js";
 import { TypeStore } from "../engine/engine_typestore.js";
@@ -12,6 +13,9 @@ import { deepClone, getParam } from "../engine/engine_utils.js";
 import type { AnimatorControllerModel, Condition, Parameter, State, Transition } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import { AnimatorConditionMode, AnimatorControllerParameterType, AnimatorStateInfo, createMotion, StateMachineBehaviour } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import type { Animator } from "./Animator.js";
+import { AnimatorControllerBuilder } from "./AnimatorController.builder.js";
+
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 
 const debug = getParam("debuganimatorcontroller");
 const debugRootMotion = getParam("debugrootmotion");
@@ -30,263 +34,6 @@ declare type CreateAnimatorControllerOptions = {
 }
 
 
-// #region AnimatorControllerBuilder
-
-/**
- * Configuration for an animation state in the builder
- */
-export declare type StateOptions = {
-    /** The animation clip for this state */
-    clip: AnimationClip;
-    /** Whether the animation should loop (default: false) */
-    loop?: boolean;
-    /** Base speed multiplier (default: 1) */
-    speed?: number;
-    /** Name of a float parameter to multiply with speed */
-    speedParameter?: string;
-    /** Normalized cycle offset 0-1 (default: 0) */
-    cycleOffset?: number;
-    /** Name of a float parameter to use as cycle offset */
-    cycleOffsetParameter?: string;
-}
-
-/**
- * Configuration for a transition in the builder
- */
-export declare type TransitionOptions = {
-    /** Duration of the crossfade in seconds (default: 0) */
-    duration?: number;
-    /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
-    exitTime?: number;
-    /** Whether the transition waits for exitTime before transitioning (default: false) */
-    hasExitTime?: boolean;
-    /** Normalized offset into the destination state's animation (default: 0) */
-    offset?: number;
-    /** Whether duration is in seconds (true) or normalized (false) (default: false) */
-    hasFixedDuration?: boolean;
-}
-
-/** String condition modes for the builder, mapped to {@link AnimatorConditionMode} */
-export type ConditionMode = "if" | "ifNot" | "greater" | "less" | "equals" | "notEqual";
-
-function conditionModeToEnum(mode: ConditionMode): AnimatorConditionMode {
-    switch (mode) {
-        case "if": return AnimatorConditionMode.If;
-        case "ifNot": return AnimatorConditionMode.IfNot;
-        case "greater": return AnimatorConditionMode.Greater;
-        case "less": return AnimatorConditionMode.Less;
-        case "equals": return AnimatorConditionMode.Equals;
-        case "notEqual": return AnimatorConditionMode.NotEqual;
-    }
-}
-
-type BuilderTransition = {
-    to: string;
-    options: TransitionOptions;
-    conditions: Array<{ parameter: string; mode: ConditionMode; threshold: number }>;
-};
-
-type BuilderState = {
-    name: string;
-    options: StateOptions;
-    transitions: BuilderTransition[];
-};
-
-/**
- * A fluent builder for creating {@link AnimatorController} instances from code.
- *
- * Use {@link AnimatorController.build} to create a new builder.
- *
- * @example
- * ```ts
- * const controller = AnimatorController.build("CharacterController")
- *     .floatParameter("Speed", 0)
- *     .triggerParameter("Jump")
- *     .state("Idle", { clip: idleClip, loop: true })
- *     .state("Walk", { clip: walkClip, loop: true })
- *     .state("Jump", { clip: jumpClip })
- *     .transition("Idle", "Walk", { duration: 0.25 })
- *         .condition("Speed", "greater", 0.1)
- *     .transition("Walk", "Idle", { duration: 0.25 })
- *         .condition("Speed", "less", 0.1)
- *     .transition("*", "Jump", { duration: 0.1 })
- *         .condition("Jump", "if")
- *     .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
- *     .build();
- * ```
- *
- * @category Animation and Sequencing
- * @group Utilities
- */
-export class AnimatorControllerBuilder {
-    private _name: string;
-    private _parameters: Parameter[] = [];
-    private _states: BuilderState[] = [];
-    private _anyStateTransitions: BuilderTransition[] = [];
-    private _defaultStateName: string | null = null;
-    private _lastTransition: BuilderTransition | null = null;
-
-    constructor(name?: string) {
-        this._name = name ?? "AnimatorController";
-    }
-
-    /** Adds a float parameter */
-    floatParameter(name: string, defaultValue: number = 0): this {
-        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Float, value: defaultValue });
-        return this;
-    }
-
-    /** Adds an integer parameter */
-    intParameter(name: string, defaultValue: number = 0): this {
-        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Int, value: defaultValue });
-        return this;
-    }
-
-    /** Adds a boolean parameter */
-    boolParameter(name: string, defaultValue: boolean = false): this {
-        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Bool, value: defaultValue });
-        return this;
-    }
-
-    /** Adds a trigger parameter */
-    triggerParameter(name: string): this {
-        this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Trigger, value: false });
-        return this;
-    }
-
-    /**
-     * Adds a state to the controller. The first state added becomes the default state.
-     * @param name - Unique name for the state
-     * @param options - State configuration including clip, loop, speed
-     */
-    state(name: string, options: StateOptions): this {
-        this._states.push({ name, options, transitions: [] });
-        return this;
-    }
-
-    /**
-     * Adds a transition between two states.
-     * Use `"*"` as the source to create a transition from any state.
-     * Chain `.condition()` calls after this to add conditions.
-     * @param from - Source state name, or `"*"` for any-state transition
-     * @param to - Destination state name
-     * @param options - Transition configuration
-     */
-    transition(from: string, to: string, options?: TransitionOptions): this {
-        const t: BuilderTransition = { to, options: options ?? {}, conditions: [] };
-        if (from === "*") {
-            this._anyStateTransitions.push(t);
-        }
-        else {
-            const state = this._states.find(s => s.name === from);
-            if (!state) throw new Error(`AnimatorControllerBuilder: source state "${from}" not found. Add it with .state() first.`);
-            state.transitions.push(t);
-        }
-        this._lastTransition = t;
-        return this;
-    }
-
-    /**
-     * Adds a condition to the most recently added transition.
-     * Multiple conditions on the same transition are AND-ed together.
-     * @param parameter - Name of the parameter to evaluate
-     * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
-     * @param threshold - Comparison threshold for numeric conditions (default: 0)
-     */
-    condition(parameter: string, mode: ConditionMode, threshold: number = 0): this {
-        if (!this._lastTransition) throw new Error("AnimatorControllerBuilder: .condition() must be called after .transition()");
-        this._lastTransition.conditions.push({ parameter, mode, threshold });
-        return this;
-    }
-
-    /**
-     * Sets which state is the default/entry state.
-     * If not called, the first added state is used.
-     * @param name - Name of the state
-     */
-    defaultState(name: string): this {
-        this._defaultStateName = name;
-        return this;
-    }
-
-    /**
-     * Builds and returns the {@link AnimatorController}.
-     * Resolves all state name references to indices.
-     */
-    build(): AnimatorController {
-        const stateIndexMap = new Map<string, number>();
-        this._states.forEach((s, i) => stateIndexMap.set(s.name, i));
-
-        let defaultStateIndex = 0;
-        if (this._defaultStateName !== null) {
-            const idx = stateIndexMap.get(this._defaultStateName);
-            if (idx === undefined) throw new Error(`AnimatorControllerBuilder: default state "${this._defaultStateName}" not found`);
-            defaultStateIndex = idx;
-        }
-
-        const resolveTransition = (t: BuilderTransition): Transition => {
-            const destIndex = stateIndexMap.get(t.to);
-            if (destIndex === undefined) throw new Error(`AnimatorControllerBuilder: transition target "${t.to}" not found`);
-            return {
-                exitTime: t.options.exitTime ?? 1,
-                hasExitTime: t.options.hasExitTime ?? false,
-                duration: t.options.duration ?? 0,
-                offset: t.options.offset ?? 0,
-                hasFixedDuration: t.options.hasFixedDuration ?? false,
-                destinationState: destIndex,
-                conditions: t.conditions.map(c => ({
-                    parameter: c.parameter,
-                    mode: conditionModeToEnum(c.mode),
-                    threshold: c.threshold,
-                })),
-            };
-        };
-
-        const states: State[] = this._states.map((s, index) => {
-            const transitions: Transition[] = s.transitions.map(resolveTransition);
-
-            // Replicate any-state transitions onto every state (except self-targeting)
-            for (const anyT of this._anyStateTransitions) {
-                const destIndex = stateIndexMap.get(anyT.to);
-                if (destIndex === index) continue;
-                transitions.push(resolveTransition(anyT));
-            }
-
-            return {
-                name: s.name,
-                hash: index,
-                motion: {
-                    name: s.options.clip.name,
-                    clip: s.options.clip,
-                    isLooping: s.options.loop ?? false,
-                },
-                transitions,
-                behaviours: [],
-                speed: s.options.speed,
-                speedParameter: s.options.speedParameter,
-                cycleOffset: s.options.cycleOffset,
-                cycleOffsetParameter: s.options.cycleOffsetParameter,
-            };
-        });
-
-        const model: AnimatorControllerModel = {
-            name: this._name,
-            guid: new InstantiateIdProvider(Date.now()).generateUUID(),
-            parameters: this._parameters,
-            layers: [{
-                name: "Base Layer",
-                stateMachine: {
-                    defaultState: defaultStateIndex,
-                    states,
-                }
-            }],
-        };
-
-        return new AnimatorController(model);
-    }
-}
-// #endregion
-
 // #region AnimatorController
 /**
  * Controls the playback of animations using a state machine architecture.
@@ -628,6 +375,9 @@ export class AnimatorController {
     /**
      * The data model describing the animation states and transitions.
      */
+    // @serializable marks this for the instantiate resolve system so it traverses into the model
+    // and remaps Object3D references (e.g. motion.clips[].node) to cloned objects.
+    @serializable()
     model: AnimatorControllerModel;
 
     /**
@@ -682,38 +432,6 @@ export class AnimatorController {
         }
     }
 
-    /**
-     * Creates a deep copy of this controller.
-     * Clones the model data but does not copy runtime state.
-     * 
-     * @returns A new AnimatorController instance with the same configuration
-     */
-    clone() {
-        if (typeof this.model === "string") {
-            console.warn("AnimatorController has not been resolved, can not create model from string", this.model);
-            return null;
-        }
-        if (debug) console.warn("AnimatorController clone()", this.model);
-        // clone runtime controller but dont clone clip or action
-        const clonedModel = deepClone(this.model, (_owner, _key, _value) => {
-            if (_value === null || _value === undefined) return true;
-            // dont clone three Objects
-            if (_value.type === "Object3D" || _value.isObject3D === true) return false;
-            // dont clone AnimationAction
-            if (isAnimationAction(_value)) { //.constructor.name === "AnimationAction") {
-                // console.log(_value);
-                return false;
-            }
-            // dont clone AnimationClip
-            if (_value["tracks"] !== undefined) return false;
-            // when assigned __concreteInstance during serialization
-            if (_value instanceof AnimatorController) return false;
-            return true;
-        }) as AnimatorControllerModel;
-        console.assert(clonedModel !== this.model);
-        const controller = new AnimatorController(clonedModel);
-        return controller;
-    }
 
     /**
      * Updates the controller's state machine and animations.
@@ -749,8 +467,18 @@ export class AnimatorController {
     get activeState(): State | undefined { return this._activeState; }
 
     constructor(model: AnimatorControllerModel) {
-        this.model = model;
-        if (debug) console.log(this);
+        // Deep-clone the model so each AnimatorController owns its own copy.
+        // This ensures independent parameter state and allows the instantiate
+        // resolve system to remap Object3D refs (e.g. motion.clips[].node) per instance.
+        // The predicate skips Object3D (keeps references) and AnimationClip/AnimationAction (shared resources).
+        this.model = deepClone(model, (_owner, _key, _value) => {
+            if (_value === null || _value === undefined) return true;
+            if (_value.isObject3D === true) return false;
+            if (isAnimationAction(_value)) return false;
+            if (_value["tracks"] !== undefined) return false; // AnimationClip
+            if (_value instanceof AnimatorController) return false;
+            return true;
+        }) as AnimatorControllerModel;
     }
 
     private _activeStates: State[] = [];