Suika3 標籤參考

索引

---

anime

執行動畫

anime 標籤會從檔案載入並執行動畫定義。 它可用來做出複雜的視覺效果、角色移動，或超越簡單轉場的迴圈環境動畫。

Basic Usage

# 執行同步動畫（等待完成）
[anime file="opening_effect.txt"]

# 執行非同步迴圈動畫
[anime file="sparkle.txt" async="true" register="my_loop"]

# 停止已註冊的非同步動畫
[anime stop="true" register="my_loop"]

Arguments

Tips

同步與非同步：

• 同步（async="false"）：適合過場動畫，讓玩家先看完動畫，再顯示文字或選項。
• 非同步（async="true"）：適合背景效果，例如飄雪或閃爍燈光，讓故事繼續時動畫也持續播放。

管理例項：

• 透過 register 引數，你可以替特定動畫加上名稱。
• 這就是你在使用 stop="true" 時，告訴引擎要停止哪個動畫的方法。

UI 控制：

• 如果動畫要佔滿全螢幕，而你希望對話視窗暫時消失以保持畫面乾淨，可以使用 showmsgbox="false"。

---

bg

變更背景

bg 標籤會以平滑淡入淡出效果變更背景圖片。 這是視覺小說裡設定場景的主要方式。

Basic Usage

# 在 1.0 秒內切換到 background.png
[bg file="background.png" time="1.0"]

# 淡出成黑畫面（移除背景）
[bg file="none" time="1.0"]

Arguments

Transition Methods (method)

透過選擇適合的轉場樣式，可以營造不同氛圍：

在 rule 與 melt 中，圖片會依照規則圖由最暗區域一路切換到最亮區域。

Tips

相對定位：

• 如果你想從目前位置微調背景，請使用 r 字首。
• 例如，x="r50" 會讓圖片從目前 X 座標往右移 50 畫素。

什麼是 rule 圖？

• 這是一張灰階圖片，黑色區域會先轉場，白色區域會最後轉場。
• 透過自訂 rule 圖，你可以做出水平擦除、圓形展開，甚至更有藝術感的圖樣！

---

bgm

播放背景音樂

bgm 標籤會播放背景音樂曲目。 音樂是營造場景氛圍的重要工具，並且會自動迴圈播放，直到被停止或更換。

Basic Usage

# Start playing a BGM track
[bgm file="field_theme.ogg"]

# Stop the current BGM (use "none")
[bgm file="none"]

Arguments

Tips

Required Format:

• For compatibility and performance, Suika3 requires BGM files to be in Ogg Vorbis format.
• The sampling rate MUST be 44,100Hz.

Looping:

• Background music is designed to loop by default, so you don't need to worry about the music ending abruptly during a long dialogue scene.

Smooth Transitions:

• If you call [bgm] while another track is already playing, the engine will typically handle the transition.
• To adjust the loudness of the music, you'll want to use the [volume] tag.

Stopping Music:

• When a scene ends or the mood changes to silence, remember to use [bgm file="none"] to give the player's ears a rest!

---

callmacro

呼叫巨集

callmacro 標籤會執行先前定義好的巨集。 它可以讓你在腳本中多次觸發特定的一串命令，例如角色登場或 UI 動畫，而不必重寫原始程式碼。

Basic Usage

# 呼叫名為 "kaito_entrance" 的巨集
[callmacro name="kaito_entrance"]

# 呼叫用於特定場景轉場的巨集
[callmacro name="fade_to_white"]

Arguments

Tips

效率：

• 使用 [callmacro] 可以讓主劇情腳本保持專注且易讀。
• 原本要看十行動畫程式碼，現在只會看到一條清楚的命令。

執行流程：

• 當引擎碰到 [callmacro] 時，會立刻跳到已定義的巨集，執行裡面的所有標籤，然後自動回到 [callmacro] 標籤後的下一行。

模組化設計：

• 可以把巨集想成你遊戲裡的「自訂標籤」。
• 如果你想改變角色入場方式，只需要在 [defmacro] 區塊更新一次程式碼，每個 [callmacro] 都會跟著反映這個變更！

---

ch

角色顯示

