Blender 3D: Noob to Pro/Advanced Tutorials/Python Scripting/External scripts

Embedding a script inside a Blender document is useful for some special purposes, but often you want to be able to reuse it across any number of Blender documents, and perhaps distribute it to others for use with their Blender projects. To do this, you will need to save the script as a text file that can be copied into your Blender user preferences. It will also need to have some additional information inserted.

The Script Header

In order for your script to be installable, it needs to have the following as its first line:

#!BPY

Following this, add a multiline Python string to define a name and other information for the script to appear in the Scripts menu:

"""
Name: 'Add Tetrahedron'
Blender: 249
Group: 'Add'
Tooltip: 'Creates a tetrahedron object'
"""

The “Blender:” line specifies the minimum required version of Blender that the script is compatible with; here we specify “249” to indicate that it wants Blender version 2.49. The “Group:” indicates which of the submenus of the Scripts menu that the script will appear in: it must match one of the existing submenu names, otherwise the script will go into the “Misc” submenu. The “Name:” is the name of the menu item that will be added for invoking this script, and the “Tooltip:” will appear when the user pauses with the mouse over that menu item.

Put It All Together

So now your complete script looks like this:

#!BPY
"""
Name: 'Add Tetrahedron'
Blender: 249
Group: 'Add'
Tooltip: 'Creates a tetrahedron object'
"""

from __future__ import division
import math
import Blender
 
NewMesh = Blender.Mesh.New("Tetrahedron")
NewMesh.verts.extend \
  (
    [
        (0, -1 / math.sqrt(3),0),
        (0.5, 1 / (2 * math.sqrt(3)), 0),
        (-0.5, 1 / (2 * math.sqrt(3)), 0),
        (0, 0, math.sqrt(2 / 3)),
    ]
  )
NewMesh.faces.extend \
  (
    [[0, 1, 2], [0, 1, 3], [1, 2, 3], [2, 0, 3]]
  )
TheObj = Blender.Object.New("Mesh", "Tetrahedron")
TheObj.link(NewMesh)
TheScene = Blender.Scene.GetCurrent()
TheScene.link(TheObj)
TheScene.update()
Blender.Window.Redraw()

Making The Script Installable

The contents of your script are now complete. In the Text Editor, find the “Save As” option under the “Text” menu, and choose a filename for saving your script—perhaps call it TetrahedronMaker.py.

That’s it. This saved text file is now ready for installation into your Blender user settings, or distribution to others for installation in their settings.

Installing The Script

To install the script, simply copy the file you previously saved into the user-scripts directory within your Blender user settings.

For different operating systems this is:

• Linux/Unix: ~/.blender/scripts
• Windows XP: C:\Program Files\Blender Foundation\Blender\.blender\scripts
• Windows XP (alt): C:\Documents and Settings\USERNAME\Application Data\Blender Foundation\Blender\.blender\scripts
• Windows Vista: C:\Users\USERNAME\AppData\Roaming\Blender Foundation\Blender\.blender\scripts
• Mac OS X:
  • Under Mac OSX the path is actually hidden in the blender.app so to know the path you would have to know that the script folder is actually hidden in the blender.app itself. Assuming that Blender is in the applications directory the path would be "/Applications/blender/blender.app/Contents/MacOS/.blender/scripts" If you try to open the .app contents from the finder you will notice that .blender section of the path is not visible, while blender will still be able to navigate to this folder.
  • Right-click (or ctrl-click) the file "blender", and select "Show Package Contents" in the popup-menu. It will display all the hidden files under blender's folder, and select "scripts" folder inside it.
  • To see this folder from the OSX terminal use the ls -a command (lists all folders/files even hidden) in the MacOS folder of the listed path. It is probably a good idea to create an alias to the scripts folder in the "/Applications/blender-2.37a-OSX-10.3-powerpc" folder so that scripts can be easily manipulated through the finder. I know that its confusing that Blender should have its script folder buried inside the app but it is necessary to keep the app portable and not require an install.
  • A safer approach than the one above consists in keeping your scripts somewhere in your home folder: with this scheme, there is no risk of deleting your scripts when you upgrade your blender application, as they are not contained within its folder. A method that follows this principle is as follows: create a folder that will contain your scripts (or some of them) inside your own home directory; then, instead of putting your files directly in the .../.blender/scripts/ folder discussed above, simply add a link to your script directory in the .../.blender/scripts/ folder (for instance with the "ln -s" Unix command, or by doing "open /Applications/blender-2.37a-OSX-10.3-powerpc/blender.app/Contents/MacOS/.blender/scripts/" [adapted to your version of blender] and then creating a link through the Finder, with File->Make Alias). Blender will now find all the scripts that you put in your home directory: it will follow the link you created in its .../.blender/scripts/ folder and go to the corresponding folder in your own directory, and find all the python scripts you put there.

Using The Installed Script

To make use of the installed script, open a new Blender document. Get rid of the default cube to avoid it obscuring things. Split the 3D View into two horizontally, and change one of the two into a Scripts Window. Go to the “Scripts” menu, and see if your “Add Tetrahedron” item appears in the “Add” submenu; if it doesn’t, select “Update Menus” (the last item in the “Scripts” menu) and have another look. Select your new menu item, and watch your tetrahedron object appear in the 3D View!