10
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. While they are all written in the same basic way, certain aspects are only al-lowed 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,
- Parametric Shape plug-ins,
- General Object construction, editing and rendering in the Object editor,
- Controller expressions in a Scene.
There are other 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.
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.
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→Configure 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.
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 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.
Parametric plug-in scripts allow you to add new basic modeling shapes to the Object editor. They are similar to the built-in spheres and cylinders in that you define their shape by a few numeric values. Anim8or executes a parametric mesh's script with updated values each time that it needs to update the geometry.
It's important to understand that when you save an .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.
Plug-in scripts that export objects appear in the Object→Export command's "Save as type:" drop-down menu along with the built-in exporters. They are indicated by the addition of ":plug-in" after the description.
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 .as8 extensions from the scripts directory will be listed in the menu. You can run other scripts from anywhere on your computer with the Scripts→Run-Script-File command.
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.
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.
Script writing is simply writing a program in the Anim8or Scripting Language, ASL. 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 Manual.
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
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 begin with a letter or an underscore "_" which can be followed by letters, underscores and digits. Examples are:
scale cos AddPoint face2 KEY_FRAME _exit
User variables begin with a $ character followed by a C name:
$counter $NewIndex $face2 $_selected_index
Variable declarationas are like those in C. Variables can be single values or arrays. Unlike C, you cannot initialize a variable in a definition however.
float $size, $width;
int $i, $counter;
shape $mySHape;
int $index[10]; /* array initially of 10 ints. */
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.
ASL supports many of the operators found in C.
ASL has a number of built in member and non-member functions. These are described elsewhere in this document. User functions must be defined before they are called and recursion is not supported.
-
negation: int, float, point2, point3, quaternion
!
not: int, float
~ bitwise not: int
++ -- prefix increment, decrement:
int, float; note: returns l-value
+ addition: int, float, point2, point3, quaternion
- subtraction: int, float, point2, point3, quaternion
+ concatenation: string
* multiplication: int, float, point2/3*float, float*point2/3,
quaternion*float, float*quaternion
/ division: int, float
% mod: int
<< >> shift: int
< == <= comparisons: int, float, string
> != >= returns int with a value of 1 or 0
&& logical AND: int, float, returns int 1 if both operands are non-zero
|| logical OR: int, float, returns int 1 if either operand is non-zero
Scripts support several kinds of run time statements. Many are similar to C but not all. Statements can be nested to any depth. There is no 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 computed 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 an else and one without one. 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 as long as the value of the expression is non-zero:
while ( <expression> )
<statement>
A for statement executes its sub-statement multiple times. For statements are not like those in C. In a script the increment 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.
User defined functions are similar to those in C, with two main exceptions. Functions must return a value, and recursion is not supported. The syntax of a function is:
<type> <ident> ( <argument-list> )
{
<statements>
return <expression>;
}
You can have multiple return statements. You should have one on all exits from the function or the result will be undefined.
A user attribute is a custom property that you can add to objects, meshes,materials, etc. An attibute associates a name with an int, float, point3, quarternion or string value. For example you can define a float value called mass and set it to 1.5. They are animatable and useful as an auxillary source of data for scripts. The dialog for defining attributes is shown below:
The attribute "mass" is a float with the value of 100. Anim8or doesn't understand these values but you can query and change their value in controller scripts to control how your characters behave with the GetAttributeFloat() and similar functions. See the Anim8or Scripting Language Manual for details.