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

スクリプト可能ツール システムの目的は、非 C++ プログラマーが Unreal Editor でインタラクティブ ツールをビルドできるようにすることです。インタラクティブ ツールとは何かという主な基準点は、モデリング モード です。しかし、スクリプト可能ツール システムはモデリングやメッシュと直接関係ありません。

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

基本クラスの BP サブクラスを作成することで、ユーザー定義のカスタム仕様のツールを スクリプト可能ツールのエディタ モード に追加することができます。スクリプト可能ツールは、ジオメトリ スクリプト処理 と組み合わせることにより、複雑なモデリング ワークフローやアセット編集ワークフローを実装できます。モデリング モードやジオメトリに関連していない、よりシンプルな機能にもこのツールを使用できます。

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

スクリプト可能ツールを使用すると、以下のことが可能なある種のミニモードを作成できます。

• ツール セットアップ時、シャットダウン時、およびティックで任意のブループリント (BP) グラフを実行する。
• 基本的な 3D ジオメトリ (ライン、ポイント) と 2D HUD ジオメトリ (投影された 3D 位置のテキスト) を描画する。
• ツールの設定として機能する、ブループリントで定義されたツールをプロパティ セットに追加する。
• そのプロパティ セット パラメータへの変更をリッスンして対応する。
• 1 つ以上の 3D ギズモを作成し、その位置を制御し、トランスフォームの変更に対応する。
• ユーザーにフィードバック メッセージを提供する。
• 特定のタイプのマウス操作をキャプチャし対応する。具体的にはビューポート内でのクリック、クリック-ドラッグ操作、および Shift、Ctrl、Alt 装飾キーを押しながらマウスでカーソルを乗せる操作。

すべてのスクリプト可能ツールには、スクリプト可能ツールのエディタ モードからアクセスします。スクリプト可能ツールのエディタ モードでは、各ツールは自動管理されたツール パレットに表示され、アクティブなツールのプロパティ セットは標準のエディタ モードの [Details (詳細)] に公開されます。エディタ モードの詳細については、「ツールとエディタ」 を参照してください。

このページの 「スクリプト可能ツールを作成する のセクションには、レベルに新しい動的メッシュ球形をスポーンするツールを作成するためのチュートリアルがあります。

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

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

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

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

UI の点では、スクリプト可能ツールは EUW よりも構造的です。パブリック変数でプロパティ セットを個別の BP オブジェクトとして定義できます。その後、そのパブリック変数は、標準の [Details] パネルで表示されます。これはいくつかの点で EUW よりもはるかにシンプルですが、シンプルさには当然多くの制限が伴います。現時点で、スクリプト可能ツールのカスタム UI をビルドする方法はありません。

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

UInteractiveScriptabletool

UInteractiveScriptabletool はすべてのスクリプト可能ツールの基本クラスです。しかし、エディタ ツールのビルドには EditorInteractiveScriptabletool をサブクラス化が最適だと思われます。そうでなければ、エディタ専用の BP 関数にアクセスできません

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

基本クラスは、主にスクリプト可能ツールのエディタ モード UI のための、ツールの動作も制御できるさまざまな設定を公開します。

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

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

• 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 ジオメトリを描画できるようにします。

ツール レンダリング

ビジュアル フィードバックを提供しようとすることは、ツールでは非常に一般的です。たとえば、一時的なアクタをスポーンすることにより、いつでも行うことができます (これを行う簡単な方法の例としては、ジオメトリ スクリプトによってプロシージャルに生成されたメッシュによる一時的な動的メッシュ アクタのスポーンがあります)。しかし通常、ラインまたはテキスト ラベルの方が効果的です。

ツールは、一連の UFunction ノードを提供する 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 ウィジェットを公開します。標準の [Details] パネルに表示されます。現時点では、ブループリントでこの 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 でツールのセットアップに保存した値を復元できます。デフォルトで、プロパティ セット クラスを使用するすべてのツールに同じ値が復元されます。しかし、異なるツールまたは同じツール内であっても、異なる値を保存または復元するためにオプションの 保存キー を提供できます。

プロパティ ウォッチャー

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

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

BP では現在、変数の参照から UProperty 型を自動的に検出するのは不可能なため、以下を行う必要があります。

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

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

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

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

ベース ツール

ベース ツールは、一般的なケースの処理および/または入力デバイスの処理とキャプチャなどの追加の機能の公開のための追加のビルトイン機能を提供する C++ スクリプト可能インタラクティブ ツール フレームワークです。

