For the complete documentation index, see llms.txt. This page is also available as Markdown.

角色动作脚本参考

Convai 角色动作系统的 API 参考——执行器基类、调度器、配置类型、调用对象和枚举。

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

IConvaiActionExecutor

Convai.Runtime.Actions — 接口

所有动作行为的扩展点。在任何 MonoBehaviour上实现,或派生自 ConvaiActionExecutorBase 来替代——请参见 编写自定义动作执行器.

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

返回 ConvaiActionExecutionResult.Unhandled 当组件无法处理调用时(例如缺少绑定组件或对等组件)使用,以便调度器能够将其单独报告。请遵循 cancellationToken 以支持批次替换和超时。

执行器基类

Convai.Runtime.Actions — 抽象 MonoBehaviour 类

每个发布的执行器都派生自其中之一,而不是直接实现 IConvaiActionExecutor 。派生可让组件自动获得 Convai 检查器——分区字段、工具提示和动作绑定状态块——无需编辑器代码。

类
派生自
添加

ConvaiActionExecutorBase

MonoBehaviour, IConvaiActionExecutor

CharacterTransform, ResolvePlayer(), DeclaredButNotSent(...)

ConvaiTargetedActionExecutor

ConvaiActionExecutorBase

目标验证、对等组件解析/缓存、缺失对等组件诊断、参数覆盖帮助程序

ConvaiCharacterActionExecutor<TPeer>

ConvaiTargetedActionExecutor

解析一个特定的角色端组件(TPeer),并将其交给 ExecuteCoreAsync

ConvaiActionExecutor<TParameters>

ConvaiActionExecutorBase

在执行前,按名称将调用参数绑定到一个强类型的 TParameters 对象

ConvaiActionExecutorBase

成员
类型
说明

CharacterTransform

Transform (受保护)

Convai 角色的 Transform:首次使用时通过向上搜索解析并缓存。若其上方未找到角色,则回退到此组件自身的 Transform(不缓存)

ResolvePlayer()

protected virtual Transform

玩家实际所在的位置;请参阅 ConvaiPlayerBody 如下。可为分屏、多套绑定组件或过场动画摄像机重写

DeclaredButNotSent(invocation, parameterName)

protected static bool

动作是否声明了 parameterName 且 Convai 角色未为其发送任何值——这可区分“对此未提供任何信息”与恰好为空的值

ConvaiTargetedActionExecutor

ExecuteAsync 是密封的:当 RequiresTarget 是 true (默认值)且调用没有已解析的目标 GameObject时,它默认返回 MissingTargetResult(invocation) — 未处理 ——而不调用 ExecuteCoreAsync。将 RequiresTarget => false 用于无目标动作(例如脚本化的点头动作)。

成员
类型
说明

MissingTargetResult(invocation)

protected virtual ConvaiActionExecutionResult

缺少必需目标时返回的结果。重写以返回 Failed(..., ConvaiActionFailureReason.TargetMissing) 而非默认值 未处理

ResolveTargetGameObject(invocation)

protected static GameObject

已解析的目标 GameObject,或 null

ResolveTargetInteractionPoint(invocation)

protected static Transform

已解析目标的 InteractionPoint,回退到其 GameObjectReference的 Transform

TryResolvePeer<T>(ref T authored, out T peer)

protected bool

解析必需的对等组件:显式的 authored 字段始终优先;否则查找 GetComponentInParent<T>() 然后 GetComponentInChildren<T>() 并在组件的生命周期内记住结果

UnhandledMissingPeer<T>()

protected ConvaiActionExecutionResult

构建一个 未处理 类型的缺失对等组件结果 T,每个组件实例仅记录一次日志

GetOverride(invocation, name, defaultValue)

protected static float/bool/string

读取调用参数覆盖值;若不存在或 invocation 是 null

ConvaiCharacterActionExecutor<TPeer>

