Build a custom scene

Add required Convai components to a new Unity scene using the Setup Required Components command and configure your first character.

A new Unity scene needs three Convai components wired together before a character can hear a player and respond: a manager, a character, and a player. Build that hierarchy in an empty scene using the Setup Required Components command, then add and configure the character itself.

Minimum required hierarchy

Every working Convai scene needs these three things:

[Manager GameObject]  → ConvaiManager + ConvaiRoomManager
[NPC GameObject]      → ConvaiCharacter + ConvaiAudioOutput + AudioSource
[Player GameObject]   → ConvaiPlayer

The setup wizard creates the first and third automatically. You add the NPC components yourself.

1

Add the required manager components

In the Unity Editor menu bar, select GameObject > Convai > Setup Required Components.

Unity creates a ConvaiManager GameObject with ConvaiManager and ConvaiRoomManager attached, and a ConvaiPlayer GameObject with ConvaiPlayer attached. Both appear in the Hierarchy.

ConvaiRoomManager always lives on the same GameObject as ConvaiManager. Do not move it to a separate GameObject.

2

Add ConvaiCharacter to your NPC

In the Hierarchy, select the NPC GameObject you want to make conversational. In the Inspector, click Add Component and add ConvaiCharacter.

3

Add AudioSource and ConvaiAudioOutput

On the same NPC GameObject, add AudioSource, then add ConvaiAudioOutput.

All three components — ConvaiCharacter, ConvaiAudioOutput, and AudioSource — should now appear on the same GameObject in the Inspector.

4

Set the Character ID

In the ConvaiCharacter component, set the Character ID field to the ID of your character from the Convai dashboard.

The Character ID field is required. If it is empty, the character cannot connect to Convai and the Scene Validator will report an error.

5

Validate the scene

In the menu bar, select GameObject > Convai > Validate Scene Setup.

A dialog appears listing errors, warnings, and recommended next steps.

Errors (must fix):

Error	Fix
No ConvaiManager found	Run Setup Required Components
No ConvaiCharacter found	Add ConvaiCharacter to your NPC GameObject
ConvaiCharacter has no Character ID	Set the Character ID from your dashboard
No ConvaiPlayer found	Run Setup Required Components

Warnings:

Warning	Fix
API key not configured	Open Convai > Settings > Credentials and enter your key

When the validator reports no errors, the scene is ready for Play Mode.

6

Enter Play Mode

Press Play. The Unity Console logs:

• [ConvaiRuntime] Started successfully — SDK initialized
• [RoomConnectionRuntimeAdapter] Room connection succeeded (mode=create). — the room connected to Convai

Speak into your microphone. The character responds within a few seconds.

If you later add a Gaze, Body Animation, Body Language, or Emotion module component to the NPC, Convai adds supporting infrastructure components to the same GameObject automatically. See Scene components reference for what each one does.

Editing settings that ship with the SDK

Some optional modules point a character at a default settings asset that ships inside the Convai package. The first time you change a field on one of these assets from a character's Inspector, Convai copies the asset into your project, points the character at the copy, and applies your edit there — the packaged original is never edited in place.

The copy is created next to the character's prefab when it has one, or under Assets/Convai/<module> otherwise. You do not create this copy yourself; changing a field is enough, and the Inspector reports where the copy was written.

Usage examples

Example 1: Safety training simulation

Scenario: An industrial safety trainer NPC responds to trainee questions about equipment procedures.

Setup:

• NPC GameObject: SafetyTrainer with ConvaiCharacter, ConvaiAudioOutput, AudioSource
• Character ID: ID of your safety trainer character from the Convai dashboard
• ConvaiCharacter._characterName: "Safety Trainer"
• ConvaiCharacter._enableRemoteAudio: true

Expected outcome: Trainees speak to the NPC and receive voice responses about safety procedures. The character name appears in the transcript UI.

Example 2: Multiple characters in one scene

Scenario: A medical training simulation with two characters — a supervising doctor and a nurse.

Setup:

• Two separate NPC GameObjects, each with ConvaiCharacter, ConvaiAudioOutput, AudioSource
• Each ConvaiCharacter has its own unique Character ID
• Only one ConvaiManager and one ConvaiPlayer in the scene

Expected outcome: Both characters are discovered and registered automatically. There is no component to add and no field to fill: ConvaiManager keeps the conversation pointed at whichever character the player is addressing, and moves it there as the player's attention shifts. See Conversation targeting for the rule that decides who is being addressed and the settings that tune it.

Character A and Character B do not share conversation context unless your Convai character configuration explicitly links them.

Next steps

With the scene built, run the validator to confirm everything is wired correctly before adding features.

Validate your setup