Unreal Python Scripting

---
name: unreal-python-scripting
description: Python API patterns for Unreal Engine 5.8 including Blueprint spawning, material workflows, component manipulation, and API limitations workarounds. Use when scripting Unreal, creating Python tools, encountering API limitations, or when user mentions unreal python, blueprint spawning, material instance, component properties, python api limitations, ue python.
allowed-tools: mcp__ue58-mcp__execute_python_code,mcp__ue58-mcp__call_tool,Read,Write,Grep
---

# Unreal Python Scripting

**Version:** 2.0.1
**Last Updated:** 2026-09-08
**Target:** Unreal Engine 5.8+
**Dependencies:** unreal Python module (built-in), UE 5.8 native MCP (HTTP, port 8000)

> **Preflight first (2026-09-08):** before the first build step of any approved plan, run the `unreal-project-preflight` skill (`ue_preflight.py --live --features <list> --plan-block`) so plugins and project settings this skill depends on are enabled in ONE restart. Mid-task "class not found / plugin not enabled" errors go back to that Step 0, never to a runtime toggle.

---

## MCP Execution

All Python code runs via `mcp__ue58-mcp__execute_python_code(code=...)` which executes directly in the UE editor process. VibeUE toolsets are also available via `mcp__ue58-mcp__call_tool(toolset_name=..., tool_name=..., arguments={...})`.

Use `mcp__ue58-mcp__discover_python_module(module_name="unreal")` to introspect available Python API.

---

## Quick Start

### Spawn Blueprint Actor
```python
import unreal

# Load Blueprint (_C suffix required!)
bp = unreal.load_class(None, "/Game/BP_Actor.BP_Actor_C")

# Spawn
actor = unreal.EditorLevelLibrary.spawn_actor_from_class(
    bp, location=unreal.Vector(0, 0, 100)
)

# Access component
comps = actor.get_components_by_class(unreal.StaticMeshComponent)
if comps:
    comps[0].set_editor_property('mobility', unreal.ComponentMobility.MOVABLE)
```

### Create Material Instance
```python
import unreal

# Load master
master = unreal.load_asset("/Game/Materials/M_Master")

# Create instance
tools = unreal.AssetToolsHelpers.get_asset_tools()
instance = tools.create_asset(
    "MI_Shot001", "/Game/Materials/Instances",
    unreal.MaterialInstanceConstant,
    unreal.MaterialInstanceConstantFactoryNew()
)

# Set parent
instance.set_editor_property('parent', master)

# Override parameters
unreal.MaterialEditingLibrary.set_material_instance_texture_parameter_value(
    instance, 'BaseColor', unreal.load_asset("/Game/Textures/T_Tex")
)
unreal.MaterialEditingLibrary.set_material_instance_scalar_parameter_value(
    instance, 'Opacity', 1.0
)
```

### Set Component Properties
```python
import unreal

# Get selected
actors = unreal.EditorLevelLibrary.get_selected_level_actors()
if actors:
    # Find camera component
    cams = actors[0].get_components_by_class(unreal.CineCameraComponent)
    if cams:
        cams[0].set_editor_property('current_focal_length', 35.0)
```

---

## Standard Workflows

### Workflow 1: Spawn Blueprint with Component Access

**Pattern:**
1. Load Blueprint class with `_C` suffix
2. Spawn via EditorLevelLibrary
3. Find component with `get_components_by_class()`
4. Set properties with `set_editor_property()`

**Key Points:**
- `_C` suffix is REQUIRED: `/Game/BP.BP_C`
- Returns list even if single component (check `if components:`)
- Component properties are case-sensitive

---

### Workflow 2: Create Material Instance from Master

**Pattern:**
1. Load master material asset
2. Create MaterialInstanceConstant via AssetTools
3. Assign parent with `set_editor_property('parent', master)`
4. Override parameters with MaterialEditingLibrary

**Key Points:**
- Use MaterialEditingLibrary for parameters (NOT `set_editor_property`)
- Parameters must exist in master material
- Save asset with `EditorAssetLibrary.save_loaded_asset()`

---

### Workflow 3: Batch Create Material Instances

