Arigify

by László Márton in Scripts and Addons

System Requirements

Any computer capable of running Blender. For more detail, please visit the requirements section of the official Blender website: https://www.blender.org/download/requirements/

Compatibility

This add-on was tested with Blender 2.90. The results were imported to Unreal Engine 4.25.3 and Unity 2020.1.6f1 and Godot Engine 3.2.3 on Windows 10. For more information see https://www.blender.org/ https://www.unrealengine.com    https://unity.com https://godotengine.org

Introduction

What is Arigify?

Arigify is a Blender add-on whose purpose is to improve the character model creation and animation pipeline involving Blender and various game engines (such as Unreal Engine 4, Unity and Godot). This software is licensed under GPL 3.0 (see the license file attatched for details). If you have acquired this add-on from a different source and use it extensively, please consider buying a copy. For available purchase options visit FiniteStateKitschMachine.com. For requesting support and reporting issues please use the options provided by the site of purchase or contact [email protected]

For whom is it intended?

Game developers and hobbyists who would like to speed up their character animation workflow between Blender and a game engine of their choice. Having an at least cursory knowledge of the process of creating a character model ,with mesh and armature (or skin and bones) included, and how to animate it is highly recommended. So is being familiar with the game engine at a level where basic concepts related to the animation of characters (and animation programming) are applicable by the user.

What does it do?

Arigify assists the user in converting their Rigify armature to a format that is easier to work with in other software (from now on we will refer to this process as „arigification“). This includes removing non-deform bones, reconnecting the bone hierarchy and removing „DEF-“ name prefices.It also includes quality of life improvements, such as automatically reparenting meshes and renaming their vertex groups to match new bone names, automatically loading selected actions to NLA for faster exporting, removing root bones and transfering their transformations to the armature objects themselves to enable root motion.

Arigify can also flip marked bones, in case the left- and right handside bones of the skeleton are required to be oriented in opposing directions, rather than mirrored with respect to the X plane (e.g. in Unreal Engine 4). Numerical suffices of bone names are moved before the directional suffices to keep support for mirroring collision bodies and constraints in Unreal Engine 4.

Known limitations

  • Arigify can only handle animation data at integer frames. Meaning, all animation curves will be evaluated between the beginning- and ending frames of their respective actions at integer intervals.

  • Arigify can only handle moving the numerical prefices in bone names before the left- and right hand side prefices, if they are not succeeded by anything else (e.g. front- and back side suffices). This also applies to leaf bone naming. 

  • Only Y primary- and X secondary bone axes are supported.

How to install

Next to the file of this very user manual can be found the add-on itself, packed within the file named „arigify.zip“. To install and use this add-on start the Blender application and follow the instructions below:

  1. In the upper-left corner of the window navigate to Edit menu > Preferences…

  2. Select Add-ons on the left side of the newly appeared preferences window

  3. Click the Install… button and in the appearing browser browse for and select the zip file of the add-on

  4. Click Install add-on to install the add-on

How to use

The options related to this add-on are visible within the Arigify panel in the armature- and bone sections of the properties panel of the currently active armature and bone. Please note, that some of the options and operators are only available in Pose mode. All options are saved for each armature and bone separately. This way the user can handle multiple armatures with their own respective animations within a single Blender project if it is desired. The options are also saved and loaded with the Blender project.

Example workflow

Once the meshing, rigging and animation of a model is done, the suggested workflow is the following:

Make sure that the proper settings are enabled and the actions you want to export are all checked within the list in the Arigify panel.

(Optional) Enable the flip setting on deform bones you wish to be flipped.

Save your Blender project! This is important as some of the steps beyond are destructive and permanent, therefore it is highly recommended to save a state, which you can restore if you intend to make further modifications to either the animation or the armature and its related mesh(es).

Run the arigification process.

Select your new armature and its associated mesh(es). In the upper left corner of the window navigate to File > Export > FBX. In the right side of the browser you can find the settings related to exporting your scene to FBX. It is outside of the scope of this manual to cover each and every setting in detail, therefore we will only examine the ones important from the perspective of this add-on and assume the others are left in their default states:

  • Include > Selected Objects:     this option should be checked to export only the objects required.

        
  • Armature > Add Leaf Bones: this option should be unchecked. If, they are needed, leaf bones should either be added manually or using the „Add end bones“ setting of this add-on.

        
  • Armature > Primary and secondary bone axes: should be Y and X, respectively.

        
  • Bake animation: should be enabled, under it NLA strips and Force Start/End Keying settings should be checked. This only exports the animations within the NLA strips and avoids duplicates.

Reload the saved project and repeat the steps if modifications are made.

For     more information on the rest of the settings please refer to the     Blender manual:     https://docs.blender.org/manual/en/2.80/addons/io_scene_fbx.html#export

Add-on Preferences

These settings are found in the add-ons section of Blender preferences.

Action list refresh frequency

Controls how many times per second the Arigify action list within the armature properties is updated. Use 0.0 to disable automatic updates. Decrease the frequency if experiencing performance issues. If disabled the list can be refreshed manually using the update action list button/operator.

Detailed Explanation of Functionalities

These settings can be found within the property panel, if an armature is selected.

Armature properties>Arigify>Arigify armature and actions

Starts the process of arigification for the selected armature based on the options set within the Arigify panels of the selected armature and its pose bones.

Armature properties>Arigify>Mark selected bones for flipping

Only usable in Pose mode. The selected bones of the active armature are marked- or unmarked for flipping.

Armature properties>Arigify>Add leaf bones

