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.