游戏叙事与剧情 / 系统课时

处理命令未注册的情况

处理命令未注册的情况

Yarn 脚本里的命令能被解析,并不等于 Unity 一定能执行它。本节用一条最小命令把“脚本名称、处理器映射、目标对象、参数转换和对象生命周期”串起来,形成一套可重复的定位顺序。

学习目标

  • 判断失败发生在命令名、处理器注册、目标对象还是参数绑定阶段。
  • 正确使用 YarnCommand 把 Yarn 命令映射到 Unity 方法。
  • 用最小复现和运行时检查确认修复已经生效。

先把命令链路拆开

一条自定义命令通常会经过“Yarn 脚本产生命令 → DialogueRunner 查找处理器 → 定位目标对象 → 转换参数 → 调用方法”。只要其中一环断开,表面现象都可能只是“命令没反应”。

Yarn 命令从脚本到 Unity 方法的处理与失败分支

排查时不要先改业务逻辑。先把命令缩到只有一个名称、一个目标对象和两个简单参数,确认映射本身成立,再逐步恢复动画、任务状态或场景切换。

用最小命令验证注册

下面的 QuestCommandBridge 挂到一个名为 QuestBridge 的活动 GameObject 上。实例方法使用 YarnCommand 暴露后,Yarn 命令的第二个词用于定位目标对象,后续参数再传给方法。

csharp
using UnityEngine;
using Yarn.Unity;

public sealed class QuestCommandBridge : MonoBehaviour
{
    [YarnCommand("quest_log")]
    public void QuestLog(string questId, int step)
    {
        // 先只记录参数,排除任务系统和动画系统的干扰。
        Debug.Log($"quest_log: {questId}, step={step}");
    }
}

片段示例:把下面内容放进一个可运行的 Yarn 节点正文。

text
Narrator: 准备执行任务命令。
<<quest_log QuestBridge main 2>>
Narrator: 命令已经返回。

预期输出:

text
quest_log: main, step=2

如果这一条仍然没有进入 QuestLog,问题就在命令映射链路,而不是后面的任务逻辑。

按固定顺序定位失败点

先核对命令名。quest_log 必须与特性中的名称完全一致,不要把 C# 方法名 QuestLog 当成 Yarn 命令名。使用 YarnCommand 时,也可以在 Unity 的 Yarn Spinner Commands 窗口里确认项目是否识别到了该命令。

接着检查目标对象。示例中的 QuestBridge 必须存在于当前活动场景中、名称匹配,并且对象处于激活状态;组件也必须挂在这个对象上。实例命令找不到目标对象时,即使特性本身正确,方法仍不会被调用。

最后核对参数。main 对应 string questId,2 对应 int step。少传、多传,或者把整数位置写成无法转换的文本,都应优先视为参数绑定问题,而不是“Yarn 卡死”。

区分自动发现与手动注册

YarnCommand 适合把命令直接绑定到场景对象上的行为,例如移动角色、播放动作或切换机关。若命令更偏全局业务,也可以在代码中对 DialogueRunner 使用 AddCommandHandler 手动注册,并在合适的生命周期里保持注册关系。

无论采用哪种方式,都应保证“开始对话之前处理器已经可用”。若手动注册代码只在某个稍后才启用的对象里执行,对话先启动、注册后发生,就会出现同一脚本有时能执行、有时不能执行的时序问题。

修复后再次运行最小命令,先确认 Console 只出现一次预期日志,再恢复真实参数和业务动作。这样可以把“注册失败”“参数失败”和“业务方法内部失败”明确分开,而不是在一条长任务流程里盲查。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

处理命令未注册的情况

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通