Difference between revisions of "BuildingMaps"

From The Battle for Wesnoth Wiki
(See Also)
(updated and expanded)
Line 1: Line 1:
A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data"). There are two ways to use this rectangle in a file: as a stand-alone map, or within a scenario. The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it.
+
A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data"). There are two ways to use this rectangle in a file: as a stand-alone map or within a scenario. The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it. For instructions on how to distribute maps, see [[BuildingMapsDistribution]].
  
== Wesnoth map data format ==
 
  
Map data is used to represent maps in Wesnoth. The encoding for maps has a specific format:
+
== Creating a map ==
 +
 
 +
Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, however some helpful hotkeys can be found in the [[WesnothMapEditor]] article. Making good, balanced, interesting maps is another task altogether.  ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].
 +
 
 +
If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.
 +
 
 +
=== Adding units and map descriptions ===
 +
 
 +
Campaign writers can't write campaigns without scenarios, so campaigns will always use scenario files. 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. The ''map_data'' key can either point to a standalone map file or include the raw map data in quotes inside the scenario file.
 +
 
 +
Using scenario files for multiplayer maps, you lose the simplicity of the standalone map file, but you gain tremendous power.  With a scenario file, you can add units and objects, include a map description, and set default map settings like allies, starting gold, and experience modifiers. You can even create custom events. Check out [[BuildingScenarios]], [[ScenarioWML]], and [[BuildingMultiplayer]] for more information.
 +
 
 +
=== Map data format ===
 +
 
 +
This is not the Matrix.  You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:
  
 
* A map starts with a header with the following keys  
 
* A map starts with a header with the following keys  
** usage, this is map for a 'map' and 'mask' for an overlay mask
+
** '''usage''', this should be '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.
+
** '''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
 
* 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.
 
* A map data file consists of any number of lines, each with the same number of strings.
Line 30: Line 43:
 
  Gg, Gg, Gg, Gg, Gg, Gg, Re, Re
 
  Gg, Gg, Gg, Gg, Gg, Gg, Re, Re
  
== Creating a map ==
+
== So now what? ==
 
 
This is not the Matrix.  You do not need to look at encoded maps.  Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, although if you run into trouble, go ahead and ask for help on the [http://www.wesnoth.org/forum forum].
 
 
 
Making good, balanced, interesting maps is another task altogether.  ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]
 
 
 
If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.
 
  
== So now what? ==
+
You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.
  
You've created an awesome map with the [[WesnothMapEditor]] and you're ready to test it out. But how can you do this? It's actually quite simple.
+
=== Play your map ===
  
==== Stand-alone maps ====
+
If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.
  
If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into your custom maps folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices dialog.
+
When creating a game on the multiplayer server, your map will be described to other players as a "Use Map" and any replays stored on the server will refer to the game as "Use Map."
  
 
For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.
 
For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.
  
==== The map_data key ====
+
=== Share your map ===
  
There's another way to use map data. The data for the map can be placed directly inside of a ''map_data'' tag in a '''[scenario]''' tag (see [[ScenarioWML]]). An example of map data encoded directly in a file might look like this:
+
When you're ready to share your map with the world, post it to the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum] or package it to be distributed on the in-game add-ons server. For instructions on how to distribute maps, see [[BuildingMapsDistribution]]
        map_data="border_size=1
 
        usage=map
 
       
 
        Gg, Ke, Gg, Gg
 
        Gg, Ce, Ce, Gg"
 
 
 
Keep in mind that it's almost always more useful to have a separate map file that you reference in a scenario than putting the data directly into the scenario (not least because the editor works on such separate map files). To use a saved map file in a campaign, you have to include the map data like this:
 
 
 
map_data="{@editor/''map_filename''}"
 
 
 
Note that @editor here means that the map should be found in the '''''userdata''/editor/maps/''' directory. You need to specify something else if your map is in another location (for example, in a campaign, the maps should go into their own folder). The [[ScenarioWML]], [[BuildingCampaignsTheCampaignFile]] and [[PreprocessorRef]] pages all contain more detailed information about how this works.
 
 
 
==== Share your map ====
 
 
 
When you're ready to share your map with the world, post if to the forum or package it to be distributed on the in-game add-ons server. For instructions on how to distribute maps, see [[BuildingMapsDistribution]]
 
 
 
== 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.
 
  
 
== See Also ==
 
== See Also ==
  
* [[BuildingMapsDistribution]]
 
 
* [[WesnothMapEditor]]
 
* [[WesnothMapEditor]]
 +
* [[TerrainCodesWML]]
 
* [[ScenarioWML]]
 
* [[ScenarioWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
* [[BuildingScenariosShroudData]]
 
* [[TerrainCodesWML]]
 
  
 
{{Create}}
 
{{Create}}

Revision as of 04:34, 11 October 2009

A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data"). There are two ways to use this rectangle in a file: as a stand-alone map or within a scenario. The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it. For instructions on how to distribute maps, see BuildingMapsDistribution.


Creating a map

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, however some helpful hotkeys can be found in the WesnothMapEditor article. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his Campaign Design How-To. If you run into trouble with the map editor, go ahead and ask for help on the Multiplayer Development forum.

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

Adding units and map descriptions

Campaign writers can't write campaigns without scenarios, so campaigns will always use scenario files. 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. The map_data key can either point to a standalone map file or include the raw map data in quotes inside the scenario file.

Using scenario files for multiplayer maps, you lose the simplicity of the standalone map file, but you gain tremendous power. With a scenario file, you can add units and objects, include a map description, and set default map settings like allies, starting gold, and experience modifiers. You can even create custom events. Check out BuildingScenarios, ScenarioWML, and BuildingMultiplayer for more information.

Map data format

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

  • A map starts with a header with the following keys
    • usage, this should be '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

So now what?

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

Play your map

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear at the top of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "Use Map" and any replays stored on the server will refer to the game as "Use Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in userdata/editor/maps/, and maps in that location are added to the top of the multiplayer map selection list.

Share your map

When you're ready to share your map with the world, post it to the Multiplayer Development forum or package it to be distributed on the in-game add-ons server. For instructions on how to distribute maps, see BuildingMapsDistribution

See Also