feat(core) Support holding hand pinching for OneHand and TwoHand grabbables.

Summary: As per requested by the developers in github, we should support OneHandGrabbable and TwoHandsGrabbable with hand tracking. This diff added a new option in Grab System to forward pinch to squeeze signal when hand tracking is enabled to support this use case.

Reviewed By: felixtrz

Differential Revision: D88771989

fbshipit-source-id: 3d1b2fe510515849d7347d5aceded1837c3c5a89

Author: zjm-meta

docs/concepts/grabbing/index.md

@@ -6,7 +6,7 @@ title: Grabbing Overview
 
 Interactive object manipulation is foundational to immersive experiences. IWSDK provides a comprehensive grabbing system that enables natural, performant object interaction through three distinct manipulation patterns—each optimized for different use cases and comfort requirements.
 
-- **One-Hand Grabbing** — Direct single-controller manipulation for basic interactions
+- **One-Hand Grabbing** — Direct single input manipulation for basic interactions
 - **Two-Hand Grabbing** — Dual-hand manipulation with scaling capabilities for precise control  
 - **Distance Grabbing** — Ray-based remote manipulation with telekinetic-style interactions
 

docs/concepts/grabbing/interaction-types.md

@@ -8,7 +8,7 @@ IWSDK's grabbing system provides three distinct interaction patterns, each imple
 
 ## One-Hand Grabbing
 
-Single-controller direct manipulation optimized for immediate, responsive interactions.
+Single-input direct manipulation optimized for immediate, responsive interactions.
 
 ### Architecture Characteristics
 
