Develop

Getting Started with Gaze Interactions

Updated: Sep 8, 2026

Overview

Gaze interaction adds eye-gaze far interaction, with a head-gaze fallback, that uses the user’s gaze as the pointing ray. The user looks at a far UI panel, a grabbable object, or a hover-only object, and a nominated hand’s pinch or select action actuates whatever is under gaze. This lets far-field interactions work without the user pointing a hand ray.

When you finish this guide, you should be able to:

Turn on gaze support for your project.
Add the gaze rig to a pawn that already uses the Interaction SDK hand rig.
Make far UI, grabbables, and hover-only objects targetable by gaze.
React to gaze targeting from Blueprints or C++.
Enter gaze mode and test the behavior on desktop and on device.

This guide assumes you already have an interaction-ready pawn. If you have not set one up yet, see Getting Started with Interaction SDK for Unreal Engine first.

For a complete working implementation, see the GazeExamples level in the Interaction SDK Samples for Unreal Engine.

Prerequisites

The Meta XR Interaction SDK plugin is enabled, and your pawn already uses the Interaction SDK standard hand rig setup.
The Epic OpenXR plugin is enabled, and Project Settings > Plugins > Meta XR > General > XR API is set to Epic Native OpenXR.
Eye tracking requires eye-tracking hardware and the horizonos.permission.EYE_TRACKING runtime permission. If the hardware is unavailable or permission is denied under Native OpenXR, Gaze Fallback Behavior selects head-directed gaze (HmdFallback) or disables gaze (DisableGaze).

Turn On Gaze Project-Wide

Gaze is disabled by default. Enable it in the project settings before adding the gaze rig.

Open Project Settings > Plugins > Meta XR - InteractionSDK, then select the Gaze group.
Note: The settings appear under Plugins > Meta XR - InteractionSDK. The settings class display name is Meta XR - Interaction, so that label may also appear in some editor views.
Set Gaze Enabled to true. This is the master switch for gaze support. It also gates the eye-tracking permission request, and it seeds the gaze rig to start in gaze mode.
Note: Allow Gaze By Default and Gaze Fallback Behavior appear in the editor only after Gaze Enabled is set to true.
With Gaze Enabled on, configure the two properties that become visible under the Gaze group:
- Allow Gaze By Default: Controls whether interactables that use the UsePluginSetting gaze policy are targetable by gaze.
- Gaze Fallback Behavior: Controls what happens when eye tracking is unavailable. Supported values are DisableGaze and HmdFallback.
Optionally set Gaze Mouse Drag Buttons, which is always visible in the Gaze group and is not gated by Gaze Enabled:
- Gaze Mouse Drag Buttons: Controls which mouse buttons hold the Play-in-Editor gaze ray during drag emulation. Supported values are LeftOrRight (default), LeftOnly, RightOnly, and None.

Add the Gaze Rig to Your Pawn

The gaze rig drives a single far-UI region interactor and injects gaze targeting into the grabbers on the same actor.

Open the pawn that contains your existing Interaction SDK hand rigs.
In the Components panel, add a UIsdkGazeRigComponent. Its Blueprint display name is ISDK Gaze Rig Component. Add it to the same actor that holds the hand rigs so the gaze rig can inject gaze targeting into their grabbers.
Compile and save the pawn.

When the component is present, it starts in gaze mode by default, seeded from the project-level Gaze Enabled setting. You can enable or disable gaze at runtime, as described in Enter Gaze Mode and Actuate.

Make Content Gaze-Targetable

Gaze can target ray interactables, grabbables, and hover-only objects when those objects allow gaze interaction and their colliders can be hit by the gaze trace.

On far-UI widgets, ray interactables, or grabbables, set the GazePolicy property. Use Allow to always allow gaze targeting, or UsePluginSetting to follow the project-level Allow Gaze By Default setting.
Ensure the object’s collider blocks the gaze trace channel. Gaze targeting uses the channel set in GazeCollisionChannel, which defaults to ECC_Visibility. An Overlap or Ignore response produces no hit.
For a hover-only feedback object, add a UIsdkHoverableComponent, exposed as ISDK Hoverable. This component responds to Hover and Unhover events, treats Cancel as Unhover, and ignores Select, Unselect, and Move.
- Give the actor a query-enabled collider on the same actor that Blocks the gaze trace channel.
- Bind the component’s InteractionPointerEvent delegate to drive highlight, audio, or tooltip responses.

Enter Gaze Mode and Actuate

Gaze mode starts automatically when Gaze Enabled is on. If it is off, or you want runtime control, enter gaze mode explicitly.

