Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

MASSim Scenario Documentation

Agents Assemble (2019)

Background Story

In the year 2088, after 43 years of depleting Mars' natural resources, humankind now faces a drastically changed ecosystem. Building so many water wells has led to the surface becoming unstable, such that volcanic eruptions have become a regular sight. People have started rebuilding efforts, though they need specialised compounds which are durable enough to survive in the new circumstances. Thus, they once again rely on their trusty All-Terrain-Planetary-Vehicles - now equipped with robotic arms and pneumatic cleanup gear - sending them into particularly hazardous environments, where they can obtain the necessary materials.


The scenario consists of two teams of agents moving on a grid. The goal is to explore the world and acquire blocks to assemble them into complex patterns.

Agents can attach things to each of their 4 sides. When the agents move or rotate, the attached things move or rotate with them. Two agents can connect things that are attached to them to create more complex structures.

Tournament points are distributed according to the score of a team at the end of the simulation. Winning a simulation awards 3 points, while a draw results in 1 point for each team.


The environment is a rectangular grid. The dimensions are not known to the agents. Agents only perceive positions relative to their own. The x-axis goes from left to right (or eastwards) and the y-axis from top to bottom (southwards). Each cell of the grid contains up to one thing that may collide with other things (i.e. agents and blocks for now). Only in the beginning of the simulation, an agent shares the same cell with one agent of the other team/s (to ensure fairness). Once one of the agents has moved, they cannot overlap again later.


Each agent controls one entity in the simulation (s.t. we can use both terms interchangeably). Agents do not know their absolute positioning in the environment. They only know their energy level (used for clearing) and whether they are currently disabled. Agents automatically recharge 1 energy per step.

Config: match.maxEnergy

Disabled agents

If an agent becomes disabled, it loses all of its attachments and remains inactive for a fixed configurable number of steps. For as long as the agent is disabled, all its actions will result in failed_status. A disabled agent repairs itself and will work normally after a few steps.

Config: match.disableDuration


There are number of things that can inhabit a cell of the grid:

  • Entities: Each agent controls an entity on the grid. Entites can move around and attach themselves to other things.
  • Blocks: The building blocks of the scenario. Each block has a specific type. Agents can pick up blocks and stick multiple blocks together. Blocks have to be arranged into specific patterns to get score points.
  • Dispenser: Each dispenser can be used to retrieve a specific kind of block.
  • Marker: A marker marks a cell. Markers do not block other things. For now, markers are used for the clear action and clear events.


Each cell of the grid has a specific terrain type.

  • empty: If nothing else is specified, a cell is just a cell.
  • goal: Agents have to be on a goal cell in order to be allowed to submit a task.
  • obstacle: Obstacle cells are not traversable, i.e. they block movement and rotations that would involve the cell.


The environment randomly generates events.

Clear events

