Python Scripting for Rigging with Control Rig

Use Python scripting in Control Rig to automate workflows and create tools for the rigging process. You can also use the Control Rig Python Log to reverse-engineer commands and copy scripts to share to other projects.

This document provides an overview of Python scripting in Control Rig, the Control Rig Python Log, and a few scripting examples.

Prerequisites

• You have a Control Rig Asset open.

• You have some experience with Python scripting in Unreal Engine.

Scripting Overview

Python is primarily used in Control Rig to interact with the Rig Graph, which consists of multiple modules:

The Control Rig Graph has been implemented using the Model - View - Controller design pattern. The model is the graph itself using the following terminology:

Accessing Control Rig

The first step when scripting is to access the main object you will be interacting with, in this case the ControlRigBlueprint object. There are several ways to access it, however your first command will usually be to load the ControlRigDeveloper module in order to make changes to Control Rig.

  unreal.load_module('ControlRigDeveloper')

To access an existing rig, load the asset with the following example command:

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

You can also load any currently open Control Rig Asset using:

  rigs = unreal.ControlRigBlueprint.get_currently_open_rig_blueprints()

Creating a new Control Rig Asset is done using:

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

Lastly, you can create a Control Rig Asset based on a Skeleton or Skeletal Mesh with the following example code:

  # load a skeletal mesh
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)

  # create a control rig for the mesh
  factory = unreal.ControlRigBlueprintFactory
  rig = factory.create_control_rig_from_skeletal_mesh_or_skeleton(selected_object = mesh)

Python Log

The Python Log provides a text log of all the actions that you performed within the Control Rig Editor. This includes actions within the viewport, the hierarchy, and the graph. Use this to reference commands to use in your Python scripts.

To access the log, click Window > Message Log from the main Control Rig menu, then select Control Rig Python Log from the Message Log sidebar.

You can now perform actions in the Rig Graph and see them recorded in the log.

If you want to save a command to share or use elsewhere, you can select any line from the log and press Ctrl + C to copy it, then you can paste in any text editor. You can also select multiple lines by holding Shift.

You can test commands by pasting them into the Output Log and executing them, ensuring the log type is set to Python. In this example, a new control is created.

Python Context

Python context is used to contextualize which Control Rig asset should be affected when running Python commands. By default, no context is set when viewing a Control Rig. You can set the context for the current Control Rig by clicking Run Python Context within the Class Settings Details panel.

This will execute a series of commands that bind the current Control Rig Asset to the Python context. This allows for commands copied from the Python Log to be pasted and executed within this Control Rig Asset.

  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 Python Script

You can also copy the entirety of a Control Rig's nodes, rig elements, and properties to your clipboard. This can then be pasted into an external script editor, or back to the Output Log to execute on another Control Rig. Copy Python Script is useful for sharing, debugging and comparing the logic between different rigs. Similar to copying individual commands, copying whole rigs can also be useful for reverse-engineering Python commands from Control Rigs.

To copy a Control Rig, click Copy Python Script within the Class Settings Details panel.

Python Script Examples

Adding Nodes

Since nodes are visual representations of RigUnit structs, you will need access to the unit in order to add a node to the graph.

  unreal.load_module('ControlRigDeveloper')

  # get an array of all available units
  units = unreal.ControlRigBlueprint.get_available_rig_units()

  # print details about the units
  for unit in units:
      print(unit.get_path_name())
      print(unreal.EditorAssetLibrary.get_metadata_tag(unit, 'Keywords'))

Next, you will need to access the Controller. The Controller is the central object used to make changes to the graph.

  controller = rig.get_controller()

To add a node to the graph you can use the add_struct_node, add_comment_node, add_parameter_node or add_variable_node functions. The example below focuses on the struct node, which is the most common type. A struct node is a visual representation of a RigUnit, therefore most of the nodes in a graph are struct nodes.

  # get the unit - you might also get this by path or similar
  unit = unreal.RigUnit_MathFloatAdd.static_struct()

  # add the node to the graph provided the unit struct, the method (is always Execute) and 2D position in the graph
  node = controller.add_unit_node(script_struct = unit, method_name = "Execute", position = unreal.Vector2D(0, 0))

Editing the Hierarchy

In addition to editing the graph, you can also edit the hierarchy using Python code. Each rig element in the Control Rig hierarchy is identified using RigElementKey, which contains the name and the type of the element. When you create or interact with elements in the hierarchy you will need to use this key.

Control Rig elements are structs, which means they are copied using their total values. As a result, if you change an element you may have to set it again in the hierarchy.

Hierarchy can be used to query elements, get or set global / local transforms, and reset elements back to their initial values.

HierarchyController can be used to add, remove and edit elements. You can also use it to rename and re-parent elements if needed.

To perform an inspection of the current hierarchy, you can use the following Python code:

  # access the hierarchy object
  hierarchy = rig.hierarchy

  # get all element keys and print them
  elements = hierarchy.get_all_keys()
  for element in elements:
      print(element)

To create a rig element, such as a bone, you can use the following code:

  # 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)

Variable and Asset Manipulation

To create a Control Rig variable with getter and setter nodes, you can use the following code:

  rig.add_member_variable("MyVariable", "Transform", is_public = True, is_read_only = False, default_value ="")

  # Create variable getter node
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = True, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Getter')

  # Create variable setter node
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = False, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Setter')

The preview mesh can also be changed using the following code:

  # load a skeletal mesh
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)

  # create a new (empty) asset
  factory = unreal.ControlRigBlueprintFactory()
  rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')

  # set the preview mesh
  rig.set_preview_mesh(preview_mesh = mesh)

The Control Rig can be compiled using any of the following code, depending on your context:

  # force a recompile of the VM
  rig.recompile_vm()

  # compile the VM if there are pending changes
  rig.recompile_vm_if_required()

  # request a compilation if auto compile is enabled and the editor is open
  rig.request_auto_vm_recompilation()

  # request the control rig to run an init pass (initialize all units)
  rig.request_control_rig_init()

  # request the control rig to run a full blueprint compile
  unreal.BlueprintEditorLibrary.compile_blueprint(rig)

Editor Startup

Python scripts can be loaded upon editor startup, which is useful for loading custom tools and built-in Python functions. You can locate this script and sample scripting functions from your project directory, under the following folder path:

Engine\Plugins\Animation\ControlRig\Content\Python

Within this folder is the init_unreal.py script, which contains the following code:

  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()

This code loads example scripts which enable extra functionality.

For example, add_controls_for_selected enables functionality for creating controls on selected bones with additional rules. These rules are determined by the custom Python script located in Engine\Plugins\Animation\ControlRig\Content\Python\RigHierarchy\add_controls_for_selected.py.