@@ -52,7 +52,7 @@ const handle = new HandleStore(object, () => ({
 
 ## Two-Hand Grabbing
 
-Dual-controller manipulation enabling advanced operations including scaling through multi-pointer coordination.
+Dual-input manipulation enabling advanced operations including scaling through multi-pointer coordination.
 
 ### Architecture Characteristics
 

docs/guides/06-built-in-interactions.md

@@ -55,7 +55,7 @@ With grabbing enabled, you can add grab components to any object. IWSDK provides
 
 ### OneHandGrabbable - Direct Manipulation
 
-For objects you grab and move directly with one hand:
+For objects you grab and move directly with one input:
 
 ```javascript
 // Make your existing robot grabbable
@@ -73,6 +73,25 @@ world
   });
 ```
 
+> Note that hand tracking is by default not working with OneHandGrabbable and TwoHandsGrabbable as the hand pinch is mapped to the trigger button instead of the squeeze button. To use hand tracking for OneHandGrabbable and TwoHandsGrabbable, you will need to enable `useHandPinchForGrab` in the grab system. For example,
+
+```javascript
+// Update your existing World.create() call in src/index.ts
+World.create(document.getElementById('scene-container'), {
+  assets,
+  xr: {
+    sessionMode: SessionMode.ImmersiveVR,
+    features: { handTracking: true },
+  },
+  features: {
+    grabbing: { useHandPinchForGrab: true }, // Enable grab system with hand pinch grabbing
+    // ... other existing features
+  },
+}).then((world) => {
+  // ... your existing setup
+});
+```
+
 ### DistanceGrabbable - At-a-Distance Interaction
 
 For objects you can grab, scale, and manipulate from far away:

examples/grab/metaspatial/Composition/Main.metaspatialcomp

@@ -9,4 +9,4 @@ entities:
           scenes:
             - ref:Scene
 metadata:
-  version: 1.34
+  version: 1.35

examples/grab/metaspatial/Composition/Main.scene

@@ -47,9 +47,9 @@ entities:
       tag: Environment
     - components:
         com.iwsdk.components.DistanceGrabbable:
-          scale: false
-          movementMode: 3
           translate: false
+          movementMode: 3
+          scale: false
         com.iwsdk.components.Interactable:
           {}
         com.meta.components.Animatable:
@@ -319,4 +319,4 @@ entities:
           visible: true
       tag: pyramid duplicate
 metadata:
-  version: 1.34
+  version: 1.35

examples/grab/src/index.js

@@ -24,11 +24,13 @@ World.create(document.getElementById('scene-container'), {
   assets,
   xr: {
     sessionMode: SessionMode.ImmersiveVR,
-    requiredFeatures: ['hand-tracking'],
+    features: {
+      handTracking: { required: true },
+    },
   },
   level: '/glxf/Composition.glxf',
   features: {
-    grabbing: true,
+    grabbing: { useHandPinchForGrab: true },
     locomotion: true,
     spatialUI: true,
   },

packages/core/src/grab/grab-system.ts

@@ -7,7 +7,7 @@
 
 import { HandleStore } from '@pmndrs/handle';
 import { PointerEventsMap } from '@pmndrs/pointer-events';
-import { createSystem, Entity } from '../ecs/index.js';
+import { createSystem, Entity, Types } from '../ecs/index.js';
 import { Object3D, Object3DEventMap } from '../runtime/index.js';
 import { DistanceGrabbable } from './distance-grabbable.js';
 import { DistanceGrabHandle, MovementMode, Handle } from './handles.js';
@@ -48,20 +48,30 @@ import { TwoHandsGrabbable } from './two-hands-grabbable.js';
  * @see {@link TwoHandsGrabbable}
  * @see {@link DistanceGrabbable}
  */
-export class GrabSystem extends createSystem({
-  oneHandGrabbables: {
-    required: [OneHandGrabbable],
+export class GrabSystem extends createSystem(
+  {
+    oneHandGrabbables: {
+      required: [OneHandGrabbable],
+    },
+    twoHandsGrabbables: {
+      required: [TwoHandsGrabbable],
+    },
+    distanceGrabbables: {
+      required: [DistanceGrabbable],
+    },
+    handles: {
+      required: [Handle],
+    },
   },
-  twoHandsGrabbables: {
-    required: [TwoHandsGrabbable],
+  {
+    /**
+     * Controls whether hand pinch gestures are forwarded as squeeze events for grab interactions.
+     * Set to `false` to disable pinch-to-grab and require the physical squeeze button instead.
+     * @default false
+     */
+    useHandPinchForGrab: { type: Types.Boolean, default: false },
   },
-  distanceGrabbables: {
-    required: [DistanceGrabbable],
-  },
-  handles: {
-    required: [Handle],
-  },
-}) {
+) {
   init() {
     // Ensure Handle component is registered in the world before queries rely on it
     if (!Handle.bitmask) {
@@ -110,7 +120,27 @@ export class GrabSystem extends createSystem({
     this.input.multiPointers.right.toggleSubPointer('grab', true);
   }
 
-  update(delta: number): void {
+  update(delta: number, time: number): void {
+    // Forward hand pinch events to squeeze for grab interactions
+    // Only forward if the system-level useHandPinchForGrab flag is enabled
+    if (this.config.useHandPinchForGrab) {
+      (['left', 'right'] as const).forEach((handedness) => {
+        if (this.input.isPrimary('hand', handedness)) {
+          const timeStamp = time * 1000;
+          if (this.input.gamepads[handedness]?.getSelectStart()) {
+            this.input.multiPointers[handedness].routeDown('squeeze', 'grab', {
+              timeStamp,
+            });
+          }
+          if (this.input.gamepads[handedness]?.getSelectEnd()) {
+            this.input.multiPointers[handedness].routeUp('squeeze', 'grab', {
+              timeStamp,
+            });
+          }
+        }
+      });
+    }
+
     // Unified handle updates
     this.queries.handles.entities.forEach((entity) => {
       const h = Handle.data.instance[entity.index] as

packages/core/src/init/world-initializer.ts

@@ -96,7 +96,7 @@ export type WorldOptions = {
     /** Locomotion (teleport/slide/turn). Boolean or config. @defaultValue false */
     locomotion?: boolean | { useWorker?: boolean };
     /** Grabbing (one/two‑hand, distance). @defaultValue false */
-    grabbing?: boolean;
+    grabbing?: boolean | { useHandPinchForGrab?: boolean };
     /** Physics simulation (Havok). @defaultValue false */
     physics?: boolean;
     /** Scene Understanding (planes/meshes/anchors). Boolean or config. @defaultValue false */
@@ -420,7 +420,10 @@ function registerFeatureSystems(
     | boolean
     | { useWorker?: boolean };
   const locomotionEnabled = !!locomotion;
-  const grabbingEnabled = !!config.features.grabbing;
+  const grabbing = config.features.grabbing as
+    | boolean
+    | { useHandPinchForGrab?: boolean };
+  const grabbingEnabled = !!grabbing;
   const physicsEnabled = !!config.features.physics;
   const sceneUnderstanding = config.features.sceneUnderstanding as
     | boolean
@@ -444,7 +447,11 @@ function registerFeatureSystems(
   }
   world.registerSystem(InputSystem, { priority: -4 });
   if (grabbingEnabled) {
-    world.registerSystem(GrabSystem, { priority: -3 });
+    const grabOpts =
+      typeof grabbing === 'object' && grabbing
+        ? { useHandPinchForGrab: grabbing.useHandPinchForGrab }
+        : undefined;
+    world.registerSystem(GrabSystem, { priority: -3, configData: grabOpts });
   }
 
   // Physics runs after Grab so it can respect Pressed overrides