> 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-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md).

# Character actions quick start

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

{% embed url="<https://youtu.be/lB5_KRWdg_w>" %}
Convai AI Character Actions Walkthrough
{% endembed %}

### Prerequisites

* The Convai Unreal Engine plugin is installed and the API key is configured. See [Install the Convai plugin](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) and [Configure your API key](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* 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](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md).
* Your character Blueprint is open or accessible from the **Content Browser**.

### Enable actions on the chatbot

{% stepper %}
{% step %}

#### Select the character

Select the NPC Actor in the level. In the **Details** panel, select the `Convai Chatbot` component.
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### Open the character Blueprint in the Content Browser

In the **Content Browser**, locate your character Blueprint (for example a MetaHuman or `ConvaiBaseCharacter` derivative).
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### Add the handler events

Open [Built-in action handlers](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md) 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.
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% hint style="warning" %}
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](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md) to add them, then test again.
{% endhint %}

### Register a scene object

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

{% stepper %}
{% step %}

#### 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 **Move Target Mode** on **Actor as goal** for this quick start.
{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

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

{% hint style="success" %}
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.
{% endhint %}

### 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](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md)).
* At least one object is registered in **Environment > Objects** with a valid **Ref**.

### Next steps

{% content-ref url="/pages/Q9OxeZ4EchM8ABZ4pIOW" %}
[Building custom action handlers](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md)
{% endcontent-ref %}

{% content-ref url="/pages/y5n6zO4nhEgGfJnXzGk4" %}
[Parameterized actions](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/qIWRz61DFTTZdII0U2XA" %}
[Configuring actions](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/configuring-actions.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.