Spacing Guild

A library of useful features for SpaceTraders API

Contents

• Installation
• Usage
  • Using Navigator
  • Using Mentat
• Build
• Documentation
  • Navigator
  • Mentat

Installation

npm i spacing-guild --save

Usage

Using Navigator

import { Navigator, ITradeRoute } from "spacing-guild";

// ...

const edric: Navigator = new Navigator(locations, ship);
const route: ITradeRoute = edric.navigate();

Example result

{
  "destination": "OE-PM",
  "cargo": [
    { "good": "FUEL", "quantity": 3, "totalVolume": 3 },
    { "good": "METALS", "quantity": 10, "totalVolume": 10 },
    { "good": "DRONES", "quantity": 2, "totalVolume": 4 },
    { "good": "FUEL", "quantity": 33, "totalVolume": 33 }
  ]
}

Using Mentat

import { Mentat } from "spacing-guild";

// ...

const distance: number = Mentat.calculateLocationDistance(locationA, locationB);
const inRange: number = Mentat.validateRange(ship, range, location);

Build

npm i

npm run build

Documentation

Navigator

The Navigator class is will decide the most profitable, possible trade from the ship's current location

It will return an object with 2 properties: Destination and Cargo

• Destination is a location type object that can be used when setting the flight plan.
• Cargo contains all the goods that should be bought from current marketplace and in what quantities, as well as the FUEL required for the trip. These goods should then be sold at the destination's marketplace.

Navigator class takes 2 arguments

• locations : A list of location objects to parse through
• ship : The ship object

Once a Navigator object is created, it automatically parses the locations and sets a list of all available trades. This list will then be used in the navigate() method to narrow down the possible trades based on the method's arguments.

note: In the following table, the column Type will contain some custom interfaces. Please refer to the Interfaces typescript file for information

| Methods | Arguments | Type | Description | | ------------------- | ------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | updateLocationsData | | void | | | | locations | ILocations[] | The list of locations | | updateShipData | | void | | | | ship | IShip | The ship object | | navigate | | returns ITradeRoute | | | | params (optional) | {range: number, fuelMargin: number} | | | | | | range is a number to limit the search for trade routes | | | | | fuelMargin is a number representing a percentage (ex. 5 is 5%) to include as error margin when calculating the FUEL needed for a trip | | | strict (optional) | boolean (default false) | Default is false. If true it throws errors instead of returning void in cases where trades are impossible |

NOTES

• If one of the profitable trades happens to be FUEL, it adds an extra entry with FUEL.
• This should not be sold as it can be used for further traveling and save costs because it was bought in a better price.
• If there is space left and no more available trades on destination, the remaining space will be empty.
• Currently this only works within the ship's system. Intersystem route plotting is the future. #TODO

Mentat

The Mentat class is solely responsible for various calculations. All methods are public static and return either a number or a boolean.

note: In the following table, the column Type will contain some custom interfaces. Please refer to the Interfaces typescript file for information

| Methods | Arguments | Type | Description | | ---------------------------------- | ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | calculateFuelToTravel | | returns number | Calculates the amount of fuel required to travel from location to destination | | | ship | IShip | | | | location | ILocation | | | | destination | ILocation | | | calculateFuelQuantity | | returns number | Calculates the remaining fuel needed to reach the quantity required for travel. Considers existing fuel in the ship. Adds extra fuel depending on the margin. | | | ship | IShip | | | | fuelToTravel | number | | | | margin | number (optional) | | | calculateDistance | | returns number | Calculates the distance between 2 points | | | ax | number | | | | ay | number | | | | bx | number | | | | by | number | | | calculateLocationDistance | | returns number | Calculates the distance between 2 locations | | | a | ILocation | | | | b | ILocation | | | calculatePricePerVolume | | returns number | Calculates the price per volume of a good. (Ex.If a unit of MACHINERY is 2 volumes and is priced at 10, then the price per volume is 5) | | | pricePerUnit | number | | | | volumePerUnit | number | | | calculateGoodProfitPerVol | | returns number | Calculates the profit per volume of a good bought in local marketplace and sold on another marketplace | | | a | IGood | | | | b | IGood | | | calculateGoodProfit | | returns number | Calculates the gross gain of selling a good | | | good | IGood | | | | amount | number | | | calculateGoodCost | | returns number | Calculates the cost of buying a good | | | good | IGood | | | | amount | number | | | calculateFuelToTravelCost | | returns number | Calculates the cost of fuel | | | amount | number | | | | unitCost | number | | | calculateCargoVolume | | returns number | Calculates the total volume of a good | | | good | IGood | | | | ship | IShip | | | calculateGoodQuantity | | returns number | Calculates the quantity of a good based on the available cargo space | | | space | number | | | | volumePerUnit | number | | | calculateProfitPerDU | | returns number | Calculates the profit per Distance Unit based on fuel cost, goods profit and distance to marketplace from the ship's position. The Profit per DU metric is used to sort the trades. The highest PpDU route is the best trade available | | | aGood | IGood | | | | bGood | IGood | | | | ship | IShip | | | | location | ILocation | | | | destination | ILocation | | | | fuelUnitCost | number | | | calculateFuelToTravelVolume | | returns number | Calculates the volume of FUEL | | | amount | number | | | calculateGoodVolume | | returns number | Calculates the volume of a good's quantity | | | amount | number | | | | good | IGood | | | calculateRemainingSpaceAfterRefuel | | returns number | Calculates the available cargo space after buying the fuel necessary for the route | | | ship | IShip | | | | fuelQuantity | number | | | validateRange | | returns boolean | Validates if a location is within the given range of the ship | | | ship | IShip | | | | range | number | | | | location | ILocation | |