unreal-harness

Set up an automated, agent-observed end-to-end test (or a guarded dev loop) for an Unreal feature in this harness. Use when someone wants to "add a test", "test this feature end-to-end", "verify X works in PIE", "build a verification harness", "guard this feature with a test", or "make a guardrail loop for an agent building X". Opinionated: the engine constructs the scenario via typed C++ primitives, the agent observes the behaviour it controls through a DIFFERENT read primitive, no mocks, headless-first. Encodes docs/TESTING.md.

Get this repo configured to run on the user's machine. Use when someone has just cloned/opened the Unreal Engine MCP repo and wants to set it up, "onboard", get started, or install its dependencies. Covers three things — (0) a dependency survey + install walkthrough (minimal vs full vs custom profile; C++ toolchain, uv/tests, Neo4j/Docker, GIMP, Pulumi/AWS, API keys), (1) locating the user's Unreal Engine install (UNREAL_ENGINE_ROOT), and (2) wiring this repo's plugin into the user's UE project so the MCP drives this code, plus setting UNREAL_PROJECT_ROOT. Invoke on requests like "onboard me", "set this up", "help me get configured", "install the dependencies", "where's my engine", "wire up the plugin".

Turn a project's accumulated QA screenshots (projects/<Game>/Saved/Screenshots/**) into a development-story video — a curated, narrative-ordered slideshow that accelerates through the debug era, eases out to linger on the polished shots, crossfades throughout, and ends by dissolving into a real gameplay clip. Covers the whole pipeline: mining the screenshot folder + project docs (GDD/PLAN/STATUS) for the story arc, agent-verifying every candidate frame (drop contentless frames, KEEP funny bugs — errors preceding a good version are the story), moving keepers into named narrative groups, and generating the ffmpeg xfade chain with a tunable pacing curve — plus optional composition layers: a 3-column strip of dev screen-recordings riding above the main pane (1x speed, sampled), a pan-out camera revealing labels (repo URL, attribution, cost, fading credits) in the side black space, and a dual-aspect render emitting 16:9 and phone-native 9:16 cuts in one pass. Use when someone wants a "progress video", "dev timelin

Write or update an architecture document for an Unreal Engine system — a conceptual spec a senior engineer can build from. Use when someone wants to "document this system", "write an architecture doc", "spec a feature before building it", "describe how X works for the team", or "update the docs to match the code". Plan-only and code-free: it researches the live editor, Blueprints, and source, then writes a Design-level document about intent, boundaries, contracts, and invariants — no implementation, no builds, no editor mutation. Works in any UE project, not one studio's house style.

Create a new Unreal Engine project under projects/ wired to this repo's UnrealMCP plugin and pre-configured with the recommended engine built-in plugins (Niagara, Water, GeometryScripting, GAS, StateTree, animation, runtime mesh, etc.), and give the project its own agent-facing CLAUDE.md. Use when someone wants to "bootstrap a project", "make a new UE project", "scaffold a test/sandbox project", get a fresh project to drive with the MCP, or "write a CLAUDE.md for this game". Produces a minimal C++ host project that loads the plugin from this repo (no copy) and builds against the engine at UNREAL_ENGINE_ROOT. Asks the intended architecture (C++-first vs Blueprint-first, single- vs multiplayer) and writes a project CLAUDE.md tuned to the answers; can also adopt an existing project by exploring it and writing a CLAUDE.md that describes it.

Build an Unreal Engine project across its flavors — the editor target for local play-in-editor (PIE), a standalone/packaged Windows client, and a dedicated server (local dev or a cooked Linux build for remote/cloud hosting). Use when someone wants to "build the game", "build the editor", "compile the project", "package for Windows", "cook content", "make a client/server build", "build the dedicated server", "make a shipping build", "build for the cloud/GameLift", or asks which build command they need and what config/platform to use. Generic across any UE project with similar Editor/Game/Server target architecture — it derives names from the project, hardcodes none. Knows the compile-vs-cook-vs-package distinction, the target matrix, and the constraints that silently break builds.

Turn a human-framed editor viewport into a reproducible, automated IN-GAME screenshot. The human positions the level-editor camera on whatever they want to see; this records that exact pose (location/rotation/FOV/aspect) and reproduces it inside the running game (PIE) through the real game render path — no character driving, no camera flying — saving the shot so any later run can re-capture the identical view with zero human input. This is the sanctioned way to build the "fixed capture rig" that CLAUDE.md / docs/TESTING.md require before any screenshot-based visual validation. Use when someone says "capture this view", "record my camera", "snapshot this framing in-game", "set up a repeatable shot of X", "make a capture rig for this", or "I framed it — grab it in the game". Pairs with /visual-critique for judging the captured frame (against a reference image or a written spec).

