https://wiki.wesnoth.org/api.php?action=feedcontributions&user=Josteph&feedformat=atomThe Battle for Wesnoth Wiki - User contributions [en]2024-03-29T14:12:08ZUser contributionsMediaWiki 1.31.16https://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64976ReleasingWesnoth2019-10-20T03:14:36Z<p>Josteph: /* todo steps to add */</p>
<hr />
<div>== todo steps to add ==<br />
<br />
Mac package: details in projectfiles/Xcode/README.md<br />
<br />
Windows package: ?<br />
<br />
Android package: (third party, but still, details?)<br />
<br />
iOS package: ?<br />
<br />
For us:<br />
<br />
* forum post in News<br />
* forum post in Announcements<br />
* Updating the download page on the wiki<br />
* Updating the front page<br />
* rebuild the front page (<code>git pull</code> and <code>make</code> after SSHing to www.wesnoth.org)<br />
* Announcing the release on Discord<br />
* Announcing the release on Steam.<br />
** This included making a new header graphic if it's a stable release.<br />
* Announcing the release on Twitter with a link to the forum post<br />
<br />
== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
** For 1.15.3, review the [https://github.com/wesnoth/wesnoth/milestone/20 pre-1.16.0 string freeze] issues<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
'''TODO:''' Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64975ReleasingWesnoth2019-10-20T03:14:20Z<p>Josteph: /* todo steps to add */</p>
<hr />
<div>== todo steps to add ==<br />
<br />
Mac package: details in projectfiles/Xcode/README.md<br />
<br />
Windows package: ?<br />
<br />
Android package: (third party, but still, details?)<br />
<br />
iOS package: ?<br />
<br />
For us:<br />
<br />
* forum post in News<br />
* forum post in Announcements<br />
* Updating the download page on the wiki<br />
* Updating the front page<br />
* rebuild the front page (`git pull` and `make` after SSHing to www.wesnoth.org)<br />
* Announcing the release on Discord<br />
* Announcing the release on Steam.<br />
** This included making a new header graphic if it's a stable release.<br />
* Announcing the release on Twitter with a link to the forum post<br />
<br />
== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
** For 1.15.3, review the [https://github.com/wesnoth/wesnoth/milestone/20 pre-1.16.0 string freeze] issues<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
'''TODO:''' Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64973ReleasingWesnoth2019-10-20T03:05:37Z<p>Josteph: todo</p>
<hr />
<div>== todo steps to add ==<br />
<br />
Mac package: details in projectfiles/Xcode/README.md<br />
<br />
Windows package: ?<br />
<br />
Android package: (third party, but still, details?)<br />
<br />
iOS package: ?<br />
<br />
For us:<br />
<br />
- forum post in News<br />
- forum post in Announcements<br />
- Updating the download page on the wiki<br />
- Updating the front page<br />
- rebuild the front page (ask Iris)<br />
- Announcing the release on Discord<br />
- Announcing the release on Steam.<br />
- This included making a new header graphic if it's a stable release.<br />
- Announcing the release on Twitter with a link to the forum post<br />
<br />
<br />
== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
** For 1.15.3, review the [https://github.com/wesnoth/wesnoth/milestone/20 pre-1.16.0 string freeze] issues<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
'''TODO:''' Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=PreprocessorRef&diff=64972PreprocessorRef2019-10-19T23:59:11Z<p>Josteph: /* #deprecated */ fix synopsis</p>
<hr />
<div>{{WML Tags}}<br />
== Overview ==<br />
<br />
Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.<br />
<br />
The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.<br />
<br />
The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).<br />
<br />
== Preprocessor directives ==<br />
<br />
The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.<br />
<br />
The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.<br />
<br />
'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.<br />
<br />
=== #define ===<br />
<br />
'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''<br />
<br />
All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define ENEMY_UNIT TYPE X Y<br />
## the ordering above is important, since the preprocessor does not distinguish<br />
## data into different types; only the ordering is used to determine which<br />
## arguments apply to which parameters.<br />
[unit]<br />
type={TYPE} ## the unit will be of type TYPE, so different<br />
## instantiations<br />
## of this macro can create different units.<br />
x={X}<br />
y={Y}<br />
side=2 ## the unit will be an enemy, regardless of the parameter<br />
## values. This reduces "repetition of information",<br />
## since it is no longer necessary to specify<br />
## each created unit as an enemy.<br />
[/unit]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
(See [[SingleUnitWML]] for further information on creating units using WML.)<br />
<br />
'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].<br />
<br />
=== #arg and #endarg ===<br />
<br />
{{DevFeature1.13|7}} <br />
<br />
Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.<br />
<br />
For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define MESSAGE TEXT<br />
<br />
#arg SPEAKER_ID<br />
narrator<br />
#endarg<br />
<br />
#arg CAPTION<br />
#endarg<br />
<br />
#arg SOUND<br />
#endarg<br />
<br />
#arg IMG<br />
#endarg<br />
<br />
[message]<br />
speaker={SPEAKER_ID}<br />
message={TEXT}<br />
caption={CAPTION}<br />
sound={SOUND}<br />
image={IMG}<br />
[/message]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
The caller of the macro can then decide which, if any, of the default values to override:<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}<br />
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}<br />
{MESSAGE _"..."}<br />
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}<br />
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}<br />
</syntaxhighlight><br />
<br />
Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.<br />
<br />
=== #undef ===<br />
<br />
'''Syntax:''' '''#undef ''symbol'' '''<br />
<br />
Removes the previous definition of the macro named ''symbol''.<br />
<br />
=== Inclusion directive {} ===<br />
<br />
This directive can be used to include macros, single files or sets of files from a target directory.<br />
<br />
==== File/directory inclusions ====<br />
<br />
'''Syntax: {''path''}'''<br />
<br />
Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.<br />
<br />
The exact location in which the ''path'' will be resolved will depend on its prefix:<br />
<br />
* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.<br />
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.<br />
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.<br />
<br />
Information for locating the user data and game data directories can be found in [[EditingWesnoth]].<br />
<br />
Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.<br />
<br />
When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.<br />
<br />
Some directories are handled in a special fashion according to their contents:<br />
<br />
* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.<br />
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:<br />
dir/<br />
dir/a/_main.cfg<br />
dir/a/other.cfg<br />
dir/b/_main.cfg<br />
dir/b/other.cfg<br />
dir/other.cfg<br />
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.<br />
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.<br />
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.<br />
<br />
==== Macro inclusions ====<br />
<br />
'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''<br />
<br />
If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.<br />
<br />
You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.<br />
<br />
Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct<br />
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong<br />
</syntaxhighlight><br />
<br />
This way even complex arguments can be passed:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MODIFY_UNIT (<br />
[filter_adjacent]<br />
canrecruit=yes<br />
[/filter_adjacent]<br />
) side 2}<br />
</syntaxhighlight><br />
<br />
Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define VARIABLE<br />
#enddef<br />
#define MACRO VARIABLE<br />
{VARIABLE} # is calling for the argument, not for the macro above<br />
#enddef<br />
</syntaxhighlight><br />
<br />
=== #ifdef and #ifndef ===<br />
<br />
Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).<br />
<br />
'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''<br />
<br />
If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.<br />
<br />
'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:<br />
<br />
'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''<br />
<br />
=== #ifhave and #ifnhave ===<br />
<br />
'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''<br />
<br />
Checks for the existence of a file. Uses the same relative paths as include directives (see below).<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="wml"><br />
#ifhave ~add-ons/My_Addon/_main.cfg<br />
{MY_ADDON_MACROS}<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnhave''' does the opposite of '''#ifhave''':<br />
<br />
'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''<br />
<br />
=== #ifver and #ifnver ===<br />
<br />
'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''<br />
<br />
Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.<br />
<br />
Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION >= 1.9.7+<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"<br />
[/message]<br />
#else<br />
#ifver WESNOTH_VERSION == 1.9.7<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"<br />
[/message]<br />
#endif<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnver''' does the opposite of '''#ifver''':<br />
<br />
'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''<br />
<br />
=== #error ===<br />
<br />
'''Syntax:''' '''#error [''message'']'''<br />
<br />
Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.<br />
<br />
Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#error This add-on does not support Wesnoth 1.11.10!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #warning ===<br />
<br />
'''Syntax:''' '''#warning [''message'']'''<br />
<br />
Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #deprecated ===<br />
<br />
{{DevFeature1.13|11}}<br />
<br />
'''Syntax:''' '''#deprecated 1 ''message'''''<br />
<br />
'''Syntax:''' '''#deprecated 2 ''version'' ''message'''''<br />
<br />
'''Syntax:''' '''#deprecated 3 ''version'' ''message'''''<br />
<br />
'''Syntax:''' '''#deprecated 4 ''message'''''<br />
<br />
The effect of this directive depends on whether it appears within a macro definition.<br />
<br />
* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.<br />
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.<br />
<br />
Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)<br />
<br />
If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.<br />
<br />
== Built-in macros ==<br />
<br />
The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.<br />
<br />
* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.<br />
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.<br />
* '''MULTIPLAYER''': defined when in multiplayer mode.<br />
* '''TUTORIAL''': defined when playing the tutorial campaign.<br />
* '''EDITOR''': defined when running the built-in map editor.<br />
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).<br />
* '''APPLE''': defined while processing the main game data when running on Mac OS X.<br />
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.<br />
* '''CURRENT_FILE''': Expands to the name of the current WML file.<br />
* '''CURRENT_DIRECTORY''': Expands to the name of the directory of {CURRENT_FILE}, I assume?<br />
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.<br />
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.<br />
<br />
Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html<br />
<br />
== Command-line preprocessor ==<br />
<br />
'''Syntax: --preprocess ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
Or the short form:<br />
<br />
'''Syntax: -p ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
You can specify a list of predefined defines with:<br />
<br />
'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''<br />
<br />
comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.<br />
<br />
The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.<br />
<br />
The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.<br />
<br />
If by chance, the simple macro define doesn't suffice, you can use:<br />
<br />
'''Syntax: --preprocess-input-macros <file>'''<br />
<br />
To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.<br />
<br />
There is also the possibility to export the preprocessed defines/macro list with:<br />
<br />
'''Syntax: --preprocess-output-macros [<target file>]'''<br />
<br />
This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.<br />
<br />
If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.<br />
<br />
Some examples:<br />
<br />
* Preprocess the entire tutorial dir, and write the results in the ~/result folder:<br />
-p ~/wesnoth/data/campaigns/tutorial ~/result<br />
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER<br />
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD<br />
<br />
If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.<br />
<br />
== See Also ==<br />
<br />
* [[SyntaxWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64971SpellingMistakes2019-10-19T23:46:16Z<p>Josteph: moved to github</p>
<hr />
<div>'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
(If you don't already have an account, see https://github.com/wesnoth/wesnoth/blob/master/.github/ISSUE_TEMPLATE/text-typos-or-improvements.md.)<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64969SpellingMistakes2019-10-19T22:34:35Z<p>Josteph: /* Northern Rebirth */ rejected, see IRC</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
<br />
===Heir to the Throne===<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64968SpellingMistakes2019-10-19T22:33:37Z<p>Josteph: /* Heir to the Throne */ S18 done, S24 correct as is, third one discarded</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
<br />
===Heir to the Throne===<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64967SpellingMistakes2019-10-19T22:22:33Z<p>Josteph: /* Eastern Invasion */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
<br />
===Heir to the Throne===<br />
S24 "rightful queen" to "rightful Queen"<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64966SpellingMistakes2019-10-19T22:21:13Z<p>Josteph: /* Eastern Invasion */ moved to #4145</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
===Heir to the Throne===<br />
S24 "rightful queen" to "rightful Queen"<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64965SpellingMistakes2019-10-19T22:16:28Z<p>Josteph: point to GitHub for Vultraz</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
===Heir to the Throne===<br />
S24 "rightful queen" to "rightful Queen"<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64964SpellingMistakes2019-10-19T22:15:09Z<p>Josteph: /* Heir to the Throne */ merged</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
===Heir to the Throne===<br />
S24 "rightful queen" to "rightful Queen"<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64963SpellingMistakes2019-10-19T21:33:24Z<p>Josteph: merged to master</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
===Heir to the Throne===<br />
S24 "rightful queen" to "rightful Queen"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
S23 "We must make haste! Far greater challenges lie before us, by tarrying here we’re diminishing our resources." comma splice<br />
<br />
S23 "mount Elnar" to "Mount Elnar" (capitalized) and pofix<br />
<br />
S23 "From a long line of kings" - sentence fragment<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=FilterWML&diff=64960FilterWML2019-10-17T22:43:49Z<p>Josteph: /* Filtering Weapons */ Document #4424/#3915</p>
<hr />
<div>{{WML Tags}}<br />
== Filtering in WML ==<br />
<br />
A ''filter'' is a special WML block.<br />
Filters are used to describe a set of units, hexes, weapons or something else.<br />
Filters are defined as matching something if all the keys in the filter match that thing.<br />
For example, if a unit filter contains two keys,<br />
a unit must match both of the keys in order to match the filter.<br />
<br />
A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.<br />
<br />
== Filtering Units ==<br />
<br />
Filters are often used in action tags (see [[EventWML]]).<br />
In this case the phrase "standard unit filter" is used in place of the set of standard keys.<br />
Sometimes a filter is used to find the first unit that matches the filter;<br />
for example, the '''[recall]''' tag recalls that unit.<br />
<br />
Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.<br />
These are subtags of '''[event]''' which describe when the event should trigger.<br />
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".<br />
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',<br />
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.<br />
<br />
See [[StandardUnitFilter]] for details.<br />
<br />
== Filtering Locations ==<br />
<br />
As you have seen, standard unit filter can contain a location filter.<br />
Several actions, such as '''[terrain]''', also use location filters.<br />
Location filters are represented on this site by the phrase "standard location filter".<br />
A common use for location filters is to check the terrain of a space.<br />
<br />
See [[StandardLocationFilter]] for details.<br />
<br />
== Filtering Sides ==<br />
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.<br />
Side filters are represented on this site by the phrase "standard side filter".<br />
<br />
See [[StandardSideFilter]] for details.<br />
<br />
== Filtering Weapons ==<br />
<br />
Sometimes weapons/attacks are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].<br />
<br />
These keys are used as filter input for attack filters.<br />
<br />
* '''range''': a range to filter<br />
** '''melee''': only melee weapons pass <br />
** '''ranged''': only ranged weapons pass <br />
* '''name''': filter on the attack's name. See <code>data/units/</code> to find the name of a particular unit's attack.<br />
* '''type''': filter on the attack's type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.<br />
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'<br />
* '''special_id''': {{DevFeature1.15|2}} Filter on a weapon special by id, for example, <code>magical</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active.<br />
* '''special_type''': {{DevFeature1.15|2}} Filter on a weapon special by tag name for example, <code>chance_to_hit</code> in <code>[chance_to_hit] id=magical</code>. True if the unit has the special, whether or not it's currently active. For values see [[AbilitiesWML]].<br />
* '''special_id_active''': {{DevFeature1.15|2}} Like '''special_id''', but true if the special is active at the current location.<br />
* '''special_type_active''': {{DevFeature1.15|2}} Like '''special_type''', but true if the special is active at the current location.<br />
* '''special''': filter on the attack's special power, matches both id and tag name. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.<br />
* '''special_active''': {{DevFeature1.13|8}} Like '''special''', but true if the special is active at the current location. {{DevFeature1.15|2}} Deprecated, see '''special_id''' and '''special_type''' instead.<br />
* '''number''': {{DevFeature1.13|5}} filter on number of attacks<br />
* '''parry''': {{DevFeature1.13|5}} filter on parry value<br />
* '''accuracy''': {{DevFeature1.13|5}} filter on accuracy value<br />
* '''movement_used''': {{DevFeature1.13|5}} filter on attack's movement cost<br />
* '''formula''': {{DevFeature1.13|5}} filter using [[Wesnoth Formula Language]]<br />
<br />
'''[and]''', '''[or]''', and '''[not]''' subfilters are also supported.<br />
<br />
== Filtering Vision ==<br />
<br />
The '''[filter_vision]''' tag allows you to filter units or locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side, and (in the case of units) whether or not the unit is hidden (via the {{tag|AbilitiesWML|hides}} ability).<br />
<br />
* '''visible''':<br />
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''side'' and, when in a SUF, the unit is not hiding.<br />
** '''no''': matches when the location is obscured by fog or shroud for the ''side'' or, when in a SUF, the unit is hiding.<br />
* '''respect_fog''': yes or no, default yes. In a location filter (only), setting this to "no" will cause the test to ignore fog; it becomes a test for shrouded or not shrouded. <br />
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.<br />
** When no viewing sides are listed, all enemy sides must pass the visibility check.<br />
*'''[[StandardSideFilter]]''' tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. If there is *at least one* matching side which can see the unit / location (accounting for fog / hiding / shroud) then the filter matches, and otherwise it fails to match.<br />
<br />
'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's (side 1's) field of vision:<br />
[event]<br />
name=moveto<br />
first_time_only=yes<br />
[filter]<br />
side=2<br />
[filter_vision]<br />
side=1 <br />
[/filter_vision]<br />
[/filter]<br />
[message]<br />
speaker=unit<br />
message="I am your enemy. I know that you can see me here."<br />
[/message]<br />
[/event]<br />
<br />
'''Note:''' In a location filter, this tag is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.<br />
<br />
== Filtering on WML data ==<br />
<br />
Some places allow you to filter directly on WML data. WML filters are more free-form than other filters, allowing arbitrary WML data that is to be matched. The following conventions are possible:<br />
<br />
* '''key=value''': Means that the key '''key''' must be present with the specified value.<br />
* '''glob_on_key=glob''': {{DevFeature1.15|0}} Means that the key '''key''' must be present with a value that matches the specified glob. In addition to the obvious, this is useful for matching the absence of a key - just place '''glob_on_key=*''' in a '''[not]''' tag.<br />
* '''[some_tag]''': In a WML filter, all tags contain further WML filter data as children. The presence of a tag in the filter means that the WML must have at least one tag '''some_tag''' present, and at least one of the '''some_tag''' tags must match the WML filter contained in '''[some_tag]'''.<br />
* '''[not]''': The WML filter contained in '''[not]''' ''must not'' match the WML.<br />
* '''[and]''': {{DevFeature1.15|0}} In addition to the main filter, the filter contained in '''[and]''' must also match the WML. In most cases this tag is not necessary (the two filters can simply be merged), but in some unusual cases (particularly when globs are involved) it might be needed to get the desired result.<br />
* '''[or]''': {{DevFeature1.15|0}} Adds another filter that is allowed to match in place of the main filter. Note that when combining several WML filters with '''[or]''' tags, the first filter must not be wrapped in '''[or]''' tags - doing so would mean that the first filter is actually an empty filter, which matches everything, meaning the other '''[or]''' tags are irrelevant.<br />
<br />
== Tutorial ==<br />
* [http://wiki.wesnoth.org/FilterWML/Examples_-_How_to_use_Filter How To Use Filter (with examples)]<br />
<br />
== See Also ==<br />
<br />
* [[UnitTypeWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=PreprocessorRef&diff=64956PreprocessorRef2019-10-16T02:09:42Z<p>Josteph: /* Built-in macros */ PR #4414</p>
<hr />
<div>{{WML Tags}}<br />
== Overview ==<br />
<br />
Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.<br />
<br />
The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.<br />
<br />
The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).<br />
<br />
== Preprocessor directives ==<br />
<br />
The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.<br />
<br />
The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.<br />
<br />
'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.<br />
<br />
=== #define ===<br />
<br />
'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''<br />
<br />
All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define ENEMY_UNIT TYPE X Y<br />
## the ordering above is important, since the preprocessor does not distinguish<br />
## data into different types; only the ordering is used to determine which<br />
## arguments apply to which parameters.<br />
[unit]<br />
type={TYPE} ## the unit will be of type TYPE, so different<br />
## instantiations<br />
## of this macro can create different units.<br />
x={X}<br />
y={Y}<br />
side=2 ## the unit will be an enemy, regardless of the parameter<br />
## values. This reduces "repetition of information",<br />
## since it is no longer necessary to specify<br />
## each created unit as an enemy.<br />
[/unit]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
(See [[SingleUnitWML]] for further information on creating units using WML.)<br />
<br />
'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].<br />
<br />
=== #arg and #endarg ===<br />
<br />
{{DevFeature1.13|7}} <br />
<br />
Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.<br />
<br />
For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define MESSAGE TEXT<br />
<br />
#arg SPEAKER_ID<br />
narrator<br />
#endarg<br />
<br />
#arg CAPTION<br />
#endarg<br />
<br />
#arg SOUND<br />
#endarg<br />
<br />
#arg IMG<br />
#endarg<br />
<br />
[message]<br />
speaker={SPEAKER_ID}<br />
message={TEXT}<br />
caption={CAPTION}<br />
sound={SOUND}<br />
image={IMG}<br />
[/message]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
The caller of the macro can then decide which, if any, of the default values to override:<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}<br />
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}<br />
{MESSAGE _"..."}<br />
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}<br />
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}<br />
</syntaxhighlight><br />
<br />
Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.<br />
<br />
=== #undef ===<br />
<br />
'''Syntax:''' '''#undef ''symbol'' '''<br />
<br />
Removes the previous definition of the macro named ''symbol''.<br />
<br />
=== Inclusion directive {} ===<br />
<br />
This directive can be used to include macros, single files or sets of files from a target directory.<br />
<br />
==== File/directory inclusions ====<br />
<br />
'''Syntax: {''path''}'''<br />
<br />
Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.<br />
<br />
The exact location in which the ''path'' will be resolved will depend on its prefix:<br />
<br />
* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.<br />
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.<br />
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.<br />
<br />
Information for locating the user data and game data directories can be found in [[EditingWesnoth]].<br />
<br />
Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.<br />
<br />
When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.<br />
<br />
Some directories are handled in a special fashion according to their contents:<br />
<br />
* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.<br />
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:<br />
dir/<br />
dir/a/_main.cfg<br />
dir/a/other.cfg<br />
dir/b/_main.cfg<br />
dir/b/other.cfg<br />
dir/other.cfg<br />
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.<br />
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.<br />
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.<br />
<br />
==== Macro inclusions ====<br />
<br />
'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''<br />
<br />
If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.<br />
<br />
You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.<br />
<br />
Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct<br />
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong<br />
</syntaxhighlight><br />
<br />
This way even complex arguments can be passed:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MODIFY_UNIT (<br />
[filter_adjacent]<br />
canrecruit=yes<br />
[/filter_adjacent]<br />
) side 2}<br />
</syntaxhighlight><br />
<br />
Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define VARIABLE<br />
#enddef<br />
#define MACRO VARIABLE<br />
{VARIABLE} # is calling for the argument, not for the macro above<br />
#enddef<br />
</syntaxhighlight><br />
<br />
=== #ifdef and #ifndef ===<br />
<br />
Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).<br />
<br />
'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''<br />
<br />
If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.<br />
<br />
'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:<br />
<br />
'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''<br />
<br />
=== #ifhave and #ifnhave ===<br />
<br />
'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''<br />
<br />
Checks for the existence of a file. Uses the same relative paths as include directives (see below).<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="wml"><br />
#ifhave ~add-ons/My_Addon/_main.cfg<br />
{MY_ADDON_MACROS}<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnhave''' does the opposite of '''#ifhave''':<br />
<br />
'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''<br />
<br />
=== #ifver and #ifnver ===<br />
<br />
'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''<br />
<br />
Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.<br />
<br />
Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION >= 1.9.7+<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"<br />
[/message]<br />
#else<br />
#ifver WESNOTH_VERSION == 1.9.7<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"<br />
[/message]<br />
#endif<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnver''' does the opposite of '''#ifver''':<br />
<br />
'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''<br />
<br />
=== #error ===<br />
<br />
'''Syntax:''' '''#error [''message'']'''<br />
<br />
Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.<br />
<br />
Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#error This add-on does not support Wesnoth 1.11.10!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #warning ===<br />
<br />
'''Syntax:''' '''#warning [''message'']'''<br />
<br />
Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #deprecated ===<br />
<br />
{{DevFeature1.13|11}}<br />
<br />
'''Syntax:''' '''#deprecated ''level'' [''version''] ''message'''''<br />
<br />
The effect of this directive depends on whether it appears within a macro definition.<br />
<br />
* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.<br />
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.<br />
<br />
Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)<br />
<br />
The ''version'' argument is technically not optional. If you provide a deprecation ''level'' of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation ''level'' of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.<br />
<br />
== Built-in macros ==<br />
<br />
The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.<br />
<br />
* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.<br />
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.<br />
* '''MULTIPLAYER''': defined when in multiplayer mode.<br />
* '''TUTORIAL''': defined when playing the tutorial campaign.<br />
* '''EDITOR''': defined when running the built-in map editor.<br />
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).<br />
* '''APPLE''': defined while processing the main game data when running on Mac OS X.<br />
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.<br />
* '''CURRENT_FILE''': Expands to the name of the current WML file.<br />
* '''CURRENT_DIRECTORY''': Expands to the name of the directory of {CURRENT_FILE}, I assume?<br />
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.<br />
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.<br />
<br />
Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html<br />
<br />
== Command-line preprocessor ==<br />
<br />
'''Syntax: --preprocess ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
Or the short form:<br />
<br />
'''Syntax: -p ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
You can specify a list of predefined defines with:<br />
<br />
'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''<br />
<br />
comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.<br />
<br />
The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.<br />
<br />
The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.<br />
<br />
If by chance, the simple macro define doesn't suffice, you can use:<br />
<br />
'''Syntax: --preprocess-input-macros <file>'''<br />
<br />
To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.<br />
<br />
There is also the possibility to export the preprocessed defines/macro list with:<br />
<br />
'''Syntax: --preprocess-output-macros [<target file>]'''<br />
<br />
This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.<br />
<br />
If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.<br />
<br />
Some examples:<br />
<br />
* Preprocess the entire tutorial dir, and write the results in the ~/result folder:<br />
-p ~/wesnoth/data/campaigns/tutorial ~/result<br />
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER<br />
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD<br />
<br />
If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.<br />
<br />
== See Also ==<br />
<br />
* [[SyntaxWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=64713DirectActionsWML2019-10-10T03:24:58Z<p>Josteph: /* [modify_unit] */ spelling</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br />
<br />
The following tags are actions:<br />
<br />
=== [endlevel] ===<br />
Ends the scenario.<br />
* '''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. <br />
<br />
When the result is "victory" the following keys can be used:<br />
* '''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).<br />
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.<br />
* '''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''.<br />
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
* '''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.<br />
* '''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.<br />
* '''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]].<br />
* '''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]].<br />
* '''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]].<br />
* <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.<br />
* <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.<br />
* '''[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]''':<br />
** '''result'''<br />
** '''bonus'''<br />
** '''carryover_percentage'''<br />
** '''carryover_add'''<br />
<br />
And there is also<br />
** '''side''' The number of the side for which these results should apply.<br />
<br />
=== [unit] ===<br />
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].<br />
* {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
<br />
This tag can also recall an existing unit, which happens when:<br />
* the '''id=''' attribute is used<br />
* a unit with that '''id=''' already exists<br />
* (might be unnecessary) the existing unit is on the side's recall list<br />
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.<br />
<br />
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.<br />
For example,<br />
[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].<br />
<br />
=== [recall] ===<br />
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.<br />
<br />
If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.<br />
<br />
* [[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).<br />
* '''x,y''': the unit is placed here instead of next to the leader.<br />
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br />
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.<br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).<br />
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.<br />
<br />
=== [teleport] ===<br />
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br />
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.<br />
* '''clear_shroud''': should shroud be cleared on arrival<br />
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''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.<br />
<br />
(Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br />
<br />
=== [terrain_mask] ===<br />
Changes the terrain on the map. See [[TerrainMaskWML]].<br />
<br />
=== [terrain] ===<br />
Changes the terrain on the map.<br />
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
* [[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.<br />
* '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
* '''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.<br />
<br />
If you want to remove the overlays from a terrain and leave only the base, use:<br />
layer=overlay<br />
terrain="^"<br />
<br />
<b>Note:</b> 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.<br />
<br />
=== [gold] ===<br />
Gives sides gold.<br />
* '''amount''': the amount of gold to give.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [unstore_unit] ===<br />
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].<br />
* '''variable''': the name of the variable.<br />
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. <br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".<br />
* '''text''': (translatable) floating text to display above the unit, such as a damage amount<br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br />
* '''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.<br />
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.<br />
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.<br />
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.<br />
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&ndash;and killed&ndash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.<br />
<br />
=== [allow_recruit] ===<br />
Allows a side to recruit units it couldn't previously recruit.<br />
* '''type''': the types of units that the side can now recruit.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [allow_extra_recruit] ===<br />
Allows a leader to recruit units it couldn't previously recruit.<br />
These types add to the types the leader can recruit because of [side]recruit=.<br />
* '''extra_recruit''': the types of units that the unit can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [disallow_recruit] ===<br />
Prevents a side from recruiting units it could previously recruit.<br />
* '''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.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [disallow_extra_recruit] ===<br />
Prevents a leader from recruiting units it could previously recruit.<br />
* '''extra_recruit''': the types of units that the side can no longer recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [set_recruit] ===<br />
Sets the units a side can recruit.<br />
* '''recruit''': the types of units that the side can now recruit.<br />
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [set_extra_recruit] === <br />
Sets the units a leader can recruit.<br />
* '''extra_recruit''': the types of units that the leader can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [modify_side] ===<br />
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!'''<br />
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* '''income''': the income given at the begining of each turn.<br />
* '''recruit''': a list of unit types, replacing the side's current recruitment list.<br />
* '''team_name''': the team in which the side plays the scenario.<br />
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.<br />
* '''gold''': the amount of gold the side owns.<br />
* '''village_gold''': the income setting per village for the side.<br />
* '''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].<br />
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
* '''shroud''': a boolean string describing the status of Shroud for the side.<br />
* '''hidden''': a boolean string specifying whether side is shown in status table.<br />
* '''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.<br />
* '''[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 [http://wiki.wesnoth.org/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.<br />
* '''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.<br />
* '''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=).<br />
* '''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=.<br />
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br />
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br />
* '''share_vision''': change both the above at the same time<br />
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].<br />
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.<br />
* '''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.<br />
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).<br />
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).<br />
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.<br />
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).<br />
<br />
=== [modify_turns] ===<br />
Modifies the turn limit in the middle of a scenario.<br />
* '''value''': the new turn limit.<br />
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
* '''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).<br />
<br />
=== [allow_end_turn] ===<br />
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.<br />
<br />
=== [disallow_end_turn] ===<br />
Disallows human players to end their turn through the user interface. This action doesn't require arguments.<br />
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.<br />
<br />
=== [capture_village] ===<br />
Changes the ownership of a village.<br />
* [[StandardLocationFilter]]: all village locations matching the filter are affected.<br />
* '''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).<br />
* '''[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).<br />
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.<br />
<br />
=== [kill] ===<br />
Removes all units (including units in a recall list) that match the filter from the game.<br />
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br />
* '''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.<br />
* '''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).<br />
* '''[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).<br />
* '''[primary_attack]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.<br />
<br />
=== [move_unit] ===<br />
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.<br />
* [[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.<br />
* '''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.<br />
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br />
* '''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'''.<br />
* '''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'''.<br />
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br />
* '''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.)<br />
* '''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.<br />
<br />
=== [modify_ai] ===<br />
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.<br />
<br />
* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.<br />
* '''path''' (string): Describes which AI object is to be modified. <br />
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [modify_unit] ===<br />
works similar to the MODIFY_UNIT macro.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br />
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.<br />
** '''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.<br />
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.<br />
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.<br />
* 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.<br />
example usage (see also the test scenario):<br />
<syntaxhighlight lang='wml'><br />
[modify_unit]<br />
[filter]<br />
x,y=38,6<br />
[/filter]<br />
hitpoints=10<br />
{TRAIT_HEALTHY}<br />
[/modify_unit]<br />
</syntaxhighlight><br />
<br />
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).<br />
<br />
'''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]:<br />
* '''side'''<br />
* '''gender'''<br />
* '''name'''<br />
* '''canrecruit'''<br />
* '''unrenamable'''<br />
* '''extra_recruit'''<br />
* '''[variables]'''<br />
* '''facing'''<br />
* '''goto_x, goto_y'''<br />
* '''hitpoints'''<br />
* '''experience'''<br />
* '''moves'''<br />
* '''[status]''' (not sure on this one)<br />
* '''attacks_left'''<br />
* '''role'''<br />
<br />
=== [transform_unit] ===<br />
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.<br />
* [[StandardUnitFilter]]: do not use a [filter] tag.<br />
* '''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.<br />
<br />
=== [petrify] ===<br />
<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br />
<br />
=== [unpetrify] ===<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.<br />
<br />
=== [object] ===<br />
Gives some unit an object which modifies their stats in some way.<br />
* '''id''': (Optional) allows the item to be removed later. 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.<br />
* '''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.<br />
* '''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.<br />
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
* '''duration''':<br />
**if 'scenario', effects only last until the end of the scenario.<br />
**if 'forever' or not set, effects never wear off.<br />
** 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.)<br />
** {{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).<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). 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]'''.<br />
* '''[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.<br />
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.<br />
* '''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.<br />
* '''image''': the displayed image of the object.<br />
* '''name''': (translatable) displayed as a caption of the image.<br />
<br />
* '''description''': (translatable) displayed as a message of the image.<br />
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
<br />
=== [remove_object] ===<br />
<br />
{{DevFeature1.13|6}}<br />
<br />
Removes an object from matching units.<br />
<br />
* [[StandardUnitFilter]]: All units matching the filter have matching objects removed. Use no [filter] tag.<br />
* '''object_id''': The id of the object to be removed.<br />
<br />
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.<br />
<br />
Note that remove_object worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 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 [modify_unit] to get a list of properties that can safely be changes via [modify_unit]<br />
<br />
=== [remove_shroud] ===<br />
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br />
<br />
=== [place_shroud] ===<br />
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br />
<br />
=== [lift_fog] ===<br />
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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.<br />
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).<br />
<br />
=== [reset_fog] ===<br />
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.)<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.<br />
* '''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}}.<br />
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].<br />
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).<br />
<br />
=== [allow_undo] ===<br />
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 &mdash; specifically when handling a menu item, where there is no current action &mdash; and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.<br />
* 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.<br />
<br />
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.<br />
* 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.<br />
* 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).<br />
<br />
If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.<br />
<br />
Due to a bug in 1.12 (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: <br />
* [message] with [option]s<br />
* [get_global_variable]<br />
* wesnoth.synchronize_choice<br />
<br />
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:<br />
<br />
[event]<br />
name="moveto"<br />
[message]<br />
message = "message"<br />
[option]<br />
label = "option 1"<br />
[command]<br />
[/command]<br />
[/option]<br />
[option]<br />
label = "option 2"<br />
[command]<br />
[/command]<br />
[/option]<br />
[/message]<br />
[allow_undo]<br />
[/allow_undo]<br />
[/event]<br />
<br />
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.<br />
<br />
=== [on_undo] ===<br />
{{DevFeature1.13|2}}<br />
Contains commands to execute when the player undoes the action which triggered the parent event.<br />
*'''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.)<br />
<br />
Note:<br />
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<br />
[event]<br />
name="undo_blah"<br />
first_time_only=no<br />
[store_unit]<br />
id="$moved_unit_id"<br />
[/store_unit]<br />
... do undo stuff stuff<br />
[/event]<br />
<br />
...<br />
... in some other event<br />
[on_undo]<br />
# store ''upvalues<br />
{VARIABLE moved_unit_id $unit.id}<br />
# call actual undo handler<br />
[fire_event]<br />
name = "undo_blah"<br />
[/fire_event]<br />
[on_undo]<br />
<br />
=== [on_redo] ===<br />
{{DevFeature1.13|2}}<br />
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.<br />
<br />
{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.<br />
<br />
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.<br />
<br />
=== [cancel_action] ===<br />
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.<br />
<br />
{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).<br />
<br />
{{DevFeature1.13|11}}<br />
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_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] on (3,3) would let the player choose whether to attack.<br />
<br />
=== [heal_unit] ===<br />
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.<br />
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.<br />
* '''[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.<br />
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.<br />
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br />
* '''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.<br />
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br />
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".<br />
<br />
=== [harm_unit] ===<br />
Harms every unit matching the filter, for the specific damage amount.<br />
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br />
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.<br />
* '''amount''': the amount of damage that will be done (required).<br />
* '''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.<br />
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''[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]].<br />
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br />
* '''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.<br />
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br />
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.<br />
* '''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.<br />
<br />
=== [time_area] ===<br />
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.<br />
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br />
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].<br />
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br />
* '''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.<br />
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.<br />
<br />
''Example:'' (caves in parts of a map)<br />
[time_area]<br />
x=1-2,4-5<br />
y=1-2,1-2<br />
{UNDERGROUND}<br />
[/time_area]<br />
<br />
=== [remove_time_area] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This is a syntactic shortcut for [time_area] remove=.<br />
* '''id''': Comma-separated list of time area ids to remove.<br />
<br />
=== [end_turn] ===<br />
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).<br />
<br />
=== [replace_map] ===<br />
<br />
Replaces the entire map.<br />
* '''map''': Content of a wesnoth map file. example:<br />
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"<br />
* '''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.<br />
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br />
* '''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.<br />
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.<br />
<br />
=== [replace_schedule] ===<br />
Replace the time of day schedule of the entire scenario.<br />
* [[TimeWML]]: the new schedule.<br />
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.<br />
<br />
=== [tunnel] ===<br />
<br />
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).<br />
<br />
'''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.<br />
<br />
* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".<br />
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).<br />
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).<br />
* '''id''': (optional) identifier for the tunnel, to allow removing.<br />
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).<br />
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction. <br />
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.<br />
* '''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).<br />
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.<br />
* '''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]]<br />
<br />
(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br />
<br />
=== [do_command] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted<br />
<br />
* [attack]<br />
* [move]<br />
* [recruit]<br />
* [recall]<br />
* [disband]<br />
* [fire_event]<br />
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]<br />
<br />
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.<br />
<br />
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.<br />
<br />
This command should always be replay safe.<br />
<br />
=== [put_to_recall_list] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Puts a unit to the recall list of its side.<br />
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.<br />
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.<br />
<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64704ReleasingWesnoth2019-10-08T19:40:45Z<p>Josteph: /* Notify packagers */</p>
<hr />
<div>== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
** For 1.15.3, review the [https://github.com/wesnoth/wesnoth/milestone/20 pre-1.16.0 string freeze] issues<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
'''TODO:''' Upload not just the sha256 files but also the actual files, as a backup in case sf.net is down etc<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64691ReleasingWesnoth2019-10-06T20:04:25Z<p>Josteph: /* Version numbering */</p>
<hr />
<div>== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
During the beta/RC/stable stages, no API changes (e.g., Lua/WML interfaces or semantics) should be made , nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64690ReleasingWesnoth2019-10-06T20:03:59Z<p>Josteph: /* Version numbering */</p>
<hr />
<div>== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
No API changes (e.g., Lua/WML interfaces or semantics) should be made during the beta/RC/stable stage, nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64689ReleasingWesnoth2019-10-06T20:00:05Z<p>Josteph: /* Version numbering */ build deps</p>
<hr />
<div>== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
No API changes (e.g., Lua/WML interfaces or semantics) should be made after the beta stage, nor large-scale or destabilizing internal changes, nor build dependencies changed. That's true from "1.15.x (1.16 beta 1)" and for the rest of the 1.16.x releases too. Such changes should be made in 1.17.x for 1.18.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64688ReleasingWesnoth2019-10-06T19:58:03Z<p>Josteph: New section "Version numbering"</p>
<hr />
<div>== Version numbering ==<br />
<br />
We use the even/odd minor number convention. A.B.C where B is even means stable and B is odd means unstable/development version.<br />
<br />
1.15.x are development versions for 1.16.0.<br />
<br />
A development version should be called "beta 1" when no further API changes are expected, nor string changes. At that point, translators and add-on authors can start working on 1.15.x without worrying that the rug be swept under their feet.<br />
<br />
A development version should be called "release candidate 1" when all blockers have been fixed.<br />
<br />
No API changes (e.g., Lua/WML interfaces or semantics) should be made after the beta stage, nor large-scale or destabilizing internal changes.<br />
<br />
== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=PreprocessorRef&diff=64663PreprocessorRef2019-10-05T00:59:32Z<p>Josteph: /* Built-in macros */ add CURRENT_FILE and CURRENT_DIRECTORY</p>
<hr />
<div>{{WML Tags}}<br />
== Overview ==<br />
<br />
Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.<br />
<br />
The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.<br />
<br />
The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).<br />
<br />
== Preprocessor directives ==<br />
<br />
The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.<br />
<br />
The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.<br />
<br />
'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.<br />
<br />
=== #define ===<br />
<br />
'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''<br />
<br />
All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define ENEMY_UNIT TYPE X Y<br />
## the ordering above is important, since the preprocessor does not distinguish<br />
## data into different types; only the ordering is used to determine which<br />
## arguments apply to which parameters.<br />
[unit]<br />
type={TYPE} ## the unit will be of type TYPE, so different<br />
## instantiations<br />
## of this macro can create different units.<br />
x={X}<br />
y={Y}<br />
side=2 ## the unit will be an enemy, regardless of the parameter<br />
## values. This reduces "repetition of information",<br />
## since it is no longer necessary to specify<br />
## each created unit as an enemy.<br />
[/unit]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
(See [[SingleUnitWML]] for further information on creating units using WML.)<br />
<br />
'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].<br />
<br />
=== #arg and #endarg ===<br />
<br />
{{DevFeature1.13|7}} <br />
<br />
Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.<br />
<br />
For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define MESSAGE TEXT<br />
<br />
#arg SPEAKER_ID<br />
narrator<br />
#endarg<br />
<br />
#arg CAPTION<br />
#endarg<br />
<br />
#arg SOUND<br />
#endarg<br />
<br />
#arg IMG<br />
#endarg<br />
<br />
[message]<br />
speaker={SPEAKER_ID}<br />
message={TEXT}<br />
caption={CAPTION}<br />
sound={SOUND}<br />
image={IMG}<br />
[/message]<br />
#enddef<br />
</syntaxhighlight><br />
<br />
The caller of the macro can then decide which, if any, of the default values to override:<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}<br />
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}<br />
{MESSAGE _"..."}<br />
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}<br />
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}<br />
</syntaxhighlight><br />
<br />
Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.<br />
<br />
=== #undef ===<br />
<br />
'''Syntax:''' '''#undef ''symbol'' '''<br />
<br />
Removes the previous definition of the macro named ''symbol''.<br />
<br />
=== Inclusion directive {} ===<br />
<br />
This directive can be used to include macros, single files or sets of files from a target directory.<br />
<br />
==== File/directory inclusions ====<br />
<br />
'''Syntax: {''path''}'''<br />
<br />
Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.<br />
<br />
The exact location in which the ''path'' will be resolved will depend on its prefix:<br />
<br />
* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.<br />
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.<br />
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.<br />
<br />
Information for locating the user data and game data directories can be found in [[EditingWesnoth]].<br />
<br />
Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.<br />
<br />
When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.<br />
<br />
Some directories are handled in a special fashion according to their contents:<br />
<br />
* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.<br />
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:<br />
dir/<br />
dir/a/_main.cfg<br />
dir/a/other.cfg<br />
dir/b/_main.cfg<br />
dir/b/other.cfg<br />
dir/other.cfg<br />
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.<br />
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.<br />
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.<br />
<br />
==== Macro inclusions ====<br />
<br />
'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''<br />
<br />
If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.<br />
<br />
You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.<br />
<br />
Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct<br />
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong<br />
</syntaxhighlight><br />
<br />
This way even complex arguments can be passed:<br />
<br />
<syntaxhighlight lang="wml"><br />
{MODIFY_UNIT (<br />
[filter_adjacent]<br />
canrecruit=yes<br />
[/filter_adjacent]<br />
) side 2}<br />
</syntaxhighlight><br />
<br />
Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:<br />
<br />
<syntaxhighlight lang="wml"><br />
#define VARIABLE<br />
#enddef<br />
#define MACRO VARIABLE<br />
{VARIABLE} # is calling for the argument, not for the macro above<br />
#enddef<br />
</syntaxhighlight><br />
<br />
=== #ifdef and #ifndef ===<br />
<br />
Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).<br />
<br />
'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''<br />
<br />
If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.<br />
<br />
'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:<br />
<br />
'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''<br />
<br />
=== #ifhave and #ifnhave ===<br />
<br />
'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''<br />
<br />
Checks for the existence of a file. Uses the same relative paths as include directives (see below).<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="wml"><br />
#ifhave ~add-ons/My_Addon/_main.cfg<br />
{MY_ADDON_MACROS}<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnhave''' does the opposite of '''#ifhave''':<br />
<br />
'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''<br />
<br />
=== #ifver and #ifnver ===<br />
<br />
'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''<br />
<br />
Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.<br />
<br />
Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION >= 1.9.7+<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"<br />
[/message]<br />
#else<br />
#ifver WESNOTH_VERSION == 1.9.7<br />
[message]<br />
speaker=narrator<br />
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"<br />
[/message]<br />
#endif<br />
#endif<br />
</syntaxhighlight><br />
<br />
'''#ifnver''' does the opposite of '''#ifver''':<br />
<br />
'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''<br />
<br />
=== #error ===<br />
<br />
'''Syntax:''' '''#error [''message'']'''<br />
<br />
Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.<br />
<br />
Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#error This add-on does not support Wesnoth 1.11.10!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #warning ===<br />
<br />
'''Syntax:''' '''#warning [''message'']'''<br />
<br />
Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.<br />
<br />
Example:<br />
<syntaxhighlight lang="wml"><br />
#ifver WESNOTH_VERSION < 1.11.10<br />
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!<br />
#endif<br />
</syntaxhighlight><br />
<br />
=== #deprecated ===<br />
<br />
{{DevFeature1.13|11}}<br />
<br />
'''Syntax:''' '''#deprecated ''level'' [''version''] ''message'''''<br />
<br />
The effect of this directive depends on whether it appears within a macro definition.<br />
<br />
* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.<br />
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.<br />
<br />
Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)<br />
<br />
The ''version'' argument is technically not optional. If you provide a deprecation ''level'' of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation ''level'' of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.<br />
<br />
== Built-in macros ==<br />
<br />
The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.<br />
<br />
* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.<br />
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.<br />
* '''MULTIPLAYER''': defined when in multiplayer mode.<br />
* '''TUTORIAL''': defined when playing the tutorial campaign.<br />
* '''EDITOR''': defined when running the built-in map editor.<br />
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).<br />
* '''APPLE''': defined while processing the main game data when running on Mac OS X.<br />
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.<br />
* '''CURRENT_FILE''': Expands to the name of the current WML file.<br />
* '''CURRENT_DIRECTORY''': Expands to the name of the directory of {CURRENT_FILE}, I assume?<br />
<br />
Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html<br />
<br />
== Command-line preprocessor ==<br />
<br />
'''Syntax: --preprocess ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
Or the short form:<br />
<br />
'''Syntax: -p ''&lt;source file/directory>'' ''<target directory>'' '''<br />
<br />
You can specify a list of predefined defines with:<br />
<br />
'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''<br />
<br />
comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.<br />
<br />
The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.<br />
<br />
The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.<br />
<br />
If by chance, the simple macro define doesn't suffice, you can use:<br />
<br />
'''Syntax: --preprocess-input-macros <file>'''<br />
<br />
To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.<br />
<br />
There is also the possibility to export the preprocessed defines/macro list with:<br />
<br />
'''Syntax: --preprocess-output-macros [<target file>]'''<br />
<br />
This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.<br />
<br />
If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.<br />
<br />
Some examples:<br />
<br />
* Preprocess the entire tutorial dir, and write the results in the ~/result folder:<br />
-p ~/wesnoth/data/campaigns/tutorial ~/result<br />
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER<br />
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:<br />
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD<br />
<br />
If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.<br />
<br />
== See Also ==<br />
<br />
* [[SyntaxWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SingleUnitWML&diff=64649SingleUnitWML2019-10-04T17:36:47Z<p>Josteph: /* Unit Data */ Add 'hidden'</p>
<hr />
<div>{{WML Tags}}<br />
The '''[unit]''' tag describes a single unit on the map or in memory, for example Konrad.<br />
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].<br />
<br />
[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)<br />
<br />
This contains keys and tags which describe the unit's [[#Unit Data|persistent data]], as well as certain [[#Unit State|state variables]] which will also persist with the unit but will change frequently as gameplay progresses. Finally, there are some keys to set certain [[#Creation Options|one-time options]] for how the unit will be initially created, which will ''not'' persist beyond initial creation.<br />
<br />
== Unit Data ==<br />
The following keys and tags describe the unit itself, and will persist with the unit (though some may change automatically when the unit advances):<br />
* <span id="type">'''type'''</span>: the ID of the unit's unit type. This key is mandatory. See [[UnitTypeWML]].<br />
<br />
* '''variation''': the [variation] of the [unit_type] as which the unit will appear.<br />
<br />
* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).<br />
<br />
* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Defaults to 1, except when the [unit] tag appears inside a [side], in which case the unit always belongs to that side, and this key is ignored.<br />
<br />
* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified, a random one will be generated for the unit to ensure that each unit has a unique '''id''' attribute (as will happen when a unit is recruited normally). In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.) Note: While it IS technically possible to create multiple units with the same ID, doing so may produce unpredictable results in many cases. WML should therefore be structured in such a way that no two units in existence ever end up with the same ID.<br />
<br />
* '''gender''': can be set to male or female to designate the gender of the unit. Default is male (unless [[#random_gender|'''random_gender''']] is set to "yes"), but if the unit has only a female variant it will be female.<br />
<br />
* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).<br />
<br />
* <span id="unrenamable">'''unrenamable'''</span>: if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).<br />
<br />
* '''canrecruit''': a special key for leaders.<br />
** '''no''': default. Unit cannot recruit.<br />
** '''yes''': unit can recruit.<br />
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.<br />
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.<br />
<br />
* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit= (only relevant for units with '''canrecruit=yes''').<br />
<br />
* '''[filter_recall]''' A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)<br />
**'''[[StandardUnitFilter]]''' tags and keys<br />
<br />
* '''level''': the unit's current level. Defaults to the level of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.<br />
<br />
* '''upkeep''': the amount of upkeep the unit will require each turn.<br />
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])<br />
** '''free''': synonymous with "loyal".<br />
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).<br />
** An integer can be used to set the upkeep cost to that number.<br />
** The default is "full".<br />
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.<br />
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.<br />
<br />
* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.<br />
<br />
* '''overlays''': a comma-separated list of images that are overlayed on the unit.<br />
** {{DevFeature1.15|0}} This key is supported when creating a unit from WML, but will be empty when writing the unit back to WML; the overlays will instead be stored as [modifications].<br />
<br />
* <span id="max_hitpoints">'''max_hitpoints'''</span>: The maximum hitpoints the unit has when at full health. Default is the max HP set for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* '''max_experience''': The experience the unit needs to advance. Default is the experience required for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* <span id="max_moves">'''max_moves'''</span>: The maximum number of movement points the unit has. Default is the number of movement specified for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* '''vision''': The the number of vision points to calculate the unit's sight range. Default is the number of vision points specified for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* '''jamming''': {{DevFeature1.15|0}} The number of jamming points for the unit. Default is the number of jamming points specified for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* <span id="max_attacks">'''max_attacks'''</span>: The number of attacks the unit can have per turn. Default is the number of attacks specified for the [unit_type] described by [[#type|'''type''']].<br />
<br />
* '''profile''': sets a portrait image for this unit. Default is the portrait image set for the [unit_type] described by [[#type|'''type''']]. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.<br />
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).<br />
<br />
* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.<br />
<br />
* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).<br />
<br />
* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]). The subnode '''mods''' is special as it is deleted on every unit rebuild (for example when the unit advances or when an [object] is removed). This makes it possible to implement [effect]s that change variables, as those will also be reapplied whenever the unit is reset. (so in particular if your effect changes the variables mods.<whatever> [remove_object] will work properly for those objects.) For example the following code will define a apply_to=moves_on_recruits effect that gives units with that effect full movement when recruited<br />
<br />
<syntaxhighlight lang='lua'><br />
function wesnoth.effects.move_on_recruit(u, cfg)<br />
-- maybe better use a status than a variable ?<br />
u.variables["mods.move_on_recruit"] = true<br />
end<br />
on_event("recruit,recall", function(ec)<br />
local unit = wesnoth.get_unit(ec.x1, ec.y1)<br />
if unit and unit.variables["mods.move_on_recruit"] then<br />
unit.attacks_left = 1<br />
unit.moves = unit.max_moves<br />
end<br />
end)<br />
</syntaxhighlight><br />
And since we used the mods subtable, [remove_object] will work properly for objects that give this effect.<br />
<br />
* '''[modifications]''' changes that have been made to the unit.<br />
** '''[trait]''' a trait the unit has. Same format as [[UnitsWML#.5Btrait.5D|[trait], UnitsWML]].<br />
** '''[object]''' an object the unit has. Same format as [[DirectActionsWML#.5Bobject.5D|[object], DirectActionsWML]].<br />
** '''[advance]''' an advancement that has already been applied to the unit. Same format as [[UnitTypeWML#After max level advancement (AMLA)|AMLA [advancement], UnitTypeWML]]. These are automatically added as the unit has AMLA advancements applied to it, but can also be specified manually to indicate that the unit already has a particular advancement applied, or to disable certain advancements (by ID). {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.<br />
<br />
* '''[event]''' The event is copied from this unit's WML description into the scenario. The event is carried along with the unit (even during advancement) and inserted into a scenario whenever this unit is first included. A [unit][event] requires a non-empty id= attribute.<br />
<br />
* '''unit_description''': overrides the unit type description for this unit. Note that this will be reset when the unit advances. To avoid this, one can either set up a ''post_advance'' [[EventWML|event]] to override the default description after promotion, or use an [object] with a profile [[EffectWML|effect]] to change the unit description.<br />
<br />
* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).<br />
<br />
* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).<br />
<br />
* '''ai_special''': causes the unit to act differently<br />
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.<br />
<br />
* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).<br />
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side<br />
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details<br />
<br />
* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.<br />
<br />
*'''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is the alignment of the [unit_type] described by [[#type|'''type''']]. This is generally not set manually.<br />
<br />
*'''advances_to''': comma-separated list of unit types to which this unit can advance. Will override the default provided by the [unit_type]. This is generally not set manually.<br />
<br />
*'''race''': See {{tag|UnitsWML|race}}. Will override the default provided by the [unit_type]. This is generally not set manually.<br />
<br />
*'''undead_variation''': Will override the default provided by the [unit_type]. This is generally not set manually.<br />
<br />
*'''usage''': Will override the default provided by the [unit_type]. This is generally not set manually.<br />
<br />
*'''zoc''': whether the unit has a zone of control. Will override the default provided by the [unit_type]. This is generally not set manually.<br />
<br />
*'''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''': Can be used to modify [[UnitsWML#.5Bmovetype.5D|existing values]].<br />
<br />
*'''[attack]''': Takes the same syntax as [[UnitTypeWML#Attacks|[unit_type][attack]]]. By default, the attacks from the [unit_type] will be included. '''Note:''' using this tag will replace ''all'' [attack] tags with the new one.<br />
<br />
*'''hidden''': Implementation detail of [[InterfaceActionsWML#%5Bhide_unit%5D|[hide_unit]]].<br />
<br />
== Unit State ==<br />
The following keys and tags describe the current state of the unit, and will change regularly as gameplay progresses:<br />
* '''x''', '''y''': the location of the unit. By default (unless modified by [[#placement|'''placement''']] below) if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list. The recall list can also be explicitly specified as the location with "recall,recall".<br />
<br />
* '''location_id''': {{DevFeature1.13|8}} the location of the unit, referencing one of the special locations defined by the map. This overrides '''x''' and '''y''' if present but otherwise has the same effect and can be modified by the placement options.<br />
<br />
* '''facing''': which way the unit is facing (this only affects how the unit is displayed).<br />
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Note that some unit types may not have distinct animations for each direction.<br />
<br />
* '''goto_x''':, '''goto_y''': the unit's current movement destination. Default is 0,0 i.e. the unit is not on a course.<br />
<br />
* '''hitpoints''': the HP of the unit. Default [[#max_hitpoints|'''max_hitpoints''']].<br />
<br />
* '''experience''': the XP of the unit. Default is 0.<br />
<br />
* '''moves''': number of movement points the unit has left. Default is [[#max_moves|'''max_moves''']].<br />
: '''Note:''' Do not assume that moves=max_moves on turns when the unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.<br />
<br />
* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give the unit rest healing. Note that this can be true even if moves is not equal to max_moves.<br />
<br />
* '''attacks_left''': number of attacks the unit has left. Default is '''max_attacks'''.<br />
<br />
* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.<br />
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].<br />
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, '''slowed''' is set to 'no'. <br />
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.<br />
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.<br />
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''ai_special = "guardian"'''.<br />
** '''unhealable''': if set to 'yes', the unit cannot be healed.<br />
** {{DevFeature1.13|6}} '''invulnerable''': if 'yes', attacks can't hit the unit.<br />
** One can add other keys to [status], but they must have boolean values, and they will not do anything meaningful on their own (but can be checked from events and acted upon accordingly). For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.<br />
<br />
* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.<br />
<br />
== Creation Options ==<br />
In addition to the unit's persistent data itself, there are several options for controlling how the unit will be created, as follows:<br />
* <span id="placement">'''placement'''</span>: How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.<br />
** '''map''': If x,y (or location_id) are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y (or location_id) are given and a valid on-map vacant location near it can be found.<br />
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.<br />
** '''recall''': Place unit on recall list. Always successful. <br />
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events. {{DevFeature1.13|8}} Deprecated, use placement=map and overwrite=yes instead.<br />
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex. {{DevFeature1.13|8}} Deprecated, use placement=map and passable=yes instead.<br />
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed. {{DevFeature1.13|8}} Deprecated, use placement=leader and passable=yes instead.<br />
* '''passable''': {{DevFeature1.13|8}} (default=no) If yes, and the specified location is of an impassable terrain for the unit being placed, the new unit will be placed in the nearest hex that is of a passable terrain for it.<br />
* '''overwrite''': {{DevFeature1.13|8}} (default=no) If yes, always place the unit at the exact specified location, overwriting the existing unit if there is one. Generally you don't want to use this together with placement=leader.<br />
<br />
* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.<br />
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give the unit fewer traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.<br />
<br />
* <span id="random_gender">'''random_gender'''</span>: "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.<br />
<br />
* '''to_variable''': (only for [event][unit]) creates the unit into the given variable instead of placing it on the map.<br />
<br />
* '''animate''': whether to display the recruitment animation for this unit as if it were being recruited/recalled. Defaults to "no". Irrelevant when the [unit] tag appears inside a [side].<br />
<br />
== See Also ==<br />
<br />
* [[UnitTypeWML]]<br />
* [[InternalActionsWMLUnitTags]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category:WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64646SpellingMistakes2019-10-03T14:47:51Z<p>Josteph: /* Tutorial */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
S23 "We must make haste! Far greater challenges lie before us, by tarrying here we’re diminishing our resources." comma splice<br />
<br />
S23 "mount Elnar" to "Mount Elnar" (capitalized) and pofix<br />
<br />
S23 "From a long line of kings" - sentence fragment<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
"A full list of abilities and weapons specials, along with traits, may be found in help."<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=64630InterfaceActionsWML2019-09-29T19:03:35Z<p>Josteph: /* [remove_unit_overlay] */</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;<br />
instead, they show something to the player. The main interface tags<br />
are '''[message]''' and '''[objectives]''', but several other tags affect<br />
the interface also.<br />
<br />
== [inspect] ==<br />
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.<br />
<br />
* '''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.<br />
<br />
== [message] ==<br />
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.<br />
<br />
The following key/tags are accepted for [message]:<br />
* [[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).<br>[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.<br />
<br />
* '''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:<br />
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image<br />
** '''unit''': the primary unit for the event is speaking<br />
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking<br />
<br />
* '''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 ''' " ''')<br />
* '''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.<br />
* '''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]).<br />
* '''[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]])<br />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> 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.<br />
* '''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. <br />
** {{DevFeature1.13|0}} <b>none:</b> display no image<br />
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.<br />
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.<br />
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.<br />
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above<br />
* '''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.<br />
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.<br />
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.<br />
* '''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.<br />
* '''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.<br />
* '''[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''<br />
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.<br />
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].<br />
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.<br />
** '''[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]])<br />
** '''[command]''': an element containing actions which are executed if the option is selected.<br />
* '''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.<br />
* '''[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''<br />
** '''variable''': the variable that the user's input will be written to<br />
** '''label''': a text label to the left of the input field<br />
** '''max_length''': the maximum number of characters that may be typed into the field<br />
** '''text''': text that is written into the field in the beginning<br />
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.<br />
<br />
=== Formatting ===<br />
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes].<br />
<br />
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.<br />
<br />
For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:<br />
<br />
<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki><br />
<br />
<br />
These are the codes taken from the Pango markup formatting guide:<br />
<br />
*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".<br />
*'''font_family''', '''face''': A font family name.<br />
*'''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'.<br />
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.<br />
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.<br />
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.<br />
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.<br />
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.<br />
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.<br />
*'''strikethrough''': 'true' or 'false' whether to strike through the text.<br />
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'<br />
*'''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.<br />
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.<br />
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.<br />
*'''gravity_hint''': One of 'natural', 'strong', 'line'.<br />
<br />
The following pango attributes are also available directly as attributes of the '''[message]''' tag:<br />
{{DevFeature1.13|4}}<br />
<br />
*'''font'''<br />
*'''font_family'''<br />
*'''font_size'''<br />
*'''font_style'''<br />
*'''font_weight'''<br />
*'''font_variant'''<br />
*'''font_stretch'''<br />
*'''color'''<br />
*'''bgcolor'''<br />
*'''underline'''<br />
*'''underline_color'''<br />
*'''rise'''<br />
*'''strikethrough'''<br />
*'''strikethrough_color'''<br />
*'''fallback'''<br />
*'''letter_spacing'''<br />
*'''gravity'''<br />
*'''gravity_hint'''<br />
<br />
== [objectives] ==<br />
The other tag used for plot development is '''[objectives]'''.<br />
The '''[objectives]''' tag overwrites any previously set objectives,<br />
and displays text which should describe the objectives of the scenario.<br />
Scenario objectives are displayed on the player's first turn after the tag is used,<br />
or as part of the event if it triggers during that player's turn.<br />
Objectives can also be accessed at any time in a scenario using the<br />
"Scenario Objectives" game menu option, making this tag useful for<br />
scenario-specific information that the player may need to refer to during play.<br />
<br />
Attributes of '''[objectives]''':<br />
* '''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.<br />
* '''[[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.<br />
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].<br />
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.<br />
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.<br />
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.<br />
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.<br />
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.<br />
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.<br />
* '''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.<br />
<br />
Tags of '''[objectives]''':<br />
* '''[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.<br />
** '''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.<br />
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''description''': text for the specific win or loss condition.<br />
** '''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''.<br />
** '''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'').<br />
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.<br />
** '''[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.<br />
* '''[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].<br />
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.<br />
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.<br />
** '''[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.<br />
* '''[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.<br />
** '''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.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.<br />
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.<br />
** '''description''': the text of the note.<br />
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.<br />
<br />
== [set_menu_item] ==<br />
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.<br />
<br />
'''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.<br />
<br />
* '''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.<br />
* '''description''': the in-game text that will appear for this item in the menu.<br />
* '''image''': the image to display next to this item.<br />
* '''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].<br />
* '''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<br />
* '''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. <br />
* '''[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.<br />
* '''[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.<br />
* '''[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:<br />
** '''key''': a string that contains the key to assign to this.<br />
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.<br />
** '''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.<br />
* '''[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.<br />
** '''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.<br />
<br />
== [clear_menu_item] ==<br />
<br />
Removes a menu item from the scenario.<br />
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).<br />
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.<br />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
<br />
=== [change_theme] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Change the current interface theme.<br />
<br />
* '''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 <b>1.14.2</b> 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).<br />
<br />
=== [item] ===<br />
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><br />
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)<br />
* '''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).)''<br />
* '''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).<br />
* '''name''' an id that can be used to remove the item.<br />
''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''<br />
or equivalently (requires Wesnoth 1.11.2+):<br />
''halo=scenery/fire[1~8].png:100''<br />
* '''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]])<br />
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.<br />
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.<br />
* '''[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]])<br />
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.<br />
<br />
=== [remove_item] ===<br />
Removes any graphical items on a given hex.<br />
* [[StandardLocationFilter]]: the hexes to remove items off<br />
* '''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.)<br />
* '''name''': removes an item with a previously defined name.<br />
<br />
=== [print] ===<br />
Displays a message across the screen. The message will disappear after a certain time.<br />
* '''text''': (translatable) the text to display.<br />
* '''size''': (default=12) the pointsize of the font to use<br />
* '''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.<br />
* '''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.<br />
<br />
=== [move_unit_fake] ===<br />
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.<br />
* '''type''': the type of the unit whose image to use<br />
* '''x''': a comma-separated list of x locations to move along<br />
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
* '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
* '''gender''': the gender of the fake unit. Example: gender=female<br />
* '''variation''': the variation of the fake unit. Example: variation=undead<br />
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.<br />
* '''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.<br />
<br />
=== [move_units_fake] ===<br />
moves multiple images of units along paths on the map. These units are moved in lockstep.<br />
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.<br />
* '''[fake_unit]''': A fake unit to move<br />
** '''type''': the type of unit whose image to use<br />
** '''x''': a comma-separated list of x locations to move along<br />
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
** '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
** '''skip_steps''': the number of steps to skip before this unit starts moving<br />
<br />
=== [hide_unit] ===<br />
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.<br />
* [[StandardUnitFilter]]: All matching units will be hidden<br />
<br />
=== [unhide_unit] ===<br />
Stops the currently hidden units from being hidden.<br />
* [[StandardUnitFilter]]: Only the matching units will be unhidden<br />
<br />
=== [lock_view] ===<br />
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.<br />
<br />
This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.<br />
<br />
{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.<br />
<br />
=== [unlock_view] ===<br />
Unlocks gamemap view scrolling for human players.<br />
<br />
=== [scroll] ===<br />
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.<br />
* '''x''', '''y''': the number of pixels to scroll along the x and y axis<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.<br />
<br />
=== [scroll_to] ===<br />
Scroll to a given hex<br />
* [[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.<br />
* '''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.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
<br />
=== [scroll_to_unit] ===<br />
Scroll to a given unit<br />
* [[StandardUnitFilter]]<br />
* '''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.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').<br />
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
<br />
=== [select_unit] ===<br />
Selects a given unit.<br />
* [[StandardUnitFilter]]: The first unit found will be selected.<br />
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)<br />
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').<br />
<br />
=== [sound]===<br />
Plays a sound<br />
* '''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.<br />
* '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
<br />
=== [sound_source] ===<br />
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.<br />
* '''id''': a unique identification key of the sound source<br />
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source<br />
* '''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<br />
* '''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)<br />
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged<br />
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded<br />
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source<br />
* '''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<br />
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center<br />
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)<br />
<br />
=== [story] ===<br />
{{DevFeature1.13|8}}<br />
<br />
Shows the story screen.<br />
* '''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.<br />
* '''[part]''': As [[IntroWML]].<br />
<br />
=== [remove_sound_source] ===<br />
Removes a previously defined sound source.<br />
* '''id''': the identification key of the sound source to remove<br />
<br />
=== [music]===<br />
Switches to playing different music<br />
* '''name''': the filename of the music to play (in ''music/'' as .ogg)<br />
* see [[MusicListWML]] for the correct syntax<br />
===[volume]===<br />
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100: <br />
* '''music''': Changes the music volume.<br />
* '''sound''': Changes the sound volume.<br />
=== [color_adjust]===<br />
Tints the color of the screen.<br />
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color<br />
=== [delay] ===<br />
Pauses the game.<br />
* '''time''': the time to pause in milliseconds<br />
* '''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.<br />
<br />
=== [redraw] ===<br />
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).<br />
* '''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).<br />
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.<br />
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.<br />
<br />
=== [unit_overlay] ===<br />
Sets an image that will be drawn over a particular unit, and follow it around<br />
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])<br />
* '''image''': the image to place on the unit<br />
<br />
=== [remove_unit_overlay] ===<br />
Removes a particular overlayed image from a unit<br />
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])<br />
* '''image''': the image to remove from the unit<br />
Using remove_object is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271<br />
<br />
=== [animate_unit] ===<br />
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).<br />
* '''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''<br />
* '''[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.<br />
* '''[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]].<br />
* '''[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.<br />
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)<br />
* '''text''': a text to hover during the animation <br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''': red value for the text color (0-255)<br />
* '''green''': green value for the text color<br />
* '''blue''': blue value for the text color<br />
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)<br />
* '''[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.<br />
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated<br />
<br />
=== [label] ===<br />
Places a label on the map.<br />
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)<br />
* '''text''': what the label should say<br />
* '''team_name''': if specified, the label will only be visible to the given team.<br />
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.<br />
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.<br />
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.<br />
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.<br />
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on<br />
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.<br />
<br />
=== [floating_text]===<br />
Floats text (similar to the damage and healing numbers) on the given locations.<br />
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.<br />
* '''text''': the text to display.<br />
<br />
The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:<br />
<br />
<pre><br />
# Float some golden yellow text at 20,20.<br />
[floating_text]<br />
x,y=20,20<br />
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"<br />
[/floating_text]<br />
</pre><br />
<br />
=== [deprecated_message] ===<br />
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.<br />
* '''message''': the message to show.<br />
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.<br />
* '''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<br />
* '''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. <br />
<br />
The meanings of the deprecation levels are as follows:<br />
<br />
# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.<br />
# It will be removed no earlier than a specified version.<br />
# It will be removed in the next stable version<br />
# It has already been removed, leaving just a stub to inform users of how to update their code.<br />
<br />
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.<br />
<br />
=== [wml_message] ===<br />
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.<br />
* '''message''': the message to show.<br />
* '''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.<br />
<br />
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.<br />
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).<br />
<br />
=== [test_condition] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
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.<br />
<br />
* '''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.<br />
* '''logger''': Same as for [wml_message]. Defaults to "warning".<br />
<br />
=== [open_help] ===<br />
Opens the in-game help.<br />
* '''topic''': the id of the topic to open<br />
=== [show_objectives] ===<br />
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.)<br />
* '''side''': the side to show the objectives. If not set, all sides are used.<br />
* '''[[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.<br />
<br />
=== [chat] ===<br />
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.<br />
* '''speaker''': (default="WML") A string for the name of the sender of the message.<br />
* '''message''': The message that should be displayed.<br />
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.<br />
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.<br />
<br />
=== [zoom] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Changes the zoom level of the map.<br />
<br />
* '''factor''': The new zoom factor<br />
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.<br />
<br />
== Useful Macros ==<br />
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].<br />
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units<br />
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations<br />
* '''{SET_IMAGE}''' Places an image on the map which has no other function.<br />
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.<br />
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.<br />
<br />
== See Also ==<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ModificationWML&diff=64629ModificationWML2019-09-29T17:53:12Z<p>Josteph: /* The [modification] toplevel tag */ spellcheck</p>
<hr />
<div>{{WML Tags}}<br />
== The [modification] toplevel tag ==<br />
<br />
This tag describes an SP or MP modification. A modification is, practically speaking, a bunch of events which get included into the scenario if the modification is enabled.<br />
<br />
The following keys/tags are recognized for '''[modification]''':<br />
<br />
* '''id''': identifier for the modification. Must be unique.<br />
* '''name''': the name of the modification, as displayed to the user.<br />
* '''type''': where the modification will be available for playing. Possible values are ''sp'', ''mp'', and ''hybrid''.<br />
* '''description''': a brief description for the modification.<br />
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.<br />
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this modification. Cannot be used in parallel with allow_scenario.<br />
* '''allow_era''': same as allow_scenario, but for eras.<br />
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.<br />
* '''allow_modification''': same as allow_scenario, but for modifications.<br />
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.<br />
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.<br />
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.<br />
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.<br />
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.<br />
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.<br />
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].<br />
* '''[lua]''': any [lua] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled.<br />
* '''[options]''': custom options. See [[OptionWML]] for details.<br />
* '''[ai]''': See [[AiWML]] for details.<br />
* '''[unit_type_fix]''' {{DevFeature1.15|0}}: Changes a unit type while this modification is active the supported attributes are:<br />
** '''type''' : the id of the unit type to change.<br />
** '''set_experience''' : changes the unit types max experience.<br />
** '''set_cost''' : changes the unit types recruit cost.<br />
** '''set_advances_to''' : changes the unit types advancements.<br />
** '''add_advancement''' : adds a unit type to the possible advancements of this unit type.<br />
** '''remove_advancement''' : removes a unit type to the possible advancements of this unit type.<br />
<br />
== The [resource] toplevel tag ==<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
The '''[resource]''' toplevel tag is similar to [modification] in that it contains [event] and [lua] tags which are then copied into the scenario. However, unlike [modification], resources defined this way are completely hidden from the user. To load a resource, use '''[load_resource] id=<i><resource id></i>''' in [scenario], [multiplayer], [era], [campaign], [modification], or [resource].</div>Jostephhttps://wiki.wesnoth.org/index.php?title=UnitTypeWML&diff=64628UnitTypeWML2019-09-29T16:21:19Z<p>Josteph: /* Other tags */ fix version</p>
<hr />
<div>{{WML Tags}}<br />
<br />
__TOC__<br />
<br />
== Unit Type ==<br />
<br />
Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])<br />
<br />
Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:<br />
* '''[advancefrom]''': Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:<br />
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.<br />
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.<br />
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.<br />
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.<br />
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".<br />
* '''attacks''': the number of times that this unit can attack each turn.<br />
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited.<br />
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.<br />
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'. <br />
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version <b>1.14.3</b>.<br />
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.<br />
::WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing).<br />
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.<br />
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).<br />
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.<br />
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.<br />
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.<br />
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.<br />
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare<br />
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games<br />
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied. <br />
* '''image''': sets the base image of the unit, which is used on the map.<br />
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.<br />
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).<br />
* '''movement''': the number of move points that this unit receives each turn.<br />
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.<br />
* '''name''':(translatable) displayed in the Status Table for units of this type.<br />
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.<br />
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.<br />
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).<br />
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:<br />
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"<br />
profile="portraits/elves/transparent/marksman+female.png"<br />
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, khalifate, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.<br />
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.<br />
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:<br> ** ''scout'': Fast, mobile unit meant for exploration and village grabbing.<br> ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.<br> ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.<br> ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.<br> ** ''healer'': Specialty 'heals' or 'cures'.<br>Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.<br />
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.<br />
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]<br />
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).<br />
* '''die_sound''': sets the sound, which is used when the unit dies.<br />
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).<br />
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).<br />
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).<br />
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.<br />
<br />
== After max level advancement (AMLA) ==<br />
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.<br />
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.<br />
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.<br />
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.<br />
** '''image''': an image to display next to the description in the advancement menu.<br />
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".<br />
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.<br />
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.<br />
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.<br />
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.<br />
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.<br />
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.<br />
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]<br />
<br />
== Attacks ==<br />
* '''[attack]''': one of the unit's attacks.<br />
** '''description''': a translatable text for name of the attack, to be displayed to the user.<br />
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]<br />
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). {{DevFeature1.15|0}} Damage type icons in the sidebar should be named icons/profiles/''type''.png. See https://github.com/wesnoth/wesnoth/pull/3732<br />
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].<br />
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png''). <br />
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable. {{DevFeature1.15|0}} Range icons in the sidebar should be named icons/profiles/''range''_attack.png. See https://github.com/wesnoth/wesnoth/pull/3732<br />
** '''damage''': the damage of this attack<br />
** '''number''': the number of strikes per attack this weapon has<br />
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too<br />
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too<br />
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.<br />
** '''attack_weight''': helps the AI to choose which attack to use when attacking, setting it to 0 disables the attack on attack. See the note about weights below.<br />
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense. See the note about weights below.<br />
Note: For the weight settings, the engine currently (as of 1.14) recognizes only two situations: >0 (normal) and <= 0 (attack completely disabled), so attack_weight=1 and attack_weight=5 have exactly the same chance of being chosen. https://r.wesnoth.org/t49322<br />
<br />
== Other tags ==<br />
* '''[base_unit]''': Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.<br />
<br />
* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.<br />
** '''size''': The size of the portrait, in pixels.<br />
** '''side''': One of left or right.<br />
** '''mirror''': Whether to flip the image horizontally.<br />
** '''image''': The image path.<br />
<br />
* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]<br />
<br />
* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]<br />
<br />
* '''[variation]''': Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.<br />
** '''variation_id''': The id of this variation. Defaults to ''variation_name''.<br />
** '''variation_name''': Translatable. The name of the variation.<br />
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.<br />
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.<br />
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.<br />
<br />
* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.<br />
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.<br />
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.<br />
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.<br />
<br />
* {{DevFeature1.15|2}} '''[special_note]''': Adds a special note to the unit's description. This tag will usually be used indirectly via a macro. It contains one key, '''note''', which just specifies the text of the note. Use of this tag results in a bulleted list of special notes, rather than the old format for special notes embedded in the '''description'''.<br />
<br />
== See Also ==<br />
<br />
* [[AnimationWML]]<br />
* [[ReferenceWML]]<br />
* [[TerrainWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64610SpellingMistakes2019-09-27T17:50:58Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
S23 "We must make haste! Far greater challenges lie before us, by tarrying here we’re diminishing our resources." comma splice<br />
<br />
S23 "mount Elnar" to "Mount Elnar" (capitalized) and pofix<br />
<br />
S23 "From a long line of kings" - sentence fragment<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=GameConfigWML&diff=64609GameConfigWML2019-09-26T18:32:23Z<p>Josteph: /* Color Palettes */ delete sentence that seems to be wrong (tested with Ravana's color changer and #4366)</p>
<hr />
<div>{{WML Tags}}<br />
== The [game_config] tag ==<br />
<br />
This tag is a top level WML tag which can only be used once because<br />
it defines basic settings that are used everywhere in the game.<br />
In official versions of Wesnoth it is in ''game_config.cfg''; values used there are labeled 'standard'.<br />
<br />
<br />
The following keys are recognised<br />
* '''base_income''': (standard 2) how much your leader earns without any villages<br />
* '''village_income''': (standard 1) how much your leader earns for each village you control<br />
* '''poison_amount''': (standard 8) the amount of damage poison deals to a unit<br />
* '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests<br />
* '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.<br />
* '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.<br />
<br />
* '''icon''': (standard 'wesnoth-icon.png') the game icon file<br />
* '''title''': (standard 'misc/title.png') the title screen image<br />
* '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image<br />
* '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario<br />
* '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario<br />
* '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen<br />
* '''logo_x''': (standard 292) the x position of the logo on the title screen<br />
* '''logo_y''': (standard 120) the y position of the logo on the title screen<br />
* '''buttons_x''': (standard 760) the x position of the buttons on the title screen<br />
* '''buttons_y''': (standard 330) the y position of the buttons on the title screen<br />
* '''buttons_padding''': (standard 20) space between buttons, and border in main menu<br />
* '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge<br />
* '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)<br />
* '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.<br />
* '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel<br />
<br />
* '''map_image''': (standard 'maps/wesnoth.png') the background image for the "About" screen<br />
* '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics<br />
* '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics<br />
* '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.<br />
* '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]<br />
* '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units<br />
* '''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units<br />
* '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied. <br />
* '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied. <br />
* ''' hp_bar_scaling ''': (standard '0.6') The ratio of hitpoints to height used for displaying the hp bar. Can be overwritten in [unit] and [unit_type].<br />
* ''' xp_bar_scaling ''': (standard '0.5') The ratio of xp to height used for displaying the xp bar. Can be overwritten in [unit] and [unit_type].<br />
* '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]<br />
* '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios<br />
<br />
* '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.<br />
The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;<br />
the second for ones which would take more.<br />
The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].<br />
The 'left' and 'right' designations are used alternately throughout the path;<br />
however, the standard values are the same for 'left' and 'right'.<br />
<br />
* '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.<br />
* '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option <br />
* '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations<br />
<br />
* '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]<br />
* '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]<br />
* '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)<br />
* '''download_campaign_image''': (standard no image) the icon for the "Download more Campaigns" campaign menu option.<br />
* '''zoom_levels''': {{DevFeature1.13|8}} A comma-separated list of valid zoom levels, with 1.0 representing 100%.<br />
<br />
== Color Palettes ==<br />
<br />
Color palettes are defined by two tags within '''[game_config]'''.<br />
<br />
* '''[color_palette]''': Contains the definitions of source palettes, such as magenta. Each key defines a palette, and must be set to a comma-separated list of hexadecimal colors.<br />
* '''[color_range]''': Defines a target color palette.<br />
** '''id''': Used to reference the palette, for example from '''[side]''' or ~RC().<br />
** '''name''': A translatable name for the color. <s>This may be ignored for non-core colors?</s><br />
** '''rgb''': A comma-separated sequence of four hexadecimal colors:<br />
**# the average shade of a unit's team-color portions<br />
**# the maximum highlight shade of a unit's team-color portions<br />
**# the minimum shadow shade of a unit's team-color portions<br />
**# the color of the markers on the mini-map.<br />
<br />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=64608DirectActionsWML2019-09-26T16:24:30Z<p>Josteph: /* [tunnel] */ use consistent style</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br />
<br />
The following tags are actions:<br />
<br />
=== [endlevel] ===<br />
Ends the scenario.<br />
* '''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. <br />
<br />
When the result is "victory" the following keys can be used:<br />
* '''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).<br />
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.<br />
* '''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''.<br />
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
* '''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.<br />
* '''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.<br />
* '''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]].<br />
* '''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]].<br />
* '''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]].<br />
* <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.<br />
* <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.<br />
* '''[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]''':<br />
** '''result'''<br />
** '''bonus'''<br />
** '''carryover_percentage'''<br />
** '''carryover_add'''<br />
<br />
And there is also<br />
** '''side''' The number of the side for which these results should apply.<br />
<br />
=== [unit] ===<br />
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].<br />
* {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
<br />
This tag can also recall an existing unit, which happens when:<br />
* the '''id=''' attribute is used<br />
* a unit with that '''id=''' already exists<br />
* (might be unnecessary) the existing unit is on the side's recall list<br />
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.<br />
<br />
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.<br />
For example,<br />
[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].<br />
<br />
=== [recall] ===<br />
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.<br />
<br />
If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.<br />
<br />
* [[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).<br />
* '''x,y''': the unit is placed here instead of next to the leader.<br />
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br />
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.<br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).<br />
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.<br />
<br />
=== [teleport] ===<br />
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br />
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.<br />
* '''clear_shroud''': should shroud be cleared on arrival<br />
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''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.<br />
<br />
(Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br />
<br />
=== [terrain_mask] ===<br />
Changes the terrain on the map. See [[TerrainMaskWML]].<br />
<br />
=== [terrain] ===<br />
Changes the terrain on the map.<br />
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
* [[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.<br />
* '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
* '''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.<br />
<br />
If you want to remove the overlays from a terrain and leave only the base, use:<br />
layer=overlay<br />
terrain="^"<br />
<br />
<b>Note:</b> 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.<br />
<br />
=== [gold] ===<br />
Gives sides gold.<br />
* '''amount''': the amount of gold to give.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [unstore_unit] ===<br />
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].<br />
* '''variable''': the name of the variable.<br />
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. <br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".<br />
* '''text''': (translatable) floating text to display above the unit, such as a damage amount<br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br />
* '''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.<br />
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.<br />
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.<br />
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.<br />
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&ndash;and killed&ndash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.<br />
<br />
=== [allow_recruit] ===<br />
Allows a side to recruit units it couldn't previously recruit.<br />
* '''type''': the types of units that the side can now recruit.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [allow_extra_recruit] ===<br />
Allows a leader to recruit units it couldn't previously recruit.<br />
These types add to the types the leader can recruit because of [side]recruit=.<br />
* '''extra_recruit''': the types of units that the unit can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [disallow_recruit] ===<br />
Prevents a side from recruiting units it could previously recruit.<br />
* '''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.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [disallow_extra_recruit] ===<br />
Prevents a leader from recruiting units it could previously recruit.<br />
* '''extra_recruit''': the types of units that the side can no longer recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [set_recruit] ===<br />
Sets the units a side can recruit.<br />
* '''recruit''': the types of units that the side can now recruit.<br />
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [set_extra_recruit] === <br />
Sets the units a leader can recruit.<br />
* '''extra_recruit''': the types of units that the leader can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [modify_side] ===<br />
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!'''<br />
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* '''income''': the income given at the begining of each turn.<br />
* '''recruit''': a list of unit types, replacing the side's current recruitment list.<br />
* '''team_name''': the team in which the side plays the scenario.<br />
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.<br />
* '''gold''': the amount of gold the side owns.<br />
* '''village_gold''': the income setting per village for the side.<br />
* '''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].<br />
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
* '''shroud''': a boolean string describing the status of Shroud for the side.<br />
* '''hidden''': a boolean string specifying whether side is shown in status table.<br />
* '''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.<br />
* '''[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 [http://wiki.wesnoth.org/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.<br />
* '''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.<br />
* '''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=).<br />
* '''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=.<br />
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br />
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br />
* '''share_vision''': change both the above at the same time<br />
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].<br />
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.<br />
* '''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.<br />
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).<br />
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).<br />
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.<br />
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).<br />
<br />
=== [modify_turns] ===<br />
Modifies the turn limit in the middle of a scenario.<br />
* '''value''': the new turn limit.<br />
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
* '''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).<br />
<br />
=== [allow_end_turn] ===<br />
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.<br />
<br />
=== [disallow_end_turn] ===<br />
Disallows human players to end their turn through the user interface. This action doesn't require arguments.<br />
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.<br />
<br />
=== [capture_village] ===<br />
Changes the ownership of a village.<br />
* [[StandardLocationFilter]]: all village locations matching the filter are affected.<br />
* '''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).<br />
* '''[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).<br />
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.<br />
<br />
=== [kill] ===<br />
Removes all units (including units in a recall list) that match the filter from the game.<br />
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br />
* '''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.<br />
* '''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).<br />
* '''[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).<br />
* '''[primary_attack]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.<br />
<br />
=== [move_unit] ===<br />
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.<br />
* [[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.<br />
* '''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.<br />
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br />
* '''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'''.<br />
* '''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'''.<br />
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br />
* '''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.)<br />
* '''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.<br />
<br />
=== [modify_ai] ===<br />
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.<br />
<br />
* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.<br />
* '''path''' (string): Describes which AI object is to be modified. <br />
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [modify_unit] ===<br />
works similar to the MODIFY_UNIT macro.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br />
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.<br />
** '''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.<br />
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.<br />
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.<br />
* 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.<br />
example usage (see also the test scenario):<br />
<syntaxhighlight lang='wml'><br />
[modify_unit]<br />
[filter]<br />
x,y=38,6<br />
[/filter]<br />
hitpoints=10<br />
{TRAIT_HEALTHY}<br />
[/modify_unit]<br />
</syntaxhighlight><br />
<br />
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).<br />
<br />
Some some peorperties of the units are reset sometimes for exmapel 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], this list of properties that are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit] is:<br />
* '''side'''<br />
* '''gender'''<br />
* '''name'''<br />
* '''canrecruit'''<br />
* '''unrenamable'''<br />
* '''extra_recruit'''<br />
* '''[variables]'''<br />
* '''facing'''<br />
* '''goto_x, goto_y'''<br />
* '''hitpoints'''<br />
* '''experience'''<br />
* '''moves'''<br />
* '''[status]''' (not sure on this one)<br />
* '''attacks_left'''<br />
* '''role'''<br />
<br />
=== [transform_unit] ===<br />
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.<br />
* [[StandardUnitFilter]]: do not use a [filter] tag.<br />
* '''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.<br />
<br />
=== [petrify] ===<br />
<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br />
<br />
=== [unpetrify] ===<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.<br />
<br />
=== [object] ===<br />
Gives some unit an object which modifies their stats in some way.<br />
* '''id''': (Optional) allows the item to be removed later. 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.<br />
* '''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.<br />
* '''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.<br />
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
* '''duration''':<br />
**if 'scenario', effects only last until the end of the scenario.<br />
**if 'forever' or not set, effects never wear off.<br />
** 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.)<br />
** {{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).<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). 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]'''.<br />
* '''[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.<br />
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.<br />
* '''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.<br />
* '''image''': the displayed image of the object.<br />
* '''name''': (translatable) displayed as a caption of the image.<br />
<br />
* '''description''': (translatable) displayed as a message of the image.<br />
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
<br />
=== [remove_object] ===<br />
<br />
{{DevFeature1.13|6}}<br />
<br />
Removes an object from matching units.<br />
<br />
* [[StandardUnitFilter]]: All units matching the filter have matching objects removed. Use no [filter] tag.<br />
* '''object_id''': The id of the object to be removed.<br />
<br />
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.<br />
<br />
Note that remove_object worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 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 [modify_unit] to get a list of properties that can safely be changes via [modify_unit]<br />
<br />
=== [remove_shroud] ===<br />
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br />
<br />
=== [place_shroud] ===<br />
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br />
<br />
=== [lift_fog] ===<br />
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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.<br />
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).<br />
<br />
=== [reset_fog] ===<br />
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.)<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.<br />
* '''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}}.<br />
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].<br />
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).<br />
<br />
=== [allow_undo] ===<br />
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 &mdash; specifically when handling a menu item, where there is no current action &mdash; and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.<br />
* 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.<br />
<br />
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.<br />
* 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.<br />
* 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).<br />
<br />
If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.<br />
<br />
Due to a bug in 1.12 (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: <br />
* [message] with [option]s<br />
* [get_global_variable]<br />
* wesnoth.synchronize_choice<br />
<br />
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:<br />
<br />
[event]<br />
name="moveto"<br />
[message]<br />
message = "message"<br />
[option]<br />
label = "option 1"<br />
[command]<br />
[/command]<br />
[/option]<br />
[option]<br />
label = "option 2"<br />
[command]<br />
[/command]<br />
[/option]<br />
[/message]<br />
[allow_undo]<br />
[/allow_undo]<br />
[/event]<br />
<br />
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.<br />
<br />
=== [on_undo] ===<br />
{{DevFeature1.13|2}}<br />
Contains commands to execute when the player undoes the action which triggered the parent event.<br />
*'''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.)<br />
<br />
Note:<br />
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<br />
[event]<br />
name="undo_blah"<br />
first_time_only=no<br />
[store_unit]<br />
id="$moved_unit_id"<br />
[/store_unit]<br />
... do undo stuff stuff<br />
[/event]<br />
<br />
...<br />
... in some other event<br />
[on_undo]<br />
# store ''upvalues<br />
{VARIABLE moved_unit_id $unit.id}<br />
# call actual undo handler<br />
[fire_event]<br />
name = "undo_blah"<br />
[/fire_event]<br />
[on_undo]<br />
<br />
=== [on_redo] ===<br />
{{DevFeature1.13|2}}<br />
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.<br />
<br />
{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.<br />
<br />
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.<br />
<br />
=== [cancel_action] ===<br />
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.<br />
<br />
{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).<br />
<br />
{{DevFeature1.13|11}}<br />
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_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] on (3,3) would let the player choose whether to attack.<br />
<br />
=== [heal_unit] ===<br />
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.<br />
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.<br />
* '''[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.<br />
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.<br />
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br />
* '''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.<br />
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br />
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".<br />
<br />
=== [harm_unit] ===<br />
Harms every unit matching the filter, for the specific damage amount.<br />
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br />
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.<br />
* '''amount''': the amount of damage that will be done (required).<br />
* '''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.<br />
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''[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]].<br />
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br />
* '''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.<br />
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br />
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.<br />
* '''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.<br />
<br />
=== [time_area] ===<br />
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.<br />
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br />
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].<br />
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br />
* '''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.<br />
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.<br />
<br />
''Example:'' (caves in parts of a map)<br />
[time_area]<br />
x=1-2,4-5<br />
y=1-2,1-2<br />
{UNDERGROUND}<br />
[/time_area]<br />
<br />
=== [remove_time_area] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This is a syntactic shortcut for [time_area] remove=.<br />
* '''id''': Comma-separated list of time area ids to remove.<br />
<br />
=== [end_turn] ===<br />
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).<br />
<br />
=== [replace_map] ===<br />
<br />
Replaces the entire map.<br />
* '''map''': Content of a wesnoth map file. example:<br />
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"<br />
* '''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.<br />
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br />
* '''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.<br />
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.<br />
<br />
=== [replace_schedule] ===<br />
Replace the time of day schedule of the entire scenario.<br />
* [[TimeWML]]: the new schedule.<br />
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.<br />
<br />
=== [tunnel] ===<br />
<br />
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).<br />
<br />
'''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.<br />
<br />
* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".<br />
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).<br />
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).<br />
* '''id''': (optional) identifier for the tunnel, to allow removing.<br />
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).<br />
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction. <br />
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.<br />
* '''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).<br />
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.<br />
* '''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]]<br />
<br />
(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br />
<br />
=== [do_command] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted<br />
<br />
* [attack]<br />
* [move]<br />
* [recruit]<br />
* [recall]<br />
* [disband]<br />
* [fire_event]<br />
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]<br />
<br />
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.<br />
<br />
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.<br />
<br />
This command should always be replay safe.<br />
<br />
=== [put_to_recall_list] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Puts a unit to the recall list of its side.<br />
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.<br />
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.<br />
<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=64607DirectActionsWML2019-09-26T16:23:47Z<p>Josteph: /* [tunnel] */ Link EventWML#Nested_Events</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br />
<br />
The following tags are actions:<br />
<br />
=== [endlevel] ===<br />
Ends the scenario.<br />
* '''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. <br />
<br />
When the result is "victory" the following keys can be used:<br />
* '''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).<br />
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.<br />
* '''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''.<br />
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
* '''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.<br />
* '''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.<br />
* '''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]].<br />
* '''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]].<br />
* '''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]].<br />
* <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.<br />
* <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.<br />
* '''[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]''':<br />
** '''result'''<br />
** '''bonus'''<br />
** '''carryover_percentage'''<br />
** '''carryover_add'''<br />
<br />
And there is also<br />
** '''side''' The number of the side for which these results should apply.<br />
<br />
=== [unit] ===<br />
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].<br />
* {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
<br />
This tag can also recall an existing unit, which happens when:<br />
* the '''id=''' attribute is used<br />
* a unit with that '''id=''' already exists<br />
* (might be unnecessary) the existing unit is on the side's recall list<br />
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.<br />
<br />
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.<br />
For example,<br />
[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].<br />
<br />
=== [recall] ===<br />
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.<br />
<br />
If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.<br />
<br />
* [[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).<br />
* '''x,y''': the unit is placed here instead of next to the leader.<br />
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br />
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.<br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).<br />
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.<br />
<br />
=== [teleport] ===<br />
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br />
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.<br />
* '''clear_shroud''': should shroud be cleared on arrival<br />
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''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.<br />
<br />
(Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br />
<br />
=== [terrain_mask] ===<br />
Changes the terrain on the map. See [[TerrainMaskWML]].<br />
<br />
=== [terrain] ===<br />
Changes the terrain on the map.<br />
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
* [[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.<br />
* '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
* '''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.<br />
<br />
If you want to remove the overlays from a terrain and leave only the base, use:<br />
layer=overlay<br />
terrain="^"<br />
<br />
<b>Note:</b> 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.<br />
<br />
=== [gold] ===<br />
Gives sides gold.<br />
* '''amount''': the amount of gold to give.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [unstore_unit] ===<br />
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].<br />
* '''variable''': the name of the variable.<br />
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. <br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".<br />
* '''text''': (translatable) floating text to display above the unit, such as a damage amount<br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br />
* '''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.<br />
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.<br />
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.<br />
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.<br />
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&ndash;and killed&ndash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.<br />
<br />
=== [allow_recruit] ===<br />
Allows a side to recruit units it couldn't previously recruit.<br />
* '''type''': the types of units that the side can now recruit.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [allow_extra_recruit] ===<br />
Allows a leader to recruit units it couldn't previously recruit.<br />
These types add to the types the leader can recruit because of [side]recruit=.<br />
* '''extra_recruit''': the types of units that the unit can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [disallow_recruit] ===<br />
Prevents a side from recruiting units it could previously recruit.<br />
* '''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.<br />
* '''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.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [disallow_extra_recruit] ===<br />
Prevents a leader from recruiting units it could previously recruit.<br />
* '''extra_recruit''': the types of units that the side can no longer recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [set_recruit] ===<br />
Sets the units a side can recruit.<br />
* '''recruit''': the types of units that the side can now recruit.<br />
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [set_extra_recruit] === <br />
Sets the units a leader can recruit.<br />
* '''extra_recruit''': the types of units that the leader can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [modify_side] ===<br />
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!'''<br />
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* '''income''': the income given at the begining of each turn.<br />
* '''recruit''': a list of unit types, replacing the side's current recruitment list.<br />
* '''team_name''': the team in which the side plays the scenario.<br />
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.<br />
* '''gold''': the amount of gold the side owns.<br />
* '''village_gold''': the income setting per village for the side.<br />
* '''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].<br />
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
* '''shroud''': a boolean string describing the status of Shroud for the side.<br />
* '''hidden''': a boolean string specifying whether side is shown in status table.<br />
* '''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.<br />
* '''[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 [http://wiki.wesnoth.org/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.<br />
* '''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.<br />
* '''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=).<br />
* '''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=.<br />
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br />
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br />
* '''share_vision''': change both the above at the same time<br />
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].<br />
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.<br />
* '''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.<br />
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).<br />
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).<br />
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.<br />
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).<br />
<br />
=== [modify_turns] ===<br />
Modifies the turn limit in the middle of a scenario.<br />
* '''value''': the new turn limit.<br />
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
* '''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).<br />
<br />
=== [allow_end_turn] ===<br />
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.<br />
<br />
=== [disallow_end_turn] ===<br />
Disallows human players to end their turn through the user interface. This action doesn't require arguments.<br />
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.<br />
<br />
=== [capture_village] ===<br />
Changes the ownership of a village.<br />
* [[StandardLocationFilter]]: all village locations matching the filter are affected.<br />
* '''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).<br />
* '''[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).<br />
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.<br />
<br />
=== [kill] ===<br />
Removes all units (including units in a recall list) that match the filter from the game.<br />
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br />
* '''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.<br />
* '''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).<br />
* '''[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).<br />
* '''[primary_attack]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.<br />
<br />
=== [move_unit] ===<br />
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.<br />
* [[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.<br />
* '''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.<br />
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br />
* '''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'''.<br />
* '''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'''.<br />
* '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br />
* '''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.)<br />
* '''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.<br />
<br />
=== [modify_ai] ===<br />
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.<br />
<br />
* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.<br />
* '''path''' (string): Describes which AI object is to be modified. <br />
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [modify_unit] ===<br />
works similar to the MODIFY_UNIT macro.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br />
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter.<br />
** '''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.<br />
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements.<br />
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.<br />
* 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.<br />
example usage (see also the test scenario):<br />
<syntaxhighlight lang='wml'><br />
[modify_unit]<br />
[filter]<br />
x,y=38,6<br />
[/filter]<br />
hitpoints=10<br />
{TRAIT_HEALTHY}<br />
[/modify_unit]<br />
</syntaxhighlight><br />
<br />
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).<br />
<br />
Some some peorperties of the units are reset sometimes for exmapel 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], this list of properties that are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit] is:<br />
* '''side'''<br />
* '''gender'''<br />
* '''name'''<br />
* '''canrecruit'''<br />
* '''unrenamable'''<br />
* '''extra_recruit'''<br />
* '''[variables]'''<br />
* '''facing'''<br />
* '''goto_x, goto_y'''<br />
* '''hitpoints'''<br />
* '''experience'''<br />
* '''moves'''<br />
* '''[status]''' (not sure on this one)<br />
* '''attacks_left'''<br />
* '''role'''<br />
<br />
=== [transform_unit] ===<br />
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.<br />
* [[StandardUnitFilter]]: do not use a [filter] tag.<br />
* '''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.<br />
<br />
=== [petrify] ===<br />
<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br />
<br />
=== [unpetrify] ===<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.<br />
<br />
=== [object] ===<br />
Gives some unit an object which modifies their stats in some way.<br />
* '''id''': (Optional) allows the item to be removed later. 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.<br />
* '''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.<br />
* '''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.<br />
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
* '''duration''':<br />
**if 'scenario', effects only last until the end of the scenario.<br />
**if 'forever' or not set, effects never wear off.<br />
** 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.)<br />
** {{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).<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). 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]'''.<br />
* '''[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.<br />
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.<br />
* '''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.<br />
* '''image''': the displayed image of the object.<br />
* '''name''': (translatable) displayed as a caption of the image.<br />
<br />
* '''description''': (translatable) displayed as a message of the image.<br />
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
<br />
=== [remove_object] ===<br />
<br />
{{DevFeature1.13|6}}<br />
<br />
Removes an object from matching units.<br />
<br />
* [[StandardUnitFilter]]: All units matching the filter have matching objects removed. Use no [filter] tag.<br />
* '''object_id''': The id of the object to be removed.<br />
<br />
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.<br />
<br />
Note that remove_object worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 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 [modify_unit] to get a list of properties that can safely be changes via [modify_unit]<br />
<br />
=== [remove_shroud] ===<br />
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br />
<br />
=== [place_shroud] ===<br />
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br />
<br />
=== [lift_fog] ===<br />
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.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.<br />
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_view=yes).<br />
<br />
=== [reset_fog] ===<br />
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.)<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.<br />
* '''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}}.<br />
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].<br />
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).<br />
<br />
=== [allow_undo] ===<br />
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 &mdash; specifically when handling a menu item, where there is no current action &mdash; and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.<br />
* 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.<br />
<br />
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.<br />
* 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.<br />
* 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).<br />
<br />
If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.<br />
<br />
Due to a bug in 1.12 (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: <br />
* [message] with [option]s<br />
* [get_global_variable]<br />
* wesnoth.synchronize_choice<br />
<br />
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:<br />
<br />
[event]<br />
name="moveto"<br />
[message]<br />
message = "message"<br />
[option]<br />
label = "option 1"<br />
[command]<br />
[/command]<br />
[/option]<br />
[option]<br />
label = "option 2"<br />
[command]<br />
[/command]<br />
[/option]<br />
[/message]<br />
[allow_undo]<br />
[/allow_undo]<br />
[/event]<br />
<br />
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.<br />
<br />
=== [on_undo] ===<br />
{{DevFeature1.13|2}}<br />
Contains commands to execute when the player undoes the action which triggered the parent event.<br />
*'''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.)<br />
<br />
Note:<br />
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<br />
[event]<br />
name="undo_blah"<br />
first_time_only=no<br />
[store_unit]<br />
id="$moved_unit_id"<br />
[/store_unit]<br />
... do undo stuff stuff<br />
[/event]<br />
<br />
...<br />
... in some other event<br />
[on_undo]<br />
# store ''upvalues<br />
{VARIABLE moved_unit_id $unit.id}<br />
# call actual undo handler<br />
[fire_event]<br />
name = "undo_blah"<br />
[/fire_event]<br />
[on_undo]<br />
<br />
=== [on_redo] ===<br />
{{DevFeature1.13|2}}<br />
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.<br />
<br />
{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.<br />
<br />
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.<br />
<br />
=== [cancel_action] ===<br />
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.<br />
<br />
{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).<br />
<br />
{{DevFeature1.13|11}}<br />
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_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] on (3,3) would let the player choose whether to attack.<br />
<br />
=== [heal_unit] ===<br />
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.<br />
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.<br />
* '''[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.<br />
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.<br />
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br />
* '''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.<br />
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br />
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".<br />
<br />
=== [harm_unit] ===<br />
Harms every unit matching the filter, for the specific damage amount.<br />
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br />
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.<br />
* '''amount''': the amount of damage that will be done (required).<br />
* '''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.<br />
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br />
* '''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.<br />
* '''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.<br />
* '''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.<br />
* '''[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]].<br />
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br />
* '''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.<br />
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br />
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.<br />
* '''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.<br />
<br />
=== [time_area] ===<br />
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.<br />
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br />
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].<br />
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br />
* '''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.<br />
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.<br />
<br />
''Example:'' (caves in parts of a map)<br />
[time_area]<br />
x=1-2,4-5<br />
y=1-2,1-2<br />
{UNDERGROUND}<br />
[/time_area]<br />
<br />
=== [remove_time_area] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This is a syntactic shortcut for [time_area] remove=.<br />
* '''id''': Comma-separated list of time area ids to remove.<br />
<br />
=== [end_turn] ===<br />
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).<br />
<br />
=== [replace_map] ===<br />
<br />
Replaces the entire map.<br />
* '''map''': Content of a wesnoth map file. example:<br />
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"<br />
* '''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.<br />
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br />
* '''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.<br />
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.<br />
<br />
=== [replace_schedule] ===<br />
Replace the time of day schedule of the entire scenario.<br />
* [[TimeWML]]: the new schedule.<br />
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.<br />
<br />
=== [tunnel] ===<br />
<br />
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).<br />
<br />
'''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.<br />
<br />
* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".<br />
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).<br />
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).<br />
* '''id''': (optional) identifier for the tunnel, to allow removing.<br />
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).<br />
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction. <br />
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.<br />
* '''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).<br />
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.<br />
* '''delayed_variable_substitution''' (boolean yes|no): If set to "yes" (default), 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]]<br />
<br />
(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br />
<br />
=== [do_command] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted<br />
<br />
* [attack]<br />
* [move]<br />
* [recruit]<br />
* [recall]<br />
* [disband]<br />
* [fire_event]<br />
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]<br />
<br />
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.<br />
<br />
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.<br />
<br />
This command should always be replay safe.<br />
<br />
=== [put_to_recall_list] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Puts a unit to the recall list of its side.<br />
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.<br />
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.<br />
<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64475SpellingMistakes2019-09-19T20:10:54Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
S23 "We must make haste! Far greater challenges lie before us, by tarrying here we’re diminishing our resources." comma splice<br />
<br />
S23 "mount Elnar" to "Mount Elnar" (capitalized) and pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64474SpellingMistakes2019-09-19T20:10:05Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
S23 "We must make haste! Far greater challenges lie before us, by tarrying here we’re diminishing our resources." comma splice<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64473SpellingMistakes2019-09-19T20:07:08Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
dialog throughout - change ''...'' to ''…'', and add to pofix<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=64396InterfaceActionsWML2019-09-14T10:32:28Z<p>Josteph: /* [item] */</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;<br />
instead, they show something to the player. The main interface tags<br />
are '''[message]''' and '''[objectives]''', but several other tags affect<br />
the interface also.<br />
<br />
== [inspect] ==<br />
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.<br />
<br />
* '''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.<br />
<br />
== [message] ==<br />
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.<br />
<br />
The following key/tags are accepted for [message]:<br />
* [[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).<br>[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.<br />
<br />
* '''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:<br />
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image<br />
** '''unit''': the primary unit for the event is speaking<br />
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking<br />
<br />
* '''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 ''' " ''')<br />
* '''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.<br />
* '''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]).<br />
* '''[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]])<br />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> 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.<br />
* '''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. <br />
** {{DevFeature1.13|0}} <b>none:</b> display no image<br />
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.<br />
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.<br />
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.<br />
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above<br />
* '''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.<br />
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.<br />
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.<br />
* '''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.<br />
* '''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.<br />
* '''[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''<br />
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.<br />
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].<br />
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.<br />
** '''[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]])<br />
** '''[command]''': an element containing actions which are executed if the option is selected.<br />
* '''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.<br />
* '''[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''<br />
** '''variable''': the variable that the user's input will be written to<br />
** '''label''': a text label to the left of the input field<br />
** '''max_length''': the maximum number of characters that may be typed into the field<br />
** '''text''': text that is written into the field in the beginning<br />
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.<br />
<br />
=== Formatting ===<br />
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes].<br />
<br />
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.<br />
<br />
For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:<br />
<br />
<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki><br />
<br />
<br />
These are the codes taken from the Pango markup formatting guide:<br />
<br />
*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".<br />
*'''font_family''', '''face''': A font family name.<br />
*'''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'.<br />
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.<br />
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.<br />
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.<br />
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.<br />
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.<br />
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.<br />
*'''strikethrough''': 'true' or 'false' whether to strike through the text.<br />
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'<br />
*'''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.<br />
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.<br />
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.<br />
*'''gravity_hint''': One of 'natural', 'strong', 'line'.<br />
<br />
The following pango attributes are also available directly as attributes of the '''[message]''' tag:<br />
{{DevFeature1.13|4}}<br />
<br />
*'''font'''<br />
*'''font_family'''<br />
*'''font_size'''<br />
*'''font_style'''<br />
*'''font_weight'''<br />
*'''font_variant'''<br />
*'''font_stretch'''<br />
*'''color'''<br />
*'''bgcolor'''<br />
*'''underline'''<br />
*'''underline_color'''<br />
*'''rise'''<br />
*'''strikethrough'''<br />
*'''strikethrough_color'''<br />
*'''fallback'''<br />
*'''letter_spacing'''<br />
*'''gravity'''<br />
*'''gravity_hint'''<br />
<br />
== [objectives] ==<br />
The other tag used for plot development is '''[objectives]'''.<br />
The '''[objectives]''' tag overwrites any previously set objectives,<br />
and displays text which should describe the objectives of the scenario.<br />
Scenario objectives are displayed on the player's first turn after the tag is used,<br />
or as part of the event if it triggers during that player's turn.<br />
Objectives can also be accessed at any time in a scenario using the<br />
"Scenario Objectives" game menu option, making this tag useful for<br />
scenario-specific information that the player may need to refer to during play.<br />
<br />
Attributes of '''[objectives]''':<br />
* '''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.<br />
* '''[[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.<br />
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].<br />
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.<br />
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.<br />
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.<br />
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.<br />
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.<br />
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.<br />
* '''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.<br />
<br />
Tags of '''[objectives]''':<br />
* '''[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.<br />
** '''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.<br />
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''description''': text for the specific win or loss condition.<br />
** '''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''.<br />
** '''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'').<br />
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.<br />
** '''[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.<br />
* '''[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].<br />
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.<br />
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.<br />
** '''[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.<br />
* '''[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.<br />
** '''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.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.<br />
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.<br />
** '''description''': the text of the note.<br />
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.<br />
<br />
== [set_menu_item] ==<br />
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.<br />
<br />
'''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.<br />
<br />
* '''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.<br />
* '''description''': the in-game text that will appear for this item in the menu.<br />
* '''image''': the image to display next to this item.<br />
* '''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].<br />
* '''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<br />
* '''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. <br />
* '''[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.<br />
* '''[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.<br />
* '''[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:<br />
** '''key''': a string that contains the key to assign to this.<br />
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.<br />
** '''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.<br />
* '''[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.<br />
** '''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.<br />
<br />
== [clear_menu_item] ==<br />
<br />
Removes a menu item from the scenario.<br />
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).<br />
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.<br />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
<br />
=== [change_theme] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Change the current interface theme.<br />
<br />
* '''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 <b>1.14.2</b> 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).<br />
<br />
=== [item] ===<br />
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><br />
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)<br />
* '''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).)''<br />
* '''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).<br />
* '''name''' an id that can be used to remove the item.<br />
''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''<br />
or equivalently (requires Wesnoth 1.11.2+):<br />
''halo=scenery/fire[1~8].png:100''<br />
* '''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]])<br />
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.<br />
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.<br />
* '''[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]])<br />
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.<br />
<br />
=== [remove_item] ===<br />
Removes any graphical items on a given hex.<br />
* [[StandardLocationFilter]]: the hexes to remove items off<br />
* '''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.)<br />
* '''name''': removes an item with a previously defined name.<br />
<br />
=== [print] ===<br />
Displays a message across the screen. The message will disappear after a certain time.<br />
* '''text''': (translatable) the text to display.<br />
* '''size''': (default=12) the pointsize of the font to use<br />
* '''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.<br />
* '''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.<br />
<br />
=== [move_unit_fake] ===<br />
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.<br />
* '''type''': the type of the unit whose image to use<br />
* '''x''': a comma-separated list of x locations to move along<br />
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
* '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
* '''gender''': the gender of the fake unit. Example: gender=female<br />
* '''variation''': the variation of the fake unit. Example: variation=undead<br />
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.<br />
* '''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.<br />
<br />
=== [move_units_fake] ===<br />
moves multiple images of units along paths on the map. These units are moved in lockstep.<br />
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.<br />
* '''[fake_unit]''': A fake unit to move<br />
** '''type''': the type of unit whose image to use<br />
** '''x''': a comma-separated list of x locations to move along<br />
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
** '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
** '''skip_steps''': the number of steps to skip before this unit starts moving<br />
<br />
=== [hide_unit] ===<br />
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.<br />
* [[StandardUnitFilter]]: All matching units will be hidden<br />
<br />
=== [unhide_unit] ===<br />
Stops the currently hidden units from being hidden.<br />
* [[StandardUnitFilter]]: Only the matching units will be unhidden<br />
<br />
=== [lock_view] ===<br />
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.<br />
<br />
This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.<br />
<br />
{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.<br />
<br />
=== [unlock_view] ===<br />
Unlocks gamemap view scrolling for human players.<br />
<br />
=== [scroll] ===<br />
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.<br />
* '''x''', '''y''': the number of pixels to scroll along the x and y axis<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.<br />
<br />
=== [scroll_to] ===<br />
Scroll to a given hex<br />
* [[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.<br />
* '''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.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
<br />
=== [scroll_to_unit] ===<br />
Scroll to a given unit<br />
* [[StandardUnitFilter]]<br />
* '''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.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').<br />
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
<br />
=== [select_unit] ===<br />
Selects a given unit.<br />
* [[StandardUnitFilter]]: The first unit found will be selected.<br />
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)<br />
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').<br />
<br />
=== [sound]===<br />
Plays a sound<br />
* '''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.<br />
* '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
<br />
=== [sound_source] ===<br />
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.<br />
* '''id''': a unique identification key of the sound source<br />
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source<br />
* '''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<br />
* '''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)<br />
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged<br />
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded<br />
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source<br />
* '''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<br />
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center<br />
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)<br />
<br />
=== [story] ===<br />
{{DevFeature1.13|8}}<br />
<br />
Shows the story screen.<br />
* '''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.<br />
* '''[part]''': As [[IntroWML]].<br />
<br />
=== [remove_sound_source] ===<br />
Removes a previously defined sound source.<br />
* '''id''': the identification key of the sound source to remove<br />
<br />
=== [music]===<br />
Switches to playing different music<br />
* '''name''': the filename of the music to play (in ''music/'' as .ogg)<br />
* see [[MusicListWML]] for the correct syntax<br />
===[volume]===<br />
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100: <br />
* '''music''': Changes the music volume.<br />
* '''sound''': Changes the sound volume.<br />
=== [color_adjust]===<br />
Tints the color of the screen.<br />
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color<br />
=== [delay] ===<br />
Pauses the game.<br />
* '''time''': the time to pause in milliseconds<br />
* '''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.<br />
<br />
=== [redraw] ===<br />
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).<br />
* '''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).<br />
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.<br />
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.<br />
<br />
=== [unit_overlay] ===<br />
Sets an image that will be drawn over a particular unit, and follow it around<br />
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])<br />
* '''image''': the image to place on the unit<br />
<br />
=== [remove_unit_overlay] ===<br />
removes a particular overlayed image from a unit<br />
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])<br />
* '''image''': the image to remove from the unit<br />
<br />
=== [animate_unit] ===<br />
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).<br />
* '''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''<br />
* '''[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.<br />
* '''[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]].<br />
* '''[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.<br />
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)<br />
* '''text''': a text to hover during the animation <br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''': red value for the text color (0-255)<br />
* '''green''': green value for the text color<br />
* '''blue''': blue value for the text color<br />
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)<br />
* '''[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.<br />
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated<br />
<br />
=== [label] ===<br />
Places a label on the map.<br />
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)<br />
* '''text''': what the label should say<br />
* '''team_name''': if specified, the label will only be visible to the given team.<br />
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.<br />
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.<br />
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.<br />
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.<br />
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on<br />
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.<br />
<br />
=== [floating_text]===<br />
Floats text (similar to the damage and healing numbers) on the given locations.<br />
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.<br />
* '''text''': the text to display.<br />
<br />
The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:<br />
<br />
<pre><br />
# Float some golden yellow text at 20,20.<br />
[floating_text]<br />
x,y=20,20<br />
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"<br />
[/floating_text]<br />
</pre><br />
<br />
=== [deprecated_message] ===<br />
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.<br />
* '''message''': the message to show.<br />
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.<br />
* '''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<br />
* '''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. <br />
<br />
The meanings of the deprecation levels are as follows:<br />
<br />
# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.<br />
# It will be removed no earlier than a specified version.<br />
# It will be removed in the next stable version<br />
# It has already been removed, leaving just a stub to inform users of how to update their code.<br />
<br />
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.<br />
<br />
=== [wml_message] ===<br />
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.<br />
* '''message''': the message to show.<br />
* '''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.<br />
<br />
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.<br />
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).<br />
<br />
=== [test_condition] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
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.<br />
<br />
* '''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.<br />
* '''logger''': Same as for [wml_message]. Defaults to "warning".<br />
<br />
=== [open_help] ===<br />
Opens the in-game help.<br />
* '''topic''': the id of the topic to open<br />
=== [show_objectives] ===<br />
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.)<br />
* '''side''': the side to show the objectives. If not set, all sides are used.<br />
* '''[[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.<br />
<br />
=== [chat] ===<br />
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.<br />
* '''speaker''': (default="WML") A string for the name of the sender of the message.<br />
* '''message''': The message that should be displayed.<br />
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.<br />
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.<br />
<br />
=== [zoom] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Changes the zoom level of the map.<br />
<br />
* '''factor''': The new zoom factor<br />
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.<br />
<br />
== Useful Macros ==<br />
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].<br />
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units<br />
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations<br />
* '''{SET_IMAGE}''' Places an image on the map which has no other function.<br />
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.<br />
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.<br />
<br />
== See Also ==<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64395ReleasingWesnoth2019-09-14T07:27:54Z<p>Josteph: /* General maintenance */</p>
<hr />
<div>== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
* Announce to developers the string freeze start date (deadline for string changes) and the release cutoff date (deadline for commits)<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64390ReleasingWesnoth2019-09-12T06:22:14Z<p>Josteph: /* Preparation steps */</p>
<hr />
<div>== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent], and either [https://github.com/wesnoth/wesnoth/labels/Fwdport Fwdport] or [https://github.com/wesnoth/wesnoth/labels/Backport Backport] depending on what branch you're releasing) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64373SpellingMistakes2019-09-09T04:10:57Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
S18 "Your people have already saved me once from a watery death, noble merfolk," - this should be "noble mer" (or maybe "noble merman" / "noble mermaid" depending on the advisor's gender)<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
S2, intro text, "He knew it likely that the orcs would return with a vengeance and slaughter every last one of them." should be "He knew it was likely that the orcs...".<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
===Wings of Victory===<br />
drakipedia.txt "The drakes work metal, but are are masters in the craftsmanship of making ceramics." - Should only be one "are".<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=64307ReleasingWesnoth2019-09-07T07:21:37Z<p>Josteph: /* Preparation steps */ add github issues steps</p>
<hr />
<div>== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Review issues in the relevant labels (probably these? [https://github.com/wesnoth/wesnoth/labels/Blocker Blocker], [https://github.com/wesnoth/wesnoth/labels/Regression Regression], [https://github.com/wesnoth/wesnoth/labels/Urgent Urgent]) and milestones (for example, [https://github.com/wesnoth/wesnoth/milestone/9 1.15.2] and [https://github.com/wesnoth/wesnoth/milestone/13 1.16.0], if a development release; just [https://github.com/wesnoth/wesnoth/milestone/17 1.14.9], if a stable release).<br />
* Review the list of issues for the ''previous'' patch release (1.15.1 or 1.14.8), make sure it's empty.<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=HelpWML&diff=63865HelpWML2019-08-31T01:51:39Z<p>Josteph: /* Help System Topic Markup */</p>
<hr />
<div>{{WML Tags}}<br />
== The toplevel [help] tag ==<br />
<br />
The [help] tag describes the Wesnoth help system.<br />
Each of the three subtags [toplevel], [section] and [topic] describe an element of the help system.<br />
<br />
* '''[toplevel]''': The toplevel tag denotes sections and topics that should be shown immediately when the "Help" button is clicked on (see the "help" action, [[ThemeWML]]). The sections referenced within this tag are read recursively, including all subsections.<br />
** '''sections''': a list of IDs of the sections to include recursively.<br />
** '''topics''': a list of IDs of the topics to show as not being included in a section; i.e. top-level topics.<br />
* '''[section]''': The section tag describes a section in the help browser. A section contains subsections and/or topics.<br />
** '''id''': is the unique ID for this section.<br />
** '''title''': (translatable) is the title of the section. It is displayed in the left menu.<br />
** '''sections''': is a list of IDs of the sections that should be this section's subsections.<br />
** '''topics''': is a list of IDs of the topics that should be included in this section. Topics will be included in the order listed unless sorting is requested.<br />
** '''generator''': provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the '''topics''' key unless ''sort_topics'' is ''yes''.<br />
** '''sort_topics''': specifies whether or not to list the topics sorted by title or in the order listed on the '''topics''' key. '''yes''' indicates fixed and generated topics should be sorted together by title. '''no''' indicates that topics should appear in the order listed with fixed topics appearing before generated topics. '''generated''' indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is '''generated'''.<br />
* '''[topic]''': The topic tag describes one topic, i.e, one help page. The keys that are meaningful in the topic tag:<br />
** '''id''': is the unique ID for this topic.<br />
** '''title''': (translatable) is the title of the topic. It is displayed in the left menu and as a header in the text area.<br />
** '''text''': (translatable) is the contents of the topics. May contain markup described below.<br />
<br />
== Help System Topic Markup ==<br />
<br />
The markup that is allowed in the text key within a topic tag is in a WML-like markup language with angle brackets.<br />
<br />
It consists of plain text, interrupted with markup tags. Between paired start and end tags (like '''<jump> ... </jump>''') you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a ''text'' key. You can't nest tags within another tag.<br />
<br />
The following key/tags are accepted inside '''text''' ([https://github.com/wesnoth/wesnoth/blob/c09c58a8c8892d5f8392de48520a4f1b0ae1f35f/src/help/help_text_area.cpp#L126-L139 source]):<br />
* '''&lt;ref&gt;''': creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.<br />
** '''dst''': the ID of the topic to reference.<br />
** '''text''': the text to display as a link to '''dst'''; i.e. when '''text''' is clicked on the page '''dst''' will be linked to.<br />
** '''force''': shows the cross reference even though the referred topic is not shown.<br />
* '''<jump>''': when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.<br />
** '''to''': the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.<br />
** '''amount''': the number of pixels to jump forward<br />
* '''<img>''': insert an image in the topic<br />
** '''src''': the path to the image relative to the '''images/''' directory.<br />
** '''align''': the position of the image with respect to the page. Values are '''here''', '''left''', '''middle''', and '''right'''.<br />
** '''float''': whether the image should float(have text filled in around it) or not (be seen as included in a line).<br />
* '''<format>''': describes a group of text in a different format. Can be used to describe different colors and font sizes.<br />
** '''bold''': whether the text should be displayed in bold('''bold''').<br />
** '''italic''': whether the text should be displayed in italics(''italics'').<br />
** '''color''': the color of the text. Only a few colors are currently supported: '''white'''(default), '''green''', '''red''', '''yellow''', and '''black'''.<br />
** '''font_size''': the height of the text in pixels. Default 9(?)<br />
** '''text''': the text to be displayed using this format.<br />
* '''<italic>''': a shortcut to '''<format>''' which inputs only the '''text''' key. Uses the attribute '''italic=yes'''<br />
* '''<bold>''': like <italic>, but uses '''bold=yes'''<br />
* '''<header>''': like <italic>, but uses both the attributes '''bold=yes''' and '''font_size=13'''(?)<br />
<br />
Example:<br />
<syntaxhighlight lang=wml><br />
[help]<br />
[toplevel]<br />
sections=introduction,gameplay<br />
topics=about<br />
[/toplevel]<br />
[section]<br />
id=gameplay<br />
sections=combat<br />
topics=income_and_upkeep,time_of_day,terrain,victory_and_defeat<br />
[/section]<br />
[topic]<br />
id=terrain<br />
title=Terrain<br />
text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"<br />
[/topic]<br />
[topic]<br />
id=victory_and_defeat<br />
title= _ "Victory and Defeat"<br />
text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up<br />
box at the beginning of each scenario. Usually you will achieve<br />
victory by killing all enemy leaders, and only be defeated by having<br />
your leader killed. But scenarios may have other victory objectives<br />
— getting your leader to a designated point, say, or rescuing someone,<br />
or solving a puzzle, or holding out against a siege until a certain<br />
number of turns have elapsed." + _"<br />
<br />
When you win a scenario, the map grays over and the<br />
<bold>text='End Turn'</bold> button changes to<br />
<bold>text='End Scenario'</bold>. You can now do things like changing<br />
your save options or (if you are in a multiplayer game) chatting with<br />
other players before pressing that button to advance."<br />
<br />
[/topic]<br />
[/help]<br />
</syntaxhighlight><br />
<br />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=HelpWML&diff=63864HelpWML2019-08-31T01:50:48Z<p>Josteph: /* Help System Topic Markup */ Fix mediawiki syntax error</p>
<hr />
<div>{{WML Tags}}<br />
== The toplevel [help] tag ==<br />
<br />
The [help] tag describes the Wesnoth help system.<br />
Each of the three subtags [toplevel], [section] and [topic] describe an element of the help system.<br />
<br />
* '''[toplevel]''': The toplevel tag denotes sections and topics that should be shown immediately when the "Help" button is clicked on (see the "help" action, [[ThemeWML]]). The sections referenced within this tag are read recursively, including all subsections.<br />
** '''sections''': a list of IDs of the sections to include recursively.<br />
** '''topics''': a list of IDs of the topics to show as not being included in a section; i.e. top-level topics.<br />
* '''[section]''': The section tag describes a section in the help browser. A section contains subsections and/or topics.<br />
** '''id''': is the unique ID for this section.<br />
** '''title''': (translatable) is the title of the section. It is displayed in the left menu.<br />
** '''sections''': is a list of IDs of the sections that should be this section's subsections.<br />
** '''topics''': is a list of IDs of the topics that should be included in this section. Topics will be included in the order listed unless sorting is requested.<br />
** '''generator''': provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the '''topics''' key unless ''sort_topics'' is ''yes''.<br />
** '''sort_topics''': specifies whether or not to list the topics sorted by title or in the order listed on the '''topics''' key. '''yes''' indicates fixed and generated topics should be sorted together by title. '''no''' indicates that topics should appear in the order listed with fixed topics appearing before generated topics. '''generated''' indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is '''generated'''.<br />
* '''[topic]''': The topic tag describes one topic, i.e, one help page. The keys that are meaningful in the topic tag:<br />
** '''id''': is the unique ID for this topic.<br />
** '''title''': (translatable) is the title of the topic. It is displayed in the left menu and as a header in the text area.<br />
** '''text''': (translatable) is the contents of the topics. May contain markup described below.<br />
<br />
== Help System Topic Markup ==<br />
<br />
The markup that is allowed in the text key within a topic tag is in a WML-like markup language with angle brackets.<br />
<br />
It consists of plain text, interrupted with markup tags. Between paired start and end tags (like '''<jump> ... </jump>''') you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a ''text'' key. You can't nest tags within another tag.<br />
<br />
The following key/tags are accepted inside '''text''':<br />
* '''&lt;ref&gt;''': creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.<br />
** '''dst''': the ID of the topic to reference.<br />
** '''text''': the text to display as a link to '''dst'''; i.e. when '''text''' is clicked on the page '''dst''' will be linked to.<br />
** '''force''': shows the cross reference even though the referred topic is not shown.<br />
* '''<jump>''': when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.<br />
** '''to''': the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.<br />
** '''amount''': the number of pixels to jump forward<br />
* '''<img>''': insert an image in the topic<br />
** '''src''': the path to the image relative to the '''images/''' directory.<br />
** '''align''': the position of the image with respect to the page. Values are '''here''', '''left''', '''middle''', and '''right'''.<br />
** '''float''': whether the image should float(have text filled in around it) or not (be seen as included in a line).<br />
* '''<format>''': describes a group of text in a different format. Can be used to describe different colors and font sizes.<br />
** '''bold''': whether the text should be displayed in bold('''bold''').<br />
** '''italic''': whether the text should be displayed in italics(''italics'').<br />
** '''color''': the color of the text. Only a few colors are currently supported: '''white'''(default), '''green''', '''red''', '''yellow''', and '''black'''.<br />
** '''font_size''': the height of the text in pixels. Default 9(?)<br />
** '''text''': the text to be displayed using this format.<br />
* '''<italic>''': a shortcut to '''<format>''' which inputs only the '''text''' key. Uses the attribute '''italic=yes'''<br />
* '''<bold>''': like <italic>, but uses '''bold=yes'''<br />
* '''<header>''': like <italic>, but uses both the attributes '''bold=yes''' and '''font_size=13'''(?)<br />
<br />
Example:<br />
<syntaxhighlight lang=wml><br />
[help]<br />
[toplevel]<br />
sections=introduction,gameplay<br />
topics=about<br />
[/toplevel]<br />
[section]<br />
id=gameplay<br />
sections=combat<br />
topics=income_and_upkeep,time_of_day,terrain,victory_and_defeat<br />
[/section]<br />
[topic]<br />
id=terrain<br />
title=Terrain<br />
text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"<br />
[/topic]<br />
[topic]<br />
id=victory_and_defeat<br />
title= _ "Victory and Defeat"<br />
text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up<br />
box at the beginning of each scenario. Usually you will achieve<br />
victory by killing all enemy leaders, and only be defeated by having<br />
your leader killed. But scenarios may have other victory objectives<br />
— getting your leader to a designated point, say, or rescuing someone,<br />
or solving a puzzle, or holding out against a siege until a certain<br />
number of turns have elapsed." + _"<br />
<br />
When you win a scenario, the map grays over and the<br />
<bold>text='End Turn'</bold> button changes to<br />
<bold>text='End Scenario'</bold>. You can now do things like changing<br />
your save options or (if you are in a multiplayer game) chatting with<br />
other players before pressing that button to advance."<br />
<br />
[/topic]<br />
[/help]<br />
</syntaxhighlight><br />
<br />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=63863SpellingMistakes2019-08-31T00:47:50Z<p>Josteph: /* Heir to the Throne */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
Li'sar unit description says "This unit's grasp", it should say "This unit’s grasp" with a Unicode quote. (and add this to pofix)<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=How_to_play_Rebels&diff=63856How to play Rebels2019-08-30T22:24:54Z<p>Josteph: /* Rebels vs Khalifate */</p>
<hr />
<div>==General Rebel Strategies:==<br />
<br />
Diversify your starting recruit against a random opponent, e.g. a Scout, a Shaman, an Archer, two Fighters, and a Mage.<br />
<br />
[[Rebels]] have excellent defense in forests. A primary consideration for your strategy should be holding and leveraging available forest hexes.<br />
<br />
Your faction is largely compromised of the neutral Elves, but the Mage, Wose, and Merman are Lawful. You will be strongest in the day, but if your opponent is also lawful it is usually best to fight at night.<br />
<br />
Rebels have an abundance of ranged attacks in addition to the Dextrous trait on Elves. This enables frequent chances to attack without taking retaliation damage; it also guarantees any opponent attacking you will take some damage in return.<br />
<br />
Second only to the Drakes, Rebels have good mobility. The Scout has the highest level 1 movement in the game, and all of your Elves have the efficient woodland movetype. Attempt to take an early village advantage and later [[Glossary|ZOC]]ing your opponent's weakened units.<br />
<br />
The Elves bring multiple special abilities to the table. The Elvish Captain provides access to the Leadership trait, which can prove the difference when fighting an enemy at their chosen time of day. Shamans provide +4 healing and the ability to slow enemy units, a cornerstone of the Rebel strategy; their 70% defense in forests even allows them to provide effective front line support.<br />
<br />
==Rebels vs Drakes==<br />
Drakes are an incredibly offensive opponent: be careful of their extreme mobility and high damage. They want nothing more than to fight you on open ground, where they will massacre your fragile Elves. Denying terrain from Drakes is irrelevant in this matchup, but ensuring that you have the best possible terrain for key fights is critical. Their Saurians bring additional threats - magical attacks to force you out of the forest, and Skirmisher allows them to assassinate wounded units in your back line.<br />
<br />
Fortunately, you have the tools to turn the tide: your Mages, while impotent against the fiery Drakes, are a key counter to their Saurian underlings. You have an abundance of Piercing damage, which the Drakes fear. Your incredible defenses can turn the tide as the easily hit Drakes fall under a flurry of arrows as their blows fail to strike your forces of the forest. You will likely aggress at night, unless he has a horde of Saurians.<br />
<br />
'''Archer:''' Pierce is the best physical damage type against all Drakes, and the Archers bring that in bulk. Be judicious where you expose them as they are the most expensive unit you'll have on your front line most turns, but you need their raw damage to shred through the large health pools of the Drakes.<br />
<br> Rating:'''A''' <br />
<br />
'''Fighter:''' The most efficient unit on your side in terms of stats/gold, the Fighter is your best answer to his Burners, and will cut up Saurians if no Mages can safely do the job. Be careful as it is slower than the average Drake. If you need to sacrifice a unit, the Fighter will deal decent retaliation damage to any drake that hits it, weakening them for a counterstrike. Finally, if you get one to Captain, that will be a significant advantage in holding off the Drakes' chosen time of day.<br />
<br> Rating:'''A-''' <br />
<br />
'''Shaman:''' You need their slow, pure and simple. A slowed Drake is likely a dead Drake. Quick Shamans might be able to snipe a Clasher on the retreat and force a favorable engagement. You don't need their defensive abilities as much as Archers should be occupying most of your front line forest hexes, but their heal is always a welcome addition. If you can slow a Burner from a forest hex, that will significantly reduce retaliation from an Archer (though it's not worth it if that Archer must then attack from a flat hex, as the reduction in defense from 70% to 40% essentially doubles the damage you will take).<br />
<br> Rating:'''B+'''<br />
<br />
'''Merman Hunter:''' These fish will provide cover at sea. High defense, pierce, good movement - what's not to like? Recruit these as necessary for the map you are playing.<br />
<br> Rating:'''B'''<br />
<br />
'''Mage:''' Completely useless against the fireproof Drakes, one or two of these can still be a key recruit against a Saurian threat. If the Saurians never leave excellent cover, a Mage will be needed to efficiently dispatch them. Be careful, as Skirmishers are a high threat at night. Don't allow a Skirmisher to attack a Mage at night from good terrain if possible - you may not be able to safely counterattack the next turn.<br />
<br> Rating:'''B-'''<br />
<br />
'''Scout:''' While their ranged attack is satisfactory, they are not worth their cost in combat. One can be useful for scouting or [[Glossary|ZOC]]; on a larger map you may require one simply for efficient village acquisition. Two is likely one too many unless you have separated fronts.<br />
<br> Rating:'''C'''<br />
<br />
'''Wose:''' Only recruit this unit if you have a cluster of villages under constant Saurian threat. Too slow to catch Saurians, extremely vulnerable to Burners, and chopped down by Clashers and Fighters, your money is better spent elsewhere. At least it will absolutely murder any Saurian it manages to actually reach.<br />
<br> Rating: '''D-'''<br />
<br />
==Rebels vs Knalgans==<br />
<br />
Terrain denial is the most important aspect of this matchup. His Poachers will be trying to take your forests, while denying his hills and mountains is critical. Note that although you enjoy maximum defence on forests, it is generally preferable to occupy a hill/mountain hex even if there is forest nearby: dwarves have only 30% defence on forest, whereas you have 50% defence on hills. If you occupy forest instead, you will have the same defence as the dwarves—and they’re tougher. <br />
<br />
Shamans and Mages shine against the Dwarves. A Shaman in a forest hex has the defense and health of a thief with no physical vulnerabilities, and if she ever slows an Ulfserker you get a free kill - not that her slow is wasted on Fighters or Gryphons.<br />
<br />
Speaking of which, another effective strategy is attrition: use your slow to cripple the enemy’s hard hitting melee units, make use of healing to recover from the damage you receive, and feel free to take pot shots at your opponent when you can.<br />
<br />
Priority levelups continue to be Druids and Captains. Healing and Leadership greatly enhance the Elves' capabilities; the captain essentially negates the Dwarves' armor. The Knalgans don't have access to these abilities, so they will provide a large advantage.<br />
<br />
'''Shaman:''' Shamans, as always, are very useful for their healing and their slowing abilities. Gryphons and fighters are the best targets for their slow; whereas guardsmen are much weaker, and you don’t want to risk slowing a thunderer. A slowed ulf is a free kill, but beware that if the shaman fails to hit, she will be vulnerable to counterattack.<br />
<br> Rating:'''A'''<br />
<br />
'''Mage:''' Very useful for finishing off dwarves on good terrain, also effective against gryphons and outlaws. However, beware of ulfs.<br />
<br> Rating:'''A'''<br />
<br />
'''Fighter:''' Good staple unit; you need a couple of these to hold the line and guard your shamans/mages. They are superior to poachers—they deal more damage and, importantly, can grab forest hexes faster—and they are also effective aganinst thunderers and fighters, provided that the latter are slowed. Still, without the backup of shamans and mages these guys will succumb to your opponent’s tougher units.<br />
<br> Rating:'''A'''<br />
<br />
'''Archer:''' Perhaps not as effective in this matchup. You’ll want to focus on tougher and cheaper fighters (which can hold those important hill hexes better). You’ll also be making use of slow a lot; there is less need for the archers’ ranged attacks. Still, 70% defence on forest and 6MP give them some important uses. <br />
<br> Rating:'''B+''' <br />
<br />
'''Wose:''' The main use for this guy is attacking thunderers; he is also very effective against slowed gryphons. However, Dwarvish Fighters are cheaper, have much better defence, and deal 7–3 against your wose’s 10–2. Woses are also very slow—they’re not good for terrain denial. A utility unit, no more.<br />
<br> Rating: '''B'''<br />
<br />
'''Merman Hunter:''' This unit is weak, and a gryphon will beat it even in water. Only recruit if there’s a lot of water on the map; and if so, recruit at least 2 or 3 in order to surround a gryphon. If the knalgan player does commit to a water battle, rejoice: your cheap units will tie up his gryphons and eventually deliver victory.<br />
<br> Rating:'''C+'''<br />
<br />
'''Scout:''' A weak unit, but may be necessary to grab far-flung villages. Elvish archers deal significantly more damage, and quick ones will double up as scouts; however, the mounted elf’s extremely high mobility (9MP) does sometimes allow it to grab hold of a mountain, which can be very strategically useful. <br />
<br> Rating:'''C+'''<br />
<br />
==Rebels vs Loyalists==<br />
Your main problem when fighting loyalists is their spearmen. Relatively cheap, relatively tough, solid damage dealers (with a ranged attack and a special ability to boot) spearmen are difficult to defeat without woses. But with woses, the battle changes: it will be the loyalist opponent who will need to find ways to defeat the woses’ massive pierce resistance, high HP, damage and regeneration. Therefore, your tactics will be centred around the wose; your other units will provide the necessary mobility, village holding, and special extras to make up for the woses’ disadvantages. If it’s not already obvious: the wose is slow, and has abysmal defence on villages.<br />
<br />
Your enemy will spam a mix of cavalry and mages to deal with your woses, and spearmen (along with horsemen) against your other units. You may also see some heavy infrantry or fencers thrown in. Your prime target will be horsemen, as they are expensive, vulnerable to archers, but extremely dangerous to all of your units (barring the wose of course). Fighting at night is obviously a good idea; at day you should play neither defensively nor offensively, instead making use of forest and slow to survive the loyalist onslaught, and keeping the pressure on your opponent. Remember that your woses are also lawful, and will easily slaughter spearmen/bowmen/HI in the absence of mages and cavalry. The latter can easily be killed by your neutral elves, even at day.<br />
<br />
'''Fighter:''' Solid unit for the money, with a pretty good melee attack—a strong one will do the same damage as a strong spearman—and a pretty decent ranged attack as well. Your opponent will attempt to beat them with two strategies: either rush at you with spearmen and cavalry, at day, in order to overwhelm your fragile units with sheer force; or they may go down the heavy infantry route. Either strategy will succeed, so you will need other units to counter it. The best use you will generally have for fighters will be to hold villages and attack enemy ranged units (primarily mages).<br />
<br> Rating:'''B+'''<br />
<br />
'''Archer:''' Very effective against cavalry, good for attacking spearmen, and difficult to get off forest—mages will hurt themselves trying to kill it. (A dextrous archer may even kill a full health mage, with luck.) This unit is great; the downside is that it’s very vulnerable to horsemen charges, especially outside of forest. Spearmen will also overwhelm them without wose backup.<br />
<br> Rating:'''A''' <br />
<br />
'''Shaman:''' Shamans are useful for their healing, and their ability to slow heavy infantry, spearmen, and horsemen. On forest they even act as frontline units: they will dodge non-magical attacks and counter with slow against mages. The downside is that they’re weak, and you can’t slow every unit your enemy will throw against you.<br />
<br> Rating:'''B+'''<br />
<br />
'''Mage:''' Not that effective in this match-up. Mages are useful for attacking heavy infantry (although woses and shamans are perfectly capable of doing that) and have magic. But the archer remains a much better choice: the mage is significantly slower, its attacks aren’t as effective against cavalry, and of course it is both more expensive and more fragile than the elf. Recruit maybe one, no more.<br />
<br> Rating:'''C+'''<br />
<br />
'''Wose:''' Against loyalists, this guy is a monster. He destroys spearmen and bowmen; he crushes heavy infantry. Even mages are vulnerable to him—two strikes from a wose will kill a mage, while three hits from a mage will not kill a wose, despite the wose’s grievious weakness to fire. Therefore, the enemy will protect his mages with impact-resistant cavalry; it will be combined arms that brings this unit down. You will need to use your other units to hold villages, destroy cavalry, and make up for this unit’s poor mobility.<br />
<br> Rating: '''A'''<br />
<br />
'''Merman Hunter:''' This unit is okay against the enemy’s merman fighters, and it’s effective against cavalry. Recruit according to the water. <br />
<br> Rating:'''B'''<br />
<br />
'''Scout:''' Useful for its mobility and ranged pierce attacks; its main use will be grabbing villages, and providing the extra hit to kill a cavalryman or mage. That said, they are torn apart by horsemen and spearmen.<br />
<br> Rating:'''C+'''<br />
<br />
==Rebels vs Northerners==<br />
<br />
The Northerner units are your antithesis: tough instead of weak, melee orientated instead of range orientated, and fast where you are slow; slow where you are fast. When fighting them, you need to be aware of their ability to outmaneouvre you on hills and mountains—but conversely, they will struggle to reach forested hexes. Your strategy will require careful use of leadership and unit traits: without them you will not be able to do sufficient damage to kill an orc or troll outright. A strong/dextrous archer/fighter will do 20% more damage over base, and this rises further with leadership. Since grunts have 38 base HP, the extra damage will often mean the difference between a dead grunt and a still-dangerous grunt (to your shamans, mages and archers).<br />
<br />
The Northerner units have two special abilities you will need to counter: poison and regeneration. You need to recruit shamans and keep them behind your front lines—that way the assassins’ poison won’t activate. Since poisoned units lose 8HP per turn, while shamans heal only +4HP per turn, this is a good trade-off. As for trolls, the trick is to take out their supporting units first, and then focus your attacks on them en masse. <br />
<br />
'''Elvish Fighter:''' A staple unit. Their blades will kill orcish archers and assassins, and defend against grunts, wolves and trolls. They are the most cost effective unit in your arsenal; this is important when fighting Northeners, as their units are very economical. <br><br />
''Rating: A''<br />
<br />
'''Elvish Archer:''' Another staple unit. Their arrows will kill any Northerner foe that’s not an assassin or an archer. They are fast; they are hard to take off forest. The only real downside is their low HP, which make them vulnerable outside of good terrain. <br><br />
''Rating: A''<br />
<br />
'''Elvish shaman:''' Their healing is invaluable against poison; their slow finds excellent targets in grunts, trolls and wolves. Low HP remains a problem though. <br><br />
''Rating: A''<br />
<br />
'''Elvish Scout:''' This unit is usually quite crummy, and while its attacks remain rather weak, they serve some very important uses in this matchup. Their extreme mobility often allows them to attack from a fourth hex; this can make the difference between a dead orc and a live one. They are fast enough to grab mountains and deny it from your enemy. They are reasonably effective against enemy wolves, and will harrass most Northerner units with their bow. Still not as good a buy as your other units, but don’t dismiss him either. <br><br />
''Rating:'' B<br />
<br />
'''Mage:''' The mage is invaluable for their ability to kill trolls and assassins; grunts and wolves also make great targets. It is often preferable to kill an assassin even if your mage gets poisoned: you can keep the poison from damaging them by placing a shaman next to them, and their ranged attacks will allow them to wound (and kill) even with 1HP. The downside to this unit is that’s very vulnerable—at night it needs to be carefully protected, or even just kept out of the way behind your lines. <br><br />
''Rating: A''<br />
<br />
'''Wose:''' Not the best buy for this matchup. Only recruit him if the enemy goes overboard with trolls—otherwise he is burned by orchish archers and cut down by grunts (and even wolves). His poor mobility and lawful alignment work against him: he’s too slow to press the attack at day, and likewise too slow to retreat at night. <br><br />
''Rating: C+''<br />
<br />
'''Merman Hunter:''' Not a bad unit. His throwing spears will harass the enemy’s numerous melee units—sometimes this will even be enough to let one of your land units make the kill, particularly if your merman is the 4th hex attacker. He has two downsides: he fights terribly on land, and his attacks are quite weak. That’s why you should give XP to your landlubbers; it’s much more useful to have a Druid, Captain, Marksman, etc. over a unit that’s only good on water. Beware of assassins’ poison, and float the hunter next to a shaman if he does get poisoned. <br><br />
''Rating: B''<br />
<br />
==Rebels vs Rebels==<br />
TODO<br />
<br />
'''Fighter:''' TODO<br />
<br> Rating:'''A-'''<br />
<br />
'''Mage:''' TODO<br />
<br> Rating:'''A-'''<br />
<br />
'''Wose:''' TODO<br />
<br> Rating: '''B+'''<br />
<br />
'''Archer:''' TODO<br />
<br> Rating:'''B''' <br />
<br />
'''Shaman:''' TODO<br />
<br> Rating:'''B-'''<br />
<br />
'''Merman Hunter:''' TODO<br />
<br> Rating:'''B-'''<br />
<br />
'''Scout:''' TODO<br />
<br> Rating:'''C'''<br />
<br />
==Rebels vs Undead==<br />
The Undead have very specific resistances and vulnerabilities, so many of your units are less useful<br />
<br />
'''Mage:''' This will be your primary ranged unit. It's one of your most expensive units, but it's worth it for its fire attack. It has a ranged magical attack as well, so you can hit units even when they have good defense. You do have to remember that this unit is lawful, so you have to use it during favorable times, and keep it out of the way when unfavorable..<br>''Rating: A''<br />
<br />
'''Shaman:''' This unit is always helpful, because it has the healing ability. Although it isn't much, it can sometimes save your other units, especially when operated in pairs behind your lines. They also have the ''Slows'' ability, which can be used against their '''Skeletons'''. You can also slow Ghouls, however it won't be as effective because the Ghoul's main weapon is Poison, not its attacks. Their weapons are impact, too, so they'll do more damage then normal..<br>''Rating: A-''<br />
<br />
'''Wose:''' Even though Woses look awesome against the undead, with their high damage impact attack and regeneration, fight the urge to spam them. They're so slow that a good player will be able to outmaneuver you and kill you easily in the night. <br>''Rating: B.''<br />
<br />
'''Fighter:''' These guys have a blade attack and a secondary pierce attack. Against undead, you want a couple for village holding and damaging Dark Adepts, however don't go overboard with them.<br>''Rating: B-''<br />
<br />
'''Archer:''' This unit has a good pierce attack and a decent blade attack. Normally this unit is excellent, but against undead he doesn't do near as much damage. The only reason to recruit this unit would be for it's high movement points, and for the 17 gold required, you may as well recruit a <br />
'''Scout'''. Don't recruit this unit, spend your gold elsewhere.<br>''Rating: D-''<br />
<br />
'''Hunter:''' This unit normally has fairly bad attacks, and then since they're both pierce, the undead's resistances make them even worse. They can be used to quickly grab water villages and hold them, but other than that they're just cruddy against '''Undead'''..<br>''Rating: F+''.<br />
<br />
==Rebels vs Khalifate==<br />
<br />
'''Note:''' The "khalifate" faction was renamed "Dunefolk" in 1.14. Furthermore, the same faction kept the name but was ''completely rebalanced'' in 1.15/1.16, so some of below may no longer be applicable (even after accounting for the unit renames in 1.14).<br />
<br />
Fighting these guys is tricky, but your old tricks are useful once more. Generally, your main problem will be the Khalifate’s HP—as usual, they have more of it than you, and the Arif in particular is a hard nut to crack. Khalifate also love hills; as when fighting dwarves, keep an eye out on opportunistic hill-grabs.<br />
<br />
Unlike when fighting dwarves—and this here is crucial—you must not fall into the trap of holding hills at the expense of forests. The Khalifate enjoys a 20% boost in defence, but dwarves enjoy a 30% boost; and while you can beat the latter by holding onto hills, this doesn’t work so well in the case of the desert-men.<br />
<br />
Expect to see lots of Arif—their marksman ability is very dangerous to archers, shamans, and even fighters. They’re also pretty damn tough. The catch? They’re pricey, and have no ranged attack.<br />
<br />
But don’t fool yourself into thinking you can outmaneouvre them and pepper them with arrows until they die. That works against dwarvish fighters, but dwarvish fighters have to go through your defence. Try this against Arifs, and they’ll kill you before you can kill them.<br />
<br />
The solution? Slow. Their high price means you can slow most of them, and they’re weak to impact—ideal targets for Woses. <br />
<br />
If an Arif manages to grab a hill, don’t try and engage it—even on forest. Rather, focus your attention on other units; try to lure them off it. At the expense of contradicting previous advice, the Arif is the one unit you should really try to keep off hills. <br />
<br />
Discretion still applies; if you can kill them with a mage, it may be worth the risk.<br />
<br />
The rest of the Khalifate faction is relatively ambidextrous in both melee and ranged—be prepared for more retaliation than usual. Shamans, unsurprisingly, are good for this.<br />
<br />
Recruitment-wise:<br />
<br />
'''Shaman:''' Slow and heal are even more powerful than usual, while some Khalifate units are weak to impact. Provided that there are no Arif nearby, this unit also survives well on forest. Get some. But remember: you’ll need to do a lot more damage than what these girls can do, if you want to win that is. <br> ''Rating: B+''<br />
<br />
'''Archer:''' Their high mobility is very useful for grabbing those important forest (and hill) hexes; their ranged attacks are useful against Arif and Hakim, while the Khalifate mounted units are weak to pierce. A good unit. Beware of attacking Jundi and Rami at dawn/dusk though—conversely, they’ll struggle getting you off forest with those. <br> ''Rating: A''<br />
<br />
'''Fighter:''' They’re useful against Rami and Jundi, and can be used to attack Arif and Naffat at night. They’re also cheaper than Khalif units, which can get you a useful numerical advantage. Still: their lesser mobility is a downside here, and the Khalifate has better resistance against blade than pierce. <br>''Rating: B+.''<br />
<br />
'''Mage:''' Their magical ranged attacks are very useful against arif and hakim, but this unit is fragile and vulnerable to counterattack. They serve a very useful function, but don’t go overboard with them. <br> ''Rating: B+''<br />
<br />
'''Wose:''' These guys are devastating against Rami, and also against Jundi and Hakim. At day they will crush them (literally). Slowed Arif are prime targets for their impact attacks, but don’t risk it otherwise. Woses, sadly, lack for blade resistance—but Arif will hesitate at the 14-2 counter attack. The only real danger to this unit is the Naffat. Try and kill those. <br> ''Rating: A-''<br />
<br />
'''Mermen Hunter:''' Already rather weak to begin with, the Hunter’s efficacy is further eroded by Arif marksmen and Rami retaliation. Use sparingly. <br> ''Rating: C+''<br />
<br />
'''Scout:''' He doesn’t fare well against Rami—the Khalif’s primary scout. Nor is he much better against the other Khalif units. Try and use archers instead. <br> ''Rating: C+''<br />
<br />
==See also==<br />
[[How to play Mages]]<br />
<br />
{{Factionbox}}<br />
<br />
[[Category:How to Play]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=CampaignWML&diff=63320CampaignWML2019-08-15T23:08:25Z<p>Josteph: /* The [campaign] Tag */ elaborate</p>
<hr />
<div>{{WML Tags}}<br />
<br />
<!--<br />
<br />
Dacyn and/or Invisible Philosopher -- please be careful<br />
you don't reduce the signal-to-noise ratio on the WML pages<br />
when editing! Eg. knowing that a tag is translatable is _important_<br />
for the 29 translations we have in progress. -- ott<br />
<br />
--><br />
<br />
This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.<br />
<br />
==The [campaign] Tag==<br />
<br />
The following keys and tags are recognized in '''[campaign]''' tags:<br />
* '''id''': the internal campaign identifier used to classify saved games<br />
* '''icon''': the image displayed in the campaign selection menu<br />
* '''name''': (translatable) name displayed in the campaign selection menu<br />
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign<br />
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)<br />
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu<br />
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".<br />
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".<br />
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.<br />
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. Currently supported extra_defines are:<br />
<ul><br />
;ENABLE_ARMAGEDDON_DRAKE<br />
:allows the advancement ''Inferno Drake'' -> ''Armageddon Drake''<br />
;ENABLE_DWARVISH_ARCANISTER<br />
:allows the advancement ''Dwarvish Runemaster'' -> ''Dwarvish Arcanister''<br />
;ENABLE_DWARVISH_RUNESMITH<br />
:allows the advancement ''Dwarvish Fighter'' -> ''Dwarvish Runesmith''<br />
;DISABLE_GRAND_MARSHAL<br />
:disallows the advancement ''General'' -> ''Grand Marshal''<br />
;ENABLE_ANCIENT_LICH<br />
:allows the advancement ''Lich'' -> ''Ancient Lich''<br />
;ENABLE_DEATH_KNIGHT<br />
:allows the advancement ''Revenant'' -> ''Death Knight'<br />
;ENABLE_TROLL_SHAMAN<br />
:allows the advancement ''Troll Whelp'' -> ''Troll Shaman''<br />
;ENABLE_WOLF_ADVANCEMENT<br />
:allows the advancements ''Wolf'' -> ''Great Wolf'' -> ''Direwolf''<br />
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}<br />
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''<br />
;ENABLE_WARMASTER {{DevFeature1.13|11}}<br />
:allows the advancement ''Dune Blademaster'' -> ''Dune Warmaster''<br />
:Note: This macro doesn't work for 1.15.0 and later as Dunefolk were revamped in 1.15.0. (In particular, the Warmaster was renamed Paragon, and the name "Dune Warmaster" now refers to a lvl3 unit that didn't exist in 1.14.)<br />
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}<br />
:allows the advancement ''Wose'' -> ''Wose Shaman''<br />
</ul><br />
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.<br />
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=<br />
* '''[difficulty]''': {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:<br />
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.<br />
** '''image''': the image to display for this difficulty in the selection menu<br />
** '''label''': a flavor label describing this difficulty. Displayed second after the image<br />
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.<br />
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.<br />
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.<br />
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes<br />
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]<br />
* '''[options]''': {{DevFeature1.13|1}} Allows configuration options to be displayed to the user, see [[OptionWML]]<br />
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) '''''(Version 1.14.6 and later only)''''' a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.<br />
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.<br />
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.<br />
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given. <br />
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.<br />
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.<br />
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".<br />
* '''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.<br />
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.<br />
<br />
The following keys are additionally recognized in multiplayer:<br />
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.<br />
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.<br />
* '''allow_era_choice''': Whether to hide era selection and use a default one when creating a game. Defaults to ''yes''.<br />
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.<br />
<br />
== Campaign credits ==<br />
<br />
The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag, but none of them will display credits if there is no "id" key present inside [campaign] (see above). The '''[about]''' tag has the following keys:<br />
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits<br />
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names<br />
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)<br />
** '''name''': The name of the contributor<br />
** '''comment''': Optional short note about what that person did<br />
** '''email''': Optional email address<br />
** '''wikiuser''': Optional, the user name on the wiki<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ScenarioWML]]<br />
* [[ReferenceWML]]<br />
* [[PblWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=ReleasingWesnoth&diff=63296ReleasingWesnoth2019-08-14T19:48:59Z<p>Josteph: /* General maintenance */ Add campaignd step for minor releases</p>
<hr />
<div>== Tools ==<br />
<br />
Tools needed for releasing:<br />
* Normal tools to build everything from Wesnoth and to fetch the repository head (cmake based assumed for this page!)<br />
* <code>po4a</code> (to be able to update the manpages and manual)<br />
* <code>docbook-xml-dtd</code> (to generate the manual HTML files)<br />
* <code>xdelta</code> 1.x (to create the Xdelta files)<br />
* <code>rsync</code> for upload of tarballs<br />
<br />
Tools for other processes:<br />
* <code>optipng</code> (only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>imagemagick</code> (tool <code>convert</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
* <code>advancecomp</code> (tool <code>advdef</code>, only for needed to run <code>utils/wesnoth-optipng</code>, not for normal releases)<br />
<br />
== General maintenance ==<br />
<br />
Not strictly release associated though the pot-update part should be done right before every release.<br />
<br />
* Run <code>utils/wesnoth-optipng</code> from the main directory of the checkout every now and then (read: <b>very</b> rarely, because it enlarges the Git repository for <i>very</i> negligible reductions in distribution size), requires the packages optipng, imagemagick and advancecomp<br />
* Run a <code>pot-update</code> regularly, once shortly before the release and before each string-freeze (including string-freezes in preparation for stable releases). This involves the following steps as of 1.13.3:<br />
<br />
# target "pot-update" regenerates pot files and updates po files according to them<br />
# target "update-po4a" reruns po4a for man pages and manual<br />
# target "manual" regenerates manual<br />
scons pot-update update-po4a manual<br />
<br />
# Make sure that no new files were created in doc/, if new manpages/manuals were created, add them<br />
git status doc/<br />
<br />
# Commit the bunch of updated po files and manpages/manuals<br />
git commit doc/ po/<br />
<br />
(the following commands should be run but are usually forgotten...)<br />
* Run <code>make lint</code> inside <code>data/tools</code> (runs <code>wmllint</code> with appropriate options), fix warnings or prod campaign and content maintainers as needed<br />
* Run <code>make reindent</code> from <code>data/tools</code> to reindent all mainline WML according to our conventions (probably don't want to do this too often as it may inconvenience coders)<br />
* Have a look at the pages from the category [[:Category:Review_on_Release|Review on Release]]<br />
* If it's a 1.foo.0 release, start a new campaignd instance on add-ons.wesnoth.org and update the port numbers as in https://github.com/wesnoth/wesnoth/commit/211f14176ce57509003ca4542d388c526157093c<br />
<br />
== Release tasks ==<br />
<br />
=== Preparation steps ===<br />
* Merge the fixes on [[SpellingMistakes]]<br />
* Make sure to run and commit a pot-update (see above), and update to the latest revision of the branch if needed. At this point you should warn people to stop pushing commits to the branch you'll be using for the release so as to avoid last-minute work sync issues or new unexpected bugs.<br />
* Check <code>changelog</code> and <code>players_changelog</code> for completeness and correctness, line wrap to 80 columns.<br />
* Bump the version numbers in <code>src/wesconfig.h</code>, <code>Doxyfile</code>, <code>changelog</code>, <code>players_changelog</code>, and <code>projectfiles/Xcode/Info.plist</code> and commit. Note that as of version 1.13.2 there are additional <code>RC_VERSION_*</code> macros in <code>src/wesconfig.h</code> needed by Windows builds. Since unlike <code>VERSION</code> these aren't freeform values, they should represent the next release version whenever <code>VERSION</code> represents an in-dev version (e.g. if <code>VERSION</code> is <code>1.13.2+dev</code>, the <code>RC_VERSION_*</code> macros should have the values for <code>1.13.3</code> instead).<br />
<br />
=== Generating the files ===<br />
<br />
# Update the git checkout, just to be sure that you have the<br />
# latest version<br />
<br />
git pull --rebase<br />
<br />
# Export the git checkout into a release tar archive (substitute<br />
# $VERSION with the release version number and $BRANCH with the<br />
# source branch). This will automatically exclude unwanted<br />
# directories from the archive following export-ignore rules in<br />
# .gitattributes<br />
<br />
git archive --format=tar --prefix="wesnoth-$VERSION/" $BRANCH > "wesnoth-$VERSION.tar"<br />
<br />
# Create the xdelta patch for the archives (this assumes that the<br />
# uncompressed $OLDVERSION tar archive is present!)<br />
<br />
xdelta delta wesnoth-$OLDVERSION.tar wesnoth-$VERSION.tar wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta<br />
<br />
# Compress the tarball<br />
<br />
bzip2 wesnoth-$VERSION.tar<br />
<br />
# Create the SHA256 sum for the tarball<br />
<br />
sha256sum wesnoth-$VERSION.tar.bz2 > wesnoth-$VERSION.tar.bz2.sha256<br />
<br />
== File upload ==<br />
<br />
The following files should be ready for upload now:<br />
<br />
* <code>wesnoth-$VERSION.tar.bz2</code><br />
* <code>wesnoth-$VERSION.tar.bz2.sha256</code><br />
* <code>wesnoth-$OLDVERSION.tar-wesnoth-$VERSION.tar.xdelta</code><br />
<br />
You must upload these files to SourceForge.net and to <code>files.wesnoth.org/releases/</code> (as backup). Since the tarballs are very large it's recommended to use rsync via SSH instead of web uploads to guarantee their integrity. After uploading to wesnoth.org it might save time to rsync to SF.net from there.<br />
<br />
For uploading to wesnoth.org, you will need to ask the site administrators for help with setting up your SSH configuration, as well as determining the destination path for the files.<br />
<br />
# Upload to files.wesnoth.org (path for reference purposes only,<br />
# does not reflect actual server set-up).<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>@wesnoth.org:WWW/html/files/<br />
<br />
# Upload to SF.net:<br />
#<br />
# * STREAM: replace with 'wesnoth' for development releases and<br />
# 'wesnoth-X.Y' for a stable release of the X.Y series.<br />
# * RELEASENAME: replace with the release name, e.g.<br />
# 'wesnoth-X.Y.Z'.<br />
<br />
rsync -avP -e ssh <FILES> <USERNAME>,wesnoth@frs.sourceforge.net:/home/frs/project/w/we/wesnoth/<STREAM>/<RELEASENAME><br />
<br />
== Build the release for testing ==<br />
<br />
You can build the release for testing while the upload is in progress. Before installing the test build make sure that no old leftover files are there, and also remove the old preferences or (preferably) use the <code>utils/wesnoth-defaults</code> script found in the repository to use a throwaway preferences dir.<br />
<br />
# Depending on whether you already compressed the tarball or not<br />
tar -xvf wesnoth-$VERSION.tar<br />
tar -xvf wesnoth-$VERSION.tar.bz2<br />
<br />
cd wesnoth-$VERSION && mkdir build && cd build<br />
<br />
# CMake command to create a test build with suffix -X.Y.Z to be<br />
# installed to /opt/wesnoth-X.Y.Z instead of /usr/local<br />
cmake .. \<br />
-DCMAKE_INSTALL_PREFIX=/opt/wesnoth-X.Y.Z \<br />
-DENABLE_SERVER=TRUE \<br />
-DENABLE_CAMPAIGN_SERVER=TRUE \<br />
-DPREFERENCES_DIR=.wesnoth-X.Y.Z \<br />
-DBINARY_SUFFIX=-X.Y.Z \<br />
-DENABLE_NOTIFICATIONS=TRUE \<br />
-DENABLE_STRICT_COMPILATION=TRUE<br />
<br />
# Build<br />
make -j<N><br />
<br />
# install<br />
sudo make install<br />
<br />
Now cd somewhere else and run the installed copy of the game (e.g. <code>/opt/wesnoth-X.Y.Z/bin/wesnoth</code>). Running right from the sources is '''not''' enough to be sure that everything works as expected.<br />
<br />
== Test the build ==<br />
This at least includes the following:<br />
<br />
* Start the editor, check if creating a map is possible<br />
* Start the game and try to connect to the official multiplayer server and to the add-on server<br />
* Start the server, connect to it using the game to see if you can enter the lobby<br />
* Check if in the game each campaign does start<br />
* Check if you can start the in-game help and the credits<br />
* Check if it is possible to create a local game<br />
* Play at least one game/scenario (or droid your side to let the AI play), this can either be a normal campaign scenario or a multiplayer game<br />
<br />
If all of those points are working as expected, go on, if not, fix the problems and restart from the very beginning.<br />
<br />
== Tagging and extra release related steps ==<br />
<br />
If everything works as expected, tag your release. Just use the version number (e.g. <code>1.13.2</code> or <code>1.14.0</code>) for the tag, no need to add <code>wesnoth-</code> in front:<br />
<br />
git tag -a -m "Wesnoth $VERSION" $VERSION HEAD && git push $VERSION<br />
<br />
Update [http://www.wesnoth.org/macro-reference.html macro-reference.html]:<br />
<br />
cd data/tools/<br />
make macro-reference.html<br />
scp macro-reference.html wesnoth@wesnoth.org:WWW/html/macro-reference.html<br />
<br />
Regenerate the game credits and paste the contents to [[Credits]] on the wiki:<br />
<br />
data/tools/about_cfg_to_wiki -w <PATH TO GAME EXECUTABLE> > about.wiki<br />
<br />
== Notify packagers ==<br />
<br />
Once all steps above are done and the upload to sourceforge is finished, you still need to notify the packagers. The announcement should include the important changes for packagers (especially path, dependencies, and other build-time changes), as well as the SHA256 checksum of the tarball attached.<br />
<br />
For the current list of packagers, check <code>/scratch/packagers-list</code> on the files.wesnoth.org filesystem.<br />
<br />
'''NOTE:''' Make sure that our "tier 1" packagers (currently Windows and OS X) whose content is hosted by us on SF.net upload the SHA256 sums of their files to files.wesnoth.org/releases/ as well!<br />
<br />
=== Example messages ===<br />
<br />
==== Development version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new feature release in the X.Y.x development series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
Nothing has changed for packagers in terms of dependencies or install <br />
locations in this release.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
==== Stable version ====<br />
Subject: Wesnoth X.Y.Z is out!<br />
<br />
Hello,<br />
<br />
Wesnoth X.Y.Z, a new maintenance release in the X.Y.x stable series, is out <br />
now.<br />
<br />
The sources are already available on SourceForge.net, and files.wesnoth.org <br />
(for backup or in case you don't trust the authenticity of the files on <br />
SF.net). We will announce the release within the next 72 hours. In the <br />
meantime you can create and upload your packages.<br />
<br />
As this is a stable maintenance release, nothing has changed for packagers in<br />
terms of dependencies or install locations.<br />
<br />
Thank you for your contribution to Wesnoth!<br />
<br />
== Cleanup and post release steps ==<br />
<br />
Bump the version numbers in the files mentioned above in the release preparation steps and commit your changes. Consider deleting the test build, tarball, xdelta, etc. from your filesystem as needed.<br />
<br />
Contact shadowm or Soliton to update the MP servers' configuration to allow users of the new release or rebuild the servers as needed (only required for development releases).<br />
<br />
== The real announcement ==<br />
<br />
Prepare the real announcement forum post for the day it is to be posted. To do so copy the last announcement from the release thread into the hidden forum (edit, then copy & paste). Edit the new copy to match the new release as needed, and leave it there for fixes and comments until the time for the real announcement comes. Make sure to use the items from <code>RELEASE_NOTES</code> (which you will purge after the final announcement is published).<br />
<br />
You should also prepare the front page/News forum post in advance.<br />
<br />
Wait until the announcement conditions are met (waited at least 24 hours and OS X and Windows builds are ready OR 72 hours passed).<br />
<br />
When ready to make the announcement public, do the following:<br />
<br />
* Update [[Download]] in the wiki (currently takes the relevant contents from [[Template:StableDownload]] and [[Template:DevDownload]]).<br />
* Post the contents of the new announcement post to the Release forum section as a new 'Announcement' topic.<br />
* Set the previous announcement to a 'Normal' topic and lock it.<br />
* Post the new News forum post to the News forum section.<br />
* Update the wesnoth.org front page (yes, this has to be done by hand, I know, it sucks ― shadowm):<br />
** Change versions, sizes, and links in the overview section to point to the latest version.<br />
** Update the front page news section with an HTML version of the News forum post.<br />
** If the front page news section is getting too large, remove some of the oldest posts.<br />
* Copy the new news to [[Older_News]].<br />
* Update topics on IRC and post to social media (Twitter, etc.) as applicable.<br />
* Clean up <code>RELEASE_NOTES</code> in the repository so it only contains the template for the next release.<br />
<br />
[[Category:Development]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=63229SpellingMistakes2019-08-13T21:45:58Z<p>Josteph: /* Units */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
Cavalier description "... is fearsome; and they..."<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=UnitsWML&diff=62291UnitsWML2019-07-18T13:39:39Z<p>Josteph: /* [movetype] */ Add screenshot example of jamming</p>
<hr />
<div>{{WML Tags}}<br />
<br />
The '''[units]''' tag is a [[ReferenceWML#WML_toplevel_tags|top-level WML tag]] which defines the unit types that will be available in the game.<br />
<br />
A [units] tag primarily contains [[UnitTypeWML|[unit_type]]] tags, each of which defines one unit type, and can also contain other tags, which mostly provide definitions of things like races and movement types that are used in unit type definitions.<br />
<br />
== Subtags of [units] ==<br />
<br />
The following tags can be used as subtags of a [units] tag.<br />
<br />
=== [unit_type] ===<br />
<br />
{{Main|UnitTypeWML}}<br />
<br />
In a [units] tag, a [unit_type] tag defines a unit type.<br />
<br />
=== [trait] ===<br />
<br />
The [trait] tag describes a trait. When it appears in the [units] toplevel, it describes a global trait, and all races with the attribute '''ignore_global_traits=no''' will have this trait.; it may also appear in other places.<br />
* '''id''': unique identifier<br />
* '''availability''': describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (''undead'' and ''mechanical'') default from a unit type's race. Ideally someone will eventually extend ''race'' to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)<br />
* '''male_name''': text displayed in the status of unit with the trait if the unit is male.<br />
* '''female_name''': text displayed in the status of unit with the trait if the unit is female.<br />
* '''name''': text displayed in the status of unit with the trait if none of the two above is used.<br />
* '''description''': text displayed for the description of the trait when moving the cursor over the trait.<br />
* '''help_text''': {{DevFeature1.13|6}} text displayed for the description of the trait in the help. Defaults to ''description'' if not specified.<br />
* '''[effect]''': described in [[EffectWML]]. More than one of these can be used.<br />
<br />
=== [movetype] ===<br />
<br />
The [movetype] tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.<br />
* '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.<br />
* '''flies''': either 'true' or 'false'(default). A unit with ''flies=true'' does not have its image's height adjusted for different terrains.<br />
* '''[movement_costs]''': describes how fast the unit moves on different terrains. The attribute '''terrain=''speed''''' means that the unit will need to use ''speed'' move points to move onto terrain with '''id=''terrain''''' (see [[TerrainWML]]).<br />
* '''[vision_costs]''': describes how far the unit clears fog and shroud on different terrains. The attribute '''terrain=''cost''''' means that the unit will need to use ''cost'' vision points to view into terrain with '''id=''terrain''''' (see [[TerrainWML]]). (If not specified for a particular terrain, the vision cost defaults to the movement cost.)<br />
* '''[jamming_costs]''': {{DevFeature1.13|0}} describes how far the unit interferes with the vision of other units over different terrains. This works the same as movement and vision costs. [https://forums.wesnoth.org/viewtopic.php?f=21&t=44577&p=644985#p644985 Example of jamming]<br />
* '''[defense]''': describes how likely the unit is to be hit on different terrains. The attribute '''terrain=''defense''''' means that the unit will be hit ''defense'' percent of the time in the terrain with '''id=''terrain'''''. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.<br />
* '''[resistance]''': describes how much damage the unit takes from different types of attacks. The attribute '''type=''resistance''''' makes the unit receive '''resistance''' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.<br />
<br />
Default keys for the [movement_costs], [vision_costs], and [defense] tags are deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable. Default keys for [resistance] are blade, pierce, impact, fire, cold, and arcane.<br />
<br />
=== [race] ===<br />
<br />
The [race] tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.<br />
* '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.<br />
* '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.<br />
* '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.<br />
* '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.<br />
* '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' '''must''' be supplied.<br />
* '''description''': description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.<br />
* '''name_generator''' {{DevFeature1.13|5}}: [[Context-free grammar]] describing unit names, if absent or invalid, falls back to male_names or female_names<br />
* '''male_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for male names<br />
* '''female_name_generator''' {{DevFeature1.13|5}}: Like name_generator, but specific for female names<br />
* '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.<br />
* '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.<br />
* '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.<br />
* '''ignore_global_traits''': 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.<br />
* '''undead_variation''': sets the default undead variation for members of this race.<br />
* '''[topic]''': describes extra help topics for this race.<br />
* '''[trait]''': describes a trait for this race. See above for syntax.<br />
<br />
=== [resistance_defaults] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
The [resistance_defaults] tag allows you to add resistance for custom damage types to already-defined movetypes (such as core movetypes).<br />
* '''id''': The damage type you want to apply resistance defaults for.<br />
* '''default''': The default resistance for all movetypes. You can set it to a number, or to a [[Wesnoth Formula Language|formula]] (enclosed in parentheses) which can reference any of the default resistance types - arcane, fire, etc. A common usage for formulas might be to set it to be equal to another resistance, eg '''default="(impact)"'''.<br />
* Other keys reference the '''name=''' attribute of a defined movetype. For example, 'smallfoot=50' will set the resistance to 50 for the smallfoot movement type. ''Note:'' The '''default=''' key and other keys are handled slightly differently. A '''default=''' value will never override an explicitly specified value either in the same [resistance_defaults] tag or in a [movetype] definition, but other keys always take priority over values specified in a [movetype] definition.<br />
<br />
=== [terrain_defaults] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
The [terrain_defaults] tag allows you to add costs and defenses for custom terrain types to already-defined movetypes (such as core movetypes).<br />
* '''id''': The '''id=''' attribute of the terrain type you want to apply cost and defense defaults for.<br />
* '''[movement]''', '''[defense]''', '''[jamming]''', '''[vision]''' - Specify the default values using the same syntax as [resistance_defaults] - an optional default key, and subsequent keys which are movetype names. As with [resistance_defaults], you can use [[Wesnoth Formula Language|formulas]] if you enclose them in parentheses.<br />
<br />
=== [hide_help] ===<br />
<br />
The [hide_help] tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.<br />
* '''type''': list of unit types.<br />
* '''race''': list of races. Equivalent to all unit types of these races.<br />
* '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.<br />
* '''all''': 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])<br />
* '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:<br />
<syntaxhighlight lang=wml><br />
[hide_help]<br />
all=yes<br />
[not]<br />
type=Yeti<br />
race=human<br />
[not]<br />
type_adv_tree=Mage<br />
[/not]<br />
[/not]<br />
[/hide_help]<br />
</syntaxhighlight><br />
<br />
== See Also ==<br />
<br />
* [[UnitTypeWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=61465SpellingMistakes2019-07-01T22:48:50Z<p>Josteph: /* Eastern Invasion */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment. Another instance in S4a.<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=61464SpellingMistakes2019-07-01T22:46:59Z<p>Josteph: /* Eastern Invasion */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
S2 "But it is our only option" is a sentence fragment<br />
<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=61457SpellingMistakes2019-07-01T16:08:23Z<p>Josteph: /* Eastern Invasion */</p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
"Across this river lies the Northlands" change "lies" to "lie"<br />
<br />
S10 "but what happened to the people living on it"<br />
<br />
===Heir to the Throne===<br />
S24 change "prince Konrad" to "Prince Konrad"<br />
S24 sentence fragment: "From a long line of kings"<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
S1 "Ay, the Sceptre of Fire. The sceptre has a long, glorious, and fearful history. But I am not here to tell you..." sentence fragment. Also "And" a few lines below that.<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
"from these simple rules arise a wealth of strategy" - change "arise" to "arises"<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
Orcish Ruler description "... not out of fear, but loyalty"<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Jostephhttps://wiki.wesnoth.org/index.php?title=TheEasternInvasion&diff=61272TheEasternInvasion2019-06-28T15:19:20Z<p>Josteph: /* Xenophobia */ capitalization</p>
<hr />
<div>:''This walkthrough is in the process of being updated for versions 1.12.x/1.13.x''<br />
<br />
<br />
In this campaign you play the role of Gweddry, a human Sergeant who has the responsibility of dealing with a powerful Lich who wants to destroy Wesnoth. As a sargeant, Gweddry has the potential to level up into a Grand Marshal, a level 4 unit that can empower his troops significantly through Leadership. You start with the support of a White Mage named Dacyn, who will be by your side throughout the campaign.<br />
<br />
As any other walkthrough, this document describes plot details that can be considered spoilers. This is particularly true for this campaign, since it contains quite a few surprises along the way, and at some points you will have to make choices that will have important repercussions for later scenarios. You may wish to read ahead to see what you will be facing. In particular, you might wish to read about the scenarios ''Captured'', ''Evacuation'' and ''Weldyn Under Attack'' in order to plan ahead.<br />
<br />
You will encounter different types of enemies, mostly undead units (especially towards the beginning and the end of the campaign), as well as orcs and trolls. Mages and Heavy Infantrymen will provide the backbone of your army. You'll probably want to level up at least one extra Mage of Light (other than Dacyn), and a few Arch/Silver Mages and Iron Maulers. You can also recruit Spearman, Cavalryman and Horseman units (the latter a few scenarios into the campaign), but their importance is perhaps less pronounced in many of the scenarios.<br />
<br />
You will encounter a few tough challenges along the way, so be prepared, and be careful assigning experience to your units, especially during the first few scenarios.<br />
<br />
=== The Outpost ===<br />
<br />
* Objectives: Defend the outpost, then move Gweddry to the trapdoor.<br />
* Lose if: Gweddry or Dacyn dies, or turns run out.<br />
* Turns: 16.<br />
* Starting units: Gweddry, Dacyn.<br />
<br />
The best approach is to recruit heavy infantry and optionally a mage. Build a line using the heavy infantry, using the castle hexes and other hexes to the northwest. When and if you have more money available later, purchase additional heavy infantry.<br />
<br />
Just hold out for the enemy attack during night time; only rotate wounded units if possible, but do not counter-attack. At dawn, start your counter-attack without worrying too much about keeping the original line intact. Instead, try to level 2 or 3 HI to Shock Troopers. The enemy's forces quickly will cease to be any danger to yours.<br />
<br />
On turn 7, Dacyn will mysteriously disappear, and you'll briefly meet Mal-Ravanal, the leader of the undead. On turn 10 (easy) or 12 (hard) the white mage returns and points out a trap door to exit the level. (Note that this trap door will be near your starting fort, so you'll either need to hold the fort or be prepared to get back to it by turn 16).<br />
<br />
Use the remaining turns to level as many units as possible and only move your leader onto the trap door in the very last turn. You may be able to finish with a couple of shock troopers, another white mage, or a level 2 Gweddry.<br />
<br />
On challenging, this scenario is quite, hmm, challenging. You can try purchasing a couple of cavalry to use as a diversionary force, capturing enemy villages and running away, taunting and distracting the enemy, and sacrificing them if necessary to save your more valuable units.<br />
<br />
=== Escape Tunnel ===<br />
* Objectives: Move Gweddry to the end of the tunnel.<br />
* Lose if: Gweddry or Dacyn dies, or turns run out.<br />
* Turns: 26/24/22 (easy/medium/hard).<br />
* Starting units: Gweddry, Dacyn.<br />
* Other:<br />
** Permanent holy amulet in north.<br />
** Treasure of 200 gold in southeast (50 in 1.13).<br />
<br />
This scenario occurs in a small cave occupied by trolls and dwarves. You start on the far west of the map, and your mission is to take Gweddry all the way to the opposite side.<br />
<br />
Take some time to choose your supporting units, depending on which ones you want to level up the quickest. Heavy Infantry are excellent frontline units, but the downside is that they move very slowly in caves. However, since Gweddry is the only unit that ''has'' to get quickly to the far east, this might not be a big problem. You can also go for a group of mostly Mages, and a couple of Spearmen. One keep of units in total should easily be enough—there's also a convenient keep with one castle tile to recruit additional units in the middle of the map, in case you need it during the battle.<br />
<br />
The map is quite small. A little east from your keep the path is forked into three directions: north is a small area with a holy amulet, east is the troll keep and south is the dwarven keep. These two last paths will merge again to the east, leading to the exit, where Gweddry needs to go. The dwarves are friendly and will help you fight your enemies.<br />
<br />
Given that you will probably be using inexperienced units, it's perhaps best to avoid going directly into the troll keep, but you can hold your position near the crossroads, on the southern path, where you can easily witness a lot of action between trolls, dwarves and undead (who are following you and show up on turn 6 from the west). The different armies will all fight each other. If you want to take a defensive stance, after having moved all your units south position one strong unit (a spearman or HI) at the end of the path leading south (so only one unit a turn can attack him) and position the White Mage right behind him to heal it every turn. These two units should easily keep of the enemies following you until the end of the scenario.<br />
<br />
The holy amulet to the north is a very useful item, which will make all the attacks (melee and ranged) of the unit that picks it up of type ''arcane''—and, unlike in other campaigns, this holy amulet is permanent! Send a quick Spearman there or Gweddry. Giving Gweddry the holy amulet (instead of a Spearman) allows him to level very quickly, which is important, since he can advance to Grand Marshal. This gives benefits in other ways on a number of later scenarios as well, such as the scenario ''The Crossing'', where you can get an easy first turn kill against the undead leader and take his castle.<br />
<br />
Move Gweddry to the northeast escorted by other units, to help him fight individual trolls if necessary, but before moving him to the end of the cave (which ends the level) send one of your units to the cave south–east, past the funny signpost warning you of the troll hole. In the cave you will discover a chest containing a troll treasure amounting to 200 gold (or 50 in 1.13).<br />
<br />
[Thrash: Alternately, I used predominately Heavy Infantry on this level. I found (on medium) they were tough enough to hold the central cave and pretty much beat the trolls into submission long enough for Gweddry to run north to the the amulet and then cover his retreat south, only then recruiting a mage when the troll numbers were lower. With other units, I had problems with the trolls overrunning them and getting Gweddry trapped to the north. Also a heavy infantry in the village by your starting fort will hold off the undead for a long time.]<br />
<br />
=== An Unexpected Appearance ===<br />
* Objectives: Defeat either enemy leader.<br />
* Lose if: Gweddry or Dacyn dies or turns run out.<br />
* Turns: 20.<br />
* Starting units: Gweddry, Dacyn.<br />
* Other:<br />
** Your next scenario depends on which leader you defeat.<br />
<br />
In this scenario you have to defeat one of the dark sorcerers on the edges of the map. Your next scenario will depend on the enemy you choose to kill. Killing the one to the west will take you to the ''Elven Alliance'' scenario, while the one to the east takes you to ''The Undead Border Patrol''.<br />
<br />
Going east is more difficult, especially on hard, but brings you more reward, such as the chance to go to Mal-Ravanal's Capital, which gives you the opportunity to get extra experience (a lot for whoever survives) and a loyal Paladin and several Knights.<br />
<br />
First kill Mal-Tar to get your keep. To do this, shoot him with Dacyn and attack him with Gweddry's melee. If you don't kill him the first turn, second turn kill him with Dacyn so Gweddry can recruit. You will be fighting a mix of undead and bats, so recruit Heavy Infantry and Mages (if you gave the amulet to a Spearman in the previous scenario, recall him, too). Dacyn might be wounded, so send him to a village. Don't worry, he can fend for himself, since the bats usually arrive one at a time and he can kill one per turn.<br />
<br />
On easy or medium (or hard going west), the attackers should be no problem, so focus on leveling units. If you move quickly you should only need to fight the attackers from one leader. Of course you can have some of your units double back to engage the second set.<br />
<br />
=== Diverging Campaign Path ===<br />
<br />
==== Elven Alliance ====<br />
* Objectives: Defeat enemy leader.<br />
* Lose if: Gweddry, Dacyn or Volas dies or turns run out.<br />
* Turns: 24/22/20 (easy/medium/hard)<br />
* Starting units: Gweddry, Dacyn.<br />
<br />
The Orc's warning about the assassin is overrated; Volas can probably take care of it himself, although you might want to leave ONE unit near him to make sure. The assassin disappears into the forest, but you won't bump into him, he'll just reappear near the elf leader on turn 6.<br />
<br />
Recruit / recall a wide assortment of units, mostly mages, spearmen and cavalry. Send mages and spearmen up to fight the opponent, send cavalry down as scouts. Any heavy infantry should go up to fight also; they will probably arrive late, and be good for reinforcements when the first troops are wounded.<br />
<br />
Align the troops in the forest, so that the enemy will be on grass; this gives you a tactical advantage. Use Dacyn to heal those who need it most - those on the corners, and any mages who are on the front lines.<br />
<br />
There is a village at {20,8} that can prove tactically very useful, because the elves usually fight somewhere near it.<br />
The elves are defeated most of the time, and the orcs claim this village; it is crucial to kill the orc on this village and take it over with a resilient spearman, or a HI.<br />
<br />
Once you have gotten past turn 6, it will be day, and the orcs will be very easy to defeat. When the assassin appears, you may ignore it unless you have a unit close-by. In that case, use it to fight the assassin. Keep pressing up. It is possible to kill the orcish leader by turn 9 for a nice gold bonus.<br />
<br />
==== The Undead Border Patrol ====<br />
* Objective: Defeat either enemy leader.<br />
* Lose if: Gweddry or Dacyn dies, or turns run out.<br />
* Turns: 20.<br />
* Starting units: Gweddry, Dacyn.<br />
* Other:<br />
** Your next scenario depends on which leader you defeat.<br />
<br />
This scenario also depends on which way you want to go. There is a Dark Sorcerer in the north-west corner and a Lich in the south-east corner. Defeating the Lich will give you the chance to go to ''Mal-Ravanal's Capital'', a challenging but rewarding scenario, while defeating the sorcerer is easier, and takes you directly to ''The Northern Outpost''.<br />
<br />
If going NW, it is fairly straightforward. The enemy is relatively weak. Do the same as in Unexpected Appearance—you may recruit a couple of suicide cavalrymen to distract the bats. One will probably get enough XP to be worth recalling. Because of the open terrain, it is recommended to use mostly heavy infantry and spearmen with the holy amulet on this level and few mages. However, as in most scenarios against undead, white mages are very useful. Try to get the opponent to fight you from the sand; this gives you a significant advantage.<br />
<br />
If you go East, expect to take some time getting over the river and through the swamp. A small force recruited to defend the fort will keep troops from the NW off of your backside and they'll pick up a good amount of experience in the process.<br />
<br />
==== Mal-Ravanal's Capital ====<br />
* Objective: Escape from the capital by killing one of the two dark sorcerers.<br />
* Lose if: Gweddry or Dacyn dies, or turns run out.<br />
* Turns: 26.<br />
* Starting units: Gweddry, Dacyn.<br />
<br />
Only reachable from ''The Undead Border Patrol'' scenario, but you may skip it and go directly to ''Northern Outpost''.<br />
<br />
The main reason to get here is to acquire a cavalry force of one Paladin (a loyal unit) and five Knights. Focus on freeing the horsemen as quickly as possible. To do this, kill the 6 Revenants guarding the cages (they will not move unless you attack them first), but note the number of Knights available is reduced by one for each of your troops that die *after you rescue the first one*. You might want to make sure any expendable troops are "expended" before this. Each rescued unit pops in with full moves.<br />
<br />
The regular Time of Day cycle does not apply here. Instead, dusk and night are twice as long as usual, so adjust your tactics accordingly. Most importantly, try to finish the mission quickly.<br />
<br />
''Comments'': This is a very challenging scenario. I started with only 100 gold, so I recalled one Mage, two Shock Troopers, one Heavy Infantry, and my holy Halberdier. I defended the starting castle for about 10 turns until the Revenants had made their way over to me. Upon killing several of them, I freed some imprisoned Knights and a Paladin. I moved my forces to kill the Death Knight, and then split my forces. I sent one group to attack Mal-Ravanal and the other to kill the Necromancer in the NW corner. By turn 30, my Eastern assault force was in postion to attack Mal-Ravanal. However, when I attacked him I wasn't able to defeat him. When I was ready, I killed the NW Necromancer and progressed to ''The Northern Outpost''.<br />
<br />
[Thrash] My take on just getting the paladin and 5 knights quickly is you want to send units in parallel to attack the NW enemy and free as many of the knights at the same time. The trick is you free the knights and then kill the NW leader right after before all your troops get overwhelmed by units from the East (and center). Time of day is critical - if you can get to the revenants before dusk, a white mage or shock trooper can kill them in one turn, after that it will take two turns or a little help (like a previously freed knight). Gweddry, even with an amulet, will probably take 3 turns to kill one, but with his one turn head start, that's OK. With one fort of recruits (2 white mages and 4 shock troopers), I was able to free 5 of the 6 and kill the NW enemy leader on turn 6 [?in which version?]. I sent 3 shock troopers and a white mage at the NW enemy, diverting one of those to freeing the 6th knight probably would have gotten me 6 out of the 6.<br />
<br />
=== The Northern Outpost ===<br />
* Objectives:<br />
** Find the outlaw leader in the villages and kill him.<br />
** Defeat the undead leader.<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: 20.<br />
* Starting units: Gweddry, Dacyn, Terraent.<br />
* Other:<br />
** A holy amulet is located on the south-west.<br />
** Horseman units can now be recruited.<br />
** Owaec joins your team after the fight is over.<br />
<br />
This scenario is reachable from the ''Elven Alliance'', ''The Undead Border Patrol'', and ''Mal-Ravanal's Capital'' scenarios.<br />
<br />
Here, there are two enemies that you must defeat: the undead and the outlaws. It is a good idea to create a separate task force for each.<br />
<br />
The undead are fairly straightforward to defeat, and in any case Owaec usually does a good part of the work. To finish off the undead, it's useful to have a white mage, since Dacyn will be busy with his special spell to reveal the outlaws for this scenario. If you don't have a white mage, you can try recruiting a few mages or else go back one or more scenarios and promote a mage to white mage. In addition to the mages or white mage, recall whomever picked up the holy amulet in one of the previous scenarios and have them accompany Gweddry to the southeast. If Gweddry is the one with the holy amulet and you have a white mage, then you can supplement them with a mage. You should also send a cavalryman/horseman or quick spearman to pick up the new holy amulet in the southwest.<br />
<br />
By contrast to the undead, the outlaws require a novel strategy. Recruit/recall fast units, e.g., cavalry and horsemen. You may supplement them by recalling quick spearmen and quick shock troopers. The challenge is that criminals will sometimes appear randomly around the villages you flag. Therefore, before flagging a village, make sure you have several healthy units around it. Note that you will get a chance to kill any newly appeared outlaws before they get a move. Outlaws will not appear in the villages that Owaec flags, so don't worry about him uncovering enemies for you. Send your outlaw hunting posse up the eastern side of the map flagging villages and fighting the bandits. One of the villages has the assassin that is the outlaw leader, and there are a lot of villages, so speed is of the essence.<br />
<br />
Once your undead task force has finished the undead, form them into a second outlaw hunting posse, transferring units as needed from the first posse. When you come across the village where the bandit leader hides, divert any available units to the battle, as the bandits have a bite.<br />
<br />
Note: A Cavalry force (such as the one acquired in Mal-Ravanal's Capital) makes short work of the bandits. Lower level units have trouble against the bandits, especially at night.<br />
<br />
Also note, that from this scenario on you can recruit horsemen. You might want to level up a paladin or two, for fast mobile undead removal services (and quick leader assassination).<br />
<br />
[Thrash] When I played, Oweac only recruited a couple mages, so he needed significant help as they get slaughtered quickly - I'd say 3-4 units. Also you don't really need to surround a village before flagging it, just have units in range to sweep in and attack if bandits pop out; this can save you some turns as move around as you can send one unit in to flag a village and move the rest on if nothing appears. Finally, the outlaw leader ran away when I played, so be prepared to chase him down.<br />
<br />
=== Two Paths ===<br />
* Objective: Defeat either enemy leader.<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: 18/17/16 (easy/medium/hard).<br />
* Starting units: Gweddry, Dacyn, Owaec.<br />
* Other:<br />
** Your next scenario depends on which leader you defeat.<br />
<br />
You must choose between going north to attack the orc leader or going north-west to attack the undead leader.<br />
<br />
One option is going north on the very east side of the map trying to fight your enemies from solid ground and mountains while they stand on sand ground with weak defense. As your troops move very slowly on this terrain, you will likely take some heavy losses however, as your enemies keep surrounding you. Also this will presumably take too many turns to reach the orc leader in time.<br />
<br />
Thus the preferred choice is to recall a couple of shock troopers and white mages and move them on the path to the north-west in a tight formation towards the undead leader. Once you survived the first enemy onslaught without loosing units, the rest of this scenario becomes rather easy as the remaining enemies come one by one. Make sure to keep on moving fast to the north-west to reach the undead leader before turns run out.<br />
<br />
On hard (and version 1.8.3), what will probably work better is an all-out suicidal cavalry charge to assassinate the undead leader as quickly as possible.<br />
<br />
It's worth noting that killing the orc leader results in what appears to be an easier and more rewarding subsequent scenario (The Crossing) than killing the undead leader (Undead Crossing).<br />
<br />
=== Diverging Campaign Path ===<br />
<br />
==== Undead Crossing ====<br />
* Objective: Defeat the enemy leader.<br />
* Lose if: Gweddry, Dacyn or Owaec dies or turns run out.<br />
* Turns: 18.<br />
* Starting units: Gweddry, Dacyn, Owaec.<br />
<br />
You need to cross the river, but not without first defeating a necromancer who is occupying a small island to the north.<br />
<br />
A good general strategy can be something like the following: recall a couple of quick swordsmen (or about-to-level quick spearmen), two white mages, a red mage or multiple regular mages, and any units with holy amulets. Shock troopers are too slow. Send these units as quickly as possible northwest through the swamp towards the eastern crossing. Meanwhile, recruit/recall cavalry. The cavalry should run as fast as possible along the southern board edge (so as to not attract undue attention from bats and swimming undead) and then up the western crossing. You can divert a couple of cavalry and Owaec to snatch up villages and then those units can join the eastern assault.<br />
<br />
Now, this scenario has a nasty surprise... Once you have fought off the bats and skeletons, you will find this was not all, as the undead leader summons a number of cuttlefish monsters (1, 2 or 4 according to the difficulty level: easy, medium or hard respectively), which appear in the water between the two crossings. These always appear on turn number 10. Be very careful where to position your troops as the cuttlefish have a very nasty melee attack.<br />
<br />
You have at least three options for the crossing. Option 1 is to just try to get a couple of your cavalry across each of the two crossings, while the rest of your units run like hell away from the water and swamp. Option 2 is to send across more units while tossing a spearman into the water as bait. Option 3 is to fight the cuttlefish, which is extremely hazardous. For a fight, maneuver your units to encourage the cuttlefish to separate, then use good melee troops backed by Gweddry (for leadership) and a white mage to kill them one at a time. Good luck. Make sure you leave your units enough time to cross the river and kill the undead leader before turns run out.<br />
<br />
==== The Crossing ====<br />
* Objective: Get Gweddry and Owaec across the river.<br />
* Lose if: Gweddry, Dacyn or Owaec dies or turns run out.<br />
* Turns: 24.<br />
* Starting units: Gweddry, Dacyn, Owaec.<br />
* Other:<br />
** Special bonuses if the objective is completed while the Ogre leader is still alive:<br />
*** Ogre leader joins you as recallable a loyal unit<br />
*** You get two additional recallable Ogre units<br />
<br />
Looking at the level, one might imagine the challenge in this scenario is crossing the wide river - where units are very vulnerable, and have very restricted mobility (particularly horses). However, this will likely prove to be the lesser of your concern: The Orcish force on the Northern bank is preoccupied with the Ogres for a good several turns, and the opponents going after you will be the Undead from the South. <br />
<br />
On Turn 2, the first contingent of Undead will appear to the South-East of your keep: A weaker leader (Revenant on Medium) "unpacks" a keep and recruits it full of units (on Medium these are L1 recruits). If Gweddry and Owaec are already in the water, you may find yourself pretty bloodied by the encounter; and the Revenant has Gold to spare for more recruiting.<br />
<br />
On Turn 8, the Undead are reinforced by a powerful Lich (on Medium) and a few leveled units (on Medium - two Revenants and a Bone Shooter) - and they get initiative, i.e. they get a round of action before you can attack them. Do you have units ready to take the blow? They might not be numerous, but they're quite deadly when ganging up on a unit of their choice. If, however, your units remain at a distance, the Lich will enter the keep and recruit...<br />
<br />
On the North bank, the Orcs and the Ogres are exchanging blows. Within a couple of turns it becomes apparent the Ogres are going to lose - but you want their leader alive. That means you either have to draw much of the Orcish forces to chase you into the river, or alternatively get Gweddry and Owaec across fast enough so that the Orcs aren't completely done with the Ogres (the Leader will most probably be the last one to die).<br />
<br />
So, when can you afford to send Gweddry and Owaec, and/or other units, up into the water? A slight tactical error in judgement can mean either numerous casualties by the undead, or alternatively loss of your potential Ogre ally.<br />
<br />
If you ''do'' manage to cross before the Ogre leader is dead, he will agrees to help you; you'll get the bonuses listed above and will skip the ''Training the Ogres'' scenario, proceeding directly to ''Xenophobia''.<br />
<br />
<br />
[Allefant]: I had only 100 gold, so recruited some units and went straight North from turn one on. The fighting in the water was quite hard, with some orcs coming down from the north. The Undead only appeared when I was in the middle of the river, so no encounter with them, and the ogre's helped get rid of the orcs on the north side.<br />
<br />
[Thrash] Make sure to cover your rear flank with some expendable troops (such as Heavy Infantry) as the Undead can move more quickly through the water than your units. Alternately, if you kill the first wave of Undead quickly enough (by turn 3), you can make it across the river before the second wave catches you from behind.<br />
<br />
Another strategy is to go straight into the water after killing the first Undead leader using the deep water in the middle of the path to Seperate the orc forces. You go to the right with Gweddry and Owaec and some support troops while letting the ogres kill many of the orcs in your way. Knights and a Paladin can hold off the Orcs enough to get across while the Undead behind you are not an issue. <br />
<br />
I had problems with the Ogre leader dying before I could get to him with this strategy, but sending Oweac into the river on turn 1 seemed to draw enough of the Orcs south to solve this problem.<br />
<br />
[Hipparchos] Agreed this is the only way to save the ogre leader (all others are too slow). I played this several ways before deciding the easiest is to recruit/recall only units with 6+ movement (Horsemen, Cavalrymen, quick Mages and quick Spearmen) which move 2 hexes through the water. Send them immediately South to the Undead leader's keep and defeat the units there within the first few turns. Then occupy the keep and wait for the reinforcements while one Horseman rides West to take villages. With no keep, the reinforcements are small and easy to defeat. Then you have no problems to your rear as your fast units catch up to Oweac and cross the river. You'll take some hits on the far bank but should get through in time to keep the Ogres alive.<br />
<br />
=== Training the Ogres ===<br />
* Objective: Capture the ogres.<br />
* Lose if: Gweddry, Dacyn or Owaec dies.<br />
* Turns: Unlimited.<br />
* Starting units: Gweddry, Dacyn, Owaec.<br />
* Other:<br />
** To add ogres to your army, "capture" them by ZoC-locking them.<br />
<br />
<br />
This can be a confusing scenario to understand. Basically, your three units just have to survive. However, if you want to be able to recall ogres later, you need to "capture" them by surrounding them. Any ogre which cannot move more than one hex in every direction will be added to your recall list. Ogres which reach the rocky borders will "escape".<br />
<br />
Ogres are especially mobile on mountains (such as in the scenario ''Lake Vrug'') and in caves (in the scenario ''Captured''). Being of neutral alignment, ogres can be helpful at night (especially in the scenario ''Weldyn Under Attack''). It's best to capture at least two.<br />
<br />
<br />
=== Xenophobia ===<br />
* Objective: Defeat all enemy leaders.<br />
* Lose if: Gweddry, Dacyn or Owaec die or turns run out.<br />
* Turns: 40/36/32 (easy/medium/hard).<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug.<br />
* Other:<br />
** A holy amulet near the orcs' keep.<br />
<br />
This is a fun and silly level as all parties in the scenario (i.e. elves, orcs, drawves, and yourself) decide to fight each other instead of forming alliances. The scenario is not very difficult, so you can use this time to gain some experience for your units and pick up another permanent holy amulet (in the north, roughly in the middle between the dwarf and the orc keep).<br />
<br />
You have two obvious options: attack the elves first or the dwarves first. Don't worry, they will be distracted by the orcs. After you kill the first leader, proceed to the orcs and then finish off the remaining leader.<br />
<br />
Attacking the elves first has the advantage that they have the richest lands, i.e., the most villages, so it means more gold for you by the end of the scenario. It has the side effect that you're more likely to face a live orc leader relative to if you had attacked the dwarves first, as the elves are pretty good at killing him.<br />
<br />
Attacking the dwarves first has the advantage that it's probably easier, since the orc leader is more likely to die at the hands of the elves. It has the disadvantage that you have to spend time getting out of the dwarven mountains and then you will ultimately fight a lot of elves, though most of them will have come out of their forests by then.<br />
<br />
In either case, you have a lot of ground to cover, so try to do without any non-quick shock troopers. Cavalry, white mages, red mages and spearman track units (preferably quick) are all good.<br />
<br />
By the end of this scenario, it's very useful to have Gweddry at least on level 3, allowing you to use his leadership ability on other units like ogres (who reach their maximum at level 2). Leveling up a group of key units will also be very important for the upcoming scenario ''Captured'', where you won't be able to recruit, but a group of your most experienced veterans will have to fight their way out of a cave. You may want to prepare several mages and knights.<br />
<br />
=== Lake Vrug ===<br />
* Objective: Defeat the Trolls and Gryphons (Drakes in 1.13), and move Dacyn to the stronghold<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: 30.<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug.<br />
* Other:<br />
** The stronghold provides 100 gold.<br />
<br />
This is a very confusing hide and seek scenario that could take you several pointless restarts until you have finally discover the enemy leaders.<br />
<br />
There are three keeps, all north of the river. The troll leader has his keep on the northeast (go to the right into the mountains directly after crossing the bridge). To find the other two keeps, go west right after crossing the river; if you stay close to the southern line of mountains, you'll find the Gryphon keep pretty easily. Finally, there is a stronghold straight north from the Gryphons, and Dacyn must reach this fortress to complete the level.<br />
<br />
Gryphons are vulnerable to the impact damage of heavy infantry and shock troopers, so recall two or three, preferably quick ones. Also recall another white mage to supplement Dacyn and as many ogres as possible, because they are probably the most useful unit for this scenario. The reason is simple: the enemy keeps are surrounded by high mountains which some of your troops cannot pass, but which the ogres handle quite easily. You might also want to recruit a horseman to scout ahead, although using that money for another mage or ogre may be a better investment.<br />
<br />
The action for this scenario can be divided into two phases. The first phase will be surviving the first onslaught of Gryphons and trolls coming your way. This will start around turn 4 with quite a number of Gryphons appearing from the northwest. On hard, the onslaught will be especially difficult to handle. When you see the first Gryphon swoop out of the fog, watch out! This means many others are coming behind. So, fall back away from the fog and form a defensive line that will eventually become a circle. Keep in mind that you can grab good terrain, i.e., the mountains, as Gryphons are only too happy to attack you wherever you are, and your ogres will hold up well there. Once you have wounded units, position your heavy units such as shock troopers and ogres very tighly around them, as the Gryphons really have quite a large moving range and thus mercilessly slay unprotected injured units.<br />
<br />
Just when you thought you had the Gryphons wrapped up, here come the trolls across the bridge. They may be only a minor nuisance on medium or easy, but on hard it's a strain facing a large number of trolls with troops bloodied by the swarm of Gryphons. Trolls are really no match for your shock troopers, however, who happily troll-crack away. Place these troopers on the grassland tiles on the edge of the river, so the trolls coming from the bridge will be forced to attack from unfavorable terrain for them (ice).<br />
<br />
Once you have dealt with this first wave of enemies, the remaining phase consists in crossing the river, finding the enemy leaders and finishing them off, which will be much easier in comparison. Unfortunately, the shock troopers won't do you much good in this end phase. When taking the enemy keeps, use the ogres, who can move well on the high mountains, unlike most of your other units.<br />
<br />
[revolting_peasent] Starting with version 1.13, the Gryphon leader recruits Drakes: First Glider Drakes (for the onslaught), then Sky Drakes. The former can be pretty safely defeated by a half-HP Ogre, the latter - not really, even individually. So even one of these can be very troublesome. This is especially true if they somehow gets near Dacyn, which they seem to have an inclination to do.<br />
<br />
=== Captured ===<br />
* Objective: Rescue Gweddry, Dacyn, and Owaec, then escape through the south-west tunnel.<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: Unlimited, then 16.<br />
* Starting units: Rescue leader and two sidekicks.<br />
* Other:<br />
** No recruiting, but a group of your veterans will be available.<br />
** A holy amulet to the south.<br />
<br />
Three of your recall troops will escape from a cell and plot a rescue operation. The scenario tries to select a level 3, level 2, and level 1 unit, but it is possible to end up with many variations. This group only needs to fight an orcish grunt and a few bats as they travel west, then south. Shortly after they encounter the orcish trash heap, one of your rescuers will don a disguise to sneak past the troll guards.<br />
<br />
The disguised unit can open a cell door to release the prisoners within. Try to select a cell containing ogres; a quick ogre has the best chance of reaching and opening another cell in the same turn. Your three heroes will also be freed, and either Dacyn or Gweddry can reach the final cell to release the last of your troops. You'll be surrounded by Troll Warriors, and unlikely to do enough damage to kill them in the first turn. Sacrifice some of your less experienced troops to block the trolls from reaching any important units. <br />
<br />
Victory occurs when Gweddry moves through the exit in the southwest corner. There is a holy necklace in the southeast. Preferably grab the holy amulet with a horseman or something similar. He will come in very hand in later scenarios (if he survives the next scenario, that is).<br />
<br />
If you have a large group of recallable units, loses in this scenario are not a big deal, as you're only going to be able to bring a fraction of your recall list past the next scenario, which is likely to kill off all but a few veterans. However, the steady stream of orc reinforcements can provide one last chance to level key units for ''Evacuation'', the next scenario.<br />
<br />
=== Evacuation ===<br />
* Objective: Destroy the bridge or defeat all enemies.<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: 12.<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug, Engineer.<br />
* Other:<br />
** Every unit not on the south side of the river when the bridge is destroyed will be lost (including units in your recall list).<br />
<br />
There are two options in this scenario: you can either defeat all enemy leaders or blow up the bridge in the south. If you finish by passing the bridge, all your units that are not on the south side of the river by the time you blow up the bridge are killed by the explosion. Cruelly, this includes your un-recalled units! Of the two options, killing all the enemy leaders is preferable if you can pull it off, so that you can keep your un-recalled troops. <br />
<br />
This is one of those scenarios many deem "impossible" (at least on Hard) - but it is by no means impossible. You will, however, have to wrap your mind around an unpleasant truth: It may be necessary to accept significant losses of higher- level troops. You should have a large number of level 2 and 3 units to recall to start this scenario, with level 2 units with high experience and close to advancement being your best asset. <br />
<br />
Whichever objective you choose to pursue, watch out for the very tight time limit of 12 turns. And watch out for the (Level 3) Warrior Trolls: They can defeat and kill most of your single units within a single turn at night. Best fight them with Mages or arcane-damage-dealing cavalry. Your mounted units are well resistant to impact (30% for Horsemen/Knights, 40% for Cavalry/Dragoons, respectively) and can deal with trolls, especially Paladins, or mounted units with an amulet (-10% Troll resistance instead of +20%). Also, you _will_ run out of money here - either on Turn 1 or on Turn 2, so don't let that large keep make you think all of your buddies will be joining you like in the last scenario.<br />
<br />
Luckily, you can (versions 1.12.2, 1.13.4) lure out the Eastern and the Southern Orc Warlord leaders on Turn 1, and since their recruits can't move on that turn, they will both have opened themselves to be taken out during the next turn. Plan your Turn 1 recruiting and Turn 2 attack carefully, to have enough muscle to take out the leaders and enough brawn and speed not to expose the damaged units too much to the two keep-full's of recruits who will scream bloody murder (literally...). <br />
<br />
The Western Troll-Warrior-lead contingent cannot reach you in full force until turn 3 and (on Medium) may not attack all-out even then, so regardless of the leader lure gambit - deal as much damage as possible during the first day, while maintaining some reserve for defense during the night. <br />
<br />
The second option - blowing up the bridge - is quite a bit easier to pull off, especially if you're on Hard or short on gold. Run South with a sufficient amount of screening units and hopefully those units you want to try and evacuate (they shouldn't be slow ones). Focus on running the Engineer - using other units to block for him, creating a ZOC corridor. Keep in mind that almost everyone is expendable (sigh...). Engage the enemy sparingly, only at those points necessary to clear the way for the evacuee units, or where you see an opportunity to level-up and heal. With the large keep in this scenario you have no excuse to dilly-dally.<br />
<br />
On Hard, If you finish the scenario with just the required units plus about three level 3 units, don't panic. You can indeed finish the rest of the scenarios, starting with just a few level 3's. Note that the next scenario, ''The Drowned Plains'', is good for leveling raw recruits. However, if you have a lot of level 3's, it would certainly be easier to tackle another upcoming "impossible" scenario, namely ''Weldyn Besieged'', so you may wish to replay ''Evacuation'' to get a better result.<br />
<br />
WanderingHero: While this scenario is cruel, its not as asinine as it appears. You've already beaten the hardest scenarios of the campaign, so you don't have much to worry about taking losses. Try saving a White Mage, and maybe a Knight that's close to Paladin or a Paladin; although even this is hardly essential. Your heavily armored units and able-bodied Ogres can be used to wall the enemy. Although the situation looks grim, you're actually near the end of the campaign, and the worst is behind you. You'll see the Checkered flag soon enough...<br />
<br />
=== The Drowned Plains ===<br />
* Objective: Defeat Khrakrahs.<br />
* Lose if: Gweddry, Dacyn or Owaec dies, or turns run out.<br />
* Turns: 28/26/24 (easy/medium/hard).<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug, Engineer.<br />
<br />
Khrakrahs is a level-4 Skeletal Dragon that will be found in or near the castle (located on an island in the south). In getting there, you need to proceed slowly and carefully through the swamp. That is because there are lots of fairly high level undead hidden there, waiting to ambush your troops. Don't panic. They are easy to take one at a time, and you can offer the killing blow to troops that you are eager to promote. Think twice about trying to maneuver more units around the back of the one you're trying to kill, as there may be more ambushing undead there.<br />
<br />
The dragon wanders around near the castle but only attacks units which he can kill instantly. If only strong units come near him, he tries to flee. Because of the fog the major challenge of this scenario is finding him and then getting him surrounded so he cannot just move away again. Once you have him trapped like this, slaying him should be easy using your stronger units —preferrably using impact weapons because the dragon has a low resistance there. Magical attacks from your magi are also very effective against the dragon.<br />
<br />
This scenario is a good opportunity for all the units with holy amulets you still have with you. Use them against the ambushers. Since there's a good early finish bonus, just recruit a keep of your best anti-undead units, find and kill the dragon and reap the reward.<br />
<br />
<br />
=== Approaching Weldyn ===<br />
* Objective: Get Gweddry to Weldyn.<br />
* Lose if: Gweddry, Dacyn, Owaec or Konrad II dies, or turns run out.<br />
* Turns: 24.<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug, Engineer.<br />
<br />
The objective is simple enough; Gweddry has to reach the castle occupied by Konrad II. This is simply a matter of moving him there quickly. The end.<br />
<br />
There is no challenge here, but with undead around you can pick up some XP with your fast moving arcane-enhanced troops (i.e., the ones that picked up holy amulets in earlier scenarios.) Try not to overrecruit or dilly-dally, though, as you need all the gold you can get for the next scenario, ''Weldyn Under Attack''.<br />
<br />
=== The Council ===<br />
<br />
Only plot in this. You see the inside of the castle.<br />
<br />
=== Weldyn Under Attack ===<br />
* Objective: Survive until end of turns.<br />
* Lose if: Gweddry, Dacyn, Owaec or Konrad II dies.<br />
* Turns: 18.<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug, Engineer, Konrad II.<br />
* Other:<br />
** At the end of this scenario you will have to choose whether to fight Mal-Ravanal directly in a duel, or repel his invasion with all you've got. This dictates the final scenario you'll play for this campaign.<br />
<br />
At scenario start, you find your keep in the center of an island. Three allied leaders also have their keeps on the island around yours. There are three enemy leaders (Liches) with equal amounts of gold at their disposal. The southwestern enemy leader is the only one that recruits Nightgaunts, the Southeastern Lich is the only one that recruits Blood Bats, and the Northern Lich is the only one that recruits Spectres.<br />
<br />
The time of-day cycle in this scenario is 3 times slower than usual, and it starts at sunset, so the first 3 turns are Dusk, and then it's night-time (first and second watch) during another half of the entire scenario, which is painful - literally, considering the damage the Undead will deal your troops. Fearless or Neutral-alignment units are important, as is careful use of your Mages of Light's Illumination (see also below).<br />
<br />
Your strategy should be to kill off one of the Liches and his troops, so that you can take over his defensive position. It's probably easiest to take the Northern keep.<br />
<br />
Typically, the backbone of your army will be Heavy Infantry track units, Mages, and your Mages of Light (Dacyn and hopefully at least another one). On the first turn, recall one of each, plus 3 Cavalry units to the rear, preferably quick. Send the cavalry to rob your allies of their villages. They won't mind. Later, the cavalry can run around to distract the enemy. Send your Heavy infantry types, Mages, and Mages of light towards the target enemy stronghold. You should supplement them with any units with arcane attacks: Arch Mages, Silver Mages, White Mages, and any units that picked up amulets in previous scenarios.<br />
<br />
However, if you managed to get your forces off the lake Vrug island in ''Evacuation'' (without blowing up the bridge), it's likely you are now able to recall a good number of Level-3 units with arcane attacks and maybe you even have a couple of Ogres. If that's the case you stand a chance (on Medium and v1.13.4 anyway) to assassinate the Northern Lich before he runs out of money. The way to do it is instruct the North-Western allied leader to attack the Northern Lich. Your units will set up in the fortified positions near the bridge due North, and in the villages - drawing some enemy units into the water and clearing one or two for your ally - while he, brilliant tactician that he is, sends his units blindly forward, North across the bridge and the stream to tackle the Lich's recruits head-on. This will bring the Weldyn units (mostly Mages probably) within range of the Lich himself, and he may come out for an attack - and into the water. If this happens (possibly on Turn 4 or 5) - make a gambit for his life: One unit can attack him from the bridge and one or two from the water. Of course these have to be arcane attacks, otherwise you're probably not going to kill him off; and apply Illumination to the attacker and maybe the Lich itself (i.e. make a Mage of Light one of the attackers). To complete the gambit, have some high-HP units defend the wounded attackers of the Lich from the side, so they don't get picked off easily the next round. Still, an L2 unit or even a Paladin is not a terrible loss in exchange for a Lich leader and his 100-gold-or-more in unrecruited units. <br />
<br />
... But it's more likely not to have such a convenient strike force, in which case you probably not be able to assassinate the Lich before he is out of gold. When he dashes out to attack, check his gold. If he's broke, you might wish to ignore him for a turn or two while you kill off other units.<br />
<br />
After you take over the stronghold, you may be able to recruit some more troops, if you saved some gold and/or did a good job capturing villages with your cavalry. Note that saving gold is of no use for ''The Duel'', so spend it now if you're in a bind (saving gold is a luxury in this level which would help you in 'Weldyn Besieged'). Next, you should start preparing for the assault waves of the other two Liches. The combined assault waves may be more than your forces can survive. Therefore, while your main force braces itself, you should send out some ogres, cavalry, and/or silver Mages as distractions, mostly along the board edges. They can even get in a few kills.<br />
<br />
For your main force, unless you have taken over the South-Western keep, you need to mind those invisible, infiltrating, backstabbing Nightgaunts that can be up to no good... they are now headed your way. Have your units form a block with their back to the board edge. Round the corners of the block towards the enemy (so that you don't have one unit face four attacks.) Keep your whole line solid and heavily wounded units buried deep inside.<br />
<br />
In addition to Nightgaunts, you have the threat of Banebows, which can do 52 ranged damage in one turn. However, they are fairly easily killed with proper strategy. Move a mage of light adjacent to blind the Banebow (i.e., remove its +25% bonus) and provide light for your lawful unit's attack (i.e., remove its -25% adjustment.) Move a Shock Trooper (or similar, preferably arcane enhanced) adjacent to the banebow and mage of light. Move a General up to lend Leadership to the attacker. You may kill the Banebow in one attack. Otherwise, if the Banebow is quite wounded, you can use the mage of light to finish it off.<br />
<br />
If you lose when you try to make a stand, you could instead try splitting your forces in two to attack the remaining two Liches. Some players have had success with this, killing the last leader by turn 14 or 15. Just remember that the objective is to survive until the end of turns, and Nightgaunts may be a problem. Killing all three leaders is a victory though and will earn you a early finish bonus of 54/turn, which is important if you go on to ''Weldyn Besieged''.<br />
<br />
If you have one or two Silver Mages available, they are quite useful in this scenario. The map is rather large so have some fast-moving units like horsemen run through enemy territory and capture individual villages. Then use the teleport ability of your silver mage to perform hit-and-run (or rather: hit-and-teleport) attacks. Make sure you do not get him killed, though, by holding out too long after attacking. Make good use of Gweddry's leadership ability (he should be a Grand Marshal by now), and of Konrad's Sceptre of Fire to get rid of the most dangerous enemies coming your way.<br />
<br />
At the end of the scenario, you must choose between challenging Mal-Ravanal to a duel (''The Duel'') or defending Weldyn against the final Undead attack (''Weldyn Besieged''). ''Weldyn Besieged'' is intended as a challenging final scenario; players without a good recall list and sizable warchest will find ''The Duel'' much more accommodating.<br />
<br />
=== Diverging Campaign Path ===<br />
<br />
==== The Duel ====<br />
* Objective: Defeat Mal-Ravanal while Dacyn is nearby.<br />
* Lose if: Gweddry or Dacyn dies, or Dacyn is not nearby when Mal-Ravanal is defeated.<br />
* Turns: Unlimited.<br />
* Starting units: Gweddry, Dacyn.<br />
* Other:<br />
** You can only recruit for the first turn.<br />
<br />
This is a somewhat strange scenario: you get to recall/recruit exactly five units and then have to fight Mal-Ravanal and his six chosen troops. Mal-Ravanal will recruit mostly level 3 units so this looks difficult. However, it is, in fact, quite manageable. Your goal is to attack first and hit hard—you should be able to eliminate two or three enemy units before they even get the chance to attack.<br />
<br />
Except for Konrad II, you will have all of your units available in the recall list (including Owaec). Recall mages of light and other high-level arcane troops. Advance onto the battlefield, but stop just short of the enemies' range. After the enemies move closer, concentrate your attacks on a few of their units, particularly those with the strongest attacks. "Cowardly" Gweddry may be able to grant leadership bonuses to your troops, however he should probably refrain from actual fighting so he does not accidentally get killed.<br />
<br />
Try to finish the fight quickly, as Mal-Ravanal plays unfair and every so often recruits another 3 units, albeit not so tough as the first batch of 6. If you position a weak unit within Mal-Ravanal's movement range the arrogant lich will gleefully charge out onto the battlefield and leave himself wide open for your counterattack.<br />
<br />
==== Weldyn Besieged ====<br />
* Objective: Defeat Mal-Ravanal while Dacyn is nearby.<br />
* Lose if: Gweddry, Dacyn, Owaec or Konrad II dies, any enemy unit reaches your keep, or Dacyn is not nearby when Mal-Ravanal is defeated.<br />
* Turns: Unlimited.<br />
* Starting units: Gweddry, Dacyn, Owaec, Terraent, Grug, Konrad II.<br />
<br />
This battle is intended as a substantial challenge, and is inadvisable with low gold or an inadequate recall list. You face off against seven enemy leaders, with the goal of finding and eliminating Mal-Ravanal among them. The liches' names aren't revealed until they are attacked, and Mal-Ravanal is more likely to be revealed later in the scenario (the names are randomly assigned when you attack). Attacking a lich gives it a small boost of gold, but killing the wrong lich gives every other lich extra gold.<br />
<br />
A quick scout unit can charge past the undead hordes to attack and identify a lich. Once you've found Mal-Ravanal, send Dacyn and any mounted arcane-attack units to attack. You can draw Mal-Ravanal out of the keep by positioning a sacrificial horseman nearby. Once the lich is out in the open, your arcane damage cavalry should have no trouble finishing the battle in a single turn.<br />
<br />
Meanwhile you'll need the rest of your troops to hold the central keep against the undead onslaught. If you can spare the funds, a few sacrificial troops can delay the incoming enemies on one side, giving you the opportunity to focus your firepower on the undead approaching from the other side(s). Note, however, that each enemy killed causes the lich to recruit another. If things turn grim, retreat to the castle and make your final stand.<br />
<br />
<br />
[[Category:Campaigns]]<br />
[[Category:Campaigns - Walkthroughs]]</div>Josteph