Skip to content

Generic Connector Protocol Reference

This page documents the WebSocket message formats for the generic connector protocol. Your integration — whether an in-game mod or a sidecar process — needs to handle these messages.

For architecture guidance, concepts like gameId and player objects, and connection setup, see Adding Support for a New Game.

Functions

Section titled “Functions”

Takaro will request data from the server and it will perform actions on the server. The game mod should implement the following functions.

Each of these will be sent over the websocket connection as a JSON message. The game server will receive a message like:

{
  type: 'request',
  payload: { action: 'getPlayers', args: [] },
  requestId: '1234',
}

The above message means that Takaro wants to call the getPlayers function on the game server. The game server should respond with a message like:

{
  type: 'response',
  payload: [... player objects],
  requestId: '1234',
}

Note the requestId field. This is used to match the request and response. The game server should always respond with the same requestId as the request. Takaro might send multiple requests at the same time, so it is important to keep track of the request IDs.

If the game server returns data in a bad format, Takaro will return an error over the websocket connection.

getPlayer

Section titled “getPlayer”

Retrieves information about a specific player.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "getPlayer",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": {
    "gameId": "12345",
    "name": "PlayerName",
    "steamId": "76561198123456789",
    "epicOnlineServicesId": null,
    "xboxLiveId": null,
    "platformId": null,
    "ip": "192.168.1.1",
    "ping": 50
  },
  "requestId": "request-uuid"
}

If the player is not found, return null:

{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

getPlayers

Section titled “getPlayers”

Retrieves a list of all currently connected players.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "getPlayers",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "gameId": "12345",
      "name": "PlayerName1",
      "steamId": "76561198123456789",
      "epicOnlineServicesId": null,
      "xboxLiveId": null,
      "platformId": null,
      "ip": "192.168.1.1",
      "ping": 50
    },
    {
      "gameId": "67890",
      "name": "PlayerName2",
      "steamId": null,
      "epicOnlineServicesId": null,
      "xboxLiveId": null,
      "platformId": "minecraft:550e8400-e29b-41d4-a716-446655440000",
      "ip": "192.168.1.2",
      "ping": 75
    },
    {
      "gameId": "54321",
      "name": "PlayerName3",
      "steamId": null,
      "epicOnlineServicesId": null,
      "xboxLiveId": null,
      "platformId": "battlenet:PlayerName-1234",
      "ip": "192.168.1.3",
      "ping": 42
    }
  ],
  "requestId": "request-uuid"
}

getPlayerLocation

Section titled “getPlayerLocation”

Retrieves the current 3D position of a specific player. The response includes optional dimension information for games that support multiple dimensions/worlds.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "getPlayerLocation",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": {
    "x": 123.45,
    "y": 67.89,
    "z": 10.11,
    "dimension": "overworld"
  },
  "requestId": "request-uuid"
}

If the player is not found, return null:

{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

getPlayerInventory

Section titled “getPlayerInventory”

Retrieves the items in a specific player’s inventory. Note that quality is a string, not all games will have a number for quality.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "getPlayerInventory",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "code": "weapon_baseball_bat",
      "name": "Baseball Bat",
      "amount": 1,
      "quality": "5"
    },
    {
      "code": "first_aid_bandage",
      "name": "First Aid Bandage",
      "amount": 5,
      "quality": "high"
    }
  ],
  "requestId": "request-uuid"
}

giveItem

Section titled “giveItem”

Gives an item to a specific player. The item code (baseball_bat in this case) is the code used in the listItems function.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "giveItem",
    "args": "{\"player\": {\"gameId\": \"12345\"}, \"item\": \"baseball_bat\", \"amount\": 1, \"quality\": \"5\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

listItems

Section titled “listItems”

Retrieves a list of all available items in the game.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "listItems",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "code": "baseball_bat",
      "name": "Baseball Bat",
      "description": "A wooden baseball bat"
    },
    {
      "code": "first_aid_bandage",
      "name": "First Aid Bandage",
      "description": "Used to stop bleeding"
    }
  ],
  "requestId": "request-uuid"
}

listEntities

Section titled “listEntities”

