@needle-tools/engine 5.1.0-alpha → 5.1.0-canary.0d9f44e

package/dist/needle-engine.d.ts

@@ -84,6 +84,7 @@ import { RawShaderMaterial } from 'three';
 import { Ray } from 'three';
 import { Raycaster } from 'three';
 import { Scene } from 'three';
+import { SceneData } from '../../plugins/types/needle-bindings.d.ts';
 import { ShaderMaterial } from 'three';
 import { ShapeJSON } from 'three.quarks';
 import { SkinnedMesh } from 'three';
@@ -918,8 +919,9 @@ export declare enum AnimatorConditionMode {
  * 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
@@ -934,6 +936,27 @@ export declare class AnimatorController {
      * @returns A new AnimatorController instance
      */
     static createFromClips(clips: AnimationClip[], options?: CreateAnimatorControllerOptions): AnimatorController;
+    /**
+     * 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;
     /**
      * Plays an animation state by name or hash.
      *
@@ -1125,6 +1148,84 @@ export declare class AnimatorController {
     private rootMotionHandler?;
 }
 
+/**
+ * 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 declare class AnimatorControllerBuilder {
+    private _name;
+    private _parameters;
+    private _states;
+    private _anyStateTransitions;
+    private _defaultStateName;
+    private _lastTransition;
+    constructor(name?: string);
+    /** Adds a float parameter */
+    floatParameter(name: string, defaultValue?: number): this;
+    /** Adds an integer parameter */
+    intParameter(name: string, defaultValue?: number): this;
+    /** Adds a boolean parameter */
+    boolParameter(name: string, defaultValue?: boolean): this;
+    /** Adds a trigger parameter */
+    triggerParameter(name: string): 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;
+    /**
+     * 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;
+    /**
+     * 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): 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;
+    /**
+     * Builds and returns the {@link AnimatorController}.
+     * Resolves all state name references to indices.
+     */
+    build(): AnimatorController;
+}
+
 export declare type AnimatorControllerModel = {
     name: string;
     guid: string;
@@ -2092,7 +2193,7 @@ export declare namespace BlobStorage {
     /**
      * Generates an md5 hash from a given buffer
      * @param buffer The buffer to hash
-     * @returns The md5 hash
+     * @returns The md5 hash as a hex string
      */
     export function hashMD5(buffer: ArrayBuffer): string;
     export function hashMD5_Base64(buffer: ArrayBuffer): string;
@@ -4006,6 +4107,9 @@ export declare type Condition = {
     threshold: number;
 };
 
+/** String condition modes for the builder, mapped to {@link AnimatorConditionMode} */
+export declare type ConditionMode = "if" | "ifNot" | "greater" | "less" | "equals" | "notEqual";
+
 /** Events regarding the websocket connection (e.g. when the connection opens) */
 export declare enum ConnectionEvents {
     ConnectionInfo = "connection-start-info"
@@ -4355,6 +4459,30 @@ export declare class Context implements IContext {
      * The main camera of the scene - this camera is used for rendering
      * Use `setCurrentCamera` for updating the main camera.
      */
+    /**
+     * Typed proxy providing direct access to scene components by node and component name.
+     * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
+     * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
+     *
+     * Each property access traverses the live scene graph on demand — no caching, always fresh.
+     * This is a convenience shorthand for `getComponent` lookups; the same result can be
+     * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
+     *
+     * @example
+     * // Toggle auto-rotate on the orbit camera
+     * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+     *
+     * @example
+     * // Change the background color
+     * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
+     *
+     * @example
+     * // Equivalent manual approach (without sceneData)
+     * const node = ctx.scene.getObjectByName("Camera");
+     * const orbit = getComponent(node, OrbitControls);
+     * if (orbit) orbit.autoRotate = true;
+     */
+    get sceneData(): SceneData;
     get mainCamera(): Camera_2;
     /** Set the main camera of the scene. If set to null the camera of the {@link mainCameraComponent} will be used - this camera is used for rendering */
     set mainCamera(cam: Camera_2 | null);
@@ -4376,8 +4504,12 @@ export declare class Context implements IContext {
     connection: NetworkConnection;
     /**  @deprecated AssetDatabase is deprecated */
     assets: AssetDatabase;
-    /** The main light in the scene */
-    mainLight: ILight | null;
+    /** All registered lights in the scene, maintained by the Light component */
+    readonly lights: Set<ILight>;
+    /** The brightest registered directional light, or null if none are registered
+     * @see lights
+     */
+    get mainLight(): ILight | null;
     /** @deprecated Use sceneLighting */
     get rendererData(): RendererData;
     /** Access the scene lighting manager to control lighting settings in the context */
@@ -7027,6 +7159,20 @@ export declare function getPeerOptions(): PeerJSOption | undefined;
 
 export declare function getResourceUserCount(object: object): number | undefined;
 
+/**
+ * Returns a lazily-resolved proxy typed as {@link SceneData}.
+ * The proxy is cached per context — each context gets exactly one instance.
+ *
+ * Shape mirrors the generated `needle-bindings.gen.d.ts`:
+ *   ctx.sceneData.MyGlb.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.MyGlb.Camera.$object  // → THREE.Camera
+ *   ctx.sceneData.MyGlb.UI.Button.$components.Button  // → Needle Button component
+ *
+ * GLB name is ignored at runtime (scene is already loaded).
+ * Node lookup starts at the scene root.
+ */
+export declare function getSceneData(ctx: IContext): SceneData;
+
 export declare function getTempColor(color?: Color): Color;
 
 /**
@@ -7357,13 +7503,20 @@ export declare class GraphicRaycaster extends ObjectRaycaster {
  * Utility class to perform various graphics operations like copying textures to canvas
  */
 export declare class Graphics {
-    private static readonly planeGeometry;
-    private static readonly renderer;
-    private static readonly perspectiveCam;
-    private static readonly orthographicCam;
-    private static readonly scene;
-    private static readonly blitMaterial;
-    private static readonly mesh;
+    private static _planeGeometry;
+    private static _renderer;
+    private static _perspectiveCam;
+    private static _orthographicCam;
+    private static _scene;
+    private static _blitMaterial;
+    private static _mesh;
+    private static get planeGeometry();
+    private static get renderer();
+    private static get perspectiveCam();
+    private static get orthographicCam();
+    private static get scene();
+    private static get blitMaterial();
+    private static get mesh();
     /**
      * Copy a texture to a new texture
      * @param texture the texture to copy
@@ -7516,6 +7669,7 @@ export declare class GroundProjectedEnv extends Component {
     updateProjection(): void;
     private _blurrynessShader;
     private _lastBlurriness;
+    private updateProjectionMaterial;
     private updateBlurriness;
 }
 
@@ -7826,6 +7980,9 @@ export declare class HoverAnimation extends Component {
     private playHover;
 }
 
+/** SSR-safe base class for web components. */
+declare const HTMLElementBase: typeof HTMLElement;
+
 export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
     addClip?(clip: AnimationClip): any;
@@ -8085,6 +8242,8 @@ declare interface ILayoutGroup extends IComponent {
 export declare interface ILight extends IComponent {
     intensity: number;
     color: Color;
+    /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
+    readonly type: "directional" | "point" | "spot";
 }
 
 declare interface ILightDataRegistry {
@@ -8301,6 +8460,10 @@ export declare class InheritVelocityModule {
     applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
 }
 
+/** Register the Rapier physics backend. Called from {@link initEngine}
+ * to ensure it runs regardless of tree-shaking. */
+export declare function initPhysics(): void;
+
 /**
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
  * Access via `this.context.input` from any component.
@@ -9591,6 +9754,9 @@ declare const enum KeyboardEnumType {
     KeyPressed = "keypress"
 }
 
+/** SSR-safe base class for keyboard events. */
+declare const KeyboardEventBase: typeof KeyboardEvent;
+
 declare type KeyboardEventListener = (evt: NEKeyboardEvent) => void;
 
 declare type KeyboardEventNames = EnumToPrimitiveUnion<KeyboardEnumType>;
@@ -9715,10 +9881,13 @@ declare type LifecycleMethodOptions = {
  */
 export declare class Light extends Component implements ILight {
     /**
-     * The type of light (spot, directional, point, etc.)
-     * Can not be changed at runtime.
+     * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
+     * Implements {@link ILight.type}. Can not be changed at runtime.
      */
-    private type;
+    get type(): ILight["type"];
+    /** Numeric LightType serialized from Unity/Blender — converts to string on write */
+    set type(value: LightType | ILight["type"]);
+    private _type;
     /**
      * The maximum distance the light affects.
      * Only applicable for spot and point lights.
@@ -9798,6 +9967,19 @@ export declare class Light extends Component implements ILight {
     get shadowResolution(): number;
     set shadowResolution(val: number);
     private _shadowResolution?;
+    /**
+     * Number of shadow cascade levels (only used when `useCascades` is true)
+     */
+    cascades: number;
+    /**
+     * Cascade split mode (only used when `useCascades` is true):
+     * - `practical` — balanced (default, recommended)
+     * - `logarithmic` — more resolution close up
+     * - `uniform` — equal splits
+     */
+    cascadeMode: "practical" | "logarithmic" | "uniform";
+    private _csm?;
+    private _csmHelper?;
     /**
      * Whether this light's illumination is entirely baked into lightmaps
      */
@@ -9819,16 +10001,12 @@ export declare class Light extends Component implements ILight {
     awake(): void;
     onEnable(): void;
     onDisable(): void;
+    onBeforeRender(): void;
     /**
      * Creates the appropriate three.js light based on the configured light type
      * and applies all settings like shadows, intensity, and color.
      */
     createLight(): void;
-    /**
-     * Coroutine that updates the main light reference in the context
-     * if this directional light should be the main light
-     */
-    updateMainLightRoutine(): Generator<undefined, void, unknown>;
     /**
      * Controls whether the renderer's shadow map type can be changed when soft shadows are used
      */
@@ -9844,6 +10022,11 @@ export declare class Light extends Component implements ILight {
      * When the rig is scaled, world-space distances change proportionally
      * causing lights to appear brighter or dimmer due to distance falloff. */
     private applyXRScale;
+    /**
+     * Creates and initializes a CSM instance for this directional light.
+     * CSM manages its own cascade DirectionalLights internally.
+     */
+    private createCSM;
     /**
      * Configures a directional light by adding and positioning its target
      * @param dirLight The directional light to set up
@@ -9877,6 +10060,25 @@ declare enum LightShadows {
     Soft = 2
 }
 
+/**
+ * Defines the type of light in a scene.
+ * @see {@link Light} for configuring light properties and behavior
+ */
+declare enum LightType {
+    /** Spot light that emits light in a cone shape */
+    Spot = 0,
+    /** Directional light that emits parallel light rays in a specific direction */
+    Directional = 1,
+    /** Point light that emits light in all directions from a single point */
+    Point = 2,
+    /** Area light */
+    Area = 3,
+    /** Rectangle shaped area light that only affects baked lightmaps and light probes */
+    Rectangle = 3,
+    /** Disc shaped area light that only affects baked lightmaps and light probes */
+    Disc = 4
+}
+
 export declare class LimitVelocityOverLifetimeModule {
     enabled: boolean;
     dampen: number;
@@ -10864,6 +11066,25 @@ export declare type MouseButtonName = "left" | "right" | "middle";
 
 /* Excluded from this release type: nameofFactory */
 
+/**
+ * Global proxy for the primary Needle Engine context.
+ * Resolves lazily on property access via `ContextRegistry.Current` —
+ * safe to import at module level, including in SSR environments
+ * (returns a silent error proxy when no context is active).
+ *
+ * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
+ * components, button handlers, or vanilla JS) instead of threading `ctx` around.
+ *
+ * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
+ *
+ * @example
+ * import { needle } from "@needle-tools/engine";
+ * button.onclick = () => {
+ *   needle.sceneData.Camera.OrbitControls.autoRotate = true;
+ * };
+ */
+export declare const needle: IContext;
+
 declare class NEEDLE_components implements GLTFLoaderPlugin {
     get name(): string;
     exportContext: {
@@ -10997,7 +11218,7 @@ export { NEEDLE_progressive }
  * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
  * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
-export declare class NeedleButtonElement extends HTMLElement {
+export declare class NeedleButtonElement extends HTMLElementBase {
     #private;
     static observedAttributes: string[];
     constructor();
@@ -11137,7 +11358,7 @@ export declare namespace NeedleEngineModelLoader {
  * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
  * @see {@link NeedleMenu} for the built-in menu configuration component
  */
-export declare class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
+export declare class NeedleEngineWebComponent extends HTMLElementBase implements INeedleEngineComponent {
     static get observedAttributes(): string[];
     get loadingProgress01(): number;
     get loadingFinished(): boolean;
@@ -12110,7 +12331,7 @@ export declare class NeedleXRUtils {
     }): void;
 }
 
-export declare class NEKeyboardEvent extends KeyboardEvent {
+export declare class NEKeyboardEvent extends KeyboardEventBase {
     source?: Event;
     constructor(type: InputEvents, source: Event, init: KeyboardEventInit);
     stopImmediatePropagation(): void;
@@ -12134,7 +12355,7 @@ export declare class NEKeyboardEvent extends KeyboardEvent {
  * @see {@link Input} for the input management system
  * @see {@link PointerType} for available pointer types
  */
-export declare class NEPointerEvent extends PointerEvent {
+export declare class NEPointerEvent extends PointerEventBase {
     /**
      * Spatial input data
      */
@@ -12900,6 +13121,12 @@ export declare class ObjectUtils {
     private static applyDefaultObjectOptions;
 }
 
+/**
+ * Remove a listener for before an XR session is requested
+ * @param fn The function to remove from the listeners
+ */
+export declare function offBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): void;
+
 /* Excluded from this release type: OffscreenCanvasExt */
 
 /**
@@ -13004,6 +13231,21 @@ export declare function onAfterRender(cb: LifecycleMethod, opts?: LifecycleMetho
  * */
 export declare function onBeforeRender(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
 
+/**
+ * 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 declare function onBeforeXRSession(fn: (args: XRSessionRequestEventArgs) => void): () => void;
+
 /**
  * Register a callback before the engine context is cleared.
  * This happens if e.g. `<needle-engine src>` changes
@@ -13225,8 +13467,9 @@ export declare function onUpdate(cb: LifecycleMethod, opts?: LifecycleMethodOpti
  *    console.log("XR session ended", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
-export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): void;
+export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): () => void;
 
 /**
  * Add a listener for when an XR session starts
@@ -13238,8 +13481,9 @@ export declare function onXRSessionEnd(fn: (evt: XRSessionEventArgs) => void): v
  *   console.log("XR session started", evt);
  * });
  * ```
+ * @returns A function to remove the listener
  */
-export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
+export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void): () => void;
 
 /**
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
@@ -14943,6 +15187,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          PointerMove = "pointermove"
      }
 
+     /** SSR-safe base class for pointer events. */
+     declare const PointerEventBase: typeof PointerEvent;
+
      /** [PointerEventData](https://engine.needle.tools/docs/api/PointerEventData) This pointer event data object is passed to all event receivers that are currently active
       * It contains hit information if an object was hovered or clicked
       * If the event is received in onPointerDown or onPointerMove, you can call `setPointerCapture` to receive onPointerMove events even when the pointer has left the object until you call `releasePointerCapture` or when the pointerUp event happens
@@ -16830,6 +17077,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      declare type ScaleClipType = "linear" | "spring";
 
+     export { SceneData }
+
      export declare class SceneLightSettings extends Component {
          ambientMode: AmbientMode;
          ambientLight?: Color;
@@ -17977,6 +18226,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare type SessionRequestedEvent = (args: {
          readonly mode: XRSessionMode;
          readonly init: XRSessionInit;
+         readonly context: Context;
      }) => void;
 
      export declare function setActive(go: Object3D, active: boolean | number): boolean;
@@ -19614,6 +19864,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
          instance?: StateMachineBehaviour;
      };
 
+     /**
+      * 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;
+     };
+
      declare type StickName = "xr-standard-thumbstick" | "xr-standard-touchpad";
 
      export declare class StreamEndedEvent {
@@ -20712,6 +20980,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
          Animation = 3
      }
 
+     /**
+      * 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;
+     };
+
      export declare class TriggerBuilder {
          private static __sceneStartTrigger?;
          static sceneStartTrigger(): TriggerModel;
@@ -23231,6 +23515,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          session: NeedleXRSession;
      };
 
+     export declare type XRSessionRequestEventArgs = {
+         readonly mode: XRSessionMode;
+         readonly init: XRSessionInit;
+         readonly context: Context;
+     };
+
      export declare class XRState {
          static Global: XRState;
          Mask: XRStateFlag;