unreal-pcg-python

Unreal Engine PCG Python 統合ガイド

概要

Python は、UE5 の Procedural Content Generation（PCG）フレームワークと2 つのレベルで連携します。

1. PCGPythonInterop Plugin（UE 5.5 以降、ベータ版） -- グラフの途中で Python コードを実行する、エディター専用の PCG グラフノード（「Execute Python Script」）です。
2. PCG Python API（UE 5.2 以降） -- エディターの自動化やカスタムノードのロジックに使用する標準の unreal モジュールクラス（PCGComponent、PCGBlueprintElement など）です。

重要： PCG の Python 機能はすべてエディター専用です。パッケージ化されたビルドやゲームの実行時に Python を実行することはできません。

公式ドキュメント

リソース	URL
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 Plugin API	https://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 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 のロードマップ	https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/2213-python-interop-plugin

コミュニティリソース

リソース	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 Plugin（「Execute Python Script」ノード）

プラグインの詳細

• 場所： Engine/Plugins/PCGInterops/PCGPythonInterop/
• ステータス： ベータ版（IsBetaVersion: true、EnabledByDefault: false）
• モジュール： PCGPythonInteropEditor（エディター専用）
• 依存関係： PCG プラグイン + PythonScriptPlugin

プラグインを有効にする

1. Python Editor Script Plugin を有効にします（Plugins > Scripting にあります）
2. PCG Python Interop を有効にします（Plugins > Procedural Content Generation にあります）
3. エディターを再起動します

「Execute Python Script」ノード

このプラグインが追加する唯一のノードです。PCG グラフ内で Python コードを実行します。

2 つの入力モード：

モード	説明
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 より）

• 1 行ごとにフィードバックを返す EvaluateStatement モード
• パラメーターの入力／出力（Blueprint／HLSL ノードのように、Python 内から変数を取得／設定）
• PCG 内の HLSL と Python に対応した汎用ソースエディター
• マルチスレッド対応の可能性

---

2. PCG Python API（エディター自動化）

これらのクラスは、PCGPythonInterop プラグインとは独立して、任意の UE Python スクリプトから import unreal を介して利用できます。

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（および理論上は Python）でカスタム PCG ノードを作成するための基底クラスです。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 を利用できません。このノードは明示的に「Editor-only, should not be used at runtime.」というエラーを出します
ノードをプログラムから作成できない	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	ベータ	PCGBlueprintHelpers が完全に文書化されました
5.5	ベータ	GPU コンピュートパスと PCGGeometryBlueprintElement が追加されました
5.7	製品版対応	PCGPythonInterop プラグインが正式化され、PCG Editor Mode が追加され、パフォーマンスが約 2 倍になりました

6. ベストプラクティス

• 自動化には Python を使用します：アセットの一括作成、パラメーターの一括検証、CI/CD パイプライン
• カスタムノードには Blueprint を使用します：API がより安定しており、デザイナーにも扱いやすく、エディターで動作します
• パフォーマンスには C++ を使用します：マルチスレッド、GPU HLSL 対応、完全な API アクセス
• Python と PCG の最適な用途：多数のアクターにまたがる生成の実行、シードの管理、外部データ（Houdini、numpy）との連携、アセット移行スクリプト