Changes between Version 3 and Version 4 of Random_Map_Generator_Internals

Timestamp:

Apr 6, 2011, 4:09:39 AM (13 years ago)

Author:

historic_bruno

Comment:

added more detail, corrected typos

Random_Map_Generator_Internals

@@ -3 +3 @@
 = 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 to read. 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.
+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, these are provided 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.
+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.
 
 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:
@@ -18 +18 @@
 }
 }}}
- * `size`: Integer. This is the size of the map in tiles (integer).
- * `height`: Flat array of 16-bit unsigned integers. This is the height data for each tile of the map.
+ * `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`: Flat 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`: Flat array of tile descriptors. Tile descriptors reference the terrain textures for a given tile and an optional priority for blending. The array must be arranged in patches, there are 16 tiles per patch.
- * `entities`: Flat array of entities.
+ * `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.