If this setting is checked additional leaf bones will be appended to the end of current leaf bones. These bones will be oriented the same as their parents and are the same length. This is useful to make the orientations of the last joints in the original chain more visible within game engines.

Armature properties>Arigify>Adjust NLA

Enabling this option will clear the Non-linear animation („NLA“ for short) stack of the armature and create new NLA tracks for each action selected within the „Actions to update“ list. It will also add strips of each action to their respective tracks. The active action of the armature is also unlinked. These modifications make it esier to export only the animations the user intends to.

Armature properties>Arigify>Remove root

If enabled the root bone of the copied armature is removed and its transformations are mapped to the armature object itself. Also, the armature object is renamed to „root“.

Armature properties>Arigify>Actions to update list

Shows the list of all actions within the Blender project file. The ones checked will be copied, renamed and their copies are updated during the arigification process, according to the new transformations of the bones, the rest will be ignored and left as is.

Armature properties>Arigify>Update all object actions button

Marks all actions in the action list for arigification. Make sure your regex auto selection setting does not interfere.

Armature properties>Arigify>Update no object actions button

Unmarks all actions in the action list for arigification. Make sure your regex auto selection setting does not interfere.

Armature properties>Arigify>Update action list button

Manually refreshes the list of actions. Only necessary if the automatic update for the action list is disabled. Use when you have added-, removed-, or modified the name of any actions.

Armature properties>Arigify>Selection regex textfield

Contains a python regular expression. This expression is used by the select/deselect and auto select operations. A few useful example inputs:

  • ^alien – selects all actions whose names start with the word “alien”

  • ^(?!alien) –     selects all actions whose names do not start with the word “alien”

  • baked$ – selects all actions whose names end with the word “baked”

  • $(?<!baked)– selects all actions whose names do not end with the word “baked”

  • ^alien*baked$ - selects all actions whose names start     with the word “alien” and end with the word “baked” with     anything (including nothing) between.

  • If the field is left empty all actions will be matched. This is useful to keep all actions checked constantly.

If the text field contains an invalid regular expression an error message describing the issue is shown under the input field.

For a more complete explanation of Python regular expressions please refer to the official documentation of Python: https://docs.python.org/3/library/re.html

Armature properties>Arigify>Selection regex select

Marks all actions for arigification in the action list, whose name matches the regular expression. Make sure your regex auto selection setting does not interfere.

Armature properties>Arigify>Selection regex deselect

Unmarks all actions for arigification in the action list, whose name matches the regular expression. Make sure your regex auto selection setting does not interfere.

Armature properties>Arigify>Auto Select

If auto select is enabled the names of all actions will be checked against the regex every time the list is refreshed, and marked or unmarked for update based on the result.

Bone properties>Arigify>Flip

If enabled, the edit bone is flipped around its local X axis during arigification. The actions are updated to negate this rotation.

The prerequisites of arigification

For armatures to be compatible with the process of arigification they must be rigify armatures. They must contain bones with „DEF-“ prefixed names, as these bones will form the bones of the newly built hierarchy, and these are the ones responsible for actually deforming the mesh(es). Before beginning, make sure that all of your actions are properly keyframed, including IK/FK switches and various Rigify related settings, to keep them from bleeding over into other actions, where they were not keyframed, during the baking process.

In the case of adding leaf bones please make sure, that bone names follow the official naming conventions supported by Blender for left- and right-hand side bones. For more details please refer to the section in the Blender documentation regarding this: https://docs.blender.org/manual/en/latest/animation/armatures/bones/editing/naming.html

Handling in-engine IK and attach bones

What we refer to as in-engine IK and attach bones in this section, are bones, whose functions are not to deform their associated mesh(es) directly, but either to be IK targets or organizational bones within the given engine. To keep these bones from being removed by Arigify, their names must be prefixed with „DEF-“, as if, they were deform bones (the prefix will be removed upon arigification). The option „deform“ should be disabled in the pose bone options for the bone in question. If the bone is to be part of the metarig, its rigify rig type should be set to „simple.raw copy“. By doing this, we make sure that it will not affect automatic weight assignment, while also being visible and animatable in the generated rig and keeping the intended name.

General tips

  • You can see the arigification progress in the console-/terminal window. On Windows you can access it by opening the Window menu > Toggle System Console. On Unix-based systems it is only available if Blender itself is started through a terminal.

  • The suggested export format is FBX.

  • Make sure your project unit in Blender is set to metric, unit scale to 0.01 and your model is matching in dimensions with the context you are planning to use it in.

  • When working with many animations it may be preferable to export the meshes and the armature first by disabling Bake animation in the FBX export options. Then, by selecting only the armature, export each animation into separate files for easier handling.

  • If experiencing graphical glitches, such as, some vertices staying in place or spiking out of the mesh during animation, make sure that each vertex has the proper amount of bones associated. To learn how many bones are supported for each vertex consult the documentation of the specific game engine used. If that data is unavailable, the numbers 8 or 4 should be reasonable to assume. To limit the amount of bones weighed to each vertex in Blender for a mesh, select the mesh in Object mode, then switch to Weight paint     mode and in the Weights menu use the Limit total operator. This will keep the strongest vertex weights, remove the rest and then normalize the remaining.

Engine specific tips

Unreal Engine 4

  • Only „.r“, „_r“ suffices, their capital- and left hand side counterparts should be used when naming bones.

  • Armature > Primary and secondary bone axes export settings: these should be set to Y and X.

  • When a constraint is between a side bone (suffixed with left- or right suffices) and a middle bone (no suffix) mirroring it only works by selecting both opposing constraints and transforming them together (relative to their default state upon generation). Hitting the „M“ shortcut gives erroneous result.