Unreal MCP and build runbook (MegaJam prep)
Pre-jam tooling, written 2026-11-09. Everything here was run on the laptop (Unreal 5.8.3, RTX 4090 Laptop) against the throwaway project prep/toolcheck/ToolCheck.uproject (engine primitives only). Tower 2 was used as the backup build machine.
Engine choice: Wednesday's gate (5.9.0 or 5.8.4; Don leans to 5.9)
Epic posted the "Unreal Engine 5.9 MegaJam Preview" (5.9.0-preview-1) on the forum on Nov 9: https://forums.unrealengine.com/t/unreal-engine-5-9-megajam-preview/2852840
- It is real and aimed at this jam. It has bigger MCP toolsets (rendering, profiling, audio, UI, level creation, Fab), an in-editor "Unreal Assistant" panel for Claude Code, and MCP that starts with the editor.
- Epic says it is not fully quality-tested, had about a week of development and a short QA pass, and should be treated as unstable. Epic tells people to test on a copy, not convert a project.
-
The known-issues list includes packaging bugs. One is UE-411525: incremental packaging with
-NoCleanStagecan ship stale content. Another is UE-412135: new projects get no editor tools until All Toolsets is enabled. (The second one also bites 5.8.3; the ToolCheck setup below already handles it.) - Getting it needs the Epic Games Launcher (Epic login, EULA) or the GitHub release (GitHub account linked to an Epic account). I could not find a download without a login, so I installed nothing.
- The jam rules name no engine version.
Recommendation of 2026-11-09 morning, superseded by the update below: build the jam game on 5.8.3. It is proven end to end today on both machines: MCP, headless packaging, smoke test and capture. The 5.9 preview gains are agent comfort, not things the judges score. Its risks land where a 4-day jam can't absorb them: crashes, a stale-package bug, and an untested toolchain on tower 2. If Don wants a look, he can install 5.9 beside 5.8 from the launcher and try Unreal Assistant on a copy of ToolCheck on Nov 10 or 11. Don't switch the jam project.
Update 2026-11-09 evening: Don is installing 5.9 on the laptop and tower 2 and updating 5.8.3 to 5.8.4. The jam engine is now decided by a Wednesday morning gate, not by this section: 5.9 gets the same proof 5.8 passed (MCP drive, clean package, smoke, OBS take, tower 2 package) plus one test per new area below; if all pass, the jam runs on 5.9, else on 5.8.4 (smoke rerun after the update). The game folder is empty until midnight, so nothing is converted.
Gate result, Wed 2026-11-11, 08:40 to 09:22 ET
Jam engine: 5.9.0. Every check passed. Each agent check was built by headless Claude Code (Sonnet) through MCP, then read back by a second, independent script. The two 5.9 snags, the background throttle and the "slow task" replies, came down to a config file and a retry. The throttle fix applies to 5.8.4 too. 5.8.4 also passed its rerun, so it stays a tested fallback.
Laptop: D:\megajam\ue59test\ToolCheck59 on D:\Epic_Games\UE_5.9\UE_5.9. Tower 2: G:\ue59test\ToolCheck59. Gate outputs (zips, takes, logs, the MetaSound render): D:\megajam\gate1111\ on the laptop.
| Check | Result | Time (ET) | Evidence |
|---|---|---|---|
| Editor start with MCP | PASS | 08:41 | 70 s on the first start, 15 to 19 s on later starts; 128 toolsets |
MCP drive, script (mcp_smoke59.py) | PASS | 08:48 | Spawn, move, read back, delete, re-save: 1.6 s, 9 to 40 ms per call (after fix 1 below) |
mcp_client.py describe and schema on 5.9 | PASS | 08:50 | Detects the 5.9 surface; exit 2 on an unknown name |
| MCP drive, headless Claude Code | PASS | 08:57 | claude -p (Sonnet, --mcp-config .mcp.json --strict-mcp-config): spawn, move, read back, delete, save in 27 s, 10 turns |
| Clean package, laptop (editor open) | PASS | 08:49 to 08:52 | -Clean, Development: build 175 s, zip 37 s; staged 644.2 MB, zip 362.5 MB; 0 errors |
| Packaged smoke, laptop zip | PASS | 08:53 | Map loaded at 12 s, 0 errors or ensures, total 86 s |
| Clean package, tower 2 | PASS | 08:41 to 08:42 | -Clean, Development: 81 s total (build 58 s, zip 23 s), 362.5 MB; copied to the laptop in 4 s, SHA-256 matched |
| Packaged smoke, tower 2 zip (on the laptop) | PASS | 08:54 | Map loaded at 11 s, 0 errors, total 34 s |
| OBS take, laptop | PASS | 08:55, 09:18 | 1920x1080, 60 fps, 30.6 s, the scene in frame (the 5.8 bar). Second take with a test tone: audio max -9 dB, RECORDING OK. See finding 6 |
| Remote Python execution | PASS | 09:00 to 09:02 | Agent ran execute_python twice and saved and read back an asset (31 s). Remote execution on (fix 3): Epic's remote_execution.py found the editor node and ran a script |
| Geometry Script call | PASS | 09:02 | Agent: box plus sphere plus plane cut, saved /Game/GateCheck/Geo/SM_GateGeo (65 s). Read back: 210 triangles |
| Niagara burst, agent-built | PASS | 09:04 | /Game/GateCheck/FX/NS_GateBurst from a template, burst count 60 read back (105 s). Read back: compile UpToDate, no errors, no warnings |
| MetaSound, agent-built | PASS | 09:05 to 09:09 | /Game/GateCheck/Audio/MS_GateTone: sine, AD envelope, multiply, output (78 s). Rendered by the engine: 440 Hz, sounds 0.81 s, max -9.1 dB. A looping variant, placed in the map and packaged, was heard in the OBS take |
| PCG graph on a CC0 mesh | PASS | 09:07 | Kenney Car Kit cone.fbx (CC0) imported in the editor; grid into Static Mesh Spawner; 16 cones (75 s). Independent regenerate: 16 instances of the cone. Level left clean |
| 5.8.4 fallback: clean package and smoke | PASS | 09:01 to 09:03 | Package 79 s, 354.5 MB; smoke map at 13 s, 0 errors, total 51 s |
5.8.4 fallback: MCP smoke (mcp_smoke.py, port 8001) | PASS | 09:05 | 0.5 s; 55 toolsets |
Findings (fixed or worked around today):
-
The background throttle switch was in the wrong file, on both engines.
UEditorPerformanceSettingsisconfig=EditorSettings, sobThrottleCPUWhenNotForeground=FalseinDefaultEditorPerProjectUserSettings.iniis ignored. With it there, 5.9 and 5.8.4 both answered every MCP call in about 330 ms. InConfig/DefaultEditorSettings.iniit works: 12 to 40 ms with the editor in the background, on both. Section 1 now says so, andprep/toolcheckhas the file. -
5.9 busy reply. Right after a save or a compile, a call can return "Not run: the Unreal Editor is running a slow
task" with
isError. Nothing changed; wait and retry.mcp_smoke59.pyretries for up to 60 s. -
Remote Python execution is
bRemoteExecution=Trueunder[/Script/PythonScriptPlugin.PythonScriptPluginSettings]inDefaultEngine.ini, not in the per-user file. It needs an editor restart. The engine default binds localhost with TTL 0, so it stays on this machine. MCP's ownexecute_pythonneeds no setting. -
Headless Claude Code works now (Don's login). The project folder is not trusted, so Claude Code ignores
.claude/settings.jsonallow lists. Pass--allowedToolswith the four 5.9 tools (mcp__unreal-mcp__list_toolsets,mcp__unreal-mcp__describe_toolsets,mcp__unreal-mcp__describe_tools,mcp__unreal-mcp__call_tool) and< /dev/nullfor stdin. Each agent check cost $0.13 to $0.43 on Sonnet (API-equivalent figures from--output-format json). -
An unfocused editor or game mutes itself. To render audio in the editor, set
au.DisableAppVolume 1first, and givestop_recording_outputa path relative toSaved, not an absolute one. An unfocused packaged game mutes too, which made the first take with sound silent.record-obs.ps1now launches the game with-ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0for takes only. The shipped game's default is unchanged. -
An agent session cannot bring the game window to the front.
SetForegroundWindow, even with the Alt-key handoff now inrecord-obs.ps1, fails from this session. The game then ran at about 8 to 20 fps during takes, measured from its log frame counter. That is the known background throttle (section 8), it is the same on 5.8, and it is not from the editor (20 fps with the editor closed) or from Windows power throttling (turning that off did not help). The script now printsGame window in front: True/False. Record the submission takes with the game in front: from Don's own desktop, or from a task started in his interactive session. - Cooking with the editor open works on 5.9 (section 6, gotcha 7 holds). Copying the 362 MB zip from tower 2 to the laptop with scp took 4 s.
- Tower 2 has had a 5.9 editor open from the launcher since Nov 9 (Don's session). It was left alone; it did not get in the way of headless packaging.
Installed engines (checked 2026-11-10): laptop 5.8.4 at D:\Epic_Games\UE_5.8 and 5.9.0 at D:\Epic_Games\UE_5.9\UE_5.9; tower 2 5.8.4 at G:\Epic_Games\UE_5.8 and 5.9.0 at C:\Program Files\Epic Games\UE_5.9. package.ps1 and start-editor-mcp.ps1 look only in the 5.8 folders, and ue_import.ps1 defaults to the laptop's 5.8, so on 5.9 every call passes -EngineDir (or -Engine). The 5.9 MCP check is mcp_smoke59.py, and mcp_client.py describe and schema detect 5.9 (built for the gate, 2026-11-11). mcp_smoke.py stays the 5.8 check.
5.9 results so far (2026-11-09, tower 2, 5.9.0 at C:\Program Files\Epic Games\UE_5.9):
-
The MCP plugin is on by default in 5.9 (off in 5.8). Our 5.8 setup lists it with
"TargetAllowList": ["Editor"], which 5.9 reads as disabling a default plugin, so the project turns code based and RunUAT fails in 12 s looking forBinaries\Win64\ToolCheckEditor.target. Fix for 5.9: drop the ModelContextProtocol entry and keep the other three. The 5.9 copy is at tower 2G:\ue59test\ToolCheck59. -
After that fix, a clean Development package took 8.5 min. Zipped size 362.5 MB, staged size 644 MB.
smoke.ps1passed on the laptop: map loaded at 10 s, 0 errors, 761 frames. - Copying the 362 MB zip from tower 2 to the laptop with scp through tower 1 took about 10 minutes. Budget for that, or have Don's upload run from tower 2.
-
Tower 2 (AMD) can't run Kimodo. It needs CUDA and about 17 GB of GPU memory. Epic's plugin quantizes the Llama 3 encoder to NF4 by default (about 6 GB instead of 15), so it should fit on the laptop's 4090. Tower 1's A5000 can run it at full precision. The encoder must be
meta-llama/Meta-Llama-3-8B-Instructexactly, plus McGill-NLP's LLM2Vec adapters; 3.1 won't work. Don requested access on 2026-11-09. -
Laptop, 2026-11-09 evening:
-
Install path: 5.9.0 is at
D:\Epic_Games\UE_5.9\UE_5.9, one folder deeper than planned, because the launcher adds its own folder. Scripts take-EngineDir. -
Startup: the 5.9 copy of ToolCheck (
D:\megajam\ue59test\ToolCheck59) started with MCP. The server answered at 41 s and listed toolsets at 49 s, on the first launch. - Toolsets: 5.9 lists 111 toolsets, against 55 in 5.8.3.
-
Install path: 5.9.0 is at
-
5.9 renamed MCP, so
mcp_smoke.pyfails on 5.9:-
Top-level tools: they are now
list_toolsets,describe_toolsets(plural; takestoolset_names),describe_toolsandcall_tool. -
Toolset names: the 5.8 Python ones (
editor_toolset.toolsets.scene.SceneToolsand similar) are gone. Actors and levels areEditorToolset.ActorToolsetandEditorToolset.LevelToolset. - Tool names: each tool's name carries its toolset prefix.
-
Fix before the jam: a 5.9 variant of the smoke test and of
mcp_client.py describe.
-
Top-level tools: they are now
-
Agents can now author effects and sounds through MCP. In 5.8 they could do neither:
-
Niagara:
NiagaraToolsets.NiagaraToolset_SystemhasCreateNiagaraSystem,AddEmitter,AddModule,SetStackInputData,AddRenderer,GetSystemCompileStateandGetStackIssues, so an agent can build an effect and check that it compiles. -
MetaSound:
MetaSoundToolset.MetaSoundAuthoringToolsethasCreateSourceBuilder,AddNodes,Connect,SetDefaultsandBuildToAsset, so an agent can build a sound graph and save it. -
Also present: PCG (
PCGToolset,PCGSpatialToolset),MaterialToolset,MaterialInstanceToolset,SoundWaveToolset, the Perf toolsets (CSV profiler, stats, GPU profiler),AutomationTestToolset,SceneCaptureToolset,InputToolset,CommonUIToolset, andeditor_toolset.toolsets.python_scripting.PythonScriptingTools. - Tested at the Wednesday gate (2026-11-11): PASS. An agent built a burst effect that compiles cleanly and a MetaSound that the engine played (gate result above).
-
Niagara:
- Python API probe (headless on tower 2, empty projects, same plugins): 5.9 exposes 13,770 names to Python, against 12,403 in 5.8.4. The changes by area:
| Area | Count, 5.8.4 to 5.9 | What's new |
|---|---|---|
| Niagara | +92 | Edit API types: emitter handles, stateless emitters and templates, simulation stages |
| Widgets | +87 | |
| Audio | +59 | |
| PCG | +34 | |
| Materials | +31 | material and material instance toolsets |
| MetaSound | +9 | authoring, discovery and inspection toolsets |
| Toolsets | 73 to 170 |
These are names only. Whether an agent can build a working Niagara burst or MetaSound is still the Wednesday gate test. A headless editor start took 23 min on 5.9's first run against 10 on 5.8, so warm the cache before the jam.
-
5.9 cache warm-up (overnight 2026-11-10 to 11-11). Command on both machines:
UnrealEditor-Cmd.exe <ToolCheck59>\ToolCheck.uproject -run=DerivedDataCache -fill -unattended -nosplash -nopause, run twice in a row, no project or engine changes. Neither machine was strictly cold: both had run 5.9 before (tower 2 packaged, laptop ran MCP), so the first run was only partly cold.
| Machine | First run (cold) | Second run (warm) | Exit codes |
|---|---|---|---|
Tower 2 (G:\ue59test\ToolCheck59) | 2622 s (43.7 min) | 99 s | 0, 0 |
Laptop (D:\megajam\ue59test\ToolCheck59) | 4369 s (72.8 min) | 187 s | 0, 0 |
-
Warm is about 26 times faster on tower 2 and 23 times faster on the laptop. Both cold runs were much slower than the 23 min above, because
-fillcompiles every shader the project can reach, not just the startup set. -
The cold logs show engine shader compile errors (
PathTracingRandomSequence.ushl-value expected,NiagaraRibbonVertexFactory.ushsyntax error) and a Chaos cloth node warning. The commandlet still exited 0. They are engine files, not ours. -
Logs:
G:\ue59test\warm\run1.logandrun2.logon tower 2,D:\megajam\ue59test\warm\on the laptop. An engine or driver update cools the cache again.
Areas 5.9 opens to agents, each with a 10 minute gate check and a fuller study after the jam:
- Audio: MetaSounds through Python and the audio toolset. Gate: a script builds a MetaSound (an oscillator through an envelope) and it plays in a packaged build.
- Effects: Niagara through Python (impossible in 5.8). Gate: a script builds a burst emitter from a template and sets its parameters.
- Materials: a script builds a material with parameters and an instance.
- Levels: PCG and the level creation toolset. Gate: a script scatters props on a landscape by rule.
- UI: the UI toolset builds a menu widget with a button that works on pad, keys and touch.
- Fab toolset: agents search Fab. Gate is search only; anything installed is a sourced asset, and accepting a license is Don's.
- Gameplay testing and profiling: an agent runs an automated play test and reads a frame time capture.
- Unreal Assistant panel: Claude Code inside the editor, compared against our external MCP client.
One exception worth testing: AnimGenOffline (5.9 preview plugin, announced by Epic's John van der Burg on X, Nov 9). It generates animation in Sequencer from a spline path, keyframe poses, Control Rig poses or a text prompt, with NVIDIA Kimodo as the first backend, and retargets automatically. That would close our Kimodo to Manny retarget gap (ASSET-PIPELINES.md), and generated motion is ours, so it scores, unlike Manny's template animations. The plan: 5.9 runs as an animation side tool only. Generate clips there, export them as FBX and import them into the 5.8.3 jam project. (Written when the jam was planned on 5.8.3. If the gate picks 5.9, AnimGenOffline runs inside the jam project and the FBX hop is not needed; on 5.8.4 the hop stands. 5.9 was installed 2026-11-09.) Before the jam (Nov 10 or 11), test it on a copy of ToolCheck: a walk on Manny, the FBX hop into 5.8.3, and foot slide measured against the BODYLAB bar (sbm/docs/BODYLAB.md). Our Kimodo trial beat the CMU retarget by 2 to 3 times but missed that bar. Needs from Don: the 5.9 install (launcher, EULA), and a Hugging Face account with a read token, because the plugin downloads its weights itself. The text prompt mode needs Kimodo's gated Llama 3 encoder (about 16 GB, Meta's license, which Don must accept) and may not fit on the laptop's 16 GB GPU while the editor runs. Path and keyframe modes worked without it in our trial. The 5.8.4 hotfix (Oct 20) lists no MCP changes, so it isn't worth an engine change this week either.
1. Project setup that works (copy into the jam project on Nov 12)
ToolCheck.uproject plugins:
-
ModelContextProtocol,AllToolsets,PythonScriptPlugin,EditorScriptingUtilities, each with"TargetAllowList": ["Editor"]. This keeps them out of the game target, so a Blueprint project still packages with the stock precompiled UnrealGame.exe and needs no C++ build. -
Do not disable any engine plugin that is on by default (AndroidFileServer, the NNE plugins and so on). I tried it: the project stops counting as content-only, and RunUAT fails in 3 s looking for
Binaries\Win64\ToolCheckEditor.target. The project would need a C++ editor target built first, and tower 2 can't build one. -
The editor writes a random
SecurityTokeninto DefaultEngine.ini for the AndroidFileServer plugin on every start, which the CI key scan would flag. DefaultEngine.ini pins that section to a placeholder value instead, and the editor keeps it.
Config/DefaultEditorPerProjectUserSettings.ini:
[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
bAutoStartServer=True
ServerPortNumber=8000
ServerUrlPath=/mcp
bEnableToolSearch=True
Config/DefaultEditorSettings.ini (corrected at the 5.9 gate, 2026-11-11: the switch is config=EditorSettings, and in the per-user file above it was ignored on both 5.8.4 and 5.9):
[/Script/UnrealEd.EditorPerformanceSettings]
bThrottleCPUWhenNotForeground=False
This matters a lot. A background editor ticks a few times a second, and every MCP call waits for a tick. Measured: about 330 ms per call with throttling on, 12 to 40 ms with it off.
On 5.9, also: leave ModelContextProtocol out of the .uproject plugin list (5.9 turns it on by default; see the 5.9 results above), and for Epic's Python pattern add to DefaultEngine.ini:
[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
Config/DefaultGame.ini needs this rule. AllToolsets pulls the GameFeatures plugin into the editor, and the editor then asks for an asset manager rule for GameFeatureData. The rule must be editor-only. A runtime rule makes the packaged game fire an ensure at startup ("Failed to load class /Script/GameFeatures.GameFeatureData"), which the smoke test caught.
[/Script/Engine.AssetManagerSettings]
+PrimaryAssetTypesToScan=(PrimaryAssetType="GameFeatureData",AssetBaseClass="/Script/GameFeatures.GameFeatureData",bHasBlueprintClasses=False,bIsEditorOnly=True,Directories=((Path="/Game/Unused")),SpecificAssets=,Rules=(Priority=-1,ChunkId=-1,bApplyRecursively=True,CookRule=Unknown))
Config/DefaultEngine.ini:
-
Target SM6:
-D3D12TargetedShaderFormats=PCD3D_SM5then+D3D12TargetedShaderFormats=PCD3D_SM6. The engine base is SM5 only. Editor templates add SM6, but a hand-made project does not. The SM5 build stalled 40 to 60 s on startup and on exit on this laptop. The SM6 build loads in 4 to 6 s. -
Set
GameDefaultMap,TransitionMapandServerDefaultMapto the real map. Otherwise the cook also pulls in/Engine/Maps/Entry, with a page of missing-plugin warnings.
.claude/settings.json in the project pre-allows the three MCP tools. .mcp.json is generated by the editor (step 2).
2. Start the editor with MCP
powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\start-editor-mcp.ps1 -Project <path>\Game.uproject
What it does:
-
Launches
UnrealEditor.exe <project> -ModelContextProtocolStartServer -ModelContextProtocolPort=8000 -ExecCmds="ModelContextProtocol.GenerateClientConfig ClaudeCode". -
Polls
http://localhost:8000/mcpuntilinitializeanswers andlist_toolsetsshows the editor toolsets. -
Prints both times. The console command writes
.mcp.jsonnext to the .uproject; it is the same as Editor Preferences > Model Context Protocol > Generate Client Config. - Exits 2 if port 8000 is already taken, which means another editor is open.
Measured startup, from launch to MCP answering with toolsets:
| Launch | Seconds | Notes |
|---|---|---|
| First ever | 70 | New project, shaders compiling |
| Second | 55 | Throttle still on |
| Third | 29 | |
| Fully warm | 19 |
Toolsets are ready within 2 s of the server answering. 5.8.3 with All Toolsets exposes 55 toolsets.
3. Prove it end to end (no agent needed)
python prep\scripts\mcp_smoke.py # 5.8
python prep\scripts\mcp_smoke59.py # 5.9: same steps with the renamed tools, and retries on "slow task"
The script does this, reading state back after each step:
-
initialize -
list_toolsets(checks SceneTools and ActorTools are present) -
Spawns
/Engine/BasicShapes/CubeasMCP_SmokeCube - Finds it
- Moves it to (250, -125, 300) and reads the transform back
-
Deletes it and confirms
find_actorsno longer returns it - Re-saves the level if it was clean before
Last run on 2026-11-09: all PASS, 0.5 s total, 11 to 41 ms per call.
For manual pokes, use python prep\scripts\mcp_client.py:
-
ping -
tools -
toolsets -
describe <toolset> -
ucall <toolset> <tool> '<json>'
4. Claude Code connection
-
From the project folder,
claude mcp listshowsunreal-mcp: http://localhost:8000/mcp (HTTP)read from.mcp.json, status "Pending approval". So Claude Code parses the generated config. -
Logged in since 2026-11-11 (Don's account). The 5.9 gate ran its agent checks this way; see the gate result
above for the 5.9
--allowedToolslist and the untrusted-folder note. - The 5.8 headless check is:
claude -p "List the Unreal toolsets, then spawn /Engine/BasicShapes/Cube named CC_TestCube with SceneTools add_to_scene_from_asset, move it with ActorTools set_actor_transform, read it back, delete it, confirm with find_actors." --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__unreal-mcp__list_toolsets,mcp__unreal-mcp__describe_toolset,mcp__unreal-mcp__call_tool"
--mcp-config skips the approval prompt. The login is still needed.
5. How the MCP surface looks (5.8.3, tool search mode)
-
Only three native tools:
list_toolsets,describe_toolset(toolset_name)andcall_tool(toolset_name, tool_name, arguments). -
tool_nameis the short name (add_to_scene_from_asset), not the dotted full name thatdescribe_toolsetprints. -
The most useful toolsets:
-
editor_toolset.toolsets.scene.SceneTools: spawn, find, remove, load level, trace -
editor_toolset.toolsets.actor.ActorTools: transforms, components, tags -
editor_toolset.toolsets.asset.AssetTools: save_assets, is_dirty, find, duplicate -
EditorToolset.EditorAppToolset: PIE start and stop, viewport camera, CaptureViewport -
EditorToolset.LogsToolset: GetLogEntries -
editor_toolset.toolsets.programmatic.ProgrammaticToolset: batches many calls in one sandboxed Python script
-
-
Object references are
{"refPath": "/Game/Map.Map:PersistentLevel.StaticMeshActor_13"}. Pass back exactly what a tool returned. -
Transforms are
{"location": {"x":..,"y":..,"z":..}, "rotation": {"pitch":..,"yaw":..,"roll":..}, "scale": {...}}. Unset fields mean "don't change".
6. Gotchas found today
- A modal dialog blocks MCP completely. While the editor showed "Save Content", every call timed out. If calls suddenly time out, look at the screen. Most often the cause is a dialog, or the editor crashed (an HTTP 502 also means a crash).
-
Spawn then delete still dirties the level, and the next editor close opens the Save dialog (gotcha 1). Save with
AssetTools.save_assetsbefore closing. The smoke script does this. -
"Optional" parameters are not optional.
CaptureViewportwithoutannotationsfails with "input param needs a default value". Pass every parameter in the schema. -
Passing
annotations: {}turns the grid and labels overlay on. - CaptureViewport is expensive. It returns a 1310x557 PNG as base64 inside JSON text, about 557 KB per call. It also takes about 1.2 s. Use it sparingly.
-
Descriptions are big.
describe_toolsetfor SceneTools is 24 KB and for ActorTools 17 KB;list_toolsetsis 13 KB. Agents should describe only the toolsets they need, once per session. - Cooking with the editor open works on 5.8.3. A forum report on 5.8.0 said the cook fought the editor for port 8000. In 5.8.3 the commandlet skips config auto-start, and all of today's packages were built with the editor open.
- Claude Code times out MCP calls at about 120 s. Keep each call short. Run long work (packaging, capture) from scripts, not as one MCP call.
-
One editor per port. A second editor on the same project fails to bind 8000. Use
-Port 8001with the start script for a second project. - Fresh projects have no toolsets until All Toolsets is enabled (5.8.x forum reports, and 5.9 UE-412135). ToolCheck enables it in the .uproject.
- serverInfo comes back with empty name and version. This is harmless. The protocol version is 2025-06-18.
6b. Epic's own pattern: Claude Code, MCP, Python, Geometry Script and PCG (read 2026-11-10)
[line about a named third party removed]
- What he does: turns single-mesh Fab assets into modular, configurable ones inside UE. A desk grows by stacking drawers; a pallet grows by adding planks.
-
How: Claude Code on UE's MCP server, with remote Python execution enabled so Claude reaches Geometry Scripting.
- Claude reads the mesh.
- It labels vertices by part (top, drawers, handles).
- It splits the mesh into repeatable modules and closes the holes the split leaves.
- It generates a PCG graph driven by a spline that reassembles the modules. PCG grammar nodes describe the structure better than Blueprints.
- Effort: 10 to 20 minutes per asset, output used straight from the prompt.
-
What he kept: the know-how lives as a Claude Code skill (
/parametrize) plus a dedicated agent in the project's.claudefolder, improved after each asset. - His advice: "if an Unreal Engine tool is not yet exposed through MCP, it is still reachable through Python scripts."
-
For us:
- Wednesday's gate adds one check: remote Python execution enabled on the 5.9 copy, and one Geometry Script call plus one PCG graph built by the agent, on a CC0 mesh.
- During the jam, write repeat jobs as project skills the same way.
- Mind the rules: sourced assets are unscored, so transforming a Fab asset doesn't make it ours. Credit it either way.
7. Headless packaging
powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\package.ps1 -Project <path>\Game.uproject -TeamName BYOKGames -GameName <GameName> [-Config Shipping]
What it runs:
-
RunUAT BuildCookRunwith-cook -stage -pak -iostore -compressed -archive -nodebuginfo -
-applocaldirectory=<engine>\Engine\Binaries\ThirdParty\AppLocalDependencies, which puts the VC++ runtime next to the exe, so players install nothing (rule 7f) -
-buildonly when the project has aSourcefolder
Then it zips the archive to <OutDir>\TeamName_GameName.zip, with a top folder of the same name. It prints the largest files, the staged size, the zip size and the time of each phase, and writes a JSON summary. Exit codes: 10 = build failed, 12 = zip over -MaxMB (950).
Measured on ToolCheck, final config (SM6, no pdb, editor-only plugins):
| Machine | Config | Build+cook+stage | Zip time | Staged | Zip |
|---|---|---|---|---|---|
| Laptop | Development | 62 s (195 s right after a renderer config change) | 29 s | 627.7 MB | 355.3 MB |
| Laptop | Shipping | 24 to 64 s | 20 to 22 s | 430.0 MB | 290.6 MB |
| Tower 2 | Development (first ever, empty shader cache) | 525 s | 41 s | 626.8 MB | 354.5 MB |
| Tower 2 | Shipping | 64 s | 14 s | 429.1 MB | 289.8 MB |
Tower 2's Shipping zip was copied back (SHA-256 matched) and passed the smoke test on the laptop.
Earlier runs show what each setting costs:
-
The Development
.pdbalone was 280 MB staged (835 MB staged, 357 MB zip with it). Now dropped by-nodebuginfo. -
SM5 only was 118 MB of
.ucas; SM6 is 195 MB.
Where a blank project's size goes (Shipping, 430 MB staged):
- UnrealGame-Win64-Shipping.exe: 158 MB (Development exe: 316 MB)
- Shaders and engine content in the .ucas: 195 MB
- DirectML.dll plus onnxruntime.dll from the default-on NNE plugins: 34 MB
- NVIDIA Aftermath: 5.5 MB
So an empty game is already about 290 MB zipped. That leaves about 650 MB for our content.
Keeping the build small:
-
Submit the Development build. The jam page asks for a "packaged Windows development build" (see
prep/SUBMISSION-KIT.md), and Development fits easily: 355 MB zipped for a blank project. Shipping is about 65 MB smaller. Keep it as a tested fallback only in case size gets tight, and only if Don accepts the risk of reading "development" loosely. - Textures. Cap generated textures at 2048, or 1024 for props: Max Texture Size per texture, or LOD groups. AI image tools output 1024 to 2048 already. Never import 4K or 8K Megascans.
- Nanite meshes. AI 3D output (TRELLIS, Hunyuan) can be 500k+ triangles. Decimate to a sane count before import, because Nanite stores every triangle and disk size grows with it. Lumen and Virtual Shadow Maps cost no disk space, only GPU.
- Audio. Import WAV and let the cook compress it (Bink Audio or ADPCM). Keep voice at 24 to 32 kHz mono, music at 44.1 kHz stereo.
- Video files in Content are stored almost as-is. Keep any in-game video short.
- Compression. Oodle Kraken is set in DefaultGame.ini (distribution level 7). Leave pak plus IoStore compression on.
-
What gets cooked. Only the maps in
+MapsToCook. Delete unused Fab or starter-content folders before the final cook, because anything referenced gets cooked. - Plugins. The NNE DLLs (34 MB staged) come from default-on plugins. Disabling them turns a Blueprint project into one that needs a C++ build (see section 1). Only do it if the project already has C++ code, and smoke test after.
- Check before every upload. The script prints the six largest staged files. Any surprise there is the first thing to fix.
Tower 2 as backup build machine:
-
Tower 2 has 5.8.4 at
G:\Epic_Games\UE_5.8(the script finds it by itself) and 5.9.0 atC:\Program Files\Epic Games\UE_5.9(pass-EngineDir). -
Copy the project with scp: the
.uproject,Config,Contentand (if any)Sourcefolders. Never copy Saved, Intermediate or DerivedDataCache. -
Run the script through
ssh studio-tower2 "powershell -NoProfile -EncodedCommand <base64 UTF-16LE>". - Its first Development cook took 9 minutes (empty shader cache). Prime it once on Nov 12 with the real project.
- Tower 2 has no Visual Studio, so it can only package Blueprint-only projects. A C++ game needs VS 2022 Build Tools there. Installing them means accepting Microsoft's license, so Don does that if we go C++.
- Tower 2 can't run the game window over ssh. Copy its zip back and smoke-test it on the laptop.
8. Smoke test every build (minutes)
powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\smoke.ps1 -Zip <...>\BYOKGames_Game.zip [-Seconds 15]
powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\smoke.ps1 -Exe <...>\Game.exe -Mode Quit # Development only
-Zip extracts to a temp folder, which also proves the zip is whole, and deletes that folder afterwards.
Run mode:
-
Launches the player-facing exe windowed with a fresh
-abslog. -
Waits for
LoadMapin the log (Shipping writes no log, so it waits for a responsive window instead). -
Holds
-Seconds. - Checks the window is still responding, then sends WM_CLOSE (same as clicking X).
-
Requires: exit code 0, no new
Saved\Crashesfolder, no fatal, assert or unhandled exception in the log, and the log past frame 1. Any otherError:orEnsure condition failedline also fails, unless it matches$AllowedErrorsat the top of the script (empty today; add a pattern only with a reason in a comment).
It prints error and ensure counts and the time to the first frame, and exits 1 on any failure.
Quit mode passes -ExecCmds="quit". Shipping ignores ExecCmds, so the script falls back to Run mode there.
Measured on ToolCheck (SM6):
- Development warm: load 4 s, PASS in 21 s; Quit mode PASS in 8 s.
- Development cold (first launch of a new folder): load 6 s, PASS in 55 s.
- Shipping warm: PASS in 32 to 37 s.
- Shipping cold from zip: PASS in 88 s; tower 2's zip PASS in 154 s.
What the long cold times mean for the judges: on the first launch from a new folder, the game runs fine, but closing it waits for background PSO (shader pipeline) compiles. That took 30 to 120 s here. A judge who quits in the first minute will see the window hang before it closes. Fixes for the jam build:
- Target SM6. With SM5 the cold launch itself froze 40 to 60 s.
- Keep a title or loading screen up for the first seconds, so precompiles finish behind it.
- Always smoke the final zip from a fresh folder. That is the judge's first-launch experience.
Two more measured traps:
- Windows throttles a game window that is not in front: 14 to 30 fps in the background against 101 fps in front, same scene. Smoke and capture scripts bring the window forward. If a frame rate looks bad, check focus first.
- A smoke failure caught a real bug today: the GameFeatureData ensure (section 1). It also exposed SM5 as a problem. Trust it.
Files
-
prep/scripts/start-editor-mcp.ps1: start the editor with MCP and wait for it -
prep/scripts/mcp_client.py: small stdlib MCP client -
prep/scripts/mcp_smoke.py: end-to-end MCP check (5.8) -
prep/scripts/mcp_smoke59.py: end-to-end MCP check (5.9) -
prep/scripts/package.ps1: headless package, zip and size gate -
prep/scripts/smoke.ps1: packaged build launch and quit check -
prep/scripts/record-obs.ps1: gameplay video with OBS (seeprep/VIDEO.md) -
prep/scripts/capture.ps1: video-only ffmpeg fallback (seeprep/VIDEO.md) -
prep/agent-rules/UNREAL-AGENT.md: rules for agents driving the editor -
prep/toolcheck/: the throwaway test project (Scripts/make_toolcheck_map.pyrebuilds its map headless)