Auto-Rig Pro Documentation

Auto-Rig Documentation



Welcome to the Auto-Rig Pro documentation! This complete guide gives instructions to start with, from installing the addon to the final mesh skinning.

Also make sure to check the dedicated youtube channel!

Installing The Addons:

Extract the .zip file you've just downloaded in a new folder (name it Auto-Rig Pro for example).


This folder contains one blend file and the addons directory. Let's install the addons:


  • Press Ctrl-Alt-U > Add-ons > Install from file >...
  • Look for the addons folder > select auto-rig then click Install from File
  • Check the box next to the addon in the list to enable it.

Proxy Picker:

  • Ctrl-Alt-U > Add-ons > Install from file >...
  • Look for addons folder > select then click Install from File
  • Check the box next to the addon in the list to enable it.

Note about the Rig Tools addon:

  • Only install the Rig Tools addon ( if you don't install the Auto-Rig addon (e.g. after rigging your character, you can send it to the animator to ensure the IK snaps and other rig functions). Make sure not to install both addons, it could potentially lead to internal conflicts.

Finally ensure Python scripts can auto-run otherwise the addon functions won't work:

  • File tab, enable the checkbox:

  • Click Save User Settings at the bottom left of the window.


Setting up the model:

  • The character model must be in the center of the world (0,0,0) with feet on the ground level when using the Smart feature.
  • It has to face the -Y global axis, it means the face and feet must point toward the front view (numpad 1). If it's not the case, just turn the object by 90° steps until it faces the front view (R key, Z key, type 90 numpad keys). You can also use the Turn buttons of the Smart tools to rotate the model so that it faces the camera (read below).


  • Now initialize its transforms: Ctrl-A > Position, Ctrl-A > Rotation & Scale

Appending the armature:

Blender 2.79 and above:

add armature

  • Press N key to enable the properties panel in the 3d view right area.
  • Look for the Auto Rig Pro panel
  • Press the Add Armature button in the Rig tab.

This button is only available in Blender 2.79 and above because it crashes Blender 2.78. Currently, you have to use Blender 2.79 test builds/RC if you want to use it. Though these builds seem stable and are about to be released, use it at your own risks, they may contain bugs!

Otherwise, with Blender 2.78, append the armature file auto_rig_[version].blend in your character scene:

  • File > Append > File location > Object > Select All objects with the A key (or Shift-F1)
  • Uncheck the Active Layer box in the bottom left area.


  • Click Append from Library

Automatic Bones Placement with Auto-rig Pro: Smart

The Smart feature is useful to quickly place the reference bones within a few clicks. It only works with biped character at the moment. It has been designed to cover several cases, however there are few guidelines to follow:

  • Fingers: the character can be in T-Pose or A-Pose, but to ensure right fingers detection, there must be enough spaces between them, and they must be all visible from the top view. For example, the first two pictures below are correct, the third is not. Straight fingers give better results than curved fingers.




If your character's fingers don't meet these requirements, you can disable the Find 5 Fingers checkbox below the Go button. If the whole character it not a biped, skip this part and go straight to the next chapter to manually place the reference bones.


  • No facial detection yet
  • Does not support vertical arms/hands
  • Depending on the character proportions, it may require manual corrections after the detection
  • Requires 5 fingers to work properly
  • Asymetric models are hardly supported

How to use:

  • Press N key to enable the properties panel in the 3d view right area.
  • Look for the Auto Rig Pro: Smart tab
  • Select all of the body objects necessary for the detection
  • Click Get Selected Objects in the Auto-rig Pro : Smart panel


The camera will frame the character in front view. If the model doesn't face the camera, you can use the Turn buttons to this end.


  • Click the Add Neck button. It creates a new circle shaped marker, just move the mouse cursor to position it.
  • Place it on the neck base of the character.
  • No need to rotate the view while doing this, keeping the front view will be just fine. The solver will automatically find the neck depth.
  • Click the next button Add Chin, place it, and do the same until get can see the Go! Button.


Press the Go! button! At the end of the process the references bones should be properly positionned on the character. Note that this may require additional manual tweaking to get a more accurate placement, depending on the character. Check the chapter Editing the reference bones to this end. You can also restore the previous markers to try different placements by clicking Restore Last Session after Get Selected Objects.

Rig Definition

Now it's time to configure and define the character skeleton. Click on the Rig tab in the Auto-Rig Pro panel.

  • (Note:You will still be able to go back whenever you want to this step after the rig completion. However if you have already binded the mesh, it may be necessary to manually add the deforming vertex groups of the limbs that were not checked before binding. Or you can unbind and bind the mesh again.)


If the character is a quadruped (dog, cat, horse...) it's necessary to switch to the Multi-Ped type instead of the default Biped. The difference will be visible later: the spine controllers used for display won't be vertically aligned since a quadruped/multi-ped stands with his "hands" on the ground. If you don't know how to position the bones of a quadruped, here is an example.

Only check the needed limbs, and to disable or duplicate a limb, see the next chapter.

Editing the Reference Bones

Whether your character is not supported by the Smart function (multi-ped) or you want to manually refine the reference bones position/ want to place the facial bones, here is how to edit them:

  • Select the armature object.
  • If you don't use Auto-rig Pro : Smart function, first scale the rig in object mode so that it globally fits the character height.
  • Press N key to enable the properties panel in the 3d view right area.
  • Look for the Auto Rig Pro tab > Rig tab, then click Edit reference bones.


Adjust the bones positions so that they fit the character proportions.

You can follow the guidelines below for a biped rig, and watch this for a multi-ped rig:

The foot_heel and foot_bank bones (the three little bones under the foot) should match the heel back position and the foot width.

rig heel rig

Remember to keep a slight angle between the arms/legs bones. It's very important for the IK chains to work properly. They MUST NEVER be straight!

rig heel

The root_ref bone tip should be centered at the bellybutton height, spine_01 at the bottom of the chest, spine_02 should reach the neck base.

rig heel

The facial bones should be positionned like this (scary isn't it ;-):

facial facial

The lips bones have to be very close to the geometry, positionned all around the lips.

The eyelids and eyes bone heads should be positionned at the eye center while the tail should reach the eyeglobe surface.

The eyebrows bones and lips_roll bones have been designed to work with shape keys and drivers (read below the Skinning chapter). However if you are used to work with the bone deform method, you can change their position and rotation the way you want for correct deformations.

Duplicate or Disable a Limb

 bally spider

To rig characters with multiple arms or legs, duplicate a limb by selecting one bone from it and click Duplicate.

Only the arms and legs can be duplicated with their linked toes and fingers. The fingers and the spine, head, can't be duplicated at the moment. However it's possible to remove (disable) them, read below.


On the contrary you can disable a source limb or a duplicated limb by clicking Disable.

It's possible to restore all disable limbs by clicking Enable All, wich will restore of the disabled limbs except the duplicated, which can't be backed up.

Import - Export Reference Bones

It's possible to save the reference bones transforms into an external file that you can load later, e.g. when the addon/armature has been updated and the Update Armature button can't do the full upgrade job. Just click the Import and Export buttons to save or load the file.

Generate The Rig

Click Match to Rig to generate the final rig.

You can go back to edit mode and make some changes anytime by clicking Edit Reference Bones again.

Final UI Tweak

You may want to adjust the controllers shape displayed in the 3D view. Just click the Edit Shape button and Exit Shape Edit once you're done.


If you haven't done it already, you might want to split the 3D view into two areas, one view to display the character and one view to display the picker panel. How to do this:

  • Click on the three tiny lines at the top right corner of the 3d view, then hold and drag it onto the left:


  • Then click the Set UI Cam button in the Misc tab, in the view you want to display the bone picker.


  • You can adjust the color theme here too.

If you can see these awful lines, just uncheck the Relationship Lines option in the properties panel. They can be disabled in Pose Mode only.


You can add a background facial picture by framing your character's head, and clicking Capture Facial. If you want to replace this openGL screenshot by a real render, just replace the saved image file with your own file.

Then if you wish to change the picker layout, click Edit Layout.... You'll be able to freely select, move, rotate and scale the picker bone shapes, buttons, text and background picture. Once you're done, click Done Layout to complete.

picker image

Skinning: Binding

Ok now you're happy with your rig, it's time to bind the mesh!

First, make sure the mesh object has no parent attached.

Note that as mentionned previously, by default the eyebrows and lips bones are supposed to be skinned with shape keys and drivers. In case you don't want to use shape keys but direct bone deform, make sure to enable their Deform checkbox in the bone property panel before binding the mesh to the rig. Thus the corresponding vertex groups will be created when binding.


Then choose one of these options:

1. Automatic no-worries way:

  • Select your character mesh, hold Shift and select the armature.
  • Click the Bind button in Skin tab. Enable Split Parts for better results if your character has clothes, props as separate meshes (not welded to the main mesh). Be aware, with high poly meshes containing lots of loose parts, it can take several minutes to bind. Use Chin will improve the head skinning based on the chin position (when facial is disabled, and for bipeds only). Just make sure the reference jawbone is properly positionned, and disable facial afterward.


It will automatically add two armature modifiers, will make a list of all the necessary vertex groups, and will roughly assign the vertices groups based on bone-vertices distances. But it's only a basis, the next step is refining the weight assignments by weight painting.

2. Manual way:

You have to skin the mesh on two armature, the order matters. The two armatures are:

The hidden object named rigg_add is an additive rig necessary to make the secondary bones (deforming on top of the first armature) work properly

The main rig armature (always visible), named rig.

To skin the mesh on the armatures (one at a time, rigg_add first), select the mesh then the armature, press Ctrl-P key > With Automatic Weight

Make sure to check the Preserve Volume box of the rig armature modifier for better deformations, unless you want to export later for game engines which doesn't handle this. I don't advise you to check it for the rig_add armature, this would lead to weird deformations.

Skinning: Weight Painting and Shape Keys

Ok, it's time to carefully paint the weight vertices for each vertex group in the list. This process can take some time, don't hesitate to test the skin accuracy by posing the character into several extreme position (arms up, arms down, arms ahead, thighs up...)

How to paint? Google is your friend for this one, this is something I won't elaborate here since you will learn much more watching a video tutorial by typing blender weight painting tutorial in Google ;-)

However you have to read the followings lines for the best usage. It's important to paint these specific regions for the arms and legs stretch/twist bones. The blender automatic solver doesn't do it automatically. Note how these regions are cut in a half, with a smooth gradient to blend it. This will bring more natural deformations.

c_arm_twist_offset and arm_stretch


Forearm_twist and forearm_stretch


Thigh_twist and thigh_stretch


Leg_twist and leg_stretch



Make sure to assign the correct vertices to these bones:

  • The big circle (c_eye_offset) is meant to deform both the eyes and eyelids. It simulates the muscles stretch and compression. The eyelids and eyesballs bones have their own vertex groups though (eyelid_bot, eyelid_top, c_eye and other secondaries), so this bone should just influence the external borders, gradually reduce the influence near the eyelids.

  • The small circle (c_eye) is meant to rotate the eyeball only.

  • The sphere circle (c_eye_ref) is meant to control the reflexion disk mesh (if any), sometime used to fake the eye reflexion, easily animatable.


Shape Keys:

As explained earlier, the lips_roll and eyebrows are supposed to be used with shape keys.

Lips roll: it will be necessary to create two shapes on your head mesh: the bottom lips kissing, and the upper lips kissing.

Eyebrows: create at least one shape key for each eyebrow bone (up or down). Set the min value to -1 to let the shape key go in the opposite direction too.

It's good to use some shape keys to make the character smile too (bone deform is less accurate), if you want to do so select the c_lips_smile bones (left and right) and uncheck their Deform property in the bone property panel.


The addon includes a tool to quickly create the drivers between a shape and a bone.

  • Select the armature, then in the Shapekeys Driver Tools enter the bone name driving the shape key or select it and click the little picker icon.
  • Hold Shift key and select the mesh, in the shape key list select the one to be driven
  • Select the transform parameter you want to use to drive (location, rotation, scale and the axis)
  • Push the button: Create driver.


In case the shape key increase too slowly or too fast while the bone is moving:

  • Left click on the pink shape key value then multiply 'var' by any number using the * (asterisk/star) character, e.g to speed up 5 time faster, write:


  • The 0, 1 and Reset buttons are optional, you can use them to set a key to 0 or 1 on the curve, according to the current bone position. It's especially useful when using multiple shape keys, such as the eyelid rotation in several steps for big eyes.

You can also negate the expression to switch the bone direction: "-var"

To delete a driver:

  • Right click on the shape key value > Delete driver

X-Muscle System Support


X-Muscles System is an addon for muscle simulation, bringing more depth and credibility to realistic characters. It's very well done and easy to setup, so I thought it could be a great addition to Auto-Rig Pro. I've been glad to work with its developper to make both addons compliants.

When creating muscles, you can select the deforming bones by enabling the layer 31 of the armature (last bottom right):



I hope you'll enjoy, this auto-rig project was an amazing experience for me (thousand lines of code and, many many hours for testing and refining). Hopefully all the energy spent in this will save you some time and headaches :) !

Feel free to get in touch for any remarks, if anythying broke with a newest Blender API update or whatever... and happy blending :D !


Auto-Rig Pro addon for Blender.
Documentation template provided by Frittt Templates