Unreal Engine の Unreal Header Tool | Unreal Engine 5.3 ドキュメンテーション

Unreal Header Tool の概要

Unreal Header Tool (UHT) は、Unreal Engine のカスタムのパースおよびコード生成のツールです。UHT では、Unreal Engine (UE) の UObject システム用にコードをパースおよび生成します。Unreal Engine のコードのコンパイルは以下の 2 つのフェーズで行われます。

Unreal Build Tool (UBT) で UHT が呼び出されると、Unreal 関連のクラスのメタデータの C++ ヘッダをパースし、さまざまな UObject 関連の機能を実装するためのカスタムコードを生成します。
UBT では、結果をコンパイルするために設定された C++ コンパイラが呼び出されます。

このページでは、次の情報を記載しています。

Unreal Header Tool を実行する

UBT で内部的に対応されているため、通常の開発ワークフローでは Unreal Header Tool (UHT) を実行する必要はありません。ただし、UHT プラグインを作成するか、UHT に変更を加える場合、UHT を個別に実行することが必要になる場合があります。

このセクションでは、UHT を手動で実行する方法について説明します。

UHT コマンドライン

UHT を実行するには、次の 2 種類の方法があります。

内部 UBT コマンド

UBT では、内部的に次のコマンドラインを使用します。UBT はすべてのヘッダファイルをスキャンして、UHT キーワードを検索してから、UHT がパースする必要のあるすべてのモジュールとソースファイルを含むマニフェストファイルを生成します。

RunUBT -Mode=UnrealHeaderTool "<PROJECT_FILE>" "<MANIFEST_FILE>" …

UHT 開発コマンド

UHT 開発時または他のエクスポートの実行時に、次のコマンドラインを使用できます。既存のマニフェストファイルに依存する代わりに、UHT では UBT が通常実行するスキャンと同じスキャンを実行し、その後、マニフェストを自動的に生成します。UHT では、このモードでの実行時に UBT と同じターゲット指定を使用します。

RunUBT -Mode=UnrealHeaderTool "-Target=<TARGET> <PLATFORM> <CONFIGURATION>" …

RunUBT -Mode=UnrealHeaderTool "-Target=<TARGET> <PLATFORM> <CONFIGURATION> -Project=\"<PROJECT_FILE>\"" …

ログオプション

UHT では、UBT がサポートしているものと同じログオプションをサポートしています。

エラーハンドリング

UHT には、エラーハンドリングに影響する 2 つのオプションがあります。

エラーとして警告
生成したコードが変更された場合に失敗

UHT は、通常、-WarningsAsError で実行されます。名前が示すように、UHT では警告が検出されると、エラーコードを返します。ホットリロードシステムでは -FailIfGeneratedCodeChanges を使用して、生成されたコードへの変更を検出し、あればエラーを返します。

デバッグ

デバッグ時に、UHT で C# タスクを多用すると、デバッグが困難になる場合があります。-NoGoWide オプションを使用すると、C# タスクの使用を無効にし、単一スレッドの実行で UHT を実行します。

エクスポータ

エクスポータは、UHT がコードおよびレポートの生成に使用するメカニズムです。デフォルトでは、UHT は標準 Codegen エクスポータおよび有効なスクリプトジェネレータのエクスポータを実行します。UHT には、デフォルトで有効になっていないサンプルエクスポータが 2 つ含まれています。

Json
統計

エクスポータを有効にする

エクスポータを有効にするには、-<EXPORTER_NAME> コマンドライン引数を使用します。通常有効になっているエクスポータを無効にするには、-No<EXPORTER_NAME> コマンドライン引数を使用します。-NoDefaultExporters オプションは、デフォルトで有効になっているすべてのエクスポータを無効にします。このオプションは、デフォルトのエクスポータとは関係なく、統計などのエクスポータを実行する場合に便利です。

エクスポータの出力

