Difference between revisions of "BuildingMaps"

Revision as of 19:17, 12 October 2005

This is all you need to know about maps:

A map is just a bunch of letters arranged in a rectangle (the rectangle is known as the "map data")
There are two ways to save this rectangle in a file

Seriously now, here are the details.

Wesnoth map data format

Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:

A map data file consists of any number of lines, each with the same number of characters.
Each character must be either a letter specified in a letter key specifying a terrain (see TerrainLettersWML), or a digit.
When the file is interpreted, each letter will be replaced by the terrain it refers to.
Each nonzero digit n where n = 1, 2, 3, ... will be replaced by keep, with the leader of side n placed on the keep.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted. Tiles in even-numbered columns are shifted down 1/2 of a tile. For example, to have a road of connected dirt ('r') tiles, the map data would look like this:

gggrr
grrgg
rgggg

Creating a map

This is not the Matrix. You do not need to look at encoded maps. The source code and most binary distributions come with the official graphical map editor. Using the map editor tends to be straightforward, judging from the feedback received from novice mapmakers. However, if you do encounter problems locating or using the editor, please ask for help on the forum.

After the map is created, you may find it easier to make small tweaks by editing the textual map data directly.

Making good, balanced, interesting maps is another task altogether, and if someone wants to take a stab at sharing insight about this art, please do so.

Using map data

Map data is used in two ways.

It is used as an input to the key map_data (see ScenarioWML).
Files consisting entirely of map data can be read and edited easily by the WesnothMapEditor.
- Files in the folder userdata/editor/maps/ which consist entirely of map data can be played in multiplayer as user maps.

The map_data key

The first way is to use the map_data key. A campaign scenario starts with the [scenario] tag. A multiplayer map scenario starts with the [multiplayer] tag. Each tag takes the key map_data. The value of the map_data key is the map data enclosed in quotes. Here is an example:

map_data="rRfRffffffffffffffcgggfffffffhmmhmhmffff
ffRfRffffffffffvfccfgffffmmhffmhXXmmmhff
ffffRRfnngvgffffscfffmfmhmmmmmfmmfmXmhff
gffffn1RgvgggfffscffffmmmfXmmmhXmmmXmhff
gfffnvggRRgfvnffcfffffhmXmmXXXXfXXmmhfff
gffffggggfR2nffccvggfffhmhXfgCgCfmmXmhff
fffffvfgfnnRR\ccffggffffmmXgfC3CgXmfmhff
ffffffvffcc|cfrrccfffffmmmXXfgggfXmhhfff
fffffcfccfcrffgvrrccffffhhmmXXggXmmfmffr
fffccfcffrrggggffrffcfffffmmmhffmfmmfrfr
fccffffrfffffhffrfffccffffffmmfrfmmrrfrf
ccffvffrffffvhhhrhhhffcfffffffffrrrhhfff
fffffffrffffffhhrrhffccffrfffffrrfhfffff
frfffffrrrffffffhrffffwrrfrfrfrfffffffff
rfrrfrffffrrfffffrfffr/wfhffrrfffffgggvf
fvffrffffffrffffffrrrfwwhhfvffrrfffggggf"

Standalone map file

The second way to store a map is in a text file that consists only of the map data. The advantage of this method is that it's simple. If you drop one of the map files in userdata/editor/maps/, the game will find it automatically in multiplayer. On the other hand, this method also works with more complex scenarios. If there is a scenario file somewhere (campaign or multiplayer) that has a line similar to the following:

map_data="{@editor/map_filename}"

then all of the map data in the file is inserted between the quote marks.

Discussion: Scenario File vs Standalone

Campaign writers can't write campaigns without scenarios, so campaigns will always use the map_data key, either with the raw data in quotes or a preprocessor symbol {} pointing to the standalone file.

Multiplayer mapmakers, however, have a choice. If you want to place an object or unit on the map, you must create a scenario file starting with the [multiplayer] tag and containing the map_data key therein. You lose the simplicity of the standalone map file, but you gain tremendous power. Not only can you add units and objects, you can set allies, experience modifiers, add a map description, and add custom events (among other things). The question, "How do I place an object on the map with the map editor" is such a common question that I am sorry this information is buried so deeply here. But, now that you know you can seek out an example of a multiplayer map scenario file to use as an example. The game comes with many maps of each type.