SpaceTraders - Ship Navigation

Overview

Ships can navigate between waypoints within a system and jump or warp between systems across the SpaceTraders universe. Ships can also dock at waypoints to refuel, repair, and trade goods.

Movement in the SpaceTraders universe is based on a grid system. Ships can only move from and to other waypoints within the same system. To move between systems, you must either jump or warp your ship.

When traveling to a new waypoint or system, your ship nav's arrival timestamp will be updated to reflect when your ship will arrive at it's destination.

Orbiting and docking

Before a ship can travel, you must first confirm that the ship is undocked and in-orbit. You can call the following endpoint to confirm your ship is in orbit, or command it to move into orbit:


curl --request POST \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/orbit' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE'

Conversely, you can call the following endpoint to dock your ship at a waypoint:


curl --request POST \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/dock' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE'

The orbit and dock requests are idempotent, meaning you can call them successively and the result will be the same. This is useful if you want to ensure your ship is in orbit before you attempt to travel to another waypoint.

Flight mode

Your ship's flight mode determines the rate at which it travels and the amount of fuel consumed. There are four flight modes:

CRUISE - Cruise flight mode is the default mode for all ships. It consumes fuel at a normal rate and travels at a normal speed.
BURN - Burn flight mode consumes fuel at a faster rate and travels at a faster speed.
DRIFT - Drift flight mode consumes the least fuel and travels at a much slower speed. Drift mode is useful when your ship has run out of fuel and you need to conserve what little fuel you have left.
STEALTH - Stealth flight mode runs with systems at a minimum, making it difficult to detect. It consumes fuel at a normal rate but travels at a reduced speed.

To update your ship's flight mode, you can call the following endpoint:


curl --request PATCH \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/nav' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE' \
 --header 'Content-Type: application/json' \
 --data '{
    "flightMode": "CRUISE"
   }'

When navigating, a ship will move to the destination, but it will not arrive immediately. Instead, it will take time to travel to the destination, and you can use the navigation status to determine when the ship will arrive.

Navigation also consumes fuel, which is required to power the ship's engines. The amount of fuel consumed is based on the distance between the current location and the destination.

To navigate your ship to a waypoint, you can call the following endpoint:


curl --request POST \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/navigate' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE' \
 --header 'Content-Type: application/json' \
 --data '{
    "waypointSymbol": ":waypointSymbol"
   }'

Warping and jumping

When moving between systems, the ship can choose to jump or warp depending on the ship's technology. Warping your ship moves it into interdimensional space, and it behaves very similar to normal waypoint travel in that it takes time and consumes normal fuel.

Jumping a ship however is instantaneous, but it requires a jump drive and a unit of antimatter. Jump drives are expensive and rare, but your command ship starts with one.

To warp your ship to a new system, you can call the following endpoint:


curl --request POST \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/warp' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE' \
 --header 'Content-Type: application/json' \
 --data '{
    "systemSymbol": ":systemSymbol"
   }'

To jump your ship to a new system, you can call the following endpoint:


curl --request POST \
 --url 'https://api.spacetraders.io/v2/my/ships/:shipSymbol/jump' \
 --header 'Authorization: Bearer INSERT_TOKEN_HERE' \
 --header 'Content-Type: application/json' \
 --data '{
    "systemSymbol": ":systemSymbol"
   }'

Gate travel

If your ship isn't equipped with a jump or warp drive, you can still travel between systems by using faction gates. Gates are special waypoints that allow you to travel between systems.

Some faction gates are restricted based on your agent's reputation with the faction. To unlock access to new systems, you can increase your reputation with the faction by completing contracts for them.

Refueling