unreal-python-scripting

---
name: unreal-python-scripting
description: Gives Unreal Engine 5.8 Python API patterns - Blueprint spawning, material instances, component properties, workarounds for API limits. Use when scripting Unreal in Python, writing Unreal Python tools, or hitting an Unreal Python API limitation.
allowed-tools: mcp__ue58-mcp__execute_python_code,mcp__ue58-mcp__call_tool,Read,Write,Grep
---

# Unreal Python Scripting

**Version:** 2.0.3
**Last Updated:** 2026-10-09
**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.

- **An execute call times out at about 30 s** ("Python execution exceeded
  30000ms") **while the script keeps running in the editor.** Split long work
  into short calls, and after a timeout read the state back instead of
  re-running - a timeout is not a failure.

---

## 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.2** (2026-10-09) - Observation 140: MCP execute calls time out at about
30 s while the script keeps running; split long work, read state back.

**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

• SKILL.md 8 KB
• reference/api_limitations_ue55.md 17 KB
• reference/blueprint_patterns.md 18 KB
• reference/component_patterns.md 21 KB
• reference/material_patterns.md 20 KB