NextAgentX/game-production-pipeline

端到端遊戲流水線

把一個想法推進到可建置產物 + 發佈方案。每個階段有固定工件、固定路徑、可執行的關卡，不允許跳階段。

以下角色是可選分工：僅在當前環境支援且允許委派時使用；否則由當前助手直接完成。按用戶實際授權和專案階段選擇工作範圍。狀態腳本只檢查文件標題和 TODO，不會自動檢查資源、實際建置或真機驗證；這些需要分別執行並記錄結果。

製作的五階段、G1–G5 里程碑、Sprint 循環和團隊規模裁剪見 references/production-cycle.md。下表七個階段是文件工件子關卡，與製作里程碑不是一一對應。

階段與工件

階段	產出	負責角色
brief	docs/00-brief.md 立項卡	製作人（你自己）
gdd	docs/01-gdd.md	game-narrative-designer
tech	docs/02-tech.md	cocos-engineer、unity-engineer 或 godot-engineer
art	docs/03-art.md + docs/art-style-bible.md + 正式美術 + assets/manifest.json	game-art-director
audio	docs/04-audio.md + 正式音訊	game-audio-designer
qa	docs/05-qa.md	game-qa-engineer
release	docs/06-release.md	game-release-operator

骨架全部在插件的 templates/docs/，複製到專案的 docs/ 再填。骨架裡的 [TODO] 不填完，關卡不放行。

工具（插件自帶，用 python 直接調）

腳本目錄 = 本插件根下的 scripts/。若不確定絕對路徑，先 codex plugin list 找到插件路徑。

用途	命令
初始化狀態	python scripts/omni_state.py init --root . --engine godot --platforms web,android
看階段進度	python scripts/omni_state.py status --root .
校驗單階段	python scripts/omni_state.py check --root . --stage gdd
推進階段（帶關卡）	python scripts/omni_state.py advance --root .
生成佔位美術（僅驗證管線）	python scripts/gen_placeholder_art.py --manifest assets/manifest.json --root .
製作路線圖	複製 templates/docs/07-production-roadmap.md 到 docs/
Sprint 計劃與復盤	複製 templates/docs/08-sprint-review.md，每輪記錄整合版本、測試和回饋
關卡評審	複製 templates/docs/09-milestones.md，記錄 G1–G5 與上線後營運評審
正式圖後處理	python scripts/process_art.py --in raw/x.png --out assets/art/x.png --size 256x64 --key-color "#FFFFFF" --check-nine --nine-slice 24
AI 動畫切幀	python scripts/split_sprite_sheet.py --input raw/sheet.png --cols 4 --rows 2 --fps 12 --loop --out-dir assets/animation/run --backup-dir doc/temp/run-frames
AI 圖片 / GIF	python scripts/gen_ai_image.py --prompt "single game icon" --format png --out assets/art/icon.png --backup-dir doc/temp --dry-run
AI 音效	python scripts/gen_ai_audio.py sfx --prompt "short sci-fi pickup" --duration 1 --out assets/audio/pickup.mp3
AI 音樂	python scripts/gen_ai_audio.py music --prompt "gentle space exploration" --duration 30 --instrumental --out assets/audio/main.mp3
生成 BGM（chiptune）	python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
合成音效	python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav
音訊壓縮核算	python scripts/compress_audio.py --dir assets/audio --check
打包圖集	python scripts/pack_atlas.py --input assets/art/ui --out-sheet assets/art/ui_atlas.png --out-data assets/art/ui_atlas.json
校驗資源清單	python scripts/validate_assets.py --manifest assets/manifest.json --root .
發佈前終檢	python scripts/validate_assets.py --manifest assets/manifest.json --final --strict-license
建置檢查/驗證	python scripts/build_check.py --project . → 加 --run 實際建置

執行順序

0. 落地工程骨架

