CLI 指令表

English

以下對應本教學使用的 0.2.0 版本。專案會使用自己固定的本機 CLI；升級後可用 prismatix <command> --help 核對選項。

日常指令

prismatix create my-game
prismatix dev my-game
prismatix validate my-game
prismatix build my-game

在專案內，把 my-game 換成 .，也可使用 npm exec -- prismatix dev . 或 pnpm exec prismatix dev .。create 安裝依賴時仍使用 npm。

參數寫法

每個命令最多接受一個位置參數，通常是專案或存檔路徑。路徑含空白時加引號。

有值的選項可寫 --name value 或 --name=value；--once 這類旗標不接 true。未知、重複或不合法的選項會回報錯誤。

--json 開啟機器可讀輸出。診斷以 NDJSON 寫入 stderr，結果另有 stdout；自動化需分開處理，並檢查結束代碼。

create

prismatix create "my game" --name "First Light" --id first-light --locale zh-TW --width 1280 --height 720

目的地必須不存在或是空資料夾。更新既有遊戲不使用這個命令。

dev

一般執行 prismatix dev my-game 即可。進階選項有 --runtime、--preview-host、--debounce，旗標有 --once、--smoke。

--once 完成一次套用與播放確認後結束，適合自動化檢查；--smoke 用於基本啟動測試。runtime 和 preview-host 的指定選項供維護者診斷套件使用，一般情況使用 CLI 內附的版本。

validate

prismatix validate my-game --json

載入設定、依賴和故事後進行驗證與編譯，沒有其他專屬選項。畫面、媒體和 callback 的實際執行仍須試玩。

build、pack、run

共用選項是 --output、--runtime、--packager、--player、--compression，以及 --encrypt 旗標。壓縮值可選 none、fast、balanced、maximum。

build 另有 --artifact-only、--distribution，兩者不可同時使用。一般 build 已會建立 Player 發行資料夾：

prismatix build my-game --output "release/First Light"
prismatix build my-game --artifact-only --output my-game/.prismatix/artifact
prismatix pack my-game --compression balanced
prismatix run my-game

依需求選擇其中一種模式，詳細差異見打包遊戲。

ids

管理故事的固定 ID。選項有 --document-id、--prefix、--backup，旗標有 --write、--check：

prismatix ids --help
prismatix ids my-game/Story/main.pxstory --check

先檢查結果，再決定是否以 --write 寫入。既有 ID 與存檔定位有關，請保留備份並檢查差異，詳見故事 ID。

migrate

處理作者文件的格式遷移。先用 prismatix migrate --help 確認來源類型，再備份、檢查報告與差異，最後寫入及試玩。

值選項包括 --report、--backup、--entry-story、--entry-ui、--supported-locales、--save-version、--id、--name、--version、--content-version、--default-locale、--story-index、--game-catalog；寫入旗標是 --write。

這個工具不同於 Player 的 saveMigrations，也不會自動改寫所有 Extension 程式。

inspect-save

prismatix inspect-save --help

檢查指定存檔，可使用 --package、--secret、--runtime、--player。提供與存檔相符的套件及執行環境；分享診斷時移除密鑰和私人路徑。

自動化紀錄

測試時記錄套件版本、Node 版本、作業系統、命令、結束代碼，以及錯誤來源行號。編譯驗證、套件安裝、原生啟動和實際試玩是不同測試，報告中分別記錄結果會比較容易追查。

實作參考：CLI 選項與實作、使用流程。