npx claudepluginhub mflrevan/unity-control-protocol --plugin ucpThis skill uses the workspace's default tool permissions.
UCP is a cross-platform CLI + Unity Editor bridge. The CLI (`ucp`) sends commands over WebSocket to a bridge package running inside the Unity Editor, which executes them via JSON-RPC 2.0 and returns results. Every command supports `--json` for machine-readable output.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
UCP is a cross-platform CLI + Unity Editor bridge. The CLI (ucp) sends commands over WebSocket to a bridge package running inside the Unity Editor, which executes them via JSON-RPC 2.0 and returns results. Every command supports --json for machine-readable output.
UCP and Unity expose a broad command surface. If you are unsure what is available in any area, prefer ucp --help and ucp <command> --help first to discover the current control surface before guessing.
.unitypackage contentStart here whenever bridge state is unknown:
ucp doctor
ucp open
ucp connect
ucp install
ucp bridge status
Use ucp <command> --help for flags such as --project, --json, --unity, --timeout, --dialog-policy, and bridge update controls.
ucp connect and other bridge-backed commands can auto-start Unity when the project and editor path are resolvable. If startup stalls on dialogs, use --dialog-policy .... If you need machine-readable output, prefer --json.
ucp compile.ucp files ... as a sandboxed fallback for bridge-mediated project file I/O.ucp scene snapshot before object or prefab work to discover instance IDs.ucp asset import-settings ... over raw .meta file edits.ucp files write and ucp files patch automatically reimport edited Unity assets and .meta files under Assets/ and Packages/ unless you pass --no-reimport.ucp packages add|remove for normal Package Manager installs and ucp packages dependency ... for explicit manifest-driven local file: references.cm for normal Unity Version Control work; use ucp vcs only as a lightweight fallback.If unsure, inspect the full surface with ucp scene --help and ucp editor --help.
ucp scene snapshot --filter "Player"
ucp scene save # save active scene before loading another
ucp scene load Assets/Scenes/Level1.unity
ucp scene load Assets/Scenes/Lighting.unity --additive
ucp scene focus --id 46894 --axis 1 0 0
ucp editor status
ucp play
ucp stop
ucp compile
Use ucp object --help, ucp asset --help, ucp material --help, and ucp prefab --help for the full command set.
ucp object get-fields --id 46894 --component Transform
ucp object set-property --id 46894 --component BoxCollider --property m_IsTrigger --value true
ucp asset search -t Material --max 10
ucp asset search -n '^SCN_[0-9]+$' --regex
ucp asset move "Assets/Legacy/Enemy.prefab" "Assets/Characters/Enemy.prefab"
ucp asset bulk-move --moves '[{"from":"Assets/Legacy/Enemy.mat","to":"Assets/Characters/Materials/Enemy.mat"}]' --dry-run
ucp asset import-settings write "Assets/Textures/HUD.png" --field m_IsReadable --value true
ucp asset reimport "Assets/Generated" --recursive
ucp material set-property --path "Assets/Materials/Agent.mat" --property _Metallic --value "0.5"
ucp prefab apply --id -136722
Object reference writes accept instanceId, asset path, or asset guid, and unresolved references fail explicitly.
Use ucp asset move / bulk-move for Unity-aware renames and folder cleanup instead of raw filesystem moves. That keeps .meta files and GUIDs intact so scenes, prefabs, build settings, and serialized object references continue to resolve.
Use ucp packages --help, ucp settings --help, ucp build --help, ucp logs --help, ucp run-tests --help, ucp profiler --help, and ucp exec --help when you need the full surface.
ucp packages add com.unity.cinemachine
ucp packages dependency set com.company.tooling file:../tooling-package
ucp packages unitypackage inspect Downloads/EnvironmentPack.unitypackage
ucp settings player
ucp settings set-player --key runInBackground --value true
ucp settings set-lighting --key fog --value true
ucp build targets
ucp build start --output "Builds/Game.exe"
ucp logs --pattern "NullReference|Exception" --count 100
ucp run-tests --mode edit --filter "UCP.Bridge.Tests.ControllerSmokeTests.LogsTail_ReturnsRequestedBufferedCount"
ucp profiler summary --limit 5
ucp exec run SetupScene
Prefer fully qualified test names when filtering, and use --json for structured log or test consumption.
Use ucp references --help for the full surface. Reference queries are read-only and do not require a running editor when native Rust indexing is available (Force Text + Visible Meta Files).
# Check native indexing compatibility
ucp references check
# Check outgoing references after a move/rename
ucp references check Assets/Prefabs
# Find all references to a material
ucp references find --asset "Assets/Materials/Agent.mat"
# Find by GUID
ucp references find --asset 933532a4fcc9baf4fa0491de14d08ed7
# Summary detail for minimal context bloat
ucp references find --asset "Assets/Scripts/PlayerController.cs" --detail summary
# JSON output for structured consumption
ucp references find --asset "Assets/Prefabs/Enemy.prefab" --json --detail normal
# Find string-based references Unity will not migrate automatically
ucp references find-strings --pattern "SCN_Menu"
# Force bridge fallback (requires running editor)
ucp references find --asset "Assets/Materials/Agent.mat" --approach bridge
Use --detail summary in general workflows to minimize context bloat — repetitive patterns (e.g., 200 MeshRenderers referencing one material) collapse to a single count line. Use --detail verbose only for small, targeted result sets.
Use references check <path> after refactors for fast missing-target verification, and references find-strings when custom string IDs or scene-path fields need manual migration help beyond GUID-safe asset moves.
ucp vcs
Prefer the native cm CLI for Unity VCS when it's available. Use ucp vcs as a lightweight fallback that prints the currently available bridge-backed VCS commands and flags.
ucp scene snapshot --filter "Player"
ucp scene focus --id 46900 --axis 1 0 0
ucp screenshot --view scene --output before.png
ucp object get-fields --id 46900 --component Rigidbody
ucp object set-property --id 46900 --component Rigidbody --property m_Mass --value "2.5"
ucp screenshot --view scene --output after.png
Use this for scene-aware iteration, not just raw file editing. Snapshot gives live instance IDs, focus aligns the Scene view for repeatable screenshots, and property changes apply through Unity immediately.
ucp object create "EnemyRoot"
ucp object add-component --id -15774 --component Rigidbody
ucp object create "Visual" --parent -15774
ucp object add-component --id -15775 --component MeshRenderer
ucp prefab create --id -15774 --path "Assets/Prefabs/EnemyRoot.prefab"
ucp prefab apply --id -15774
Use this for bridge-native authoring loops: assemble hierarchy in-scene, attach components, then persist it as a prefab. Refresh IDs with ucp scene snapshot if compilation, reloads, or other editor events invalidate handles.
# Preferred when you already have workspace access
<edit scripts/files locally>
ucp compile
# Fallback when you want bridge-mediated writes
ucp files write Assets/Scripts/EnemyAI.cs --content "..."
# Imported assets: update importer settings instead of hand-editing .meta
ucp asset import-settings write "Assets/Models/Enemy.fbx" --field m_GlobalScale --value 0.5
ucp asset reimport "Assets/Models/Enemy.fbx"
UCP is unique here because it can bridge Unity-aware apply steps: ucp compile handles recompilation after local edits, while ucp files write / patch automatically reimport eligible assets and .meta files unless you intentionally defer with --no-reimport.
ucp packages search com.unity.cinemachine
ucp packages add com.unity.cinemachine
ucp packages info com.unity.cinemachine
ucp packages registries add --name github --url https://npm.pkg.github.com --scope com.company
ucp packages dependency set com.company.tooling file:../tooling-package
ucp packages unitypackage inspect Downloads/EnvironmentPack.unitypackage
ucp packages unitypackage import Downloads/EnvironmentPack.unitypackage --select Assets/Environment/Trees
Use packages add|remove for normal UPM installs, packages dependency ... for explicit manifest references, and packages unitypackage ... when you need machine-friendly inspection plus selective import for archive-based content. Scoped registry adds may surface Unity's own security popup the first time a new registry is introduced.
ucp compile
ucp play
ucp logs status
ucp logs --pattern "Exception|Error" --count 15
ucp stop
Use this loop for autonomous playtesting. If ucp play fails, fix compile or console-blocking errors first, then retry. Use logs for buffered inspection without needing to stream the entire editor log. ucp logs status returns curated/collapsed stats.
ucp profiler status
ucp profiler session start --mode play
ucp play
ucp profiler frames list --limit 1 --json
ucp profiler summary --limit 10
ucp profiler timeline --frame <fresh-frame> --thread 0 --limit 20
ucp profiler hierarchy --frame <fresh-frame> --thread 0 --limit 20
ucp profiler capture save --output ProfilerCaptures/session.json
ucp profiler session stop
ucp stop
Use profiler commands when debugging performance, spikes, or hot paths. Prefer grabbing a fresh frame id from ucp profiler frames list immediately before timeline, hierarchy, or callstacks, because live editor frame ids churn quickly. summary is intentionally bounded to recent frames by default, and capture save --output *.json exports a structured snapshot for agents/scripts without relying on unsupported live editor raw-binary logging.
ucp connect || exit 1
ucp run-tests --mode edit
ucp build set-defines "CI;RELEASE"
ucp build start --output "Builds/Game.exe"
ucp scene snapshot --json > hierarchy.json
ucp logs --level error
ucp screenshot
This is a compact handoff workflow for agents: capture hierarchy state, inspect current errors, and grab a visual snapshot before deciding on the next action.