Retrieves a list of all available entities in the game. This includes both NPCs and monsters. Vanilla and modded entities should be included.

The metadata field is optional and can be used to store additional (game-specific) information about the entity.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "listEntities",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "code": "pig",
      "name": "Pig",
      "description": "Some tasty bacon",
      "type": "friendly",
      "metadata": {
        "health": 10
      }
    },
    {
      "code": "skeleton",
      "name": "Skeleton",
      "description": "A spooky skeleton",
      "type": "hostile",
      "metadata": {
        "health": 50,
        "damage": 10
      }
    }
  ],
  "requestId": "request-uuid"
}

listLocations

Section titled “listLocations”

List all locations in the game. Locations are game-defined structures or areas. Some examples:

  • Minecraft villages, nether fortresses, end cities, …
  • 7 Days to Die POIs (Points of Interest)
  • Rust monuments

Locations must be either rectangular or circular, not both. The metadata field is optional and can be used to store additional information about the location.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "listLocations",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "position": {
        "x": 123.45,
        "y": 67.89,
        "z": 10.11,
        "dimension": "overworld"
      },
      "radius": 50,
      "name": "village",
      "code": "village_1",
      "metadata": {}
    },
    {
      "position": {
        "x": 200.0,
        "y": 100.0,
        "z": 50.0,
        "dimension": "nether"
      },
      "sizeX": 100,
      "sizeY": 50,
      "sizeZ": 100,
      "name": "forest",
      "code": "forest_38",
      "metadata": {}
    }
  ],
  "requestId": "request-uuid"
}

executeConsoleCommand

Section titled “executeConsoleCommand”

Executes a console command on the game server.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "executeConsoleCommand",
    "args": "{\"command\": \"say Hi\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": {
    "success": true,
    "rawResult": "Message sent: Hi",
    "errorMessage": null
  },
  "requestId": "request-uuid"
}

sendMessage

Section titled “sendMessage”

Sends a message to one or more players.

If the recipient field is not provided, the message should be a global message. If the recipient field is provided, the message should be sent to the specified player (DM/whisper).

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "sendMessage",
    "args": "{\"message\": \"Welcome to the server!\", \"opts\": {\"recipient\": {\"gameId\": \"12345\"}}}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

teleportPlayer

Section titled “teleportPlayer”

Teleports a player to a specific location. The coordinates are passed as x, y, and z values. The dimension parameter is optional and allows teleportation across different game dimensions/worlds (e.g., overworld, nether, end in Minecraft).

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "teleportPlayer",
    "args": "{\"player\": {\"gameId\": \"12345\"}, \"x\": 123.45, \"y\": 67.89, \"z\": 10.11, \"dimension\": \"nether\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

Note: The dimension parameter is optional. If not provided, the player will be teleported within their current dimension. Games that don’t support dimensions can safely ignore this parameter.

testReachability

Section titled “testReachability”

Tests if the game server is reachable and properly configured. Think of this as a ping/pong test. If something is misconfigured, the response can contain a reason field with a description of the issue.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "testReachability",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": {
    "connectable": true,
    "reason": null
  },
  "requestId": "request-uuid"
}

kickPlayer

Section titled “kickPlayer”

Kicks a player from the server.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "kickPlayer",
    "args": "{\"player\": {\"gameId\": \"12345\"}, \"reason\": \"Violated server rules\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

banPlayer

Section titled “banPlayer”

Bans a player from the server. The expiresAt field is optional. If not provided, the ban will be permanent. expiresAt is a ISO 8601 formatted date string.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "banPlayer",
    "args": "{\"player\": {\"gameId\": \"12345\"}, \"reason\": \"Cheating\", \"expiresAt\": \"2031-12-31T23:59:59Z\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

unbanPlayer

Section titled “unbanPlayer”

Removes a ban for a specific player.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "unbanPlayer",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

listBans

Section titled “listBans”

Retrieves a list of all currently banned players.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "listBans",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": [
    {
      "player": {
        "gameId": "12345",
        "name": "BannedPlayer1"
      },
      "reason": "Cheating",
      "expiresAt": "2031-12-31T23:59:59Z"
    },
    {
      "player": {
        "gameId": "67890",
        "name": "BannedPlayer2"
      },
      "reason": "Being rude",
      "expiresAt": "2031-12-31T23:59:59Z"
    }
  ],
  "requestId": "request-uuid"
}