解析 TPeer 一次,通过 TryResolvePeer 并将其直接交给 ExecuteCoreAsync;缺失组件会返回 未处理 ,通过 UnhandledMissingPeer<TPeer>() ,然后才运行你的方法。这是需要恰好一个角色端控制器的执行器所共用的基类——例如 ConvaiScanEnvironmentActionExecutor (需要一个 ConvaiGazeController)和 ConvaiLeadPlayerActionExecutor (需要一个 ConvaiNavMeshLocomotion).

ConvaiActionExecutor<TParameters>

绑定以下对象的公共字段和属性: TParameters 按参数名称(支持的成员类型: string, float, double, int, bool, ConvaiResolvedActionTarget, ConvaiActionParameterValue)。使用 [ConvaiActionParameter("name")] 当 DTO 成员名称与创作的参数名称不同时。

ConvaiPlayerBody

Convai.Runtime.Actions — public static class

对于不是执行器的场景代码,玩家实际所在的位置。 ConvaiActionExecutorBase.ResolvePlayer() (protected virtual, ConvaiActionExecutorBase.cs:113)是执行器端对此的简写。

方法
签名
说明

Resolve

static Transform Resolve()

用于衡量玩家位置的 Transform:优先使用场景中的 ConvaiPlayer,并解析为其绑定组件实际移动的 Transform(其中的 CharacterController 或 Rigidbody ,而不是预制体根节点);如果两者均不存在,则回退到 Camera.main; null 如果两者都不存在

TryResolveFloorPosition

static bool TryResolveFloorPosition(float floorHeight, out Vector3 position)

玩家站立的位置,平铺到 floorHeight。返回 false 当没有人可供测量时

ConvaiActionExecutionResult

Convai.Runtime.Actions — 只读结构

以下项的返回类型: IConvaiActionExecutor.ExecuteAsync.

属性

属性
类型
说明

状态

ConvaiActionExecutionStatus

此执行步骤的结果

Message

string

可选诊断详情。会传至控制台、动作编辑器和你自己的游戏代码——绝不会传给 Convai 角色

答案

string

此动作发现的内容,以角色可以大声说出的一句普通话写成。对于执行可见动作而非回答问题的动作为空

HasAnswer

bool

此结果是否包含非空的 答案

异常

异常

执行器抛出异常时捕获的异常

FailureReason

ConvaiActionFailureReason

机器可读的失败原因; 无 用于非失败情况

工厂方法

方法
签名
适用于

成功

static ConvaiActionExecutionResult Succeeded(string message = null)

行为已成功完成,且没有玩家需要听到的内容

Answered

static ConvaiActionExecutionResult Answered(string answer, string message = null)

行为发现了玩家所询问的内容——读取仪表、清点群体数量、测量距离。 message 默认为 answer

Failed

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

发生未分类错误。映射到 ConvaiActionFailureReason.Custom 当 message 非空,否则 无

Failed

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

发生了具有已知结构化原因的错误。在新代码中优先使用,而非未分类重载

已取消

static ConvaiActionExecutionResult Canceled()

该 CancellationToken 因超时以外的原因被发出信号。 FailureReason 是 被打断

超时

static ConvaiActionExecutionResult TimedOut(string message = null)

请勿手动调用。 当 TimeoutSeconds 到期时,调度器会自动返回此结果。 FailureReason 是 超时

未处理

static ConvaiActionExecutionResult Unhandled(string message = null)

此执行器有意拒绝该调用。 FailureReason 是 无

Answered(...) 是区分查询动作与其他所有类型的依据:它是唯一会填充 答案,以及 答案 的工厂方法。它是 Convai 角色唯一会被告知的结果部分。是否说出、静默记住,还是由角色自行判断,取决于动作的 ConvaiActionAnswerDelivery 设置,而非执行器。请参阅 回答问题而非执行动作 以了解完整模式。

ConvaiActionFailureReason

Convai.Runtime.Actions

