Skip to main 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​

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​

Retrieves information about a specific player.

Request​

{
  "type": "request",
  "payload": {
    "action": "getPlayer",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

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​

Retrieves a list of all currently connected players.

Request​

{
  "type": "request",
  "payload": {
    "action": "getPlayers",
    "args": []
  },
  "requestId": "request-uuid"
}

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​

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

Request​

{
  "type": "request",
  "payload": {
    "action": "getPlayerLocation",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

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​

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​

{
  "type": "request",
  "payload": {
    "action": "getPlayerInventory",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

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​

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

Request​

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

Response​

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

listItems​

Retrieves a list of all available items in the game.

Request​

{
  "type": "request",
  "payload": {
    "action": "listItems",
    "args": []
  },
  "requestId": "request-uuid"
}

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​

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​

{
  "type": "request",
  "payload": {
    "action": "listEntities",
    "args": []
  },
  "requestId": "request-uuid"
}

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​

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​

{
  "type": "request",
  "payload": {
    "action": "listLocations",
    "args": []
  },
  "requestId": "request-uuid"
}

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​

Executes a console command on the game server.

Request​

{
  "type": "request",
  "payload": {
    "action": "executeConsoleCommand",
    "args": "{\"command\": \"say Hi\"}"
  },
  "requestId": "request-uuid"
}

Response​

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

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​

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

Response​

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

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​

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

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​

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​

{
  "type": "request",
  "payload": {
    "action": "testReachability",
    "args": []
  },
  "requestId": "request-uuid"
}

Response​

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

kickPlayer​

Kicks a player from the server.

Request​

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

Response​

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

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​

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

Response​

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

unbanPlayer​

Removes a ban for a specific player.

Request​

{
  "type": "request",
  "payload": {
    "action": "unbanPlayer",
    "args": "{\"gameId\": \"12345\"}"
  },
  "requestId": "request-uuid"
}

Response​

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

listBans​

Retrieves a list of all currently banned players.

Request​

{
  "type": "request",
  "payload": {
    "action": "listBans",
    "args": []
  },
  "requestId": "request-uuid"
}

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​

Initiates a graceful shutdown sequence for the game server.

Request​

{
  "type": "request",
  "payload": {
    "action": "shutdown",
    "args": []
  },
  "requestId": "request-uuid"
}

Response​

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

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​

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​

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​

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​

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​

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​

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​

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"
    }
  }
}