TextSpaced: An infinite and shared text-based universe.

API

The TextSpaced API is in development but allows for gathering game data and playing the game programmatically. Information on how to use the API and full documentation can be found at https://api.textspaced.com.

A working example of using the API in jQuery can be viewed at https://www.textspaced.com/examples/nearby/index.html with the option to download the entire source.

Using the API is rather straight forward. Simply perform GET or POST request to the endpoints listed in the documentation with any required parameters. An example in vanilla JavaScript using XHR and jQuery of an AJAX call to the API are as follows:

let data = "";
let xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});
xhr.open("POST", "https://api.textspaced.com/owned/ships/?key=value");
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.send(data);
$.ajax({
    url: "https://api.textspaced.com/owned/ships/",
    type: 'POST',
    datType: 'JSON',
    headers: {
        "Authorization": "Bearer " + token
    },
    data: params
})
                        

This example performs a POST request to the specified URL, which in this case is a list of ships that you own. The authorisation bearer token is required with every call to identify who you are. You can retrieve your API token by typing API in the Messenger version of TextSpaced or opening settings in the web version and coping your API token from there.

In the jQuery example the token parameter must be replaced with your actual API token and the params parameters are any parameters you wish to send, as detailed in the documentation.

An similar POST request using cURL in PHP would look like:

                        <?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.textspaced.com/owned/ships/?key=value',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer $token',
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
                        

In this PHP example the same endpoint is called as the jQuery example, parameters are appended to the URL and the authorisation bearer token included as a header.

The API is JSON based and will return responses in JSON format as described in the documentation. In the PHP example, using the json_decode function will convert the JSON into a PHP object for easier use. We recommend using an app such as Postman for helping to debug your requests before creating your own code. For API calls that are actions, such as move, a response format is used with a code and description about the outcome of the action. These codes are broken down below for convenience.

Response Codes

M category response codes are related to movement.

  • M1: Successfully moved via FTL.
  • M2: Cannot travel via FTL while in a Fractured Space sector.
  • M3: Cannot move while docked.
  • M4: Cannot move to a sector you are already in.
  • M5: Cannot move while landed.
  • M6: Cannot move while the helm is in follow mode.
  • M7: Cannot move via FTL while the light drive is destroyed.
  • M8: Cannot move via FTL while the engines are destroyed.
  • M9: Cannot move while internal systems are destroyed.
  • M10: Destination is further than ship range.
  • M11: Destination is further than ship charge.
  • M12: An active Null Space Inhibitor in the sector is preventing FTL travel.
  • M13: Current position cannot be determined, FTL travel is not possible.
  • M14: Cannot move while mining.
  • M15: Cannot move while already in FTL.
  • M16: Cannot travel while using amenities.
  • M17: Cannot move while repairing a structure.
  • M18: Cannot move while repairing.
  • M19: Cannot move while using a room.
  • M20: Cannot move while trawling.
  • M21: Cannot determine current position.
  • M22: Cannot locate current ship.
  • M23: Invalid sector ID used as destination.
  • M24: Cannot move while light drive is reinitialising.
  • M25: Can only move to adjacent sectors with sub-light travel.
  • M26: Not currently in sub-light travel.

D category response codes are related to docking.

  • D1: Successfully docked.
  • D2: Cannot dock while internal systems are destroyed.
  • D3: Cannot determine ship position for docking.
  • D5: Already docked.
  • D6: Currently landed, cannot dock.
  • D7: Cannot dock while helm is in follow mode.
  • D8: Cannot dock while mining.
  • D9: Cannot dock while in travelling.
  • D10: Cannot dock while using amenity.
  • D11: Cannot docking while repairing structure.
  • D12: Cannot dock while repairing ship.
  • D13: Cannot dock while using room.
  • D14: Cannot dock while trawling.
  • D15: Target invalid.
  • D16: Cannot dock with target while having hostile karma with their faction.
  • D17: Cannot dock while cloaked.
  • D18: Cannot dock while ship is contaminated.
  • D19: Structure has not been fully constructed.
  • D20: No free bays available.
  • D21: Target could not be found.
  • D22: Cannot dock while engines are destroyed.
  • D23: Current ship is not capable of ship docking.
  • D24: Cannot undock at this time, location cannot be calculated.
  • D25: Successfully undocked.

Related