步骤失败时的机器可读原因,以及自由文本 Message.

值
说明

无

无失败,或原因未分类(以下项的默认值: 成功/未处理)

TargetMissing

调用需要一个已解析目标,但不存在该目标

TargetUnreachable

目标已解析,但无法到达

PathBlocked

在概念上存在通往目标的路径,但该路径被阻塞(例如没有有效的 NavMesh 路径)

PeerMissing

未在角色上找到必需的对等组件(控制器、移动组件、绑定组件)

InvalidState

执行器或依赖项处于无法处理请求的状态

超时

该步骤超过了其定义的超时时间

被打断

该步骤在完成前被中断(取消、替换或取代)

Custom

仅通过以下项传达的任何其他执行器特定失败: Message

TargetNotActionable

目标已解析,但缺少此动作对其执行操作所需的组件(请参阅 RequiredTargetComponent 在 ConvaiActionArchetypeAttribute)

Busy

角色当前无法接受请求,因为它正在执行占用相同部分的任务;稍后再次提出相同请求通常会成功

ConvaiActionDefinition

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

将后端动作名称绑定到本地执行器、其强类型参数及其调度行为的创作定义。仅渲染后的线缆模板(来自 ToActionConfigString)会发送给 Convai。

字段和属性

成员
类型
说明

ActionName

string

与后端命令匹配的动作名称(不区分大小写)

说明

string

发送给 Convai 以提供上下文的可选描述

参数

List<ConvaiActionParameterDefinition>

渲染到线缆模板中的有序强类型参数

TargetRequirement

ConvaiActionTargetRequirement

此动作所需的目标类型

执行器

MonoBehaviour

执行行为的组件。必须实现 IConvaiActionExecutor。此处的显式引用始终优先于 ExecutorTypeHint

ExecutorTypeHint

string

以下项的可选短类型名称或完整类型名称: IConvaiActionExecutor 当以下条件满足时,在角色层级结构上自动绑定 执行器 是 null — 由在以下项内创作的定义使用: ConvaiActionSet 资源,无法保存场景引用

TimeoutSeconds

float

最长执行时间(秒)。 0 或更小的值会禁用超时

FailurePolicyOverride

ConvaiActionFailurePolicyOverride

对调度器批次失败策略的每动作覆盖

AnswerDelivery

ConvaiActionAnswerDelivery

角色如何处理一个 Answered(...) 结果。仅用于创作——绝不会发送给 Convai

WaitForBotSpeech

bool

新批次的第一步是否等待角色语音

DelayAfterBotSpeechSeconds

float

语音门控解除后的可选延迟

类别

string (属性)

在动作编辑器中为动作归档所用的可选创作标签。仅用于组织——不会发送给 Convai

已启用

bool (属性)

创作时的可用性。已禁用的动作不包含在 action_config 发送给 Convai 的内容中。默认值为 true

方法

方法
签名
说明

ToActionConfigString

string ToActionConfigString()

渲染为此定义发送给 Convai 的线缆模板字符串

ConvaiActionAnswerDelivery

Convai.Runtime.Actions

Convai 角色如何处理动作返回的 答案 。在动作编辑器中按动作创作,名称为 完成时.

值
整数
说明

UseCharacterSetting

0

遵从角色的 ConvaiActionFeedbackRelay。默认值

RememberOnly

1

角色保留答案而不大声说出。它仍会传入角色的记忆

MentionIfRelevant

2

角色自行决定该答案是否值得提及

TellThePlayer

3

角色会说出动作发现的内容。用于回答直接问题的动作

ConvaiActionParameterDefinition

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

单个强类型动作参数的创作定义,由以下项引用: ConvaiActionDefinition.Parameters.

字段
类型
说明

名称

string

用作线缆键和模板锚点的参数名称

说明

string

发送给 Convai 以提供上下文的可选描述

类型

ConvaiActionParameterType

声明的参数类型。 自动 会从值中推断。默认值 自动

