The Battle for Wesnoth Wiki - User contributions [en]

Android

2025-10-03T05:09:34Z

AI: /* MMMPPpxxVA */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

===== <code>MMMPPpxxVA</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

===== <code>12MMMPPpVA</code> =====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

===== <code>12MMPPpxVA</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

Android

2025-10-02T10:17:46Z

AI: /* Other version code scheme drafts */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/Dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

===== <code>MMMPPpxxVA</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - Build variant (0 is clean, 1 might be google play integrations. Could be a bitfield or an enum)
* A - ABI (as above)
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, default (clean) variant, arm64

===== <code>12MMMPPpVA</code> =====
Basically the same thing, just shifted to the right by eating up the unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 clean arm64, as above.

===== <code>12MMPPpxVA</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 clean arm64, as above.

Android

2025-10-02T09:21:50Z

AI: /* Other version code scheme drafts */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid creates the file /data/Dist with contents "F-Droid" during the build process)
* we may want various variants of builds, that is, a "clean" build, a build with google play integrations, a build with a different integration, and so on. This may or may not be tied to the store the APK is distributed on

Drafts of possible approaches:

===== <code>MMMPPpxxxV</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - ABI
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, arm64

===== <code>12MMMPPpxV</code> =====
Basically the same thing, just shifted to the right by eating up unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 arm64, as above.

===== <code>12MMPPpxxV</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 arm64, as above.

Android

2025-10-02T09:01:21Z

AI: /* Other version code scheme drafts */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9.
The highest version code currently (2025-10-02) in use is 1191601002.

Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid adds an identifier in its build process)
* we may want builds with or without certain integrations (like google play integrations). This may or may not be tied to the store

Drafts of possible approaches:

===== <code>MMMPPpxxxV</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - ABI
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, arm64

===== <code>12MMMPPpxV</code> =====
Basically the same thing, just shifted to the right by eating up unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 arm64, as above.

===== <code>12MMPPpxxV</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 arm64, as above.

Android

2025-10-02T09:00:22Z

AI: /* Other version code scheme drafts */

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible. The PR to remove/disable the existing version codes on f-droid has been rejected, so we're probably stuck with version codes > 1.19e9
The highest version code currently (2025-10-02) in use is 1191601002.
Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid adds an identifier in its build process)
* we may want builds with or without certain integrations (like google play integrations). This may or may not be tied to the store

Drafts of possible approaches:

===== <code>MMMPPpxxxV</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - ABI
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, arm64

===== <code>12MMMPPpxV</code> =====
Basically the same thing, just shifted to the right by eating up unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 arm64, as above.

===== <code>12MMPPpxxV</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 arm64, as above.

Android

2025-10-02T08:58:42Z

AI:

This pages contains some specific information about the Battle for Wesnoth new Android port (1.19+)

== Playing controls ==
* Tap a unit to select/deselect it.
* Tap a unit, then tap the target hex to show defense stats of that unit and footsteps. (Similar to hover on PC)
* Tap a unit, then double tap on the target hex to move it. Alternative, you can drag along the path to choose the exact path which the unit is supposed to move by.
* Drag from attacker unit towards attacked unit to attack.

== The Settings menu (Splash screen) ==

== Logs and debugging steps ==
* Install adb (Android Debug Bridge) on your computer. Search internet for information about your OS. Install drivers for your phone/tablet if necessary.
* Enable Developer Mode on your Android device (phone/tablet). Again, the internet is your friend. On newer devices, you need tap Settings > About Phone > Build Number 7 times until it says "You are now a developer", then go into the Setting > System > Developer Options (newly appeared), and find "USB Debugging" in the menu and turn that on.
* Connect phone to PC. Do <code>adb logcat</code> or similar from a terminal/command prompt to see if your device appears on the list and is authorized. Tap ok on your phone if any permission request appears.
* Run <code>adb logcat -c</code> (clears existing logs), then <code>adb logcat > log.txt</code> (or <code>adb logcat</code> and copy from terminal). Run Wesnoth on phone. Reproduce the crash.
* stop <code>adb logcat</code> on PC, and attach the <code>log.txt</code> to your issue report on github along with detailed steps of the bug, and use the Android label.

(Note: adb can be <code>./adb.exe</code> on Windows. Use internet for help on any of the steps if needed, this is supposed to be a preliminary guideline. Steps might slightly differ based on manufacturer or Android version.)

=== Enabling taps ===
It is useful for debugging purposes, especially if you're sharing a screen recording of your bug, to show where you're tapping on the screen in the screen recording. See [https://discussio.zendesk.com/hc/en-gb/articles/4625151970065-How-to-Show-Taps-for-Mobile-Screen-Sharing-on-Android here] for how to enable that.

=== Turning off Developer Mode ===
Go to System > Developer Options and turn off the '''Use developer options''' toggle.

=== Dev Notes ===
==== Version Code scheme (1191601001 - post 1.19.16 fixup) ====
<code>MmmPPppVVV</code>

Where,
* <code>M</code> - Major version code, so far at 1; since the max versionCode is 21000000 it can go up to 2
* <code>mm</code> - Minor version code.
* <code>PP</code> - Patch version code.
* <code>pp</code> - Android patch version/any other use.
* <code>VVV</code> - Reserved for ABI/Variants.
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Rest unused (variants if we need them)

==== New Version Code scheme draft ====
This is but one possible idea among many, and is not final.

<code>MSUUmmPPppVV</code>

Where,
* 1 - Major version code. Wesnoth's version's first digit is almost always 1, but the max versionCode is 21000000 so it can go upto 2 if needed.
* S - store identifier (must be greater than 2 to allow upgrade from previous scheme.) For example:
** <code>2</code> - F-Droid
** <code>3</code> - Google Play
** Others if needed.
* UU - unused/unspecified.
* mm - Minor version
* PP - Patch version
* pp - Android Patch version
* VV - ABI/Variants
** Last digit - ABI (<code>['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86': 3, 'x86_64': 4]</code>)
** Last but one digit - Unused (variants if we need them)

E.g., 1.20.14 with hotfix 1, Fdroid, arm64 ABI would be: <code>120020140102</code>.

==== Other version code scheme drafts ====

Given that we only have 10 digits to work with (max being 2.1e9, which is signed INT_MAX with some margin), the above scheme is not possible.
The highest version code currently (2025-10-02) in use is 1191601002.
Further constraints are:
* version codes should go up
* each ABI needs its own version code
* we may have multiple APK releases for one "regular wesnoth version" to fix android-only issues (android patch version)
* we may have builds that differ per store (F-droid adds an identifier in its build process)
* we may want builds with or without certain integrations (like google play integrations). This may or may not be tied to the store

Drafts of a possible approaches:

===== <code>MMMPPpxxxV</code> =====
* MMM - Combined Major/Minor: 1.19 = 119, but each subsequent minor *or* major bump increases this number by 1. This remains visually the same until 2.0 happens.
* PP - Patch version
* p - Android patch version
* V - ABI
* x - Unspecified, available for expanding these fields or adding other flags (like store and/or integrations)

Example: <code>1220320002</code> would be version 1.22 (or 2.0 or 2.2, but 2 stables from 1.18), patch 3, android patch 2, arm64

===== <code>12MMMPPpxV</code> =====
Basically the same thing, just shifted to the right by eating up unspecified digits, and with the first digits fixed to 12. Leaves 8 "additional epochs" available for future expansion.

Example: <code>1212203202</code> would be version 1.22.3.2 arm64, as above.

===== <code>12MMPPpxxV</code> =====
Removes the major version digit, freeing up 1 digit. Not functionally different from the major-minor scheme, but reduces the number of available version bumps until epoch change.

Example: <code>1222032002</code> would be version 1.22.3.2 arm64, as above.

Eastern History

2019-06-14T15:05:52Z

AI:

This page is to describe history that occurred in the Silver Lands, the region east of what is on the main map. Currently, it also describes some things to the south of wesnoth. This should eventually be moved, or we could rename the page.

[https://sourceforge.net/p/wesnoth-umc-dev/code/HEAD/tree/branches/resources/images/maps/wesnoth-north-silver_lands.jpg?format=raw Best map as of 2019-06-14].
Relevant part is everything to the south-east of Lin-Elens.

== Prehistory ==
* Elves inhabit Lin-Elens.
* Minotaurs live on the plains around the Lake Aoir. (named Minotaur's Lake on the map)
* Dwarves live in the mountains around Firecloud Peak. They are prohibited by treaty with the elves from claiming the hills south of the great river.
* The Eltireans live in floating isles hidden above the eastern side of the Flamebreath Desert.
* Saurians live in the Ssyuriss Fenn.

== 20 BW - 200 YW: Drakes and Dwarves ==

=== 20 BW ===
* Dwarves from Firecloud Peak cross the Great River and colonize the hills of Triththa.

=== 181 YW ===
* The Silver Drakes attack Firecloud peak and the surrounding area, drafting most of the saurians from Ssyuriss Fenn into their ranks.
* The dwarvish defenses crumble under the combined offensive. When it becomes clear that the war is lost, the survivors evacuate to Triththa.
* The saurians suffer the brunt of the casualties in the war. The remainder are enslaved by the drakes.

=== 182 YW ===
* The saurians remaining in Ssyuriss Fenn are soundly defeated by a Triththan offensive. The remnants of their civilization are a number of disorganised tribes.

== 20-400 YW: Arrival of humans ==
The period in which humans first entered the Silver Lands, and carved out their own nations.

=== 23 YW ===
* Human settlement of the Estmarks begins.

=== 99-127 YW ===
* Large increase in the use of magic in the Estmarks.

=== 127 YW ===
* An orcish invasion pushes the settlers south, out of the Estmarks, before the Grand Army of Wesnoth can arrive.
* The settlers found a number of new settlements on the edge of the Kerlath hills and the Sandy Wastes.
* The orcish horde is driven out by the numerically superior Grand Army of Wesnoth, but some tribes desert and settle the areas furthest from wesnoth.
* Contact between the settlers and the Kingdom of Wesnoth is lost completely.
* The settlers acquire a distaste for magic, thinking its use brought on the orcish horde.

=== 171-300 YW ===
* The settlers expand around the edge of the desert, eventually reaching the mountains south of Lake Aoir.

=== 336 YW ===
* A large group of magic-using settlers leaves the desert, heading north.

=== 337-368 YW ===
* The exiles settle in the plains near the Lin-Elens.
* The exiles rapidly expand their territory.
* Ideological conflict about types of magic starts fracturing the new nation.
* The sides eventually consolidate around the cities of Noct and Diurna, on opposite sides of the river.

=== 395-398 YW ===
* The various tribes around the desert are unified as the Khalifate. Magic is outlawed

== ? ==

=== 546-550 YW ===
* Contact between the Khalifate and Wesnoth is reestablished, trade flourishes.

=== 551 YW ===
* Ravanal is banished from the Khalifate for the use of magic.

== 1283-? YW: the Era of Strife ==
=== 1283 YW ===
* Start of the great war in the Silver Lands, thus marking the beginning of the Era of Strife

Under construction...

For that reason, no category tags have yet been added.

DataURI

2018-03-20T12:14:18Z

AI:

Instead of referring to an image included in an add-on, an image path may also contain the image directly as a [https://en.wikipedia.org/wiki/Data_URI_scheme Data URI (wikipedia)]. This can be useful for add-on icons in the [[PblWML]] (which may otherwise only contain core images) or for single-file scenarios.

Beyond these cases, Data URIs are less useful, as they are larger than the images themselves, and clutter up the files that include them.

== Format ==

A Data URI appears as follows: <code>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

It can be split into the following sections:
<code>data</code> <code>image/png;base64</code> <code>iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

==== Schema ====
The <code>data:</code> part specifies that this is a Data URI.

==== Mime type ====
The <code>image/png</code> part specifies that this is a PNG image. Also supported is <code>image/jpeg</code>.

===== base64 =====
Technically part of the mime type, this specifies that the image data is encoded using Base64.

==== Data ====
The random-looking characters following the comma are the actual image data.

== Creating a Data URI ==
Wesnoth does not yet support generating a Data URI for you, but there are alternatives.

=== Websites ===
There are a large number of Data URI generator websites. Googling for [https://google.com/search?q=data+uri+generator data uri generator] will find them.

=== Manually ===
Creating a data URI by hand can be accomplished by taking your image, Base64-encoding it and formatting it as shown above.

DataURI

2018-03-15T14:14:35Z

AI:

Instead of referring to an image included in an add-on, an image path may also contain the image directly as a [https://en.wikipedia.org/wiki/Data_URI_scheme Data URI (wikipedia)]. This can be useful for add-on icons in the [[PblWML]] (which may otherwise only contain core images) or for single-file scenarios.

Beyond these cases, Data URIs are less useful, as they are larger than the images themselves, and clutter up the files that include them.

== Format ==

A Data URI appears as follows: <code>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

It can be split into the following sections:
<code>data</code> <code>image/png;base64</code> <code>iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

==== Schema ====
The `data:` part specifies that this is a Data URI.

==== Mime type ====
The `image/png` part specifies that this is a PNG image. Also supported is `image/jpeg`.

===== base64 =====
Technically part of the mime type, this specifies that the image data is encoded using Base64.

==== Data ====
The random-looking characters following the comma are the actual image data.

== Creating a Data URI ==
Wesnoth does not yet support generating a Data URI for you, but there are alternatives.

=== Websites ===
There are a large number of Data URI generator websites. Googling for [https://google.com/search?q=data+uri+generator data uri generator] will find them.

=== Manually ===
Creating a data URI by hand can be accomplished by taking your image, Base64-encoding it and formatting it as shown above.

FancyAddonIcons

2018-03-15T14:14:22Z

AI:

An add-on's icon is the first thing a player is going to look at when picking add-ons. A good add-on icon can attract many players, so it should not be neglected. However, custom images cannot be used, they will be seen only by people who have it installed, that usually means that the author will think it's correct, although it is not. Despite this limitation, there is a way to create quite cool add-on icons. It is called [[ImagePathFunctionWML]]. Another method that can be used is a [[DataURI]]

== Introduction ==
Of course, you can create a code like (careful, it is long!):
items/bonestack.png~BLIT(items/bonestack.png~CROP(20,0,52,52),0,20)~BLIT(items/bonestack.png~CROP(0,0,52,52),20,20)~BLIT(items/burial.png~CROP(20,0,52,72),0,0)~BLIT(items/burial.png~CROP(0,0,52,62),20,10)~BLIT(units/undead-skeletal/archer-die2-6.png~CROP(10,0,62,62)~RC(magenta>black),0,10)~BLIT(units/orcs/sovereign-lead-2.png~RC(magenta>black))~BLIT(items/burial.png~CROP(0,0,62,52),10,20)

But testing this will be very tedious and annoying, reloading the entire add-on to view it somewhere, or even uploading it to test it every time. To make this easier, download an add-on named ''Image loading tester'', it will help you a lot with this. The add-on is absolutely minimalistic, and has no obvious effect anywhere. To use it, either execute this WML chunk:
[lua]
code=<<wesnoth.image_test()>>
[/lua]

Or activate the debug mode (:debug in [[CommandMode]]), and use this command:
lua wesnoth.image_test()
The second option is probably more convenient.

A window will show up, there will be a text box and two buttons. Type your image code into the text box and click on the Show button (or hit Enter instead). This way, you will be able to verify it very quickly. It is recommended to do this while running wesnoth from command prompt (on Windows) or Terminal (on Linux), it will notice you about some errors in your code (on Windows, you can also read stderr.txt afterwards).

Because the code on a single line possibly with many nested brackets is almost unreadable for humans, it is recommended to write it in a text file with indentation and new lines, then to use Find&Replace to remove all tabs, spaces and new lines and paste it into the text box. I will use indented codes later, for better readability, and it will be necessary to remove all spaces and new lines from it or copying the version when it is already removed bellow it if you want to try it out.

To understand better the numeric values that look like just made up to fit, you might want to learn the coordinates needed in an image editor like GIMP.

It is also recommended to use wesnoth 1.12 or later wesnoth 1.11, 1.10 tends to randomly crash when copying stuff from the textbox and that annoys a lot, even if it happens only sometimes. I have written the examples to work with these versions.

Now, you can verify your codes easily, and you can progress to the next step.

== Step by step tutorial ==
Let us think about creating an add-on image for a campaign where elves attack undead. It would consist of an Elvish Hero chopping undead to pieces, supported by spells of an Elvish Sorceress behind him. We will create an image for it in several steps. Try out each one of them to see what is changed.

'''1.''' Image showing an Elvish Hero in an attacking position is units/elves-wood/hero-melee-3.png. So we start with it:
units/elves-wood/hero-melee-3.png

'''2.''' Nothing interesting so far. Let us add a skeleton he is slashing. The image units/undead-skeletal/skeleton/skeleton-se-melee3.png is in a good fighting position, also exposing his belly to our hero. We will use the ~BLIT function of [[ImagePathFunctionWML]] to add him to the picture. Now we have:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png
)
Note that the new lines and indentation are added only for readability, it will not work in game, you'll have to remove all new lines and breaks. Here it is without indents:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png)

'''3.''' However, they are quite in an awkward position. We will need to add some offset to the skeleton. ~BLIT accepts two additional arguments that mean the offset of the image. However, it would not fit on the image then (this prints an error message into the command line, Termina or stderr.txt), so we need to crop it. The ~CROP function accepts four arguments, the first two are the coordinates where the selected part of the image should start (pixels to the right first, pixels down second), the second two is the desired size of the result (width and height respectively). In this case, we start cropping on the top left corner, therefore the first two coordinates will be 0 and 0. The offset will be 20,20 (pixels to left first, pixels down second), so we need the resolution of the image to be 52x52 (original is 72x72, we subtract 20 from both numbers). The four arguments of crop will be therefore 0,0,52,52, and the two additional arguments of ~BLIT will be 20,20. Together, it should look like this:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(0,0,52,52)
,20,20)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(0,0,52,52),20,20)

'''4.''' Now, the skeleton needs to be headed differently, because he isn't attacking the hero. The ~FLIP function is designed for this. Use ~FLIP(horizontal) for this. We will also need to adjust the offset in CROP and BLIT, because it would look bad:
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,47)~FL(horizontal)
,40,20)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,47)~FL(horizontal),40,20)

