API Reference
Details on how to interact with the game environment.
Agents connect to the game server via websockets.
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. |
spectator | |
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). |
agentId
: specify eitheragentA
(Wizard) oragentB
(Knight).name
: (doesn't do anything right now)
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:
(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. |
(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. |
(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) |
(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) |
(Type: number) The current game tick.
"tick": 75
(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 |
(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 | |
agent_id | string | Whether you are Agent A or B. |
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"
}
]
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.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.
{
"type": "unit",
"agent_id": "b",
"data": {
"type": "bomb",
"unit_id": "h"
}
}
{
"type": "unit",
"agent_id": "b",
"data": {
"type": "detonate",
"coordinates": [
10,
10
],
"unit_id": "h"
}
}
{
"type": "unit",
"agent_id": "b",
"data": {
"type": "move",
"move": "up",
"unit_id": "h"
}
}
{
"type": "unit_state",
"data": {
"coordinates": [
4,
10
],
"hp": 3,
"inventory": {
"bombs": 1
},
"blast_diameter": 3,
"unit_id": "h",
"owner_id": "b",
"invulnerability": 0
}
}
{
"type": "entity_expired",
"data": [
4,
10
]
}
{
"type": "entity_spawned",
"data": {
"created": 79,
"x": 4,
"y": 10,
"type": "b",
"ownerUnitId": "h",
"expires": 119,
"hp": 1,
"blast_diameter": 3
}
}
{
"type": "entity_state",
"coordinates": [
10,
9
],
"updated_entity": {
"created": 275,
"x": 10,
"y": 9,
"type": "a",
"expires": 315,
"hp": 0
}
}
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', .. |
type: string | 'request_tick' |
Example action packet:
action_packet = {
type: "bomb",
unit_id: "c"
}
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 |
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.
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 invokenext(...)
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.
Coming soon.
Last modified 2yr ago