Scene metadata quick start

Tag a world actor with the Convai Object Component, assign its name and description, and confirm a Convai character can reference it in conversation.

Attach a UConvaiObjectComponent to a world Actor, give it a name and description, and test whether a Convai character can use that object as scene context during conversation.

Prerequisites

• The Convai Unreal Engine plugin installed and the API key configured.
• A UConvaiChatbotComponent and a UConvaiPlayerComponent in the level, with a valid Character ID and a working microphone. See Add your first Convai character if you have not completed that setup.

Expose an actor and verify recognition

1

Select the target actor

Open your level and click the Actor you want Convai characters to know about, such as a door, crate, or lever.

2

Add the object component

In the Details panel, click Add Component and search for UConvaiObjectComponent or Convai Object. Select the component to add it to the Actor.

3

Set the object name and description

With the Convai Object Component selected, set the object identity fields in the Details panel:

• Name — a short, unique label, for example FrontDoor.
• Description — a plain sentence about the object, for example A large wooden door at the main entrance.

Names must be unique in the level. See Scene metadata component reference for details on duplicate handling and the full field list.

4

Enter Play mode and ask the character

Press Play. Walk up to the Convai character and ask: "What do you know about the door?" or "Describe the objects near you." The character should mention the name and description you set.

If the character does not reference the object, open the Output Log and filter by ConvaiSubsystemLog for registration warnings or ConvaiObjectComponentLog for component warnings. See Troubleshoot scene metadata for a full list of symptoms.

5

Add a tracked property (optional)

To give the character awareness of live game state, expand Tracked Properties in the Details panel and click + to add a row. Click Bind next to Property Path and select a UPROPERTY from the Actor. Set a plain-language Description and choose a ShouldRespond value.

For the full tracked property workflow, see Scene metadata component reference — Tracked properties.

When configured correctly, the character responds to questions about the object using the name and description you set.

For the full list of properties and functions available on the component, see Scene metadata component reference.

Next steps

Scene metadata component referenceManaging the environment at runtimeTroubleshoot scene metadata