#UECopilot Plugin Documentation

Version: 1.0.0 | Last Updated: 2026-05-08 Target Engine: Unreal Engine 5.4+

#1. Plugin Overview

#1.1 What is UECopilot?

UECopilot is an AI-assisted development plugin integrated into the Unreal Engine 5 editor. Through the Blueprint MCP Server (Blueprint Model Context Protocol Server, UEMCP), it exposes UE5's Blueprint data structures and editing operations as HTTP APIs, allowing AI models (such as Claude, GPT, etc.) to directly read, understand, create, and modify Blueprint assets.

One-sentence summary: UECopilot enables AI to "understand" your Blueprints and operate them for you like an experienced TA/programmer.

#1.2 Operation Mode

#2. Core Capabilities Overview

UECopilot's UEMCP module has been comprehensively expanded and currently provides 130+ MCP tools, covering the following 16 major capability domains:

Capability Rating Descriptions:

• Mature: Full tool functionality, edge cases well handled, SEH protection in place
• Stable: Core paths usable, some boundary conditions to watch for
• Developing: Basic capabilities available, advanced scenarios need improvement

#2.1 What Can It Do? (Scenario Descriptions)

Scenario 1: AI-Assisted Blueprint Debugging

User: "Help me check if there are any disconnected pins in this Blueprint"
AI → calls find_disconnected_pins → returns all unconnected input pins
AI → provides fix suggestions

Scenario 2: AI-Assisted Blueprint Refactoring

User: "Change all function calls referencing OldClass to NewClass"
AI → calls replace_function_calls (supports dry_run preview) → executes replacement

Scenario 3: AI-Assisted Material Creation

User: "Help me create a material with a normal map and color adjustment"
AI → create_material → add_material_expression (TextureSample, Multiply, etc.)
     → connect_material_pins → completes the material network

Scenario 4: AI-Assisted Animation State Machine

User: "Add an Idle→Run transition in this Anim Blueprint"
AI → add_anim_state → add_anim_transition → set_transition_rule

Scenario 5: Safe Experimentation

User: "I want to modify this function parameter type, but I'm worried about issues"
AI → snapshot_graph (take snapshot first) → change_function_parameter_type → if error, restore_graph

Scenario 6: Level Automation Setup

User: "Generate a 10x10 grid of StaticMesh Cubes at the center of the level"
AI → list_actors (check current state) → loop spawn_actor → set_actor_transform
     → focus_actor to view the result

Scenario 7: Automated PIE Runtime Testing

User: "Start the game, teleport the player to the Boss area, and confirm the Boss has spawned correctly"
AI → start_pie → is_pie_running (wait for ready)
     → pie_teleport_player → pie_query_actors(classFilter="Boss") → stop_pie

Scenario 8: Automated Visual Verification

User: "Switch to Wireframe mode, take a screenshot, then switch back to Lit mode"
AI → set_view_mode(mode="Wireframe") → take_screenshot
     → set_view_mode(mode="Lit")

Scenario 9: UMG Programmatic Operations

User: "Add a 'Start Game' button under the Root of WBP_MainMenu"
AI → list_widget_tree → add_widget(widgetClass="Button", name="StartButton")
     → set_widget_property(property="Text", value="Start Game")

Scenario 10: Performance Debugging

User: "Check the current r.Shadow settings and lower shadow quality"
AI → list_cvars(filter="r.Shadow") → set_cvar(name="r.ShadowQuality", value="2")

Scenario 11: Workflow Orchestration

User: "Select the 3 StaticMeshActors in the center, duplicate them and shift 200cm to the right"
AI → begin_transaction("Duplicate actors") → set_editor_selection(["SM_A", "SM_B", "SM_C"])
     → duplicate_actor(offset={x:200}) → end_transaction

#3. System Requirements

• Unreal Engine: 5.4+
• Operating System: Windows 64-bit (fully tested)
• Additional Dependencies: Node.js (for Web UI service, MCP service does not require it)

#4. Usage Guide

#4.1 Recommended Workflow

The recommended workflow follows four steps: "Preview → Snapshot → Execute → Verify":