UHT では、UHT 開発に便利なエクスポータ出力のディレクトリを 1 つ作成します。これらのオプションの出力は、「Engine/Programs/UnrealHeaderTool/Saves」ディレクトリにあります。UHT 開発を実行する前に、-WriteRef オプションを使用して、生成されたすべての出力のコピーを作成します。変更を繰り返す場合、-VerifyRef オプションを使用して、新しく作成した出力を -WriteRef で生成された出力と比較します。これによって、出力に対する予期しない変更がないことが確認されます。

-NoOutput オプションを使用して、UHT で出力を通常書き込む場所に書き込まないようにします。

UHT 実行の一般的な問題

パースされないデリゲートのみを含むソースファイル

他の文とは異なり、UHT では自動的に任意の DECLARE_DYNAMIC_ デリゲートをパースします。ただし、ヘッダファイルにこれらのデリゲートが含まれていて、他の UHT キーワードが含まれていない場合、UBT では、パースする必要があるものとしてヘッダを見なしません。

この問題を回避するには、前述の UDELEGATE キーワードを少なくとも 1 つのデリゲートで使用します。

スクリプトジェネレータで UHT を拡張する

C# UHT では、プラグインでスクリプトジェネレータを定義する機能をサポートしています。この例は、「Engine\Plugins\ScriptPlugin\Source\ScriptGeneratorUbtPlugin」にあります。

UBT は、<PLUGIN_NAME>.ubtplugin.csproj C# プロジェクトファイル名が存在することで、プラグインを認識します。ここで、<PLUGIN_NAME> はプラグインの名前です。C# プロジェクトを設定する場合、プロジェクト参照を使用する代わりに「Engine\Binaries\DotNET\UnrealBuildTool」ディレクトリにある UBT と UHT のアセンブリ参照を使用します。これは、UBT でプラグインを作成する場合、ロックされたファイルの問題を回避します。

指定子、キーワード、プロパティなどを定義するために UHT で同じメカニズムを使用できる場合、エクスポータのみがサポートされます。さらに、エクスポータはプラグインの「Intermediate」ディレクトリへのファイル出力に制限されます。UBT では、標準 Codegen エクスポータ以外で生成されたファイルはコンパイルされません。スクリプトジェネレータプラグインの場合、コンパイルは、通常、プラグイン内の他の C++ コードに含まれる単一の生成済み .inl ファイルによって行われます。

IUhtExportFactory インターフェースは、UHT にアクセスを提供しています。

メソッド	説明
`IUhtExportFactory.Session`	パッケージのコレクションおよびその定義済みのタイプへのアクセスを提供します。C++ UHT とは異なり、3 つのタイプには、UHT によってパースされた各タイプに関するすべての情報が含まれています。
`IUhtExportFactory.CreateTask`	コンテンツをエクスポートするタスクまたは `-NoGoWide` が指定された場合に直接実行するタスクを作成します。
`IUhtExportFactory.MakePath`	`CommitOutput` に渡すファイル名を生成します。
`IUhtExportFactory.CommitOutput`	変更された場合にのみ、出力をディスクに書き込みます。`-WriteRef` または `-VerifyRef` オプションを使用する場合、ファイルはエクスポータの名前に基づいたサブディレクトリにも書き込まれます。
`IUhtExportFactory.AddExternalDependency`	UBT で UHT の再実行が必要かどうかを確認するためにチェックするファイルを追加します。たとえば、出力を変更するコンフィギュレーションファイルを外部依存関係として追加できます。

UHT エクスポータの拡張を有効にする

UHT が拡張を認識するために、次の 2 点が必要です。

クラスには、UnrealHeaderTool クラス属性が含まれている必要があります。
関数には、UhtExporter メソッド属性が含まれている必要があります。

エクスポータを追加する場合、属性に次の設定が含まれている必要があります。

Name：エクスポータの名前。この名前はある程度固有である必要があります。
Options：プラグインが有効になっている場合は常に実行されるように、デフォルトに設定します。
ModuleName：エクスポータを含むプラグインモジュールの名前。

