Auto-Rig Documentation

Welcome

Welcome to the Auto-Rig Pro documentation! This complete guide gives instructions to start with, from installing the addon, rigging, to skinning and appending the character in a new scene. Note you can download this documentation by clicking the download icon in the top right corner of this page.

Also make sure to check the dedicated youtube channel for video tutorials and useful informations.

---

Installing The Addons:

Extract the .zip file in a new folder (name it Auto-Rig Pro for example).

This folder contains one blend file, the addons directories containing the addons to install, and the remap presets that may be used with the Remap tool. Here is how to install the addons.

Auto-Rig

• In Blender, press Ctrl-Alt-U > Add-ons > Install from file >...
• Look for the addons folder > select auto-rig master.zip 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 proxy_picker.py 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 (rig_tools.zip) 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.

---

Setup

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:

• 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.

  

• Choose a rig preset between human (biped) and animals (quadrupeds). This documentation covers the human biped only, but the same principles apply to the other types.

This button is only available in Blender 2.79 and above because of stability issues with previous versions.

If you use previous versions such as 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

Important note! To keep everything working, you should not manually delete any objects or bones linked to the armature, even if they're invisible, such as cs_grp and its children, cam_ui, rig_add, etc...)

---

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:

• The character can be in T-Pose or A-Pose. For the fingers detection, there must be enough spaces between fingers. The palm must face the floor, if the hand is too much twisted forward or backward, the fingers detection will fail.

If your character's fingers don't meet these requirements, you can choose Skip Fingers above the Go button (read below). If the whole character it not a biped, skip this part and go straight to the next chapter to manually place the reference bones.

Limitations:

• Depending on the character proportions, it may require manual corrections after the detection.
• The fingers may not detect properly if there is not enough space between them, if they are too curled, or if there are too many complicated shapes around the hand, such as big bracelets for example.

How to use:

• If you wish to setup the facial markers (optional), first make sure the eyeballs are in a separate object, and name it accordingly to easily find it later (the object can contain a single eyeball with a mirror modifier or both left and right eyeballs without modifier)
• 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.

• If the character is not symmetrical, uncheck Mirror. Otherwise the left markers/bones are mirrored on the right (right from the character's perspective).
• 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.

Depending on the character's fingers count, choose Find 5 Fingers, Find 4 Fingers or Skip Fingers.

Optionally you can setup the facial markers (if you wish to rig the facial):

• Push the Facial Setup button.
• Position the markers vertices to match your character face proportions:

  

• Enter the eyeball object name in the dedicated input field
• Press the Go! button!

At the end of the process the references bones should be properly positionned on the model. Note that this may require additional manual tweaking to get a more accurate placement.

The fingers detection should run fine with most of the characters, however it may fail sometime. In this case, the first thing to try is to move a little the wrist marker (you can click Recover Last Session to restore the previous markers positions). Then reduce or increase the Voxel Precision value, and then try to increase the Finger Thickness. If it still does not work, there's something special in the hands design that prevents the detection to work. Feel free to send your character for inspection (check the Bug Report chapter on the left menu of this page), if the issue can be fixed i'll let you know, if not, place the fingers manually: 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 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.

The spine bones amount can be adjusted from 3 to 4, and the is neck up to 16 bones. One global "neck_master" controller will be added if the neck bones amont is greater than 1. It can be rotated in option, to rotate all neck bones at once.

If you want the fingers phalanges to curve when scaling the first one, set the Rot From Scale property below the fingers checkboxes. Set it to Disable to disable this feature.

Just next to it, you can also define the default shapes of the fingers and toes (circles or boxes).

There are two deformation modes in option for the secondary bones (bones used to curve the arms, legs). Bendy bones may be better for very cartoony characters, since it better supports high bones stretching, and is generally smoother. Here is a comparison:

Additive

• Exportable to Fbx when enabling Advanced in the export options
• 3-4 controllers per limb for precise shapes sculpting, but not as smooth as Bendy Bones
• Additive skinning involves more bones, so more vertex groups

Bendy Bones

• Not exportable to Fbx
• Only 2 controllers per limb but very smooth control
• Easy skinning: only one vertex group per limb, the secondary and twist bones are computed internally by the bendy bones system

---

Editing the Reference Bones

Whether your character is not supported by the Smart function (not a biped) or you want to manually refine the reference bones position, or 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 viewport 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.

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!

Also, the IK chains roll can't be manually adjusted. It's calculated when clicking Match to Rig, the reference bones roll have no effect. But you can adjust the roll by changing the bones alignment as shown below. Here the arm is shown from the front view, it can be straight from this point of view, but must keep a slight angle backward (check from the top view):

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.

The facial bones should be positionned like this, with bones X-Ray display in the first picture (see-through): scary, isn't it?

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 lips_roll bones have been designed to work with shape keys and drivers (read below the Skinning chapter).

Duplicate or Disable a Limb

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

Only the arms, legs, neck, head, facial, and ears can be duplicated. It may not be possible to duplicate individual bones: for example, the arms duplication will duplicate the arm, forearm, hands and fingers as a whole, the head duplication will duplicate the neck, head and linked facial if any as a whole. The fingers and spine bones cannot be duplicated yet.

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

If disabling a limb is not precise enough to remove a specific bone, you should avoid deleting the bone manually. It can break the rig functions when clicking Match to Rig for example. Instead, consider hiding the bone. Read the FAQ to this end ("Is it possible to delete bones?").

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 with controllers and mechanic.

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

---

Hand Fist

Optionally, you can add a fist controller on the hands. This controller is meant to blend the fingers into a pre-defined fist pose. This allows a better grasp than the default "Fingers Grasp" property since that simply curls the phalanges along the X axis, wich may be inacurrate.

• Create a new action and make sure to include "rig_fist" in its name.

• Keyframe the fingers controllers (rotate directly the fingers controllers, the Rotation From Scale can't be used here) this way:
  frame 0 = rest pose, frame 10 = fist pose

• Select the hand controller and click the Add Hand Fist button to generate the controller. Fingers will curl into the fist pose when scaling it.

  
  

  

---

Final UI Tweak

You may want to adjust the controllers shapes. Just click the Edit Shape... button and Apply Shape once you're done. To mirror the shape to the other side, click the little button next to Edit Shape

If you haven't done it already, you might want to split the 3D viewport 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 viewport, 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.

  

• If you don't need the picker panel, you can delete it with the X icon button next to Add Picker.

• Add Picker will generate a new picker if it has been deleted. It's also possible to Export or Import a picker layout file.

• 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 Apply Layout to complete.

---

Skinning: Binding

Note! The Voxel Heat Diffuse Skinning addon is compatible with Auto-Rig Pro and does a great job at clothes and props skinning. See below to use it.

First, make sure the mesh objects have no parent attached. If so, select it and press Alt-P > Clear Parent and Keep transforms

• Select first your character meshes objects, then the armature holding the Shift key.

• 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.

• If binding does not work, make sure to check the FAQ.

If you own the Voxel Heat Diffuse Skinning addon, here is how to use it on top of the default Auto-Rig Pro skinning:

• It's good to prevent small parts (fingers, facial) from being skinned with voxels for better results: select the fingers and facial vertices.
• Select the mesh first and the armature holding Shift, check Protect Selected Vertex and click Voxel Heat Diffuse Skinning in the Voxel Skinning's interface panel.
• Unhide the rig_add armature in the outliner by clicking the eye icon.

  

• Select the mesh first and the rig_add armature holding Shift, and click again the Voxel Skinning button.
• Hide the rig_add armature by clicking the eye icon again.

---

Skinning: Weight Painting and Shape Keys

Ok, it's time to carefully paint the weight vertices for each vertex group in the list. The auto-skinning is just a basis, if the results are not good enough, it's up to the rigger to work on it.

Facial rigging demo:

How to paint the weights?

To quickly select the deforming bones and check the associated vertex groups in one click, you can display only the layer 31 of the armature, wich includes the deforming bones only (no controllers):

A quick search in Google (such as "blender weight painting tutorial") will give you the basis of the Blender's weight painting tools if you don't know them, this is something I won't elaborate here. Basically, it's all about browsing the vertex groups list and painting the weights. For a high quality skinning, 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...)

Here are a few notes about some specific painting regions:

Clothes

If the automatic skinning of clothes is not good enough, and if the body is modeled and skinned underneath, you can consider to transfer the weights from the body to the clothes. This way, they will perfectly stick to the body.

• Select the clothes objects, then the body (holding Shift, the target first, then the source), Space bar key > type "Transfer Mesh Data" > choose "Vertex Groups". In the tool shelf options (T key, bottom area) choose Nearest Face Interpolated instead of Nearest Vertex, All Layers instead of Active Layer, and you'll find here more options to fine-tune the transfer.

  

Eyes

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 bones 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.

Note you can use shape keys to make the character smile too and for eyebrows deformations (bone deform is less accurate), if you want to do so select the bones that you want to use with shape keys, and uncheck the Deform 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
• Back in the Auto-Rig Pro tab, select the transform parameter you want to use to drive (location, rotation, scale and the axis)
• Click Create driver.

If the shape key increases 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):

