Open the books

RAW FILE: UNREAL-AGENT.md, as written during the jam

Source prep/agent-rules/UNREAL-AGENT.md in the jam repo. Last git commit of this file: 2026-11-11. About 970 words. Scrubbed only for private details and one line about another entrant. Mistakes left in on purpose.

Rules for agents driving the Unreal editor over MCP

Read this before your first MCP call. The background and measurements are in prep/MCP-RUNBOOK.md.

Setup

  1. Connection. The editor is started with prep/scripts/start-editor-mcp.ps1. The server is http://localhost:8000/mcp, local only, with no auth. Never expose it, proxy it, or point it at another host.
  2. Check before working. Run python prep/scripts/mcp_client.py ping. If it is unreachable, the editor is closed, still loading (19 to 70 s), crashed, or showing a dialog. Say which one; do not retry in a loop.
  3. The tools. Three native tools: list_toolsets, describe_toolset(toolset_name) and call_tool(toolset_name, tool_name, arguments).
    • tool_name is the short name, for example add_to_scene_from_asset.
    • Describe only the toolsets you need, once per session. Each description is 10 to 25 KB.
    • On 5.9 the surface is renamed (MCP-RUNBOOK, "Engine choice"): four native tools, list_toolsets, describe_toolsets(toolset_names), describe_tools(tool_names) and call_tool. Actors and levels are EditorToolset.ActorToolset and EditorToolset.LevelToolset, assets EditorToolset.AssetToolset. Tool names are PascalCase (AddToSceneFromAsset, SaveAsset), arguments camelCase (assetPath). Python is editor_toolset.toolsets.python_scripting.PythonScriptingTools: call read_me once, then execute_python with script: {"language": "Python", "content": "..."}. The check is prep/scripts/mcp_smoke59.py.
    • 5.9 busy reply. "Not run: the Unreal Editor is running a slow task" means nothing changed. Wait a few seconds and retry; it often follows a save or a compile.

One call at a time

  1. Calls run one by one on the editor's game thread. Never send calls in parallel.
  2. Keep every call short. Claude Code gives up on a call after about 120 s.
    • Long work (cooking, packaging, video capture, mass imports) goes through scripts in prep/scripts, not through one MCP call.
  3. Batching. For many small edits, use ProgrammaticToolset.execute_tool_script. Call get_execution_environment once first, and keep each script to one logical step.

Never open a modal

  1. A modal dialog freezes MCP for everyone until a human clicks it. That includes Save prompts, "Are you sure", import option windows and the Plugins restart prompt. Avoid every action that opens one.
  2. If calls start timing out, stop. Report it and ask for a screenshot or a human.
  3. Never close the editor with unsaved changes. Save first (rule 11); closing a dirty level opens the Save dialog.

Save often, and only what you meant

  1. Before a change:
    • Note the current level: SceneTools.get_current_level.
    • Note whether it is dirty: AssetTools.is_dirty.
  2. After each finished step, save the assets you changed: AssetTools.save_assets with explicit paths. Do this at least every 10 minutes.
    • An empty list saves everything dirty. Use it only when you know what is dirty.
  3. Commit through git by explicit paths after saving. Never use git add -A, git add . or git commit -a.
  4. Don't fight other writers. Do not edit a level another agent is editing. Never save someone else's work-in-progress asset.

Verify everything you change

  1. Read state back after every change:
    • Spawned: find_actors by label returns exactly one.
    • Moved: get_actor_transform matches within 0.01.
    • Deleted: find_actors returns none.
    • Property set: get it again.
    • A tool's returnValue: true is not proof.
  2. Look when it matters, not every step: EditorAppToolset.CaptureViewport.
    • Pass every parameter. Use annotations only when you need the grid and labels.
    • Each image is about 0.5 MB of base64 text. Use it at milestones.
  3. Check the log after risky steps: LogsToolset.GetLogEntries with a narrow pattern, for example Error|Warning.
  4. Before saying a gameplay change works, run it:
    • Play: EditorAppToolset.StartPIE then StopPIE, or
    • Package and smoke test: prep/scripts/package.ps1 then prep/scripts/smoke.ps1.

What to avoid

  1. Pass exactly what tools return. Do not guess object paths or property names; use the refPath you got back. For widgets and objects, list_properties before set_properties.
  2. No engine or editor settings changes without the lead agent's say. Never touch plugins, project settings, renderer settings, or anything that asks for a restart.
  3. No deleting assets or folders except ones you created in this session, by exact path. No wildcard deletes.
  4. No third-party assets pulled in by an agent. No Fab, no Megascans, no web downloads. Sourced assets need Don and a line in prep/SOURCED-ASSETS.md.
  5. Respect the jam rules.
    • Before Nov 12 00:00 ET: no game content at all. Only the ToolCheck project with engine primitives.
    • From Nov 12: everything players see or hear is Teen-rated and in English.
    • No logos or trademarks except the Unreal Engine logo.
  6. Live Coding does not pick up new UFUNCTIONs. After adding one, the editor must restart, and that is a human-approved step.

Level building

Method from Epic's article "Exploring AI-assisted level design in Unreal Engine" (Chris Cook, Nov 11, 2026).

  1. Load prep/LEVEL-CONTRACT.md first, every time. Use its metrics; DEFAULT rows are placeholders, say so if the game has no value yet.
  2. Block out from primitives before final assets. Name actors for what they are. Describe the space by purpose and relationships and leave room to propose.
  3. Capture and inspect after each step with python prep/scripts/scene_capture.py --args '{...}' (top-down, four corners, eye height, plus bounds, gaps and capsule clearance). It uses its own temporary cameras, so the editor viewport stays the user's. Needs bRemoteExecution=True (runbook section 1).
  4. Fix what the captures show: left and right reversals, gaps and slivers, doorway and landing clearances. One fix, then re-capture.
  5. Review at player scale from several angles and walk the routes (checklist in the contract). Furnish, terrain, vegetation and lighting come after the blockout passes.
  6. Write what worked and what failed into the jam's lessons (LESSONS.md entry, with the numbers) so it can become a skill afterwards.

Your report back

  1. List what you changed (assets and actors by path), what you verified and how, and what you saved and committed. Give the exact error text of any failure.