Meta Developers

A Grabbable entity is an entity which has Motion set to Interactive, and Interaction set to Grabbable or Both. Examples of grabbable entities are gun and handheld devices. They require a variety of small changes to function correctly within Meta Horizon worlds on Web and Mobile. These changes include:

Set the avatar pose: You can set the avatar pose and the animation used when holding a particular kind of grabbable. For example, a pistol is held and activated in a different way than a sword or a rifle.
Play avatar animations: Since firing mechanics are driven purely by CodeBlocks, the avatar animations must also be played by CodeBlocks.
Set the aim direction: For players on web and mobile, guns need to fire in a set direction, regardless of what the animation does. You can specify a fixed direction for each grabbable that overrides the firing direction.
Setting the action button icons: When playing on mobile, you can declare what the action buttons represent when a grabbable is being held. For example a gun may have a fire action and a reload action. The primary button defaults to firing the same CodeBlock event as pulling the trigger on the Quest controller, so this works for most scenarios. The secondary and tertiary action buttons fire the same CodeBlock event as Button 1 and Button 2 respectively.
Crosshair selection: Games commonly use crosshairs which are generated by casting a ray from the grabbable. This can cause issues when playing animations because they won’t truly represent where the gun is aiming. To remedy this, there is a custom way of overlaying a crosshair on the screen for web and mobile players.
Holster icon selection: this icon will be used in the lightweight UI representing items attached to the user’s avatar, which users can interact with to switch between and equip items.

Set the avatar pose

The avatar pose will specify the position of the avatar and the animation set which will be played while a grabbable is being held. You can choose an Avatar Pose according to how you want the user to hold and use the grabbable entity. The default pose holds the object in the player’s hand with default animations (e.g. running normally rather than aiming a weapon).

The avatar pose can be found in the properties of the grabbable entity:

Select the grabbable entity then move the thumbstick up to select ...Properties.
Select More, then select the pose you want to assign to the entity from the dropdown next to Avatar Pose.

Play avatar animations

You can play avatar animations using the Trigger grip animation for player CodeBlock. The Trigger grip animation for player CodeBlock requires a reference to the player that should play the animation, and the name of the animation to play.

There are two animation names:

Fire
Reload

Different avatar poses will play different animations. For example, Sword plays a swinging animation when the Fire grip animation is triggered.

Grab anchors

In the event that an item is held incorrectly, we can enable Use Grab Anchor toggle in the grabbable entity properties. This allows us to set a grab anchor position and rotation so the avatar holds the item correctly.

Set the aim direction

You can use the GrabbableAim property to specify the direction a weapon points when it’s held. Without this, the firing direction of the weapon is driven by animation, which leads to unpredictable results. The aim direction allows you to specify a true aiming reference for projectile launchers that are linked to a grabbable entity, for web and mobile players.

The GrabbableAim property represents the position and orientation in which bullets travel, and you can click and drag it into a new position. This setting ensures the gun aims towards the reticle in the centre of the screen, while maintaining any ProjectileLauncher offsets for web and mobile players.

The Grab Aim Position and Rotation relates only to Projectile Launchers that are owned by the player. Ensure to set the ownership of the projectile launcher to the player during grab for this feature to work as expected. Having the local player own the launcher will also have the benefit of instant projectile launcher feedback.

Set the action button icons

You can use the action button icons to determine which control icons are visible on mobile devices. You can select which icons are visible for grabbable entities by selecting the entity and then choosing the action icons for Primary Action Icon, Secondary Action Icon and Tertiary Action Icon. Setting action icons for any of these is optional. By default, all action buttons will show for a grabbable entity, with a generic action icon for each button.

To select an action icon, select the Primary Action Icon, Secondary Action Icon or Tertiary Action Icon dropdown, and then choose the most appropriate icon for the intended action. Selecting None removes the control from the screen. You should select None if you don’t intend to use Primary, Secondary or Tertiary action buttons on the grabbable entity.

Hide action buttons by default

You can hide all action buttons for every grabbable entity by default, so that grabbable entities only display the buttons where the action icons have been explicitly set. The available actions and the icons can then be individually enabled. This setting can be enabled in the Player Settings.

Manage button presses

Each action button is hooked up to a CodeBlock event that fires when the player holds the grabbable entity with the script attached, and presses the appropriate action button. You can use CodeBlocks to catch these events and then trigger functionality in the world.

Available action icons

The pool of available icons grows continually. The following table lists examples of icons that you can set for controls on web and mobile.

Crosshair selection

Picking up a grabbable item in Meta Horizon worlds for web and mobile displays a crosshair in the center of the screen. By default this crosshair is a dot. You can change the crosshair type using the Crosshair Type property on grabbable entities.

Current crosshair options include: