tlecommunity.com / site
New TLE Community website using Eleventy. tlecommunity.com
Star
Fork 0
Watch
site content developers api index.md
8.4 kB
Markdown
at main

title: 'Introduction to the TLE API' layout: 'layouts/page.njk' #

This document can introduce you to interacting with the TLE Community game server.

Servers #

The list of playable servers can be read from https://tlecommunity.com/servers.json.

{{ servers | prettyPrintJson | safe }}

Each server in this list is an instance of the game, an individual universe separated from the others. Your app will need to allow users to select which server they want to interact with from this list.

API Versions #

Currently two versions of the API exist together. The responses and paramters are fundamentally the same however the conventions for sending requests and receiving responses are very different. The V2 convention was introduced as part of the TLE Community rollout and will be the standard going forward, however the old system is supported and will likely remain for the lifetime of this edition of the game.

V1 AKA "JSON-RPC" #

TLE Community uses a JSON-RPC 2.0 based API. You can read more about JSON-RPC 2.0 at http://www.jsonrpc.org/specification.

You can access these methods either as HTTP POSTs or GETs.

HTTP GET #

Many of the methods can be accessed using an HTTP GET request. Here's an example URL:

https://game.tlecommunity.com/empire?jsonrpc=2.0&id=1&method=is_name_available&params=["Lacuna Expanse Corp"]

The https://game.tlecommunity.com/ part gets you to the server.

Then /empire lets you interact with the Empire module. See the API reference for the complete list.

To make it JSON-RPC 2.0 compatible, you must include the jsonrpc=2.0&id=1 part.

Then specify the method you wish to call with method=is_name_available.

And finally pass in whatever parameters you need like params=["Lacuna Expanse Corp"]. Parameters need to be encoded in JSON. Some requests require an object of parameters, this would look like params={"this":"that","foo":"bar"}

Note: You must URL encode the params. If you don't, you'll get a parse error from the server.

HTTP POST #

Most programming languages will have a JSON-RPC 2.0 client you can either use directly, or download from the internet. These will use HTTP POST. If you need to manually create a POST, it would look like:

POST https://game.tlecommunity.com/species

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "is_name_available",
  "params": ["Human"]
}

Note: It's important to make the distinction here that when you're sending a POST, you're not sending URL parameters. You're sending a full POST body. If you format it with parameters like a GET request you'll get a parse error in response.

Use Post When Possible #

HTTP POST is the preferred method of execution. The reasons for this are:

  • You can make multiple method calls in the same request, per the JSON-RPC 2.0 specification.
  • Depending upon the HTTP Client, you'll have somewhere between 512 and 2048 bytes to send the request on a GET, but it can be unlimited on a POST.
  • If you use an HTTP GET, you'll need to URL Encode the params, but with POST you don't need to do that.

Response #

Either way you'll get a response back with either a result or an error message.

Result #

If you make a successful request you'll get a response like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 1
}

Error #

If an exception is thrown you'll get an error response. It's a hash containing a code, message, and data section.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 1000,
    "message": "Name not available.",
    "data": null
  }
}

Note: If you get a JSON-RPC error, then the web server will also give you a 500 HTTP error code.

V2 AKA "Open API/Swagger" #

Available on the /v2/ endpoint of any TLE Community server is a more idiomatic layout of the game's API. Using HTTP POST you can call https://game.tlecommunity.com/v2/<module>/<method> and get a JSON response. The Session ID is passed in via the Authorization HTTP header with the header value taking the form Token <token here>. Finally - named arguments are supported for all API calls to reduce ambiguity in the spec. The server's /v2/ proxy layer still supports sending positional arguments (it just passes them through without changing them) however if you send an object, it will convert that into the legacy positional args on-the-fly.

Response #

A complete example would look like the following:

POST https://game.tlecommunity.com/v2/spaceport/get_ships_for
Authorization: Token <session ID here>
Body: {
  "from_body_id": 1234,
  "target": { "star_id": 5678 },
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "available": [],
    "unavailable": [
      {
        "ship": {
          "date_available": "11 09 2026 02:08:54 +0000",
          "date_started": "11 09 2026 02:08:54 +0000",
          "hold_size": 0,
          "payload": [],
          "combat": 0,
          "id": 133,
          "fleet_speed": 0,
          "number_of_docks": null,
          "can_recall": 0,
          "type": "short_range_colony_ship",
          "berth_level": 0,
          "image": "short_range_colony_ship",
          "stealth": 0,
          "task": "Docked",
          "can_scuttle": 1,
          "max_occupants": 0,
          "name": "The Gift",
          "speed": 5500,
          "type_human": "Short Range Colony Ship"
        },
        "reason": [1009, "Can only be sent to planets."]
      }
    ],
    "incoming": [],
    "fleet_send_limit": 600,
    "status": {
      "empire": "Omitted for brevity",
      "body": "Omitted for brevity",
      "server": {
        "rpc_limit": 2000,
        "time": "15 09 2026 03:58:25 +0000",
        "version": 4.0004,
        "star_map_size": { "x": [-2000, 2000], "y": [-2000, 2000] }
      }
    }
  }
}

Error #

An error response is exactly the same as the old API:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 1000,
    "message": "Name not available.",
    "data": null
  }
}

RPC Limit #

You may only make a number of calls up to the RPC Limit in a given 24 hour period. The current limit is 2000 on meanjin-one. They are also rate limited to 60 calls per minute on meanjin-one. The counter resets roughly (give or take 60 minutes) at midnight GMT. Your RPC calls are counted across all clients you use and your own programs.

If you find yourself needing more RPC calls than the limit allows then you are likely making a lot of redundant requests. For example body.get_buildings() returns the entire list of buildings, and a time as to when their stats will change. So instead of calling every building on every planet every time your program looks something up, cache it until it changes.

Status #

Most methods will provide a status block as part of the response. This is used to update the user interface and alert the user to things. The status block looks like this:

{
  /* ... */
  "status": {
    "server": {
      "time": "01 31 2010 13:09:05 +0600",
      "version": 2.0604,
      "announcement": 1, // see the Announcement API
      "rpc_limit": 2500, // max calls per day, compare to empire rpc_count
      "star_map_size": {
        "x": [-15, 15],
        "y": [-15, 15],
        "z": [-15, 15]
      }
    },
    "empire": {
      // this block is not always included
      // See get_status() in Empire
    },
    "body": {
      // this block is not always included
      // See get_status() in Body
    }
  }
}

Methods using the 'hash of named parameters' method can specify a 'no_status : 1' argument which will inhibit the return of a status block. This can be slightly more efficient for those cases where you don't care to check the status so often.

Modules #

The full, list of RPC modules and their methods lives in the API reference.