huayuehua15-netizen/unity-gameplay-dev

Unity 玩法開發技能（第一人稱 / Unity 6 / URP）

路徑約定（先讀這一行）：本檔案裡所有 scripts/、references/、assets/ 都是相對於本 SKILL.md 所在目錄。 執行腳本前先定位該目錄。不同宿主安裝位置不同：Claude Code 外掛在外掛目錄下；Cursor/Codex 由 install.ps1 裝到 <專案>/skills/game-dev/<技能名>/。不確定時先用 glob 找到本 SKILL.md 的絕對路徑，再用絕對路徑呼叫腳本。 直接在專案根目錄下 python scripts/xxx.py 會 file-not-found。

概述

本技能把 GDD 規格和 3D 資產變成可玩的遊戲功能：用 MCP 在 Unity 裡建立/修改腳本、掛元件、配置動畫與 UI、進入 Play 模式驗證、執行測試、打包。預設技術棧：Unity 6（6000.x LTS，相容 6000.3）、URP、UGUI、新 Input System、Cinemachine 3（可選）、單機、無連線。

邊界

• 做：玩法邏輯、控制器、互動、UI、背包/對話/存檔、AI、音訊、測試、建置與效能定位。
• 不做：3D 資產製作/匯入/材質（交給 unity-blender-mcp 技能）；多人連線（Netcode）；Shader 手寫（僅給特效選型建議）。
• 目標專案用第一人稱；第三人稱/俯視角沿用同一套架構（狀態機、輸入、互動、UI 不變），僅控制器與相機分支不同，見 references/02。
• 2D 專案：架構層（狀態機/事件匯流排/存檔/背包/UI 棧）照用，但角色控制、物理、導覽、效能預算必須換， 見 references/11-2d-gameplay.md。不要拿 3D 的 CharacterController + NavMesh 去做 2D。

前置環境

• Unity 6000.x（6000.0 LTS 支援到 2026 年 10 月，之後應升級至 6000.3 LTS；程式碼兩者相容）。
• 必裝套件：com.unity.inputsystem（新輸入系統）、com.unity.ugui（UGUI）、com.unity.ai.navigation（NavMesh 烘焙）、com.unity.test-framework（測試，腳手架隨 --tests 自動寫）；可選：com.unity.cinemachine、URP com.unity.render-pipelines.universal。
• 安裝套件走 MCP manage_packages，或腳手架自動寫 manifest（Input System / UGUI / 測試框架，版本按編輯器內建與主線回退表解析）；安裝後 Project Settings → Active Input Handling 設為 Both（腳手架會寫 activeInputHandler: 2）。
• 版本確認：專案裡 ProjectSettings/ProjectVersion.txt；不確定 API 時用 unity_docs / unity_reflect，禁止憑記憶寫不熟悉的 API。

標準工作流程（從 GDD 到可玩功能）

流程 A：新專案/新工程從零搭建

1. 確認版本與管線：manage_editor 讀編輯器版本；專案 URP 還是 Built-in（材質和後處理不同）。
2. 執行腳手架：python scripts/new_gameplay.py --out "<專案>/Assets/Game" --namespace <遊戲名>，產生框架程式碼、asmdef、測試程式集，並自動補 Input System 依賴；開啟一次 Unity 讓套件下載後再重跑一次以回填 asmdef GUID。
   • ⚠️ 首次編譯報 CS0234/CS0246（找不到 UnityEngine.InputSystem）是預期行為，不是腳手架壞了：全新專案還沒下載套件，讀不到 InputSystem 的 asmdef GUID。開啟一次 Unity 讓套件下載 → 重跑腳手架 → GUID 回填 → 再編譯即零錯誤。
   • 已在 Unity 6000.0.84f1 實測：重跑後編譯零錯誤，InventoryTests 3/3 通過。