---

Appending - Linking in a scene

There are two methods to load a rigged character in a final file. Appending will load a static copy of the rigged character in the file, this means if you change the character geometry or armature in the rig file, the changes won't be applied to the character in the final file. It's just a copy. On the contrary, Linking will load a dynamic copy of the character (instance). Changes made in the rig file will automatically be applied in the final file, which is very useful!

• First make sure your rig file only contains your character rig and meshes objects (no render camera, light....)
• Parent the meshes objects to the armature for easy character scaling
• For consistency and clarity in the final scene, rename the root character object char_grp into something more approriate e.g. bobby_grp. This way you'll be able to easily distinguish multiple characters in the final scene.

Appending

• In a new scene, File > Append > Select the rigged character file > Objects > Select all objects with A key > Uncheck Active layer

Linking

More steps...

First, loading:

Option A - Object method (easy):

• In a new scene: File > Link > rigged character file path > Objects> Select all with A key, disable Active Layer

Option B - Group method:

• By default, all rig objects are grouped inside the "char_rig" group. You have to include the user added objects as well inside (mainly the character meshes). You can rename this group.
• Then, in a new scene: File > Link > rigged character file path > Group > Select the character's group
• After linking, all objects are frozen, all displayed in the same layer, including custom shapes. Let's change that:
• In the outliner, click the + to display the char object child.



• Right click on the arrow paper icon > Link Group Object to Scene.
• Hide the char object (it's a duplicate, unnecessary)

Second step, let's make the armature editable. Currently, it's not possible to enter pose mode!

• Select the armature > Ctrl-Alt-P > Make Proxy
• Yeah! Now we can pose the character.
• To finish, let's set up the picker panel. Just select the cam_ui object in the outliner > Ctrl-Alt-P > Make Proxy and parent it to the armature (in object mode Ctrl-P > Keep Transforms)
• In a new window (3d viewport), select a bone in pose mode and click Set UI Cam in the Rig Main Properties tab

---

Conclusion

Make sure to check the other documentation chapters on the left, Rig Features, Game Engine Export and other chapters.

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

Artell