スクリプト可能単独クリック ツール

マウス クリック サポートは以下のとおりです。

• TestIfHitByClick： マウス クリックをキャプチャするためのヒットの深度を示す有効な FInputRayHit を返す必要があります。

• OnHitByClick： マウス ボタンを押したときと離したときの両方でクリックが発生する場合に呼び出されます。

カーソルを乗せた状態のサポートは以下のとおりです。

• OnHoverHitTest： カーソルを乗せた状態をキャプチャするためのヒットの深度を示す有効な FInputRayHit を返す必要があります。

• OnHoverBegin： OnHoverHitTest を通過したあと、カーソルを乗せるシーケンスが始まるときに呼び出されます。

• OnHoverUpdate： カーソルを乗せた状態の間、カーソルが移動するたびに呼び出されます。

• OnHoverEnd： カーソルを乗せた状態が終了するときに呼び出されます。

スクリプト可能クリック ドラッグ ツール

マウス ドラッグ サポートは以下のとおりです。

• TestIfCanBeginClickDrag： ドラッグ シーケンスを開始するためのヒットの深度を示す有効な FInputRayHit を返す必要があります。

• OnDragBegin： TestIfCanBeginClickDrag を通過したあと、ドラッグ シーケンスが始まると呼び出されます。

• OnDragUpdatePosition： ドラッグ シーケンス中にカーソルが移動したとき呼び出されます。

• OnDragEnd： マウス ボタンを離したことによりドラッグ シーケンスが終了した場合に呼び出されます。

• OnDragSequenceCancelled： Esc キーやウィンドウがフォーカスを失うなど、さまざまな理由でドラッグ シーケンスが終了した場合に呼び出されます。

カーソルを乗せた状態のサポートは以下のとおりです。

• OnHoverHitTest： カーソルを乗せた状態をキャプチャするためのヒットの深度を示す有効な FInputRayHit を返す必要があります。

• OnHoverBegin： OnHoverHitTest を通過したあと、カーソルを乗せるシーケンスが始まるときに呼び出されます。

• OnHoverUpdate： カーソルを乗せた状態の間、カーソルが移動するたびに呼び出されます。

• OnHoverEnd： カーソルを乗せた状態が終了するときに呼び出されます。

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

