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.

Engine-script interface

The CMapGenerator provides a minimal interface to 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 some JavaScript functions:

• RMS.LoadLibrary(name) - load a library, choosing the API to which a random map script will have access, e.g. "rmgen".
• RMS.ExportMap(data) - export generated map data from the scripts to the engine.
• RMS.SetProgress(percent) - set the map generation progress percentage, so the loading screen progress bar can be updated. Percentage must be an integer 1-100.
• RMS.GetCivData() - returns an array of civilization data from /civs/*.json, which is useful for determining civ-specific units and structures.
• RMS.MaybeGC() - possibly run the garbage collector.

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": { "index": [0, 1, 0, 0, 2, ... ], "priority": [0, 1, 0, 0, 2, ... ] }
  "entities": [ { "id": 100, "templateName": "units/hele_support_female_citizen", "position": {"x": 102.4, "y": 0, "z": 64.8}, "rotation": {"x": 0, "y": 0.86, "z": 0} }, ... ]
}

• size: Integer. This is the size of the map in tiles.
• height: Flat 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: Object. Contains two flat arrays specifying terrain tile data for the map - see below.
• entities: Array of entity objects. Entities specify something like a tree, soldier, or building in the game - see below.

Tile Data

{
  "index" : [0, 1, 0, 0, 2, ... ],
  "priority" : [0, 1, 0, 0, 2, ... ]
}

Originally this was an array of tile descriptor objects but the size of the resulting map data was greatly reduced by using two typed arrays. This data does not need to consider patches, this will all be handed by CMapReader.

• indexes: Flat array of 16-bit unsigned integers. Texture ID to be used for each tile (value is referenced from textureNames array).
• priority: Flat array of 16-bit unsigned integers. Optional priority for texture blending each tile (value of 0 is default). Considering adjacent tiles, the texture with higher priority will be blended on top of the tiles with lower priorities.

Entity format

  "id": 1034,
  "templateName": "units/hele_support_female_citizen",
  "position": {"x": 102.4, "y": 0, "z": 64.8},
  "rotation": {"x": 0, "y": 0.86, "z": 0}

• id: Integer. Unique ID of this entity, used by the engine to identify each instance.
• templateName: String. Template name of the entity, usually specifies faction and unit/building type for players, or special gaia templates.
• position: 3D vector object. Position of the entity, in map coordinates (4.0 map units = 1.0 tile unit). Note: the y position (height) is not currently supported.
• rotation: 3D vector object. Rotation of the entity, in radians. Note: only rotation about y-axis (vertical) is currently supported.

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