Animal Rigger ProScripting
Build, bind and export from Python, for batches of animals or a pipeline.
Every button in the add-on calls a function in one module, api. Anything you can do in the sidebar, a script can do.
Import it
When the add-on is installed from a file, Blender puts it under bl_ext.user_default:
from bl_ext.user_default.animal_rigger_pro import apiIf you installed it into another extensions repository, use that repository's name in place of user_default.
Rig an animal from a marks file
Mark the animal once, save the marks, and a script can do the rest:
import bpy
from bl_ext.user_default.animal_rigger_pro import api
mesh = bpy.data.objects["Dog_Body"]
# The marks, species, feet and features, from a saved file.
definition = api.load_json("/path/to/dog.arig.json", mesh)
# Stop here if anything must be fixed first.
rows = api.refresh_diagnostics(definition)
if not api.can_build(definition):
raise SystemExit([row.code for row in rows])
rig = api.generate(definition).rig # build the rig
report = api.bind(definition) # bind the skin
print("Points no bone moves:", report.unweighted)
api.export(definition, "/path/to/dog.fbx", engine="UNREAL")Run it in Blender's Scripting workspace, or from a terminal without opening Blender's window:
blender --background my_scene.blend --python rig_dog.pyThe main functions
| Function | What it does |
|---|---|
api.define(mesh, species="dog") | Starts rigging a mesh, like Start rigging this animal. Returns the definition. |
api.get_definition(mesh) | The mesh's definition, or None. |
api.load_json(path, mesh) | Loads a marks file onto a mesh, replacing its marks. |
api.save_json(definition, path) | Saves the marks to a file. |
api.refresh_diagnostics(definition) | Checks the marks and returns the problems, like Problems. |
api.can_build(definition) | True when nothing must be fixed first. |
api.generate(definition) | Builds or rebuilds the rig. .rig on the result is the armature. |
api.rebuild_preview(definition) | What a rebuild would change, without building. |
api.restore(definition) | Puts back the last build that worked, like Undo last build. |
api.rig_of(definition) | The animal's rig, or None. |
api.bind(definition, robust=False) | Binds the skin. robust=True is Robust bind. |
api.export(definition, path, engine="UNREAL") | Writes the rig out. See below. |
api.preflight(mesh) | The mesh check, with nothing changed. |
Export options
api.export(
definition, "/path/to/dog.glb",
engine="GLTF", # "UNREAL", "UNITY" or "GLTF"
naming="UNREAL", # "BLENDER", "UNREAL", "RIGIFY" or "MIXAMO"
root_motion=True, # travel and turn on the root bone
influence_limit=4, # bones per point; the engine's own limit when left out
animation=True, # bake the rig's action
)These match the options in the Export file window.
When a build fails
api.generate raises BuildAborted when the rig cannot be built, and the scene is left as it was. The problems are on the definition, with the same codes as the problems page:
for row in definition.diagnostics:
print(row.code, row.message)Stability
api.API_VERSION is 1 in add-on 0.1.0. Names and arguments in api only change when this number goes up. Everything outside api is internal and can change in any release.