Blender 3D: Noob to Pro/Advanced Tutorials/Python Scripting/Addon Custom Property

Addons will commonly do more than unconditionally perform a single action; the user may be able to control their actions in various ways. We can add controls for adjusting settings to our addon panel, and associate these with custom properties that we define for the current scene; Blender will then take care of updating the property values as the user operates those controls, and our operator’s invoke routine can fetch those property values when it runs.

Defining A Property
Properties need to be defined at the same time our custom classes get registered. We previously did this in top-level statements, but now let’s gather it all together into a register method, like this:

Here we are attaching the property as a new attribute of Blender’s Scene class; Python lets us assign new attributes to just about any object, and Blender takes full advantage of that. Note that the property must be created using one of the property-definition routines provided in bpy.props: choose the one that matches the type of property you want to create. Here we are defining a simple true/false toggle, which the user will control via a checkbox. Whatever name you use for your custom class attribute, an instance of that class will have an attribute with the same name, holding the actual value for that property.

The name will be used as the name of a control for examining or changing this property, while the description will appear as a tooltip when the user hovers the mouse over the control. The default is used as the initial value of the property.

Note also I tried to use a name, make_tetrahedron_inverted, which is less likely to clash with names defined by other addons or parts of Blender.

Let’s also add an unregister method, which undoes everything that <TT>register</TT> does. This won’t actually be used for now, but it will become relevant later when we extract the addon for separate installation:

To make the checkbox appear, add the following line to our panel’s <TT>draw</TT> routine:

The first argument to the <TT>prop</TT> method must be an instance of the class to which we attached our property definition above; in this case, it is the current scene.

Finally, we need to finish off our script with the following bit of boilerplate which will invoke our registration routine in the situations (like the Text Editor) where Blender doesn't do it for us:

Using The Property
Now we actually need to use the property in our operator’s <TT>execute</TT> routine. We’ll use it to negate a scale factor which will be applied to the Z coordinate of the vertices of the tetrahedron:

But only the last vertex has a nonzero Z coordinate, so this is the only one that needs a change in its computation:

Put It All Together
To recap all our changes, here is the complete updated script:

As before, execute the script with. Check the Tool Shelf in the 3D View, and your panel should now look like this:

Try executing it with and without the checkbox checked, and you should end up with two tetrahedra pointing in opposite directions.