ch 標籤可在各個圖層上顯示、隱藏或更新角色圖片。 它可以同時精細控制多個角色與背景的位置、縮放與旋轉。

Basic Usage

# 在中央顯示角色
[ch center="chara001.png" time="1.0"]

# 顯示多個角色並指定位置
[ch left="chara002.png" right="chara003.png" time="0.5"]

# 隱藏指定角色
[ch center="none" time="1.0"]

Arguments

圖層檔案引數

指定檔名即可將圖片載入到某個圖層。設為 none 則會解除安裝（隱藏）圖片。

圖層引數引數

上面的每個圖層（例如 center）都可以使用下列字尾自訂（例如 center-x、center-rotate）。

Tips

批次更新：

• 你可以在單一 [ch] 標籤中同時更新多個角色與背景，讓它們一起完美地進行動畫。

相對變換：

• 和 bg 標籤一樣，所有數值引數都支援 r 字首。
• 例如 center-y="r-50" 會讓中央角色從目前位置往上移動 50 畫素。

---

chapter

設定章節名稱

chapter 標籤會設定目前章節的名稱。 這個名稱通常會被遊戲系統用來在存檔/讀檔選單或遊戲畫面上顯示進度，方便玩家追蹤劇情進展。

Basic Usage

# 在故事段落開頭設定章節名稱
[chapter name="Chapter 01: The Beginning"]

# 隨著故事推進更新章節名稱
[chapter name="Intermission: A Quiet Night"]

Arguments

Tips

存檔顯示：

• 在許多 Suika3 設定中，你在這裡設定的字串會顯示在「存檔」與「讀檔」欄位上。
• 請選一個能讓玩家清楚記得目前進度的名稱！

一致性：

• 在開始新的主要場景或章節的 [label] 後立刻呼叫 [chapter] 標籤，是個很好的習慣。

更新名稱：

• 你可以隨時多次呼叫 [chapter]。
• 每次呼叫時，舊的章節名稱都會被新的名稱覆蓋。

---

choose

顯示選擇選項

choose 標籤會顯示最多 8 個可互動按鈕給玩家。 它會把所選專案的文字儲存在變數中。

Basic Usage

# 將選擇結果儲存在變數中
[choose
    text1="Red Pill"
    text2="Green Pill"
    text3="Blue Pill"
    name="user_choice"
    value1="red"
    value2="green"
    value3="blue"
]

Arguments

Localization

例如，如果使用者的作業系統語系是日文，系統會優先採用 text1-ja，而不是 text1。

對於所有英文系統語系，-en 會作為預裝置援。 如果標籤中指定了像 -en-gb 這樣更精確的變體，而且它與使用者地區最相符，就會優先採用。 西班牙文與法文也使用相同機制。 請注意，繁體中文不會回退到簡體中文。

例如，如果使用者語系是 en-AU，會套用以下優先順序：

• 1. text1-en-au
• 1. text1-en
• 1. text1

以下目前尚未支援，但預計未來會支援。

Tips

分支邏輯：

• 你可以使用 [if] 標籤檢查儲存的值，建立複雜分支。

[choose
  name="var1"
  text1="Go to school"
  text2="Go to hospital"
  value1="1"
  value2="2"]

[if lhs="${var1}" op="=" rhs="1"]
  # 學校。
[else]
  # 醫院。
[endif]

變數儲存：

• 因為所有內容本質上都是字串，請記得像 "100" 這樣的數字也會以文字儲存。
• Suika3 的邏輯標籤（例如 if）可以拿這些字串來做比較。

---

set

設定變數

set 標籤會把值指定給某個變數名稱。 在 Suika3 中，所有變數都會被視為文字字串，但在像 [if] 這類其他標籤中仍可做數值比較。

Basic Usage

# 將單純字串指派給變數
[set name="player_name" value="Kaito"]

# 設定類似數字的值（仍會以字串儲存）
[set name="health" value="100"]

# 透過設定空字串來清除變數
[set name="flag_event_01" value=""]

# 將 var1 加 1。
[set name="var1" value1="${var1}" op="+" value2="1"]

Arguments

Tips

字串處理：

