@needle-tools/engine 4.2.5 → 4.3.0-alpha.1

package/src/engine-components/DragControls.ts

@@ -18,8 +18,10 @@ import { SyncedTransform } from "./SyncedTransform.js";
 import type { IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
 import { ObjectRaycaster } from "./ui/Raycaster.js";
 
+/** Enable debug visualization and logging for DragControls by using the URL parameter `?debugdrag`. */
 const debug = getParam("debugdrag");
 
+/** Buffer to store currently active DragControls components */
 const dragControlsBuffer: DragControls[] = [];
 
 /**
@@ -34,7 +36,7 @@ export enum DragMode {
     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 adjusted dynamically while dragging. */
+    /** The drag plane is snapped to surfaces in the scene while dragging. */
     SnapToSurfaces = 4,
     /** Don't allow dragging the object */
     None = 5,
@@ -42,18 +44,24 @@ export enum DragMode {
 
 /**
  * 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 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
      */
     public static get HasAnySelected(): boolean { return this._active > 0; }
     private static _active: number = 0;
 
-    /** @returns a list of DragControl components that are currently active */
+    /** 
+     * Retrieves a list of all DragControl components that are currently dragging objects.
+     * @returns Array of currently active DragControls components
+     */
     public static get CurrentlySelected() {
         dragControlsBuffer.length = 0;
         for (const dc of this._instances) {
@@ -63,51 +71,71 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         }
         return dragControlsBuffer;
     }
-    /** Currently active and enabled DragControls components */
+    /** Registry of currently active and enabled DragControls components */
     private static _instances: DragControls[] = [];
 
-
-
-    // dragPlane (floor, object, view)
-    // snap to surface (snap orientation?)
-    // two-handed drag (scale, rotate, move)
-    // keep upright (no tilt)
-
-    /** How and where the object is dragged along. */
+    /** 
+     * Determines how and where the object is dragged along. Different modes include
+     * dragging along a plane, attached to the pointer, or following surface normals.
+     */
     @serializable()
     public dragMode: DragMode = DragMode.DynamicViewAngle;
 
-    /** Snap dragged objects to a XYZ grid – 0 means: no snapping. */
+    /** 
+     * Snaps dragged objects to a 3D grid with the specified resolution.
+     * Set to 0 to disable snapping.
+     */
     @serializable()
     public snapGridResolution: number = 0.0;
 
-    /** Keep the original rotation of the dragged object. */
+    /** 
+     * When true, maintains the original rotation of the dragged object while moving it.
+     * When false, allows the object to rotate freely during dragging.
+     */
     @serializable()
     public keepRotation: boolean = true;
 
-    /** How and where the object is dragged along while dragging in XR. */
+    /** 
+     * 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.
+     */
     @serializable()
     public xrDragMode: DragMode = DragMode.Attached;
 
-    /** Keep the original rotation of the dragged object while dragging in XR. */
+    /** 
+     * When true, maintains the original rotation of the dragged object during XR dragging.
+     * When false, allows the object to rotate freely during XR dragging.
+     */
     @serializable()
     public xrKeepRotation: boolean = false;
 
-    /** Accelerate dragging objects closer / further away when in XR */
+    /** 
+     * 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.
+     */
     @serializable()
     public xrDistanceDragFactor: number = 1;
 
-    /** When enabled, draws a line from the dragged object downwards to the next raycast hit. */
+    /** 
+     * 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.
+     */
     @serializable()
     public showGizmo: boolean = false;
 
-    /** The currently dragged object (if any) */
+    /** 
+     * 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() {
         return this._targetObject;
     }
 
     /**
-     * Use to update the object that is being dragged by the DragControls
+     * 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) {
         this._targetObject = obj;
@@ -133,8 +161,8 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
                 this._rigidbody[wasKinematicKey] = false;
             }
         }
-
     }
+    
     private _rigidbody: Rigidbody | null = null;
 
     // future:
@@ -182,11 +210,20 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         DragControls._instances = DragControls._instances.filter(i => i !== this);
     }
 
+    /**
+     * 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(_obj: Object3D | null = null) {
         return this.context.connection.allowEditing;
     }
 
-    /** @internal */
+    /** 
+     * 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) {
         if (!this.allowEdit(this.gameObject)) return;
         if (evt.mode !== "screen") return;
@@ -202,12 +239,20 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         this.context.domElement.style.cursor = 'pointer';
     }
 
-    /** @internal */
+    /** 
+     * 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) {
         if (this._isDragging || this._potentialDragStartEvt !== null) args.use();
     }
 
-    /** @internal */
+    /** 
+     * 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) {
         if (!this.allowEdit(this.gameObject)) return;
         if (evt.mode !== "screen") return;
@@ -215,7 +260,11 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         this.context.domElement.style.cursor = 'auto';
     }
 
-    /** @internal */
+    /** 
+     * 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) {
         if (!this.allowEdit(this.gameObject)) return;
         if (args.used) return;
@@ -262,7 +311,11 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         }
     }
 
-    /** @internal */
+    /** 
+     * Handles pointer up events. Finalizes or cancels the drag operation.
+     * @param args Pointer event data containing information about the interaction
+     * @internal
+     */
     onPointerUp(args: PointerEventData) {
         if (debug) Gizmos.DrawLabel(args.point ?? this.gameObject.worldPosition, "POINTERUP:" + args.pointerId + ", " + args.button, .03, 3);
         if (!this.allowEdit(this.gameObject)) return;
@@ -293,9 +346,12 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         }
     }
 
-    /** @internal */
+    /**
+     * Updates the drag operation every frame. Processes pointer movement, accumulates drag distance
+     * and triggers drag start once there's enough movement.
+     * @internal
+     */
     update(): void {
-
         for (const handler of this._dragHandlers.values()) {
             if (handler.collectMovementInfo) handler.collectMovementInfo();
             // TODO this doesn't make sense, we should instead just use the max here
@@ -324,7 +380,12 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             this.onAnyDragUpdate();
     }
 
-    /** Called when the first pointer starts dragging on this object. Not called for subsequent pointers on the same object. */
+    /** 
+     * 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(evt: PointerEventData) {
         if (!evt || !evt.object) return;
 
@@ -356,7 +417,10 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             this._draggingRigidbodies.push(...rbs);
     }
 
-    /** Called each frame as long as any pointer is dragging this object. */
+    /** 
+     * Called each frame as long as any pointer is dragging this object.
+     * Updates visuals and keeps rigidbodies awake during the drag.
+     */
     private onAnyDragUpdate() {
         if (!this._dragHelper) return;
         this._dragHelper.showGizmo = this.showGizmo;
@@ -373,7 +437,11 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         InstancingUtil.markDirty(object);
     }
 
-    /** Called when the last pointer has been removed from this object. */
+    /** 
+     * 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(evt: PointerEventData | null) {
         if (!this || !this._isDragging) return;
         this._isDragging = false;
@@ -399,7 +467,10 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     }
 }
 
-/** Common interface for pointer handlers (single touch and multi touch) */
+/** 
+ * Common interface for pointer handlers (single touch and multi touch).
+ * Defines methods for tracking movement and managing target objects during drag operations.
+ */
 interface IDragHandler {
     /** Used to determine if a drag has happened for this handler */
     getTotalMovement?(): Vector3;
@@ -414,7 +485,10 @@ interface IDragHandler {
     onDragUpdate?(numberOfPointers: number): void;
 }
 
-/** Handles two touch points affecting one object. Allows movement, scale and rotation of objects. */
+/** 
+ * Handles two touch points affecting one object. 
+ * Enables multi-touch interactions that allow movement, scaling, and rotation of objects.
+ */
 class MultiTouchDragHandler implements IDragHandler {
 
     handlerA: DragPointerHandler;
@@ -660,15 +734,27 @@ class MultiTouchDragHandler implements IDragHandler {
 }
 
 
-/** Handles a single pointer on an object. DragPointerHandlers are created on pointer enter, 
- * help with determining if there's actually a drag, and then perform operations based on spatial pointer data.
+/** 
+ * Handles a single pointer on an object. 
+ * DragPointerHandlers manage determining if a drag operation has started, tracking pointer movement,
+ * and controlling object translation based on the drag mode.
  */
 class DragPointerHandler implements IDragHandler {
 
-    /** Absolute movement of the pointer. Used for determining if a motion/drag is happening. 
-     * This is in world units, so very small for screens (near-plane space change) */
+    /** 
+     * Returns the accumulated movement of the pointer in world units.
+     * Used for determining if enough motion has occurred to start a drag.
+     */
     getTotalMovement(): Vector3 { return this._totalMovement; }
+    
+    /** 
+     * Returns the object that follows the pointer during dragging operations.
+     */
     get followObject(): GameObject { return this._followObject; }
+    
+    /**
+     * Returns the point where the pointer initially hit the object in local space.
+     */
     get hitPointInLocalSpace(): Vector3 { return this._hitPointInLocalSpace; }
 
     private context: Context;
@@ -1249,18 +1335,28 @@ class DragPointerHandler implements IDragHandler {
     }
 }
 
-/** Currently does _only_ provide visuals support for DragControls operations.
- * Previously it also provided the actual drag functionality, but that has been moved to DragControls for now.
+/** 
+ * Provides visual helper elements for DragControls.
+ * Shows where objects will be placed and their relation to surfaces below them.
  */
 class LegacyDragVisualsHelper {
 
+    /** Controls whether visual helpers like lines and markers are displayed */
     showGizmo: boolean = true;
+    
+    /** When true, drag plane alignment changes based on view angle */
     useViewAngle: boolean = true;
 
+    /**
+     * Checks if there is a currently selected object being visualized
+     */
     public get hasSelected(): boolean {
         return this._selected !== null && this._selected !== undefined;
     }
 
+    /**
+     * Returns the currently selected object being visualized, if any
+     */
     public get selected(): Object3D | null {
         return this._selected;
     }