3. 安裝場景引導物件：按 references/01 建立啟動場景（GameManager、AudioManager、UIManager、EventSystem、Canvas），用 manage_gameobject / manage_components。
4. 按功能順序實現：輸入 → 第一人稱控制器 → 互動 → HUD → 具體玩法系統 → AI → 音訊/VFX（順序見下「功能開發順序」）。
5. 逐功能驗證：每完成一個功能，Play 模式手動測試 + 寫 EditMode/PlayMode 測試，見 references/00 的驗證迴圈。
6. 導覽/烘焙/建置：NavMesh 烘焙、場景入 Build、打包前清單，見 references/08、references/09。

流程 B：單一功能開發（最常見）

讀 GDD 對應單頁（角色/互動/系統/對話/動畫規格）→ 列出要改的腳本與元件 → 選範本或新建 → 按 MCP 編輯迴圈實現 → Play 驗證 → 補測試 → 更新功能完成定義。

流程 C：排錯與最佳化

編譯/執行報錯查 references/10；掉幀/卡頓走 references/08 的 Profiler 流程；MCP 操作失敗按 references/00 的降級方案。

MCP 編輯迴圈（每次改程式碼都遵守）

1. refresh_unity 先同步磁碟；read_console 確認起點無錯。
2. 建立腳本：create_script；改腳本：優先 script_apply_edits（結構化方法級編輯），小改才用 apply_text_edits；改完 validate_script。
3. refresh_unity 觸發編譯 → read_console 看編譯結果（有 CS 錯誤立即修，不允許帶錯繼續）。
4. 掛元件/配參考：manage_components / manage_gameobject；動畫用 manage_animation；UI 用 manage_gameobject（UI Toolkit 才用 manage_ui）。
5. 進入 Play 模式驗證：manage_editor 切換 playmode，read_console 查執行階段例外；視角/手感用 find_gameobjects 讀 Transform 狀態確認，必要時 execute_code 截圖 Game View。
6. 多個不衝突操作合併進 batch_execute；每個功能結束前 manage_scene 存檔。

功能開發順序（腳手架之後）

1. 輸入 InputReader（腳手架已產生）→ 場景裡掛 Player，WASD/滑鼠動起來
2. 第一人稱 PlayerLook + FirstPersonController（走、跑、跳、蹲、落地）
   - 2D 專案改用 `PlatformerController2D`（`--dimension 2d` 時自動產生，3D 專用檔案不會產生）
3. 互動 Interactor + 門/拾取物（準星提示 UI 打通）
4. HUD + 選單面板棧（UIManager，ESC 暫停）
5. 玩法系統：Health/背包/對話（按 GDD 取捨）
6. 存檔 SaveSystem（把已做系統接入 ISaveable）
7. 敵人 AI：NavMesh 烘焙 + EnemyAI + 感知
8. 音訊 AudioManager + 混音器；VFX（粒子/槍口/命中）
9. 效能 Profiler 定幀；建置打包（references/08、09）

腳手架與範本

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests：不產生測試程式集
#   --editor-data "Editor/Data 路徑"：解析 Input System 版本（不傳則按版本回退表）

範本清單（assets/templates/）。注意：範本裡含有 {{NS}} 命名空間佔位符，手動複製時先取代，或直接執行 new_gameplay.py 自動產生，否則無法編譯：

模組	檔案	用途
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	單例、狀態機、事件匯流排、遊戲流程（選單/遊戲/暫停/載入）
Input	InputReader	新 Input System 程式化封裝，鍵盤滑鼠+手把
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D：CharacterController 移動、滑鼠視角、跑跳蹲。2D：Rigidbody2D 平台跳躍（含 coyote time / jump buffer / 可變跳躍高度）
Interaction	InteractableBase / Interactor / PickupItem	準星互動、拾取範例
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	生命、背包、JSON 存檔、線性對話、物件池、音訊
AI	EnemyAI / EnemyPerception	NavMesh 巡邏/追擊/攻擊狀態機 + 視錐感知
UI	UIPanel / UIManager / HUDController	面板棧、HUD 血條/提示/字幕
Tests	InventoryTests（+ asmdef）	背包邏輯測試範例，run_tests 可執行

