Character actions quick start

Enable character actions, set up pawn movement and navigation, register scene objects, and verify default movement actions in Play mode.

We will prepare an existing Convai NPC to run character actions. By the end, your NPC will have the default action handlers, movement setup, NavMesh coverage, and a registered object target so you can test Move To, Follow, Stop Moving, and Wait For.

Convai AI Character Actions Walkthrough

Prerequisites

• The Convai Unreal Engine plugin is installed and the API key is configured. See Install the Convai plugin and Configure your API key.
• A level contains an NPC Actor with a Convai Chatbot component and a Convai Player component on the player pawn. See Add your first Convai character.
• Your character Blueprint is open or accessible from the Content Browser.

Enable actions on the chatbot

1

Select the character

Select the NPC Actor in the level. In the Details panel, select the Convai Chatbot component.

2

Confirm Enable Actions is on

Under Convai | Actions, expand Environment and confirm Enable Actions is ticked. It defaults to true on new Convai Chatbot components.

The Actions array is pre-populated with Move To, Follow, Stop Moving, and Wait For. Leave these entries in place for this quick start.

Set up pawn movement

Default movement actions require a pawn that can navigate. The plugin provides an editor utility that configures movement for common character setups.

1

Open the character Blueprint in the Content Browser

In the Content Browser, locate your character Blueprint (for example a MetaHuman or ConvaiBaseCharacter derivative).

2

Run Setup Convai Pawn Movement

Right-click the Blueprint asset, select Convai, then Setup Convai Pawn Movement.

The utility adjusts the Blueprint based on its parent class:

Parent class	What the utility does
Exact AActor parent	Reparents to APawn and adds Floating Pawn Movement with Convai-tuned defaults.
APawn (not Character)	Adds Floating Pawn Movement if missing and applies tuned defaults.
Character	Tunes the existing Character Movement component (max walk speed, acceleration, braking).
Custom Actor subclass that is not a pawn	Logs a warning and leaves the parent class unchanged. Reparent to APawn or Character, then run the utility again.
Non-Actor parent	Logs a warning in the Output Log. Use an Actor-based Blueprint for action movement.

If the utility reports a warning, open Window > Output Log and search for ConvaiContentBrowserContextMenu to read the message.

Add a navigation mesh

The Move To and Follow actions rely on Unreal's built-in navigation system to find a path to the destination. Without a built NavMesh, the character cannot calculate a route and will stay in place.

1

Place a Nav Mesh Bounds Volume

Open Window > Place Actors (or use the level editor quick-add menu). Search for Nav Mesh Bounds Volume and drag it into the level.

2

Scale the volume and build paths

Scale the volume so it covers every area the character should walk on. Select Build > Build Paths (or Build All).

Press P in the viewport to toggle the green navigation overlay. Confirm green coverage under the character spawn point and any planned destinations.

Add the default action handlers

The Actions array only declares what Convai can ask the NPC to do. The NPC still needs matching Blueprint events for Move To, Follow, Stop Moving, and Wait For before movement can run.

1

Add the handler events

Open Built-in action handlers and add the four default handlers to the NPC Actor Blueprint. Use Create Convai Action Handler when it is available, or create Custom Events with the exact action names.

2

Compile the Blueprint

Click Compile and Save after the handlers are added. If you are testing the pipeline for the first time, add a temporary Print String node at the start of each handler so you can confirm the event fires.

Test default movement actions

Run the level in Play mode and wait for the session to connect. Try these spoken prompts:

Prompt	Expected behavior
"Follow me"	The character tracks the player.
"Stop" or "Stop following me"	The character halts movement.

The player is registered automatically when bAutoFillConversationPartnerFromPlayer is true on the chatbot (the default), so "me" resolves to the conversation partner.

If the character speaks but does not move, the character Blueprint is missing the handler events for Move To, Follow, Stop Moving, and Wait For. See Built-in action handlers to add them, then test again.

Register a scene object

To navigate to props in the level, add them to the chatbot's environment.

1

Add an object entry

With the NPC Actor selected, expand Convai | Actions > Environment > Objects and click +.

Set:

• Name — a short, distinct label Convai can return exactly, for example "cube" or "Crate".
• Ref — the target Actor (use the picker or eyedropper).
• Description — optional plain-language hint, for example "A blue cube on the floor".

Leave Object Is on Whole Actor for this quick start.

2

Add more objects if needed

Repeat for each interactable prop. Use distinct names such as "cube" and "gun" rather than "cube" and "cube2" so Convai can choose the right target.

Test navigation and action sequences

In Play mode, try prompts that combine multiple default actions:

• "Go to the cube." — the character walks to the registered object.
• "Go to the cube, wait for a few seconds, then go to the gun, then come back to me." — the character runs a multi-step action sequence.

When the character moves to the named object and advances through a multi-action sequence, the action pipeline is working. Keep registered object names short and unambiguous so reference parameters resolve correctly.

Verify the setup

Before moving on, confirm:

• Enable Actions is ticked on the Convai Chatbot component.
• The character Blueprint has movement configured (via Setup Convai Pawn Movement or an equivalent manual setup).
• A Nav Mesh Bounds Volume covers walkable areas and paths are built.
• Default action handlers exist on the character Blueprint (or you implemented them from Built-in action handlers).
• At least one object is registered in Environment > Objects with a valid Ref.

Next steps

Building custom action handlersParameterized actionsConfiguring actions