Meta Developers

As of August 31, 2022, Mobile SDK and the VrApi library are no longer supported. Future updates will be delivered through OpenXR extensions and our OpenXR Mobile SDK, not through any new updates to Meta Mobile or PC APIs.

Discontinuing Mobile SDK support means:

New apps must use OpenXR unless a waiver is granted.
New apps will not have access to Meta Native Mobile APIs, but existing apps can continue using them.
No assistance will be provided for creating new apps with Meta Native APIs. You will find recommendations for migrating existing apps to OpenXR in the developer guides.
Only critical security, privacy, or safety issues in Meta Native APIs will be addressed.
Any testing of Meta Native Mobile will be restricted to automated QA tests, only to ensure core features remain functional.

For more information about this deprecation, see Meta All In on OpenXR: Deprecates Proprietary APIs.

Meta allows users to define their play area with a Guardian boundary visualization. This visualization triggers based on the user’s proximity to the bounding shape that the user has configured. The boundary visualization is handled by Meta software and is superimposed over the game or experience. Developers may interact with the Guardian boundary in various ways. Possible use cases include pausing the game if the user leaves the play area, or placing geometry in the world based on boundary points to create a “natural” integrated barrier with in-scene objects. When a user approaches the boundary, the runtime automatically provides visual cues to the user that it is near.

Guardian Functionality

Roomscale versus Seated

Roomscale experiences require a minimum amount of unobstructed floor space. It is recommended that there be a 9ft x 9ft space with a 6ft x 6ft playable area free of obstructions for roomscale play.

Seated (stationary) experiences should not promote much movement beyond reaching with arms or leaning from the torso.

Local versus Stage

The default tracking space is Local, which means re-centering works as normal. This is the correct behavior for most apps.

Some apps may want to remain anchored to the same space for the duration of the experience because they lay out according to the user’s Guardian bounds. For example, an app might dynamically lay out furniture to take advantage of the full Guardian space defined by the user. These apps may want to use the Stage tracking space. The Stage space has its origin on the floor at the center of the play area with its forward direction pointed towards one of the edges of the bounding box. This is not changed by the user-initiated re-center. However, it may still change mid-app if a user walks from one Guardian space to another, so you will still want to double-check the bounds when the app returns from a paused state.

There is also a Local Tilted tracking space for “bed mode” support. This space defines the tilted orientation a user would like their content displayed in.

Set the tracking space by passing a ovrTrackingSpace value to vrapi_SetTrackingSpace as shown in these examples:

vrapi_SetTrackingSpace( ovr, VRAPI_TRACKING_SPACE_LOCAL );
vrapi_SetTrackingSpace( ovr, VRAPI_TRACKING_SPACE_STAGE );
vrapi_SetTrackingSpace( ovr, VRAPI_TRACKING_SPACE_LOCAL_TILTED );

Setting Up Guardian

The initial setup experience directs users to create their Guardian System. The Guardian System validates the user-defined boundary for the minimum required space. If the user does not have enough physical space to create the minimum required bounds, they will have the option to play seated/stationary. The seated/stationary boundary is a predefined boundary centered around the user’s HMD. After the initial setup scenario is completed, users will have the ability to create new Guardian boundaries in the same or a new space.

When the user starts a VR experience in a room with a Guardian boundary defined, the system automatically identifies the user’s room and associated Guardian bounds. The tracking system must be functional in order for saved boundaries to be recognized. This allows users to quickly start their VR experience without having to create a new boundary whenever they want to use their Meta Quest.

If your head or controllers approach the edge of the Guardian space, the pass-through camera view will fade in so you can avoid objects outside of the Guardian space and return safely to the play area. You will also be given the option to create additional Guardian areas.

Due to the unique immersive qualities provided by the untethered Meta Quest, at least one Guardian boundary must be created for the chosen play area before the user will be allowed to begin their VR experience.

Guardian API

The following functions return information about the outer boundary and play area:

Function Description

Function	Description
`vrapi_GetBoundaryGeometry`	Gets the geometry of the Guardian System as list points that define outer boundary space. You can choose to get just the number of points by passing in a null value for `points` or by passing in a `pointsCountInput` size of 0. Otherwise `pointsCountInput` will be used to fetch as many points as possible from the Guardian points data. If the input size exceeds the number of points that are currently stored off, we only copy up to the number of points that we have, and `pointsCountOutput` will return the number of copied points.
`vrapi_GetBoundaryOrientedBoundingBox`	Gets the dimension of the oriented bounding box for the Guardian System. This is the largest fit rectangle within the Guardian boundary geometry. The `pose` value contains the forward facing direction as well as the translation for the oriented box. The `scale` return value returns a scalar value for the width, height, and depth of the box. These values are half the actual size as they are scalars and in meters.

vrapi_GetBoundaryGeometry

Gets the geometry of the Guardian System as list points that define outer boundary space. You can choose to get just the number of points by passing in a null value for points or by passing in a pointsCountInput size of 0. Otherwise pointsCountInput will be used to fetch as many points as possible from the Guardian points data. If the input size exceeds the number of points that are currently stored off, we only copy up to the number of points that we have, and pointsCountOutput will return the number of copied points.

vrapi_GetBoundaryOrientedBoundingBox

Gets the dimension of the oriented bounding box for the Guardian System. This is the largest fit rectangle within the Guardian boundary geometry. The pose value contains the forward facing direction as well as the translation for the oriented box. The scale return value returns a scalar value for the width, height, and depth of the box. These values are half the actual size as they are scalars and in meters.

During runtime you can request the status information of a given point or from a given input device using the following functions:

Function	Description
`vrapi_TestPointIsInBoundary`	Tests collision/proximity of a 3D point against the boundary system and returns whether or not a given point is inside or outside of the Guardian boundary. If a more detailed set of boundary trigger information is requested, an `ovrBoundaryTriggerResult` may be passed in. However, null may also be passed in to just return whether a point is inside the boundary or not.
`vrapi_GetBoundaryTriggerState`	Tests collision/proximity of position-tracked devices (such as the HMD and/or Meta Quest Touch Controllers) against the Guardian boundary. This function returns an `ovrGuardianTriggerResult` which contains information such as distance and closest point based on collision/proximity test.

The ovrBoundaryTriggerResult struct that is populated during these function calls consists of the following members:

Member	Type	Description
`closestPoint`	`ovrVector3f`	Closest point on the boundary surface.
`closestPointNormal`	`ovrVector3f`	Normal of the closest point on the boundary surface.
`closestDistance`	`float`	Distance to the closest Guardian boundary surface.
`isTriggering`	`bool`	True if the boundary system is being triggered. Note that due to fade in/out effects this may not exactly match visibility.

When retrieving bounds trigger information with vrapi_GetBoundaryTriggerState, use one of the following ovrTrackedDeviceTypeId values to specify an input device:

Enum	Value	Description
`VRAPI_TRACKED_DEVICE_HMD`	`0`	Headset.
`VRAPI_TRACKED_DEVICE_HAND_LEFT`	`1`	Left controller.
`VRAPI_TRACKED_DEVICE_HAND_RIGHT`	`2`	Right controller.

Additionally, you can set the bounds to be visible to orient the user or explain how you will use the space by calling vrapi_RequestBoundaryVisible with true. When you are finished, simply pass false and the bounds will behave as they should normally.

Function	Description
`vrapi_RequestBoundaryVisible`	Used to force Guardian mesh visibility to true. Setting back to false will set the Guardian system back to regular functionality.
`vrapi_GetBoundaryVisible`	Used to query whether or not the Guardian visualization is visible.

Did you find this page helpful?