專案結構與設定

故事、素材、UI 和 Extension 放在哪裡，以及 prismatix.json 的常用欄位。

檔案放在哪裡？

下面列出範本檔案，以及後續教學會加入的內容：

my-game/
  prismatix.json              專案設定
  package.json               工具版本
  package-lock.json          依賴版本鎖定
  Story/main.pxstory          起始故事
  Characters/guide.pxcharacter
  Assets/window.png
  Assets/guide.png
  Content/UI/Title.pxui       標題畫面
  Content/Fonts/              字型與授權
  Content/Localization/zh-TW.json
  Content/Extensions/        後續新增的擴充
  Content/game.pxgame         後續指定的遊戲資料
  .prismatix/                編譯與預覽暫存
  dist/                      打包結果

主要編輯 Story、Characters、Assets 和 Content。.prismatix/ 會在建置時重建，修改故事請回到原始 .pxstory 檔。

prismatix.json

prismatix.json 是平常編輯的設定檔。CLI 會補上未指定的預設值，交給 SDK 編譯。下面示範名稱、語言和解析度；把這些欄位合併到現有設定，保留素材及角色清單：

{
  "id": "first-light",
  "name": "First Light",
  "defaultLocale": "zh-TW",
  "resolution": {"width": 1280, "height": 720}
}

你也可能看到 project.pxproject。這是欄位完整的專案格式，遵循 PrismatiXProject schema revision 2，包含故事入口、UI、版本、索引和擴充清單。剛開始製作遊戲時，使用 prismatix.json 即可。

CLI 收到資料夾路徑時，依序尋找 prismatix.json、project.pxproject，最後才嘗試 Story/main.pxstory。若同時存在兩份設定，會優先載入 prismatix.json；也可以直接把設定檔路徑傳給 CLI。

常用欄位

欄位	用途
`id`、`name`	專案識別碼與顯示名稱
`resolution`	遊戲的邏輯畫面寬高
`defaultLocale`、`supportedLocales`	預設語言與支援語言
`assets`、`characters`	素材清單與角色來源
`gameCatalog`	遊戲變數、畫廊與解鎖資料
`storyIndex`	章節、場景和各語言的故事檔
`extensions`	要載入的 `.pxextension`
`uiEntryPoints`、`uiComponents`	畫面路由與共用 UI 元件
`graphicsTier`、`effects`	圖形功能層級與自訂效果
`version`、`contentVersion`、`saveVersion`、`saveMigrations`	發行版本與存檔更新規則

後續章節會逐一新增需要的設定。已有陣列就追加項目，例如在 extensions 加入另一個擴充，或在 assets 加入新背景。

路徑、別名與 ID

內容路徑相對於專案根目錄，使用 /，例如 Assets/window.png。不能使用電腦上的絕對路徑、../ 或網址。Extension 的 entry、modules 則相對於 manifest 所在資料夾，詳見Extension 教學。

幾種識別方式的用途不同：素材 UUID 對應一個資源；guide 是故事裡使用的角色別名；[id main.welcome] 對應一個故事操作。新增內容時才配置新 ID，修改既有內容時保留原 ID。已發行作品還需要檢查存檔相容性。

交給 Git 管理

提交故事、設定、素材、授權、擴充原始碼、建置設定，以及 package.json 和 lockfile。node_modules/、預覽暫存和玩家存檔則留在本機。

另一台電腦應依 lockfile 安裝相同工具版本。升級 CLI 或 SDK 時，先在分支測試故事、打包結果與舊存檔。

接下來看撰寫第一個故事。

實作參考：專案 schema、範本設定、載入流程。