Back to Details

unreal-pcg-python

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unreal Engine PCG Python Integration Guide

Unreal Engine PCG Python集成指南

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.
Python在两个层面与UE5的程序化内容生成（PCG）框架交互：
  1. PCGPythonInterop插件（UE 5.5+，测试版）——仅编辑器可用的PCG图节点（"Execute Python Script"），可在图执行过程中运行Python代码。
  2. PCG Python API（UE 5.2+）——标准
    unreal
    模块类（
    PCGComponent
    、
    PCGBlueprintElement
    等），用于编辑器自动化和自定义节点逻辑。
重要提示：所有PCG Python功能均仅支持编辑器环境。Python无法在打包版本或游戏运行时运行。

Official Documentation

官方文档

ResourceURL
PCG Framework Overviewhttps://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-overview
PCG Framework Landing Pagehttps://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine
PCG Development Guideshttps://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-development-guides
PCG Node Referencehttps://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-node-reference-in-unreal-engine
PCG Data Types Referencehttps://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-data-types-reference-in-unreal-engine
PCGPythonInterop Plugin APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/API/PluginIndex/PCGPythonInterop
Python Editor Scriptinghttps://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python
PCGComponent Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGComponent
PCGBlueprintElement Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintElement
PCGBlueprintHelpers Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintHelpers
PCGSpatialData Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGSpatialData
PCGPointData Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGPointData
Python Interop Roadmaphttps://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/2213-python-interop-plugin
资源链接
PCG框架概述https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-overview
PCG框架首页https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine
PCG开发指南https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-development-guides
PCG节点参考https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-node-reference-in-unreal-engine
PCG数据类型参考https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-data-types-reference-in-unreal-engine
PCGPythonInterop插件APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/API/PluginIndex/PCGPythonInterop
Python编辑器脚本https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python
PCGComponent Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGComponent
PCGBlueprintElement Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintElement
PCGBlueprintHelpers Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGBlueprintHelpers
PCGSpatialData Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGSpatialData
PCGPointData Python APIhttps://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PCGPointData
Python互操作路线图https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/2213-python-interop-plugin

Community Resources

社区资源

ResourceURL
Forum: Create PCG Graph with Pythonhttps://forums.unrealengine.com/t/create-pcg-graph-with-python/1714891
Forum: Generate PCG through Pythonhttps://forums.unrealengine.com/t/generate-pcg-through-python-script/2053107
Forum: Change PCG Parameters from Pythonhttps://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 Examplehttps://github.com/cgtoolbox/HoudiniToPCGDataExample
资源链接
论坛：使用Python创建PCG图https://forums.unrealengine.com/t/create-pcg-graph-with-python/1714891
论坛：通过Python脚本生成PCGhttps://forums.unrealengine.com/t/generate-pcg-through-python-script/2053107
论坛：从Python修改PCG参数https://forums.unrealengine.com/t/how-to-change-pcg-graph-parameters-from-python/2060532
自定义PCG节点指南（Blueshift）https://blueshift-interactive.com/2025/09/03/how-to-create-custom-pcg-nodes/
PCG扩展工具包（社区C++插件）https://github.com/PCGEx/PCGExtendedToolkit
Houdini转PCG数据示例https://github.com/cgtoolbox/HoudiniToPCGDataExample

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

1. PCGPythonInterop插件（"Execute Python Script"节点）

Plugin Details

插件详情

  • Location: 
    Engine/Plugins/PCGInterops/PCGPythonInterop/
  • Status: Beta (
    IsBetaVersion: true
    , 
    EnabledByDefault: false
    )
  • Module: 
    PCGPythonInteropEditor
    (Editor-only)
  • Dependencies: 
    PCG
    plugin + 
    PythonScriptPlugin
  • 位置： 
    Engine/Plugins/PCGInterops/PCGPythonInterop/
  • 状态： 测试版（
    IsBetaVersion: true
    ，
    EnabledByDefault: false
    ）
  • 模块： 
    PCGPythonInteropEditor
    （仅编辑器可用）
  • 依赖项： 
    PCG
    插件 + 
    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
  1. 启用Python Editor Script Plugin（在插件>脚本分类下）
  2. 启用PCG Python Interop（在插件>程序化内容生成分类下）
  3. 重启编辑器

The "Execute Python Script" Node

"Execute Python Script"节点

This is the only node the plugin adds. It runs Python code within a PCG graph.
Two input modes:
ModeDescription
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).
这是该插件新增的唯一节点，可在PCG图内运行Python代码。
两种输入模式：
模式描述
Input
从"Source"引脚的FString属性读取Python代码，或使用内置默认脚本
File
执行磁盘上的
.py
文件
核心特性：
  • 仅在主线程运行（受Python GIL限制）
  • 不可缓存——每次图运行时都会重新执行
  • 无数据输出——输出引脚仅用于依赖控制（执行顺序）
  • 执行时会显示编辑器提示框（可通过
    bMuteEditorToast
    关闭）
  • 默认内置脚本：
    print("Hello PCG World!")
