Creating Blender add-on

Blender scripting system provides lots of opportunities to simplify and accelerate the workflow, allowing to outsource routine operations to the system and expanding work opportunities through access to the scripting language. However, writing a good script which can be used frequently in various projects, uncomfortable each time to reconnect it to each new project. In addition, this script can be improved with some windows and editable parameters fields. Making complete add-on from the script, you can expand it with additional functionality and connect to the Blender add-ons system.

To start lets write a simple script addign tube mesh to scene:

Now lets expand its functionality to a full add-on.

To convert a script into Blender add-on it needs to perform 4 Blender API requirements:

1. At first all the code, which currently is a simple command sequence, needs to be wraped in class. API requires to inherit users classes from several predefined classes:

API requires to declare all user classes as static, so they do not need to define __init__ constructor and __del__ destructor.

In our add-on example we perform an action to create a mesh. The function execute is declared in bpy.types.Operator class. It performes some action when its container class calls via the Blender API – just what we need. Therefore lets wrap our script code in a class and inherit it from bpy.types.Operator. Override function execute and puts all executable code of the script to it. Execute function should returns successful completion expression { ‘FINISHED’}:

A class that inherits bpy.types.Operator becomes a full Blender API operator.

Blender API operators have some other predefined functions to override by user:

• poll – performes before executing the operator, and in case of its execution error – the operator is not further performed;
• invoke – for interactive operations, such as drag and drop items;
• draw – for creation of graphic elements, panels;
• modal – used in operators, which require periodic call, for example by cutting edges. Do not interrupt after { ‘FINISH’} returns;
• cancel – called while operator cancel

2. To include created class into the Blender API, we need to register it by calling bpy.utils.register_class() function, specify in its parameters name of the class:

Before workflow finishing class needs to be unregistered:

It is necessary to perform registration of our class during add-on initialization, and unregistration of it – at the time of add-on closing. To do this Blender API provides the following condition: if the add-on code defines functions register and unregister, they will be called: the first when initializing add-on, the second – when it is turned off.

Append these functions to add-on code, and fill them with registering and unregistering our class instructions:

3. Any class registered in the Blender API, must have a unique identifier to refer it by ID.

As an identifier it is necessary to use a string constant with predetermined name bl_idname. This constant is required in any connnected to the Blender API class. Another class identifier requirement – its value should contains a point. Most likely for a more convenient grouping classes identifiers within the API.

To determine our class identifier lets create that variable and assign it a value of ‘mesh.create_tube’:

Then our class functional (execute function) which, after registration in the Blender API, becomes the operator, can be called by:

Another text constant bl_label, containing the label of our class, must be declared in the scope of it. This text will be used in panel headers or menu items featuring our class.

Lets define the necessary constants in our add-on class:

If you need to define other constants or variables in add-on class scope, it is recommended to provide them all with bl_ prefix.

4. To finalize add-on lets make its description. This requirement is not fully binding, but it is still worth carrying out of it. After writing a few add-ons without any descriptions, even their author is very difficult to understand their purpose. To make add-on description fill a dictionary with predefined name bl_info with required texts. bl_info dictionary has the following predefined items:
   1. name – the name of the add-on
   2. author – its author
   3. version – version of the add-on
   4. blender – Blender version for which add-on developed
   5. category – category for placing add-on in add-ons list
   6. location – where to look for add-on using
   7. url – link to the source code of the add-on
   8. description – more detailed description of the add-on

At a minimum it needs to fill the name, category, and blender items.

Add description to the beginning of our add-on :

The full source code of our add-on now looks like this:

The addon is finished in a minimum performance. You can install it to the Blender, open Python Console window and call the operator with bpy.ops.mesh.create_tube() command.

Call add-on functionality through Python Console is very inconvenient. Lets modify our add-on – add to the mesh creating menu (Shift + a – Mesh) new item to call our operator – creating a tube.

Append to our source code the definition of the function forms the structure of the desired menu. In our case – one button with “plugin” icon and text label taken from bl_label constant. Functionality of our operator will bind to this button.

layout object contains a structure that defines the menu. We added to it one item, associated with our operator through its bl_idname.

To appedn and remove this item to Blender menu during add-on registration and unregistration, add the following commands to the register and unregister functions:

Full add-on souce code:

If you have already installed the add-on, reinstall it – remove by clicking the Remove button in the User Preferences – Add-ons – Add Mesh: Create Tube Addon window and install it again from the file with modified source code.

After reinstalling add-on and its activation, a new item “Create Tube” appears in Add Mesh Menu.

When meshes added to scene, N-bar draws standart panel, with parameters set to assign initial values to newly created mesh. Lets add the same panel with initial parameters to our create tube add-on.

To create such panel in the N-bar, in the description of our class we need to add the variable with a predefined name bl_options. This variable – numbered set, the content of which depends on options we want to be available for the operator. Default value is “REGISTER” – only registration of the options (the single value when a variable is not explicitly defined). Add “UNDO” value to bl_options for the operator to include it in a cancellation stack (undo – redo) and make it possible to create a panel in the N-bar.

After adding this constant to our class, empty panel will be created in the N-bar with tube adding to scene.

The default parameters of tube generation specified in our execute function:

• n – number of edges
• r1 – outer tube radius
• r2 – inner tube radius
• h – tube height

We need to convert them from simple variables to the real operator properties. Operator properties represent bpy.props._property_type_ structure:

This example declares integer operator property with a default value of 0. To treat it in class functions self pointer is used:

Let’s convert the initial parameters of our operator to properties:

Remove direct set of these parameters in the begining of execute function. Inside the function treat properties with self pointer.

Since the initial tube parameters set by real bpy.props properties, creating a mesh, they will be automatically added to the initial mesh properties panel in the N-bar and can be tuned.

Full and final addon code:

Add-on completed. It could be installed and activated for quick creation of tube objects.

Mini bonus:

Lots of addons have this piece of code at the end:

This code is used only during the developing add-on process. Having add-on code or the IDE link to it in the Text Editor window – clicking Run Script button immediately runs the add-on (executes it registrations in Blender API with calling register function) allows immediately testing its work. This piece of code is absolutely not necessary in released add-on.