unreal-blueprint-codegen

Unreal Engine Blueprint コード生成（UE 5.4–5.7）

エディターモジュールの C++ から、完全な .uasset ファイル（Blueprint、Widget Blueprint、ドメインアセット）を生成します。UE 5.7 で検証済みです。ほとんどのパターンは UE 5.4 でも動作します。

このスキルが適用される場面

ユーザーが、エディタを操作する代わりに、変数、関数グラフ、イベントグラフの配線、ウィジェット階層、UMG アニメーション、カスタムアセットグラフなどのアセットコンテンツをプログラムで作成したい場合に適用されます。典型的な用途は、Marketplace のサンプルコンテンツ（クイックスタート、ウォークスルー、デモ会話）を生成することです。手作業でバイナリの .uasset ファイルから不要なものを削除するのではなく、再現可能な形で再生成できます。

ユーザーが実行時のウィジェット生成（ゲーム実行中の CreateWidget / WidgetTree->ConstructWidget）だけを行いたい場合、このスキルは過剰です。通常の UMG を使ってください。

必須の前提条件

• Type=Editor（または UncookedOnly）の C++ エディターモジュールが必要です。Python ではイベントグラフを作成できません。UEdGraph / UK2Node_* は公開されていないためです。C++ で UBlueprintFunctionLibrary をセットアップし、Python のエントリーポイントが必要な場合は、その UFUNCTION を Python から呼び出します。
• モジュールは、少なくとも UnrealEd、BlueprintGraph、Kismet、KismetCompiler、AssetTools、AssetRegistry に依存する必要があります。Widget Blueprint では UMG、UMGEditor、MovieScene、MovieSceneTracks を追加します。動作する .Build.cs については、assets/experiment-module-template/ を参照してください。
• IWYU：各エンジンヘッダーを明示的にインクルードします。独自のヘッダーでは UPackage / UObject などを前方宣言し、完全なヘッダーは .cpp だけに取り込みます。

30 秒でつかむ基本モデル

Asset = UPackage  +  UObject (e.g. UBlueprint / UWidgetBlueprint / UMyAsset)
                     |
                     +-- source UEdGraph (editor-only, what designers see)
                     |     +-- UK2Node_* / UEdGraphNode_* (the boxes)
                     |           +-- UEdGraphPin (the wires)
                     |
                     +-- generated UClass  <- produced by CompileBlueprint
                           +-- FProperty / UFunction (what code uses at runtime)

グラフにエディターノードを生成し、ピンを配線してから、CompileBlueprint を呼び出して生成クラスをビルドします。最後にパッケージを保存します。

判断ツリー

目的	参照先
通常の Blueprint に変数、関数、カスタムイベント、数学ノードを追加する	references/k2node-cookbook.md
ウィジェット階層を含む Widget Blueprint を作成する	references/widget-blueprint-cookbook.md
C++ から UMG アニメーション（UWidgetAnimation + MovieScene トラック／キーフレーム）を追加する	references/widget-blueprint-cookbook.md
コンパイラが「function not found」と表示する、FindPinChecked がアサートする、またはノードにピンがない	references/two-pass-compile.md — デバッグする前に必ず読んでください
作業を始めるための、動作するモジュールのひな形が必要	assets/experiment-module-template/
Engine API の予期しない仕様や、バージョン固有の問題に遭遇した	references/caveats.md

標準的なワークフロー

ジェネレーター関数ごとに、次の手順を実行します。

1. パッケージを作成／ロードする：CreatePackage(*FullPath) の後に Package->FullyLoad() を呼び出します。
2. アセットを作成する：FKismetEditorUtilities::CreateBlueprint(...) を使います（UBlueprint と UWidgetBlueprint の両方に対応しています。適切な Blueprint クラスと GeneratedClass を渡します）。
3. コンテンツを構築する — 変数、関数グラフ、ウィジェットツリー、アニメーションを追加します。
4. イベントグラフを配線する／ユーザー関数を呼び出す — 配線が手順 3 で作成したコンテンツを参照する場合は、中間コンパイルの後にのみ行います（two-pass-compile.md を参照）。
5. MarkBlueprintAsStructurallyModified + CompileBlueprint — 最後に一度だけ実行します（または、2 パス方式では 2 回）。
6. 保存する：FAssetRegistryModule::AssetCreated(Asset) + Package->MarkPackageDirty() + UPackage::SavePackage(...) を実行します。

ひな形：

#include "Engine/Blueprint.h"
#include "Kismet2/BlueprintEditorUtils.h"
#include "Kismet2/KismetEditorUtilities.h"
#include "AssetRegistry/AssetRegistryModule.h"
#include "UObject/SavePackage.h"

