feat(core) Support target position and quaternion offset in DistanceGrabbable.

zjm-meta · meta-codesync[bot] · commit 3eea7a831523 · 2025-12-15T15:40:47.000-08:00
Summary:
Added the support of target position and quaternion offset configuration in DistanceGrabbable. Support the target pos and quat calculation in Distance Handle and use lerp and slerp for the movement control.

Rev2: Add snap support when the object arrives at the input source and have it rest when the pointer is up.

Reviewed By: felixtrz

Differential Revision: D89073193

fbshipit-source-id: ea3867aee125d43a093ed250dd65ef538c554ad0
diff --git a/examples/grab/index.html b/examples/grab/index.html
@@ -13,7 +13,7 @@
       name="viewport"
       content="width=device-width, initial-scale=1, shrink-to-fit=no"
     />
-    <title>IWSDK Boilerplate</title>
+    <title>IWSDK Grab Example</title>
   </head>
   <body style="margin: 0">
     <div id="scene-container"></div>
diff --git a/examples/grab/metaspatial/Composition/Main.scene b/examples/grab/metaspatial/Composition/Main.scene
@@ -81,7 +81,15 @@ entities:
       tag: earth
     - components:
         com.iwsdk.components.DistanceGrabbable:
-          {}
+          targetPositionOffset:
+            - 0.100000001
+            - 0
+            - 0
+          targetQuaternionOffset:
+            - 0
+            - 120
+            - 0
+            - 1
         com.iwsdk.components.Interactable:
           {}
         com.meta.components.Animatable:
@@ -264,7 +272,16 @@ entities:
       tag: opera_house
     - components:
         com.iwsdk.components.DistanceGrabbable:
-          movementMode: 0
+          targetPositionOffset:
+            - 0
+            - 0.300000012
+            - 0
+          moveSpeedFactor: 0.5
+          targetQuaternionOffset:
+            - 12
+            - 0
+            - 0
+            - 1
         com.iwsdk.components.Interactable:
           {}
         com.meta.components.Animatable:
diff --git a/packages/core/src/grab/distance-grabbable.ts b/packages/core/src/grab/distance-grabbable.ts
@@ -19,6 +19,7 @@ import { MovementMode } from './handles.js';
  * - **RotateAtSource**: Object rotates in place without translation or scaling.
  * - Optional `returnToOrigin` makes objects snap back to their original position when released.
  * - Supports rotation, translation, and scaling with per‑axis constraints.
+ * - Configure target position and rotation offsets relative to the input source for MoveTowardsTarget mode.
  * - Works with the {@link GrabSystem} to create specialized distance grab handles.
  * - Perfect for telekinetic‑style interactions and remote object manipulation.
  *