エディタ内の使用では ScriptabletoolsFramework または ScriptabletoolsEditorMode のみが必要な「uproject」ファイルと「uplugin」ファイルの Editor のみが TargetAllowList セクションに含まれるように、以下のとおり設定します。

		{

			"Name": "ScriptabletoolsEditorMode",

			"Enabled": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

{ "Name": "ScriptabletoolsEditorMode", "Enabled": true, "TargetAllowList": [ "Editor" ] },

スクリプト可能ツールを作成する

このガイドでは、半径プロパティがツールの UI で公開される新しい動的メッシュ球体をクリック時にレベル内でスポーンする新規ツール ブループリントを作成する方法について説明します。

プラグインを有効にする

スクリプト可能ツール エディタ モードを利用するには、関連付けられたプラグインを有効にする必要があります。

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

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

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

   
3. Scriptable Tools Editor Mode プラグインを有効にし、ダイアログのポップアップで、[Yes (はい)] を選択します。スクリプト可能ツール フレームワーク モジュールはエディタ モードによって自動的に含まれるため、有効にする必要はありません。
4. 以下の手順の一部の関数は Geometry Scripting プラグインも必要とするため、まだ有効にしていない場合は有効にします。
5. エディタを再起動したあと、[Selection Mode (選択モード)] ドロップダウンから新しいモード、Scriptable Tool モードに変更します。

6. 左側に空のツール パレットがある以下のような UI が表示されるはずです。

   

コア設定

1. コンテンツ ブラウザ 内で右クリックして、ポップアップ ウィンドウの [Editor Utility (エディタ ユーティリティ)] サブメニューを選択し、新規 エディタ ユーティリティ ブループリント を作成します検索ボックスに「Scriptable」と入力し、EditorScriptableSingleClicktool を選択します。

   

   厳密には「エディタ ユーティリティ ブループリント」を使用する必要はありません。通常の ブループリント クラス を作成することもできます。しかし、エディタ ツールを作成する際、エディタ ユーティリティ ブループリントの代わりにブループリント クラスを使用する場合、エディタ サブシステムと他のさまざまなエディタ専用機能にはアクセスできません (EditorScriptabletool 内にも)。

2. 新規 BP アセットの名前を「tool_MakeSphere」にし、右クリック して [Edit (編集)] を選択するか、アセットを ダブルクリック して、ブループリントを開きます。BP エディタの右側の [Details] パネルで、ツールに名前を付けることができます。この例では「Sphere」が使われています。また、[Category (カテゴリ)] の名前に文字列を入力します。

   

3. コンパイル (Ctrl + Alt) して 保存 (Ctrl + S) します。スクリプト可能ツール モードに切り替えます。ツール パレットの該当する カテゴリ 名のセクションに Sphere ツールが表示されるようになるはずです。

   

4. Sphere ツールを実行できるようになりました。もちろん何も実行されませんが、ツールを開始することができます。ビューポートの下部中央の [Complete (完了)] ボタンを使用して、ツールを終了します。

   

5. BP エディタに戻ります。左のパネルで [Function (関数)] セクションの最後にカーソルを乗せます。[Override (オーバーライド)] ドロップダウンが表示されます[Test If Hit By Click (クリックによるヒットのテスト)] を選択し、マウスのヒットテストの新規イベントを作成します。ドロップダウン リストの関数は、実装できる利用可能なツール API 関数です。

6. 以下のとおり関数を接続します。

   

7. 2 つ目の オーバーライド を On Hit By Click イベントに追加します。

8. Event On Hit By Click の Click Pos ピン上で右クリックし、[Split Struct Pin (構造体ピンを分割)] を選択します。それから、以下のとおり Click イベントを接続します。ここでは基本的に、Hit Test イベントと同じライントレースを繰り返し、ヒット時に 動的メッシュ アクタ (ここのノードは最初は「Spawn actor from Class」で、ドロップダウンから [Dynamic Mesh actor (動的メッシュ アクタ)] を選択すると名前を変更します) をスポーンし、Geometry Scripting を使用してそのアクタ内のメッシュを Sphere に設定しています。

   

   [Split Struct Pin] オプションは、グラフをシンプルにするため、BP ノードのピン上で右クリックして使用します。

9. コンパイルし、メインのビューポートに戻り、Sphere ツールを実行します。ビューポート内でクリックすると、クリックした位置に新しい球体が配置されるはずです。

   

半径プロパティを追加する

これでツールのベースが作成できました。機能を拡張するために、球体に半径の設定を追加できます。

1. コンテンツ ブラウザに戻って右クリックし、新規 ブループリント クラス を作成し、検索ボックスに「propertyset」と入力し、ScriptableInteractivetoolPropertySet を選択します。新規 BP アセットに名前を付け (ここでは「MakeSphere_Settings」を使用)、開いて編集します。

   

2. 左の [Variables (変数)] セクションの丸の中の [+] をクリックして新規変数を追加します。名前を 「Radius」 にし、型を [Float (浮動小数)] に変更し、目アイコンをクリックして目を開いて変数を パブリック にします (変数をパブリックにしなければ詳細パネルに表示されません)。コンパイル (Ctrl + Alt) して 保存 (Ctrl + S) します。

3. 右のパネルで [Slider Range (スライダ範囲)] フィールドを探し、値を 10 と 200 に設定し、[Default Value (デフォルト値)] を 50 に設定します。再び コンパイル します。

   

4. ツール ブループリントに戻り、On Script Setup 関数に オーバーライド を追加します。

5. Event On Script Setup で Add Property Set Of Type ノードを呼び出し、[Type (タイプ)] ドロップダウンで自分のプロパティ セット BP クラスを選択します (上記で使用したものと同じ名前「MakeSphere_Settings」)

   

6. プロパティ セットに変数を作成します。そうすることで、あとの作業が簡単になります。Cast To ノードを追加します。 は自分の BP 設定クラスの名前です (たとえば、MakeSphere_Settings)。

7. As Make Sphere Settings ピン上で 右クリック し、[Promote to Variable (変数へ昇格)] を選択します。これにより、自動で新規変数が追加されます。変数の名前を「Settings」に変更します。

8. グラフの On Hit By Click イベントに戻り、パブリック Radius フィールドを Settings 変数から Append Sphere Box ノードの Radius ピンに接続し、コンパイル します。

   

9. ビューポートに戻り、Sphere ツールを再度実行します。[Details] パネルに Radius のスライダが表示されるはずです。この値を変更すると、配置された球形のサイズが変わります。

   

カスタム設定のあるツールの作成とマウス クリックの処理をすべてブループリントで行いました。