The Battle for Wesnoth Wiki - User contributions [en]

Palette Cleanup

2025-08-24T00:49:36Z

Doofus-01:

This is WIP, should not be linked to yet.

==Purpose==
Unit sprites are supposed to be pixel art, but sometimes this breaks down. Maybe someone accidentally edited an image with an anti-aliasing tool (e.g. cut-paste lasso, paintbrush) or maybe the original contribution just had too many similar colors. Starting in 1.17, an effort was made to enforce a set palette: https://github.com/wesnoth/wesnoth/issues/6417

This page does not address image metadata, that is covered elsewhere.*

==Background==
====Why do sprites need to be pixel art?====
The game works just fine with non-pixel art images*, but there are some reasons for the pixel art sprite convention:
* Simplifies color swapping - having a set palette makes it simpler to map the original colors to new colors. The most obvious example of this is the team coloring magenta/pink conversion to red for player 1.
* Distinction from terrain/scenery - The terrain and scenery images are not pixel art. With the current conventions, the sprites or "game pieces" should have a clear distinction from the background or "game board"
* Stylistic decision - pixel art is an art form, not simply a limitation, even if it may have had its origins in graphics limitations of the 1970s and earlier.

====Enforcing a palette means restricting colors... Don't cramp my artistic expression!====
It might sound restrictive, but no one said the palette needed to be 8-bit. If you need to add a color to the palette, that is fine, just do it deliberately (see below).

==Palette Cleanup (with an Example)==
Consider these two images:
https://forums.wesnoth.org/download/file.php?id=101241&type=.png
https://forums.wesnoth.org/download/file.php?id=101242&type=.png

The one on the left has 72 colors, the one on the right has 41. Notice the difference? If the palette was chosen correctly, the changes should not noticeably alter the image. Even 41 colors is probably more than is really needed. A bash script to produce the output was:
<syntaxhighlight lang=bash>
#!/bin/bash
mkdir output
mkdir reports
for f in *.png
do
magick $f -dither None -remap HumanLoyalist_ColorMap.png -strip output/$f
# comment these out if you don't need to manually check the results
convert output/$f -define histogram:unique-colors=true -format %c -write histogram:info:reports/info-histo_output_$f.txt
convert $f -define histogram:unique-colors=true -format %c -write histogram:info:reports/info-histo_input_$f.txt
done
rm output/*ColorMap.png
echo Finished!
</syntaxhighlight>

The ColorMap image

https://github.com/wesnoth/wesnoth/blob/master/data/core/images/units/human-loyalists/HumanLoyalist_ColorMap.png?raw=true&type=.png

is included in mainline unit image directories, but you could use your own if the image is not intended for mainline contribution. With the ImageMagick bash script shown above, the ColorMap needs three things:
# the colors needed for the palette
# at least one fully transparent pixel
# at least one 60% opacity shadow pixel (''srgba(23,0,53,0.6)'')**

You'll see in the output reports that there are still colors with only 1-3 pixels, so this isn't optimized. But the palette is still fairly small and, most importantly, every color is tracked and the same across the animation frames, so simple color-swapping is now (reliably) possible and broken team coloring is less likely. The restrictions on the alpha channel, where only the shadow can be semitransparent, help to clean up any almost invisible cruft floating around the sprite.

If you do intend to contribute a sprite image to mainline, and the relevant ColorMap image does not have the colors you need, simply add the needed colors as squares to the ColorMap. The image can be as large as it needs to be, so add another column or row if needed (be sure to leave at least one empty square).

----
----

==Notes==
*CI currently enforces attribution and copyright, it doesn't enforce color palettes, that is still a manual process. Neither of these things are required for UMC, however the copyrights of UMC content do still matter if hosted on the add-ons server.

**It looks like there has already been some slight drift since [[Creating_Shadows_Under_Units]] was written, which makes the palette restriction more relevant

Palette Cleanup

2025-08-23T23:55:05Z

Doofus-01: /* Example */

This is WIP, should not be linked to yet.

==Purpose==
Unit sprites are supposed to be pixel art, but sometimes this breaks down. Maybe someone accidentally edited an image with an anti-aliasing tool (e.g. cut-paste lasso, paintbrush) or maybe the original contribution just had too many similar colors. Starting in 1.17, an effort was made to enforce a set palette: https://github.com/wesnoth/wesnoth/issues/6417

==Background==
====Why do sprites need to be pixel art?====
The game works just fine with non-pixel art images, but there are few reasons for the pixel art sprite convention:
* Simplifies color swapping - having a set palette makes it simpler to map the original colors to new colors. The most obvious example of this is the team coloring magenta/pink conversion to red for player 1.
* Distinction from terrain/scenery - The terrain and scenery images are not pixel art. With the current conventions, the sprites or "game pieces" should have a clear distinction from the background or "game board"
* Stylistic decision - pixel art is an art form, not simply a limitation, even if it may have had its origins in graphics limitations.

====Enforcing a palette means restricting colors... Don't cramp my artistic expression!====
It might sound restrictive, but no one said the palette needed to be 8-bit. If you need to add a color to the palette, that is fine, just do it deliberately.

==Palette Cleanup (with an Example)==
Consider these two images:
https://forums.wesnoth.org/download/file.php?id=101241&type=.png
https://forums.wesnoth.org/download/file.php?id=101242&type=.png

The one on the left has 72 colors, the one on the right has 41. Notice the difference? If the palette was chosen correctly, the changes should not noticeably alter the image. Even 41 colors is probably more than is really needed. A bash script to produce the output was:
<syntaxhighlight lang=bash>
#!/bin/bash
mkdir output
mkdir reports
for f in *.png
do
magick $f -dither None -remap HumanLoyalist_ColorMap.png -strip output/$f
# comment these out if you don't need to manually check the results
convert output/$f -define histogram:unique-colors=true -format %c -write histogram:info:reports/info-histo_output_$f.txt
convert $f -define histogram:unique-colors=true -format %c -write histogram:info:reports/info-histo_input_$f.txt
done
rm output/*ColorMap.png
echo Finished!
</syntaxhighlight>

The ColorMap image

https://github.com/wesnoth/wesnoth/blob/master/data/core/images/units/human-loyalists/HumanLoyalist_ColorMap.png?raw=true&type=.png

is included in mainline unit image directories, but you could use your own. With the ImageMagick bash script shown above, the ColorMap needs three things:
# the colors needed for the palette
# at least one fully transparent pixel
# at least one 60% opacity shadow pixel (''srgba(23,0,53,0.6)'')*

You'll see in the output reports that there are still colors with only 1-3 pixels, so this isn't optimized. But the palette is still fairly small and, most importantly, every color is tracked and the same across the animation frames, so simple color-swapping is now (reliably) possible and broken team coloring is less likely. The restrictions on the alpha channel, where only the shadow can be semitransparent, help to clean up any almost invisible cruft floating around the sprite.

Palette Cleanup

2025-08-23T20:59:14Z

Doofus-01: /* Example */

Palette Cleanup

2025-08-23T20:54:44Z

Doofus-01: /* Background - Is this really needed? */

Palette Cleanup

2025-08-23T20:51:33Z

Doofus-01: First Draft

Palette Cleanup

2025-08-23T13:32:09Z

Doofus-01: Created page with "This is WIP ==Purpose== Unit sprites are supposed to be pixel art, but sometimes this breaks down. Maybe someone accidentally edited an image with an anti-aliasing tool (e.g..."

This is WIP

==Purpose==
Unit sprites are supposed to be pixel art, but sometimes this breaks down. Maybe someone accidentally edited an image with an anti-aliasing tool (e.g. cut-paste lasso, paintbrush) or maybe the original contribution just had too many similar colors. Starting in 1.17, an effort was made to enforce a set palette: https://github.com/wesnoth/wesnoth/issues/6417

===Why do sprites need to be pixel art?===
The game works just fine with non-pixel art images, but there are few reasons for the pixel art sprite convention:
* Simplifies color swapping - having a set palette makes it simpler to map the original colors to new colors. The most obvious example of this is the team coloring magenta/pink conversion to red for player 1.
* Distinction from terrain/scenery - The terrain and scenery images are not pixel art. With the current conventions, the sprites or "game pieces" should have a clear distinction from the background or "game board"
* Stylistic decision - pixel art is an art form, not simply a limitation, even if it may have had its origins in graphics limitations.

ImageMetadata

2025-08-23T13:05:05Z

Doofus-01: /* Metadata and Image Editors */

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - were briefly used for PNG because they are most likely to be edited with GIMP. However, this fact was not worth the extra size and complication, so they are no longer used. Please use the EXIF tags for PNG, just like JPG and WEBP.
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP, JPG and PNG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -EXIF:CreateDate="<Y:m:d H:M:S>" -EXIF:Copyright="<copyright>" -EXIF:Artist="<name (account name)>" -EXIF:UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy github continuous integration (CI), image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist. The format is "Real Name (screen/account name)" with each person separated by a semicolon (;) and either real name or screen name may be omitted. More than one "artist" does not imply a collaboration, it may just mean there was a visible edit to the image.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0". The copyright cannot be changed arbitrarily.

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
'''Note:''' Since most of the information below deals with XMP data, it is of limited value. However, the more relevant EXIF data can often be preserved if editing an existing image, so pay attention to save/export options in whatever editor you use. The XMP metadata may still be worth saving because information can be transferred from XMP to EXIF. An example from '''exiftool''' would be the -[+]TAG[+-]<SRCTAG option:

<code>exiftool '-EXIF:Artist<XMP:Creator' my_image.png</code>

====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed EXIF tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99973&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-08-23T12:15:36Z

Doofus-01: /* Authorship and Copyright */

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - were briefly used for PNG because they are most likely to be edited with GIMP. However, this fact was not worth the extra size and complication, so they are no longer used. Please use the EXIF tags for PNG, just like JPG and WEBP.
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP, JPG and PNG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -EXIF:CreateDate="<Y:m:d H:M:S>" -EXIF:Copyright="<copyright>" -EXIF:Artist="<name (account name)>" -EXIF:UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy github continuous integration (CI), image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist. The format is "Real Name (screen/account name)" with each person separated by a semicolon (;) and either real name or screen name may be omitted. More than one "artist" does not imply a collaboration, it may just mean there was a visible edit to the image.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0". The copyright cannot be changed arbitrarily.

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed EXIF tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99973&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-05-26T18:21:07Z

Doofus-01: /* Examples */

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - were briefly used for PNG because they are most likely to be edited with GIMP. However, this fact was not worth the extra size and complication, so they are no longer used. Please use the EXIF tags for PNG, just like JPG and WEBP.
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP, JPG and PNG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate="<Y:m:d H:M:S>" -Copyright="<copyright>" -Artist="<name (account name)>" -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed EXIF tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99973&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-05-26T18:08:22Z

Doofus-01: /* Basic usage of exiftool */

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - were briefly used for PNG because they are most likely to be edited with GIMP. However, this fact was not worth the extra size and complication, so they are no longer used. Please use the EXIF tags for PNG, just like JPG and WEBP.
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP, JPG and PNG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate="<Y:m:d H:M:S>" -Copyright="<copyright>" -Artist="<name (account name)>" -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed XMP tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99456&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-05-26T18:03:20Z

Doofus-01: /* Authorship and Copyright */

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate="<Y:m:d H:M:S>" -Copyright="<copyright>" -Artist="<name (account name)>" -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG, JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed XMP tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99456&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

1.19 Roadmap

2025-04-06T03:04:15Z

