スクリプト可能ツール システム

スクリプト可能ツール システムは、カスタム インタラクティブ ツールを作成するための機能とエディタ モードを提供します。このシステムの目的は、非 C++ プログラマーが Unreal Engine でインタラクティブ ツールをビルドできるようにすることです。

インタラクティブ ツールの主な基準点は、モデリング エディタ モード です。しかし、スクリプト可能ツール システムはモデリング モードやジオメトリ スクリプトと直接関係ありません。

スクリプト可能ツール システムのプラグインは、ブループリント (BP) に インタラクティブ ツール フレームワーク を公開し、クリエイターやテクニカル アーティストがモデリング モードと同様に動作するツールを設計する方法を提供します。

スクリプト可能ツールを使い始める際は、ブループリントの基本を学んでおくことをお勧めします。詳細については、「ブループリント入門」を参照してください。

基本クラスのブループリント (BP) サブクラスを作成することで、カスタム仕様のツールを スクリプト可能ツール のエディタ モードに追加することができます。エディタ モードを使うと、プロジェクトでこれらのカスタム ツールにアクセスできます。

スクリプト可能ツールは何のために使用しますか？

スクリプト可能ツールの用途

• ツール セットアップ時、シャットダウン時、およびティックで任意のブループリント (BP) グラフを実行する。
• 基本的な 3D ジオメトリ (たとえばライン、ポイント) と 2D HUD ジオメトリ (たとえば投影された 3D 位置のテキスト) を描画する。
• ユーザーから見えるツール設定として機能する、ブループリントで定義されたプロパティ セットをツールに追加する。
• それらのプロパティ セット パラメータへの変更をリッスンして対応する。
• 1 つ以上の 3D ギズモを作成し、その位置を制御し、トランスフォームの変更に対応する。
• ユーザーにフィードバック メッセージを提供する。
• マウス クリック、マウス ホバー、キーボード ウォッチャーなどの入力デバイス動作を追加し、それらのキー イベントでブループリントのグラフを実行する。
• ブループリント スレート ウィジェット (UMG) と統合し、ビューポート ウィジェットのようなカスタム ユーザー インターフェース (UI) を提供する。
• 現在のシーン選択に基づいて、ツールを開始するためのカスタム条件を定義する。

スクリプト可能ツールは、プロシージャル コンテンツ生成 (PCG) やモーション デザイン など、エンジンの他の機能と組み合わせることができます。

システムの概要や、デベロッパーが他の機能と組み合わせてダンジョンを構築している方法については、「Geometry Scripting and Scriptable Tools (ジオメトリ スクリプト処理とスクリプト可能ツール) | Unreal Fest 2024」の動画を参照してください。

スクリプト可能ツールのエディタ モードとノードにアクセスする

プラグインを有効化

スクリプト可能ツールのエディタ モードを使用し、ノードにアクセスするには、関連するプラグインを有効にする必要があります。

プラグインを有効にするか、すでに有効になっていることを確認するには、次の手順に従います。

1. メニュー バー で、[Edit (編集)] > [Plugins (プラグイン)] を選択します。

2. 検索バー に、「scriptable tools」と入力します。

3. Scriptable Tools Editor Mode プラグインを有効にし、ダイアログのポップアップで、[Yes (はい)] を選択します。

スクリプト可能ツール フレームワーク モジュールを有効にする必要はありません。エディタ モードでは、自動的にそれが含まれています。

エディタ モード

すべてのスクリプト可能ツールは スクリプト可能ツール のエディタ モードからアクセスします。エディタ モードを開くには、レベル エディタのドロップダウンで [Selection Mode (選択モード)] をクリックします。

各ツールはエディタ モードで自動的に管理されるツール パレットに表示され、アクティブなツールのプロパティ セットは設定パネルに表示されます。エディタ モードの詳細については、「レベル エディタ モード」を参照してください。

ツール パレットには、グループ タグに応じてツールが表示されるフィルタ オプションがあります。この機能を使うと、ツールをグループ化し、エディタ モードで読み込むツール グループを選択することができます。グループ化することで、多くのツールがあるプロジェクトを整理することができるため、すべてのツールから探し出す負担が軽減されます。

ブループリント ノード

