动作执行器

所有六个动作执行器组件的参考——注视、事件、NavMesh 移动、动画触发器以及组合拾取执行器。

Executor 是在分发器运行一个动作步骤时执行场景内行为的组件。Convai SDK 随附六个 executor 组件。本页记录每个 Inspector 字段，并说明何时使用各个 executor。

LookAtTargetActionExecutor

可在可配置的持续时间内平滑旋转 NPC 使其面向已解析的目标。使用 Quaternion.Slerp 并支持取消。

属性	值
菜单路径	添加组件 → Convai → 动作 → Look At Target Action Executor
命名空间	Convai.Runtime.Actions
需要目标	是——返回 未处理 如果未解析到目标

Inspector 字段：

字段	类型	默认值	说明
_rotateRoot	Transform	null	要旋转的 Transform。若未指定，则使用组件自身的 transform.
_duration	float	0.5	完成旋转所需的秒数。 0 会立即瞬移到位。

行为： 该 executor 会在 _duration 秒内从当前旋转插值到目标位置朝向。如果根对象或目标在执行过程中被销毁，则返回 失败.

UnityEventActionExecutor

触发一个 UnityEvent 并立即返回 成功。不需要解析目标。可用它将任何后端动作连接到 Inspector 绑定的回调，而无需编写代码——切换门、播放声音、打开 UI 面板。

属性	值
菜单路径	添加组件 → Convai → 动作 → Unity Event Action Executor
命名空间	Convai.Runtime.Actions
需要目标	没有

Inspector 字段：

字段	类型	说明
_onExecute	UnityEvent	每次动作步骤运行时都会调用。可在 Inspector 中绑定任意数量的回调。

TransformMoveToActionExecutor 仅用于原型阶段。 它会立即将角色传送到位，不会有动画或路径寻路。发布给用户之前，请将其替换为 NavMeshMoveToActionExecutor 或自定义 executor。

TransformMoveToActionExecutor

会立即将 NPC 的 Transform 瞬移到解析后的目标位置，并可附加可选偏移。同步执行——在一帧内完成。

属性	值
菜单路径	添加组件 → Convai → 示例 → Transform Move To Action Executor
命名空间	Convai.Sample.Behaviors
需要目标	是——返回 失败 如果未解析到目标

Inspector 字段：

字段	类型	默认值	说明
_moveRoot	Transform	null	要移动的 Transform。若未指定，则使用组件自身的 transform.
_offset	Vector3	(0, 0, 0)	应用到目标位置的世界空间偏移。可用于停在目标前方一点。

NavMeshMoveToActionExecutor

驱动一个 NavMeshAgent 移动到解析后的目标位置，并等待代理到达停止距离。该动作步骤会一直保持激活直到抵达，这意味着分发器会在导航完成前暂停下一步。

属性	值
菜单路径	添加组件 → Convai → 示例 → NavMesh Move To Action Executor
命名空间	Convai.Sample.Behaviors
需要目标	是——返回 失败 如果未解析到目标

Inspector 字段：

字段	类型	默认值	说明
_agent	NavMeshAgent	自动解析	该 NavMeshAgent 要驱动的对象。若未指定，则从同一个 GameObject on Awake.
_stoppingDistance	float	0.5	以世界单位表示、代理被视为已到达的距离。

场景中必须先烘焙 NavMesh，此 executor 才能导航。打开 窗口 → AI → 导航 并在进入播放模式前进行烘焙。若代理起始时不在 NavMesh 上， SetDestination 会静默失败，而 executor 会一直循环，直到 TimeoutSeconds 超时。

AnimatorTriggerActionExecutor

通过可配置的绑定列表，将后端动作名称映射到 Animator 触发器参数。触发该参数并立即返回 成功 ——它不会等待动画结束。

属性	值
菜单路径	添加组件 → Convai → 示例 → Animator Trigger Action Executor
命名空间	Convai.Sample.Behaviors
需要目标	没有

Inspector 字段：

字段	类型	默认值	说明
_animator	Animator	自动解析	该 Animator 要驱动的对象。若未指定，则从同一个 GameObject on Awake.
_bindings	List<AnimatorTriggerActionBinding>	空	将动作名称映射到触发器名称。每个条目都有两个字符串字段（见下文）。

AnimatorTriggerActionBinding 字段：

