Main Generator Engine¶
This describes the main classes that manage the generation of a rig.
The rig generation process is managed by an instance of the Generator class. It duplicates the metarig, instantiates the rig objects, creates the root control bone, executes the generation stages, and manages some other global operations.
The generator instance has the following fields:
- Blender context in which the generation was invoked.
- Current scene.
- Current view layer.
- Current layer collection.
- Current collection.
- The original metarig object.
- The rig object being generated.
- The name of the current stage being executed.
- The ScriptGenerator object that manages generation of the UI script.
- The ArtifactManager object that manages additional helper Objects produced by rig generation.
- The random identifier string for the rig being generated.
- A list of all rig instances.
- A list of all rig instances without a parent rig.
- A map from bone names to the rig instance that owns them.
- A map from bone names to sets of bones created by copying from them.
These are the public methods of the Generator class:
- By default, all bones left without a parent are parented to the root control. This method excludes a bone from this function.
generator.find_derived_bones(bone_name, *, by_owner=False, recursive=True)
- Returns a set of bones copied from the specified one. The
by_owneroption limits search to the owner rig of the bone. The
recursiveoption enables walking through multiple chained copies.
generator.set_layer_group_priority(bone_name, layers, priority)
- Assign a priority value used for choosing which layer to base the bone group choice on for the given bone. The value is set for the given layers.
- May be used from
SubstitutionRig.substitute()to rename ORG bones.
- Looks up a rig class by its ID string.
- Returns a string containing the rig class and base bone.
Rigs that don't inherit from the
BaseRig class are considered to use
the legacy interface, and are wrapped in a
wrapper class. The wrapper itself interfaces.
The old style
generate method is invoked during the
generate_bones stage, because that is the only stage that can create
- The instance of the legacy rig wrapped by the class.
In some special cases (mainly backward compatibility) it is necessary to present one or more different rig components as one, with the actual set of rigs depending on the structure and parameters of the rig.
This can be achieved by implementing a
Rig class that inherits from
rigify.base_generate.SubstitutionRig. Such classes are handled
specially during the rig instantiation phase: instead of saving the
newly created rig instance, the Generator immediately invokes its
substitute() method, and uses the list of rig instances returned
from it instead.
- The instance of Generator.
- The rig being generated.
- The name of the main bone that instantiated the rig.
- The parameters attached to the main bone.
- Snapshot of the parameters attached to the main bone.
- Invoked immediately after instantiation and expected to return a list of
If it is necessary, this method may temporarily switch to edit mode to modify bone parenting and/or orientations.
- Returns the parameters container for the given bone.
rig.assign_params(bone_name, param_dict=None, ...)
- Assigns values into the parameter container of the given bone. Parameter values may be supplied as a dictionary, or directly as named parameters. If both are supplied, the named parameters have precedence.
- Creates a rig instance of the given type (specified as a class, or an ID string) for the specified bone.
Some functionality within the generation process isn't naturally tied to any specific rig component, and is instead equally shared between all of them. The generation of the UI script is one such example.
Such features can be conveniently implemented via classes that inherit
rigify.base_generate.GeneratorPlugin. Due to the metaclass and
base classes used by GeneratorPlugin, such classes become parameterized
singletons, which can have the same stage callbacks as regular rig
- Stage callbacks of the generator plugin instances are invoked after all of the rig callbacks are completed, in the order of decreasing priority.
- The Generator instance.
- The rig being generated.
- Initializes the plugin instance. As a parameterized singleton, every unique set of constructor parameter values creates a separate class instance, while passing the same values result in the same object.
This class manages additional objects that are created as a part of generating the rig and are owned by it. It tracks them across multiple re-generations of the rig to avoid duplicates, and deletes them when not needed anymore.
All artifact objects must be uniquely identified by their owner rig component (its base bone) and an arbitrary name assigned within it. At the end of generation any previously existing artifacts that were not touched during this generation pass are deleted.
Artifacts must not be deleted during generation other than through methods of this class, or it can cause a crash.
artifacts.create_new(owner: BaseRig, obj_type: str, name: str) -> Object
- Creates an artifact object of the specified type (same values as
object.type) and name from scratch. If an artifact with that name already exists from a previous generation, all references are updated to point to the new instance, and the existing one is deleted.
artifacts.find_or_create(owner: BaseRig, obj_type: str, name: str, *, recreate=False) -> tuple[bool, Object]
- Creates an artifact object of the specified type and name, or reuses the
existing one. If there is a type mismatch, the existing object is
deleted as if it didn't exist.
recreateparameter is used to implement
create_new, i.e. makes the method always create a new instance, replacing the existing one if necessary.
Returns a flag signifying if an existing instance was found, and the found or created object.
artifacts.new_temporary(owner: BaseRig, obj_type: str, name="temp") -> Object
- Creates a new temporary artifact of the given type. Temporaries are always deleted at the end of generation and are tracked separately from the permanent artifacts. The name only matters for diagnostics and naming the Object.
- Immediately deletes the temporary object that was previously created