コントロール リグによるリギングのための Python スクリプティング

コントロール リグで Python スクリプティング を使用すると、ワークフローを自動化し、リギング プロセスのためのツールを作成できます。また、コントロール リグの Python ログ を使用してコマンドをリバース エンジニアリングし、スクリプトをコピーして他のプロジェクトと共有することもできます。

このドキュメントでは、コントロール リグでの Python スクリプティングの概要、コントロール リグの Python ログについて説明し、スクリプト サンプルをいくつか紹介します。

前提条件

• コントロール リグ アセットを開いていること。

• Unreal Engine での Python スクリプティング の経験があること。

スクリプティングの概要

Python は主にコントロール リグで、複数のモジュールで構成されるリグ グラフを操作するために使用されます。

コントロール リグ グラフは、モデル - ビュー - コントローラー の設計パターンを使用して実装されています。このモデルは、グラフ自体であり、以下の用語を使用します。

Python は、Python Editor Script プラグイン から有効化されます。このプラグイン自体は、Unreal Engine でデフォルトで有効になっています。また、Control Rig プラグイン を有効にすると、依存関係にあるため Python Editor Script プラグインも自動的に有効になります。

コントロール リグにアクセスする

スクリプトを作成する際の最初のステップは、操作するメイン オブジェクト (この場合は ControlRigBlueprint オブジェクト) にアクセスすることです。複数のアクセス方法がありますが、コントロール リグに変更を加えるため、通常、最初のコマンドで、ControlRigDeveloper モジュールをロードします。

	
	unreal.load_module('ControlRigDeveloper')
	
Copy full snippet

unreal.load_module('ControlRigDeveloper')

既存のリグにアクセスするには、次のコマンド例を使用して、アセットをロードします。

	
	rig = unreal.load_object(name = '/Game/ControlRig/Samples/Mannequin_ControlRig', outer = None)
	
Copy full snippet

rig = unreal.load_object(name = '/Game/ControlRig/Samples/Mannequin_ControlRig', outer = None)

また、次のコマンドを使用して、現在開いているコントロール リグ アセットをロードすることもできます。

	
	rigs = unreal.ControlRigBlueprint.get_currently_open_rig_blueprints()
	
Copy full snippet

rigs = unreal.ControlRigBlueprint.get_currently_open_rig_blueprints()

新しいコントロール リグ アセットを作成するには、次のコマンドを使用します。

	
	factory = unreal.ControlRigBlueprintFactory()
	rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')
	
Copy full snippet

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)
	
Copy full snippet

# スケルタルメッシュをロードする 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()
	
Copy full snippet

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'))
	
Copy full snippet

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()
	
Copy full snippet

controller = rig.get_controller()

グラフにノードを追加するには、add_struct_node 関数、add_comment_node 関数、add_parameter_node 関数、または add_variable_node 関数を使用できます。以下の例では、最も一般的なタイプである struct (構造体) ノードに焦点を当てています。struct ノードは RigUnit を視覚的に表現したものです。そのため、グラフ内のほとんどのノードは struct ノードです。

	
	# ユニットを取得する - パスなどでこれを取得することもできます
	unit = unreal.RigUnit_MathFloatAdd.static_struct()
	
	# ユニットの構造体、メソッド (常に Execute)、およびグラフ内の 2D 位置を入力したグラフにノードを追加する
	node = controller.add_unit_node(script_struct = unit, method_name = "Execute", position = unreal.Vector2D(0, 0))
	
Copy full snippet

# ユニットを取得する - パスなどでこれを取得することもできます unit = unreal.RigUnit_MathFloatAdd.static_struct() # ユニットの構造体、メソッド (常に Execute)、およびグラフ内の 2D 位置を入力したグラフにノードを追加する 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)
	
Copy full snippet

# 階層オブジェクトにアクセスする hierarchy = rig.hierarchy # すべての要素のキーを取得し、それらを出力する elements = hierarchy.get_all_keys() for element in elements: print(element)

ボーンなどのリグ要素を作成するには、次のコードを使用できます。

	
	# 階層コントローラー オブジェクトにアクセスする
	hierarchy_ctrlr = rig.get_hierarchy_controller()
	
	# 新規ボーンを追加する
	new_bone_key = hierarchy_ctrlr.add_bone(name = "MyBone", parent = unreal.RigElementKey(), transform = unreal.Transform())
	
	# Z 上の 10 ユニット離れた親に新しい子ボーンを追加する
	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)
	
Copy full snippet

# 階層コントローラー オブジェクトにアクセスする hierarchy_ctrlr = rig.get_hierarchy_controller() # 新規ボーンを追加する new_bone_key = hierarchy_ctrlr.add_bone(name = "MyBone", parent = unreal.RigElementKey(), transform = unreal.Transform()) # Z 上の 10 ユニット離れた親に新しい子ボーンを追加する 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')
	
Copy full snippet

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)
	
Copy full snippet

# スケルタルメッシュをロードする 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)
	
Copy full snippet

# 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
Copy full snippet

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()
	
Copy full snippet

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 スクリプトで決定されます。