Scripting

So confused

It is possible to extend Blender using Python. To interact with Blender the Blender Python API (BPY) is used. Scripts can be made into add-ons that can be shared with other python users.

Some basic things

Turn on Developer extras and python tool-tips in the Edit/Preferences/Interface tab.
Use the python console in blender for testing. It support autocomplete with the tab key.
The system console show printouts and errors from addons. Show it with the menu Window/Toggle System console.
Use Edit/Menu Search (F3) to search for commands.
Use reload scripts command to reload. It is also found in the menu blender icon/system/reload scripts. Add it to favorites with right click then q to use.
Hover over a menu or button and CTL+C to copy the command it will run and then you can paste it into the python console. For a operator you can remove the ) at the end and press tab to autocomplete and show all paramerters.
Blender use python 3.x.
To learn from existing scripts look at
- Blender 2.90\2.90\scripts\startup\bl_ui - For the user interface
- Blender 2.90\2.90\scripts\startup\bl_operators - for operators
- Blender 2.90\2.90\scripts\addons - For add-ons

Add-ons

The add-ons blender use can be managed from Edit/Preferences/Add-ons. Enable/Disable the addon of choice, modify it's settings, read documentation and report bugs. To install a new add-on use the Install button to select the python or zip file with the addon. The add-on will be installed in the Blender 2.90\2.90\scripts\addons folder. If it is a python file it will be put directly in the folder and if it is a zip it will be unpacked into a sub folder.

A blender add-on must contain a bl_info variable, a register function and a unregister function. If the add-on is in multiple files and to be put into it's own folder they should be in a __init__.py file. The bl_info variable is filled with metadata that Blender use it to display information about the add-on in the Preferences\Add-on panel. The register function is called when they add-on is loaded and it should register classes, add menu items and everything else to prepare the add-on. The unregister function cleanup before the add-on unloads and should undo what the register function did.

bl_info

What to extend

You extend blender by defining operators or user interface elements such as buttons, menus, headers and panels. This is done by defining a class, which is a subclass of an existing type.

panels - bpy.types.Panel

menus - bpy.types.Menu

operators - bpy.types.Operator

bpy.types.PropertyGroup

bpy.types.AddonPreferences

bpy.types.UIList

Application Modules

This is the application modules you find grouped inside of Bpy.

Context - bpy.context

This store the active state of blender such as user selection, scene, tools settings and more. Some functions get a context sent in and then it's best to use it as it instead. The context is read only and should be changed using API functions. For example you can modify the settings in the active_object but to change what object is active use the correct API function or variable.

.active_object
.selected_objects
.scene
.area

Data - bpy.data

Used to access data from the loaded blend-file. At the top level there is a number of collections that you can access by name or index. Examples of collections are cameras, meshes and lights. To add or remove data-blocks use the collections new and remove functions. In each data-block you can access its attributes. Tooltips in the blender often show the attribute they modify.

https://docs.blender.org/manual/en/latest/files/data_blocks.html

scenes - docs

A blender file can contain multiple scenes. To get the active scene use context.scene.

collections - docs

A collection contains objects and children collections.

Use .objects() to get objects directly linked in the collection.
Use link()/unlik() to add/remove objects from collection.
.all_objects give all objects including objects in child collections.
.children contains the child collections of a collection. Use link() and unlink() to connect/disconnect a collection to it.
When creating a new collection (bpy.data.collection.new()) store it in a variable as it might be given a other name if it already exist.
The master collection for a scene is stored in scene.collection. All other collections are found in bpy.data.collections.

armatures - Skeleton used to deform meshes.

https://docs.blender.org/api/current/bpy.types.Armature.html

materials - Set shading and texturing render properties.

https://docs.blender.org/api/current/bpy.types.Material.html

meshes - Geometry made of vertices/edges/faces.

https://docs.blender.org/api/current/bpy.types.Mesh.html

objects - An entity in the scene with location, scale, rotation.

https://docs.blender.org/api/current/bpy.types.Object.html

Operators

Types - bpy.types

Here are the blender specific types. Such as mesh, object or lamp.

Utils

bpy.utils.register_class

bpy.utils.unregister_class

Standalone Modules

bgl

bmesh - documentation

The bmesh module gives access to blenders internal mesh editing API. To use it you create a bmesh, get the data from a mesh with from_mesh(), modify the bmesh and then write the data back to the mesh with to_mesh().