**Multi-Shot Pattern:**
```python
master = unreal.load_asset("/Game/Materials/M_Master")
tools = unreal.AssetToolsHelpers.get_asset_tools()

for shot_num in range(1, 51):
    instance = tools.create_asset(
        f"MI_Shot{shot_num:03d}",
        "/Game/Materials/Instances",
        unreal.MaterialInstanceConstant,
        unreal.MaterialInstanceConstantFactoryNew()
    )
    instance.set_editor_property('parent', master)

    # Override texture per shot
    texture = unreal.load_asset(f"/Game/Textures/Shot{shot_num:03d}/T_Base")
    unreal.MaterialEditingLibrary.set_material_instance_texture_parameter_value(
        instance, 'PlateTexture', texture
    )
```

**Naming:** `MI_Shot001`, `MI_Shot002`, etc.

---

### Workflow 4: Component Property Batch Setting

**Pattern:**
```python
# Select multiple actors in editor first
actors = unreal.EditorLevelLibrary.get_selected_level_actors()

for actor in actors:
    lights = actor.get_components_by_class(unreal.PointLightComponent)
    for light in lights:
        light.set_editor_property('intensity', 5000.0)
        light.set_editor_property('light_color',
            unreal.LinearColor(1.0, 0.8, 0.6, 1.0)
        )
```

**Handles:** Missing components gracefully (empty list)

---

### Workflow 5: Work Around API Limitations

**Problem:** Some component registration methods not available in Python

**Workaround:**
- Use Blueprint actor with pre-configured components
- Component hierarchy must be defined in Blueprint

**Example:**
```python
# Use Blueprint-based approach
bp = unreal.load_class(None, "/Game/BP_CameraWithPlate.BP_CameraWithPlate_C")
actor = unreal.EditorLevelLibrary.spawn_actor_from_class(bp, ...)
# Components already configured in Blueprint
```

**See:** `reference/api_limitations_ue55.md` for complete list

---

## Troubleshooting

### Issue 1: "Blueprint Class Not Found"

**Symptom:** `TypeError: 'NoneType' object is not callable`

**Fix:**
- Add `_C` suffix: `/Game/BP_Actor.BP_Actor_C`
- Copy reference from Content Browser (right-click -> Copy Reference)
- Use forward slashes `/` not backslashes `\`

---

### Issue 2: "Component Property Not Settable"

**Symptom:** `AttributeError: property not found`

**Fix:**
- Check property name (case-sensitive)
- Use `dir(component)` to list available properties
- Some properties are C++ only

---

### Issue 3: "Material Parameter Not Updating"

**Symptom:** Parameter set but material doesn't change

**Fix:**
```python
# WRONG
instance.set_editor_property('BaseColor', texture)

# CORRECT
unreal.MaterialEditingLibrary.set_material_instance_texture_parameter_value(
    instance, 'BaseColor', texture
)
```

**Rule:** Always use MaterialEditingLibrary for material instance parameters

---

## Key Patterns

### Blueprint Loading
```python
# Pattern: _C suffix required
bp = unreal.load_class(None, "/Game/Path/BP_Name.BP_Name_C")
#                                       ^ Repeat name with _C
```

### Type Coercion
```python
# Vector
unreal.Vector(x, y, z)

# Rotator (pitch, yaw, roll)
unreal.Rotator(0, 90, 0)

# Color (RGBA, 0.0-1.0)
unreal.LinearColor(1.0, 0.0, 0.0, 1.0)
```

### Asset Creation Pattern
```python
tools = unreal.AssetToolsHelpers.get_asset_tools()
asset = tools.create_asset(
    asset_name="AssetName",
    package_path="/Game/Folder",
    asset_class=unreal.AssetClass,
    factory=unreal.FactoryClass()
)
```

---

## Reference Documentation

**api_limitations_ue55.md** - Python API limitations and workarounds
**blueprint_patterns.md** - Blueprint loading and spawning (`_C` suffix)
**material_patterns.md** - Material workflows (MaterialEditingLibrary)
**component_patterns.md** - Component manipulation patterns

---

## Constitutional Compliance

### Article I: General Purpose Scripts
- All patterns apply to ALL projects (no hard-coded paths)

### Article III: Progressive Disclosure
- SKILL.md under 500 lines, reference docs on-demand

### Article V: Follow Official Patterns
- UE Python API, MaterialEditingLibrary, AssetTools

---

## Version History

**v2.0.0** (2026-07-06) - UE 5.8 Migration
- Migrated from UE 5.5 to UE 5.8
- Updated MCP calling pattern: `mcp__ue58-mcp__execute_python_code`
- Added VibeUE toolset and Python introspection references
- Added MCP Execution section

**v1.0.0** (2025-10-25) - Initial Release
- Blueprint spawning, material instances, component properties
- API limitations database, 5 workflows, 4 troubleshooting issues