The AIR format and standard
===========================
M.U.G.E.N, Elecbyte (c)1999

Beta-release documentation (incomplete)
Updated 11 Aug 99

I.   The format
II.  Reserved Action Numbers
III. Recommended Action Numbers

I. The format
-------------

Here's a typical entry from an .air file:

; Standing Animation
[Begin Action 000]
Clsn2Default: 2
 Clsn2[0] = -10,  0, 10,-79
 Clsn2[1] =  -4,-92,  6,-79
0,3, 0,0, 7
0,2, 0,0, 7
0,1, 0,0, 7
0,0, 0,0, 50
0,1, 0,0, 7
0,2, 0,0, 7
0,3, 0,0, 7
0,4, 0,0, 60


Semicolon (;) is used for comments.  They can be used anywhere and
everything after the semicolon on the same line is ignored.

[Begin Action nnn]
This defines an action.  You can have many actions, but keep in 
mind that there are reserved actions numbers.  These numbers and 
their associated actions are listed below.

Clsn2Default: 2
This says that there are two collision boxes being defined and they
will be defined for all the entries below the Clsn definition.  In
this case for every sprite in this action.  If you don't want to 
have a default collision box, then change Clsn2Default to Clsn2.
You must put the Clsn definition before a sprite entry.  Each
sprite entry can have its own collision boxes.  Clsn2 refers to a
plain collision box and Clsn1 refers to an "attacking" box.  You 
use attacking boxes when making attacking actions such as punching
and kicking or special moves.

Sprite entries-
0,3, 0,0, 7
1st number is the sprite's group number.  
2nd number is the sprite's image number.
You assign these numbers to your sprites when you make an .sff file.

So group #0 and image #3 were defined with sprmaker with an entry 
such as:
work\mypic.pcx
0   (group number)
3   (image number)
40  X axis
40  Y axis

3rd and 4th numbers are the X and Y offsets from this sprite's axis.
These are usually 0,0.  If you want the sprite to appear 5 pixels
forwards, put "5" for the 3rd number.  To make the sprite 15 pixels
up, put "-15" for the 4th number, and so on.

5th number is the length of time to display the sprite before moving
onto the next, measured in game-ticks.  There are 60 game-ticks in
one second at normal game speed.
For the 5th number, you can specify "-1" if you want that sprite
to be displayed indefinitely, or until you switch to a different
action.  If you choose to do this, do it only on the last sprite
of the action.

We will refer to each of these sprites as an "element".
The "looptime" of an action is the sum of all the times of each
element.  Basically, it is the total length of the action in
game-ticks.  If the last sprite has a time of "-1", the looptime
will be considered infinite.  We call that "no loop".  Actions
with a finite loop time will go back to the first element
after it has finished displaying the last element, and keep
looping until the you switch to another action.

; Standing Animation
[Begin Action 000]
Clsn2Default: 2
 Clsn2[0] = -10,  0, 10,-79
 Clsn2[1] =  -4,-92,  6,-79
0,3, 0,0, 7
0,2, 0,0, 7
Loopstart      ;<---
0,1, 0,0, 7
0,0, 0,0, 50
0,1, 0,0, 7
0,2, 0,0, 7
0,3, 0,0, 7
0,4, 0,0, 60

Adding a line with the word "Loopstart" will make the animation
begin looping from the element on the following line.

When testing out your animations, you may find the pause and
frame-advance functions useful.  To pause, hit the "Pause" button.
To advance the game by one game-tick, press Scroll Lock.  Frame-
advance only works when the game is paused.

Optional paramters
------------------
Here's an entry:
15,1, 0,0, 5

If you want to flip the sprite horizontally and/or vertically, you
will need to use the "flip" parameters: V for vertical flip, and
H for horizontal flip.  These parameters will be 6th on the line.
For example:

15,1, 0,0, 5, H   ;<-- This flips it horizonally
15,2, 0,0, 5, V   ;<-- This flips it vertically
15,3, 0,0, 5, VH  ;<-- This flips it both ways, ie. rotates 180 deg

Flipping the sprite around is especially useful for making throws.
The opponent who is being thrown will temporarily get the player's
animation data, and enter the "being thrown" animation action.
You'll might have to flip the sprites around to make the "thrown"
action look correct.

For certain things such as hit sparks, you might like to use
color addition to draw the sprite, making it look "transparent".
You won't need to use this to make a character, so you don't have
to worry about this if you choose not to.  The parameters for
color addition and subtraction are "A" and "S" respectively, and
should go as the 7th on the line.
For example:

15,4, 0,0, 5, ,A   ;<-- Color addition (flip parameter omitted)
15,4, 0,0, 5, H, S ;<-- Flips horizontally and does color subtraction



====================================================================
II. Reserved Action Numbers
---------------------------

You might want to make these actions first before working on your
own.  

The states that use these are mostly in common.cns. Others are
coded-in.


An "opt" besides the number means the animation is optional


