角色动作示例

Convai 角色动作系统的渐进式示例——Inspector 设置、事件订阅、脚本化批处理注入和导航错误恢复。

这四个示例从最简单的配置逐步进展到完全的脚本控制。每个示例都是独立的——你可以在不先阅读其他示例的情况下跟随任意一个。

示例 1 — 消防安全取回（Inspector 设置，无代码）

场景： 一个消防安全培训模拟。受训者请求时，讲师 NPC 会取来一个灭火器。无需脚本。

前提条件： 场景中已烘焙好 NavMesh。

Inspector 配置

在讲师 NPC 的 GameObject，添加以下组件：

• ConvaiCharacter
• ConvaiActionConfigSource
• ConvaiActionDispatcher （将两个策略都保持默认：Queue、StopBatch）
• NavMeshMoveToActionExecutor — _stoppingDistance = 0.6

在 ConvaiActionConfigSource:

动作定义：

动作名称	目标要求	执行器
取回	对象	NavMeshMoveToActionExecutor
指向	任一	LookAtTargetActionExecutor

可作用对象：

名称	说明
灭火器	主泵控制面板旁墙上支架上的红色便携式 CO2 灭火器
警报面板	安装在场地入口附近、带红色拉柄的紧急警报面板

预期结果：

• “取回灭火器” → NPC 会导航到灭火器处，并在距离 0.6 个单位的位置停下。
• “指向警报面板” → NPC 会在 0.5 秒内转身面向警报面板。
• “取回警报” → Convai 会根据描述正确将“alarm”解析为“Alarm Panel”。

打开 Console，并按以下内容过滤： ConvaiActionDebugProbe （如果已添加探针）。你应该会看到：

[ConvaiActionDebugProbe] 第1步成功：cmd='Retrieve Extinguisher', def='Retrieve', target=Object:Extinguisher

示例 2 — 入职清单集成（事件订阅）

场景： 一个企业入职培训模拟。当 NPC 演示每个工作站时，清单 UI 会前进一步。完成完整的设备参观后，训练阶段会推进。

C# 设置

连接 OnBatchCompleted 到清单管理器。如果你在 Inspector 中进行连线，则 dispatcher 端无需额外代码。对于通过代码连线：

using Convai.Runtime.Actions;
using UnityEngine;

public sealed class OnboardingTourController : MonoBehaviour
{
    [SerializeField] private ConvaiActionDispatcher _dispatcher;
    [SerializeField] private TrainingChecklistUI _checklist;

    private void OnEnable()
    {
        _dispatcher.OnBatchCompleted.AddListener(HandleTourStepCompleted);
        _dispatcher.OnBatchAborted.AddListener(HandleTourStepFailed);
    }

    private void OnDisable()
    {
        _dispatcher.OnBatchCompleted.RemoveListener(HandleTourStepCompleted);
        _dispatcher.OnBatchAborted.RemoveListener(HandleTourStepFailed);
    }

    private void HandleTourStepCompleted()
    {
        _checklist.MarkCurrentStepComplete();
        _checklist.AdvanceToNextStep();
    }

    private void HandleTourStepFailed()
    {
        _checklist.MarkCurrentStepIncomplete();
    }
}

ConvaiActionConfigSource 定义：

动作名称	目标要求	执行器
Walk To	对象	NavMeshMoveToActionExecutor
Demonstrate	对象	LookAtTargetActionExecutor

可作用对象： 每个工作站都已按其名称和位置描述注册。

预期结果： 受训者说“给我看看档案系统。”NPC 走到文件柜前，面向它，并 OnBatchCompleted 触发后——清单会自动推进到下一步。

示例 3 — 带回退对话的导航失败（错误恢复）

场景： 一个建筑工地安全模拟。当 NPC 无法到达危险区域（路径被阻塞）时，它会承认障碍，而不是静默停止。

C# 设置

订阅 OnStepFailed 并注入一个动态上下文事件，让 NPC 说出自然的回退回应：

using Convai.Runtime.Actions;
using UnityEngine;

public sealed class ActionFailureHandler : MonoBehaviour
{
    [SerializeField] private ConvaiActionDispatcher _dispatcher;
    [SerializeField] private ConvaiCharacter _character;

    private void OnEnable() =>
        _dispatcher.OnStepFailed.AddListener(HandleStepFailed);

    private void OnDisable() =>
        _dispatcher.OnStepFailed.RemoveListener(HandleStepFailed);

    private void HandleStepFailed(ConvaiActionInvocation invocation)
    {
        if (invocation.Command.Name != "Move To") return;

        string targetName = string.IsNullOrEmpty(invocation.Command.Target)
            ? "那个位置"
            : invocation.Command.Target;

        // 告诉 Convai 发生了什么，这样 NPC 就能自然地作出回应
        _character.DynamicContext.AddEvent(
            $"移动到 '{targetName}' 失败——路径被阻塞。" );
    }
}

预期结果： NPC 朝危险区域前进， NavMeshAgent 未能完成路径时，执行器返回 失败，以及 OnStepFailed 会触发。回退事件被注入后，NPC 会说出类似“我无法到达化学品存储区——路径被脚手架挡住了。”的话。

设置 FailurePolicy 到 StopBatch （默认）这样同一批次中的后续步骤（例如“Demonstrate hazard”）就不会在导航步骤失败时继续执行。

示例 4 — 脚本化演示序列（程序化注入）

场景： 一个医疗程序培训模拟。在培训脚本中定义的某个时刻（由时间线事件触发），NPC 会自动完成一段设备演示，而无需等待受训者提出请求。

C# 设置

使用 ConvaiActionDispatcher.EnqueueActions 用于从时间线触发器或 UI 按钮注入一个多步骤序列：

using System.Collections.Generic;
using Convai.Runtime.Actions;
using Convai.Shared.Types;
using UnityEngine;

public sealed class DemonstrationTrigger : MonoBehaviour
{
    [SerializeField] private ConvaiActionDispatcher _dispatcher;

    // 从 Unity Timeline 信号、UI 按钮或游戏事件中调用此函数
    public void RunDefibrillatorDemo()
    {
        _dispatcher.EnqueueActions(new List<ConvaiActionCommand>
        {
            new ConvaiActionCommand("Move To", "Equipment Cart"),
            new ConvaiActionCommand("Pick Up", "Defibrillator"),
            new ConvaiActionCommand("Move To", "Patient Bed"),
            new ConvaiActionCommand("Point At", "Patient Bed")
        });
    }
}

连接 RunDefibrillatorDemo 到一个 UnityEngine.Timeline 信号、一个 UI 按钮 OnClick，或场景中的任何其他触发器。

预期结果： 讲师 NPC 会导航到设备推车，拿起除颤器，走到病床前，并转身面向它——整个过程无需受训者说任何话。 OnBatchCompleted 会在序列完成时触发，你可以用它来推进训练阶段。

BatchPolicy = Queue 可确保如果受训者正与一个激活的动作批次对话，这个脚本化序列会礼貌等待。切换为 BatchPolicy = ReplaceCurrent 如果演示应中断任何正在进行的动作。

下一步

排查角色动作问题角色动作脚本参考