Scripted Objects are objects within your scene whose geometry and other properties are procedurally generated by a script. For many types of objects, it is far easier to write a script that generates the shape than to try to model it by hand. Fractal shapes are a good example of this. So are repetitive objects: fields of grass, clouds of snowflakes, and so on. In addition, scripting lets you build "intelligence" directly into your objects so they animate themselves in a realistic way.
Tool Scripts are scripts that you execute to perform specific functions. These may be very simple scripts that you write on the fly to accomplish certain tasks, or very complicated ones that effectively add new commands to Art of Illusion.
Startup Scripts are executed automatically every time Art of Illusion is launched. This allows you to configure the program in ways that are far more complex than what you can do through the Preferences window. It also allows you to write scripts that act as Plugins, adding new features to the program.
Many examples of all of these types of scripts will be presented later in this tutorial.
The Beanshell scripting language is designed to be "interpreted Java". Its syntax is based directly on Java, and if you have programmed in Java before, you can start writing Beanshell scripts almost immediately. There are a few differences you should be aware of, however. Beanshell adds several features to the language to make it more convenient as a scripting language, such as dynamic typing and method closures. In addition, there are a few features of Java that are not supported by Beanshell, such as generics.
Full documentation on the Beanshell language can be found at www.beanshell.org. (Note that Art of Illusion uses Beanshell 2.0.) In addition, if you have never programmed in Java before, you may want to look at Sun's Java tutorial. There is no need to go through the entire tutorial, but you should read the early sections to learn the language syntax and the basics of object oriented programming.
Art of Illusion uses the Buoy user interface toolkit. If you write many scripts that present user interfaces, you will probably want to learn about Buoy. This is not a requirement: you can always use Swing or AWT instead. But Buoy is much better, and that will allow you to take advantage of the many user interface classes that are built into Art of Illusion.
Before we go any further, there are some caveats I should get out of the way. There are several things you should be aware of before you begin scripting.
First, scripting is not fully documented. It gives you direct access to the classes and objects that make up Art of Illusion, and for many of them, there is no documentation available beyond the source code itself. In this tutorial, I will try to teach you how to do many of the things you are most likely to want to do; but as soon as you go beyond what is described here, you are on your own.
Second, scripting is subject to change. Once again: scripting gives you direct access to the program's classes and data structures, and those will change with time. As much as possible, I try to avoid changes that are likely to break compatibility, especially in the parts of the code most likely to be used by scripts. Nonetheless, you should assume that any script written for one version of Art of Illusion may need to be modified before it will run correctly on future versions.
Finally, scripting is dangerous. You can easily write a script which contains an infinite loop and freezes the program. Or you can write a script which corrupts the internal representation of your scene and causes the program to crash. I have made no attempt to protect against this, since doing so would necessarily limit the power of scripting. If you want extreme power and flexibility, scripting is for you. If you want a safe, predictable environment, you should probably stick to the more conventional modelling tools.
What? I haven't scared you off yet? Good! Because scripting really is an amazingly powerful tool, and as you will see, writing basic scripts is really very easy. Once you get a look at what can be done with scripting, you will wonder how you ever got by without it.
Next: A Simple Scripted Object