Enter gaze mode with one of the following:
- Call SetGazeMode(true) on the gaze rig.
- Call ToggleGazeMode() on the gaze rig.
- Run the Meta.InteractionSDK.ToggleGazeMode console command, which toggles all gaze rigs in the world.
```
 // GazeRig is your pawn's UIsdkGazeRigComponent.
 GazeRig->SetGazeMode(true);
```
While gaze mode is active, the user looks at a target and the nominated hand’s pinch or select action actuates it.
To tune how far UI targeted by gaze behaves while a hand holds a grab, set EIsdkGazeGrabInteractionBehavior. Supported values are AllowNewHovers, BlockNewHovers, and DropAllHovers.

Hand and controller rays are disabled while gaze mode is active, and they are restored when gaze mode is turned off.

Test the Behavior

You can test gaze on desktop for rapid iteration or on device for the full experience.

For rapid iteration on desktop without a device, use the Play-in-Editor gaze emulator. It deprojects the mouse cursor into a world-space gaze ray. The emulator applies to desktop Play-in-Editor only, not VR Preview.
For on-device testing on a device that lacks eye-tracking hardware, set Gaze Fallback Behavior to HmdFallback. Gaze then uses the head-forward fallback.
For a device with eye tracking, deploy the APK as usual and grant the eye-tracking permission when prompted.
To debug why a far-UI panel is not responding to gaze as expected, add a UIsdkWidgetRegionDebugComponent to the actor that owns the panel. Its Blueprint display name is ISDK Widget Region Debug Component.
- It draws an unfilled wireframe box per targeting region. The whole-panel region is drawn in a distinct color from the sub-widget regions.
- With bAutoWireWidget set to true (the default), the component auto-wires to the owning actor’s first UWidgetComponent at BeginPlay when WidgetComponent is not set.
- Its visualization is compiled out of Shipping builds.
For more detail on the component, see the sibling Gaze Interactions in Interaction SDK overview page.

To explore a prebuilt setup, open the GazeExamples sample level. The IsdkSamplePawn has been updated to include the gaze rig component.

The GazeExamples level with a video panel, a UI panel, and gaze-targetable props on a table.

React to Gaze in Game Code

Access the rig-owned targeting component through UIsdkGazeRigComponent::GetGazeTargeting(), then bind its delegates or poll its getters.

The targeting component exposes these Blueprint-assignable delegates:

Delegate	Fires when
`OnGazeTargetChanged`	The current ray interactable target changes
`OnGazeHoverableChanged`	The current hoverable changes
`OnGazeGrabbableChanged`	The current grabbable changes
`OnGazeMove`	The gaze hit result moves
`OnGazeGrabbableMove`	The gaze hit result over a grabbable moves
`OnGazePrimarySourceUnavailable`	The primary gaze source cannot produce a valid pose and Gaze Fallback Behavior is `DisableGaze`

You can also poll the current state with GetCurrentGazeTarget(), GetCurrentHoverable(), GetCurrentGrabbable(), GetCurrentHitResult(), and GetCurrentGazePose().

In C++: Bind a delegate through the targeting component.

// GazeRig is your pawn's UIsdkGazeRigComponent.
UIsdkGazeTargetingComponent* Targeting = GazeRig->GetGazeTargeting();
Targeting->OnGazeTargetChanged.AddDynamic(this, &AMyPawn::HandleGazeTargetChanged);

To read overall gaze state for UI or telemetry, use the GetGazeState function on UIsdkGazeFunctionLibrary. This is a Blueprint-accessible static function that takes a world context object.

// Called from a pawn or actor with a valid game world.
EIsdkGazeState State = UIsdkGazeFunctionLibrary::GetGazeState(this);

Note: Pass a valid game-world context object, such as a pawn or actor, to GetGazeState. A UMG widget’s own context can resolve to the wrong world, so prefer calling from the actor and passing the resulting value into the widget.

Troubleshooting

An Object Never Highlights Under Gaze

Confirm that the object’s collider Blocks the gaze trace channel, that the collider is query-enabled, and that the collider is on the same actor as the interactable or hoverable component. Overlap and Ignore responses produce no hit. Also confirm that the object’s GazePolicy allows gaze, either through Allow or through UsePluginSetting with Allow Gaze By Default enabled.

Gaze State Is Not Eye Tracking or HMD Fallback

Confirm that Gaze Enabled is on in the project settings and that a UIsdkGazeRigComponent is present. If no gaze rig is present, UIsdkGazeFunctionLibrary::GetGazeState returns DisabledBySettings. Also confirm that you are passing a valid game-world context object to GetGazeState. The Output Log message Gaze interaction requires Native OpenXR. Gaze remains disabled while MetaXR/OVRPlugin is the active XR provider. means MetaXR/OVRPlugin is active and gaze is disabled regardless of Gaze Fallback Behavior.

Pinch Does Nothing While Looking at a Target

The nominated selecting hand must be tracked for its pinch or select action to actuate the target under gaze. Confirm that the hand is tracked before actuating.