# Custom Scene Setup

## Introduction

This guide shows how to integrate Convai into your own Unity scene by adding the **Convai Manager**, creating a Convai Player, and configuring Convai Characters.

## Prerequisites

* Convai SDK installed
* API key configured successfully
* Your scene opened in Unity

## Step-by-step

{% stepper %}
{% step %}

#### Add the Convai Manager

* In Unity top menu, go to **GameObject → Convai → Setup Required Components**\
  **or** Right-click in the **Hierarchy** → **Convai → Setup Required Components**

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fqc7zruDxmrgIjizuNXvK%2Fimage.png?alt=media&#x26;token=5477569e-6dd9-4da1-9d7e-1ed7dd3b8751" alt=""><figcaption></figcaption></figure>

* Confirm and proceed in the popup.
* **Expected result:** A single **Convai Manager** object exists in your scene.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FpeSzFWAQDmHE3Q4NtbOy%2Fimage.png?alt=media&#x26;token=098e95f0-0df6-49b3-8cc3-46fe42452fef" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Create or select your Player object

* Select your existing player GameObject, or create an empty one.
* Add **Convai Player Component**.
* Set **Player Name**.
* **Expected result:** The scene has exactly one configured Convai Player.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FafMJNWpbidgM3PBvu5WB%2Fimage.png?alt=media&#x26;token=a2c2a2fb-926d-4fce-b4bb-6fd674715404" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Add Convai Character components

For each character GameObject you want to make conversational:

* Add **Convai Character** component
* Set **Character ID**

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FcMwXgVxIKNpuZH79aNw5%2Fimage.png?alt=media&#x26;token=7c4e937f-5d68-4d83-bc7f-9942a5e94d28" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Get your Character ID from Convai

* [In Convai dashboard](https://docs.convai.com/api-docs/convai-playground/character-customization/character-description#id-1.-character-name-and-id), open your character and copy its ID.
  {% endstep %}

{% step %}

### Validate your scene setup

* Use one of the validation options:
  * Top menu: **GameObject → Convai → Validate Scene Setup**
  * Hierarchy right-click: **Convai → Validate Scene Setup**

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FCRgB8mLnLfpnKk63O3CS%2Fimage.png?alt=media&#x26;token=a68a2bde-f934-4e3e-94ac-3a8b3a55233e" alt=""><figcaption></figcaption></figure>

* **Expected result:** A success message like:
  * “Scene setup is correct!” and the number of Convai Characters found.

<figure><img src="https://413558230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FP5ydynLmltresUoHW7F9%2Fimage.png?alt=media&#x26;token=3d1f040a-acd3-437b-8e5f-7b557321e4bf" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Run a conversation test

* Press **Play**
* Speak using microphone or use Chat UI if present
* **Expected result:** Characters respond. Microphone conversation is **hands-free** (no push-to-talk required).
  {% endstep %}
  {% endstepper %}

## Troubleshooting

* **Validation fails**
  * Confirm that a **Convai Manager** object exists in the scene.
  * Ensure you added **Convai Player Component** to a player object.
  * Ensure each character has a valid **Character ID**.
* **Characters don’t respond**
  * Confirm API key is set.
  * Check Console for network/auth errors.

## Conclusion

You’ve integrated Convai into your custom scene, validated the setup, and confirmed characters can respond. Next, optionally add **Chat UI** to support text input and transcripts.

{% hint style="info" %}
**Need help?** For questions, please visit the [**Convai Developer Forum**](https://forum.convai.com/).
{% endhint %}