Right now (1.9 Beta 3) the ship AI is inconsistent in how it decides to attack other ships. Each order has a slightly different rule. This record describes the current AI rules and proposes changes.
New AI Settings
To increase flexibility of the AI, we add a few of new AI settings to control how the ship reacts to threats:
reactToAttack
This setting defines how the ship reacts to being attacked. The following values are supported:
default
: This is the current behavior. The actual response depends on the order. For example, if attacked during theguard
order, the ship will retaliate.chase
: If attacked, we chase the attacker (or order-giver) out tothreatRange
. We check visibility (if we cannot see the attacker, we do not chase). If we're already attacking an enemy ship, we switch to target the attacker only if appropriate.deter
: If attacked, we turn to shoot at the attacker, but do not chase (we stay on our current course). We check visibility and only switch targets if appropriate. We stop deterring as appropriate.deterWithSecondaries
: If attacked, we use our secondary weapons (if any) to attack the attacker, but we do not turn or change course.none
: Do not react to an attack.
reactToThreat
This setting defines how the ship reacts to an enemy ship approaching within threatRange
. We support the same values as reactToAttack
.
threatRange
This is the maximum range (in light-seconds) at which we respond to a threat. The default is 30 light-seconds.
Current Rules by Order
The rules of engagement vary depending on the ship's current order and AI settings. The behavior described here will be followed if the new settings above are set to default
. Below we describe the AI rules by order:
Aim
CStandardShipAI
Maneuver to aim at a target.
- Target specified in order.
- Does not fire secondary weapons.
- Does not respond if attacked.
Approach
CApproachOrder
Approach some destination object.
ImplementAttackNearestTarget
: Attacks nearest, visible enemy ship without maneuvering (unlessnoTargetsOfOpportunity
is set).ImplementFireOnTargetsOfOpportunity
: Fires secondary weapons (if any) to attack visible enemy ships (unlessnoTargetsOfOpportunity
is set). Excludes non-aggressors unless we are aggressors (in AI settings). Includes blacklisted player. Excludes stations. Includes missile defense.- Does not respond if attacked. But escorts (if any) will respond.
Attack
CAttackOrder
Attack a target.
- Target specified in order.
ImplementAttackTarget
: Attacks the target, maneuvering as necessary.ImplementFireOnTargetsOfOpportunity
.- Avoids enemy stations
- Does not respond if attacked.
AttackArea
CAttackOrder
Attacks all ships in range of a given object.
CSpaceObject::GetVisibleEnemies
: Filtered by ships in range of object. Excludes non-aggressors (ships that have not fired weapons recently). Excludes stations.ImplementAttackTarget
: Attacks the target, maneuvering as necessary.ImplementFireOnTargetsOfOpportunity
.- Avoids enemy stations.
- Stays in range of object.
- If attacked, calls
CalcIsBetterTarget
to see if it should switch targets.
AttackHold
CStandardShipAI
Attacks the specified target without moving.
ImplementAttackTarget
: Attacks the target, but does not move (only rotates).ImplementFireOnTargetsOfOpportunity
.- Does not respond if attacked. But escorts (if any) will respond.
AttackNearestTarget
CAttackOrder
Attacks nearest target until there are no more visible enemy ships in range.
- Same as AttackArea but does not restrict to an area.
AttackStation
CAttackStationOrder
Attacks a station target.
- Target specified in order.
ImplementAttackTarget
: Attacks target, maneuvering as necessary.ImplementFireOnTargetsOfOpportunity
.- If attacked, we decide if we should switch to attacking the attacker. This uses
CalcIsBetterTarget
plus additional custom logic.
Bombard
CStandardShipAI
Attacks the specified target without moving.
ImplementAttackTarget
: Attacks the target, but does not move (only rotates).ImplementFireOnTargetsOfOpportunity
.- Does not respond if attacked. But escorts (if any) will respond.
Dock
CNavigateOrder
Navigates to destination and docks.
ImplementAttackNearestTarget
.ImplementFireOnTargetsOfOpportunity
.- If attacked, set current target, but we do not change course or maneuver.
Escort
CEscortOrder
Escorts another ship.
- If non-combatant, then we just follow (no secondary weapons).
ImplementAttackTarget
is we have a target.ImplementAttackNearestTarget
ImplementFireOnTargetsOfOpportunity
.CSpaceObject::GetVisibleEnemyInRange
: We chase visible enemy ships in range (30 light-seconds). UnlessnoAttackOnThreat
is set, or if shields are down.- If attacked, we chase attacker unless we're a non-combatant.
- NOTE: If we go beyond 30 light-seconds we turn back. Technically we should only return if our target has gone beyond 30 light-seconds of the principal.
Follow
CEscortOrder
Escorts another ship, but does not chase enemy ships.
- If non-combatant, then we just follow.
ImplementAttackTarget
is we have a target.ImplementAttackNearestTarget
.ImplementFireOnTargetsOfOpportunity
.
Gate
CNavigateOrder
Navigates to stargate and gates.
- Same as dock order.
GateOnStationDestroyed
CStandardShipAI
Gates out if order target is destroyed.
- Does not respond to attacks.
GateOnThreat
CStandardShipAI
Gates out if station we're docked with is dead or angry.
- If we're attacked, we gate out.
Goto
CNavigateOrder
Navigate to within a certain distance of destination.
- Same as dock order.
GotoPos
CNavigateOrder
Navigate to within 1 light-second of a point.
- Same as dock order.
Guard
CStandardShipAI
Waits at a station and attacks enemies that approach.
- Calls
CSpaceObject::GetVisibleEnemyInRange
to find threats within range (30 light-seconds). - Once a threat it targeted, we call
ImplementAttackTarget
to chase the target andImplementFireOnTargetsOfOpportunity
(for secondary weapons). - While returning from chasing a target, we call
ImplementAttackNearestTarget
andImplementFireOnTargetsOfOpportunity
. - When returning from chasing a target, we call
GetVisibleEnemyInRange
again to see if any more enemies show up. - If attacked, we chase the attacker.
- NOTE: If guard has no enemies, then we should return to base using standard dock order (rather than implement navigation in guard order). But make sure we still respond appropriately to communications, etc.
Hold
CWaitOrder
Ship stays in one place but attacks enemies that approach.
- Calls
CSpaceObject::GetVisibleEnemyInRange
to look for enemies inside a certain range (unlessnoAttackOnThreat
is set). The range is either 30 light-seconds or, for aggressor ships, the maximum weapon range. - If we have a target, calls
ImplementAttackTarget
without moving. - Calls
ImplementFireOnTargetsOfOpportunity
. - We stop attacking if the enemy is well out of range, or if we can no longer see it, or if we're not an aggressor and we haven't been attacked for a while.
- If we're attacked and we don't already have a target, there is a chance we attack back.
HoldAndAttack
CAttackOrder
Attacks a given target without moving.
- Target specified in order.
- Calls
ImplementAttackTarget
on the target without moving. - Calls
ImplementFireOnTargetsOfOpportunity
. - Does not respond to attacks.
HoldCourse
CStandardShipAI
Moves in a straight line on a given course heading.
- Calls
ImplementAttackNearestTarget
. - Calls
ImplementFireOnTargetsOfOpportunity
. - Does not respond to attacks.
Loot
CStandardShipAI
Mine
CStandardShipAI
NavPath
CNavigateOrder
Follow a given nav-path.
- Calls
ImplementAttackNearestTarget
- Calls
ImplementFireOnTargetsOfOpportunity
. - If attacked, set current target, but we do not change course or maneuver.
Orbit
CStandardShipAI
Orbits around a given object at a given distance.
- Calls
ImplementAttackNearestTarget
- Calls
ImplementFireOnTargetsOfOpportunity
. - Does not respond to attacks.
OrbitExact
COrbitExactOrder
Orbits around a given object using Kepler orbit parameters.
- Calls
ImplementAttackNearestTarget
and turns to aim at target. - Calls
ImplementFireOnTargetsOfOpportunity
. - Does not respond to attacks.
OrbitPatrol
COrbitPatrolOrder
Orbits around a given object using Kepler orbit parameters, and chases enemy threats.
- When orbiting, behaves the same as orbitExact, but we call
CSpaceObject::GetVisibleEnemyInRanage
out to 30 light-seconds to look for threats. - When we have a target, we chase it like the patrol order.
- If attacked, we send
msgAttackDeter
message to our base.
Patrol
CStandardShipAI
Orbits around a given object and chases enemy threats.
- When orbiting, calls
ImplementAttackNearestTarget
andImplementFireOnTargetsOfOpportunity
. - Calls
CSpaceObject::GetVisibleEnemyInRage
out to 30 light-seconds (from base) to look for threats. - When we have a target, we call
ImplementAttackTarget
to chase it. - We stop chasing when we're beyond our range and we haven't been attack recently (using
IsBeingAttacked
. - If attacked, we target the attacker. We also send the
msgAttackDeter
message to our base. - If we're attacked and we already have a target, we do not react.
Scavenge
CStandardShipAI
Look around for loot.
- While looking for look, we can
ImplementAttackNearestTarget
(but we don't turn to face attacker). We also callImplementFireOnTargetsOfOpportunity
. - If attacked while looking for loot, we temporarily attack the attacker, until the attacker stops attacking.
- If attacked while heading towards something to loot, we attack the attacker without maneuvering.
- If attacked while looting, we don't react.
Sentry
CSentryOrder
Defend a station without moving.
- We turn to attack the nearest target within 20 light-seconds. (
ImplementAttackNearestTarget
). - We call
CSpaceObject::GetVisibleEnemyInRange
within 30 light-seconds to acquire a target. - When attacking a target, we call
ImplementAttackTarget
without maneuvering. - If we're attacked, there is a chance that we target the attacker.
- If we're attacked, we sometimes send
msgAttackDeter
message to our base.
TradeRoute
CStandardShipAI
Wander the system docking with friendly stations.
- We use Dock order to travel between stations.
- While docked at a station we use WaitForThreat order.
TurnTo
CStandardShipAI
Turns to the given angle.
- While turning we call
ImplementAttackNearestTarget
without maneuvering. - While turning we call
ImplementFireOnTargetsOfOpportunity
. - If attacked we do not respond.
Wait
CWaitOrder
We wait.
- We don't attack anyone while waiting. Not even targets of opportunity.
- If we're attacked, we do not respond.
WaitForEnemy
CWaitOrder
We wait for an enemy to appear.
- As soon as we detect an enemy, the order ends.
- If attacked, the order ends.
WaitForTarget
CWaitOrder
We wait for a specified target to appear.
- While waiting, we call
ImplementAttackNearestTarget
but we don't turn. - While waiting, we call
ImplementFireOnTargetsOfOpportunity
. - If the target we're waiting for attack us, we end the order.
- If anyone else attacks us, we do not respond.
WaitForThreat
CWaitOrder
We wait for something to attack our station.
- If something attacks our stations (makes it angry) or destroys is, then the order ends.
- If anyone attacks us (even a friend), the order ends.
WaitForUndock
CWaitOrder
Wait for the specified target to undock.
- While waiting we do not react.
Wander
CStandardShipAI
Wander the system.
- We call
ImplementAttackNearestTarget
without turning. - We call
ImplementFireOnTargetsOfOpportunity
. - If attacked, we temporarily attack the attacker, until the attacker stops attacking.