コントロールリグで Python スクリプティング を使用すると、ワークフローを自動化し、リギング プロセスのためのツールを作成できます。また、コントロールリグの Python ログ を使用してコマンドをリバースエンジニアリングし、スクリプトをコピーして他のプロジェクトと共有することもできます。
このドキュメントでは、コントロールリグでの Python スクリプティングの概要、コントロールリグの Python ログについて説明し、スクリプト サンプルをいくつか紹介します。
前提条件
-
コントロールリグ アセットを開いていること。
-
Unreal Engine で Python スクリプティング を使用した経験があること。
スクリプティングの概要
Python は主にコントロールリグで、複数のモジュールで構成されるリグ グラフを操作するために使用されます。
モジュール名 | 説明 |
---|---|
ControlRig | リグのランタイムが格納されています。 |
ControlRigDeveloper | リグに変更を加えるためのすべての機能が格納されています。 |
ControlRigEditor | フロントエンドとユーザー インターフェースのロジックが格納されています。 |
コントロールリグ グラフは、モデル - ビュー - コントローラー の設計パターンを使用して実装されています。このモデルは、グラフ自体であり、以下の用語を使用します。
コントロールリグの Python の用語 | 説明 |
---|---|
RigUnit (リグユニット) | リグの関数を定義する C++ 構造体 (例:FRigUnit_GetBoneTransform)。 |
ピン | 関数の 1 つの入力または出力。 |
リンク | 2 つのピン間の接続。 |
ノード | RigUnit の視覚的な表現。 |
グラフ | リグ内のすべてのノードとリンクを含む有向グラフ。 |
PinPath (ピンパス) | グラフ内のピンのアドレスを記述した文字列 (例:NodeA.Translation.X)。 |
コントローラー | グラフで変更を行うために使用するオブジェクト。 |
RigElementKey (リグ要素キー) | ボーン、コントロール、Null、カーブから選択する。 |
ボーン | 変形に使用するスケルトン内のリグの要素。 |
コントロール | 相互作用に使用するリグの要素。 |
Null | 中間トランスフォームに使用するリグの要素。 |
カーブ | 浮動小数点チャンネルを格納するために使用するリグの要素。 |
形状 | ビューポートのコントロールの視覚的な表現。 |
階層 | リグ内のすべてのボーン、コントロール、Null、カーブを格納するコンテナ。 |
HierarchyController (階層コントローラー) | HierarchyController は、コントローラーと同じように、階層に変更を加えるために使用される。 |
コンパイラ | コントロールリグ グラフを高性能ランタイムにするためのオブジェクト。 |
VM | リグの実行に使用される仮想マシンのランタイム。 |
定数 | ランタイム時に変更されない値。 |
パラメータ | リグへの入力またはリグからの出力として使用可能な値。 |
変数 | ランタイム時に変更可能な値で、リグの実行後も保持される。 |
ControlRigBlueprint (コントロールリグブループリント) | グラフ、コントローラー、コンパイラ、VM を格納するアセット。 |
ファクトリ | 新しいオブジェクトを作成およびインポートするオブジェクト。これは、Unreal Editor 全体で、アセットを作成するために使用されます。 |
Python は、Python Editor Script プラグイン から有効化されます。このプラグイン自体は、Unreal Engine でデフォルトで有効になっています。また、Control Rig プラグイン を有効にすると、依存関係にあるため Python Editor Script プラグインも自動的に有効になります。
コントロールリグにアクセスする
スクリプトを作成する際の最初のステップは、操作するメイン オブジェクト (この場合は ControlRigBlueprint オブジェクト) にアクセスすることです。複数のアクセス方法がありますが、コントロールリグに変更を加えるため、通常、最初のコマンドで、ControlRigDeveloper モジュールをロードします。
unreal.load_module('ControlRigDeveloper')
既存のリグにアクセスするには、次のコマンド例を使用して、アセットをロードします。
rig = unreal.load_object(name = '/Game/ControlRig/Samples/Mannequin_ControlRig', outer = None)
また、次のコマンドを使用して、現在開いているコントロールリグ アセットをロードすることもできます。
rigs = unreal.ControlRigBlueprint.get_currently_open_rig_blueprints()
新しいコントロールリグ アセットを作成するには、次のコマンドを使用します。
factory = unreal.ControlRigBlueprintFactory()
rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')
最後に、次のコード サンプルを使用すると、スケルトンまたはスケルタル メッシュに基づくコントロールリグ アセットを作成できます。
# スケルタルメッシュをロードします
mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)
# そのメッシュにリグコントロールを作成します
factory = unreal.ControlRigBlueprintFactory
rig = factory.create_control_rig_from_skeletal_mesh_or_skeleton(selected_object = mesh)
Python ログ
Python ログ では、コントロールリグ エディタ内で実行したすべてのアクションのテキスト ログを提供します。このログには、ビューポート、階層、グラフ内のアクションが含まれます。このログを使用すると、Python スクリプトで使用するコマンドを参照することができます。
このログにアクセスするには、コントロールリグのメインメニューから [Window (ウィンドウ)] > [Message Log (メッセージ ログ)] をクリックし、[Message Log (メッセージログ)] のサイドバーから [Control Rig Python Log (コントロールリグの Python ログ)] を選択します。