连接词

string

在线缆模板中参数之前渲染的可选连接词(例如 “在……上” 或 “在……中”)

选项

List<string>

当以下项为 类型 是 Choice

ConvaiActionInvocation

Convai.Runtime.Actions — 密封类

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

属性

属性
类型
说明

命令

ConvaiActionCommand

此步骤的原始后端命令

Definition

ConvaiActionDefinition

匹配到的本地动作定义。 null 如果未找到定义(步骤将失败)

ResolvedTarget

ConvaiResolvedActionTarget

已解析的目标绑定。 null 如果动作没有目标或解析失败

Character

ConvaiCharacter

执行此动作的 NPC

BatchIndex

int

调度器生命周期内,所属批次的顺序索引

StepIndex

int

此步骤在当前批次中的从零开始索引

方法

方法
签名
说明

TryGetParameter

bool TryGetParameter(string name, out ConvaiActionParameterValue value)

尝试按名称读取强类型参数(不区分大小写)

GetString

string GetString(string name, string fallback = "")

读取字符串参数,返回 fallback 当不存在时

GetNumber

float GetNumber(string name, float fallback = 0f)

读取数值参数,返回 fallback 当不存在时

GetBool

bool GetBool(string name, bool fallback = false)

读取布尔参数,返回 fallback 当不存在时

GetReference

ConvaiResolvedActionTarget GetReference(string name)

根据角色的动作配置解析引用参数;当参数没有显式类型时,回退到定义中的目标要求

ConvaiResolvedActionTarget

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

单个动作步骤的解析后目标,由中描述的解析层级产生 动作目标解析的工作方式.

属性
类型
说明

Kind

ConvaiActionTargetKind

解析后的目标是 Object、Character 还是 None

名称

string

解析后的名称(来自后端命令)

ObjectBinding

ConvaiActionObjectDefinition

匹配到的对象定义。 null 如果 Kind != Object

CharacterBinding

ConvaiActionCharacterDefinition

匹配到的角色定义。 null 如果 Kind != Character

GameObjectReference

GameObject

场景 GameObject 来自匹配的绑定

InteractionPoint

Transform

绑定显式交互点(如果已设置),否则为 GameObjectReference的 transform,否则为 null。每个已发布的定向执行器都会移动到这里或朝向这里,而不是原始的 GameObjectReference transform

ConvaiActionCommand

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

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

属性

属性
类型
说明

名称

string

必需。后端选择的动作名称(例如, "Move To")

目标

string

可选。后端解析为目标的对象或角色名称。 null 如果没有目标

ActionString

string

从后端重建的原始动作字符串 名称 和 目标

参数

Dictionary<string, ConvaiActionParameterValue>

从后端响应和当前 Unity 模板解析出的强类型参数。键不区分大小写

WaitForBotSpeech

bool

新批次中的第一个动作是否应在运行前等待角色说话结束

DelayAfterBotSpeechSeconds

float

在语音门控释放后应用的可选延迟

已增强

bool

true 一旦命令针对当前动作模板完成增强后。调度器会在分发前仅增强一次未标记命令

HasTarget

bool

true 当 目标 非空

构造函数

构造函数会规范化 名称 和 目标 并从中推导出 ActionString 。 参数, WaitForBotSpeech, DelayAfterBotSpeechSeconds,以及 已增强 默认值为其空值,并由后端响应或增强过程填充。

ConvaiActionParameterValue

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

增强后的一个强类型动作参数。每种表示都会尽力从原始文本中填充; 类型 指示作者模板意图使用哪一种。

属性
类型
说明

类型

ConvaiActionParameterType

类型转换后的有效类型。一个作者定义的 自动 解析为一个具体类型

RawValue

string

解析此值所依据的修剪后原始文本

StringValue

string

作为文本的值(与 RawValue 相同,已修剪)

NumberValue

float

解析后的浮点数,或 0 当文本不是数值时

