NovelML 语法参考

这份档案说明 NovelML 的基本语法，以及它的执行方式。

每个标签的详细说明，请参阅「Suika3 标签参考」。

1. NovelML 是由称为「标签」的引擎命令所组成

NovelML 是一串标签。标签是 给引擎的命令。

每个标签都会告诉引擎要做什么
标签会依照出现顺序逐一执行
标签执行完后就会视为「完成」，「执行位置」会往下移动

如果你再次写出同一个标签，它在 每次执行时 都会做同样的事。

2. 执行会从上往下进行

NovelML 会从档案上方一路执行到下方，一次处理一个标签。

执行通常只会往前推进
同一时间只有一个目前的 执行位置

[text text="Hello"]
[text text="World"]

在这个例子中：

先显示 Hello
再显示 World

3. 所有内容都必须写成标签

在 NovelML 中，每一行都必须是标签。

整个剧本都要用标签撰写
就连文字也必须使用 [text] 标签

[text text="It's a beautiful day."]

4. 会等待的标签与不会等待的标签

标签主要分成两种：

执行后立即进入下一个标签的标签
会等待 使用者输入或某件事完成的标签

常见的「等待」标签包含：

text（等待点选）
click（等待点选）
wait（等待指定时间）
video（等待播放结束）

这些标签会让执行暂停，不需要任何特殊语法。

4.1 在背景执行的标签（非同步）

有些标签可以 在背景执行（非同步）。

常见例子：

anime
move

这些标签会：

建立并开始动画或移动
如果指定 async="true"，引擎 不会等待 它结束，而是立刻接著执行下一个标签

因此，async="true" 标签后面的内容，可能会在动画仍在播放时就开始执行。

这样就能做出像这样的效果：

移动背景或角色
同时显示文字或执行其他效果

5. 会改变执行流程的标签

一般来说，执行会从上到下进行，但有些标签会 改变后续的执行位置。

5.1 标签

[label start]

标签会在剧本中标记一个命名位置
执行 label 本身不会做任何事

5.2 跳转

[goto name="start"]

6. 条件分支（if / elseif / else）

[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]

只会执行第一个符合条件的区块
没被选到的区块会 完全跳过
elseif 可以写零次或多次
else 是可选的

7. 变数与变数展开

7.1 设定变数

使用 [set] 标签来设定变数。

[set name="player_name" value="Alice"]

所有变数都是字串
数字与布林值也会以字串形式储存

7.2 变数展开

你可以在标签值与文字中使用变数展开。

[text text="${player_name} stands up"]

${...} 会在执行时被替换成变数值
展开会发生在 标签执行时

[set name="x" value="1"]
[text text="${x}"]
[set name="x" value="2"]
[text text="${x}"]

这个例子中的输出会先是 1，再是 2。

8. 巨集是可以整体执行的区块

巨集可以把数个标签分组，并一起执行。

[defmacro name="greet"]
  [text text="Hello"]
[endmacro]

[callmacro name="greet"]

9. 切换档案（load）

[load file="scene2.txt" label="start"]

file= 是必填，label= 是选填。

10. 到了档案结尾会发生什么事

如果执行流程：

到达档案结尾，而且
没有再发生任何 goto 或 load 标签

那么 剧本执行就会结束。

不过，在某些平台上（例如 iOS 或游戏主机），应用程式不被允许直接结束。

因此建议你的剧本 明确地：

用 goto 跳回标题画面，或
用 load 载入标题场景

而不要让它自动结束。

11. 这份档案和其他档案的关系

这份档案是搭配以下内容使用的：

标签参考：说明每个标签的用途
这份档案：说明剧本如何执行

各个标签的细节请参阅「标签参考」。