Yarn Spinner：对话驱动的叙事游戏开发实战指南

如果你在做一款剧情驱动的独立游戏，对话系统是绕不过去的坎。

自研对话系统费时费力，容易出Bug，还很难给策划用。最终往往是程序员写一堆字符串表，策划改一个标点都要找你——这不是好的工作流。

Yarn Spinner 就是来解决这个问题的。

它是一个专为叙事游戏设计的开源对话引擎，最初由Secret Location开发（《Night in the Woods》的对话系统就是用它），后来开源并支持Unity、Unreal和Godot三大主流引擎。

Yarn Spinner是什么

Yarn Spinner的核心是一个对话剧本格式（.yarn文件），你可以把它理解成一种专门为对话设计的脚本语言。编剧写剧本，程序员加载引擎，策划直接改脚本——不需要编译，不需要重启游戏。

title: Start
---
<<set $playerName to "阿强">>
欢迎来到酒馆，陌生人！我叫 <<print $innkeeperName>>。

请坐吧，你要喝点什么？
-> 啤酒
   <<set $choice to "beer">>
   老板：好嘞，一杯麦酒！请稍等。
-> 果汁
   <<set $choice to "juice">>
   老板：果汁？有点意思，给你来一杯鲜榨的。
-> 什么也不点
   <<jump LeaveEarly>>
===

这段脚本可以立即在游戏里运行，支持分支选择、变量、跳转——全部由非程序人员编写。

核心概念：Node、Line、Option

Node（节点）

Yarn Spinner的剧本由多个**Node（节点）**组成，每个Node有唯一标题（title:），相当于游戏中的一个场景或对话片段。

title: 酒馆老板对话
---
...对话内容...
===

Line（对话行）

对话行是Yarn Spinner的核心内容，用<<character>>标注说话人：

<<老板>> 欢迎光临！
<<阿强>> 你好。

不带标注的行会被当作旁白或叙述文字。

Option（选项）

选项用->开头，支持多级嵌套：

-> 你好老板
   <<jump 老板问候>>
-> 最近生意怎么样
   <<jump 老板抱怨>>
-> 离开
   <<jump 离开酒馆>>

Commands（命令）

<<set>>、<<jump>>、<<if>>等都是Yarn Spinner的内置命令：

<<set $reputation to $reputation + 1>>
<<if $health < 30>>
   <<jump 紧急治疗节点>>
<<else>>
   <<jump 正常节点>>
<<endif>>

三大引擎集成对比

引擎	集成难度	图形化编辑器	官方支持	适合项目
Unity	⭐ 低	✅ Yarn Editor插件	官方主力	所有规模
Godot	⭐ 低	✅ 内置	官方插件	所有规模
Unreal	⭐⭐ 中	⚠️ 第三方	社区维护	中大型

Unity集成（推荐）

1. Unity Package Manager: com.yarnspinner.unity
2. 导入后，Yarn目录设为Yarn Project
3. DialogueRunner组件拖到场景
4. 开始写.yarn文件

// 加载Yarn Project
var yarnProject = YarnProjectCreator.CreateYarnProject();
dialogueRunner.yarnProject = yarnProject;

// 启动对话
dialogueRunner.StartDialogue("StartNode");

Godot集成

# Godot 4.x
func start_conversation():
    var yarn_project = YarnProject.new()
    yarn_project.load_project("res://dialogue/main.yarn")
    $YarnSpinner.start(yarn_project, "Start")

Unreal集成（需要社区插件）

Unreal支持通过C++或Blueprint节点调用Yarn Spinner，但图形编辑器需要额外安装插件。适合已经有Unreal使用经验的团队。

Yarn Spinner最佳实践

实践一：用变量替代硬编码

反例：

<<老板>> 欢迎回来，阿强！
<<老板>> 你的金币余额是128枚。

正例：

<<set $greeting to "欢迎回来，{$playerName}！">>
<<老板>> <<print $greeting>>
<<老板>> 你的金币余额是<<print $gold>>枚。