BoolValue

bool

解析后的布尔值,或 false 当文本不是可识别的布尔值时

ResolvedReference

ConvaiActionParameterReference

当文本命名了一个目标时,匹配到的作者定义目标; null 否则返回

IsConstraintMatch

bool

false 仅当 Choice 参数文本不是其作者定义选项之一时

Presence

ConvaiActionParameterPresence

Convai Character 是否为此参数提供了值

通过以下方式读取参数 ConvaiActionInvocation.TryGetParameter, GetString, GetNumber, GetBool,或 GetReference 而不是索引访问 ConvaiActionCommand.Parameters 。

ConvaiActionParameterPresence

Convai.Shared.Types

一个参数的值是否确实来自 Convai Character。声明了三个参数的动作总会返回三个,因为未填写的槽位会被填充以保持值与作者顺序对齐 — Presence 这就是执行器区分填充槽位和已回答槽位的方式。

值
整数
说明

已提供

0

此槽位已提供值。默认

缺失

1

没有值到达此槽位;该参数之所以存在,只是因为动作声明了它

在对空值采取行动之前先检查这个: 缺失 表示没有人提到该参数,执行器应自行决定——拒绝、询问,或应用自己的默认值——而不是把空值当作指令。 缺失 还会通过 动作 日志类别记录一次。

ConvaiActionParameterReference

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

名称和值类型共同构成一个 引用 参数在增强过程中被解析为的内容。

属性
类型
说明

名称

string

原始值匹配到的作者定义目标名称(已修剪,绝不为 null)

Kind

ConvaiActionTargetKind

名称是否匹配到作者定义的对象或角色

ConvaiActionParameterReference 是查找键,不是场景绑定——它不包含 GameObjectReference。将其解析为一个活动的 GameObject 到 ConvaiActionInvocation.GetReference(name),它返回一个 ConvaiResolvedActionTarget.

ConvaiActionConfig

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

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

属性
类型
说明

动作

List<string>

此会话允许的动作名称。只发送名称——执行器绑定保持本地

对象

List<ConvaiActionObjectDefinition>

后端可作为目标引用的对象。 GameObjectReference 绝不会被序列化

角色

List<ConvaiActionCharacterDefinition>

后端可作为目标引用的角色。 GameObjectReference 绝不会被序列化

CurrentAttentionObject

string

初始关注对象名称。必须与中的某项匹配 对象

ConvaiActionConfigPatch

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

当前会话动作能力的运行时补丁,通过以下方式发送 character.DynamicContext.Apply(...).

属性
类型
说明

动作

List<string>

替换动作列表

角色

List<ConvaiActionCharacterDefinition>

替换角色目标列表

对象

List<ConvaiActionObjectDefinition>

替换对象目标列表

CurrentAttentionObject

string

在列表替换后解析得到的关注更新

ConvaiActionObjectDefinition

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

属性
类型
已序列化
说明

名称

string

是("name")

在动作命令中使用的标识符。大小写不敏感匹配

说明

string

是("description")

发送给 Convai 以用于引用解析的自然语言描述

GameObjectReference

GameObject

没有 ([JsonIgnore])

本地场景引用。绝不发送给 Convai

仅文本

bool

没有 ([JsonIgnore])

声明此条目有意没有 GameObjectReference。如果没有它,缺失引用会被报告为设置错误

别名

List<string>

没有 ([JsonIgnore])

解析层级会精确匹配的备用名称(第 2 步),然后才进入规范化/包含式匹配

InteractionPoint

Transform

没有 ([JsonIgnore])

要移动到或瞄准的显式点。当 GameObjectReference时,回退到 null

可用

bool

没有 ([JsonIgnore])

本地解析开关, true 默认开启。不可用条目会被解析层级跳过

ConvaiActionCharacterDefinition

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

属性
类型
已序列化
说明

名称

string

是("name")

此角色目标的标识符

简介

string

是("bio")

