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]

一个标记可以标记剧本中的命名位置
运行标记本身不执行任何操作

5.2跳转

[goto name="start"]

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

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

只有第一个匹配的块会被执行
未选中的块会被完全跳过
你可以写零次或多次 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. 本文档与其他文档的关系

本文档旨在配合以下内容：

标签参考：解释每个标签的作用
本文档：解释剧本如何运行

关于各个标签的详细信息，请参阅“标签参考”。