角色动作脚本参考

Convai 角色动作系统的 API 参考——分发器类型、执行器接口、配置类、调用对象、结果类型和枚举。

Convai 角色动作系统中所有公共类型的完整 API 参考。所有类型都位于 Convai.Runtime.Actions, Convai.Runtime.Components，或 Convai.Shared.Actions 命名空间，除非另有说明。

ConvaiActionDispatcher

MonoBehaviour — Convai.Runtime.Actions

菜单路径： 添加组件 → Convai → Convai Action Dispatcher

约束： DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

属性

属性	类型	说明
BatchPolicy	ConvaiActionBatchPolicy	当前批处理策略（代码中只读；在 Inspector 中设置）
FailurePolicy	ConvaiActionBatchFailurePolicy	当前失败策略（代码中只读；在 Inspector 中设置）
OnBatchStarted	UnityEvent	当一个批次开始执行时触发
OnStepStarted	ConvaiActionInvocationUnityEvent	在每个动作步骤开始时触发
OnStepSucceeded	ConvaiActionInvocationUnityEvent	当执行器返回时触发 成功
OnStepFailed	ConvaiActionInvocationUnityEvent	当步骤失败时触发（Failed、Canceled 或 TimedOut）
OnStepUnhandled	ConvaiActionInvocationUnityEvent	当执行器返回时触发 未处理
OnBatchCompleted	UnityEvent	当所有批处理步骤完成且批次未被中止时触发
OnBatchAborted	UnityEvent	当 StopBatch 策略在失败后提前终止批次时

方法

方法	签名	说明
EnqueueActions	void EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions)	向调度器提交一个批次。遵循当前活动的 BatchPolicy.

ConvaiActionConfigSource

MonoBehaviour — Convai.Runtime.Components

菜单路径： 添加组件 → Convai → Convai Action Config Source

约束： DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

属性

属性	类型	说明
Definitions	IReadOnlyList<ConvaiActionDefinition>	已编写的动作定义列表
Objects	IReadOnlyList<ConvaiActionObjectDefinition>	已编写的可动作对象列表
Characters	IReadOnlyList<ConvaiActionCharacterDefinition>	已编写的可动作角色列表
InitialAttentionObject	string	在连接时预先设为 NPC 焦点的对象名称

方法

方法	签名	说明
BuildActionConfig	ConvaiActionConfig BuildActionConfig()	构建并返回连接时的负载。如果没有有效定义，则返回 null 。
TryResolveObject	bool TryResolveObject(string objectName, out ConvaiActionObjectDefinition actionObject)	按名称查找已注册对象（不区分大小写）。如果找到则返回 true 。

ConvaiCharacter — 与动作相关的成员

MonoBehaviour — Convai.Runtime.Components

事件

事件	类型	说明
OnActionsReceived	event Action<IReadOnlyList<ConvaiActionCommand>>	当 Convai 为此角色返回一个动作批次时触发。在调度器处理之前触发。

属性

属性	类型	说明
ActionConfig	ConvaiActionConfig	返回当前会话动作配置的克隆。可能在 null 连接之前。

方法

方法	签名	说明
GetActionConfigSource	ConvaiActionConfigSource GetActionConfigSource()	返回 ConvaiActionConfigSource 在此 GameObject，或 null.
SetCurrentAttentionObject	void SetCurrentAttentionObject(string objectName, string runLlm = "false")	将后端的锚定更新为指定对象。需要处于活动对话中。如果对象名称不在当前活动动作配置中，则会被静默忽略。
SetCurrentAttentionObject	void SetCurrentAttentionObject(ConvaiActionObjectDefinition actionObject, string runLlm = "false")	接受定义引用的重载。
ClearCurrentAttentionObject	void ClearCurrentAttentionObject(string runLlm = "false")	清除当前注意对象。需要处于活动对话中。

RoomSessionConnectOptions — 动作字段

Convai.Runtime.Room

