PyUnreal Documentation¶

Pythonic wrapper for Unreal Engine's Python API. PyMEL for Unreal.

What is PyUnreal?¶

PyUnreal wraps Unreal Engine's verbose, C++-style Python API into a clean, object-oriented interface built for Tech Artists. If you've used PyMEL in Maya, you'll feel right at home.

Before (raw UE Python):

import unreal
lib = unreal.MCAAnimBlueprintLibrary
skel = unreal.EditorAssetLibrary.load_asset('/Game/Characters/SK_Mannequin')
abp = lib.create_anim_blueprint('/Game/AnimBP', 'ABP_Character', skel)
lib.add_state_machine(abp, 'Locomotion', True)
lib.add_state(abp, 'Locomotion', 'Idle')
lib.set_default_state(abp, 'Locomotion', 'Idle')
lib.set_state_animation(abp, 'Locomotion', 'Idle', idle_anim)
lib.add_state(abp, 'Locomotion', 'Walk')
lib.set_state_animation(abp, 'Locomotion', 'Walk', walk_anim)
lib.add_transition(abp, 'Locomotion', 'Idle', 'Walk', 0.2)
lib.add_transition(abp, 'Locomotion', 'Walk', 'Idle', 0.2)
lib.compile_anim_blueprint(abp)

After (PyUnreal):

from pyunreal import load
from pyunreal.anim import AnimBlueprint

skeleton = load('/Game/Characters/SK_Mannequin')
abp = AnimBlueprint.create('/Game/AnimBP', 'ABP_Character', skeleton)

loco = abp.add_state_machine('Locomotion')
idle = loco.add_state('Idle', animation=load('/Game/Anims/Idle'), default=True)
walk = loco.add_state('Walk', animation=load('/Game/Anims/Walk'))

idle.transition_to(walk, crossfade=0.2)
walk.transition_to(idle, crossfade=0.2)

abp.compile()

Installation¶

Inside Unreal Engine¶

Copy the pyunreal/ folder to your project's Content/Python/ directory, or add its parent directory to your Python path in Project Settings > Python > Additional Paths.

pip (for development outside UE)¶

pip install pyunreal

Two-Tier Architecture¶

PyUnreal works at two levels:

Tier	Requires	What You Get
Standalone	UE Python interpreter	Asset loading, scene queries, standard `unreal.*` wrappers
MCA Editor	MCA Editor plugin	AnimBP graph editing, Blueprint node wiring, deep engine access

Methods that require MCA Editor will raise a clear error with install instructions if the plugin is not loaded.

Guides¶

Getting Started -- Install, configure, and run your first script
AnimBP Cookbook -- Common AnimBP recipes and patterns
Blueprint Cookbook -- Blueprint creation, variables, batch setup
Control Rig Cookbook -- Rig inspection, controls, transforms

API Reference¶

Utilities¶

load() -- Load assets from the Content Browser
asset_exists() -- Check if an asset exists

Animation Blueprint¶

AnimBlueprint -- Create, load, and compile Animation Blueprints
StateMachine -- Add and list states within a state machine
State -- Set animation, create transitions, set as default
Transition -- Configure crossfade and auto-transition rules
EventGraph -- EventGraph node creation and pin wiring

Blueprint¶

Blueprint -- Create, load, and manage Blueprints
Component -- Read-only component data
Variable -- Variable with read/write defaults

Control Rig¶

ControlRig -- Load and build Control Rig hierarchies
Control -- Control with transform and shape access
Bone -- Read-only skeleton bone
Null -- Space/group element

Material¶

Material -- Create, load, and assign materials

Viewport¶

viewport -- Viewport control (focus, camera, screenshot)

Scene & Actors¶

Actor -- Spawn and manipulate level actors
scene -- Scene queries (find, select, filter)

Exceptions¶

PyUnrealError -- Base exception and subclasses

Requirements¶

Python 3.9+ (ships with UE 5.x)
Unreal Engine 5.4+
MCA Editor plugin (optional, for advanced features)

License¶

MIT