游戏叙事与剧情 / 系统课时
用函数读取游戏状态
用函数读取游戏状态
对话条件经常要读取“玩家等级、任务是否完成、角色名”等运行时数据。本课把这些数据通过 Yarn Spinner 函数暴露给脚本,让 Yarn 只负责判断和展示,而游戏状态仍由 Unity 中的真实系统维护。
学习目标
- 理解 Yarn 函数适合读取哪些运行时状态
- 用
DialogueRunner.AddFunction注册返回int、bool和string的查询函数 - 在 Yarn 条件和文本插值中调用函数,并验证返回值
让游戏状态保持单一来源
如果玩家等级已经由角色系统维护,就不要为了对话再复制一份 $player_level。复制状态会带来同步问题:升级后忘记同步 Yarn 变量,对话就会读到旧值。
更稳妥的做法是把 Yarn 函数当成“只读查询口”。脚本调用函数时,函数立即从当前游戏对象读取最新值并返回。函数应尽量短、无副作用,不要在查询函数里发奖励、改任务进度或播放动画。

注册查询函数
下面的组件演示三个函数。DialogueStateBridge、PlayerState 和 QuestState 可以放在同一场景中,并在 Inspector 中把引用连好。
csharp
using System.Collections.Generic;
using UnityEngine;
using Yarn.Unity;
public sealed class DialogueStateBridge : MonoBehaviour
{
[SerializeField] private DialogueRunner dialogueRunner;
[SerializeField] private PlayerState playerState;
[SerializeField] private QuestState questState;
private void Awake()
{
// 函数只读取运行时状态,不修改游戏数据。
dialogueRunner.AddFunction<int>("player_level", () => playerState.Level);
dialogueRunner.AddFunction<string>("player_name", () => playerState.DisplayName);
dialogueRunner.AddFunction<string, bool>("quest_done", id => questState.IsCompleted(id));
}
}
public sealed class PlayerState : MonoBehaviour
{
public string DisplayName = "Mira";
public int Level = 7;
}
public sealed class QuestState : MonoBehaviour
{
private readonly HashSet<string> completed = new HashSet<string>();
private void Awake()
{
completed.Add("intro");
}
public bool IsCompleted(string id)
{
return completed.Contains(id);
}
}预期结果
text
进入 Play Mode 后,DialogueRunner 注册 player_level、player_name、quest_done 三个函数。
示例本身不会额外打印控制台日志。AddFunction 适合把已有服务或组件包装成查询接口。脚本层只依赖稳定的函数名,不需要知道角色系统、任务系统具体存在哪里。
在 Yarn 脚本里使用返回值
下面是片段示例,假设节点已包含在当前 YarnProject 中,并且对话开始前已经执行了上面的 Awake。
text
title: StateGate
---
Narrator: {player_name()},等级 {player_level()}。
<<if player_level() >= 5 and quest_done("intro")>>
Guide: 你已经完成入门任务,可以进入遗迹。
<<else>>
Guide: 还不满足进入条件。
<<endif>>
===预期结果
text
Narrator: Mira,等级 7。
Guide: 你已经完成入门任务,可以进入遗迹。函数可以出现在表达式和行内插值中。条件求值发生在执行到该位置时,因此如果玩家在进入节点前刚升级或刚完成任务,脚本会读取更新后的状态。
把查询和修改分开
函数最适合回答“现在是什么状态”。会改变世界状态的动作,例如领取奖励、切换镜头、播放表情,更适合用 Yarn 命令处理。这样脚本中的表达式仍然容易推理,也不会因为一个看似普通的条件判断而悄悄修改游戏数据。
当函数名、参数和返回类型保持稳定后,对话脚本可以持续使用这些接口,而角色与任务系统内部实现仍可独立重构。
按自己的节奏,确认真正理解。