Custom Scene Setup

Add the required Convai objects, set up a player, and connect characters to Convai.

Introduction

This guide integrates Convai into your own scene by adding the required core objects, creating a Convai player, and configuring Convai characters.

Prerequisites

  • Convai SDK installed

  • API key configured successfully

  • Your scene opened in Unity

Step-by-step

1

Add required Convai scene objects

  • In Unity top menu, go to GameObject → Convai → Setup Required Components or Right-click in the HierarchyConvai → Setup Required Components

  • Confirm and proceed in the popup.

  • Expected result: These objects exist in your scene:

    • [Convai Service Bootstrap]

    • [Convai Composition Root]

    • [Convai Room Manager]

2

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.

3

Add Convai Character components

For each character GameObject you want to make conversational:

  • Add Convai Character component

  • Set Character ID

4

Get your Character ID from Convai

5

Validate your scene setup

  • Use one of the validation options:

    • Top menu: GameObject → Convai → Validate Scene Setup

    • Hierarchy right-click: Convai → Validate Scene Setup

  • Expected result: A success message like:

    • “Scene setup is correct!” and the number of Convai Characters found.

6

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

Troubleshooting

  • Validation fails

    • Confirm the required objects exist 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.

circle-info

Need help? For questions, please visit the Convai Developer Forumarrow-up-right.

Last updated

Was this helpful?