[[TOC]]

= The random map generator =

There is a random map generator integrated with the engine. Random map scripts (RMS) are implemented in Javascript with a minimal C++ interface, see [wiki:Random_Map_Generator_Internals Random Map Generator Internals].

== Playing Random Maps ==

Random maps can be played through the game setup, by choosing Random from the Match Type dropdown. See the [wiki:Manual_SettingUpAGame Gameplay Manual] for more details.

== Guide to !JavaScript ==

The game supports scripts written in Javascript, which are used for random maps, game logic, and AIs. The engine uses the [https://developer.mozilla.org/en/SpiderMonkey SpiderMonkey] library to implement the language. References for those interested in Javascript programming:
 * https://developer.mozilla.org/en/JavaScript
 * http://msdn.microsoft.com/en-us/library/6974wx4d

== Guide to Random Map Scripting ==

Basically a random map script is responsible for all the logic of generating a map: modeling terrain, placing units and resources, and then returning the data to the engine. In practice, most of the logic is hidden by APIs also implemented in JavaScript. We have added the concept of libraries for this purpose.

Random map scripts are placed in the `maps/random/` directory (see [wiki:Mod_Layout mod layout]). In addition to the script itself, there is also an associated [wiki:JSON] data file. This file is loaded by game setup to recognize a new random map, and it includes various settings, see [wiki:Random_Map_Generator_Internals#DefiningtheMap defining the map] for details.

=== Load libraries ===

A random map script should first load any libraries it will need. Libraries are stored in the game data directories under `maps/random/libraryName/`. When a library is loaded, all scripts in that directory are parsed and their code made available to the random map script. They are loaded through the function call `Engine.LoadLibrary(libraryName)`.

=== Initialize the library ===

The next step is to initialize the library. This may vary, but for rmgen, you would call `InitMap()`.

=== Save the results ===

The random map script should end with a call to `Engine.ExportMap(data)`, which returns all the map data back to the engine. In rmgen this is abstracted by a call to `ExportMap()`. For the exact format of the data see [wiki:Random_Map_Generator_Internals Random Map Generator Internals].

'''Note:''' The export map function does a coordinate conversion from the 2D used in the rmgen libs to 3D for the engine. You should only use it once, only after the map is fully generated.

=== Design Tips and Conventions ===

* Maps should be round, not square.
 * Square maps in atlas are deprecated.
 * Round maps avoid sharp corners, hence more esthetical.
 * The minimap is round, so square maps don't fit.
 * On circular maps, all locations are equally reachable from the center of the map, while Civic Centers in corners of square maps are hard to reach (not considering terrain).

* Place terrain over an area rather than a tile. Most times placing tiles only looks unnatural. In addition remember terrain from the same biome fits better to each other than tiles from different biomes.

* In a player's starting area, not many obstructions should be placed within a radius of 20 tiles, so the player has space to build a base there. Large clumps of trees can be problematic. Especially avoid placing very uneven terrain and water there. Remember that Iberians get walls as a civilization bonus which are placed by default with their starting entities and have roughly a radius of 20 tiles.

* A player's starting buildings should be rotated uniformly to face the player's initial camera view. A rotation of about `-PI/4` is standard. Starting units should be grouped together neatly.

* Placed entities (especially trees) shouldn't obstruct the player's initial view of their units and structures.

* Don't place entities outside the reachable map area (That causes problems with AIs).

* Match the aesthetics of hand-crafted scenarios as much as possible.

== Roadmap / To do ==

* Colliding entity detection: On many maps there are entities like trees or chicken in Iberian walls or the Civic Center. To make sure this will not happen we need a finer grained collision detection than tile based. An implementation can be found [[https://wildfiregames.com/forum/index.php?/topic/16242-random-maps-suggestions-bug-reports-and-ideas-about-random-maps-here/&do=findComment&comment=297548|here]]. Components involved: Map, placers, areas, constraints

* Obstructed tile detection: A way to detect areas of partially and fully obstructed tiles by an entity either already placed or with the information of how it is to be placed should be available to avoid placing e.g. terrain entities there. This is missing and relatively straight forward to add with the entity information available in RMGen. This should include the wall builder though more complex entity placements like this should IMO be done first during map generation so later obstruction can be avoided by constraining the partially obstructed tiles. Components involved: Areas, map, placers, wallbuider, constraints.

* Unreachable tile detection: While this is tricky and may be fully implemented in part 2 (unifying simulations and RMGen by generating maps while the engine is running) some measures can be taken on a lib level to make things easier for the map author. That mainly includes turning entities outside of the playable map to their corresponding actors instead but also a flood fill method to detect every player can reach every other player or e.g. gatherable entities. Components involved: Constraints, painters.

* Unbuildable tile detection: A way to - at least roughly - detect tiles that can or cannot be build on in-game are needed to avoid placement of e.g. walls on terrain the player can not build on in-game (or even reach with melee units). Components involved: Areas, constraints, map.

* Painter/placer support: Unifying all functionality that can be used with painters/painters to have a painter or placer. Examples for that would be the diamond square terrain generation and the starting entity placement. There are likely a lot more that has to be found and listed e.g. in [[https://wildfiregames.com/forum/index.php?/topic/16242-random-maps-suggestions-bug-reports-and-ideas-about-random-maps-here/|The Random Map Forum Topic]]. Components involved: Painters, placers, areas, constraints.

== Available Libraries ==

Here's a list of libraries currently included with the map generator:

 * [wiki:Rmgen_Library rmgen]
 * [wiki:Heightmap_Library heightmap]
 * [wiki:Rmgen2_Library rmgen2]
 * [wiki:Random_Biome_Library]