Agents on Unreal

1. 01

   Cursor

   Install, sign in. It is a VS Code fork — extensions, themes and keybinds carry over.

2. 02

   Both agents

   They run in the Cursor terminal, against the tree open in the editor.

   # Claude Code — long multi-file runs
   npm i -g @anthropic-ai/claude-code
   claude
   
   # Codex — CLI, or the extension (ID: openai.chatgpt)
   npm i -g @openai/codex
   codex

   Cursor's own agent is Ctrl+I. All three coexist. One rule: one agent per file at a time.

3. 03

   IntelliSense: clangd

   Without it Cursor has no symbol navigation and no macro awareness on a UE project. Generate the compile database with UBT:

   "C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\DotNET\
     UnrealBuildTool\UnrealBuildTool.exe" -mode=GenerateClangDatabase
     -project="D:\Proj\Game.uproject" -game -engine
     GameEditor Win64 Development

   compile_commands.json lands in the engine root — copy it to the project root. Install llvm-vs-code-extensions.vscode-clangd and disable Microsoft's C/C++ IntelliSense; two language servers on one project fight and both crawl.

   The same file also serves Claude Code — this gives it real symbol navigation instead of grep:

   /plugin install clangd-lsp@claude-plugins-official

   Not incremental — the file is rebuilt in full, around a minute. Rerun after adding a module or new .cpp files, not after every build. Dropping -engine from the UBT command shrinks the index a lot, at the cost of navigation into engine code.

4. 04

   Keep junk out of the index

   .cursorignore in the project root:

   Binaries/
   Intermediate/
   DerivedDataCache/
   Saved/
   Content/
   *.uasset
   *.umap

   Intermediate and DerivedDataCache are tens of GB of generated code; Content is binary.

5. 05

   AGENTS.md

   One file in the root, read by both Cursor and Codex. Next to it, a CLAUDE.md containing See AGENTS.md.

   # Game — Unreal Engine 5.7, C++20, IWYU
   
   Build:  Build.bat GameEditor Win64 Development -project=...
   Tests:  UnrealEditor-Cmd.exe ... -ExecCmds="Automation RunTests Game"
   
   ## Rules
   - API is UE 5.7. Never use UE4-era APIs. If unsure of a signature,
     read the header under Engine/Source/Runtime/ — do not guess.
   - Ask before writing. Never batch several file writes into one approval.
   - "X.generated.h" is ALWAYS the last include in a header.
   - Every UObject* member reachable from a UObject must be UPROPERTY()
     or the GC collects it. Use TObjectPtr<T> for members.
   - A new module dependency goes into Game.Build.cs in the same change.
   - Never touch Content/, *.uasset, *.umap — binary, unreadable to you.
   - Files are read-only under Perforce: run `p4 edit <file>` first.
   - Do not reformat files you did not otherwise need to change.

   Add a line every time the agent gets something wrong.

6. 06

   Epic's plugin

   Official Epic plugin for Claude Code — hundreds of tools across 30+ toolsets: actors, blueprints, materials, Niagara, Sequencer, automation tests. It drives a running editor.

   # in Claude Code
   /plugin install unreal-engine-skills-for-claude-code@claude-plugins-official
   
   # in the editor: enable the ModelContextProtocol and AllToolsets plugins,
   # then in the console (default port 8000):
   ModelContextProtocol.StartServer

   Live access to the editor, and execute_tool_script runs arbitrary Python with full project rights. Keep per-action approval on. Submit to Perforce before a long session, not after.

Logic that lives in Blueprints is out of reach: describe the graph, paste a screenshot, or move it to C++. Epic's plugin covers part of this — it talks to a running editor and can read and build graphs — but that is editor control, not repository access.

• Ask what the engine already has, first

  Gameplay Ability System, Subsystems, Enhanced Input, Gameplay Tags, DataAsset, Mass. It has all of Engine/Source and finds these faster than a docs search.

• Ask for options, not an answer

  A single proposal gets shaped to fit your framing. Three with tradeoffs force it to say what is wrong with each.

• Ask "what breaks", not "is this fine"

  It will agree with the second one.

• You are the architect

  Left alone it produces generic designs — extra layers and interfaces for variation the project does not have. Its job is pressure and holes, not the decision.

Prompt to paste:

Task: <...>

Do not propose a solution yet. First:
1. What in UE 5.7 already solves this — with paths under Engine/Source.
2. Three architectures with tradeoffs.
3. What breaks in each: replication, scale, a year of maintenance.
4. What you would ask me before choosing.

Do not touch files. Output: docs/design/<name>.md

Cover per feature: the C++/Blueprint boundary; Actor vs ActorComponent vs Subsystem vs plain UObject; module boundaries and Build.cs dependencies (cycles are painful); what replicates; DataAsset/DataTable vs hardcoded; plugin vs game module.

Commit the doc. Every implementation session starts from it.

• Plan mode first

  Shift+Tab, in both Cursor and Claude Code. It reads the code, asks questions, writes a plan naming files, and waits. A wrong turn here costs a twenty-minute rebuild, not a revert.

• Approve every action by hand

  Do not turn it off. This is where wrong turns get caught — and under Perforce, where other people's files stay out of your changelist.

• One task, one session

  /clear when done. Leftover context degrades answers before it is noticeable.

• Read the whole diff

  Which sets the task size: one reviewable PR per run.

• The build is the test

  Build command in AGENTS.md; let it run and read the errors. It parses UE template errors faster than you do.

• Never let it guess an API

  "Read Engine/Source/Runtime/Engine/Classes/GameFramework/Character.h and follow it" beats "write code using method X".

• Split the agents by job

  Claude Code: long multi-file runs, reading unfamiliar code. Cursor agent: local edits in the open file. Codex: background task.

• p4 edit first

  Otherwise it hits read-only files and invents workarounds instead of saying so.

• Two misses in a row is the prompt

  Reword, add context, narrow scope. A third identical attempt will not work.