OVRBoundary Guardian System API

OVRBoundary exposes an API for interacting with the Rift Guardian System.

The Oculus Guardian System is an in-VR visualization of a user’s Play Area. The boundary visualization is handled automatically by Oculus software, but developers may interact with the Guardian System in various ways using the OVRBoundary API. 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.

During Touch setup, users define an interaction area by drawing a perimeter called the Outer Boundary in space with the controller. An axis-aligned bounding box called the Play Area is calculated from this perimeter.

When tracked devices approach the Outer Boundary, the Oculus runtime automatically provides visual cues to the user demarcating the Outer Boundary. This behavior may not be disabled or superseded by applications, though the Guardian System visualization may be disabled via user configuration in the Oculus app.

See OVRBoundary in our Developer Reference for additional details.

Basic Use

Boundaries are BoundaryType.OuterBoundary and BoundaryType.PlayArea.

Node types are Node.HandLeft, Node.HandRight, and Node.Head.

Applications may query the location of nodes relative to the Outer Boundary or Play Area by using OVRBoundary.BoundaryTestResult TestNode(), which takes the node and boundary type as arguments.

Applications may also query arbitrary points relative to the Play Area or Outer Boundary using OVRBoundary.BoundaryTestResult TestPoint(), which takes the point coordinates in the tracking space as a Vector3 and boundary type as arguments.

Results are returned as a struct called OVRBoundary.BoundaryTestResult, which includes the following members:

MemberTypeDescription
IsTriggeringboolReturns true if the node or point triggers the queried boundary type.
ClosestDistancefloatDistance between the node or point and the closest point of the test area.
ClosestPointVector3Describes the location in tracking space of the closest boundary point to the queried node or point.
ClosestPointNormalVector3Describes the normal of the boundary point that is closest to the queried node or point.

Applications may request that boundaries be displayed or hidden using OVRBoundary.SetVisible(). Note that the Oculus runtime will override application requests under certain conditions. For example, setting Boundary Area visibility to false will fail if a tracked device is close enough to trigger the boundary’s automatic display, and setting the visibility to true will fail if the user has disabled the visual display of the boundary system.

Applications may query the current state of the boundary system using OVRBoundary.GetVisible().

Additional Features

OVRBoundary.GetGeometry() returns an array of up to 256 points that define the Boundary Area or Play Area in clockwise order at floor level. You may query the dimensions of a Boundary Area or Play Area using OVRBoundary.GetDimensions(), which returns a Vector3 containing the width, height, and depth in tracking space units, with height always returning 0.