字段	类型	说明
动作名称	string	要匹配的动作名称（不区分大小写）。必须与 ConvaiActionConfigSource的动作定义中的某个条目匹配。
TriggerName	string	动作匹配时要触发的 Animator 触发器参数。必须与 Animator Controller 中的确切触发器名称一致。

示例绑定列表：

动作名称	TriggerName
挥手	TriggerWave
敬礼	TriggerSalute
指向	TriggerPoint

如果没有任何绑定与传入的动作名称匹配，executor 会返回 失败 并带有消息 没有匹配 '<action name>' 的绑定.

PickUpActionExecutor

复合 executor，串联三种行为：导航到目标 → 触发动画触发器 → 等待动画 → 将对象附加到手部 Transform。该步骤会一直保持激活，直到三阶段全部完成。

属性	值
菜单路径	添加组件 → Convai → 示例 → Pick Up Action Executor
命名空间	Convai.Sample.Behaviors
需要目标	是——返回 失败 如果未解析到目标

Inspector 字段：

字段	类型	默认值	说明
_mover	NavMeshMoveToActionExecutor	所需	驱动到目标的导航。必须赋值——若为 null，则返回 失败 如果为 null。
_animator	Animator	null	要驱动的 Animator。可选——如果为 null 则跳过。
_pickUpTrigger	string	"PickUp"	到达目标后要触发的 Animator 触发器参数。
_attachPoint	Transform	null	被拾取对象要重新父级到的 Transform（例如手部骨骼）。可选——如果为 null，则不会重新父级。
_animationDuration	float	1.0	触发动画后，等待多少秒再将对象重新父级。

执行顺序：

1. NavMeshMoveToActionExecutor.ExecuteAsync 导航到目标。如果失败或被取消， PickUpActionExecutor 会立即返回该结果。
2. _animator.SetTrigger(_pickUpTrigger) 被调用。
3. 等待 _animationDuration 秒（可取消）。
4. 目标 GameObject 会重新父级到 _attachPoint 并将本地位置/旋转设为零。
5. 返回 成功.

PickUpActionExecutor 通过 NavMeshMoveToActionExecutor 直接调用 ExecuteAsync。这两个组件必须位于同一个 GameObject ，且场景中必须存在已烘焙的 NavMesh。

选择合适的 executor

使用场景	推荐的 executor
NPC 平滑地面向目标	LookAtTargetActionExecutor
任何无需目标、绑定到游戏玩法回调的动作	UnityEventActionExecutor
无需 NavMesh 的快速原型开发	TransformMoveToActionExecutor
带路径寻路的生产级 NPC 移动	NavMeshMoveToActionExecutor
针对不同动作播放不同动画	AnimatorTriggerActionExecutor
一个命令完成导航 + 拾取 + 附加	PickUpActionExecutor
自定义移动栈、物品栏、UI、物理	编写自定义动作 executor

使用示例

示例 1——带手势和移动的安全讲师

场景： 一个工作场所安全培训模拟。讲师 NPC 使用两个始终可用的 executor 来指向危险源并演示设备位置。

NPC 上的 Inspector 设置：

• LookAtTargetActionExecutor — _duration = 0.8
• UnityEventActionExecutor — _onExecute → 调用 HazardHighlightManager.HighlightActive()

ConvaiActionConfigSource 定义：

动作名称	目标要求	执行器
指向	任一	LookAtTargetActionExecutor
标记危险	无	UnityEventActionExecutor

预期结果： “指向燃气阀”→ NPC 会在 0.8 秒内转身面向燃气阀。“标记危险”→ UnityEvent 会触发并在 UI 中高亮当前危险。

示例 2——带动画的设备取回

场景： 一个医疗培训场景。讲师取回一个除颤器并将其递交出去。

Inspector 设置：

• NavMeshMoveToActionExecutor — _stoppingDistance = 0.6
• PickUpActionExecutor — _mover = NavMeshMoveToActionExecutor, _pickUpTrigger = "GrabItem", _attachPoint = RightHandBone, _animationDuration = 1.2

ConvaiActionConfigSource 定义：

动作名称	目标要求	执行器
取回	对象	PickUpActionExecutor

预期结果： “取回除颤器”→ NPC 导航到除颤器，播放 1.2 秒的抓取动画，然后除颤器附加到右手骨骼上。

下一步

分发器与批处理策略编写自定义动作执行器