Unreal Python工具开发：骨骼资产工具[Controlrig]

JoshWindsor

作者 @ocarina 2022-07-18
Unreal引擎更新后，本文介绍在Unreal5引擎下，处理骨骼资产的相关API及其具体实现。帮助对于Unreal 插件开发陌生的但是又面对着快速变化需求开发者提供便捷的学习文档。
涉及资产处理：Skeleton Mesh、Skeleton、Physics asset、Animation Bluepring、Control rig
目录

Unreal 工具开发：骨骼资产工具目录
Python开发环境
ControlRig

• 变量的增删查改
  
• Hierarchy的增删查改
  
• RigGraph图表节点逻辑关系
  

Python开发环境

开发工具：VsCode + Unrela Engine
注意事项：
文档编写所用引擎版本Unreal5.0
Unreal默认支持Python 版本为Python3.7.7 Unreal Python工具不支持游戏Runtime运行启动插件：
Editor Scripting Utilities Python Editor Script Plugin
官方启动文档：Unreal Scripting the Editor using Python
官方Python API文档：Unreal Python API
FBX Content Pipeline
ControlRig

Control Rig提供了相当自由的Api用于扩展功能，不仅仅是一个辅助的动画Asset，还有成为引擎中完整的骨骼动画控制器的潜力。借用提供的参数库可以在引擎中定制化开发支持实时动画制作流程。本次介绍的API如下，作为快速实践可以迅速入手Controlrig编辑器的二次开发。



变量的增删查改

