Brain Stacks

Page history last edited by kosai 1 year, 3 months ago

All enemy ships, neutral ships, and monsters have a "Brain Stack" consisting of a set of AI blocks, which is initially set to the Default Brain Stack for that object type. The AI resolves each block from top (first) to bottom (last), so each AI block can supersede the AI blocks above it. The stack can be cleared using the clear_ai command, and AI blocks can be appended to the stack using the add_ai command. For debugging, the current Brain Stack of a ship or monster can be viewed by selecting it on the Science console of the first player ship (usually named Artemis) and hitting F7 on the server a couple of times until the Brain Stack screen is shown.

AI Block	Can be added to	Description
ATTACK	Ships	Move toward and attack a named object (targetName), moving at throttle of value1.
AVOID_BLACK_HOLE	Ships	If a black hole is closer than value1, turn left to avoid it.
AVOID_SIGNAL	Monsters	Avoid a beacon that repels this monster type. Added in v2.7.0. value1 is used, but its meaning is currently unknown.
AVOID_WHALE	Ships	If a whale is closer than value1, turn left to avoid it.
CHASE_AI_SHIP	Ships, Monsters	If an AI ship on a different side is closer than value1 (value2 if the AI ship is in a nebula), turn to attack it.
CHASE_ANGER	Ships, Monsters	If this enemy or fleet is smarting from a recent attack, turn to attack the source.
CHASE_ENEMY	Ships	Obsolete. If an enemy is closer than value1 (value2 if the enemy is in a nebula), turn to attack it. This block was removed long ago (perhaps in v2.1?) even though it is still mentioned in the mission-file-docs.txt file. Use CHASE_AI_SHIP instead.
CHASE_FLEET	Ships	If an enemy fleet is closer than value1, turn to follow it. If this enemy is a fleet leader, the fleet follows. This block is usually used to make an enemy "shadow" another enemy fleet.
CHASE_MONSTER	Monsters	If another monster of type value1 is closer than value2, turn to attack it.
CHASE_NEUTRAL	Ships	Obsolete. If a neutral ship is closer than value1 (value2 if the neutral ship is in a nebula), turn to attack it. This block was removed long ago (perhaps in v2.1?) even though it is still mentioned in the mission-file-docs.txt file. Use CHASE_AI_SHIP instead.
CHASE_OTHER_MONSTERS	Ships	Added in v2.7.0. If a monster other than a whale is closer than value1, turn to attack it. If this enemy is a fleet leader, the fleet follows.
CHASE_PLAYER	Ships, Monsters	If a player ship is closer than value1 (value2 if the player is in a nebula), turn to attack it. If this ship is a fleet leader, the fleet follows.
CHASE_SIGNAL	Monsters	Chase a beacon set to attract this monster type. Added in v2.7.0. value1 is used, but its meaning is currently unknown.
CHASE_STATION	Ships, Monsters	If a station is closer than value1, turn to attack it. If this enemy is a fleet leader, the fleet follows.
CHASE_WHALE	Ships	If a whale is closer than value1, turn to attack it. If this enemy is a fleet leader, the fleet follows.
DEFEND	Ships	Add this block to make a neutral that is "defending" another object attack enemies that get within (value2), as long as the neutral is closer than (value1) to whatever it's defending. This does not affect enemy ships, it is used by friendly ships to determine the radius at which it will attack an enemy if given a command by Comms to defend a target.
DIR_THROTTLE	Ships, Monsters	The script can add this block to force an AI brain to a specific heading (value1) and throttle (value2).
DRAGON_NEST	Monsters	Added in v2.7.0. No arguments are used.
ELITE_AI (v2.3 and earlier)	Ships	If the enemy wants to behave like an elite, using special abilities like cloaking and warping, it needs this block. As of version 2.4, this was renamed to SPCL_AI.
FIGHTER_BINGO	Ships	This block (for fighters only) makes the fighter go back to its carrier when fuel is low.
FOLLOW_COMMS_ORDERS	Ships	Without this block, a neutral will ignore comms.
FOLLOW_LEADER	Ships	In a fleet with a leader, ships with this block will follow the pathfinding information sent to the as a result of the "LEADER_LEADS" AI command being carried out by the leader of the fleet. Pair with "LEADER_LEADS" and "TRY_TO_BECOME_LEADER" AI commands. For all three commands to work together correctly, assign them to every ship within the fleet in this order in the mission script: TRY_TO_BECOME_LEADER LEADER_LEADS FOLLOW_LEADER
FRENZY_ATTACK	Monsters
GO_TO_HOLE	Monsters	This block is used by the Typhon. value1 is probably the number of enemy ships it will eat before returning home. value2, value3, and value4 are used but their meanings are unknown.
GUARD_STATION	Ships	Usually placed early in the brain stack, this block orders the ship back to the nearest station of the same side. If the station is destroyed, the ship will find the next station to go guard. value1 is used, but its meaning is unknown.
LAUNCH_FIGHTERS	Ships	This block (for carriers only) launches all fighters that are refueled when a player ship is closer than (value1).
LEADER_LEADS	Ships	A ship with this block, that successfully becomes the leader of a fleet after the "TRY_TO_BECOME_LEADER" AI command has run, will send their current pathfinding information to the rest of the ships within their fleet. Pair with "TRY_TO_BECOME_LEADER" and "FOLLOW_LEADER" AI commands. For all three commands to work together correctly, assign them to every ship within the fleet in this order in the mission script: TRY_TO_BECOME_LEADER LEADER_LEADS FOLLOW_LEADER
MOVE_WITH_GROUP	Monsters	Applicable to monsters with a pod number (whales and piranhas), this block has 4 arguments (value1, value2, value3, and value4). value1 is the throttle value. value2, value3 and value4 are unknown, and appear to always be 0 in normal scenarios. This block should normally be the first block in the brain stack.
PLAY_IN_ASTEROIDS	Monsters	Added in v2.7.0. No arguments are used.
POINT_THROTTLE	Ships, Monsters	The script can add this block to force an AI brain to a specific location (value1=x, value2=y, value3=z) and throttle(value4).
PROCEED_TO_EXIT	Ships	All neutrals start out with a position (off the map) that they are trying to go to. This block guides them there.
RANDOM_PATROL	Monsters	Added in v2.7.0. value1 is used, but its meaning is currently unknown.
RELEASE_PIRANHAS	Monsters	Applicable to wrecks. value1=side(piranhas will not be created when a player of this side is too close), value2=dist(player ships gets this close, piranhas are created), value3=num of piranhas spawned, value4=pod number of this monster group (0-9). The F7 brain stack display on the server will only show the value2 number, not the other attributes.
SPCL_AI	Ships	If the enemy wants to behave like an elite, using special abilities like cloaking and warping, it needs this block. In versions 2.3 and earlier, this was called ELITE_AI.
STAY_CLOSE	Monsters	Applicable to monsters with a pod number (whales and piranhas), this block has 4 arguments (value1, value2, value3, and value4). value1 seems to be the maximum distance to stay apart. value 2 is the throttle value. value3 and value4 are unknown, and appear to always be 0 in normal scenarios. This block should normally be the last block in the brain stack.
TARGET_THROTTLE	Ships, Monsters	The script can add this block to force an AI brain to move towards a specific unit (targetName) and throttle(value1). value1=throttle, value2=0 means fire on, ~0 means move towards but don't target
TRY_TO_BECOME_LEADER	Ships	With this block, ships in the fleet with test against one-another to become the leader of that fleet. When the test is complete, one ship will be designated as the leader. Pair with "LEADER_LEADS" and "FOLLOW_LEADER" AI commands. For all three commands to work together correctly, assign them to every ship within the fleet in this order in the mission script: TRY_TO_BECOME_LEADER LEADER_LEADS FOLLOW_LEADER