Scripting in Art of Illusion

Copyright 2002-2013 by Peter Eastman

Last Modified: Dec. 2, 2013
Modified For: v3.0
Original Release Date: Nov. 24, 2002
Originally Written For: v1.3


  1. Overview
  2. A Simple Scripted Object
  3. Animated Objects
  4. Textured Objects
  5. An Advanced Scripted Object
  6. Object3D and ObjectInfo
  7. Tool Scripts
  8. Startup Scripts

1. Overview

Scripting is one of the most powerful features of Art of Illusion. It uses the Groovy scripting language to let you write scripts which directly control or modify the classes and objects that make up Art of Illusion. The scripts that you can write fall into three classes:

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 Groovy scripting language is modelled after Java, and if you have programmed in Java before, you can start writing Groovy scripts almost immediately. There are many differences, however, and Groovy adds lots of features to the language to make it more convenient as a scripting language. Full documentation can be found at (Art of Illusion also supports the Beanshell scripting language, but that is mainly for backwards compatibility. Groovy is recommended for most purposes, and it is used exclusively in this tutorial.)

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