API Reference

Details on how to interact with the game environment.

🧩 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

Required parameters:

  • role can take one of the 3 following values:

Value

Description

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

Connect via the game client to watch a game being played by 2 other agents.

admin

If the TRAINING_MODE_ENABLED=1environment flag is set (see ⚙️ Environment Variables), 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 (Wizard) or agentB (Knight).

  • 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:

game_state
{
    "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 objects are 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"
        ]
    }
}

Property

Type

Description

agent_id

string

Agent identifier (either a or b)

unit_ids

array

List of unit IDs belonging to this agent.

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",
        "owner_id": "a",
        "invulnerability": 0
    }

Property

Type

Description

coordinates

array

[X,Y] location

hp

number

Health points

inventory

object

Items owned by unit (currently just bomb ammo)

bombs

number

Number of bombs available to place (i.e. ammo)

E.g. to get ammo for unit C:game_state["unit_state"]["c"]["inventory"]["bombs"]

blast_diameter

number

Diameter of blast range for bombs placed by this unit

unit_id

string

This unit's identifier (valid IDs: c, d,e, f,g,h)

owner_id

string

The agent to which this unit belongs (either a or b)

invulnerability

number

Latest tick number after which this unit is no longer invulnerable (inclusive). E.g. "invulnerability": 60 → this unit is invulnerable until tick 60.

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", 
        "owner_unit_id": "h", 
        "expires": 100, 
        "hp": 1, 
        "blast_diameter": 3
    }
],

Property

Type

Description

created

number

Tick on which this entity was created (0 = part of the initial world rendering)

x

number

x-coordinate

y

number

y-coordinate

type

string

One of:

a: Ammo b: Bomb x: Blast bp: Blast Powerup m: Metal Block o: Ore Block w: Wooden Block

ownerUnitId

string

ID of the unit that owns this entity.

expires

number

Tick on which this entity will perish from the map.

E.g. a bomb placed with expires=74 will explode on tick 74.

hp

number

Health Points taken before entity perishes

blast_diameter

number

Diameter of blast range (if this entity is a bomb)

world

(Type: object ) Information on the world map.

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

Property

Type

Description

width

number

# cells horizontally (Default: 15)

height

number

# cells vertically (Default: 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
},

Property

Type

Description

tick_rate_hz

number

Number of ticks per second

game_duration_ticks

number

Number of ticks before end game fire starts

fire_spawn_interval_ticks

number

Number of ticks between each end-game fire spawn

connection

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

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

Property

Type

Description

id

number

Used for managing your agent's connection to tournament servers (can be ignored).

role

string

Either agent, spectator, or admin. See 🧩 Roles.

agent_id

string

Whether you are Agent A or 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.

Entity

Properties

Metal Block (indestructible)

created, x, y, type=m

Wooden Block (destructible)

created, x, y, type=w, hp

Ore Block (destructible)

created, x, y, type=o, hp

Ammo pickup

created, x, y, type=a, expires, hp

Blast radius powerup

created, x, y, type=bp, expires, hp

Bomb

created, x, y, type=b, ownerUnitId, expires, hp, blast_diameter

Explosion

created, x, y, type=x, ownerUnitId, expires

End-game fire

created, x, y, type=x

"entities":[
   {
      # metal block (indestructible)
      "created": 0,
      "x":6,
      "y":0,
      "type":"m"
   }
]

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

Entity expired

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

Entity spawned

