Core Concept

Non-player ships use orders to control behavior. A ship keeps a list of orders to execute. The ship follows the first order in the list. Once completed, the order is removed and the ship continues executing the next order in the list.

For example, imagine a ship with 3 orders:

Dock with a station
Wait for 4 seconds
Gate out

The ship will execute the above in order. At any time, of course, the developer may delete or add orders, depending on circumstances.

Some orders have indefinite duration. For example, the guard order lasts until it is canceled. Other orders have a time duration—they end after a certain period of time. And other orders end once the order is accomplished. For example, the attack order ends when the designated target is destroyed.

Many orders have parameters. For example, the dock order takes an object as a parameter (so we know what to dock with). Other orders take options such as duration, distance, etc.

Giving Orders

There are three main methods for giving orders to a ship. Each methods is described below:

Orders in Ship Tables

You may specify a single order for a ship in a ship table. This allows us to spawn ships with an order. For example, imagine a ship table of guards:

<ShipTable ...>
   <Ship class="&scRoninA;" count="1" orders="patrol:10"/>
</ShipTable>

The orders= attribute above specifies the patrol orbit. The station that we're patrolling is implied. The value of 10 is the radius of the patrol (in light-seconds).

Some orders support multiple options. In that case, you can used the following syntax:

<ShipTable ...>
   <Ship class="&scRoninA;" count="1" orders="patrol:radius=10:threatRange=20"/>
</ShipTable>

In the above example, we specify two options: radius and threatRange. The supported options depend on the specific order. See the Reference section below.

Orders in TLisp

You may control the list of orders using TLisp.

(shpOrder obj order [param] [options])

The above adds an order to the ship. param is generally the target. For example, for the attack order, this is the object to attack. The options argument is either a single value or a TLisp struct containing each option.

For example, if we want to add a patrol order we can write:

(shpOrder obj 'patrol stationObj 10)

Or, if we want to specify multiple options, we use a TLisp struct:

(shpOrder obj 'patrol stationObj {
   radius: 10
   threatRange: 20
   })

Note that this function always adds orders to the end of the list. If you want to add orders to the beginning of the list, call shpOrderImmediate.

If you want to replace the current orders, call shpCancelOrders first.

Orders in Events

Whenever a ship finds itself with no more orders, we call the <OnOrdersCompleted> event on the ship. The event is responsible for adding new orders (e.g., with shpOrder). If the event does not add any orders (or there is no event) then the ship will gate out of the system.

It is very common to add an event handler to a ship (using objSetEventHandler) to add the <OnOrdersCompleted> event.

Reference

IN PROGRESS

aim

(shpOrder shipObj 'aim targetObj)

orbitExact

(shpOrder shipObj 'orbitExact centerObj options)

This order instructs the ship to keep an exact orbit around the center. If any threats approach within the threat range, the ship will fire on it without leaving orbit. It will turn or use omnidirectional weapons.

Options

radius: Orbit radius in light-seconds (default 10). Radius can be a dice range and can include a scale suffix. For example, "100 pixel" sets the radius to be 100 pixels.
speed: The orbital speed in degrees per tick (default 1).
eccentricity: Orbital eccentricity (default 0.0).
angle: Angular offset in orbit (in degrees). Defaults to auto, which keeps separation with other objects orbiting at the same radius.
threatRange: Attack enemies in given range (in light-seconds). Defaults to 30.

orbitPatrol

(shpOrder shipObj 'orbitPatrol centerObj options)

This order is the same as orbitExact except that ships will chase enemies in range.

Options

Same as orbitExact, plus one additional option:

threatStopRange: When chasing enemy ships, this is the maximum range from the center (in light-seconds) that we will reach before turning back. The default is 120.

Resolve