UBlueprint* CreateBP(const FString& PackagePath, const FString& AssetName, UClass* ParentClass)
{
    const FString FullPath = PackagePath / AssetName;
    UPackage* Package = CreatePackage(*FullPath);
    Package->FullyLoad();

    UBlueprint* BP = FKismetEditorUtilities::CreateBlueprint(
        ParentClass,                  // e.g. AActor::StaticClass() or UUserWidget::StaticClass()
        Package,
        FName(*AssetName),
        BPTYPE_Normal,
        UBlueprint::StaticClass(),    // or UWidgetBlueprint::StaticClass()
        UBlueprintGeneratedClass::StaticClass(),  // or UWidgetBlueprintGeneratedClass::StaticClass()
        FName("MyGenerator"));        // calling-context tag; any FName

    // ... build content here ...

    FBlueprintEditorUtils::MarkBlueprintAsStructurallyModified(BP);
    FKismetEditorUtilities::CompileBlueprint(BP);

    FAssetRegistryModule::AssetCreated(BP);
    Package->MarkPackageDirty();
    const FString Filename = FPackageName::LongPackageNameToFilename(
        Package->GetName(), FPackageName::GetAssetPackageExtension());
    FSavePackageArgs Args;
    Args.TopLevelFlags = RF_Public | RF_Standalone;
    UPackage::SavePackage(Package, BP, *Filename, Args);

    return BP;
}

重要なルール（クックブックを読まない場合も、必ず確認してください）

1. UK2Node_CallFunction では AllocateDefaultPins より先に SetExternalMember を設定する

UK2Node_CallFunction* Node = NewObject<UK2Node_CallFunction>(Graph);
Node->FunctionReference.SetExternalMember(
    GET_FUNCTION_NAME_CHECKED(UKismetSystemLibrary, PrintString),
    UKismetSystemLibrary::StaticClass());
Node->AllocateDefaultPins();   // AFTER. Reverse and the node spawns pinless.

UK2Node_VariableSet/Get でも同じルールが適用されます。まず変数参照を設定してから、AllocateDefaultPins を呼び出してください。

2. MarkBlueprintAsStructurallyModified と Modified の違い

• StructurallyModified：ノードの追加・削除、変数の追加・削除、ピンのトポロジー変更がある場合です。クラスレイアウトが再生成されます。
• Modified：既存のノードや変数のプロパティ変更のみの場合です（例：デフォルト値の変更）。

コード生成では、ほとんどの場合 MarkBlueprintAsStructurallyModified を使ってください。

3. 関数呼び出しは実行チェーンに接続しないと削除されます

非ピュア関数（実行ピンを持つ関数）は、実行チェーンに接続する必要があります。実行ピンを接続せずにデータ出力を接続すると、BP コンパイラーによって呼び出しが削除され、データピンはデフォルト値を返します。症状：警告 「X was pruned because its Exec pin is not connected」。

// WRONG — Compute is non-pure, exec not wired, gets pruned:
EvtThen->MakeLinkTo(SetCounter->GetExecPin());
ComputeRet->MakeLinkTo(CounterValPin);  // reads default, not actual return

// RIGHT — Compute in the chain:
EvtThen->MakeLinkTo(CallCompute->GetExecPin());
CallCompute->GetThenPin()->MakeLinkTo(SetCounter->GetExecPin());
ComputeRet->MakeLinkTo(CounterValPin);

4. (0,0) は避けてください — 自動生成されるデフォルトイベントが配置されています

AActor ベースの BP と Widget Blueprint は、(0, 0) にプレースホルダーイベント（BeginPlay、Tick、ActorBeginOverlap、PreConstruct、Construct）を自動生成します。ノードは、たとえば Y=-300、X=-400 のように、十分離れた位置に配置してください。そうしないと、ユーザーがアセットを開いたときに、ノードが入り組んだ状態になります。

5. 新しく作成したコンテンツを参照するノードがある場合は、2 パスでコンパイルします

関数 Compute を作成し、同じパス内でそれを参照する CallCompute を接続すると、CallCompute の AllocateDefaultPins が、生成クラスに Compute が反映される前に実行されます。そのため、InValue／ReturnValue のピンが存在せず、FindPinChecked がアサートします。修正方法：関数の構築後にコンパイルしてから、呼び出しを接続します。UK2Node_VariableGet で参照する UMG アニメーションも同様です。references/two-pass-compile.md を参照してください。

UE 5.7 でよくある注意点（全項目は caveats.md を参照）