Build and maintain a game project's architecture-documentation system — a bidirectionally-navigable, code-synced knowledge base genericized from a production UE reference project's two-taxonomy model. One namespace, three modes. `/docs taxonomy` builds the FORWARD taxonomy (the file-by-file source atlas TAXONOMY.md + doc router INDEX.md, for top-down navigation). `/docs reverse` builds the REVERSE taxonomy (backward-reference CLAUDE.md files that point a leaf folder up to its owning doc + an ANNOTATE.md backlog of undocumented systems). `/docs audit` is the SYNC loop (verify each doc against the code, one per pass, with a resumable ledger). Use for "build a taxonomy / index the codebase / source atlas", "add folder pointers / annotate the source tree / stop agents drifting off-architecture", "audit the docs / check docs against code / find stale docs". Markdown-only — no source edits, no editor mutation. Generic across any UE project (C++-first, Blueprint-first, or with a TS backend); derives source roots fro

Advise on integrating AWS GameLift (GameLift Servers) — choosing a hosting model, designing game session queues and FlexMatch matchmaking, and deciding how much of the match/place/run lifecycle to own vs delegate to AWS. Use when someone asks "how do I set up a GameLift queue", "add matchmaking", "how should we host dedicated servers", "do we need FlexMatch", "custom control plane vs AWS-native", "why are placements timing out", or wants to understand GameLift's hosting/placement model before building. Neutral, vendor-fact-grounded, code-free advisor — not a code generator.

Import a layered GIMP composition (.xcf) into Unreal as correctly-configured UTexture2D assets and wire it up — in one of two modes. MOCKUP mode recreates a GIMP-authored UI/HUD layout as a UMG widget one time (tight-crop + anchor math, the user fine-tunes after). CONTRACT mode establishes a LIVING layered asset — a layer-NAMING GRAMMAR, co-registered full-canvas exports with zero placement math, a COMMITTED reproducible export script + manifest, and optional CPU hit-mask/bounding-box sidecars for irregular-shape interaction (maps, state overlays, drill-down UI). Use for "import the HUD from GIMP", "bring my GIMP layers into Unreal", "re-import the touched-up art", "set up a layered map/overlay pipeline", "make the GIMP export repeatable", "hit-test the painted regions". Driven live over the GIMP MCP + UnrealMCP, or headlessly via gimp-console-3. NOT an art generator — it moves existing layers; pair with /icon or /see for art/measurement.

Produce a UI icon end-to-end for any UE project — pick the art style (object / glyph / glyph-mono), generate the art (GPT image gen → background removal → downscale to a crisp transparent PNG), review it on a checkerboard contact sheet, import it as a correctly-configured UTexture2D (sRGB + EditorIcon), then wire/display it (data-asset field, hardcoded path, or the bundled IconWidget) and verify it renders. Handles one icon or one coherent family (a glyph set, a category set) per run. Dispatch when an icon is missing/broken/wrong, or to generate a new set. NOT a project-wide icon audit.

Render a "press this key" indicator on screen — a glyph (letter / SPACE / SHIFT / LMB) painted on a key-shaped tile (a keycap, square, or pill texture). Use when a project needs keypress hints, input prompts, a controls overlay, a tutorial "press W/A/S/D" row, or any "show the player which key to press" UI. Owns the hard part — placing a glyph on a beveled cap's TOP FACE (not its box center), sizing the font and cap so it reads as a label, swapping square↔wide by label length, and an optional looped press-down call-to-action. Genericized to any project: it references no specific keycap art — you supply the texture and measure it with the `/see` skill. Ships a drop-in C++ UMG widget template and the layout math a consumer uses to size it.

Project a live Unreal project's assets — Blueprints, StateTrees, materials, Niagara, data tables — into a Neo4j graph database so their topology becomes queryable with Cypher. Use when someone wants to "dump/ingest assets into Neo4j", "graph the Blueprints", "build a Blueprint/StateTree graph", "query the project as a graph", "trace an execution/data-flow chain", "find all callers of X across Blueprints", "set up Neo4j for this project", or "index the AI StateTrees". Generic across ANY project driven by this harness — it reads through the harness's canonical MCP read tools and derives the asset set from the live project; it hardcodes no game-specific assets, paths, or schema. A read-only analysis projection, never a mutation path.

Advise on Unreal Engine multiplayer networking and replication — choosing a replication system (Iris vs legacy vs Replication Graph), picking the right device per kind of state (replicated property vs RPC vs custom serialization vs nothing), and the server-authority/prediction/validation discipline that makes networked state correct. Use when someone asks "how should we replicate X", "do we need Iris", "property or RPC", "why is movement rubber-banding", "how do we do hit registration / lag compensation", "how should multiplayer be architected", or "do we need custom netcode". Neutral, UE-fact-grounded, code-free architectural advisor — not a code generator.

