Story 指令表
查閱 23 個內建指令的寫法、參數和單位。
這份表列出 0.2.0 作者編譯器接受的 .pxstory 語法。JavaScript API 與 C++ VM 的內部命令不是這份語法的一部分。
基本寫法
| 寫法 | 用途 |
|---|---|
; comment | 整行註解 |
*start | 宣告標籤 |
@guide | 指定接下來說話的角色 |
| 普通文字行 | 台詞；沒有說話者時是旁白 |
| 空白行 | 結束目前說話者設定 |
[command ...] | 執行指令，一行一個 |
使用 UTF-8、不含 BOM 的檔案，目前單檔上限為 16 MiB。標籤、別名和明確 ID 以英文字母或數字開頭，後續可使用英數、.、_、-。
參數使用 name=value，含空白的字串加引號，布林值寫成 true／false。Extension 的結構化參數使用 JSON：
[tutorial.note message="A message with spaces"]
; 語法示例：使用前先宣告相符的 Extension 指令
[demo.position point=[20,40] enabled=true]Story 文字不會直接執行 JavaScript，也沒有在此定義 ${score} 等通用插值語法。
流程與等待
| 指令 | 範例 | 說明 |
|---|---|---|
id | [id main.line01] | 固定下一個操作的 ID，也接受 value=... |
choice | [choice text="Go" goto=next] | 顯示選項，指向同檔標籤 |
choice.wait | [choice.wait] | 放在連續選項後，目前不產生獨立 IR 操作 |
jump | [jump target=next] | 直接跳到同檔標籤 |
call | [call target=common] | 呼叫共用段落 |
return | [return] | 返回 call 之後的位置 |
end | [end] | 結束故事 |
wait | [wait duration=500] | 等待 500 毫秒 |
wait 也接受位置參數，以及 500ms、0.5s。沒有單位時以毫秒計算，因此 [wait 0.5] 不是半秒。值必須有限且非負。
選項需要 text 和有效目標。同一組選項連續排列，標籤只標記位置，不會自動阻止流程往下執行。
背景與角色
| 指令 | 範例 | 參數 |
|---|---|---|
bg | [bg Assets/window.png] | 資源位置參數或 asset |
show | [show guide expression=smile position=left] | 角色位置參數或 character，另有 expression、position、x、y、scale |
move | [move guide x=80 duration=400 wait=true] | 角色、position、x、y、scale、duration、ease、wait |
hide | [hide guide] | 角色位置參數或 character |
位置可用 left、center、right，或 1、2、3，也接受 centre。角色和表情須先登記。
move 至少指定 position、x、y、scale 的其中一項。duration 是毫秒，原生補間預設為 600 毫秒及 outCubic。wait=true 會等待移動完成；需要平滑移動時指定 x／y／scale，單純切換位置 slot 不一定會插值。
變數與條件
| 指令 | 範例 | 說明 |
|---|---|---|
set | [set score=1] | 設定一個值，也接受 name=score value=1 |
if | [if score >= 1] | 判斷條件 |
else | [else] | 條件不成立時的分支，可省略 |
endif | [endif] | 結束對應的 if |
變數先在 game catalog 宣告型別。set 不計算右側算式，不能用 [set score=score+1] 加分；計算使用 Extension API。
條件支援括號、比較、算術和布林運算，完整說明見變數與條件。
聲音與畫面
| 指令 | 範例 | 參數 |
|---|---|---|
voice | [voice Assets/greeting.wav] | 語音資源 |
bgm | [bgm Assets/evening.wav] | 音樂資源 |
se | [se Assets/bell.wav] | 音效資源 |
timeline | [timeline Animations/greeting.pxtimeline] | 資源位置參數或 timeline |
ui | [ui route=save operation=push] | 路由和操作，操作預設 push |
effect | [effect value=PRESET] | 單一效果預設名稱 |
camera | [camera value=PRESET] | 單一鏡頭預設名稱 |
三個音訊指令只傳入資源；音量與淡入淡出使用 ctx.audio。Timeline 的完整播放控制也在 Runtime API。
PRESET 是佔位名稱，不是內附效果。需要設定 x／y／zoom 或 shader 參數時，使用 ctx.stage.camera、screenEffect 或 .pxeffect，見動畫與特效。
部分內建指令會讀入卻忽略多餘參數，因此沒有語法錯誤不表示參數已生效；請依表中列出的欄位使用。
Extension 與錯誤碼
其他名稱必須在專案登記的 .pxextension 中宣告，並由 JavaScript 實作。[video]、[anim]、[nvl] 不在這份內建指令表中。
PXSTORY1199 表示未知指令。PXSTORY1201–1206 處理 Extension 參數的必填、型別、列舉、範圍和未知欄位；PXSTORY1210–1213 處理 ID 格式、重複和沒有後續操作等問題。