在Unreal5.0的Control Rig 的Variables面板中，变量无法被多选，在迁移Control Rig数据时，需要对变量进行批量操作，这时就需要调用Python API来修改变量。 ControlRigBlueprint 支持的操作有但不限于：
① 创建一个新变量 ② 修改一个变量的类型、值、公开属性
# 代码运行环境为 Unreal5.0.2 python 3.7
import unreal
# 编辑器操作类，选中资产操作
@unreal.uclass()
class EditorUtil(unreal.GlobalEditorUtilityBase):
pass
# unreal ControlrigBlueprint蓝图类
@unreal.uclass()
class Controlrig_Blueprint(unreal.ControlRigBlueprint):
pass
# 创建一个简单的类来拓展管理
class CtrlRig_Variable_Processor():
editor_util = None
controlrig_bp = None
def __init__(self):
self.editor_util = EditorUtil()
self.controlrig_bp = Controlrig_Blueprint()
# 获取选中的Control rig资产
def get_selected_asset(self):
selected_assets = self.editor_util.get_selected_assets()
if (len(selected_assets)):
# 当前仅考虑单个资产操作，可在代码基础上进行扩展实现批量操作
selected_asset = selected_assets[0]
return selected_asset
else:
print(
"[error] fail to get selected asset, please select the right
asset in unreal engine content browser")
return None
def set_variable(self, var_name, var_type):
# Create new variable
self.controlrig_bp.add_member_variable(var_name, var_type)
# Change variable
# controlrig_bp.change_member_variable_type("variable_name","float"
False, False, 0)
def call_create_variable(self, var_name, var_type):
self.controlrig_bp = self.get_selected_asset()
if(isinstance(self.controlrig_bp, unreal.ControlRigBlueprint)):
self.set_variable(var_name, var_type)
else:
print("[error] selected type is not correct, please select the right
asset in unreal engine content browser")
# 调用
Ctrlrig_var_op = CtrlRig_Variable_Processor()
Ctrlrig_var_op.call_create_variable("variable_01", "vector")
执行结果



Hierarchy的增删查改

在Unreal5.0的Control Rig 的Rig Hierachy和Curve面板中，可以通过读取外部数据在Unreal中创建控制器、修改骨骼和添加Curve曲线。支持在Controlrig资产编辑器中选中key操作，ConrtolrigHierarchyController中可选的key类型有：Bone、Curve、Control、Null(space) ControlrigHierachyController(Unreal4.27及以前使用
ControlrigHierarchyModifier类管理，部分API有改变) RigHierarchyController RigHierarchy
支持的操作有但不限于： ① 增删查改Bone\Curve\Control\Null(space)\parent ② 导入/导出 层级结构信息(包括
Curve)
# 代码运行环境为 Unreal5.0.2 python 3.7
import unreal
# 编辑器操作类，选中资产操作
@unreal.uclass()
class EditorUtil(unreal.GlobalEditorUtilityBase):
pass
# unreal ControlrigBlueprint蓝图类
@unreal.uclass()
class Controlrig_Blueprint(unreal.ControlRigBlueprint):
pass
@unreal.uclass()
class Controlirg_RigHierarchyController(unreal.RigHierarchyController):
pass
# 创建一个简单的类来拓展管理
@unreal.uclass()
class Controlirg_RigHierarchy(unreal.unreal.RigHierarchy):
pass
class CtrlRig_Variable_Processor():
editor_util = None
controlrig_bp = None
controlrig_hierachy = None
controlrig_hierachy_ctrl = None
def __init__(self):
self.editor_util = EditorUtil()
self.controlrig_bp = Controlrig_Blueprint()
self.controlrig_hierachy = Controlirg_RigHierarchy()
self.controlrig_hierachy_ctrl = Controlirg_RigHierarchyController()
# 获取选中的Control rig资产
def get_selected_asset(self):
selected_assets = self.editor_util.get_selected_assets()
if (len(selected_assets)):
# 当前仅考虑单个资产操作，可在代码基础上进行扩展实现批量操作
selected_asset = selected_assets[0]
return selected_asset
else:
print(
"[error] fail to get selected asset, please select the right
asset in unreal engine content browser")
return None
def modify_hierachy(self, var_name):
new_curve = self.controlrig_hierachy_ctrl.add_curve(
var_name, 0.0, True, False)
'''Api:
# add_control(name, parent, settings, value, setup_undo=True)
# add_curve(name, value=0.000000, setup_undo=True,
print_python_command=False)
# add_bone(name, parent, transform, transform_in_global=True,
bone_type=RigBoneType.USER, setup_undo=False, print_python_command=False)
# add_null(name, parent, transform, transform_in_global=True,
setup_undo=False, print_python_command=False)
'''
def modify_selected_hierachy(self):
# 选中key信息在hierarchy类中
root = self.controlrig_hierachy.get_selected_keys()
# 导出选中Keys信息操作,返回值是str类型
keys = self.controlrig_hierachy_controller.export_selection_to_text()
# 重新导入Keys,支持字符修改，所有的键包括骨骼控制器应该都作为RigElementKey类被
保存和支持读写。
# 因为这块的Api文档在近几个文档变化较大，更完善的Api调用请查阅文档。
# self.controlrig_hierachy_controller.import_from_text(keys, True, False,
True)
def call_create_variable(self, var_name):
self.controlrig_bp = self.get_selected_asset()
if(isinstance(self.controlrig_bp, unreal.ControlRigBlueprint)):
# unreal提供了Api从Controlrig BP类中读取Controlrig Hierachy
# 在4.27中ControlrigHierachy统一用HierarchyModifier类管理，在Unreal5.0
中拆分成了下面两个类
self.controlrig_hierachy_ctrl =
self.controlrig_bp.get_hierarchy_controller()
self.controlrig_hierachy =
self.controlrig_hierachy_ctrl.get_hierarchy()
self.modify_hierachy(var_name)
else:
print(
"[error] selected type is not correct, please select the right
asset in unreal engine content browser")
# 调用
Ctrlrig_var_op = CtrlRig_Variable_Processor()
Ctrlrig_var_op.call_create_variable("custom_curve")
执行结果：创建了自定义曲线，通过unreal.RigHierarchyController.Rename_element() 方法还可以更改现有的
curve属性，在迁移metahuman Curve和图表到自定义角色Controlrig中时这一步操作能很大的提高效率和Unreal控制器的复用性。



RigGraph图表节点逻辑关系

Controlrig提供的API里，也提供了节点创建的插件，主要基于RigController、RigVMGraph、RigVMNode三个类去调度和操作图表逻辑。
Control的节点类型依然是分成RigVMNode的可视化内容和仅存储数据用于实际计算的Rig_Unit单元内容。通过以上接口，我们可以在VMNode层级进行操作。
[RigVMGraph](https://docs.unrealengine.com/5.0/en-
US/PythonAPI/class/RigVMGraph.html?highlight=rigvm#unreal.RigVMGraph) [RigVMController](https://docs.unrealengine.com/5.0/en-
US/PythonAPI/class/RigVMController.html#unreal.RigVMController)
支持的操作有但不限于：
① 程序化创建一个新的逻辑节点，并且自定义创建、定义引脚类型、连接关系。 ② 读取所选节点的值、引脚、连接关系
# 代码运行环境为 Unreal5.0.2 python 3.7
import unreal
# 编辑器操作类，选中资产操作
@unreal.uclass()
class EditorUtil(unreal.GlobalEditorUtilityBase):
pass
# unreal ControlrigBlueprint蓝图类
@unreal.uclass()
class Controlrig_Blueprint(unreal.ControlRigBlueprint):
pass
# 创建一个简单的类来拓展管理
class CtrlRig_Node_Processor():
editor_util = None
controlrig_bp = None
def __init__(self):
self.editor_util = EditorUtil()
self.controlrig_bp = Controlrig_Blueprint()
# 获取选中的Control rig资产
def get_selected_asset(self):
selected_assets = self.editor_util.get_selected_assets()
if (len(selected_assets)):
# 当前仅考虑单个资产操作，可在代码基础上进行扩展实现批量操作
selected_asset = selected_assets[0]
return selected_asset
else:
print(
"[error] fail to get selected asset, please select the right asset
in unreal engine content browser")
return None
def call_create_node(self):
self.controlrig_bp = self.get_selected_asset()
if(isinstance(self.controlrig_bp, unreal.ControlRigBlueprint)):
self.add_comment_node()
else:
print(
"[error] selected type is not correct, please select the right
asset in unreal engine content browser")
def add_comment_node(self):
# Models = self.controlrig_bp.get_all_models()
Controls = self.controlrig_bp.get_controller()
# Model = self.controlRigBP.get_model()
"""
Model = Models[0] # 获取蓝图图表VMGraph
if Model:
Nodes = Model.get_select_nodes() # 获取蓝图选中节点
if(len(Nodes)):
Node_name = Nodes[0]
Node = Model.find_node_by_name(Node_name)
Descriptions = Model.get_variable_descriptions()
Dec = Descriptions[0]
print(Node)
"""
# Add Command Node
Controls.add_comment_node(
"Hello", (0.0, 0.0), (400.0, 300.0), (0.0, 0.0, 0.0, 0.0), "command",
True, True)
# 调用
Ctrlrig_var_op = CtrlRig_Node_Processor()
Ctrlrig_var_op.call_create_node()

执行结果