> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-usage-examples.md). # Gaze attention usage examples These Blueprint recipes show the most common `UConvaiPlayerComponent` and `UConvaiObjectComponent` gaze-attention patterns. Each example states its scenario, the setup required, and the expected runtime outcome. Complete [Gaze attention quick start](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md) first if gaze attention is not enabled yet or you have not tagged a world object. ### React to a gaze event in Blueprint **Scenario:** A safety-drill simulation highlights dangerous equipment when the player looks at it and plays a warning sound. **Setup:** In the player pawn's Event Graph, bind to `OnGazeBegin` on `UConvaiPlayerComponent`. ``` // Blueprint pseudocode — wire these nodes in the Event Graph Event BeginPlay → Get Component (UConvaiPlayerComponent) → Bind Event to OnGazeBegin → Custom Event: OnPlayerGazeBegin(PlayerComponent, ObjectComponent) → Play Sound at Location (WarningCue) ``` The `ObjectComponent` parameter on the event carries the `UConvaiObjectComponent` that was entered. Read its `ObjectEntry.Name` to identify which object triggered the event. In Blueprint, `ObjectEntry` is exposed as a struct pin — expand it to access the `Name` field. `OnGazeEnd` fires when gaze leaves the object, regardless of whether attention was ever promoted. Use it to stop looping effects started in `OnGazeBegin`. **Outcome:** The warning sound plays the instant the crosshair enters a tagged object — before the attention threshold is reached. ### Change the highlight color per object type **Scenario:** A corporate-onboarding experience uses a green highlight for safe-to-interact items and a red highlight for restricted areas. **Setup:** Bind to `OnGazeBegin` and set `GazeHighlightColor` on the player component before the next object is highlighted. ``` // Blueprint pseudocode Event OnPlayerGazeBegin(PlayerComponent, ObjectComponent) → Branch: ObjectComponent.ObjectEntry.Name == "RestrictedPanel" True → Set GazeHighlightColor (1.0, 0.1, 0.1, 1.0) // red False → Set GazeHighlightColor (0.1, 1.0, 0.1, 1.0) // green ``` `GazeHighlightColor` is `BlueprintReadWrite` on `UConvaiPlayerComponent`. The player component applies the highlight before it broadcasts `OnGazeBegin`, so a color change in this event affects the next highlighted target unless you refresh the highlight through a custom highlight actor. **Outcome:** Each object type receives a distinct silhouette color with no additional assets required. ### Use a custom highlight actor **Scenario:** A medical-training simulation requires a pulsing glow effect rather than a static silhouette. **Setup:** 1. In the Content Browser, create a new Blueprint class with parent `AConvaiGazeHighlightActor`. Name it `BP_PulsingGazeHighlight`. 2. In the Blueprint class defaults, enable **Can Ever Tick** (the base C++ class disables ticking on UE 5.3+). Override `Tick` to animate `EmissiveIntensity` using a sine curve over time. 3. On `UConvaiPlayerComponent`, set `GazeHighlightActorClass` to `BP_PulsingGazeHighlight`. The player component spawns and destroys the highlight actor automatically. `GetTarget()` and `GetTargetComponent()` in the Blueprint subclass give read access to the current target if the custom effect needs to attach to it. **Outcome:** Every gazed-at object shows an animated pulsing glow instead of the static Fresnel silhouette. ### Lock attention to an object manually **Scenario:** A narrative sequence must hold the character's attention on a briefing screen regardless of where the player looks. {% hint style="info" %} `SetObjectInAttention` has no effect when **Enable Actions** (`EnvironmentData.bEnableActions`) is `false` on the chatbot. Confirm actions are enabled before wiring this pattern. {% endhint %} **Setup:** Call `SetObjectInAttention` directly from Blueprint at the start of the narrative beat. ``` // Blueprint pseudocode Event NarrativeBriefingStart → Get Component (UConvaiChatbotComponent) → SetObjectInAttention AttentionObject: (FConvaiObjectEntry for "BriefingScreen") Text: "The player is reviewing the mission briefing." ShouldRespond: Always bFlushImmediately: false ``` After this call, `AttentionSource` on the chatbot becomes `Explicit (Blueprint/C++)`. Gaze-driven attention updates are silently rejected until the lock is cleared. To release the lock at the end of the narrative beat: ``` // Blueprint pseudocode Event NarrativeBriefingEnd → SetObjectInAttention AttentionObject: (empty FConvaiObjectEntry — leave Name blank) Text: "" ShouldRespond: Never ``` Passing an empty `FConvaiObjectEntry` clears the attention slot and resets `AttentionSource` to `None`, allowing gaze to take over again. **Outcome:** The character focuses on the briefing screen for the duration of the cutscene, then resumes normal gaze-driven attention. ### Build a custom cursor widget **Scenario:** A first-person simulation needs a crosshair image that changes from a dot to a target reticle when the player looks at a Convai object. **Setup:** 1. Create a new Blueprint class with parent `UConvaiGazeCursorWidget`. Name it `BP_TargetReticleCursor`. 2. Add an `Image` widget to the Blueprint widget tree. Set its brush to the dot image by default. 3. Implement `OnGazeStateChanged`: ``` // Blueprint pseudocode — inside BP_TargetReticleCursor Event OnGazeStateChanged(bInGazeActive) → Branch: bInGazeActive True → Set Image Brush (TargetReticleBrush) False → Set Image Brush (DotBrush) ``` 4. On `UConvaiPlayerComponent`, set `GazeCursorWidgetClass` to `BP_TargetReticleCursor`. `SetGazeActive` is still called on the custom class at runtime by the player component. `IsGazeActive()` is available as a Blueprint Pure function if the widget needs to poll state elsewhere. **Outcome:** The reticle changes image every time gaze enters or leaves a Convai object, with no changes to the player pawn Blueprint required. ### Adjust timing for a simulation with many close objects **Scenario:** A factory-floor simulation places Convai objects within 1–2 metres of each other. The default 1-second dwell and 5-second release result in the character reacting to unintentional glances. **Setup:** On `UConvaiPlayerComponent`, adjust the timing properties in the **Details** panel or at runtime: ``` // Blueprint pseudocode — called during BeginPlay Get Component (UConvaiPlayerComponent) → Set GazeAttentionDelay = 2.0 // require a longer deliberate look → Set GazeAttentionLossDelay = 2.0 // release attention more quickly after looking away ``` Both properties are `BlueprintReadWrite` and can be changed at runtime, for example to tighten tolerances during an assessment phase and relax them during free exploration. **Outcome:** The character only promotes attention after a deliberate two-second look, and releases it quickly when the player glances away. ### Expose individual sub-components of a complex actor **Scenario:** An industrial-safety simulation uses a single `BP_ControlPanel` actor that has two independently interactable parts: an `EmergencyStop` button and a `FuelGauge` dial. Looking at each part should trigger a different AI response. **Setup:** 1. Select `BP_ControlPanel` in the level. In the **Details** panel, click **Add Component** twice to add two `UConvaiObjectComponent` instances. Name them `ConvaiObject_EmergencyStop` and `ConvaiObject_FuelGauge` (the component label is for editor clarity; the gaze filter uses `ObjectEntry.ComponentName`). 2. Configure `ConvaiObject_EmergencyStop` under **Convai | Object** → **Object Entry**: * **Name** — `"EmergencyStop"` * **Description** — `"A red mushroom button that cuts power to the whole line."` * **Move Target Mode** — `Component as goal` (required for sub-mesh scoping) * **Component Name** — `"SM_EmergencyStopButton"` (the exact Static Mesh component name on the actor) 3. Configure `ConvaiObject_FuelGauge` under **Convai | Object** → **Object Entry**: * **Name** — `"FuelGauge"` * **Description** — `"A dial showing current fuel pressure in bar."` * **Move Target Mode** — `Component as goal` * **Component Name** — `"SM_FuelGaugeDial"` 4. On `UConvaiPlayerComponent`, ensure **Gaze Attention Text** (`GazeAttentionText`) and **Gaze Should Respond** (`GazeShouldRespond`) are configured as needed. `ObjectEntry.ComponentName` matching is case-insensitive substring lookup and applies only when **Move Target Mode** is `Component as goal`. With the default **Actor as goal** mode, a non-empty **Component Name** does not scope gaze. If the name cannot be resolved, the component is excluded from scoped gaze detection and a warning is logged on first component resolve. Call `GetResolvedComponent(true)` on the `UConvaiObjectComponent` at runtime to confirm the match. **Outcome:** Looking at `SM_EmergencyStopButton` highlights only that mesh and promotes `"EmergencyStop"` to attention. Looking at `SM_FuelGaugeDial` highlights only that mesh and promotes `"FuelGauge"`. Looking at the panel frame does not promote either scoped object because no configured component scope matches that hit. ### Next steps {% content-ref url="/pages/tzRboWm1eecuLuhSsAmt" %} [How gaze attention works](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md) {% endcontent-ref %} {% content-ref url="/pages/Y1a2EJCnlVUVqiuNeKuC" %} [Gaze attention reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md) {% endcontent-ref %} {% content-ref url="/pages/vhd0cZEs5OqbzqVwljKh" %} [Troubleshoot gaze attention](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-usage-examples.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.