> 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-unity-sdk/getting-started/build-a-custom-scene.md). # 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. {% stepper %} {% step %} #### 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. {% endstep %} {% step %} #### 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`. {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### Set the Character ID In the `ConvaiCharacter` component, set the **Character ID** field to the ID of your character from the [Convai dashboard](https://convai.com). {% hint style="warning" %} The Character ID field is required. If it is empty, the character cannot connect to Convai and the Scene Validator will report an error. {% endhint %} {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### 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](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/scene-components.md) for what each one does. {% endstep %} {% endstepper %} ### 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/` 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](/api-docs/plugins-and-integrations/convai-unity-sdk/features/conversation-targeting.md) 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. {% content-ref url="/pages/35a808a76b0d30cee351c5b850b110058a2eb840" %} [Validate your setup](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/validate-your-setup.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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/build-a-custom-scene.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.