PyConstraints

Blender Constraints System 

 Overview

This patch implements python-defined constraints.

Pyconstraints are python text buffers that begin with #BPYCONSTRAINT.
No loading of external pyconstraints is supported (deliberately), the idea being that forcing people to include the constraints in the .blend is the best way to avoid compatibility issues.

 A PyConstraint needs to define two functions:

  • doConstraint(source_matrix, target_matrix, idproperties_of_constraint)
  • getSettings(idproperties_of_constraint) 

In addition, if a PyConstraint needs to use a target object as input:

  • USE_TARGET = True;  
  • doTarget(target_object, subtarget_bone, target_matrix, id_properties_of_constraint) 

The patch I present here is based on the initial patch released by Joe Eagar (joeedh). Please refer to the sample script(s) provided here to understand how to work with Py-Constraints.

 

 Usage Notes - Scripting

The doConstraint function is called to evaluate the constraint. It is vital that this function is present, otherwise the constraint will not do anything. The source_matrix and target_matrix are both copies of the matrices passed to the evaluate_constraint c-function. The id_properties_of_constraint argument however is wrapped data - it is the idproperties that are stored for each PyConstraint. This function should return a 4x4 matrix, which will become the owner's new matrix (after interpolation is done, that is).

The getSettings function is called when the user presses the 'Options' button in the UI. It is responsible for getting/setting the values of the id_properties of the constraint and setting up + processing the clever numbut that pops up to do so. When writing a script that takes advantage of this, must use the Blender.Draw.PupBlock method to create the UI (all other unrelated commands offerred by the Blender.Draw module should not be used). 

The USE_TARGET = True; line is needed to show that the constraint needs to have a target. It doesn't really matter too much where you place it in the script, as long as it is in the global namespace (i.e. not within a function). 

The doTarget function is called to perform any operations (set private id_properties not exposed to the user) that are needed by the constraint involving direct access to the target. Another purpose of this function is to make a custom 4x4 matrix. It is not critical that this function is defined, as the constraints code will default to making sensible guesses about what  target matrices to retrieve instead. The target_object is wrapped data, representing the target object; and the subtarget_bone is also wrapped data, representing the subtarget pose-bone (where applicable). Also, the id_properties_of_constraint is wrapped idproperties. On the other hand, the target_matrix is not wrapped data. This function should return a 4x4 matrix (which is the target matrix to use).

Patch - Latest Version

 Latest Patch

Latest ('Stable') Patch

Sample Constraints (fully functional)