@needle-tools/engine/lib/engine-components/DragControls.d.ts

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.

import { Object3D } from "three";
import { Behaviour } from "./Component.js";
import type { IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
/**
 * The DragMode determines how an object is dragged around in the scene.
 */
export declare enum DragMode {
    /** Object stays at the same horizontal plane as it started. Commonly used for objects on the floor */
    XZPlane = 0,
    /** Object is dragged as if it was attached to the pointer. In 2D, that means it's dragged along the camera screen plane. In XR, it's dragged by the controller/hand. */
    Attached = 1,
    /** Object is dragged along the initial raycast hit normal. */
    HitNormal = 2,
    /** Combination of XZ and Screen based on the viewing angle. Low angles result in Screen dragging and higher angles in XZ dragging. */
    DynamicViewAngle = 3,
    /** The drag plane is snapped to surfaces in the scene while dragging. */
    SnapToSurfaces = 4,
    /** Don't allow dragging the object */
    None = 5
}
/**
 * DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space).
 * Debug mode can be enabled with the URL parameter `?debugdrag`, which shows visual helpers and logs drag operations.
 *
 * @category Interactivity
 * @group Components
 */
export declare class DragControls extends Behaviour implements IPointerEventHandler {
    /**
     * Checks if any DragControls component is currently active with selected objects
     * @returns True if any DragControls component is currently active
     */
    static get HasAnySelected(): boolean;
    private static _active;
    /**
     * Retrieves a list of all DragControl components that are currently dragging objects.
     * @returns Array of currently active DragControls components
     */
    static get CurrentlySelected(): DragControls[];
    /** Registry of currently active and enabled DragControls components */
    private static _instances;
    /**
     * Determines how and where the object is dragged along. Different modes include
     * dragging along a plane, attached to the pointer, or following surface normals.
     */
    dragMode: DragMode;
    /**
     * Snaps dragged objects to a 3D grid with the specified resolution.
     * Set to 0 to disable snapping.
     */
    snapGridResolution: number;
    /**
     * When true, maintains the original rotation of the dragged object while moving it.
     * When false, allows the object to rotate freely during dragging.
     */
    keepRotation: boolean;
    /**
     * Determines how and where the object is dragged along while dragging in XR.
     * Uses a separate setting from regular drag mode for better XR interaction.
     */
    xrDragMode: DragMode;
    /**
     * When true, maintains the original rotation of the dragged object during XR dragging.
     * When false, allows the object to rotate freely during XR dragging.
     */
    xrKeepRotation: boolean;
    /**
     * Multiplier that affects how quickly objects move closer or further away when dragging in XR.
     * Higher values make distance changes more pronounced.
     * This is similar to mouse acceleration on a screen.
     */
    xrDistanceDragFactor: number;
    /**
     * When enabled, draws a visual line from the dragged object downwards to the next raycast hit,
     * providing visual feedback about the object's position relative to surfaces below it.
     */
    showGizmo: boolean;
    /**
     * Returns the object currently being dragged by this DragControls component, if any.
     * @returns The object being dragged or null if no object is currently dragged
     */
    get draggedObject(): Object3D<import("three").Object3DEventMap> | null;
    /**
     * Updates the object that is being dragged by the DragControls.
     * This can be used to change the target during a drag operation.
     * @param obj The new object to drag, or null to stop dragging
     */
    setTargetObject(obj: Object3D | null): void;
    private _rigidbody;
    /** The object to be dragged – we pass this to handlers when they are created */
    private _targetObject;
    private _dragHelper;
    private static lastHovered;
    private _draggingRigidbodies;
    private _potentialDragStartEvt;
    private _dragHandlers;
    private _totalMovement;
    /** A marker is attached to components that are currently interacted with, to e.g. prevent them from being deleted. */
    private _marker;
    private _isDragging;
    private _didDrag;
    /** @internal */
    awake(): void;
    /** @internal */
    start(): void;
    /** @internal */
    onEnable(): void;
    /** @internal */
    onDisable(): void;
    /**
     * Checks if editing is allowed for the current networking connection.
     * @param _obj Optional object to check edit permissions for
     * @returns True if editing is allowed
     */
    private allowEdit;
    /**
     * Handles pointer enter events. Sets the cursor style and tracks the hovered object.
     * @param evt Pointer event data containing information about the interaction
     * @internal
     */
    onPointerEnter?(evt: PointerEventData): void;
    /**
     * Handles pointer movement events. Marks the event as used if dragging is active.
     * @param args Pointer event data containing information about the movement
     * @internal
     */
    onPointerMove?(args: PointerEventData): void;
    /**
     * Handles pointer exit events. Resets the cursor style when the pointer leaves a draggable object.
     * @param evt Pointer event data containing information about the interaction
     * @internal
     */
    onPointerExit?(evt: PointerEventData): void;
    /**
     * Handles pointer down events. Initiates the potential drag operation if conditions are met.
     * @param args Pointer event data containing information about the interaction
     * @internal
     */
    onPointerDown(args: PointerEventData): void;
    /**
     * Handles pointer up events. Finalizes or cancels the drag operation.
     * @param args Pointer event data containing information about the interaction
     * @internal
     */
    onPointerUp(args: PointerEventData): void;
    /**
     * Updates the drag operation every frame. Processes pointer movement, accumulates drag distance
     * and triggers drag start once there's enough movement.
     * @internal
     */
    update(): void;
    /**
     * Called when the first pointer starts dragging on this object.
     * Sets up network synchronization and marks rigidbodies for dragging.
     * Not called for subsequent pointers on the same object.
     * @param evt Pointer event data that initiated the drag
     */
    private onFirstDragStart;
    /**
     * Called each frame as long as any pointer is dragging this object.
     * Updates visuals and keeps rigidbodies awake during the drag.
     */
    private onAnyDragUpdate;
    /**
     * Called when the last pointer has been removed from this object.
     * Cleans up drag state and applies final velocities to rigidbodies.
     * @param evt Pointer event data for the last pointer that was lifted
     */
    private onLastDragEnd;
}