@needle-tools/engine 5.0.2 → 5.1.0-canary.87c4c44

package/src/engine/postprocessing/types.ts

@@ -0,0 +1,43 @@
+import type { EffectComposer } from "postprocessing";
+import type { ToneMapping } from "three";
+import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+/**
+ * Minimal interface for a postprocessing effect as seen by the core stack.
+ * Implemented by `PostProcessingEffect` in engine-components.
+ */
+export interface IPostProcessingEffect {
+    readonly active: boolean;
+    readonly enabled: boolean;
+    /** When true, this effect is a tonemapping effect. The core stack uses this to detect tonemapping-only scenarios. */
+    readonly isToneMapping?: boolean;
+}
+
+/**
+ * Extended interface for tonemapping effects.
+ * When ONLY tonemapping effects are in the stack, the core applies tonemapping
+ * directly to the renderer instead of creating a full postprocessing pipeline.
+ */
+export interface ITonemappingEffect extends IPostProcessingEffect {
+    readonly isToneMapping: true;
+    /** The three.js ToneMapping enum value to apply to the renderer */
+    readonly threeToneMapping: ToneMapping;
+    /** The exposure value to apply to the renderer */
+    readonly toneMappingExposure: number;
+}
+
+/**
+ * Interface for the pipeline builder that manages the EffectComposer.
+ * Implemented by `PostProcessingHandler` in engine-components.
+ */
+export interface IPostProcessingHandler {
+    readonly composer: EffectComposer | ThreeEffectComposer | null;
+    readonly hasSmaaEffect: boolean;
+    multisampling: number;
+    adaptivePixelRatio: boolean;
+
+    apply(effects: IPostProcessingEffect[]): Promise<void>;
+    unapply(dispose?: boolean): void;
+    updateAdaptivePixelRatio(): void;
+    dispose(): void;
+}

package/src/engine/webcomponents/WebXRButtons.ts

@@ -6,7 +6,7 @@ import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { ButtonsFactory } from "./buttons.js";
 import { getIconElement } from "./icons.js";
 import { NeedleMenu } from "./needle menu/needle-menu.js";
-import { getOrCreateQuicklookHandler,type IQuicklookHandler } from "./quicklook-handler.js";
+import { getOrCreateQuicklookHandler, type IQuicklookHandler } from "./quicklook-handler.js";
 
 // TODO: move these buttons into their own web components so their logic is encapsulated (e.g. the CSS animation when a xr session is requested)
 
