Oculus Guardian System

Native SDK
All-In-One VR

Oculus has users 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 Oculus 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 Oculus 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 Oculus 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 Oculus 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:

vrapi_GetBoundaryGeometryGets 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_GetBoundaryOrientedBoundingBoxGets 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:

vrapi_TestPointIsInBoundaryTests 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_GetBoundaryTriggerStateTests collision/proximity of position-tracked devices (such as the HMD and/or Oculus 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:

closestPointovrVector3fClosest point on the boundary surface.
closestPointNormalovrVector3fNormal of the closest point on the boundary surface.
closestDistancefloatDistance to the closest Guardian boundary surface.
isTriggeringboolTrue 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:


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.

vrapi_RequestBoundaryVisibleUsed to force Guardian mesh visibility to true. Setting back to false will set the Guardian system back to regular functionality.
vrapi_GetBoundaryVisibleUsed to query whether or not the Guardian visualization is visible.