unreal-pcg-python

---
name: "unreal-pcg-python"
description: "Python interacts with UE5's Procedural Content Generation (PCG) framework at two levels:"
license: "MIT"
---

# Unreal Engine PCG Python Integration Guide

## Overview

Python interacts with UE5's Procedural Content Generation (PCG) framework at **two levels**:

1. **PCGPythonInterop Plugin** (UE 5.5+, Beta) -- An editor-only PCG graph node ("Execute Python Script") that runs Python code mid-graph.
2. **PCG Python API** (UE 5.2+) -- Standard `unreal` module classes (`PCGComponent`, `PCGBlueprintElement`, etc.) for editor automation and custom node logic.

**Important:** All PCG Python functionality is **editor-only**. Python cannot run in packaged builds or at game runtime.

## Official Documentation

| Resource | URL |
|----------|-----|
| **PCG Framework Overview** | https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-overview |
| **PCG Framework Landing Page** | https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine |
| **PCG Development Guides** | https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-development-guides |
| **PCG Node Reference** | https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-node-reference-in-unreal-engine |
| **PCG Data Types Reference** | https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-data-types-reference-in-unreal-engine |
| **PCGPythonInterop Plugin API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/API/PluginIndex/PCGPythonInterop |
| **Python Editor Scripting** | https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python |
| **PCGComponent Python API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGComponent |
| **PCGBlueprintElement Python API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintElement |
| **PCGBlueprintHelpers Python API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintHelpers |
| **PCGSpatialData Python API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGSpatialData |
| **PCGPointData Python API** | https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGPointData |
| **Python Interop Roadmap** | https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/2213-python-interop-plugin |

### Community Resources

| Resource | URL |
|----------|-----|
| Forum: Create PCG Graph with Python | https://forums.unrealengine.com/t/create-pcg-graph-with-python/1714891 |
| Forum: Generate PCG through Python | https://forums.unrealengine.com/t/generate-pcg-through-python-script/2053107 |
| Forum: Change PCG Parameters from Python | https://forums.unrealengine.com/t/how-to-change-pcg-graph-parameters-from-python/2060532 |
| Custom PCG Nodes Guide (Blueshift) | https://blueshift-interactive.com/2025/09/03/how-to-create-custom-pcg-nodes/ |
| PCG Extended Toolkit (community C++ plugin) | https://github.com/PCGEx/PCGExtendedToolkit |
| Houdini to PCG Data Example | https://github.com/cgtoolbox/HoudiniToPCGDataExample |

---

## 1. PCGPythonInterop Plugin ("Execute Python Script" Node)

### Plugin Details

- **Location:** `Engine/Plugins/PCGInterops/PCGPythonInterop/`
- **Status:** Beta (`IsBetaVersion: true`, `EnabledByDefault: false`)
- **Module:** `PCGPythonInteropEditor` (Editor-only)
- **Dependencies:** `PCG` plugin + `PythonScriptPlugin`

### Enabling the Plugin

1. Enable **Python Editor Script Plugin** (under Plugins > Scripting)
2. Enable **PCG Python Interop** (under Plugins > Procedural Content Generation)
3. Restart the editor

### The "Execute Python Script" Node

This is the **only node** the plugin adds. It runs Python code within a PCG graph.

**Two input modes:**

| Mode | Description |
|------|-------------|
| `Input` | Reads Python source from an FString attribute on the "Source" pin, or uses an inline default script |
| `File` | Executes a `.py` file from disk |

**Key characteristics:**
- Runs on **main thread only** (Python GIL constraint)
- **Not cacheable** -- re-executes every time the graph runs
- **No data output** -- output pin is dependency-only (for execution ordering)
- Shows an editor toast on execution (suppressible via `bMuteEditorToast`)
- Default inline script: `print("Hello PCG World!")`

**Settings (UPROPERTY):**

```
ScriptInputMethod  -- EPCGPythonScriptInputMethod (Input or File)
ScriptSource       -- FPCGAttributePropertyInputSelector (which attribute holds the script)
ScriptPath         -- FFilePath (path to .py file, filtered to *.py)
bMuteEditorToast   -- bool (suppress editor notification)
```

All properties marked `PCG_Overridable` (can be set via PCG parameter overrides).

### Planned Future Features (from source TODOs)

- `EvaluateStatement` mode for line-by-line feedback
- Parameter inputs/outputs (get/set variables from within Python, like Blueprint/HLSL nodes)
- Generalized source editor in PCG for HLSL + Python
- Potential multi-thread support

---

