Game Admin Guide

• 1: Map Definition
• 1.1: Small Map
• 1.2: Maze
• 1.3: Arena

1 - Map Definition

In Microservice Dungeon, the maps are custom-created. A game can be started based on a specific map type. This section explains how to specify such a map type.

There is a REST API that can be used to create a new map type (TODO provide link to OpenApi). Basically, a map type is described by a complex JSON structure. This structure contains of the following major parts:

1. Base attributes (name, description, dimensions)
2. Gravity zones
3. Tile type zones (with planets or voids), determining the basic map structure
4. Planet type distribution zones (space stations, black holes, mines)
5. Replenishment zones (to define where resources will be replenished during the game)

The above simplified domain model shows the five components of a map definition. The actual JSON syntax will be shown by example, based on three sample maps¹, in the coming subsections.

Base Attributes (1)

For each map type, the map dimension is given as the coordinate of the top-right corner. As explained in the Game Rules section, the map coordinate in the left bottom corner is (0,0), and x-/y-coordinates increase to the top and to the right. In addition to that, a map type has a distinctive name, and a brief description that can be used in a UI for selecting it as base for a game.

Zone Definitions

All four components of a map definition basically consist of ordered lists of map zones. A map zone can cover a part of the map, or the complete map. Each zone is stacked on top of the previous zones in the list. If zones overlap, then the top zone overrides the settings on those below.

A zone can be one of three types:

• tile
• rectangle
• ring

Tile Zone

A single tile is just defined by its coordinate.

Rectangle Zone

A rectangle zone is specified by its lower-left and its upper-right corner coordinate (that would be (2,2) and (6,4) in the above example).

Ring Zone

A ring zone uses the fact that a rectangular map can be decomposed into rings of tiles, starting with ring no. 0 at the map edge (see above). A ring zone is therefore defined by its “from” and “to” ring indices (0…1 in our example).

Gravity Zones (2)

The first thing to be defined for a map are the gravity zones. This is an ordered list of the value objects as depicted below.

Note that this section can also be incomplete or empty. Each map tile that hasn’t been specified is assumed to have a medium gravity level of 2. The gravity level is a simple domain primitive, with constants 1 … 3.

Tile Type Zones (3)

This section of a map definition determines the basic map structure. It is an ordered list of zones containing planets, and zones containing voids.

This section, too, can be incomplete or empty. The default for unspecified map tiles is void.

Planet Type Distribution Zones (4)

This section of the map definition determines the distribution of space stations, black holes, and resource mines.

The type attribute for the PlanetUsageType is a simple enum (space_station | black_hole | mine). There is no type for empty planets. Planets are all considered empty unless a usage is assigned to them. The distribution is done randomly within the given zone. (If you want to place a certain usage, for example a space station, to a specific location on the map instead of a random location, you need to use a tile zone.)

If the assigned usage is mine, then its resource type also needs to be specified in the attribute resource. The is also a domain primitive in the shape of a simple enum (bio_matter | cryo_gas | dark_matter | ion_dust | plasma_cores).

The ordered list of planet type distribution zones can be empty, but the overall map needs to have at least one space station capable of spawning robots. If the list of distribution zones does not contain such a space station, one will be assigned randomly at the end of processing the planet types.

Specifying the number of usages to be assigned

The number of usages (e.g. space stations) that should be assigned to planets in the given zone is defined by the attribute count. Its type CountType allows to specify either

• a fixed number (e.g. 5 space stations), or
• a number relative to the number of empty planets in the zone (e.g. 10% of the empty planets in the zone to be assigned a space station), or
• a number relative to the total number of players in the game (e.g. 1 space stations per player, plus 2 extra).

For simplicity reasons, count type is a string allowing a simple expression with predefined keywords like this:

• 5
• empty_planets * 0.1
• players + 2

More formally, the syntax is defined as follows:

CountType = FixedCount | EmptyPlanetsCount | PlayersCount;
FixedCount = <integer>;
EmptyPlanetsCount = "empty_planets" Operator <float>;
PlayersCount = "players" Operator <float>;
Operator = "+" | "-" | "*" | "/";

Multiple distribution zones can overlay each other. Note that the empty planets meta counter always refers to the amount of planets still empty after having applied the previous distribution zones. So, if you have a rectangle with 12 planets, and 5 of them have already been assigned in zones specified prior to this zone, then empty_planets amounts to 7.

Results of an Operator expression are always rounded up to the next full integer. Evidently there are illegal expressions: For instance empty_planets + 2 is evidently unfulfillable and will be rejected as a faulty specification.

Replenishment Zones (5)

Replenishment zones are used to define where resources will be replenished during the game, when exhausted by mining. The ordered list of replenishment zones forms the last section of a map definition. This section can be empty or incomplete.

A replenishment zone always relates to all the resource mines within that zone. The mines can be filtered by specifying the attribute onlyForResource. If this attribute is omitted or null, then all resource mines in the zone, regardless of their resource, are affected by the replenishment. If the attribute is set to a specific resource type, then only those mines of that resource type are affected. The resource types are the same as in planet type distribution zones, namely bio_matter | cryo_gas | dark_matter | ion_dust | plasma_cores.

The replenishment itself is defined by two attributes:

• threshold: This is an integer value defining a stock level in the resource mine. When the stock level of the mine is equal to or below this threshold, then the replenishment is triggered.
• replenishBy: This is an integer value defining how many resource units are added to the stock of the mine when the replenishment is triggered.

The attribute location can have the values existing or new.

• existing: The replenishment is done at the resource mine where the stock level is at or below the threshold. The mine continues to exist, just its stock is increased by the replenishBy value.
• new: The mine at the location where the stock level is at or below the threshold is closed (removed). A new resource mine is created at a random empty planet within the same zone, with an initial stock equal to the replenishBy value. With this option, resource mines “move around” the map during the game.

If no replenishment zones are specified, then the resources on the map are just decreasing and will not be replenished during the game.

1.1 - Small Map

The Small Map is a “MSD map in a nutshell”. It just has 70 (10 x 7) tiles, suitable only for a small number of players (<= 5), otherwise the map will be too crowded to provide much fun.

(tbd: detailed description)

1.2 - Maze

(todo: description of the map)

1.3 - Arena

(todo: description of the map)