Adding support for a new game

Takaro uses a generic connector protocol that allows any game to integrate with Takaro. You build a client (either as an in-game mod or as a standalone process) that connects to Takaro over WebSocket and implements a set of functions and events.

This page covers how to choose your architecture and the core concepts. For the full protocol specification with request/response formats, see the Generic Connector Protocol Reference.

The protocol is versioned. New connectors should implement Generic Game Protocol v1, and existing version 0 connectors keep working unchanged.

Choosing Your Architecture

Before writing code, decide how your integration will run. Both approaches use the same Generic Connector Protocol: the difference is where your code runs and how it accesses game data.

In-Game Mod (Recommended)

Write a mod or plugin that runs inside the game server process. The mod connects outbound to Takaro’s WebSocket endpoint and has direct access to the game’s internal APIs.

┌─────────────────────────────┐              ┌──────────┐
│       Game Server           │              │  Takaro  │
│                             │              │  (Cloud) │
│   ┌───────────────────┐    │     WSS      │          │
│   │     Your Mod      │────┼─────────────>│          │
│   │  (runs in-game)   │    │    :443      │          │
│   └───────────────────┘    │              │          │
│                             │              │          │
└─────────────────────────────┘              └──────────┘

Because the mod runs inside the game, it can hook directly into game events (player joins, chat, deaths), execute commands with full context, and access player data, inventories, and world state without going through an external protocol.

Advantages:

• Server admins install it like any other mod: drop a file into a folder
• Game server hosting companies already support mod installation, which helps adoption
• Direct API access means you can implement all Takaro functions
• Single process: no extra infrastructure to manage

Requirements:

• The game must have a modding or plugin framework (Spigot, Oxide, Unreal Engine modding, etc.)
• The framework must allow opening outbound WebSocket connections
• The framework must expose the APIs you need: player events, command execution, player data