## 2. PCG Python API (Editor Automation)

These classes are available via `import unreal` in any UE Python script, independent of the PCGPythonInterop plugin.

### Create PCG Graph Assets

```python
import unreal

asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
graph = asset_tools.create_asset(
    'MyPCGGraph', '/Game/PCG',
    unreal.PCGGraph, unreal.PCGGraphFactory()
)
```

### Trigger PCG Generation

```python
# Get PCGComponent from an actor
pcg_comp = actor.get_component_by_class(unreal.PCGComponent)

pcg_comp.generate(True)          # force full regeneration
pcg_comp.generate_local(True)    # local only, no replication
pcg_comp.set_graph(my_graph)     # swap graph asset
pcg_comp.seed = 42               # set deterministic seed
pcg_comp.cleanup(True, False)    # cleanup generated components
```

### Work with Spatial Data

```python
# PCGSpatialData operations
spatial_data.to_point_data()              # convert to points
spatial_data.intersect_with(other)        # boolean intersection
spatial_data.union_with(other)            # boolean union
spatial_data.subtract(other)              # boolean subtraction
spatial_data.get_bounds()                 # get spatial bounds
spatial_data.get_density_at_position(pos) # sample density

# PCGPointData
point_data = unreal.PCGPointData()
points = point_data.get_points()          # -> Array[PCGPoint]
point_data.set_points(modified_points)
```

### PCGBlueprintHelpers (Utility Functions)

```python
helpers = unreal.PCGBlueprintHelpers
helpers.get_actor_data(context)
helpers.get_component(context)
helpers.get_random_stream_from_point(point, settings, component)
helpers.compute_seed_from_position(position)
helpers.create_pcg_data_from_actor(actor, parse_actor)
```

---

## 3. Custom PCG Nodes via PCGBlueprintElement

`PCGBlueprintElement` is the base class for custom PCG nodes in Blueprint (and theoretically Python). Available since UE 5.2.

### Key Overridable Methods

| Method | Purpose |
|--------|---------|
| `execute(input)` | Primary execution -- receives and returns `PCGDataCollection` |
| `execute_with_context(context, input)` | Execution with PCG context access |
| `point_loop_body(context, data, point, metadata, iteration)` | Per-point processing |
| `variable_loop_body(...)` | Per-point, returns variable number of output points |
| `iteration_loop_body(context, iteration, a, b, metadata)` | Fixed-count iteration |
| `node_title_override()` | Custom display name |
| `node_color_override()` | Custom node color |

### Configurable Properties

```python
element.custom_input_pins    # Array[PCGPinProperties]
element.custom_output_pins   # Array[PCGPinProperties]
element.has_default_in_pin   # bool
element.has_default_out_pin  # bool
element.is_cacheable         # bool
element.requires_game_thread # bool
```

---

## 4. Known Limitations

| Limitation | Details |
|-----------|---------|
| **Editor-only** | No Python in packaged builds or runtime. The node explicitly errors: "Editor-only, should not be used at runtime." |
| **No programmatic node creation** | Python cannot add/connect nodes within a PCG graph programmatically (Epic confirmed, as of 2024) |
| **No data output from Execute Python Script** | The node only provides execution ordering, not PCG data flow |
| **Main thread only** | Python execution blocks the main thread |
| **API churn** | Method names changed between 5.2-5.5 (e.g., `loop_on_points` -> `point_loop`) |
| **Parameter access is finicky** | Setting PCG graph parameters from Python via `ParametersOverrides` requires navigating complex property bags |

## 5. Version History

| UE Version | PCG Status | Python Notes |
|------------|-----------|--------------|
| 5.2 | Experimental | `PCGBlueprintElement`, `PCGComponent` Python API introduced |
| 5.3 | Experimental | `PCGSpatialData` documented, loop API stabilized |
| 5.4 | Beta | `PCGBlueprintHelpers` fully documented |
| 5.5 | Beta | GPU compute path, `PCGGeometryBlueprintElement` added |
| 5.7 | Production-Ready | `PCGPythonInterop` plugin formalized, PCG Editor Mode, ~2x perf |

## 6. Best Practices

- **Use Python for automation**: Batch asset creation, parameter sweeps, CI/CD pipelines
- **Use Blueprint for custom nodes**: More stable API, designer-friendly, works in editor
- **Use C++ for performance**: Multi-threaded, GPU HLSL support, full API access
- **Python + PCG sweet spot**: Triggering generation across many actors, managing seeds, integrating external data (Houdini, numpy), asset migration scripts