From 6834737f2d25a83c2d6a63f8d7cb8b87eb3dcce9 Mon Sep 17 00:00:00 2001 From: daixiawu Date: Mon, 29 Jun 2026 17:35:34 +0800 Subject: [PATCH] chore: add Unity MCP pilot workflow --- .codex/skills/th1-unity-mcp-workflow/SKILL.md | 85 +++++++++++++++++ .../th1-unity-mcp-workflow/agents/openai.yaml | 6 ++ .../references/assessment-2026-06-29.md | 95 +++++++++++++++++++ Unity/Packages/manifest.json | 1 + 4 files changed, 187 insertions(+) create mode 100644 .codex/skills/th1-unity-mcp-workflow/SKILL.md create mode 100644 .codex/skills/th1-unity-mcp-workflow/agents/openai.yaml create mode 100644 .codex/skills/th1-unity-mcp-workflow/references/assessment-2026-06-29.md diff --git a/.codex/skills/th1-unity-mcp-workflow/SKILL.md b/.codex/skills/th1-unity-mcp-workflow/SKILL.md new file mode 100644 index 000000000..78eab3935 --- /dev/null +++ b/.codex/skills/th1-unity-mcp-workflow/SKILL.md @@ -0,0 +1,85 @@ +--- +name: th1-unity-mcp-workflow +description: TH1 workflow for safe Unity MCP use with Funplay/IvanMurzak-style Unity Editor automation. Use when Codex configures, evaluates, updates, or operates Unity MCP tools for TH1 UI prefab work, scene/prefab inspection, screenshots, Play Mode validation, Console/compile diagnostics, MCP tool whitelisting, or project-specific Unity editor automation. +--- + +# TH1 Unity MCP Workflow + +## Core Rule + +Treat Unity MCP as a high-permission editor automation bridge, not as a normal read-only tool. It gives Codex live Unity Editor state, screenshots, Play Mode control, prefab/scene/component operations, and optional dynamic C# execution. Use it to shorten visual and prefab feedback loops, but keep changes reviewable through TH1's normal git, build, and Unity validation paths. + +## First Moves + +- Use `th1-base` first for broad Unity/package/build/resource changes. +- Run `git status --short`; preserve unrelated Unity/OSS/tool changes. +- Prefer read-only MCP tools first: editor state, hierarchy, selection, prefab stage, logs, compile errors, screenshots, and package list. +- Before enabling write/destructive tools, identify the exact prefab, scene, DataAsset, or package file that may change. +- Never use Unity MCP to edit export-flow outputs unless the user explicitly asks: `Unity/Assets/Resources/Export/*`, `Unity/Assets/BundleResources/Export/*`, `Tools/Multilingual.xlsx`, `Tools/MultilingualTxt.txt`. +- Do not use MCP dynamic C# execution for MemoryPack, obfuscation, HybridCLR bootstrap, package manifests, or save/network format changes without explicit confirmation. + +## Installed Baseline + +TH1 currently pilots `FunplayAI/funplay-unity-mcp` through `Unity/Packages/manifest.json`: + +```json +"com.gamebooom.unity.mcp": "https://github.com/FunplayAI/funplay-unity-mcp.git#v0.4.8" +``` + +Funplay is the first-stage default because it is Editor-only, Unity 2022.3 compatible, smaller than the IvanMurzak stack, and exposes a focused `core` tool profile. The IvanMurzak Unity-MCP project remains a candidate for later evaluation when TH1 needs broader CLI, Docker/cloud, runtime/in-game, or custom tool ecosystem support. + +For the research record and rollout notes, read `references/assessment-2026-06-29.md` when changing MCP selection, tool exposure, auth, or rollout policy. + +## Safe Operating Mode + +Use this order for UI/prefab work: + +1. Inspect static code and TH1 UI patterns first. +2. Use MCP read tools to inspect live selection, hierarchy, prefab stage, component values, logs, compile errors, and screenshots. +3. Make source/prefab edits through established Unity APIs or normal file edits, not ad-hoc YAML surgery. +4. Use Unity screenshots or Play Mode only for validation, unless the task explicitly requires editor-side object creation. +5. Check `git diff` after every MCP write action. + +For Funplay `execute_code`: + +- Keep default safety checks on. +- Prefer dedicated tools and `execute_menu_item` before `execute_code`. +- Use `execute_code` only for bounded inspection or a clearly named batch operation with explicit before/after logs. +- Do not pass `safety_checks=false` unless the user explicitly approves that exact operation. + +For IvanMurzak-style tools if installed later: + +- Use `UNITY_MCP_TOOLS` to whitelist only the needed tool IDs. +- Keep destructive tools disabled unless explicitly required: asset delete/move, script delete/update, package add/remove, reflection method call, dynamic script execute. +- Require token auth for HTTP/standalone transport. + +## TH1 UI And Prefab Value + +Use Unity MCP especially for: + +- Inspecting actual prefab component state instead of guessing from YAML. +- Opening prefab stage, reading `RectTransform`, image, TMP, controller binding, and button event state. +- Capturing Game View or prefab screenshots after a UI edit. +- Finding Missing Script, missing references, disabled objects, unexpected scale/alpha, and layout overflow. +- Validating UI workflows in Play Mode with Console checks. + +Do not let MCP bypass TH1 architecture. UI behavior still follows `th1-ui-patterns`; gameplay mutations still go through action logic; text/localization still follows `th1-multilingual`. + +## Verification + +For package/config changes: + +- Prefer opening Unity 2022.3.53f1 and letting Package Manager resolve `Packages/packages-lock.json`. +- Then run the relevant editor or hotfix build if scripts changed. +- For pure skill/docs changes, run the skill creator validation script: + +```powershell +python C:\Users\daixiawu\.codex\skills\.system\skill-creator\scripts\quick_validate.py C:\TH1\TH1\.codex\skills\th1-unity-mcp-workflow +``` + +Before finishing any MCP-assisted edit, report: + +- Which MCP server/tool profile was used. +- Whether any dynamic code execution or destructive tools were used. +- What Unity-side validation was performed. +- Any remaining uncommitted files unrelated to the task. diff --git a/.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml b/.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml new file mode 100644 index 000000000..d89447214 --- /dev/null +++ b/.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "TH1 Unity MCP Workflow" + short_description: "Safe TH1 Unity MCP workflow." + default_prompt: "Use $th1-unity-mcp-workflow to plan or execute a safe TH1 Unity MCP UI/prefab automation task." +policy: + allow_implicit_invocation: true diff --git a/.codex/skills/th1-unity-mcp-workflow/references/assessment-2026-06-29.md b/.codex/skills/th1-unity-mcp-workflow/references/assessment-2026-06-29.md new file mode 100644 index 000000000..ad9cdee7c --- /dev/null +++ b/.codex/skills/th1-unity-mcp-workflow/references/assessment-2026-06-29.md @@ -0,0 +1,95 @@ +# TH1 Unity MCP Assessment - 2026-06-29 + +## Decision + +Pilot Funplay MCP for Unity first. Do not install both Funplay and IvanMurzak Unity-MCP into the TH1 main Unity project at the same time without a separate evaluation branch. + +## Why Funplay First + +- Repository: `FunplayAI/funplay-unity-mcp` +- Package: `com.gamebooom.unity.mcp` +- Version pinned in TH1: `v0.4.8` +- License: MIT +- Unity compatibility: `2022.3` +- Runtime footprint: Editor-only asmdef +- Default posture: focused `core` profile, loopback HTTP server, safety checks for `execute_code` + +Primary TH1 use cases: + +- Live Unity Editor inspection. +- Console and compile diagnostics. +- Hierarchy, selection, prefab stage, and component inspection. +- Screenshot and Play Mode validation. +- Prefab/UI verification after Codex edits. + +Main risk: + +- It includes `execute_code`, file, asset, package, and GameObject write tools. Its safety checks are defensive pattern checks, not a sandbox. + +## Why IvanMurzak Is Candidate, Not Default + +- Repository: `IvanMurzak/Unity-MCP` +- Package: `com.ivanmurzak.unity.mcp` +- Observed release during assessment: `0.82.2` +- License: Apache-2.0 +- Unity compatibility: `2022.3` +- Larger ecosystem: CLI, Docker/cloud deployment, runtime/in-game mode, many tools, tool enable/disable UI, token auth options. + +Reasons to delay in TH1 mainline: + +- Broader install footprint and additional dependencies. +- Includes runtime direction, not just Editor-only workflow. +- Supports powerful tools such as dynamic script execution, reflection method calls including private methods, package installation, and destructive asset/script operations. +- HTTP auth defaults must be configured deliberately; do not rely on defaults. + +Install later only when TH1 needs one of: + +- CLI-managed Unity MCP lifecycle. +- Runtime/in-game MCP integration. +- Richer custom MCP tool ecosystem. +- Docker/cloud MCP server deployment. + +## Rollout Plan + +1. Install Funplay Git package in `Unity/Packages/manifest.json`. +2. Configure Codex MCP URL to `http://127.0.0.1:8765/`. +3. Open Unity and start `Funplay > MCP Server`. +4. First test only read-style calls: scene info, editor state, selection, compile errors, Console logs, screenshot. +5. For UI/prefab tasks, require `git status` and `git diff` after any MCP write call. +6. Keep IvanMurzak uninstalled until a task needs its extra capabilities. + +## MCP Safety Policy For TH1 + +Default allowed categories: + +- Read editor state. +- Read hierarchy/selection/prefab stage. +- Read compile errors and Console logs. +- Capture screenshots. +- Enter/exit Play Mode for explicit validation. + +Requires explicit user intent: + +- Modify prefab/scene/component values. +- Create/delete/copy/rename assets. +- Install/remove packages. +- Dynamic C# execution. +- Reflection method calls. + +Avoid through MCP: + +- MemoryPack serialization format changes. +- Obfuscation settings. +- HybridCLR bootstrap or AOT metadata flow. +- Network/save payload schema changes. +- Manual edits to export-flow outputs. + +## Expected New Value Over Plain Codex + +Before MCP, Codex mostly reads and edits files, then verifies with command-line builds. After Unity MCP, Codex can inspect and validate the live Unity Editor state. The biggest TH1 gains are: + +- Safer prefab work via Unity APIs instead of YAML guessing. +- Visual UI feedback through screenshots. +- Faster compile/Console error loops. +- Better detection of missing references, missing scripts, bad RectTransform values, wrong active state, and prefab-stage issues. +- Foundation for future TH1-specific MCP tools, such as UI binding checks, prefab reference audits, and screenshot smoke tests. diff --git a/Unity/Packages/manifest.json b/Unity/Packages/manifest.json index 4bc4c15a5..d9787a2a4 100644 --- a/Unity/Packages/manifest.json +++ b/Unity/Packages/manifest.json @@ -2,6 +2,7 @@ "dependencies": { "com.code-philosophy.hybridclr": "https://github.com/focus-creative-games/hybridclr_unity.git#v8.12.0", "com.cysharp.memorypack": "https://github.com/Cysharp/MemoryPack.git?path=src/MemoryPack.Unity/Assets/Plugins/MemoryPack#1.10.0", + "com.gamebooom.unity.mcp": "https://github.com/FunplayAI/funplay-unity-mcp.git#v0.4.8", "com.github-glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity", "com.tuyoogame.yooasset": "2.1.1", "com.unity.collab-proxy": "2.5.2",