Step 1: Preview & Analysis
  ├── Use get_blueprint / get_blueprint_graph to understand current state
  ├── Use search_blueprints to search for relevant nodes
  ├── Use get_actor_properties to inspect Actor properties
  ├── Use list_widget_tree to view UMG hierarchy
  └── Use check_pin_compatibility to pre-check pin connection feasibility

Step 2: Create Safety Snapshot
  ├── Use snapshot_graph to save the current graph state
  └── Use begin_transaction / end_transaction to wrap multi-step operations

Step 3: Execute Changes
  ├── Use add_node / connect_pins / delete_node, etc. to edit Blueprints
  ├── Use spawn_actor / set_actor_transform to manipulate the level
  ├── Use add_widget / set_widget_property to modify UMG
  ├── Tools with dryRun parameter should be used for a dry run first
  └── For major changes, use validate_blueprint to check compilation results

Step 4: Verify & Restore
  ├── Use validate_blueprint to verify Blueprint integrity
  ├── Use diff_graph to compare differences before and after changes
  ├── Use get_dirty_packages to check unsaved modifications
  └── If issues arise, use restore_graph to roll back or undo to revert

#4.2 AI Prompt Tips

Good prompt examples:

# Clearly specify the target object
"Add a Print String node to the EventGraph of Blueprint MyCharacter, printing 'Hello'"

# Step-by-step operations
"1. First take a snapshot of MyCharacter's EventGraph
 2. Then change the input parameter type of the MoveForward function from float to double
 3. Finally verify if the Blueprint has compilation errors"

# Query first, then operate
"First list all Blueprints in the project that inherit from Character,
 then tell me their names and paths"

# Level operations
"Select all StaticMeshActors in the current level and get each actor's properties"

Vague prompts to avoid:

✗ "Help me fix this Blueprint" — Which Blueprint? Fix what?
✗ "Add a feature" — What feature? Where to add it?
✗ "Modify the material" — Which material? Change it to what?
✗ "Run it" — Start PIE? Validate Blueprint? Search assets?

#4.3 Usage Notes

1. MCP service is not head-safe: Although SEH (Structured Exception Handling) protection is used, erroneous operations in extreme cases could still cause the editor to crash. It is recommended to save the project and back up important Blueprints before operating.

2. All write operations support Ctrl+Z undo: The server wraps each write operation in an Undo transaction, but it is recommended to manually save promptly after continuous operations.

3. Snapshots are saved to disk: Snapshot files are stored in the Project/Saved/BlueprintMCP/Snapshots/ directory and are not included in project version control. Manual backup is recommended for important operations.

4. AI model differences in understanding UE terminology: Different AI models may have varying understandings of UE-specific terms (such as "pin connection", "break struct", "event dispatcher"). Please use UE5 official terminology in your prompts.

5. Editor Mode vs Commandlet Mode differences:

   • In Editor Mode, PIE/Viewport/Level/Actor tools are fully available
   • In Commandlet Mode, only Blueprint layer and CVar tools are available (no World context)

#5. MCP Tools Complete Reference

Note: The following lists all MCP tools that can be directly invoked through AI conversation. Tool names use snake_case convention. You can use these tool names directly in your prompts.

#5.1 Blueprint Retrieval & Reading (8 Tools)

#5.2 Blueprint Node Editing (15 Tools)

#5.3 Blueprint Variable System (6 Tools)

#5.4 Function & Parameter Management (4 Tools)

#5.5 Blueprint Structure & Metadata (9 Tools)

#5.6 Component System (3 Tools)

#5.7 User-Defined Types (4 Tools)

#5.8 Material System (18 Tools)

Material Reading:

Material Writing:

Material Instances:

Material Functions:

Material Safety:

#5.9 Animation Blueprint System (12 Tools)

#5.10 Safety & Snapshot System (6 Tools)

#5.11 Asset Discovery & Reflection (5 Tools)

#5.12 Level & Actor Management (v2 New, 16 Tools)

#5.12.1 Basic Actor Operations

#5.12.2 Actor Component Operations

#5.12.3 Material Operations on Actors

#5.12.4 Level Management

#5.12.5 Level Blueprint Management

