chore: add Unity MCP pilot workflow
This commit is contained in:
parent
3ef3bcec7f
commit
6834737f2d
85
.codex/skills/th1-unity-mcp-workflow/SKILL.md
Normal file
85
.codex/skills/th1-unity-mcp-workflow/SKILL.md
Normal file
@ -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.
|
||||
6
.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml
Normal file
6
.codex/skills/th1-unity-mcp-workflow/agents/openai.yaml
Normal file
@ -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
|
||||
@ -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.
|
||||
@ -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",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user