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. 這份檔案和其他檔案的關係

這份檔案是搭配以下內容使用的：

- 標籤參考：說明每個標籤的用途
- 這份檔案：說明劇本如何執行

各個標籤的細節請參閱「標籤參考」。
