疑難排解

先看終端機的第一個具體錯誤，確認檔名與行號，再逐項修改。一次改一個問題，比同時重裝工具和重寫設定更容易找到原因。

安裝與啟動

問題	檢查項目
npm 回報 E404	確認該版本是否已發布，以及是否需要維護者提供的 registry
找不到 prismatix	確認全域安裝成功及 PATH 設定；專案內也可用 npm exec
無法建立專案	目的地須不存在或為空資料夾，且可寫入、不是符號連結
找不到 native runtime	檢查 CLI 套件是否包含相符平台和版本的 runtime
本機 CLI 版本不符	依 package.json 和 lockfile 還原專案工具
路徑被拆成多個參數	對含空白的完整路徑加引號

初次建立需要 registry 連線。若建立過程中斷留下鎖定目錄，先確認沒有仍在執行的建立程序，再依錯誤訊息處理。

prismatix validate my-game
prismatix validate my-game --json

PXCLI1001 表示載入失敗，先檢查 JSON、使用中的設定檔和引用路徑。PXCLI1101 是建置失敗的總結，詳細原因通常在更前面的訊息。

PXCLIJSX1002 與 TSX 評估有關，檢查 import、default export 和 UI 元件型別。

PXSTORY1199 表示未知指令，常見原因是拼字或大小寫錯誤、未登記 Extension，或使用了本版本不支援的語法。PXSTORY1210–1213 則與 ID 格式、重複或後面沒有操作有關。

台詞意外變成旁白時，檢查 @guide 後是否有空白行；兩條分支連續播放時，檢查第一條分支末尾是否少了 jump 或 end。

編譯出錯時，CLI 會保留上一個可玩的預覽。修好終端機指出的檔案並存檔，再觀察更新。

成功更新後場景重新開始，是目前的預覽方式。第一次啟動就出錯時，也可以直接修改後存檔；結束開發時用 Ctrl+C 關閉，避免同時啟動多個預覽程序。

依序核對檔案路徑、大小寫、素材 ID，以及角色表情的 assetId。媒體檔存在卻不能播放時，再檢查編碼和裝置；文字缺字則檢查 fontChain 與字型。

Story 的音訊指令只傳入資源，額外寫上 volume 或 fade 不會套用完整音訊控制。需要調整時，使用 ctx.audio。

WASM、基本圖形層級和原生 Player 的功能不同。影片或 GPU 效果無法使用時，先看平台支援和能力診斷。

核對 project.extensions、描述檔的 entry／modules、指令 ID、參數和 capabilities。Story 只能呼叫 commands，UI 使用 actions。

使用 TypeScript 時，確認已重新 bundle。輸出的 JavaScript 不應留下未解析的 @prismatix/runtime import、node:fs、DOM 或 Node.js 的 require。驗證成功後，仍要讓劇情實際走到 callback，檢查執行結果。

先確認使用的是 Player，不是已重建或關閉的 Preview 暫存欄位。再檢查內容版本、存檔版本、故事定位、資料型別和 state provider 版本，詳見存檔與更新。

更新時先用測試存檔副本驗證，保留舊版 Player 以便比較。

若輸出資料夾多了存檔、log 或手動修改的檔案，CLI 可能拒絕覆寫。改用新的輸出目錄，原資料保留。移動遊戲時，要一起帶走完整發行資料夾，而不只是 Player 執行檔。

附上引擎或套件版本、作業系統與 CPU 架構、Node／npm 版本、重現步驟，以及第一個完整錯誤訊息和行號。也請說明問題發生在 validate、原生 Preview、WASM Preview 或 Player。

畫面問題附上截圖與操作步驟；存檔問題使用測試資料，標示新舊版本。最小範例中移除密鑰、私人路徑、玩家資料及無法分享的素材。

文件和網站建置檢查不會執行原生引擎；實際遊戲的畫面、聲音與存檔結果，仍需透過對應平台試玩確認。