エディタ モードで表示されるツールを作成するには、ブループリントで公開されているスクリプト可能ツール機能を使用します。スクリプト可能ツールの基本クラスにアクセスするには、ブループリント クラスまたはエディタ ユーティリティ ブループリントのどちらかを使用できます。基本クラスとサブクラスの詳細については、このページの「スクリプト可能ツール クラス」セクションを参照してください。

ブループリント エディタでは、すべてのスクリプト可能ツール ノードはスクリプト可能ツール サブメニューの下にあります。

ブループリント エディタ内のスクリプト可能ツール サブメニュー。

機能の全リストは、ブループリント と Python の API ドキュメントを参照してください。

スクリプト可能ツールとエディタ ユーティリティ ウィジェットの違い

エディタ ユーティリティ ウィジェット (EUW) は、非モーダル ダイアログ ウィンドウで、ビジュアル GUI ビルダーでビルドされたカスタム UI を含みます。このビジュアル GUI ビルダーでは、あらゆるエディタ スクリプト処理が可能です。非常に強力な機能ですが、非モーダル ダイアログであるため、さまざまな制限があります。

インタラクティブ ツール (スクリプト可能ツールの基礎) は、モーダル です。つまり、ツールがアクティブな間は他のツールはアクティブにできず、エディタの状態がより厳しく管理されます。たとえばツールは、保存、レベルの変更、プレイインエディタ (PIE) の開始前に自動的にシャットダウンし、自動保存は、ツールを終了するまで延期されます。この機能があるため、多くのことはツールで行う方がツール以外で行うよりも安全です。たとえばレベルで一時的なアクタを作成し、ツールのシャットダウン時に破壊する場合、間違って保存されることはありません。

同様に、モーダル状態では、ツールはマウスをより効率的にキャプチャできます。

UI の点では、スクリプト可能ツールは EUW よりも構造的です。パブリック変数でプロパティ セットを個別の BP オブジェクトとして定義できます。これらのパブリック変数は、標準的なエディタ モードの設定パネルに表示されます。

スクリプト可能ツールは、ランタイム時でも利用可能ですが、UE プロジェクトでこれを活用するために追加のインフラストラクチャを設定する必要があります。

また、スクリプト可能ツールはプロジェクト内にあるすべてのツールを発見し、アクセスするための中心的な場所であるのに対して、EUW は主にコンテンツ ブラウザからアクセスするためのものであり、検索性と構成の管理はユーザーに任されています。

スクリプト可能ツールのクラス

UScriptableInteractiveTool はすべてのスクリプト可能ツールの基本クラスです。 このクラスには、イベント、ツール名などの一般的な設定、レンダリング オプション、ギズモ、メッセージング、ツールのシャットダウン オプションなどがサブクラスに含まれています。エディタ専用の BP 関数にアクセスするには、エディタ変数の UEditorScriptableInteractiveTool を使用します。

UScriptableModularBehaviorTool と UEditorScriptableModularBehaviorTool は、ツール内でマウスとキーボードのインタラクションをサポートするためのサブクラスです。マウスとキーボードの動作が不要でない限り、この 2 つのクラスが一般的に使われます。

UScriptableClickDragTool は非推奨です。ただし、以前にこのクラスを使って作成したツールは、最新バージョンのエディタでも機能します。

ブループリント クラスまたはユーティリティ ウィジェット ブループリントを作成する際にスクリプト可能ツール ノードにアクセスするには、上記のクラスのいずれかを選択する必要があります。これらのクラスの詳細については、このページの「モジュラー ベース ツール」セクションを参照してください。

スクリプト可能ツールの設定

基本クラスは、主にスクリプト可能ツールのエディタ モード UI のための、ツールの動作も制御できるさまざまな設定を公開します。ブループリントを開くと、ツールの [Details (詳細)] パネルに以下のオプションが表示されます。

スクリプト可能ツール イベント

スクリプト可能ツールのクラスは、ツールがさまざまなときにさまざまなことを行うための一連の標準イベントを提供します。すべてのツール クラスには標準イベントがあり、さまざまな追加の関数がベース ツールで利用できます。

