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

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

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

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