cp -r <plugin>/templates/godot4/* .        # 或 unity / cocos3
mkdir -p docs assets/art assets/audio doc/temp
cp <plugin>/templates/docs/*.md docs/
cp <plugin>/templates/assets-manifest.json assets/manifest.json
python scripts/omni_state.py init --root . --engine godot --platforms web,android
python scripts/omni_state.py checkpoint --root . --task "立項" --next "寫 brief"

開工前先讀 .omni/active.md（若有）：那是上個會話留下的當前任務與卡點，壓縮或換會話後比對話可靠。

三個模板的成熟度不同，必須如實告訴用戶：

模板	狀態	需要的手動步驟
godot4	可直接執行（已實測導入 + 跑通主場景）	無
unity	可打開，場景需生成	選單 Tools ▸ Omni ▸ Create Main Scene
cocos3	代碼與配置就緒	新建場景 → 掛 GameRoot 到 Canvas → 設起始場景

1. 立項與概念（G1）

問清五件事：核心體驗、平臺優先級、MVP 範圍、變現與合規、現有資產與引擎。填 docs/00-brief.md 與 docs/01-gdd.md，記錄待驗證假設和 Go / No-Go 決議。預算與里程碑按團隊規模估算並標注不確定性。

2. gdd

派 game-narrative-designer。要求：數值給具體值、每條可驗收、單列「對引擎能力的要求」。填完 advance。

3. 預製作與垂直切片（G2）

按引擎派 cocos-engineer、unity-engineer 或 godot-engineer。要求：先給剖析數據再給優化；分平臺建置配置要具體到紋理格式與分包策略。提早實現可玩原型來驗證核心循環。

4. art（正式資源落地）

派 game-art-director 出 docs/03-art.md 與 assets/manifest.json，並按 game-art-production 技能執行：

1. 先做風格聖經 docs/art-style-bible.md：一段固定風格錨定文字 + 色板 + 禁止項
2. 逐資產生：調用當前會話圖像工具或已配置的 AI 圖片 API，按需生成變體；需要透明背景時請求透明輸出，遵守專案圖片備份規則。動畫按 game-animation-production 生成 GIF 或精靈表並檢查切幀。
3. 後處理成規格：

python scripts/process_art.py --in raw/btn_raw.png --out assets/art/ui/ui_btn_primary.png \
  --size 256x64 --mode fit --key-color "#FFFFFF" --key-tolerance 14 \
  --nine-slice 24 --check-nine

4. 登記 manifest：tier: "final" + source + license + commercial_ok + ai_generated
5. 終檢：validate_assets.py --final --strict-license

在 G2 前製作一個完整但範圍小的垂直切片，把程式、策劃、美術和音訊整合到目標引擎；實測畫面品質、資源管線、建置和性能。切片未證明方案可重複、成本可接受前，不根據 demo 估量產排期。插件裏的狀態腳本只檢查文件，不會替你驗證這道關卡。

5. 音訊製作

派 game-audio-designer 出 docs/04-audio.md，並按 game-audio-production 技能選路線：

• 路線 A（AI 生成）：優先使用當前可用的音訊生成工具；或使用 gen_ai_audio.py 接 ElevenLabs API，詳見 game-audio-production。服務的金鑰、權限、計費和授權需事先明確。
• 路線 B（8-bit，離線零成本）：

python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
python scripts/gen_sfx.py --list
python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav

• 必須壓縮：python scripts/compress_audio.py --dir assets/audio --bitrate 96k；無 ffmpeg 時按腳本提示改用引擎導入期壓縮（Godot QOA / Unity Vorbis / Cocos mp3-ogg）
• 必須寫平臺差異：小遊戲需互動後播放、iOS 靜音鍵、Web 自動播放策略

批量製作（G3）與 Sprint 循環

G2 通過後才按垂直切片的實際產能計劃批量製作。填寫 docs/07-production-roadmap.md；每輪從策劃、程式、美術、音訊 backlog 中選一個可驗收目標，用 docs/08-sprint-review.md 記錄範圍、負責人、整合建置、測試、回饋與復盤。週期按團隊能力定，通常 2–4 週，小團隊可以更短。每輪以實際可玩版本評審，失敗或未整合的工作明確標記。

6. 測試與打磨（G4 / G5）

派 game-qa-engineer 出測試計劃。Alpha 後進入 Beta 內容鎖定，預設停止新增功能；如確需加功能，記錄對工期、測試範圍和關卡的影響並重新評審。準備 Gold 前必須真的跑一次建置，並且看一眼畫面：

python scripts/build_check.py --project .                            # 先看命令
python scripts/build_check.py --project . --run --capture g4-beta     # 建置 + 啟動 + 截圖
python scripts/omni_state.py check --root . --stage qa --evidence     # 文件 + 證據一起校驗
python scripts/omni_state.py advance --root . --to release            # 無證據會被攔下

截圖落在 docs/qa/evidence/<名字>/，receipt.json 記錄所覆蓋檔案的 sha256。之後任何一次改動都會讓這份證據顯示過期——過期的截圖不算證據，重新截。

解析通過不等於跑起來，跑起來不等於看得對：文字擠出色塊、面板溢出、元素沒出現，只有看圖才發現。Unity 與 Cocos 沒有內置的無人值守截圖能力，腳本會如實返回 NOT ASSESSED；此時用 --capture-cmd 給命令，或明說「沒看過畫面」，不許當成通過。確實要先推進可用 --no-evidence，但交付時必須寫明沒看過。

建置失敗就把日誌原樣交給對應引擎工程師，不要自己猜。記錄實際測試、平臺相容及候選包證據，邀請負責人評審後再確認 Gold / Release。文件 advance 不會自動通過 Alpha、Beta、Gold 或簽署發佈。

使用 docs/09-milestones.md 記錄 G1–G5 的負責人、證據路徑與決議。Alpha = 功能完整，Beta = 內容鎖定，Gold = 目標平臺發行候選通過評審；這些狀態需要人工基於實際證據確認，不能從文件階段推斷。

7. 發佈與營運

派 game-release-operator 出 docs/06-release.md。所有平臺數字帶「以官方最新為準」與複核入口。

發佈後記錄線上問題、崩潰/業務指標、玩家回饋和熱修復狀態，回寫下一版本 backlog 與路線圖。按需開啟下一輪 Sprint；done 只代表本輪工件完結，不代表停止營運。

交付給用戶時

## 當前階段
state.json 裏的 stage + 關卡狀態

## 已產出工件
docs/ 與 assets/ 清單，標出仍是 placeholder 的數量

## 建置與證據
build_check 的結果：成功 / 失敗 / 未執行；有沒有截圖，截圖覆蓋哪些檔案，是否已過期

## 未完成的真實缺口
明確說清哪些還需要人做

鐵律

1. 不許跳階段：advance 會攔，別繞過；繞過等於交付不可信
2. 文件不是終點：tech 階段之後必須真的產生程式碼與資源檔案，只交文件不算完成
3. 建置必須真跑：qa 階段沒有建置結果就不許進 release；狀態腳本不會自動攔截，需人工核對
4. draft 不算完成：tier: "draft" 的資源不能進發佈；--final 終檢會攔。交付時必須說清還有多少 draft
5. 數字帶出處：包體上限、引擎能力一律標版本與複核方式
6. 每輪 Sprint 交付可玩建置：任務完成數不能代替建置、測試和評審
7. 關卡以評審證據為準：omni_state.py 只檢查文件標題及 TODO，不能自動驗證玩法、建置、設備或發行審批
8. 產物優先於敘述：派出去的角色聲稱寫了檔案，就校驗那個路徑存在。不存在就是 PHASE FAILED——不推進、不總結為完成。一段流暢的「我將要…」不是證據，磁碟上的檔案才是
9. qa 之後必須有截圖：沒有 docs/qa/evidence/ 裏的可⽤截圖，不許進 release；advance 會攔。NOT ASSESSED 不是通過

這套流水線做不到的

• 3D 模型與骨骼動畫：本鏈路側重 2D；AI 逐幀結果需要檢查並可能需要修圖。
• AI 音樂與音效：需要當前可用的生成工具或具備權限的外部服務；程式化合成不等同於 AI 生成。
• 商用字體：只能用 OFL 開源字體，商用字體需用戶自購授權
• 替你簽名、上架、過審：只能給清單與排期，不能替你點後臺
• 真機相容驗證：需要真實裝置
• 保證程式碼無 bug：建置通過 ≠ 功能正確，功能正確 ≠ 好玩