= AI =

== Overview ==
Current AI is implemented in the hierarchy of classes FormationController, ArtificialController, AIController, WaypointController and WaypointPatrolController.

New set of classes are being created in this: ticket:263.

The basic features of new AI are:
 * Fighting: AI tries to dodge bullets
 * Flying: AI flies in divisions of 4 spaceships
 * Actionpoints: Just like waypoints, actionpoints can be set in XML file.

== Structure ==
When alone, every AI class does the same. To make AI fight smart, different AI Controllers are to be assigned to several spaceships:

DivisionController makes 4 spaceships fly in formation. It manages most of the logics of the division, which consists of 1 DivisionController, 1 SectionController and 2 Wingmen. 

Hierarchy looks in a following way:
CommonController -> FlyingController -> FightingController -> ActionpointController,
ActionpointController -> DivisionController, SectionController, WingmanController.
 * CommonController stores all the basic functions being used
 * FlyingController handles flying functionality
 * FightingController handles fighting functionality
 * ActionpointController makes decisions if this is DivisionController
 * DivisionController executes ActionpointController::action() each 1 second
 * SectionController follows DivisionController and, when fighting, tries to find itself a good enemy to shoot at
 * WingmanController follows its leader (either DivisionController or SectionController) and, when fighting, attacks the same target.

Because the actionpoints are set to DivisionController, when it dies, it gives the actionpoints either to SectionController of the division (if exists) or to its Wingman.

== Fighting ==
When fighting, DivisionController fights in pair with its WingmanController and SectionController in pair with its Wingman. Those two sections of two ships try to attack different targets in order to achieve maximum damage output. 

Wingan and Leader try to become attacker and defender, so that enemies waste their time trying to kill one while another finishes them off.

== Formations ==
In XML file different formation types can be set to DivisionController: WALL, FINGER4 and DIAMOND. Although they don't have a great effect on a gameplay, one might find DIAMOND or FINGER4 to look nicer than a simple WALL.

== Actionpoints ==
Actionpoints are implemented as state machines in their own class called ActionpointController, which is a parent class of Division-, Section-, and WingmanController. Basic states are:
 * NONE: spaceship tries to pop the next actionpoint from the stack
 * FIGHTALL: spaceship fights all the enemies on the map (if DivisionController, its division fights together with it) until all the enemies are dead.
 * ATTACK: attacks a specific target until target is dead.
 * PROTECT: follows a specific target until no protection required (when that spaceship dies).
 * FLY: flies to a specific point. Whenever enemy is close, AI attacks it, then returns back to current action.
More than one Actionpoint can be attached to a controller, resulting in a slightly complex behaviour, for example, following code would result in a spaceship firstly flying towards (0,0,0), then attacking a spaceship with a name "attack", then trying to protect a human player, if none is spawned or human dies, it protects a spaceship with a name "protect", then it fights all enemies on the map:
{{{
<SpaceShip position="-2000, 1500, -1000" lookat="0,0,0" team=0 name="ss2">
  <templates>
    <Template link=spaceshipassff />
  </templates>
  <controller>
    <DivisionController team=0 formationMode="finger4">
      <actionpoints>
        <Actionpoint position="0,0,0" action="FLY" /> 
        <Actionpoint position="0,0,0" action="ATTACK" attack="attack" />
        <Actionpoint position="0,0,0" action="PROTECt" protectMe=true />
        <Actionpoint position="0,0,0" action="PROTECt" protect="protect" /> 
        <Actionpoint position="0,0,0" action="FIGHTALL" />
      </actionpoints>
    </DivisionController>
  </controller>
</SpaceShip>
}}}

== Efficiency ==
Because there is a fixed number of spaceships in a division, it is possible to spread out CPU-heavy tasks. As of today, division has a total tact period of 2 seconds, 0.25 sec of which is assigned to each ship of the division. During those 0.25 sec the most heavy methods are being executed. Also, independently of the 2 seconds-long tact, each 0.25 seconds fighting logic is being called, which results in a smooth, and yet fast decision making.