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]
```

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

### 5.2 跳转

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

---

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

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

- 只会执行第一个符合条件的区块
- 没被选到的区块会 **完全跳过**
- `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. 这份档案和其他档案的关系

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

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

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