Autohost

Modes

For now, we're only caring about the slaved mode, as it's a lot more work to implement dedicated mode and might not be necessary until we get a lot more players. Dedicated mode might not be ever realized.

All commands that are currenty defined are for the slaved mode of operation, there is nothing in place for dedicated one.

Dedicated

Communication from players goes directly to the autohost.

Pros

Lightens the load on the Tachyon server and makes scaling easier
Improved latency for players as messages don't need to be sent through a middleman server
Players in existing battles can keep playing games there even if the Tachyon server goes down

Cons

Tachyon server becomes unaware of activity taking place in battles directly, meaning any additional desired functionality such as telemetry or message logging would need to be implemented separately

Slaved

The Tachyon server acts as a middleman to broker messages between players and the autohost.

Pros

The Tachyon server effectively has full control over the autohost, making it possible to interject communications which could be useful for various reasons
The autohost's implementation has the potential to be much simpler, as the Tachyon server could handle all the pre-game communications and only interface with the autohost when launching the game and putting it in touch with the players

Cons

The Tachyon server has to do more heavy lifting for custom games, where lots of comms can take place before the game begins
Increased Tachyon server load/bandwidth
If the Tachyon server goes down, all the existing lobbies (pre-game battles) will also go down

Matchmaking

Autohosts used for matchmaking should use the slaved mode as no pregame communication between players and the autohost is required. The Tachyon server can dictate the battle's settings, start new game on autohost with those parameters and send connetion details to players.

Custom Battles

Autohosts used for custom games should use the dedicated mode as lots of pregame communication can take place.

addPlayer
kickPlayer
kill
mutePlayer
sendCommand
sendMessage
specPlayers
start
status
subscribeUpdates
update

AddPlayer

Request to add a new player to the battle.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostAddPlayerRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/addPlayer" },
        "data": {
            "title": "AutohostAddPlayerRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "userId": { "$ref": "../../definitions/userId.json" },
                "name": { "type": "string" },
                "password": { "type": "string" }
            },
            "required": ["battleId", "userId", "name", "password"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "ipsum",
    "commandId": "autohost/addPlayer",
    "data": {
        "battleId": "00000000-0000-0000-0000-000000000000",
        "userId": "351",
        "name": "ipsum",
        "password": "ipsum"
    }
}

TypeScript Definition

export type UserId = string;

export interface AutohostAddPlayerRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/addPlayer";
    data: AutohostAddPlayerRequestData;
}
export interface AutohostAddPlayerRequestData {
    battleId: string;
    userId: UserId;
    name: string;
    password: string;
}

Response

JSONSchema

{
    "title": "AutohostAddPlayerResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostAddPlayerOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/addPlayer" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostAddPlayerFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/addPlayer" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "fugiat",
    "commandId": "autohost/addPlayer",
    "status": "success"
}

TypeScript Definition

export interface AutohostAddPlayerOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/addPlayer";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

KickPlayer

Kick a player from a battle.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostKickPlayerRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/kickPlayer" },
        "data": {
            "title": "AutohostKickPlayerRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "userId": { "$ref": "../../definitions/userId.json" }
            },
            "required": ["battleId", "userId"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "ea",
    "commandId": "autohost/kickPlayer",
    "data": {
        "battleId": "00000000-0000-0000-0000-000000000000",
        "userId": "351"
    }
}

TypeScript Definition

export type UserId = string;

export interface AutohostKickPlayerRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/kickPlayer";
    data: AutohostKickPlayerRequestData;
}
export interface AutohostKickPlayerRequestData {
    battleId: string;
    userId: UserId;
}

Response

JSONSchema

{
    "title": "AutohostKickPlayerResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostKickPlayerOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/kickPlayer" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostKickPlayerFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/kickPlayer" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "quis",
    "commandId": "autohost/kickPlayer",
    "status": "success"
}

TypeScript Definition

export interface AutohostKickPlayerOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/kickPlayer";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

Kill

Request to kill a battle.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostKillRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/kill" },
        "data": {
            "title": "AutohostKillRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" }
            },
            "required": ["battleId"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "Ut",
    "commandId": "autohost/kill",
    "data": {
        "battleId": "00000000-0000-0000-0000-000000000000"
    }
}

TypeScript Definition

