{"_id":"58796782cd4a9c37007c9744","parentDoc":null,"user":"571fa519db52d01700f5cf3d","project":"571fa55ca0acd42000af9545","__v":0,"version":{"_id":"58796781cd4a9c37007c96ef","__v":4,"project":"571fa55ca0acd42000af9545","createdAt":"2017-01-13T23:49:21.393Z","releaseDate":"2017-01-13T23:49:21.393Z","categories":["58796781cd4a9c37007c96f0","58796781cd4a9c37007c96f1","58796781cd4a9c37007c96f2","58796781cd4a9c37007c96f3","58796781cd4a9c37007c96f4","58796781cd4a9c37007c96f5","58796781cd4a9c37007c96f6","58796781cd4a9c37007c96f7","58796781cd4a9c37007c96f8","58796781cd4a9c37007c96f9","58796781cd4a9c37007c96fa","58796781cd4a9c37007c96fb","58796781cd4a9c37007c96fc","58796781cd4a9c37007c96fd","58796781cd4a9c37007c96fe","58796781cd4a9c37007c96ff","58796781cd4a9c37007c9700","58b157ca1756cf370022f90d","58b1596f5dae732f00adeca2","58b1605a5dae732f00adecb1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Mukota","version_clean":"3.1.0","version":"3.1.0"},"category":{"_id":"58796781cd4a9c37007c96f4","project":"571fa55ca0acd42000af9545","__v":0,"version":"58796781cd4a9c37007c96ef","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-01-01T16:45:52.489Z","from_sync":false,"order":6,"slug":"interactions","title":"Interactions"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-01T16:47:18.600Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"## Overview\n\nThe Interact Grab script is attached to a Controller object and requires the `VRTK_ControllerEvents` script to be attached as it uses this for listening to the controller button events for grabbing and releasing interactable game objects.\n\nIt listens for the `AliasGrabOn` and `AliasGrabOff` events to determine when an object should be grabbed and should be released.\n\nThe Controller object also requires the `VRTK_InteractTouch` script to be attached to it as this is used to determine when an interactable object is being touched. Only valid touched objects can be grabbed.\n\nAn object can be grabbed if the Controller touches a game object which contains the `VRTK_InteractableObject` script and has the flag `isGrabbable` set to `true`.\n\nIf a valid interactable object is grabbable then pressing the set `Grab` button on the Controller (default is `Grip`) will grab and snap the object to the controller and will not release it until the `Grab` button is released.\n\nWhen the Controller `Grab` button is released, if the interactable game object is grabbable then it will be propelled in the direction and at the velocity the controller was at, which can simulate object throwing.\n\nThe interactable objects require a collider to activate the trigger and a rigidbody to pick them up and move them around the game world.\n\n## Inspector Parameters\n\n * **Controller Attach Point:** The rigidbody point on the controller model to snap the grabbed object to. If blank it will be set to the SDK default.\n * **Grab Precognition:** An amount of time between when the grab button is pressed to when the controller is touching something to grab it. For example, if an object is falling at a fast rate, then it is very hard to press the grab button in time to catch the object due to human reaction times. A higher number here will mean the grab button can be pressed before the controller touches the object and when the collision takes place, if the grab button is still being held down then the grab action will be successful.\n * **Throw Multiplier:** An amount to multiply the velocity of any objects being thrown. This can be useful when scaling up the play area to simulate being able to throw items further.\n * **Create Rigid Body When Not Touching:** If this is checked and the controller is not touching an Interactable Object when the grab button is pressed then a rigid body is added to the controller to allow the controller to push other rigid body objects around.\n\n## Class Events\n\n * `ControllerGrabInteractableObject` - Emitted when a valid object is grabbed.\n * `ControllerUngrabInteractableObject` - Emitted when a valid object is released from being grabbed.\n\n## Unity Events\n\nAdding the `VRTK_InteractGrab_UnityEvents` component to `VRTK_InteractGrab` object allows access to `UnityEvents` that will react identically to the Class Events.\n\n * `OnControllerGrabInteractableObject` - Emits the ControllerGrabInteractableObject class event.\n * `OnControllerUngrabInteractableObject` - Emits the ControllerUngrabInteractableObject class event.\n\n## Event Payload\n\n * `uint controllerIndex` - The index of the controller doing the interaction.\n * `GameObject target` - The GameObject of the interactable object that is being interacted with by the controller.\n\n## Class Methods\n\n### ForceRelease/1\n\n  > `public void ForceRelease(bool applyGrabbingObjectVelocity = false)`\n\n  * Parameters\n   * `bool applyGrabbingObjectVelocity` - If this is true then upon releasing the object any velocity on the grabbing object will be applied to the object to essentiall throw it. Defaults to `false`.\n  * Returns\n   * _none_\n\nThe ForceRelease method will force the controller to stop grabbing the currently grabbed object.\n\n### AttemptGrab/0\n\n  > `public void AttemptGrab()`\n\n  * Parameters\n   * _none_\n  * Returns\n   * _none_\n\nThe AttemptGrab method will attempt to grab the currently touched object without needing to press the grab button on the controller.\n\n### GetGrabbedObject/0\n\n  > `public GameObject GetGrabbedObject()`\n\n  * Parameters\n   * _none_\n  * Returns\n   * `GameObject` - The game object of what is currently being grabbed by this controller.\n\nThe GetGrabbedObject method returns the current object being grabbed by the controller.\n\n## Example\n\n`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.\n\n`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.\n\n`VRTK/Examples/014_Controller_SnappingObjectsOnGrab` demonstrates the different mechanisms for snapping a grabbed object to the controller.","excerpt":"","slug":"vrtk_interactgrab","type":"basic","title":"VRTK_InteractGrab"}
## Overview The Interact Grab script is attached to a Controller object and requires the `VRTK_ControllerEvents` script to be attached as it uses this for listening to the controller button events for grabbing and releasing interactable game objects. It listens for the `AliasGrabOn` and `AliasGrabOff` events to determine when an object should be grabbed and should be released. The Controller object also requires the `VRTK_InteractTouch` script to be attached to it as this is used to determine when an interactable object is being touched. Only valid touched objects can be grabbed. An object can be grabbed if the Controller touches a game object which contains the `VRTK_InteractableObject` script and has the flag `isGrabbable` set to `true`. If a valid interactable object is grabbable then pressing the set `Grab` button on the Controller (default is `Grip`) will grab and snap the object to the controller and will not release it until the `Grab` button is released. When the Controller `Grab` button is released, if the interactable game object is grabbable then it will be propelled in the direction and at the velocity the controller was at, which can simulate object throwing. The interactable objects require a collider to activate the trigger and a rigidbody to pick them up and move them around the game world. ## Inspector Parameters * **Controller Attach Point:** The rigidbody point on the controller model to snap the grabbed object to. If blank it will be set to the SDK default. * **Grab Precognition:** An amount of time between when the grab button is pressed to when the controller is touching something to grab it. For example, if an object is falling at a fast rate, then it is very hard to press the grab button in time to catch the object due to human reaction times. A higher number here will mean the grab button can be pressed before the controller touches the object and when the collision takes place, if the grab button is still being held down then the grab action will be successful. * **Throw Multiplier:** An amount to multiply the velocity of any objects being thrown. This can be useful when scaling up the play area to simulate being able to throw items further. * **Create Rigid Body When Not Touching:** If this is checked and the controller is not touching an Interactable Object when the grab button is pressed then a rigid body is added to the controller to allow the controller to push other rigid body objects around. ## Class Events * `ControllerGrabInteractableObject` - Emitted when a valid object is grabbed. * `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. * `OnControllerGrabInteractableObject` - Emits the ControllerGrabInteractableObject class event. * `OnControllerUngrabInteractableObject` - Emits the ControllerUngrabInteractableObject class event. ## Event Payload * `uint controllerIndex` - The index of the controller doing the interaction. * `GameObject target` - The GameObject of the interactable object that is being interacted with by the controller. ## Class Methods ### ForceRelease/1 > `public void ForceRelease(bool applyGrabbingObjectVelocity = false)` * Parameters * `bool applyGrabbingObjectVelocity` - If this is true then upon releasing the object any velocity on the grabbing object will be applied to the object to essentiall throw it. Defaults to `false`. * Returns * _none_ The ForceRelease method will force the controller to stop grabbing the currently grabbed object. ### AttemptGrab/0 > `public void AttemptGrab()` * Parameters * _none_ * Returns * _none_ The AttemptGrab method will attempt to grab the currently touched object without needing to press the grab button on the controller. ### GetGrabbedObject/0 > `public GameObject GetGrabbedObject()` * Parameters * _none_ * Returns * `GameObject` - The game object of what is currently being grabbed by this controller. The GetGrabbedObject method returns the current object being grabbed by the controller. ## 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.