Back to files

Using kludge3d's scripting features

Introduction

In my opinion, the Python scripting capability of kludge3d is easily the most interesting feature to be added in recent memory. At the moment, the kludge3d functions that can be accessed through scripts (the "scripting interface" or "scripting API") are limited, as compared to other 3d modelers with Python scripting (ex. Blender). However, there is enough to create some interesting tools.

Before going any further, let it be known that I assume that the reader is at least a little familiar with Python. If you are not, I suggest that you visit the Python web site (www.python.org) and check out some of the tutorials. Python is an easy language to learn.

The functions in kludge3d's scripting API are listed in the file 'src/pywrapper_wrap.doc'. You can also check out the 'src/pywrapper.c' file for more info.

Running Python code

Running Python code in kludge3d is easy. Once kludge3d is running, you can type Python code into the text box at the bottom of the "Groups" notebook tab. You can treat this the same as you would the command-line Python interpreter, with the following exceptions:

• Don't call any functions which expect input from stdin. You won't be able to send any input to them.
• The command-line Python interpreter will print out the return value of any statement you execute directly. Kludge3d won't do that; you need to use the 'print' keyword. (See the next item, also.)
• You won't see the text output. This is where kludge3d's log window becomes handy.

About the log window

Were it not for the log window, all of the text output generated by kludge3d (including output from Python scripts) would be sent to the console. If you use your window manager to start kludge3d (rather than a command line), you would never see such output. To remedy this, the log window intercepts and stores all of the text output by kludge3d.

There is a second Python text box at the bottom of the log window, for your convenience. You can use either one; they both do the same thing.

Writing re-usable tools

Using the Python text box, you can experiment with the scripting API. However, once you are ready to create a re-usable script, you will want to create a script file to store it in. See the README file for info on where to put your script files. Briefly, they should go in ~/.kludge3d, and you should put an "import" entry in ~/.kludge3d/base.py for each of your modules.

Once you've done this, you can call your script by entering:

modulename.functionname( )

...in the Python text box, where modulename is the name of the file that you stored your functions in, and functionname is the name of the function you want to call. Any arguments to your function go between the parenthesis, and are separated by commas. You can avoid all this typing (and can avoid having to remember the arguments to your functions) by adding your functions to the script-shortcut buttons in kludge3d's "Tools" notebook tab.

About the shortcut buttons in the "Tools" notebook tab

If you would like to create shortcut buttons for your scripts, you need to add the following line to the end of your script file:

register_function( __name__, functionname )

You would obviously substitute your function's name for functionname. You need to call register_function once for each function you want to appear in the Tools tab.

The next time you run kludge3d, a button with your function's name will appear under the "Scripts" rollup in the "Tools" notebook tab. If you click on the button, a dialog will pop up showing the function's name, the "doc string" for the function, and a prompt for each of the function's arguments.

Take a look at the example scripts

If you're uncertain about where to start, take a look at the scripts I've written. They can be found in the 'scripts' directory. The 'prefabs.py' file is a good place to start.