Version 6 (modified by 13 years ago) ( diff ) | ,
---|
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.
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)
- return 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.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": [ { "idx" : 0x0001, "priority" : 0 }, ... ] "entities": [ { "id" : 100, "name" : "units/hele_support_female_citizen", "x" : 102.4, "z" : 64.8, "angle" : 0.86}, ... ] }
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.entities
: Array of entity objects. Entities specify something like a tree, unit, or building in the game.
Tile descriptor format
{ "idx" : 8, "priority" : 0 }
idx
: Integer. Texture ID to be used (value is referenced fromtextureNames
array).priority
: Integer. Optional priority for texture blending (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, "name": "units/hele_support_female_citizen", "x": 102.4, "z": 64.8, "angle": 0.86
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
,z
: Float. Position of the entity on the map (in XZ map coordinates; 4.0 map units = 1.0 tile unit).angle
: Float. Rotation of the entity about y-axis (vertical), in radians.
CMapReader is responsible for parsing this data and creating the map, in a process very similar to that for scenarios.