Animations explained (ASM code)

Applicable
MS Flight
FSXA
FSX
FS2004
FS2002

This article describes how the FS2004 style scenery animations work. But not from the point of view of a design program like GMax or FSDS3, but from the ASM source code point of view. So this article is mainly of interest if you are not afraid of the ASM source code and want to understand the structure behind the animations a bit better.

I want to note that this article describes my current knowledge of the animations. So it could be that certain parts are not really explained correctly yet, as I do not fully understand them. Any comments are welcome of course.

Basic animations

In the first part of this article I will explain how a simple animation can be defined in the source code and what the different commands actually do. I use the source code of a simple animated box as example. This box has an animation that contains of a translation in the first 50 frames and a rotation in the next 50.

Animating your object

After you have defined your object in the source code, it is rather easy to apply a certain animation to it. Below you find the piece of source code that defines my box. To give this object a certain translation or animation all you have to do is to apply a matrix to it using the BGL_SET_MATRIX_INDIRECT command. In the code below you see that three matrices are applied. The first is a static translation that defines the coordinate system to use for the animations. The other two are the translation and the rotation part of the animation itself. And that is all you have to do in the BGL section of the MDL file to create an animation.

test_tutorial_MasterScale_1 label BGLCODE
    BGL_SET_MATRIX_INDIRECT	0
test_tutorial_anim_1 label BGLCODE
    BGL_SET_MATRIX_INDIRECT	1
    BGL_SET_MATRIX_INDIRECT	2
    VAR_BASE_32   VAR_BASE_PARAMS
    MATERIAL 0 ; <134,110,8,255> 
    DRAW_TRI_BEGIN 0, 24
    DRAW_TRI    2,   7,  18 ; poly=1 part=4
    DRAW_TRI   18,  13,   2 ; poly=2 part=4
    DRAW_TRI    5,  16,  21 ; poly=3 part=4
    DRAW_TRI   21,  10,   5 ; poly=4 part=4
    DRAW_TRI    1,  12,  15 ; poly=5 part=4
    DRAW_TRI   15,   4,   1 ; poly=6 part=4
    DRAW_TRI   14,  20,  23 ; poly=7 part=4
    DRAW_TRI   23,  17,  14 ; poly=8 part=4
    DRAW_TRI   19,   8,  11 ; poly=9 part=4
    DRAW_TRI   11,  22,  19 ; poly=10 part=4
    DRAW_TRI    6,   0,   3 ; poly=11 part=4
    DRAW_TRI    3,   9,   6 ; poly=12 part=4
    DRAW_TRI_END
    BGL_RETURN

Matrix relations

In the previous section is sounded really simple, how to make an animation. But of course the scenery engine needs to know a little more than the matrix number to apply. It needs to know the kind of transformation these matrices define and also how the different transformations should act together. This is defined in the SCEN section of the MDL file.

Below you see the code defining the SCEN section of my example file. As you can see it is a sort of table with three entries, one for each matrix.

scene_graph_riff_start_test_tutorial	label	word
    db  'S','C','E','N'   
    dd  scene_graph_riff_end_test_tutorial - $ - 4

    dw 3
bgl_scene_graph_entry_test_tutorial_0	label	byte
BGL_SCENEGRAPH_ENTRY	0, 1, -1, bgl_animation_command_end_test_tutorial_0 - bgl_animation_command_start_test_tutorial_0, bgl_animation_command_start_test_tutorial_0 - bgl_scene_graph_entry_test_tutorial_0
bgl_scene_graph_entry_test_tutorial_1	label	byte
BGL_SCENEGRAPH_ENTRY	1, 2, -1, bgl_animation_command_end_test_tutorial_1 - bgl_animation_command_start_test_tutorial_1, bgl_animation_command_start_test_tutorial_1 - bgl_scene_graph_entry_test_tutorial_1
bgl_scene_graph_entry_test_tutorial_2	label	byte
BGL_SCENEGRAPH_ENTRY	2, -1, -1, bgl_animation_command_end_test_tutorial_2 - bgl_animation_command_start_test_tutorial_2, bgl_animation_command_start_test_tutorial_2 - bgl_scene_graph_entry_test_tutorial_2
scene_graph_riff_end_test_tutorial label word

