11 Scripts

You can extend Anim8or's basic functionality and automate repeated tasks with scripts written in a programming language built into Anim8or. It is designed to make animation easier with features unique to Anim8or's operation.
There are several places that you can use scripts and they are all written in the same basic way. However certain aspects are only allowed for specific kinds of scripts. For example you can't refer to a Figure in the Object Editor, and the time() function is not meaningful outside of a Scene.
Scripts may be used in the following places:
  • Object text file export plug-ins,
  • Parameteric Shape plug-ins,
  • General Object construction, editing and rendering in the Object editor,
  • Controller expressions in a Scene.
There are many more useful places for scripts that will be added in future releases.
This chapter provides an overview of scripts and the basics of using them in Anim8or.  A more detailed language definition is provided in the Anim8or Scripting Language Manual.

Creating a Script
A script is a text file that has either a .txt or .a8s extension. You may use any text editor to create and modify them, or you may create the within Anim8or. Normally a script will have a .txt extension.  If it has a .a8s extension and you place it in the "Scripts" directory set in the File->Configure dialog Anim8or will attempt to preload it when it begins execution. If the script is appropriately defined it will become a plug-in. Alternately it can be added as a command in the appropriate Scripts menu for easy execution when you are modeling or animating.

The Script Directory
You may configure Anim8or to preload scripts from a directory called the scripts directory when it begins execution.  This is where you put any plug-ins that you want to use and common modeling scripts.  You set the directory in the File->Configuration dialog and need to make sure that the Preload Scripts box is checked.

When preload is enabled Anim8or will read any files in this directory that have the extension .a8s and parse them as scripts.  If a file has no errors it will be added to the Anim8or interface.  Parametric shape plug-ins will go in the left hand toolbar.  Object export scripts will be added as additional choices in the Object->Export dialog and Object command scripts will be added to the Scripts menu.  All other files with the .a8s extension will be parsed for correctness but not saved in the computer's memory.  You can run them with the Scripts->Run_Script_File command at any time.

Installing a Script
All you need to do to install a script is to copy it into the scripts directory that you have chosen.  Anim8or will load is when it starts running.  It will also list the scripts read in the command window and any errors that it finds.
You may also store other scripts in this directory for convenient access but not have them preloaded by changing the file extension to .txt.  You can edit and run then from with in Anim8or with the Scripts->Edit_Script_File and Scripts->Run_Script_File commands.  You can also load modeling scripts with the Scripts->Load_Script_File command.  It's not possible to load additional plug-ins while Anim8or is running.

Plug-in Scripts
Plug-in scripts work exactly like commands that are built into Anim8or.  The only difference is that they are written in the Anim8or scripting language and can be added or removed as you wish. 
A plug-in script must be written to perform a specific task.  Early in the script it will have a directive declaring what kind of plug-in it is and other related details.  This is how Anim8or knows where to "plug it in".  Additionally each kind has specific rules that it must follow or it would not work correctly.
It's important to understand that when you save a .an8 project that uses a parametric shape plug-in you will need to have that plug-in installed when to properly view your model at a later time.  You can load and edit a project with a missing shape plug-in but you won't be able to see or alter those shapes during that session.  This is not the case for modeling or export plug-ins.  Once you run of these they will make a change to your project or write an output file just like you used other similar commands.

Running a Modeling Script
A modeling script is simply a script that is not a plug-in.  They contain commands like you would use to build a model or make a material.  When you run a modeling script it will change your project it some way and exit so that you can continue working.  Normally this will happen very fast but it is possible to write a script that will take a long time to complete.  Once you've become familiar with a particular script you will know what to expect from it.
You run modeling scripts from the Scripts menu.  Those with .an8 extensions from the scripts directory will be listed in the menu.  You can run other from anywhere on your computer with the Scripts->Run_Script_File command.

Using Controller Scripts
You can also use scripts instead of key-frame splines in controllers.  To change a particular controller to use them select the "On" button in the Expression area in the key frame dialog.  Anim8or will supply a very simple script to set the value of the controller, normally to 0. You may edit the script with the Edit button.


Script Errors
If Anim8or detects an error while running a script it will print a message to the command window.  If you are able to write scripts this may help you find and fix the problem.  If you are running a plug-in then you should contact the author for a fix.

