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
See 🗺️ Map generation​
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
See 🗺️ Map generation​
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.

References - Previous

Environment Overview

Next - References

Submission Instructions

Last modified 2yr ago

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=1`environment 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).

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'`

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`	See 🗺️ Map generation	`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`	See 🗺️ Map generation	`int`	723470

API Reference

🧩 Connection

🎮 Game State Definitions

`agents[agent_id]`

`unit_state[unit_id]`

`entities`

`world`

`tick`

`config`

`connection`

📦 Game Entities

🚩 Server Packets (Events)

Bomb placements

Detonation

Movement

Unit state update

Entity expired

Entity spawned

Entity state update

🕹️ Action Packets

⚙️ Environment Flags

🗺️ Map generation (`PRNG_SEED`and `WORLD_SEED`)

🔼 Forward Model

⏫ Submission

`Property`	Type	Description
`agent_id`	string	Agent identifier (either `a` or `b`)
`unit_ids`	array	List of unit IDs belonging to this agent.

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`