发送给 Convai 的简短描述(例如,“现场安全主管”)

GameObjectReference

GameObject

没有 ([JsonIgnore])

本地场景引用。绝不发送给 Convai

仅文本

bool

没有 ([JsonIgnore])

与上的本地仅含义相同 ConvaiActionObjectDefinition

别名

List<string>

没有 ([JsonIgnore])

与上的本地仅含义相同 ConvaiActionObjectDefinition

InteractionPoint

Transform

没有 ([JsonIgnore])

与上的本地仅含义相同 ConvaiActionObjectDefinition

可用

bool

没有 ([JsonIgnore])

与上的本地仅含义相同 ConvaiActionObjectDefinition

ConvaiActionTarget

Convai.Runtime.Actions — MonoBehaviour

菜单路径: 添加组件 → Convai → Actions → Convai Action Target

将任何 GameObject 标记为运行时动作锚定目标,无需代码。启用后,它对所选角色的合并动作配置可见,并会像作者定义的对象或角色一样参与解析层级,区别只是同名的作者定义条目总是优先。

属性
类型
说明

TargetName

string

解析层级匹配的目标名称。空白时默认为此 GameObject的名称

Kind

ConvaiActionTargetKind

这是否是一个可执行的对象或角色

说明

string

发送给 Convai 用于锚定(Object 类型)

简介

string

发送给 Convai 用于锚定(Character 类型)

别名

List<string>

解析层级精确匹配的备用名称(第 2 步)

InteractionPoint

Transform

可选的显式移动或瞄准点

ApplyTo

ConvaiActionTargetApplyScope

启用时哪些角色会注册此目标: AllCharacters 或 SpecificCharacters

SpecificCharacters

List<ConvaiCharacter>

要注册到的角色,当 ApplyTo 是 SpecificCharacters

RegisterOnEnable

bool

目标是否在启用时注册、在禁用时注销。默认 true

内置执行器类型

每个执行器的完整字段级参考都在上 动作执行器。目录中的一部分:

执行器
菜单路径
备注

ConvaiLeadPlayerActionExecutor

Convai/Actions/Lead Player To Target

Body Animation 包;需要一个 ConvaiNavMeshLocomotion peer

ConvaiScanEnvironmentActionExecutor

Convai/Actions/Scan Environment

Gaze 包;需要一个 ConvaiGazeController peer

ConvaiCountTargetGroupActionExecutor

Convai/Actions/Count Target Group

Observation 包;需要一个 ConvaiActionTargetGroup 在解析后的目标上;返回 Answered(...)

ConvaiMeasureDistanceActionExecutor

Convai/Actions/Measure Distance

Observation 包;不需要配对对象;返回 Answered(...)

Observation 包的执行器回答一个问题,而不是执行可见动作,使用 ConvaiActionExecutionResult.Answered(...) 而不是 Succeeded(...).

ConvaiActionDispatcher

MonoBehaviour — Convai.Runtime.Actions

菜单路径: 添加组件 → Convai → Convai Action Runner

约束: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

属性

属性
类型
说明

BatchPolicy

ConvaiActionBatchPolicy

当前批处理策略(代码中只读;在 Inspector 中设置)

FailurePolicy

ConvaiActionBatchFailurePolicy

当前失败策略(代码中只读;在 Inspector 中设置)

IsBusy

bool

当前是否有批次正在执行

PendingBatchCount

int

排在当前批次后面的批次数量

CurrentActionName

string

当前正在执行的动作显示名称,或为空

CancelOnUserSpeech

bool

启用后,当玩家开始说话时,调度器会立即取消正在执行的批次并清空队列。默认关闭

EnablePerformanceReactions

bool

批次/步骤生命周期是否通知 IActionPerformanceReactor 同伴(Gaze、Body Language、Emotion)。默认开启

OnBatchStarted

UnityEvent

当一个批次开始执行时触发

OnStepStarted

