🍅Grabbable

Basic Information

Attaching this component to any rigidbody object with a collider will make it grabbable by a working hand.

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

Learn more about Physics Joints

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)

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

Rigidbody settings will affect how a grabbable is handled.

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

//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)

//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

//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.

Distance Grabbing

🧲pageDistance Grabbing