export interface AutohostKillRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/kill";
    data: AutohostKillRequestData;
}
export interface AutohostKillRequestData {
    battleId: string;
}

Response

JSONSchema

{
    "title": "AutohostKillResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostKillOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/kill" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostKillFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/kill" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "dolore",
    "commandId": "autohost/kill",
    "status": "success"
}

TypeScript Definition

export interface AutohostKillOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/kill";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

MutePlayer

Mute a player in a battle.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostMutePlayerRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/mutePlayer" },
        "data": {
            "title": "AutohostMutePlayerRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "userId": { "$ref": "../../definitions/userId.json" },
                "chat": { "type": "boolean" },
                "draw": { "type": "boolean" }
            },
            "required": ["battleId", "userId", "chat", "draw"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "labore",
    "commandId": "autohost/mutePlayer",
    "data": {
        "battleId": "11111111-1111-1111-1111-111111111111",
        "userId": "351",
        "chat": false,
        "draw": false
    }
}

TypeScript Definition

export type UserId = string;

export interface AutohostMutePlayerRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/mutePlayer";
    data: AutohostMutePlayerRequestData;
}
export interface AutohostMutePlayerRequestData {
    battleId: string;
    userId: UserId;
    chat: boolean;
    draw: boolean;
}

Response

JSONSchema

{
    "title": "AutohostMutePlayerResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostMutePlayerOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/mutePlayer" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostMutePlayerFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/mutePlayer" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "incididunt",
    "commandId": "autohost/mutePlayer",
    "status": "success"
}

TypeScript Definition

export interface AutohostMutePlayerOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/mutePlayer";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

SendCommand

Send a custom command for the autohost to execute.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostSendCommandRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/sendCommand" },
        "data": {
            "title": "AutohostSendCommandRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "command": { "type": "string" },
                "arguments": { "type": "array", "items": { "type": "string" } }
            },
            "required": ["battleId", "command"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "tempor",
    "commandId": "autohost/sendCommand",
    "data": {
        "battleId": "11111111-1111-1111-1111-111111111111",
        "command": "tempor"
    }
}

TypeScript Definition

export interface AutohostSendCommandRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/sendCommand";
    data: AutohostSendCommandRequestData;
}
export interface AutohostSendCommandRequestData {
    battleId: string;
    command: string;
    arguments?: string[];
}

Response

JSONSchema

{
    "title": "AutohostSendCommandResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostSendCommandOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/sendCommand" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostSendCommandFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/sendCommand" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "eiusmod",
    "commandId": "autohost/sendCommand",
    "status": "success"
}

TypeScript Definition

export interface AutohostSendCommandOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/sendCommand";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

SendMessage

Send a message for the autohost to display to players.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostSendMessageRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/sendMessage" },
        "data": {
            "title": "AutohostSendMessageRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "message": { "type": "string", "maxLength": 127 }
            },
            "required": ["battleId", "message"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "do",
    "commandId": "autohost/sendMessage",
    "data": {
        "battleId": "11111111-1111-1111-1111-111111111111",
        "message": "do"
    }
}

TypeScript Definition

export interface AutohostSendMessageRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/sendMessage";
    data: AutohostSendMessageRequestData;
}
export interface AutohostSendMessageRequestData {
    battleId: string;
    message: string;
}

Response

JSONSchema

{
    "title": "AutohostSendMessageResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostSendMessageOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/sendMessage" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostSendMessageFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/sendMessage" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "id",
    "commandId": "autohost/sendMessage",
    "status": "success"
}

TypeScript Definition

export interface AutohostSendMessageOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/sendMessage";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

SpecPlayers

Force players to become spectators in a battle.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostSpecPlayersRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/specPlayers" },
        "data": {
            "title": "AutohostSpecPlayersRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "userIds": {
                    "type": "array",
                    "items": { "$ref": "../../definitions/userId.json" }
                }
            },
            "required": ["battleId", "userIds"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "sint",
    "commandId": "autohost/specPlayers",
    "data": {
        "battleId": "22222222-2222-2222-2222-222222222222",
        "userIds": [
            "351"
        ]
    }
}

TypeScript Definition

export type UserId = string;

