kawagiri/TH1
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
TH1/.codex/skills/th1-unity-mcp-workflow/SKILL.md

4.8 KiB
Raw Blame History

name, description
name description
th1-unity-mcp-workflow 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:

"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:
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.