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 the guard order, the ship will retaliate.
  • chase: If attacked, we chase the attacker (or order-giver) out to threatRange. 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 (unless noTargetsOfOpportunity is set).
  • ImplementFireOnTargetsOfOpportunity: Fires secondary weapons (if any) to attack visible enemy ships (unless noTargetsOfOpportunity 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). Unless noAttackOnThreat 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 and ImplementFireOnTargetsOfOpportunity (for secondary weapons).
  • While returning from chasing a target, we call ImplementAttackNearestTarget and ImplementFireOnTargetsOfOpportunity.
  • 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 (unless noAttackOnThreat 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 and ImplementFireOnTargetsOfOpportunity.
  • 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 call ImplementFireOnTargetsOfOpportunity.
  • 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.