State machine
Contents
The State Machine
The AI system consists of a 'stack' of state machines (or AI's).
The top AI of this stack is the active AI. This state machine has the structure of a plist file. The main level is an array of states. Each of this states is an array of messages.
States
On creation of an entity the system assigns a state machine (= AI) to every entity. It looks in the shipdata.plist file for an entry with name "ai_type". If none is defined it defaults to nullAI.plist. Then it starts the state with name "GLOBAL". From hereon the machine is on its own and in most cases there is an instruction in the GLOBAL state to jump to an state with a more descriptive name.
Default Messages
There are three messages that must always be present in a state. ENTER, UPDATE, EXIT. When the system enters a new state it first looks for a message with name ENTER. Then it will execute all the commands in this state. At the same time the update timer is set to its default value of 0.125 seconds.
After the update time is finished it looks for an entry with the name UPDATE. This one then will be executed. This means that without defined pauses, the update will be executed 8 times every second. Whenever a "pauseAI:" is executed, this time is added to the latest update time. So pause will not postpone the current command line but has only effect on the next update time.
When there is an instruction to go to another state it first executes the state with name EXIT.
Normal Messages
Some commands return messages to the state machine like "TARGET_FOUND" or TARGET_LOST. These messages are put on a stack with a maximum size of 32 entries. Whenever an update is executed, the messages in this stack are compared against message entries in the currently active state. If it finds one, the commands in this message line are executed. Take note that normal messages are only examined after the UPDATE commands are executed and not after execution of the ENTER commands.
To be more precise: After execution of the UPDATE commands, all received message are copied to a new execution list and the current message stack is cleared. Then all the commands that correspond to received messages are executed, and the new messages these commands may generate are not examined until the next update time.
Priority Messages
Some messages can't wait until the next update. Good examples are commands were the entity is removed from the universe like "performWitchspaceExit". When it jumps it returns "WITCHSPACE_OK". When it had to wait till the next update the entity could already be removed from the universe together with its state machine. But when the entity has escorts these must also get a command to follow. For these reason some messages are prioritized and will be executed immediately when there is a corresponding entry.
