---
agentTools:
  projectIndex: https://vrtoolkit.readme.io/llms.txt
---

# VRTK_InteractGrab

## Overview

Determines if the Interact Touch can initiate a grab with the touched Interactable Object.

**Required Components:**

* `VRTK_InteractTouch` - The touch component to determine when a valid touch has taken place to denote a grab can occur. This must be applied on the same GameObject as this script if one is not provided via the `Interact Touch` parameter.

**Optional Components:**

* `VRTK_ControllerEvents` - The events component to listen for the button presses on. This must be applied on the same GameObject as this script if one is not provided via the `Controller Events` parameter.

**Script Usage:**

* Place the `VRTK_InteractGrab` script on either:
  * The GameObject with the Interact Touch and Controller Events scripts.
  * Any other scene GameObject and provide a valid `VRTK_ControllerEvents` component to the `Controller Events` parameter and a valid `VRTK_InteractTouch` component to the `Interact Touch` parameter of this script.

## Inspector Parameters

* **Grab Button:** The button used to grab/release a touched Interactable Object.
* **Grab Precognition:** An amount of time between when the grab button is pressed to when the controller is touching an Interactable Object to grab it.
* **Throw Multiplier:** An amount to multiply the velocity of any Interactable Object being thrown.
* **Create Rigid Body When Not Touching:** If this is checked and the Interact Touch is not touching an Interactable Object when the grab button is pressed then a Rigidbody is added to the interacting object to allow it to push other Rigidbody objects around.
* **Controller Attach Point:** The rigidbody point on the controller model to snap the grabbed Interactable Object to. If blank it will be set to the SDK default.
* **Controller Events:** The Controller Events to listen for the events on. If the script is being applied onto a controller then this parameter can be left blank as it will be auto populated by the controller the script is on at runtime.
* **Interact Touch:** The Interact Touch to listen for touches on. If the script is being applied onto a controller then this parameter can be left blank as it will be auto populated by the controller the script is on at runtime.

## Class Events

* `GrabButtonPressed` - Emitted when the grab button is pressed.
* `GrabButtonReleased` - Emitted when the grab button is released.
* `ControllerStartGrabInteractableObject` - Emitted when a grab of a valid object is started.
* `ControllerGrabInteractableObject` - Emitted when a valid object is grabbed.
* `ControllerStartUngrabInteractableObject` - Emitted when a ungrab of a valid object is started.
* `ControllerUngrabInteractableObject` - Emitted when a valid object is released from being grabbed.

## Unity Events

Adding the `VRTK_InteractGrab_UnityEvents` component to `VRTK_InteractGrab` object allows access to `UnityEvents` that will react identically to the Class Events.

* All C# delegate events are mapped to a Unity Event with the `On` prefix. e.g. `MyEvent` -> `OnMyEvent`.

## Class Methods

### IsGrabButtonPressed/0

> `public virtual bool IsGrabButtonPressed()`

* Parameters
  * *none*
* Returns
  * `bool` - Returns `true` if the grab alias button is being held down.

The IsGrabButtonPressed method determines whether the current grab alias button is being pressed down.

### ForceRelease/1

> `public virtual void ForceRelease(bool applyGrabbingObjectVelocity = false)`

* Parameters
  * `bool applyGrabbingObjectVelocity` - If this is true then upon releasing the Interactable Object any velocity on the Interact Touch GameObject will be applied to the Interactable Object to essentiall throw it. Defaults to `false`.
* Returns
  * *none*

The ForceRelease method will force the Interact Grab to stop grabbing the currently grabbed Interactable Object.

### AttemptGrab/0

> `public virtual void AttemptGrab()`

* Parameters
  * *none*
* Returns
  * *none*

The AttemptGrab method will attempt to grab the currently touched Interactable Object without needing to press the grab button on the controller.

### GetGrabbedObject/0

> `public virtual GameObject GetGrabbedObject()`

* Parameters
  * *none*
* Returns
  * `GameObject` - The game object of what is currently being grabbed by this controller.

The GetGrabbedObject method returns the current Interactable Object being grabbed by the this Interact Grab.

### ForceControllerAttachPoint/1

> `public virtual void ForceControllerAttachPoint(Rigidbody forcedAttachPoint)`

* Parameters
  * `Rigidbody forcedAttachPoint` - The rigidbody to use as the controller attach point.
* Returns
  * *none*

The ForceControllerAttachPoint method updates the rigidbody being used as the controller grab attach position.

## Example

`VRTK/Examples/005_Controller/BasicObjectGrabbing` demonstrates the grabbing of interactable objects that have the `VRTK_InteractableObject` script attached to them. The objects can be picked up and thrown around.

`VRTK/Examples/013_Controller_UsingAndGrabbingMultipleObjects` demonstrates that each controller can grab and use objects independently and objects can also be toggled to their use state simultaneously.

`VRTK/Examples/014_Controller_SnappingObjectsOnGrab` demonstrates the different mechanisms for snapping a grabbed object to the controller.