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.

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.

{
  "type": "identify",
  "data": {
    "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.

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.

Category	Functions
Players	getPlayer, getPlayers, getPlayerLocation, getPlayerInventory
Items	giveItem, listItems
World	listEntities, listLocations
Commands	executeConsoleCommand, sendMessage, teleportPlayer
Moderation	kickPlayer, banPlayer, unbanPlayer, listBans
Server	testReachability, shutdown

Event	Trigger
player-connected	Player joins the server
player-disconnected	Player leaves the server
chat-message	Player sends a chat message
player-death	Player dies
entity-killed	Player kills an entity
log	Game server produces a log line

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)
• Mock implementation — Used for internal Takaro testing (TypeScript)