これで、リグ グラフでアクションを実行すると、ログに記録されるようになりました。

コマンドを保存して共有したり、他の場所で使用したりする必要がある場合は、ログの任意の行を選択して Ctrl + C キーを押してコピーし、任意のテキスト エディタに貼り付けることができます。また、Shift キーを押しながら選択すると、複数の行を選択できます。

コマンドをテストするには、コマンドを [Output Log (アウトプット ログ)] に貼り付けて、実行します。この際、ログ タイプは必ず [Python] に設定します。この例では、新しいコントロールが作成されます。

Python コンテキスト
Python コンテキストは、Python コマンドを実行するときに、どのコントロールリグ アセットに作用する必要があるかをコンテキスト化するために使用されます。デフォルトでは、コントロールリグを表示する際には、コンテキストは設定されていません。現在のコントロールリグのコンテキストを設定するには、[Class Settings (クラス設定)] の [Details] パネルで、[Run Python Context (Python コンテキストを実行)] クリックします。

この操作により、現在のコントロールリグ アセットを Python コンテキストにバインドする一連のコマンドが実行されます。このことにより、Python ログからコピーしたコマンドをこのコントロールリグ アセット内に貼り付けて実行することができます。

blueprint.get_controller_by_name('').set_node_selection([])
import unreal
blueprint = unreal.load_object(name = '/Game/ShowAndTell202009/Pretzel/Mannequin_FBIK_CtrlRig', outer = None)
library = blueprint.get_local_function_library()
library_controller = blueprint.get_controller(library)
hierarchy = blueprint.hierarchy
hierarchy_controller = hierarchy.get_controller()
Python スクリプトのコピー
また、コントロールリグのノード、リグ要素、およびプロパティの全体をクリップボードにコピーすることができます。これを外部のスクリプト エディタに貼り付けたり、アウトプット ログに貼り付けることで、別のコントロールリグで実行することができます。Python スクリプトのコピーは、異なるリグ間のロジックの共有、デバッグ、比較に役立ちます。個別のコマンドのコピーと同様に、リグ全体をコピーすることも、コントロールリグから Python コマンドをリバースエンジニアリングするうえで役立ちます。
コントロールリグをコピーするには、[Class Settings] の [Details] パネルで [Copy Python Script (Python スクリプトをコピー)] をクリックします。