• 由於 Suika3 會把所有內容都當成文字，value="100" 和 value="May" 在內部的處理方式是相同的。
• 你可以在其他標籤（例如 text 或 if）中使用 ${variable_name} 語法來引用這些變數。

旗標管理：

• 對於遊戲旗標（例如「是否遇過主角」），常見作法是使用 "true" 和 "false"，或 "1" 和 "0"。
• 一致性很重要！如果你一開始使用 "1"，就請一直維持下去，這樣 [if] 判斷才不會混淆。

變數命名：

• 請避免在變數名稱中使用空格或特殊符號。my_variable 會比 my variable! 安全得多。

---

click

等待點選

click 標籤會暫停指令碼執行，等待玩家點選滑鼠或按下按鍵。 它通常用來在畫面變化之間，或在重大轉場前製造停頓。

Basic Usage

# 變更背景，然後等待玩家點選
[bg file="sunset.png" time="1.0"]
[click]

# 點選之後顯示角色
[ch center="chara01.png" time="1.0"]

Arguments

這個標籤不接受任何引數。

Tips

時機與節奏：

• 當你想在對話繼續前，讓玩家先看一下新的背景或特定角色表情時，可以使用 [click]。
• 和 [text] 標籤不同，[text] 在顯示訊息後會自動等待點選，而 [click] 則用於非對話段落中的手動流程控制。

視覺回饋：

• 當指令碼執行到 [click] 標籤時，遊戲會停在目前畫面。請確保前面的動畫（例如 [bg] 或 [ch]）都有設定 time，不然畫面可能會顯得太突兀地靜止。

若要定時等待：

• 請使用 [wait] 來做定時等待。

---

goto

跳轉到標籤

goto 標籤會立刻把 NovelML 的執行移到指定標籤。 它是控制故事流程的實用工具，可以讓你跳過某些段落，或迴圈回前面的部分。

請注意，小型分支應該用 [if] 來實作。

Basic Usage

# 跳到早晨場景的開頭
[goto name="morning_start"]

# ... 這段指令碼會被跳過 ...

[label name="morning_start"]
[text text="The sun rises over the horizon."]

Arguments

Tips

無條件跳轉：

• 和 [if] 不同，[goto] 會在引擎碰到標籤時立刻跳到目標標籤。

流程管理：

• 可以在分支路徑的結尾使用 [goto]，把故事帶回「共通」路線。
• 搭配其他邏輯時，它也很適合拿來建立迴圈（例如「返回標題」流程）。

跨檔案？：

• 請記得 [goto] 通常只會在目前指令碼檔案內運作。
• 如果你想完全跳到另一個檔案，就要看 [load] 標籤了！

---

defmacro

定義巨集

defmacro 標籤會開始定義一個巨集。 巨集可以把多個標籤與命令組成一個有名稱的區塊，並且能在腳本中透過 [callmacro] 重複使用。

Basic Usage

# 為特定角色登場定義巨集
[defmacro name="enter_kaito"]
    [ch center="kaito_smile.png" time="0.5"]
    [text name="Kaito" text="Hey! Did I keep you waiting?"]
[endmacro]

# 之後在腳本中只要一行就能呼叫
[callmacro name="enter_kaito"]

Arguments

Tips

結束定義：

• 每個 [defmacro] 都必須搭配 [endmacro] 標籤，標示定義結束。

程式重用：

• 巨集很適合重複出現的序列，例如特定 UI 轉場、角色專屬視覺配置，或複雜的音效與畫面組合。

組織方式：

• 常見做法是在主腳本檔的最前面，或在啟動時載入的獨立檔案中，集中定義所有巨集。

巢狀與邏輯：

• 你幾乎可以在巨集中放入任何其他標籤，包含 [if] 判斷，甚至可以用 [returnmacro] 依條件提前離開巨集。

---

gui

顯示 GUI

gui 標籤會從指定檔案載入並顯示圖形化使用者介面（GUI）定義。 它可用來顯示選單、標題畫面或自訂互動面板。

Basic Usage

# 顯示主選單 GUI
[gui file="main_menu.txt"]

# 顯示自訂存檔/讀檔畫面
[gui file="save_screen.txt"]

Arguments

Tips

GUI 定義：