字段	类型	说明
ActionConfigOverride	ConvaiActionConfig	设置后，将替换 ConvaiActionConfigSource.BuildActionConfig() 在此会话中的结果。
ActionDefinitionsOverride	List<ConvaiActionDefinition>	设置后，将替换此会话的 Inspector 动作定义。如果两者都设置，则会按 ActionConfigOverride.Actions 进行过滤。

ConvaiActionCommand

Convai.Shared.Types — 可序列化的密封类

由后端返回的单步结构化动作命令。

属性

属性	类型	说明
名称	string	必需。由后端选择的动作名称（例如， "Move To").
目标	string	可选。后端解析为目标的对象或角色名称。 null 如果没有目标。
HasTarget	bool	true 当 目标 非空时。

构造函数

new ConvaiActionCommand("Move To", "Crate")  // 名称 + 目标
new ConvaiActionCommand("Wave")              // 仅名称

ConvaiActionConfig

Convai.Shared.Actions — 可序列化的密封类

在连接时将动作能力序列化到会话连接负载中。

属性

属性	类型	说明
动作	List<string>	此会话允许的动作名称。仅发送名称——执行器绑定保持在本地。
Objects	List<ConvaiActionObjectDefinition>	后端可引用为目标的对象。 GameObjectReference 绝不会被序列化。
Characters	List<ConvaiActionCharacterDefinition>	后端可引用为目标的角色。 GameObjectReference 绝不会被序列化。
CurrentAttentionObject	string	初始注意对象名称。必须匹配 Objects.

ConvaiActionDefinition

Convai.Runtime.Actions — 可序列化的密封类

后端动作名称与执行器组件之间的本地 Unity 绑定。只有 动作名称 会发送到后端。

字段

字段	类型	说明
动作名称	string	映射到此定义的动作名称。运行时不区分大小写匹配。
目标要求	ConvaiActionTargetRequirement	此动作需要哪种目标。
执行器	MonoBehaviour	执行该行为的组件。必须实现 IConvaiActionExecutor.
TimeoutSeconds	float	最大执行时间（秒）。 0 = 无超时。

ConvaiActionObjectDefinition

Convai.Shared.Actions — 可序列化的密封类

属性

属性	类型	已序列化	说明
名称	string	是（"name")	在动作命令中使用的标识符。匹配时不区分大小写。
说明	string	是（"description")	发送给 Convai 用于引用解析的自然语言描述。
GameObjectReference	GameObject	没有 ([JsonIgnore])	本地场景引用。绝不发送给 Convai。

ConvaiActionCharacterDefinition

Convai.Shared.Actions — 可序列化的密封类

属性

属性	类型	已序列化	说明
名称	string	是（"name")	此角色目标的标识符。
Bio	string	是（"bio")	发送给 Convai 的简短描述（例如，“场地安全主管”）。
GameObjectReference	GameObject	没有 ([JsonIgnore])	本地场景引用。绝不发送给 Convai。

ConvaiActionInvocation

Convai.Runtime.Actions — 密封类

传递给执行器和所有调度器事件的类型化执行上下文。

属性

属性	类型	说明
命令	ConvaiActionCommand	此步骤的原始后端命令。
Definition	ConvaiActionDefinition	匹配到的本地动作定义。 null 如果未找到定义（步骤将失败）。
ResolvedTarget	ConvaiResolvedActionTarget	已解析的目标绑定。 null 如果动作没有目标或解析失败。
角色	ConvaiCharacter	执行此动作的 NPC。
BatchIndex	int	在调度器生命周期内，该包含批次的顺序索引。
StepIndex	int	当前批次中此步骤的从 0 开始的索引。

ConvaiResolvedActionTarget

Convai.Runtime.Actions — 可序列化的密封类

单个动作步骤的解析目标。

属性

