# Grabbable ## Basic Information Attaching this component to any rigidbody object with a collider will make it grabbable by a working [hand](/auto-hand-docs/auto-hand/hand.md). The way grabbables "feels" while being held or touched depends on the hand/grabbables Rigidbody settings. Depending on the mass and drag settings the object will feel more heavy/light or more/less aerodynamic. This is because the hand is driven by rigidbody forces and the connection between the hand and the grabbable is managed through a physics joint. [Learn more about Rigidbodies](https://docs.unity3d.com/ScriptReference/Rigidbody.html) [Learn more about Physics Joints](https://docs.unity3d.com/Manual/Joints.html) Grabbables must be added with or under a rigidbody. One rigidbody object made up of multiple colliders can have multiple grabbables because grabbables settings work on a per collider basis. By default all colliders under a grabbable will automatically be made grabbable if the `Make Children Grabbable` value is enabled and no other grabbables are found.
`Body` must be connected to a rigidbody * **(this will automatically be filled on start with the local rigidbody if found)** #### `Highlight Material` will create a copy of the grabbable mesh and apply this material to it on highlight #### `Copy Settings` will overwrite this grabbables settings with the included grabbable #### `Grab Type`: This value determines how the object is grabbed by the hand * **`Default`: grabbable will default to the grabbing hand’s setting** * **`Hand to Grabbable`: hand will go to the grabbable and bring it back to the follow target** * **`Grabbable to Hand`: grabbable will float to the hand** #### `Hand Type` which hands are allowed to grab (Both\Left\Right) #### `Single Hand Only` Whether or not to allow multiple hands to grab this object or not * **`Allow Held Swapping` Whether or not the held singled handed object should be swapped into the other hand when grabbed** #### `Use Gentle Grab` if enabled the hand will not return automatically when grabbing but will instead return based on your controller movement and the hands gentle grab speed #### `Maintain Grab Offset` will create an offset equal to the difference in position and rotation to the object on grab (Great for things like levers and doorknobs where you don't want the hand to return on grab) #### `Ignore weight` will apply a movement follower component (only while held) to simulate weightlessness #### `Parent On Grab` will parent the grabbable to the Hand's PARENT on the grab. Should be true for any object you can pickup and carry away. * **This flag is checked when the player is teleported to decide whether to bring the object on teleport or with the player, or dropped** * **This flag will also allow the body to move objects with it while moving for a smoother result while walking/holding an object** #### `Joint Break Force` will determine the force needed to break the joint and the hand connection. * **This value can be set to "infinity" so the connection never breaks through physics force (this can cause possible jitter if the difference in rigidbody mass/density between the hand and grabbable is too high)** ## **Advanced Information**
#### **`Make Children Grabbable`** if true, all the children of this grabbable object with a collider will be given a `Grabbable Child` component on Start(), which will allow it to be grabbed even though it does not have a grabbable component directly #### `Grab Priority Weight` creates grab priority by dividing grab ray cast hit distance by this value. Grabs are determined by the closest raycast hit distance #### `Ignore Release Time` determines how long the hand will ignore the colliders of the grabbable when released. Allows for smoother releases with thrown objects, recommend setting to 0 for things like doors and walls #### `Custom Grab Joint` will override the default fixed joint created by the hand with a custom physics joint between the hand and the grabbable. To create a custom joint, make prefab with rigidbody and custom joint at root then connect that prefab to this value #### `Jointed Bodies` should take all the dynamic jointed rigidbodies attached to this grabbable. For example, when creating a handheld button, you’d attach the grabbable base of the rigidbody to the jointed spring of the button. #### `Held Ignore Colliders` the hand holding this grabbable will ignore these colliders only while holding this grabbable. For example, a door handle where you don't want the door collider to interfere with the hand colliders #### `Pull Apart Break Only` will make it so the OnBreak event will only be called if two hands are holding the grabbable during the joint break. (This option is available because it is possible to create the break event with one hand through jointed objects or by forcing objects into static objects) {% hint style="info" %} An object can have multiple grabbables with different instructions per collider of an object. Meaning as long as the grabbables are under a root "body" are connected, they can each have their own custom settings {% endhint %} {% hint style="danger" %} Rigidbody settings will affect how a grabbable is handled. {% endhint %} ## Grabbable Events See Tips 🔍 for more information on Unity Events
#### `On Grab` is called when the hand touches the grabbable, after the grab connection is made #### `On Release` is called when the hand releases the grabbable #### `On Squeeze` called on when the squeeze button is trigger while holding a grabbable. Squeeze button is determined by the `Hand Controller Link` settings (attached to “Input” gameobject under hands in demo) #### `On Highlight` is triggered by the hand when this grabbable first becomes the grab target of a hand #### `On Joint break` is called whenever the hand joint connection breaks unless "Pull-Apart Break Only" is activated, in which it will only get called when the joint breaks and two hands are holding the grabbable (this is to simulate ripping objects apart) ### `Grabbable Extra Events`
#### `On First Grab` is only called when no hands are currently holding this object on grab #### `On Last Release` is only called when the last hand is releasing this grabbable ## **Programming Info** #### Releasing > Includes functions for forcing releasing / dropping from the grabbable class ```csharp //Will make all held hands release this object grabbable.HandsRelease() //Will make the given hand release this object grabbable.HandRelease(Hand hand) //Will make all hands release this object, without applying throw force (as if it was dropped) grabbable.ForceHandsRelease() //Will make the given hand release this object, without applying throw force (as if it was dropped) grabbable.ForceHandRelease(Hand hand) ``` #### Haptics > Auto Hand haptics supported for XR, SteamVR, and OVR if supported by your device for that system (Haptics not currently supported through OpenXR) ```csharp //Will play haptic on the hand if supported by input system and device grabbable.PlayHapticVibration() grabbable.PlayHapticVibration(float duration) grabbable.PlayHapticVibration(float duration, float amp) ``` #### Getters ```csharp //Returns a list of the hands holding this grabbable grabbable.GetHeldBy() //Returns the grabbables placePoint if is placed or highlighting, null if none grabbable.placePoint ``` ## Grab Lock The grab lock component can be used to prevent a grabbable from being dropped when the regular release is triggered. The new "On Grab Pressed" event will be called when the grab locked item is "grabbed" in the hand
## Grabbable Throw Event This throw event will trigger only after a grabbable has been released with a velocity magnitude of the "break velocity" and collides with something in the included "collision layer"
## Grabbable Child Auto Hand's grabbing check is done per collider, which means if your grabbable is made up of many colliders. * You can add a grabbable component to a child of a grabbable as long as it is connected to the same rigidbody "body" * You can enable "Make Children Grabbable", which will automatically apply this script to all eligible colliders under the grabbable root. * You can manually apply this Grabbable Child component to each collider you want to make grabbable.
![](/files/y4UUF8kY9sQF3R7PeFfq) ## Distance Grabbing {% content-ref url="/spaces/5zKO0EvOjzUDeT2aiFk3/pages/yd7Uhy8PnJg1pPD9znZ5" %} [Distance Grabbing](/auto-hand-docs/auto-hand/grabbable/distance-grabbing.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://earnest-robot.gitbook.io/auto-hand-docs/auto-hand/grabbable.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.