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:

  • 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"
        ]
    }
}

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
    }

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
    }
],

world

(Type: object ) Information on the world map.

"world": {
    "width": 15,
    "height": 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
},

connection

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

"connection": {
    "id": 1,
    "role": "agent",
    "agent_id": "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.

"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.

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.

🗺️ 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