Number    Description                  Comments
-------   ------------                 --------
0         Standing
5   opt   Turning                      Must have finite looptime
10        Stand to crouch              Finite looptime
11        Crouching
12        Crouch to stand              Finite looptime
20        Walking forwards
21        Walking backwards
40        Jump start (on ground)       Shown just before player leaves ground
41        Jump neutral (upwards)       Shown when player is going up
42        Jump forwards (upwards)      Shown when player is going up-towards
43        Jump back (upwards)          Shown when player is going up-back
44  opt   Jump neutral (downwards)     Activated when Y-velocity > -2
45  opt   Jump fwd (downwards)         Same as above
46  opt   Jump back (downwards)        Same as above
47        Jump landing                 Shown as player lands on ground
100       Run fwd/hop forward
105       Hop back
110       Dodge up                     
115       Dodge down
120       Start guarding (stand)       Finite looptime
121       Start guarding (crouch)      Finite looptime
122       Start guarding (air)         Finite looptime
130       Guard (stand)
131       Guard (crouch)
132       Guard (air)
140       Stop guarding (stand)        Finite looptime
141       Stop guarding (crouch)       Finite looptime
142       Stop guarding (air)          Finite looptime
150       Guarding a hit (stand)       Finite looptime
151       Guarding a hit (crouch)      Finite looptime
152       Guarding a hit (air)         No loop
170 opt   Lose                         
175 opt   Time Over
180 opt   Win                          No loop (181-189 for multiple)
190 opt   Intro                        No loop
195 opt   Taunt                        Finite looptime (See Note 1)

5000      Stand/Air Hit high (light)   Looptime around 10-20
5001 opt  Stand/Air Hit high (medium)    "     (See Note 2)
5002 opt  Stand/Air Hit high (hard)      "
5005      Stand Recover high (light)   No loop (See Note 3)
5006 opt  Stand Recover high (medium)    "
5007 opt  Stand Recover high (hard)      "
5010      Stand/Air Hit low (light)    Looptime around 10-20
5011 opt  Stand/Air Hit low (medium)     "
5012 opt  Stand/Air Hit low (hard)       "
5015      Stand Recover low (light)    No loop
5016 opt  Stand Recover low (medium)     "
5017 opt  Stand Recover low (hard)       "
5020      Crouch Hit (light)           Looptime around 10-20
5021 opt  Crouch Hit (medium)            "
5022 opt  Crouch Hit (hard)              "
5025      Crouch Recover (light)       No loop
5026 opt  Crouch Recover (medium)        "
5027 opt  Crouch Recover (hard)          "
5030      Stand/Air Hit back           Looptime around 10-20
5035      Stand/Air Hit transition     Looptime around 5-15 (See Note 3)
5040      Air Recover                  No loop
5050      Air Fall                     No loop
5051 opt  Air Fall (coming down)       No loop
5060 opt  Air going straight up        --- new ---
5061 opt  Coming down from hit up      --- new ---
5070      Tripped
5080      LieDown Hit (stay down)      (See Note 4)
5090      LieDown Hit (hit up into air)
5100      Bounce from ground into air
5105      Hit ground from bounce       Looptime around 3 or 4
5110      LieDown
5120      Get up from LieDown
5150 opt  LieDead (first rounds)
5155 opt  LieDead (final round)
5200      Fall-recovery near ground
5210      Fall-recovery in mid-air
5300      Dizzy
5500 opt  "Continue?" screen           If omitted, plays dizzy anim
5510 opt  "Yes" to "Continue"          If omitted, plays first win anim
5520 opt  "No" to "Continue"

Note 1: Taunts do not actually have to use only this state number.
        It is more of a recommended number than a reserved one. If your
        character has multiple taunts, feel free to use any other state
        numbers.
Note 2: If medium and heavy hits are omitted, they default to the light hits
Note 3: "No loop" means last frame has a time of -1.
        For recover animation, the first frame of each recovery should be the
        last frame of the corresponding hit. Eg. If action 5000 has frame
        5000,0 and 5000,1, then action 5005 should start with frame 5000,1.
        This is because the animation will be locked in the first frame of
        the recovery after the hit animation is over, but before the player
        has recovered from the hit.
        If you have a Stand/Air Hit transition animation, then the first
        frame of Air Recover and Air Fall should be the last frame of the
        transition animation.
Note 3: The Stand/Air Hit transition animation is played back after each
        hit animation in (or into) the air, but before the Air Recover
        and Air Fall animations.
Note 4: You can loop the LieDown Hit if you want the player to look like he
        is "twitching" while being hit


====================================================================
III. Recommended Action Numbers
-------------------------------

You don't have to follow this exactly, but it should serve as a
guideline. In general, the states in the CNS should have the same
numbers as the animation they use, to reduce confusion.

You might want space out your animation and state numbers nicely.
This gives room for you to add in more actions as necessary.
For instance, Stand_a and Stand_b could have action numbers 200
and 210 respectively.


Number    Description
-------   ------------
0-199     - reserved -
          Basic attacks:
200-299   Standing attacks
300-399   More standing attacks, running attacks
400-499   Crouch attacks
500-599   More crouch attacks
600-699   Air attacks
700-799   More air attacks
800-999   Unused - use if you need more states
          Special attacks:
1000-2999 All special attacks
          Hyper (super) attacks:
3000-4999 All hyper attacks
5000-5999 - reserved -

