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.
Required parameters:
role
can take one of the 3 following values:
Value | Description |
| (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. |
| Connect via the game client to watch a game being played by 2 other agents. |
| If the |
agentId
: specify eitheragentA
(Wizard) oragentB
(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:
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]
agents[agent_id]
(Type: object) Information for the given agent_id
.
| Type | Description |
| string | Agent identifier (either |
| array | List of unit IDs belonging to this agent. |
unit_state[unit_id]
unit_state[unit_id]
(Type: object) Information for the given unit_id
.
| Type | Description |
| array | [X,Y] location |
| number | Health points |
| object | Items owned by unit (currently just bomb ammo) |
| number | Number of bombs available to place (i.e. ammo) E.g. to get ammo for unit C: |
| number | Diameter of blast range for bombs placed by this unit |
| string | This unit's identifier (valid IDs: |
| string | The agent to which this unit belongs (either |
| number | Latest tick number after which this unit is no longer invulnerable (inclusive). E.g. |
entities
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.
| Type | Description |
| number | Tick on which this entity was created (0 = part of the initial world rendering) |
| number | x-coordinate |
| number | y-coordinate |
| string | One of:
|
| string | ID of the unit that owns this entity. |
| number | Tick on which this entity will perish from the map. E.g. a bomb placed with |
| number | Health Points taken before entity perishes |
| number | Diameter of blast range (if this entity is a bomb) |
world
world
(Type: object ) Information on the world map.
| Type | Description |
| number | # cells horizontally (Default: 15) |
| number | # |
tick
tick
(Type: number) The current game tick.
config
config
(Type: object) Configuration settings for the game environment. (Can be changed, see ⚙️ Environment Flags).
| Type | Description |
| number | Number of ticks per second |
| number | Number of ticks before end game fire starts |
| number | Number of ticks between each end-game fire spawn |
connection
connection
(Type: object) Information about your agent's connection with the game server.
| Type | Description |
| number | Used for managing your agent's connection to tournament servers (can be ignored). |
| string | Either agent, spectator, or admin. See 🧩 Roles. |
| 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) |
|
Wooden Block (destructible) |
|
Ore Block (destructible) |
|
Ammo pickup |
|
Blast radius powerup |
|
Bomb |
|
Explosion |
|
End-game fire |
|
🚩 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
Detonation
Movement
Unit state update
Entity expired
Entity spawned
Entity state update
🕹️ 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 ( |
Place bomb |
|
Move (up, down, left, right) |
|
Detonate bomb |
|
Request tick (Admin-only, see 🧩Connection) |
|
Example action packet:
⚙️ 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 |
| Enables/disables admin role (will be disabled in tournament mode) |
|
|
| Used for game connection | - |
|
| No. of ticks before ammo pickup perishes |
| 40 |
| If a spawn appears, weighting % that it will be an ammo (versus a powerup). |
| 0.9 |
| No. of ticks a bomb blast lasts for |
| 10 |
| No. of ticks before blast powerup perishes |
| 40 |
| If a spawn appears, weighting % that it will be a powerup (versus an ammo)
|
| 0.1 |
| No. of ticks before a bomb explodes |
| 40 |
| No. of ticks before a bomb can be remotely detonated |
| 5 |
| Probability of a spawn appearing somewhere on the map each tick |
| 0.025 |
| No. of ticks between each single tile of fire spawned |
| 2 |
| No. of ticks before ring of fire spawns |
| 300 |
| Time (ms) before game server starts after both agents connect |
| 2000 |
| Starting no. of ammo |
| 3 |
| Starting blast diameter for bombs (# of tiles including the bomb's tile) |
| 3 |
| Starting HP |
| 3 |
| No. of ticks an agent is invulnerable for |
| 5 |
| Disable/enable game server log outputs |
| 1 |
| Enables admin role (see 🧩 Roles). Agent actions are no longer tied to the clock and ticks need to be stepped through manually. |
| 0 |
| Disable/enable symmetrical map generation (on vertical axis) |
| 1 |
| Size of map (y-axis) |
| 15 |
| Size of map (x-axis) |
| 15 |
| Controls # of ore blocks in map |
| 0.0617.. |
| For game server communication | - | 3000 |
|
| 615035 | |
| Disable/enable shutdown of game server once game is over. |
| 1 |
| Controls # of steel blocks in map |
| 0.222... |
| No. of ticks per second |
| 10 |
| No. of players |
| 2 |
| Time that the game server will wait for agents to connect before disqualifying them (used for official tournament matches) |
|
|
| Controls # of wooden blocks in map |
| 0.246.. |
|
| 723470 |
🗺️ Map generation (PRNG_SEED
and WORLD_SEED
)
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 spawnsWorld 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:
The forward model agent is provided two connections (one to the game, and one to the forward model server)
The forward model can use the
ForwardState
class to invokenext(...)
with a sequence ID (used as a way to acknowledge the packet by the server)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.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