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

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';
@@ -2192,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;
@@ -4458,6 +4459,25 @@ 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.
      */
+    /**
+     * 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.
+     *
+     * 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
+     * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+     *
+     * @example
+     * // Change the background color
+     * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
+     */
+    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);
@@ -4479,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 */
@@ -7130,6 +7156,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;
 
 /**
@@ -7460,13 +7500,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
@@ -7930,6 +7977,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;
@@ -8189,6 +8239,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 {
@@ -9699,6 +9751,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>;
@@ -9823,10 +9878,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.
@@ -9932,11 +9990,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
      */
@@ -9985,6 +10038,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;
@@ -10972,6 +11044,21 @@ export declare type MouseButtonName = "left" | "right" | "middle";
 
 /* Excluded from this release type: nameofFactory */
 
+/**
+ * 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.
+ *
+ * Safe to import at module level, including in SSR environments.
+ * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
+ *
+ * @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: {
@@ -11105,7 +11192,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();
@@ -11245,7 +11332,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;
@@ -12218,7 +12305,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;
@@ -12242,7 +12329,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
      */
@@ -15074,6 +15161,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
@@ -16961,6 +17051,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;