its_simpl.json

When your server starts, a file is already waiting for it at /simpl/its_simpl.json. It says which match this server is for, who is playing, and where players connect. The path is the same for ZIP builds and Docker images. Read it once when your server starts. A server started directly, not by matchmaking, has no match ID or queue ID: match_id and queue_id are null.

Example

{
  "server_id": "srv_a1b2c3",
  "match_id": "match_d4e5f6",
  "queue_id": "queue_g7h8i9",
  "region": "iad",
  "version_tag": "0.1.0",
  "network_ports": [
    {
      "name": "game",
      "protocol": "tcp",
      "internal_port": 8080,
      "external_port": 31456,
      "host": "iad.servers.simpl.gg",
      "ip": "203.0.113.10",
      "tls_enabled": true
    }
  ],
  "lobby_ids": ["lobby_j1k2l3"],
  "players": [
    {
      "player_id": "player_m4n5o6",
      "lobby_id": "lobby_j1k2l3",
      "team": "survivors",
      "role": "survivor",
      "state": {
        "mmr": 1450
      }
    }
  ],
  "custom_data": {}
}

Fields

Field	What it is
`server_id`	This server’s ID.
`match_id`	The match’s ID. `null` when the server was not started by matchmaking.
`queue_id`	The queue that made the match. `null` when the server was not started by matchmaking.
`region`	The region the server runs in.
`version_tag`	The name of the build this server runs.
`network_ports`	The server’s ports. See below.
`lobby_ids`	The lobbies in this match. Empty if you started the server yourself.
`players`	The players in this match. Empty if you started the server yourself.
`custom_data`	Any data you attached when the server was started.

Each player has a player_id and a lobby_id. team and role are there only when your queue uses teams and roles. state is the player state they sent, or null.

Network ports

Each entry in network_ports is one port:

name: the port’s name. Players connect to the port named game.
host: the address players connect to. It looks like {region}.servers.simpl.gg.
external_port: the port number players connect to.
internal_port: the port number your server listens on. For the game port it is the same number as the SIMPL_PORT_GAME environment variable.
ip: the server’s IP address. It can be null. Players should use host.
tls_enabled: true means Simpl handles encryption for this port. Connect with wss:// using the host name. Your game still listens on plain TCP. See Browser games (wss://). It is false for a port without TLS.

Players connect to host:external_port. For a port with tls_enabled set to true, they connect to wss://host:external_port, and never use ip. Your server should listen on the port in the SIMPL_PORT_GAME environment variable, and bind UDP to SIMPL_UDP_BIND_ADDRESS and TCP to SIMPL_TCP_BIND_ADDRESS, exactly as given. Don’t type an address yourself, even one that matches today.

Getting Started

Build Your Server

Run Your Server

Players

Unreal SDK

Platform

its_simpl.json

Example

Fields

Network ports

​Example

​Fields

​Network ports

Example

Fields

Network ports