When a clear event happens, a certain area is marked similar to a clear action. The timing and size of an event is random. Each event can be perceived (i.e. its clear markers) for a few steps before it actually occurs. Once it resolves, the marked area is cleared (see the clear action for more details). Additionally, new obstacle terrain is created randomly around the center of the event (and not necessarily in the previously marked area).


  • chance - the chance for a clear event to start in any step (in %)
  • radius - the bounds for the event size
  • warning - the number of steps the area is marked before the event resolves
  • create - the bounds for how many obstacles are created (additional to the number of objects destroyed by the event)
  • perimeter - an additional radius where new obstacles may be created (added to the event's radius)


Tasks have to be completed to get score points. They appear randomly during the course of the simulation.

  • name: an identifier for the task
  • deadline: the last step in which the task can be submitted
  • reward: the number of score points that can be earned by completing the task
  • requirements: each requirement describes a block that has to be attached to the agent
    • x/y: the coordinates of the block (the agent being (0,0))
    • type: the required type of the block


In each step, an agent may execute exactly one action. The actions are gathered and executed in random order.

All actions have the same probability to just fail randomly.

Each action has a number of parameters. The exact number depends on the type of action. Also, the position of each parameter determines its meaning. Parameters are always string values.


The agent won't do anything this turn. Always successful (except for random fail).


Moves the agent in the specified direction.

No Parameter Meaning
0 direction One of {n,s,e,w}, representing the direction the agent wants to move in.
Failure Code Reason
failed_parameter Parameter is not a direction.
failed_path Cannot move to the target location because the agent or one of its attached things are blocked.
failed_forbidden New agent position would be out of map/grid bounds.


Attaches a thing to the agent. The agent has to be directly beside the thing.

No Parameter Meaning
0 direction One of {n,s,e,w}, representing the direction to the thing the agent wants to attach.
Failure Code Reason
failed_parameter Parameter is not a direction.
failed_target There is nothing to attach in the given direction
failed The thing could not be attached because the agent already has too many things attached OR the thing is already attached to an agent of another team.


Detaches a thing from the agent. Only the connection between the agent and the thing is released.

No Parameter Meaning
0 direction One of {n,s,e,w}, representing the direction to the thing the agent wants to detach from.
Failure Code Reason
failed_parameter Parameter is not a direction.
failed_target There was no attachment to detach in the given direction.
failed There was a thing but not attached to the agent.


Rotates the agent (and all attached things) 90 degrees in the given direction. For each attached thing, all intermediate positions for the rotation have to be free as well. For any thing, the intermediate rotation positions are those, which have the same distance to the agent as the thing and are between the thing's current and target positions.

No Parameter Meaning
0 direction One of {cw, ccw}, representing the rotation direction (clockwise or counterclockwise).
Failure Code Reason
failed_parameter Parameter is not a (rotation) direction.
failed One of the things attached to the agent cannot rotate to its target position OR the agent is currently attached to another agent.


Two agents can use this action to connect things attached to them. They have to specify their partner and the block they want to connect. Both blocks are connected (i.e. attached to each other) if they are next to each other and the connection would not violate any other conditions.


agent1 is on (3,3) and agent2 is on (3,7). agent1 has a block attached on (3,4) and one attached to that block on (3,5). agent2 has a block attached on (3,6). Both agents want to connect their attached blocks, namely those on (3,5) (of agent1) and (3,6) (attached to agent2). Then, agent1 has to perform connect(agent2,0,2), while agent2 has to perform connect(agent1,0,-1) in the same step. If both actions succeed, the blocks will be connected and still attached to both agents.

No Parameter Meaning
0 agent The agent to cooperate with.
1/2 x/y The local coordinates of the block to connect.
Failure Code Reason
failed_parameter First parameter is not an agent of the same team OR x and y cannot be parsed to valid integers.
failed_partner The partner's action is not connect OR failed randomly OR has wrong parameters.
failed_target At least one of the specified blocks is not at the given position or not attached to the agent or already attached to the other agent.
failed The given positions are too far apart OR one agent is already attached to the other (or through other blocks), or connecting both blocks would violate the size limit for connected structures.


Disconnects two attachments (probably blocks) of the agent.

No Parameter Meaning
0/1 attachment1 The x/y coordinates of the first attachment.
2/3 attachment2 The x/y coordinates of the second attachment.
Failure Code Reason
failed_parameter No valid integer coordinates given.
failed_target Target locations aren't attachments of the agent or not attached to each other directly.


Requests a new block from a dispenser. The agent has to be in a cell adjacent to the dispenser and specify the direction to it.

E.g. if an agent is on (3,3) and a dispenser is on (3,4), the agent can use request(s) to make a block appear on (3,4).

No Parameter Meaning
0 direction One of {n,s,e,w}, representing the direction to the position of the dispenser to use.
Failure Code Reason
failed_parameter Parameter is not a direction.
failed_target No dispenser was found in the specific position.
failed_blocked The dispenser's position is currently blocked by another agent or thing.


Submit the pattern of things that are attached to the agent to complete a task.

No Parameter Meaning
0 task The name of an active task.
Failure Code Reason
failed_target No active task could be associated with first parameter.
failed One or more of the requested blocks are missing OR the agent is not on a goal terrain.


Prepare to clear an area (a target position and the 4 adjacent cells).

  • The area is cleared after a number of consecutive successful clear actions for the same target position.
  • The action consumes a fixed amount of energy.

The effect of clearing a cell depends on the cells content:

  • obstacle terrain becomes normal terrain
  • blocks are destroyed
  • entities become disabled
No Parameter Meaning
0/1 target The x/y coordinates of the target position.
Failure Code Reason
failed_parameter No valid integer coordinates given.
failed_target Target location is not within the agent's vision radius or outside the grid.
failed_status The agent's energy is too low.
  • Config: match.clearSteps - number of action required for a successful clear
  • Config: match.clearEnergyCost - energy cost for a clear action (subtracted when the clear actually resolves)

all actions

All actions can also have the following failure codes:

Failure Code Reason
failed_random The action failed randomly.
unknown_action The action is unknown to the server.


Percepts are sent by the server as JSON files and contain information about the current simulation. Initital percepts (sent via SIM-START messages) contain static information while other percepts (sent via REQUEST-ACTION messages) contain information about the current simulation state.

The complete JSON format is discussed in

Initial percept

This percept contains information that does not change during the whole simulation. As mentioned in the protocol description, everything is contained in a simulation element.

Complete Example (with bogus values):

  "type": "sim-start",
  "content": {
    "time": 1556638383203,
    "percept": {
      "name": "agentA1",
      "team": "A",
      "steps": 700,
      "vision": 5
  • name: the agent's name
  • team: the name of the agent's team
  • steps: the sim's total number of steps

Step percept

This percept contains information about the simulation state at the beginning of each step.

Agents perceive the state of a cell depending on their vision. E.g. if they have a vision of 5, they can sense all cells that are up to 5 steps away.

Example (complete request-action message):

   "type": "request-action",
   "content": {
      "id": 1,
      "time": 1556636930397,
      "deadline": 1556636934400,
      "step" : 1,
      "percept": {
         "score": 0,
         "lastAction": "move",
         "lastActionResult": "success",
         "lastActionParams": ["n"],
         "energy": 300,
         "disabled": false,
         "things": [
               "x": 0,
               "y": 0,
               "details": "",
               "type": "entity"
               "x": 0,
               "y": -5,
               "details": "",
               "type": "entity"
               "x": 2,
               "y": -1,
               "details": "b1",
               "type": "block"
               "x": 2,
               "y": -1,
               "type": "marker",
               "details" : "clear"
         "terrain": {
            "goal": [[-4,-1],[-4,0],[-5,0]],
            "obstacle": [[4,-1],[4,0],[4,1]]
         "tasks": [
              "name": "task2",
              "deadline": 188,
              "reward" : 44,
              "requirements": [
                     "x": 1,
                     "y": 1,
                     "details": "",
                     "type": "b0"
                     "x": 0,
                     "y": 1,
                     "details": "",
                     "type": "b1"
                     "x": 0,
                     "y": 2,
                     "details": "",
                     "type": "b1"
         "attached": [[2,-1]]
  • score: the current team score
  • lastAction: the last action submitted by the agent
  • lastActionResult: the result of that action
  • lastActionParams: the parameters of that action
  • energy: the agent's current energy level
  • disabled: whether the agent is disabled
  • things: things in the simulation visible to the agent
    • x/y: position of the thing relative to the agent
    • type: the type of the thing (entity, block, dispenser, marker,...)
    • details: details about the thing
      • for blocks and dispensers: the block type
      • for entities: the team
      • for markers: the type of marker (i.e. clear)
        • clear: the cell is about to be cleared
        • ci: "clear_immediate" - a clear event will clear the cell in 2 steps or less
        • cp: "clear_perimeter" - the cell is in the perimeter of a clear event (i.e. new obstacles may be generated there as part of the event)
  • terrain: the terrain around the agent (if no value is given for a visible cell, the terrain is just empty)
  • task: a task taht is currently active
    • name: the task's identifier
    • deadline: the last step during which the task can be completed
    • reward: the score points rewarded for completing the job
    • requirements: the relative positions in which blocks have to be attached to the agent (the agent being (0,0))
      • x/y: the relative position of the required block
      • type: the type of the required block
      • details: currently not used
  • attached: an array of position arrays - each position represents a thing that is (directly or indirectly) attached to an entity


Each simulation configuration is one object in the match array.


  "id": "2019-SampleSimulation",
  "steps": 500,
  "randomSeed": 17,
  "randomFail": 1,

  "attachLimit": 10,
  "clearSteps" : 3,
  "clearEnergyCost" : 30,
  "disableDuration" : 4,
  "maxEnergy" : 300,

  "entities" : [
    {"standard": 10}

  "blockTypes": [3, 3],
  "dispensers": [5, 10],

  "grid" : {
    "height" : 50,
    "width" : 50,
    "file" : "conf/maps/test40x40.bmp",
    "instructions": [
      ["cave", 0.45, 10, 5, 4],
      ["line-border", 1],
      ["ragged-border", 3]
    "goals": {
      "number" : 3,
      "size" : [1,2]

  "tasks" : {
    "size" : [2, 4],
    "duration" : [100, 200],
    "probability" : 0.05

  "events" : {
    "chance" : 15,
    "radius" : [3, 5],
    "warning" : 5,
    "create" : [-3, 1],
    "perimeter" : 2

  "setup" : "conf/setup/test.txt"

For each simulation, the following parameters may be specified:

  • id: a name for the simulation; e.g. used in replays together with the starting time
  • steps: the number of steps the simulation will take
  • randomSeed: the random seed that is used for map generation and action execution
  • randomFail: the probability for any action to fail (in %)
  • attachLimit: the maximum number of things that can be attached to each other
  • blockTypes: upper and lower bounds for the number of block types
  • dispensers: upper and lower bounds for the number of dispenser per block type
  • entities: the number of entities (i.e. agents) per type
  • clearSteps: how often a clear action has to be executed to take effect
  • clearEnergyCost: how much an effective clear action costs
  • disableDuration: for how many steps an agent remains disabled
  • maxEnergy: an agent's initial and maximum energy level
  • grid:
    • height/width: dimensions of the environment
    • file: a bitmap file describing the map layout (see examples for more information)
    • instructions: an arbitrary number of map generation steps
      • cave: generates a cave like structure using a cellular automaton
        • 1st parameter: chance for a cell to start as an obstacle
        • 2nd parameter: number of iterations
        • 3rd parameter: min. number of obstacle neighbours for an empty cell to become an obstacle
        • 4th parameter: min. number of obstacle neighbours for an obstacle to remain an obstacle
      • line-border: creates a straight line of obstacles around the map
        • 1st parameter: width of the line
      • ragged-border: creates an irregular border around the map
        • 1st parameter: initial (and average) width of the border
    • goals:
      • number: number of goal areas
      • size: bounds for goal area radius
  • tasks:
    • size: bounds for the size of a tasks (i.e. number of blocks)
    • duration: bounds for a task's duration (i.e. number of steps)
    • probability: probability to create a new task in any step (0-1)
  • events:
    • chance: chance to generate an event in any step (0-100)
    • radius: bounds for the event radius
    • warning: number of steps the event area is marked before the event occurs
    • create: bounds for how many additional obstacles an event can create (besides those that were removed)
    • perimeter: an additional radius where new obstacles may be created (added to the event's radius)
  • setup: a file describing additional steps to be performed before the simulation starts
    • might be useful for testing & debugging
    • see examples for more information

Currently, there is only one standard agent role.


Currently, no special scenario commands are available. You may use a simulation setup file instead.


A few things are still planned for 2019/20:

  • agents pushing other agents/blocks..
  • more terrain options
  • add-ons (that agents can attach to themselves to unlock further actions)
  • NPCs (entities controlled by the server)