好处：同一段对话可以用在多个玩家身上，不需要为每个名字写单独的对话分支。

实践二：状态标记法管理剧情分支

当对话分支很多时，建议用状态标记而不是条件嵌套：

// 推荐方式：先统一设置状态，最后统一分支
<<if $met_innkeeper>>
   <<set $scene to "重逢">>
<<else>>
   <<set $scene to "初见">>
   <<set $met_innkeeper to true>>
<<endif>>

<<jump $scene>>
===

这样即使后面加了很多场景，也能通过搜索$scene快速找到所有分支出口。

实践三：对话与表现层分离

Yarn Spinner只负责对话逻辑，不负责表现层（角色立绘、表情、位置动画）。这是设计上的刻意选择。

建议在Unity中使用事件系统处理表现层：

// Yarn Spinner发送自定义命令，Unity处理表现
dialogueRunner.AddCommandHandler("show_emotion", (string[] parameters) => {
    var emotion = parameters[0];
    var character = parameters[1];
    // 这里写立绘/表情/位置变化的逻辑
});

dialogueRunner.AddCommandHandler("play_sound", (string[] parameters) => {
    AudioManager.Play(parameters[0]);
});

在Yarn脚本中：

<<show_emotion happy 老板>>
<<play_sound tavern_ambient>>

实践四：多人协作的文件组织

大型项目的对话文件组织建议：

dialogue/
├── characters/
│   ├── 老板.yarn
│   ├── 阿强.yarn
│   └── NPC群像.yarn
├── locations/
│   ├── 酒馆.yarn
│   └── 城镇.yarn
└── main.yarn  ← 主入口，引用所有子文件

在main.yarn中用include指令引用：

<<include "characters/老板.yarn">>
<<include "locations/酒馆.yarn">>

实践五：国际化处理

Yarn Spinner支持多语言，但需要预先规划：

title: Start
---
// line: 这段对话需要翻译
<<老板>> 欢迎光临！
===

建议在项目初期就确定语言键格式，避免后期大规模重写。

实践六：调试工作流

Yarn Spinner的Unity插件内置了调试窗口，可以：

实时查看变量值
单步执行对话
查看所有Node和跳转路径

建议：策划写完对话后，先在Unity里用调试器跑一遍，确认所有分支都能正常到达，再交程序员接入游戏逻辑。

Yarn Spinner vs 其他方案

特性	Yarn Spinner	Ink	Fungus
语言	Yarn（类YAML）	Inkle's ink	Block-based
Unity原生支持	✅ 官方	⚠️ 社区	✅ 官方
Godot支持	✅ 官方插件	❌ 无	❌ 无
条件分支	✅	✅	✅
变量系统	✅	✅	✅
学习曲线	低	中	很低
图形编辑器	✅ Unity插件	❌	✅

Ink（Inkle's ink）的脚本语言更强大，适合超长文本和复杂统计类游戏，但Unity集成需要自己写。Fungus上手最简单，但可扩展性最弱。

典型应用场景

RPG支线任务对话

title: 支线任务_丢失的猫
---
<<if $mainQuest >= 3>>
   <<set $questAvailable to true>>
   <<NPC>> 终于有人来了！我的猫不见了……
   -> 我来帮你找
      <<set $quest_猫 to "进行中">>
      <<jump 任务接取>>
   -> 现在没空
      <<NPC>> 好吧……希望有人能帮帮我。
      <<jump END>>
<<else>>
   <<NPC>> （她看起来在等什么人。）
   <<jump END>>
<<endif>>
===

AVG/视觉小说主线

title: 第五章_真结局前夜
---
<<show_bg 夜街>>
<<play_bgm 回忆主题曲>>
<<玩家>> 明天就是决战了。
<<女主角>> 你……会回来吗？
-> 当然会
   <<set $affection += 10>>
   <<set $endingFlag to "good">>
-> 我不知道
   <<set $affection += 2>>
   <<set $endingFlag to "normal">>
===