When you take a look at the BGL_SCENEGRAPH_ENTRY command you see that it has 5 parameters. The last two define which part of the animation command (ANIC) section of the MDL file creates the actual matrices. So that is where the actual transformation that needs to be applied is defined. We will take a look at the ANIC section later on.

The first three parameters define the relation between the different matrices and that is what we will discuss here. The first parameter is the actual matrix number, this is also the number that we called with the BGL_SET_MATRIX_INDIRECT command in the BGL section. The second parameter defines the next child matrix of this matrix, while the third one defines the next peer matrix.

So what do these child and peer relations do? When two matrices have a child relation, this means that if you apply them after each other the resulting transformation is the combination of both of them. When you look at the example code above, you can see that the matrix 1 and matrix 2 have a child relation (these were the translation and rotation matrix), so when you apply them both as we did in the BGL section you object will get both the translation and the rotation.

When two matrices have a peer relation this means that the transformation state is popped back till before the next matrix is applied. So in this case only the last matrix will have an effect on your final transformation of the object.

So in the example animation you can see that the matrix 1 is a child of matrix 0, while matrix 2 is a child again of matrix 1. So when you apply them all three, as happened in the BGL section, the total transformation is the combination of all three matrices.

Creating the transformation matrix

As we saw in the previous section, the SCEN table points to part of the MDL ANIC section. In the ANIC section the animation matrix, that we want to apply, is actually calculated.

For the static transformation the code to calculate this matrix is rather easy, you can see it below. The command points to a table storing the transformation we want and assigns it to the matrix number that we can then call afterwards. The table that stores the transformation will be discussed later.

bgl_animation_command_start_test_tutorial_0	label	BGLCODE
     BGL_TRANSFORM_INDIRECT  0, 0
 bgl_animation_command_end_test_tutorial_0	label	BGLCODE

For the animations matrices the code to calculate them is a bit more complex. The basic idea is that we have a timer that increases its value each 1/18th of a second (thus at 18Hz) and we want to use that to drive the animation. So our first task is to generate a frame number from this running timer.

Below you see the first piece of the code that does this. The BGL_INTERPOLATE command is used to interpolate a given table based on another value. So in the code below we use the table at the location test_tutorial_1_tick18_mod_1 to interpolate the value of BGL_TICK18 and we store the result in the variable usrvar. How this table actually works will be discussed later on, for now it is enough to remember that we use it to split the running timer into smaller pieces. So that we can get a frame number that is running in the range we want (0 to 100 frames in this example).

bgl_animation_command_start_test_tutorial_1	label	BGLCODE
    LOCAL_BASE_32 test_tutorial_1_tick18_mod_1
    BGL_INTERPOLATE VAR_BASE_GLOBAL,BGL_TICK18,\
                    VAR_BASE_GLOBAL,usrvar,\
                    VAR_BASE_LOCAL,(offset test_tutorial_1_tick18_mod_1 - offset test_tutorial_1_tick18_mod_1)

The next part of the code performs a similar task, but this time we read the result of the previous interpolation and interpolate this again. When we discuss the tables used to do this, it will become clear why splitting this in two pieces is easier.

    LOCAL_BASE_32 test_tutorial_1_tick18_mod_2
    BGL_INTERPOLATE VAR_BASE_GLOBAL,usrvar,\
                    VAR_BASE_GLOBAL,usrvar,\
                    VAR_BASE_LOCAL,(offset test_tutorial_1_tick18_mod_2 - offset test_tutorial_1_tick18_mod_2)

The third and last interpolation then converts the output of the previous interpolation, which was an integer number, into a float. This is because the actual animation command that we use next requires a float.

    LOCAL_BASE_32 test_tutorial_1_float_convert_hi
    BGL_INTERPOLATE VAR_BASE_GLOBAL,usrvar,\
                    VAR_BASE_GLOBAL,usrvr3,\
                    VAR_BASE_LOCAL,(offset test_tutorial_1_float_convert_hi - test_tutorial_1_float_convert_hi)
    VAR_BASE_32   VAR_BASE_GLOBAL
    SETWRD usrvr2,0