• file 引數指向一個文字檔，這個檔案會定義介面的版面、按鈕與動作。
• 這些檔案會指定圖片放置的位置，以及使用者互動時會發生什麼事（例如跳到標籤或結束遊戲）。

流程中的用途：

• 一般來說，[gui] 標籤會用在像標題畫面這類圖形化選單。

自訂化：

• 因為 GUI 是定義在外部檔案中，所以你可以為遊戲做出多種外觀，只要用這個標籤呼叫不同檔案即可切換。

---

label

定義標籤

label 標籤會定義腳本中的特定位置，可供 [goto] 或 [load] 之類的跳轉命令鎖定。 它就像故事導覽用的書籤。

Basic Usage

# 為新章節的開頭定義標籤
[label name="chapter_01_start"]

# 使用跳轉命令前往這個標籤
[goto name="chapter_01_start"]

Arguments

Tips

導覽控制：

• 標籤很適合用來建立分支路徑。
• 例如，你可以在故事某個段落的開頭放一個 label，方便長距離跳轉。

名稱唯一：

• 同一個腳本檔內的每個標籤名稱都必須唯一。
• 如果有兩個同名標籤，引擎可能會不知道該跳去哪裡，這對誰都不方便。

組織方式：

• 使用像 label_evening_park 這種有描述性的名稱，會比 label1 更好。
• 這會讓你（也讓我！）之後更容易閱讀腳本並理解發生了什麼。

---

text

顯示文字

text 標籤會在訊息框中顯示訊息。 它可以顯示主要對話或旁白，也可以選擇在名稱框中顯示角色名稱。

Basic Usage

# 旁白樣式（不顯示名稱）
[text text="The wind was howling through the trees."]

# 角色對話
[text name="Keith" text="I've been waiting for you here in the small room."]

Arguments

Localization

例如，如果使用者的作業系統語系是日文，系統會優先採用 text-ja，而不是 text。

對於所有英文系統語系，-en 會作為預設備援。 如果標籤中指定了像 -en-gb 這樣更精確的變體，而且它與使用者地區最相符，就會優先採用。 西班牙文與法文也使用相同機制。 請注意，繁體中文不會回退到簡體中文。

例如，如果使用者語系是 en-GB，會套用以下優先順序：

• 1. text-en-gb
• 1. text-en
• 1. text

以下目前尚未支援，但預計未來會支援。

動作

你可以在 text 標籤中使用特殊參數。

# 清除訊息框。
[text action="clear"]

# Clear the message box and show it.
[text action="new"]

# Show the message box.
[text action="show"]

# Hide the message box.
[text action="hide"]

NVL Mode

You can enter the NVL mode by setting some config.