'''5.''' However, we want the skeleton to be chopped in half by the Hero's sword. We can do this by placing two conveniently cropped images of skeleton one above another.
units/elves-wood/hero-melee-3.png
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)
,40,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)
,40,47)
Or without indentation:
units/elves-wood/hero-melee-3.png~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal),40,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal),40,47)

'''6.''' We want our heroes to be also teamcoloured, so we can change the default colour (magenta) to some other colour. The colours you can change it to can be found in the data/core/team_colors.cfg file. The colours are changed using the ~RC function. Because our heroes are good and the undead are bad, let's team-colour the undead black and the heroes white.
units/elves-wood/hero-melee-3.png~RC(magenta>white)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)~RC(magenta>black)
,40,47)
Or without indentation:
units/elves-wood/hero-melee-3.png~RC(magenta>white)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,22)~FL(horizontal)~RC(magenta>black),40,47)

'''7.''' Now, we want to add the Sorceress casting a spell to the background. She should be behind the Elvish Hero, and she should have an offset, but that can be done by cropping. To make sure that she won't be hid behind the Hero too badly, the hero and the skeleton will have to be offset too. Because we need an image of dimensions 72x72 as background, and a cropped Sorceress does not have such dimensions, we will have to use misc/blank-hex.png as background (it is a blank image) and place the sorceress on it. The offsets were adjusted to make it look better.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(15,10,57,62),0,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''8.''' Now, we need to add some halo to her, she is casting a spell, no? A suitable halo can be halo/elven/faerie-fire-halo4.png, let's use it. Its resolution is 96x96, that is quite awkward because it is larger than our image, but we can crop it easily.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''9.''' Now, to add the homing missile of the spell. halo/elven/ice-halo3.png looks convenient. Placing it on the image together with a skeleton that would be the victim of this spell is analogical to things done previously.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)
,30,0)
~BLIT(
halo/elven/ice-halo3.png~CROP(0,20,62,52)
,10,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(halo/elven/ice-halo3.png~CROP(0,20,62,52),10,0)~BLIT(units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black),30,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

'''10.''' We might colourise the skeleton blue, to make him appear frozen. There are two functions for this, ~CS and ~GS. ~GS removes all colour, transforming all colours into shades of gray. ~CS is used to change the colour, it accepts three arguments, the change to the red colour, the change to the green colour and the change to the blue colour. Negative numbers (from -1 to -255) mean removing the colour from all pixels (respecting transparency), so ~CS(0,-255,-255) will remove all colours except red, so that only the red part of the light will remain. Positive numbers (from 1 to 255) will add the colour to all pixels (unless invisible), so ~CS(255,0,0) will set the red fraction of the colour to maximum. ~CS(255,-255,-255) will remove all colours but red, and add a maximum of red everywhere, creating a single-colour image. To create the effect of frozen, we first use ~GS and then we use ~CS to make it bluer.
misc/blank-hex.png
~BLIT(
units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62)
,0,0)
~BLIT(
halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52)
,0,0)
~BLIT(
units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)~GS()~CS(50,50,150)
,30,0)
~BLIT(
halo/elven/ice-halo3.png~CROP(0,20,62,52)
,10,0)
~BLIT(
units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62)
,0,10)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black)
,40,20)
~BLIT(
units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black)
,40,57)
Or without indentation:
misc/blank-hex.png~BLIT(units/elves-wood/sorceress-magic-3.png~RC(magenta>white)~CROP(10,15,57,62),0,0)~BLIT(halo/elven/faerie-fire-halo4.png~CROP(14,44,72,52),0,0)~BLIT(units/undead-skeletal/deathblade-idle-2.png~FL(horizontal)~CROP(0,15,42,67)~RC(magenta>black)~GS()~CS(50,50,150),30,0)~BLIT(halo/elven/ice-halo3.png~CROP(0,20,62,52),10,0)~BLIT(units/elves-wood/hero-melee-3.png~RC(magenta>white)~CROP(0,0,72,62),0,10)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,5,32,29)~FL(horizontal)~RC(magenta>black),40,20)~BLIT(units/undead-skeletal/skeleton/skeleton-se-melee3.png~CROP(20,35,32,12)~FL(horizontal)~RC(magenta>black),40,57)

Now, we are done with this image.

== More examples ==
Here are more examples of stuff you can do using these methods. They don't contain precise information how it is done, but it should be clear if you have read the tutorial.

=== The Spellsword ===
The purpose of this example is to show the usage of the opacity ~O function. When called on magical halo, it can be used to make the halo partially before and partially behind the unit (place the image there twice with 50% opacity, once under him, once above him). It can be also used to create motion blur.

halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~CROP(6,6,66,66)~O(25%)~RC(magenta>blue)
)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~CROP(3,3,69,69)~O(50%)~RC(magenta>blue)
)
~BLIT(
units/elves-wood/high-lord-attack-sword-2.png~RC(magenta>blue)
)
~BLIT(
halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)
)
~BLIT(
halo/elven/faerie-fire-halo3.png~CROP(0,5,57,72)
,15,0)
Without indentation:
halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%)~BLIT(units/elves-wood/high-lord-attack-sword-2.png~CROP(6,6,66,66)~O(25%)~RC(magenta>blue))~BLIT(units/elves-wood/high-lord-attack-sword-2.png~CROP(3,3,69,69)~O(50%)~RC(magenta>blue))~BLIT(units/elves-wood/high-lord-attack-sword-2.png~RC(magenta>blue))~BLIT(halo/elven/elven-shield-halo-100pct.png~CROP(44,44,72,72)~O(50%))~BLIT(halo/elven/faerie-fire-halo3.png~CROP(0,5,57,72),15,0)

=== Zorro ===
The purpose of this example is to show that some body parts can be taken from the original body (provided that they can be selected easily), modified and placed back. Or placed on to different place. Or to a completely different sprite.

units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)
~BLIT(
units/human-loyalists/master-at-arms-crossbow-2.png~CROP(2,27,18,14)~FL(horiz)
,48,27)
~BLIT(
units/human-outlaws/assassin-throwknife1.png~CROP(29,17,11,13)~RC(magenta>black)
,26,21)
~BLIT(
halo/misc/leadership-flare-7.png~CROP(0,5,46,67)
,26,0)
~BLIT(
halo/misc/leadership-flare-6.png~CROP(33,7,39,65)
,0,0)
~BLIT(
units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~CROP(20,11,20,17)~CS(-100,-100,-100)
,20,11)
Without indentation:
units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~BLIT(units/human-loyalists/master-at-arms-crossbow-2.png~CROP(2,27,18,14)~FL(horiz),48,27)~BLIT(units/human-outlaws/assassin-throwknife1.png~CROP(29,17,11,13)~RC(magenta>black),26,21)~BLIT(halo/misc/leadership-flare-7.png~CROP(0,5,46,67),26,0)~BLIT(halo/misc/leadership-flare-6.png~CROP(33,7,39,65),0,0)~BLIT(units/human-loyalists/master-at-arms-crossbow-2.png~RC(magenta>black)~CROP(20,11,20,17)~CS(-100,-100,-100),20,11)

=== Lich Wars ===
The purpose of this is to show how can text be used in the graphics. It mostly revolves around the misc/font8x8.png file (it is not in core, but in another images folder belonging to the game, next to the data folder that contains the core folder; using it causes no trouble).

misc/blank-hex.png
~BLIT(
units/undead-skeletal/deathblade-dying-2.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)~O(50%)
,10,10)
~BLIT(
units/undead-skeletal/deathblade-dying-1.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)
,10,10)
~BLIT(
units/undead-necromancers/ancient-lich-melee.png~RC(magenta>red)~CROP(20,10,52,62)
)
~BLIT(
halo/undead/black-magic-3.png~FL(vert)~CROP(15,40,72,60)~O(70%)
)
~BLIT(
misc/blank-hex.png
~BLIT(
misc/font8x8.png~CROP(39,33,8,8)
,16,56)
~BLIT(
misc/font8x8.png~CROP(16,32,8,8)
,24,56)
~BLIT(
misc/font8x8.png~CROP(47,24,8,8)
,32,56)
~BLIT(
misc/font8x8.png~CROP(8,33,8,8)
,40,56)
~BLIT(
misc/font8x8.png~CROP(48,41,8,8)
,16,64)
~BLIT(
misc/font8x8.png~CROP(32,25,8,8)
,24,64)
~BLIT(
misc/font8x8.png~CROP(8,40,8,8)
,32,64)
~BLIT(
misc/font8x8.png~CROP(16,41,8,8)
,40,64)
~CS(-255,0,-255)
)
Without indentation:
misc/blank-hex.png~BLIT(units/undead-skeletal/deathblade-dying-2.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62)~O(50%),10,10)~BLIT(units/undead-skeletal/deathblade-dying-1.png~FL(horiz)~RC(magenta>red)~CROP(0,0,62,62),10,10)~BLIT(units/undead-necromancers/ancient-lich-melee.png~RC(magenta>red)~CROP(20,10,52,62))~BLIT(halo/undead/black-magic-3.png~FL(vert)~CROP(15,40,72,60)~O(70%))~BLIT(misc/blank-hex.png~BLIT(misc/font8x8.png~CROP(39,33,8,8),16,56)~BLIT(misc/font8x8.png~CROP(16,32,8,8),24,56)~BLIT(misc/font8x8.png~CROP(47,24,8,8),32,56)~BLIT(misc/font8x8.png~CROP(8,33,8,8),40,56)~BLIT(misc/font8x8.png~CROP(48,41,8,8),16,64)~BLIT(misc/font8x8.png~CROP(32,25,8,8),24,64)~BLIT(misc/font8x8.png~CROP(8,40,8,8),32,64)~BLIT(misc/font8x8.png~CROP(16,41,8,8),40,64)~CS(-255,0,-255))