たとえば、「Engine\Plugins\ScriptPlugin\Source\ScriptGeneratorUbtPlugin」にある ScriptGenerator.cs の例を参照してください。

[UhtExporter(Name="ScriptPlugin", Description="Generic Script Plugin Generator", Options=UhtExporterOptions.Default, ModuleName="ScriptPlugin")]

その他のオプションは、Epic エクスポータに不要か予約済みのいずれかです。たとえば、前述の例の Description は必須オプションではありません。

その他の UHT 拡張

UnrealHeaderTool クラス属性は、エクスポータ以外の多数のものに使用されます。現在、スクリプトジェネレータのエクスポータは、サポートされている拡張タイプのみです。

次の属性は、UHT 内の重要な要素を定義します。

属性	説明
`UhtKeword`	`UCLASS` などのトークン。
`UhtSpecifier`	指定子。
`UhtSpecifierValidator`	メタデータのバリデータ。
`UhtPropertyType`	新しいプロパティタイプ。
`UhtStructDefaultValue`	`USTRUCT` のデフォルト値。
`UhtLocTextDefaultValue`	`LOCTEXT` マクロのデフォルト値。
`UhtEngineClass`	C# クラスを別のエンジンタイプに関連付けます。

コード生成の変更が不要であるため、新しい指定子、バリデータ、およびデフォルト値を追加できます。新しいエンジンタイプ、プロパティタイプ、またはキーワードを追加すると、正しく実装するためにエンジンに多数の変更が必要になるので、これらの追加は慎重に行う必要があります。

UHT コマンドラインリファレンス

オプション

コマンドライン引数	説明
`-Verbose`	ログ出力の詳細を増やします。
`-VeryVerbose`	ログ出力の詳細を最大化します。
`-Log`	ログファイルの場所を指定します。この引数を指定しない場合、使用されるデフォルトの場所は「`Engine/Programs/UnrealHeaderTool/Saved/Logs/UnrealHeaderTool.log`」です。
`-Timestamps`	ログにタイムスタンプを含めます。
`-FromMsBuild`	Microsoft Build Engine (MSBuild) 用にメッセージをフォーマットします。
`-NoLog`	デフォルトのログファイルなど、ログファイルの作成を無効にします。
`-Test`	テストスクリプトを実行します。
`-WarningsAsErrors`	警告をエラーとして扱います。
`-NoGoWide`	同時のパースとコード生成を無効にします。
`-WriteRef`	出力をすべて参照ディレクトリに書き込みます。
`-VerifyRef`	出力をすべて検証ディレクトリに書き込み、参照出力と比較します。
`-FailIfGeneratedCodeChanges`	出力ファイルへの任意の変更をエラーとして見なします。
`-NoOutput`	参照出力以外の出力ファイルを保存しません。
`-IncludeDebugOutput`	デバッグに役立てるために生成済みの出力に追加のコンテンツを含めます。
`-NoDefaultExporters`	すべてのデフォルトのエクスポータを無効にします。特定のエクスポータを実行する必要がある場合に便利です。

ジェネレータ

コマンドライン引数	説明
`-Stats`	タイプの統計。
`-NoStats`	タイプの統計を無効にします。
`-Json`	パッケージの Json の説明。
`-NoJson`	パッケージの Json の説明を無効にします。
`-CodeGen`	標準 Unreal Engine コードジェネレータ。これはデフォルトのジェネレータです。
`-NoCodeGen`	デフォルトの Unreal Engine コードジェネレータを無効にします。

詳細情報

Unreal Engine リフレクションシステム

UObjects とその関連メタデータ指定子などの Unreal Engine リフレクションシステムの詳細については、「Unreal Engine リフレクションシステム」のドキュメントを参照してください。

Unreal Build Tool

Unreal Engine ビルドプロセスおよびビルドのカスタマイズの詳細については、「Unreal Build Tool」のドキュメントを参照してください。