@needle-tools/engine 5.1.0-alpha → 5.1.0-alpha.1

package/src/engine/engine_physics_rapier.ts

@@ -46,16 +46,21 @@ const $colliderRigidbody = Symbol("rigidbody");
 
 declare const NEEDLE_USE_RAPIER: boolean;
 globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
-if (debugPhysics)
-    console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
 
-if (NEEDLE_USE_RAPIER) {
-    ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
-        if (debugPhysics)
-            console.log("Register rapier physics backend")
-        evt.context.physics.engine = new RapierPhysics(evt.context);
-        // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
-    });
+/** Register the Rapier physics backend. Called from {@link initEngine}
+ * to ensure it runs regardless of tree-shaking. */
+export function initPhysics() {
+    if (debugPhysics)
+        console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
+
+    if (NEEDLE_USE_RAPIER) {
+        ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
+            if (debugPhysics)
+                console.log("Register rapier physics backend")
+            evt.context.physics.engine = new RapierPhysics(evt.context);
+            // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
+        });
+    }
 }
 
 

package/src/engine/engine_utils.ts

@@ -184,12 +184,12 @@ export function setOrAddParamsToUrl(url: URLSearchParams, paramName: string, par
 
 /** Adds an entry to the browser history. Internally uses `window.history.pushState` */
 export function pushState(title: string, urlParams: URLSearchParams, state?: any) {
-    window.history.pushState(state, title, "?" + urlParams.toString());
+    window.history.pushState(state, title, "?" + urlParams.toString() + window.location.hash);
 }
 
 /** Replaces the current entry in the browser history. Internally uses `window.history.replaceState` */
 export function setState(title: string, urlParams: URLSearchParams, state?: any) {
-    window.history.replaceState(state, title, "?" + urlParams.toString());
+    window.history.replaceState(state, title, "?" + urlParams.toString() + window.location.hash);
 }
 
 // for room id

package/src/engine/xr/NeedleXRSession.ts

@@ -32,7 +32,7 @@ declare type NeedleXRFrame = XRFrame & { fillPoses?: FillPosesFunction };
  * Use `args.xr` to access the NeedleXRSession */
 export type NeedleXREventArgs = { readonly xr: NeedleXRSession }
 export type SessionChangedEvt = (args: NeedleXREventArgs) => void;
-export type SessionRequestedEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit }) => void;
+export type SessionRequestedEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit, readonly context: Context }) => void;
 export type SessionRequestedEndEvent = (args: { readonly mode: XRSessionMode, readonly init: XRSessionInit, newSession: XRSession | null }) => void;
 
 /** Result of a XR hit-test
@@ -492,7 +492,7 @@ export class NeedleXRSession implements INeedleXRSession {
 
             if (!arSupported && (mode === "immersive-ar" || mode === "ar")) {
 
-                this.invokeSessionRequestStart("immersive-ar", init);
+                this.invokeSessionRequestStart("immersive-ar", init, context ?? Context.Current);
 
                 // if we are in an iframe, we need to navigate the top window
                 const topWindow = window.top || window;
@@ -662,7 +662,7 @@ export class NeedleXRSession implements INeedleXRSession {
                 script.onBeforeXR(mode, init);
             }
         }
-        this.invokeSessionRequestStart(mode, init);
+        this.invokeSessionRequestStart(mode, init, context ?? Context.Current);
         if (debug) showBalloonMessage("Requesting " + mode + " session (" + Date.now() + ")");
         Telemetry.sendEvent(Context.Current, "xr", {
             action: "session_request",
@@ -693,9 +693,9 @@ export class NeedleXRSession implements INeedleXRSession {
         return session;
     }
 
-    private static invokeSessionRequestStart(mode: XRSessionMode, init: XRSessionInit) {
+    private static invokeSessionRequestStart(mode: XRSessionMode, init: XRSessionInit, context: Context) {
         for (const listener of this._sessionRequestStartListeners) {
-            listener({ mode, init });
+            listener({ mode, init, context });
         }
     }
     private static invokeSessionRequestEnd(mode: XRSessionMode, init: XRSessionInit, session: XRSession | null | undefined | void) {

package/src/engine/xr/events.ts

@@ -1,4 +1,5 @@
-import type { NeedleXRSession } from "./NeedleXRSession.js";
+import { NeedleXRSession } from "./NeedleXRSession.js";
+import type { Context } from "../engine_context.js";
 
 export declare type XRSessionEventArgs = { session: NeedleXRSession };
 
@@ -14,11 +15,13 @@ const onXRSessionStartListeners: ((evt: XRSessionEventArgs) => void)[] = [];
  *   console.log("XR session started", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
 export function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void) {
     if (onXRSessionStartListeners.indexOf(fn) === -1) {
         onXRSessionStartListeners.push(fn);
     }
+    return () => offXRSessionStart(fn);
 }
 /**
  * Remove a listener for when an XR session starts
@@ -51,11 +54,13 @@ const onXRSessionEndListeners: ((evt: XRSessionEventArgs) => void)[] = [];
  *    console.log("XR session ended", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
 export function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void) {
     if (onXRSessionEndListeners.indexOf(fn) === -1) {
         onXRSessionEndListeners.push(fn);
     }
+    return () => offXRSessionEnd(fn);
 };
 
 /**
@@ -78,6 +83,44 @@ export function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void) {
 }
 
 
+export declare type XRSessionRequestEventArgs = { readonly mode: XRSessionMode, readonly init: XRSessionInit, readonly context: Context };
+
+/**
+ * Add a listener that fires before an XR session is requested.
+ * Use this to modify the session init options, e.g. to add optional features like `camera-access`.
+ * @param fn The function to call before the XR session is requested
+ * @example
+ * ```js
+ * onBeforeXRSession((args) => {
+ *   args.init.optionalFeatures ??= [];
+ *   args.init.optionalFeatures.push("camera-access");
+ * });
+ * ```
+ * @return A function to remove the listener
+ */
+export function onBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void) {
+    if (onBeforeXRSessionListeners.indexOf(fn) === -1) {
+        onBeforeXRSessionListeners.push(fn);
+        // Delegate to NeedleXRSession which owns the actual invocation
+        NeedleXRSession.onSessionRequestStart(fn);
+    }
+    return () => offBeforeXRSession(fn);
+}
+
+/**
+ * Remove a listener for before an XR session is requested
+ * @param fn The function to remove from the listeners
+ */
+export function offBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void) {
+    const index = onBeforeXRSessionListeners.indexOf(fn);
+    if (index !== -1) {
+        onBeforeXRSessionListeners.splice(index, 1);
+        NeedleXRSession.offSessionRequestStart(fn);
+    }
+}
+
+const onBeforeXRSessionListeners: ((args: XRSessionRequestEventArgs) => void)[] = [];
+
 /**
  * @internal
  * Invoke the XRSessionStart event

package/src/engine/xr/init.ts

@@ -1,4 +1,3 @@
-import { isDevEnvironment, showBalloonMessage } from "../debug/index.js";
 import { DeviceUtilities, setParamWithoutReload } from "../engine_utils.js";
 import { NeedleXRSession } from "./NeedleXRSession.js";
 
@@ -13,12 +12,6 @@ export function initXR() {
 
     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);

package/src/engine-components/AnimatorController.ts

@@ -9,7 +9,7 @@ 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";
 
@@ -30,16 +30,274 @@ 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.
  * 
  * 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
@@ -107,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.
      *