TickLoop — the AI control surface for Unreal Engine

Drive Unreal Engine 5 with an AI agent. TickLoop is a Model Context Protocol (MCP) server that turns natural-language requests into real editor actions — authoring Blueprints, materials, levels, animation, AI, audio, VFX, UI, and gameplay, live, in a running editor. Built first for Claude Code; works with Claude Desktop, Cursor, OpenAI Codex, and any MCP client. (The name nods to Tick(), Unreal's per-frame heartbeat.)

309 tools. Every one verified live against a real UE 5.7 editor — not mocked.

It drives Unreal over Epic's built-in Python Remote Execution; the core needs zero compilation. A thin, MIT-licensed C++ plugin — installed by default — unlocks the things Python genuinely cannot reach: Blueprint node-graph editing, Behavior Tree graphs, Anim Blueprint state machines, UMG screen UI, Level Blueprint, undo/redo transactions, and real Landscape creation.

Status: alpha, under heavy active development — and already deep.

---

Why it's different

Most "Unreal MCP" servers stop at spawning actors and setting properties. TickLoop authors the things that normally require a human clicking around the editor for hours — and it does it from data:

• 🧠 Behavior Tree graphs — Root → composite → tasks, compiled to a working runtime tree.
• 🚶 Anim Blueprint state machines — states (each with its own animation graph) + transitions, 0 compile errors. The deepest graph in Unreal, authored programmatically.
• 🔊 MetaSound + Sound Cue graphs — node graphs wired and saved, not template copies.
• 🏔️ Real ALandscape with components + heightmap import → procedural terrain by composition (noise material → render target → heightmap).
• 🧩 Deep Blueprint authoring — any K2 node, RPCs, interfaces, event dispatchers, structs/enums, replication, pin wiring, and arrange_bp_graph which lays a graph out by its connections — readable, never stacked at (0,0).
• ⚙️ Universal reflection layer — edit any property, call any UFUNCTION, read any setting. No named tool for it? You can still do it.

Built on three hard rules: native engine features only · composable primitives, not turnkey black boxes · no template duplication. Every tool maps to a real Unreal capability the AI can combine into anything.

---

What it can do — 309 tools

🔌 marks tools that use the default-installed C++ plugin; everything else is pure Python over Epic's remote-execution API.

Area	Tools	Highlights
Blueprints & Level Blueprint 🔌	67	Variables & replication, typed functions / RPCs, structs / enums / interfaces / dispatchers, every K2 graph node, pin wiring, arrange_bp_graph, compile_bp_report.
Materials & shading	23	Master / instance / function / parameter-collection; graph authoring (noise, math, coords → base color / metallic / roughness / emissive / normal), recipes (metal-scratched, wood, …), subsurface profiles, material layers.
Actors, components & world	62	Spawn / transform / attach; components incl. instanced meshes, splines, skeletal-mesh + anim-class, mass override, post-process materials; levels, streaming, world settings; sky / fog / clouds / lights, real Landscape 🔌 + heightmap, scene-capture, 3D text, draw-material-to-render-target, foliage, decals.
Modeling & mesh pipeline	13	GeometryScript mesh creation (primitives, boolean/CSG, merge, simplify, noise-displace, procedural terrain); Nanite, reduction LODs, collision (simple / convex-decomposition), lightmaps.
Animation & AI 🔌	11	Anim BP / montage / blend space (1D + 2D) / aim offset; anim state-machine authoring; Behavior Tree / Blackboard + BT graph authoring; EQS.
Audio & VFX	18	Sound Cue graph + MetaSound authoring; attenuation, reverb, sound mix, submix, sound class, ambient; Niagara create / spawn / params; render-target drawing.
Physics	5	Physical materials, simulate-physics, collision profiles, constraints, mass.
Cinematics	10	Level Sequences — bind actors; transform / visibility / camera-cut / audio / skeletal tracks; spawnables; camera animation.
UI — UMG 🔌	7	Widget Blueprints — build & lay out the widget tree by friendly name, set text / properties, editor-utility widgets, inspect.
Assets & data	17	Find / import / duplicate / rename / save / delete, dependency graphs, audit; DataTables (+ rows), data assets, curves, structs / enums, string tables, render targets.
Paper2D & media	8	Sprites, flipbooks, tilesets, tilemaps; Media Player / Texture / file source.
Gameplay & input	5	Enhanced Input actions & mapping contexts; game mode; force-feedback; navigation.
Play, build & ship	17	PIE (single + multiplayer + simulate); headless build / cook / package / automation; C++ files & UCLASS stubs.
Universal layer & project 🔌	46	Reflection (any property / function / setting), introspection, diagnostics / unreal_doctor, project settings, transactions (checkpoint / rollback), batch & composite macros, Remote Control.

Full per-tool catalog: docs/tools_reference.md — auto-generated from the live registry.

---

Built to be trusted

• Proven end-to-end on a real game. TickLoop authored a complete, playable game — Orb Collector: collectible spinning orbs, scoring, a 60-second timer, win/lose, a HUD, a Game Over screen, and an auto-restart loop — entirely through these tools on the Third Person template, every Blueprint compiling with 0 errors and PIE running with 0 runtime errors. The reproducible build scripts live in scripts/game/.
• Verified live, not mocked. Every tool is exercised against a running UE 5.7 editor — and the deep frontier tools (BT graphs, anim state machines, MetaSound, Landscape) are each confirmed to compile with 0 errors and open in their editors without corruption. scripts/coverage_sweep.py drives the toolset against the editor and reports PASS / SKIP(reason) / FAIL; the reference run is 241 PASS / 50 SKIP / 0 FAIL (SKIPs are tools needing external assets, modals, or a separate process). Tip: on a fresh, shader-compiling project, run the sweep after the editor warms up and in batches — firing hundreds of rapid remote-exec calls at a cold editor can overwhelm Unreal's Python plugin.
• Two-layer testing. A fast offline CI gate (ruff + mypy --strict + 317 pytest tests over an in-process fake bridge, asserting the exact call each tool sends) is the gate that must stay green, plus the live sweep above.
• Safe by default. Every batch is one undo transaction; checkpoint / rollback so an agent can never half-break your project.
• Capability-negotiated. The server probes your editor at startup and only exposes the tools it can actually run — never a confusing hard error.
• Three transports. Live editor (Python remote), HTTP (Remote Control), and headless (cook / package / test with no editor open).

---

⚠️ Warnings & gotchas

• build_editor / package_project build the project's own editor target. On an installed-engine project this can leave binaries the launcher won't load (a Target.cs conflict). Recover by rebuilding the UnrealEditor target. cook_project (-run=Cook, no build) is safe.
• write_cpp_file / create_cpp_class mutate your project's Source/ and need a recompile — on a Blueprint-only project this adds a C++ module. Avoid unless you mean it.
• PIE tools drop the Python-remote connection while Play owns the game thread — reconnect after.
• Plugin-gated tools (Blueprint graph, BT/anim graphs, Landscape, UMG, transactions) need the C++ plugin compiled (the installer does this for you).
• Adding new plugin C++ tools needs a build cycle — close the editor, rebuild the UnrealEditor target (Build.bat UnrealEditor Win64 Development -Project="...uproject" -waitmutex), reopen. Closing the editor with a live remote connection can show a benign Python-plugin shutdown crash — the build still proceeds. (Normal tool use never needs this; only authoring tools in the plugin does.)
• Pace bulk automation on a cold or freshly-created project. Firing hundreds of rapid remote-exec calls back-to-back (e.g. the full coverage sweep) while the editor is still compiling shaders can overwhelm Unreal's Python plugin and crash the editor. Let the editor warm up first and run large batches with a small delay between calls — agents driving the server normally are paced enough.
• Headless tools need UE_ENGINE_DIR set; Remote Control tools need the RemoteControl plugin
  • its HTTP server (:30010).
• Some creators need external assets (a Skeleton for animation, a source file for import).
• Alpha software. Use checkpoint / rollback and version control; review what the AI does.

---

Quick start

uv sync                                      # install
uv run pytest tests/unit tests/integration   # offline test suite (no Unreal needed)

Install into Claude Code (one command)

From inside your Unreal project's folder (so it finds the .uproject):

./scripts/install.ps1     # Windows
./scripts/install.sh      # macOS/Linux

That single command:

• registers the server with Claude Code at user scope — available in every project;
• drops an init_unreal.py so the editor auto-enables Python Remote Execution on next launch;
• copies the TickLoop C++ plugin into the project by default (--no-plugin for the Python-only subset);
• (--with-skills) installs TickLoop's Claude Code skills into ~/.claude/skills/;
• (--with-codex) also registers with OpenAI Codex and installs the same playbooks as Codex prompts.

Preview with -DryRun / --dry-run. Equivalent: uv run tickloop install. Check readiness with uv run tickloop doctor. Then launch the editor and ask Claude to run unreal_doctor first — it reports exactly which capabilities (and tools) are available.

⚠️ If unreal_doctor shows editor: false, enable Python Remote Execution manually. The installer's init_unreal.py auto-enables it on the next editor launch, but it can't if the Python Editor Script Plugin is disabled, the file didn't load, or the setting didn't persist. Turn it on yourself: Edit → Project Settings → Plugins → Python → check Enable Remote Execution, then restart the editor (or, in the editor's Output Log set to Python, run exec(open(r"<repo>/scripts/enable_ue_remote_exec.py").read()) once and restart). The editor then answers discovery on 239.0.0.1:6766 and the live tools connect.

Use with OpenAI Codex

TickLoop is a standard stdio MCP server, so it works with Codex too: uv run tickloop install --with-codex (or register manually — see docs/codex.md). The same two playbooks ship as Codex prompts (/tickloop-usage, /tickloop-planning).

Install on another machine — clone-free

uvx tickloop install                          # from a published PyPI release
uvx --from git+https://github.com/TICKLOOP-UE/tickloop tickloop install \
    --from-git https://github.com/TICKLOOP-UE/tickloop

Clean footprint

uv run tickloop uninstall     # removes the plugin too; --dry-run to preview

Requirements

• Python 3.11+ (Unreal embeds CPython 3.11.8; we match it).
• Unreal Engine 5.4–5.7 (validated live on 5.7; Windows-first, macOS/Linux as a stretch goal).
• For live-editor tools: the Python Editor Script Plugin enabled and remote execution on (the installer handles this, or run scripts/enable_ue_remote_exec.py once in the editor).

The C++ plugin

Editor-only, MIT, ships inside the package and installs by default. It exposes what Python can't reach as UBlueprintFunctionLibrary endpoints the server calls — Blueprint graph editing, Behavior Tree & Anim state-machine authoring, Landscape creation, UMG, and transactions. Pure-Python tools keep working with --no-plugin; plugin-gated tools are simply hidden when the plugin is absent (capability-negotiated, never a hard error). See docs/plugins.md.

Skills (Claude Code)

Two lean, opt-in workflows installed with --with-skills: tickloop-usage (how to drive the whole toolset well) and tickloop-planning (design a feature before building). Tightly scoped to Unreal-via-tickloop, so they stay dormant on other work. See docs/skills.md.

Documentation

• docs/architecture.md — how the pieces fit together.
• docs/install.md — per-version Unreal setup and enabling remote execution.
• docs/claude_code.md — Claude Code config and a first-run walkthrough.
• docs/codex.md — using TickLoop with OpenAI Codex (config + prompts).
• docs/tools_reference.md — auto-generated catalog of every tool.
• docs/plugins.md — the C++ plugin libraries.
• docs/skills.md — the Claude Code skills (and Codex prompts).
• docs/testing.md — how TickLoop is tested (offline + live).

Contributing & requests

TickLoop is open to contributions and requests — they're very welcome.

• Want a tool that isn't here? Open an issue and request it. Coverage grows from real needs — tell us what you're trying to do in the editor.
• Found a bug or a tool that misbehaves on your engine version? File it with the tool name and what you ran; live-editor quirks across UE versions are exactly what we want to hear about.
• Sending a PR? uv sync then uv run pytest tests/unit tests/integration (no Unreal needed); ruff + mypy --strict must stay green, and each new tool ships with an offline integration test. See CONTRIBUTING.md.

License

MIT — free and open source. The Python Remote Execution protocol is implemented natively (Epic's reference client is not vendored). The C++ plugin uses Unreal's public editor API, same MIT license.