italink/unrealclientprotocol/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.

Object Path Conventions

CDO class name convention: Drop the U or A prefix. UKismetSystemLibrary -> Default__KismetSystemLibrary.

Available Blueprint Function Libraries

UCP provides several function libraries. Each has its own Skill for detailed documentation:

Response Format

• Success: Returns the result value directly, no wrapper.
• Failure: Returns {"error":"...", "expected":{...}} where expected contains the function signature.
• Transaction ID: Every response includes an "id" field (e.g. "UCP-A1B2C3D4"), automatically generated by the plugin. This ID is also the Undo transaction description — record it for safe undo (see unreal-object-operation skill).
• Deferred Response: Functions returning FUCPDeferredResponse use async execution — UCP.py keeps the TCP connection open and receives the result when the operation completes. No polling needed. Set UE_TIMEOUT to a larger value for long operations (e.g. $env:UE_TIMEOUT = "120" for Live Coding compile).
• Log: If warnings/errors occurred, a log field (string array) is appended.
• Log level: Add "log_level":"all" to any request to capture all log levels (default captures Warning+). Options: "all", "log", "display", "warning" (default), "error".