Character actions scripting reference

API reference for the Convai character actions system — dispatcher types, executor interface, config classes, invocation objects, result types, and enums.

Complete API reference for all public types in the Convai character actions system. All types are in the Convai.Runtime.Actions, Convai.Runtime.Components, or Convai.Shared.Actions namespaces unless noted.

ConvaiActionDispatcher

MonoBehaviourConvai.Runtime.Actions

Menu path: Add Component → Convai → Convai Action Dispatcher

Constraints: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

Properties

Property
Type
Description

BatchPolicy

ConvaiActionBatchPolicy

Current batch policy (read-only from code; set in Inspector)

FailurePolicy

ConvaiActionBatchFailurePolicy

Current failure policy (read-only from code; set in Inspector)

OnBatchStarted

UnityEvent

Fires when a batch begins execution

OnStepStarted

ConvaiActionInvocationUnityEvent

Fires at the start of each action step

OnStepSucceeded

ConvaiActionInvocationUnityEvent

Fires when an executor returns Succeeded

OnStepFailed

ConvaiActionInvocationUnityEvent

Fires when a step fails (Failed, Canceled, or TimedOut)

OnStepUnhandled

ConvaiActionInvocationUnityEvent

Fires when an executor returns Unhandled

OnBatchCompleted

UnityEvent

Fires when all batch steps finish without the batch being aborted

OnBatchAborted

UnityEvent

Fires when StopBatch policy cuts the batch short after a failure

Methods

Method
Signature
Description

EnqueueActions

void EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions)

Submits a batch to the dispatcher. Respects the active BatchPolicy.

ConvaiActionConfigSource

MonoBehaviourConvai.Runtime.Components

Menu path: Add Component → Convai → Convai Action Config Source

Constraints: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

Properties

Property
Type
Description

Definitions

IReadOnlyList<ConvaiActionDefinition>

The authored action definitions list

Objects

IReadOnlyList<ConvaiActionObjectDefinition>

The authored actionable objects list

Characters

IReadOnlyList<ConvaiActionCharacterDefinition>

The authored actionable characters list

InitialAttentionObject

string

Object name to pre-seed as the NPC's focus at connect time

Methods

Method
Signature
Description

BuildActionConfig

ConvaiActionConfig BuildActionConfig()

Builds and returns the connect-time payload. Returns null if no valid definitions exist.

TryResolveObject

bool TryResolveObject(string objectName, out ConvaiActionObjectDefinition actionObject)

Looks up a registered object by name (case-insensitive). Returns true if found.

ConvaiCharacter — action-relevant members

MonoBehaviourConvai.Runtime.Components

Events

Event
Type
Description

OnActionsReceived

event Action<IReadOnlyList<ConvaiActionCommand>>

Fires when Convai returns an action batch for this character. Fires before the dispatcher processes it.

Properties

Property
Type
Description

ActionConfig

ConvaiActionConfig

Returns a clone of the active session's action config. May be null before connect.

Methods

Method
Signature
Description

GetActionConfigSource

ConvaiActionConfigSource GetActionConfigSource()

Returns the ConvaiActionConfigSource on this GameObject, or null.

SetCurrentAttentionObject

void SetCurrentAttentionObject(string objectName, string runLlm = "false")

Updates backend grounding to the named object. Requires an active conversation. Silently ignored if the object name is not in the active action config.

SetCurrentAttentionObject

void SetCurrentAttentionObject(ConvaiActionObjectDefinition actionObject, string runLlm = "false")

Overload that accepts a definition reference.

ClearCurrentAttentionObject

void ClearCurrentAttentionObject(string runLlm = "false")

Clears the current attention object. Requires an active conversation.

RoomSessionConnectOptions — action fields

Convai.Runtime.Room

Field
Type
Description

ActionConfigOverride

ConvaiActionConfig

When set, replaces ConvaiActionConfigSource.BuildActionConfig() for this session.

ActionDefinitionsOverride

List<ConvaiActionDefinition>

When set, replaces the Inspector action definitions for this session. Filtered against ActionConfigOverride.Actions if both are set.

ConvaiActionCommand

Convai.Shared.Types — Serializable sealed class

Structured action command for one step, as returned by the backend.

Properties

Property
Type
Description

Name

string

Required. Action name selected by the backend (e.g., "Move To").

Target

string

Optional. Object or character name the backend resolved as the target. null if no target.

HasTarget

bool

true when Target is non-empty.

Constructor

ConvaiActionConfig

Convai.Shared.Actions — Serializable sealed class

Connect-time action affordances serialized into the session connect payload.

Properties

Property
Type
Description

Actions

List<string>

Action names allowed for this session. Only names are sent — executor bindings stay local.

Objects

List<ConvaiActionObjectDefinition>

Objects the backend may reference as targets. GameObjectReference is never serialized.

Characters

List<ConvaiActionCharacterDefinition>

Characters the backend may reference as targets. GameObjectReference is never serialized.

CurrentAttentionObject

string

Initial attention object name. Must match an entry in Objects.

ConvaiActionDefinition

Convai.Runtime.Actions — Serializable sealed class

Local Unity binding between a backend action name and an executor component. Only ActionName is sent to the backend.

Fields

Field
Type
Description

ActionName

string

The action name that maps to this definition. Case-insensitive matching at runtime.

TargetRequirement

ConvaiActionTargetRequirement

What kind of target this action requires.

Executor

MonoBehaviour

The component that performs the behavior. Must implement IConvaiActionExecutor.

TimeoutSeconds

float