shutdown

Section titled “shutdown”

Initiates a graceful shutdown sequence for the game server.

Request

Section titled “Request”
{
  "type": "request",
  "payload": {
    "action": "shutdown",
    "args": []
  },
  "requestId": "request-uuid"
}

Response

Section titled “Response”
{
  "type": "response",
  "payload": null,
  "requestId": "request-uuid"
}

Takaro Game Events

Section titled “Takaro Game Events”

These are the events that Takaro expects to receive from game servers. These events allow Takaro to react to changes in real-time.

Event Structure

Section titled “Event Structure”

All events should be sent over the websocket connection as a JSON message with the following structure:

{
  "type": "gameEvent",
  "payload": {
    "type": "<event type>",
    "data": {
      /* event specific data */
    }
  }
}

log

Section titled “log”

Event Type: log

Sent when a new log line is generated by the game server.

{
  "type": "gameEvent",
  "payload": {
    "type": "log",
    "data": {
      "msg": "Server started on port 26900"
    }
  }
}

player-connected

Section titled “player-connected”

Event Type: player-connected

Sent when a player connects to the game server. The player object must include the required gameId and name fields. Other fields like steamId, epicOnlineServicesId, xboxLiveId, platformId, ip, and ping are optional.

Include the appropriate platform identifier based on your game’s authentication system. Use platformId for custom platforms following the platform:id format.

{
  "type": "gameEvent",
  "payload": {
    "type": "player-connected",
    "data": {
      "player": {
        "gameId": "12345",
        "name": "SteamPlayer",
        "steamId": "76561198123456789",
        "epicOnlineServicesId": null,
        "xboxLiveId": null,
        "platformId": null,
        "ip": "192.168.1.1",
        "ping": 50
      }
    }
  }
}

Example with platformId for a custom platform:

{
  "type": "gameEvent",
  "payload": {
    "type": "player-connected",
    "data": {
      "player": {
        "gameId": "67890",
        "name": "MinecraftPlayer",
        "steamId": null,
        "epicOnlineServicesId": null,
        "xboxLiveId": null,
        "platformId": "minecraft:550e8400-e29b-41d4-a716-446655440000",
        "ip": "192.168.1.2",
        "ping": 75
      }
    }
  }
}

player-disconnected

Section titled “player-disconnected”

Event Type: player-disconnected

Sent when a player disconnects from the game server.

{
  "type": "gameEvent",
  "payload": {
    "type": "player-disconnected",
    "data": {
      "player": {
        "gameId": "12345"
      }
    }
  }
}

chat-message

Section titled “chat-message”

Event Type: chat-message

Sent when a player sends a chat message.

The channel field must be one of:

  • global
  • team
  • friends
  • whisper

The player field is optional, as some chat messages might be system messages without an associated player.

{
  "type": "gameEvent",
  "payload": {
    "type": "chat-message",
    "data": {
      "player": {
        "gameId": "12345",
        "name": "PlayerName"
      },
      "channel": "global",
      "msg": "Hello everyone!"
    }
  }
}

player-death

Section titled “player-death”

Event Type: player-death

Sent when a player dies in the game.

The attacker field is optional and should only be included if the player was killed by another player.

{
  "type": "gameEvent",
  "payload": {
    "type": "player-death",
    "data": {
      "player": {
        "gameId": "12345",
        "name": "PlayerName"
      },
      "attacker": {
        "gameId": "67890",
        "name": "AttackerName"
      },
      "position": {
        "x": 123.45,
        "y": 67.89,
        "z": 10.11,
        "dimension": "overworld"
      }
    }
  }
}

entity-killed

Section titled “entity-killed”

Event Type: entity-killed

Sent when a player kills an entity in the game.

{
  "type": "gameEvent",
  "payload": {
    "type": "entity-killed",
    "data": {
      "player": {
        "gameId": "12345",
        "name": "PlayerName"
      },
      "entity": "zombie",
      "weapon": "baseball_bat"
    }
  }
}