[text action="hide"]
[wait time="0.3"] # Wait for the message box to hide.
[config name="game.novel" value="true"]
[config name="msgbox.image" value="system/message/msgbox-nvl.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="0"]
[config name="msgbox.margin.line" value="60"]
[config name="namebox.enable" value="false"]
[config name="choose.box1.idle" value="system/choose/nvl.png"]
[config name="choose.box1.hover" value="system/choose/nvl.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box2.idle" value="system/choose/nvl.png"]
[config name="choose.box2.hover" value="system/choose/nvl.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box3.idle" value="system/choose/nvl.png"]
[config name="choose.box3.hover" value="system/choose/nvl.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="click.move" value="true"]
[text action="clear"]

You can go back to ADV mode by resetting the config.

[text action="hide"]
[wait time="0.3"] # Wait for the message box to hide.
[config name="game.novel" value="false"]
[config name="msgbox.image" value="system/message/msgbox.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="520"]
[config name="msgbox.margin.line" value="40"]
[config name="namebox.enable" value="true"]
[config name="choose.box1.idle" value="system/choose/idle.png"]
[config name="choose.box1.hover" value="system/choose/hover.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box2.idle" value="system/choose/idle.png"]
[config name="choose.box2.hover" value="system/choose/hover.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box3.idle" value="system/choose/idle.png"]
[config name="choose.box3.hover" value="system/choose/hover.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover.anime"]
[config name="click.move" value="false"]

In NVM mode, you can control text messages like this:

# New page.
[text action="clear"]
[text text="Hello, this is NVL mode test."]
[text text="NVL mode has a fullscreen-styled message box."]
[text text="By default, each text tag will do a line feed."]
[text text="To continue a paragraph,"]
[text text="specify the space parameter." space=" "]

# New page.
[text action="clear"]
[text text="Please clear the message box explicitly."]

Voice

If the current language is en-us, a voice file will resolved in the following order:

1. voice-en-us parameter
2. voice/en-us/ + voice parameter
3. voice-en parameter
4. voice/en/ + voice parameter
5. voice parameter

If the current language is ja, a voice file will resolved in the following order:

1. voice-ja parameter
2. voice/ja/ + voice parameter
3. voice parameter

Tips

Automatic Waiting:

• Unlike other tags, the text tag automatically waits for a player's click after the message is fully displayed.
• You don't need to add a [click] tag after every line of dialogue!

Using Variables:

• You can include variables within your text by using the ${variable_name} syntax.
• Example: [text text="Hello, ${player_name}!"] will greet the player using whatever name is stored in that variable.

Line Breaks:

• Check your project's configuration for how long a single line can be.
• If your text is too long, it might overflow the message box, so keep an eye on the length of your text argument!

---

if

條件分支

if 標籤可讓 NovelML 根據特定條件分支。 透過比較變數或值，你可以建立獨特的故事路徑，或對玩家先前的選擇做出反應。

Basic Usage

# 檢查變數是否等於某個值
[if lhs="${points}" op="==" rhs="100"]
    [text text="滿分！你太棒了。"]
[elseif lhs="${points}" op=">=" rhs="80"]
    [text text="做得好！你過關了。"]
[else]
    [text text="下次再接再厲。"]
[endif]

Arguments

Comparison Operators (op)

你可以使用這些運算子來定義兩側的比較方式：

Tips

結束區塊：

• 每個 [if] 區塊都必須以 [endif] 標籤結束。
• 如果忘了加，引擎可能會搞不清楚條件結束在哪裡！

變數語法：

• 當你把變數用在 lhs 時，請一律用 ${} 包起來。
• 例如請使用 lhs="${flag_01}"，不要只寫 lhs="flag_01"。

字串與數字處理：

• Suika3 會把變數值當成字串，但這些運算子仍可讓你進行類似數值比較。
• 只要保持值的一致性即可（例如用 "1" 表示真、"0" 表示假）。

多重分支：

• 你可以在 [if] 與 [endif] 之間使用任意多個 [elseif] 標籤，來檢查多個特定條件。

---

elseif

附加條件分支

elseif 標籤會在 [if] 區塊中指定額外條件。 只有在前面的 [if] 與任何先前的 [elseif] 條件都為假時才會進行評估。

Basic Usage

[if lhs="${rank}" op="==" rhs="A"]
    [text text="太棒了！你是高手。"]
[elseif lhs="${rank}" op="==" rhs="B"]
    [text text="做得好！繼續加油。"]
[elseif lhs="${rank}" op="==" rhs="C"]
    [text text="不錯，但你還可以更好。"]
[else]
    [text text="別放棄！再試一次。"]
[endif]

Arguments

與 [if] 相同。另請參閱 if。

Tips

順序評估：

• 引擎會由上到下檢查條件。
• 只要有一個 [if] 或 [elseif] 條件成立，就會執行其區塊，並略過其餘分支（包含其他 [elseif] 與 [else]）。

位置：

• [elseif] 必須放在 [if] 標籤與 [else] 或 [endif] 標籤之間。
• 你可以根據需要使用任意多個 [elseif] 標籤來涵蓋所有情況！

維護性：

• 如果有很多條件都在檢查同一個變數，使用多個 [elseif] 標籤會比把多個 [if] 區塊互相巢狀更乾淨，也更有效率。

---

else

預設條件分支

else 標籤會定義一個當前面 [if] 或 [elseif] 條件都不成立時要執行的程式區塊。 它會成為分支邏輯中的「預設」路徑。

Basic Usage

[if lhs="${weather}" op="==" rhs="sunny"]
    [text text="It's a beautiful day!"]
[elseif lhs="${weather}" op="==" rhs="rainy"]
    [text text="I should bring an umbrella."]
[else]
    # 如果不是晴天也不是雨天就會執行（例如多雲或下雪）
    [text text="今天的天空看起來很有意思。"]
[endif]

Arguments

這個標籤不接受任何引數。

Tips

最後保底：

• 使用 [else] 來處理你在 [if] 或 [elseif] 中沒有明確涵蓋的情況。
• 這可以確保遊戲永遠有一條可走的有效路徑。

位置：

• [else] 必須放在所有 [elseif] 標籤之後（如果有的話），並且緊接在 [endif] 標籤之前。
• 每個 [if] 區塊只能有一個 [else]。

可選性：

• 你不一定要包含 [else] 區塊。
• 如果沒有任何條件成立，而且也沒有 [else]，引擎就會直接略過全部內容，繼續執行 [endif] 之後的部分。

---

endif

結束條件分支

endif 標籤會標示由 [if] 標籤開始的條件區塊結束。 它會告訴引擎在分支邏輯完成後，回到正常的腳本執行流程。

Basic Usage

[if lhs="${love_points}" op=">=" rhs="50"]
    [text text="She gives you a warm smile."]
[else]
    [text text="She greets you politely."]
[endif]

# 不論上面的結果如何，腳本都會繼續執行到這裡
[text text="這一天仍在繼續..."]

Arguments

這個標籤不接受任何引數。

提示

必要結尾：

• 每一個 [if] 標籤都必須有對應的 [endif]。
• 可以把它們想成一對括號，用來維持故事邏輯的整齊。

位置：

• 請一律把 [endif] 放在條件序列的最後，也就是所有 [elseif] 或 [else] 區塊之後。

巢狀：

• 如果你把一個 [if] 放在另一個 [if] 裡面，請確保每一個都有自己的 [endif]。
• 正確的巢狀結構，是讓複雜劇情旗標不出錯的關鍵！

---

load

載入腳本檔案

load 標籤會把目前腳本切換到另一個 NovelML 檔案。 它主要用來把大型故事整理成多個章節，或在標題畫面與主劇情等不同遊戲部分之間切換。

Basic Usage

# 載入並從 scene02.novel 的開頭開始
[load file="scene02.novel"]

# 載入 scene02.novel，並直接跳到特定標籤
[load file="scene02.novel" label="chapter2_start"]

Arguments

Tips

專案組織：

• 不要把整個遊戲都寫在同一個超大檔案裡，請使用 [load] 將內容拆成好管理的區塊，例如 chapter1.novel、chapter2.novel 等。

立即切換：

• 當引擎碰到 [load] 標籤時，會立刻停止執行目前的 NovelML 檔案，並切換到新檔案。
• 原檔案中 [load] 之後的任何命令都不會被執行。

全域旗標：

• 不用擔心你的變數——即使載入新的腳本檔案，先前用 [set] 標籤設定的值仍會保留！

---

se

播放音效

se 標籤會播放音效（SE）。 音效通常用於敲門、腳步聲或 UI 反饋這類短促聲音，能替場景增加沉浸感與真實感。

Basic Usage

# 播放一次音效
[se file="door_open.ogg"]

# 停止目前所有正在播放的音效
[se file="none"]

Arguments

Tips

必要格式：

• 和 BGM 一樣，Suika3 要求 SE 檔案必須是 Ogg Vorbis 格式。
• 取樣率必須是 44,100Hz，才能確保高音質與相容性。

音效疊加：

• 音效通常可以在 BGM 播放時一併播放。
• 它們會佔用自己的音軌，因此不會中斷音樂。

音量控制：

• 若要調整音效音量而不影響 BGM，請在 [volume] 標籤中使用 track="se"。

環境音用途：

• 雖然 SE 常用於短音效，但你也可以拿來做循環的環境音（例如風聲或雨聲）。
• 載入存檔時，循環中的 SE 會被還原。

---

volume

設定音訊音量

volume 標籤會設定特定音軌的音量。 它很適合用來確保背景音樂不會蓋過重要的音效或角色語音。

Basic Usage

# 將 BGM 音量設為 50%
[volume track="bgm" volume="0.5"]

# 將 SE 音量設為最大
[volume track="se" volume="1.0"]

# 將語音靜音
[volume track="voice" volume="0.0"]

Arguments

Track Types (track)

Suika3 將音訊分為三種主要音軌：

Tips

立即變更：

• 當 time 大於 0 時，音量變更會逐漸發生。
• time="0" 則表示立即變更。

預設音量：

• 建議在遊戲一開始就設定好你偏好的音量，例如在 start 標籤中，讓玩家從頭就有一致的體驗。

---

skip

設定快轉狀態

skip 標籤可以啟用或停用遊戲中的快轉功能。 它很適合用來避免玩家跳過重要的過場，或確保某些場景能以預定節奏體驗。

Basic Usage

# 啟用快轉功能
[skip enable="true"]

# 在關鍵場景中停用快轉功能
[skip enable="false"]

Arguments

Tips

過場控制：

• 快轉功能通常會在啟動畫面與標誌出現前停用。

還原設定：

• 關鍵場景結束後，別忘了設定 [skip enable="true"]。
• 玩家通常會喜歡能夠跳過已看過文字的自由。

系統行為：

• 這個標籤會控制引擎整體的「快轉」狀態。
• 即使玩家按下快轉快捷鍵，只要 enable 設為 false，引擎也會忽略它。

---

config

設定組態值

config 標籤可以直接在標記中修改遊戲系統的設定。 它對於動態調整遊戲 UI 非常重要，例如移動訊息框或即時修改系統層級參數。

Basic Usage

# 變更訊息框位置
[config name="msgbox.x" value="100"]
[config name="msgbox.y" value="200"]

# 更新特定系統設定
[config name="msgbox.font.size" value="24"]

Arguments

Tips

UI 自訂：

• 你可以在特定場景中使用 [config] 重新定位訊息框，營造更具電影感的效果。

動態調整：

• 因為這個標籤可以在腳本中的任何地方呼叫，所以你可以隨著故事推進改變遊戲的「外觀與手感」。
• 例如為「回憶」段落調整 UI。

參數名稱：

• name 引數要特別小心！
• 它必須與你的 Suika3 專案設定中定義的內部設定鍵完全一致。
• 另請參閱 完整設定列表

---

layer

直接操作圖層

layer 標籤可以直接控制特定的圖片與文字圖層。 雖然像 [bg] 和 [ch] 這類標籤更適合一般場景，但 [layer] 能讓你精準地獨立修改任一圖層的位置、縮放與旋轉。

Basic Usage

# 直接將圖片載入中央角色圖層（chc）
[layer name="chc" file="heroine_smile.png"]

# 只調整背景（bg）的位置與透明度
[layer name="bg" x="100" y="100" alpha="128"]

# 旋轉臉部圖層
[layer name="chf" rotate="45.0" center-x="100" center-y="100"]

Arguments

Common Layer Names (name)

Suika3 內建了相當豐富的預定義圖層。

以下是完整圖層清單：

Tips

精準控制：

• 當你在處理沒有專用標籤的自訂效果圖層（例如 eff1 等）時，可以用 [layer] 手動將圖片載入圖層。

即時更新：

• 和 [ch] 或 [bg] 不同，layer 標籤通常會立即更新畫面。
• 如果你想讓這些變化隨時間動畫化，應該改用 [move] 標籤。

圖層階層：

• 請記住圖層是疊放的。
• 例如 chf（臉部角色）永遠會渲染在 chc（中央角色）前方。
• 理解這個「Z 順序」是建立複雜視覺構圖的關鍵。

---

move

圖層動畫

move 標籤會在指定時間內讓特定圖層產生動畫。 它很適合做滑動效果、角色拉近，或旋轉螢幕元素，為場景加入動態感。

Basic Usage

# 在 2.0 秒內將中央角色移到新位置
[move time="2.0" center-x="150" center-y="100"]

# 相對移動：把背景往右推 50 像素
[move time="1.0" bg-x="r50"]

# 在旋轉圖層的同時逐漸淡出
[move time="3.0" face-alpha="0" face-rotate="r360"]

Arguments

共通：

(layer):

(suffix):

Tips

非阻塞動畫（async="true"）：

• 腳本會在開始 [move] 後立刻繼續執行下一個命令。
• 如果你想讓腳本等到動畫結束，可以在後面接一個 [wait] 標籤，並使用相同的 time 值。

相對變換：

• 使用 r 前綴（例如 x="r100"）對重複動作非常有用，例如讓角色「跳動」或「晃動」，而不必計算絕對座標。

視覺修飾：

• 把 scale-x 和 scale-y 與 move 結合，可以在角色臉部上做出「放大」效果，營造戲劇性的特寫。

---

pencil

鉛筆

在圖層上繪製文字。

Basic Usage

[pencil layer="bg" font-size="30" text="Hello, World!"]

Arguments

Supported Layer Name

---

returnmacro

從巨集返回

returnmacro 標籤會立刻結束目前的巨集，並將腳本執行返回到原始 [callmacro] 標籤後的那一行。 它特別適合在 [if] 區塊中，依特定條件提前停止巨集。

Basic Usage

[defmacro name="check_item"]
    [if lhs="${has_key}" op="==" rhs="false"]
        [text text="The door is locked."]
        [returnmacro]
    [endif]

    # 只有在 has_key 為真時才會執行這一段
    [text text="你用鑰匙打開了門！"]
[endmacro]

Arguments

This tag does not take any arguments.

提示

提前退出：

• 在 [if] 區塊中使用 [returnmacro]，可在滿足條件時跳過巨集的其餘命令。
• 這會讓你的巨集更有彈性，也更強大。

隱式返回：

• 你其實不必在每個巨集的最後都放 [returnmacro]。
• 一旦引擎碰到 [endmacro] 標籤，就會自動返回主腳本。

流程控制：

• 請記得，這個標籤只會結束「目前」的巨集。它不會停止整個遊戲，也不會跳到其他標籤，只會把你送回巨集被呼叫的地方。

---

video

播放影片

video 標籤會在畫面上播放影片檔。 它非常適合用於開場動畫、轉場過場，或最適合以動態影片呈現的高衝擊視覺效果。

Basic Usage

# 播放開場影片（不可跳過）
[video file="opening.mp4"]

# 播放一段可由玩家點擊跳過的短過場。
[video file="cutscene01.mp4" skippable="true"]

Arguments

Tips

檔案支援：

• 請確認你的影片檔是 .mp4（H.264 + AAC）格式。
• 如果你要支援 32 位元 Windows，請另外準備 .wmv 檔，再與 .mp4 檔一同提供；此時可省略副檔名，例如 [video file="opening"]。

轉場：

• 影片播放完畢（或被跳過）後，引擎會自動繼續執行腳本中的下一個命令。
• 通常會建議在 [video] 標籤後接一個 [bg] 標籤，確保影片結束後畫面正好符合你的預期。

影片中的音訊：

• 大多數影片檔都會包含自己的音軌。
• 請記得，這個音訊會和正在播放的 [bgm] 一起播放。
• 如果影片本身有聲音，你可能會想在開始播放前先用 [bgm file="none"] 停掉音樂。

---

wait

等待時間

wait 標籤會暫停 NovelML 的執行一段指定時間。 它對於控制視覺轉場節奏、製造戲劇性停頓，或在不需要玩家輸入的情況下精準控制時機都很重要。

Basic Usage

# 在下一個命令前暫停 1.5 秒
[wait time="1.5"]

# 在角色變更之間製造短暫停頓
[ch center="chara01_surprised.png" time="0.5"]
[wait time="1.0"]
[text text="She couldn't believe her eyes."]

Arguments

Tips

非互動停頓：

• 和等待玩家操作的 [click] 不同，[wait] 會在時間到後自動繼續。
• 這很適合用在「自動播放」段落或有時間限制的視覺序列。

與動畫搭配：

• 如果你在 [ch] 或 [bg] 標籤中使用 time 引數，引擎會在動畫播放時立即前往下一個命令。
• 若你想讓腳本停在動畫結束前，或停得更久以營造戲劇效果，可以在動畫後加上 [wait]。

使用者體驗：

• 請小心不要在沒有視覺理由的情況下，把 [wait] 設太久（例如超過 3 秒），不然玩家可能會以為遊戲卡住了！