系統定位
VibeGame 是由 Agent 團隊執行開發與驗收的遊戲開發框架。使用者提供需求，團隊依各自角色完成工作。
| 元件 | 用途 |
|---|---|
| Claude Code 與 Codex | 執行開發 Agent |
| Python CLI | 初始化專案及管理開發環境 |
| Phaser 3 | 執行網頁遊戲 |
主要產出是遊戲專案目錄，包含：
project.json。場景與物件 JSON。
JavaScript。
素材清單。
工作紀錄。
適用於 2D 網頁遊戲原型，以及需要持續修改玩法與素材的專案。
需求與協調
- 使用者
- orchestrator
- designer
- PRD 與 GDD
任務執行
- architect
- programmer
- auditor
- artist
執行與驗收
- Phaser 引擎
- player
- reviewer
- 狀態與畫面證據
靜態檢查、實際遊玩及最終審查分別執行。
以下能力仍列在 README 未完成的 roadmap：
Godot。
Unity。
端到端 3D 製作。
以下操作以目前公開的 Phaser 實作為範圍。
安裝與驗證
- 未完成：
Python 3.12 或更新版本。
- 未完成：
已安裝
uv與tmux。 - 未完成：
已安裝、登入並可使用 Claude Code 或 Codex。
- 未完成：
選用角色的 CLI 與模型均可在目前帳號使用。
- 未完成：
完整美術與視覺驗證流程所需的圖片生成及 VLM API 已設定。
標準安裝不需要 Node.js 或 npm。保留原始碼 checkout；安裝採 editable 模式，CLI 會從該目錄讀取：
引擎。
範本。
Dashboard。
git clone https://github.com/tettethu/VibeGame
cd VibeGame
./setup.sh在來源 checkout 旁建立新的遊戲目錄，再啟動團隊：
cd ..
mkdir my-game
cd my-game
vibegame init
vibegame startinit 預設會初始化或使用 Git，並建立框架基線 commit。已有工作內容時改用 vibegame init --no-commit 檢查變更，再自行建立供 worktree 使用的基線。
Codex hooks
若有角色使用 Codex，安裝後執行：
vibegame setup codex-hooks接著開啟 Codex，輸入 /hooks，信任新增的 VibeGame hooks。此指令會寫入使用者的 ~/.codex/hooks.json；安裝與信任缺少任一步，Agent 可能無法登記到 Dashboard，啟動程序也可能持續等待。
首次使用 Claude Code 的略過權限模式時，依 README 在一般終端機完成同意畫面，再啟動受管理的 session。先確認下方權限限制，勿把受管理 session 當成隔離環境。
Provider 與角色設定
| 位置 | 用途 | 操作限制 |
|---|---|---|
src/.vibegame/settings.json | 新專案的角色 CLI、模型及可選 effort | 修改 agents 時保留 hooks |
src/.vibegame/team/models.json | CLI 模型清單、參數對應與權限預設 | 名稱須同時符合框架清單及實際 provider |
src/.vibegame/defaults.json | 新專案預設語言 | 查核版本的預設為 en |
checkout 根目錄的 .env | 圖片、VLM 與可選第三方服務 | 不提交到 Git，也不放入前端程式 |
遊戲的 .vibegame/settings.json | 已初始化專案的角色設定 | 與來源範本分開檢查 |
隨附的角色設定混用 Claude Code 與 Codex。只安裝其中一種工具時，先把需要 CLI 的角色改到可用的 harness 與模型，不要直接沿用全部預設值。
| 服務 | 必填設定 | 可選設定 |
|---|---|---|
| 圖片生成 | IMAGE_PROVIDER、IMAGE_API_KEY、IMAGE_MODEL | IMAGE_BASE_URL |
| VLM | VLM_BASE_URL、VLM_API_KEY、VLM_MODEL | 無 |
VLM 的 base URL 停在 /v1，不包含 /chat/completions。
VLM 沒有內建的預設模型 ID。從服務商確認模型名稱與視覺輸入能力後填入；單憑 API 相容格式，不能判定模型能檢查遊戲畫面。
核心能力
初始化
vibegame init
建立遊戲專案
複製框架、角色與引擎，建立場景、輸入及素材目錄；預設包含 Git commit。
團隊啟動
vibegame start
Dashboard 與 Agent session
啟動協調與協作環境；初始訊息可搭配 --project 指定遊戲目錄。
目標執行
/vibegame-build
端到端遊戲製作
在 Agent 對話中提交遊戲目標；此為技能指令，不是在 shell 直接執行的程式。
靜態檢查
vibegame check
專案資料驗證
檢查專案、場景、素材、腳本及輸入設定；通過不代表實際玩法已驗收。
執行與觀察
vibegame run --port auto
可操作的遊戲 runtime
啟動遊戲伺服器與受控瀏覽器；可再由 play 介面查詢狀態及取得畫面。
結束執行
vibegame close
關閉遊戲 runtime
關閉追蹤中的 runtime；Dashboard 與 Agent 團隊屬於另一組程序。
從其他目錄繼續工作時，start 的專案路徑使用 --project。位置參數是送給 orchestrator 的訊息：
vibegame start --project ./my-game "Continue polishing the boss fight"Dashboard 提供以下分頁：
Chat。
Assets。
Objects。
Play。
Play 的靜態預覽與 run 啟動的受控 runtime 不同；需要狀態檢查或可重複輸入測試時，使用後者。
來源的技能目錄包含以下工作流程；它們與 shell 裡的 CLI 子指令分開：
| 技能名稱 | 用途 | 啟動邊界 |
|---|---|---|
vibegame-start | 檢查團隊與載入工作脈絡 | 針對已啟動的團隊 |
vibegame-build | 規劃、執行與驗收遊戲目標 | 依流程確認目標與任務計畫 |
vibegame-edit | 修改既有遊戲的風格、類型或規則 | 先建立基線，再進入 build 流程 |
self-evolve | 提升可重用的專案資源 | 使用者明確要求並核准候選項目 |
artist-self-evolve | 整理可重用的美術製作方法 | 由 lead 指派，不自行背景啟動 |
Agent 分工與任務交接
| 角色 | 主要責任 | 交付或限制 |
|---|---|---|
orchestrator | 釐清需求、維護 PRD、拆分任務與驗收 | 決定任務邊界及完成條件 |
designer | 遊戲設計與 GDD | 不負責實作程式 |
architect | 調查程式與規範、建立技術計畫 | 產出 plan.md 與任務脈絡 |
programmer | 依計畫實作 | 交接前執行程式檢查 |
auditor | 程式與規範的靜態審查 | 不執行遊戲，可做規範允許的修正 |
player | 實際輸入、行為與畫面驗證 | 需要能處理視覺資訊的能力 |
artist | 生成、處理及登記美術素材 | 完成素材後更新 manifest |
reviewer | 目標完成後的功能、畫面與可玩性檢查 | 與單一任務的 auditor 分開 |
角色依任務啟動，無須每次同時執行全部角色。一般任務交接順序如下：
PRD。
技術計畫。
實作。
靜態審查。
執行驗證。
orchestrator 驗收。
任務資料位於 .vibegame/tasks/<name>/，常見文件如下：
prd.md。plan.md。context.json。只追加內容的
log.md。
驗收條件分開記錄：
檔案是否有效。
畫面是否可辨識。
操作是否符合規格。
reviewer 可拒絕交付。多階段審查需以實際輸入與證據為基礎；角色名稱本身不構成正確性保證。
引擎資料與美術資產
| 路徑 | 內容 | 修改方式 |
|---|---|---|
project.json | 畫布、物理、起始場景、manifest 與輸入設定 | 保留引擎啟動入口及必要欄位 |
scenes/*.scene.json | 初始 node tree | 宣告視覺、碰撞、腳本與子物件 |
entities/*.node.json | 可重複實例化的物件 | 共用角色或障礙定義 |
scripts/*.js | 遊戲行為與一般 JavaScript 邏輯 | 有生命週期需求時使用 Node |
assets/**/manifest.json | 素材 key、檔案及 atlas frame | 由 project.json.manifests 列入載入範圍 |
config/input-map.json | 按鍵到遊戲 action 的對應 | 讓輸入規則與實作分開 |
先確定角色與碰撞在遊戲世界中的尺寸，再調整美術顯示比例。以下資料須分開設定：
圖片解析度。
顯示大小。
collider 尺寸。
更換外觀後要重新檢查碰撞。可先用 placeholder_image 或 placeholder_atlas 驗證玩法，再替換為登記好的素材。
圖片生成後，確認以下項目：
裁切。
pivot。
atlas frame。
動畫。
artist 的標準 sprite 流程如下：
生成含有單一動作所有 frame 的圖片。
去背。
切割。
串接。
登記 manifest。
這個流程不要求每個動作都先生成影片。使用者已指定的素材包則先檢查及處理，再登記。
引擎的原始 index.html 透過 CDN 載入 Phaser 3.80.1。標準開發沒有前端打包步驟，但部署與離線使用仍需確認這個外部資源可載入。
操作原則
先驗收最小玩法
先指定單一場景、操作、失敗與重開條件；用替代素材完成行為驗證，再安排美術替換。
分開靜態檢查與遊玩證據
check 檢查專案資料；player 以實際輸入、狀態與畫面驗證玩法。兩者不能互相替代。
控制生成與測試成本
一般專案 check 不呼叫付費 API；--api 會增加 VLM 與圖片生成 smoke checks。先檢查本機資料，再決定是否執行付費測試。
保留來源 checkout
CLI 依賴原始碼目錄；更新該目錄後，既有遊戲仍需檢查自身的框架與引擎版本。
圖片生成會把提示與影像送至外部服務。部分圖片處理 Agent 流程也會使用 VLM，包括：
去背。
裁切。
正規化。
開始前分別訂定下列用量的額度與停止條件：
CLI 推理。
圖片生成。
VLM 評估。
可選影片生成。
圖片生成紀錄位於 .vibegame/logs/imagegen.jsonl，包含：
完整 prompt。
參考圖片路徑。
模型。
輸出位置。
錯誤。
回報問題時提供來源版本及必要錯誤訊息；分享日誌前移除私密資料。
操作範例
在前面的 my-game 專案啟動 orchestrator 後，送出以下建議的驗收規格。本次未執行範例的生成或遊玩測試。
/vibegame-build Build a single-screen 2D dodge game. Use arrow keys to move, avoid falling hazards, and survive for 30 seconds to win. A hit ends the round. Add a visible timer, clear win and lose states, and a restart button. Use placeholder assets first. Verify movement, collisions, the timer, and restart before replacing art. Keep API keys out of runtime files.把工作拆成以下項目，分別寫出可觀察結果：
輸入與移動。
障礙與碰撞。
計時與結束狀態。
重新開始。
素材替換。
避免把「遊戲可玩」當成唯一完成標準。
團隊交付後，在遊戲目錄執行：
vibegame check
vibegame run --port auto保留關鍵狀態與畫面證據，再執行 vibegame close。下列檢查通過後，再進入美術替換與回歸檢查：
遊戲勝負。
介面可讀性。
重開狀態。
限制與注意事項
| 症狀或限制 | 檢查與處理 |
|---|---|
| Codex 有啟動，但 Dashboard 空白或等待 session | 完成 vibegame setup codex-hooks 與 Codex 的 /hooks 信任步驟 |
| 只安裝一種 CLI，部分角色啟動失敗 | 檢查每個角色的 cli 與 model，不要沿用需要另一種工具的設定 |
| 既有專案有自己的 staging 內容 | init 預設會重建 staging 並提交；先保存工作，使用 --no-commit 後人工檢查 |
| 更新後 runtime 報缺少 clock 支援 | 先保存自訂引擎變更，再更新遊戲內的框架與引擎；不能只更新 CLI checkout |
check 通過，遊戲仍有操作或視覺問題 | 補 player 的執行階段測試；Dashboard Play 預覽不等同受控 runtime 驗證 |
| 圖片或視覺測試失敗 | 檢查 provider、base URL、模型能力、憑證與額度；check --api 會呼叫付費服務 |
| 想改用 Godot、Unity 或 3D 流程 | 目前 README 將這些能力列為 roadmap；不要以現行 Phaser 手冊推定可用 |
start 在使用 Claude 角色時，會處理使用者 ~/.claude.json 的專案信任設定。全域 hooks、信任登記與專案內的設定不同；導入前檢查使用者層級檔案的變更。
套件採 Apache-2.0。README 的商業部署通知是作者請求，並明載：
不要求核准。
不收授權費。
不修改 Apache-2.0 權利。
以下條款仍需各自確認：
圖片模型。
外部服務。
使用素材。
後續操作
既有遊戲更新
在 VibeGame 來源 checkout 拉取更新後，到遊戲目錄執行 vibegame init --no-commit。檢查差異，再決定是否選擇 Replace entire engine；整份引擎替換會移除遊戲內的引擎修改，且需要另外確認。
遊戲發佈
vibegame release --dry-run
vibegame releaserelease 預設建立或更新本機的 release 分支；它不會自動 push 或部署。遊戲使用 entities/、modules/ 或其他額外 runtime 目錄時，在 project.json.releaseExtraRoots 明確列入；素材仍由 manifest 選取。
在發佈分支驗證：
實際 HTTP 路徑。
所有場景。
動態物件。
使用自訂 backend 的遊戲，還要部署該服務並注入正確的 API 位址；工具的本機 runtime 不會替遊戲提供正式模型 backend。
共用資源提升
vibegame evolve 把完成並經使用者核准的共用資源複製回已安裝 CLI 的來源 checkout。可提升的資源類型如下：
skeleton。
module。
contract。
先用 --dry-run 檢查複製計畫。目的地已存在時會停止，不會覆寫或合併；下列操作也不會自動執行：
修改索引。
commit。
push。
本手冊查核修訂為 fc9cbbe1f82c217b6d1946c00f51d309e584d826，套件版本 0.1.0。操作介面與限制依此修訂的官方資料查核；具體來源見參考連結。
本次未執行：
付費圖片生成。
VLM 呼叫。
完整 Agent 遊戲製作。