I’m not really a Blender expert, but I did work a little on scripting once in a while over the past month or two. I thought I’d share some of the problems that confused me, so others might get it started faster.
I write “for programmers” because I think many of the mistakes I made ultimately stemmed from my attempts to use programming ideas on a scripting environment (more on that later), so non-programmers might not have a problem with them. But of course anyone who wants to script in Blender might find something here useful.
1. Most, if not all, of the Blender scripting documentation and discussion is geared towards scripting as a way to assist modeling, not to replace it (which is what I’m doing). If you’re trying to make a script that does any serious kind of modeling on it’s own, you probably won’t find any documentation (of course, if anyone knows anything I missed, I’d love to hear about it). Your main source of information is the reference - keep it in your browser favourites. But even that is kind of lacking (it contains all the fields and functions, but many of them have little or no description).
2. Most importantly, if you’re a programmer – the Blender scripting API is made for scripting, not programming. This means that many things work in a kind of counter-intuitive way for a programming API – because as a scripting API, it does not expect much logic and automatic flow – it’s meant to be simply a series of tasks that could have been done by a human Blender user. This mostly means two things:
2a. None of the functions work directly on objects. This is very confusing, because as a programmer you’d expect that, for example, to add a vertex to a Mesh, you’ll need to work with the mesh object. But the scripting world doesn’t work with behind-the-scenes objects – instead, it works on selected objects and active objects just like the Blender UI. If you want to do something to a mesh, you need to select it first, and then the mesh operations will know to work on it. The bpy.ops.object module has some functions for selecting objects, and bpy.context can give you information on currently selected objects.
2b. None of the functions have return values. This can be quite confusing for a programmer, as you might expect that, for example, after creating an object you’ll get a reference to it as a return value. But no – after you create an object, the only way to reference it is to use the fact that it automatically becomes active, and thus getting the active object from bpy.context.
3. Make sure you understand the difference between an object and a datablock. Okay, I don’t think I fully understand it myself, but I know it’s important – basically, all the details of your object (mesh, lamp, curve etc.) are saved in the datablock. The object is a simple, general purpose entity, which has a property called “data” that links to it’s datablock. So for example, if you select a mesh object and want to work on the mesh, you need to get the selected object’s name (from bpy.context), then get the actual object from bpy.data.objects[name], and then getting obj.data. The object is an instance of class Object, while the datablock will be an instance of class Mesh – so the vertices and other properties are in the Mesh, not the Object.
4. Generally, when you’re trying to make something happen automatically, it’s always good to do it step-by-step in the Python console first, and only then write the script. This is because debugging is very problematic in Blender, usually when you crash a script from the text editor, you have no idea which line crashed and why.
5. Some text editor tips:
5a. The Blender text editor is not exactly a professional IDE. Most importantly, save your work often – if you accidentally make an endless loop or an impossibly complex operation, Blender will crash and you’ll lose your current work.
5b. In case you’re not used to working with the keyboard in Blender – note that the keyboard focus, unlike in most applications, always changes to where the mouse cursor is. That means if you want to write something in the text editor, make sure the cursor is in the text editor (I can’t count how many times I started writing, only to find I’m activating all sorts of weird keyboard shortcuts in the 3D view).
5c. There’s a button in the text editor menu that activates context highlighting. I missed it at first, and it made my work much less pleasant.