#5.13 PIE Runtime Control & Query (v2 New, 7 Tools)

Supported Play Modes:

#5.14 Viewport Camera & Rendering (v2 New, 9 Tools)

#5.14.1 Viewport & Camera Control

#5.14.2 View Mode & Visual Settings

Supported View Modes:

#5.14.3 Screenshot

Screenshot save path: {Project}/Saved/Screenshots/

#5.15 Editor Tools & Selection (v2 New, 11 Tools)

#5.15.1 Editor Selection Management

#5.15.2 Content Browser

#5.15.3 Editor Utilities

#5.15.4 Undo/Redo

All MCP write operations executed between begin_transaction / end_transaction will be grouped into a single atomic undo action.

#5.16 UMG Widget Management (v2 New, 7 Tools)

Common Widget Classes: TextBlock, Button, Image, VerticalBox, HorizontalBox, Overlay, CanvasPanel, Border, SizeBox, ScaleBox, ScrollBox, Spacer, ProgressBar, Slider, CheckBox

#5.17 CVar & Output Log (v2 New, 5 Tools)

#5.17.1 Console Variables (CVar)

Supported Modes: Editor Mode and Commandlet Mode. Note that some CVars may require an editor restart to take effect.

#5.17.2 Output Log

The first call to get_output_log automatically starts log capture. Log filtering supports matching by message/category text, or filtering by severity level (Error / Warning).

#5.18 Asset Special Operations (v2 New, 8 Tools)

#5.18.1 Groom Hair Binding

#5.18.2 Skeleton & Socket

#5.18.3 Console Command

#5.18.4 Level Gameplay Snapshot

#5.19 Workflow Resources (MCP Resources)

In addition to Tools, the TypeScript MCP Server exposes two read-only Resources for AI to consult before working:

#5.20 Utility Functions & Safety Mechanisms

Type Resolver (ResolveTypeFromString)

Supported type resolution formats:

SEH Safety Protection (Windows Only)

For high-risk operations (Blueprint compilation, material expression addition, package saving, etc.), the __try/__except Structured Exception Handling (SEH) mechanism is used. This means that even if an operation causes an internal engine crash (such as an access violation), the service will not completely crash, but will instead return an error message.

Undo Transaction Support

All tool calls that modify Blueprints are wrapped in Undo/Redo transactions. This means that when used in the editor, operations executed by AI can be undone with Ctrl+Z.

#6. Usage Boundaries & Limitations

#6.1 Known Limitations

#6.2 Unsupported Scenarios

1. C++ Code Operations: Cannot create or modify C++ code files
2. Runtime Breakpoint Debugging: Does not support breakpoints, step execution, or other debugging features
3. Multi-User Collaboration: No concurrency control mechanism
4. Content Migration: Does not support cross-project content migration
5. Source Control: Does not directly interact with Perforce/Git/SVN
6. Packaging & Build: Does not support packaging, cooking, or other build workflows
7. DataTable Operations: DataTable/CurveTable editing is not currently supported
8. Niagara System: Does not support Niagara particle system operations

#6.3 Safety Boundaries

✅ CAN DO:
   · Read/create/modify Blueprint, Material, Anim Blueprint assets
   · Create structs and enums
   · Take safety snapshots and restore
   · Spawn/delete/modify Actors in the level
   · Start/stop/pause PIE and query runtime state
   · Control viewport camera and rendering modes
   · Take viewport screenshots
   · Create and modify Widget Blueprints (UMG)
   · Read and write CVar console variables
   · Read and filter output logs
   · Navigate the Content Browser and open asset editors
   · Manage editor selection state
   · Perform batch operations with atomic undo

❌ SHOULD NOT DO:
   · Expose the editor to external network access
   · Make bulk modifications without version control
   · Rely on AI to fully understand the semantics of complex graph structures
   · Use directly on critical nodes without testing

⚠️ USE CAUTION:
   · Changing the parent class of an existing Blueprint (may cause extensive disconnections)
   · Batch renaming/deleting assets
   · Changing variable types (may disconnect existing connections)
   · Large-scale modifications in Anim Blueprint state machines
   · Deleting Actors during PIE runtime (may break game logic)

