Scripts

Note: This page may be out of date. To download and install the very latest scripts and plugins, please click the "Getting Started" link in the menu on the right. To read information about the latest scripts and plugins, please visit the Art of Illusion Scripts and Plugins Repository.

Installing Scripts and Plugins: You do not have to compile plugins for Art of Illusion; the process of downloading and installing is automatic and easy. Please view the "Getting Started" page here on the wiki for a brief tutorial.

Art of Illusion core features can be extended in many ways using scripts and/or plugins. Scripts are short pieces of code written in beanshell script, a scripting language quite close to Java. Plugins are java archive files that contains java bytecode. Scripts and plugins will not be discussed here (please refer to the Art of Illusion home page where a full discussion of this topic is available). However, it is essential for an end user to understand how scripts and plugins work since some essential features are provided through this mechanism.

Types of Scripts

There are three flavors of scripts, namely Object scripts, Tools scripts and Startup scripts. Scripts are placed in the Scripts subfolder of Art of Illusion main folder: tools scripts go in the Scripts/Tools folder, objects scripts go in Scripts/Objects and startup scripts go in Scripts/Startup. Objects scripts, tools scripts and startup scripts purposes are completely different.

Object Scripts
Object scripts create one or several object(s) each time the script is evaluated: the object is the script and it is relevant to call it a scripted object. For example, such a script can create a hexagonal grid with a sphere at each lattice node. Since objects scripts are evaluated each time the scene is likely to change, the time parameter can be used to animate the scripted object. Using the hexagonal grid example, the radius of the spheres can vary with time.

Each scripted object in the scene carries its own copy of the script which has to be executed before the scene is evaluated. In this respect, the object scripts that reside in Scripts/Objects can be seen as templates for a particular kind of scripted object. At creation time, one of these template can be loaded, or a new script can be written from scratch. If a script “template” is used, then the user will most likely change some parameters or even modify the script code. For obvious reasons, the original script file will not be updated, unless the user saves the modified script and overwrites the original file.

Tool Scripts
Tool scripts, on the other hand, modify one or several existing object(s) or create a new object. They are similar to any other editing command, except that the command code happens to reside in a script rather than in AoI. Tool scripts are not modified, unless you need to tailor one for specific purposes. They are executed through selecting the script name in the Scripts submenu of the Tool menu. Tool scripts are generally the first kind of extensions one wishes to install because some features they bring are essential. Indeed, AoI is shipped with several scripts. It is often easier to write a script than to write the equivalent command in AoI code because scripts do not have to be compiled and are easier to maintain web design.

Startup Scripts
Startup scripts are generally utility scripts that are executed upon startup. There are not many of these (in fact none are available through the Scripts and Plugins Manager at this time).

Types of Plugins

Plugins are installed in the Plugins subfolder of Art of Illusion main folder. Plugins contain compiled Java code and can be considered as bits of Art of Illusion code that happen to be in a different place. Plugins can do about anything, so it is difficult to put them in different categories. There are many different kinds of plugins: renderers plugins, tools plugins, translator plugins, generic plugins, etc.

Renderer Plugins
Renderer plugins contain one or several renderers. In fact, the two AoI renderers, the raytracer renderer and the raster renderer, are provided through a plugin that is called Renderers.jar that resides in the Plugins subfolder.

Tool Plugins
Tool plugins are basically like tool scripts: they modify existing objects or create new objects. The principle is the same. Scripts are generally used when the code written to achieve the tool purposes is small. When the code becomes complex and contains several hundreds or more lines, it is best to write a plugin. Like tool scripts, tool plugins commands are triggered through selecting the relevant command in the Tools menu.

Translator Plugins
Translator plugins allow to import/export different file formats into/from AoI.

Texture and Material Plugins
Texture and material plugins allow to bring more procedural modules to AoI procedural editor.

Generic Plugins
Generic plugins can do a lot of different things. In fact, they extend AoI in a seamless way and the user cannot generally tell if the feature is provided by a plugin or exists in core AoI. The scripts and plugin manager, for example, is a generic plugin...

The Scripts and Plugins Manager

...which makes a nice transition to scripts and plugins management. Basically, scripts and plugins are installed by simply placing the relevant .bsh or .jar file in the relevant folder and relaunching AoI if necessary. The Scripts and Plugins Manager, however, helps management of these files. You can browse scripts and plugins available that are not yet installed on your system and get updates for those already installed. Versions of the scripts and plugins installed via the manager are always compatible with the target AoI version. Freshly installed scripts can be tested ‘on the fly’ and uninstalled whithout having to restart AoI. More information on the Scripts and Plugins Manager can be found at http://aoisp.sourceforge.net/spmanagement.html.

Alpha or preview realeases of scripts or plugins are generally made available by their authors and are not available from the scripts and plugins manager until authors consider them to be stable enough.

An AoI Scripts & Plugins Repository has been recently set up on Sourceforge, the goal of which is to gather scripts and plugins sources and informations. For the time being, this page will outline the various scripts and plugins, and include links on how to use them. Please include you information and links to resources below. I am going to begin to outline a number of the scripts below - please correct/add to/adjust these, particularly if you were the developer of the script.


Scripts and Plugins NOT yet in Repository

TroyTools by TroY
Puts a new menu item on the Tools menu, allowing for some options settings, like:
-automatically maximize the AoI window
-automatically activate Grid and Snap to Grid
-automatically set Ambient Color to black
Download plugin (get Java 1.5 version from forum post attachment): http://www.bryce-board.de/thread.php?threadid=14867.