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

用命令触发游戏行为

用命令触发游戏行为

对话脚本负责“说什么”,游戏运行时代码负责“角色和场景做什么”。Yarn Spinner 的命令可以把两者连接起来:脚本发出命令,DialogueRunner 找到对应处理函数,再由 Unity 代码播放动画、修改物体状态或启动移动逻辑。

学习目标

  • 能在 Yarn 脚本中发出带参数的命令,并理解命令与对白的执行顺序。
  • 能在 Unity 中为 DialogueRunner 注册命令处理函数。
  • 能区分立即完成的命令与需要等待动作结束的命令。

从脚本发出动作命令

Yarn 命令使用 <<命令名 参数>> 的形式。下面的节点片段先让角色播放动画,再打开场景中的门,最后继续对白。

text
NPC: 我们先打开门。
<<play_anim Wave>>
<<set_gate true>>
NPC: 门已经打开了。

这里的 play_anim 和 set_gate 不是 Yarn Spinner 自动提供的游戏行为,而是项目自己定义的命令名。脚本只描述意图,真正操作 Animator 和 GameObject 的代码放在 Unity 侧。

在运行时代码中注册处理函数

下面的组件把两个命令映射到 C# 方法。把它挂到一个常驻对象上,并在 Inspector 中赋值 DialogueRunner、角色 Animator 与门对象。

csharp
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 片段后,预期控制台可看到:

text
play_anim: Wave
set_gate: True

同时角色切换到 Wave 动画状态,门对象被设为激活。若控制台没有对应日志,先检查命令名是否完全一致以及桥接组件是否已启用;若日志存在但画面没变化,则继续检查 Animator 状态名和对象引用。

Yarn 命令到 Unity 行为的调用链

需要等待时让命令拥有执行时长

上面的两个处理函数都是立即返回的,因此命令触发后对话会继续向下执行。移动角色、淡入淡出或等待动画结束时,如果下一句对白必须等动作完成,可以让命令处理函数返回 IEnumerator,把等待过程放进协程。

下面是片段示例,依赖同一个桥接组件中的 actorAnimator,并额外注册命令 wait_anim。

csharp
using System.Collections;
using UnityEngine;

private IEnumerator WaitAnimation(float seconds)
{
    actorAnimator.Play("Wave");
    yield return new WaitForSeconds(seconds);
}

对应注册可以写成:

csharp
dialogueRunner.AddCommandHandler<float>("wait_anim", WaitAnimation);

Yarn 中调用:

text
<<wait_anim 1.0>>
NPC: 动作结束后才显示这句。

预期结果是命令开始后先播放动画并等待约 1 秒,再继续交付下一句对白。实际帧时序会受游戏运行状态影响,因此验收重点是“对白不会早于协程结束继续”,而不是精确到某一帧。

给命令划清职责边界

命令适合产生副作用,例如播放动画、移动角色、开关灯光、切换场景对象。决定剧情走向的数据则应保持可追踪:如果“门已打开”之后还要参与 Yarn 条件判断,应明确同步对应剧情变量,而不是只依赖场景物体当前是否激活。

命令名也应表达意图,例如 play_anim、set_gate,避免使用 do_thing 这类含义模糊的名字。参数保持少而稳定,让脚本作者能仅凭命令文本理解会发生什么。这样对话脚本与 Unity 实现可以各自演进,而不会把具体组件细节泄漏到剧情文本里。

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

目录与阅读设置

记录一个想法

用命令触发游戏行为

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

登录哪都通