Blender 3D: Noob to Pro/Advanced Tutorials/Blender Scripting/A Separately Installable Addon

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Embedding a script inside a Blender document is useful for some special purposes, but often you want to be able to reuse an addon across any number of Blender documents, and perhaps distribute it to others for use with their Blender projects. To do this, you will need to save the script as a text file that can be copied into your Blender user preferences. It will also need to have some additional information inserted.

The Addon Info Dictionary[edit | edit source]

In order for the addon to be installable by Blender, it will need to define a global called bl_info, the value of which is a dictionary. This contains various information about compatibility with versions of Blender, and also descriptive information to be shown to the user as they browse through the list of installable addons.

Here’s what the info should look like:

bl_info = \
    {
        "name" : "Tetrahedron Maker",
        "author" : "J Random Hacker <jrhacker@example.com>",
        "version" : (1, 0, 0),
        "blender" : (2, 5, 7),
        "location" : "View 3D > Edit Mode > Tool Shelf",
        "description" :
            "Generate a tetrahedron mesh",
        "warning" : "",
        "wiki_url" : "",
        "tracker_url" : "",
        "category" : "Add Mesh",
    }

Most of the fields are informational. The “category” value must be one of the predefined ones that you will see listed in Blender’s User Preferences window when you switch to the “Add-Ons” tab; the addon display is sorted by category and by name within category, and the user can list scripts in all categories or in just one category.

The “version” field indicates the version of your script, and can be a tuple of any number of integers; the numbers are shown to the user joined with decimal points (e.g. “(1, 0, 0)” is displayed as “1.0.0”). The “blender” field indicates compatibility with versions of Blender; Blender versions older than this are supposed to reject the script. (Though what happens when a newer version introduces a backward-incompatible API change is not quite clear...)

Making The Addon Installable[edit | edit source]

The contents of your addon script are now complete. In the Text Editor, find the “Save As” option under the “Text” menu, and choose a filename for saving your script—perhaps call it TetrahedronMaker.py.

That’s it. This saved text file is your complete addon, ready for installation into your Blender user settings, or distribution to others for installation in their settings.

Installing The Addon[edit | edit source]

To install the addon into your Blender user settings, go to the User Preferences, and bring up the Add-Ons tab. (It doesn’t matter what document you might have open at this stage.) In the window header, click the “Install Add-On...” button, and find the TetrahedronMaker.py file you previously saved; select that, and click the “Install Add-On” button in the file selector. This copies the script file into your personal addons directory, which in Unix/Linux is ~/.blender/2.5x/scripts/addons/. You can also directly copy your script file into this directory, instead of using the “Install Add-On...” button. To uninstall an addon, use the Remove button that appears in its info panel (see below) or delete the script from this directory, together with its .pyc (compiled) version (which you will find in the __pycache__ subdirectory).

Using The Installed Addon[edit | edit source]

To make use of the installed addon, open a new Blender document. Go to the User Preferences window, and bring up the Add-Ons tab. Browse through the list of addons (feel free to restrict the display to the “Add Mesh” category as specified above) until you find your Tetrahedron Maker. You can click the white triangle to the left of the name to expand the list item display to show all the details:

Note the buttons that may appear along the bottom: the “Remove” button appears for your own user-installed scripts, not for ones installed systemwide; the “Link to the Wiki” button is only visible if you provided a URL in the “wiki_url” field of your bl_info; and “Report a Bug” comes up only if there is something in the “tracker_url” field.

Click the checkbox in the top right corner of the item display to enable the addon for this document.

Now switch to the 3D View, bring up the Tool Shelf if it’s not already visible, and you should see that familiar panel appear:

You know what to do next...