From BlenderWiki

Jump to: navigation, search

Script requirements

To have your script show up in the Add-Ons panel, it needs to:

  • be in the addons/ directory
  • contain a dictionary called "bl_info"
  • define register() / unregister() functions.

Script meta informations

You have to include a python dictionary named "bl_info" as outlined above.

bl_info = {
    "name": "My Script",
    "description": "Single line explaining what this script exactly does.",
    "author": "John Doe, Jane Doe",
    "version": (1, 0),
    "blender": (2, 65, 0),
    "location": "View3D > Add > Mesh",
    "warning": "", # used for warning icon and text in addons panel
    "wiki_url": "http://wiki.blender.org/index.php/Extensions:2.5/Py/"
                "Scripts/My_Script",
    "category": "Add Mesh"}
name
(string)
Name of the script. This will be displayed in the add-ons menu as the main entry.
description
(string)
This short text helps the user to decide if he needs the addon when he reads the addons list. Any further help text should be put in the help page (see wiki_url).
author
(string)
Author name(s).
version
(tuple of integers)
Script version. Please put any important notes into the warning field, don't use text in the version number.
blender
(tuple of 3 integers)
The minimum Blender version required to run the script. In the add-ons panel this is used to check if the user has a Blender version that is new enough to enable the script. eg.
Blender2.65 -> (2, 65, 0), note that the last value should normally be kept to zero, this is blenders sub-versions which scripts wont normally need to use.


location
(string)
Explains where the new functionality can be found. For example: "View3D > Properties > Measure"
warning
(string)
Used for warning icon and text in addons panel. If this is empty you will see nothing; if it's non-empty, you will see a warning icon and the text you put here alerts the user about a bug or a problem to be aware of.
wiki_url
(string)
Link to the wiki page of the script: here you should put the script manual and useful external links (not allowed anymore from 2.5x).
Exclamation mark.png
This url is mandatory to be accepted in Blender Addon repositories (see below)
category
(string)
Defines the group to which the script belongs. This is used for filtering in the add-ons panel. A list of categories currently used in the extensions project can be found below. Please pay attention to the correct spelling and capitalization of them.
List of categories
  • 3D View
  • Add Mesh
  • Add Curve
  • Animation
  • Compositing
  • Game Engine
  • Import-Export
  • Lighting
  • Material
  • Mesh
  • Object
  • Physics
  • Pyconstraint
  • Pydriver
  • Pynode
  • Render
  • System
  • Text Editor

Wiki page

Scripts submitted to or distributed in our Blender Addon repositories should always have a wiki page linked in the script itself (in bl_info dictionary). This is very important to be sure people won't be left wondering how to use a script, and to link to release logs in a nice way.

If in doubt: read our wiki guidelines

If you're new to mediawiki, please read Wiki guidelines

Temporary page

If you submit a script to the Blender Addon repositories, but don't have time to format a proper wiki page in the same time, please create the page anyway and add the code {{WikiTask/Todo}}, so that we see it's going to be written.

Page name

Compose the page name like this:

Extensions:2.5/Py/Scripts/ + <script category> + / + <script name>

Release logs page name

If you have a release log, don't add it to the Manual page itself to avoid too many informations; rather, add a new page with the same name as the extension page, but with namespace "Dev", like this:

Dev:2.5/Py/Scripts/ + <script category> + / + <script name>
Example
Script manual page Extensions:2.5/Py/Scripts/Animation/RotoBezier
Script development page Dev:2.5/Py/Scripts/Animation/RotoBezier


Use the ScriptInfo template!

In the extension manual page, use the template ScriptInfo.

If you have a release log page, you can link it in the releaselog field.

Here's the wikitext you should copy and fill in:
{{ScriptInfo
|name= Extension name
|tooltip= Tooltip
|menu= Location in the UI
|usage= Quick explanation of how to use the script
|version= Version
|blender= Compatible Blender version
|category= The category field used in bl_addon_info dict
|author= Author(s)
|license= Extension's License
|distribution= How the script is distributed (can be: Release, Contrib, Extern)
|note= Note(s)
|exe= Executable name
|download= Download url
|modules= Used standard Python modules
|deps= External python modules or Binary dependencies 
|data= Eventual data needed by the extension
|bugtracker= Extension tracker page URL where to report bugs
|warning= Eventual warnings
|link= Useful links (author homepage, documentation pages, etc)
|releaselog= Release log page, possibly in this wiki
|issues= Known issues
}}
Exclamation mark.png
This template is adaptive: unrequired slots can be left blank and won't show up, in order to return a clean table.


About external links

To avoid have scripts referring to broken links, since 2.5 we've chosen to ask our script developers to put their homepage in the wikipage and not allow external links right in the script itself. This is easier to manage for everyone that doesn't have access to Git repositories.

Please add your homepage in the link field, thanks!


Add a manual!

Take your time to write a small manual, explaining how to use the script options. Possibly, add pictures and if you have them, add videos.

Updates
When you add features to your addon, don't forget to add the proper documentation in the addon wiki page: this helps users and developers to have a good reference about the addon development.


Link your page in the catalog page

Once you have completed your script manual page, link it in the catalog page.


Publishing a script in Blender

If you want to publish your addon on Blender Foundation servers, please read about the Process to Submit Addons to Blender repositories.


See also

Addons usage

Addons manual page
Here we collect informations about general addons usage

Coding style

Style Guide for Python Code
Recomended coding conventions for the Python code
PEP8 Checker
A tool to check your Python code against some of the style conventions in PEP 8 just linked above
PYCH
Online PEP 8 Python code checker