The final piece of code than does the actual calculation of the matrix we want to use for our animation. The floating frame number we calculated before is the input, together with the table that defines the animation we want. This table is discussed in the next section in more detail. The three parameters at the end, that are set to 0.0 in this example seem to define an offset for the animation result. The last parameter is the matrix number that we use to call this animation.

    LOCAL_BASE_32 test_tutorial_trans_1
    BGL_ANIMATE_INDIRECT   VAR_BASE_GLOBAL,usrvr2,VAR_BASE_LOCAL,(offset test_tutorial_trans_1 - offset test_tutorial_trans_1),0.0,0.0,0.0,1
 bgl_animation_command_end_test_tutorial_1	label	BGLCODE

Storing the animation data

We have now seen how the transformation matrices are calculated and how their relations are defined. But we have not yet seen in which format their data is stored. That will be discussed in this section.

We will start the static transformation matrices. These are stored in the TRAN section of the MDL file. Below you see the lines of code that define such a matrix. There are no opcodes in this section, just a serie of 16 floating values that define one matrix. If you find 32 values, you know there must be two matrices defined.

; Static matrix parameters for transform: 0
    real4      1.000000,     0.000000,     0.000000,     0.000000  
    real4      0.000000,     0.000000,     1.000000,     0.000000  
    real4      0.000000,    -1.000000,     0.000000,     0.000000  
    real4      0.000000,     0.000000,     0.000000,     1.000000

What do these 16 values define? The upper 3x3 matrix defines the rotation of the coordinate system and the bottom 1x3 matrix is the translation. If you want a more mathematical explanation, including some nice sine and cosine formulas on how to calculate the rotation part, have a look at this article from the DirectX SDK.

When we look at the source code given above, you can see that a XZY coordinate system is changed into a XYZ coordinate system with this matrix. And also the positive direction of the Z-axis is changed.

test_tutorial_1_tick18_mod_1 label word
    dw  82
    dw -32768,0,-31154,1615
    dw -31152,0,-29538,1615
    dw -29536,0,-27922,1615
    dw -27920,0,-26306,1615
    dw -26304,0,-24690,1615
    dw -24688,0,-23074,1615
    dw -23072,0,-21458,1615
    dw -21456,0,-19842,1615
    dw -19840,0,-18226,1615
    dw -18224,0,-16610,1615
    dw -16608,0,-14994,1615
    dw -14992,0,-13378,1615
    dw -13376,0,-11762,1615
    dw -11760,0,-10146,1615
    dw -10144,0,-8530,1615
    dw -8528,0,-6914,1615
    dw -6912,0,-5298,1615
    dw -5296,0,-3682,1615
    dw -3680,0,-2066,1615
    dw -2064,0,-450,1615
    dw -448,0,1166,1615
    dw 1168,0,2782,1615
    dw 2784,0,4398,1615
    dw 4400,0,6014,1615
    dw 6016,0,7630,1615
    dw 7632,0,9246,1615
    dw 9248,0,10862,1615
    dw 10864,0,12478,1615
    dw 12480,0,14094,1615
    dw 14096,0,15710,1615
    dw 15712,0,17326,1615
    dw 17328,0,18942,1615
    dw 18944,0,20558,1615
    dw 20560,0,22174,1615
    dw 22176,0,23790,1615
    dw 23792,0,25406,1615
    dw 25408,0,27022,1615
    dw 27024,0,28638,1615
    dw 28640,0,30254,1615
    dw 30256,0,31870,1615
    dw 31872,0,32767,896

test_tutorial_1_tick18_mod_2 label word
    dw  32
    dw 0,0,100,100
    dw 101,0,201,100
    dw 202,0,302,100
    dw 303,0,403,100
    dw 404,0,504,100
    dw 505,0,605,100
    dw 606,0,706,100
    dw 707,0,807,100
    dw 808,0,908,100
    dw 909,0,1009,100
    dw 1010,0,1110,100
    dw 1111,0,1211,100
    dw 1212,0,1312,100
    dw 1313,0,1413,100
    dw 1414,0,1514,100
    dw 1515,0,1615,100

