State machine - Revision history

Eric Walch: Updated the statemachine explanation

2010-11-21T11:48:27Z

Updated the statemachine explanation

Eric Walch: /* Default Messages */

2008-02-15T09:38:02Z

‎Default Messages

Eric Walch: /* Examples */

2007-10-28T11:06:21Z

‎Examples

Eric Walch: Added examples

2007-10-28T11:01:55Z

Added examples

Eric Walch: The state machin, NEW

2007-10-27T11:55:38Z

The state machin, NEW

Winston at 13:24, 12 July 2006

2006-07-12T13:24:02Z

Arexack: /* Related links */

2006-01-23T20:56:34Z

‎Related links

Arexack: /* Links */

2006-01-23T20:56:06Z

‎Links

Arexack: /* Links */

2006-01-23T20:55:38Z

‎Links

Arexack: /* Links */

2006-01-23T20:34:30Z

‎Links

@@ Line 5: / Line 5: @@
 ==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.
 ==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.
+Some commands return messages to the state machine like "TARGET_FOUND" or TARGET_LOST. These messages are put on a list with a maximum size of 32 entries and duplicate messages are ignored. Whenever an update is executed, the messages in this list 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.
+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. When using the JS system, these priority messages are generated with the command "''reactToAIMessage()''".
 ==Examples==
 Best thing to understand how it works is to look at an unusual example with three states that only shows some messages:
     WAIT_FOR_SHOT = {
         ATTACKED = ("setStateTo: WARN_PLAYER", "setStateTo: IDLE");
-    UPDATE = ();
+     };
     WARN_PLAYER = {
         ENTER = ("commsMessage: Help, don't shoot");
-        EXIT = ();
+     };
     IDLE = {
         ENTER = ("pauseAI: 10");

@@ Line 8: / Line 8: @@
 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.
+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 existing update time is replaced by the new 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.

@@ Line 39: / Line 39: @@
     };
-In the first state waits only for the message "ATTACKED". If it receives it, it executes the first command: "setStateTo: WARN_PLAYER". For this it sets the pointers to the second state and executes its ENTER message, the commsMessage: "Help, don't shoot".
+The first state waits only for the message "ATTACKED". If it receives it, it executes the first command: "setStateTo: WARN_PLAYER". For this it sets the pointers to the second state and executes its ENTER message, the commsMessage: "Help, don't shoot".
 But the original commandline is not finished and so the second command is executed: "setStateTo: IDLE". Now the pointers are set to the third state and his ENTER message is executed. But this one only sets the next update time with a pause of 10 seconds. Now all commands are finished and control is given back to the game. On the next update time the statemachine is set to the third state and that UPDATE message is executed every 10 seconds. When is receives an attack in this state it executes his EXIT commands and returns to the first state.
-Of course this is a nonsense script but clearly shows how the machine jumps from state to state. It always finishes all pending messages in the original state, even when there are "setStateTo:" commands inside. Then there are more jumps in one line, or more messages were set with a jump command, all the enter messages are executed, but it ends in the last state.
+Of course this is a nonsense script but clearly shows how the machine jumps from state to state. It always finishes all pending messages in the original state, even when there are "setStateTo:" commands inside. When there are more jumps in one line, or more messages contain a "setStateTo:" command, all the enter messages are still executed, but it ends in the last defined state.
 The only exeptions are the commands setAITo: or switchAITo:. In this case the whole statemachine is put on hold and a new one is started.

@@ Line 18: / Line 18: @@
 ==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.
 == Related links ==
 * [[OXP_howto_AI]]

@@ Line 1: / Line 1: @@
 The AI system consists of a '[[Stacked AI|stack]]' of state machines (or AI's).
 == Related links ==
 * [[OXP_howto_AI]]
@@ Line 8: / Line 24: @@
 * [[Messages]]
 * [[AI|defaultAIs]]
 [[Category:Oolite]]

@@ Line 6: / Line 6: @@
  [[OXP_howto_AI]]
  [[methods]]
  [[Messages]]
  [[AI|defaultAI's]]

@@ Line 7: / Line 7: @@
  [[methods]]
  [[Oolite]]
 {{Stub}}