> 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/built-in-action-handlers.md). # Built-in action handlers Every new `Convai Chatbot` component includes four pre-configured action templates: `Move To`, `Follow`, `Stop Moving`, and `Wait For`. These templates define the action *names* and *parameters* — you still need to implement the corresponding Blueprint events in your NPC character Blueprint. This page provides a copy-ready handler pattern for each action. ### Choosing the right handler | Action | Parameters | Purpose | Completion model | | ------------- | -------------------------- | --------------------------------------------------- | -------------------------------------- | | `Move To` | `destination` (Reference) | Navigate to a registered object or character target | Completes when movement ends | | `Follow` | `character` (Reference) | Start continuously following a registered character | Completes after the follow loop starts | | `Stop Moving` | — | Cancel any in-progress movement | Completes immediately | | `Wait For` | `time in seconds` (Number) | Pause the action queue for a duration | Completes after the delay | {% hint style="info" %} The movement handler patterns use `AI Move To` and require an AI Controller and Nav Mesh Bounds Volume. `Wait For` does not require navigation. If your NPC does not use Unreal's navigation system, replace the movement logic with your own approach and keep the same `HandleActionCompletion` pattern. {% endhint %} ### Move To Navigates the NPC to a registered object. The `destination` parameter is a `Reference` type that resolves against the registered object name. **Parameter:** | Name | Type | Description | | ------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `destination` | Reference (`FConvaiObjectEntry`) | The object the NPC should walk to. Resolved against the registered `Objects` and `Characters` lists (`Objects` searched first). | **Blueprint handler:** Use **Create Convai Action Handler** (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below. ``` // Blueprint pseudocode // Custom Event named "Move To" with one FConvaiResultAction input Event Move To(ActionData: FConvaiResultAction) // Read and resolve the destination DestEntry = GetParamAsRef(ActionData, "destination") ResolveGoalLocation( Entry = DestEntry, SourceActor = Self, // outputs: OutGoalActor, OutGoalComponent, OutGoalLocation, OutAcceptanceRadius, OutMode, bSuccess, bAlreadyThere, bReachable, PathEnd, PathPoints ) // Guard: destination Actor must be alive if not bSuccess: AbortActionSequence( EventText = "Navigation target no longer exists", ShouldRespond = Always ) return // Skip movement if already at the goal if bAlreadyThere: HandleActionCompletion(IsSuccessful = true) return // Branch on the resolved mode and issue AI Move To with the correct pin if OutMode == Actor: AIMoveTo(Target = OutGoalActor, AcceptanceRadius = OutAcceptanceRadius) else: AIMoveTo(Destination = OutGoalLocation, AcceptanceRadius = OutAcceptanceRadius) // Wait for OnMoveCompleted (bind to AIController.ReceiveMoveCompleted or use // a task/latent action), then call: HandleActionCompletion(IsSuccessful = true) ``` **Key points:** * Always branch on `Out Mode` before wiring `AI Move To` — `Actor` mode uses the actor pin, `Vector` mode uses the location pin. Wiring the wrong pin makes the movement use the wrong goal interpretation. * `ResolveGoalLocation` with a live `Source Actor` also computes `bOut Reachable` and `Out Path Points`, which you can use to bail out early if no navmesh path exists. * `AcceptanceRadius` comes from the registered `FConvaiObjectEntry` (default `150` cm). Increase it for large objects or decrease it for precise sub-component targeting. ### Follow Starts a continuous follow behavior for a registered character. The follow timer or task can keep running after the action completes; call `HandleActionCompletion(true)` after the follow loop starts so future actions can dispatch. **Parameter:** | Name | Type | Description | | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `character` | Reference (`FConvaiObjectEntry`) | The character to follow. Resolved against the registered `Objects` and `Characters` lists (`Objects` searched first). | **Blueprint handler:** Use **Create Convai Action Handler** (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below. ``` // Blueprint pseudocode // Custom Event named "Follow" with one FConvaiResultAction input Event Follow(ActionData: FConvaiResultAction) TargetEntry = GetParamAsRef(ActionData, "character") if TargetEntry.Ref is None: AbortActionSequence( EventText = "Follow target not found", ShouldRespond = Always ) return // Start a repeating timer (e.g., every 0.5s) that calls // AIMoveTo(Target = TargetEntry.Ref, AcceptanceRadius = 150.0) // Store the timer handle so Stop Moving can cancel it. // Complete the Follow action after the loop starts. // The timer/task keeps running until Stop Moving fires later. HandleActionCompletion(IsSuccessful = true) ``` **Implementation note — polling timer:** A common approach is a `Set Timer by Function Name` node that re-issues `AI Move To` toward the target Actor every 0.5–1.0 seconds. Store the timer handle in a Blueprint variable, then call `HandleActionCompletion(true)` after the timer starts. When `Stop Moving` fires later, clear the timer and complete the stop action. Alternatively, implement a `BehaviorTree` task that loops until an external signal is set, and signal it from the `Stop Moving` handler. ### Stop Moving Cancels any in-progress movement behavior and completes the current action. If `Follow` started a timer or task, `Stop Moving` should clear that timer or task and then call `HandleActionCompletion(true)` for the stop action. **Parameters:** none **Blueprint handler:** Use **Create Convai Action Handler** (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below. ``` // Blueprint pseudocode // Custom Event named "Stop Moving" with one FConvaiResultAction input Event Stop Moving(ActionData: FConvaiResultAction) // Cancel the repeating follow timer ClearTimer(FollowTimerHandle) // Stop current movement immediately AIController.StopMovement() // Complete the Stop Moving action HandleActionCompletion(IsSuccessful = true) ``` {% hint style="warning" %} The Blueprint Custom Event name must be `Stop Moving` (with a space) to match the default action name exactly. `StopMoving` (no space) will not dispatch. {% endhint %} *** ### Wait For Pauses the action queue for a configurable number of seconds. After the delay, `HandleActionCompletion` advances the queue to the next action. **Parameter:** | Name | Type | Description | | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `time in seconds` | Number (`float`) | The number of seconds to pause. Convai fills this value; guide it with a clear parameter description such as `"A plain number of seconds, e.g. 3"`. | **Blueprint handler:** Use **Create Convai Action Handler** (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below. ``` // Blueprint pseudocode // Custom Event named "Wait For" with one FConvaiResultAction input Event Wait For(ActionData: FConvaiResultAction) Seconds = GetParamAsNumber(ActionData, "time in seconds") // Guard: clamp to a sensible range Seconds = Clamp(Seconds, 0.1, 30.0) // Use Unreal's built-in Delay node (latent action) Delay(Duration = Seconds) // After the delay completes: HandleActionCompletion(IsSuccessful = true) ``` **Implementation note — Delay node:** The built-in **Delay** Blueprint node is a latent action and works correctly here. If your handler logic is inside a function rather than a Custom Event, use a `Set Timer by Event` node instead (latent actions only work in event graphs, not in Blueprint functions). *** ### Modifying the default actions You can rename, remove, or extend any default action in the `Actions` array: * **Rename** — change `Name` in the Details panel and rename the Blueprint Custom Event to match. * **Remove** — select the entry in the `Actions` array and click the delete button. The Blueprint event becomes dead code but does not cause an error. * **Add a parameter** — add an `FConvaiActionParam` entry to the `Parameters` array on the template. Update your handler to read the new parameter with `GetParamAs*`. If you rename any of these action templates, rename the corresponding Blueprint Custom Event to match, including spaces. Unreal resolves handler names case-insensitively, but `"Stop Moving"` and `"StopMoving"` are different names. *** ### 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/KjK5RrpmmborH095i0oC" %} [Character actions examples](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/character-actions-examples.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/built-in-action-handlers.md?ask=&goal= ``` `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.