[[Category:WML_Tips]]

PblWML

2018-03-15T14:10:23Z

AI:

{{WML Tags}}

To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.

See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.

Note: Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.

: Instead of a standard Wesnoth image, a [[DataURI]] can also be used. This way, an image can be directly included into the _server.pbl file.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.
: '''This value is required'''.

=== version ===
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers — and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the “Update All” button to work correctly. ([[#Version Key Examples|See Examples]])
: '''This value is required'''.

=== author ===
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.
: '''This value is required'''.

=== passphrase ===
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.
: '''This value is required'''.

=== dependencies ===
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== tags ===
{{DevFeature1.13|12}}
: An optional string including a comma-separated list of keywords used for matching add-ons when typing terms into the Filter box on the top left of the Add-ons Manager. There are no specific requirements on the syntax of the keywords listed here, but a general recommendation is to keep them relevant for players. For example, one might include the add-on's acronym in the tags, the names or acronyms of add-ons to which it is related, and so on.

=== core ===
{{DevFeature1.13|0}}
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself.

=== translate ===
: If set to ''true'', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)

: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.

=== type ===
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:

:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}
:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''campaign_sp_mp'': hybrid campaign.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''mod_mp'': multiplayer modification.
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
:* ''other'': The type to use when no other type fits.
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

: '''This value is required'''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.
: '''This value is required'''.

=== [feedback] ===
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.

==== topic_id ====
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

The following are examples of '''good''' version values:

version="1.5"
version="0.11.4"
version="0.1.4beta"
version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"
version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0
1.5 < 1.5c
1.0 < 1.0.1
1.0c < 1.0.1a
1.0.1a < 1.0.1c
1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

<syntaxhighlight lang=wml>
title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"
# The following tag is only used by Wesnoth 1.11.8 and later!
[feedback]
topic_id=12345
[/feedback]
</syntaxhighlight>

== See Also ==

* [[IGNFileFormat]]
* [[FancyAddonIcons]]
* [[ReferenceWML]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

DataURI

2018-03-15T14:09:57Z

AI: Created page with "Instead of referring to an image included in an add-on, an image path may also contain the image directly as a [https://en.wikipedia.org/wiki/Data_URI_scheme Data URI (wikiped..."

Instead of referring to an image included in an add-on, an image path may also contain the image directly as a [https://en.wikipedia.org/wiki/Data_URI_scheme Data URI (wikipedia)]. This can be useful for add-on icons in the [[PblWML]] (which may otherwise only contain core images) or for single-file scenarios. Beyond these cases, Data URIs are less useful, as they are larger than the images themselves, and clutter up the files that include them.

== Format ==

A Data URI appears as follows: <code>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

It can be split into the following sections:
<code>data</code> <code>image/png;base64</code> <code>iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code>

==== Schema ====
The `data:` part specifies that this is a Data URI.

==== Mime type ====
The `image/png` part specifies that this is a PNG image. Also supported is `image/jpeg`.

===== base64 =====
Technically part of the mime type, this specifies that the image data is encoded using Base64.

==== Data ====
The random-looking characters following the comma are the actual image data.

== Creating a Data URI ==
Wesnoth does not yet support generating a Data URI for you, but there are alternatives.

=== Websites ===
There are a large number of Data URI generator websites. Googling for [https://google.com/search?q=data+uri+generator data uri generator] will find them.

=== Manually ===
Creating a data URI by hand can be accomplished by taking your image, Base64-encoding it and formatting it as shown above.

Eastern History

2014-04-25T00:37:33Z

AI: Remove from candidates for deletion

This page is to describe history that occurred in the Silver Lands, the region east of what is on the main map. Currently, it also describes some things to the south of wesnoth. This should eventually be moved, or we could rename the page.

[http://postimage.org/image/amrz0frzz/ Best map as of 2011-11-01].
Relevant part is everything to the south-east of Lin-Elens.

== Prehistory ==
* Elves inhabit Lin-Elens.
* Minotaurs live on the plains around the Lake Aoir. (named Minotaur's Lake on the map)
* Dwarves live in the mountains around Firecloud Peak. They are prohibited by treaty with the elves from claiming the hills south of the great river.
* The Eltireans live in floating isles hidden above the eastern side of the Flamebreath Desert.
* Saurians live in the Ssyuriss Fenn.

== 20 BW - 200 YW: Drakes and Dwarves ==

=== 20 BW ===
* Dwarves from Firecloud Peak cross the Great River and colonize the hills of Triththa.

=== 181 YW ===
* The Silver Drakes attack Firecloud peak and the surrounding area, drafting most of the saurians from Ssyuriss Fenn into their ranks.
* The dwarvish defenses crumble under the combined offensive. When it becomes clear that the war is lost, the survivors evacuate to Triththa.
* The saurians suffer the brunt of the casualties in the war. The remainder are enslaved by the drakes.

=== 182 YW ===
* The saurians remaining in Ssyuriss Fenn are soundly defeated by a Triththan offensive. The remnants of their civilization are a number of disorganised tribes.

== 20-400 YW: Arrival of humans ==
The period in which humans first entered the Silver Lands, and carved out their own nations.

=== 23 YW ===
* Human settlement of the Estmarks begins.

=== 99-127 YW ===
* Large increase in the use of magic in the Estmarks.

=== 127 YW ===
* An orcish invasion pushes the settlers south, out of the Estmarks, before the Grand Army of Wesnoth can arrive.
* The settlers found a number of new settlements on the edge of the Kerlath hills and the Sandy Wastes.
* The orcish horde is driven out by the numerically superior Grand Army of Wesnoth, but some tribes desert and settle the areas furthest from wesnoth.
* Contact between the settlers and the Kingdom of Wesnoth is lost completely.
* The settlers acquire a distaste for magic, thinking its use brought on the orcish horde.

=== 171-300 YW ===
* The settlers expand around the edge of the desert, eventually reaching the mountains south of Lake Aoir.

=== 336 YW ===
* A large group of magic-using settlers leaves the desert, heading north.

=== 337-368 YW ===
* The exiles settle in the plains near the Lin-Elens.
* The exiles rapidly expand their territory.
* Ideological conflict about types of magic starts fracturing the new nation.
* The sides eventually consolidate around the cities of Noct and Diurna, on opposite sides of the river.

=== 395-398 YW ===
* The various tribes around the desert are unified as the Khalifate. Magic is outlawed

== ? ==

=== 546-550 YW ===
* Contact between the Khalifate and Wesnoth is reestablished, trade flourishes.

=== 551 YW ===
* Ravanal is banished from the Khalifate for the use of magic.

== 1283-? YW: the Era of Strife ==
=== 1283 YW ===
* Start of the great war in the Silver Lands, thus marking the beginning of the Era of Strife

Under construction...

For that reason, no category tags have yet been added.

DutchTranslation

2014-03-09T22:50:01Z

AI: /* Dutch translation */

== Dutch translation ==

=== Status 2014-03-09 ===
1.12 is in beta en verdere 1.10 releases zijn onwaarschijnlijk. Alle versies op [http://gettext.wesnoth.org] wijzen naar de 1.11 branch. [[TextdomainStatus]] kan een indicatie geven van welke textdomains beter geschikts zijn om nu te vertalen. (maar de stringfreeze is al begonnen, dus alles moet nu klaar staan.

=== Vertalers ===
Deze informatie is verouderd.

==== Actieve vertalers ====
* Alexander van Gessel (AI/AI0867) - [mailto:AI0867_AT_gmail.com]
* Ijsbrand Oudshoorn - [mailto:oudshoorn_AT_eitri_DOT_nl]
* Foppe Benedictus (Fopper) - [mailto:foppeDOTbenedictusATgmailDOTcom]
* LightFighter
* Jon Jacobs
* Koen Vervloesem (koan) - [mailto:koenATvervloesemDOTeu]

==== Inactieve vertalers ====
* Joeri Melis
* Thomas Hugo de Groot
* Thijs van der Spek
* Rob van der Vleugel - [mailto:vleugelATgmailDOTcom]
* Pieter Vermeylen (Onne) - [mailto:pitoeATinameDOTcom]
* Roel Thijs (Roel) - [mailto:roel.thijsATgmailDOTcom]
* Tobe Deprez - [mailto:tobedeprezATscarletDOTbe]
* Arne Deprez - [mailto:arnedeprezATscarletDOTbe]
* Julien Rossi (Tux2b) - [mailto:julienATrossiDOTbiz]
* Ernst Segers - [mailto:ernst1700ATgmailDOTcom]
* Roger Koot - [mailto:rDOThDOThDOTkootATmedDOTuuDOTnl]
* Maarten Albrecht (bloom) - [mailto:maartenalbrechtATgmailDOTcom]
* Koen Douterloigne - [mailto:hagnorATyahooDOTcom]

=== Afspraken ===
Probeer consistent te zijn tussen verschillende textdomains. Als bijvoorbeeld een eenheid in een veldtocht en in wesnoth-units een andere naam heeft is dat erg onduidelijk.

====Vertaling van allianties====
{| class="wikitable"
! Engels !! Nederlands
|-
| Lawful || Gezagsgetrouw
|-
| Neutral || Neutraal
|-
| Chaotic || Wetteloos
|-
|}

====Vertaling van rassen====
{|class="wikitable"
!Engels!!Nederlands
|-
|Drakes||Draaklingen
|-
|Dwarves||Dwergen
|-
|Elfs||Elfen
|-
|Goblins||Kobolds
|-
|Gryphons||Griffioenen
|-
|Human||Mensen
|-
|Orcs||Orks
|-
|Saurians||Saurianen
|-
|Troll||Trollen
|-
|Undead||Ondoden
|-
|Ogres||Boemannen
|-
|Mermen||Meermannen
|-
|Monsters||Monsters
|-
|Nagas||Nagas
|-
|Wose||Enten
|-
|}

Eenheden zijn te vinden in de [http://units.wesnoth.org eenhedenboom]

==== Aanpassingsvoorstellen ====
{| class="wikitable"
! Engels !! Nederlands !! Voorstel
|-
| Alignment || Alliantie || Iets anders, mogelijk gebaseerd op activiteitscyclus
|-
|}

=== Claims ===

De nieuwe manier om bij te houden waar je mee bezig bent. Als het engels van een groene vertaling is aangepast of de tijdsduur is verstreken, kan je de taak zelf claimen.

{| class="wikitable"
!Textdomain||Vertaler||Claimdatum||Deadline/Tijdsduur
|-
!colspan="5"| Core
|- style="text-decoration:line-through; color:green;"
|wesnoth||GCI||27 December 2010||10 januari 2011
|- style="text-decoration:line-through; color:green;"
|wesnoth-anl||AI||27 December 2010||een paar dagen
|- style="text-decoration:line-through; color:green;"
|wesnoth-editor||AI||27 December 2010||een paar dagen
|- style="text-decoration:line-through; color:green;"
|wesnoth-help||GCI||27 December 2010||10 januari 2011
|- style="text-decoration:line-through; color:green;"
|wesnoth-units||GCI||27 December 2010||10 januari 2011
|-
!colspan="5"| Mainline veldtochten
|- style="text-decoration:line-through; color:green;"
|wesnoth-aoi||GCI||27 December 2010||10 januari 2011
|- style="text-decoration:line-through; color:green;"
|wesnoth-thot||GCI||27 December 2010||10 januari 2011
|-
!colspan="5"| UMC
|}
{| class="wikitable"
|+ Legenda
! Status !! Vertalen?
|- style="color:blue;"
| Geclaimd || Nee
|- style="color:green;"
| Af || Nee
|- style="color:orange;"
| Verouderd || Ja
|- style="color:black;"
| Ongeclaimd || Ja
|}
[[Category:Translations]]

=== See Also ===

* [[WesnothTranslations]]
* [http://gettext.wesnoth.org Translation statistics]

[[Category:Translations]]

Timeline of Wesnoth

2014-03-07T05:39:28Z

AI: /* 21 YW */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 501 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 534 YW ===

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

=== 535 YW ===

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

=== 550 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

===858 YW===

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

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

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

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

== History Credits ==

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

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

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

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]
* [[Future History]] '''(unofficial)'''

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

InterfaceActionsWML

2013-11-25T19:30:59Z

AI: /* [scroll_to] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. (Note: Don't use this if the message has options, as such message can only be shown to the current player.)
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''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.
* '''[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.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.
The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event fill be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''use_hotkey''' {{DevFeature1.11}}: if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''' {{DevFeature1.11}}: contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
* {{DevFeature1.11}} '''force_scrolling''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
* {{DevFeature1.11}} '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* {{DevFeature1.11}} '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

InterfaceActionsWML

2013-11-25T19:30:42Z

AI: /* [scroll_to_unit] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. (Note: Don't use this if the message has options, as such message can only be shown to the current player.)
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''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.
* '''[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.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.
The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event fill be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''use_hotkey''' {{DevFeature1.11}}: if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''' {{DevFeature1.11}}: contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
* {{DevFeature1.11}} '''force_scrolling''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
* {{DevFeature1.11}} '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* {{DevFeature1.11}} '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

InterfaceActionsWML

2013-11-25T19:29:54Z

AI: /* [scroll_to] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. (Note: Don't use this if the message has options, as such message can only be shown to the current player.)
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''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.
* '''[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.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.
The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event fill be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''use_hotkey''' {{DevFeature1.11}}: if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''' {{DevFeature1.11}}: contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
* {{DevFeature1.11}} '''force_scrolling''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

InterfaceActionsWML

2013-11-25T19:28:51Z

AI: /* [scroll] */

{{WML Tags}}
== Interface actions ==

Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. (Note: Don't use this if the message has options, as such message can only be shown to the current player.)
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''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.
* '''[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.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.
The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event fill be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''use_hotkey''' {{DevFeature1.11}}: if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[default_hotkey]''' {{DevFeature1.11}}: contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
* {{DevFeature1.11}} '''force_scrolling''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
* {{DevFeature1.11}} '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.
* {{DevFeature1.11}} '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.

=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)

=== [remove_sound_source] ===
Removes a previously defined sound source.
* '''id''': the identification key of the sound source to remove

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

WesnothRepository

2013-11-03T17:23:41Z

AI:

{{Compiling Wesnoth}}

The Battle for Wesnoth code base is stored in a version control repository. Version control allows the entire dev team to edit files concurrently. The software tracks revisions, stores a record of all edits, revents simultaneous editing from causing clashes. All changes are stored in the version control repository.

When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.

The Wesnoth repository uses Git and lives at https://github.com/wesnoth/wesnoth-old

== Git ==

Git is the most widely used open-source version-control system. You can learn more about it at the Git home page, http://git-scm.com/.

Git replaced Subversion as Wesnoth's version control system in March 2013. Subversion had itself previously replaced an older program called "CVS" or "concurrent versioning system" in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.

== Browse the code ==

There are currently two main streams of development: trunk (1.11.x) and stable branch (1.10.x). Most other branches are only used for a short time to do some testing without disturbing the main development. You can use your web browser to navigate through the source code:

https://github.com/wesnoth/wesnoth-old

== Download ==

To check out a read-only copy into a directory called ''wesnoth'',

git clone git://github.com/wesnoth/wesnoth-old.git wesnoth

== Commit access ==

For commit access, you must have a developer account on GitHub, it must be registered as part of the Wesnoth group, and you must check out with:

git clone git@github.com:wesnoth/wesnoth-old.git wesnoth

== Update ==

Do this from inside the ''wesnoth'' directory

git pull

== Reviewing your changes ==

Before committing, it's always wise to run

git diff

and look at the output. Some kinds of mistakes that are hard to see embedded in all the code you have modified are more easily spotted in the isolated diff lines.

== Generating patches ==

Under Git on a Unix-like operating system, you'll typically do

git format-patch HEAD~1..HEAD

or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and endingth with the extension ".patch". See [[PatchSubmissionGuidelines]] for more on how to get these merged into the public repository.

== Push to your own fork ==

If you have an account on github, you can fork the repository and add your fork as a remote to your clone.

git remote add fork git@github.com:YOUR_USERNAME/wesnoth-old.git

You can then push your feature branches to your fork.

git push fork local_branch_name:remote_branch_name

Feature branches can be used to base pull requests on using github's webinterface.

== See Also ==

* [[CompilingWesnoth]]

[[Category:Development]]

WesnothRepository

2013-11-03T17:09:33Z

AI: Get rid of the "-code" suffix sourceforge artifact

{{Compiling Wesnoth}}

The Battle for Wesnoth code base is stored in a version control repository. Version control allows the entire dev team to edit files concurrently. The software tracks revisions, stores a record of all edits, revents simultaneous editing from causing clashes. All changes are stored in the version control repository.

When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.

The Wesnoth repository uses Git and lives at https://github.com/wesnoth/wesnoth-old

== Git ==

Git is the most widely used open-source version-control system. You can learn more about it at the Git home page, http://git-scm.com/.

Git replaced Subversion as Wesnoth's version control system in March 2013. Subversion had itself previously replaced an older program called "CVS" or "concurrent versioning system" in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.

== Browse the code ==

There are currently two main streams of development: trunk (1.11.x) and stable branch (1.10.x). Most other branches are only used for a short time to do some testing without disturbing the main development. You can use your web browser to navigate through the source code:

https://github.com/wesnoth/wesnoth-old

== Download ==

To check out a read-only copy into a directory called ''wesnoth'',

git clone git://github.com/wesnoth/wesnoth-old.git wesnoth

== Commit access ==

For commit access, you must have a developer account on GitHub, it must be registered as part of the Wesnoth group, and you must check out with:

git clone git@github.com:wesnoth/wesnoth-old.git wesnoth

== Update ==

Do this from inside the ''wesnoth'' directory

git pull

== Reviewing your changes ==

Before committing, it's always wise to run

git diff

and look at the output. Some kinds of mistakes that are hard to see embedded in all the code you have modified are more easily spotted in the isolated diff lines.

== Generating patches ==

Under Git on a Unix-like operating system, you'll typically do

git format-patch HEAD~1..HEAD

or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and endingth with the extension ".patch". See [[PatchSubmissionGuidelines]] for more on how to get these merged into the public repository.

== See Also ==

* [[CompilingWesnoth]]

[[Category:Development]]

UnitTypeWML

2013-08-03T17:33:13Z

AI:

{{WML Tags}}

__TOC__

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''[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. 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:
** ''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.
** ''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.
: 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.
* '''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.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn.
* '''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.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''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.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is the normal ellipse; "misc/ellipse-nozoc" is a dashed ellipse that should be used for units without zone of control. {{DevFeature1.11}} 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".
* '''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.
* '''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).
* '''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.
* '''hide_help''': determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''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
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''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
* '''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]]).
* '''movement''': the number of move points that this unit receives each turn.
* '''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.
* '''name''':(translatable) displayed in the Status Table for units of this type.
* '''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.
* '''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.
* '''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. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]).
* '''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.
* '''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: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. 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.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.{{DevFeature1.11}}
* '''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).

== After max level advancement (AMLA) ==
* '''[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.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description (see [[DescriptionWML]]) 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.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''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.
*** 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.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''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 (if ''name=x'' then ''icon=attacks/x.png'' is assumed unless present). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}).
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory.
** '''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.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''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.
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''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
For the weight settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

== Other tags ==
* '''[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. Attributes in this unit overwrite the copy. Tags modify the corresponding tag of the original, so for example the first '''[attack]''' tag in the derived unit would modify the first attack of the base unit rather than defining a new attack.

* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.
** '''size''': The size of the portrait, in pixels.
** '''side''': One of left or right.
** '''mirror''': Whether to flip the image horizontally.
** '''image''': The image path.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[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]]

* '''[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.
** '''variation_name''': The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, which are then overwritten by the keys and tags of this variation. Defaults to no.
*** {{DevFeature1.11}} The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''. A special case is the '''id''' key, for which support is incomplete. If '''id''' is set for a variation, then it applies when filtering existing units (including the breakdown of units in the "damage versus" tooltip), but it cannot be used to create a new unit. For reliable behavior, '''id''' should match the parent type's id. {{DevFeature1.11}} Changing the id for a variation is fully supported starting in 1.11.2.

* '''[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.
** '''inherit''': if ''yes'', inherits all the properties of the base unit. Defaults to yes.
*** {{DevFeature1.11}} The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''. A special case is the '''id''' key, for which support is incomplete. If '''id''' is set for a variation, then it applies when filtering existing units (including the breakdown of units in the "damage versus" tooltip), but it cannot be used to create a new unit. For reliable behavior, '''id''' should match the parent type's id. {{DevFeature1.11}} Changing the id for a variation is fully supported starting in 1.11.2.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

UnitTypeWML

2013-08-03T17:31:07Z

AI:

{{WML Tags}}

__TOC__

Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''[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. 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:
** ''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.
** ''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.
: 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.
* '''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.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn.
* '''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.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''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.
* '''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".
* '''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.
* '''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).
* '''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.
* '''hide_help''': determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''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
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''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
* '''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]]).
* '''movement''': the number of move points that this unit receives each turn.
* '''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.
* '''name''':(translatable) displayed in the Status Table for units of this type.
* '''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.
* '''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.
* '''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. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]).
* '''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.
* '''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: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. 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.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.{{DevFeature1.11}}
* '''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).

== After max level advancement (AMLA) ==
* '''[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.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description (see [[DescriptionWML]]) 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.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''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.
*** 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.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''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 (if ''name=x'' then ''icon=attacks/x.png'' is assumed unless present). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}).
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory.
** '''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.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''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.
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''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
For the weight settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

== Other tags ==
* '''[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. Attributes in this unit overwrite the copy. Tags modify the corresponding tag of the original, so for example the first '''[attack]''' tag in the derived unit would modify the first attack of the base unit rather than defining a new attack.

* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.
** '''size''': The size of the portrait, in pixels.
** '''side''': One of left or right.
** '''mirror''': Whether to flip the image horizontally.
** '''image''': The image path.

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

* '''[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]]

* '''[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.
** '''variation_name''': The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, which are then overwritten by the keys and tags of this variation. Defaults to no.
*** {{DevFeature1.11}} The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''. A special case is the '''id''' key, for which support is incomplete. If '''id''' is set for a variation, then it applies when filtering existing units (including the breakdown of units in the "damage versus" tooltip), but it cannot be used to create a new unit. For reliable behavior, '''id''' should match the parent type's id. {{DevFeature1.11}} Changing the id for a variation is fully supported starting in 1.11.2.

* '''[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.
** '''inherit''': if ''yes'', inherits all the properties of the base unit. Defaults to yes.
*** {{DevFeature1.11}} The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''. A special case is the '''id''' key, for which support is incomplete. If '''id''' is set for a variation, then it applies when filtering existing units (including the breakdown of units in the "damage versus" tooltip), but it cannot be used to create a new unit. For reliable behavior, '''id''' should match the parent type's id. {{DevFeature1.11}} Changing the id for a variation is fully supported starting in 1.11.2.

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

ModificationWML

2013-06-10T15:16:31Z

AI:

{{WML Tags}}
== The [modification] toplevel tag ==

{{DevFeature1.11}} This tag describes a multiplayer modification. A modification is practically a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''':

* '''id''': identifier for the modification. Must be unique.
* '''name''': the name of the modification, as displayed to the user.
* '''description''': a brief description for the modification.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.
* '''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.
* '''allow_era''': same as allow_scenario, but for eras.
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

EraWML

2013-06-10T14:16:44Z

AI: /* The [era] top level tag */

{{WML Tags}}
== The [era] top level tag ==

This tag describes one era. An era is a set of teams to play in multiplayer.

In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.

The following key/tags are recognized for '''[era]'''
* '''id''': ID of the era - must be unique. No gameplay effect
* '''name''': displayed name of the era.
* '''require_era''': whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
* '''allow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
* '''disallow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
* '''ignore_incompatible_scenario''': {{DevFeature1.11}} a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
* '''allow_modification''': {{DevFeature1.11}} same as allow_scenario, but for modifications.
* '''disallow_modification''': {{DevFeature1.11}} same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': {{DevFeature1.11}} same as ignore_incompatible_scenario, but for modifications.
* '''force_modification''': {{DevFeature1.11}} a list of modification ids. The specified modifications must be enabled to play this era.
* '''[multiplayer_side]''': a faction in the era. This tag contains many of the same keys as a [side] tag (A description of the [side] tag can be found in [[SideWML]]). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys(currently, not tags) of the [multiplayer_side] tag of the faction which the side chose.
** '''id''': faction ID - must be unique to your era. No gameplay effect
** '''name''': a description that Wesnoth displays as the option selecting that faction; see [[DescriptionWML]]. Any image in this description will ''not'' use the team color.
** '''image''': an image to display in the option. This image will use the team color.
** '''flag_rgb''': often set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]
** '''leader''': a list of unit types. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
** '''random_leader''': if this list of types is present, it would use this list to instead to choose a random leader. If not it would use '''leader'''
** '''random_faction''': default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly.
** '''choices''': Empty by default. If non-empty and the faction has '''random_faction=yes''', it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
** '''except''': Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
** '''type''': the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default.
** '''recruit''': a comma-separated list of unit types this faction can recruit.
** '''terrain_liked''': an unseparated list of terrains (see [[TerrainCodesWML]]). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
* '''[event]''': any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See [[EventWML]].
* '''[options]''': {{DevFeature1.11}} custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

== See Also ==

* [[ReferenceWML]]
* [[SideWML]]

[[Category: WML Reference]]

Wescamp.py Instructions

2013-05-10T19:30:27Z

AI:

Documented here is how wescamp.py works.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
* Administrator rights on github.com/wescamp (if you need to create new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
** You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
** This option can still be useful if no repositories are created. Github has a limit of 60 API requests per hour if you are not logged in, or 5000 if you are.
* -b BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout
* -B BRANCH can be used to specify the version we're syncing. This overrides the -w derived branch. It can also be used as a fallback for when -p isn't given, but there are some issues with that (see below).
* -e ERROR_LOG can be used to specify a file to save all errors to. This is useful for log storage and automated runs.

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G longhexadecimalstringthatisanoath2bearertoken
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Issues ==
GitHub has a 60 requests per hour limit if you do not pass authentication info. If you do, this limit is raised to 5000. It is possible to hit the 60-requests limit doing read-only operations, so it's a good habit to always use -G.

The -B option will override the -w derived github version just fine, but doesn't work well as a addon-server version. This is because addon-server development version uses the development branch version (e.g. 1.11), while on github we use the version of the stable it will become (e.g. 1.12). So when using -B, you should still use -p.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

Wescamp.py Instructions

2013-05-10T19:24:34Z

AI: /* Invocation */

Documented here is how wescamp.py works.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
* Administrator rights on github.com/wescamp (if you need to create new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
** You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
** This option can still be useful if no repositories are created. Github has a limit of 60 API requests per hour if you are not logged in, or 5000 if you are.
* -b BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout
* -B BRANCH can be used to specify the version we're syncing. This overrides the -w derived branch. It can also be used as a fallback for when -p isn't given, but there are some issues with that (see below).
* -e ERROR_LOG can be used to specify a file to save all errors to. This is useful for log storage and automated runs.

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G longhexadecimalstringthatisanoath2bearertoken
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

EasyCoding

2012-11-28T00:48:12Z

AI: Already done

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add possibility to give reason for "ignore" ===
As per FR #16001 [https://gna.org/bugs/?16001]

on it - uzyszkodnik 31.03.2012

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301].

--[[User:Gabba|Gabba]] 19 March 2012 : This is currently assigned to me, but as I lack time and interest to finish integrating this, GSoC students or other interested coders are welcome to take up the current patch and finish the job: https://gna.org/patch/?1381

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
--[[User:Endercoaster|endercoaster]] 30, March 2010. I'm gonna give this one a try.

=== Support for standalone multiplayer scenarios ===
There used to be support for standalone scenarios in the userdata tree, in reorganising the trees this feature got lost and an add-on is now required to add a scenario.
Re-add this feature. It is probably a good idea to mirror the mainline multiplayer tree.

=== Support variable recall cost in wml ===
see https://gna.org/bugs/?16538

the syntax needs to be discussed and refined, but the overall idea is good

make sure to update whiteboard to handle this correctly

Ask Boucman

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to AI ==

Fix some todos, add new formula functions, or do minor improvements to the formula language. Make it easier to debug the formula language, add more ai components.

Please discuss these with Crab, Dragonking, Sirp or Boucman

=== Add more ai actions ===

Add an ai action (and add lua function to do that) to set a goto on a unit

--[[User:Teugon|Teugon]] 00:32, 4 April 2012 (UTC)

Add an ai action (and add lua function to do that) to send a chat message to a player

--[[User:Tyrannodogg|Tyrannodogg]] 11:48, 5 April 2012 (UTC)

Add an ai action (and add lua function to do that) to use a right-click menu item.

There is also [[Practical_Guide_to_Modifying_AI_Behavior#Ideas_for_Potentially_Easy_AI_Patches|this list]] of (unapproved) and (potentially) easy AI feature requests.

=== write a (fai or c++ or lua) candidate action for leader control ===

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature
=== Story Screen improvements ===
see http://www.wesnoth.org/forum/viewtopic.php?p=439346#p439346 for the suggestion and https://gna.org/patch/?1587 for a patch that already touched that area heavily

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

At the moment there are no easy tasks available.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

Euschn 24/03/2009

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add a cycle parameter to the unit animation WML ===

Animations have a "cycle" internal parameter that decides if the animation loops when it finishes.

Right now that parameter is decided purely by the engine depending on the circumstances, but it would make sense to move it to a frame paramter.

This task is mainly to add a new boolean parameter in the particle class and using/exposing it to WML in a way similar to a unit_frame

ask boucman for details

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

Wescamp.py Instructions

2012-10-15T15:22:57Z

AI: /* Examples */

Documented here is how wescamp.py works.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
* Administrator rights on github.com/wescamp (if you need to create new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
** You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
* -B BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G longhexadecimalstringthatisanoath2bearertoken
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

Wescamp.py Instructions

2012-10-15T15:21:55Z

AI: /* Invocation */

Documented here is how wescamp.py works.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
* Administrator rights on github.com/wescamp (if you need to create new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
** You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
* -B BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

CampaignServerWML

2012-09-23T16:31:12Z

AI: Removed a 6-year old "current trunk only" statement

= Campaign Server WML =

This page describes the WML commands exchanged between campaign download clients and a campaign server.

== Listing Available Campaigns ==

This request is used to retrieve a list of campaigns available on the server and some overview information about them.

* Request
** '''[request_campaign_list]'''
*** '''after''': only select campaigns last updated after the indicated time. ''after'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated after Mon Oct 10 21:42:41 2005 GMT, you could not specify a value for ''times_relative_to'' (to use the default of relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]) and specify ''after'' = "1128980561".
*** '''before''': only select campaigns last updated before the indicated time. ''before'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated over a day ago, you could specify ''times_relative_to'' = "now" and ''before'' = "-86400".
*** '''language''': return information only about campaigns that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. "de") or a two letter language code followed by a two character region code (e.g. "pt_BR"). Note that "pt" will not match "pt_BR".
*** '''name''': return information for this campaign. If the name is specified and not the empty string then only information about campaigns with matching names (unless something changes there will be at most one such campaign) will be returned.
*** '''times_relative_to''': "now" means that ''before'' and ''after'' are in seconds relative to the time when the request is processed by the campaign server. Any other value, or if it is not set, indicates that ''before'' and ''after'' are in seconds relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch].
* Response
** '''timestamp''': what time the campaign server thought it was when this response was generated. You shouldn't count on this as a guaranty that no new campaigns will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
** '''[campaigns]'''
*** '''[campaign]'''
**** '''author''': author(s) of the campaign.
**** '''dependencies''': list of add-on dependencies
**** ''description'': (current trunk only) description of the campaign. For pre 1.0 campaigns this should also describe the playability.
**** '''downloads''': the number times the campaign (including previous versions) has been downloaded directly from the campaign server.
**** '''filename''': filename campaign is stored in (currently the same as ''name'').
**** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
**** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
**** '''size''': the size of the campaign in bytes on the campaign server.
**** '''timestamp''': when this version of the campaign was uploaded.
**** '''title''': campaign title. This is not a translatable string.
**** '''translate''': whether the campaign will be automatically send to wescamp and updated from wescamp.
**** '''uploads''': number of uploads (initial upload gets 1)
**** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
**** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
**** '''[translation]'''
***** '''language''': a language that this campaign has appeared to have been at least partially translated into. The following heuristic is used when a campaign is uploaded to extract a list of languages. The list of directories in the uploaded campaign is recursively searched. If a directory named 'LC_MESSAGES' is found then the name of the object containing this '''[dir]''' (normally the parent directory, but could be the campaign name if someone did something silly) is added to the list of translations. Directories named "LC_MESSAGES" are not searched for further matches. The normal naming convention is to use Posix locale names. This will usually be a two letter language code (e.g. "de") or a two letter language code followed by a two letter region code (e.g. "pt_BR"). Since "en_US" is the base language, this language will not be listed as an available translation.

== Downloading a Campaign ==

This command is used to download a specified campaign from the campaign server.

* Request
** '''[request_campaign]'''
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
* Response
** '''author''': author(s) of the campaign.
** '''campaign_name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
** '''name''': this field will always be empty. Client code would treat it as a directory name if it was not empty.
** '''timestamp''': the time the campaign was last uploaded to the campaign server. This is a decimal string containing the number of seconds since the unix epoch.
** '''title''': the title of the campaign. This is not a translatable string.
** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
** '''[file]'''
*** '''name''': the name of the file. This does not include any path information.
*** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
** '''[dir]'''
*** '''name''': the name of the directory. This does not include any path information.
*** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).

== Uploading a Campaign ==

This command is used to upload a new or updated version of an add on campaign to the campaign server.

* Request
** '''[upload]'''
*** '''author''': author(s) of the campaign.
*** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
*** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
*** '''passphrase''': this is used to control updates to campaigns on the server. For existing campaigns, if the passphrase doesn't match, the update will be rejected. You can't easily change the passphrase yourself. If you lose or need to change the passphrase you need to contact the server administrator.
*** '''email''': it is used by campaign server administrators to contact authors in case of important problems with their add-ons (incompatibilities, broken data files, violation of server [[Distributing_content#License|policies]], etc.).
*** '''title''': the title of the campaign. This is not a translatable string.
*** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
*** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
*** '''[data]'''
**** '''[file]'''
***** '''name''': the name of the file. This does not include any path information.
***** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
**** '''[dir]'''
***** '''name''': the name of the directory. This does not include any path information.
***** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).
* Response
** '''[message]'''
*** '''message''': translatable string that indicates that the campaign upload was successful.

== Changing the Passphrase for a Campaign ==

This command is used to change the passphrase for a campaign. Currently the normal client doesn't have a way to use this. However, you can use the perl script campaign_passphrase.pl to do it, if you have a copy of the source tree.

* Request
** '''[change_passphrase]'''
*** '''name''': The name of campaign.
*** '''passphrase''': The old passphrase.
*** '''new_passphrase''': The new passphrase.
* Respose
** '''[message]'''
*** '''message''': Translatable string that says that the passphrase was changed.

== Deleting a Campaign ==

This command is used to delete an existing campaign from the campaign server.

* Request
** '''[delete]'''
*** '''name''': The name of the campaign to delete.
*** '''passphrase''': This must match the passphrase on record for the campaign or the master_password in order for the campaign to be deleted. Master_password.
* Response
** '''[message]'''
*** '''message''': Translatable string that says that the campaign was deleted.

== Request License Information ==

Retrieve the terms of the license used for any uploaded campaigns. You may not upload a campaign if you don't (or can't) aggree to the license. Wesnoth requires campaigns (including images and sound) to be licensed under the GPL. For more information on licensing, see [[Wesnoth:Copyrights]].

* Request
** '''[request_terms]'''
* Response
** '''[message]'''
*** '''message''': translatable string containing the text of the license.

== Developer commands ==

* Request
** '''[validate_scripts]'''
*** '''name''': The name of the campaign to sign.
*** '''master_password''': The signing password.
* Response
** '''[message]'''
*** '''message''': Translatable(?) string that says that the campaign was signed.

== See Also ==

* [[UserScenarios#Campaign_Server_Web_Access]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]

[[Category:WML Reference]]

MultiplayerServerWML

2012-09-20T13:37:33Z

AI: The server can redirect you.

= Multiplayer Server WML =
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in big-endian. Below you'll find information about what data the (unzipped) packages contain.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server response (if the server does not accept this version)
** '''[redirect]'''
*** '''host''': The host you should connect to.
*** '''port''': The port you should connect to.
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB).

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Room commands ==
Note: the room commands are in general and are subject to change.
* '''[room_join]'''
** '''room''': The room name to join
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
** '''[members]''': member list sent to the player that joined
*** '''[member]''': (repeated) members
**** '''name''': This member's name
* '''[room_part]'''
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
* '''[room_query]''': specific room-related queries.
** '''[rooms]''': List rooms created on the server, or
** '''[names]''': List members of a given room
*** '''room''': The room name (if applicable)
** '''[persist]''': Check or set room persistance
*** '''value''': (optional) set room persistance to this value (yes/no)
* '''[room_query_response]''': contains specific response to a room_query.
** '''message''': optional text message response
** '''room''': room name (if applicable)
** '''[rooms]''': room list
*** '''[room]''': (repeated) rooms
**** '''name''': This room's name
** '''[members]''': member list
*** '''[member]''': (repeated) members
**** '''name''': This member's name

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nickname.
*** '''mail''': The email address for the nickname.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nickname.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

MultiplayerServerWML

2012-09-20T13:33:28Z

AI: /* The handshake */

= Multiplayer Server WML =
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].

== The handshake ==

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in big-endian. Below you'll find information about what data the (unzipped) packages contain.

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB).

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
** '''room''': The room the message is from/to
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Room commands ==
Note: the room commands are in general and are subject to change.
* '''[room_join]'''
** '''room''': The room name to join
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
** '''[members]''': member list sent to the player that joined
*** '''[member]''': (repeated) members
**** '''name''': This member's name
* '''[room_part]'''
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
* '''[room_query]''': specific room-related queries.
** '''[rooms]''': List rooms created on the server, or
** '''[names]''': List members of a given room
*** '''room''': The room name (if applicable)
** '''[persist]''': Check or set room persistance
*** '''value''': (optional) set room persistance to this value (yes/no)
* '''[room_query_response]''': contains specific response to a room_query.
** '''message''': optional text message response
** '''room''': room name (if applicable)
** '''[rooms]''': room list
*** '''[room]''': (repeated) rooms
**** '''name''': This room's name
** '''[members]''': member list
*** '''[member]''': (repeated) members
**** '''name''': This member's name

== Nickname registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nickname.
*** '''mail''': The email address for the nickname.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nickname.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nickname of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

Wescamp.py Instructions

2012-08-10T23:56:00Z

AI:

Wescamp.py Instructions

2012-08-10T23:54:29Z

AI: Remove -g

Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
* Administrator rights on github.com/wescamp (for creating new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
* -B BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

Wescamp.py Instructions

2012-08-10T23:34:29Z

AI: /* Invocation */

Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
* Administrator rights on github.com/wescamp (for creating new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
* -u ADDON uploads a single add-on to wescamp.
* -U uploads all translatable add-ons.
* -l lists all add-ons.
* -L lists all translatable add-ons.
* -c creates a normal checkout
* -C creates a read-only checkout (doesn't require any github credentials)
* -s SERVER is the hostname of the add-on server
* -p PORT is the port of the add-on server
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
* -B BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c -g
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown -g
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -g -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -g -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

FormulaAI

2012-07-25T01:22:06Z

AI: /* Available variables */

== Overview ==

The Wesnoth Formula AI is an attempt to develop an AI framework for Wesnoth that allows easy and fun development and modification of AIs for Wesnoth. In addition to the technical information on this page, a tutorial-style guide is also available at [[Formula AI Howto]].

Wesnoth already has support for AIs written in Python, but writing AIs in Python has a couple of problems:

* it's still rather difficult, especially for a non-programmer, to develop an AI, even in Python
* Python is insecure; a malicious trojan horse Python script masquerading as an AI could do untold damage

The Wesnoth Formula AI aims to create a fairly simple, pure functional language which allows one to implement an AI. It also aims to allow AIs to be tweaked and modified by people with relatively little technical programming experience; anyone who can use WML should also be able to use the Formula AI to tweak an AI to make the AI in a scenario behave how they want.

== How formulas get called ==

=== Formulas Command Line ===

To attempt to make it convenient to debug formulas, one can run formulas from within Wesnoth, and see the results. To run a formula, just start game and type 'f'. A command textbox will appear, where you can type a formula, and the results will be printed. For instance, typing

8 + 4

will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)

=== Side-wide formulas ===
The first way to get a formula called is to assign it to a [side] in a WML map. This formula will be called every turn, so it is best used for very simple sides (a couple of special units which should have semi-scripted moves, or a simple handling followed by calls to the standard C++ AI)

To use the Formula AI, one should put an [ai] tag inside the [side] tag. Inside this [ai] tag, one should set up the ''side_formulas'' stage and specify the 'move' attribute to be a formula for the movement the AI will make. Each time it's the AI's move, this formula will be run, and the move it results in will be executed. Then the formula will be run again; it'll continue to be run until it stops producing a valid move, at which point the AI will end its turn. Alternatively there is a command that the formula may return which will make it end its turn immediately.

A sample AI which does nothing but recruit Wolf Riders is as follows:
[side]
...
[ai]
version=10710
[stage]
engine=fai
name=side_formulas
move="recruit('Wolf Rider')"
[/stage]
[/ai]
[/side]

=== Unit Formulas ===

You can specify a formula for any kind of unit. This is a simple way of doing it:

[unit]
...
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
[/ai]
[/unit]

Above formula will simply move unit one hex to the north every turn. Note how "me" keyword allows access to unit itself. In addition, the ''unit_formulas'' stage also needs to be set up in the side definition:

[side]
...
[ai]
version=10710
[stage]
engine=fai
name=unit_formulas
[/stage]
[/ai]
[/side]

If you need to execute unit formulas in a specific order, you can set a priority:

[unit]
...
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
priority=10
[/ai]
[/unit]

Units with highest priority get their formula executed first.

You can also define AI unit-specific variables and use them in you formulas:

[unit]
...
[ai]
formula="if(attack, attack, move(me.loc, me.vars.guard_loc) )
where attack = choose(filter(attacks, units = [me.loc] and distance_between(me.vars.guard_loc, target) <= me.vars.guard_radius and unit_at(target).side=me.vars.hostile_side-1 ), avg_damage_inflicted)"

[vars]
guard_radius=3
guard_loc="loc(8,5)"
hostile_side=1
[/vars]
[/ai]
[/unit]

This formula will get location position from variable guard_loc and make sure that unit attacks only opponent from side 1 (value specified by hostile_side variable) which is 3 hexes (guard_radius) or less from guard_loc.

Types of variables that are supported:
*number:
variable=3
*text (important: note the ' ' within " "):
name="'I am variable'"
*list:
number_list=[ 1, 2, 3]
* map:
map=[ 'Elvish Archer' -> 70, 'Elvish Shaman' -> 60 ]
*location:
place="loc(X,Y)"

=== Candidate move evaluation ===
==== Overview ====
Units in wesnoth have all sort of special abilities, special powers and special usages. Thus, it was needed to have an easy way to describe special behaviour for special units. Adding an formula to a unit only partially solves the problem. It allows easily to have special units (like ennemy heroes) have special behaviour but not normal units with special powers to to behave smartly.

Candidate moves are a way to have formula that will

* evaluate a given situation
* see if they are able to provide "special moves" for the case they know how to handle
* give a move to do if the situation match their condition

==== Evaluation Algorithm ====

Each side will have some candidate move blocks made of
* a name for the move
* a type (see below for description of the different types and how they are called)
* a formula returning a score for the move
* a formula executing the move to do

The engine will run the following pseudo-code

while (a formula returned a score greatern than 0) {
foreach (registered candidate move) {
foreach (set of parameters for that candidate move's type) {
call the evaluation formula, note the score returned
}
}
if (the highest score returned was greater than 0) {
call the candidate move that returned the highest score with the corresponding set of parameters
}
}

in other word, we evaluate all candidate moves, then run the candidate move with the highest score, then re-evaluate everything, until no candidate move wants to play anymore

==== Syntax ====
To add a new candidate move to the RCA AI ''main_loop'' stage, use the following syntax:

[ai]
version=10710
[stage]
id=main_loop
name=testing_ai_default::candidate_action_evaluation_loop
{AI_CA_GOTO}
{AI_CA_RECRUITMENT}
{AI_CA_MOVE_LEADER_TO_GOALS}
{AI_CA_MOVE_LEADER_TO_KEEP}
{AI_CA_COMBAT}
{AI_CA_HEALING}
{AI_CA_VILLAGES}
{AI_CA_RETREAT}
{AI_CA_MOVE_TO_TARGETS}
{AI_CA_PASSIVE_LEADER_SHARES_KEEP}

[candidate_action]
engine=fai
name=go_south
type=movement
evaluation="if((me.hitpoints < me.max_hitpoints), 60010, 0)"
action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
[/candidate_action]
[/stage]
[/ai]

This is an example of a candidate action that gets added to all the standard RCA AI candidate actions and moves each unit with movement points left one hex south. It is also possible to use
{ai/aliases/stable_singleplayer.cfg}
inside the [side] tag to set up the standard RCA AI candidate actions, and then add the customized candidate actions later using [modify_ai] or one of the available macros.

Each [candidate_action] block describes a candidate move and must have the following fields

* ''name'' : the name of this candidate block
* ''type'' : see the paragraph about types below, this describe the implicite variables that the formulas will be called with
* ''evaluation'' : a formula returning an integer. This number reflects how good the move is compared to other moves. Values of zero will mean the move is not a good idea and should be skipped
* ''action'' : A formula that will be called if that candidate move is the best one

==== Candidate move types ====

there are two types of candidate moves

* '''attack''' : these are called once for every pair <me,target> where me is a variable set to a unit on the AI side, and target is a variable set to an ennemy unit that "me" can reach
* '''movement''' : these are called once for every unit on the AI side, the "me" variable is set to the corresponding unit

=== Summary : a typical AI turn ===

An AI turn will run the following formulas. Any formula returning an "end turn" move will (of course) finish the turn. But assuming this doesn't happen :
* All unit formulas are called once
* All candidate moves are evaluated and played
* All ''move='' formulas are called until they don't return valid moves
* If no ''move='' formula is provided, we drop automatically to C++
* Turn is ended.

Note that this means that you have to explicitely call "fallback" or set up the RCA AI ''main_loop'' stage specifically, if you want the C++ AI to finish your moves after a side-wide formula. Also note that the stages are executed in the order in which they are put into the [ai] tag, not in the order of the above list.

== Formula Basics ==

* The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers and decimal/floating point numbers, but operations will default to integer math unless operands are specified as floating point. For example:

4 + 8*7 #evaluates to 60
(4 + 8)*7 #evaluates to 84
8 % 6 #evaluates to 2
5 / 2 #evaluates to 2
5.0 / 2 #evaluates to 2.5
5 / 2.0 #evaluates to 2.5
3 ^ 2 #evaluates to 9

* It also supports equality, = and !=, and comparison operators, <, >, <=, and >=. 'false' values are 0 (integer) and null. Other values are true. It also supports common operators such as and, or, and not:

2 = 4 #evaluates to 0
2 <= 3 #evaluates to 1
0 != 1 #evaluates to 1
not 4 #evaluates to 0
not 0 #evaluates to 1
(2 < 4) and (3 > 6) #evaluates to 1 and 0 which evaluates to 0
(2 < 4) or (3 > 6) #evaluates to 1 or 0 which evaluates to 1

* Formula language supports also 'dice' operator 'd'. Example usage is:

3d5

Which will give you one of results of rolling three five-sided dice (so random number between 3 and 15). NOTE: We encourage you to use this operator only when it is really needed. In most cases, you should not base the AI decisions on random results except for scenario replayability purposes.

== Data Types ==

Formula System supports different types of data, which can be stored as a variables and are used in evaluations:

* Numbers: like 0, 1, 2 etc. Floating-point numbers are not supported. 0 is equal to logical 'false', any other number is 'true'.

* Text strings:

'this is a text string'

* Lists: A list is a sequence of values. For example, ai.my_units is a list of unit objects. A list is represented as square brackets, [], surrounding a comma-seperated list. For instance:

[4, 8, 7]

is a list of three numbers, and

[]

is a empty list. Various functions can operate on lists.

To acces one particular element of a list we can use operator [], for example:

my_list[0]

Returns first element from the my_list, so:

[ 10, 20, 30, 40][2]

Returns

30

* Maps: A map is a sequence of pairs, each pair is a key and assigned to it value. For example:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ]

Is a map which consist of two pairs, first one assigns to the text string 'Elvish Fighter' the value 50, second one assigns 60 to the 'Elvish Archer' string.

To access value assigned to the key, we can use operator []:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ][ 'Elvish Fighter' ]

Above example returns

50

== AI Formula Language ==

=== Overview ===

The formula language must be able to access information about the scenario being played to make intelligent decisions. Thus there are various 'inputs' that one may access. A simple example of an input is the turn number one is on, given by the input, 'turn'. Try bringing up the formula command line using 'f' and then type in

turn

The AI will print out the current turn number the game is on.

The 'turn' input is a simple integer. However, some inputs are complex types which contain other inputs, or which may be lists of inputs. For instance, the input 'my_units' contains a list of all the AI's units.

A complex input such as a unit will contain a variety of inputs inside it. If one has a unit input, called 'u' for instance, one can access the 'x' co-ordinate of that unit by using u.loc.x -- u.loc accesses the 'location' object inside the 'unit' object, and the 'location' object contains 'x' and 'y' inputs inside it, which are the x and y co-ordinate of the unit.
=== Available variables ===
these are variables that you can call in an AI formula or from the command line.

Some of these variables are complicated data structues, calling their name from the formula command line will allow you to easily see their content

use the '''dir''' and '''debug_print''' to inspect the variables

to get a coplete list, use the
dir(self)
command

* ''attacks'' a list of all possible attacks
NOTE: this variable returns a list of all possible attacks (including attack combinations - attacking a single enemy unit with several units) , which is immediately treated as list of attack orders, which is evaluated (so, evaluation of this variable results in attacks being made). If you want to get the list without such evaluation, wrap it inside the array, "[attacks]". If you want to get the first attack, wrap it inside the array twice, "[[attacks[0]]]"

* ''my_attacks'' a list of all possible attacks. It returns slightly different list then ''attacks''. I.e. when only two units (attacker and dedenter) are on the board ''attacks'' return one attack, from the position with the highest defence and ''my_attacks'' returns all 6 attacks from all adjacent tiles.
* ''my_side'' global variables describing your own side
* ''teams'' all the data about all the teams
* ''turn'' the current turn number
* ''time_of_day'' the current time of day
* ''keeps'' all keep locations
* ''vars'' all localy set varables using the set_var function
* ''allies'' a list of all sides that are friendly
* ''ennemies'' a list of all sides that are enemy
* ''my_moves'' a list of all my moves
* ''enemy_moves'' a list of all enemy moves
* ''my_leader'' our leader unit
* ''my_recruits'' the list of units that can be recruited by us
* ''recruits_of_side'' foreach side the list of units that can be recruited
* ''units'' the complete list of all units
* ''units_of_side'' foreach side, a list of all owned units
* ''my_units'' the complete list of all units owned by the current player
* ''enemy_units'' all units that are enemy to the current player
* ''villages'' all the villages on the map
* ''my_villages'' all the villages owned by the current player
* ''villages_of_side'' for each side, the list of villages owned
* ''enemy_and_unowned_villages'' all villages that you don't own
* ''map'' all the data about the map

=== Built-in functions ===
The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. List of these functions, usage and simple examples can be found [http://www.wesnoth.org/wiki/FormulaAI_Functions here].

=== Custom Functions ===

* You can define your own functions. A function is a formula which takes some inputs as parameters. Suppose we wanted to define a function that puts some value on a unit, we might add the following to the [ai] tag:

[function]
name=value_unit
inputs="unit"
formula="unit.hitpoints + unit.level*4"
[/function]

This has defined a new function which takes a 'unit' as an input, and runs the given calculation over it.

* We can have multiple inputs in our functions, to define them, just create comma-separated inputs list:

inputs="attacker,defender"

This has defined a new function which takes both 'attacker' and 'defender' as an inputs.

* Sometimes, we use one of our inputs really often in our function - to make our life easier we can make its members (inputs) directly accessible from within the formula. This is improved version of function from above:

[function]
name=value_unit
inputs="unit*"
formula="hitpoints + level*4"
[/function]

As you can see, if we define input with a * char at the end, we make it a 'default input' for a formula. Note, that you can define only one default input per function.

* It is important to know difference between formulas defined in custom functions, and formula defined by a 'move=' in a [ai] tag. For example, if we want to get info about leader, we write in formula 'my_leader' - which acces member of the AI. To be able to use 'my_leader' in custom functions we have to add 'ai' as an input for our function:

inputs="ai"

allows us to access leader info by writing 'ai.my_leader', or:

inputs="ai*"

allows us to access leader info by simply writing 'my_leader'

* You can also use 'def' [[#Keywords|keyword]] to define custom functions

=== Comments ===

Comments in Formula AI scripts are enclosed by # #:

#Define opening move#
def opening(ai*)
if(turn = 1,
move(loc(11,23), loc(14,22)),
[])

Comments may also be included at the end of a line:

def opening(ai*)
if(turn = 1,
move(loc(11,23), loc(14,22)), #capture village#
[]) #do nothing#

and they may also be used inline:

def opening(ai*)
if(turn = 1,
move(loc(11,23) #my_leader#, loc(14,24) #closest village#),
[] #do nothing# )

== Keywords ==

The formula language has some reserved keywords to provide primitive functionality. Currently the following keywords are defined:

* where: This keyword is used to defining statements in formulas. You can define multiple comma-separated statements. Syntax:

<formula> where <comma-separated list of statements>

For example formula:

a + b where a = 2, b = 4

will give as result 6.

* functions: Returns a list of all built-in and custom functions available to the AI

* def: This keyword creates functions using the syntax:

def function_name(arg1, arg2, ....) function_body

For example,

def sum(x,y) x + y

creates a function sum taking two arguments and returns their sum.

== Files and formulas ==

You can easily split your formulas between different files and include them when necessary. For example:

[unit]
...
formula={my_unit_formula.fai}
[/unit]

Will look for unit formula in the my_unit_formula.fai file.

Although it is not mandatory, we advocate to use following syntax in your fai files:

faifile '<filename>'
...
faiend

This makes formula system know which file it is working with now, and gives you improved error reporting, which is often really helpful. Valid syntax for my_unit_formula.fai would be:

faifile 'my_unit_formula.fai'
...
faiend

== Tool Support ==

=== ctags ===

For some rudimentary support for exuberant ctags, add the following to .ctags (or create the file if it doesn't exist):

--langdef=formulaai
--langmap=formulaai:.fai
--regex-formulaai=/^def[ \t]*([a-zA-Z0-9_]+)/\1/d,definition/

This is especially nice when used with an editor or plugin with ctags support, such as Taglist for Vim.

=== Vim ===

====Syntax Highlighting====

Follow these steps to enjoy vim syntax highlighting support for Formula AI.

# Grab the Formula AI vim syntax file, [http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/tools/vim/formulaai.vim formulaai.vim].
# Copy formulaai.vim to .vim/syntax
# Add the following to .vimrc :
autocmd! BufRead,BufNewFile *.fai setfiletype formulaai

====Taglist Support====

First you will need the very nice [http://www.vim.org/scripts/script.php?script_id=273 taglist plugin]. Follow the link for downloads and install directions if you don't already have it installed.

Next, you'll need Formula AI support for exuberant ctags, follow the instructions in the [[#ctags|ctags]] section.

Once you have all that, simply add the following line to your .vimrc:

let tlist_formulaai_settings = 'formulaai;d:definition'

To test it all out, open a Formula AI script file and enter the command
:Tlist

You should now have some nice highlighting and be able to easily navigate through formula, enjoy!

[[Category:Development]]

[[Category:Development]]

DirectActionsWML

2012-05-01T21:17:35Z

AI: [object] duration updates

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

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

The following tags are actions:

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

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

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

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

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

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

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

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

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

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. Such units will be automatically hit (and killed) in combat, but if given the chance to heal, they will have a minimum of one hit point after healing (regardless of how negative their hit points were). This is unusual-looking behavior, so often should be avoided.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== [transform_unit] ===
transforms every unit matching the filter to the given unit type. Keeps intact hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

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

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

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

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

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

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

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

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.

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

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

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

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

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.

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

=== [tunnel] ===

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

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

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

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

== See Also ==

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

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

User:AI/Eastern History Notes

2012-04-15T04:10:51Z

AI: /* Minotaurs */

Secret stuff regarding Eastern_History (not linked because of WhatLinksHere stuff)

== Silver Drakes ==
The silver drakes are unusual in that they aren't led by a single ruler, but a council constituted from one drake of each of the castes. Succession is otherwise as normal.
The council guards the knowledge of the process of maturation into a dragon. A single ruler might be tempted, but even a large nation of drakes cannot expect to sustain a council of 5 dragons.

When the silver drakes take firecloud peak, they unknowingly share this volcano with the Fire King (one of the Earthen Kings). The fire king eventually reaches out to one of the members of the council and reveals/invents a way to only partially trigger the maturation process. This confers most of the magical strength of a dragon onto the drake, without significantly increasing its size.

This drake informed 4 trusted friends of this process, underwent it together and then had his friends challenge and defeat the other members of the council. One of the surviving council members is Græk Lon, who was exiled and soon afterwards captured by Krados. (see TSL/ask espreon)

The Fire King's angle here is that the rigid moral code of the drakes, combined with their disdain for other races, makes a very useful tool.

== Minotaurs ==
The creator goddess of the minotaurs, Askela, is better known under the name Uria. She turned them from their original human forms into minotaurs after a slight that is said to be the worship of a bull.
To better understand her in the future, she granted the minotaurs 3 crystals. This started a shamanistic practice centered around crystals, with the three holy ones in possession of the highest elders.

What lead to the start the era of strife was the unification of the three minotaur nations under Rilend Ironfist and the three crystals in the hands of his mage and advisor Zeal. Zeal cut out his eyes and used the crystals to forge a connection to Askela.
(possibly advised by Zeal) Rilend went to war to expand the empire of Lithia and eventually needed to lead his overstretched forces himself.
While Zeal was left unchecked in the palace, both he and Uria were corrupted for unknown reasons.
Zeal, envisioning the next target for conquest, caused the apocalyptic destruction of the rival human nations of Noct and Diurna, using demonic forces.
However, Rilend returned to Lithia in order to contain Zeal, who quickly assembled an army of demons and mercenaries to defend himself. The ensuing battle claimed the lives most of minotaur army Rilend had brought, and the forces he left behind were overstretched and leaderless, and were killed or routed in the following months.
Zeal was defeated, but managed to bind his soul to the three crystals as he died.

It is henceforth forbidden to unite the three crystals, as the power is too dangerous to be used.
Later, the minotaurs are losing a war and are getting pushed back to their capital. A young talented shaman takes one of the holy crystals after the elder who owned it dies in battle. With the power of the crystal, he manages to win several battles, but for every battle he wins, several others are lost. He holds on to the holy crystal, effectively making him an elder, and begins to resent the other elders, who do not use their power effectively in battle.
At some point, he attempts to relieve the force of one of the other elders, which has been encircled. He manages to break into the encirclement, but can't break them out until the elder dies. He takes up this crystal too, and gains access power far beyond his expectation.
With his new power, he takes command of all minotaurs present, breaks through the encirclement and marches straight to the final crystal, destroying all in his path. There, he demands the crystal of the final elder, explaining that the combined power will allow him to truly defeat the enemy nation.
The elder refuses, and the shaman, enraged, kills him for refusing to serve Lithia's best interests. He takes the final crystal, at which point Zeal (slowly or quickly?) possesses him.

Possibly more stuff about Zeal in TSL.

== Eventide ==
The forerunners of the eventide where pre-khalifate settlers who left the desert because of the taboo on magic.
The cities of Noct and Diurna were founded after conflicts about which forms of magic should be used, which eventually consolidated around Noct using magic of darkness and Diurna using magic of light.

The eventide formed after Noct and Diurna were both destroyed by the cataclysm described in the minotaur section. They banded together to take revenge. More by accident than through knowledge, the first target of their anger was at least the correct nation, Lithia. With the overstretched minotaur offensive crumbling and retreating beyond easy reach in the absence of its leader, the eventide quickly picked a new target, the xenophobic elves from the northern forest.

== Triththa ==
The dominion of triththa started out as an illegal colony according to the treaties with the elves. To maintain secrecy, trade with firecloud peak was initially kept to a minimum. (50 BW - 50 YW or so) When the elves finally found out, the orcs were more pressing concern, and besides some strong words, not much was done.

Not long afterwards, firecloud peak was invaded by the silver drakes and the survivors mostly evacuated to the hills and plains of triththa. With this trade with the west was cut off. The elves were not going to let illegal settlers cross one of their most sacred forests, the drakes were hostile to everyone, the desert was too large to cross and other routes were too long to send more than occasional messengers.

This had two important effects: runecraft was maintained, but not communicated to the west and a critical ingredient for the use of thundersticks became unavailable.

More to come...

Wescamp.py Instructions

2012-03-04T03:30:20Z

AI: /* Examples */

Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
* Administrator rights on github.com/wescamp (for creating new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
Invocation (for -u and -U) is the same as with svn, with the following differences:
* The -g/--git switch is required
* The -G/--github-login (with argument in the form of USER:PASSWORD) is required an upload would create a new repository on github. This is because a json API is used to create the new repository.

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c -g
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown -g
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -g -G USER:PASSWORD
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -g -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

Wescamp.py Instructions

2012-03-04T03:28:09Z

AI: /* Examples */

Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
* Administrator rights on github.com/wescamp (for creating new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
Invocation (for -u and -U) is the same as with svn, with the following differences:
* The -g/--git switch is required
* The -G/--github-login (with argument in the form of USER:PASSWORD) is required an upload would create a new repository on github. This is because a json API is used to create the new repository.

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c -g
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown -g
In this case a checkout of the Invasion_from_the_Unknown-1.10 repository already exists in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -g -G USER:PASSWORD
In this case the directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -g -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

PblWML

2012-02-21T23:31:28Z

AI: /* email */

{{WML Tags}}

To upload an add-on you have made, you need a .pbl file.

This is a file with name '''data/add-ons/''Addon_name''.pbl''' or, for Wesnoth 1.6 and later, '''data/add-ons/''Addon_Name''/_server.pbl''' in a subdirectory. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]

When you upload a add-on, the file '''data/add-ons/''Addon_Name''.cfg'''
and the directory '''data/add-ons/''Addon_Name''/''' will be published. Alternatively, '''data/add-ons/''Addon_Name''.cfg''' can be replaced with '''data/add-ons/''Addon_Name''/_main.cfg'''. Your add-on must be based entirely on these paths.

Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.

== What goes into a .pbl file? ==

'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''

The following keys are recognized for .pbl files:

=== icon ===
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and not a custom one. A custom file will work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.

: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.

=== title ===
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.

=== version ===
: Displayed to the right of the title, it is just text. However, starting with Wesnoth 1.6, the ''required'' format is x.y.z where x, y and z are numbers and a value for x greater than 0 implies the add-on is complete feature-wise. Trailing non-numeric elements are allowed, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])

=== author ===
: Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.

=== passphrase ===
: Not displayed, it prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.

=== description ===
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.

=== dependencies ===
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])

=== translate ===
: If set to '''true''', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)

: You should make sure your add-on complies with some very specific [[WesCamp#How_to_contribute_to_this_Project|conventions]] required to ease the process for translators.

=== type ===
: Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:

:* ''campaign'': single player campaign.
:* ''scenario'': single player scenario.
:* ''era'': multiplayer era.
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.
:* ''map_pack'': multiplayer map-pack.
:* ''campaign_mp'': multiplayer campaign.
:* ''scenario_mp'': multiplayer scenario. (See the note below.)
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
:* ''other'': The type to use when no other type fits.

'''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.

=== email ===
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.

The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== Examples ==

=== Dependency Key Example ===

The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:

dependencies=Imperial_Era,Era_of_Myths

=== Version Key Examples ===

The following are examples of '''good''' version values:

version="1.5"

version="0.11.4"

version="0.1.4beta"

version="1.5c"

The following are examples of '''bad''' version values:

version="Beta1.5"

version="Incomplete (0.3.4)"

In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.

Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.

0.5 < 1.0

1.5 < 1.5c

1.0 < 1.0.1

1.0c < 1.0.1a

1.0.1a < 1.0.1c

1.0 Final < 1.0.1 Beta

=== Example .pbl File ===

title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@example.com"

== See Also ==

* [[ReferenceWML]]
* [[BuildingCampaignsThePBLFile]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

Wescamp.py Instructions

2012-02-07T15:22:41Z

AI: /* Examples */

Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.

== Requirements ==
* Git
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
* Administrator rights on github.com/wescamp (for creating new repositories)

== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:
/tmp/wescamp/1.10
/tmp/wescamp-1.10

== Invocation ==
Invocation (for -u and -U) is the same as with svn, with the following differences:
* The -g/--git switch is required
* The -G/--github-login (with argument in the form of USER:PASSWORD) is required an upload would create a new repository on github. This is because a json API is used to create the new repository.

== Examples ==
./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown -g
In this case a checkout of the Invasion_from_the_Unknown-1.10 repository already exists in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -g -G USER:PASSWORD
In this case the directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -g -G USER:PASSWORD
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

== Notes ==
If there's anything missing, please contact me. (AI0867)

[[Category:Translations|*]]

WesCamp

2012-01-17T17:39:23Z

AI: /* See Also */

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== If you are someone who just wants to translate ==

Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen add-on and language. Then read the information '''for translators''' on this page here to know whom to tell what you are working on, and where to submit your translations.

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== Preparing your add-on for WesCamp ==

In order for your add-on to be compatible with WesCamp’s translation tools, certain things must be done. This section describes what must be done and what should be done anyway.

=== The textdomain declaration ===
First, your add-on must declare a textdomain. To do this, make sure something like the following is inside of your _main.cfg:

[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]

Note that to be compatible with WesCamp’s tools, the part of the textdomain after ''wesnoth-'' must match your add-on’s directory name. In this example, the add-on’s directory is ''Son_of_Haldric'', thus we would get ''wesnoth-Son_of_Haldric''.

The ''translations'' directory is where compiled translations would go.

=== The textdomain bindings ===

All files with translatable strings must be bound to your domain. See the example below:

#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...
[/unit_type]

Note that you can reuse translations for strings in mainline domains by using multiple textdomain bindings or a gettext helper file (which will be explained later):

# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
...
[/attack]

#textdomain wesnoth-Son_of_Haldric

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, wesnoth-test, and wesnoth-units.

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:

name= _ "Mu"

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

name= _ ""

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

name= _ "{TYPE} Mu"

To show why it will not work:

#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

name= _ "Sword Mu"
name= _ "Bow Mu"

Since those are not in the catalogues, they will not get translated.

=== The gettext helper file ===

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy. It is also more wmllint-friendly.

Here is an example of a gettext helper file:

#textdomain wesnoth-lib

#define STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define STR_SWORD
_"sword" #enddef

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

[attack]
id=sword
name={STR_SWORD}
...
[/attack]

[terrain_type]
id=ice2
name={STR_ICE}
...
[/terrain_type]

=== Getting your add-on into WesCamp ===

Now, to get your add-on into WesCamp, all you do is put this line into your add-on’s .pbl file and upload to the add-ons server:

translate=true

Your add-on will eventually be uploaded to WesCamp’s Subversion repository by mordante’s script, which he runs whenever.

== How to contribute to this project ==

=== Translators ===

Translating add-ons works the same as translating mainline. All of the information about this already exists in the wiki (see the links below). The files you need are located in the project’s [https://github.com/wescamp Github repositories] (they might take a bit of effort to locate. Alternatively, you can use [http://gettext.wesnoth.org gettext.wesnoth.org]). When they are translated, mail them to [mailto:Majora700@gmail.com Espreon] or (as a last resort) [mailto:david_AT_torangan.de Torangan].

Before you start translating you should:
* Look at the subpage of the add-on you wish to translate to see if someone is already working on it.
* Contact the translation team for your target language for guidance.

If you have questions, join the [irc://irc.freenode.net/wesnoth #wesnoth] channel on the Freenode IRC network and ask in there. Of course, you will also get answers if you ask your questions in the [http://forums.wesnoth.org/viewforum.php?f=7 Translations & Internationalization forum], or e-mail [mailto:Majora700@gmail.com Espreon] or [mailto:david_AT_torangan.de Torangan].

== See Also ==

* [[GettextForTranslators|GetText for Translators]] - how to translate Wesnoth using [[GetText]]
* [[WesnothTranslations|Wesnoth Translations]]
* [[TranslatorsGuide|Translators' Guide]]
* [http://gettext.wesnoth.org Translation statistics]
* [https://github.com/wescamp WesCamp project at Github]
* [[Wescamp.py_Instructions|Wescamp for Maintainers]]

[[Category:Translations|*]]
[[Category:Campaigns]]

WesCamp

2012-01-17T17:12:20Z

AI: /* See Also */

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== If you are someone who just wants to translate ==

Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen add-on and language. Then read the information '''for translators''' on this page here to know whom to tell what you are working on, and where to submit your translations.

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== Preparing your add-on for WesCamp ==

In order for your add-on to be compatible with WesCamp’s translation tools, certain things must be done. This section describes what must be done and what should be done anyway.

=== The textdomain declaration ===
First, your add-on must declare a textdomain. To do this, make sure something like the following is inside of your _main.cfg:

[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]

Note that to be compatible with WesCamp’s tools, the part of the textdomain after ''wesnoth-'' must match your add-on’s directory name. In this example, the add-on’s directory is ''Son_of_Haldric'', thus we would get ''wesnoth-Son_of_Haldric''.

The ''translations'' directory is where compiled translations would go.

=== The textdomain bindings ===

All files with translatable strings must be bound to your domain. See the example below:

#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...
[/unit_type]

Note that you can reuse translations for strings in mainline domains by using multiple textdomain bindings or a gettext helper file (which will be explained later):

# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
...
[/attack]

#textdomain wesnoth-Son_of_Haldric

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, wesnoth-test, and wesnoth-units.

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:

name= _ "Mu"

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

name= _ ""

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

name= _ "{TYPE} Mu"

To show why it will not work:

#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

name= _ "Sword Mu"
name= _ "Bow Mu"

Since those are not in the catalogues, they will not get translated.

=== The gettext helper file ===

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy. It is also more wmllint-friendly.

Here is an example of a gettext helper file:

#textdomain wesnoth-lib

#define STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define STR_SWORD
_"sword" #enddef

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

[attack]
id=sword
name={STR_SWORD}
...
[/attack]

[terrain_type]
id=ice2
name={STR_ICE}
...
[/terrain_type]

=== Getting your add-on into WesCamp ===

Now, to get your add-on into WesCamp, all you do is put this line into your add-on’s .pbl file and upload to the add-ons server:

translate=true

Your add-on will eventually be uploaded to WesCamp’s Subversion repository by mordante’s script, which he runs whenever.

== How to contribute to this project ==

=== Translators ===

Translating add-ons works the same as translating mainline. All of the information about this already exists in the wiki (see the links below). The files you need are located in the project’s [https://github.com/wescamp Github repositories] (they might take a bit of effort to locate. Alternatively, you can use [http://gettext.wesnoth.org gettext.wesnoth.org]). When they are translated, mail them to [mailto:Majora700@gmail.com Espreon] or (as a last resort) [mailto:david_AT_torangan.de Torangan].

Before you start translating you should:
* Look at the subpage of the add-on you wish to translate to see if someone is already working on it.
* Contact the translation team for your target language for guidance.

If you have questions, join the [irc://irc.freenode.net/wesnoth #wesnoth] channel on the Freenode IRC network and ask in there. Of course, you will also get answers if you ask your questions in the [http://forums.wesnoth.org/viewforum.php?f=7 Translations & Internationalization forum], or e-mail [mailto:Majora700@gmail.com Espreon] or [mailto:david_AT_torangan.de Torangan].

== See Also ==

* [[GettextForTranslators|GetText for Translators]] - how to translate Wesnoth using [[GetText]]
* [[WesnothTranslations|Wesnoth Translations]]
* [[TranslatorsGuide|Translators' Guide]]
* [http://gettext.wesnoth.org Translation statistics]
* [https://github.com/wescamp WesCamp project at Github]

[[Category:Translations|*]]
[[Category:Campaigns]]

WesCamp

2012-01-17T16:55:12Z

AI: /* Translators */

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== If you are someone who just wants to translate ==

Then, simply go to http://gettext.wesnoth.org, and download the .po file of your chosen add-on and language. Then read the information '''for translators''' on this page here to know whom to tell what you are working on, and where to submit your translations.

This page is dedicated to describing how to translate user-made content with the help of the [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n] project.

This project is hosted at [http://www.berlios.de/ BerliOS] and maintained by [mailto:david_AT_torangan.de Torangan] and [mailto:Majora700@gmail.com Espreon]. Add-ons are uploaded into the Subversion repository and .po files of the content are created. The .po files are updated regularly and the stats can be found at http://gettext.wesnoth.org.

== Preparing your add-on for WesCamp ==

In order for your add-on to be compatible with WesCamp’s translation tools, certain things must be done. This section describes what must be done and what should be done anyway.

=== The textdomain declaration ===
First, your add-on must declare a textdomain. To do this, make sure something like the following is inside of your _main.cfg:

[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]

Note that to be compatible with WesCamp’s tools, the part of the textdomain after ''wesnoth-'' must match your add-on’s directory name. In this example, the add-on’s directory is ''Son_of_Haldric'', thus we would get ''wesnoth-Son_of_Haldric''.

The ''translations'' directory is where compiled translations would go.

=== The textdomain bindings ===

All files with translatable strings must be bound to your domain. See the example below:

#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...
[/unit_type]

Note that you can reuse translations for strings in mainline domains by using multiple textdomain bindings or a gettext helper file (which will be explained later):

# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
...
[/attack]

#textdomain wesnoth-Son_of_Haldric

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, wesnoth-test, and wesnoth-units.

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:

name= _ "Mu"

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

name= _ ""

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

name= _ "{TYPE} Mu"

To show why it will not work:

#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

name= _ "Sword Mu"
name= _ "Bow Mu"

Since those are not in the catalogues, they will not get translated.

=== The gettext helper file ===

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy. It is also more wmllint-friendly.

Here is an example of a gettext helper file:

#textdomain wesnoth-lib

#define STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define STR_SWORD
_"sword" #enddef

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

[attack]
id=sword
name={STR_SWORD}
...
[/attack]

[terrain_type]
id=ice2
name={STR_ICE}
...
[/terrain_type]

=== Getting your add-on into WesCamp ===

Now, to get your add-on into WesCamp, all you do is put this line into your add-on’s .pbl file and upload to the add-ons server:

translate=true

Your add-on will eventually be uploaded to WesCamp’s Subversion repository by mordante’s script, which he runs whenever.

== How to contribute to this project ==

=== Translators ===

Translating add-ons works the same as translating mainline. All of the information about this already exists in the wiki (see the links below). The files you need are located in the project’s [https://github.com/wescamp Github repositories] (they might take a bit of effort to locate. Alternatively, you can use [http://gettext.wesnoth.org gettext.wesnoth.org]). When they are translated, mail them to [mailto:Majora700@gmail.com Espreon] or (as a last resort) [mailto:david_AT_torangan.de Torangan].

Before you start translating you should:
* Look at the subpage of the add-on you wish to translate to see if someone is already working on it.
* Contact the translation team for your target language for guidance.

If you have questions, join the [irc://irc.freenode.net/wesnoth #wesnoth] channel on the Freenode IRC network and ask in there. Of course, you will also get answers if you ask your questions in the [http://forums.wesnoth.org/viewforum.php?f=7 Translations & Internationalization forum], or e-mail [mailto:Majora700@gmail.com Espreon] or [mailto:david_AT_torangan.de Torangan].

== See Also ==

* [[GettextForTranslators|GetText for Translators]] - how to translate Wesnoth using [[GetText]]
* [[WesnothTranslations|Wesnoth Translations]]
* [[TranslatorsGuide|Translators' Guide]]
* [http://gettext.wesnoth.org Translation statistics]
* [https://developer.berlios.de/projects/wescamp-i18n WesCamp-i18n project at Berlios.de]
* [http://svn.berlios.de/viewcvs/wescamp-i18n/ WesCamp-i18n SVN tree]

[[Category:Translations|*]]
[[Category:Campaigns]]

Wescamp.py Instructions

2011-12-27T00:54:30Z

AI: /* Notes */

Wescamp.py Instructions

2011-12-27T00:53:29Z

AI: /* Checkouts */

Sandbox

2011-12-15T18:26:55Z

AI:

The sandbox is for editing and formatting experiments. If you are already logged in, click on the "Edit" link above to experiment yourself!
[[Category:Wesnoth Wiki]]


{{LinkMacro|GOLD|easy normal hard}}

And now a simple {{LinkMacro|GOLD}} link.

{{Transclusion test}}

[[foo]]

Fosdem2012

2011-12-14T00:26:48Z

AI: /* Schedule/Plans */

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2012. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2012 will take place at the first weekend in Febuary 2012, on Saturday 4th and Sunday 5th.

* Fosdem - http://fosdem.org/2012/

== Schedule/Plans ==
{| border="1" width="100%"
|-
! (nick)name(s)
! Arrival
! Departure
! Accomodation
|-
| Ivanovic
| Fri, 3rd, "afternoon" (~15:00 at "chokopolis"; not 100% sure yet)
| Sun, 5th, leaving right from ULB campus
| 2go4?
|-
| AI
| Friday?
| Sunday?
| 2go4?
|-
|}

For accommodations please keep in mind that parking in the center of Brussels is really problematic. It might make sense to drive to the University where FOSDEM takes place, park there and take the bus into the town center (where some of the hotels/hostels are).

Possible hostels that we at least contacted over the last years (some of them might already be booked out by now!):
* [http://www.chab.be/ CHAB]
* [http://www.2go4.be/ 2go4] Note: groups bigger 6 are not allowed, so we can (officially) not form a complete Wesnoth group at this hostel, got to meet somewhere in town/at the university...
* [http://www.jeugdherbergen.be/brusselE.htm Bruegel YH]

On the official FOSDEM page [http://www.fosdem.org/2012/practical/accommodation some more possible hotels/hostels] are listed.

== Maps ==
* [http://tinyurl.com/3a65gr Bruegel YH]
* [http://tinyurl.com/35br9c Brussels Central (Train Station) → Bruegel YH]
* [http://tinyurl.com/37d9v4 Bruegel YH → Brussels Central (Train Station) → Novotel Grand Place]
* [http://tinyurl.com/2mzns6 Novotel Grand Place]
* [http://tinyurl.com/3dggg3 CrownePlaza (Europa)]
* [http://tinyurl.com/36epxj FOSDEM]
* [http://tinyurl.com/2w4bms Novotel Grand Place -> FOSDEM]

== Transportation ==
Information about how to reach the FOSDEM is listed at the [http://www.fosdem.org/2012/transportation official transportation subpage].

Short version of how to get there for those that reside in Bruegel YH and Novotel Grand Place (basically town center):

* Enter Bus 71 (Debrouckere - Central Station ("Gare Centrale") - Delta) somewhere at 'Central Station'
* Leave the bus at "ULB" (crossroads Ave. Adolphe Buyl - Sq. Deveze)
* Walk down Ave. Paul Heger on your right hand.

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own (though there will be the open source game dev devroom on Sunday where hopefully many Wesnoth devs will participate). Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like the last three years, it will be room number 115 in the building AW1. Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or something like this). Mordante will (hopefully) also bring a multi-outlet power strip and a 20m extension cable. There is no wired network, everything wireless (and sometimes rather/very unstable!). Beside this you should bring laptops since there are no computers available for hacking.

Short version:
AW1 - Room 115 (at least on Saturday)

== Discussions and Results ==
We usually discuss all sorts of things at FOSDEM, this section is basically a (really short) summary of things that were discussed including their results. First are the discussions that were done "in plenum" with basically all attendees around. At the bottom is an area meant for discussions that were held in sub groups that not all devs might be aware of that were around.

Please make sure to list any topics you want to talk about below. The GameDev Room topic might serve as sample...

===Wesnoth presence in the GameDev Room===
Since Ivanovic is responsible for organizing the Open Source Game Development Devroom which takes place on Sunday 5th, there will at least be one Wesnoth Dev busy with this room. Though several other will hopefully support Ivanovic in this effort and be around to listen to many interesting talks and presentations.

== Group Picture ==
Has to be taken first.

== Previous Years ==
* [http://www.wesnoth.org/wiki/Fosdem2011 FOSDEM 2011 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2010 FOSDEM 2010 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2009 FOSDEM 2009 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page], [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)], [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]