• 5.7 の UUserWidget には PlayAnimationByName がありません。 使用できるのは PlayAnimation(UWidgetAnimation*, ...) のみです。文字列ではなく、アニメーションには UK2Node_VariableGet を使って接続してください。
• アニメーションの FName は表示ラベルと一致させる必要があります。 UUserWidget::GetAnimationByName は GetFName() と照合します。両方を設定してください：NewObject<UWidgetAnimation>(WBP, FName("SlideIn"), ...) と Anim->SetDisplayLabel(TEXT("SlideIn"))。
• Outer の階層は重要です。 UWidgetAnimation の outer は WBP である必要があります。UMovieScene の outer はアニメーションである必要があります。outer が誤っていると、アニメーションはエディターの Animations パネルに表示されません。
• 生成アセットが参照するタグには、UE_DEFINE_GAMEPLAY_TAG_STATIC を使用してください。 ジェネレーター関数内で実行時に UGameplayTagsManager::AddNativeGameplayTag を呼び出しても手遅れです。エディター UI のタグツリーはすでに構築されています。モジュールのロード時に登録してください。
• Python から UEdGraph／UK2Node_* にはアクセスできません。 イベントグラフを作成するには、C++ を使う方法しかありません。Python からの呼び出しが必要な場合は、ジェネレーターを UBlueprintFunctionLibrary の BlueprintCallable UFUNCTIONs として公開してください。
• FBlueprintEditorUtils::AddFunctionGraph は、デフォルトでは Result ノードを生成しません。 Entry のみ生成します。関数が値を返す場合は、FGraphNodeCreator<UK2Node_FunctionResult> で手動作成してください。

FEdGraphPinType の簡易チートシート

FEdGraphPinType T;
T.PinCategory = UEdGraphSchema_K2::PC_Boolean;            // bool
T.PinCategory = UEdGraphSchema_K2::PC_Int;                // int32
T.PinCategory = UEdGraphSchema_K2::PC_Real;
T.PinSubCategory = UEdGraphSchema_K2::PC_Float;           // float
T.PinSubCategory = UEdGraphSchema_K2::PC_Double;          // double
T.PinCategory = UEdGraphSchema_K2::PC_String;             // FString
T.PinCategory = UEdGraphSchema_K2::PC_Name;               // FName
T.PinCategory = UEdGraphSchema_K2::PC_Text;               // FText
T.PinCategory = UEdGraphSchema_K2::PC_Object;             // object ref
T.PinSubCategoryObject = AActor::StaticClass();           //   (with target class)
T.ContainerType = EPinContainerType::Array;               // wrap as TArray<>
T.ContainerType = EPinContainerType::Set;                 // TSet<>
T.ContainerType = EPinContainerType::Map;                 // TMap<>  (PinValueType for value)

次のように使用します：FBlueprintEditorUtils::AddMemberVariable(BP, FName("MyVar"), T, FString(TEXT("DefaultValueAsString")));

ワークフローのチェックリスト

このスキルを使ってジェネレーターを実装する際は、次の点を確認してください。

1. エディターモジュールが適切な依存関係とともに存在することを確認します（テンプレートはassets/experiment-module-template/にあります）。
2. アセットの種類に関連するパターンについて、references/k2node-cookbook.mdを読みます。
3. Widget Blueprintsの場合は、references/widget-blueprint-cookbook.mdも読みます。
4. 同じ関数内で作成されたコンテンツ間の接続を行う場合は、2パスコンパイルの構成を計画します（references/two-pass-compile.md）。
5. 新しい動作をバグと判断する前に、既知の落とし穴についてreferences/caveats.mdを確認します。
6. エディターのターゲットをビルドし、エディターを開いて、UFUNCTIONを呼び出し（多くの場合、Output LogからPythonを使います）、アセットを目視で確認してテストします。
7. 繰り返し調整します。ノードの表示に問題がある場合（赤いエラー枠、ピンがない、「X pruned」という警告、データが流れるはずの場所にデフォルト値が表示されるなど）、原因はたいてい次のいずれかです。実行ワイヤーがない、割り当て順序が間違っている、2パスコンパイルが必要、またはピン名が間違っている。

このスキルでは扱わないこと

• 生成したアセットのクック／パッケージ化 — 通常の.uassetファイルなので、ほかのアセットと同様に配布できます。
• Editor Utility Widgets / Blutilities — これらからジェネレーターのUFUNCTIONを呼び出すことはできますが、EUWの設計は別途UMGで行う必要があります。
• ランタイムUMG — CreateWidget、AddToViewport、ゲームコード内でのアニメーションPlayAnimation呼び出し。これはコード生成ではありません。
• カスタムUEdGraphスキーマ — ドメイン固有のグラフ（ダイアログ、クエスト、アビリティツリーなど）に生成する場合は、プラグイン独自のコンパイラーエントリーポイントを使います。静的コンパイラークラスはエクスポートされていないことが多いため、リンクに失敗した場合は静的コンパイラーではなく、グラフの更新メソッド（例：UMyGraph::UpdateAsset()）を呼び出してください。