GETTING STARTED

> 00 · SET UP

Every request carries the API key from registration as a bearer token. Every order also carries an Idempotency-Key: send the same one again and the order isn't queued twice.

export ARCHON=https://archon.nexus/v1
export KEY=ark_…

import time, uuid, requests

API = "https://archon.nexus/v1"
shell = requests.Session()
shell.headers["Authorization"] = "Bearer ark_…"

> 01 · READ YOUR HULL

A new player owns one ship, the Hull. /me gives your home system and the hull information: where it is, its job and its hold.

curl -s $ARCHON/me -H "Authorization: Bearer $KEY"

me = shell.get(f"{API}/me").json()
hull = me["hull"]

{
  "id": 3, "name": "kestrel", "empire": "Kestrel Holdings", "home_system_id": 7,
  "hull": {
    "id": 1, "kind": "hull", "system_id": 7, "body_id": 161,
    "job": "idle", "cargo": {}, "cargo_capacity": 500, "fuel": 200, "mining_rate": 60,
    …
  },
  …
}

> 02 · LOOK AROUND

Your home system starts surveyed. The Shell returns sightings, not the live world: each body as of the tick it was last seen, kept current while a ship or station of yours is there.

curl -s $ARCHON/systems/7 -H "Authorization: Bearer $KEY"

bodies = shell.get(f"{API}/systems/{me['home_system_id']}").json()["bodies"]
target = max(bodies, key=lambda b: b["surface"].get("iron", 0))

{
  "id": 7, "name": …, "surveyed": true,
  "bodies": [
    { "id": 160, "kind": "star", "surface": {}, "as_of": 0, … },
    { "id": 161, "kind": "asteroid_field", "surface": { "iron": 984, "silicate": 592, "carbon": 296, "copper": 100 }, "as_of": 0, … },
    { "id": 162, "kind": "asteroid_field", "surface": { "iron": 492, "silicate": 296, "carbon": 148, "copper": 50 }, "as_of": 0, … },
    …
  ]
}

> 03 · MOVE TO A BODY

An order is queued at once and resolves on tick_due, after the ship's command latency. The ship then flies until it arrives, and is idle again.

curl -s -X POST $ARCHON/fleet/ships/1/move \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: move-1" \
  -H "Content-Type: application/json" \
  -d '{"body_id": 162}'

def order(ship, verb, **body):
    headers = {"Idempotency-Key": str(uuid.uuid4())}
    return shell.post(f"{API}/fleet/ships/{ship['id']}/{verb}", json=body, headers=headers).json()

def wait(ship):
    time.sleep(20)  # let the order resolve
    while shell.get(f"{API}/fleet/ships/{ship['id']}").json()["job"] != "idle":
        time.sleep(15)

order(hull, "move", body_id=target["id"])
wait(hull)

{ "order": 1, "tick_due": 1, "duplicate": false, "dry_run": false, … }

> 04 · MINE

An extract order mines the body the ship is at, taking its mining_rate each minute in the surface's proportions, until the hold is full or the body is empty. Then the ship is idle until its next order.

curl -s -X POST $ARCHON/fleet/ships/1/extract \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: mine-1" \
  -H "Content-Type: application/json" \
  -d '{"body_id": 162}'

curl -s $ARCHON/fleet/ships/1 -H "Authorization: Bearer $KEY"

order(hull, "extract", body_id=target["id"])
wait(hull)
print(shell.get(f"{API}/fleet/ships/{hull['id']}").json()["cargo"])

{ "id": 1, "body_id": 162, "job": "idle", "cargo": { "iron": 246, "silicate": 148, "carbon": 74, "copper": 25 }, … }

> ANALYSIS first ore aboard. hull idle.

> TICKS, ORDERS, LATENCY

TICK

The world advances one tick at a time. Durations are written in minutes and turned into ticks by tick_scale, so they keep their real-time length.

ORDER

A ship carries out one order at a time. When it finishes, it is idle until the next one arrives. Nothing acts on its own.

INFONET

Orders travel your Infonet: every system within range of one of your command posts. A ship inside it gets its orders next tick, later if it's deep in your command tree; a ship outside it gets them only once it's back in range. The hull is a command post; an uplink or a forward HQ extends the Infonet.