{
    "type": "entity_spawned",
    "data": {
        "created": 79,
        "x": 4,
        "y": 10,
        "type": "b",
        "ownerUnitId": "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.

Action

Required Properties (property: type | valid values)

Place bomb

type:string| 'bomb'

unit_id:string | 'a', 'b', 'c', ..

Move (up, down, left, right)

type:string| 'move'

move: string| 'up', 'down', 'left', 'right'

unit_id: string | 'a', 'b', 'c', ..

Detonate bomb

type:string| 'move'

coordinates: [number, number]| [x,y]

unit_id:string | 'a', 'b', 'c', ..

Request tick (Admin-only, see 🧩Connection)

type:string| 'request_tick'

Example action packet:

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

⚙️ Environment Flags

You can change the game environment's default variables by setting the appropriate flag in docker-compose.yml provided in the starter kits.

You will need to rebuild the game server (i.e. exit and re-run docker-compose up) each time you adjust environment variables.

Environment Variable

Description

Accepted Values

Default Value

ADMIN_ROLE_ENABLED

Enables/disables admin role (will be disabled in tournament mode)

0 or 1

1

AGENT_SECRET_ID_MAP

Used for game connection

-

agentA,agentB

AMMO_DURATION_TICKS

No. of ticks before ammo pickup perishes

int

40

AMMO_SPAWN_WEIGHTING

If a spawn appears, weighting % that it will be an ammo (versus a powerup). AMMO_SPAWN_WEIGHTING + BLAST_POWERUP_SPAWN_WEIGHTING = 1

float

0.9

BLAST_DURATION_TICKS

No. of ticks a bomb blast lasts for

int

10

BLAST_POWERUP_DURATION_TICKS

No. of ticks before blast powerup perishes

int

40

BLAST_POWERUP_SPAWN_WEIGHTING

If a spawn appears, weighting % that it will be a powerup (versus an ammo)

AMMO_SPAWN_WEIGHTING + BLAST_POWERUP_SPAWN_WEIGHTING = 1

float

0.1

BOMB_DURATION_TICKS

No. of ticks before a bomb explodes

int

40

BOMB_ARMED_TICKS

No. of ticks before a bomb can be remotely detonated

int

5

ENTITY_SPAWN_PROBABILITY_

PER_TICK

Probability of a spawn appearing somewhere on the map each tick

float

0.025

FIRE_SPAWN_INTERVAL_TICKS

No. of ticks between each single tile of fire spawned

int

2

GAME_DURATION_TICKS

No. of ticks before ring of fire spawns

int

300

GAME_START_DELAY_MS

Time (ms) before game server starts after both agents connect

int

2000

INITIAL_AMMUNITION

Starting no. of ammo

int

3

INITIAL_BLAST_DIAMETER

Starting blast diameter for bombs (# of tiles including the bomb's tile)

int

3

INITIAL_HP

Starting HP

int

3

INVULNERABILITY_TICKS

No. of ticks an agent is invulnerable for

int

5

TELEMETRY_ENABLED

Disable/enable game server log outputs

0 or 1

1

TRAINING_MODE_ENABLED

Enables admin role (see 🧩 Roles). Agent actions are no longer tied to the clock and ticks need to be stepped through manually.

0 or 1

0

SYMMETRICAL_MAP_ENABLED

Disable/enable symmetrical map generation (on vertical axis)

0 or 1

1

MAP_HEIGHT

Size of map (y-axis)

int

15

MAP_WIDTH

Size of map (x-axis)

int

15

ORE_BLOCK_FREQUENCY

Controls # of ore blocks in map

float

0.0617..

PORT

For game server communication

-

3000

PRNG_SEED

int

615035

SHUTDOWN_ON_GAME_END_ENABLED

Disable/enable shutdown of game server once game is over.

0 or 1

1

STEEL_BLOCK_FREQUENCY

Controls # of steel blocks in map

float

0.222...

TICK_RATE_HZ

No. of ticks per second

int

10

TOTAL_AGENTS

No. of players

int

2

TOURNAMENT_AGENT_CONNECTION

_GRACE_PERIOD_MS

Time that the game server will wait for agents to connect before disqualifying them (used for official tournament matches)

int

null

WOOD_BLOCK_FREQUENCY

Controls # of wooden blocks in map

float

0.246..

WORLD_SEED

int

723470

🗺️ Map generation (PRNG_SEEDand 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

This is still experimental. This feature is intended for agents to build simulations of potential future states (such as for Monte Carlo Tree Search).

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 participants who want to implement a game agent in a language of their choice.

⏫ Submission

Coming soon.

Last updated