关于 unreal-pcg-python
这是面向 Unreal Engine 编辑器自动化的 PCG Python 指南，涵盖 UE 5.2+ API 与 UE 5.5+ 插件。适合需要批量管理 PCG 生成、数据和自定义节点逻辑的开发者；同时说明编辑器限制和已知缺项。
主要功能
- 01通过 Python 创建 PCG 图资产
- 02触发生成并管理种子
- 03处理空间数据
- 04使用 PCGBlueprintElement 编写节点逻辑
- 05在图中运行 Python 脚本
适用场景
- 01批量创建 PCG 资产
- 02为多个 Actor 触发生成
- 03调整生成种子与图资产
- 04在 PCG 图中执行外部 Python 文件
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/unreal-pcg-python确认已加载。
详细介绍
Unreal Engine PCG Python 集成指南
概述
Python 可以在两个层面与 UE5 的程序化内容生成（PCG）框架交互：
- PCGPythonInterop 插件（UE 5.5+，Beta）——仅限编辑器使用的 PCG 图节点（“Execute Python Script”），可在图执行过程中运行 Python 代码。
- PCG Python API（UE 5.2+）——标准的
unreal模块类（PCGComponent、PCGBlueprintElement等），用于编辑器自动化和自定义节点逻辑。
重要提示： 所有 PCG Python 功能都仅限编辑器使用。Python 不能在打包后的版本中或游戏运行时运行。
官方文档
社区资源
| 资源 | URL |
|---|---|
| 论坛：使用 Python 创建 PCG 图 | https://forums.unrealengine.com/t/create-pcg-graph-with-python/1714891 |
| 论坛：通过 Python 生成 PCG | https://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 Extended Toolkit（社区 C++ 插件） | https://github.com/PCGEx/PCGExtendedToolkit |
| Houdini 到 PCG 数据示例 | https://github.com/cgtoolbox/HoudiniToPCGDataExample |
1. PCGPythonInterop 插件（“Execute Python Script”节点）
插件详情
- 位置：
Engine/Plugins/PCGInterops/PCGPythonInterop/ - 状态： Beta（
IsBetaVersion: true，EnabledByDefault: false） - 模块：
PCGPythonInteropEditor（仅限编辑器） - 依赖项：
PCG插件 +PythonScriptPlugin
启用插件
- 启用Python Editor Script Plugin（位于 Plugins > Scripting 下）
- 启用PCG Python Interop（位于 Plugins > Procedural Content Generation 下）
- 重启编辑器
“Execute Python Script” 节点
这是该插件添加的唯一节点。它可在 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 参数覆盖进行设置。
计划中的未来功能（来自源代码 TODO）
- 用于逐行反馈的
EvaluateStatement模式 - 参数输入/输出（在 Python 中获取/设置变量，类似 Blueprint/HLSL 节点）
- 在 PCG 中提供用于 HLSL + Python 的通用源代码编辑器
- 可能支持多线程
2. PCG Python API（编辑器自动化）
这些类可通过在任意 UE Python 脚本中执行 import unreal 使用，与 PCGPythonInterop 插件无关。
创建 PCG 图资产
import unreal
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
graph = asset_tools.create_asset(
'MyPCGGraph', '/Game/PCG',
unreal.PCGGraph, unreal.PCGGraphFactory()
)
触发 PCG 生成
# 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
使用空间数据
# 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（实用函数）
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. 通过 PCGBlueprintElement 创建自定义 PCG 节点
PCGBlueprintElement 是 Blueprint 中自定义 PCG 节点的基类（理论上也支持 Python）。从 UE 5.2 开始提供。
可重写的主要方法
| 方法 | 用途 |
|---|---|
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() | 自定义节点颜色 |
可配置属性
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. 已知限制
| 限制 | 详情 |
|---|---|
| 仅限编辑器 | 打包构建或运行时不支持 Python。该节点会明确报错：“仅限编辑器使用，不应在运行时使用。” |
| 无法通过程序创建节点 | Python 无法在 PCG 图中以编程方式添加/连接节点（Epic 已确认，截至 2024 年） |
| Execute Python Script 没有数据输出 | 该节点仅用于控制执行顺序，不参与 PCG 数据流 |
| 仅限主线程 | Python 执行会阻塞主线程 |
| API 变动 | 方法名称在 5.2 至 5.5 之间发生变化（例如，loop_on_points -> point_loop） |
| 参数访问较为繁琐 | 通过 Python 使用 ParametersOverrides 设置 PCG 图参数时，需要处理复杂的属性包 |
5. 版本历史
| UE 版本 | PCG 状态 | Python 说明 |
|---|---|---|
| 5.2 | 实验性 | 引入 PCGBlueprintElement、PCGComponent Python API |
| 5.3 | 实验性 | 记录了 PCGSpatialData，循环 API 趋于稳定 |
| 5.4 | Beta | 完整记录了 PCGBlueprintHelpers |
| 5.5 | Beta | 添加 GPU 计算路径、PCGGeometryBlueprintElement |
| 5.7 | 可用于生产环境 | 正式推出 PCGPythonInterop 插件、PCG Editor Mode，性能约提升 2 倍 |
6. 最佳实践
- 使用 Python 进行自动化：批量创建资产、参数扫描、CI/CD 流水线
- 使用 Blueprint 创建自定义节点：API 更稳定，方便设计人员使用，可在编辑器中运行
- 使用 C++ 提升性能：支持多线程、GPU HLSL，并可完整访问 API
- Python + PCG 的理想应用场景：触发多个 Actor 的生成、管理种子、集成外部数据（Houdini、numpy）、资产迁移脚本
评论
支持 Markdown