设置项（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)
所有标记为
PCG_Overridable
的属性均可通过PCG参数覆盖进行设置。

Planned Future Features (from source TODOs)

计划中的未来功能（来自源码TODO）

  • 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
  • EvaluateStatement
    模式，支持逐行反馈
  • 参数输入/输出（可在Python内部获取/设置变量，类似Blueprint/HLSL节点）
  • PCG中支持HLSL+Python的通用代码编辑器
  • 潜在的多线程支持

2. PCG Python API (Editor Automation)

2. PCG Python API（编辑器自动化）

These classes are available via 
import unreal
in any UE Python script, independent of the PCGPythonInterop plugin.
这些类可在任何UE Python脚本中通过
import unreal
导入，与PCGPythonInterop插件无关。

Create PCG Graph Assets

创建PCG图资源

python
import unreal

asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
graph = asset_tools.create_asset(
    'MyPCGGraph', '/Game/PCG',
    unreal.PCGGraph, unreal.PCGGraphFactory()
)
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

触发PCG生成

python
undefined
python
undefined

Get PCGComponent from an actor

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

Work with Spatial Data

处理空间数据

python
undefined
python
undefined

PCGSpatialData operations

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

PCGPointData

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

PCGBlueprintHelpers (Utility Functions)

PCGBlueprintHelpers（实用函数）

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

3. 通过PCGBlueprintElement创建自定义PCG节点

PCGBlueprintElement
is the base class for custom PCG nodes in Blueprint (and theoretically Python). Available since UE 5.2.
PCGBlueprintElement
是Blueprint中自定义PCG节点的基类（理论上也支持Python），自UE 5.2起可用。

Key Overridable Methods

可重写的核心方法

MethodPurpose
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
方法用途
execute(input)
主执行方法——接收并返回
PCGDataCollection
execute_with_context(context, input)
带PCG上下文访问的执行方法
point_loop_body(context, data, point, metadata, iteration)
逐点处理逻辑
variable_loop_body(...)
逐点处理，支持返回可变数量的输出点
iteration_loop_body(context, iteration, a, b, metadata)
固定次数迭代逻辑
node_title_override()
自定义节点显示名称
node_color_override()
自定义节点颜色

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

4. 已知限制

LimitationDetails
Editor-onlyNo Python in packaged builds or runtime. The node explicitly errors: "Editor-only, should not be used at runtime."
No programmatic node creationPython cannot add/connect nodes within a PCG graph programmatically (Epic confirmed, as of 2024)
No data output from Execute Python ScriptThe node only provides execution ordering, not PCG data flow
Main thread onlyPython execution blocks the main thread
API churnMethod names changed between 5.2-5.5 (e.g., 
loop_on_points
-> 
point_loop
)
Parameter access is finickySetting PCG graph parameters from Python via 
ParametersOverrides
requires navigating complex property bags
限制详情
仅支持编辑器打包版本或运行时无法使用Python。节点会明确报错："Editor-only, should not be used at runtime."
无法程序化创建节点截至2024年，Epic确认Python无法在PCG图内程序化添加/连接节点
Execute Python Script无数据输出该节点仅提供执行顺序控制，不支持PCG数据流输出
仅主线程运行Python执行会阻塞主线程
API变更频繁5.2-5.5版本间方法名称有变更（例如
loop_on_points
→ 
point_loop
）
参数访问复杂通过
ParametersOverrides
从Python设置PCG图参数需要处理复杂的属性结构

5. Version History

5. 版本历史

UE VersionPCG StatusPython Notes
5.2Experimental
PCGBlueprintElement
, 
PCGComponent
Python API introduced
5.3Experimental
PCGSpatialData
documented, loop API stabilized
5.4Beta
PCGBlueprintHelpers
fully documented
5.5BetaGPU compute path, 
PCGGeometryBlueprintElement
added
5.7Production-Ready
PCGPythonInterop
plugin formalized, PCG Editor Mode, ~2x perf
UE版本PCG状态Python相关说明
5.2实验性引入
PCGBlueprintElement
、
PCGComponent
Python API
5.3实验性
PCGSpatialData
文档完善，循环API稳定
5.4测试版
PCGBlueprintHelpers
文档完全完善
5.5测试版新增GPU计算路径、
PCGGeometryBlueprintElement
5.7生产就绪
PCGPythonInterop
插件正式化，新增PCG编辑器模式，性能提升约2倍

6. Best Practices

6. 最佳实践

  • 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
  • 使用Python实现自动化：批量创建资源、参数扫描、CI/CD流水线
  • 使用Blueprint创建自定义节点：API更稳定，便于设计师使用，支持编辑器环境
  • 使用C++实现高性能逻辑：支持多线程、GPU HLSL、完整API访问
  • Python+PCG的最佳场景：跨多个Actor触发生成、管理随机种子、集成外部数据（Houdini、numpy）、资源迁移脚本