@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.deec6e4

package/dist/needle-engine.d.ts

@@ -3623,7 +3623,7 @@ declare class ColorSerializer extends TypeSerializer {
     onSerialize(data: any): any | void;
 }
 
-export declare const colorSerializer: ColorSerializer;
+export declare let colorSerializer: ColorSerializer;
 
 /**
  * Utility method to check if two materials were created from the same glTF material
@@ -4097,7 +4097,7 @@ declare class ComponentSerializer extends TypeSerializer {
     findObjectForGuid(guid: string, root: Object3D): any;
 }
 
-export declare const componentSerializer: ComponentSerializer;
+export declare let componentSerializer: ComponentSerializer;
 
 declare type ComponentType = "button" | "thumbstick" | "squeeze" | "touchpad";
 
@@ -4460,13 +4460,14 @@ export declare class Context implements IContext {
      * 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.
+     * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
+     * Types are generated automatically from your GLB files when the dev server starts.
      *
-     * 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)`.
+     * You can store references to objects or components for later use.
+     * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
+     * in which case stored references may become stale.
+     *
+     * @experimental This API may change in future versions.
      *
      * @example
      * // Toggle auto-rotate on the orbit camera
@@ -4475,12 +4476,6 @@ export declare class Context implements IContext {
      * @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;
@@ -4504,15 +4499,21 @@ 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.
+     * @see mainLight for accessing the main directional light in the scene
+     */
+    readonly lights: ILight[];
+    /** The brightest registered directional light, or null if none are registered
+     * @see lights
+     */
+    get mainLight(): ILight | null;
     /** @deprecated Use sceneLighting */
-    get rendererData(): RendererData;
+    private get rendererData();
     /** Access the scene lighting manager to control lighting settings in the context */
-    sceneLighting: RendererData;
-    addressables: Addressables;
-    lightmaps: ILightDataRegistry;
-    players: PlayerViewManager;
+    readonly sceneLighting: RendererData;
+    readonly addressables: Addressables;
+    readonly lightmaps: ILightDataRegistry;
+    readonly players: PlayerViewManager;
     /** Access the LODs manager to control LOD behavior in the context */
     readonly lodsManager: LODsManager;
     /** Access the needle menu to add or remove buttons to the menu element */
@@ -5919,19 +5920,6 @@ export declare class EnvironmentScene extends Scene {
     createAreaLightMaterial(intensity: number): MeshBasicMaterial;
 }
 
-export declare const euler: EulerSerializer;
-
-declare class EulerSerializer extends TypeSerializer {
-    constructor();
-    onDeserialize(data: any, _context: SerializationContext): Euler | undefined;
-    onSerialize(data: any, _context: SerializationContext): {
-        x: any;
-        y: any;
-        z: any;
-        order: any;
-    };
-}
-
 /**
  * EventList manages a list of callbacks that can be invoked together.
  * Used for Unity-style events that can be configured in the editor (Unity or Blender).
@@ -6064,7 +6052,7 @@ declare class EventListSerializer extends TypeSerializer {
     onDeserialize(data: EventListData, context: SerializationContext): EventList<any> | undefined | null;
 }
 
-export declare const eventListSerializer: EventListSerializer;
+export declare let eventListSerializer: EventListSerializer;
 
 /**
  * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
@@ -7159,16 +7147,13 @@ 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.
  *
- * Accessing a property traverses the scene graph on demand:
- * - First level  → find Object3D by node name
- * - Second level → getComponent by component name (via TypeStore)
- * - Third level  → read/write a field on the real component 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
  *
- * If a node or component is not found, property accesses log a warning
- * instead of throwing, so chained access never crashes.
- *
- * @example
- * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+ * GLB name is ignored at runtime (scene is already loaded).
+ * Node lookup starts at the scene root.
  */
 export declare function getSceneData(ctx: IContext): SceneData;
 
@@ -8241,6 +8226,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 {
@@ -8457,10 +8444,20 @@ export declare class InheritVelocityModule {
     applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
 }
 
+/* Excluded from this release type: initAddressableSerializers */
+
+/** Register all builtin serializers and prototype patches.
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
+ * when the package declares `sideEffects: false`.
+ */
+export declare function initBuiltinSerializers(): void;
+
 /** Register the Rapier physics backend. Called from {@link initEngine}
  * to ensure it runs regardless of tree-shaking. */
 export declare function initPhysics(): void;
 
+/* Excluded from this release type: initVolumeParameterSerializer */
+
 /**
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
  * Access via `this.context.input` from any component.
@@ -9878,10 +9875,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.
@@ -9987,11 +9987,6 @@ export declare class Light extends Component implements ILight {
      * 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
      */
@@ -10040,6 +10035,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;
@@ -11028,15 +11042,13 @@ 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).
+ * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
+ * Use it in React/Svelte/Vue components, button handlers, or plain JavaScript.
  *
- * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
- * components, button handlers, or vanilla JS) instead of threading `ctx` around.
+ * Safe to import at module level, including in SSR environments.
+ * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
- * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
+ * @experimental This API may change in future releases.
  *
  * @example
  * import { needle } from "@needle-tools/engine";
@@ -13039,7 +13051,7 @@ declare class ObjectSerializer extends TypeSerializer {
     onDeserialize(data: ObjectData | string | null, context: SerializationContext): Object3D<Object3DEventMap> | Component | null | undefined;
 }
 
-export declare const objectSerializer: ObjectSerializer;
+export declare let objectSerializer: ObjectSerializer;
 
 declare type ObjectToNodeMap = {
     [uuid: string]: number;
@@ -23507,6 +23519,35 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
+declare module 'three' {
+    interface SkinnedMesh {
+        staticGenerator?: StaticGeometryGenerator;
+        staticGeometry?: BufferGeometry;
+        staticGeometryLastUpdate?: number;
+    }
+    interface Mesh {
+        acceleratedRaycast?: any;
+    }
+    interface SkinnedMesh {
+        /** @deprecated use autoUpdateMeshBvhInterval */
+        autoUpdateMeshBVH?: boolean;
+        /**
+         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
+         * @default undefined (disabled)
+         */
+        autoUpdateMeshBvhInterval?: number;
+        bvhNeedsUpdate?: boolean;
+    }
+}
+
+
+declare module 'three' {
+    interface Vector3 {
+        slerp(end: Vector3, t: number): Vector3;
+    }
+}
+
+
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -23645,32 +23686,3 @@ declare module 'three' {
         contains(object: Object3D | null | undefined): boolean;
     }
 }
-
-
-declare module 'three' {
-    interface Vector3 {
-        slerp(end: Vector3, t: number): Vector3;
-    }
-}
-
-
-declare module 'three' {
-    interface SkinnedMesh {
-        staticGenerator?: StaticGeometryGenerator;
-        staticGeometry?: BufferGeometry;
-        staticGeometryLastUpdate?: number;
-    }
-    interface Mesh {
-        acceleratedRaycast?: any;
-    }
-    interface SkinnedMesh {
-        /** @deprecated use autoUpdateMeshBvhInterval */
-        autoUpdateMeshBVH?: boolean;
-        /**
-         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
-         * @default undefined (disabled)
-         */
-        autoUpdateMeshBvhInterval?: number;
-        bvhNeedsUpdate?: boolean;
-    }
-}