ConvaiActionInvocationUnityEvent

每个动作步骤开始时触发

OnStepSucceeded

ConvaiActionInvocationUnityEvent

当执行器返回时触发 成功 或 Answered

OnStepFailed

ConvaiActionInvocationUnityEvent

当某一步失败时触发(Failed、Canceled 或 TimedOut)

OnStepUnhandled

ConvaiActionInvocationUnityEvent

当执行器返回时触发 未处理

OnStepCompleted

ConvaiActionStepReportUnityEvent

每一步结束后触发,无论成功与否,附带完整的 ConvaiActionStepReport

OnBatchCompleted

UnityEvent

当所有批次步骤都完成且批次未被中止时触发

OnBatchAborted

UnityEvent

触发条件: StopBatch 策略会在失败后提前结束批次

OnCancelledByUserSpeech

事件 Action<string>

触发条件: CancelOnUserSpeech 取消正在执行的动作,携带其显示名称

方法

方法
签名
说明

EnqueueActions

void EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions)

向调度器提交一个批次。遵循当前的 BatchPolicy

参见 调度器和批处理策略 以了解批处理/失败策略行为和调优指导。

ConvaiActionConfigSource

MonoBehaviour — Convai.Runtime.Components

菜单路径: 添加组件 → Convai → Convai Actions

约束: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

属性

属性
类型
说明

Definitions

IReadOnlyList<ConvaiActionDefinition>

作者定义的内联动作定义列表

ActionSets

IReadOnlyList<ConvaiActionSet>

可复用的动作集资源,优先合并到 Definitions之前;内联定义在与任何集合名称冲突时总是获胜

对象

IReadOnlyList<ConvaiActionObjectDefinition>

作者定义的可执行对象列表

角色

IReadOnlyList<ConvaiActionCharacterDefinition>

作者定义的可执行角色列表

InitialAttentionObject

string

在连接时预先设为 NPC 关注点的对象名称

ActionExecutionMode

ConvaiActionExecutionMode

声明由 ConvaiActionDispatcher 或自定义代码来运行此角色的动作。运行时不改变任何内容;供 SDK 自身的设置检查使用

BehaviorHost

GameObject

新建作者动作行为被添加到的对象:分配的子对象,或在未分配时添加到角色本身

方法

方法
签名
说明

BuildActionConfig

ConvaiActionConfig BuildActionConfig()

构建并返回连接时载荷。如果不存在有效定义,则返回 null 在此角色上运行命令。默认;设置检查在此模式下会期望有一个调度器组件

ConvaiActionExecutionMode

Convai.Runtime.Components

值
整数
说明

ConvaiActionDispatcher

0

随附的 ConvaiActionDispatcher on this character runs the commands. Default; setup checks expect a dispatcher component in this mode

CustomCode

1

你的代码订阅 ConvaiCharacter.OnActionsReceived 或 ConvaiManager.Events.OnCharacterActionReceived 而不是

ConvaiCharacter — 与动作相关的成员

MonoBehaviour — Convai.Runtime.Components

事件

事件
类型
说明

OnActionsReceived

event Action<IReadOnlyList<ConvaiActionCommand>>

当 Convai 为此角色返回一个动作批次时触发。在调度器处理之前触发

属性

属性
类型
说明

ActionConfig

ConvaiActionConfig

返回当前会话动作配置的克隆。可能为 null 在连接之前

方法

方法
签名
说明

GetActionConfigSource

ConvaiActionConfigSource GetActionConfigSource()

返回 ConvaiActionConfigSource 上的 GameObject,或 null

当前关注对象的运行时更新由动态上下文系统处理,而不是由 ConvaiCharacter 直接处理。参见 动作目标解析的工作方式.

RoomSessionConnectOptions — 动作字段

Convai.Runtime.Room

字段
类型
说明

ActionConfigOverride

ConvaiActionConfig

设置后,将替换 ConvaiActionConfigSource.BuildActionConfig() 用于此会话

