游戏叙事与剧情 / 系统课时
用命令触发游戏行为
用命令触发游戏行为
对话脚本负责“说什么”,游戏运行时代码负责“角色和场景做什么”。Yarn Spinner 的命令可以把两者连接起来:脚本发出命令,DialogueRunner 找到对应处理函数,再由 Unity 代码播放动画、修改物体状态或启动移动逻辑。
学习目标
- 能在 Yarn 脚本中发出带参数的命令,并理解命令与对白的执行顺序。
- 能在 Unity 中为
DialogueRunner注册命令处理函数。 - 能区分立即完成的命令与需要等待动作结束的命令。
从脚本发出动作命令
Yarn 命令使用 <<命令名 参数>> 的形式。下面的节点片段先让角色播放动画,再打开场景中的门,最后继续对白。
NPC: 我们先打开门。
<<play_anim Wave>>
<<set_gate true>>
NPC: 门已经打开了。这里的 play_anim 和 set_gate 不是 Yarn Spinner 自动提供的游戏行为,而是项目自己定义的命令名。脚本只描述意图,真正操作 Animator 和 GameObject 的代码放在 Unity 侧。
在运行时代码中注册处理函数
下面的组件把两个命令映射到 C# 方法。把它挂到一个常驻对象上,并在 Inspector 中赋值 DialogueRunner、角色 Animator 与门对象。
using UnityEngine;
using Yarn.Unity;
public sealed class DialogueCommandBridge : MonoBehaviour
{
[SerializeField] private DialogueRunner dialogueRunner;
[SerializeField] private Animator actorAnimator;
[SerializeField] private GameObject gate;
private void Awake()
{
// 命令参数会按处理函数声明的类型传入。
dialogueRunner.AddCommandHandler<string>("play_anim", PlayAnimation);
dialogueRunner.AddCommandHandler<bool>("set_gate", SetGate);
}
private void OnDestroy()
{
dialogueRunner.RemoveCommandHandler("play_anim");
dialogueRunner.RemoveCommandHandler("set_gate");
}
private void PlayAnimation(string stateName)
{
actorAnimator.Play(stateName);
Debug.Log($"play_anim: {stateName}");
}
private void SetGate(bool active)
{
gate.SetActive(active);
Debug.Log($"set_gate: {active}");
}
}运行前要保证 Animator 中确实存在名为 Wave 的状态,并且 gate 引用了要切换的场景对象。执行前面的 Yarn 片段后,预期控制台可看到:
play_anim: Wave
set_gate: True同时角色切换到 Wave 动画状态,门对象被设为激活。若控制台没有对应日志,先检查命令名是否完全一致以及桥接组件是否已启用;若日志存在但画面没变化,则继续检查 Animator 状态名和对象引用。

需要等待时让命令拥有执行时长
上面的两个处理函数都是立即返回的,因此命令触发后对话会继续向下执行。移动角色、淡入淡出或等待动画结束时,如果下一句对白必须等动作完成,可以让命令处理函数返回 IEnumerator,把等待过程放进协程。
下面是片段示例,依赖同一个桥接组件中的 actorAnimator,并额外注册命令 wait_anim。
using System.Collections;
using UnityEngine;
private IEnumerator WaitAnimation(float seconds)
{
actorAnimator.Play("Wave");
yield return new WaitForSeconds(seconds);
}对应注册可以写成:
dialogueRunner.AddCommandHandler<float>("wait_anim", WaitAnimation);Yarn 中调用:
<<wait_anim 1.0>>
NPC: 动作结束后才显示这句。预期结果是命令开始后先播放动画并等待约 1 秒,再继续交付下一句对白。实际帧时序会受游戏运行状态影响,因此验收重点是“对白不会早于协程结束继续”,而不是精确到某一帧。
给命令划清职责边界
命令适合产生副作用,例如播放动画、移动角色、开关灯光、切换场景对象。决定剧情走向的数据则应保持可追踪:如果“门已打开”之后还要参与 Yarn 条件判断,应明确同步对应剧情变量,而不是只依赖场景物体当前是否激活。
命令名也应表达意图,例如 play_anim、set_gate,避免使用 do_thing 这类含义模糊的名字。参数保持少而稳定,让脚本作者能仅凭命令文本理解会发生什么。这样对话脚本与 Unity 实现可以各自演进,而不会把具体组件细节泄漏到剧情文本里。