@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
99 lines (98 loc) • 3.53 kB
TypeScript
import { Intersection } from "three";
import { type IRaycastOptions, RaycastOptions } from "../../engine/engine_physics.js";
import { Behaviour } from "../Component.js";
/**
* [ObjectRaycaster](https://engine.needle.tools/docs/api/ObjectRaycaster) Base class for raycasters that detect pointer interactions.
* Derive from this class to create custom raycasting logic.
*
* **Built-in raycasters:**
* - {@link ObjectRaycaster} - Raycasts against 3D objects
* - {@link GraphicRaycaster} - Raycasts against UI elements
* - {@link SpatialGrabRaycaster} - Sphere overlap for XR grab
*
* **Important:** If you override `awake`, `onEnable`, or `onDisable`,
* call the base class methods to ensure proper registration with {@link EventSystem}.
*
* @category Interactivity
* @group Components
* @see {@link EventSystem} for the event dispatch system
*/
export declare abstract class Raycaster extends Behaviour {
awake(): void;
onEnable(): void;
onDisable(): void;
abstract performRaycast(_opts?: IRaycastOptions | RaycastOptions | null): Intersection[] | null;
}
/**
* ObjectRaycaster enables pointer interactions with 3D objects.
* Add this component to any object that needs click/hover detection.
*
* **Usage:**
* Objects with ObjectRaycaster will receive pointer events when
* they implement interfaces like {@link IPointerClickHandler}.
*
* **Note:**
* In older Needle Engine versions the ObjectRaycaster was required to be added to the Scene.
* This is no longer the case - the EventSystem will automatically handle raycasts.
*
*
* @category Interactivity
* @group Components
* @see {@link IPointerClickHandler} for click events
* @see {@link DragControls} for drag interactions
*/
export declare class ObjectRaycaster extends Raycaster {
private targets;
private raycastHits;
ignoreSkinnedMeshes: boolean;
start(): void;
performRaycast(opts?: IRaycastOptions | RaycastOptions | null): Intersection[] | null;
}
/**
* GraphicRaycaster enables pointer interactions with UI elements.
* Add this to a {@link Canvas} or UI hierarchy to enable button clicks,
* hover effects, and other UI interactions.
*
* **Requirements:**
* - Must be on the same object as a Canvas or on a parent
* - UI elements need proper RectTransform setup
*
* @example Enable UI interaction
* ```ts
* // Add to Canvas object
* canvas.addComponent(GraphicRaycaster);
* // Now buttons and other UI elements will respond to clicks
* ```
*
* @summary Raycaster for UI elements
* @category User Interface
* @group Components
* @see {@link Canvas} for UI root
* @see {@link Button} for clickable UI
* @see {@link EventSystem} for event handling
*/
export declare class GraphicRaycaster extends ObjectRaycaster {
constructor();
}
/**
* SpatialGrabRaycaster enables direct grab interactions in VR/AR.
* Uses sphere overlap detection around the controller/hand position
* to allow grabbing objects by reaching into them.
*
* **Features:**
* - Active only during XR sessions
* - Can be globally disabled via `SpatialGrabRaycaster.allow`
* - Works alongside ray-based interaction
*
* @category XR
* @group Components
* @see {@link WebXR} for XR session management
* @see {@link DragControls} for object manipulation
*/
export declare class SpatialGrabRaycaster extends Raycaster {
/**
* Use to disable SpatialGrabRaycaster globally
*/
static allow: boolean;
performRaycast(_opts?: IRaycastOptions | RaycastOptions | null): Intersection[] | null;
}