The Battle for Wesnoth Wiki - User contributions [en]

Talk:TerrainMaskWML

2013-04-16T23:57:12Z

Jamiescott: Useful but incomplete

This page seems to be protected so I can't add or fix anything. If someone who can could take a moment to add an explanation of the "usage" key that would be great!

Terrain

2013-04-16T13:27:51Z

Jamiescott: /* Information */

The information center for all things Terrain

==='''[[Tiles_Status]]'''===

The central organizing page for coordinating work on terrain..

===Information===
* [[TerrainLettersWML]] - A list of the letters used to represent terrain types and how to interpret them.
* [[TerrainCodeTableWML]] - Auto-generated list of current terrains with sample tile images.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [[Terrain_Terms]] --Standard Definitions for Terrain Terminology
* [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml Ayin's Terrain Graphics document] - If you really, ''really'' need to get technical, this describes the terrain graphics WML system in depth. Unfortunately, the examples are in the old 1.2 format, but it's still useful.

===Tutorials===
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in wesnoth, and how they interact with adjacent tiles.
* [[How To Make Seamless Tiles]] - The tutorial is aimed at Photoshop users, but the technique is similar with The GIMP.
* [[CastleTutorial|Castle Tutorial]] - A description of how Wesnoth's castle tiles work (needs updating, but useful nonetheless)
* [[MultiHexTutorial|Multi-Hex Tiling Tutorial]] - A description of how multi-hex tiles work.
* [[Editing Castles]] - Instructions for how to make/edit castles (and other corner-based terrains) using yobbo's GIMP script.

[[Category:Art Tutorials]]

Turning Square Tiles into Hex

2013-04-13T17:16:59Z

Jamiescott: /* Method 2: Rotation */

In Wesnoth the Terrain graphics are made with seamlessly tiling hexagonal pixmaps. These are more difficult to make than square tiles, for which ready made scripts exist in most image manipulation programs, and which can also be found in multitude of libraries, free to use.

If you cut a square tile into a hexagon, it's only going to be seamless in north and south edges. To make it seamless in all edges takes a bit of trickery, but it's relatively simple. There are two methods to do it, the one that is better depending on the circumstances.

==Method 1: Keeping the Orientation==

Let's start with a dry mud texture from the standard GIMP library:

http://koti.welho.com/thonkasa/Roinaa/hextile1.png

First it must be scaled to 54x36 pixel size (this applies to the standard 72x72 pixel Wesnoth hexes, for other hexes the figures are width*0.75 and height/2). Then resize the canvas by 2 in both directions and fill the empty space with copies of the tile:

http://koti.welho.com/thonkasa/Roinaa/hextile2.png

Now crop the image to 72x72 pixels (the exact placement of the cropping does not matter) and trim the corners so that it matches the standard hex:

http://koti.welho.com/thonkasa/Roinaa/hextile3.png

Now comes the moment of truth: what happens when we tile this hex? Let's see:

http://koti.welho.com/thonkasa/Roinaa/hextile4.png

Almost makes you believe in magic, doesn't it?

There are two important things to notice:

# The size and aspect ratio of the original texture are not preserved (unless it is already 54x36 pixels), but this can be a good thing. If you start with a square tile where the pattern is seen as if looking down from above, when it gets scaled down vertically, it creates an impression of perspective (in Wesnoth, the terrain is seen from an angle, not directly above).
# The hex will contain the original pattern twice, that is, every unique feature in the original tile will appear in the hex tile two times. This may make the pattern appear too densely repeating, but once you have the hex made, you can change something about one copy of each feature to counteract this effect (as long as you don't touch the edge pixels, the tile will stay seamless).

==Method 2: Rotation==

In the second method the original tile must be square, for it will be rotated 45 degrees. The rotation may prove useful in cases where the pattern has straight forms, like stripes or checkers. In that case the end result will generally look better if the lines go from SE to NW and SW to NE rather than from south to north and west to east. So if your pattern has strong lines vertically or horizontally, you should use this method.

If the original tile is not square, scale it horizontally or vertically so that it is. Double the size of the canvas in both directions and fill the space with copies of the tile, creating a 2x2 pattern. Below is our example, a ceramic tile pattern:

http://koti.welho.com/thonkasa/Roinaa/hextile21.png

Next rotate the image 45 degrees and scale it so that the height becomes 144 and width 216 pixels:

http://koti.welho.com/thonkasa/Roinaa/hextile22.png

Then cut the hex shape out anywhere you like (don't include any transparent pixels), and that's it (notice that the pattern appears only once in the hex):

http://koti.welho.com/thonkasa/Roinaa/hextile23.png

If you doubt that it can be this simple, let's see how it tiles:

http://koti.welho.com/thonkasa/Roinaa/hextile24.png

Which method to use depends on your requirements. If you need to preserve the original orientation, use method 1. If you need the rotation, or must have the pattern repeated only once per hex, use method 2 (simultaneously preserving orientation and having 1 repeat/hex is not possible with these methods). If the orientation and repeat number don't matter, the appropriate method depends on the desired size of the pattern: method 2 reproduces the pattern twice as big as method 1.

[[Category: Art Tutorials]]

Turning Square Tiles into Hex

2013-04-13T17:14:47Z

Jamiescott: /* Method 2: Rotation */

In Wesnoth the Terrain graphics are made with seamlessly tiling hexagonal pixmaps. These are more difficult to make than square tiles, for which ready made scripts exist in most image manipulation programs, and which can also be found in multitude of libraries, free to use.

If you cut a square tile into a hexagon, it's only going to be seamless in north and south edges. To make it seamless in all edges takes a bit of trickery, but it's relatively simple. There are two methods to do it, the one that is better depending on the circumstances.

==Method 1: Keeping the Orientation==

Let's start with a dry mud texture from the standard GIMP library:

http://koti.welho.com/thonkasa/Roinaa/hextile1.png

First it must be scaled to 54x36 pixel size (this applies to the standard 72x72 pixel Wesnoth hexes, for other hexes the figures are width*0.75 and height/2). Then resize the canvas by 2 in both directions and fill the empty space with copies of the tile:

http://koti.welho.com/thonkasa/Roinaa/hextile2.png

Now crop the image to 72x72 pixels (the exact placement of the cropping does not matter) and trim the corners so that it matches the standard hex:

http://koti.welho.com/thonkasa/Roinaa/hextile3.png

Now comes the moment of truth: what happens when we tile this hex? Let's see:

http://koti.welho.com/thonkasa/Roinaa/hextile4.png

Almost makes you believe in magic, doesn't it?

There are two important things to notice:

# The size and aspect ratio of the original texture are not preserved (unless it is already 54x36 pixels), but this can be a good thing. If you start with a square tile where the pattern is seen as if looking down from above, when it gets scaled down vertically, it creates an impression of perspective (in Wesnoth, the terrain is seen from an angle, not directly above).
# The hex will contain the original pattern twice, that is, every unique feature in the original tile will appear in the hex tile two times. This may make the pattern appear too densely repeating, but once you have the hex made, you can change something about one copy of each feature to counteract this effect (as long as you don't touch the edge pixels, the tile will stay seamless).

==Method 2: Rotation==

In the second method the original tile must be square, for it will be rotated 45 degrees. The rotation may prove useful in cases where the pattern has straight forms, like stripes or checkers. In that case the end result will generally look better if the lines go from SE to NW and SW to NE rather than from south to north and west to east. So if your pattern has strong lines vertically or horizontally, you should use this method.

If the original tile is not square, scale it horizontally or vertically so that it is. Double the size of the canvas in both directions and fill the space with copies of the tile, creating a 2x2 pattern. Below is our example, a ceramic tile pattern:

http://koti.welho.com/thonkasa/Roinaa/hextile21.png

Next rotate the image 45 degrees and scale it so that the height becomes 144 and width 216 pixels:

http://koti.welho.com/thonkasa/Roinaa/hextile22.png

Then cut the hex shape out anywhere it doesn't include transparent pixels, and that's it (notice that the pattern appears only once in the hex):

http://koti.welho.com/thonkasa/Roinaa/hextile23.png

If you doubt that it can be this simple, let's see how it tiles:

http://koti.welho.com/thonkasa/Roinaa/hextile24.png

Which method to use depends on your requirements. If you need to preserve the original orientation, use method 1. If you need the rotation, or must have the pattern repeated only once per hex, use method 2 (simultaneously preserving orientation and having 1 repeat/hex is not possible with these methods). If the orientation and repeat number don't matter, the appropriate method depends on the desired size of the pattern: method 2 reproduces the pattern twice as big as method 1.

[[Category: Art Tutorials]]

Turning Square Tiles into Hex

2013-04-13T17:09:50Z

Jamiescott: /* Method 1: Keeping the Orientation */

In Wesnoth the Terrain graphics are made with seamlessly tiling hexagonal pixmaps. These are more difficult to make than square tiles, for which ready made scripts exist in most image manipulation programs, and which can also be found in multitude of libraries, free to use.

If you cut a square tile into a hexagon, it's only going to be seamless in north and south edges. To make it seamless in all edges takes a bit of trickery, but it's relatively simple. There are two methods to do it, the one that is better depending on the circumstances.

==Method 1: Keeping the Orientation==

Let's start with a dry mud texture from the standard GIMP library:

http://koti.welho.com/thonkasa/Roinaa/hextile1.png

First it must be scaled to 54x36 pixel size (this applies to the standard 72x72 pixel Wesnoth hexes, for other hexes the figures are width*0.75 and height/2). Then resize the canvas by 2 in both directions and fill the empty space with copies of the tile:

http://koti.welho.com/thonkasa/Roinaa/hextile2.png

Now crop the image to 72x72 pixels (the exact placement of the cropping does not matter) and trim the corners so that it matches the standard hex:

http://koti.welho.com/thonkasa/Roinaa/hextile3.png

Now comes the moment of truth: what happens when we tile this hex? Let's see:

http://koti.welho.com/thonkasa/Roinaa/hextile4.png

Almost makes you believe in magic, doesn't it?

There are two important things to notice:

# The size and aspect ratio of the original texture are not preserved (unless it is already 54x36 pixels), but this can be a good thing. If you start with a square tile where the pattern is seen as if looking down from above, when it gets scaled down vertically, it creates an impression of perspective (in Wesnoth, the terrain is seen from an angle, not directly above).
# The hex will contain the original pattern twice, that is, every unique feature in the original tile will appear in the hex tile two times. This may make the pattern appear too densely repeating, but once you have the hex made, you can change something about one copy of each feature to counteract this effect (as long as you don't touch the edge pixels, the tile will stay seamless).

==Method 2: Rotation==

In the second method the original tile must be square, for it will be rotated 45 degrees. The rotation may prove useful in cases where the pattern have straight forms, like stripes or checkers. In that case the end result will generally look better if the lines go from SE to NW and SW to NE rather than from south to north and west to east. So if your pattern has these lines vertically and horizontally, you should use this method.

If the original tile is not square, scale it horizontally or vertically so that it is. Double the size of the canvas in both directions and fill the space with copies of the tile, creating a 2x2 pattern. Below is our example, a ceramic tile pattern:

http://koti.welho.com/thonkasa/Roinaa/hextile21.png

Next rotate the image 45 degrees and scale it so that the height becomes 144 and width 216 pixels:

http://koti.welho.com/thonkasa/Roinaa/hextile22.png

Then cut the hex shape out (anywhere where it doesn't include transparent pixels), and that's it (notice that the pattern appears only once in the hex):

http://koti.welho.com/thonkasa/Roinaa/hextile23.png

If you doubt that it can be this simple, let's see how it tiles:

http://koti.welho.com/thonkasa/Roinaa/hextile24.png

Which method to use depends on your requirements. If you need to preserve the original orientation, use method 1. If you need the rotation, or must have the pattern repeated only once per hex, use method 2 (both preserving orientation and having 1 repeat/hex is not possible with these methods). If the orientation and repeat number don't matter, the appropriate method depends on the desired size of the pattern: method 2 reproduces the pattern twice as big as method 1.

[[Category: Art Tutorials]]

Tiles Tutorial

2013-04-13T16:59:01Z

Jamiescott: /* Multihex tiles */

=== Normal Tiles ===

Normal tiles consist of a set of variant 72x72 tiles used for a given terrain type. The probability for showing the different variants are given in terrain-graphics.cfg. In addition each terrain type has a set of transition tiles:

* 6 basic transitions: n, ne, se, s, sw, nw
* 6 "2-side trans": n-ne, ne-se, se-s, s-sw, sw-nw, nw-n
* 6 "3-side trans": n-ne-se, ne-se-s, se-s-sw, s-sw-nw, sw-nw-n, nw-n-ne
* 6 "4-side trans": n-ne-se-s, ne-se-s-sw, se-s-sw-nw, s-sw-nw-nw, sw-nw-n-ne, nw-n-ne-se

Few terrain types use all these possible transitions, if any.

It is possible to make several transitions and use different ones depending on which terrain type is adjacent. There is also a need for special transitions for terrains adjacent to castles.

Transitions are drawn around tiles according to the definitions in terrain-graphics.cfg. Each terrain is placed in a given layer. This defines which terrain will draw a transition when adjacent to another. Terrains in the "higher" layers will draw their transitions on top of terrain layered further down.

Each transition is stored in a separate image file.

'''Example 1.'''

1 tile + the 6 basic transitions:

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles.png

'''Example 2.'''

1 tile + 2 x nw trans and a sw-nw-n trans. (This may seem strange, but the transitions are named after where the image is drawn in the transition tile itself, not where it's "attached" to the terrain tile).

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles2.png

=== Multihex tiles ===

Multihex tiles work differently. They don't have separate transitions. One could say the transitions are attached to the tile itself. They also behave differently. While normal tiles draw their transitions according to layering, a multihex tile will overlap terrain either vertically and/or horizontally. This means, for example, that mountain tops will extend into tiles above, removing the need for a special transition. For other sorts of terrain like grassland (and other flat ones) this must be done in a way that will allow them to mesh into each other. Of course multihex is not necessarily ideal for all terrain types.

'''Examples'''

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles.png

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles2.png

Note on overlay tiles: define a background tile which gets drawn first underneath the overlay using the regular layering rules for that particular terrain type.

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles3.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

Tiles Tutorial

2013-04-13T16:42:18Z

Jamiescott: /* Normal Tiles */

=== Normal Tiles ===

Normal tiles consist of a set of variant 72x72 tiles used for a given terrain type. The probability for showing the different variants are given in terrain-graphics.cfg. In addition each terrain type has a set of transition tiles:

* 6 basic transitions: n, ne, se, s, sw, nw
* 6 "2-side trans": n-ne, ne-se, se-s, s-sw, sw-nw, nw-n
* 6 "3-side trans": n-ne-se, ne-se-s, se-s-sw, s-sw-nw, sw-nw-n, nw-n-ne
* 6 "4-side trans": n-ne-se-s, ne-se-s-sw, se-s-sw-nw, s-sw-nw-nw, sw-nw-n-ne, nw-n-ne-se

Few terrain types use all these possible transitions, if any.

It is possible to make several transitions and use different ones depending on which terrain type is adjacent. There is also a need for special transitions for terrains adjacent to castles.

Transitions are drawn around tiles according to the definitions in terrain-graphics.cfg. Each terrain is placed in a given layer. This defines which terrain will draw a transition when adjacent to another. Terrains in the "higher" layers will draw their transitions on top of terrain layered further down.

Each transition is stored in a separate image file.

'''Example 1.'''

1 tile + the 6 basic transitions:

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles.png

'''Example 2.'''

1 tile + 2 x nw trans and a sw-nw-n trans. (This may seem strange, but the transitions are named after where the image is drawn in the transition tile itself, not where it's "attached" to the terrain tile).

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles2.png

=== Multihex tiles ===

Multihex tiles work differently. They don't have seperate transitions. One could say the trans are attached to the tile itself. They also behave differently. While normal tiles draw their trans according to the layering a multihex tile will rather overlap terrain either vertically and/or horizontally. This means fx that mountain tops will extend into tiles above removing the need for a special transition. for other sorts of terrain like grassland and other flat ones this must be done in a way that will allow them to mesh into each other. Of course multihex is not neccesarily ideal for all terrain types.

'''Examples'''

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles.png

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles2.png

Note on overlay tiles: you define a background tile which gets drawn first underneat them using the regular layering rules for that particual terrain type.

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles3.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

Tiles Tutorial

2013-04-13T16:38:23Z

Jamiescott: /* Normal Tiles */

=== Normal Tiles ===

Normal tiles consist of a set of variant 72x72 tiles used for a given terrain type. The probability for showing the different variants are given in terrain-graphics.cfg. In addition each terrain type has a set of transition tiles:

* 6 basic transitions: n, ne, se, s, sw, nw
* 6 "2-side trans": n-ne, ne-se, se-s, s-sw, sw-nw, nw-n
* 6 "3-side trans": n-ne-se, ne-se-s, se-s-sw, s-sw-nw, sw-nw-n, nw-n-ne
* 6 "4-side trans": n-ne-se-s, ne-se-s-sw, se-s-sw-nw, s-sw-nw-nw, sw-nw-n-ne, nw-n-ne-se

Few terrain types use all these possible transitions, if any.

It is possible to make several transitions and use different ones depending on which terrain type is adjacent. There is also a need for special transitions for terrains adjacent to castles.

Transitions are drawn around tiles according to the definitions in terrain-graphics.cfg. Each terrain is placed in a given layer. This defines which terrain will draw a transition when adjacent to another. Terrains in the "higher" layers will draw their transitions on top of terrain layered further down.

Each transition is stored in a separate image file.

'''Example 1.'''

1 tile + the 6 basic transitions:

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles.png

'''Example 2.'''

1 tile + 2 x nw trans and a sw-nw-n trans. (This might seem strange, but the trans. are named after where the trans. is drawn in the trans. tile itself, not where it's "attached" to the terrain tile).

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles2.png

=== Multihex tiles ===

Multihex tiles work differently. They don't have seperate transitions. One could say the trans are attached to the tile itself. They also behave differently. While normal tiles draw their trans according to the layering a multihex tile will rather overlap terrain either vertically and/or horizontally. This means fx that mountain tops will extend into tiles above removing the need for a special transition. for other sorts of terrain like grassland and other flat ones this must be done in a way that will allow them to mesh into each other. Of course multihex is not neccesarily ideal for all terrain types.

'''Examples'''

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles.png

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles2.png

Note on overlay tiles: you define a background tile which gets drawn first underneat them using the regular layering rules for that particual terrain type.

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles3.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

Tiles Tutorial

2013-04-13T16:33:34Z

Jamiescott: /* Normal Tiles */

=== Normal Tiles ===

Normal tiles consist of a set of variant 72x72 tiles used for a given terrain type. The probability for showing the different variants are given in terrain-graphics.cfg. In addition each terrain type has a set of transition tiles:

* 6 basic transitions: n, ne, se, s, sw, nw
* 6 "2-side trans": n-ne, ne-se, se-s, s-sw, sw-nw, nw-n
* 6 "3-side trans": n-ne-se, ne-se-s, se-s-sw, s-sw-nw, sw-nw-n, nw-n-ne
* 6 "4-side trans": n-ne-se-s, ne-se-s-sw, se-s-sw-nw, s-sw-nw-nw, sw-nw-n-ne, nw-n-ne-se

Few terrain types use all these possible transitions, if any.

It is possible to make several transitions and use different ones depending on which terrain type is adjacent. There is also a need for special transitions when terrains are adjacent to castles.

Transitions are drawn around tiles according to a what is defined in terrain-graphics.cfg. Each terrain is placed in a given layer. This defines which terrain will draw their transition when adjacent to another. This means that the one which are layered the "highest" will draw their transitions on top of terrain layered further down.

Each of these transitions are stored in separate image files.

'''Example 1.'''

1 tile + the 6 basic transitions:

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles.png

'''Example 2.'''

1 tile + 2 x nw trans and a sw-nw-n trans. (This might seem strange, but the trans. are named after where the trans. is drawn in the trans. tile itself, not where it's "attached" to the terrain tile).

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles2.png

=== Multihex tiles ===

Multihex tiles work differently. They don't have seperate transitions. One could say the trans are attached to the tile itself. They also behave differently. While normal tiles draw their trans according to the layering a multihex tile will rather overlap terrain either vertically and/or horizontally. This means fx that mountain tops will extend into tiles above removing the need for a special transition. for other sorts of terrain like grassland and other flat ones this must be done in a way that will allow them to mesh into each other. Of course multihex is not neccesarily ideal for all terrain types.

'''Examples'''

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles.png

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles2.png

Note on overlay tiles: you define a background tile which gets drawn first underneat them using the regular layering rules for that particual terrain type.

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles3.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

Tiles Tutorial

2013-04-13T16:32:05Z

Jamiescott: /* Normal Tiles */

=== Normal Tiles ===

Normal tiles consist of a set of variant 72x72 tiles used for a given terrain type. The probability for showing the different variants are given in terrain-graphics.cfg. In addition each terrain type has a set of transition tiles:

* 6 basic transitions: n, ne, se, s, sw, nw
* 6 "2-side trans": n-ne, ne-se, se-s, s-sw, sw-nw, nw-n
* 6 "3-side trans": n-ne-se, ne-se-s, se-s-sw, s-sw-nw, sw-nw-n, nw-n-ne
* 6 "4-side trans": n-ne-se-s, ne-se-s-sw, se-s-sw-nw, s-sw-nw-nw, sw-nw-n-ne, nw-n-ne-se

Few terrain types use all these possible transitions, if any.

It is possible to make several transitions and use different ones depending on which terrain type is adjacent. There is also a need for some special transitions when terrains are adjacent to castles.

Transitions are drawn around tiles according to a what is defined in terrain-graphics.cfg. Each terrain is placed in a given layer. This defines which terrain will draw their transition when adjacent to another. This means that the one which are layered the "highest" will draw their transitions on top of terrain layered further down.

Each of these transitions are stored in separate image files.

'''Example 1.'''

1 tile + the 6 basic transitions:

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles.png

'''Example 2.'''

1 tile + 2 x nw trans and a sw-nw-n trans. (This might seem strange, but the trans. are named after where the trans. is drawn in the trans. tile itself, not where it's "attached" to the terrain tile).

http://www.idi.ntnu.no/~haskjold/wesnoth/info/normal_tiles2.png

=== Multihex tiles ===

Multihex tiles work differently. They don't have seperate transitions. One could say the trans are attached to the tile itself. They also behave differently. While normal tiles draw their trans according to the layering a multihex tile will rather overlap terrain either vertically and/or horizontally. This means fx that mountain tops will extend into tiles above removing the need for a special transition. for other sorts of terrain like grassland and other flat ones this must be done in a way that will allow them to mesh into each other. Of course multihex is not neccesarily ideal for all terrain types.

'''Examples'''

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles.png

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles2.png

Note on overlay tiles: you define a background tile which gets drawn first underneat them using the regular layering rules for that particual terrain type.

http://www.idi.ntnu.no/~haskjold/wesnoth/info/multihex_tiles3.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

TerrainWML

2013-04-13T16:15:54Z

Jamiescott: /* the toplevel [terrain_type] tag */

{{WML Tags}}
== the toplevel [terrain_type] tag ==

The [terrain_type] tag describes a terrain in WML.
Terrains are usually described in the terrain.cfg file

the [terrain_type] tag has the following keys and subtags
* '''symbol_image''': an image used for this terrain in the minimap
* '''editor_image''': an image used for this terrain in the map editor; if not defined uses symbol_image
* '''id''': a non-translatable string identifying this terrain. It is used as the key for attributes in some parts of WML, such as {{tag|UnitsWML|movetype}} (but see also the aliasof= attribute below; not all ids need to be listed under movetypes).
* '''name''': the name of the terrain, a translatable string used for the display of terrain type in the game and the map editor
* '''description''': the detailed description of the terrain, a translatable string used for the display of terrain type in the game and the map editor. If this is not present, the game and editor will fall back to the '''name''' attribute. The difference is that the name tends to describe the game effect of the terrain type (e.g., "Forest") but the description attribute also carries information about visual subtype (e.g. "Summer Deciduous Forest").
* '''editor_name''': a detailed name for the terrain used only in the map editor. Terrains are presented in the editor as "''<editor_name>''/''<name>'' (''<aliases>'')" when this attribute is used.
* '''string''': this is the string that represents the terrain in maps and scenarios
* '''unit_height_adjust''': how much the unit graphic should be moved up or down when on that terrain
* '''submerge''': float, between 0 and 1: specifies how much of the unit graphic should be submerged by the terrain
* '''light''': signed value: this will modify the local light level on that hex by that amount for gameplay.
* '''max_light''': {{DevFeature1.11}} signed value: this is the maximum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is higher.
* '''min_light''': {{DevFeature1.11}} signed value: this is the minimum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is lower.
* '''heals''': signed value: this value is the amount of HP a unit on this terrain will be healed at the start of every turn. (If set to true a unit on that terrain will be healed 8 HP at the start of every turn.) This notation is <b>deprecated</b> and support might be removed at some point.
* '''gives_income''': if set to true, this terrain will give income every turn when flagged, as if it were a village
* '''recruit_onto''': if set to true, it is possible to recruit or recall on that terrain
* '''recruit_from''': if set to true it is possible to recruit when a unit that can recruit is on that terrain
* '''aliasof''': comma separated string of terrains of which this terrain will be an alias. This is a list of terrains, with + and - signs having special meanings. The string is read left to right taking the best value until a minus sign is encountered, after which it takes the worst value instead. The plus sign reverts to best value. (Note: after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
* '''def_alias''': like ''aliasof'' but overides it for defense calculation only
* '''mvt_alias''': like ''aliasof'' but overides it for movement calculation only
* '''income_description''': for terrains with ''gives_income'' and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
* '''income_description_ally''': like ''income_description'' but if owned by an ally
* '''income_description_enemy''': like ''income_description'' but if owned by an enemy
* '''income_description_own''': like ''income_description'' but if owned by yourself
* '''editor_group''': a comma separated list of editor_group ids to which this terrain belongs.
* '''hidden''': (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.

== See Also ==

* [[ReferenceWML]]
* [[TerrainCodesWML]]
* [[EditorGroupWML]]

[[Category: WML Reference]]

TerrainWML

2013-04-13T16:08:36Z

Jamiescott: /* the toplevel [terrain_type] tag */

{{WML Tags}}
== the toplevel [terrain_type] tag ==

The [terrain_type] tag describes a terrain in WML.
Terrains are usually described in the terrain.cfg file

the [terrain_type] tag has the following keys and subtags
* '''symbol_image''': an image used for this terrain in the minimap
* '''editor_image''': an image used for this terrain in the map editor; if not defined uses symbol_image
* '''id''': a non-translatable string identifying this terrain. It is used as the key for attributes in some parts of WML, such as {{tag|UnitsWML|movetype}} (but see also the aliasof= attribute below; not all ids need to be listed under movetypes).
* '''name''': the name of the terrain, a translatable string used for the display of terrain type in the game and the map editor
* '''description''': the detailed description of the terrain, a translatable string used for the display of terrain type in the game and the map editor. If this is not present, the game and editor will fall back to the '''name''' attribute. The difference is that the name tends to describe the game effect of the terrain type (e.g., "Forest") but the description attribute also carries information about visual subtype (e.g. "Summer Deciduous Forest").
* '''editor_name''': a detailed name for the terrain used only in the map editor. Terrains are presented in the editor as "''<editor_name>''/''<name>'' (''<aliases>'')" when this attribute is used.
* '''string''': this is the string that represents the terrain in maps and scenarios
* '''unit_height_adjust''': how much the unit graphic should be moved up or down when on that terrain
* '''submerge''': float, between 0 and 1: specifies how much of the unit graphic should be submerged by the terrain
* '''light''': signed value: this will modify the local light level on that hex by that amount for gameplay.
* '''max_light''': {{DevFeature1.11}} signed value: this is the maximum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is higher.
* '''min_light''': {{DevFeature1.11}} signed value: this is the minimum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is lower.
* '''heals''': signed value: this value is the amount of HP a unit on this terrain will be healed at the start of every turn. (If set to true a unit on that terrain will be healed 8 HP at the start of every turn.) This notation is <b>deprecated</b> and support might be removed at some point.
* '''gives_income''': if set to true, this terrain will give income every turn when flagged, as if it were a village
* '''recruit_onto''': if set to true, it is possible to recruit or recall on that terrain
* '''recruit_from''': if set to true it is possible to recruit when a unit that can recruit is on that terrain
* '''aliasof''': comma separated string representing terrains that this terrain will be an alias of. This is a list of characters, with the + and - signs having special meanings. the string is read left to right taking the best value. when a minus sign is encountered, it starts taking the worst instead. the plus sign reverts it back to the best (note after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
* '''def_alias''': like ''aliasof'' but overides it for defense calculation only
* '''mvt_alias''': like ''aliasof'' but overides it for movement calculation only
* '''income_description''': for terrains with ''gives_income'' and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
* '''income_description_ally''': like ''income_description'' but if owned by an ally
* '''income_description_enemy''': like ''income_description'' but if owned by an enemy
* '''income_description_own''': like ''income_description'' but if owned by yourself
* '''editor_group''': a comma separated list of editor_group ids to which this terrain belongs.
* '''hidden''': (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.

== See Also ==

* [[ReferenceWML]]
* [[TerrainCodesWML]]
* [[EditorGroupWML]]

[[Category: WML Reference]]

TerrainWML

2013-04-13T16:05:58Z

Jamiescott: /* the toplevel [terrain_type] tag */

{{WML Tags}}
== the toplevel [terrain_type] tag ==

The [terrain_type] tag describes a terrain in WML.
Terrains are usually described in the terrain.cfg file

the [terrain_type] tag has the following keys and subtags
* '''symbol_image''': an image used for this terrain in the minimap
* '''editor_image''': an image used for this terrain in the map editor; if not defined uses symbol_image
* '''id''': a non-translatable string identifying this terrain. It is used as the key for attributes in some parts of WML, such as {{tag|UnitsWML|movetype}} (but see also the aliasof= attribute below; not all ids need to be listed under movetypes).
* '''name''': the name of the terrain, a translatable string used for the display of terrain type in the game and the map editor
* '''description''': the detailed description of the terrain, a translatable string used for the display of terrain type in the game and the map editor. If this is not present, the game and editor will fall back to the '''name''' attribute. The difference is that the name tends to describe the game effect of the terrain type (e.g., "Forest") but the description attribute also carries information about visual subtype (e.g. "Summer Deciduous Forest").
* '''editor_name''': a detailed name for the terrain used only in the map editor. Terrains are presented in the editor as "''<editor_name>''/''<name>'' (''<aliases>'')" when this attribute is used.
* '''string''': this is the string that represents the terrain in maps and scenarios
* '''unit_height_adjust''': how much the unit graphic should be moved up or down when on that terrain
* '''submerge''': float, between 0 and 1: specifies how much of the unit graphic should be submerged by the terrain
* '''light''': signed value: this will modify the local light level on that hex by that amount for gameplay.
* '''max_light''': {{DevFeature1.11}} signed value: this is the maximum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is higher.
* '''min_light''': {{DevFeature1.11}} signed value: this is the minimum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is lower.
* '''heals''': signed value: this value is the amount of HP a unit on this terrain will be healed at the start of every turn. (If set to true a unit on that terrain will be healed 8 HP at the start of every turn, this notation is deprecated and support might be removed at some point.)
* '''gives_income''': if set to true, this terrain will give income every turn when flagged, as if it were a village
* '''recruit_onto''': if set to true, it is possible to recruit or recall on that terrain
* '''recruit_from''': if set to true it is possible to recruit when a unit that can recruit is on that terrain
* '''aliasof''': comma separated string representing terrains that this terrain will be an alias of. This is a list of characters, with the + and - signs having special meanings. the string is read left to right taking the best value. when a minus sign is encountered, it starts taking the worst instead. the plus sign reverts it back to the best (note after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
* '''def_alias''': like ''aliasof'' but overides it for defense calculation only
* '''mvt_alias''': like ''aliasof'' but overides it for movement calculation only
* '''income_description''': for terrains with ''gives_income'' and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
* '''income_description_ally''': like ''income_description'' but if owned by an ally
* '''income_description_enemy''': like ''income_description'' but if owned by an enemy
* '''income_description_own''': like ''income_description'' but if owned by yourself
* '''editor_group''': a comma separated list of editor_group ids to which this terrain belongs.
* '''hidden''': (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.

== See Also ==

* [[ReferenceWML]]
* [[TerrainCodesWML]]
* [[EditorGroupWML]]

[[Category: WML Reference]]

TerrainCodesWML

2013-04-13T15:57:23Z

Jamiescott: /* Decoding the Terrain Codes */

{{WML Tags}}

Note: the old (1.2) terrain system is no longer documented here. If you have 1.2 maps you will need to convert them using [[Maintenance_tools|wmllint]].

== Terrain strings ==

The following rules hold for terrain strings. Note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.

* terrain strings are composed from one or more terrain codes of 2 to 4 characters each, separated by ^.
* terrain codes start with a capital letter and the following letters are lower case
* terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
* the underscore is used as a leader for internal terrain codes
* the star '*' can be used for wildcards in some places where a terrain code is required
* the symbol ^ indicates that a terrain is created with layers, for example Gs^Fp means Savanna(Gs) with a Forest(Fp) overlay.

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Terrain Table ===

The list of terrains can be found at [[TerrainCodeTableWML]]. Since most overlays can be combined with most bases the list is not complete.

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/multiplayer/factions/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/core/macros/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

== Decoding the Terrain Codes ==
The initial letters of each terrain code have a standard meaning, though some are not obvious.
* A = “Arctic” i.e. frozen
* B = “Bridge”
* C = “Castle”
* D = “Desert”
* E = "Embellishment"
* F = “Forest”
* G = “Grass”
* H = “Hills”
* I = "Interior" (possible future use)
* J = ''testing''
* K = “Keep”
* L
* M = “Mountains”
* N
* O
* P
* Q = "Un-walkable"
* R = “Road”
* S = “Swamp”
* T
* U = “Underground”
* V = “Village”
* W = “Water”
* X = "Impassable"
* Y = ''Reserved for UMC''
* Z = ''Reserved for UMC''
* _ = "special system stuff"

Additional letters do not always follow the same meaning, but are as consistent as possible.

* \, |, / = for indicating the direction of bridges
* a =
* b =
* c = "city"
* d = "dry or desert, deciduous"
* e = "encampment"
* f = "flowers, fall"
* g
* h = "human"
* i = "ice"
* j
* k
* l = "lava"
* m = "mixed"
* n
* o = "orc"
* p = "pine"
* q
* r
* s = "simple"
* t
* u = "underground"
* v = "elvish"
* w
* x = "chasm"
* y = ''Reserved for UMC''
* z = ''Reserved for UMC''

== See Also ==
* [[TerrainWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TerrainCodesWML

2013-04-13T15:54:16Z

Jamiescott: /* Terrain strings */

{{WML Tags}}

Note: the old (1.2) terrain system is no longer documented here. If you have 1.2 maps you will need to convert them using [[Maintenance_tools|wmllint]].

== Terrain strings ==

The following rules hold for terrain strings. Note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.

* terrain strings are composed from one or more terrain codes of 2 to 4 characters each, separated by ^.
* terrain codes start with a capital letter and the following letters are lower case
* terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
* the underscore is used as a leader for internal terrain codes
* the star '*' can be used for wildcards in some places where a terrain code is required
* the symbol ^ indicates that a terrain is created with layers, for example Gs^Fp means Savanna(Gs) with a Forest(Fp) overlay.

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Terrain Table ===

The list of terrains can be found at [[TerrainCodeTableWML]]. Since most overlays can be combined with most bases the list is not complete.

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/multiplayer/factions/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/core/macros/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

== Decoding the Terrain Codes ==
The initial letters of each terrain code have a standard meaning, though some are not obvious.
* A = “Arctic” i.e. frozen
* B = “Bridge”
* C = “Castle”
* D = “Desert”
* E = "Embellishment"
* F = “Forest”
* G = “Grass”
* H = “Hills”
* I = "Interior" (possible future use)
* J = ''testing''
* K = “Keep”
* L
* M = “Mountains”
* N
* O
* P
* Q = "Un-walkable"
* R = “Road”
* S = “Swamp”
* T
* U = “Underground”
* V = “Village”
* W = “Water”
* X = "Impassable"
* Y = ''Reserved for UMC''
* Z = ''Reserved for UMC''
* _ = "special system stuff"

Additional letters are not always follow the same meaning, but are as consistent as possible.

* \, |, / = for indicating the direction of bridges
* a =
* b =
* c = "city"
* d = "dry or desert, deciduous"
* e = "encampment"
* f = "flowers, fall"
* g
* h = "human"
* i = "ice"
* j
* k
* l = "lava"
* m = "mixed"
* n
* o = "orc"
* p = "pine"
* q
* r
* s = "simple"
* t
* u = "underground"
* v = "elvish"
* w
* x = "chasm"
* y = ''Reserved for UMC''
* z = ''Reserved for UMC''

== See Also ==
* [[TerrainWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

FloodWML

2013-04-11T03:15:33Z

Jamiescott: /* Ranking terrain codes */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and thus create an unwelcome user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs from which the flood starts, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable that stores the current state of the flood (you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by one hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmen
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
Note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because it alters the list of current hexes from the first wave of the flood. When you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming most of the macro's run time is choosing the appropriate terrain type to convert. If you have a wide-spreading flood, this will have to be done for many hexes. Consequently, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you give them, and quit the iteration when the appropriate string is found. If you put the more abundant terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that it converts shallow water to deep (in this example). You start to spread the second with a delay so the first wave will remain ahead.

=== Avoiding obstacles ===
Imagine you have a little stream which spreads straight south and can transform green grass to shallow water. So what happens if it accidentally meets a mountain? It stops. Well, we don't want that - but neither do we want to convert the mountain to anything else. So we can add to the terrain table:
Mm>Mm
This won't change the mountain's type (more precisely, it will be changed from Mm to Mm), and the flood won't regard it as an obstacle anymore. Our stream will continue flowing on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

FloodWML

2013-04-11T03:13:55Z

Jamiescott: /* When to do it? */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and thus create an unwelcome user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs from which the flood starts, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable that stores the current state of the flood (you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by one hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmen
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
Note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because it alters the list of current hexes from the first wave of the flood. When you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming most of the macro's run time is choosing the appropriate terrain type to convert. If you have a wide-spreading flood, this will have to be done for many hexes. Consequently, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you gave them, and quits the iteration when the appropriate string is found. If you put the more often terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that it converts shallow water to deep (in this example). You start to spread the second with a delay so the first wave will remain ahead.

=== Avoiding obstacles ===
Imagine you have a little stream which spreads straight south and can transform green grass to shallow water. So what happens if it accidentally meets a mountain? It stops. Well, we don't want that - but neither do we want to convert the mountain to anything else. So we can add to the terrain table:
Mm>Mm
This won't change the mountain's type (more precisely, it will be changed from Mm to Mm), and the flood won't regard it as an obstacle anymore. Our stream will continue flowing on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

FloodWML

2013-04-11T03:11:13Z

Jamiescott: /* Usage */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and thus create an unwelcome user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs from which the flood starts, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable that stores the current state of the flood (you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by one hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmen
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
Note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because it alters the list of current hexes from the first wave of the flood. When you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming up most of the macro's run time is choosing the appropriate terrain type to convert the original to. If you have a wide-spreading flood, this will have to be done for many hexes. Conclusively, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you gave them, and quits the iteration when the appropriate string is found. If you put the more often terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that it converts shallow water to deep (in this example). You start to spread the second with a delay so the first wave will remain ahead.

=== Avoiding obstacles ===
Imagine you have a little stream which spreads straight south and can transform green grass to shallow water. So what happens if it accidentally meets a mountain? It stops. Well, we don't want that - but neither do we want to convert the mountain to anything else. So we can add to the terrain table:
Mm>Mm
This won't change the mountain's type (more precisely, it will be changed from Mm to Mm), and the flood won't regard it as an obstacle anymore. Our stream will continue flowing on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

FloodWML

2013-04-11T03:01:07Z

Jamiescott: /* Avoiding obstacles */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include it here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and so make a serious blow on user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs where the flood starts from, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable to store the current state of the flood in (but you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by on hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmans
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
One note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because that alters the list of hexes which are currently form the first wave of the flood. So if you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming up most of the macro's run time is choosing the appropriate terrain type to convert the original to. If you have a wide-spreading flood, this will have to be done for many hexes. Conclusively, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you gave them, and quits the iteration when the appropriate string is found. If you put the more often terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that it converts shallow water to deep (in this example). You start to spread the second with a delay so the first wave will remain ahead.

=== Avoiding obstacles ===
Imagine you have a little stream which spreads straight south and can transform green grass to shallow water. So what happens if it accidentally meets a mountain? It stops. Well, we don't want that - but neither do we want to convert the mountain to anything else. So we can add to the terrain table:
Mm>Mm
This won't change the mountain's type (more precisely, it will be changed from Mm to Mm), and the flood won't regard it as an obstacle anymore. Our stream will continue flowing on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

FloodWML

2013-04-11T02:58:15Z

Jamiescott: /* Two-wave flood */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include it here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and so make a serious blow on user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs where the flood starts from, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable to store the current state of the flood in (but you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by on hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmans
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
One note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because that alters the list of hexes which are currently form the first wave of the flood. So if you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming up most of the macro's run time is choosing the appropriate terrain type to convert the original to. If you have a wide-spreading flood, this will have to be done for many hexes. Conclusively, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you gave them, and quits the iteration when the appropriate string is found. If you put the more often terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that it converts shallow water to deep (in this example). You start to spread the second with a delay so the first wave will remain ahead.

=== Avoiding obstacles ===
Imagine that you have a little stream which spreads straight to south and can transform green grass to shallow water. So what does happen if it accidentally meets a mountain? It stops. Well, we don't want that - but neither to convert the mountain to anything else. So we can add this to the terrain table:
Mm>Mm
This won't change the mountains type (more precisely, it will be changed from Mm to Mm), but the flood won't regard it as an obstacle anymore. Our example stream will continue on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

FloodWML

2013-04-11T02:56:25Z

Jamiescott: /* Switching terrain table */

'''FloodWML works for 1.9 and above'''

== Usage ==
You can find sources at the bottom of the page. It's too long to include it here.

'''NOTE: these macros are performing lots of complex calculations thus they are quite slow. They can make your scenario lag and so make a serious blow on user experience, especially on older machines. To make sure you've minimized the negative effects, please read the Optimization section below.'''

=== Create flood ===
{CREATE_FLOOD "1,1;2,3" "ne,n" "Gg>Ww;Gs>Wwt" awesome_flood}
Where "1,1;2,3" is a semicolon separated list of coordinate pairs where the flood starts from, "ne,n" is a comma separated list of directions in which the flood will spread, "Gg>Ww;Gs>Wwt" is a semicolon separated list of transformations where a>b means that the hexes with the terrain code a will be converted to b, and finally awesome_flood is the variable to store the current state of the flood in (but you might better think about it as the flood's id).

=== Spread flood ===
{SPREAD_FLOOD awesome_flood}
Where awesome_flood is the flood's id :). This will spread the flood by on hex. If a hex with a unit is flooded, an event named 'submerged' will be fired. Example
#kill all sunken spearmans
[event]
name=submerged
[filter]
type=Spearman
[/filter]

[kill]
id=$unit.id
animate=yes
[/kill]
[/event]

=== Modify flood data ===
{SET_FLOOD_DIRECTIONS "se,s" awesome_flood}
{SET_FLOOD_TERRAIN_TABLE "Gg>Wwg;Gs>Ww" awesome_flood}
{SET_FLOOD_SOURCE "3,3;5,4;6,6" awesome_flood}
One note: all of these macros replace current data in awesome_flood, so old information is lost. This is especially important for SET_FLOOD_SOURCE because that alters the list of hexes which are currently form the first wave of the flood. So if you call it, the original flood will stop and a new one will start from "3,3;5,4;6,6" or whatever you specify.

== Optimization ==

=== When to do it? ===
The part consuming up most of the macro's run time is choosing the appropriate terrain type to convert the original to. If you have a wide-spreading flood, this will have to be done for many hexes. Conclusively, if you have a big flood with a big terrain table, it's likely that you'll have to optimize it.

=== Ranking terrain codes ===
When searching for the matching terrain code for a specific hex, the algorithm will iterate through the terrain table's elements in the order you gave them, and quits the iteration when the appropriate string is found. If you put the more often terrains to the front, you can achieve radical performance improvements.

=== Switching terrain table ===
Sometimes it's hard to decide which code to put first because different ones are common in different stages of the flood. For example, an avalanche starts at a mountain, where there are mostly hills, but it reaches the plains where it finds more flat terrain. In this case, it's best to completely replace the terrain table with the SET_FLOOD_TERRAIN_TABLE macro, so you can give higher rankings to the new common terrains.

== Tips & Tricks ==

=== Two-wave flood ===
It's not unimaginable that you want to make your flood heterogeneous - for example, shallow water on the edges and deep water in the middle. You can't do this with one flood - but you can with two! You set up the first one just as normal, and the second one in a way that that it converts shallow water to deep (in this example). You start to spread the second with a delay so that the first wave will be ahead.

=== Avoiding obstacles ===
Imagine that you have a little stream which spreads straight to south and can transform green grass to shallow water. So what does happen if it accidentally meets a mountain? It stops. Well, we don't want that - but neither to convert the mountain to anything else. So we can add this to the terrain table:
Mm>Mm
This won't change the mountains type (more precisely, it will be changed from Mm to Mm), but the flood won't regard it as an obstacle anymore. Our example stream will continue on the other side of the mountain hex.

== Source Code ==

#define INVERT_DIRECTIONS DIRECTIONS OUT_VAR
#a macro to change directions to their opposites (n->s, sw->ne, etc)
#DIRECTIONS is a comma-separated list of directions
#OUT_VAR is the variable to write the output in.

[set_variables]
name=TMP_inverted_directions
[split]
list={DIRECTIONS}
separator=","
key=direction
remove_empty=yes
[/split]
[/set_variables]

{FOREACH TMP_inverted_directions TMP_ID_i}
[set_variable]
name=TMP_inverted_directions[$TMP_ID_i].direction
value="-" + $TMP_inverted_directions[$TMP_ID_i].direction
[/set_variable]
{NEXT TMP_ID_i}

{CLEAR_VARIABLE {OUT_VAR}}

[set_variable]
name={OUT_VAR}
[join]
variable=TMP_inverted_directions
separator=","
key=direction
[/join]
[/set_variable]

{CLEAR_VARIABLE TMP_inverted_directions}
#enddef

#define STORE_FLOODABLE_LOCATIONS SOURCE DIRECTIONS TERRAINS OUT_VAR
#stores hexes of type TERRAINS whose neighbour in one of DIRECTIONS directions can be found in SOURCE
#SOURCE an array of locations
#DIRECTIONS is a list of directions
#TERRAINS comma-separated list of terrain codes
#OUT_VAR the variable to write the output in
#
#NOTE: this macro is in fact used to store the hexes of type TERRAINS which are neighbours of SOURCE in
#certain directions, but we achieve that by inverting those directions outside of this macro. See INVERT_DIRECTIONS.

[store_locations]
variable={OUT_VAR}

terrain={TERRAINS}

[filter_adjacent_location]
adjacent={DIRECTIONS}
find_in={SOURCE}
[/filter_adjacent_location]
[/store_locations]
#enddef

#define SPLIT_PAIRS PAIRS SEP1 SEP2 OUT_VAR
[set_variables]
name=TMP_pairs
[split]
list={PAIRS}
key=pair
separator={SEP1}
remove_empty=true
[/split]
[/set_variables]

{FOREACH TMP_pairs TMP_SP_i}
[set_variables]
name=TMP_splitted
[split]
list=$TMP_pairs[$TMP_SP_i].pair
separator={SEP2}
key=value
[/split]
[/set_variables]

[set_variable]
name={OUT_VAR}[$TMP_SP_i].value1
value=$TMP_splitted[0].value
[/set_variable]
[set_variable]
name={OUT_VAR}[$TMP_SP_i].value2
value=$TMP_splitted[1].value
[/set_variable]
{NEXT TMP_SP_i}

{CLEAR_VARIABLE TMP_pairs}
{CLEAR_VARIABLE TMP_splitted}
#enddef

#define FLOOD_SINGLE_HEX X Y TERRAIN_TABLE
[store_locations]
variable=TMP_current_hex
x={X}
y={Y}
[/store_locations]

{FOREACH {TERRAIN_TABLE} FSH_i}
[if]
[variable]
name=TMP_current_hex.terrain
equals=${TERRAIN_TABLE}[$FSH_i].value1
[/variable]
[then]
{MODIFY_TERRAIN ${TERRAIN_TABLE}[$FSH_i].value2 {X} {Y}}
[set_variable]
name=FSH_i
value=${TERRAIN_TABLE}.length
[/set_variable]
[/then]
[/if]
{NEXT FSH_i}

{CLEAR_VARIABLE TMP_current_hex}
#enddef

#define SET_FLOOD_TERRAIN_TABLE TERRAIN_TABLE DATA_VAR
{SPLIT_PAIRS {TERRAIN_TABLE} ";" ">" {DATA_VAR}.terrain_table}
[set_variable]
name={DATA_VAR}.floodable_terrains
[join]
variable={DATA_VAR}.terrain_table
separator=","
key=value1
[/join]
[/set_variable]
#enddef

#define SET_FLOOD_DIRECTIONS DIRECTIONS DATA_VAR
{INVERT_DIRECTIONS {DIRECTIONS} {DATA_VAR}.directions}
#enddef

#define SET_FLOOD_SOURCE SOURCE DATA_VAR
{SPLIT_PAIRS {SOURCE} ";" "," TMP_source_coordinates}
[set_variable]
name=TMP_fields_x
[join]
variable=TMP_source_coordinates
key=value1
separator=","
[/join]
[/set_variable]
[set_variable]
name=TMP_fields_y
[join]
variable=TMP_source_coordinates
key=value2
separator=","
[/join]
[/set_variable]

[store_locations]
variable={DATA_VAR}.fields
x=$TMP_fields_x
y=$TMP_fields_y
[/store_locations]
#enddef

#define CREATE_FLOOD SOURCE DIRECTIONS TERRAIN_TABLE DATA_VAR
[clear_variable]
name={DATA_VAR}
[/clear_variable]

{SET_FLOOD_SOURCE {SOURCE} {DATA_VAR}}
{SET_FLOOD_TERRAIN_TABLE {TERRAIN_TABLE} {DATA_VAR}}
{SET_FLOOD_DIRECTIONS {DIRECTIONS} {DATA_VAR}}
#enddef

#define SPREAD_FLOOD DATA_VAR
{STORE_FLOODABLE_LOCATIONS {DATA_VAR}.fields ${DATA_VAR}.directions ${DATA_VAR}.floodable_terrains {DATA_VAR}.fields}

{FOREACH {DATA_VAR}.fields TMP_SF_i}
{FLOOD_SINGLE_HEX ${DATA_VAR}.fields[$TMP_SF_i].x ${DATA_VAR}.fields[$TMP_SF_i].y {DATA_VAR}.terrain_table}
{NEXT TMP_SF_i}
[redraw][/redraw]

[store_unit]
variable=TMP_submerged_units
[filter]
[filter_location]
find_in={DATA_VAR}.fields
[/filter_location]
[/filter]
[/store_unit]

{FOREACH TMP_submerged_units TMP_SF_i}
[fire_event]
[primary_unit]
id=$TMP_submerged_units[$TMP_SF_i].id
[/primary_unit]
name=submerged
[/fire_event]
{NEXT TMP_SF_i}

{CLEAR_VARIABLE TMP_submerged_units}

#enddef

== See Also ==
* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

Timeline of Wesnoth

2013-03-12T19:43:27Z

Jamiescott: /* After the Fall */

This is a chronological history of the country of Wesnoth and surrounding regions, gleaned from written accounts and verbal histories passed down through the generations. Portions of entries surrounded by parentheses and containing a question mark are assumed or unconfirmed information. The history is sorted by era, and within the era by date, using the Foundation of Wesnoth as a base. BW=Before Wesnoth, YW=Years Wesnoth. They function the same way as BC and AD do in our timekeeping system. Each of the eras is summarized before the timeline for that era begins. This history of the Great Continent is a subject of active scholarship.

The world that Wesnoth resides in is called Irdya. Before the Fall and the (unchronicled) technological age, this name is only rarely used.

'''Spoiler warning!'''
This page contains plot spoilers to several campaigns.

__NOTOC__
[[#Prehistory - 20 YW: The Founding of Wesnoth|The Founding of Wesnoth]]

[[#20-130 YW: The Taming of the Wild|The Taming of the Wild]]

[[#200-350 YW: The Golden Age of Wesnoth|The Golden Age of Wesnoth]]

[[#350-417 YW: The First Dark Age of Wesnoth|The First Dark Age of Wesnoth]]

[[#417-530 YW: The Turmoil of Asheviere|The Turmoil of Asheviere]]

[[#530-630 YW: The Age of Fear|The Age of Fear]]

[[#628-673 YW: The Silver Age of Wesnoth|The Silver Age of Wesnoth]]

[[#761-816 YW: The Legacy of Black-Eye Karun|The Legacy of Black-Eye Karun]]

[[#After the Fall|After the Fall]]

== Prehistory - 20 YW: The Founding of Wesnoth ==
During the age of the Founding of Wesnoth, there were two important geographic locations, these being the Green Isle and the Great Continent. Haldric is the main historical figure at this time. This age ends with the founding of Wesnoth as a country in the Great Continent, and with Orcs attacking both elves and men from the sea.

=== Prehistory ===
* Elves and Dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle] from a continent further to the west.

=== 200 BW ===
* The Lich-Lords arrive on the Green Isle after losing a war in the distant West.
* After a long war Haldric's people come to dominate the Green Isle.
* The 'Wesfolk' and their Lich-Lords are pushed onto marginal lands.

=== 12 BW ===
* The Crown Prince of Southbay discovers the Great Continent.

=== 11-7 BW ===
* The Crown Prince makes several voyages between the Green Isle and the Great Continent.

=== 6 BW ===
* Following these voyages to the Great Continent, the elder Crown Prince falls ill and dies.
* His younger brother is implicated in a plot to kill him.
* As a distraction the younger Prince starts a war with the Wesfolk and their Lich-Lords.
* The Lich-Lords sense they will be destroyed and open gates to the homeland of the Orcs in the West.

=== 5-2 BW ===
* The Green Isle is overrun with Orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the Orcs.
* [http://wiki.wesnoth.org/CharactersStorys#Prince_HaldricPrince Haldric] leads the evacuation of the survivors to the Great Continent. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth '''The Rise of Wesnoth'''] begins.

=== 1 BW ===
* Human settlers, led by Prince Haldric, arrive at the western coast of the Great Continent (the landfall occurs in the future Bay of Pearls) in large numbers.
* Humans arrive in the middle of a simmering dispute between the Elves and Dwarves.
* The Elves and Dwarves are distrustful of humans, and there is a small skirmish.
* Messengers from Wesmere Forest come and ask Haldric to come before the Ka'lian.
* Prince Haldric asks the Four Elvish Lords ([http://wiki.wesnoth.org/CharactersStorys#Lady_Dionli Dionli], [http://wiki.wesnoth.org/CharactersStorys#Lord_Logalmier Logalmier], Aryad, and El'Isomithir) for help and land.
* They set before him four quests to prove his worth, which he completes.

=== 1 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric] is granted the plains north and south of the Great River.
* Haldric agrees to a Pact of Mutual Defence with the Elves, but the Ka'lian decides it will betray him and allow humans and orcs to exhaust each other in war if the opportunity presents. Haldric, learning of this, considers the Pact a dead letter.
* The Ruby of Fire is temporarily hidden, and the [http://wiki.wesnoth.org/CharactersStorys#Lich-Lord_Jevyan lich-lord Jevyan] is deceived into believing it is held by the Elves.
* Haldric founds the country of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] in the central plain south of the great River.
* Reign of Haldric I (formerly prince Haldric) begins. [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth '''The Rise of Wesnoth'''] ends.

=== 2 YW ===
* Orcs, following the ships fleeing from the Green Isle, begin to arrive on the Great Continent.
* These Orcs are defeated by Haldric's forces.
* Some of the Orcish survivors flee back to the Green Isle, others move to attack the Elves.
* King Haldric helps the Elves fight the surviving Orcs.

=== 8 YW ===
* A second wave of Orcs arrive from the Green Isle; these Orcs begin claiming large portions of the northern Great Continent for themselves.
* [http://wiki.wesnoth.org/CharactersStorys#Erlornas Erlornas] of Wesmere is involved in the first direct elvish clash with orcs ([http://wiki.wesnoth.org/Mainline_Campaigns#An_Orcish_Incursion '''An Orcish Incursion'''] takes place in 8-9YW).
* Haldric I publicly repudiates the Pact he spoke with the Elves, refusing to give aid.

=== 9-11 YW ===
* Many Elves are killed in battle by the Orcs.
* Elvish emissaries are turned away from Wesnoth.

=== 12 YW ===
* Orcs fail to take the Wesmere Forest and instead march down the coast, devastating human settlements there.
* Elves refuse to aid the Humans in confronting the Orcs.
* Human refugees from the coastal settlements relocate in what will become known as the Great Central Plain. Dan'Tonk, which will become Wesnoth's largest city, is founded.

=== 20 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric I] dies.
* [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] ascends to the throne.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] escape an orcish invasion of their home in Lintanir Forest. [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere'''] begins.
* Humans and elves decisively defeat the orcs at Tath, thus halting the orcish advance.
* A new treaty between humans and elves is signed and King Haldric II allows emissaries of the Elves to return to Wesnoth.
* Elves inform [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] of the danger posed by the unshielded Ruby of Fire.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar], later to become successive High Lords of the Elves, are able to sneak into an orcish camp by stealth and assassinate the Great Chief Brurbar. A long orcish civil war for succession follows. The orcs are unable to undertake action against any other race during this period and Wesnoth enjoys a long period during which it can expand with little opposition.

== 20-130 YW: The Taming of the Wild ==
This era is that in which the kingdom of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] expanded and defined its borders, and settled the area which it had claimed for its own. The Taming of the Wild refers to the settling of the unsettled lands, as well as to the colonization of the Northlands. The end of this era is marked by friction between the city-state of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] and the country of Wesnoth, which will continue for the next several hundred years.

=== 21 YW ===
* Founding of the Great Academy on Alduin.

* [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz] is relieved of command by the Ka'lian. He retires to Lintanir Forest with [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil]. A faction of xenophobic elves begins to gether around [http://wiki.wesnoth.org/CharactersStorys#Landar Landar].

=== 25-40 YW ===
* In 25 YW [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a Dwarven tribe to build the Scepter of Fire with the Ruby of Fire as its centerpiece; Elves associated with [http://wiki.wesnoth.org/CharactersStorys#Landar Landar's] faction attack during the transfer. [http://wiki.wesnoth.org/Mainline_Campaigns#Sceptre_of_Fire '''Scepter of Fire'''] begins.
* Action of '''The Scepter of Fire''' takes place. Haldric II is informed that the Scepter was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [http://wiki.wesnoth.org/CharactersStorys#Thursagan Thursagan], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.

=== 26-50 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] declares himself High Lord of the Elves, leading to civil war.

=== 51 YW ===
* Wesnothian New Writing (the script later called "steel-hand", to distinguish it from the more complex "brush-hand" cursive brought from the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle]) is promulgated by royal decree. From this date all royal documents and public inscriptions are in New Writing. It spreads rapidly via the mercantile class. The older brush-hand writing continues to be used for magical purposes, scholarship, and in certain elevated literary forms.

=== 50-93 YW ===
* Elvish civil war (and [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere''']) ends. [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] declared High Lord, begins reorganizing and militarizing Elvish society to fight the orcs. In late 93 YW he cedes control to a reconstituted Ka'lian and retires again to the Forest of Lintanir.

=== 121 YW ===
* Orcish civil war sputters to a halt. Raids on elves and humans resume. Period of uncontested human expansion ends, but the [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnothian] Army is more than equal to any of its opponents in battle.

=== 122 YW ===
* City of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] is sacked by orcs.
* Meneldur, a sailor of Elensefar, sets out on a quest to regain the city. UMC '''Saving Elensefar''' begins.

=== 123 YW ===
* Elensefar is retaken by Meneldur along with Undead from the Green Isle.
* Elensefar becomes an independent city-state for the first time. UMC '''Saving Elensefar''' ends.

=== 161-164 YW ===
* The newly crowned king sought to make safe once and for all the wildlands that separated the human cities surrounding Weldyn and the coastal regions of Elensefar.
* The grand army of Wesnoth, personally led by the High Council of Archmagi, destroyed all enemies residing within Wesnoth.
* The city-state of Elensefar is formally united to the kingdom. Settlements from it spread north of the river into the new frontier province of Annuvin, carefully avoiding the margins of Wesmere Forest.

=== 164-176 YW ===
* During this twelve year span, the western fortress of Halstead was erected in the very heart of the western wilderlands.

=== 199 YW ===
* Emboldened by the far-reaching arm of Halstead's protection, settlement in the west explodes
* The settlements of Aldril and Carcyn grow to become major cities, the first as an important port due to its position on the Bay of Pearls, and the second as a stop on the road to Elensefar and military outpost along the Great River
* Settlers from Carcyn cross the Great River to establish the first settlements north of it and east of Wesmere.

== 200-350 YW: The Golden Age of Wesnoth ==
The Golden Age of Wesnoth was the time of the great kings, and of peace and prosperity within the kingdom. The Orcs had suffered a grave defeat at the hands of Wesnoth and Elensefar seventy-five years earlier, so they did not pose much of a threat, and whenever they did attack they were quickly defeated. This allowed the army to lessen in size, and the kings of this age to undertake the great public works they are renowned for. The era ends when the king of Wesnoth dies without an heir, and a new dynasty begins.

=== 251 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil], wife of [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz], dies.

=== 350 YW ===
* Disintegration of the Kingdom follows the death of Haldric IV.
* [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] remains a province of Wesnoth but exerts increasing independence due to isolation.
* Treaty between lord of Elensefar and king of Wesnoth signed.

== 350-417 YW: The First Dark Age of Wesnoth ==
The first Dark Age was a time of strife and invasion. When Haldric IV died, he left Wesnoth without a king, and the next 70 years were marked by short-lived dynasties, attacks by ever more aggressive orcs, and the further separation of Wesnoth and Elensefar. The Dark Age ended when Garard I took the throne, and began a new dynasty that would last for several hundred years.

=== 360 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] born in Parthyn.

=== 363 YW ===
* Last of [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz's] children dies. Kalenz, condemned to outlive his offspring by the potion of Crelanu, leaves the Forest of Lintanir and begins wandering the Great Continent.

* Village of Maghre terrorized by a minor necromancer. Action of [http://wiki.wesnoth.org/Mainline_Campaigns#A_Tale_Of_Two_Brothers '''A Tale of Two Brothers'''] takes place.

=== 389 YW ===
* Garard, a future king of Wesnoth, is born.
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] returns to Parthyn from the Academy at Alduin. [http://wiki.wesnoth.org/Mainline_Campaigns#Descent_into_Darkness '''Descent Into Darkness'''] begins.

== 417-530 YW: The Turmoil of Asheviere ==
King Garard's dynasty was long-lived and productive, but it was also punctuated by significant turmoil: the end of the first king's reign was marred by orcish and undead raids, and the second was murdered by his own wife and son. It was not until 517 YW that the usurpation of the throne by Queen Mother Asheviere was ended.

=== 417 YW ===
* Ending years of strife and division, Garard I seizes the throne and becomes king of Wesnoth, beginning the [[Garardine Dynasty]].

=== 440 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Garard_II Crown Prince Garard II] is born.

=== 442 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador], later called "the Great", is born.

=== 450 YW ===
* Prince Arand is born.

=== 468 YW ===
* Zorlan becomes Great Chief of the northern orcs
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador] graduates from the Great Academy. [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs '''Delfador's Memoirs'''] begins.

=== 470 YW ===
* Garard I dies; [http://wiki.wesnoth.org/CharactersStorys#Garard_II Garard II] ascends to the throne of Wesnoth
* Orcs under Great Chief Zorlan and undead raised by the necromancer [http://wiki.wesnoth.org/CharactersStorys#Iliah-Malal Iliah-Malal] raid Wesnoth's borders. All but the first and the last three scenarios of [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs'''Delfador's Memoirs''' ] take place in this year.
* Control of the Estmarks is effectively lost during this war, not to be regained for decades. Outposts are built on the near side of the Weldyn to repel orc raids. The long watch of the River Guard begins.

=== 478 YW ===
* Garard II marries Asheviere.
* Garard issues the Edict of the Scepter, providing that the crown shall settle after his death on whichever member of the royal family successfully retrieves it from the Caverns of Flame.

=== 480 YW ===
* Crown Prince Eldred is born.

=== 483 YW ===
* Erain and Ethyn, identical twins and brothers of Eldred, are born.

=== 498 YW ===
* Princess Li'sar is born.

=== 500 YW ===
* Prince Konrad is born, the youngest of several sons of Prince Arand.
* Wesnoth and the orcs of the north go to war.

=== 501 YW ===

===== Betrayal on the battlefield =====
* Garard leads his army to orc encampment at Galcadar by the Ford of Abez.
* Garard's forces split into two groups, one led by himself and the other by his son Eldred.
* Eldred betrays his father and attacks him with the troops under his control.
* Eldred slays King Garard and his uncle Prince Arand on the battlefield of Abez.

===== Reprisal =====
* Delfador escapes the battle and heads to Weldyn.
* Eldred gives tribute to the Orcish king, who stops his attacks.
* Delfador gathers a force of Loyalists to avenge Garard's Death.
* Eldred's forces confront Delfador's Loyalists at Weldyn.
* The Loyalists are defeated, but Eldred is slain by Delfador in the fight.

===== Asheviere seizes power =====
* Asheviere orders the slaughter of Garard's nephews and declares herself Queen of Wesnoth.
* Hearing of the news Delfador infiltrates the palace.
* Delfador finds the youngest prince Konrad as he is slain.
* Delfador flees, taking Konrad's body for burial to the land of the Elves.
* While traveling through Wesnoth, Elf Lady Parandra finds an orphaned human child.
* Parandra and Delfador agree to give the orphan the identity of Prince Konrad.
* Delfador and Konrad flee to live in refuge with the Wood Elves of the great southwestern forest.

===== The country resists Asheviere =====
* Elensefar refuses to submit to Asheviere and declares itself an independent city-state.
* After several defeats, Wesnoth's army retreats from the remote areas of the kingdom. The western Wesnothian border recedes, is fixed, and remains heavily defended.
* As a result of the loyalist withdrawal, several small human communities on the west coast of the Great Continent live in relative independence while elves flourish in the great forest to the southwest of Wesnoth.
* A band of Wesnoth citizens organizes resistance to Asheviere's siezure of power. They are eventually forced to abandon their home and settle in the Three Sisters ('''Liberty''').

=== 502-517 YW ===
* Delfador raises Konrad under the protection of the Elves.

=== 517 YW ===
* Asheviere hires Orcish forces to hunt down her nephew-in-law Konrad.
* Orcish forces converge on Delfador's refuge.
* Konrad flees his home with the elves and embark upon a quest to regain the throne of Wesnoth. '''Heir To The Throne''' begins.

=== 518 YW ===
* Konrad crosses the Great River into the Northlands on a search for the Sceptre of Fire.
* They enter the Caves of Knalga, allied with Princess Li'sar, and find it.
* They return to Wesnoth and claim the throne. '''Heir to the Throne''' ends.

=== 522 YW ===
* Birth of Princess Ana'sar.

=== 530 YW ===
* Wesnothian colonists begin reclaiming the Estmarks.

=== 544 YW ===
* With both sides of the lower Weldyn River again civilized territory, the River Guard posts south of Soradoc are abandoned. Wesnothian military activity shifts eastward into the Estmarks.

== 530-630 YW: The Age of Fear ==
The Age of Fear takes its names from the events of the end of the era. On the surface, the first 90 years were very uneventful. However, during this time unexplainable magical events took place, especially in the eastern lands. Previously tamed lands were slowly claimed by wilderness as fear and paranoia gradually overshadowed the spirit of pioneering and adventure displayed earlier in Wesnoth's history. In the last 10 years of the age, Wesnoth bore the brunt of the most powerful Undead attack ever and was nearly destroyed. By the end of the era, most of Wesnoth had been made barren, most of the great buildings inside and outside of Weldyn were razed, and the population of Wesnoth was half of what it had been.

It was in this era that certain areas of the chaotic Northlands were for the first time put into any kind of law and order. A small group of humans and dwarves, accepting anyone of any race who wished to join, formed themselves into the "Northern Alliance”, with the vision of making the Northlands safe to live in. Over time, this alliance grew slowly but steadily in power. By the end of the era, the alliance had succeeded in making a few small areas, including Knalga and the surrounding regions, stable and prosperous. Consequently, many people evacuated from the wasteland that most of Wesnoth had become and moved north - depleting the population of Wesnoth still further.

=== 533 YW ===
* Delfador succumbs to old age and dies, his body is entombed alongside his staff in Eregonor.
* The next great sage of Wesnoth, [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn], is born.

=== 534 YW ===

* The small community of Dwarven Doors, in the Northlands just outside Knalga, rebels against the Orcish overlords. '''Northern Rebirth''' begins.
* The residents, led by Tallin, head underground and find dwarves, whom they ally with.
* Their combined forces destroy a lich who is attempting to claim Knalga as his own.
* Abhai finds the [http://wiki.wesnoth.org/CampaignDialogue:NR#Abhai_Finds_Rod_of_Justice Rod of Justice]

=== 535 YW ===

* The warlord-aspirant Rakshas attacks Tallin and his forces, but does not penetrate the dwarves' defences.
* To help defeat the orcs, Tallin secures the help of two Liches, and rescues an elvish princess to secure the help of the elves.
* Assisted by his new allies, Tallin smashes the forces of Rakshas.
* According to some historians, Tallin and the elvish princess are married; others say they parted in bad blood.
* To preserve the new-found peace in the Northlands, Tallin and his allies form the Northern Alliance. '''Northern Rebirth''' ends.

=== 550 YW ===

* Lord Hamel of Knalga sends an expedition to Kal Kartha to determine the fate of the Hammer of Thursagan ('''The Hammer of Thursagan''' takes place in late 550 YW to early 551 YW.).
* Dwarves at Knalga and elsewhere begin to reclaim the lost art of runesmithing.
* Wesnothian colonization expands southward past Fort Tahn.

=== 563 YW ===
* Konrad and Li'sar die after an extraordinarily long reign.
* Princess Ana'sar becomes queen.
* The seer Galdren becomes prominent at the court of Weldyn.

=== 585 YW ===
* Queen Ana'sar retires.
* Haldric VII becomes king of Wesnoth.

=== 589 YW ===
* Dacyn the White Mage and Ravanal, an eastern wizard, compete to be the king's advisor.
* The seer Galdren dies after advising Haldric VII to choose Dacyn.
* The king does as Galdren advises.

=== 593 YW ===
* Ravanal reveals that he has turned to evil, and flees from Weldyn.
* Konrad II is born.
* Certain southern frontier regions are formally annexed to the Kingdom of Wesnoth as the Province of Kerlath.

=== 598 YW ===
* South Guard organized as a semi-detached formation of the Royal Army, to protect the inhabitants of the frontier province of Kerlath.

=== 605 YW ===
Gweddry born ???

=== 607 YW ===
* South Guard ceases reporting. Haldric VII sends Deoran, son of Haldiel, to investigate. '''The South Guard''' takes place in 607-608 YW.

=== 612 YW ===
* Haldric VII dies. Konrad II is crowned King of Wesnoth.
* Dacyn continues his duties as advisor with Konrad II.

=== 625 YW ===
* Mysterious disappearances of livestock and peasants cause partial evacuation of the the '''Estmark Hills'''. Lords of the Horse Plains report increased banditry from there.
* Konrad II sends [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec] and [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] to man the old River Guard strongpoints. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion'''] begins.

=== 626 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal] attacks the middle outpost where [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] and [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] are stationed.
* Dacyn and Gweddry travel to the northern outpost, and, with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec], retreat into the northlands.
* In the Far North, the wife of Kai Laudiss slain in a large raid by the orcs of Tirigaz on Jotha
* Kai Laudiss slain by poisoned orcish dart during failed attack on the Port of Tirigaz orcs. His son, [http://wiki.wesnoth.org/CharactersStorys#Kai_Krellis Krellis] suceeds him as Kai and relies on the wisdom of [http://wiki.wesnoth.org/CharactersStorys#Cylanna Cylanna], a priestess.
* The merfolk city of Jotha is overrun by undead (Mal Kevek and others). The action of [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water '''Dead Water'''] takes place.

=== 627 YW ===
* Wesnoth's last defences are broken and the undead march on Wesnoth
* In the northlands, the orcs drive [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry's] army back across the river.
* Weldyn is besieged.
* Gweddry breaks through undead lines to reach Weldyn and a council is held.
* Gweddry's army is fortunate and kills [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal]. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion''' ] ends. [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_water '''Dead Water'''] ends (about this time).
* Wesnoth is saved, but large portions have been laid waste by the undead.
* After destroying [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal's] henchmen the mermen relaxed and began rebuilding in earnest, and soon Jotha was restored.

== 628-673 YW: The Silver Age of Wesnoth ==

The Silver Age, or restoration of the Wesnothian kingdom, essentially coincides with the rest of the long and successful reign of [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II]. During this period Wesnoth largely recovered from the damage that Mal-Ravanal's undead attack had done. It would, however, never quite regain the majesty it had at the height of its power.

The Northlands, aided by a second wave of colonization north from Wesnoth, become more civilised and stable. Although nowhere near as prosperous as Wesnoth was during its Golden Age, the Northlands developed towns of significant size and a thriving - if somewhat dangerous - trade network.

Four major powers soon came to dominate much of the Northlands. First there were the dwarves, who controlled most of the mountains and a vast array of underground tunnels and caverns. To the east, shrouded in mystery, lay the Elvish forests which continued to be inaccessible to anyone not of elvish blood. The remaining landscape was dominated either by orcish tribes, or independent human earldoms. As competition for the land grew fierce, wars smoldered between human and orcish forces.

=== 628-635 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 761-816 YW: The Legacy of Black-Eye Karun ==

After decades of struggle, Black-Eye Karun becomes the first warlord since the assassination of Great Chief Brurbar in 20 YW to unite all the different squabbling orcish tribes under his banner. Among his many accomplishments as a Sovereign, his most famous is the creation of the Great Council.

Karun was a far-sighted individual and he knew that after his death the orcish tribes would once again turn to fighting among themselves, with little he could do to prevent that and consequent peril from the Wesnothians and elves.

Consequently, Karun selected from among all the different tribes six of the most sober and wisest orcs and thus created the Great Council. It was the Great Council's job to stay aloof from any tribal or territorial squabbling amongst the orcs, but yet always remain there to give advice to whomever came to seek it. In order to preserve the orcish race in the event of an emergency, he invested in them the power to call up The Great Horde. It was established that every orc, no matter what tribe he came from, must obey the summons of The Great Horde and follow wholeheartedly the leader that the Great Council put at the head of The Great Horde.

===812 YW===
Rahul I becomes Lord Protector of the Northern Alliance

===816 YW===
* Rahul I (Lord Protector of the Northern Alliance) and Black Eye Karun sign a peace treaty ending a 15 year war between the humans and the orcs. Soon after this Karun, is ambushed and killed in mysterious circumstances.

===829===
Howgarth III succeeds Rahul I as Lord Protector of the Northern Alliance

===842 YW===
* Famine in the Northlands. Famine led humans to colonize some orcish lands and push orcs into desolated hill country. The few orcish tribes who had remained part of the Alliance, feeling the pressure, either left Alliance territory or revolted and were destroyed.
* Retaliating, the orcs systematically slaughtered human colonies and villages on their lands. Then, Earl Lanbec'h — the most powerful human warlord of the North — determined to abolish the orcish menace raised an army and conferred leadership of it to his son-in-law Baron Alber.
* In response, the Great Council set up by the Black Eye Karun calls upon The Great Horde and bestows leadership of it upon [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]; [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] begins.

===843 YW===
* Half of the Great Council is treacherously slain by the allied human forces and orcish unity disintegrates. Faced with the extermination of all the orcs on the Great Continent, [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] forcibly asserts his control over the orcish territories and defeats the enemy forces. The Northern Alliance arrives on the scene in time for the final battle and helps Kapou’e defeat the forces of the northern earldoms, who had broken the treaty. Kapou’e then assumes the position of Sovereign over the northern tribes, and his rule ushers in an unprecedented era of unity and prosperity for the orcs.
* After 843: Portions of Kapou'e's army act as mercenaries in foreign struggles with other races which keeps them from attacking their nearest neighbors.

===852 YW===
*[http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] repels a large elvish invasion.

===858 YW===

*The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]. [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] ends.

==After the Fall==
At some unknown point in the future, an unspeakable cataclysm scorched the surface of the lands. The Wesnoth magicians try to raise up a 3rd sun in the sky, but they fail and the 'sun' falls down over Weldyn. The capital is no more. The King and his family are dead and there is no heir. The local leaders tear apart Wesnoth. The nights become longer, days hotter. Evil creatures show up. Forests die, hills turn into rocky wastelands and fields become barren deserts. In the apocalypse allies turn against each other and friends fight over what few resources remain. The great nations were destroyed, and huge numbers of people died. Still amidst the chaos somehow small groups of people survived, sheltered in hidden places. In this post-apocalyptic world survival is a daily struggle as a few remaining tribes eke out an existence among the ruins of fallen empires. Heroic bands of elves, nomadic refugee humans, savage hordes of orcs and dark necromancers all forge new lives under the merciless dual suns, Sela and Naia, of this new Wesnoth.

===??? Post-Wesnoth===

* The Quenoth elves adapt to life in barren world of the Great Southern Desert. Over time they lost their affinity for the woodlands of their ancestry and embrace life in the sandy wastelands.
* Under the leadership of Tanuil, the Quenoth elves build and sustain a fortified village around a rare oasis. The village thrives amidst the hostilities of the desert.
* One night, a meteor storm rains from the sky and destroys the village of the Quenoth elves. '''Under the Burning Suns''' begins. The next day, Tanuil, like many others, is missing and presumed dead. Kalehssar (Kaleh), nephew of Tanuil, takes leadership of the remaining Quenoth elves as the surviving next of kin.
* Kaleh, heeding the voice of his god Eloh in his dreams, gathers the remaining Quenoth elves and leads them north to a new promised land, foregoing rebuilding of their desert village.
* The Quenoth elves battle their way north through Undead, Orcs, Bandits and other evil, venturing underground beneath a large mountain range at the command of Eloh.
* Befriending unexpected allies underground, Kaleh's forces survive to the other side of the mountain.
* Keratur, son of Tanuil and survivor of the cataclysm, insane with fright attacks Kaleh. Kaleh defeats Keratur.
* Kaleh defies commands given him by a vision of Eloh.
* The Quenoth reach the ocean. Aided by Merfolk, they escape the mainland and head for a newly discovered island, a place where the Quenoth may settle in peace.
* On the island, the Quenoth confront Yechnagoth, the Eater of Souls and impersonator of Eloh. Yechnagoth and army are destroyed by the Quenoth.
* Kaleh and the elves settle on their newfound, and newly named, Quenoth Isle. '''Under the Burning Suns''' ends.

== History Credits ==

* Timelined by Kamahawk and Turin. Revised to incorporate material from later version of Legend of Wesmere and reconcile different versions of the history of the Scepter of Fire by Eric S. Raymond.

* History derived from:
** Eastern Invasion
** Heir to the Throne
** Legend of Wesmere
** Liberty
** Northern Rebirth
** The Hammer of Thursagan
** The Rise of Wesnoth
** Under the Burning Suns
** Dead Water
** Delfador's Memoirs

* Setting details derived from:
** Invasion from the Unknown

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]

[[Category:World of Wesnoth]]
[[Category:History]]

Timeline of Wesnoth

2013-03-12T19:40:15Z

Jamiescott: /* After the Fall */

This is a chronological history of the country of Wesnoth and surrounding regions, gleaned from written accounts and verbal histories passed down through the generations. Portions of entries surrounded by parentheses and containing a question mark are assumed or unconfirmed information. The history is sorted by era, and within the era by date, using the Foundation of Wesnoth as a base. BW=Before Wesnoth, YW=Years Wesnoth. They function the same way as BC and AD do in our timekeeping system. Each of the eras is summarized before the timeline for that era begins. This history of the Great Continent is a subject of active scholarship.

The world that Wesnoth resides in is called Irdya. Before the Fall and the (unchronicled) technological age, this name is only rarely used.

'''Spoiler warning!'''
This page contains plot spoilers to several campaigns.

__NOTOC__
[[#Prehistory - 20 YW: The Founding of Wesnoth|The Founding of Wesnoth]]

[[#20-130 YW: The Taming of the Wild|The Taming of the Wild]]

[[#200-350 YW: The Golden Age of Wesnoth|The Golden Age of Wesnoth]]

[[#350-417 YW: The First Dark Age of Wesnoth|The First Dark Age of Wesnoth]]

[[#417-530 YW: The Turmoil of Asheviere|The Turmoil of Asheviere]]

[[#530-630 YW: The Age of Fear|The Age of Fear]]

[[#628-673 YW: The Silver Age of Wesnoth|The Silver Age of Wesnoth]]

[[#761-816 YW: The Legacy of Black-Eye Karun|The Legacy of Black-Eye Karun]]

[[#After the Fall|After the Fall]]

== Prehistory - 20 YW: The Founding of Wesnoth ==
During the age of the Founding of Wesnoth, there were two important geographic locations, these being the Green Isle and the Great Continent. Haldric is the main historical figure at this time. This age ends with the founding of Wesnoth as a country in the Great Continent, and with Orcs attacking both elves and men from the sea.

=== Prehistory ===
* Elves and Dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle] from a continent further to the west.

=== 200 BW ===
* The Lich-Lords arrive on the Green Isle after losing a war in the distant West.
* After a long war Haldric's people come to dominate the Green Isle.
* The 'Wesfolk' and their Lich-Lords are pushed onto marginal lands.

=== 12 BW ===
* The Crown Prince of Southbay discovers the Great Continent.

=== 11-7 BW ===
* The Crown Prince makes several voyages between the Green Isle and the Great Continent.

=== 6 BW ===
* Following these voyages to the Great Continent, the elder Crown Prince falls ill and dies.
* His younger brother is implicated in a plot to kill him.
* As a distraction the younger Prince starts a war with the Wesfolk and their Lich-Lords.
* The Lich-Lords sense they will be destroyed and open gates to the homeland of the Orcs in the West.

=== 5-2 BW ===
* The Green Isle is overrun with Orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the Orcs.
* [http://wiki.wesnoth.org/CharactersStorys#Prince_HaldricPrince Haldric] leads the evacuation of the survivors to the Great Continent. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth '''The Rise of Wesnoth'''] begins.

=== 1 BW ===
* Human settlers, led by Prince Haldric, arrive at the western coast of the Great Continent (the landfall occurs in the future Bay of Pearls) in large numbers.
* Humans arrive in the middle of a simmering dispute between the Elves and Dwarves.
* The Elves and Dwarves are distrustful of humans, and there is a small skirmish.
* Messengers from Wesmere Forest come and ask Haldric to come before the Ka'lian.
* Prince Haldric asks the Four Elvish Lords ([http://wiki.wesnoth.org/CharactersStorys#Lady_Dionli Dionli], [http://wiki.wesnoth.org/CharactersStorys#Lord_Logalmier Logalmier], Aryad, and El'Isomithir) for help and land.
* They set before him four quests to prove his worth, which he completes.

=== 1 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric] is granted the plains north and south of the Great River.
* Haldric agrees to a Pact of Mutual Defence with the Elves, but the Ka'lian decides it will betray him and allow humans and orcs to exhaust each other in war if the opportunity presents. Haldric, learning of this, considers the Pact a dead letter.
* The Ruby of Fire is temporarily hidden, and the [http://wiki.wesnoth.org/CharactersStorys#Lich-Lord_Jevyan lich-lord Jevyan] is deceived into believing it is held by the Elves.
* Haldric founds the country of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] in the central plain south of the great River.
* Reign of Haldric I (formerly prince Haldric) begins. [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth '''The Rise of Wesnoth'''] ends.

=== 2 YW ===
* Orcs, following the ships fleeing from the Green Isle, begin to arrive on the Great Continent.
* These Orcs are defeated by Haldric's forces.
* Some of the Orcish survivors flee back to the Green Isle, others move to attack the Elves.
* King Haldric helps the Elves fight the surviving Orcs.

=== 8 YW ===
* A second wave of Orcs arrive from the Green Isle; these Orcs begin claiming large portions of the northern Great Continent for themselves.
* [http://wiki.wesnoth.org/CharactersStorys#Erlornas Erlornas] of Wesmere is involved in the first direct elvish clash with orcs ([http://wiki.wesnoth.org/Mainline_Campaigns#An_Orcish_Incursion '''An Orcish Incursion'''] takes place in 8-9YW).
* Haldric I publicly repudiates the Pact he spoke with the Elves, refusing to give aid.

=== 9-11 YW ===
* Many Elves are killed in battle by the Orcs.
* Elvish emissaries are turned away from Wesnoth.

=== 12 YW ===
* Orcs fail to take the Wesmere Forest and instead march down the coast, devastating human settlements there.
* Elves refuse to aid the Humans in confronting the Orcs.
* Human refugees from the coastal settlements relocate in what will become known as the Great Central Plain. Dan'Tonk, which will become Wesnoth's largest city, is founded.

=== 20 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric I] dies.
* [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] ascends to the throne.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] escape an orcish invasion of their home in Lintanir Forest. [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere'''] begins.
* Humans and elves decisively defeat the orcs at Tath, thus halting the orcish advance.
* A new treaty between humans and elves is signed and King Haldric II allows emissaries of the Elves to return to Wesnoth.
* Elves inform [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] of the danger posed by the unshielded Ruby of Fire.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar], later to become successive High Lords of the Elves, are able to sneak into an orcish camp by stealth and assassinate the Great Chief Brurbar. A long orcish civil war for succession follows. The orcs are unable to undertake action against any other race during this period and Wesnoth enjoys a long period during which it can expand with little opposition.

== 20-130 YW: The Taming of the Wild ==
This era is that in which the kingdom of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] expanded and defined its borders, and settled the area which it had claimed for its own. The Taming of the Wild refers to the settling of the unsettled lands, as well as to the colonization of the Northlands. The end of this era is marked by friction between the city-state of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] and the country of Wesnoth, which will continue for the next several hundred years.

=== 21 YW ===
* Founding of the Great Academy on Alduin.

* [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz] is relieved of command by the Ka'lian. He retires to Lintanir Forest with [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil]. A faction of xenophobic elves begins to gether around [http://wiki.wesnoth.org/CharactersStorys#Landar Landar].

=== 25-40 YW ===
* In 25 YW [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a Dwarven tribe to build the Scepter of Fire with the Ruby of Fire as its centerpiece; Elves associated with [http://wiki.wesnoth.org/CharactersStorys#Landar Landar's] faction attack during the transfer. [http://wiki.wesnoth.org/Mainline_Campaigns#Sceptre_of_Fire '''Scepter of Fire'''] begins.
* Action of '''The Scepter of Fire''' takes place. Haldric II is informed that the Scepter was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [http://wiki.wesnoth.org/CharactersStorys#Thursagan Thursagan], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.

=== 26-50 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] declares himself High Lord of the Elves, leading to civil war.

=== 51 YW ===
* Wesnothian New Writing (the script later called "steel-hand", to distinguish it from the more complex "brush-hand" cursive brought from the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle]) is promulgated by royal decree. From this date all royal documents and public inscriptions are in New Writing. It spreads rapidly via the mercantile class. The older brush-hand writing continues to be used for magical purposes, scholarship, and in certain elevated literary forms.

=== 50-93 YW ===
* Elvish civil war (and [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere''']) ends. [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] declared High Lord, begins reorganizing and militarizing Elvish society to fight the orcs. In late 93 YW he cedes control to a reconstituted Ka'lian and retires again to the Forest of Lintanir.

=== 121 YW ===
* Orcish civil war sputters to a halt. Raids on elves and humans resume. Period of uncontested human expansion ends, but the [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnothian] Army is more than equal to any of its opponents in battle.

=== 122 YW ===
* City of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] is sacked by orcs.
* Meneldur, a sailor of Elensefar, sets out on a quest to regain the city. UMC '''Saving Elensefar''' begins.

=== 123 YW ===
* Elensefar is retaken by Meneldur along with Undead from the Green Isle.
* Elensefar becomes an independent city-state for the first time. UMC '''Saving Elensefar''' ends.

=== 161-164 YW ===
* The newly crowned king sought to make safe once and for all the wildlands that separated the human cities surrounding Weldyn and the coastal regions of Elensefar.
* The grand army of Wesnoth, personally led by the High Council of Archmagi, destroyed all enemies residing within Wesnoth.
* The city-state of Elensefar is formally united to the kingdom. Settlements from it spread north of the river into the new frontier province of Annuvin, carefully avoiding the margins of Wesmere Forest.

=== 164-176 YW ===
* During this twelve year span, the western fortress of Halstead was erected in the very heart of the western wilderlands.

=== 199 YW ===
* Emboldened by the far-reaching arm of Halstead's protection, settlement in the west explodes
* The settlements of Aldril and Carcyn grow to become major cities, the first as an important port due to its position on the Bay of Pearls, and the second as a stop on the road to Elensefar and military outpost along the Great River
* Settlers from Carcyn cross the Great River to establish the first settlements north of it and east of Wesmere.

== 200-350 YW: The Golden Age of Wesnoth ==
The Golden Age of Wesnoth was the time of the great kings, and of peace and prosperity within the kingdom. The Orcs had suffered a grave defeat at the hands of Wesnoth and Elensefar seventy-five years earlier, so they did not pose much of a threat, and whenever they did attack they were quickly defeated. This allowed the army to lessen in size, and the kings of this age to undertake the great public works they are renowned for. The era ends when the king of Wesnoth dies without an heir, and a new dynasty begins.

=== 251 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil], wife of [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz], dies.

=== 350 YW ===
* Disintegration of the Kingdom follows the death of Haldric IV.
* [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] remains a province of Wesnoth but exerts increasing independence due to isolation.
* Treaty between lord of Elensefar and king of Wesnoth signed.

== 350-417 YW: The First Dark Age of Wesnoth ==
The first Dark Age was a time of strife and invasion. When Haldric IV died, he left Wesnoth without a king, and the next 70 years were marked by short-lived dynasties, attacks by ever more aggressive orcs, and the further separation of Wesnoth and Elensefar. The Dark Age ended when Garard I took the throne, and began a new dynasty that would last for several hundred years.

=== 360 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] born in Parthyn.

=== 363 YW ===
* Last of [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz's] children dies. Kalenz, condemned to outlive his offspring by the potion of Crelanu, leaves the Forest of Lintanir and begins wandering the Great Continent.

* Village of Maghre terrorized by a minor necromancer. Action of [http://wiki.wesnoth.org/Mainline_Campaigns#A_Tale_Of_Two_Brothers '''A Tale of Two Brothers'''] takes place.

=== 389 YW ===
* Garard, a future king of Wesnoth, is born.
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] returns to Parthyn from the Academy at Alduin. [http://wiki.wesnoth.org/Mainline_Campaigns#Descent_into_Darkness '''Descent Into Darkness'''] begins.

== 417-530 YW: The Turmoil of Asheviere ==
King Garard's dynasty was long-lived and productive, but it was also punctuated by significant turmoil: the end of the first king's reign was marred by orcish and undead raids, and the second was murdered by his own wife and son. It was not until 517 YW that the usurpation of the throne by Queen Mother Asheviere was ended.

=== 417 YW ===
* Ending years of strife and division, Garard I seizes the throne and becomes king of Wesnoth, beginning the [[Garardine Dynasty]].

=== 440 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Garard_II Crown Prince Garard II] is born.

=== 442 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador], later called "the Great", is born.

=== 450 YW ===
* Prince Arand is born.

=== 468 YW ===
* Zorlan becomes Great Chief of the northern orcs
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador] graduates from the Great Academy. [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs '''Delfador's Memoirs'''] begins.

=== 470 YW ===
* Garard I dies; [http://wiki.wesnoth.org/CharactersStorys#Garard_II Garard II] ascends to the throne of Wesnoth
* Orcs under Great Chief Zorlan and undead raised by the necromancer [http://wiki.wesnoth.org/CharactersStorys#Iliah-Malal Iliah-Malal] raid Wesnoth's borders. All but the first and the last three scenarios of [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs'''Delfador's Memoirs''' ] take place in this year.
* Control of the Estmarks is effectively lost during this war, not to be regained for decades. Outposts are built on the near side of the Weldyn to repel orc raids. The long watch of the River Guard begins.

=== 478 YW ===
* Garard II marries Asheviere.
* Garard issues the Edict of the Scepter, providing that the crown shall settle after his death on whichever member of the royal family successfully retrieves it from the Caverns of Flame.

=== 480 YW ===
* Crown Prince Eldred is born.

=== 483 YW ===
* Erain and Ethyn, identical twins and brothers of Eldred, are born.

=== 498 YW ===
* Princess Li'sar is born.

=== 500 YW ===
* Prince Konrad is born, the youngest of several sons of Prince Arand.
* Wesnoth and the orcs of the north go to war.

=== 501 YW ===

===== Betrayal on the battlefield =====
* Garard leads his army to orc encampment at Galcadar by the Ford of Abez.
* Garard's forces split into two groups, one led by himself and the other by his son Eldred.
* Eldred betrays his father and attacks him with the troops under his control.
* Eldred slays King Garard and his uncle Prince Arand on the battlefield of Abez.

===== Reprisal =====
* Delfador escapes the battle and heads to Weldyn.
* Eldred gives tribute to the Orcish king, who stops his attacks.
* Delfador gathers a force of Loyalists to avenge Garard's Death.
* Eldred's forces confront Delfador's Loyalists at Weldyn.
* The Loyalists are defeated, but Eldred is slain by Delfador in the fight.

===== Asheviere seizes power =====
* Asheviere orders the slaughter of Garard's nephews and declares herself Queen of Wesnoth.
* Hearing of the news Delfador infiltrates the palace.
* Delfador finds the youngest prince Konrad as he is slain.
* Delfador flees, taking Konrad's body for burial to the land of the Elves.
* While traveling through Wesnoth, Elf Lady Parandra finds an orphaned human child.
* Parandra and Delfador agree to give the orphan the identity of Prince Konrad.
* Delfador and Konrad flee to live in refuge with the Wood Elves of the great southwestern forest.

===== The country resists Asheviere =====
* Elensefar refuses to submit to Asheviere and declares itself an independent city-state.
* After several defeats, Wesnoth's army retreats from the remote areas of the kingdom. The western Wesnothian border recedes, is fixed, and remains heavily defended.
* As a result of the loyalist withdrawal, several small human communities on the west coast of the Great Continent live in relative independence while elves flourish in the great forest to the southwest of Wesnoth.
* A band of Wesnoth citizens organizes resistance to Asheviere's siezure of power. They are eventually forced to abandon their home and settle in the Three Sisters ('''Liberty''').

=== 502-517 YW ===
* Delfador raises Konrad under the protection of the Elves.

=== 517 YW ===
* Asheviere hires Orcish forces to hunt down her nephew-in-law Konrad.
* Orcish forces converge on Delfador's refuge.
* Konrad flees his home with the elves and embark upon a quest to regain the throne of Wesnoth. '''Heir To The Throne''' begins.

=== 518 YW ===
* Konrad crosses the Great River into the Northlands on a search for the Sceptre of Fire.
* They enter the Caves of Knalga, allied with Princess Li'sar, and find it.
* They return to Wesnoth and claim the throne. '''Heir to the Throne''' ends.

=== 522 YW ===
* Birth of Princess Ana'sar.

=== 530 YW ===
* Wesnothian colonists begin reclaiming the Estmarks.

=== 544 YW ===
* With both sides of the lower Weldyn River again civilized territory, the River Guard posts south of Soradoc are abandoned. Wesnothian military activity shifts eastward into the Estmarks.

== 530-630 YW: The Age of Fear ==
The Age of Fear takes its names from the events of the end of the era. On the surface, the first 90 years were very uneventful. However, during this time unexplainable magical events took place, especially in the eastern lands. Previously tamed lands were slowly claimed by wilderness as fear and paranoia gradually overshadowed the spirit of pioneering and adventure displayed earlier in Wesnoth's history. In the last 10 years of the age, Wesnoth bore the brunt of the most powerful Undead attack ever and was nearly destroyed. By the end of the era, most of Wesnoth had been made barren, most of the great buildings inside and outside of Weldyn were razed, and the population of Wesnoth was half of what it had been.

It was in this era that certain areas of the chaotic Northlands were for the first time put into any kind of law and order. A small group of humans and dwarves, accepting anyone of any race who wished to join, formed themselves into the "Northern Alliance”, with the vision of making the Northlands safe to live in. Over time, this alliance grew slowly but steadily in power. By the end of the era, the alliance had succeeded in making a few small areas, including Knalga and the surrounding regions, stable and prosperous. Consequently, many people evacuated from the wasteland that most of Wesnoth had become and moved north - depleting the population of Wesnoth still further.

=== 533 YW ===
* Delfador succumbs to old age and dies, his body is entombed alongside his staff in Eregonor.
* The next great sage of Wesnoth, [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn], is born.

=== 534 YW ===

* The small community of Dwarven Doors, in the Northlands just outside Knalga, rebels against the Orcish overlords. '''Northern Rebirth''' begins.
* The residents, led by Tallin, head underground and find dwarves, whom they ally with.
* Their combined forces destroy a lich who is attempting to claim Knalga as his own.
* Abhai finds the [http://wiki.wesnoth.org/CampaignDialogue:NR#Abhai_Finds_Rod_of_Justice Rod of Justice]

=== 535 YW ===

* The warlord-aspirant Rakshas attacks Tallin and his forces, but does not penetrate the dwarves' defences.
* To help defeat the orcs, Tallin secures the help of two Liches, and rescues an elvish princess to secure the help of the elves.
* Assisted by his new allies, Tallin smashes the forces of Rakshas.
* According to some historians, Tallin and the elvish princess are married; others say they parted in bad blood.
* To preserve the new-found peace in the Northlands, Tallin and his allies form the Northern Alliance. '''Northern Rebirth''' ends.

=== 550 YW ===

* Lord Hamel of Knalga sends an expedition to Kal Kartha to determine the fate of the Hammer of Thursagan ('''The Hammer of Thursagan''' takes place in late 550 YW to early 551 YW.).
* Dwarves at Knalga and elsewhere begin to reclaim the lost art of runesmithing.
* Wesnothian colonization expands southward past Fort Tahn.

=== 563 YW ===
* Konrad and Li'sar die after an extraordinarily long reign.
* Princess Ana'sar becomes queen.
* The seer Galdren becomes prominent at the court of Weldyn.

=== 585 YW ===
* Queen Ana'sar retires.
* Haldric VII becomes king of Wesnoth.

=== 589 YW ===
* Dacyn the White Mage and Ravanal, an eastern wizard, compete to be the king's advisor.
* The seer Galdren dies after advising Haldric VII to choose Dacyn.
* The king does as Galdren advises.

=== 593 YW ===
* Ravanal reveals that he has turned to evil, and flees from Weldyn.
* Konrad II is born.
* Certain southern frontier regions are formally annexed to the Kingdom of Wesnoth as the Province of Kerlath.

=== 598 YW ===
* South Guard organized as a semi-detached formation of the Royal Army, to protect the inhabitants of the frontier province of Kerlath.

=== 605 YW ===
Gweddry born ???

=== 607 YW ===
* South Guard ceases reporting. Haldric VII sends Deoran, son of Haldiel, to investigate. '''The South Guard''' takes place in 607-608 YW.

=== 612 YW ===
* Haldric VII dies. Konrad II is crowned King of Wesnoth.
* Dacyn continues his duties as advisor with Konrad II.

=== 625 YW ===
* Mysterious disappearances of livestock and peasants cause partial evacuation of the the '''Estmark Hills'''. Lords of the Horse Plains report increased banditry from there.
* Konrad II sends [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec] and [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] to man the old River Guard strongpoints. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion'''] begins.

=== 626 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal] attacks the middle outpost where [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] and [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] are stationed.
* Dacyn and Gweddry travel to the northern outpost, and, with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec], retreat into the northlands.
* In the Far North, the wife of Kai Laudiss slain in a large raid by the orcs of Tirigaz on Jotha
* Kai Laudiss slain by poisoned orcish dart during failed attack on the Port of Tirigaz orcs. His son, [http://wiki.wesnoth.org/CharactersStorys#Kai_Krellis Krellis] suceeds him as Kai and relies on the wisdom of [http://wiki.wesnoth.org/CharactersStorys#Cylanna Cylanna], a priestess.
* The merfolk city of Jotha is overrun by undead (Mal Kevek and others). The action of [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water '''Dead Water'''] takes place.

=== 627 YW ===
* Wesnoth's last defences are broken and the undead march on Wesnoth
* In the northlands, the orcs drive [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry's] army back across the river.
* Weldyn is besieged.
* Gweddry breaks through undead lines to reach Weldyn and a council is held.
* Gweddry's army is fortunate and kills [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal]. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion''' ] ends. [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_water '''Dead Water'''] ends (about this time).
* Wesnoth is saved, but large portions have been laid waste by the undead.
* After destroying [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal's] henchmen the mermen relaxed and began rebuilding in earnest, and soon Jotha was restored.

== 628-673 YW: The Silver Age of Wesnoth ==

The Silver Age, or restoration of the Wesnothian kingdom, essentially coincides with the rest of the long and successful reign of [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II]. During this period Wesnoth largely recovered from the damage that Mal-Ravanal's undead attack had done. It would, however, never quite regain the majesty it had at the height of its power.

The Northlands, aided by a second wave of colonization north from Wesnoth, become more civilised and stable. Although nowhere near as prosperous as Wesnoth was during its Golden Age, the Northlands developed towns of significant size and a thriving - if somewhat dangerous - trade network.

Four major powers soon came to dominate much of the Northlands. First there were the dwarves, who controlled most of the mountains and a vast array of underground tunnels and caverns. To the east, shrouded in mystery, lay the Elvish forests which continued to be inaccessible to anyone not of elvish blood. The remaining landscape was dominated either by orcish tribes, or independent human earldoms. As competition for the land grew fierce, wars smoldered between human and orcish forces.

=== 628-635 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 761-816 YW: The Legacy of Black-Eye Karun ==

After decades of struggle, Black-Eye Karun becomes the first warlord since the assassination of Great Chief Brurbar in 20 YW to unite all the different squabbling orcish tribes under his banner. Among his many accomplishments as a Sovereign, his most famous is the creation of the Great Council.

Karun was a far-sighted individual and he knew that after his death the orcish tribes would once again turn to fighting among themselves, with little he could do to prevent that and consequent peril from the Wesnothians and elves.

Consequently, Karun selected from among all the different tribes six of the most sober and wisest orcs and thus created the Great Council. It was the Great Council's job to stay aloof from any tribal or territorial squabbling amongst the orcs, but yet always remain there to give advice to whomever came to seek it. In order to preserve the orcish race in the event of an emergency, he invested in them the power to call up The Great Horde. It was established that every orc, no matter what tribe he came from, must obey the summons of The Great Horde and follow wholeheartedly the leader that the Great Council put at the head of The Great Horde.

===812 YW===
Rahul I becomes Lord Protector of the Northern Alliance

===816 YW===
* Rahul I (Lord Protector of the Northern Alliance) and Black Eye Karun sign a peace treaty ending a 15 year war between the humans and the orcs. Soon after this Karun, is ambushed and killed in mysterious circumstances.

===829===
Howgarth III succeeds Rahul I as Lord Protector of the Northern Alliance

===842 YW===
* Famine in the Northlands. Famine led humans to colonize some orcish lands and push orcs into desolated hill country. The few orcish tribes who had remained part of the Alliance, feeling the pressure, either left Alliance territory or revolted and were destroyed.
* Retaliating, the orcs systematically slaughtered human colonies and villages on their lands. Then, Earl Lanbec'h — the most powerful human warlord of the North — determined to abolish the orcish menace raised an army and conferred leadership of it to his son-in-law Baron Alber.
* In response, the Great Council set up by the Black Eye Karun calls upon The Great Horde and bestows leadership of it upon [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]; [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] begins.

===843 YW===
* Half of the Great Council is treacherously slain by the allied human forces and orcish unity disintegrates. Faced with the extermination of all the orcs on the Great Continent, [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] forcibly asserts his control over the orcish territories and defeats the enemy forces. The Northern Alliance arrives on the scene in time for the final battle and helps Kapou’e defeat the forces of the northern earldoms, who had broken the treaty. Kapou’e then assumes the position of Sovereign over the northern tribes, and his rule ushers in an unprecedented era of unity and prosperity for the orcs.
* After 843: Portions of Kapou'e's army act as mercenaries in foreign struggles with other races which keeps them from attacking their nearest neighbors.

===852 YW===
*[http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] repels a large elvish invasion.

===858 YW===

*The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]. [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] ends.

==After the Fall==
At some unknown point in the future, an unspeakable cataclysm scorched the surface of the lands. The Wesnoth magicians try to rise up a 3rd sun in the sky, but they fail and the 'sun' falls down over Weldyn. The capital is no more. The King and his family are dead and there is no heir. The local leaders torn apart Wesnoth. The nights become longer, days hotter. Evil creatures show up. Forests died, hills turned into rocky wastelands and fields became barren deserts. In the apocalypse allies turned against each other and friends fought over what few resources remained. The great nations were destroyed, and huge numbers of people died. Still amidst the chaos somehow small groups of people survived, sheltered in hidden places. In this post-apocalyptic world survival is a daily struggle as a few remaining tribes eke out an existence among the ruins of fallen empires. Heroic bands of elves, nomadic refugee humans, savage hordes of orcs and dark necromancers all forge new lives under the merciless dual suns, Sela and Naia, of this new Wesnoth.

===??? Post-Wesnoth===

* The Quenoth elves adapt to life in barren world of the Great Southern Desert. Over time they lost their affinity for the woodlands of their ancestry and embrace life in the sandy wastelands.
* Under the leadership of Tanuil, the Quenoth elves build and sustain a fortified village around a rare oasis. The village thrives amidst the hostilities of the desert.
* One night, a meteor storm rains from the sky and destroys the village of the Quenoth elves. '''Under the Burning Suns''' begins. The next day, Tanuil, like many others, is missing and presumed dead. Kalehssar (Kaleh), nephew of Tanuil, takes leadership of the remaining Quenoth elves as the surviving next of kin.
* Kaleh, heeding the voice of his god Eloh in his dreams, gathers the remaining Quenoth elves and leads them north to a new promised land, foregoing rebuilding of their desert village.
* The Quenoth elves battle their way north through Undead, Orcs, Bandits and other evil, venturing underground beneath a large mountain range at the command of Eloh.
* Befriending unexpected allies underground, Kaleh's forces survive to the other side of the mountain.
* Keratur, son of Tanuil and survivor of the cataclysm, insane with fright attacks Kaleh. Kaleh defeats Keratur.
* Kaleh defies commands given him by a vision of Eloh.
* The Quenoth reach the ocean. Aided by Merfolk, they escape the mainland and head for a newly discovered island, a place where the Quenoth may settle in peace.
* On the island, the Quenoth confront Yechnagoth, the Eater of Souls and impersonator of Eloh. Yechnagoth and army are destroyed by the Quenoth.
* Kaleh and the elves settle on their newfound, and newly named, Quenoth Isle. '''Under the Burning Suns''' ends.

== History Credits ==

* Timelined by Kamahawk and Turin. Revised to incorporate material from later version of Legend of Wesmere and reconcile different versions of the history of the Scepter of Fire by Eric S. Raymond.

* History derived from:
** Eastern Invasion
** Heir to the Throne
** Legend of Wesmere
** Liberty
** Northern Rebirth
** The Hammer of Thursagan
** The Rise of Wesnoth
** Under the Burning Suns
** Dead Water
** Delfador's Memoirs

* Setting details derived from:
** Invasion from the Unknown

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]

[[Category:World of Wesnoth]]
[[Category:History]]

DirectActionsWML

2013-03-11T12:41:40Z

Jamiescott: /* [endlevel] */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': {{DevFeature1.11}} Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].

=== [unit] ===
Places a unit on the map. For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''to_variable''': spawn directly into a variable instead of on the map.

=== [recall] ===
Recalls a unit. The unit is recalled free of charge, and is placed near the leader.
* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the position to teleport to.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit loose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': {{DevFeature1.11}} (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit.
* '''type''': the types of units that the side can no longer recruit.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': {{DevFeature1.11}} a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': {{DevFeature1.11}} If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': {{DevFeature1.11}} If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': {{DevFeature1.11}} Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|AiWML]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the :inspect command. Can add traits with immediate effect. Cannot remove things. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

note: The syntax allowed is somehow vague. Just try things and possibly correct/add/modify this documentation. (a [http://forums.wesnoth.org/viewtopic.php?f=21&t=31676& forum thread] discusses some related issues).

=== [transform_unit] ===
Transforms every unit matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
{{DevFeature1.11}} Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this to work around a bug when adding ABILITY_TELEPORT via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up). {{DevFeature1.11}} 'level' has been renamed to 'scenario'.
**if 'forever' or not set, effects never wear off.
** {{DevFeature1.11}} if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed)
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
{{DevFeature1.11}}Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).

=== [reset_fog] ===
{{DevFeature1.11}}The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===

Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* {{DevFeature1.11}} Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

This tag does nothing during recruit and recall actions, as the game incorrectly ignores whether or not an event fired during those times. {{DevFeature1.11}} This has been fixed in the latest development release.

The types of actions that can be undone are movement, recruitment, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the "harm_amount" key.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* [[TimeWML]]: the new schedule.
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit loose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain). ([http://forums.wesnoth.org/viewtopic.php?f=21&t=14749&p=405667&hilit=tunnel#p405667 source])

* '''id''' identifier for the tunnel, to allow removing (optional).
* '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)
* '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)
* '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)
* '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).
* '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).
* '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for "all units".

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

SingleUnitWML

2013-03-11T12:38:00Z

Jamiescott: /* How to describe a single unit */

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''parent_type''': {{DevFeature1.11}} overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. note: This value currently (1.9.12) does not work since it apparently wasn't implemented; see also http://gna.org/bugs/?15113
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit=, only working for units with '''canrecruit=yes'''.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''[status] guardian = 'yes''''.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.

* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.

* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.

* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken.

* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
**'''[[StandardUnitFilter]]''' tags and keys

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] requires a non-empty id= attribute.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

SingleUnitWML

2013-03-11T11:27:21Z

Jamiescott: /* How to describe a single unit */

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''parent_type''': {{DevFeature1.11}} overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. note: This value currently (1.9.12) does not work since it apparently wasn't implemented; see also http://gna.org/bugs/?15113
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit=, only working for units with '''canrecruit=yes'''.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''[status] guardian = 'yes''''.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.

* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.

* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.

* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken.

* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
**'''[[StandardUnitFilter]]''' tags and keys

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] is required a non-empty id= attribute.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

SingleUnitWML

2013-03-11T11:24:06Z

Jamiescott: /* How to describe a single unit */

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''parent_type''': {{DevFeature1.11}} overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. note: This value currently (1.9.12) does not work since it apparently wasn't implemented; see also http://gna.org/bugs/?15113
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit=, only working for units with '''canrecruit=yes'''.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''[status] guardian = 'yes''''.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.

* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.

* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.

* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). {{DevFeature1.11}} Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken.

* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
**'''[[StandardUnitFilter]]''' tags and keys

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] is required a non-empty id= attribute.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

Talk:Create

2013-03-09T01:42:51Z

Jamiescott: /* Translator confusion? */ new section

* Jetryl - I added a solicitation for one major thing at the top of the page. Our code is more or less functional, but we desperately need more help in the graphics and sound department if we're going to reach what I hope to reach for a 2.0 release. I'd have added solicitation for music, but last time I checked, Aleksi and Tim didn't want the help. *shrugs*

== Translator confusion? ==

It looks like someone (Marsianen) is working on a translation of this page, which is great! but they (you) accidentally saved the translated version to the original page overwriting the original. I have reverted the page to English. Please be careful when translating pages to keep your work in the proper place.

Create

2013-03-09T01:34:38Z

Jamiescott: Undo revision 48682 by Marsianen (Talk)

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The semi-current list of projects we are working can be found [http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= here]. We'll happily help you out, if you take a swing at them.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

Create

2013-03-09T01:34:01Z

Jamiescott: Undo revision 48681 by Marsianen (Talk)

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The semi-current list of projects we are working can be found [http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= here]. We'll happily help you out, if you take a swing at them.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== Что я могу создать, и как? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Карты]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

Create

2013-03-09T01:29:30Z

Jamiescott: Undo revision 48683 by Marsianen (Talk)

{{Create/Translations}}
{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have a UTF-8 text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The semi-current list of projects we are working can be found [http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= here]. We'll happily help you out, if you take a swing at them.

== Прочитайте это в первую очередь! ==
Прежде чем изменить или добавить что-либо, важно, понять, как the game stores и организует ее данных. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== Что я могу создать, и как? ==



<div class="thumb tright"><div>
[http://img837.imageshack.us/img837/865/screenshot20120205at529.png http://img26.imageshack.us/img26/8613/thumbhav.png]
<div class="thumbcaption">Battle for Wesnoth 1.10 map editor</div></div>
</div>

* [[BuildingMaps|Карты]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]]
* [[BuildingFactions|Multiplayer factions and eras]]

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth
* [[Practical Guide to Modifying AI Behavior|Artificial Intelligence]] - how to create and modify AI behaviour

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns



== What have others done? ==

There is a multitude of multiplayer factions and eras, multiplayer maps and discussion of campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://forums.wesnoth.org/viewforum.php?f=19 Faction and Era Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and Campaign Development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[Timeline of Wesnoth|The timeline of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* ADDON SERVER [http://addons.wesnoth.org web interface] - An alternate way to download user made content

[[Category:Create|*]]

EditingWesnoth

2013-02-16T14:27:01Z

Jamiescott: /* Game and User Directories */

{{EditingWesnoth/Translations}}


== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally should not modify these files, but you can if you want to modify a unit or something.

The user data directory holds your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content (add-ons/maps). In this wiki, "user data" and ''userdata''/ refer to this directory.

The paths to the game data and user data directories vary according to the operating system and packager.

=== Where is my '''game''' data directory? ===

====Windows====

* ''X:\Program Files\Battle for Wesnoth <version>\data'', where X: corresponds to the drive where Windows is installed (normally C:).
* On 64-bit computers, it will be in ''X:\Program Files (x86)\Battle for Wesnoth <version>\data''.
* The path may be different if you originally chose to install the game in a different location. In such case, look for the data folder in the folder where you installed the game.

====Mac OS X====

* SourceForge.net bundle: Control+click on the application icon. Select "Show Package Contents." Select "Contents", then "Resources".
* Custom builds: ''/usr/local/share/wesnoth''

====Linux====

* Custom builds: ''/usr/local/share/wesnoth''
* Debian/Ubuntu packages, or emerge (Gentoo): ''/usr/share/games/wesnoth''
* Red Hat Linux-based distributions in general (openSUSE, Fedora): ''/usr/share/wesnoth''
* Mandriva: ''/usr/share/games/wesnoth''
* Slackware Linux: ''/usr/local/share/wesnoth''

In a terminal, the command <code>wesnoth --path</code> shows the game data directory.

====BSD====

* OpenBSD package: ''/usr/local/share/wesnoth''

The command <code>wesnoth --path</code> also works.

=== Where is my '''user''' data directory? ===

====Windows====

* Windows 2000/XP (1.8 and later): ''My Documents\My Games\Wesnoth1.8''
* Windows Vista/7 (1.8 and later): ''Documents\My Games\Wesnoth1.8''
* General (before 1.8): ''X:\Program Files\Battle for Wesnoth <version>\userdata'', where X: corresponds to the drive where Windows is installed (normally C:).

''Note: If you don't remember where you installed the game, right click on the game's shortcut, open properties, and click on the "Find target" button, then search for the "data" folder.''

''Note: If you chose "Store userdata in the install location" during installation you will find your userdata as mentioned above under "General". This will also apply if you launch wesnoth.exe directly instead of using the start menu shortcut.''

''Note: If your userdata folder is located in the install location (for the reasons mentioned above) and you are not an administrator on this machine Windows Vista/7 will silently redirect any write access to the so called Virtual Store. You can find your userdata folder in e.g. C:\Users\<yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version>''

====Mac OS X====

* SourceForge.net bundle: ''~/Library/Application Support/Wesnoth_1.x/'' (1.8 and later), or ''~/Library/Preferences/Wesnoth'' (older versions). As of OS X 10.7, this location is hidden by default.
* Custom builds: same as Linux - see below for details.

====Linux====
* Wesnoth 1.10: ''~/.local/share/wesnoth/1.10''
* Wesnoth 1.9: ''~/.local/share/wesnoth/1.9''
* Wesnoth 1.8: ''~/.wesnoth1.8''
* Older versions: ''~/.wesnoth''

In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.

====BSD====
* Same place as Linux.

== Game Data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/core/units/ and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

== User Data ==

The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/add-ons - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/add-ons directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/add-ons directory might look like:
* ''userdata''/data/add-ons/MyCampaign/ - your campaign's directory
* ''userdata''/data/add-ons/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/add-ons/MyCampaign/scenarios
** ''userdata''/data/add-ons/MyCampaign/units
** ''userdata''/data/add-ons/MyCampaign/images
** ''userdata''/data/add-ons/MyCampaign/music
** ''userdata''/data/add-ons/MyCampaign/sounds
** ''userdata''/data/add-ons/MyCampaign/utils

== See Also ==

* [[Create]]

[[Category:Create]]

EditingWesnoth

2013-02-16T14:21:02Z

Jamiescott: /* Game and User Directories */

{{EditingWesnoth/Translations}}


== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally should not modify these files, but you can if you want to modify a unit or something.

The user data directory holds your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content (add-ons). In this wiki, "user data" and ''userdata''/ refer to this directory.

The paths to the game data and user data directories vary according to the operating system and packager.

=== Where is my '''game''' data directory? ===

====Windows====

* ''X:\Program Files\Battle for Wesnoth <version>\data'', where X: corresponds to the drive where Windows is installed (normally C:).
* On 64-bit computers, it will be in ''X:\Program Files (x86)\Battle for Wesnoth <version>\data''.
* The path may be different if you originally chose to install the game in a different location. In such case, look for the data folder in the folder where you installed the game.

====Mac OS X====

* SourceForge.net bundle: Control+click on the application icon. Select "Show Package Contents." Select "Contents", then "Resources".
* Custom builds: ''/usr/local/share/wesnoth''

====Linux====

* Custom builds: ''/usr/local/share/wesnoth''
* Debian/Ubuntu packages, or emerge (Gentoo): ''/usr/share/games/wesnoth''
* Red Hat Linux-based distributions in general (openSUSE, Fedora): ''/usr/share/wesnoth''
* Mandriva: ''/usr/share/games/wesnoth''
* Slackware Linux: ''/usr/local/share/wesnoth''

In a terminal, the command <code>wesnoth --path</code> shows the game data directory.

====BSD====

* OpenBSD package: ''/usr/local/share/wesnoth''

The command <code>wesnoth --path</code> also works.

=== Where is my '''user''' data directory? ===

====Windows====

* Windows 2000/XP (1.8 and later): ''My Documents\My Games\Wesnoth1.8''
* Windows Vista/7 (1.8 and later): ''Documents\My Games\Wesnoth1.8''
* General (before 1.8): ''X:\Program Files\Battle for Wesnoth <version>\userdata'', where X: corresponds to the drive where Windows is installed (normally C:).

''Note: If you don't remember where you installed the game, right click on the game's shortcut, open properties, and click on the "Find target" button, then search for the "data" folder.''

''Note: If you chose "Store userdata in the install location" during installation you will find your userdata as mentioned above under "General". This will also apply if you launch wesnoth.exe directly instead of using the start menu shortcut.''

''Note: If your userdata folder is located in the install location (for the reasons mentioned above) and you are not an administrator on this machine Windows Vista/7 will silently redirect any write access to the so called Virtual Store. You can find your userdata folder in e.g. C:\Users\<yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version>''

====Mac OS X====

* SourceForge.net bundle: ''~/Library/Application Support/Wesnoth_1.x/'' (1.8 and later), or ''~/Library/Preferences/Wesnoth'' (older versions). As of OS X 10.7, this location is hidden by default.
* Custom builds: same as Linux - see below for details.

====Linux====
* Wesnoth 1.10: ''~/.local/share/wesnoth/1.10''
* Wesnoth 1.9: ''~/.local/share/wesnoth/1.9''
* Wesnoth 1.8: ''~/.wesnoth1.8''
* Older versions: ''~/.wesnoth''

In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.

====BSD====
* Same place as Linux.

== Game Data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/core/units/ and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

== User Data ==

The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/add-ons - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/add-ons directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/add-ons directory might look like:
* ''userdata''/data/add-ons/MyCampaign/ - your campaign's directory
* ''userdata''/data/add-ons/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/add-ons/MyCampaign/scenarios
** ''userdata''/data/add-ons/MyCampaign/units
** ''userdata''/data/add-ons/MyCampaign/images
** ''userdata''/data/add-ons/MyCampaign/music
** ''userdata''/data/add-ons/MyCampaign/sounds
** ''userdata''/data/add-ons/MyCampaign/utils

== See Also ==

* [[Create]]

[[Category:Create]]