Blender 3D: Blending Into Python/2.5 quickstart

In Blender 2.5  replaces the old   module, introducing with it a completely new Python API. This page is designed to give an overview of how to perform key scripting tasks with, and should be of interest both to newcomers and those transitioning from the 2.4x releases.

The console
The built-in Python console has had a major overhaul in Blender 2.5, and now supports autocompletion (press ). This is great for exploring all the new functions, though inline documentation is sparse.

Latest version (14-7-2010) activate console:.

Context + Operation = Result
The 2.5 series introduces the  module. Once you register your script as an "operation" it will integrate directly into the UI and can appear as a standard button identical to the built-in tools (which also use ). Usefully for programmers, the function call of each operation appears in the tooltip of its button.

There is also a big conceptual change in : instead of being explicitly passed a target, operations deduce one from Blender's current "context". The context includes an array of what is currently selected, the current active object or bone, the active editing mode, the state of the Blender window, user preferences, and more besides.

Operations take no arguments and return no values. For this reason calling them from within complex scripts is considered sloppy, since you must indirectly set the operation's target, then (unless you already have a pointer) hunt indirectly for its results. Calling objects' functions directly is still supported, of course; unfortunately, as of 2.5 alpha 0 there are still a lot of ops that can't be replicated with direct calls.

Performing tasks in 2.5
Remember that  functions do not return a value. After calling one to create an object, you will need to get a handle to the result yourself!

Creation and destruction

 * Creates an object and empty datablock, and links it to the current scene. See also.
 * Creates an object and empty datablock, and links it to the current scene. See also.


 * Creates a new scene. Can be a clone or full duplicate of the current scene.
 * Creates a new scene. Can be a clone or full duplicate of the current scene.


 * Adds verts, edges and faces to a mesh. Object mode only.
 * Adds verts, edges and faces to a mesh. Object mode only.


 * Adds a modifier to an object.
 * Adds a modifier to an object.


 * If two verts are selected, creates an edge. If three or more verts are selected, creates face(s) as well.
 * If two verts are selected, creates an edge. If three or more verts are selected, creates face(s) as well.


 * Adds a cube to the current mesh object. Other  functions exist.
 * Adds a cube to the current mesh object. Other  functions exist.


 * Adds a bone to the active armature.
 * Adds a bone to the active armature.


 * Deletes the selected objects, mesh, etc. Many versions exist for different types.
 * Deletes the selected objects, mesh, etc. Many versions exist for different types.
 * Deletes the selected objects, mesh, etc. Many versions exist for different types.

Manual object creation
If you need finer control than  provides, or just return values, follow this example:

""

There is also,  ,  ,   and.

Getting objects and data

 * A group of collections of Python objects. There are many - one for each type. As with normal dictionaries you can pick objects out by name or by index, to add new datablocks use  or   for images, sounds and fonts.
 * A group of collections of Python objects. There are many - one for each type. As with normal dictionaries you can pick objects out by name or by index, to add new datablocks use  or   for images, sounds and fonts.
 * A group of collections of Python objects. There are many - one for each type. As with normal dictionaries you can pick objects out by name or by index, to add new datablocks use  or   for images, sounds and fonts.
 * A group of collections of Python objects. There are many - one for each type. As with normal dictionaries you can pick objects out by name or by index, to add new datablocks use  or   for images, sounds and fonts.


 * An object's datablock.
 * An object's datablock.


 * A mesh's vertex collection. Read-only.
 * A mesh's vertex collection. Read-only.


 * An armature's bone dict, in object and edit mode respectively. If you access the wrong object for the current context, it will appear empty.
 * An armature's bone dict, in object and edit mode respectively. If you access the wrong object for the current context, it will appear empty.
 * An armature's bone dict, in object and edit mode respectively. If you access the wrong object for the current context, it will appear empty.

Context management

 * Set the current mode. Note that the mode may not end up exactly as you set it here: for instance,  can become.
 * Set the current mode. Note that the mode may not end up exactly as you set it here: for instance,  can become.


 * These functions return the user's currently active item, which is generally the last one of its type selected.  returns a generic Python type.
 * To set the active item, assign a Python object to one of the following values:
 * or
 * The active object is highlighted white in the outliner.
 * These functions return the user's currently active item, which is generally the last one of its type selected.  returns a generic Python type.
 * To set the active item, assign a Python object to one of the following values:
 * or
 * The active object is highlighted white in the outliner.
 * The active object is highlighted white in the outliner.


 * Returns an array of the currently-selected objects. Other functions exist for editbones, "editable objects" and pchans.
 * Returns an array of the currently-selected objects. Other functions exist for editbones, "editable objects" and pchans.
 * Returns an array of the currently-selected objects. Other functions exist for editbones, "editable objects" and pchans.
 * Returns an array of the currently-selected objects. Other functions exist for editbones, "editable objects" and pchans.


 * Boolean value defining whether the object is selected.
 * Boolean value defining whether the object is selected.

Registering an operation
See. With your script registered, you will be able to add it to the Tool shelf and launch it from the spacebar menu.