• Event On Script Setup： ツールが起動したとき 1 回実行します。通常ここにプロパティ セットを追加し、プレビュー オブジェクトなどを作成します。

• Event On Script Tick： 他のティックと同じように、エディタ ティックごとに実行します。

• Event On Script Shutdown： ツールがシャットダウンされたときに実行します。たとえば、ユーザーが明示的にツールを閉じた場合、モードがツールを強制的にシャットダウンするかツールが自らシャットダウンします。

• Event On Script Draw HUD： フレームごと、およびツールが HUD API オブジェクトから 2D HUD を描画できる場合に実行します。詳細については、以下のセクションを参照してください。

Event On Script Render はレガシーな描画方法です。イベントがフレームごとに実行され、ツールがラインやポイントなどのシンプルな 3D ジオメトリを描画できるようにします。レガシー機能は使用可能ですが、以下の点に注意してください。

• このイベントはリアルタイムであるため、Render が呼び出されるたびに線が再描画される。

• ジオメトリには永続的な参照が保持されていないため、ブループリント内でプリミティブの操作を管理する必要がある。

カスタム条件

ツールを開始するための現在のシーン選択に基づいてカスタム条件を追加することができます。カスタム条件は、[Class Defaults (クラス デフォルト)] > [Details (詳細)] パネル > [Scriptable Tool Settings (スクリプト可能ツール設定)] > [Tool Setup Requirements (ツール設定要件)] > [Custom (カスタム)] で定義できます。

カスタム クラスには以下の関数が含まれています。

• OnCanBuildTool： ティックで実行する必要があります。

• OnSetupTool： ユーザーがクリックした後、ツールの実行前に機能します。

ツール ビルダー グラフはティックごとに実行されるため、ここでの複雑な条件はエディタのパフォーマンスを低下させる可能性があります。

ツール レンダリング

ツールはビジュアル フィードバックを提供するのが一般的です。このフィードバックを定義する 1 つの方法は、一時的なアクタをスポーンすることです。たとえば、ジオメトリ スクリプト処理によってプロシージャルに生成されたメッシュを使用して、一時的なダイナミックメッシュ アクタをスポーンできます。しかし通常、ラインまたはテキスト ラベルの方が効果的です。

スクリプト可能ツールは、一連の UFunction ノードを持つ API オブジェクトを提供することにより、このようなレンダリングをサポートします。

レンダリングオプション

スクリプト可能ツールの Drawing API には、線、点、三角形の描画オプション セットがあります。各セットには、「描画」カテゴリの追加の相対オプションが含まれています。

これらの描画オプションはツールによって割り当てられ、ジオメトリを含みます。これらのセットを使えば、ツールの存続期間中いつでも、それぞれのジオメトリを追加したり削除したり、必要に応じて更新したりすることもできます。

Add Triangle Set ノードにはクワッド用のオプションがあります。

レガシー オプション

従来のレンダリング コマンドは Event On Script Render イベント ノードで実行します。

このイベントについては、前述したように以下のとおりです。

• レンダリング API でオーバーライドできる。

• 線と点を描画する。

• ティックで実行され、次のティックで消える。

• 永続性なし。

2D 描画 HUD と 3D レンダリング イベントはそれぞれ、DrawHUDAPI オブジェクトと RenderAPI オブジェクトによって呼び出されます。ツールは、内部でこの API オブジェクトを作成し管理します。この API オブジェクトは、ツールによって提供されるフレームごとの一時的状態の情報に依存するため、アクセスできる場所はこのイベントからのみです。

BP にはデバッグ描画関数の標準ライブラリもあります。DrawHUD とレンダリング関数のオルタナティブとして使用することもでき、いつでも呼び出すことができます。しかし、これは開発のみであり、今後はツール レンダリング API の機能を増やす予定です。

ギズモ

スクリプト可能ツールの基本クラスの別の機能は、複数の 3D トランスフォーム ギズモを作成するオプションです。これは標準エディタ ギズモではなく、モデリング モードのギズモ です。ギズモを開発および管理するための一連の関数と、ギズモの変更に対応するためのイベントが提供されます。

ギズモ オブジェクトは、ブループリントに直接公開されません。代わりに、文字列 識別子 でギズモをスポーンします。さまざまなギズモ関数とイベントはこの識別子から動作します。