Doofus-01: /* 1.19.13 (06/15/2025) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.19 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here (link is to the 1.17 page, might change for 1.19)].

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

This is just an outline currently, with some point releases for the early, middle and late parts of the branch.

== Note on Single-Player Campaign Reworks ==

We have some campaign reworks planned and in-progress.

* In-progress: The South Guard, The Deceiver's Gambit (DM replacement), The Rise of Wesnoth
* In-progress but slower development: Legend of Wesmere (still Hybrid), Heir to the Throne (grand overhaul)
* SotBE (secret)

The first three (TSG, TDG and TRoW) might have higher chances of getting into 1.19.x cycle before any of the others.
The other three might be going into 1.21.x so have been mentioned here just to prepare for an unprecedented development allowances (more assistance in coding, accelerated development speed, etc).

If you have inquiries on the reworks, contact SP rework team leaders (forums/discord):
* Dalas (TSG/TDG/HttT)
* Dwarftough/Mechanical (LoW)
* Gweoddeoran (TRoW)
* LK (SotBE)

== 1.19.0 (05/26/2024) ==
* Move the Dunefolk into Default Era (Pentarctagon) - completed in #8688

== 1.19.1 (06/16/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6826 #6826] Merge hardware accelerated unit submerge effect, if possible (Pentarctagon)
** Completed in [https://github.com/wesnoth/wesnoth/pull/8687 #8687].

== 1.19.2 (07/21/2024) ==
* Finish adding ability/weapon special unit tests (Pentarctagon)
* Release tentative TSG re-revision add-on, building on Yumi's work (Dalas)
** Depending on reception, additional development may be needed, or the rework may be dropped altogether.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.3 (08/18/2024) ==
* Investigate replacing mariadbpp with Boost.MySql (Pentarctagon)

== 1.19.4 (09/15/2024) ==
* Release final (hopefully) TDG add-on. Collect feedback and fix bugs (Dalas)
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.5 (10/20/2024) ==
* [https://github.com/wesnoth/wesnoth/pull/6512 #6512] New type of deprecation warning, when a deprecated attribute is used alongside its replacement (octalot)
* [https://github.com/wesnoth/wesnoth/pull/7082 #7082] Get wmllint running against mainline during CI with no errors (Pentarctagon)
* GUI2 port of the Help Browser (LumiousE/babaissarkar, CelticMinstrel)
** Completed in [https://github.com/wesnoth/wesnoth/pull/3653 #3653]

== 1.19.6 (11/17/2024) ==

== 1.19.7 (12/15/2024) ==
* Unified recruit/recall dialog (LumiousE/babaissarkar) (related issues: [https://github.com/wesnoth/wesnoth/issues/1059 1059], [https://github.com/wesnoth/wesnoth/issues/8829 8829], [https://github.com/wesnoth/wesnoth/issues/5237 5237])
** Completed in [https://github.com/wesnoth/wesnoth/pull/9499 #9499]

== 1.19.8 (01/19/2025) ==

* [https://github.com/wesnoth/wesnoth/issues/8585 #8585], [https://github.com/wesnoth/wesnoth/issues/9035 #9035] Solve all issues with [damage_type] (octalot)
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. This is on the roadmap twice, I'm planning to do it annually. (octalot, but open to volunteers)

== 1.19.9 (02/16/2025) ==
* Release first half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 2 months.

== 1.19.10 (03/16/2025) ==
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)
* Add "pseudo-queues" as a built-in feature for the multiplayer lobby (pentarctagon)

== 1.19.11 (04/20/2025) ==

== 1.19.12 (05/18/2025) ==
* Improve UtBS. (Hejnewar) This includes:
** Removal and replacement of some abilities, mainly hero ones.
** Better accomodation of high level units to the new recall system.
** Difficulty of Nightmare+.
** Changes to some maps and scenarios, mainly in order to make them more fluid.
* Mercenaries SP/MP campaign (still didn't give up) (Hejnewar) This includes:
** New pixelart terrains and backgrounds (particularily tough for someone without pixelart skills).
* Balance (Hejnewar)
* New MP maps and scenarios. (Hejnewar) This includes:
** New short survival.
** Recovery of long lost mapmaking art.
** New PvP and PvPvE maps, including experimental scenarios with events.

== 1.19.13 (06/15/2025) ==
* Add a History section with a timeline and pages for each major faction to the in-game Encyclopedia (Gothyoba)
* Establish clear direction on weather graphics (doofus-01)

== 1.19.14 (07/20/2025) ==

== 1.19.15 (08/17/2025) ==
* Play through any remaining mainline campaigns worth playing through (ie: not LoW, TRoW or SotBE) and add at least a minimum baseline of achievements to them (Pentarctagon)
* Replace TDG's current magic system with an improved and more developer-friendly version (amakriLexa04)

== 1.19.16 (09/21/2025) ==

== 1.19.17 (10/19/2025) ==
* Release second half of HttT revision and gather feedback, fix bugs, etc (Dalas)
** This is a VERY rough release date. Probably +/- 3 months.
** If all goes well, some months from now I'll need to convert this from add-on to mainline so translators can begin work.

== 1.19.18 (11/16/2025) ==

== 1.19.19 (12/21/2025) ==

== 1.19.20 (01/18/2026) ==
* Go through all the added translatable strings, and check that they're used. For example, look for campaign-specific abilities which aren't used in the campaign. (octalot, but open to volunteers)
* Take a serious look at supporting a competitive mode/ELO ranking natively (pentarctagon)

== 1.19.21 (Beta 1) (02/15/2026) ==
'''This marks the beginning of the feature freeze and string freeze for 1.19;''' the only API changes made past this point must be to fix bugs.

== 1.19.22 (Beta 2) (03/15/2026) ==

== 1.19.23 (Beta 3) (04/19/2026) ==

== 1.19.24 (RC1) (05/17/2026) ==
'''This marks the beginning of the API freeze;''' no API changes for for any reason can be made at this point. Additional RC releases will be done as needed.

* Add new screenshots for 1.20

== 1.20.0 (06/21/2026) ==

[[Category:Roadmaps]]

Create Art

2025-03-23T12:21:05Z

Doofus-01: /* See Also */

{| style="float:right; margin-left:1em;"
|__TOC__
|}