Maximum execution time in seconds. 0 = no timeout.

ConvaiActionObjectDefinition

Convai.Shared.Actions — Serializable sealed class

Properties

Property
Type
Serialized
Description

Name

string

Yes ("name")

Identifier used in action commands. Case-insensitive matching.

Description

string

Yes ("description")

Natural language description sent to Convai for reference resolution.

GameObjectReference

GameObject

No ([JsonIgnore])

Local scene reference. Never sent to Convai.

ConvaiActionCharacterDefinition

Convai.Shared.Actions — Serializable sealed class

Properties

Property
Type
Serialized
Description

Name

string

Yes ("name")

Identifier for this character target.

Bio

string

Yes ("bio")

Short description sent to Convai (e.g., "Site safety supervisor").

GameObjectReference

GameObject

No ([JsonIgnore])

Local scene reference. Never sent to Convai.

ConvaiActionInvocation

Convai.Runtime.Actions — Sealed class

Typed execution context passed to executors and all dispatcher events.

Properties

Property
Type
Description

Command

ConvaiActionCommand

The raw backend command for this step.

Definition

ConvaiActionDefinition

The matched local action definition. null if no definition was found (step will fail).

ResolvedTarget

ConvaiResolvedActionTarget

The resolved target binding. null if the action has no target or resolution failed.

Character

ConvaiCharacter

The NPC executing this action.

BatchIndex

int

Sequential index of the containing batch across the dispatcher's lifetime.

StepIndex

int

0-based index of this step within the current batch.

ConvaiResolvedActionTarget

Convai.Runtime.Actions — Serializable sealed class

Resolved target for one action step.

Properties

Property
Type
Description

Kind

ConvaiActionTargetKind

Whether the resolved target is an Object, Character, or None.

Name

string

The resolved name (from the backend command).

ObjectBinding

ConvaiActionObjectDefinition

The matched object definition. null if Kind != Object.

CharacterBinding

ConvaiActionCharacterDefinition

The matched character definition. null if Kind != Character.

GameObjectReference

GameObject

The scene GameObject from the matching binding. The primary access point in executors.

ConvaiActionExecutionResult

Convai.Runtime.Actions — Readonly struct

Return type for IConvaiActionExecutor.ExecuteAsync.

Properties

Property
Type
Description

Status

ConvaiActionExecutionStatus

The outcome of this execution step.

Message

string

Optional human-readable detail. Available in event handlers and logs.

Exception

Exception

The exception that caused failure, if any.

Factory methods

Method
Signature
Use when

Succeeded

static ConvaiActionExecutionResult Succeeded()

The behavior completed successfully.

Failed

static ConvaiActionExecutionResult Failed(string message = null, Exception exception = null)

A genuine error occurred.

Canceled

static ConvaiActionExecutionResult Canceled()

The CancellationToken was signaled.

TimedOut

static ConvaiActionExecutionResult TimedOut()

Do not call manually. The dispatcher returns this automatically when TimeoutSeconds expires.

Unhandled

static ConvaiActionExecutionResult Unhandled(string message = null)

This executor intentionally declines the invocation.

IConvaiActionExecutor

Convai.Runtime.Actions — Interface

The extension point for all action behavior. Implement on any MonoBehaviour.

Enumerations

ConvaiActionBatchPolicy

Convai.Runtime.Actions

Value
Integer
Description

Queue

0

New batches wait until the current batch completes. Default.

ReplaceCurrent

1

Cancels the active step and all pending batches; starts the new batch immediately.

DropIncoming

2

Discards new batches until all current and queued work is finished.

ConvaiActionBatchFailurePolicy

Convai.Runtime.Actions

Value
Integer
Description

StopBatch

0

A failed step aborts the remaining batch. OnBatchAborted fires. Default.

ContinueBatch

1

Execution continues to the next step regardless. OnBatchCompleted fires.

ConvaiActionTargetRequirement

Convai.Runtime.Actions

Value
Integer
Description

None

0

Action does not require a target.

Object

1

Action requires a resolved object target.

Character

2

Action requires a resolved character target.

Either

3

Action accepts either an object or a character as target.

ConvaiActionTargetKind

Convai.Runtime.Actions

Value
Integer
Description

None

0

No target resolved.

Object

1

Target is a registered object.

Character

2

Target is a registered character.

ConvaiActionExecutionStatus

Convai.Runtime.Actions

Value
Integer
Dispatcher event fired

Succeeded

0

OnStepSucceeded

Failed

1

OnStepFailed

Canceled

2

OnStepFailed

TimedOut

3

OnStepFailed

Unhandled

4

OnStepUnhandled

ConvaiActionInvocationUnityEvent

Convai.Runtime.Actions — Serializable class extending UnityEvent<ConvaiActionInvocation>

Wrapper type that makes ConvaiActionInvocation serializable as a UnityEvent parameter. Assign handlers in the Inspector like any standard UnityEvent. The event's single argument is the ConvaiActionInvocation for that step.

ConvaiActionDebugProbe

Convai.Runtime.Actions — Sealed MonoBehaviour

Menu path: Add Component → Convai → Debug → Convai Action Debug Probe

Constraints: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

See Troubleshoot character actions for the full Inspector field reference and usage guide.

Context menu actions

Command
Effect

Inject Test Batch

Submits a Move To command targeting the first registered object to the dispatcher. Tests the pipeline without a live conversation.

Reset Probe State

Resets all counters and text fields to zero/empty.

Next steps

Character actions examplesTroubleshoot character actions

Last updated

Was this helpful?