UE5 Python Script Development Guide

A workflow-oriented guide for developing reliable UE5 Editor Python scripts.

Prerequisites

[Critical] ue5-visual subagent and ue-mcp server must be available. If not present, refuse to use this skill.

CLI scripts for capture and diagnostics are in scripts/. See Capture Scripts Reference for details.

Development Workflow

Phase 1: Requirements

Clarify requirements with user using AskUserQuestions tool until you have 95% confidence in understanding their intentions.

Phase 2: Planning

Do not implement yet - just plan.

[Critical] Every step implements and tests ONE script. Three types allowed:

Script Types

Testing Protocol

Each script step has three substeps:

• x.1 - Run asset-diagnostic.py to check for issues, fix all errors/warnings
• x.2 - Capture screenshots (orbital/window/PIE based on script type)
• x.3 - MANDATORY: Use ue5-visual subagent to analyze screenshots

Example Plan

For "Create island level with two fighting robots":

## Step 1: Scene-setup - create_island_level.py
Setup island, sea, atmosphere, light, and two robots
- Step 1.1: Run asset diagnostic, fix issues
- Step 1.2: Capture orbital screenshots
- Step 1.3: [MANDATORY] ue5-visual analysis

## Step 2: Configuration - configure_robots.py
Configure collisions, physics, attack abilities
- Step 2.1: Run asset diagnostic, fix issues
- Step 2.2: Capture window screenshots
- Step 2.3: [MANDATORY] ue5-visual analysis

## Step 3: Integration Test - run_in_pie.py
Setup PIE capture, play level, collect screenshots
- Step 3.1: [MANDATORY] ue5-visual analysis

[Critical] Add ALL substeps to todo list using TodoWrite.

Script Organization

Organize scripts in task-specific subdirectory:

${CLAUDE_PROJECT_DIR}/Scripts/<task_name>/
    ├── create_island_level.py
    ├── configure_robots.py
    ├── tmp/                    # Test/debug scripts
    └── screenshots/            # Verification screenshots
        ├── orbital/
        ├── editor/
        └── pie/

Phase 3: Implementation

1. [Critical] Check Common Pitfalls for related documents

2. Follow Best Practices

3. Reference example scripts:

   • Add gameplay tag
   • Create blendspace
   • Create level
   • Customize atmosphere
   • Create blueprint with physics
   • PIE screenshot capturer

4. Use ue-mcp tool editor.execute to run scripts

5. Use ue5-api-expert to verify API usage when unsure

Visual Verification

Presets for orbital capture: orthographic (6 views), perspective (4 views), birdseye (4 views), all (14 views)

See Capture Scripts Reference for full parameter documentation.

[Critical] Do NOT skip visual analysis. Use ue5-visual agent after every capture.

Asset Diagnostic

Run before visual verification to identify issues:

• Use asset_diagnostic Python module via editor.execute
• Check for common issues in levels, actors, and blueprints

Fix all errors and warnings before proceeding. See Asset Diagnostic Reference.

Additional Resources

• Best Practices - Debug visualization, subsystems, transactions, asset registry
• ExtraPythonAPIs Plugin - For socket/bone attachment in Blueprints
• Capture Scripts Reference - CLI parameter documentation
• Editor Capture API - Python module API
• Asset Diagnostic API - Diagnostic module API
• C++ Source Investigation - When Python API is insufficient