For Alpha 5, there will be a random map generator integrated with the engine. This document describes the interaction between the engine and the random map scripts.

Generating the Map

When loading a scenario, the CMapReader class simply reads an XML file (with map settings, list of entities, and other textual data) together with a binary file called a PMP (which specifies height map and terrain textures). For a random map, there is obviously no predefined map data to load. Instead, the engine uses a new CMapGenerator class. The CMapGenerator needs the name of a random map script and some settings, such as number of players and their civs. These are selected during game setup.

The CMapGenerator provides a few things for the random map scripts. One is a global variable g_MapSettings which specifies all the map settings as created by game setup. CMapGenerator also exposes two JavaScript functions: RMS.LoadLibrary(name) and RMS.ExportMap(data). LoadLibrary is used for choosing the API to which a random map script will have access. ExportMap is used to return generated map data from the scripts to the engine.

Data format

The data from a random map script must be in an exact format, independent of the methods used to generate it. This format can be specified in JSON as follows:

{
  "size": 128,
  "height": [ 1000, ... ]
  "seaLevel": 20.0,
  "textureNames": [ "medit_grass_field_a", ... ]
  "tileData": [ { "texIdx1" : 0x0001, "texIdx2" : 0xFFFF, "priority" : 0 }, ... ]
  "entities": [ { "id" : 100, "name" : "units/hele_support_female_citizen", "x" : 102.4, "y" : 64.8, "angle" : 0.86, "isActor" : false}, ... ]
}

• size: Integer. This is the size of the map in tiles.
• height: Array of 16-bit unsigned integers. This is the height data for each tile of the map.
• seaLevel: Float. This is the height of the sea, the value in the heightmap for which all lower terrain will be under water.
• textureNames: Array of strings. This is the terrain textures used. They must be in the order in which they were defined (as they are referenced by tile data).
• tileData: Array of tile descriptor objects. Tile descriptors reference the terrain texture(s) for a given tile. The array must be arranged in patches; there are 16 tiles per patch.
• entities: Array of entity objects. Entities specify something like a tree, unit, or building in the game.

Tile descriptor format:

{
  "texIdx1" : 8,
  "texIdx2" : 2,
  "priority" : 0
}

• texIdx1: Integer. Primary texture to be used (value is referenced from textureNames array).
• texIdx2: Integer. Optional secondary texture to be used (value of 0xFFFF for none).
• priority: Integer. Optional priority for texture blending (value of 0 is default). TODO: Explain how this works.

Entity format:

  "id": 1034,
  "name": "units/hele_support_female_citizen",
  "x": 102.4,
  "y": 64.8,
  "angle": 0.86,
  "isActor": false

• id: Integer. Unique ID of this entity, used by the engine to identify each instance.
• name: String. Template name of the entity, usually specifies faction and unit/building type for players, or special gaia templates.
• x, y: Float. Position of the entity on the map (in tiles).
• angle: Float. Rotation of the entity about y-axis.
• isActor: Bool. This flags tells the map reader whether this entity is an actor or not.

CMapReader is responsible for parsing this data and creating the map, in a process very similar to that for scenarios.