Writing Scripts
Script writing is simply writing a program in the Anim8or script language.  You can learn to write simple scripts fairly easily, particularly controller expressions.  Complex scripts can require advanced programming skills.  This manual does not explain how to write scripts.  However if you know how to program in C or Java you should have no problem writing scripts.
A simple summary of the major aspects of Anim8or's scripting language is described in the following sections.  The full syntax for scripts is described in "The Anim8or Scripting Language".

Data Types
There are quite a few predefined types in scripts.  You will recognize some of them but many are specific to Anim8or.  Some common types are:
int       - 32 bit signed integer
float     - single precision floating point number
point3    - a vector of 3 floats
object    - an Object
figure    - a Figure
material  - a Material
shape     - a component of an Object such as a Mesh or Sphere

Variables
Scripts use typed variables. You must declare a variable and give it a type before you can use it. Built-in variables and functions use normal C rules for their names. That is they must begin with a letter or an underscore "_" which can be followed by letters, underscores and digits.  Examples are:
scale     cos     AddPoint    face2     FIRST_KEY_FRAME     _exit
User variables begin with a $ character followed by a C name:
$counter     $NewIndex     $face2    $_first_selected_index
Variable declares are like those in C.  Variables can single valus or arrays.  You cannot initialize a variable in a definition however.
float $size, $width;
int $i, $counter;
shape $mySHape;
int $index[10];   /* An array that initially has 10 integers. */
Arrays are much more flexible than those found in most languages. You can change the number of elements they hold in a running script, add and delete elements, and do other operations. There is more about arrays later on in this chapter and in the reference manual.

Expressions
There are quite a few predefined types in scripts.  You will recognize some of them but many are specific to Anim8or.  Some common types are:
int       - 32 bit signed integer
float     - single precision floating point number
point3    - a vector of 3 floats
object    - an Object
figure    - a Figure
material  - a Material
shape     - a component of an Object such as a Mesh or Sphere

Statements
Scripts support several kinds of run time statements. Many are similar to C but not all. Statements can be nested to any depth.  There are no user defined functions or goto.
The basic statement is an assignment.  It is like C's except you cannot cascade multiple assignments in the same statement. The value of the expression is computer and saved in the variable at the left:
<variable> = <expression>;
Compound statements group several statements together into a single statement. When encountered each statement within a compound statement is executed in order. They are useful when you need to use more than one statement as part of a structured statement.
{
    <statement>
    <statement>
    ...
    <statement>
}
An if statement allows you to conditionally execute one or more commands. There are two forms one with and else and one without it. The expression is first evaluated.  If it is not equal to zero then the <then-statement> is executed. If there is an <else-statement> it is skipped. If the value of the expression is zero then the <else-statement> is executed if one is present. The full statement is:
if ( <expression> )
    <then-statement>
else
    <else-statement>
and the form without an <else-statement> is:
if ( <expression> )
    <then-statement>
A while statement repeatedly evaluates an expression and executes a statement until the value of the expression is zero:
while ( <expression> )
    <statement>
A for statement executes it's sub-statement multiple times. For statements are not like those in C. In a script the incriment and limit used with the control variable are computed prior to executing the sub-statement and saved. These values are used each time the body of the for statement has been executed to update the control variable and to test to see if the loop should be executed again. The syntax of a for statement is different from C to help remind you that it does not follow C's rules.  There are two forms.  The one without the <step-expr> uses a step value of 1:
for <variable> = <init-expr> to <limit-expr> step <step-expr> do
    <statement>
for <variable> = <init-expr> to <limit-expr> do
    <statement>
The <variable> must be declared prior to the for statement and must be an int or a float. Initially the <init-expr> is evaluated and assigned to the <variable>. Then the <limit-expr> and <step-expr> are evaluated. If there is no <step-expr> a value of 1 is used. The value of <init-expr> is compared with that of <limit-expr>. If it is greater and the value of <step-expr> is greater than zero, or if it is less than and the value of <step-expr> is negative, or if the value of <step-expr> is zero then the execution of the for statement is complete. Otherwise the <statement> is executed, the saved value of <step-expr> is added to <variable> and they are tested in the same manner to see if the <statement> should be executed again.

This page was last updated on May 30, 2006
 Copyright 2006 R. Steven Glanville