> 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/getting-started/scene-components-reference.md).

# Scene components reference

This page is a reference for the four components the Convai plugin provides. Use it while building or debugging your scene. For a step-by-step walkthrough of adding components, see [Add your first Convai character](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md).

The Convai Unreal Engine plugin adds four components to Unreal Engine. Each has a distinct role — understanding their responsibilities prevents the most common wiring mistakes.

### Component roles

| Component        | Class                      | Search name in Add menu       | Attach to                                   |
| ---------------- | -------------------------- | ----------------------------- | ------------------------------------------- |
| Convai Chatbot   | `UConvaiChatbotComponent`  | `BP Convai ChatBot Component` | NPC character Blueprint                     |
| Convai Player    | `UConvaiPlayerComponent`   | `BP Convai Player Component`  | Player pawn Blueprint                       |
| Convai Object    | `UConvaiObjectComponent`   | `Convai Object`               | Any in-scene Actor the AI should know about |
| Convai Face Sync | `UConvaiFaceSyncComponent` | `Convai Face Sync`            | NPC character Blueprint                     |

{% hint style="info" %}
**BP vs bare component:** Searching `BP Convai ChatBot Component` or `BP Convai Player Component` adds the Blueprint-wrapped version, which comes pre-wired with push-to-talk input and the chat UI widget. Searching `Convai Chatbot` or `Convai Player` adds the bare C++ component — this works but requires you to wire push-to-talk, chat widget, and audio capture yourself.
{% endhint %}

### How the components connect

```mermaid
graph TD
    A["Player Pawn"] --> B["UConvaiPlayerComponent\ncaptures microphone audio"]
    B -->|"streams audio / receives responses"| C["UConvaiChatbotComponent\nmanages conversation with Convai"]
    D["NPC Character Blueprint"] --> C
    D --> E["UConvaiFaceSyncComponent\napplies face animation data"]
    C -->|"face animation data"| E
    F["Any Scene Actor"] --> G["UConvaiObjectComponent\nvisible to all chatbots in the level"]
```

The `UConvaiPlayerComponent` and `UConvaiChatbotComponent` connect through the session managed by `UConvaiSubsystem` — a game instance subsystem the plugin registers automatically. You do not need to reference the subsystem directly in most Blueprint setups.

### Component details

{% tabs %}
{% tab title="Convai Chatbot" %}
`UConvaiChatbotComponent` is the AI brain for a non-player character. It holds the `CharacterID` that links the component to a character you created on the Convai dashboard. At runtime it connects to Convai, receives player speech or text from a `UConvaiPlayerComponent`, and streams the response back.

**Editable Details panel fields:**