#7. Conversational MCP Operation Prompt Accuracy Challenges

#7.1 Core Challenges

Using natural language through AI models to operate UE5 Blueprints presents the following core challenges:

#Challenge 1: Loss of 3D Semantics in Graph Structure

A Blueprint graph is a 2D visual structure. AI can only see a flat JSON node list, losing spatial information such as:

• Node positions and layout (proximity implies logical grouping)
• Visual grouping through comment boxes
• Execution flow direction (left-to-right, top-to-bottom conventions)
• Color cues (node type indicators, execution wire colors)

Impact: AI struggles to understand the "design intent" of a graph and can only see structured connection data.

#Challenge 2: Implicit Knowledge of Pin Types

Pin types in UE5 are a complex system:

Impact: AI may provide semantically incorrect pin pairings when constructing connect_pins requests.

#Challenge 3: Cascading Effects of Changes

A simple modification can trigger a chain reaction:

Changing variable type (int → float)
  → All Get/Set node output pin types change
    → Nodes connected to these pins may disconnect
      → Downstream node input values become invalid
        → Compilation produces warnings or errors

Impact: AI struggles to fully predict all cascading effects of a change, even with dryRun support.

#Challenge 4: Ambiguity of UE Terminology

Impact: AI may confuse terminology across different contexts, leading to incorrect request parameters.

#Challenge 5: Session State Maintenance

Round 1: AI → "List all Blueprints"
          Service → returns 50 Blueprint names

Round 2: AI → "Open the first one"
          Problem → Which "first one"? The user needs to maintain conversation context

Impact: The plugin itself is stateless; each tool call is independent. The AI model needs to maintain state within the conversation, but the context window is limited.

#7.2 Current Mitigation Strategies

Mitigation measures already implemented at the plugin level:

1. Detailed error messages: Returns specific error reasons and available options when operations fail (e.g., lists of available pin names, graph names, etc.)
2. dryRun mode: Key modification operations support preview mode, returning impact analysis
3. Snapshot mechanism: Supports pre-operation snapshots with post-operation restoration
4. SEH protection: Crash protection in extreme cases

#10. FAQ & Troubleshooting

#10.1 Operational Issues

Q: Changes to a Blueprint are not taking effect

1. Check if the saved field in the returned JSON is true
2. Manually save the asset in the editor (Ctrl+S)
3. Reopen the Blueprint graph to see changes

Q: Blueprint compilation errors

1. Use the validate_blueprint tool to see specific error messages
2. If a snapshot exists, use restore_graph to restore
3. Or use Ctrl+Z to undo in the editor

Q: AI cannot find the specified Blueprint

1. Ensure the Blueprint name is correct (case-sensitive)
2. Use the list_blueprints tool to see all available Blueprints
3. Level Blueprints need to be referenced by the map name

Q: Level Actor operations fail ("requires editor mode")

1. Confirm the UE5 editor is running (not commandlet mode)
2. Check is_pie_running — editor mode operations cannot execute during PIE runtime
3. Confirm a level is currently open (not an empty world)

#10.2 Performance Issues

Q: First call to list_blueprints is slow The first call triggers a full asset registry scan. Subsequent calls use caching and will be faster.

Q: PIE operations start slowly PIE startup requires compiling the level and loading assets. Use is_pie_running to poll and wait for the ready state.

#11. Appendix: Capability Statistics

#11.1 Overview Data

#11.3 Type Support Coverage

#Conclusion

UECopilot's goal is to become a powerful co-pilot for UE5 developers — not to replace your judgment, but to help you complete repetitive tasks faster, reduce human errors, and maintain operational accuracy and traceability in large projects.

Recommendations for users:

• Start small: Try it out on simple Blueprints first
• Make good use of snapshots: Take a snapshot before any major operation
• Progressive adoption: Start with reading → simple modifications → complex creation → full Level/PIE workflow, gradually going deeper
• Leverage transactions: Use begin_transaction / end_transaction to group multi-step operations into atomic undo actions
• Provide feedback: If you encounter issues, please provide detailed logs to help the plugin improve continuously

UECopilot - Empowering Unreal Engine development with AI wings