參考文件索引（按需載入）

• references/00-mcp-code-workflow.md：MCP 47 個工具按玩法任務對應、編輯迴圈、Play 驗證、測試、無 MCP 降級
• references/01-architecture.md：目錄結構、asmdef、命名規範、資料驅動、參考/事件/單例使用邊界、ScriptableObject
• references/02-input-and-fp-controller.md：Input System 落地、Player 預製體層級、第一人稱移動視角參數表、第三人稱/俯視分支
• references/03-interaction-animation.md：互動層、Animator 狀態機/Blend Tree/根運動、動畫事件、Humanoid 對接
• references/04-ui-ugui.md：Canvas/EventSystem 搭建、面板棧、HUD、暫停、輸入切換
• references/05-gameplay-systems.md：血量/背包/對話/存檔/物件池的使用與擴展規範、資料定義
• references/06-ai-navigation.md：NavMesh 烘焙、敵人配置、巡邏點、感知調參、狀態擴展
• references/07-audio-vfx.md：AudioMixer 分組、音訊池、音樂淡變、粒子/VFX Graph 選型
• references/08-performance.md：60fps 預算、Profiler/Frame Debugger 流程、常見熱點
• references/09-build-release.md：建置設定、場景清單、Steam/Deck 檢查、存檔相容
• references/10-troubleshooting.md：編譯/空參考/執行順序/輸入/導覽/UI 常見錯誤對照
• references/11-2d-gameplay.md：做 2D 專案先讀這篇。2D 套件安裝、Sprite 匯入、Physics2D 與層矩陣、 2D 平台跳躍（coyote time/jump buffer）、Tilemap 與 Composite 碰撞、像素完美相機、 以 overdraw 與 Batch 計的 2D 預算（三角形面預算表對 2D 無意義）。

2D 專案注意：本技能的 C# 範本預設是 3D 第一人稱（CharacterController、NavMesh）。 2D 請複用與維度無關的部分（EventBus、StateMachine、Inventory、SaveSystem、Health、 ObjectPool、UIManager、AudioManager），而控制器、導覽、物理、效能預算按 references/11 重寫。

鐵律

• 數值來自 GDD：移動速度、跳躍、傷害、判定幀、視野距離都要在 Inspector 暴露且與 GDD 單頁一致；GDD 沒寫的標 【待確認】，禁止編造數字。
• 每步必須可驗證：改完程式碼編譯零錯誤、Play 模式實測；手感類（移動/視角/攻擊）必須錄得到 Transform/狀態證據，不能只說"應該可以"。
• 禁止假編譯：validate_script 或 read_console 沒過就不算完成；無法在本環境驗證時明確聲明，不編造結果。
• 資料與邏輯分離：可調數值用 SerializeField/ScriptableObject；表現層訂閱事件，不寫進系統類別。
• 命名規範：類別 PascalCase；檔案名稱與主要類別名稱一致；場景/預製體 Level_01_、PF_Player；常數不含中文；Console 出現 CS 警告也要修。
• 小步提交：一個功能一個 commit；改前存檔/備份場景；危險操作（刪除、批次改元件）先列出影響物件。

功能完成定義（DoD）

• 實現的邏輯與 GDD 單頁一致，數值可追溯（業界預設值已標註）
• 編譯零錯誤零警告（read_console 截圖/讀數為證）
• Play 模式實測通過：輸入、狀態切換、互動、回饋都能重現
• 可單元測試的邏輯有測試（run_tests 綠燈）
• 相關參考/元件/層級配置完整（預製體拖入空場景即可使用，不依賴手動臨時連線）
• 存檔新增欄位已處理版本號；新增場景已入 Build
• 效能無新增熱點（目標 60fps，行動裝置/Deck 見 08）