BuildingMaps

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 map format changed in 1.3.x; this description is for the newer version.

The encoding for maps has a specific format:

A map starts with a header with the following keys
- usage, this is map for a 'map' and 'mask' for an overlay mask
- border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
Between the header and the data should be 1 empty line
A map data file consists of any number of lines, each with the same number of strings.
Each string must be a string specified in a string key specifying a terrain (see TerrainLettersWML).
Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
When the file is interpreted, each string will be replaced by the terrain it refers to.
Empty lines are allowed before, after and between lines of characters, between lines is not advised.
Terrains may be prefixed with a number followed by one space, these indicate the starting position for side n. n = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

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 ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

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. When compiling from source, remember to use the --enable-editor option when configuring, otherwise the map editor won't be compiled. 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="111111111111111111"

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. Check out BuildingMultiplayer for more information.