Unreal Client Protocol

UnrealClientProtocol

Communicate with a running UE editor through the UnrealClientProtocol TCP plugin. UCP exposes a single command — call any UFunction on any UObject via JSON. All functionality is provided through Blueprint Function Libraries that you invoke this way.

Invocation

When you read this SKILL.md, you already know its absolute path. Replace the filename with scripts/UCP.py to get UCP.py's path. For example, if this file is at X/Skills/unreal-client-protocol/SKILL.md, then UCP.py is at X/Skills/unreal-client-protocol/scripts/UCP.py. Do NOT search or glob for UCP.py.

Use PowerShell here-string (@'...'@) to pipe JSON into UCP.py. This avoids all quote/escape issues:

@'
{"object":"/Script/UnrealClientProtocol.Default__ObjectOperationLibrary","function":"FindObjectInstances","params":{"ClassName":"/Script/Engine.World"}}
'@ | python "<path-to-UCP.py>"

IMPORTANT: The @' must be on its own line, and '@ must also be at the start of its own line. This is PowerShell here-string syntax — the content between them is passed verbatim with zero escaping needed.

NEVER use echo '...' or echo "..." for JSON in PowerShell — quotes and braces will be corrupted.

Command Format

{"object":"<object_path>","function":"<func_name>","params":{...}}

• object: Full UObject path — use CDO path for static/library functions, instance path for member methods.
• function: The UFunction name exactly as declared in C++.
• params: (optional) Map of parameter name -> value. UObject* params accept path strings. Omit WorldContextObject.

Parameter handling

• Out parameters (TArray<AActor*>& OutActors, etc.) can be omitted from params — they are auto-initialized and returned as part of the result after execution.
• Return values and all out parameters are serialized together in the response. For example, calling GetAllActorsOfClass with only {"ActorClass":"/Script/Engine.StaticMeshActor"} returns {"OutActors":["/Game/Maps/Main.Main:PersistentLevel.Cube_0", ...]}.
• UObject* parameters accept full object paths as strings. The system resolves them automatically.

Complex Operation Strategy

When an operation involves predictable multi-step logic (loops, conditionals, bulk modifications), do NOT issue many individual calls. Instead:

1. Write a Python script that performs all the steps in one go.
2. Execute it via a single call to UPythonScriptLibrary::ExecutePythonScript.

This dramatically reduces tool-call round-trips and gives you the full power of Python for flow control.

Core Principle — "Knowledge First"

You (the AI) already possess extensive knowledge of the Unreal Engine C++ / Blueprint API. Always leverage that knowledge to construct commands directly. Use DescribeObject / DescribeObjectFunction only when uncertain about project-specific classes.

Key Rules

1. Construct from knowledge first. You know UE APIs. Just call them.
2. Script for bulk operations. When you need loops or conditionals, write a Python script and execute it via ExecutePythonScript.
3. WorldContext is auto-injected. Never pass WorldContextObject manually.
4. Latent functions are not supported. Functions with FLatentActionInfo will be rejected.
5. Check the log field. If the response contains a log array, warnings or errors occurred.
6. Read error responses carefully. A failed call returns {"error":"...", "expected":{...}} — use it to self-correct.