建立第一個專案

安裝前的準備

先安裝含 npm 的 Node.js。這個版本的 CI 使用 24.14.0，另外有 Windows 搭配 24.2.0 的測試紀錄。在終端機確認兩個命令都能執行：

node --version
npm --version

CLI 套件需要包含你所在平台的原生 runtime。一般製作遊戲不必安裝 C++、CMake 或 vcpkg，也不必下載引擎原始碼。

0.2.0 套件狀態：本文依據的版本仍以私人 registry 測試。先確認維護者提供的版本與 registry；公開 npm 找不到套件時，請看發行紀錄。

在準備存放遊戲的資料夾執行：

npm install -g @prismatix/cli
prismatix create my-game
prismatix dev my-game

create 會建立 my-game，放入中文故事、角色與背景、標題畫面和預設對話介面，也會安裝專案使用的 CLI／SDK 並產生 package-lock.json。不需要再執行 npm init 或另外安裝 authoring SDK。

預覽開啟後，按 Start 進入故事。先試試兩個選項，確認能走到不同段落。

開啟 my-game/Story/main.pxstory，找到 [id main.welcome]。保留 ID，把下面的台詞改成：

[id main.welcome]
@guide
歡迎來到我寫的第一個故事！

存檔後，CLI 會重新編譯並替換預覽。目前每次更新都會重新開始場景，不會接著停在剛才的台詞。

有語法錯誤時，終端機會顯示檔名、行號與原因，舊預覽則繼續保留。修好後再存檔即可，不用重新執行 dev；第一次啟動就出錯時也一樣。

結束試玩請按 Ctrl+C。.prismatix/dev/ 留下的檔案是開發暫存，不用提交到 Git。

建立另一個專案時，可以直接指定選項：

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

--name 是顯示名稱，--id 是專案識別碼，--width 和 --height 是畫面寬高，接受 1–16384 的整數。路徑含空白時要加引號。

--locale 只設定語言標籤，範本台詞仍是中文；英文故事的設定方式見多語系。

目的地必須不存在或是空資料夾。建立專案時需要連上 registry；安裝成功後，CLI 才會把準備好的專案移到目的地。

prismatix validate my-game
prismatix build my-game

validate 檢查設定與故事。build 則產生包含 Player 和遊戲內容的發行資料夾，預設位置是 my-game/dist/<project-id>/。詳細流程見打包遊戲。

平常也可以在專案內啟動：

cd my-game
npm exec -- prismatix dev .

已安裝 pnpm 的環境可用 pnpm exec prismatix dev .。不過 create 目前仍透過 npm 安裝依賴，所以 npm 需要保留。既有專案會使用自己的固定 CLI 版本，記得一起保存 package.json 和 lockfile。

Preview 的 Save/Load 只保留這次開啟期間的進度，重建或關閉後就會清除。測試「關閉遊戲、重新開啟、讀取進度」時，請使用打包後的 Player。

接下來看專案結構，認識剛才建立的檔案。

實作參考：快速開始、create、CLI。