From BlenderWiki

[edit] A working Python example

Now that you’ve seen that Blender is extensible via Python scripting and that you’ve got the basics of script handling and how to run a script, before smashing your brain with the full python API reference, let’s have a look at a quick working example.

We will present a tiny script to produce polygons. This indeed duplicates somewhat the Space → Add → Mesh → Circle toolbox option, but will create “filled” polygons, not just the outline.

To make the script simple yet complete it will exhibit a Graphical User Interface (GUI) completely written via Blender’s API.

[edit] Headers, importing modules and globals

The first 32 lines of code are listed below:

Script header

After the necessary comments with the description of what the script does there is (lines [016-022]) the importing of Python modules. Blender is the main Blender Python API module. NMesh is the module providing access to Blender’s meshes, while BGL and Draw give access to the OpenGL constants and functions and to Blender’s windowing interface, respectively.

The math module is Python’s mathematical module, but since both the math and the os modules are built into Blender you don’t need a full Python install for this!

The polygons are defined via the number of sides they have and their radius. These parameters have values which must be defined by the user via the GUI, hence lines [025-026] create two “generic button” objects, with their default starting value.

Finally, the GUI objects works with, and generates, events. Events identifier (or events ID for short) are integers left to the coder to define (they should all be different, unless special needs!). It is usually a good practice to define mnemonic names for events, as is done here in lines [029-031].

[edit] Drawing the GUI

The code responsible for drawing the GUI should reside in a draw function (GUI drawing).

GUI drawing

Lines [037-039] merely grant access to global data. The real interesting stuff starts from lines [042-044]. The OpenGL window is initialized, and the current position set to (x=8, y=103). The origin of this reference is the lower left corner of the script window. Then the title “Demo Polygon Script” is printed. A further string is written (lines [047-048]).

Then the input buttons for the parameters are created. The first (lines [049-050]) is a Num Button, exactly like those in the various Blender Button Windows. For the meaning of all the parameters please refer to the API reference. Basically there is the button label, the event generated by the button, its location (x,y) and its dimensions (width, height), its value, which is a data belonging to the Button object itself, the minimum and maximum allowable values and a text string which will appear as a help while hovering on the button, as a tooltip. Lines [051-052] defines a Num Button with a slider, with a very similar syntax. Lines [055-056] finally create a Draw button which will create the polygon and an Exit button.

[edit] Managing Events.

The GUI is not drawn, and will not work, until a proper event handler is written and registered (Handling events).

Handling events

Lines [058-060] define the keyboard event handler, here responding to the Q with a plain Exit() call.

More interesting are lines [062-072], in charge of managing the GUI events. Every time a GUI button is used this function is called, with the event number defined within the button as a parameter. The core of this function is hence a “select” (if/elif) structure executing different codes according to the event number.

As a last call, the Register() function is invoked. This effectively draws the GUI and starts the event capturing cycle (“event loop”).

[edit] Mesh handling

Finally, Main function shows the main function, the one creating the polygon. It is a rather simple mesh editing, but shows many important points of the Blender’s internal data structure.

Main function

The first important line here is number [082]. Here a new mesh object, poly is created. The mesh object is constituted of a list of vertices and a list of faces, plus some other interesting stuff. For our purposes the vertices and faces lists are what we need.

Of course the newly created mesh is empty. The first cycle (lines [085-092]) computes the x,y,z location of the NumberOfSides vertices needed to define the polygon. Being a flat figure it is z=0 for all. Line [091] calls the NMesh method Vert() to create a new vertex object of co-ordinates (x,y,z). Such an object is then appended (line [092]) in the poly Mesh verts list.

Finally (lines [095-096]) a last vertex is added in the centre.

Lines [099-104] now connect these vertices to make faces. It is not required to create all vertices beforehand and then faces. You can safely create a new face as soon as all its vertices are there.

Line [100] creates a new face object. A face object has its own list of vertices v (up to 4) defining it.

Lines [101-103] appends three vertices to the originally empty f.v list. The vertices are two subsequent vertices of the polygon and the central vertex. These vertices must be taken from the Mesh verts list.

Finally line [104] appends the newly created face to the faces list of our poly mesh.

[edit] Conclusions

If you create a polygon.py file containing the above described code and load it into a Blender text window, as you learned in the previous page, and press AltP in that window to run it, you will see the script disappearing and the window turn grey. In the lower left corner the GUI will be drawn (The GUI of our example).

By selecting, for example, 5 vertices and a radius 0.5, and by pressing the Draw button a pentagon will appear on the xy plane of the 3D window (The result of our example script).

Redirects to fix

• Doc:Manual/Game Engine/Logic/Actors → Doc:Manual/Game Engine/Logic/Object type
• Doc:Manual/Modelling/Meshes/Edge and Face Tools → Doc:Manual/Modelling/Meshes/Edge Tools