export interface AutohostSpecPlayersRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/specPlayers";
    data: AutohostSpecPlayersRequestData;
}
export interface AutohostSpecPlayersRequestData {
    battleId: string;
    userIds: UserId[];
}

Response

JSONSchema

{
    "title": "AutohostSpecPlayersResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostSpecPlayersOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/specPlayers" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostSpecPlayersFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/specPlayers" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "nulla",
    "commandId": "autohost/specPlayers",
    "status": "success"
}

TypeScript Definition

export interface AutohostSpecPlayersOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/specPlayers";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

Start

Tell the autohost client to launch the game server (spring-dedicated.exe or spring-headless.exe) with the given script data.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostStartRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/start" },
        "data": {
            "title": "AutohostStartRequestData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "engineVersion": {
                    "type": "string",
                    "pattern": "^[0-9a-zA-Z .+-]+$"
                },
                "gameName": { "type": "string" },
                "mapName": { "type": "string" },
                "gameArchiveHash": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{128}$"
                },
                "mapArchiveHash": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{128}$"
                },
                "startDelay": { "type": "integer" },
                "startPosType": {
                    "$ref": "../../definitions/startPosType.json"
                },
                "allyTeams": {
                    "type": "array",
                    "items": { "$ref": "../../definitions/allyTeam.json" },
                    "minItems": 1
                },
                "spectators": {
                    "type": "array",
                    "items": { "$ref": "../../definitions/player.json" }
                },
                "mapOptions": {
                    "type": "object",
                    "patternProperties": { "^(.*)$": { "type": "string" } }
                },
                "gameOptions": {
                    "type": "object",
                    "patternProperties": { "^(.*)$": { "type": "string" } }
                },
                "restrictions": {
                    "description": "Mapping from unitDefId to the maximum number of units of that type that can be built.",
                    "type": "object",
                    "patternProperties": {
                        "^(.*)$": { "type": "integer", "minimum": 0 }
                    }
                },
                "luamsgRegexp": {
                    "description": "When set, battle will generate updates for luamsgs matching this regexp. No updates will be generated if this is not set.",
                    "type": "string",
                    "format": "regex"
                }
            },
            "required": [
                "battleId",
                "engineVersion",
                "gameName",
                "mapName",
                "startPosType",
                "allyTeams"
            ]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "dolor",
    "commandId": "autohost/start",
    "data": {
        "battleId": "22222222-2222-2222-2222-222222222222",
        "engineVersion": "99",
        "gameName": "dolor",
        "mapName": "dolor",
        "startDelay": -70000000,
        "startPosType": "fixed",
        "allyTeams": [
            {
                "teams": [
                    {
                        "dolorb": -70000000,
                        "startPos": {
                            "x": -70000000,
                            "y": -70000000
                        }
                    }
                ]
            }
        ],
        "restrictions": {
            ".": 15000000
        }
    }
}

TypeScript Definition

export type StartPosType = "fixed" | "random" | "ingame" | "beforegame";
export type UserId = string;

export interface AutohostStartRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/start";
    data: AutohostStartRequestData;
}
export interface AutohostStartRequestData {
    battleId: string;
    engineVersion: string;
    gameName: string;
    mapName: string;
    gameArchiveHash?: string;
    mapArchiveHash?: string;
    startDelay?: number;
    startPosType: StartPosType;
    allyTeams: [AllyTeam, ...AllyTeam[]];
    spectators?: Player[];
    mapOptions?: {
        [k: string]: string;
    };
    gameOptions?: {
        [k: string]: string;
    };
    restrictions?: {
        [k: string]: number;
    };
    luamsgRegexp?: string;
}
export interface AllyTeam {
    teams: [Team, ...Team[]];
    startBox?: StartBox;
    allies?: number[];
    customProperties?: CustomStartScriptProperties;
}
export interface Team {
    players?: Player[];
    bots?: Bot[];
    advantage?: number;
    incomeMultiplier?: number;
    faction?: string;
    color?: {
        r: number;
        g: number;
        b: number;
    };
    startPos?: {
        x: number;
        y: number;
    };
    customProperties?: CustomStartScriptProperties;
}
export interface Player {
    userId: UserId;
    name: string;
    password: string;
    rank?: number;
    countryCode?: string;
    customProperties?: CustomStartScriptProperties;
}
export interface CustomStartScriptProperties {
    [k: string]: string;
}
export interface Bot {
    hostUserId: string;
    name?: string;
    aiShortName: string;
    aiVersion?: string;
    aiOptions?: {
        [k: string]: string;
    };
    customProperties?: CustomStartScriptProperties;
}
export interface StartBox {
    top: number;
    bottom: number;
    left: number;
    right: number;
}

Response

JSONSchema

{
    "title": "AutohostStartResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostStartOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/start" },
                "status": { "const": "success" },
                "data": {
                    "title": "AutohostStartOkResponseData",
                    "type": "object",
                    "properties": {
                        "ips": {
                            "type": "array",
                            "items": {
                                "anyOf": [
                                    { "type": "string", "format": "ipv4" },
                                    { "type": "string", "format": "ipv6" }
                                ]
                            }
                        },
                        "port": {
                            "type": "integer",
                            "minimum": 1024,
                            "maximum": 65535
                        }
                    },
                    "required": ["ips", "port"]
                }
            },
            "required": ["type", "messageId", "commandId", "status", "data"]
        },
        {
            "title": "AutohostStartFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/start" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "battle_already_exists",
                        "engine_version_not_available",
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "aute",
    "commandId": "autohost/start",
    "status": "success",
    "data": {
        "ips": [
            "40.40.40.40"
        ],
        "port": 11345
    }
}

TypeScript Definition

export interface AutohostStartOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/start";
    status: "success";
    data: AutohostStartOkResponseData;
}
export interface AutohostStartOkResponseData {
    ips: string[];
    port: number;
}

Possible Failed Reasons: battle_already_exists, engine_version_not_available, internal_error, unauthorized, invalid_request, command_unimplemented

Status

This event should be sent to the server on connection and whenever any of the status properties change.

Endpoint Type: Event
Source: Autohost
Target: Server
Required Scopes: tachyon.lobby

Event

JSONSchema

{
    "title": "AutohostStatusEvent",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "event" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/status" },
        "data": {
            "title": "AutohostStatusEventData",
            "type": "object",
            "properties": {
                "maxBattles": { "type": "integer", "minimum": 0 },
                "currentBattles": { "type": "integer", "minimum": 0 }
            },
            "required": ["maxBattles", "currentBattles"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "event",
    "messageId": "nisi",
    "commandId": "autohost/status",
    "data": {
        "maxBattles": 17000000,
        "currentBattles": 17000000
    }
}

TypeScript Definition

export interface AutohostStatusEvent {
    type: "event";
    messageId: string;
    commandId: "autohost/status";
    data: AutohostStatusEventData;
}
export interface AutohostStatusEventData {
    maxBattles: number;
    currentBattles: number;
}

SubscribeUpdates

Ask the autohost to send us updates about its battles.

Endpoint Type: Request -> Response
Source: Server
Target: Autohost
Required Scopes: tachyon.lobby

Request

JSONSchema

{
    "title": "AutohostSubscribeUpdatesRequest",
    "tachyon": {
        "source": "server",
        "target": "autohost",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/subscribeUpdates" },
        "data": {
            "title": "AutohostSubscribeUpdatesRequestData",
            "type": "object",
            "properties": {
                "since": { "$ref": "../../definitions/unixTime.json" }
            },
            "required": ["since"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "request",
    "messageId": "ullamco",
    "commandId": "autohost/subscribeUpdates",
    "data": {
        "since": 1705432698000000
    }
}

TypeScript Definition

export type UnixTime = number;

export interface AutohostSubscribeUpdatesRequest {
    type: "request";
    messageId: string;
    commandId: "autohost/subscribeUpdates";
    data: AutohostSubscribeUpdatesRequestData;
}
export interface AutohostSubscribeUpdatesRequestData {
    since: UnixTime;
}

Response

JSONSchema

{
    "title": "AutohostSubscribeUpdatesResponse",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "AutohostSubscribeUpdatesOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/subscribeUpdates" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "AutohostSubscribeUpdatesFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "autohost/subscribeUpdates" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}

Example

{
    "type": "response",
    "messageId": "exercitation",
    "commandId": "autohost/subscribeUpdates",
    "status": "success"
}

TypeScript Definition

export interface AutohostSubscribeUpdatesOkResponse {
    type: "response";
    messageId: string;
    commandId: "autohost/subscribeUpdates";
    status: "success";
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented

Update

Inform the server of battle updates.

Endpoint Type: Event
Source: Autohost
Target: Server
Required Scopes: tachyon.lobby

Event

JSONSchema

{
    "title": "AutohostUpdateEvent",
    "tachyon": {
        "source": "autohost",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "event" },
        "messageId": { "type": "string" },
        "commandId": { "const": "autohost/update" },
        "data": {
            "title": "AutohostUpdateEventData",
            "type": "object",
            "properties": {
                "battleId": { "type": "string", "format": "uuid" },
                "time": { "$ref": "../../definitions/unixTime.json" },
                "update": {
                    "anyOf": [
                        {
                            "title": "StartUpdate",
                            "description": "The battle has started.",
                            "type": "object",
                            "properties": { "type": { "const": "start" } },
                            "required": ["type"]
                        },
                        {
                            "title": "FinishedUpdate",
                            "description": "The battle finished, generated once per every single player reporting who won.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "finished" },
                                "userId": {
                                    "$ref": "../../definitions/userId.json"
                                },
                                "winningAllyTeams": {
                                    "description": "Ally team IDs",
                                    "type": "array",
                                    "items": { "type": "integer" },
                                    "minItems": 1
                                }
                            },
                            "required": ["type", "userId", "winningAllyTeams"]
                        },
                        {
                            "title": "EngineMessageUpdate",
                            "description": "A message from the engine, e.g. some ip is trying to connect.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "engine_message" },
                                "message": { "type": "string" }
                            },
                            "required": ["type", "message"]
                        },
                        {
                            "title": "EngineWarningUpdate",
                            "description": "A warning from the engine.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "engine_warning" },
                                "message": { "type": "string" }
                            },
                            "required": ["type", "message"]
                        },
                        {
                            "title": "EngineQuitUpdate",
                            "description": "The engine process for battle has quit cleanly, no more updates will be sent for this battle.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "engine_quit" }
                            },
                            "required": ["type"]
                        },
                        {
                            "title": "EngineCrashUpdate",
                            "description": "The engine process for battle has crashed, no more updates will be sent for this battle.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "engine_crash" },
                                "details": {
                                    "description": "Optional, short, details of the crash.",
                                    "type": "string"
                                }
                            },
                            "required": ["type"]
                        },
                        {
                            "title": "PlayerJoinedUpdate",
                            "type": "object",
                            "properties": {
                                "type": { "const": "player_joined" },
                                "userId": {
                                    "$ref": "../../definitions/userId.json"
                                },
                                "playerNumber": {
                                    "description": "Player number in the game, can be useful for custom commands",
                                    "type": "integer"
                                }
                            },
                            "required": ["type", "userId", "playerNumber"]
                        },
                        {
                            "title": "PlayerLeftUpdate",
                            "type": "object",
                            "properties": {
                                "type": { "const": "player_left" },
                                "userId": {
                                    "$ref": "../../definitions/userId.json"
                                },
                                "reason": {
                                    "enum": [
                                        "lost_connection",
                                        "left",
                                        "kicked"
                                    ]
                                }
                            },
                            "required": ["type", "userId", "reason"]
                        },
                        {
                            "title": "PlayerChatUpdate",
                            "anyOf": [
                                {
                                    "type": "object",
                                    "properties": {
                                        "type": { "const": "player_chat" },
                                        "userId": {
                                            "$ref": "../../definitions/userId.json"
                                        },
                                        "message": { "type": "string" },
                                        "destination": {
                                            "enum": [
                                                "allies",
                                                "all",
                                                "spectators"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "userId",
                                        "message",
                                        "destination"
                                    ]
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "type": { "const": "player_chat" },
                                        "userId": {
                                            "$ref": "../../definitions/userId.json"
                                        },
                                        "message": { "type": "string" },
                                        "destination": { "const": "player" },
                                        "toUserId": {
                                            "$ref": "../../definitions/userId.json"
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "userId",
                                        "message",
                                        "destination",
                                        "toUserId"
                                    ]
                                }
                            ]
                        },
                        {
                            "title": "PlayerDefeatedUpdate",
                            "type": "object",
                            "properties": {
                                "type": { "const": "player_defeated" },
                                "userId": {
                                    "$ref": "../../definitions/userId.json"
                                }
                            },
                            "required": ["type", "userId"]
                        },
                        {
                            "title": "LuaMsgUpdate",
                            "description": "This update is generated only for messages matching luamsgRegexp set in the battle start script.",
                            "type": "object",
                            "properties": {
                                "type": { "const": "luamsg" },
                                "userId": {
                                    "$ref": "../../definitions/userId.json"
                                },
                                "script": { "enum": ["ui", "game", "rules"] },
                                "uiMode": {
                                    "description": "Set when script is 'ui'",
                                    "enum": ["all", "allies", "spectators"]
                                },
                                "data": {
                                    "type": "string",
                                    "contentEncoding": "base64",
                                    "contentMediaType": "application/octet-stream"
                                }
                            },
                            "required": ["type", "userId", "script", "data"]
                        }
                    ]
                }
            },
            "required": ["battleId", "time", "update"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}

Example

{
    "type": "event",
    "messageId": "Ut velit",
    "commandId": "autohost/update",
    "data": {
        "battleId": "33333333-3333-3333-3333-333333333333",
        "time": 1705432698000000,
        "update": {
            "type": "engine_message",
            "message": "Ut velit"
        }
    }
}

TypeScript Definition

export type UnixTime = number;
export type UserId = string;
export type PlayerChatUpdate =
    | {
          type: "player_chat";
          userId: UserId;
          message: string;
          destination: "allies" | "all" | "spectators";
      }
    | {
          type: "player_chat";
          userId: UserId;
          message: string;
          destination: "player";
          toUserId: UserId;
      };

export interface AutohostUpdateEvent {
    type: "event";
    messageId: string;
    commandId: "autohost/update";
    data: AutohostUpdateEventData;
}
export interface AutohostUpdateEventData {
    battleId: string;
    time: UnixTime;
    update:
        | StartUpdate
        | FinishedUpdate
        | EngineMessageUpdate
        | EngineWarningUpdate
        | EngineQuitUpdate
        | EngineCrashUpdate
        | PlayerJoinedUpdate
        | PlayerLeftUpdate
        | PlayerChatUpdate
        | PlayerDefeatedUpdate
        | LuaMsgUpdate;
}
export interface StartUpdate {
    type: "start";
}
export interface FinishedUpdate {
    type: "finished";
    userId: UserId;
    winningAllyTeams: [number, ...number[]];
}
export interface EngineMessageUpdate {
    type: "engine_message";
    message: string;
}
export interface EngineWarningUpdate {
    type: "engine_warning";
    message: string;
}
export interface EngineQuitUpdate {
    type: "engine_quit";
}
export interface EngineCrashUpdate {
    type: "engine_crash";
    details?: string;
}
export interface PlayerJoinedUpdate {
    type: "player_joined";
    userId: UserId;
    playerNumber: number;
}
export interface PlayerLeftUpdate {
    type: "player_left";
    userId: UserId;
    reason: "lost_connection" | "left" | "kicked";
}
export interface PlayerDefeatedUpdate {
    type: "player_defeated";
    userId: UserId;
}
export interface LuaMsgUpdate {
    type: "luamsg";
    userId: UserId;
    script: "ui" | "game" | "rules";
    uiMode?: "all" | "allies" | "spectators";
    data: string;
}

Files

autohost.md

Latest commit

History

autohost.md

File metadata and controls

Autohost

Modes

Dedicated

Pros

Cons

Slaved

Pros

Cons

Matchmaking

Custom Battles

AddPlayer

Request

TypeScript Definition

Response

TypeScript Definition

KickPlayer

Request

TypeScript Definition

Response

TypeScript Definition

Kill

Request

TypeScript Definition

Response

TypeScript Definition

MutePlayer

Request

TypeScript Definition

Response

TypeScript Definition

SendCommand

Request

TypeScript Definition

Response

TypeScript Definition

SendMessage

Request

TypeScript Definition

Response

TypeScript Definition

SpecPlayers

Request

TypeScript Definition

Response

TypeScript Definition

Start

Request

TypeScript Definition

Response

TypeScript Definition

Status

Event

TypeScript Definition

SubscribeUpdates

Request

TypeScript Definition

Response

TypeScript Definition

Update

Event

TypeScript Definition