AvatarGrab Sample Scene

The Unity AvatarGrab sample scene demonstrates how to use an Oculus Avatar’s hands to interact with nearby predefined objects in a scene.

This scene puts you in control of an Oculus Avatar in front of a table with many different objects that can be picked up, held, dropped, and thrown by using the grip triggers of the Touch controllers. These objects are affected by gravity and physics and can be thrown at and collide with other objects resulting in realistic physical reactions.

The goal of this topic is to help you understand the prefabs, Game Objects, components, and properties that make this functionality work. You can also use this sample scene as a starting point for your own application.

AvatarGrab sample scene

Scene Walkthrough

This section describes the key prefabs and Game Objects that make the core functionality of this scene work. For this scene, the following are covered:

  • LocalAvatarWithGrab Prefab – Prefab for the local Oculus Avatar, grabbing hands (grabbers), and OVRCameraRig.
  • AvatarGrabberLeft and AvatarGrabberRight Game Objects – Child objects of LocalAvatarWithGrab that enable grabbing functionality for the avatar’s hands.
  • Grabbable Game Objects (ToyCubePf) – Objects in the scene that have been configured to be grabbed, held, dropped, and thrown.

LocalAvatarWithGrab Prefab

LocalAvatarWithGrab in Unity Hierarchy

The LocalAvatarWithGrab prefab renders the user’s avatar and hands and contains the components necessary for the hands to grab and interact with objects in the scene. It also contains an OVRCameraRig to serve as the user’s VR camera and provide access to OVRManager.

Select LocalAvatarWithGrab in the Hierarchy and look at it in the Inspector window. The most notable component is OvrAvatar, which defines and renders an avatar. In this sample scene, it provides the hands that will be used to manipulate objects.

The OvrAvatarLocalDriver component drives the avatar with movement from the local user’s HMD and controllers, rather than using recorded playback data.

For more information on Oculus Avatars, see the Oculus Avatar SDK.

AvatarGrabberLeft and AvatarGrabberRight Game Objects

Select either of these children of LocalAvatarWithGrab in the Hierarchy and look in the Inspector window. These objects and their children are responsible for enabling the avatar’s hands to grab objects. Notable components include the following:

RigidBody

A standard Unity component that allows physics to be applied to an object. It is required to allow physical interaction with other objects in the scene.

For grabbers, Use Gravity is disabled to prevent gravity from affecting our hands. Is Kinematic is enabled to prevent hand movement from being affected by events such as collisions while still preserving their ability to physically interact with certain objects.

OVRGrabber

OVRGrabber in Unity Inspector

This key component enables the avatar’s hands to grab and interact with objects that have been configured with an OVR Grabbable component. Since this component is key to grabbing functionality, let’s go over all of its properties.

  • Grab Begin and Grab End – These define the grip trigger threshold for grabbing and releasing objects. For Grab Begin, the closer to 1, the further you must pull in the grip trigger to grab an object. For Grab End, the closer to 0, the more you must release the trigger to drop or throw an object.
  • Parent Held Object – Makes the grabbed object a child of the grabber. Although enabling this works in this sample scene, it can create issues in certain physics simulations.
  • Grip Transform – An attached child transform that indicates where to snap grabbed objects to. This transform is also used to rank objects for grabbing when there are multiple options.
  • Grab Volumes – Attached child collider objects that detect grabbable object candidates. These child collider objects must have Is Trigger enabled so they can successfully trigger grabbing events. This also prevents the colliders from being affected by physics.
  • Controller – Indicates the controller that the grabber is tied to. This ties the grabber to either the left or right avatar hand provided by OvrAvatar. This property is the only difference between AvatarGrabberLeft and AvataraGrabberRight.
  • Parent Transform – Transform of the parent object. You do not have to do anything with this property, but it can be used to attach the grabber to objects other than your avatar.

Grabbable Game Objects (ToyCubePf)

This section looks at one of the many grabbable objects in the scene in detail, but the information applies to all of them, regardless of shape or size.

In the Hierarchy, go to Environment > Dynamic > CubeRow > ToyCubePf (4) and look at the Game Object in the Inspector window.

In addition to mesh-related components present on all models, grabbable objects need to be configured with the following components to work properly:

Box Collider

A standard Unity component used to define the shape of an object for physical collision and interaction. This is what OVRGrabber is looking at when it tries to grab an object. Some objects in the scene use Sphere Colliders when the shape of the object is appropriate.

RigidBody

A standard Unity component that allows physics to be applied to an object. It is required to allow physical interaction with other objects in the scene.

Although RigidBody is also used when making grabbers, its settings differ here. For grabbable objects, Use Gravity is enabled to allow for realistic throws and collisions with other interactive objects. Is Kinematic is disabled to allow physics to have full effect over the object.

OVRGrabbable

OVRGrabbable in Unity Inspector

This key component enables the object to be grabbed by avatar hands that have been configured with an OVRGrabber component. Since this component is key to grabbing functionality, let’s go over all of its properties:

  • Allow Offhand Grab – When enabled, allows an object to be grabbed.
  • Snap Position – When enabled, the grabbed object’s position will snap to match the transform in Snap Offset.
  • Snap Orientation - When enabled, the grabbed object’s orientation (rotation) will snap to match the transform in Snap Offset.
  • Snap Offset – A transform that is an offset relative to the OVR Grabber that the grabbed object’s position and/or orientation can snap to.
  • Grab Points – When several objects are used to make one larger object, the collider for each object is placed in Grab Point’s elements, allowing the objects to behave as a single object. In the Hierarchy, select Environment > Dynamic > ToyT-BlockPf to see an example of this property’s use.

Using in Your Own Apps

The LocalAvatarWithGrab prefab can easily be dropped into your own app to provide grabbing functionality without configuration. If you would like to experiment or have more over control over the implementation, perhaps by trying to use an OVRPlayerController instead of an OVRCameraRig to allow for player movement, AvatarGrabberLeft and AvatarGrabberRight are also available by themselves as prefabs.

Grabbable objects must be configured with OVRGrabbable, RigidBody, and an appropriate collider in addition to standard mesh-related components.