NovelML 语法参考
========================

本文档解释了 NovelML 的基本语法及其运行方式。

关于每个标签的详细说明，请参阅“Suika3 标签参考”。

---

## 1. NovelML 是一组被称为“标签”的引擎命令列表

NovelML 是 **标签** 的列表。一个标签是 **给引擎的命令** 。

- 每个标签告诉引擎执行某个操作
- 标签按照出现的顺序 **逐个运行**
- 标签运行完毕后，即视为“完成”，“执行位置”向前移动

如果你再次编写相同的标签，它将在 **每次运行时** 执行相同的操作。

---

## 2. 执行顺序是从上到下

NovelML 从文件顶部到底部运行，一次处理一个标签。

- 执行通常向前推进
- 只有一个当前的 **执行位置**

```PlainText
[text text="Hello"]
[text text="World"]
```

在这种情况下：

1. 显示 `Hello`
2. 然后显示 `World`

---

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

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

- 整个剧本都是使用标签编写的
- 即使是文本也必须使用 `[text]` 标签

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

---

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

主要有两种标签：

- **运行后立即移动到下一个标签的标签**
- **等待用户输入或某事件完成的标签**

常见的“等待”标签包括：

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

这些标签无需任何特殊语法即可暂停执行。****

### 4.1在后台运行的标签（异步）

某些标签可能**在后台运行**（异步）。

典型示例：

- `anime`
- `move`

这些标签：

- 创建并开始动画或移动
- 如果指定了 `async="true"`，引擎**不会等待其完成**，而是立即继续下一个标签

因此，`async="true"` 标签之后的标签可能会在**动画仍在播放时**运行。

这让你可以做诸如：

- 移动背景或角色
- 同时显示文本或运行其他效果

---

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

通常执行是从上到下，但某些标签**会改变执行的继续位置**。

### 5.1标记

```PlainText
[label start]
```

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

### 5.2跳转

```PlainText
[goto name="start"]
```

---

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

```PlainText
[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[elseif]
```

- 只有第一个匹配的块会被执行
- 未选中的块会被**完全跳过**
- 你可以写零次或多次 `elseif`
- `else` 是可选的

---

## 7. 变量与变量展开

### 7.1设置变量

使用 `[set]` 标签设置变量。

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

- 所有变量都是**字符串**
- 数字和布尔值也存储为字符串

### 7.2变量展开

你可以在标签值和文本中使用变量展开。

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

- `${...}` 在运行时被替换为变量值
- 展开发生在**标签执行时**

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

在这个例子中，输出是 `1` 然后是 `2`。

---

## 8. 宏是你可以作为一个单元运行的块

宏允许你将多个标签组合并一起运行。

```PlainText
[defmacro name="greet"]
  [text text="Hello"]
[endmacro]
[callmacro name="greet"]
```

---

## 9. 切换文件（load）

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

`file=` 是必需的，`label=` 是可选的。

---

## 10. 文件结束时发生什么

如果执行：

- 到达文件末尾，且
- 没有更多的 `goto` 或 `load` 标签发生

那么**剧本执行结束**。

然而，在某些平台（例如 iOS 或游戏主机）上，应用程序不被允许退出。

因此，建议你的剧本**显式地**：

- 使用 `goto` 跳回标题，或
- 使用 `load` 加载标题场景

而不是自动结束。

---

## 11. 本文档与其他文档的关系

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

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

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