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:
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
.
unit_state[unit_id]
unit_state[unit_id]
(Type: object) Information for the given unit_id
.
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.
world
world
(Type: object ) Information on the world map.
tick
tick
(Type: number) The current game tick.
config
config
(Type: object) Configuration settings for the game environment. (Can be changed, see ⚙️ Environment Flags).
connection
connection
(Type: object) Information about your agent's connection with the game server.
📦 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.
🚩 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.
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.
🗺️ 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