ActionDefinitionsOverride

List<ConvaiActionDefinition>

设置后,将替换此会话的 Inspector 动作定义。会根据 ActionConfigOverride.Actions 如果两者都设置了

ConvaiActionStepReport

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

在以下位置发出的已完成步骤报告 ConvaiActionDispatcher.OnStepCompleted.

属性
类型
说明

Invocation

ConvaiActionInvocation

报告所描述的调用

Result

ConvaiActionExecutionResult

该步骤的原始执行器结果

FailureReason

ConvaiActionFailureReason

透传给 Result.FailureReason

BatchAborted

bool

此步骤是否中止了剩余批次

Message

string

成功详情,或非成功状态下的失败消息

FailureMessage

string

包含批次后果的失败详情。成功时为空

枚举

动作系统的其余枚举,按此处分组供参考。

ConvaiActionBatchPolicy

Convai.Runtime.Actions

值
整数
说明

队列

0

新批次会等待当前批次完成。默认

替换当前

1

取消当前步骤和所有待处理批次;立即开始新批次

丢弃传入项

2

在所有当前和排队中的工作完成之前,丢弃新的批次

ConvaiActionBatchFailurePolicy

Convai.Runtime.Actions

值
整数
说明

StopBatch

0

某一步失败会中止剩余的批次。 OnBatchAborted 触发。默认

继续批次

1

执行无论如何都会继续到下一步。 OnBatchCompleted 触发

ConvaiActionTargetRequirement

Convai.Runtime.Actions

值
整数
说明

无

0

动作不需要目标

对象

1

动作需要一个已解析的对象目标

Character

2

动作需要一个已解析的角色目标

任一

3

动作可接受对象或角色作为目标

ConvaiActionFailurePolicyOverride

Convai.Runtime.Actions

值
整数
说明

使用调度器默认值

0

遵循 ConvaiActionDispatcher 失败策略。默认

StopBatch

1

非成功结果会中止剩余的批次

继续批次

2

非成功结果会让剩余的批次继续

ConvaiActionTargetKind

Convai.Shared.Types

值
整数
说明

无

0

未解析到目标

对象

1

目标是已注册对象

Character

2

目标是已注册角色

ConvaiActionParameterType

Convai.Shared.Types

值
整数
说明

自动

0

按该顺序尽力推断为引用、数字、布尔值或字符串。默认

引用

1

按名称解析一个已创建的对象或角色目标

字符串

2

保留原始文本

数值

3

解析不变区域性的浮点数

布尔

4

解析 true/是/1 或 false/否/0

Choice

5

要求使用预设的选项字符串之一。不匹配会通过 IsConstraintMatch

ConvaiActionExecutionStatus

Convai.Runtime.Actions

值
整数
调度器事件已触发

成功

0

OnStepSucceeded

Failed

1

OnStepFailed

已取消

2

OnStepFailed

超时

3

OnStepFailed

未处理

4

OnStepUnhandled

ConvaiActionInvocationUnityEvent

Convai.Runtime.Actions — 可序列化类,继承自 UnityEvent<ConvaiActionInvocation>

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

ConvaiActionStepReportUnityEvent 是用于 ConvaiActionDispatcher.OnStepCompleted;它扩展自 UnityEvent<ConvaiActionStepReport> 并携带完整的 ConvaiActionStepReport 替代。

ConvaiActionDebugProbe

MonoBehaviour — Convai.Runtime.Actions

菜单路径: 添加组件 → Convai → Actions → Diagnostics → Convai Action Monitor

约束: DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

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

上下文菜单操作

命令
效果

注入测试批次

提交一个 移动到 将针对第一个已注册对象的命令提交给调度器。在没有实时对话的情况下测试管道

重置探针状态

将所有计数器和文本字段重置为零/空

下一步

动作执行器角色动作示例排查角色动作问题

最后更新于

这有帮助吗?