Scripts and Plugins Management
Warning: information given here is slightly outdated. However it's still pertinent. We'll try to update this page soon
Art of Illusion is shipped with a plugin called "The Scripts and Plugins Manager". This plugin allows to manage the scripts and plugins installed in Art of Illusion folder. Using this tool, scripts can be installed, updated or removed on the fly, without even relaunching AoI (Objects and Tools scripts, not Startup scripts for obvious reasons !). Plugins modification however requires that AoI is relaunched to work properly.
Scripts/Plugins managed and installed do not need the manager to be used after being installed. The job of the Manager is only to download remote files or delete local files, just as you would do manually. The installed scripts or plugins are just usual files with some extra information.
1. Usage
Launch AoI and select the last item of the Tools menu, named "Scripts & Plugins Manager". The following window appears :
The tabbed pane on the left side shows three tabs. The first one (Manage) allows browsing of currently installed scripts and plugins. The second tab (Update) browses updates available at a remote repository for these installed items. The third tab (Install) allows to browse scripts and plugins available at the same repository but that are not currently installed and are thus candidates for installation. The remote repository scan for scripts and plugins begins only when one of the two last tabs is selected.
The pane at the right side of the window show some information about the currently selected object: name, author, version, etc... The Delete script button as shown on the picture allows deletion of the selected file. Warning : do not delete vital AoI plugins (i.e. Renderers, OSSpecific, Tools and Translators). On some systems (at least Windows), it is not possible at the moment to delete a plugin because it is being used by AoI. The manager then asks you to remove it manually, i.e. delete the specified plugin file from the Plugins directory. Quit and relaunch AoI after deletion.
The buttons shown at the bottom of the pane depend on the tab currently selected. This second picture shows the dialog as it is when the Update tab is selected.
This time there are three buttons and a checkbox at the bottom of the pane. The Selected checkbox allows the selection of a particular script or plugin for update. The Select all button checks all the available items for update and is equivalent to manually checking all the available scripts and plugins. All the checked scripts or plugins show a checkmark over the relevant file icons. The Update this file button immediatly installs the current item, whether it is selected or not. Finally, the Update all selected files button installs all selected files, i.e. the items that have a checked selected checkbox.
The Install tab works exactly the same way as the Update tab.
If scripts have been installed or updated, they are directly available in AoI where they can be used. It is thus possible to install a script that sounds interesting, test it and remove it if it turns up that the script is not that interesting after all.
The Setup button allows to choose the repository used to get remote files, though at the moment the Sourceforge repository is the only source for scripts and plugins. Setup also allows to specify proxy information if you have to use a proxy.
Security Warning: Passwords are saved crypted. However, since the code for password decryption is available in the source code, it is always possible to break the cipher if one wants to. If you do not wish the password to be saved, enter a dummy password in the setup window before quitting the manager. No one can be held responsible for anything that could happen due to this feature.
The Rescan button is for rescanning the current repository for updates and installs.
Finally, there is a status bar at the bottom of the window. This status bar shows which URL is contacted and what kind of information is downloaded. There are two occasions on which the Script and Plugins Manager contacts remote distant sites:when downloading an up-to-date repositories list from Sourceforge, in case the repositories list has changed;when scanning a repository.
2. Limitations
It is expected that the AoI standard directory structure (Plugins, Scripts/Tools, Scripts/Objects, Scripts/Startup) is correctly set 'the manager won't create any missing or misspelled directory).If the system doesn't allow for 'hot' plugin deletion (e.g. Windows), then plugin upgrade presumably works but information shown in the Manage tree afterwards is missing.After deleting a script or plugin, it appears back in the Install tree. In some cases, it can already be selected for install.The Manager doesn't check for writing permissions before downloading a file. A write permission is not allowed, it will silently abort update/install.
3. How does it work?
The manager relies on xml information stored:in the first /* */ commented section of a script, orin an xml file included in the jar archive file of a plugin. For reasons of remote access speed, this xml file is stored separately on the remote repository, along with the jar file of the plugin. This companion xml file is not downloaded at install or update.
Here is a sample of how this information is stored:
/* <?xml version='1.0' standalone='yes' ?>
<script> <name>SPManager</name>
<author>Francois Guillet (fpgui@users.sourceforge.net)</author>
<version>0.1</version>
beta>1</beta>
<date>02/27/2004</date>
<description> The Script and Plugin Manager is a plugin that makes the management of scripts and plugins easy. It scans for updates of installed scripts/plugins and shows all the not-yet-installed items available at repositories.
</description> <comments> Still at beta stage ! </comments> </script> */
All fields are optional. The version number should follow the format MM.mm, where mm is the minor number. It is essential that the minor number does not exceed two digits. A version number of M.n is treated as M.n0, not as M.0n. That means that 1.1 means 1.10 and not 1.01. If the beta tag is specified, the version is considered beta. The beta version number is then the value specified within the beta tag. Beta versions are always superseded by a non beta version having the same version number, e.g. 1.11beta3 is updated by 1.11.
The description tag identifies the text that goes in the description field. A special format allows to have carriage returns (CR) after each line for proper display in a text editor or in AoI when editing Script Objects. Any CR after a line is removed. A sequence of two CRs or one whitespace plus one CR is translated as one CR. A sequence of three CRs, or preferably one space plus two CRs is translated as two CRS. Using this translation, it is possible to have a format that will be both readable in a text editor that does not wrap lines and in the text area of the plugin manager. See the Fur.bsh description field for an example.
The comments section works the same way.
There is a fileset tag that identifies a set of companion files to the script, if any. Each file must be identified within the fileset using the file tag. For example:<fileset> <file>file1.aoi</file> <file>file2.aoi</file>
</fileset>
Using the file tag file outside a fileset definition is not allowed. The file name must be written exactly 'as is' between the begin and end tags. A script can have several fileset definitions, which are treated for the time being as a merged single fileset.
3. Repository Structure
The repository structure is exactly the same as the AoI structure. The Http address, that is http://aoisp.sourceforge.net/AoIRepository/ points on a folder which contains two folders named Plugins and Scripts (beware of the uppercase initials). All the plugins must be put in the Plugins folder. The Scripts folder contains three folders named Objects, Startup and Tools.
A repository holds all the versions of a script or plugin corresponding to the different versions of AoI. Instead of having scripts or plugins files in the usual folders (Plugins, Tools, Startup, Objects), all the versions of script or plugin are contained in a subfolder. For example, the Platonic Solid script is different if the version of AoI is 1.7 or 1.8. The repository structure is then:
Note the text file named PlatonicSolid.txt. Its contents are reproduced below:
1.8 : Platonic_Solid_1.8.bsh
1.7 : Platonic_Solid_1.7.bsh
This file specifies which script file corresponds to a specific AoI version. In this case, the script Platonic_Solid_1.7.bsh is the relevant one for the AoI 1.7 version, and Platonic_Solid_1.8.bsh for the 1.8 version. Once one of these files is selected for install, it is copied in the user's Scripts/Objects folder and renamed Platonic Solid.bsh, after the name that is specified using the name tag of the xml header. The folder containing the different scripts may have any name. The different scripts contained in this folder may be named in whatever way is thought best. The text file, however must be named folder_name.txt. If the folder is named foo, then the text file must be named foo.txt. Use whitespaces in file names at your own risk ! (It's best to avoid them anyway).
Scripts or plugins companion files are stored in the same folder as the scripts or plugins. Different versions can refer to the same companion file(s) using the fileset tag. However, if the companion file(s) needs to be updated for a newer AoI version, it must then have a different name which will be kept at installation.
Whereas the xml info file for plugins is locally contained in the java archive file, it would be very long and tedious to have to download the entire plugin to fetch the xml file from a remote repository. For this reason, this file stands along the java archive file in the repository. It must have the same name, only terminated by a .xml extension. If foo_1.8.jar is the name of a plugin, the the xml info must be contained in the file foo_1.8.xml.
There are three "special" cases which are handled by the manager:No version of a script exists for a previous AoI release;The script has not been updated, but it is still valid and useful for newer AoI versions;The script is no longer available for new versions, whether it is been abandoned, incompatible with new version, its features have been integrated into AoI, or whatever.
The first case is simply indicated by the fact that the previous AoI versions are not stated in the text file. In the Platonic Solid script example, no version is available before 1.7.
To solve the second case configuration, it is considered that a script is valid for any newer version until it is stated otherwise. For example, the following list:
1.8 : Platonic_Solid_1.8.bsh
1.7 : Platonic_Solid_1.7.bsh
1.5 : Platonic_Solid_1.5.bsh
states that no script exists before AoI 1.5, that Platonic_Solid_1.5.bsh is to be used for v1.5 to 1.6, that there is one specific version for v.17, and that Platonic_Solid_1.8.bsh is to be used for any version greater or equal to 1.8.
The script existence is terminated typing a - (minus) character in place of the script name. If the Platonic Solid script isn't available for all versions greater than 2.0, then the above list goes:
2.0 : -
1.8 : Platonic_Solid_1.8.bsh
1.7 : Platonic_Solid_1.7.bsh
1.5 : Platonic_Solid_1.5.bsh