Changes between Version 2 and Version 3 of Rmgen_Library
- Timestamp:
- Jul 9, 2011, 2:18:32 AM (13 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Rmgen_Library
v2 v3 1 [[TOC]] 1 2 Rmgen is the name of the default script library included with the random map generator. This document describes how to use it. 2 3 3 = Map Coordinate System=4 == Map Coordinate System == 4 5 5 6 The map uses the same x,z coordinate system as in-game, with all units, including those for height, equal to the size of 1 tile (which is actually 4.0 model-space units). This seemed less confusing because most people will think in terms of tiles. 6 7 7 = Terrains=8 == Terrains == 8 9 9 10 The concept of terrains in rmgen is more than just textures that are painted onto a tile. As part of the terrain, a tile can also have objects on it that are "attached" to the terrain and hence removed when the tile is painted with a different terrain (for example, if you paint a forest and then paint a patch of desert inside of it, there will be no trees on the desert). Furthermore, API functions that require terrains can also take a number of complex objects that might paint different tiles with different textures but still make up one type of "logical terrain" (for example, something that paints mixed types of dirt for variation). The following ways of specifying a terrain are available: … … 15 16 '''TODO:''' Later it should be possible to provide custom JS terrain objects as well. 16 17 17 = Accessing Map Data Directly=18 == Accessing Map Data Directly == 18 19 19 20 The lowest-level way to create a map is to set terrain and elevation for each tile specifically and place objects individually. Although this is often not what you'll want to use for ease-of-use reasons, there might be cases (such as non-standard gameplay maps) where you might want to do something not possible with the higher-level API. Thus, the API provides functions that give complete control over the map to allow this: … … 24 25 * 25 26 26 = Placing Terrain: Areas=27 == Placing Terrain: Areas == 27 28 28 29 The core concept of terrain placement is that of ''areas''. An area is a set of tiles of related terrain that constitutes a feature of the map, such as a body of water, a forest, etc. Once you have placed areas, you can also refer to them to control placement of other areas or objects; for example, place gold mines only on dirt patch areas, place fish only on water areas, or make forests avoid player base areas. … … 37 38 This section will talk about area placers and painters; full information on constraints can be found in the Constraints section below. 38 39 39 == Creating a single area==40 === Creating a single area === 40 41 41 42 The simplest way to create an area is using the `createArea(placer, painter, constraint)` function. This takes a given placer object and tries to place the area within the given constraint. If it succeeds, it paints the area and returns the area object. If it fails, it returns `undefined` and does not change any terrain. (You can check for failure with `if(createArea(...) === undefined)`). 42 43 43 == Creating multiple areas at random locations==44 === Creating multiple areas at random locations === 44 45 45 46 For many areas, you do not want to specify an exact location for the area placer, you just want to place it at a random place that satisfies the constraint you provide. You might also want to create several similar areas using the same placer and painter but in different locations within the same constraints. Thus, the most common way to place areas is using the `createAreas(centeredPlacer, painter, constraint, number, retryFactor)` function. This takes 5 parameters: … … 51 52 It returns an array of the areas placed (or an empty array if none). 52 53 53 == Area placers==54 === Area placers === 54 55 55 56 The following area placers are available. Centered placers can be used with `createAreas`. Note that most objects have editable fields of the same names as its constructor parameters after you construct it. 56 57 57 === Centered placers===58 ==== Centered placers ==== 58 59 59 60 * `ClumpPlacer(size, coherence, smoothness, x, z)`: Places an irregular "clump" or "blob" of terrain at a specified point (or could be placed at a random point with `createAreas`. The parameters mean the following: … … 63 64 * '''x, z''': Optional tile coordinates of placer. 64 65 65 === Other placers===66 ==== Other placers ==== 66 67 67 68 * `RectPlacer(x1, z1, x2, z2)`: Places a grid-aligned rectangle from (x1,z1) to (x2,z2), where x1 < x2 and z1 < z2. Not usable with `createAreas` since it's not a centered placer. 68 69 69 == Area painters==70 === Area painters === 70 71 71 72 The following area painters are available. Remember that terrains can be any of the objects in the "A Note on Terrains" section above. … … 80 81 * If the `type` is set to `ELEVATION_MODIFY`, it raises/lowers all tiles in the area by the specified amount (for example, elevation = 2 would increase them by 2 and elevation = -3 would lower them by 3). 81 82 82 = Placing Units: Object Groups=83 == Placing Units: Object Groups == 83 84 84 85 An ''object'' or ''entity'' is the game's representation of various units, buildings, and props that occur on a map. You can place objects in a similar way to painting terrains by using ''object groups''. An object group is one or more types of objects which can be placed according to an optional constraint. This process is analogous to creating an area, but it doesn't modify the terrain. … … 90 91 * (Optional) '''minAngle''', '''maxAngle''': The variation in angle of placed objects (to make them all face the same direction, set these equal). Default to 0 and 2*PI, respectively. 91 92 92 == Creating a single object group==93 === Creating a single object group === 93 94 94 95 To place one object group at a known location, use the function `createObjectGroup(placer, player, constraint)`. Given a placer, player ID, and optional constraint, it will try to create the object group. If successful it will return `true`, or `false` on failure. 95 96 96 == Creating multiple object groups at random locations==97 === Creating multiple object groups at random locations === 97 98 98 99 Just like `createAreas` for terrains, there is a `createObjectGroups(placer, player, constraint, number, retryFactor)` function for placing multiple object groups at random locations. 99 100 100 == Object group placers==101 === Object group placers === 101 102 102 103 Currently there is only one object group placer `SimpleGroup(objects, avoidSelf, tileClass, x, z)`: … … 106 107 * (Optional) '''x, z''': Tile coordinates of the center of the placer. 107 108 108 = Grouping Similar Features: Tile Classes=109 == Grouping Similar Features: Tile Classes == 109 110 110 111 In random maps, it is often the case that terrain types and objects will be interconnected. Also when creating the map, we want to avoid some features when placing others. One way of achieving this is by using ''tile classes''. Tile classes can be painted like terrains, although they don't affect the appearance by themselves. They are like placeholders that tell the map script where to place or avoid placing other things. An example usage of tile classes could be to define a "base" area at the starting location of each player. Within this area you probably would want to exclude some things: forests, lakes, and opponents. Likewise you'd want to include resources like berry bushes and sheep. 111 112 112 == Working with tile classes==113 === Working with tile classes === 113 114 114 115 To create a tile class call `createTileClass()` which will return a new integer ID. Store the ID in a variable for future reference. If you want to get the tile class object, call `getTileClass(id)` and it will return the object or `undefined` if the ID was invalid. … … 116 117 Points can be added individually to a tile class with `addToClass(x, z, id)`. In practice this would be tedious, and one advantage of areas is they allow a simple representation of points. There is a special area painter just for this purpose, `TileClassPainter(tileClass)`. This could be used directly if you have a tile class object, but more common is using the `paintClass(id)` helper function, which will return a `TileClassPainter` matching the given ID. 117 118 118 = Controlling Placement: Constraints=119 == Controlling Placement: Constraints == 119 120 120 121 Both areas and object groups use ''constraints'' to limit their placement to specific parts of the map. This is usually the key to making realistic and fair random maps. For example, on most maps, you want a number of clumps of forest, but you want them to be spread out to make most areas of the map reachable, so you will probably want to use an "avoid forest by X meters" constraint on your forest objects. Similarly, you want iron mines to be spread out fairly, and you also don't want them to be inside forests, or under water. If you're making some kind of "king of the hill" map though, you might want the same mines to be only in some area in the center of the map. The list goes on. … … 135 136 * `avoidClasses(...)`: Avoid all the given tile classes by the minimum distances specified. 136 137 137 = Map Helpers=138 == Map Helpers == 138 139 139 140 These functions are for accessing properties of the map settings: … … 144 145 * `isCircularMap()`: Returns true if the map is circular. 145 146 146 = Environment Helpers=147 == Environment Helpers == 147 148 148 149 The environment of a map represents sky, lighting, and water settings. For example a tropical island map might have a clear blue sky, bright sun, and light blue water, whereas a temperate map might have muddy water and an overcast sky. The environment doesn't affect gameplay but does provide a more realistic setting. The following are some functions to adjust the environment of a random map. … … 165 166 * `setWaterReflectionTintStrength(s)` 166 167 167 = Miscellaneous Helpers=168 == Miscellaneous Helpers == 168 169 169 170 The following utility functions are available to scripts. Especially useful are the randomization functions for when you want parameters like terrains or area sizes to vary. … … 174 175 * `chooseRand(...)`: Returns one of its arguments at random (takes any number of arguments). 175 176 176 = Script Library=177 == Script Library == 177 178 178 179 These are the scripts that are part of the rmgen library:
