🧩 Connection

Agents connect to the game server via websockets.

The provided starter kits will have this set up for you.

GAME_CONNECTION_STRING=ws://game-server:3000/?role=agent&agentId=agentId&name=python3-agent

Roles

role can take one of the 3 following values:

• agent- (Default) Connect as one of 2 agents that can send actions to the game server. If you connect as an agent via the game client, you can play as a human player.
• spectator - can connect to the game to observe the game - usually through the game client.
• admin - if the TRAINING_MODE_ENABLED=1 environment flag is set (see ⚙️ Environment Flags), agents in the admin role will be able to send admin packets that step through the game tick-by-tick (see the 'Request Tick' action in 🕹️ Action Packets).

agentId : specify either agentA or agentB.

name: (doesn't do anything right now)

🎮 Game State Definitions

Your agent receives information from the environment each tick as a JSON packet. In the starter kits, this packet is stored in game_state.

The first game_state your agent receives will contain a full state of the environment. Example:

{
    "agents": {
        "a": {
            "agent_id": "a",
            "unit_ids": [
                "c",
                "e",
                "g"
            ]
        },
        "b": {
            "agent_id": "b",
            "unit_ids": [
                "d",
                "f",
                "h"
            ]
        }
    },
    "unit_state": {
    ...
    },
    "entities": [
        {
            "created": 0,
            "x": 11,
            "y": 7,
            "type": "m"
        },
        {
            "created": 0,
            "x": 12,
            "y": 4,
            "type": "o",
            "hp": 3
        }
    ],
    "world": {
        "width": 15,
        "height": 15
    },
    "tick": 0,
    "config": {
        "tick_rate_hz": 10,
        "game_duration_ticks": 1800,
        "fire_spawn_interval_ticks": 5
    },
    "connection": {
        "id": 1,
        "role": "agent",
        "agent_id": "b"
    }
}

After the first game_state, packets received from the server contain only the latest updates to the game environment. The provided starter kits handle the simulation logic and will return game_state in full for your agent. If you are building an agent from scratch, you will need to implement this simulation logic as well.

The following environment data is available from the game server:

agents[agent_id]

(Type: object) Information for the given agent_id.

"agents": {
    "a": {
        "agent_id": "a",
        "unit_ids": [
            "c",
            "e",
            "g"
        ]
    },
    "b": {
        "agent_id": "b",
        "unit_ids": [
            "d",
            "f",
            "h"
        ]
    }
}

unit_state[unit_id]

(Type: object) Information for the given unit_id.

"unit_state": {
    "c": {
        "coordinates": [
            3,
            10
        ],
        "hp": 3,
        "inventory": {
            "bombs": 3
        },
        "blast_diameter": 3,
        "unit_id": "c",
        "agent_id": "a",
        "invulnerable": 0,
        "stunned": 0
    }

entities

(Type: array of objects) A list of entities (e.g. blocks, explosions) on the map. Does not include players/units. See 📦 Game Entities for a full list of entities and how they will appear.

"entities": [
    {
        "created": 60,
        "x": 3,
        "y": 9,
        "type": "b",
        "unit_id": "h",
        "expires": 100,
        "hp": 1,
        "blast_diameter": 3
    }
],

world

(Type: object) Information on the world map.

"world": {
    "width": 15,
    "height": 15
}

tick

(Type: number) The current game tick.

"tick": 75

config

(Type: object) Configuration settings for the game environment. (Can be changed, see ⚙️ Environment Flags).

"config": {
    "tick_rate_hz": 10,
    "game_duration_ticks": 1800,
    "fire_spawn_interval_ticks": 5
},

connection

(Type: object) Information about your agent's connection with the game server.

"connection": {
    "id": 1,
    "role": "agent",
    "agent_id": "b"
}

📦 Game Entities

entities are provided in game_state and represent objects in the game.

Below is a list of all available entities and their required properties. For a description of the properties, see 🎮 Game State Definitions.​

🚩 Server Packets (Events)

On each tick, the game server will send a server packet containing updates to the game environment. These packets conform to validServerPacket in the validation schema.

The provided starter kits use the server packets to update and return game_state for you.

Below is a list of the possible event types (in the order they are executed). See 🎮 Game State Definitions for a description of each property.

Bomb placements

{
    "type": "unit",
    "agent_id": "b",
    "data": {
        "type": "bomb",
        "unit_id": "h"
    }
}

Detonation

{
    "type": "unit",
    "agent_id": "b",
    "data": {
        "type": "detonate",
        "coordinates": [10, 10],
        "unit_id": "h"
    }
}

Movement

{
    "type": "unit",
    "agent_id": "b",
    "data": {
        "type": "move",
        "move": "up",
        "unit_id": "h"
    }
}

Unit state update

{
    "type": "unit_state",
    "data": {
        "coordinates": [4, 10],
        "hp": 3,
        "inventory": {
            "bombs": 1
        },
        "blast_diameter": 3,
        "unit_id": "h",
        "owner_id": "b",
        "invulnerability": 0,
        "stunned": 0
    }
}

Entity expired

{
    "type": "entity_expired",
    "data": [4, 10]
}

Entity spawned

{
    "type": "entity_spawned",
    "data": {
        "created": 79,
        "x": 4,
        "y": 10,
        "type": "b",
        "unit_id": "h",
        "expires": 119,
        "hp": 1,
        "blast_diameter": 3
    }
}

Entity state update

{
    "type": "entity_state",
    "coordinates": [10, 9],
    "updated_entity": {
        "created": 275,
        "x": 10,
        "y": 9,
        "type": "a",
        "expires": 315,
        "hp": 0
    }
}

🕹️ Action Packets

On each tick, the game server accepts one action packet per unit per agent.

An action packet must conform to the validation schema (ValidAgentPacket). The starter kits provide an interface for sending actions.

The available action packets are detailed below.

Example action packet:

action_packet = {
    type: "bomb",
    unit_id: "c"
}

🔐 Administrator API

Full reference found on our github

Requirements:

1. You must have ADMIN_ROLE_ENABLED=1 flag set to use this feature.
2. You must be connected as the admin role to send these packets.

Reset game

Allows you to restart or renew the game instead of having to restart the game engine. You can also provide an optional prng_seed and world_seed property to reset the game with. (Also available in the administrator UI).

export interface RequestGameReset {
    readonly type: "request_game_reset";
    readonly world_seed?: number;
    readonly prng_seed?: number;
}

Tick through the game manually

You need to have TRAINING_MODE_ENABLED=1 configured for the engine to use this.

Allows you to step through a game tick by tick to get a better grasp of what is happening. (Also available in the administrator UI).

{
    "type": "request_tick"
}

Get next game state

You need to have TRAINING_MODE_ENABLED=1 configured for the engine to use this.

This allows you to get the next state of the game given a game_state and a list of actions as defined by the typescript schema below:

export interface EvaluateNextStatePacket {
    readonly type: "next_game_state";
    readonly sequence_id: number;
    readonly state: GameState;
    readonly actions: Array<{
        readonly agent_id: string;
        readonly action: AgentPacket;
    }>;
}

The response will be the next game state as evaluated by the game engine.

⚙️ Environment Flags

The environment's default variables can be changed by setting the appropriate flag in docker-compose.yml.

You will need to add the --build flag when restarting the game engine (i.e. docker-compose --build).

🗺️ Map generation (using PRNG_SEED and WORLD_SEED)

Maps are symmetrically and pseudo-randomly generated.

By default, the same map will be generated each time the game is loaded. You can change this by changing the environment variables:

• Game Seed PRNG_SEED: stochasticity of the game and item spawns

• World Seed WORLD_SEED: generation of the first game map (placement of blocks etc)

Both can be set to an integer value between 0 and 9,007,199,254,740,991.

Remember to vary the game/world seeds so that your agent doesn't overfit to the default map.

Some seeds will generate invalid maps.

🔼 Forward Model

The forward model will not be provided in tournament servers. You can still use the forward model for your own training purposes, but this feature is still experimental. This feature is intended for agents to build simulations of potential future states (such as for Monte Carlo Tree Search).

If you're interested in this feature, please get in touch with us on Discord or email so we can improve on it!

We've provided starter kits for implementing an agent that uses a forward model (_fwd) to simulate actions in the game state.

At a high level:

1. The forward model agent is provided two connections (one to the game, and one to the forward model server)

2. The forward model can use the ForwardState class to invoke next(...) with a sequence ID (used as a way to acknowledge the packet by the server)

3. When a response is received the callback _on_next_game_state is invoked and the object passed into it contains the same sequence ID so the agent can map it to whatever data store / object and use that to make decisions.

4. An example of all the packets is included in the JSON-schema definition for users who want to implement a game agent in a language of their choice.