Advise on how to architect complicated NPC / creature / enemy AI in Unreal Engine — the layered model (multi-sense perception → pawn-side awareness memory → StateTree decision → action execution → data-asset tuning) and how to turn a behavior spec into that structure. Use when someone wants to "design enemy/creature/companion AI", "structure AI behavior", "how should I use StateTree for AI", "add perception/senses", "build an AI to this spec", "why is my AI flickering between targets", "should this be a StateTree task or a condition", or "how do I keep AI logic out of the tree". Neutral, UE-fact-grounded, design-level advisor — it teaches the architecture and helps you shape it to spec; it is not a creature/game-specific behavior library and not a code generator.

Specialist for reasoning about the position, orientation, and spatial geometry of objects in an Unreal Engine world — actors, the camera, skeletal-mesh bones, sockets, attached meshes, and projectiles. Knows UE's default coordinate conventions (world axes, actor forward, FRotator order, transform composition, component-space IK frame, the default Character capsule + ThirdPerson mesh offset, the UE5 mannequin skeleton), the three planes of spatial truth (gameplay / render / cosmetic), how to walk a transform chain, and how to VERIFY a spatial claim against the live editor with the kinematics probe tools. Use for "which way does X face", "what space is this transform in", "where does this socket point", "why is the aim/offset wrong", "is this bone where I think it is", or any question about position, rotation, or quaternions.

Run a disciplined, document-driven refactoring loop on a game (or on the harness's own Bun/TS code) — DRY/functional C++ extraction, TypeScript service de-duplication, UMG/Slate widget consolidation, or feature-first project/asset structure. Genericized from a production UE reference project's proven refactor loops. One namespace, four modes. The loop is anchored to a worklist document with three areas — TODO / DONE / DEFERRED — and processes exactly ONE logically distinct refactor per iteration under a strict architectural-purity + scope contract (zero behavior change, no new abstractions, locality of behavior, bias toward leaving things alone). Use for "refactor this", "DRY up X", "de-duplicate the widgets", "extract the math/logic", "split a 600-line file", "clean up the service layer", "restructure the Content tree", "find extractable utilities". Behavior-preserving only — it never adds features. Complements `/architect` (writes the design) and `/docs` (keeps the taxonomy synced).

Analyze an image/texture to understand its REAL geometry — true (trimmed) dimensions ignoring transparent padding, the opaque content bounds, the solid interior that's safe to render content/text over, the bright field vs a dark/burnt rim, edge feathering, shape, and whether it will distort if stretched to a target size. Returns resolution-independent fractions + pixels as JSON AND an annotated proof PNG, and self-verifies. Dispatch BEFORE placing UI content over an image, sizing/scaling a sprite or background, choosing UMG OverlaySlot/Canvas padding for a transparent texture, deciding stretch-vs-9-slice, or any "what part of this image is actually drawable / how big is the real content / where's the transparency" question. Pure analysis — does NOT import assets, edit textures, or touch Unreal (hand its numbers to whatever wires the widget — e.g. the `key-indicator-helper` skill for keypress glyphs).

Generate a tileable PBR texture set with local Python (numpy/PIL) AND land it as real Unreal assets over the MCP. Pass the full Python source as the argument — the skill stages and runs it, then imports the resulting PNGs to /Game/Generated/<slug>/, builds (or reuses) a master material, creates a per-slug Material Instance, and produces TestSphere + TestCube preview meshes wired to that MI. Use for procedural PBR sets (stone/metal/fabric/…), mesh-bake helpers, or any local Python that ends with files under assets/textures/. The decisive reason to bake a texture instead of computing noise live in a material: a baked texture has a MIP CHAIN, so it filters cleanly at distance/grazing/top-down — live shader noise has no mips and aliases into shimmer/crawl.

External, grounded critic for a RENDER against a DESIRED STATE that is EITHER a reference IMAGE or a written TEXT spec — one skill, two modes. IMAGE mode (--reference <img>): art-direction comparison — sends the reference + the render to Gemini and returns a calibrated, rubric-scored breakdown of what matches and what differs, per element, with engine-specific fixes. SPEC mode (--desired "<text>"): adversarial spec-conformance — decomposes the written desired state into independently-checkable attributes ("crimson", "square", "centered") and reports DESIRED vs OBSERVED with a pass/fail verdict and a specific fix per attribute. Honest, not performatively harsh: every cited difference is grounded in what is actually visible, and genuine matches are credited. Use whenever you must judge whether a render matches a target — a concept image OR a description — and want a second opinion beyond your own eyes; drives a render -> critique -> fix loop and can gate it on a numeric score. Triggers: "compare to the concept"