

****************************************************
* FAQ
****************************************************

Q: Why is it so small?? Starcraft is about 120 Mb...
A: It dosn't have to store all the rotations of a sprite.
    It can generate them at run time, but it's kinda slow so a cache is welcome.
    There are two cache settings in 'config.ini':

    - Max cache     - the maximum amount of memory used as a cache.
    - Cache timeout - when the cache is full, old sprites (older than this
                      setting) are dumped, so that the new ones can fit.


Q: Can i change the units??
A: You can change everything: name, properties, animation, behaviour...
   So if you dont like the default behaviour - wich is doing nothing - all
   you have to do is modify the script.
   The file 'rules.ini' contains the unit properties:

   Name = Scout                           //unit name
   Supply = -1                            //this is added to the player supply (it can be both + or -)
   Aluminium = 100                        //unit aluminium mass
   Steel = 0                              //steel mass
   Gold = 0                               //gold mass
   Life = 100                             //hitpoints
   Mana = 0                               //mana points - you nead this to cast spells
   Shield = 0                             //shield - armour doesnt affect shield - so if 5 damage bullet does a takes 5 shield points
   Armour = 0                             //0 < armour < 10. The value means what procent of the bullet damage the armour stops
   Speed = 3                              //unit speed
   Agressivity = 0                        //0-if shot, run like hell. 1-shot back. 2-watchdog
   Radar range = 200                      //every ship is equiped with a little radar and this setting controls its range
   Radar type = 0                         //0-normal radar. 1-hi sensitivity radar
   Rot speed = 16                         //how fast the ship rotates
   Weapon = 22mm Bullets                  //the weapon
   Order0 = Stop                          //first order
   Order1 = Hold position
   Order2 = Move
   Order3 = Attack
   Order4 = Patrol
   Build0 = Scout
   Upgrade0 = Life
   Animation = Scout animation            //the animation displayed on screen
   Icon = Scout icon animation            //the anim used as a icon when the ship is selected


   [WEAPON 0]
   Name = 22mm Bullets                    //weapon name
   Bullet type = 0                        //0-BULLET (hits the target instantly). 1-MISSILE (follows the target). 2-FLASH (hits instantly (has no anim)). 3-KAMIKAZE (destroys the unit that launched it (no anim either))
   Damage = 5                             //the amount of damage
   Rate = 400                             //fire rate
   Splash = 0                             //splash area
   Range = 200                            //fire range - the target must be in this range to fire
   Speed = 1                              //bullet speed
   Animation = 22MM animation             //bullet animation


   [ORDER 0]
   Name = Stop                            //order name
   Shortcut = s                           //shortcut
   Icon = Stop icon animation             //icon anim

   [BUILD 0]
   Name = Scout                           //name of the thing being built
   Time = 100                             //how long it takes to build it
   Aluminium = 20                         //cost - be carefull that you can build a 200t unit with only 1t of that metal
   Steel = 20
   Gold = 10
   Shortcut = s
   Icon = Scout icon animation

   [UPGRADE 0]
   Name = Life
   Time = 50
   Aluminium = 20                         //aluminium cost
   Aluminium factor = 0                   //how much to raise the cost for each upgrade level
   Steel = 0
   Steel factor = 0
   Gold = 0
   Gold factor = 0
   Shortcut = s
   Icon = Upgrade life icon animation



****************************************************
* ANIMATIONS
****************************************************

The animation system uses a special language made out of simple commands.
To define a new animation, create a new entry in rules.ini:

                    _________________ this is important, so your name should be something like 'my animation', or 'Scout animation'...
                   |
[ANIMATION NAME ANIMATION]
fSPRITE000 s60 d1               -line 0
fSPRITE001                      -line 1
                                -empty line
fSPRITE002                      -line 2
#comment                        -comment
g0                              -line 3

As you can see, empty lines and comments dont count.
The basic syntax:

abP1,P2,P3,P4...
~~
where:
  ab - the command itself (the highlight part)
  P1.. - arguments (depending on the command). There is no space after the comma

--------------

fN         - displays the sprite named N, from the animd.dat datafile
~
FN1,N2     - displays all sprites from N1 to N2
~
sT         - wait Tms before moving to the next line
~
xN,X       - how the sprite is drawn. If you dont specify a x command, the sprite
~			 will be drawn solid.
             If N==0, translucency will be used
             If N==1, the 'add' effect will be used
             If N==2, the sprite will be drawn using antialiasing (if it is enabled)
             X controls the solidity of drawing

llN,X,Y,S  - Light location N has coords X, Y and sprite S
~~			 This location is used to display lights on top of the sprite.
             Tho position is computed every time using the anim rotation too.
             I use this command to draw flames.

lwN,X,Y,R  - Weapon location N has coords X, Y and rotation R
~~			 This locations are used as the starting location for the bullets.
             Rotation R is added to the bullet rotation (good for missiles)

pN,X,Y     - Adds a particle with definition N at X, Y
~			 Good for smoke and explosions

gX         - Goto line X. Be carefull how you count the lines
~
GX         - Goto section X.
~
dX         - The line increment (step) - it can be negative too.
~
rX         - sprite rotation is X
~
RX         - 1 to disable rotation
~
eX         - define a new section numbered X - its like a label
~
--------------

All the coordonates are relative to the unit position and rotation.
'Sprite' means an image found in 'animd.dat'. Sprites are accessed via their
name, so you shouldn't strip this info from the datafile.
Also, always be sure to have 's' and 'd' on the first line.

In the case of unit, bullet and icon animations, sections have a special meaning

BULLETS and UNITS:
       section 0 - when unit does nothing
       section 1 - for moving
       section 3 - when unit dies

ICONS:
       section 0 - normal icon
       section 1 - double sized icon
       section 2 - normal icon
       section 3 - highlighted icon (when the mouse is on top)


****************************************************
* SCRIPTS
****************************************************

Ok, now for the difficult part.
The scripts are actualy C programs, compiled at run time.
There are several functions that you can call from a script. You can find them
in ai/headers/import.h .

Every unit has it's own script named unitXX.ai, where XX is the unit type.
Every group (there are 12 groups) has a script - groupXX.ai
There is a master script also - brain.ai

Only computer players get to have group and brain scripts.

Unit scripts can have these functions exported:

 - void process(UNIT *unit)
   this one is called for every game cycle

 - void draw(UNIT *unit)
   this is called after the unit is drawn

 - void init(UNIT *unit)
   when the unit is created

 - void shutdown(UNIT *unit)
   when the unit is removed

 - void kill(UNIT *unit)
   when the unit dies

 - void damage(UNIT *unit)
   when the unit is hit


Brain scripts can export this functions:

 - void process(PLAYER *player)
   this one is called at for every game cycle

 - void draw(PLAYER *player)
   this is called after the player (all its units) is drawn


Maps are scripts also.
They can export this functions:

 - void process()
   this one is called for every game cycle - good for scenario processing

 - void draw()
   this is called after the map is drawn

 - void init()
   when the map is created - this should add units, players, buildings - do everything

 - void shutdown()
   when the map is dsstroyed

