Yarn 脚本是专用于 Yarn Spinner 进行用于游戏的对话内容脚本编写的一种脚本语言（具开发文档所言，是完备的编程语言），除了书写基础的对话文本内容内容之外，还拥有分支、函数和命令等功能。本文中，我们以程序向的角度，介绍该语言的基本语法和使用。

本文的内容和章节参考了官方开发文档中的对应章节，并加入了本人自己的补充和测试结果，若有失误请以官方开发文档为准。

另请参见：Yarn Spinner 开发文档：用 Yarn 写作

一、文件

1. 新建 Yarn 文档

类似普通的编程语言，Yarn 脚本可以以纯文本的形式进行编写，并保存于以 .yarn 作为后缀名的文本文件中。

因此，可以在系统的任意位置新建文本文档，并将其后缀名修改为 .yarn 即可开始进行写作。

Yarn 文档的文件名一般没有要求，可以任意进行起名。

2. Yarn 编辑器

由于 Yarn 是一种完备的编程语言，虽然大多数情况下使用记事本等程序也能进行编写，但是其无法提供语法高亮等提示性信息。

Yarn Spinner 项目为 Visual Sutido Code (简称 Vscode ) 提供了语法支持插件，因此，此处更建议使用 Visual Studio Code 作为编辑器进行编写。

在 Vscode 的拓展商店中搜索 Yarn Spinner 即可找到对应的插件，点击安装即可。

如果你无法在找到，请点击 此处 跳转到网页端的商店进行安装。

插件为 Vscode 提供了语法支持、补全和跳转等功能，下文中也将使用 Vscode 进行 Yarn 脚本编辑，但是此处不再对其功能进行详细的演示。

如果想了解更多关于 Yarn Spinner 的 Vscode 插件的用法，请参见：Yarn Spinner 开发文档：在 VS Code 中编辑

二、基本语法

1. 节点

Yarn 脚本的由一个个节点 (Node) 组成，文本内容被放置于不同的节点之中，节点相当于文本的段落。

每个节点由一个节点头 (Header) 和节点体 (Body) 构成。

(1) 节点头

节点头主要放置键值对 (形如 Key: Value ) 形式的节点元数据。

节点头中必须含有一个名为标题 (title) 的键值对，标题是节点的标识符，因此在整个 Yarn 项目中都不允许出现标题重复的节点。

注意：标题的书写类似于编程语言中的变量名，可以包含字母、数字和下划线，但不能以数字作为起始。此外，标题也是可以使用中文作为命名的。

(2) 节点体

节点体能够放置任意形式的文本，作为对话的主要内容。此外，节点体中还可以放置特殊形式的选项和命令，具体我们将在下文详细介绍。

(3) 分隔符

在 Yarn 脚本的书写中，节点与节点之间、节点头与节点体之间分别都要用到分隔符进行分割。

其中，节点头与节点体之间使用 --- 符号进行分隔，而节点与节点之间使用 === 符号进行分隔，即放置在节点体的结尾处。

分隔符是必须存在的，否则该脚本无法被正确的解析。

一个正确的节点书写示例如下：

title: 这是标题
---
这是内容
===

2. 节点内容

节点内容即指上文中提到的节点体中的内容。节点内容大概可以分为三类：行、选项和命令。

(1) 行

行即指节点内容中的对话文本，当节点运行时，节点内容中的文本会被逐行的发送到游戏中。

参考以下 Yarn 代码：

title: 示例节点_01
---
这是一行文本。


相邻的文本行之间可以添加任意的空行，空行不会被解析到游戏中。
在游戏中会一行一行的显示这些文本。
===

上述代码在游戏中的运行效果如下所示：

文本行可以角色名起始，并使用冒号 (注意是英文的冒号) 来与文本内容间隔，来指定这句话的说话人。

注意：只要一行文本中包含英文冒号，那么从左往右第一个英文冒号前的文本就会被标记为角色名。

参考以下 Yarn 代码：

title: 示例节点_02
---
丰川祥子: 这是最后通告。
丰川祥子: 从今以后不要再和我扯上关系了。
长崎素世: 等一下，不要走！
长崎素世: 要是没有祥子的话，我...
===

上述代码在游戏中的运行效果如下所示：

这些行文本可以包含几乎所有文本，除了一些 Yarn Spinner 用来标记对话中的额外信息的特殊字符，这些字符将会在下文中提到。

(2) 注释

Yarn 脚本中的注释以 /// 作为起始，可以被放置于节点体中的任意位置。注释不会被以任何形式载入到游戏中。

参考以下 Yarn 代码：

title: 注释节点
---
/// 开始
你好，世界。 /// 这是文本行
===

(3) 选项

当你想让玩家进行一个抉择，或是想要让玩家决定要说什么，那么可以使用选项。选项会向玩家弹出多个可选按钮，让玩家单击其中一个选项来继续。

① 基本选项

选项以 -> 符号起始，并在其后书写选项的内容。

参考以下 Yarn 代码：

title: 示例节点_03
---
守卫: 曾经我也是一名像你一样的冒险者。
守卫: 直到我膝盖中了一箭。

-> 可悲可叹
-> 谁管你啊
===

上述代码在游戏中的运行效果如下所示：

② 选项组

多个中间无空行、有相同缩进的文本行的选项是同组选项，非同组选项会被分别显示。

参考以下 Yarn 代码：

title: 示例节点_04
---
Pop子: 填志愿的时候说想成为圣骑士结果被骂了

-> ......
/// 此处空行
-> 抱歉，刚刚在想HellShake矢野的事情。

上述代码在游戏中的运行效果如下：

③ 选项后续

若在某选项的后一行书写内容，并添加一级缩进，则该行内容将被视为该选项的后续，即选择该选项后将会继续播放的内容。

参考以下 Yarn 代码：

title: 示例节点_05
---
张三: 想不出话了.

-> 哈哈.
   这是哈哈的后续.
-> 呃.
   这是呃的后续.

上述代码在游戏中的运行效果如下：