Messages

AI States and Messages

When an AI state machine is started it is always put into the state GLOBAL, and it will be sent an ENTER message.

The following table describes some of the messages the game engine might send to an AI state machine.

AIs might be passed these messages as a matter of routine, in which case the AI will wait until its next cycle before reacting, or it might be asked to react to the given message immediately.

When an AI reacts to a message it examines the state it is currently in: if the state has an entry for a given message it responds by performing the corresponding list of actions, if it has no corresponding entry the message is discarded and ignored.

ACCEPT_DISTRESS_CALL 
AEGIS_CLOSE_TO_PLANET
AEGIS_IN_DOCKING_RANGE
AEGIS_LEAVING_DOCKING_RANGE
AEGIS_NONE
APPROACH_COORDINATES
APPROACH_START
APPROACH_STATION
ATTACKED
CARGO_SCOOPED
COLLISION
CONDITION_GREEN 
   Lowest alert status of station entity, next level: Condition_Yellow.
CONDITION_YELLOW
   Second level of station entity alert status, next level: Red_Alert.
COURSE_OK
DEPLOYING_ESCORTS
DESIRED_RANGE_ACHIEVED
DOCKED
DOCKING_ABORTED
DOCKING_COMPLETE
DOCKING_REFUSED
DOCKING_REQUESTED
ECM
ENERGY_FULL
ENERGY_LOW
ENTER  
   Always sent to the new (now current) state of the AI state machine after switching to a new state.
   See State machine - "Program flow" for more detail
ENTERED_WITCHSPACE
ESCORTING
EXIT
   Always sent to the current state of the AI state machine before switching to a new state.
   See State machine - "Program flow" for more detail
EXITED_WITCHSPACE
FACING_DESTINATION
FIGHTING
FLEEING
FRUSTRATED
GONE_BEYOND_RANGE
GROUP_ATTACK_TARGET
HOLD_FULL
HOLD_POSITION
INCOMING_MISSILE
LANDED_ON_PLANET
LAUNCHED
MOTHER_LOST
   sent if an escorting ship, or a group of ships, loses its Leader.
NO_STATION_FOUND
NO_TARGET
NOT_ESCORTING
NOTHING_FOUND
ODDS_BAD   }
ODDS_GOOD  }    Odds determined by CheckGroupOdds method (see NOTES below)
ODDS_LEVEL }
REACHED_SAFETY
   Sent when the ship controlled by the AI is fleeing its primary_target and is at least desired_range kms from it. 
RED_ALERT
   Entity attacked.
RESTARTED
   Sent when an AI state machine is made the current AI state machine by becoming the top of the AI state machine stack for a particular entity.
STATION_FOUND
TARGET_CLEAN
TARGET_DESTROYED
TARGET_FOUND
   Sent when searching for a target and something suitable is found. 
   The found_target can be made the primary target by calling setTargetToFoundTarget in response to this message.
TARGET_FUGITIVE
TARGET_LOST
TARGET_MARKED
TARGET_MINOR_OFFENDER
TARGET_OFFENDER
THARGOID_DESTROYED
TRY_AGAIN_LATER
UPDATE
   This message is sent to the current state each time the AI gets a chance to "think".
   See State machine - "Program flow" for more detail
WAIT_FOR_SUN
   See OXP howto AI - "setSunSkimStartCoordinates" (under Navigation) for more detail
WAYPOINT_SET
YELLOW_ALERT
   Hostile craft in scanner range.

Notes

Meta-Messages

ENTER Always sent to the new (now current) state of the AI state machine after switching to a new state.

EXIT Always sent to the current state of the AI state machine before switching to a new state.

UPDATE This message is sent to the current state each time the AI gets a chance to "think".

See State machine - "Program flow" for more detail

Alerts & Conditions

CONDITION_GREEN Lowest alert status of station entity, next level: Condition_Yellow

CONDITION_YELLOW Second level of station entity alert status, next level: Red_Alert

RED_ALERT Entity attacked

YELLOW_ALERT Hostile craft in scanner range

Odds

ODDS_BAD

ODDS_GOOD

ODDS_LEVEL

Odds are determined by the CheckGroupOdds method. This seems to appear nowhere in this wiki but will be found in the ShipEntityAI.m file in the Vanilla game code as follows:

- (void) checkGroupOddsVersusTarget
{
	NSUInteger ownGroupCount = [[self group] count] + (ranrot_rand() & 3);				// add a random fudge factor
	NSUInteger targetGroupCount = [[[self primaryTarget] group] count] + (ranrot_rand() & 3);	// add a random fudge factor
	
	if (ownGroupCount == targetGroupCount)
	{
		[shipAI message:@"ODDS_LEVEL"];
	}
	else if (ownGroupCount > targetGroupCount)
	{
		[shipAI message:@"ODDS_GOOD"];
	}
	else
	{
		[shipAI message:@"ODDS_BAD"];
	}
}

Note that Svengali's Cabal Common Library OXP contains a js.script for this too (which may also be lurking inside his Library OXP).

Vanilla Game Code

See the ShipEntityAI.m file for more detail on the above (Folders: Oolite > src > Core > Entities)

Links

• OXP howto AI (.plist AI's)
• State machine (.plist AI's)
• Methods
• AI (.plist AI's)
• AI methods (.plist AI's)

Javascript AIs

• Oolite Javascript Reference: PriorityAI Documentation
• Oolite PriorityAI Tutorial (Javascript AI's)