基本 TRS ギズモは、すべての軸の平行移動、回転、縮尺の要素を組み合わせます。しかし、ギズモ オプション をカスタマイズすることにより、特定のタスクのためのよりシンプルなギズモを作成できます。たとえば、他のギズモのサブ要素を無効にして XY 平面の平行移動と回転のみを有効にします。

ツール メッセージング

標準のスクリプト可能ツールの BP API は、ユーザーへのメッセージのためのさまざまな関数を提供します。

• Display User Help Message は、エディタ UI の下部にあるヘルプ文字列を更新します。

  

• Display User Warning Message は、ツールの [Settings (設定)] パネルの文字列を更新します。

  
• Clear User Messages は、現在のヘルプまたは警告メッセージをクリアします。
• Add Log Message は現在、エディタのログにメッセージを出力します。

上記のメッセージは FText 文字列で、ローカライズも可能です。現時点では、単一の警告のみ表示できますが、これは将来改良される可能性があります。

未分類

スクリプト可能ツールは常に、現在のワールドのコンテキスト内で実行します。たとえば、レベル エディタでは、標準レベル ワールドです。Get Tool World 関数を使用して、ツールのコンテキスト内のこのワールドにアクセスできます。

ツール シャットダウン

既存のスクリプト可能ツールの標準フローは、UI に表示される [Accept (同意)]、[Cancel (キャンセル)]、または [Complete (完了)] ボタンをクリックします。しかし、ツールが自らを呼び出すこともできる Request tool Shutdown 関数により、スクリプト可能ツールを明示的にシャットダウンすることもできます。この関数は、bAccept フラグを受け取ります。このフラグは、シャットダウンの同意とキャンセルのオプションがあるツール、およびオプションのユーザー ポップアップ メッセージにのみ関連します。

ツール プロパティ セット

スクリプト可能ツールは、Property Set UObject をとおしてユーザーに UI ウィジェットを公開します。標準の [Tool Settings (ツール設定)] パネルに表示されます。現時点では、ブループリントでこの UI をカスタマイズする方法はないため、標準のプロパティ設定 (アクタ BP でパラメータに行えることと同様) のみ利用可能です。

プロパティ セットを作成するには、以下のとおり、ScriptableInteractivetoolPropertySet 型の BP サブクラスを作成します。

それから、編集のためにプロパティ セット サブクラス BP を開き、パブリック メンバー変数を追加します。以下のブーリアン、整数、列挙型が追加されます。

特定のスクリプト可能ツールでプロパティ セットを作成するには、Add Property Set of Type 関数を使用します。この関数は通常、Event On Script Setup で使用されます。ただし、いつでも使用できます。

Property Set Type パラメータに正しいクラス タイプを選択する必要があります。上記で作成した BP サブクラスのタイプ名を選択します。さらに、各プロパティ セットに対して一意の 識別子 を設定する必要があります (単一のツールに複数のプロパティ セットを組み合わせることができます)。あとでこのプロパティ セット オブジェクトへのアクセスが必要になる可能性があります。そのため、Add Property Set Of Type の出力を BP サブクラス タイプにキャストし、ローカル変数に保存することを推奨します。

ユーザーがスクリプト可能ツールのインスタンスを作成する場合、プロパティ セットのパブリック メンバー変数がツールパレットの横、[Scriptable Tools (スクリプト可能ツール)] 設定パネルの左に表示されるようになります。

スクリプト可能ツール クラスには、プロパティ セットで作業するためのさまざまなヘルパー関数があります。Remove Property Set by Name を使用してプロパティ セットを削除できますが、ほとんどの場合、必要ないことに留意してください。何かの基準または他のパラメータ変更に基づいてプロパティ セットの非表示と表示を単に切り替えたい場合、Set Property Set Visible by Name を使用してください。

さらに、ツールシャットダウン時に Save Property Set Settings を使用して、プロパティ セットの現在の値を保存し、Restore Property Set Settings でツールのセットアップに保存した値を復元できます。デフォルトで、プロパティ セット クラスを使用するすべてのツールに同じ値が復元されます。しかし、異なるツールまたは同じツール内であっても、異なる値を保存または復元するためにオプションの 保存キー を提供できます。