Existing examples: Minecraft (Java/Spigot), 7 Days to Die (C#)

Sidecar Process

If the game doesn’t support mods, or its modding API doesn’t expose what you need, you can run a separate process alongside the game server. This process connects to the game using whatever external protocol is available (RCON, HTTP API, console) and separately connects to Takaro’s WebSocket endpoint. It bridges between the two.

┌──────────────────┐              ┌──────────────────┐              ┌──────────┐
│   Game Server    │              │  Sidecar Process │              │  Takaro  │
│                  │    RCON /    │                  │     WSS      │  (Cloud) │
│                  │◄────────────>│  Bridges game    │─────────────>│          │
│                  │    HTTP      │  to Takaro       │    :443      │          │
└──────────────────┘              └──────────────────┘              └──────────┘

Trade-offs:

• Server admins need to run an additional process next to the game server. On dedicated hardware this is straightforward, but many game server hosting providers don’t allow running extra processes. This can limit adoption.
• External protocols like RCON expose limited data compared to in-game APIs. Some Takaro functions may not be fully implementable, or may require workarounds like parsing console output.
• Event detection often relies on polling or log parsing, which adds latency and can be fragile across game updates.

When to use this:

• The game has no modding support, or mods can’t access the APIs you need
• The game does expose RCON, an HTTP API, or some other external interface
• You accept the trade-offs above

A game with limited Takaro integration is better than no integration at all. If the sidecar approach is the only viable path, it’s still worth building.

Tip

Some sidecar implementations pair with a lightweight in-game component (e.g. a small mod that only forwards events) while the sidecar handles the Takaro connection and command execution. This hybrid approach can give you better event coverage than pure RCON/API polling.

Existing example: Palworld Bridge (community: TypeScript sidecar + UE4SS Lua mod for events)

Which Should I Choose?

If the game supports mods that can open WebSocket connections and hook into game events, go with an in-game mod. Only fall back to a sidecar when the game makes it impossible to run custom code inside the server process.

Concepts

Takaro uses the concept for a gameId to identify players. This is a unique identifier for the player in the game. Different games will have different ways of identifying players. For example, in 7 Days to Die, the gameId is the ‘cross ID/EOS ID’ of the player. In other games, it might be the SteamID, a UUID or some other identifier. When Takaro calls a function that pertains to a specific player, it will pass the gameId as an argument.

Player Object Structure

Takaro expects player objects to follow the IGamePlayer interface structure. This interface supports multiple gaming platforms and provides a consistent way to represent player data across different games.

Required Fields:

• gameId (string): Unique identifier for the player in the game
• name (string): Player’s display name/username

Optional Fields:

• steamId (string): Steam platform identifier
• epicOnlineServicesId (string): Epic Games platform identifier
• xboxLiveId (string): Xbox Live platform identifier
• platformId (string): Generic platform identifier in platform:id format
• ip (string): Player’s IP address
• ping (number): Player’s connection ping

Platform ID Implementation

The platformId field provides a flexible way to identify players from platforms not covered by Steam, Epic, or Xbox Live. It follows a strict format to ensure consistency:

Format: platform:identifier

Validation Rules:

• Must contain exactly one colon (:) separating platform and identifier
• Platform part: Only alphanumeric characters, hyphens (-), and underscores (_)
• Identifier part: Only alphanumeric characters, hyphens (-), and underscores (_)
• No spaces or special characters allowed
• Both platform and identifier parts must have at least one character

Examples:

Valid:
- minecraft:550e8400-e29b-41d4-a716-446655440000
- battlenet:PlayerName-1234
- origin:OriginPlayerID
- discord:123456789012345678
- custom_platform:player_123

Invalid:
- invalidformat (missing colon)
- platform: (empty identifier)
- :identifier (empty platform)
- platform with spaces:id (spaces not allowed)
- platform:id:extra (multiple colons)

When to Use Each Platform Field

Use platform-specific fields when available:

• Steam-based games → populate steamId
• Epic Games Store games → populate epicOnlineServicesId
• Xbox Live integrated games → populate xboxLiveId

Use platformId for:

• Games with custom authentication systems
• Platforms not covered by the specific fields above
• Cross-platform games with unified player IDs
• Games using Discord, Battle.net, Origin, or other platforms

Best Practices:

• Choose descriptive platform names (e.g., minecraft, battlenet, origin)
• Use consistent naming across your game instances
• Prefer official platform identifiers when possible

Connecting to Takaro

Takaro exposes a websocket server at wss://connect.takaro.io/. The game mod should connect to this and send a identify message containing the identity token and registration token.

• Identity token: This is a unique token that identifies the game instance. If you connect with a new token, Takaro will create a new gameserver record. If you connect with an existing token, Takaro will update the existing gameserver record. It is important to keep this token the same across restarts of the game, otherwise Takaro will start with fresh data every time.
• Registration token: This is a secret token that is used to authenticate the game instance. This token is generated for a domain in Takaro. This should be kept secret, otherwise other game instances can connect to Takaro and insert their data in your domain.
• Name (optional): The server name shown in Takaro. It defaults to the identity token. For a server your connector created, Takaro keeps the name in sync with what your connector reports, until an operator renames the server in Takaro.
• Game (optional): A lowercase game identifier such as 7d2d or enshrouded. Takaro shows it when the game has no Game Profile.
• Connector (optional): Your connector’s name and semantic version, for example { "name": "my-game-connector", "version": "1.4.0" }. Takaro records it so it can see which connector releases are still in use.

Protocol versions

The Generic Game Protocol has a Protocol Version, a plain integer that covers only the wire format: the handshake, the error shape and event delivery. A connector that sends no protocolVersions speaks version 0, which is supported forever. New game features never bump the version. They are Capabilities, which a game declares in its Capability Manifest during the handshake.

Identify (version 1, recommended)

{
  "type": "identify",
  "payload": {
    "identityToken": "my-server-1",
    "registrationToken": "<registration token>",
    "name": "My Server",
    "game": "my-game",
    "connector": { "name": "my-game-connector", "version": "1.4.0" },
    "protocolVersions": [1],
    "capabilities": [
      { "name": "players.list" },
      { "name": "players.get" },
      { "name": "chat.send" },
      { "name": "moderation.kick" },
      { "name": "events.player-connected" },
      { "name": "events.chat-message" },
      { "name": "game.profile", "parameters": { "name": "My Game", "version": "1.0.2" } }
    ]
  }
}

On success you get an identifyResponse with the version Takaro picked:

{
  "type": "identifyResponse",
  "payload": { "gameServerId": "6f1c2a4e-0b7d-4c1e-9a55-2f4f1a8e9d10", "protocolVersion": 1 },
  "requestId": "a3d1c1f0-5b7e-4c55-8a3e-0c9e8f7d6b5a"
}

If the versions do not overlap, the response carries the error code no_shared_protocol_version and Takaro closes the socket with close code 1008. If you leave out capabilities, the manifest is empty and every action except testReachability is answered with unsupported. See Generic Game Protocol v1 for the details.

Declare game.profile so the dashboard shows your game’s name, build and icon instead of “Generic”. See Game Profile for the fields and the getGameIcon action.

Identify (version 0)

{
  "type": "identify",
  "payload": {
    "identityToken": "<identity token>",
    "registrationToken": "<registration token>"
  }
}

You will get a identifyResponse message back saying if it worked or not. If the message contains a error field in the payload, there’ll be more details about what went wrong. If the payload contains a gameServerId field, it was successful. The success payload also contains "protocolVersion": 0, which version 0 connectors can ignore.

What to Implement

The generic connector protocol defines a set of functions that Takaro can call on your game server and a set of events your integration pushes to Takaro. Both are sent as JSON messages over the WebSocket connection.

On version 1 you declare only what you support, and Takaro answers the rest with unsupported. The Capability column lists the name to declare in your Capability Manifest.

Category	Function	Capability (v1)
Players	getPlayers	players.list
Players	getPlayer	players.get
Players	getPlayerLocation	players.location
Players	getPlayerInventory	players.inventory
Items	giveItem	items.give
Items	listItems	items.list
World	listEntities	entities.list
World	listLocations	locations.list (version 1 only)
Commands	executeConsoleCommand	console.execute
Commands	sendMessage	chat.send
Commands	teleportPlayer	players.teleport
Moderation	kickPlayer	moderation.kick
Moderation	banPlayer	moderation.ban
Moderation	unbanPlayer	moderation.unban
Moderation	listBans	moderation.listBans
Server	testReachability	always (not a capability)
Server	shutdown	server.shutdown

Event	Trigger
player-connected	Player joins the server
player-disconnected	Player leaves the server
chat-message	A chat message is sent (by a player, or by the console/server without a player)
player-death	Player dies
entity-killed	Player kills an entity
log	Game server produces a log line
player-positions	Version 1 only: a batch of every online player’s Position, once per declared interval
inventory-changed	Version 1 only: one item line gained or lost, with its cause

On version 1 each event carries a streamId and seq and is acknowledged by Takaro, see Event delivery. You also declare each event type you emit as events.<type> in the manifest. Most of these entries are descriptive, but events.player-positions and events.inventory-changed are required before Takaro accepts those events, and they turn polling off. See Pushed Positions.

Games that can draw a map declare the map capability, see Map.

See the Generic Connector Protocol Reference for complete request/response formats and event payload structures.

Reference Implementations

• Minecraft: In-game mod (Java/Spigot)
• 7 Days to Die: In-game mod (C#)
• Palworld Bridge: Sidecar process (TypeScript + UE4SS Lua)