属性	类型	说明
种类	ConvaiActionTargetKind	解析后的目标是 Object、Character 还是 None。
名称	string	解析出的名称（来自后端命令）。
ObjectBinding	ConvaiActionObjectDefinition	匹配到的对象定义。 null 如果 Kind != Object.
CharacterBinding	ConvaiActionCharacterDefinition	匹配到的角色定义。 null 如果 Kind != Character.
GameObjectReference	GameObject	场景 GameObject 来自匹配绑定。在执行器中是主要访问点。

ConvaiActionExecutionResult

Convai.Runtime.Actions — 只读结构体

返回类型，适用于 IConvaiActionExecutor.ExecuteAsync.

属性

属性	类型	说明
Status	ConvaiActionExecutionStatus	此执行步骤的结果。
消息	string	可选的人类可读详情。在事件处理程序和日志中可用。
Exception	Exception	导致失败的异常（如果有）。

工厂方法

方法	签名	何时使用
成功	static ConvaiActionExecutionResult Succeeded()	行为已成功完成。
失败	static ConvaiActionExecutionResult Failed(string message = null, Exception exception = null)	发生了真实错误。
Canceled	static ConvaiActionExecutionResult Canceled()	该 CancellationToken 已发出信号。
超时	static ConvaiActionExecutionResult TimedOut()	不要手动调用。 当 TimeoutSeconds 超时。
未处理	static ConvaiActionExecutionResult Unhandled(string message = null)	此执行器有意拒绝该调用。

IConvaiActionExecutor

Convai.Runtime.Actions — 接口

所有动作行为的扩展点。实现于任何 MonoBehaviour.

public interface IConvaiActionExecutor
{
    Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}

枚举

ConvaiActionBatchPolicy

Convai.Runtime.Actions

值	整数	说明
Queue	0	新的批次会等待当前批次完成。默认。
ReplaceCurrent	1	取消当前活动步骤和所有待处理批次；立即开始新批次。
DropIncoming	2	丢弃新批次，直到所有当前和排队中的工作完成。

ConvaiActionBatchFailurePolicy

Convai.Runtime.Actions

值	整数	说明
StopBatch	0	失败的步骤会中止剩余批次。 OnBatchAborted 触发。默认。
ContinueBatch	1	无论如何，执行都会继续到下一步。 OnBatchCompleted 会触发。

ConvaiActionTargetRequirement

Convai.Runtime.Actions

值	整数	说明
无	0	动作不需要目标。
对象	1	动作需要解析出的对象目标。
角色	2	动作需要解析出的角色目标。
任一	3	动作接受对象或角色作为目标。

ConvaiActionTargetKind

Convai.Runtime.Actions

值	整数	说明
无	0	未解析到目标。
对象	1	目标是已注册对象。
角色	2	目标是已注册角色。

ConvaiActionExecutionStatus

Convai.Runtime.Actions

值	整数	调度器事件已触发
成功	0	OnStepSucceeded
失败	1	OnStepFailed
Canceled	2	OnStepFailed
超时	3	OnStepFailed
未处理	4	OnStepUnhandled

ConvaiActionInvocationUnityEvent

Convai.Runtime.Actions — 扩展自的可序列化类 UnityEvent<ConvaiActionInvocation>

包装类型，使 ConvaiActionInvocation 可作为 UnityEvent 参数进行序列化。像任何标准 UnityEvent 一样在 Inspector 中分配处理程序。事件的单个参数是 ConvaiActionInvocation 用于该步骤的。

ConvaiActionDebugProbe

Convai.Runtime.Actions — 密封 MonoBehaviour

菜单路径： 添加组件 → Convai → Debug → Convai Action Debug Probe

约束： DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

请参见 排查角色动作问题 完整的 Inspector 字段参考和使用指南。

上下文菜单操作

命令	效果
注入测试批次	提交一个 Move To 将命令（以第一个已注册对象为目标）发送到调度器。在没有实时对话的情况下测试管线。
重置探针状态	将所有计数器和文本字段重置为零/空。

下一步

角色动作示例排查角色动作问题