COMMAND

Command organises a player's ships: tags label them, ship queries select them, groups save a query, and command nodes form a chain of command under the hull.

Tags

• PUT /v1/tags/{entity_kind}/{entity_id}/{tag} tags an owned ship, station, facility or gate. DELETE on the same path removes the tag.
• A tag is lowercase letters, digits, - and _.
• Tags are bookkeeping: written at once, with no order and no event, and seen only by their owner.
• GET /v1/tags lists tagged things. ?tag= filters ship, station, facility and gate lists.

Ship queries

• POST /v1/fleet/ships/query returns the owner's ships that match a query. It only reads.
• A match object holds when every field in it holds. and, or and not combine queries.
• Exact fields: kind, system_id, body_id, ring, sector, job, tag and name.
• Threshold fields: cargo, fuel, speed and wear, with <, <=, >, >= and =. Several operators make a range.
• worn matches ships at their wear limit. unassigned matches ships directly under the hull.
• node matches ships in a command node; under matches ships in it or any node below it.
• A ship moving between bodies is at no body. A ship jumping is in no system and no ring.

{"and": [
  {"kind": "harvest", "ring": "relay"},
  {"not": {"job": "harvesting"}},
  {"fuel": {"<": 20}}
]}

Groups

• A group is a ship query saved under a name. It picks up new ships that match.
• PUT /v1/fleet/groups/{name} saves one, and GET and DELETE on the same path read and remove it. GET /v1/fleet/groups/{name}/ships lists its ships now.
• Groups are bookkeeping, written at once. A group's query cannot use another group.

Command nodes

• A node is a named unit, such as a squadron or a fleet, with one parent: another node or the hull. Depth has no limit.
• A ship is in at most one node, or directly under the hull. The hull is the root and joins no node.
• Every change to nodes is an order, resolved in the tick with node.changed and ship.assigned events.
• GET /v1/fleet/nodes and GET /v1/fleet/nodes/{id} show each node's parent, ships and the nodes below it. Nodes are private.

• Disbanding moves a node's ships and child nodes up to its parent.
• A lent ship counts as a member of the node it is lent to until until_tick, then returns to its own node.
• A node's formation and preferred range in fights are set on the node. Its ships without a preferred range of their own take the nearest one up the chain. See Combat.

Depth and latency

• Each level of nodes between the hull and a ship adds to the delay before a delivered order runs. See Orders and Latency.
• A hosted node is commanded from its host, a ship or station command post of its owner's. Depth counts only the levels below the nearest hosted node.
• A host disabled, captured or wrecked loses its node (node.changed lost). A host handed over returns its node to the hull (unhosted).

Orders to many ships

• POST /v1/fleet/orders sends one order to every ship of a group, query or node.
• An order to a node reaches its ships, ships in nodes below it, and ships lent to any of them. assign, attach and detach reach only a node's own ships.
• An order to a node that no longer exists fails with not_found.