Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
365 lines (276 sloc) 13.5 KB

MASSim Scenario Documentation

Agents Assemble (2019)

Background Story

In the year 2090, ...


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.


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.


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.


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.


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.


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.

(TODO: example graphic)

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.


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.

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
  • 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"],
         "things": [
               "x": 0,
               "y": 0,
               "details": "",
               "type": "entity"
               "x": 0,
               "y": -5,
               "details": "",
               "type": "entity"
               "x": 2,
               "y": -1,
               "details": "b1",
               "type": "block"
         "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"
  • 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
  • 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, ...)
    • details: details about the thing (the block-type for blocks and dispensers)
  • 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


Each simulation configuration is one object in the match array.


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

  "attachLimit": 10,
  "blockTypes": [3, 3],
  "dispensers": [2, 3],

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

  "grid": {
    "height": 40,
    "width": 40,
    "file": "conf/maps/test.bmp"

  "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
  • grid:
    • height/width: dimensions of the environment
    • file: a bitmap file describing the map layout (see examples for more information)
  • 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:

  • 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)
You can’t perform that action at this time.