Unreal Samples

Oculus provides samples which illustrate basic VR concepts in Unreal such as Touch, haptics, and the Boundary Component API for interacting with the Guardian System.

Samples are available from the Oculus Unreal GitHub repository. To access this repository, you must be subscribed to the private EpicGames/UnrealEngine repository (see https://www.unrealengine.com/ue4-on-github for details). An Unreal license is not required.

All samples require a compatible version of the Unreal Engine which supports the illustrated features. To explore samples, we generally recommend using Unreal versions that we ship from our GitHub repository, which always include the latest features. For a review of which Unreal versions support which features, see Unreal Game Engine.

Guardian and Play Area Sample App

This sample app:

  • Demonstrates how to use Blueprints to access the Oculus Guardian System
  • Demonstrates how to position, scale, and rotate objects with respect to the Play Area
  • Demonstrates how to determine when the Guardian boundary is viloated by the headset or either controller

This sample app only works with 6DOF (six degrees of freedom) headsets, currently the Oculus Rift.

Outer Boundary and Play Area

This sample app renders both the Outer Boundary and the Play Area. The Outer Boundary is the complex set of points and interconnecting lines that the user draws when they setup their boundaries. The Play Area is an automatically generated rectangle within the Outer Boundary:

Sample App Behavior

This sample renders the left and right controllers as black checkered spheres. It also displays a cylinder. The cylinder disappears whenever the headset or either of the controllers violate the guardian.

Drawing the Boundaries and Positioning Objects

The body of the Blueprint contains two For loops that draw the Play Area and Outer Boundary.

The first For loop steps through the Outer Boundary points by calling Get Guardian Points with the Boundary Type set to Outer Boundary. It draws each point on the floor as Debug Point’s, and then draws lines between the Debug Point’s.

The following image shows part of the unit cube (white) that has been transformed to conform to the Play Area. The black area is the shadow of the cube. You can see part of the outline of the Outer Boundary, along the floor. In the headset, the white cube is translucent, and you can see where the Outer Boundary continues along the floor. In the headset, you can also see the vertical lines that make up the Guardian representation, whenever the headset or either of the controllers violate the boundary.

The portion of the Blueprint that draws the Outer Boundary is shown below:

This code calls Get Guardian Points which returns an array that contains all the positions of the Guardian points. The Guardian has no height; it is an infinitly high vertical boundary. So, this For loop draws the Guardian points on the floor and connects them with lines. The Draw Debug Line node takes the current point and the next point (with an index that is incremented by 1), and draws the line segment between them.

You can press ‘Q’ on the keyboard (when using the Oculus Rift) to redraw the Outer Boundary. Alternatively, press the trigger on the right controller. (The future Oculus Quest headset does not connect to a PC, so it is not possible to type ‘Q’ on a keyboard.)

The subsequent For loop works in a similar manner, except it retrieves the Play Area points, instead of the Outer Boundary points:

Display and Hide the Cylinder

An Event Tick is fired on every frame:

On each frame, we check to see if the Guardian is visible. The Guardian will be displayed whenever the headset or one of the controllers is violating the boundary. If the Guardian is displayed, we hide the Cylinder. Otherwise, we show the Cylinder:

Setting the Transform for Objects in the Play Area

On each frame we get the Play Area transform, and position a unit cube to align with the Play Area:

By using the above approach, SetWorldTransform enables you to easily scale, rotate, and position objects with respect to the Play Area. The Play Area is a rectangle, so it has three properties: Scale (width and length), Position (the center position), Rotation. It is possible to transform a unit cube - or any other object that you wish - to conform with the Play Area transform by using the technique shown above.

You can use this approach for a wide variety of purposes within your app. For example, if you want to know where the center of the Play Area is, just use the position property of the Transform. If you want to know the rotation value for the Play Area, use the rotation property of the Transform. And, if you want to know the size of the Play Area, read the scale property of the Transform.

If you want to map the floor of your game/app to the Play Area, take the floor and give it a 1m x 1m size. Then you scale/position/rotate it according to the Transform properties.

In this sample, a transform of a 1m x 1m unit cube is placed at the floor of the Play Area. So, if you look down, you will see the cube (as shown earlier in this section). The scale value for the height of the unit cube is 1, which makes it 1m in height. It rises 50 cm above the floor because it is centered vertically with half of the cube above the floor, and half below.

Suppose you want to place something 1m from the center of the Play Area, such as a sword. To do this, you would call Get Play Area Transform, retrieve the center of the Play Area from the Position property of the transform. Add 1m in the desired direction. Then call SetWorldPosition. This works regardless of the position of the Play Area within the UE4 world.

Suppose you don’t want to position the sword an absolute meter from the center of the Play Area, but rather to a location that is relative to the size of the Play Area. For example, you may have a 20 m Play Area in the X direction, and you want to position the sword half of that distance (in this case 10 m) in the X direction. You would position the sword at 0.5 x the scale of the Play Area in the X direction. You obtain this from the Transform.

Note that the Outer Boundary doesn’t have a Transform, because it has a significantly more complex shape which does not have an obvious scale, position, and rotation. Since the Outer Boundary is too complex for normal game development, the Play Area was created to simplify app development.

Manually Modifying the Guardian Visibility

This sample app also provides the ability to manually hide or show the Guardian. Press 'V' on the keyboard or press the right controller’s FaceButton1 to call Set Guardian Visibility with Guardian Visible to True. Similarly, press 'X' on the keyboard or press the right controller’s FaceButton2 to call Set Guardian Visibility with Guardian Visible to False.

Layer Sample

LayerSample is a Blueprint sample that illustrates the use of VR Compositor Layers to display a UMG UI.

This sample includes two spheres that track with the Touch controllers and two UMG widgets rendered as VR Compositor layers. One is rendered as a quad layer and the other as a cylinder layer.

Actor_Blueprint illustrates rendering a UMG widget into a stereo layer. The widget is first rendered into a Material, then the SlateUI texture is pulled from the Material into the stereo layer. This is the UMG widget that is rendered to the quad and cylindrical layers in the sample.

Open MenuBlueprint to open the UMG widget in the UMG Editor.

NewGameMode and VRCharacter are used to initialize the scene and make the scene display at the appropriate height, and so forth.

Input Samples

The Oculus GitHub repo includes two samples illustrating input in Oculus/Samples. The Gear VR Controller illustrates tracking and input for the Oculus Go Controller and Gear VR Controller - open the Level Blueprint to see a typical implementation.

The Touch sample illustrates tracking, thumbstick control, and haptics control using PlayHapticEffect() and PlayHapticSoundWave(). Two spheres track with the Touch controllers. The right controller thumbstick may be used to control the position of the light gray box. Touch capacitance sensors detect whether the right thumb is in a touch or near-touch position, which controls the height of the box. Press and hold the left Touch grip button to play a haptics clip. Press and hold the left Touch X button to create a haptics effect by setting the haptics value directly.

You will find the Haptics control Blueprint and the Thumbstick control Blueprint in the Touch sample Level Blueprint. NewGameMode and VRCharacter are used to initialize the scene and make the scene display at the appropriate height, and so forth.

Mixed Reality Capture Sample

A trivial sample map with mixed reality capture enabled is available in our GitHub repository (access instructions here) in Samples/Oculus/MixedRealitySample. Select the OculusMR_CastingCameraActor1 instance to see how it is configured for the Level.

For more information, see Oculus Rift: Mixed Reality Capture.

Sample Scene

A trivial sample map with mixed reality capture enabled is available in our GitHub repository (access instructions here) in Samples/Oculus/MixedRealitySample.

Legacy Touch Sample

This is sample is available with legacy versions using Oculus integration 1.14 or earlier - for more information, see Unreal Game Engine.

TouchSample illustrates basic use of Oculus Touch including controller tracking and thumbstick control. It also illustrates haptics control using PlayHapticEffect() and PlayHapticSoundWave(). Two spheres track with the Touch controllers. The right controller thumbstick may be used to control the position of the light gray box. Touch capacitance sensors detect whether the right thumb is in a touch or near-touch position, which controls the height of the box. Press and hold the left Touch grip button to play a haptics clip. Press and hold the left Touch X button to create a haptics effect by setting the haptics value directly.

You will find the Haptics control Blueprint and the Thumbstick control Blueprint in the sample Level Blueprint. NewGameMode and VRCharacter are used to initialize the scene and make the scene display at the appropriate height, and so forth.