Graphic artists working on artwork intended for mainline Wesnoth usually meet on the [http://forums.wesnoth.org/viewforum.php?f=9 Art Contributions forum] or on the [http://forums.wesnoth.org/viewforum.php?f=18 restricted Art Development forum] ("restricted" meaning that only those users with special permissions - such as art contributors and developers - can post there). The former is a great place to post and discuss new and current mainline Wesnoth art and graphics, and the latter to see what the art development team is working on. Artists working on graphics for [[Glossary|UMC]] add-ons meet in the [http://forums.wesnoth.org/viewforum.php?f=23 Art Workshop forum].

Unit and terrain art is stored in the lossless ''Portable Network Graphics'' (PNG) format. Each frame of a unit animation, and each variation of a terrain is stored as a separate .png file in ''data/core/images'' under the [[EditingWesnoth#Where_is_my_game_data_directory.3F|main data directory]] of the game, and generally these files will be 72 x 72 pixels (the size of Wesnoth's basic hexagonal tile) with an alpha channel (a part of the file that indicates how transparent each pixel is). When creating your own images, you can test them without overwriting any game data by putting them in your [[EditingWesnoth#Where_is_my_user_data_directory.3F|user data directory]]. The game also supports JPEG images, although these are better suited for story art.

To edit these graphics, you'll need some program capable of creating PNG's - some of the programs in the following list are free, open-source software, and will do the job nicely: [[Art Programs]]

[[Give Your Hero A Personality|Give Your Hero A Personality]]

== Art Tutorials ==

These are a work-in-progress, and describe both how to make art fit into Wesnoth's style, as well as giving some considerable tips on drawing in general. Especially useful is the [[External Tutorials]] page which lists a large number of art tutorials available on the web.

=== General Art and Computer Graphics ===
Note: articles that mention making art in physical formats in this section are outdated; artists are encouraged to make their art in digital-native formats these days.
* [[Using the Levels Adjustment]] - How to make scanned pencil drawings ''not'' look washed out.
* [[Extending dynamic range]] - The Grooviest (so far) tutorial about extending the dynamic range of images and how this technique can be used to make better scans of pencil drawings.
* [[Scanning with camera]] - How to transfer real-life art to computer using a digital camera instead of a scanner.
* [[Art Supplies]] - What physical items you need to do larger cell-shaded art like that of Jetrel/Jormungadr/et al.
* [[Inking With Pencils|Computer Inking a Sketch]] - Info from Jason Lutes on his portrait workflow.
* [[Scaling Digital Images]] - How to properly resize an image on a computer.
* [[How to Shade]] - An attempt at tackling a very complicated topic.
* [[Designing weapons and armour]] - Advice from zookeeper on designing realistic weapons for your characters.
* [[Portrait Tutorial]] - A guide on how to draw unit/character portraits by Kitty.
* [[Armour Tutorial]] A tutorial on how to shade metallic armour by LordBob.
====Vector Art====
Sgt. Groovy's vector workshop - Tips and tricks for drawing with Inkscape.
:* [[Z-order tricks]] - A few methods for faking overlapping shapes.
:* [[Variable-width strokes]] - How to make the strokes vary in width, like being drawn with a flat-tipped pen — no tablet needed!
:* [[Shaped gradients with Gaussian blur]] - How to make gradients in other shapes than linear or radial.
:* [[Smooth shading in vector]] - The basic vector techniques for smooth shading, employing Gaussian blur and clipping/masking.
:* [[Vector Inking]] - Vector techniques, including mouse-only, for inking your sketches.
:* [[Making portrait art in vector]] - A complete tutorial for making Wesnoth unit portraits in vector graphics.

=== [[Terrain|Terrain Graphics]] ===

The following is information specific to drawing terrain for Wesnoth. Read Frame's "Tiles Tutorial" for a good overview of how terrain graphics work.

* [[Mesilliac's Essay on Terrain Perspective]] - The geometry behind the perspective used for terrain tiles in Wesnoth.
* [[Tiles Tutorial]] - Frame's tutorial describing the process of making terrain tiles in Wesnoth, and how they interact with adjacent tiles.
* [[Turning Square Tiles into Hex]] - Nifty tricks for transforming square (or any rectangle) shaped seamless tiles into hexagon seamless tiles.
* [[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.

These describe the system used to specify how terrains behave in game:
* [[TerrainCodesWML]] - A list of the letters used to represent terrain types.
* [[TerrainGraphicsWML]] - If you really need to get technical, start here.
* [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.

=== Sprite Art ===
The following are different tutorials about sprite work compiled by various Wesnoth sprite artists. These will give you the most specific-to-Wesnoth information about making sprites, and are well worth a read.

* [[Creating Unit Art]] - A list of specifications you will need to match.
* [[Give Your Hero A Personality]] - Tricks for editing existing images, including some clip art.
* [[Team Color Shifting]] - How to create art that uses our new team color system.
* [[TeamColoring]] - How to automatically team-color sprites to see what they look like in various colors.
* [[Creating Shadows Under Units]] - How we create the shadows for the units in-game.
* [[How to Anti-Alias Sprite Art]] - A means of removing the jagged edges on pixel lines, for those that wish to do so.
* [http://forums.wesnoth.org/download/file.php?id=56284 Zerovirus's Spriting Workflow] - Wesnoth artist Zerovirus explains step-by-step his methodology for creating Wesnoth sprites from scratch (.png file).
* [[Creating a scratch built sprite]] - An attempt to show some ways creating a sprite from scratch.
* [[FrankenPacks]] - A quick and dirty way to create sprites for [[Glossary|UMC]].
* [[Choosing your palette]] - Make shadows look interesting.

====Animation====
:* [[Basic Animation Tutorial]] - Or "How to Animate Sprites for Dummies," covering the basic theory, and all of the mistakes to avoid.
:* [[From Base Frame To Full Animation]] - A solid method of moving baseframes forward towards full animation.
:* [[How to create motion blurs]] - A simple explanation on how to create attack animation weapon blurs.
:* [[Making Bow Animations]] - The current standard for how we want bow animations to work.
:* [[Fire Animation]] - A great guide to creating fire FX by rhyging5.

=== External Tutorials ===
The following page contains dozens of links to tutorials covering all manner of artwork, including sprite art. These were not made by Wesnoth artists, but should prove very useful for general instruction.

* [[External Tutorials]]

== See Also ==
* [[Create]]
* [[EditingWesnoth]]
* [[Project]]
* [[ImageMetadata]]

[[Category:Art Tutorials]]

ImageMetadata

2025-03-23T12:16:47Z

Doofus-01: corrections and examples

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool is supposed to read but not write this flag (so ''-all='' argument shouldn't clobber it, but sometimes it does). GIMP will set this flag, but it can get removed by further processing. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate="<Y:m:d H:M:S>" -Copyright="<copyright>" -Artist="<name (account name)>" -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG files:
* '''XMP:Creator''' must exist.

* '''XMP:Rights''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

For JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

===Examples===
A sprite (PNG) with the needed XMP tags is shown below.

https://forums.wesnoth.org/download/file.php?id=99456&type=.png

Examples of WebP showing the Alpha flag issue can be found at this forum post:

https://forums.wesnoth.org/viewtopic.php?p=694451#p694451

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

DeveloperGuide

2025-03-23T03:27:43Z

Doofus-01: /* See also */

This page describes guidelines developers with push access to the Wesnoth repository should follow. Most items apply to prospective contributors as well, in addition to the [[PatchSubmissionGuidelines|patch submission guidelines]].

__TOC__

== General ==

{{NewDevsGoHereSidebox}}

* [[WesnothRepository#Push_access|Set up developer access to the repository]], if applicable.
* Participate in the #development channel on [https://discord.gg/battleforwesnoth Discord] as well as #wesnoth-dev IRC channel on irc.libera.chat to coordinate with other developers. Bots report commits and regression testing status, and other developers may ask you questions or provide feedback.

== Commits ==

* Any given branch should compile without warnings and run after every commit -- we use Github Actions, which will report any build failures on master and maintenance branches (1.12, 1.14, etc.) to the #development Discord channel.
* All unit tests should pass after commit -- the CI will also test this. To run the C++ unit tests on your own machine, compile the "boost_unit_tests" executable and run it. To run the WML unit tests, run <code>run_wml_tests -u</code> in the checkout root.
* Do not disable or ignore unit tests without a very good reason!
* A few small commits are better than a single large commit (which is hard to review), so when possible split it in working parts with info about where you are going
* Always review your changes, both before committing locally and before pushing upstream (see [[WesnothRepository#Reviewing your changes]]).
* Never use the "force" option when pushing to the upstream Wesnoth repositories (see [[WesnothRepository#Force-pushing_policy]]).

=== Changelog and release notes ===

We provide a changelog at the root of the Wesnoth distribution and Git checkouts. It contains all changes, except for those that are only relevant to mainline developers and which are not expected to impact players or creators in any way.

It is your responsibility to update the changelog as you see fit for every commit. To avoid any chance of merge conflicts due to the changelog, it is recommended to add a file to the changelog_entries folder at the root of the repository rather than updating the changelog directly.

=== Commit messages ===

A good commit should not only contain good changes, but also include a helpful description of them for other developers, people tracking regressions, project maintainers, and even yourself in the future. There are many style guides on the Web describing best practices for documenting your Git commits.

Regardless of style, usually the most important info is the '''goal''' of the commit. It's less important to describe what you did (you can just look at the diff for that; though for the summary line it's still useful) and more important '''why''' you did it.

For Wesnoth in particular, the general consensus is that contributors should adhere to the following rules:

* Every commit message should begin with a self-contained summary/subject line no more than 72 characters long. This is the first (and often the only) line someone using browsing tools will see. Like with email subjects, this line should not have a trailing stop.
* If your message needs more than a leading summary line, separate it from the rest with a blank line.
* Subsequent lines should also be no more than 72 characters long. Use blank lines to separate paragraphs and list items.
* When working on a mainline campaign/scenario, start the commit message with its acronym. For example <code>HttT: </code> when working on HttT in general and <code>HttT S03: </code> if the commit only applies to the third scenario of HttT (see below).
* Likewise, if you work on the code of a specific component, you may want to use it as a prefix. That is e.g., <code>gui2: </code> or <code>wesnothd: </code>.
* If you are performing branch merges, Git may include a list of conflicted paths in the commit message template. Edit this out; it ceases to be interesting after the conflicts have been resolved.
* If you need to mention commit SHA1 hashes (e.g. in revert messages), make sure to use hashes from the upstream repository that are unlikely to change due to a future local or remote merge or rebase operation.

There are a few additional points to keep in mind for the wording of the contents:

* Include "bug #1234" somewhere in your commit message if it addresses a bug or feature request from the Wesnoth bug tracker.
* Use the project's [[Glossary#Wesnothian_Acronyms|standard abbreviations]] for campaigns and gameplay concepts, like HttT for <cite>Heir to the Throne</cite>, ZoC for "Zone of Control", etc. If referring to a particular campaign or scenario in your commit subject, you should use this convention: "HttT S01: Made Galdrad less suicidal"

== Dependencies ==
* Any changes to Wesnoth's build and run-time dependencies must be discussed first.
* Update the CMake and SCons recipes accordingly.
* Changes must be mentioned in the changelog, so they can be included in the forum announcement for the next release, and in the emails to packagers.

== Bugs management ==
* Close bugs once a fix is pushed.
* Check regularly if there are new bugs relevant to your code and, if any, assign them to you.

== See also ==
* [[WesnothRepository]]
* [[PatchSubmissionGuidelines]]
* [[SoftwareTesting]]
* [[Project]]
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
* [[ReferenceWML]]
* [[ImageMetadata]]
[[Category:Development]]

Project

2025-03-23T03:23:56Z

Doofus-01: replace forum link with wiki page for image metadata

<div class="tright"> __TOC__ </div>

The Battle for Wesnoth is an [https://opensource.org/faq#osd open source] software project hosted on [https://github.com/wesnoth GitHub], created and maintained by The Battle for Wesnoth Project, an [[Credits|international team of volunteers]] from diverse backgrounds. Conceived in 2003 by David White, Wesnoth has caught the interest of a multitude of fans who have since contributed to different aspects of the game such as engine coding, content creation, art and music development, translation, packaging, testing, and community management.

The Project is governed by the Project Manager and the Project Council as per the [https://www.wesnoth.org/constitution/ Project Constitution]. The current Project Manager [https://forums.wesnoth.org/viewtopic.php?t=55254 elected] by the development team for the Wesnoth 1.19.x development cycle is Pentarctagon. Past Project Managers include Charles Dang (vultraz), Iris Morelle (Irydacea), Nils Kneuper (Ivanovic) and Isaac Clerencia (isaac).

The Wesnoth.org website, primary multiplayer server, and add-ons server facilities are managed by a few members of the project who staff the game's backend infrastructure.

Funding for infrastructure and art and music commissions is provided by Wesnoth, Inc., a US-based company which manages revenue from donations made to Wesnoth through [https://liberapay.com/Wesnoth Liberapay] and [https://wesnoth.itch.io/battle-for-wesnoth itch.io]. While Wesnoth, Inc. financially supports the project, it does not have any involvement in its organization and direction. The current board of directors consists of Elvish_Hunter, Pentarctagon, and Soliton.

== Content Creators ==

Wesnoth's great replay value mainly stems from the great abundance of custom-made content developed by our talented community. It only takes a copy of the game, a text editor, creativity, and patience to create your own campaign, era, or multiplayer scenario!

See [[Create]] for more information on the subject of user-made content development.

== Artists ==

There is plenty of room for improvement in areas such as animations and sound effects. User-made content creators are also always in need of new art, music, and sounds for their own projects!

* [https://forums.wesnoth.org/viewforum.php?f=9 Mainline art contributions forum] ''Attribution & copyright requirements for a contribution are outlined at [[ImageMetadata]]''
* [https://forums.wesnoth.org/viewforum.php?f=18 Mainline art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=23 User-made art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=14 Music contributions forum]

== Developers ==

The project is always eager to welcome new contributors able to help by fixing [https://bugs.wesnoth.org/ bugs], cleaning up and improving on existing code, or implementing new and exciting features!

* [[WesnothRepository]] — cloning and using our Git repository
* [[CodingStandards]] and [[HackingWesnoth]] — information on our C++ style and coding conventions
* [[PatchSubmissionGuidelines]] — instructions for submitting your code contributions
* [[DeveloperGuide]] — additional information on commit messages, unit tests, etc.
* [https://devdocs.wesnoth.org/ Source code documentation] — generated from the game's source code using Doxygen and updated daily.
* [[ReferenceWML]] — information on the Wesnoth Markup Language (WML) and the game's Lua API
* [[DeveloperResources]] — additional development-related links

== Translators ==

In order to better reach its audience, Wesnoth needs people able to translate the game into other languages from across the globe. If you consider yourself able to help, join the translation team for your language -- or if none has been established already, follow the instructions to start your own!

* [[WesnothTranslations]] — includes a list of translation maintainers and useful links for prospective translators
* [http://gettext.wesnoth.org Statistics]

[[Category:Development]]

ImageMetadata

2025-03-23T03:09:39Z

Doofus-01:

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool can read but not write this flag (so ''-all='' argument won't clobber it). GIMP will set this flag, but some optimizing scripts or programs can remove it. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
exiftool -overwrite_original -all= -Date="<Y:m:d H:M:S>" -Rights="<copyright>" -Creator="<name (account name)>" -Description="<comment>" <target file>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate="<Y:m:d H:M:S>" -Copyright="<copyright>" -Artist="<name (account name)>" -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG files:
* '''XMP:Creator''' must exist.

* '''XMP:Rights''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

For JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

(Examples would be nice, but uploads are not allowed.)
====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-03-23T03:07:13Z

Doofus-01: some formatting

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool can read but not write this flag (so ''-all='' argument won't clobber it). GIMP will set this flag, but some optimizing scripts or programs can remove it. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
exiftool -overwrite_original -all= -Date=<Y:m:d H:M:S> -Rights=<copyright> -Creator=<name (account name)> -Description="<comment>" <target file>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate=<Y:m:d H:M:S> -Copyright=<copyright> -Artist=<name (account name)> -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG files:
* '''XMP:Creator''' must exist.

* '''XMP:Rights''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

For JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

(Examples would be nice, but uploads are not allowed.)
====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
''Image->Metadata->Edit Metadata''
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
''Layer->Edit Metadata...''
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-03-23T01:31:31Z

Doofus-01: Add some wiki topography data

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
exiftool -g <file>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool can read but not write this flag (so ''-all='' argument won't clobber it). GIMP will set this flag, but some optimizing scripts or programs can remove it. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
exiftool -overwrite_original -all= -Date=<Y:m:d H:M:S> -Rights=<copyright> -Creator=<name (account name)> -Description="<comment>" <target file>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
exiftool -overwrite_original -all= -CreateDate=<Y:m:d H:M:S> -Copyright=<copyright> -Artist=<name (account name)> -UserComment="<comment>" <target file>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG files:
* '''XMP:Creator''' must exist.

* '''XMP:Rights''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

For JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
Image->Metadata->Edit Metadata
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
Layer->Edit Metadata...
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

== See also ==
* [[Create]]
* [[Maintenance_tools]]

[[Category:Development]]

ImageMetadata

2025-03-23T01:21:21Z

Doofus-01: Cleanup formatting

== Image Metadata ==

Author and copyright data of Wesnoth images are contained in the image metadata. For most of Wesnoth's project history, image authorship and copyrights were tracked in a separate text document. Such a document can still be generated from the metadata, but is not currently (2025) part of the commit process. There is no expectation that an artist correctly format the metadata, but the individual committing the image to the project files is expected to do so.

A lot of different programs can manipulate metadata, and they all seem to have different ways of doing it.
'''Exiftool''' is platform-independent, command-line application that has been the primary toolkit applied to Wesnoth images. More info can be found at https://www.exiftool.org/index.html

The discussion assumes GIMP (or Krita) is the image editor used, but it is probably equally valid for Adobe Photoshop. Other editors probably have some metadata support, this is a wiki.

===Basic usage of exiftool===

To view metadata of an image <file> grouped by tag
<syntaxhighlight> exiftool -g <file> </syntaxhighlight>
'''Note:''' WEBP must contain "Alpha" in RIFF:WebP_Flags or else the transparent background will be lost when EXIF tags are added. Exiftool can read but not write this flag (so ''-all='' argument won't clobber it). GIMP will set this flag, but some optimizing scripts or programs can remove it. Viewing the image metadata with the above command will allow you to check.

To write the needed metadata (Author and Copyright) but remove all the other info injected by image editors (most of which is useful in some context, just not this one), we use ''-all='' to clear the deck. For small PNG files, thumbnail data can double the file size, and this matters because we have ''a lot'' of these little files. We can also use ''-overwrite_original'' to prevent a backup file. Different tag groups have different names for very similar fields, and they often don't match what you see in the image editor dialogs.
* XMP (dc "Dublin Core") tags - Used for PNG because they are most likely to be edited with GIMP (see below).
<syntaxhighlight>exiftool -overwrite_original -all= -Date=<Y:m:d H:M:S> -Rights=<copyright> -Creator=<name (account name)> -Description="<comment>" <target file></syntaxhighlight>

* EXIF - Used for WEBP and JPG, as Exif data seemed more visible in some file managers. We could add both XMP and Exif to all images, but that would make the files larger.
<syntaxhighlight>exiftool -overwrite_original -all= -CreateDate=<Y:m:d H:M:S> -Copyright=<copyright> -Artist=<name (account name)> -UserComment="<comment>" <target file></syntaxhighlight>

===Metadata and CI===

====Authorship and Copyright====

To satisfy CI, image metadata is checked for a small set of entries.

For PNG files:
* '''XMP:Creator''' must exist.

* '''XMP:Rights''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

For JPEG, WEBP:
* '''EXIF:Artist''' must exist.

* '''EXIF:Copyright''' must contain "GNU GPL v2+", "CC BY-SA 4.0", or "CC0"

====Optional tags reported in CI====
(This needs to be fixed, both here and CI.)

===Metadata and Image Editors===
====GIMP (2.10)====
Image->Metadata->Edit Metadata
*PNG - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*WEBP - Can read/write XMP:Creator, XMP:Rights, and XMP:Description under the "Description" tab
*JPEG - Can read IPTC:By-line or EXIF:Artist (IPTC takes precedence), shown under "Description", exports to XMP and IPTC groups

====Krita (5.1)====
Layer->Edit Metadata...
*PNG - Does not always import XMP:Creator or XMP:Rights, but can write to them under "Dublin Core" tab, as well as XMP:Description
*WEBP - Does not seem to import anything, but can write XMP:Creator and XMP:Rights
*JPEG - Can import EXIF:Artist and EXIF:Copyright, shown under "Dublin Core" as Creator & Rights, exported under IPTC:By-line and IPTC:Copyright Notice

ImageMetadata

2025-03-22T23:38:28Z

Doofus-01: Initial draft of image metadata guide

Project

2024-11-04T03:52:20Z

Doofus-01:

<div class="tright"> __TOC__ </div>

The Battle for Wesnoth is an [https://opensource.org/faq#osd open source] software project hosted on [https://github.com/wesnoth GitHub], created and maintained by The Battle for Wesnoth Project, an [[Credits|international team of volunteers]] from diverse backgrounds. Conceived in 2003 by David White, Wesnoth has caught the interest of a multitude of fans who have since contributed to different aspects of the game such as engine coding, content creation, art and music development, translation, packaging, testing, and community management.

The Project is governed by the Project Manager and the Project Council as per the [https://www.wesnoth.org/constitution/ Project Constitution]. The current Project Manager [https://forums.wesnoth.org/viewtopic.php?t=55254 elected] by the development team for the Wesnoth 1.19.x development cycle is Pentarctagon. Past Project Managers include Charles Dang (vultraz), Iris Morelle (Irydacea), Nils Kneuper (Ivanovic) and Isaac Clerencia (isaac).

The Wesnoth.org website, primary multiplayer server, and add-ons server facilities are managed by a few members of the project who staff the game's backend infrastructure.

Funding for infrastructure and art and music commissions is provided by Wesnoth, Inc., a US-based company which manages revenue from donations made to Wesnoth through [https://liberapay.com/Wesnoth Liberapay] and [https://wesnoth.itch.io/battle-for-wesnoth itch.io]. While Wesnoth, Inc. financially supports the project, it does not have any involvement in its organization and direction. The current board of directors consists of Elvish_Hunter, Pentarctagon, and Soliton.

== Content Creators ==

Wesnoth's great replay value mainly stems from the great abundance of custom-made content developed by our talented community. It only takes a copy of the game, a text editor, creativity, and patience to create your own campaign, era, or multiplayer scenario!

See [[Create]] for more information on the subject of user-made content development.

== Artists ==

There is plenty of room for improvement in areas such as animations and sound effects. User-made content creators are also always in need of new art, music, and sounds for their own projects!

* [https://forums.wesnoth.org/viewforum.php?f=9 Mainline art contributions forum] - Attribution & copyright requirements for a contribution are outlined in this [https://forums.wesnoth.org/viewtopic.php?t=58825 forum post.]
* [https://forums.wesnoth.org/viewforum.php?f=18 Mainline art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=23 User-made art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=14 Music contributions forum]

== Developers ==

The project is always eager to welcome new contributors able to help by fixing [https://bugs.wesnoth.org/ bugs], cleaning up and improving on existing code, or implementing new and exciting features!

* [[WesnothRepository]] — cloning and using our Git repository
* [[CodingStandards]] and [[HackingWesnoth]] — information on our C++ style and coding conventions
* [[PatchSubmissionGuidelines]] — instructions for submitting your code contributions
* [[DeveloperGuide]] — additional information on commit messages, unit tests, etc.
* [https://devdocs.wesnoth.org/ Source code documentation] — generated from the game's source code using Doxygen and updated daily.
* [[ReferenceWML]] — information on the Wesnoth Markup Language (WML) and the game's Lua API
* [[DeveloperResources]] — additional development-related links

== Translators ==

In order to better reach its audience, Wesnoth needs people able to translate the game into other languages from across the globe. If you consider yourself able to help, join the translation team for your language -- or if none has been established already, follow the instructions to start your own!

* [[WesnothTranslations]] — includes a list of translation maintainers and useful links for prospective translators
* [http://gettext.wesnoth.org Statistics]

[[Category:Development]]

Project

2024-11-04T02:15:14Z

Doofus-01:

<div class="tright"> __TOC__ </div>

The Battle for Wesnoth is an [https://opensource.org/faq#osd open source] software project hosted on [https://github.com/wesnoth GitHub], created and maintained by The Battle for Wesnoth Project, an [[Credits|international team of volunteers]] from diverse backgrounds. Conceived in 2003 by David White, Wesnoth has caught the interest of a multitude of fans who have since contributed to different aspects of the game such as engine coding, content creation, art and music development, translation, packaging, testing, and community management.

The Project is governed by the Project Manager and the Project Council as per the [https://www.wesnoth.org/constitution/ Project Constitution]. The current Project Manager [https://forums.wesnoth.org/viewtopic.php?t=55254 elected] by the development team for the Wesnoth 1.19.x development cycle is Pentarctagon. Past Project Managers include Charles Dang (vultraz), Iris Morelle (Irydacea), Nils Kneuper (Ivanovic) and Isaac Clerencia (isaac).

The Wesnoth.org website, primary multiplayer server, and add-ons server facilities are managed by a few members of the project who staff the game's backend infrastructure.

Funding for infrastructure and art and music commissions is provided by Wesnoth, Inc., a US-based company which manages revenue from donations made to Wesnoth through [https://liberapay.com/Wesnoth Liberapay] and [https://wesnoth.itch.io/battle-for-wesnoth itch.io]. While Wesnoth, Inc. financially supports the project, it does not have any involvement in its organization and direction. The current board of directors consists of Elvish_Hunter, Pentarctagon, and Soliton.

== Content Creators ==

Wesnoth's great replay value mainly stems from the great abundance of custom-made content developed by our talented community. It only takes a copy of the game, a text editor, creativity, and patience to create your own campaign, era, or multiplayer scenario!

See [[Create]] for more information on the subject of user-made content development.

== Artists ==

Graphic artists and musicians usually meet on the [https://forums.wesnoth.org/ Wesnoth.org forums]. While the main game is generally regarded as feature-complete, there is plenty of room for improvement in areas such as animations and sound effects. User-made content creators are also always in need of new art, music, and sounds for their own projects!

* [https://forums.wesnoth.org/viewforum.php?f=9 Mainline art contributions forum]
* [https://forums.wesnoth.org/viewforum.php?f=18 Mainline art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=23 User-made art development forum]
* [https://forums.wesnoth.org/viewforum.php?f=14 Music contributions forum]

== Developers ==

The project is always eager to welcome new contributors able to help by fixing [https://bugs.wesnoth.org/ bugs], cleaning up and improving on existing code, or implementing new and exciting features!

* [[WesnothRepository]] — cloning and using our Git repository
* [[CodingStandards]] and [[HackingWesnoth]] — information on our C++ style and coding conventions
* [[PatchSubmissionGuidelines]] — instructions for submitting your code contributions
* [[DeveloperGuide]] — additional information on commit messages, unit tests, etc.
* [https://devdocs.wesnoth.org/ Source code documentation] — generated from the game's source code using Doxygen and updated daily.
* [[ReferenceWML]] — information on the Wesnoth Markup Language (WML) and the game's Lua API
* [[DeveloperResources]] — additional development-related links

== Translators ==

In order to better reach its audience, Wesnoth needs people able to translate the game into other languages from across the globe. If you consider yourself able to help, join the translation team for your language -- or if none has been established already, follow the instructions to start your own!

* [[WesnothTranslations]] — includes a list of translation maintainers and useful links for prospective translators
* [http://gettext.wesnoth.org Statistics]

[[Category:Development]]

ReferenceWML

2024-04-01T01:24:31Z

Doofus-01: adding environment variables link to "See also" section

{{WML Tags}}
== The Wesnoth Markup Language ==

The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).

This page is a collection of pointers to different common WML structures.

See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
for a tutorial style overview.

''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''

== How WML works ==

* [[SyntaxWML]] Description of WML syntax
* [[VariablesWML]] How to use WML variables
* [[PreprocessorRef]] the WML preprocessor syntax
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.
* [[AddonsWML]] Content that can be published and downloaded via the add-ons server

== WML toplevel tags ==

The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.

* [[GameConfigWML]] the top level '''[game_config]''' tag
* [[UnitsWML]] the top level '''[units]''' tag
** [[AbilitiesWML]] a list of the different abilities a unit or weapon can have
** [[UnitTypeWML]] how to describe a unit type
** [[AnimationWML]] how to animate units
* [[CoreWML]] the top level '''[core]''' tag
* [[CampaignWML]] the top level '''[campaign]''' tag
** [[CreditsWML]] how to describe the credits (the '''[about]''' tag)
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', and '''[test]'''
** [[EventWML]] how to describe an event (the '''[event]''' tag)
** [[SideWML]] how to describe a side (the '''[side]''' tag)
** [[MapGeneratorWML]] the random map generator
** [[TimeWML]] how to describe a day
** [[IntroWML]] how to describe the intro screen (the '''[story]''' and '''[part]''' tags)
* [[EraWML]] the top level '''[era]''' tag
* [[ModificationWML]] the top level '''[modification]''' and '''[resource]''' tags
* [[TerrainWML]] the top level '''[terrain_type]''' tag
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
* [[ThemeWML]] the top level '''[theme]''' tag
* [[LanguageWML]] the top level '''[language]''' tag
* [[LocaleWML]] the top level '''[locale]''' tag
* [[HelpWML]] the top level '''[help]''' tag
* [[BinaryPathWML]] the top level '''[binary_path]''' tag
* [[FontsWML]] the top level '''[fonts]''' tag
* [[GettextForWesnothDevelopers#The_textdomain_tag|Textdomains]] the '''[textdomain]''' tag

Some other files use the WML format, but with different tags.

* [[AchievementsWML]] the [achievement_group] and [achievement] tags.
* [[SavefileWML]] a description of the format of savegames
** [[ReplayWML]] a description of the format of player actions such as moving a unit
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
* [[PblWML]] a description of the format of server-uploadable campaigns
* [[SchemaWML]] a description of WML files that define the structure of other WML files
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
* [[GUIToolkit]] creating dialogs

== Other WML tags ==

* [[EventWML]] how to describe an event
** [[FilterWML]] the construct to filter on [[StandardUnitFilter|units]], [[StandardLocationFilter|locations]], [[StandardSideFilter|sides]], weapons, vision, and WML data.
** [[ActionWML]] to describe the actions which occur when the event is fired
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
*** [[DirectActionsWML]] actions that directly affect gameplay: for example, creating a unit
**** [[SingleUnitWML]] how to describe a unit (for uses such as placing one on the map with the '''[unit]''' tag)
*** [[InternalActionsWML]] actions that WML uses internally: for example, storing a variable
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example, displaying a message
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)
* [[AiWML]] how to describe parameters for AI (the '''[ai]''' tag)
* [[EffectWML]] the construct to modify a unit (the '''[effect]''' tag)
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
* [[EditorWML]] tags controlling the post-1.4 editor's behavior
* [[MusicListWML]] for playing music (see also [[Available Music]] for a list of what's available)

== Predefined macros ==

Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.

== Other ==

* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted
* [[ConventionsWML]] how to make your WML more readable
* [[Wml_optimisation]] how to make your WML code more efficient
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.
* [[Maintenance tools]] for wmlindent, wmllint, wmlscope
* [[CommandMode]] commands are not strictly speaking part of WML, but they are useful for debugging it, and could be a little hard to find, so linking to them here makes sense.
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
* [[ImagePathFunctions]] (IPFs) are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
* [[Pango formatting]] shows ways to enrich descriptions (pango markup, which can generate basic html tags like <nowiki>, , </nowiki> and others).
* [[Wesnoth_Formula_Language]] (WFL) often used with $() formulas.
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...

== See Also ==

* [[BuildingMaps]] the text-based format for Wesnoth maps
* [[TerrainCodeTableWML]] a list of all terrains, and [[TerrainCodesWML]], on how to use them
* [[MultiHexTutorial]] a description of the multi-hex tiling system
* [[IGNFileFormat]] a description of the ignore file format
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
* [[Environment_variables]] a cheat-sheet for CLI environment variables
* Back to [[Create]]

[[Category: WML Reference]]

Environment variables

2024-04-01T01:18:02Z

Doofus-01: Creating a page for environment variables

== Command Line ==
Running Wesnoth from command line allows you to set options on the fly ("wesnoth -d" for starting in debug mode or "wesnoth --nocache" to disable cache, for example). Try "wesnoth --help" to see all the options.

=== Environment Variables ===

Any program run from command line can be further influenced by [https://en.wikipedia.org/wiki/Environment_variable environment variables]. This section is to document the wesnoth-specific available environment variables.

* '''WESNOTH_NO_LOG_FILE'''
: By default, error/warning/info messages are directed to a log file, and some are displayed in-game. However, if you set '''WESNOTH_NO_LOG_FILE="true"''', running wesnoth from command line allows you to instantly see warnings, errors, and other information that could be useful when debugging Wesnoth or your add-on.

LuaAPI/types/widget

2023-11-23T12:28:58Z

Doofus-01: /* label */

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[treeview]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: All widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: All widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: All widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

== Widget methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' befor calling the method.

[[Category:Lua Reference]]

DirectActionsWML

2023-05-28T23:09:55Z

Doofus-01: /* [terrain] */

{{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. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''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 yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''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''': 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]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [[SingleUnitWML|filter_recall]] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[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.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''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).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [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 hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''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.
* '''location_id''': This key sets a string as a way to mark the hex or hexes for later reference. It is very similar to the leader starting position, and can also be set that way in the map editor.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

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 is that there are too many choices to make; should a unit lose 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]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): 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''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. 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.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes 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''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

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. Any leader on this side will now be able to recruit the new units.
* '''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]] 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 are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_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.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''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]] 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. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader 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. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] 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.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_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''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''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. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''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''': 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]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai]]]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''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''': 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''': 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
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [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 require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [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''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): 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 ({{DevFeature1.13|8}} or if it has a victory animation and animate=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).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[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.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''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.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (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.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] 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]] tags and keys; default for empty side= is all sides, as usual in a 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.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements, and will potentially overwrite existing modifications.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit (saved inside the unit's [variables] tag); uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

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:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]'''
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map 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. Hit points will be changed if necessary to respect the transformed unit's maximum hit points. Regardless of anything else, the unit will be rebuilt. Thus, transforming a unit to its current type is a way to force a rebuild, for example after manually removing a modification.
* [[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. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** 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.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''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 for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[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 tries 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). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[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". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''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_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the object to be removed.

=== [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] ===
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_vision=all).

=== [reset_fog] ===
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.
* 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.

The types of actions that can be undone are movement, 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.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less 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. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[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 yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''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.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [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. If yes, also the corresponding advance and post advance 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. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[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. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''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''': 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''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. 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.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [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_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=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 lose 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.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [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).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

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

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

Progress an achievement by the specified amount, with an optional limit for how far the achievement can be progressed.

* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''amount''': The amount to increment the achievement.
* '''limit''': (optional) Using this attribute will prevent achievements from progressing past this value.

== 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 [https://www.wesnoth.org/macro-reference.html 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]]

StandardLocationFilter

2023-05-28T23:04:09Z

Doofus-01:

{{WML Tags}}
From [[FilterWML]], this is the standard way of filtering on locations.
The term [[StandardLocationFilter]] means that the set of such keys and tags (see below) can appear at that point. Sometimes a [[StandardLocationFilter]] needs to be included in a [filter_location] tag. There are however many tags which accept the [[StandardLocationFilter]] directly as an argument such as [store_locations]. Generally, if the tag [filter_location] is not mentioned to be a possible subtag of the outer tag in question, then don't put it.

== Attributes ==
The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, or neutral). Note: ''chaotic'', ''lawful'', and ''neutral''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [[#Filtering_Terrains|Filtering Terrains]]).
* '''x,y''': the same as in the unit filter; supports any range ([[StandardLocationFilter#Notes_about_Coordinate_Usage|notes]])
* '''location_id''': {{DevFeature1.13|?}} Matches a special location set in the map. This can also be a side number to match that side's starting location. Note: this does not accept a comma separated list, one has to use [or] tags. {{DevFeature1.15|0}} Accepts a comma separated list. This key can be set in the map editor or with the [terrain] tag.
* '''area''': matches locations assigned to the [[DirectActionsWML#.5Btime_area.5D|[time_area]]] with the given id.
* '''include_borders''': {{DevFeature1.13|0}} whether the SLF will include border hexes or not. Will override the default behavior of the tag this appears in.
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).
* '''gives_income''': {{DevFeature1.15|11}} Matches whether or not a hex gives income, based on its terrain_type settings.
* '''[filter_vision]''': this tests whether or not the location is currently visible
** '''visible''': yes or no, default yes. "yes" filters for visible locations, "no" filters for invisible locations.
** '''respect_fog''': yes or no, default yes. "yes" filters for locations that are clear of both fog and shroud, "no" filters for locations that are clear of shroud.
** [[StandardSideFilter]] tags and keys as arguments. If there is '''at least one''' matching side which can see the location then the filter matches, and otherwise it fails to match.
*'''[filter_owner]''': If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([[StandardLocationFilter#Notes_about_Radius_Usage|notes]])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[#Directions|notes]])
* '''formula''': {{DevFeature1.13|5}} a [[Wesnoth Formula Language]] formula. Some terrain-specific variables, for example "light" and "castle", can be used in the filter [[#Wesnoth_Formula_Language|(see list below)]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.
* '''lua_function''': {{DevFeature1.13|5}} the name of a [[LuaWML|Lua]] function in the global environment that takes arguments <code>x, y</code> and returns true if the given location matches the filter. Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.

==Notes about Coordinate Usage==

When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

While some locations should only be one hex (like the starting position of a unit),
others filter over multiple hexes.
The following syntax is used to filter over multiple hexes:

Dashes('''-''') are used to have the location be a range of hexes.
There must be values before and after the dash;
everything in between these numbers (inclusively) is part of the range.

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.
E.g. in order to specify multiple locations 1,4 and 2,5, use:

<syntaxhighlight lang='wml'>
[tag]
x=1,2
y=4,5
[/tag]
</syntaxhighlight>

You should have the same number of commas in each list, and both '''x''' and '''y''' are always lists. For example, this does not mean the locations (1,4) and (2,4):
<syntaxhighlight lang='wml'>
[tag]
x=1,2
y=4 # bad example, implementation-defined behavior
[/tag]
</syntaxhighlight>

A pair can have a single value for one coordinate and a range for the other. This matches (1,4) and the entire column from (2,1) downwards:
<syntaxhighlight lang='wml'>
[tag]
x=1, 2
y=4,1-999
[/tag]
</syntaxhighlight>

Providing only '''x''' or only '''y''' is valid. This matches the entire columns from (1,1) and (2,1) downwards:
<syntaxhighlight lang='wml'>
[tag]
x=1,2
[/tag]
</syntaxhighlight>

Note: although the ordering of locations in a list generally does not matter,
the action '''[move_unit_fake]''' takes in a list of hexes,
and moves an image onto each of those hexes in order.

==Notes about Radius Usage==
If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.

<syntaxhighlight lang='wml'>
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
</syntaxhighlight>

Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:

<syntaxhighlight lang='wml'>
[have_location]
x,y=15,23
radius=5 # oops... this time it won't work as expected
[not]
[filter]
[/filter]
[/not]
[have_location]
</syntaxhighlight>

will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.

== Directions ==

Some attributes expect a direction or list of directions. Valid base directions are n, ne, nw, s, se, sw, and there are three operators supported as well:

* To take the opposite direction, use - (eg -n is the same as s)
* {{DevFeature1.13|2}} To rotate clockwise, use :cw (eg n:cw is the same as ne)
* {{DevFeature1.13|2}} To rotate counterclockwise, use :ccw (eg n:ccw is the same as nw)

You can't apply multiple rotation operators - for example, "n:cw:ccw" is not a valid direction. If for some reason you really need multiple rotations, you can use parentheses (so, "(n:cw):ccw" is valid and is the same as n). Similarly, "--n" is not valid, but "-(-n)" is valid and is the same as n.

This syntax is mainly useful when used in conjunction with variable substitution in the adjacent key in [filter_adjacent_location] and in [filter_adjacent] (in [[StandardUnitFilter]]), but will work anywhere a direction is expected. For example, using [modify_unit] to change a unit's direction:

<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
# ... Whatever filter you need
[/filter]
facing=-$this_unit.facing
[/modify_unit]
</syntaxhighlight>

That will cause the matched units to turn around.

== Filtering Terrains ==

The '''terrain=''' key allows you to filter based on the terrain of a space, for example:

<syntaxhighlight lang='wml'>
[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]
</syntaxhighlight>

At some places the terrains can be filtered with a match list. This list is a comma separated list of [[TerrainCodesWML|terrain strings]] and patterns which will be processed in order. As soon as a pattern matching the reference terrain is found, the result of the filter will be determined.

Normally, if one of the patterns matches, the filter is considered successful. However, the special pattern <tt>!</tt> inverts this every time it is encountered – when inverted, the filter is considered ''unsuccessful'' when one of the patterns matches. In other words, <tt>Gg</tt> matches only basic grass, while <tt>!,Gg</tt> matches ''anything but'' basic grass.

When the end of the list is reached without any matches, normally the result is an unsuccessful match. However, if the match is currently inverted, ie there are an odd number of <tt>!</tt>, then the result is a successful match.

An individual terrain pattern consists of two parts, the base and the overlay, separated by the <tt>^</tt> character. The overlay (including the preceding <tt>^</tt>) is optional; if omitted, only terrains without overlays can be matched. The pattern may end with the wildcard character <tt>*</tt> (or be composed solely of the wildcard character). The pattern to match any terrain is <tt>*^*</tt>.

Example 1: 
ww* matches ww, www, wwW but not WWW 
!, ww returns false if ww found and true if not 
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

Example 2: 
<nowiki>*</nowiki>^V* matches all village-terrain 
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].

== Wesnoth Formula Language ==

When using SLF's '''formula''' attribute, the context object is a '''terrain hex object''' with the following properties:

* '''x''', '''y''', '''loc''': the latter is a '''location object''' such as what would be returned by [[Wesnoth_Formula_Language#loc|loc()]].
* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''light'''
* '''village''': a boolean containing the value of [terrain_type]gives_income=
* '''castle'''
* '''keep'''
* '''healing''': an integer containing the value of [terrain_type]heals=
* '''owner_side'''

For an up-to-date list, check the C++ function terrain_callable::get_value(const std::string& key) const.

Some location formulas also have access to a '''teleport_unit''' variable, which is a '''[[StandardUnitFilter#Wesnoth_Formula_Language|unit object]]'''.

== Tutorial ==
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

1.17 Roadmap

2022-02-05T13:16:38Z

Doofus-01: /* 1.17.15 (04/16/2023) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.17 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=55255 here].

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.17 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.18 released by February 2024. This will allow 1.18 to be in the Ubuntu 24.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other specific criteria to use as a final deadline. Alternatively, depending on what plans people have, 1.18 can be scheduled to happen earlier than that (in 2023).

== 1.17.0 (01/16/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6292 #6292] Fix+backport "Multi-turn moves are visible to enemy players" (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6283 #6283] Fix+backport "OOS watching MP replays" (Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6285 #6285] Fix+backport "Multiplayer scenarios with custom terrains don't load for non-host" (already done by Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6315 #6315] Fix+backport "[store_unit] and [modify_unit] move units from recall list to map" (octalot or celticminstrel)

== 1.17.1 (02/20/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6305 #6305] Fix "[foreach]array=this_item.something does not write back to the outer this_item". Undecided whether to backport. (octalot)
* (no issue logged) Add+backport Editor docs about the pink "D" deprecation marker (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6383 #6383] Fix+backport (Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6400 #6400] Fix+backport show in the terrain help that oases heal (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6422 #6422] Fix+backport hide editor hints about shift+click (octalot)

== 1.17.2 (03/20/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6225 #6225] Fix+backport Clarify editor docs about terrain mode, possibly revise error handling UX (octalot)

== 1.17.3 (04/17/2022) ==

== 1.17.4 (05/15/2022) ==
* Add forum_auth support to campaignd (Pentarctagon)

== 1.17.5 (06/19/2022) ==
* UtBS S12 (The Final Confrontation) Rework (knyghtmare)
* scenario_boss Micro AI (maybe it will be UtBS specific but it remains to be seen) (knyghtmare)
* Untitled RPG scenario/mini-campaign (depends on my schedule) (knyghtmare)

== 1.17.6 (07/17/2022) ==

== 1.17.7 (08/21/2022) ==
* Finish adding code comments for the WML unit tests (Pentarctagon)

== 1.17.8 (09/18/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)
* Reorganize the WML unit test file/folder structure so it's easier to find specific tests without using grep (Pentarctagon)

== 1.17.9 (10/16/2022) ==

== 1.17.10 (11/20/2022) ==
* sprite palette cleanup completed (doofus-01)

== 1.17.11 (12/18/2022) ==

== 1.17.12 (01/15/2023) ==
* New multiplayer maps focused on player vs player vs ai (Hejnewar)
* Revert [https://github.com/wesnoth/wesnoth/pull/6463 #6463] removing the deprecated SPECIAL_NOTES macro again (octalot)

== 1.17.13 (02/19/2023) ==

== 1.17.14 (03/19/2023) ==

== 1.17.15 (04/16/2023) ==
* finalize sprite palettes and swatches for defined recoloring (doofus-01)

== 1.17.16 (05/21/2023) ==

== 1.17.17 (06/18/2023) ==

== 1.17.18 (07/16/2023) ==

== 1.17.19 (08/20/2023) ==

== 1.17.20 (09/17/2023) ==
* Continue adding more WML/lua unit tests to improve API coverage (Pentarctagon)
* Balance changes focused mostly on higher levels and experience (Hejnewar)
* Hybrid Dunefolk campaign (Hejnewar)

== 1.17.21 (10/15/2023) (Beta 1) ==
'''This marks the beginning of the feature freeze and string freeze for 1.17;''' the only API changes made past this point must be to fix bugs.

== 1.17.22 (11/19/2023) (Beta 2) ==

== 1.17.23 (12/17/2023) (Beta 3) ==

== 1.17.24 (01/21/2024) (RC1) ==
'''This marks the beginning of the API freeze;''' no API changes for for any reason can be made at this point. Additional RC releases will be done as needed.

== 1.18.0 (02/18/2024) ==

[[Category:Roadmaps]]

1.17 Roadmap

2022-02-05T13:12:42Z

Doofus-01: /* 1.17.10 (11/20/2022) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.17 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=55255 here].

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.17 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.18 released by February 2024. This will allow 1.18 to be in the Ubuntu 24.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other specific criteria to use as a final deadline. Alternatively, depending on what plans people have, 1.18 can be scheduled to happen earlier than that (in 2023).

== 1.17.0 (01/16/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6292 #6292] Fix+backport "Multi-turn moves are visible to enemy players" (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6283 #6283] Fix+backport "OOS watching MP replays" (Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6285 #6285] Fix+backport "Multiplayer scenarios with custom terrains don't load for non-host" (already done by Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6315 #6315] Fix+backport "[store_unit] and [modify_unit] move units from recall list to map" (octalot or celticminstrel)

== 1.17.1 (02/20/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6305 #6305] Fix "[foreach]array=this_item.something does not write back to the outer this_item". Undecided whether to backport. (octalot)
* (no issue logged) Add+backport Editor docs about the pink "D" deprecation marker (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6383 #6383] Fix+backport (Pentarctagon)
* [https://github.com/wesnoth/wesnoth/issues/6400 #6400] Fix+backport show in the terrain help that oases heal (octalot)
* [https://github.com/wesnoth/wesnoth/issues/6422 #6422] Fix+backport hide editor hints about shift+click (octalot)

== 1.17.2 (03/20/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/6225 #6225] Fix+backport Clarify editor docs about terrain mode, possibly revise error handling UX (octalot)

== 1.17.3 (04/17/2022) ==

== 1.17.4 (05/15/2022) ==
* Add forum_auth support to campaignd (Pentarctagon)

== 1.17.5 (06/19/2022) ==
* UtBS S12 (The Final Confrontation) Rework (knyghtmare)
* scenario_boss Micro AI (maybe it will be UtBS specific but it remains to be seen) (knyghtmare)
* Untitled RPG scenario/mini-campaign (depends on my schedule) (knyghtmare)

== 1.17.6 (07/17/2022) ==

== 1.17.7 (08/21/2022) ==
* Finish adding code comments for the WML unit tests (Pentarctagon)

== 1.17.8 (09/18/2022) ==
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)
* Reorganize the WML unit test file/folder structure so it's easier to find specific tests without using grep (Pentarctagon)

== 1.17.9 (10/16/2022) ==

== 1.17.10 (11/20/2022) ==
* sprite palette cleanup completed (doofus-01)

== 1.17.11 (12/18/2022) ==

== 1.17.12 (01/15/2023) ==
* New multiplayer maps focused on player vs player vs ai (Hejnewar)
* Revert [https://github.com/wesnoth/wesnoth/pull/6463 #6463] removing the deprecated SPECIAL_NOTES macro again (octalot)

== 1.17.13 (02/19/2023) ==

== 1.17.14 (03/19/2023) ==

== 1.17.15 (04/16/2023) ==

== 1.17.16 (05/21/2023) ==

== 1.17.17 (06/18/2023) ==

== 1.17.18 (07/16/2023) ==

== 1.17.19 (08/20/2023) ==

== 1.17.20 (09/17/2023) ==
* Continue adding more WML/lua unit tests to improve API coverage (Pentarctagon)
* Balance changes focused mostly on higher levels and experience (Hejnewar)
* Hybrid Dunefolk campaign (Hejnewar)

== 1.17.21 (10/15/2023) (Beta 1) ==
'''This marks the beginning of the feature freeze and string freeze for 1.17;''' the only API changes made past this point must be to fix bugs.

== 1.17.22 (11/19/2023) (Beta 2) ==

== 1.17.23 (12/17/2023) (Beta 3) ==

== 1.17.24 (01/21/2024) (RC1) ==
'''This marks the beginning of the API freeze;''' no API changes for for any reason can be made at this point. Additional RC releases will be done as needed.

== 1.18.0 (02/18/2024) ==

[[Category:Roadmaps]]

ReferenceWML

2021-09-26T23:42:52Z

Doofus-01:

{{WML Tags}}
== The Wesnoth Markup Language ==

The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).

This page is a collection of pointers to different common WML structures.

See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
for a tutorial style overview.

''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''

== How WML works ==

* [[SyntaxWML]] Description of WML syntax, and how to use variables
* [[PreprocessorRef]] the WML preprocessor syntax
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.

== WML toplevel tags ==

The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.

* [[GameConfigWML]] the top level '''[game_config]''' tag
* [[UnitsWML]] the top level '''[units]''' tag
** [[UnitTypeWML]] how to describe a unit type
** [[AnimationWML]] how to animate units
* [[CampaignWML]] the top level '''[campaign]''' tag
* [[CoreWML]] the top level '''[core]''' tag
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', '''[test]''', and '''[tutorial]'''
** [[EventWML]] how to describe an event
** [[SideWML]] how to describe a side
** [[MapGeneratorWML]] the random map generator
** [[TimeWML]] how to describe a day
** [[IntroWML]] how to describe the intro screen
* [[EraWML]] the top level '''[era]''' tag
* [[TerrainWML]] the top level '''[terrain_type]''' tag
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
* [[ThemeWML]] the top level '''[theme]''' tag
* [[LanguageWML]] the top level '''[language]''' tag
* [[LocaleWML]] the top level '''[locale]''' tag
* [[HelpWML]] the top level '''[help]''' tag
* [[BinaryPathWML]] the top level '''[binary_path]''' tag
* [[FontsWML]] the top level '''[fonts]''' tag
* [[WesCamp#The_textdomain_declaration|Textdomains]] the '''[textdomain]''' tag

Some other files use the WML format, but with different tags.

* [[SavefileWML]] a description of the format of savegames
** [[ReplayWML]] a description of the format of player actions such as moving a unit
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
* [[PblWML]] a description of the format of server-uploadable campaigns
* [[SchemaWML]] a description of WML files that define the structure of other WML files
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
* [[GUIToolkit]] creating dialogs

== Other WML tags ==

* [[EventWML]] how to describe an event
** [[FilterWML]] the construct to filter on units, locations, and weapons
** [[ActionWML]] to describe the actions which occur when the event is fired
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
*** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit
**** [[SingleUnitWML]] how to describe a unit
*** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)
* [[AiWML]] how to describe parameters for AI
* [[EffectWML]] the construct to modify a unit
* [[AbilitiesWML]] a list of the different abilities a unit or weapon can have
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
* [[EditorWML]] tags controlling the post-1.4 editor's behavior

== Predefined macros ==

Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.

== Other ==

* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted
* [[ConventionsWML]] how to make your WML more readable
* [[Wml_optimisation]] how to make your WML code more efficient
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.
* [[Maintenance tools]] for wmlindent, wmllint, wmlscope
* [[CommandMode]] commands are not strictly speaking part of WML, these could be a little hard to find so there's a link here.
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
* [[ImagePathFunctions]] are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
* [[Pango formatting]] shows ways to enrich descriptions (pango markup, which can generate basic html tags like <nowiki>, , </nowiki> and others).
* [[Wesnoth_Formula_Language]] (WFL) often used with $() formulas.
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...

== See Also ==

* [[BuildingMaps]] the text-based format for Wesnoth maps
* [[TerrainCodeTableWML]] a list of all terrains, and [[TerrainCodesWML]], on how to use them
* [[MultiHexTutorial]] a description of the multi-hex tiling system
* [[IGNFileFormat]] a description of the ignore file format
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]

[[Category: WML Reference]]

LuaAPI/UpdatingFrom14

2021-07-05T13:41:19Z

Doofus-01: /* GUI2 API */

This page contains a summary of the major Lua API changes between 1.12 and 1.15, to help make updating older code simpler.

In general, when it says "renamed", the new function is a drop-in replacement for the old one. When it says "replaced", the new function probably has a different API (such as different arguments) or might not even be a function at all.

=== Functions in wesnoth namespace ===

* '''weesnoth.remove_fog''' renamed to '''wesnoth.sides.remove_fog'''
* '''wesnoth.add_ai_component''' renamed to '''wesnoth.sides.add_ai_component'''
* '''wesnoth.add_fog''' renamed to '''wesnoth.sides.place_fog'''
* '''wesnoth.add_modification''' renamed to '''wesnoth.units.add_modification'''
* '''wesnoth.add_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (write to key)
* '''wesnoth.add_tile_overlay''' renamed to '''wesnoth.interface.add_hex_overlay'''
* '''wesnoth.add_widget_definition''' renamed to '''gui.add_widget_definition'''
* '''wesnoth.advance_unit''' renamed to '''wesnoth.units.advance'''
* '''wesnoth.alert''' renamed to '''gui.alert'''
* '''wesnoth.allow_end_turn''' renamed to '''wesnoth.interface.allow_end_turn'''
* '''wesnoth.append_ai''' renamed to '''wesnoth.sides.append_ai'''
* '''wesnoth.canonical_path''' renamed to '''filesystem.canonical_path'''
* '''wesnoth.change_ai_component''' renamed to '''wesnoth.sides.change_ai_component'''
* '''wesnoth.clear_messages''' renamed to '''wesnoth.interface.clear_chat_messages'''
* '''wesnoth.color_adjust''' replaced with '''wesnoth.interface.color_adjust'''
* '''wesnoth.compare_versions''' replaced with '''wesnoth.version''', which creates a version object that can be compared with standard comparison operators
* '''wesnoth.confirm''' renamed to '''gui.confirm'''
* '''wesnoth.copy_unit''' renamed to '''wesnoth.units.clone'''
* '''wesnoth.create_animator''' renamed to '''wesnoth.units.create_animator'''
* '''wesnoth.create_side''' renamed to '''wesnoth.sides.create'''
* '''wesnoth.create_unit''' renamed to '''wesnoth.units.create'''
* '''wesnoth.create_weapon''' renamed to '''wesnoth.units.create_weapon'''
* '''wesnoth.debug_ai''' renamed to '''wesnoth.sides.debug_ai'''
* '''wesnoth.debug''' renamed to '''wml.tostring'''; in addition, it now produces an output that is valid WML, meaning that <syntaxhighlight lang=lua inline>wml.parse(wml.tostring(wml_table))</syntaxhighlight> will output a clone of '''wml_table''' (though for this purpose there's a separate '''wml.clone''' function which is probably faster).
* '''wesnoth.delay''' renamed to '''wesnoth.interface.delay'''
* '''wesnoth.delete_ai_component''' renamed to '''wesnoth.sides.delete_ai_component'''
* '''wesnoth.deselect_hex''' renamed to '''wesnoth.interface.deselect_hex'''
* '''wesnoth.end_level''' replaced with assignable '''wesnoth.scenario.end_level_data'''
* '''wesnoth.end_turn''' renamed to '''wesnoth.interface.end_turn'''
* '''wesnoth.erase_unit''' renamed to '''wesnoth.units.erase'''
* '''wesnoth.eval_conditiona''' renamed to '''wml.eval_conditional'''
* '''wesnoth.extract_unit''' renamed to '''wesnoth.units.extract'''
* '''wesnoth.find_cost_map''' renamed to '''wesnoth.paths.find_cost_map'''
* '''wesnoth.find_path''' renamed to '''wesnoth.paths.find_path'''
* '''wesnoth.find_reach''' renamed to '''wesnoth.paths.find_reach'''
* '''wesnoth.find_vacant_tile''' renamed to '''wesnoth.paths.find_vacant_tile'''
* '''wesnoth.find_vision_range''' renamed to '''wesnoth.paths.find_vision_range'''
* '''wesnoth.float_label''' renamed to '''wesnoth.interface.float_label'''
* '''wesnoth.format_conjunct_list''' renamed to '''stringx.format_conjunct_list'''
* '''wesnoth.format_disjunct_list''' renamed to '''stringx.format_disjunct_list'''
* '''wesnoth.format''' renamed to '''stringx.vformat''' and can also be called directly on a string literal
* '''wesnoth.gamestate_inspector''' renamed to '''gui.show_inspector'''
* '''wesnoth.get_all_vars''' replaced with read-only variable '''wml.all_variables''' (but it should still be used sparingly)
* '''wesnoth.get_displayed_unit''' renamed to '''wesnoth.interface.get_displayed_unit'''
* '''wesnoth.get_end_level_data''' replaced with readable '''wesnoth.scenario.end_level_data'''
* '''wesnoth.get_image_size''' renamed to '''filesystem.image_size'''
* '''wesnoth.get_max_liminal_bonus''' replaced with read-ony '''wesnoth.current.schedule.liminal_bonus'''
* '''wesnoth.get_mouseover_tile''' renamed to '''wesnoth.interface.get_hovered_hex'''
* '''wesnoth.get_recall_units''' renamed to '''wesnoth.units.find_on_recall'''
* '''wesnoth.get_selected_tile''' renamed to '''wesnoth.interface.get_selected_hex'''
* '''wesnoth.get_side_variable''' and '''wesnoth.set_side_variable''' replaced by '''variables''' member in side data (found in '''wesnoth.sides''' array). This otherwise works the same as '''wml.variables'''.
* '''wesnoth.get_sides''' renamed to '''wesnoth.sides.find'''
* '''wesnoth.get_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (read key)
* '''wesnoth.get_starting_location''' replaced by '''starting_location''' member in side data
* '''wesnoth.get_time_of_day''' replaced with '''wesnoth.schedule.get_time_of_day''' and '''wesnoth.schedule.get_illumination''' as well as '''wesnoth.current.schedule.time_of_day'''
* '''wesnoth.get_time_stamp''' renamed to '''wesnoth.ms_since_init'''
* '''wesnoth.get_traits''' replaced with '''wesnoth.game_config.global_traits'''
* '''wesnoth.get_unit''' renamed to '''wesnoth.units.get'''
* '''wesnoth.get_units''' renamed to '''wesnoth.units.find_on_map'''
* '''wesnoth.get_variable''' and '''wesnoth.set_variable''' are replaced by '''wml.variables''' which can be indexed with a variable path - set a variable by assigning to it
* '''wesnoth.have_file''' renamed to '''filesystem.have_file'''
* '''wesnoth.highlight_hex''' renamed to '''wesnoth.interface.highlight_hex'''
* '''wesnoth.invoke_synced_command''' renamed to '''wesnoth.sync.invoke_command'''
* '''wesnoth.is_enemy''' renamed to '''wesnoth.sides.is_enemy'''
* '''wesnoth.is_fogged''' renamed to '''wesnoth.sides.is_fogged'''
* '''wesnoth.is_shrouded''' renamed to '''wesnoth.sides.is_shrouded'''
* '''wesnoth.is_skipping_messages''' renamed to '''wesnoth.interface.is_skipping_messages'''
* '''wesnoth.lock_view''' renamed to '''wesnoth.interface.lock'''
* '''wesnoth.match_side''' renamed to '''wesnoth.sides.matches'''
* '''wesnoth.match_unit''' renamed to '''wesnoth.units.matches'''
* '''wesnoth.message''' renamed to '''wesnoth.interface.add_chat_message'''
* '''wesnoth.music_list''' renamed to '''wesnoth.audio.music_list'''
* '''wesnoth.open_help''' renamed to '''gui.show_help'''
* '''wesnoth.place_shroud''' replaced with '''wesnoth.sides.place_shroud''' and '''wesnoth.sides.override_shroud'''
* '''wesnoth.play_sound''' renamed to '''wesnoth.audio.play'''
* '''wesnoth.put_recall_unit''' renamed to '''wesnoth.units.to_recall'''
* '''wesnoth.put_unit''' renamed to '''wesnoth.units.to_map'''
* '''wesnoth.random''' renamed to '''mathx.random'''
* '''wesnoth.read_file''' renamed to '''filesystem.read_file'''
* '''wesnoth.remove_modifications''' renamed to '''wesnoth.units.remove_modifications'''
* '''wesnoth.remove_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (assign nil to key)
* '''wesnoth.remove_tile_overlay''' renamed to '''wesnoth.interface.remove_hex_overlay'''
* '''wesnoth.replace_schedule''' renamed to '''wesnoth.schedule.replace'''
* '''wesnoth.scroll_to_tile''' renamed to '''wesnoth.interface.scroll_to_hex'''
* '''wesnoth.scroll''' renamed to '''wesnoth.interface.scroll'''
* '''wesnoth.select_unit''' renamed to '''wesnoth.units.select''' (also available as wesnoth.interface.select_unit)
* '''wesnoth.set_end_campaign_credits''' replaced with assignable '''wesnoth.scenario.show_credits'''
* '''wesnoth.set_end_campaign_text''' replaced with assignable '''wesnoth.scenario.end_text''' and '''wesnoth.scenario.end_text_duration'''
* '''wesnoth.set_next_scenario''' replaced with assignable '''wesnoth.scenario.next'''
* '''wesnoth.set_side_id''' renamed to '''wesnoth.sides.set_id'''
* '''wesnoth.set_time_of_day''' (which was undocumented and unofficial) replaced with assigning '''wesnoth.current.schedule.time_of_day''', though that only covers part of the original functionality
* '''wesnoth.show_lua_console''' renamed to '''gui.show_lua_console'''
* '''wesnoth.show_menu''' renamed to '''gui.show_menu'''
* '''wesnoth.show_message_box''' renamed to '''gui.show_prompt'''
* '''wesnoth.show_message_dialog''' renamed to '''gui.show_narration'''
* '''wesnoth.show_popup_dialog''' renamed to '''gui.show_popup'''
* '''wesnoth.show_story''' renamed to '''gui.show_story'''
* '''wesnoth.skip_messages''' renamed to '''wesnoth.interface.skip_messages'''
* '''wesnoth.sound_volume''' replaced with read-write '''wesnoth.audio.volume'''
* '''wesnoth.switch_ai''' renamed to '''wesnoth.sides.switch_ai'''
* '''wesnoth.synchronize_choice''' renamed to '''wesnoth.sync.evaluate_single'''
* '''wesnoth.synchronize_choices''' renamed to '''wesnoth.sync.evaluate_multiple'''
* '''wesnoth.teleport''' renamed to '''wesnoth.units.teleport'''
* '''wesnoth.theme_items''' renamed to '''wesnoth.interface.game_display''' - it's still a table with the same keys as before
* '''wesnoth.tovconfig''' renamed to '''wml.tovconfig'''
* '''wesnoth.transform_unit''' renamed to '''wesnoth.units.transform'''
* '''wesnoth.unit_ability''' renamed to '''wesnoth.units.ability'''
* '''wesnoth.unit_defense''' renamed to '''wesnoth.units.chance_to_be_hit'''
* '''wesnoth.unit_jamming_cost''' renamed to '''wesnoth.units.jamming_on'''
* '''wesnoth.unit_movement_cost''' renamed to '''wesnoth.units.movement_on'''
* '''wesnoth.unit_resistance''' renamed to '''wesnoth.units.resistance'''
* '''wesnoth.unit_vision_cost''' renamed to '''wesnoth.units.vision_on'''
* '''wesnoth.unsynced''' renamed to '''wesnoth.sync.run_unsynced'''
* '''wesnoth.view_locked''' renamed to '''wesnoth.interface.is_locked'''
* '''wesnoth.wml_matches_filter''' renamed to '''wml.matches_filter'''
* '''wesnoth.zoom''' renamed to '''wesnoth.interface.zoom'''

==== wesnoth.tovconfig and related functions in plugins ====

The '''wesnoth.tovconfig''' function has been removed from the plugin context. This will have no effect on most people, as the plugin context is rarely used. A plugin context is any Lua script loaded using the <tt>--plugin</tt> command-line parameter, primarily intended for creating bots on the multiplayer server.

If you were calling '''wesnoth.tovconfig''' in a plugin, then you have several options for updating your code. If you simply needed to verify that a variable holds a valid WML table, you can use '''wml.valid''' instead. If you need to substitute variables into a WML table, you can also use '''wml.interpolate''' to replicate the behaviour of '''wml.tovconfig''', supplying the variables themselves as an extra argument (another WML table).

In addition, the helper functions '''parsed''', '''literal''', '''shallow_parsed''', and '''shallow_literal''' are not available in the plugin context.

==== GUI2 API ====

There has been a major rehaul of the GUI2 API for arbitrary custom dialogs. See [[LuaAPI/types/widget]] and [[LuaAPI/gui/widget]] for details; the changes are also summarized below.

* '''wesnoth.add_dialog_tree_node''' renamed to '''gui.widget.add_item_of_type''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference
* '''wesnoth.get_dialog_value''' and '''wesnoth.set_dialog_value''' removed; instead access the appropriate member of the widget, such as '''selected_index''' or '''selected''' or '''text''' or '''value''' or '''percentage''' or '''selected_item_path''' or '''unfolded''' or '''unit''' or '''label'''. Some of these may be write-only.
* '''wesnoth.remove_dialog_item''' renamed to '''gui.widget.remove_items_at''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference.
* '''wesnoth.set_dialog_active''' removed; instead assign the '''enabled''' member of a widget
** A simple example showing the old code commented out, replacement right below <syntaxhighlight lang=lua >
-- local function preshow()
local function preshow(self)
local var_a = true
-- < whatever you are doing to determine if button should be active >
-- wesnoth.set_dialog_active(var_a, "my_button_id")
local widget_handle = self:find('my_button_id')
widget_handle.enabled = var_a
-- ...
end
</syntaxhighlight>

* '''wesnoth.set_dialog_callback''' removed; instead simply assign to a widget's callback handler, eg <syntaxhighlight lang=lua inline>my_widget.on_modified = function() end</syntaxhighlight>
* '''wesnoth.set_dialog_canvas''' renamed to '''gui.widget.set_canvas''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference
* '''wesnoth.set_dialog_focus''' renamed to '''gui.widget.focus''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference
* '''wesnoth.set_dialog_markup''' removed; instead assign the '''use_markup''' member of a widget
* '''wesnoth.set_dialog_tooltip''' removed; instead assign the '''tooltip''' member of a widget
* '''wesnoth.set_dialog_visible''' removed; instead assign the '''visible''' member of a widget
* '''wesnoth.show_dialog''' renamed to '''gui.show_dialog'''
* The '''preshow''' and '''postshow''' functions passed to '''gui.show_dialog''' now take a single parameter, which is a reference to the dialog's root widget (a widget of type "window"). This can be passed to '''gui.widget.find''' to look up widgets by their path. You can also access direct child widgets by simply indexing the root widget.

==== Map API ====

Due to a major rehaul of the map API, many map functions are now methods on the map object, available as '''wesnoth.current.map''' (abbreviated in the below listing to just '''map''').

* '''wesnoth.add_time_area''' renamed to '''wesnoth.map.place_area'''
* '''wesnoth.get_locations''' renamed to '''wesnoth.map.find'''
* '''wesnoth.get_map_size''' replaced with '''map.playable_width''', '''map.playable_height''', and '''map.border_size'''
* '''wesnoth.get_terrain_info''' replaced with '''wesnoth.terrain_types'''
* '''wesnoth.get_terrain''' replaced with '''map[{x,y}]'''
* '''wesnoth.get_village_owner''' renamed to '''wesnoth.map.get_owner'''
* '''wesnoth.get_villages''' replaced with '''wesnoth.map.find''' (with '''gives_income = true''')
* '''wesnoth.label''' renamed to '''wesnoth.map.add_label'''
* '''wesnoth.match_location''' renamed to '''wesnoth.map.matches'''
* '''wesnoth.remove_time_area''' renamed to '''wesnoth.map.remove_area'''
* '''wesnoth.set_terrain''' replaced with assigning '''map[{x,y}]''' - helper functions in '''wesnoth.map''' expose the more advanced assignment operations ('''replace_overlay''', '''replace_both''', '''replace_if_failed''') - just assign the result of one of these functions to the hex
* '''wesnoth.set_village_owner''' renamed to '''wesnoth.map.set_owner'''
* '''wesnoth.special_locations''' renamed to '''map.special_locations''' (note: the length operator is no longer supported)
* '''wesnoth.terrain_mask''' replaced with '''map:terrain_mask'''

The following functions are only available in map generation scripts:

* '''wesnoth.create_filter''' renamed to '''wesnoth.map.filter'''
* '''wesnoth.create_map''' renamed to '''wesnoth.map.create'''
* '''wesnoth.default_generate_height_map''' renamed to '''wesnoth.map.generate_height_map'''
* '''wesnoth.generate_default_map''' renamed to '''wesnoth.map.generate'''
* '''map:get_locations''' renamed to '''map:find'''
* '''map:get_tiles_radius''' replaced with '''map::find_in_radius''' (and the order of arguments changed)

=== helper module ===

The helper module is being phased out, so quite a lot of things have been moved out of it. This section is written under the assumption that you loaded it with <syntaxhighlight lang=lua inline>local helper = wesnoth.require "helper"</syntaxhighlight> or the like, but many people call it '''H''' instead of '''helper''', so keep that in mind.

* '''helper.child_array''' renamed to '''wml.child_array'''
* '''helper.child_count''' renamed to '''wml.child_count'''
* '''helper.child_range''' renamed to '''wml.child_range'''
* '''helper.distance_between''' renamed to '''wesnoth.map.distance_between'''
* '''helper.find_attack''' renamed to '''wesnoth.units.find_attack'''
* '''helper.get_child''' renamed to '''wml.get_child'''
* '''helper.get_nth_child''' renamed to '''wml.get_nth_child'''
* '''helper.get_user_choice''' renamed to '''gui.get_user_choice'''
* '''helper.get_variable_array''' renamed to '''wml.array_access.get'''
* '''helper.get_variable_proxy_array''' renamed to '''wml.array_access.get_proxy'''
* '''helper.literal''' renamed to '''wml.literal'''
* '''helper.modify_unit''' renamed to '''wesnoth.units.modify'''
* '''helper.move_unit_fake''' renamed to '''wesnoth.interface.move_unit_fake'''
* '''helper.parsed''' renamed to '''wml.parsed'''
* '''helper.rand''' renamed to '''mathx.random_choice'''
* '''helper.round''' renamed to '''mathx.round'''
* '''helper.set_variable_array''' renamed to '''wml.array_access.set'''
* '''helper.set_wml_tag_metatable''' replaced with '''wml.tag''', which is a table that works exactly the same as what this function would return
* '''helper.set_wml_var_metatable''' replaced with '''wml.variable.proxy''', which is a table that works exactly the same as what this function would return
* '''helper.shallow_literal''' renamed to '''wml.shallow_literal'''
* '''helper.shallow_parsed''' renamed to '''wml.shallow_parsed'''
* '''helper.shuffle''' renamed to '''mathx.shuffle'''
* '''helper.wml_error''' renamed to '''wml.error'''

=== items module ===

There were also a few things in an "items" module that have been moved into the main API.

* '''items.place_halo''' renamed to '''wesnoth.interface.add_item_halo'''
* '''items.place_image''' renamed to '''wesnoth.interface.add_item_image'''
* '''items.remove''' renamed to '''wesnoth.interface.remove_item'''

[[Category:Lua Reference]]

Release Notes 1.15.4

2020-08-22T11:53:00Z

Doofus-01: /* New Content */

== New Content ==
=== Addon titles and descriptions made translatable ===
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].

=== Units ===
==== Dunefolk ====
Most of the Dunefolk faction's units have new/updated animations. There is also a new unit called falconer, which is a branch in the skirmisher line.

=== Knalgan Alliance ===
The Poacher and Trapper sprites and animations have been improved.

=== Multiplayer ===
==== World Conquest ====
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.

==== Lobby ====
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.

=== Terrain ===
An earthy variation to rockbound caves has been added, using terrain code "Uhe".
Ancient/weathered variations of the stone floor tiles and walls have been added, with terrain codes "Ias" and "Xoa".

== Changes To Existing Content ==

=== Campaign changes ===

==== Under the Burning Suns ====
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.

==== Delfador's Memoirs ====
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.

=== Balance changes ===
==== Drakes ====
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.

==== Dunefolk ====
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units.

==== Knalgan Alliance ====
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups

Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.

Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.

==== Loyalists ====
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.

==== Northerners ====
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.

==== Rebels ====
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.

Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.

Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend.

==== Undead ====
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit.

Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.

Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.

==== Monsters ====
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.

== Fixes ==
=== Graphics engine memory leak fix ===
An issue dating back to version 1.13.13 was found in the game’s graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.

=== Scenario configuration files created by the scenario editor ===
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.

The editor-generated .cfg files can be thought of as an extended format for map files. It’s possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.

=== Add-on manager downloading the same add-on twice when updating ===
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.

=== Creating a game when a map contains an invalid terrain ===
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.

=== Handling of high resolution monitors ===
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.

== General/Misc ==
=== Python2 removal complete ===
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.

=== Build report ===
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.

=== Timestamps on replay file names ===
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.

=== Eclipse UMC plugin deprecated ===
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.

== Newly Introduced Issues ==

[[Category:Release_Notes]]

Release Notes 1.15.4

2020-08-22T11:42:48Z

Doofus-01: /* Dunefolk */

== New Content ==
=== Addon titles and descriptions made translatable ===
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].

=== Units ===
==== Dunefolk ====
Most of the Dunefolk faction's units have new/updated animations. There is also a new unit called falconer, which is a branch in the skirmisher line.

=== Knalgan Alliance ===
The Poacher and Trapper sprites and animations have been improved.

=== Multiplayer ===
==== World Conquest ====
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.

==== Lobby ====
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.

== Changes To Existing Content ==

=== Campaign changes ===

==== Under the Burning Suns ====
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.

==== Delfador's Memoirs ====
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.

=== Balance changes ===
==== Drakes ====
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.

==== Dunefolk ====
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units.

==== Knalgan Alliance ====
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups

Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.

Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.

==== Loyalists ====
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.

==== Northerners ====
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.

==== Rebels ====
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.

Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.

Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend.

==== Undead ====
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit.

Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.

Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.

==== Monsters ====
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.

== Fixes ==
=== Graphics engine memory leak fix ===
An issue dating back to version 1.13.13 was found in the game’s graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.

=== Scenario configuration files created by the scenario editor ===
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.

The editor-generated .cfg files can be thought of as an extended format for map files. It’s possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.

=== Add-on manager downloading the same add-on twice when updating ===
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.

=== Creating a game when a map contains an invalid terrain ===
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.

=== Handling of high resolution monitors ===
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.

== General/Misc ==
=== Python2 removal complete ===
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.

=== Build report ===
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.

=== Timestamps on replay file names ===
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.

=== Eclipse UMC plugin deprecated ===
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.

== Newly Introduced Issues ==

[[Category:Release_Notes]]

Release Notes 1.15.4

2020-08-22T11:38:39Z

Doofus-01: /* Under the Burning Suns */

== New Content ==
=== Addon titles and descriptions made translatable ===
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].

=== Units ===
==== Dunefolk ====
Most of the Dunefolk faction's units have new/updated animations.

=== Knalgan Alliance ===
The Poacher and Trapper sprites and animations have been improved.

=== Multiplayer ===
==== World Conquest ====
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.

==== Lobby ====
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.

== Changes To Existing Content ==

=== Campaign changes ===

==== Under the Burning Suns ====
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.

==== Delfador's Memoirs ====
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.

=== Balance changes ===
==== Drakes ====
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.

==== Dunefolk ====
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units.

==== Knalgan Alliance ====
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups

Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.

Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.

==== Loyalists ====
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.

==== Northerners ====
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.

==== Rebels ====
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.

Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.

Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend.

==== Undead ====
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit.

Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.

Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.

==== Monsters ====
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.

== Fixes ==
=== Graphics engine memory leak fix ===
An issue dating back to version 1.13.13 was found in the game’s graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.

=== Scenario configuration files created by the scenario editor ===
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.

The editor-generated .cfg files can be thought of as an extended format for map files. It’s possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.

=== Add-on manager downloading the same add-on twice when updating ===
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.

=== Creating a game when a map contains an invalid terrain ===
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.

=== Handling of high resolution monitors ===
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.

== General/Misc ==
=== Python2 removal complete ===
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.

=== Build report ===
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.

=== Timestamps on replay file names ===
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.

=== Eclipse UMC plugin deprecated ===
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.

== Newly Introduced Issues ==

[[Category:Release_Notes]]

1.15 Roadmap

2020-08-08T16:32:02Z

Doofus-01: /* 1.15.6 (10/17/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Fix #5004 (Pentarctagon)
* Fix #4898 (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* Drop the python2 wmlparser and wmlparser2. This would finish issue #1508, and it now seems to be at the "remove it and see if anyone wants it back" stage. (octalot).
* Either drop or document the l10n-track file, issue #4717 (octalot)

== 1.15.5 (09/19/2020) ==

* Campaignd storage rework and incremental updates (#5038), then incremental uploads (kabachuha)
* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* Improve the documentation for the editor, following from the discussion in PR #4999 (octalot)
* Fix issue #4876, by making UtBS's Quenoth elves not share their help pages with forest elves (octalot)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* Add a help page for gold/silver crowns and loyal marker, issue #4455. (octalot)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)
* Mainline Undead Empire (an ANL scenario) (Sevu)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate email or passphrase value (Pentarctagon)
* Reorganize scenario/era/modification data in the <nowiki>game_info</nowiki> and <nowiki>game_modification_info</nowiki> database tables into a separate <nowiki>game_content_info</nowiki> table (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)
* Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps. (octalot)
* Handling of vision and movement, issues #3356, #4179. (octalot)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)
* Either merge or reject a refactor of terrain handling, as described in issue #4279, Ford^Overlay: Costs for worst(best(a, b), c, d) terrain are worst(a, b, c, d). (octalot)
* Remove the wesnoth-ai textdomain, as suggested in #4669 (octalot)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)
* Possibly work on an UtBS dialogue touchup. (nemaara)
* By this time, hopefully move around the campaigns so that they're more correctly ordered in difficulty (either rebalancing or simply changing their difficulty ratings). Applies especially to EI. (nemaara)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-08-08T16:31:23Z

Doofus-01: /* 1.15.4 (08/22/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Fix #5004 (Pentarctagon)
* Fix #4898 (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* Drop the python2 wmlparser and wmlparser2. This would finish issue #1508, and it now seems to be at the "remove it and see if anyone wants it back" stage. (octalot).
* Either drop or document the l10n-track file, issue #4717 (octalot)

== 1.15.5 (09/19/2020) ==

* Campaignd storage rework and incremental updates (#5038), then incremental uploads (kabachuha)
* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* Improve the documentation for the editor, following from the discussion in PR #4999 (octalot)
* Fix issue #4876, by making UtBS's Quenoth elves not share their help pages with forest elves (octalot)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* Add a help page for gold/silver crowns and loyal marker, issue #4455. (octalot)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)
* Mainline Undead Empire (an ANL scenario) (Sevu)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate email or passphrase value (Pentarctagon)
* Reorganize scenario/era/modification data in the <nowiki>game_info</nowiki> and <nowiki>game_modification_info</nowiki> database tables into a separate <nowiki>game_content_info</nowiki> table (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)
* Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps. (octalot)
* Handling of vision and movement, issues #3356, #4179. (octalot)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)
* Either merge or reject a refactor of terrain handling, as described in issue #4279, Ford^Overlay: Costs for worst(best(a, b), c, d) terrain are worst(a, b, c, d). (octalot)
* Remove the wesnoth-ai textdomain, as suggested in #4669 (octalot)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)
* Possibly work on an UtBS dialogue touchup. (nemaara)
* By this time, hopefully move around the campaigns so that they're more correctly ordered in difficulty (either rebalancing or simply changing their difficulty ratings). Applies especially to EI. (nemaara)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T15:27:32Z

Doofus-01: /* 1.15.14 (06/19/2021) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T15:26:46Z

Doofus-01: /* 1.15.6 (10/17/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T15:25:24Z

Doofus-01: /* 1.15.5 (09/19/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T02:06:51Z

Doofus-01: /* 1.15.14 (06/19/2021) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T02:01:09Z

Doofus-01: /* 1.15.11 (03/20/2021) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)
* Portraits for any new animals added in earlier milestones (doofus-01)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T01:58:44Z

Doofus-01: /* 1.15.8 (12/19/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)
* Sprites and basic animations for any approved new animals (doofus-01)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T01:56:47Z

Doofus-01: /* 1.15.4 (08/22/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)
* PR for new animals/monsters, art to be finalized later (doofus-01)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T01:53:57Z

Doofus-01: /* 1.15.9 (01/16/2021) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)
* PR for Ghoul line portraits (doofus-01)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T01:52:06Z

Doofus-01: /* 1.15.5 (09/19/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

1.15 Roadmap

2020-07-26T01:46:54Z

Doofus-01: /* 1.15.6 (10/17/2020) */

This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.

== Instructions ==
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.

Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.

== 1.15.4 (08/22/2020) ==

* Mainlining World conquest II (gfgtdf)
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)
* Add the logger level statements needed to fix #4898 (Pentarctagon)
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)
* Add Royal Warrior portrait (LordBob)

== 1.15.5 (09/19/2020) ==

* Campaignd support for different min wesnoth versions (gfgtdf)
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)

== 1.15.6 (10/17/2020) ==

* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)
* Re-add the dunefolk faction to WCII (gfgtdf)
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)
* Implement a game history viewer by utilizing queryd (Pentarctagon)
* Add Wose shaman portrait (Lordbob)
* Look how practical the new mainline macros are (Sevu)
* PR with changes to mainline macros (Sevu)
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)

== 1.15.7 (11/21/2020) ==
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)
* Rebalance prices of monster units & Chocobone (Sevu)
* Mainline Visual Map Pack (Sevu)

== 1.15.8 (12/19/2020) ==
* Add SQL support to campaignd using mariadbpp (Pentarctagon)
* Store add-on upload history in the database (Pentarctagon)
* Revamp Duelist line portraits (Lordbob)

== 1.15.9 (01/16/2021) ==
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)

== 1.15.10 (02/20/2021) ==
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)
* Add missing story art for tRoW (Lordbob)

== 1.15.11 (03/20/2021) ==
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)

== 1.15.12 (04/17/2021) ==
* Add story art for UtBS (Lordbob)

== 1.15.13 (05/15/2021) ==
*

== 1.15.14 (06/19/2021) ==
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)

== 1.15.15 (07/17/2021) ==
*

[[Category:Roadmaps]]

PblWML

2020-02-17T02:44:19Z

Doofus-01: /* type */

{{WML Tags}}

To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.

See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.

Note: Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctions]] to recolor it.

: {{DevFeature1.13|12}} Instead of a standard Wesnoth image, a [[DataURI]] can also be used. This way, an image can be directly included into the _server.pbl file. Take care to leave no trailing newline.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.
: '''This value is required'''.

=== version ===
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers — and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the “Update All” button to work correctly. ([[#Version Key Examples|See Examples]])
: '''This value is required'''.

=== author ===
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.
: '''This value is required'''.

=== passphrase ===
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.
: '''This value is required'''.

=== dependencies ===
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== tags ===
{{DevFeature1.13|12}}
: An optional string including a comma-separated list of keywords used for matching add-ons when typing terms into the Filter box on the top left of the Add-ons Manager. There are no specific requirements on the syntax of the keywords listed here, but a general recommendation is to keep them relevant for players. For example, one might include the add-on's acronym in the tags, the names or acronyms of add-ons to which it is related, and so on.

=== core ===
{{DevFeature1.13|0}}
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself.

=== translate ===
: If set to ''true'', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)

: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.

: Note: As of April 4th, 2015, WesCamp appears to have been abandoned for about a year. It might be back soon, it might not. Instead, please refer to [[GettextForWesnothDevelopers#Gettext_for_UMC_Developers]].

=== type ===
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:

:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}
:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''campaign_sp_mp'': hybrid campaign.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''mod_mp'': multiplayer modification ({{DevFeature1.13|11}} can also used for single-player modifications, although it's still called ''mod_mp'').
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc. Note: Shows as Resources, not Media, in the add-ons interface
:* ''other'': The type to use when no other type fits.
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

: '''This value is required'''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.
: '''This value is required'''.

=== [feedback] ===
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.

==== topic_id ====
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

The following are examples of '''good''' version values:

version="1.5"
version="0.11.4"
version="0.1.4beta"
version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"
version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0
1.5 < 1.5c
1.0 < 1.0.1
1.0c < 1.0.1a
1.0.1a < 1.0.1c
1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

<syntaxhighlight lang=wml>
title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"
[feedback]
topic_id=12345
[/feedback]
</syntaxhighlight>

== See Also ==

* [[IGNFileFormat]]
* [[FancyAddonIcons]]
* [[ReferenceWML]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2020-01-06T04:12:50Z

Doofus-01: /* [remove_item] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://developer.gnome.org/pango/stable/pango-Markup.html Pango markup formatting codes].

Remember to use single quotes (') instead of double quotes (") within the formatting string, as double quotes cannot be escaped, and the string will appear fragmented and possibly cause errors. Escaping markup is described in https://github.com/wesnoth/wesnoth/blob/master/src/font/pango/escape.hpp#L35-L39.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''': if specified, only removes the given image item (This image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)
* '''name''': removes an item with a previously defined name.
''Note: The filtering on this tag is not what a normal person would expect. Filtering on the item's halo key or name key will most likely fail. This should be fixed some day, see https://github.com/wesnoth/wesnoth/issues/4689 For now, use the SLF and/or image key.''

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. {{DevFeature1.13|x}} Use of red, green, blue is now deprecated; use color=0,0,0 instead.

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using remove_object is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

InterfaceActionsWML

2020-01-06T04:12:07Z

Doofus-01: /* [remove_item] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). [message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://developer.gnome.org/pango/stable/pango-Markup.html Pango markup formatting codes].

Remember to use single quotes (') instead of double quotes (") within the formatting string, as double quotes cannot be escaped, and the string will appear fragmented and possibly cause errors. Escaping markup is described in https://github.com/wesnoth/wesnoth/blob/master/src/font/pango/escape.hpp#L35-L39.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).
* '''name''' an id that can be used to remove the item.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''': if specified, only removes the given image item (This image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)
* '''name''': removes an item with a previously defined name.
''Note: The filtering on this tag is not what a normal person would expect. Filtering on the item's halo key or name key will most likely fail. This should be fixed some day, but for now see https://github.com/wesnoth/wesnoth/issues/4689 For now, use the SLF and/or image key.''

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. {{DevFeature1.13|x}} Use of red, green, blue is now deprecated; use color=0,0,0 instead.

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to] ===
Scroll to a given hex
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''': As [[IntroWML]].

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
Using remove_object is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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