unreal-expert
Unreal expert (technical director and agent protocol)
Version 0.1 (2026-09-24), part of Unreal Engine Expert Skills v0.1.
Expert Unreal work is a loop run against numbers: set the budget, build one stage, measure it, look at it, fix it, then advance. An agent without a mouse gets there by choosing the right channel for each action, working like the Details panel (one transaction, explicit saves), and never trusting its own eyes alone. This skill is the protocol, the shared toolkit in scripts/, and the map to the team. Target: UE 5.8 on macOS Apple Silicon.
Status (2026-09-24): UE 5.8 is not installed. Every in-engine call in scripts/ and references/ is not yet run in Unreal. The pure-Python parts ran offline and pass (eight test files, 314 checks on Python 3.14, 311 on 3.9). First action once the engine is installed: tests/code/unreal-expert/run_all.sh --live with UE_TEST_PROJECT set to a scratch project, then references/ue-5.8-traps.md section 7.
1. Execution channels
| Channel | Use for | Rules |
|---|---|---|
Epic Unreal MCP (plugin ModelContextProtocol, Experimental), your MCP client via .mcp.json |
structured edits covered by shipped toolsets (actors, scene, material instances, Sequencer, PCG, UMG, animation), in the open editor | Enable Unreal MCP and All Toolsets; if "connected but can do nothing", add Editor Toolset, which Epic's webinar says the docs omit (Sam Deiter, k0tgmrBuIJc [00:18:13]). Start with -ModelContextProtocolStartServer -ModelContextProtocolPort=8000 or ModelContextProtocol.StartServer; ModelContextProtocol.GenerateClientConfig ClaudeCode writes .mcp.json; editor first, agent second. Calls run serially on the game thread: never overlap them. describe_toolset only for the toolset you need now: Niagara's is "almost a quarter of a million" (k0tgmrBuIJc [00:46:04]). Loopback, no auth. |
Editor Python in the running editor (ue_remote.PythonRemote, or a custom Python toolset on the MCP server) |
loops, audits, anything toolsets lack, screenshots | Enable Python Remote Execution (Project Settings > Plugins > Python). Full unreal API; the editor ticks between calls. One call = one named transaction that reports what it did. |
Headless commandlet (ue_run.run_python, UnrealEditor-Cmd <uproject> -run=pythonscript) |
audits, imports, batch edits, validation, CI, when no editor has the project open | No level loaded (map= loads one), fewer modules, no rendering. The boot waits for the Asset Registry (get_asset_registry().wait_for_completion(), 5.8 batch example); a job passes only on its boot's job-id UE_RESULT line, never on the exit code. A commandlet that saves must not touch a project an open editor has loaded: the editor holds a write lock (Jamie Dale, 0guOMTiwmhk [01:17:18]). |
Full editor, one shot (mode="editor": -ExecutePythonScript; mode="latent": ticking boot that quits after) |
jobs needing full modules; latent: screenshots and renders without a running editor | -ExecutePythonScript shuts down right after the script, so nothing ticks; ue_run adds -ScriptErrorsAreFatal (5.5) so a failing script fails the process. Latent jobs are generators: yield = one tick. |
Remote Control API (ue_remote.RemoteControl, 127.0.0.1:30010) |
batched property writes on known objects, live presets, -game builds |
Off until WebControl.StartServer. 5.8 disables remote UFUNCTION calls by default with an allow list (5.8 release notes). C++ names, WRITE_TRANSACTION_ACCESS for undo, public EditAnywhere properties only. |
| Console and cvars | stats, view modes, quality switches, HighResShot |
From Python unreal.SystemLibrary.execute_console_command(world, cmd) [verify]; at launch -DPCVars= (before init, overrides read-only cvars; Profiling with Purpose, C-AjCqjKRSs [00:14:13]), not -ExecCmds. Restore what you change. |
Commandlets and UAT (ue_run.run_commandlet, run_uat) |
DataValidation, ResavePackages -fixupredirects, WorldPartitionBuilderCommandlet, BuildCookRun |
Headless; parse the log (ue_run.scan_log). |