プロパティ ウォッチャー

プロパティ セットで必要性が高いと思われる一般的な関数は、プロパティ値の変更に対応する関数です。完全に信頼できる唯一の解決策は、ティック関数で値をポーリングすることです。しかし、これは一般的なパターンであるため、スクリプト可能ツール システムはこのようなポーリングを自動的に行うことができるユーティリティのプロパティ ウォッチャー関数を提供しています。

スクリプト可能ツールで以下の関数を使用して、プロパティ セットの特定のプロパティの変更をウォッチし、値が変更されたらイベントを呼び出します。

BP では現在、変数の参照から UProperty 型を自動的に検出するのは不可能です。検出の準備をするには、以下を行います。

• プロパティ セットのパブリック変数の型に一致する関数を必ず使用する。
• 正しい プロパティ名 (プロパティ セットのパブリック変数の名前) をパスする。

シンプルな型 (整数、フロート、ブール、文字列、FName、列挙型またはオブジェクト プロパティ) ではない場合、汎用 Watch Property バージョンを使用できます。ただし、そのコールバック イベントはより制限されます。

以下は Watch Enum Property 関数の例です。列挙型は知られていないため、これは、シンプルな型の最も複雑なものです。コールバック イベントに渡される New Value パラメータは uint8 で、正しい UEnum 型 (この場合は EGeometryScriptAxis) に明示的にキャストされる必要があります。現時点では、ここでのエラーをチェックできません。エディタはこの関数を任意の列挙型にキャストします。

複雑なパラメータ (たとえば、FVector メンバー変数などのネスティングされている UStruct) では、Watch Property 関数を使用できます。この関数はほとんどすべての UProperty 変数の変更を検出できます。ただし、コールバックイベントは他のフィールドのように New Value パラメータを受信しません。ツールでプロパティ セットにメンバー変数を作成した場合、イベントでプロパティ値を直接フェッチできます。また、このウォッチャー型は計算量が多いため、必要な場合に限って使用してください。

モジュラー ベース ツール

ベース ツールは、一般的なケースの処理および入力デバイスの処理とキャプチャなどの追加の機能の公開のための追加のビルトイン機能を提供するスクリプト可能インタラクティブ ツール フレームワークの C++ サブクラスです。作成するツールの型に応じて、ベース ツールを選びます。ベース ツールのエディタ バージョンでは、エディタ専用の BP 関数にアクセスできます。

スクリプト可能モジュラー動作ツール クラスとそのエディタ インスタンスは、コールバックのリストでパラメータ化された動作関数へのアクセスを提供します。このシステムは、組み込みイベントを置き換えて、必要な場合は複製を行って動作を組み合わせてマッチさせる手段として利用できます。この置き換えは、1 つのツールの中に、異なる条件でトリガーされる複数のクリック動作を作成できるため、便利です。たとえば、マウスの左ボタンでクリックし、右ボタンでクリックして、左クリック + ctrl でといった動作も可能です。

公開された動作の例：

• クリックとドラッグ
• ホバー
• マウスのホイール
• マルチクリック
• クリックまたはドラッグ
• シングルおよびマルチ キーボード入力

スクリプト可能ツールの動作入力。

エディタのみでプラグインを有効化する

Unreal Engine では、プロジェクトのモジュールやプラグインに対してプラグインの依存関係を定義することができます。

エディタ内で使用する際に UScriptabletoolsFramework または UScriptabletoolsEditorMode を必要とする .uproject ファイルおよび .uplugin ファイルでは、TargetAllowList セクションを Editor に設定します。 プラグインとファイル設定の詳細については、「プラグイン」を参照してください。

		{

			「名前」：「ScriptabletoolsEditorMode」、

			「有効」：true、

			「TargetAllowList」：[

				「エディタ」

			]

		},	
Copy full snippet

{ 「名前」：「ScriptabletoolsEditorMode」、 「有効」：true、 「TargetAllowList」：[ 「エディタ」 ] },

次のステップ

スクリプト可能ツール システムの基本を理解できたところで、「スクリプト可能ツールを作成する」のチュートリアルに従って独自のツールを作り始めましょう。