@@ -47,6 +48,15 @@ import { MovementMode } from './handles.js';
  * })
  * ```
  *
+ * @example Distance grabbable with offset (object stays 0.3m in front of controller)
+ * ```ts
+ * entity.addComponent(DistanceGrabbable, {
+ *   movementMode: MovementMode.MoveTowardsTarget,
+ *   targetPositionOffset: [0, 0, -0.3], // 0.3m forward in controller space
+ *   targetQuaternionOffset: [0, 0, 0, 1], // no rotation offset
+ * })
+ * ```
+ *
  * @category Grab
  * @see {@link GrabSystem}
  * @see {@link OneHandGrabbable}
@@ -100,8 +110,18 @@ export const DistanceGrabbable = createComponent(
     },
     /** A boolean value to set whether the object snap back to its original position and rotation. */
     returnToOrigin: { type: Types.Boolean, default: false },
-    /** Object movement speed for the MoveTowardsTarget movement mode. */
-    moveSpeed: { type: Types.Float32, default: 0.1 },
+    /** Object movement and rotation speed factor for the MoveTowardsTarget movement mode with a scale from 0 to 1. */
+    moveSpeedFactor: { type: Types.Float32, default: 0.1 },
+    /** Target position offset relative to the input source for MoveTowardsTarget mode in [x, y, z]. */
+    targetPositionOffset: {
+      type: Types.Vec3,
+      default: [0, 0, 0],
+    },
+    /** Target rotation offset as a quaternion relative to the input source for MoveTowardsTarget mode in [x, y, z, w]. */
+    targetQuaternionOffset: {
+      type: Types.Vec4,
+      default: [0, 0, 0, 1],
+    },
   },
   'Component for distance-based object grabbing and manipulation',
 );
diff --git a/packages/core/src/grab/grab-system.ts b/packages/core/src/grab/grab-system.ts
@@ -8,7 +8,12 @@
 import { HandleStore } from '@pmndrs/handle';
 import { PointerEventsMap } from '@pmndrs/pointer-events';
 import { createSystem, Entity, Types } from '../ecs/index.js';
-import { Object3D, Object3DEventMap } from '../runtime/index.js';
+import {
+  Object3D,
+  Object3DEventMap,
+  Vector3,
+  Quaternion,
+} from '../runtime/index.js';
 import { DistanceGrabbable } from './distance-grabbable.js';
 import { DistanceGrabHandle, MovementMode, Handle } from './handles.js';
 import { OneHandGrabbable } from './one-hand-grabbable.js';
@@ -252,6 +257,14 @@ export class GrabSystem extends createSystem(
     const returnToOrigin = Boolean(
       entity.getValue(DistanceGrabbable, 'returnToOrigin'),
     );
+    const targetPosOffset = entity.getVectorView(
+      DistanceGrabbable,
+      'targetPositionOffset',
+    );
+    const targetQuatOffset = entity.getVectorView(
+      DistanceGrabbable,
+      'targetQuaternionOffset',
+    );
     const opts = () => ({
       rotate: entity.getValue(DistanceGrabbable, 'rotate')
         ? {
@@ -287,7 +300,14 @@ export class GrabSystem extends createSystem(
       opts,
       movementMode!,
       returnToOrigin,
-      entity.getValue(DistanceGrabbable, 'moveSpeed') ?? 0.1,
+      entity.getValue(DistanceGrabbable, 'moveSpeedFactor') ?? 0.1,
+      new Vector3(targetPosOffset[0], targetPosOffset[1], targetPosOffset[2]),
+      new Quaternion(
+        targetQuatOffset[0],
+        targetQuatOffset[1],
+        targetQuatOffset[2],
+        targetQuatOffset[3],
+      ),
     );
     handle.bind(obj);
     obj.pointerEventsType = { deny: 'grab' };
diff --git a/packages/core/src/grab/handles.ts b/packages/core/src/grab/handles.ts
@@ -31,18 +31,32 @@ export const MovementMode = {
 
 export class DistanceGrabHandle<T> extends HandleStore<T> {
   private previousPointerOrigin: Vector3 | undefined;
+  private isSnapped: boolean = false;
+  private static SNAP_THRESHOLD = 0.005;
+  private static MOVE_SPEED_SCALE = 100;
   private static _tmp = new Vector3();
+  private static _tmpQuat = new Quaternion();
   private static _posHelper = new Vector3();
   private static _quatHelper = new Quaternion();
+  private static _offsetPosHelper = new Vector3();
+  private static _offsetQuatHelper = new Quaternion();
 
   constructor(
     readonly target_: Object3D | { current?: Object3D | null },
     public readonly getOptions: () => HandleOptions<T> = () => ({}),
     public readonly movementMode: string,
     public readonly returnToOrigin: Boolean,
-    public readonly moveSpeed: number = 0.1,
+    public readonly moveSpeedFactor: number = 0.1,
+    public readonly targetPosOffset: Vector3 = new Vector3(0, 0, 0),
+    public readonly targetQuatOffset: Quaternion = new Quaternion(0, 0, 0, 1),
   ) {
     super(target_, getOptions);
+
+    this.targetQuatOffset.normalize();
+
+    (target_ as Object3D).addEventListener('pointerup', () => {
+      this.isSnapped = false;
+    });
   }
 
   update(time: number) {
@@ -95,30 +109,40 @@ export class DistanceGrabHandle<T> extends HandleStore<T> {
       case MovementMode.MoveTowardsTarget: {
         const [p1] = this.inputState.values();
         const pointerOrigin = p1.pointerWorldOrigin;
-        const distance = pointerOrigin.distanceTo(
+        const pointerQuaternion = p1.pointerWorldQuaternion;
+
+        // Calculate target position by applying position offset in pointer's local space
+        const targetPosition = DistanceGrabHandle._offsetPosHelper
+          .copy(this.targetPosOffset)
+          .applyQuaternion(pointerQuaternion)
+          .add(pointerOrigin);
+
+        // Calculate target rotation by multiplying pointer rotation with rotation offset
+        const targetQuaternion = DistanceGrabHandle._offsetQuatHelper
+          .copy(pointerQuaternion)
+          .multiply(this.targetQuatOffset);
+
+        const distance = targetPosition.distanceTo(
           DistanceGrabHandle._posHelper,
         );
 
-        if (distance > this.moveSpeed) {
-          const step = DistanceGrabHandle._tmp
-            .copy(pointerOrigin)
-            .sub(DistanceGrabHandle._posHelper)
-            .normalize()
-            .multiplyScalar(this.moveSpeed);
-          DistanceGrabHandle._posHelper.add(step);
-        } else {
-          DistanceGrabHandle._posHelper.set(
-            pointerOrigin.x,
-            pointerOrigin.y,
-            pointerOrigin.z,
+        if (!this.isSnapped && distance > DistanceGrabHandle.SNAP_THRESHOLD) {
+          DistanceGrabHandle._posHelper.lerp(
+            targetPosition,
+            this.moveSpeedFactor * time * DistanceGrabHandle.MOVE_SPEED_SCALE,
           );
-          DistanceGrabHandle._quatHelper.set(
-            p1.pointerWorldQuaternion.x,
-            p1.pointerWorldQuaternion.y,
-            p1.pointerWorldQuaternion.z,
-            p1.pointerWorldQuaternion.w,
+          DistanceGrabHandle._quatHelper.slerp(
+            targetQuaternion,
+            this.moveSpeedFactor * time * DistanceGrabHandle.MOVE_SPEED_SCALE,
           );
+        } else {
+          if (!this.isSnapped) {
+            this.isSnapped = true;
+          }
+          DistanceGrabHandle._posHelper.copy(targetPosition);
+          DistanceGrabHandle._quatHelper.copy(targetQuaternion);
         }
+
         break;
       }
     }
@@ -137,7 +161,7 @@ export class DistanceGrabHandle<T> extends HandleStore<T> {
 
       // Transform desired world quaternion to local space
       const parentWorldQuaternionInverse = target.parent
-        .getWorldQuaternion(new Quaternion())
+        .getWorldQuaternion(DistanceGrabHandle._tmpQuat)
         .invert();
       quaternion
         .copy(DistanceGrabHandle._quatHelper)