test_tutorial_1_float_convert_hi  label word
    dw  12               ; num entries
    dw  0,0
    dw  1,16256
    dw  2,16384
    dw  4,16512
    dw  8,16640
    dw  16,16768
    dw  32,16896
    dw  64,17024
    dw  128,17152
    dw  256,17280
    dw  512,17408
    dw  1024,17536

test_tutorial_trans_1       label word
    dw           1       ; 1: Point (translation) 
    real4     -1.0       ; Previous panim value
    real4 16 dup (0.0)   ; Cached matrix 
    dw           3       ; number of entries
    real4      0.0,  0.000000,  0.000000,  0.000000 ; frame/x/y/z values
    real4     50.0, 20.000000,  0.000000,  0.000000 ; frame/x/y/z values
    real4    100.0, 20.000000,  0.000000,  0.000000 ; frame/x/y/z values

test_tutorial_quat_1        label word
    dw           3       ; 3: Quaternion (rotation) 
    real4     -1.0       ; Previous panim value
    real4 16 dup (0.0)   ; Cached matrix 
    dw          27       ; number of entries
    real4      0.0,  0.000000,  0.000000,  0.000000,  1.000000 ; frame/x/y/z/w values
    real4     51.0,  0.000000,  0.000000, -0.015707,  0.999877 ; frame/x/y/z/w values
    real4     53.0,  0.000000,  0.000000, -0.047106,  0.998890 ; frame/x/y/z/w values
    real4     55.0,  0.000000,  0.000000, -0.078459,  0.996917 ; frame/x/y/z/w values
    real4     57.0,  0.000000,  0.000000, -0.109734,  0.993961 ; frame/x/y/z/w values
    real4     59.0,  0.000000,  0.000000, -0.140901,  0.990024 ; frame/x/y/z/w values
    real4     61.0,  0.000000,  0.000000, -0.171929,  0.985109 ; frame/x/y/z/w values
    real4     63.0,  0.000000,  0.000000, -0.202787,  0.979223 ; frame/x/y/z/w values
    real4     65.0,  0.000000,  0.000000, -0.233445,  0.972370 ; frame/x/y/z/w values
    real4     67.0,  0.000000,  0.000000, -0.263873,  0.964557 ; frame/x/y/z/w values
    real4     69.0,  0.000000,  0.000000, -0.294040,  0.955793 ; frame/x/y/z/w values
    real4     71.0,  0.000000,  0.000000, -0.323917,  0.946085 ; frame/x/y/z/w values
    real4     73.0,  0.000000,  0.000000, -0.353475,  0.935444 ; frame/x/y/z/w values
    real4     75.0,  0.000000,  0.000000, -0.382683,  0.923880 ; frame/x/y/z/w values
    real4     77.0,  0.000000,  0.000000, -0.411514,  0.911403 ; frame/x/y/z/w values
    real4     79.0,  0.000000,  0.000000, -0.439939,  0.898028 ; frame/x/y/z/w values
    real4     81.0,  0.000000,  0.000000, -0.467930,  0.883766 ; frame/x/y/z/w values
    real4     83.0,  0.000000,  0.000000, -0.495459,  0.868631 ; frame/x/y/z/w values
    real4     85.0,  0.000000,  0.000000, -0.522499,  0.852640 ; frame/x/y/z/w values
    real4     87.0,  0.000000,  0.000000, -0.549023,  0.835807 ; frame/x/y/z/w values
    real4     89.0,  0.000000,  0.000000, -0.575005,  0.818150 ; frame/x/y/z/w values
    real4     91.0,  0.000000,  0.000000, -0.600420,  0.799685 ; frame/x/y/z/w values
    real4     93.0,  0.000000,  0.000000, -0.625243,  0.780430 ; frame/x/y/z/w values
    real4     95.0,  0.000000,  0.000000, -0.649448,  0.760406 ; frame/x/y/z/w values
    real4     97.0,  0.000000,  0.000000, -0.673012,  0.739631 ; frame/x/y/z/w values
    real4     99.0,  0.000000,  0.000000, -0.695913,  0.718126 ; frame/x/y/z/w values
    real4    100.0,  0.000000,  0.000000, -0.707107,  0.707107 ; frame/x/y/z/w values