@@ -120,10 +120,27 @@ export class WebXRButtonFactory {
 
         button.classList.add("webxr-button");
         button.dataset["needle"] = "webxr-ar-button";
-        button.innerText = "Enter AR";
-        button.prepend(getIconElement("view_in_ar"))
         button.title = "Click to start an AR session";
-        button.addEventListener("click", () => NeedleXRSession.start(mode, init));
+        const setDefaultText = () => {
+            button.innerText = "Enter AR";
+            button.prepend(getIconElement("view_in_ar"));
+        };
+        setDefaultText();
+
+        let tapAgainTimeout: ReturnType<typeof setTimeout>;
+        button.addEventListener("click", () => {
+
+            NeedleXRSession.start(mode, init);
+
+            if (DeviceUtilities.isiOS() && !DeviceUtilities.isVisionOS()) {
+                setTimeout(() => {
+                    button.innerHTML = "Tap again";
+                    button.prepend(getIconElement("view_in_ar"));
+                    clearTimeout(tapAgainTimeout);
+                    tapAgainTimeout = setTimeout(setDefaultText, 4000);
+                }, 500);
+            }
+        });
         NeedleMenu.setElementPriority(button, arButtonPriority);
         this.updateSessionSupported(button, mode);
         this.listenToXRSessionState(button, mode);

package/src/engine/webcomponents/icons.ts

@@ -1,6 +1,5 @@
 import { Texture } from "three";
 
-
 const fontname = "Material Symbols Outlined";
 
 /** Returns a HTML element containing an icon. Using https://fonts.google.com/icons   
@@ -21,7 +20,10 @@ export function getIconElement(str: string): HTMLElement {
     span.setAttribute("aria-label", str + " icon");
     span.setAttribute("aria-hidden", "true");
     fontReady(fontname).then(res => {
-        if (res) span.style.visibility = "";
+        if (res) {
+            span.style.visibility = "";
+            span.innerText = str; // re-assign, otherise more_vert doesnt show up. Maybe because of layout restructuring on mobile
+        }
         else {
             if (str === "more_vert") {
                 span.style.visibility = "";
@@ -31,7 +33,7 @@ export function getIconElement(str: string): HTMLElement {
                 span.style.display = "none";
             }
         }
-    })
+    });
     return span;
 }
 

package/src/engine/xr/NeedleXRSession.ts

@@ -79,13 +79,9 @@ function getDOMOverlayElement(domElement: HTMLElement) {
 }
 
 
-
 handleSessionGranted();
 async function handleSessionGranted() {
 
-    // await delay(400);
-
-
     let defaultMode: XRSessionMode = "immersive-vr";
 
     try {
@@ -109,8 +105,6 @@ async function handleSessionGranted() {
         return;
     }
 
-    // showBalloonMessage("sessiongranted: " + defaultMode);
-
     // TODO: asap session granted doesnt handle the pre-room yet
     if (getParam("debugasap")) {
         let asapSession = globalThis["needle:XRSession"] as XRSession | undefined | Promise<XRSession>;
@@ -149,7 +143,6 @@ async function handleSessionGranted() {
         navigator.xr?.addEventListener('sessiongranted', async () => {
             // enableSpatialConsole(true);
 
-
             const lastSessionMode = sessionStorage.getItem("needle_xr_session_mode") as XRSessionMode;
             const lastSessionInit = sessionStorage.getItem("needle_xr_session_init") ?? null;
             const init = lastSessionInit ? JSON.parse(lastSessionInit) : null;
@@ -331,7 +324,18 @@ export class NeedleXRSession implements INeedleXRSession {
      * @param mode The XRSessionMode to check if it is supported
      * @returns true if the browser supports the given XRSessionMode
      */
-    static isSessionSupported(mode: XRSessionMode) { return this.xrSystem?.isSessionSupported(mode).catch(err => { if (debug) console.error(err); return false }) ?? Promise.resolve(false); }
+    static isSessionSupported(mode: XRSessionMode) {
+        // We cache the result of the session support check to avoid unnecessary calls to isSessionSupported. This is especially important for user input events that internally run session support checks during onclick where the event must be resolved as fast as possible.
+        if (this._sessionSupportedCache[mode] !== undefined) {
+            return Promise.resolve(this._sessionSupportedCache[mode]);
+        }
+        return this.xrSystem?.isSessionSupported(mode).then(supported => {
+            this._sessionSupportedCache[mode] = supported;
+            return supported;
+        }).catch(err => { if (debug) console.error(err); return false }) ?? Promise.resolve(false);
+    }
+
+    private static _sessionSupportedCache: { [mode in XRSessionMode]?: boolean } = {};
 
     private static _currentSessionRequest?: Promise<XRSession>;
     private static _activeSession: NeedleXRSession | null;
@@ -466,10 +470,11 @@ export class NeedleXRSession implements INeedleXRSession {
         // handle iOS platform where "immersive-ar" is special:
         // - we either launch QuickLook
         // - or forward to the Needle App Clip experience for WebXR AR
-        // TODO: should we add a separate mode (e.g. "AR")? https://linear.app/needle/issue/NE-5303
         if (DeviceUtilities.isiOS()) {
 
-            const arSupported = await this.isARSupported().catch(() => false);
+            // IMPORTANT: on iOS we should have prefetched immersive-ar support already on app start (this is done in xrInit()) - if not then clicking the Enter AR button for the very first time does not immediately open the AppClip overlay.  
+            // Without an async await here the overlay *does* however open even when clicking for the very first time. (To test this you need to clear the local experience cache on device)
+            const arSupported = this._sessionSupportedCache["immersive-ar"] ?? await this.isARSupported();
 
             // On VisionOS, we use QuickLook for AR experiences; no AppClip support for now.
             if (DeviceUtilities.isVisionOS() && !arSupported && (mode === "ar" || mode === "immersive-ar")) {
@@ -489,11 +494,14 @@ export class NeedleXRSession implements INeedleXRSession {
 
                 this.invokeSessionRequestStart("immersive-ar", init);
 
+                // if we are in an iframe, we need to navigate the top window
+                const topWindow = window.top || window;
+                const originalUrl = topWindow.location.href;
+
                 // Forward to the AppClip experience (Using the apple.com url the appclip overlay shows immediately)
                 // const url =`https://appclip.needle.tools/ar?url=${(location.href)}`;
                 const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
                 url.searchParams.set("url", location.href);
-
                 const urlStr = url.toString();
 
                 Telemetry.sendEvent(Context.Current, "xr", {
@@ -502,16 +510,43 @@ export class NeedleXRSession implements INeedleXRSession {
                     url: urlStr,
                 });
 
-                // if we are in an iframe, we need to navigate the top window
-                const topWindow = window.top || window;
                 try {
                     console.debug("iOS device detected - opening Needle App Clip for AR experience", { mode, init, url });
+
+                    // Prewarm the appclip by opening the URL
+                    // BUT on safari triggering this with multiple URLs causes the
+                    // Browser to show the dialogue AGAIN in the background
+                    // SO: we don't do it here...
+                    const key = "appclip-prewarm:" + new URL(url).origin;
+                    const allowMultipleNavigations = sessionStorage.getItem(key) === null;
+                    if (allowMultipleNavigations) {
+                        const secondUrl = new URL(url);
+                        secondUrl.searchParams.set("prewarm", "1");
+                        // eslint-disable-next-line xss/no-location-href-assign
+                        topWindow.location.href = secondUrl.toString();
+
+                        // wait a bit to give the device time to fetch the app clip metadata - this seems to fix the double tap issue (500 ms seem to work)
+                        await new Promise(res => setTimeout(res, 300));
+                    }
+
                     // navigate to app clip url but keep the current url in history, open in same tab
                     // eslint-disable-next-line xss/no-location-href-assign
                     topWindow.location.href = urlStr;
+
+                    if (allowMultipleNavigations && !DeviceUtilities.isSafari()) {
+                        setTimeout(() => {
+                            const url2 = new URL(url);
+                            url2.searchParams.set("prewarm", "1");
+                            // eslint-disable-next-line xss/no-location-href-assign
+                            topWindow.location.href = url2.toString();
+                        }, 500);
+                    }
+
+                    sessionStorage.setItem(key, "1");
+
                 }
                 catch (e) {
-                    console.warn("Error navigating to AppClip " + urlStr + "\n", e);
+                    console.warn(`Error navigating to AppClip ${urlStr}\n`, e);
                     // if top window navigation fails and we are in an iframe, we try to navigate the top window directly
                     const weAreInIframe = window !== window.top;
                     if (weAreInIframe) {
@@ -531,7 +566,7 @@ export class NeedleXRSession implements INeedleXRSession {
         }
 
         if (mode === "quicklook") {
-            console.warn("QuickLook mode is only supported on iOS devices");
+            console.error("QuickLook mode is only supported on iOS devices.");
             return null;
         }
 

package/src/engine/xr/init.ts

@@ -0,0 +1,56 @@
+import { isDevEnvironment, showBalloonMessage } from "../debug/index.js";
+import { DeviceUtilities, setParamWithoutReload } from "../engine_utils.js";
+import { NeedleXRSession } from "./NeedleXRSession.js";
+
+/**
+ * Initialize XR subsystem. Called from `initEngine()`
+ */
+export function initXR() {
+    // Prewarm AR support check
+    NeedleXRSession.isARSupported();
+
+
+
+    if (DeviceUtilities.isiOS()) {
+
+        if (isDevEnvironment()) {
+            const randomParameterValue = Date.now().toString();
+            setParamWithoutReload("debug_appclip", randomParameterValue);
+            showBalloonMessage("iOS appclip debug: " + randomParameterValue);
+        }
+
+        // Prefetch
+        const url = new URL("https://appclip.apple.com/id?p=tools.needle.launch-app.Clip");
+        url.searchParams.set("url", location.href);
+        const urlStr = url.toString();
+        fetch(urlStr, { method: "HEAD", mode: "no-cors" }).catch(() => {
+            // appclip prefetch - to get metadata faster on iOS devices, this seems to fix the double tap issue when opening the appclip for AR sessions.
+        });
+
+        try {
+            // We add the meta tag here to preload app clip card data for iOS.
+            const meta = window.top?.document.querySelector('meta[name="apple-itunes-app"]');
+            if(!meta) {
+                const metaTag = document.createElement("meta");
+                metaTag.name = "apple-itunes-app";
+                metaTag.content = "app-id=6757205152, app-clip-bundle-id=tools.needle.launch-app.Clip, app-clip-display=card";
+                window.top?.document.head.appendChild(metaTag);
+            }
+        }
+        catch (e) {
+            console.warn("Error adding apple-itunes-app meta tag for appclip support\n", e);
+        }
+
+        try {
+            // We preconnect to apple here to speed up the appclip meta request for the first click. NOT sure if necessary and working but can't hurt either?
+            const topWindow = window.top || window;
+            const preconnectMeta = topWindow.document.createElement("link");
+            preconnectMeta.rel = "preconnect";
+            preconnectMeta.href = url.toString();
+            topWindow.document.head.appendChild(preconnectMeta);
+        }
+        catch (e) {
+            console.warn("Error adding preconnect link for appclip.apple.com\n", e);
+        }
+    }
+}

package/src/engine-components/AnimationUtils.ts

@@ -1,29 +1,19 @@
 import { Object3D } from "three";
 
-const $objectAnimationKey = Symbol("objectIsAnimatedData");
+import { AnimationUtils } from "../engine/engine_animation.js";
 
 /** Internal method - This marks an object as being animated. Make sure to always call isAnimated=false if you stop animating the object
  * @param obj The object to mark
  * @param isAnimated Whether the object is animated or not
+ * @deprecated Use {@link AnimationUtils.setObjectAnimated} instead
  */
 export function setObjectAnimated(obj: Object3D, animatedBy: object, isAnimated: boolean) {
-    if (!obj) return;
-    if (obj[$objectAnimationKey] === undefined) {
-        if (!isAnimated) return;
-        obj[$objectAnimationKey] = new Set<object>();
-    }
-
-    const set = obj[$objectAnimationKey] as Set<object>;
-    if (isAnimated) {
-        set.add(animatedBy);
-    }
-    else if (set.has(animatedBy))
-        set.delete(animatedBy);
+    return AnimationUtils.setObjectAnimated(obj, animatedBy, isAnimated);
 }
 
-/** Get is the object is currently animated. Currently used by the Animator to check if a timeline animationtrack is actively animating an object */
+/** Get is the object is currently animated. Currently used by the Animator to check if a timeline animationtrack is actively animating an object 
+ * @deprecated Use {@link AnimationUtils.getObjectAnimated} instead
+*/
 export function getObjectAnimated(obj: Object3D): boolean {
-    if (!obj) return false;
-    const set = obj[$objectAnimationKey] as Set<object>;
-    return set !== undefined && set.size > 0;
+    return AnimationUtils.getObjectAnimated(obj) || false;
 }

package/src/engine-components/AnimatorController.ts

@@ -9,27 +9,13 @@ import { Context } from "../engine/engine_setup.js";
 import { isAnimationAction } from "../engine/engine_three_utils.js";
 import { TypeStore } from "../engine/engine_typestore.js";
 import { deepClone, getParam } from "../engine/engine_utils.js";
-import type { AnimatorControllerModel, Condition, State, Transition } from "../engine/extensions/NEEDLE_animator_controller_model.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";
 
 const debug = getParam("debuganimatorcontroller");
 const debugRootMotion = getParam("debugrootmotion");
 
-/**
- * Generates a hash code for a string
- * @param str - The string to hash
- * @returns A numeric hash value
- */
-function stringToHash(str): number {
-    let hash = 0;
-    for (let i = 0; i < str.length; i++) {
-        const char = str.charCodeAt(i);
-        hash = ((hash << 5) - hash) + char;
-        hash = hash & hash;
-    }
-    return hash;
-}
 
 /**
  * Configuration options for creating an AnimatorController
@@ -43,15 +29,275 @@ declare type CreateAnimatorControllerOptions = {
     transitionDuration?: number,
 }
 
-/** 
+
+// #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.
  * 
  * The AnimatorController manages animation states, transitions between states,
  * and parameters that affect those transitions. It is used by the {@link Animator}
  * component to control animation behavior on 3D models.
  * 
- * Use the static method {@link AnimatorController.createFromClips} to create
- * an animator controller from a set of animation clips.
+ * Use {@link AnimatorController.build} to fluently create a controller with parameters,
+ * states, transitions, and conditions. For simple sequential playback,
+ * use {@link AnimatorController.createFromClips}.
  * 
  * @category Animation and Sequencing
  * @group Utilities
@@ -119,6 +365,30 @@ export class AnimatorController {
         return controller;
     }
 
+    /**
+     * Creates a new {@link AnimatorControllerBuilder} for fluently constructing a controller with
+     * parameters, states, transitions, and conditions.
+     *
+     * @param name - Optional name for the controller
+     * @returns A new builder instance
+     *
+     * @example
+     * ```ts
+     * const ctrl = AnimatorController.build("MyController")
+     *     .floatParameter("Speed")
+     *     .state("Idle", { clip: idleClip, loop: true })
+     *     .state("Walk", { clip: walkClip, loop: true })
+     *     .transition("Idle", "Walk", { duration: 0.25 })
+     *         .condition("Speed", "greater", 0.1)
+     *     .transition("Walk", "Idle", { duration: 0.25 })
+     *         .condition("Speed", "less", 0.1)
+     *     .build();
+     * ```
+     */
+    static build(name?: string): AnimatorControllerBuilder {
+        return new AnimatorControllerBuilder(name);
+    }
+
     /**
      * Plays an animation state by name or hash.
      *