| Field                           | Default   | Description                                                                                                                                                                                                                                                           |
| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CharacterID`                   | *(empty)* | **Required.** The unique ID from the Convai dashboard that identifies which character this component represents.                                                                                                                                                      |
| `bAutoInitializeSession`        | `true`    | When `true`, the component connects to Convai automatically on BeginPlay. Set to `false` to call `StartSession()` manually.                                                                                                                                           |
| `InterruptVoiceFadeOutDuration` | `1.0`     | Seconds over which the character's speech audio fades out when `InterruptSpeech` is called. `0` cuts audio immediately. See [Configure character audio](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-character-audio.md). |

**Runtime value (read-only):** `CharacterName` is populated from the character's dashboard configuration once the session loads. It is `BlueprintReadOnly` — readable in Blueprint but not editable in the **Details** panel. Manage character configuration in the Convai dashboard.

**Useful runtime functions (Blueprint-callable):**

| Function             | Blueprint display name | Returns | Description                                                                             |
| -------------------- | ---------------------- | ------- | --------------------------------------------------------------------------------------- |
| `GetIsTalking()`     | Is Talking             | `bool`  | `true` while the character is speaking.                                                 |
| `IsInConversation()` | —                      | `bool`  | `true` while an active conversation session exists (listening, processing, or talking). |

`IsListening()` and `IsProcessing()` are exposed in Blueprint but currently return `false` in the plugin source. Use `GetIsTalking()` and `IsInConversation()` for reliable state checks until those functions are implemented.

**Blueprint events fired by this component:**

| Event                             | Description                                                 |
| --------------------------------- | ----------------------------------------------------------- |
| `OnActionReceivedEvent_V2`        | The character has determined actions to perform.            |
| `OnEmotionStateChangedEvent`      | The character's emotional state has updated.                |
| `OnCharacterDataLoadEvent_V2`     | Character metadata from the dashboard is ready.             |
| `OnNarrativeSectionReceivedEvent` | A narrative design section was triggered.                   |
| `OnInteractionIDReceivedEvent`    | A new interaction was assigned an ID.                       |
| `OnInterruptedEvent`              | The character's speech was interrupted by new player input. |
| `OnFailureEvent`                  | A network or authentication error occurred.                 |

The `CharacterID` field is the only required field. All other fields have usable defaults.
{% endtab %}

{% tab title="Convai Player" %}
`UConvaiPlayerComponent` represents the human participant in the conversation. It captures microphone audio and streams it to the active `UConvaiChatbotComponent` during a conversation.

**Details panel fields:**

| Field        | Default   | Description                                                                                                              |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `PlayerName` | *(empty)* | Name of the player shown to the AI character in conversation context.                                                    |
| `EndUserID`  | *(empty)* | Persistent identifier for this player, used by the long-term memory feature to recall past interactions across sessions. |
| `bMute`      | `false`   | When `true`, silences microphone input without stopping the session. Toggle at runtime to mute/unmute the player.        |

**Useful runtime functions (Blueprint-callable):**

| Function                           | Returns           | Description                                                                                          |
| ---------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `UnmuteStreamingAudio()`           | `bool`            | Begin streaming microphone audio to the active chatbot.                                              |
| `MuteStreamingAudio()`             | `void`            | Stop streaming audio.                                                                                |
| `UpdateVadBP(EnableVAD)`           | `bool`            | Enable (`true`) or disable (`false`) hands-free voice activity detection. Returns `true` on success. |
| `SendText(ChatbotComponent, Text)` | `void`            | Send a text message to the specified chatbot without microphone input.                               |
| `GetIsStreaming()`                 | `bool`            | `true` while audio is actively streaming to a chatbot.                                               |
| `GetAvailableCaptureDeviceNames()` | `TArray<FString>` | List of available microphone device names.                                                           |
| `SetCaptureDeviceByIndex(Index)`   | `bool`            | Switch to the device at the specified index.                                                         |
| `SetCaptureDeviceByName(Name)`     | `bool`            | Switch to the device with the specified name.                                                        |

One `UConvaiPlayerComponent` on the player pawn can talk to any `UConvaiChatbotComponent` in the level.

**VAD settings (beta.20+):** Voice activity detection thresholds can be configured project-wide in **Edit > Project Settings > Plugins > Convai > Audio Settings | VAD** using `FConvaiVADSettings` fields: `Confidence` (0.0–1.0, default 0.7), `StartSecs` (default 0.2), `StopSecs` (default 2.2), and `MinVolume` (0.0–1.0, default 0.6). Set `bUseServerDefault` to `true` to defer to server-side defaults.

**Pre-wired pawn:** `ConvaiPlayerWithVoiceActivation` (`Content/Core/ConvaiPlayerWithVoiceActivation`) is a ready-to-use player pawn with voice-activation capture. Use it as a starting point when you want hands-free input without calling `UpdateVadBP(true)` manually.
{% endtab %}

{% tab title="Convai Object" %}
`UConvaiObjectComponent` marks an in-scene Actor so every Convai chatbot in the level can reference it by name. Attach it to doors, switches, items, rooms, or any object that your AI characters should be able to name, describe, or interact with.

**Details panel fields:**

| Field               | Default         | Description                                                                                                                                                                                                                                            |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ObjectEntry`       | —               | Identity of the object, shown as inline fields in the **Details** panel. Set **Name** (**required** — the name the AI uses to refer to this object in conversation and actions) and **Description** (a short bio included in the character's context). |
| `TrackedProperties` | *(empty array)* | `UPROPERTY` values on the parent Actor to monitor. When a tracked value changes, the update is pushed to all chatbots automatically.                                                                                                                   |

The component provides each object with:

* **Identity** — the **Name** and **Description** fields of `ObjectEntry`, which appear in the character's context.
* **Live state** — `TrackedProperties` entries that monitor `UPROPERTY` values on the Actor and push updates to chatbots when they change.
  {% endtab %}

{% tab title="Convai Face Sync" %}
`UConvaiFaceSyncComponent` drives blendshape-based lip sync and facial animation on an NPC. It receives pre-computed face animation data from the `UConvaiChatbotComponent` and applies it frame by frame in sync with the character's speech audio.

**Details panel fields:**

| Field         | Default               | Description                                                                                              |
| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
| `LipSyncMode` | MetaHuman Blendshapes | Selects the blendshape target. Must match the character's rig. See the table below for available values. |

**LipSyncMode values:**

| Display name             | Enum value                        | Use with                                                          |
| ------------------------ | --------------------------------- | ----------------------------------------------------------------- |
| Off                      | `EC_LipSyncMode::Off`             | Disables face sync entirely.                                      |
| Auto                     | `EC_LipSyncMode::Auto`            | Lets the plugin choose the mode based on available data.          |
| Viseme Based             | `EC_LipSyncMode::VisemeBased`     | Custom rigs using OVR visemes (15 shapes).                        |
| MetaHuman Blendshapes    | `EC_LipSyncMode::BS_MHA`          | MetaHuman characters and Reallusion CC5 characters. **(Default)** |
| ARKit Blendshapes        | `EC_LipSyncMode::BS_ARKit`        | CC4 characters.                                                   |
| CC4 Extended Blendshapes | `EC_LipSyncMode::BS_CC4_Extended` | Reallusion CC4 characters.                                        |
| {% endtab %}             |                                   |                                                                   |
| {% endtabs %}            |                                   |                                                                   |

### Blueprint wrappers

The plugin ships Blueprint-wrapped versions of each component in `Content/`. Use these instead of the bare C++ components — they include push-to-talk input binding, chat widget integration, and audio capture out of the box.

| Asset                                                       | Content path                               | What it includes                                                                    |
| ----------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------- |
| `BP_ConvaiChatbotComponent` (`BP Convai ChatBot Component`) | `ConvaiConveniencePack/ConvaiBPComponent/` | `UConvaiChatbotComponent` pre-wired with push-to-talk and `Chat_WB`.                |
| `BP_ConvaiPlayerComponent` (`BP Convai Player Component`)   | `ConvaiConveniencePack/ConvaiBPComponent/` | `UConvaiPlayerComponent` pre-wired with push-to-talk, `Chat_WB`, and `UISelection`. |
| `BP_ConvaiSamplePlayer`                                     | `ConvaiConveniencePack/Sample/`            | Sample player pawn with `BP_ConvaiPlayerComponent` attached.                        |
| `BP_SampleGameMode`                                         | `ConvaiConveniencePack/Sample/`            | Game mode that sets `BP_ConvaiSamplePlayer` as the default pawn.                    |
| `BP_Convai3DWidgetComponent` / `WBP_3DChatWidget`           | `ConvaiConveniencePack/3DWidget/`          | In-world 3D chat UI widget component.                                               |
| `Chat_WB` / `MicSettings_WB`                                | `Widgets/`                                 | Screen-space chat overlay and microphone settings panel.                            |
| `ConvaiPlayerWithVoiceActivation`                           | `Core/`                                    | Player pawn with voice-activation (VAD) enabled by default.                         |

{% hint style="warning" %}
`ConvaiBasePlayer` and `ConvaiBaseCharacter` in `Content/Core/` are deprecated. Reparent your classes to a standard Character or Pawn and add `BP_ConvaiPlayerComponent` or `BP_ConvaiChatbotComponent` instead.
{% endhint %}

### Next steps

{% content-ref url="/pages/g8UGNK2Dicyeh9I9zZ6x" %}
[Validate your setup](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/validate-your-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/wO1MGAXD0InYM2apk7cV" %}
[Configure conversation input](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-conversation-input.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/getting-started/scene-components-reference.md?ask=<question>&goal=<endgoal>
```

`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.