# Tux_AQFH : The SLAM Animation Language.

by Steve Baker

# Introduction.

SLAM stands for Simple Language for Animating Models.

When you want a creature to move around in the world of Tux_AQFH, or perhaps construct a moving platform or a complicated trap, it's painful to have to add that code into the main Tux software.

Hence, there is a VERY simple interpretive language embedded in the game. SLAM programs look a lot like very simple C programs that run in parallel on 'virtual machines' - one per object being animated.

SLAM programs are compiled into a simple machine code for the SLAM virtual machine - which runs fairly efficiently. Please don't suggest I use PERL or PYTHON any of those other interpetive languages, they are all far slower than SLAM and/or don't offer the features I need.

## Attaching SLAM Programs to Models

You can attach a SLAM program to a model by adding the following comment the node that you wish to have animated.

        @slamdcs "<filename.slam>" <arg0> <arg1> <arg2> ...

Arguments are passed to the SLAM program via the 'getarg' command (see below) and they must be simple floating point numbers.

## Statements

The only statements in SLAM are:

        pause ;

        while ( <condition> )
          <statement> ;

        if ( <condition> )
          <statement> ;

        if ( <condition> )
          <statement> ;
        else
          <statement> ;

        <variable> = <expression> ;

        <function> ( <expression_list> ) ;

        { <statement_list> }

There are no functions (except builtin ones), no 'for' or 'do-while' loops, no 'switch/case', no 'goto' and no comments. There are no '#' directives and no strings. Also no 'return' statement.

All of the statements that ARE implemented work just like they would in C - except for the special 'pause' statement - which is described below.

## Expressions

Expressions follow the usual C rules, although only the following operators are supported:

       +, -, *, /, (), <, >, <=, >=, ==, !=

Notice that the relational expressions return 1.0 for TRUE and 0.0 for FALSE. Operator precedence is as in C.

## Constants

Constants are always treated as 'float' and are accepted in any form that the C++ 'atof' function can accept.

## Variables

You can have up to 16 variables per program - but you can pick any variable name. Variables are all of type 'float' but you do not declare variables. There are no arrays or structures.

## Running

Each frame of animation, the interpreter will run the SLAM program until it hits a 'pause' statement, at which point the program will freeze until next frame and then continue running until the next 'pause'.

Be careful not to get your SLAM programs stuck in infinite loops because the game WILL continue running the program until it either ends or hits a 'pause'.

## Builtin Functions

The list of builtin functions (provided by the Tux game) is likely to change over time - here is the current list:

### Math functions: sin, cos, tan, atan2, sqrt

Same as in C except that all angles are in degrees.

### I/O functions: print

Prints a list of float's to stdout (presumably for debug).

    eg
         print ( a, b, 1234.567 ) ;

### Motion: setpos, settrans

Move the object to which this program is attached.

    eg
        setpos   ( x, y, z ) ;
        settrans ( x, y, z, h, p, r ) ;

Most of the time, you'll want to make one setpos or settrans per frame - usually just before the 'pause' command.

### Command Arguments: getarg

Gets the N'th command line argument.

    eg
        start_position = getarg ( 2 ) ;

Returns the third command line argument (they are numbered from zero).

### SLAM shared memory: getglobal/setglobal

There are 1024 memory locations that are shared between SLAM programs. They are accessed via a pair of function calls:

    eg
        setglobal ( 10, 123.456 ) ;
        x = getglobal ( 10 ) ;

(This would set 'x' equal to 123.456 via global number 10). Notice that you can call a setglobal in one SLAM program and a getglobal in another in order to pass information from one program to another. This could be used to make two monsters coordinate their attacks on Tux.

It is not defined when changes to a global are seen by other programs - but it will never be before the next 'pause' statement. Also, all the setglobal and getglobal calls between a pair of 'pause' statements will always be 'atomic'.

## Example Program.

Place this comment in a model file:

       @slamdcs "slamcode/square.slam" 100

Then place this code into `"slamcode/square.slam"` in the main Tux_AQFH directory:

    x = 0 ; y = 0 ; z = 0 ;

    while ( 1 )
    {
      while ( x <  getarg(0) ) { x = x+0.05 ; setpos (x,y,z) ; pause ; }
      while ( y <  getarg(0) ) { y = y+0.05 ; setpos (x,y,z) ; pause ; }
      while ( x > -getarg(0) ) { x = x-0.05 ; setpos (x,y,z) ; pause ; }
      while ( y > -getarg(0) ) { y = y-0.05 ; setpos (x,y,z) ; pause ; }
    }

This will make the model move around in a square pattern 100 units across at a speed of 0.05 units per 30th second.

## When SLAM programs get too complex.

Most SLAM programs are quite long but execute very little code each frame. If your SLAM code starts to get too complex, it may be time to rewrite the guts of the code in C++ and making a new builtin function that can be called in a much simpler SLAM program.

To do this, you'll have to add your function to the table in src/hooks.cxx :

      SLAM_Extension extensions[] =
      {
         ...

         { "my_function", 3, my_function },

         ...
      } ;

The first item in the entry is the name the function will have in SLAM programs, the second is the number of parameters it should have and the final entry is the address of the C++ function that implements it.

In this case, SLAM programs will call your function as:

       result = my_function ( a, b, c ) ;

or simply:

       my_function ( a, b, c ) ;

...but C++ code for 'my_function' will look like this:

       float my_function ( int argc, float *argv )
       {
         float a = argv [ 0 ] ;
         float b = argv [ 1 ] ;
         float c = argv [ 2 ] ;
          ...
         return result ;
       }

If the number of arguments in the SLAM_Extension array is -1 then SLAM will not check the number of arguments and your own code can accept an arbitary number of arguments.

All builtins return a result - which the SLAM program is at liberty to ignore or incorporate into an expression.