Python スクリプトのサンプル
ノードを追加する
ノードは RigUnit 構造体の視覚的な表現であるため、グラフにノードを追加するためには、このユニットにアクセスする必要があります。
unreal.load_module('ControlRigDeveloper')
# すべての使用可能なユニットの配列を取得します
units = unreal.ControlRigBlueprint.get_available_rig_units()
# そのユニットに関する詳細をプリントします
for unit in units:
print(unit.get_path_name())
print(unreal.EditorAssetLibrary.get_metadata_tag(unit, 'Keywords'))
次に、コントローラーにアクセスする必要があります。コントローラーは、グラフに変更を加えるために使用する中心的なオブジェクトです。
controller = rig.get_controller()
グラフにノードを追加するには、add_struct_node
関数、add_comment_node
関数、add_parameter_node
関数、または add_variable_node
関数を使用できます。以下の例では、最も一般的なタイプである struct (構造体) ノードに焦点を当てています。struct ノードは RigUnit を視覚的に表現したものです。そのため、グラフ内のほとんどのノードは struct ノードです。
# ユニットを取得します - これをパスまたは類似する単位 = unreal.RigUnit_MathFloatAdd.static_struct() でも取得することができます
# ユニット構造体、メソッド (常に Execute)、グラフ内の2次元位置を指定して、グラフにノードを追加します
node = controller.add_unit_node(script_struct = unit, method_name = "Execute", position = unreal.Vector2D(0, 0))
階層を編集する
グラフの編集だけでなく、Python コードを使用して階層を編集することもできます。コントロールリグ階層の各リグ要素は、RigElementKey を使用して識別されます。RigElementKey には、要素の名前とタイプが格納されています。階層内の要素を作成したり操作したりする際には、このキーを使用する必要があります。
コントロールリグの要素は構造体です。つまり、コントロールリグの要素はその合計値を使用してコピーされます。そのため、要素を変更すると、階層内でその要素を再度設定する必要がある場合があります。
階層 は、要素のクエリ、グローバル/ローカル トランスフォームのゲットまたはセット、要素の初期値へのリセットに使用することができます。
HierarchyController を使用すると、要素の追加、削除、編集を行うことができます。また、必要に応じて要素の名前を変更したり、要素の親を変更するために使用できます。
現在の階層の調査を実行するには、次の Python コードを使用できます。
# 階層オブジェクトにアクセスします
hierarchy = rig.hierarchy
# すべての要素キーを取得し、それらをプリントします
elements = hierarchy.get_all_keys()
for element in elements:
print(element)
ボーンなどのリグ要素を作成するには、次のコードを使用できます。
# access the hierarchy controller object
hierarchy_ctrlr = rig.get_hierarchy_controller()
# add a new bone
new_bone_key = hierarchy_ctrlr.add_bone(name = "MyBone", parent = unreal.RigElementKey(), transform = unreal.Transform())
# add a new child bone to a parent that is 10 units away on Z
child_transform = unreal.Transform(location = [0, 0, 10])
new_child_bone_key = hierarchy_ctrlr.add_bone(name = "ChildBone", parent = new_bone_key, transform = child_transform)
変数およびアセットの操作
ゲッター ノードおよびセッター ノードを使用してコントロールリグ変数を作成するには、次のコードを使用できます。
rig.add_member_variable("MyVariable", "Transform", is_public = True, is_read_only = False, default_value ="")
# 変数ゲッタノードを作成します。
controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = True, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Getter')
# 変数セッタノードを作成します
controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = False, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Setter')
また、プレビュー メッシュは以下のコードを使用して変更できます。
# スケルタルメッシュをロードします
mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)
# 新しい (空の) アセットを作成します
factory = unreal.ControlRigBlueprintFactory()
rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')
# プレビューメッシュを設定します
rig.set_preview_mesh(preview_mesh = mesh)
コンテキストに応じて、次のいずれかのコードを使用して、コントロールリグをコンパイルすることができます。
# VM の再コンパイルを強制します
rig.recompile_vm()
# 保留中の変更がある場合は VM をコンパイルします
rig.recompile_vm_if_required()
# 自動コンパイルが有効でエディタが開いている場合、コンパイルをリクエストします
rig.request_auto_vm_recompilation()
# コントロールリグに最初のパスの実行をリクエストします (全ユニットを初期化する)
rig.request_control_rig_init()
# コントロールリグに完全なブループリントのコンパイルをリクエストします
unreal.BlueprintEditorLibrary.compile_blueprint(rig)
エディタの起動
エディタ起動時に Python スクリプトをロードすることができます。これは、カスタム ツールやビルトインの Python 関数のロードに役立ちます。このスクリプトとサンプルのスクリプト関数は、次のフォルダ パスのプロジェクト ディレクトリに格納されています。
Engine\Plugins\Animation\ControlRig\Content\Python
このフォルダの中に、init_unreal.py スクリプトがあり、次のコードが格納されています。
import RigHierarchy.add_controls_for_selected
import RigHierarchy.add_null_above_selected
import RigHierarchy.align_items
RigHierarchy.add_controls_for_selected.run()
RigHierarchy.add_null_above_selected.run()
RigHierarchy.align_items.run()

このコードは、追加機能を有効にするサンプル スクリプトをロードします。
たとえば、add_controls_for_selected は、選択したボーンのコントロールを追加のルールで作成する機能を有効にします。これらのルールは、Engine\Plugins\Animation\ControlRig\Content\Python\RigHierarchy\add_controls_for_selected.py に格納されているカスタムの Python スクリプトで決定されます。
