The Battle for Wesnoth Wiki - User contributions [en]

ImagePathFunctions

2024-12-29T22:35:09Z

Atreides: /* BLIT: Blit function */ translating blit to english ; )

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

A color palette can be either the attribute name from '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' (like magenta) or a comma separated list of hex color values.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-and-paste ==

=== BLIT: Blit function ===
Blit (superimpose) the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== CROP_TRANSPARENCY ===
{{devfeature1.17|26}}
Removes any transparent padding from around an image.

'''~CROP_TRANSPARENCY()'''

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

=== Pseudo IPFs ===

The following functions are ignored by the IPF image modification module, but used by other Wesnoth components. They only work in special areas.

==== NO_TOD_SHIFT: Disabling ToD ====

{{DevFeature1.13|8}}

This is used by the terrain renderer and prevents terrain and item images from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

==== RIGHT: Display portraits on the right ====

'''''([[DevFeature|Version 1.5.8 and later only]])'''''

This is used by the [[InterfaceActionsWML#.5Bmessage.5D|'''[message]''']] interface action and can be used to show a portrait on the right side of the screen.

'''~RIGHT()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [https://irydacea.me/projects/wespal Wespal] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
* [https://github.com/wesnoth/wesnoth/blob/master/src/image_modifications.cpp src/image_modifications.cpp] - file where IPFs are implemented
[[Category:WML Reference]]

Wesnothd

2024-02-21T16:26:53Z

Atreides: typo

'''wesnothd''' is the multiplayer server for Wesnoth, shipped as a separate executable named ''wesnothd''. Points of interest regarding the server are:
* [[MultiplayerServerWML]] for the network protocol
* [[ServerAdministration]] for admin commands
* [[WesnothdDesign]] for some info about the design of the server

[[Category:Development]]
[[Category:Server Documentation]]

ModificationWML

2024-01-18T19:17:48Z

Atreides: /* The [modification] toplevel tag */

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

This [[AddonsWML|addon module]] tag describes an SP or MP modification. A modification is, practically speaking, a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''', in addition to all the common [[AddonsWML|addon module keys and tags]]:

* '''type''': where the modification will be available for playing. Possible values are ''sp'', ''mp'', and ''hybrid''. hybrid equals mp + sp. N.B. If omitted it defaults to hybrid. Availability in SP also depends on whether or not modification tag is inside a multiplayer define. There is a bug where one can use modifications (not having type=mp) inside such a define by loading multiplayer and returning and then selecting campaign from the main screen.
* '''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.

== The [resource] toplevel tag ==

{{DevFeature1.13|2}}

The '''[resource]''' toplevel tag is another type of [[AddonsWML|addon module tag]] which is similar to '''[modification]''' but is invisible to the player. It can only be loaded on developer request, by the '''[load_resource]''' tag. It supports most of the common [[AddonsWML|addon module keys and tags]]. Besides that, there are no additional keys or tags supported in '''[resource]'''.

Glossary

2023-12-05T17:46:37Z

Atreides: /* Unofficial MP Eras */ Added in the rest of the most downloaded eras which have acronyms that I've heard

Use the following list to demystify the various (mostly wesnoth specific) terms and acronyms you may run into.



== Gaming Terms ==

; ability : A special game rule or capability applied to all units of the given unit type - for example every Elvish Shaman has the ability "heal". (See [[AbilitiesWML]] for creating abilities.)

; campaign: A sequence of scenarios with a connecting storyline. ([[MainlineCampaigns]], [[Guide_to_UMC_Content]], [[CampaignWML]])

; creeping biggerism: the tendency for sprite artists to make new sprites bigger and more detailed than the existing ones, leading to issues of scale.

; era: A set of factions available in multiplayer. You can download additional eras from the [[Guide_to_UMC_Content|add-on server]]. ([[EraWML]])

; faction: A set of units available to be plated as a side in multiplayer games. ([[EraWML|multiplayer_side WML tag]])

; fog of war: A scenario option; enemy units are displayed only when close to player's units

; mainline: A [[MainlineCampaigns|campaign]], multiplayer map, era, faction, image, or other resource that ships with the Wesnoth distribution. The opposite of "[[#U|UMC]]".

; scenario: A sequence of turns played on one map. ([[ScenarioWML]])

; shroud: A scenario option; the whole map is black at the beginning, only parts already "discovered" by the player are visible.

; team color (TColor, TC): A unit graphic done so that color of some unit part (e.g. clothes) reflects the team where unit belongs ([[Team Color Shifting]])

; trait: A random minor modification of a unit; it makes a unit different from other units of the same type. ([[UnitsWML|the trait tag]])

; UMC: "User-Made content" or "User-Maintained Content", campaigns and other material that does not ship with the game but is available for download from the [[Guide_to_UMC_Content|Wesnoth add-on server]].

; [[WesCamp|Wescamp]]: The (former) project for translating unofficial user-made campaigns

; zone of control (ZoC): game rule; when a unit moves to a hex adjacent to enemy unit, it usually cannot move further.

; zone-locked: said of a unit that has entered an enemy ZoC and therefore cannot move further (often just "zoced" for short).

== Wesnothian Acronyms ==

*AI - Artificial Intelligence (An 'AI side' is a side controlled by the computer)
*AMLA - After Maximum Level Advancement
*AoH - Age of Heroes
*BfM - Battle for Meridia
*BfW - Battle for Wesnoth (the name of the game)
*BWH - '''B'''een suggested before. '''W'''e think it's a good idea. '''H'''ope to add it eventually.
*CABD - Can Already Be Done, e.g., you can already create custom unit abilities via WML.
*CtH - Chance to Hit (also C2H)
*CtBH - Chance to Be Hit (also C2BH)
*CtK - Chance to Kill (also C2K)
*CtBK - Chance to Be Killed (also C2BK)
*FoW - Fog of War (i.e. fog)
*FFA - Free For All (playing a map with >2 players without teams)
*FPI - Frequently Posted Idea (read the [http://www.wesnoth.org/forum/viewtopic.php?t=1158|FPI Post] from the Ideas Forum)
*HANE—EtH - Hexes Are Not Evil - Embrace the Hex
*HAPMA - Hexes Are Possibly Miles Across
*HP - Hit points
*IIRWIIR - It Is Ready When It Is Ready
*IPF - [[ImagePathFunctions|Image Path Function]]
*KISS - Keep It Simple, Stupid: Applies to coding, not game rules (although indirectly it does): see [[WesnothPhilosophy]]
*MAI - Micro AI: see: [[Micro_AIs]]
*MP - Multiplayer or Movement Points
*MUB - Massive Unit Blobs
*N3T - No 3-Teams; A belief stating that contests between three equal and opposing forces are inherently unbalanced
*OAB - Options Are Bad; In reference to gameplay, not user interface options. Mostly used by Turin.
*OFWRA - Old Flame War Revival Alert; In other words, we have discussed this before and have no interest in discussing it again, especially if it got ugly
*OOS - Out Of Sync - an error generated by Wesnoth. OOS errors occur when game data for one player is different/incompatible from the others
*PoD - Paths of Daggers, the name of a 2v2 multiplayer map.
*RiPLIB - Reduction in Power when Leveling Is Bad: means that when a unit upgrades, at least one of its options should be strictly superior to the original unit. [http://www.wesnoth.org/forum/viewtopic.php?t=1423 Reference 1] / [http://www.wesnoth.org/forum/viewtopic.php?t=7205 Reference 2]
*RNG - Random Number Generator
*RPG - Role Playing Game - [http://www.wesnoth.org/forum/viewtopic.php?t=4385 1)] Wesnoth's experience system. <nowiki>2)</nowiki> An "RPG-style" game on the MP server means the primary focus will be walking your leader-units through a scripted storyline involving map exploration and lots of WML.
*RTS - Real Time Strategy Game - as opposed to a turn-based game like Wesnoth
*SLF - [[StandardLocationFilter]]
*SP - Single Player (Campaigns)
*SSF - [[StandardSideFilter]]
*SUF - [[StandardUnitFilter]]
*TBS - Turn Based Strategy Game, like Wesnoth
*ToD - Time of Day
*TWP - The Wesnoth Philosophy: [[WesnothPhilosophy]]
*UAPEB - Units Are Possibly Entire Battalions
*UMC - User Made Campaign or User Made Content (any add-on not packaged with Wesnoth)
*WICOT - WML is capable of this (the requested feature is already possible to script, so no need to hard-code it in C++)
*WINR - Wesnoth Is Not Realistic
*WIN_ - Wesnoth Is Not... (Warcraft, Lord of the Rings, medieval Europe, an RPG, a wargame, a war simulation, Fire Emblem, etc.)
*WML - Wesnoth Markup Language: [[ReferenceWML]]
*XP - Experience
*ZoC - Zone of Control

== Names of Mainline Campaigns and Scenarios ==

*AoI - ''An Orcish Incursion''
*DiD - ''Descent into Darkness''
*DM - ''Delfador's Memoirs''
*DW - ''Dead Water''
*EI - ''The Eastern Invasion''
*HttT - ''Heir to the Throne''
** BoP - ''Bay of Pearls''
** DD - ''Dwarven Doors''
** HotNE - ''Home of the North Elves''
** IotD - ''Isle of the Damned''
** RtW - ''Return to Wesnoth''
** SoE - ''Siege of Elensefar''
** SoF - ''Sceptre of Fire''
** TotC - ''Test of the Clans''
*IoM - ''Isle of Mists'' (MP, mainlined in 1.15)
*LoW - ''Legend of Wesmere''
*NR - ''Northern Rebirth''
*SoF - ''Sceptre of Fire''
*SotA - ''Secrets of the Ancient''
*SotBE - ''Son of the Black Eye''
*TB (or AToTB) - ''A Tale of Two Brothers''
*THoT - ''The Hammer of Thursagan''
*TRoW - ''The Rise of Wesnoth''
*TSG - ''The South Guard''
*UtBS - ''Under the Burning Suns''
*WC - ''World Conquest'' (MP, mainlined in 1.15)

== Unofficial Campaigns ==

*ANO - ''A New Order''
*AotDS - ''Aria of the Dragon Slayer''
*ARL - ''A Rough Life''
*ASoF - ''A Song of Fire''
*AtS - ''After the Storm''
*BCoA - ''Black Cross of Aleron''
*BMR - ''Bad Moon Rising''
*BW - ''Brave Wings''
*CCamp - ''Custom Campaign''
*FoaP - ''Fate of a Princess''
*FTC - ''Forward They Cried''
*FtF - ''Flight to Freedom''
*Gns - ''Genesis''
*HoI1 - ''Hero of Irdya - Book I''
*IftU - ''Invasion from the Unknown''
*IQ - ''Inky's Quest''
*LotI - ''Legend of the Invincibles''
*SE - ''Saving Elensefar''
*SfF - ''Struggle for Freedom''
*TBC - ''The Beautiful Child''
*TDH - ''The Dark Hordes''
*TEG - ''The Earth's Gut''
*TFE - ''The Final Exam''
*TLU - ''To Lands Unknown''
*TSL - ''The Silver Lands''
*TSoG - ''The Sojournings of Grog''
*WoF - ''Winds of Fate'' (formerly WoV for ''Wings of Victory'' or ''Wings of Valor'')
*WotJ - ''War of the Jewel''

<div id="Unit_Names"></div>

== Unofficial MP Eras ==

*AE - ''Ageless Era/Archaic Era''
*ANLE - ''A New Land Era''
*EEaW - ''17th Century Eastern Europe at War''
*EoM - ''Era of Myths''
*EoMa - ''Era of Magic''
*GSE - ''Great Steppe Era''
*IE - ''Imperial Era''
*RE - ''Rashy Era''
*RotL/Rotl - ''Reign of The Lords''
*WoL - ''War of Legends''

== Unit Jargon ==

*bird - usually Gryphon Rider/Master (knalgans), or occasionally a Falcon or Eagle Rider from the [//units.wesnoth.org/1.14/Extended_Era/en_US/era_extended_37.0.0.0.html Extended Era] Aragwaith and Kalifa factions.
*DA - Dark Adept (undead)
*fish - Merman (loyalists or rebels) or Naga Fighter (northerners)
*frog - a Saurian, especially "magic frog" for an Augur
*gobo - An affectionate, if somewhat derogatory term for the Goblin Spearman
*gunner - Dwarvish Thunderer/Thunderguard/Dragonguard (knalgans)
*HI - Heavy Infantryman (loyalists)
*MoL - Mage of Light (loyalists or rebels)
*pyro - Unit in the Drake Burner line
*Ulf - Dwarvish Ulfserker (knalgans)
*WC - Walking Corpse (undead)
*zombie - Walking Corpse

== General Acronyms ==

*AFaICT - As Far as I Can Tell (A statement with a disclaimer on truthfulness)
*AFaIK - As Far as I Know (A statement with a disclaimer on truthfulness)
*AfK - Away from the Keyboard
*ASaP - As Soon as Possible
*BRB - Be Right Back
*BtW - By the Way (A statement with a disclaimer on relevance)
*DTRT - Do The Right Thing (expectation for how something should work)
*EV - Expected Value
*FTR - For The Record
*FUBAR - F***ed up beyond all repair / reason
*FWIW - For what it's worth
*FYI - For Your Information
*GG - Good Game (a common courtesy to say after a multiplayer game; alternatively "GGWP" for "Good Game, Well Played")
*GtG - Got to Go
*IANAL - I Am Not A Lawyer (A disclaimer that a statement may not constitute legal advice.)
*IDK - I Don't Know
*IIRC - If I Recall/Remember Correctly (A statement with a disclaimer on truthfulness)
*IIUC - If I Understand Correctly (Similar to IIRC, but not implying that the speaker once knew with certainty.)
*IMHO - In My Humble Opinion (A statement with a disclaimer on objectiveness) (can also be read as "In My Honest Opinion")
*IMO - In My Opinion
*IYSWIM - If You See What I Mean (A statement seeking agreement)
*LGTM - Looks Good To Me (used by maintainers when approving Pull Requests on GitHub)
*LMAO - Laughing My A** Off
*LTNS - Long Time No See
*OMG - oh my god(s)
*OP - either "OverPowered", "Original Post", or "Original Poster", depending on context.
*OT - Off Topic: can refer either to the forum category ([http://www.wesnoth.org/forum/viewforum.php?f=11]) or to spam
*OtOH - On the Other Hand (A contrast)
*PR - Pull Request (in the context of contributing to a project like Wesnoth on GitHub; other projects that use other issue trackers use it to mean Problem Report instead)
*QFT - Quote For Truth
*RotFL - Rolling on the Floor Laughing; also RoFL
*RtFM - Read the F***ing Manual
*TTYL - Talk To You Later

[[Category:World of Wesnoth]]

StartingPoints

2023-10-30T16:14:24Z

Atreides: /* Playing the Game (Play) */ updated link to units for 1.16

{{Translations}}
{| style="float:right"
|
__NOTOC__
|}

What would you like to learn about Wesnoth in this wiki? [[Play]] it, [[create]] with it, [[support]] for it, examine the [[project]], view [[credits]] of it.

This is a page with starting points to exploring this wiki about The Battle for Wesnoth. In addition to the wiki, there's also a [//www.wesnoth.org homepage], a [//www.wesnoth.org/forum forum], and a [https://github.com/wesnoth Github project page].

* [[Special:Categories|List of all page categories in this wiki]]
* [[Special:Allpages|List of all pages in this wiki]]

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [https://github.com/wesnoth/wesnoth/blob/master/INSTALL.md Compiling Wesnoth] - on Unix, Mac, Windows, GNU/Linux, etc
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineCampaigns]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online
* [[Replays]] - archive of replays new and old
* [[How to play...]] - learn more about various faction vs faction strategies

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ChatCommands]] - commands you can use when on a multiplayer server
* [[ServerAdministration]] - commands that invoke direct server response (mostly for getting information)
* [//units.wesnoth.org/ Units] - Units advancement trees and stats
** [//units.wesnoth.org/1.16 Stable version]
** [//units.wesnoth.org/trunk Trunk version]
* [[Races]] - [[Drakes (race)|Drakes]], [[Dwarves]], [[Elves]], [[Humans]], [[Orcs]], [[Undead (race)|Undead]], etc.
** [[Factions]] - all major factions, mainline and user-made
* [[Glossary|Glossary]] - common Wesnothian jargon, acronyms and slang explained

== Tweaking the Game ([[Create]]) ==
==== Scenarios & Campaigns ====
* [[Guide_to_UMC_Content]] - user-written scenarios, campaigns and game modifications
* [[BuildingCampaigns]] - how to make your own single player campaigns
* [[MultiplayerContent]] - how to make your own multiplayer scenarios and campaigns
* [[BuildingScenarios]] - how to make your own scenarios
* [[BuildingUnits]] - how to make your own units
* [[BuildingFactions]] - how to make your own faction

==== References ====
* [[ReferenceWML]] - all about Wesnoth Markup Language

==== Art related ====
* [[Create_Art#Art_Tutorials|Art Tutorials]] - help in creating art

== Improving the Game ==
* [[ReportingBugs]] - use GitHub!
* [//www.wesnoth.org/wiki/ReportingBugs#Guidelines_for_suggesting_features Guidelines for suggesting features] - To submit a feature request, use https://bugs.wesnoth.org
==== Developer information ====
* [[DeveloperResources]] - useful links
* [//changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothRepository]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[DeveloperGuide]] - for those who received repository commit rights
* [[Git_for_Wesnoth_Crash_Course]] - guide for contributors who are new to git / github
* [[SoftwareTesting]] - for programmers
* [//www.wesnoth.org/units/trunk/animations.html Missing unit animations] - what's available and what's missing
* [[Wesnoth_AI]] - starting point for AI documentation
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[EasyCoding]] - Bugs and features that are easy to implement for new coders
* [[NotSoEasyCoding]] - Bugs and features which are doable but lacking someone working on them
* [[WesnothdDesign]] - Guide to the design of wesnothd, the multiplayer server.
* [[SummerOfCodeIdeas]] - Ideas for Google summer of code

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - translation maintainers contact information

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[Timeline of Wesnoth]] - the timeline of Wesnoth campaigns
* [[Geography of Wesnoth]] - description of Wesnoth and surrounding lands
* [[WesnothFigures]] - notable figures of valorous and infamous deeds in Wesnoth
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel
* [[Trailer]] - the Wesnoth trailer

== Other ==
* [[UsefulLinks]]
* [//en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiHaiku]]

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki
* [[WikiMigration]] - we were looking for a replacement for our old wiki (and ended up using Mediawiki)

[[Category:Wesnoth Wiki]]

User:Atreides

2023-01-02T17:14:22Z

Atreides: A mini bio?

Hi there. I'm a relative newcomer to Wesnoth. I've been playing games for a loooong time though. Even more recently I've gotten into WML (and now LUA) and ended up updating more than a dozen abandoned add-ons. I even created a new one.

Guide to UMC Content

2023-01-02T02:58:28Z

Atreides: /* Lonely Era (LE) */

This is a guide to current-ish user-made content for players. It provides unfamiliar players with detailed information about campaigns (including story, completion, difficulty and playing style) as well as detailed information about eras. Feel free to edit this guide, as it is a wiki.

This list covers add-ons for the latest 2 stable releases (1.14 and 1.16) of Wesnoth. There are archived versions of this page for [[Guide_to_UMC_Content/1.10|1.10]] and [[Guide_to_UMC_Content/1.12|1.12]].

For content creators who loved an add-on that hasn't been added to 1.14 or 1.16 yet, and are wondering about taking it over, please ensure that its entry on the older (1.12 or 1.10) wiki page is up to date, add a link to the add-on's feedback thread in the forums, and generally do the tidy-up that doesn't need you to start changing the campaign, and then ask the old maintainer. (You should probably also wait a bit before assuming that a maintainer isn't already porting to 1.16).

If you are looking for even more campaigns, please see the links in at the bottom of this page.

== Instructions ==
When adding a campaign to the list, please place it in its alphabetically sorted location, ignoring any initial article ("A", "An", or "The").

=== Blueprint for Campaigns ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status:
** Broken = Does not work at all
** Incomplete = Partially written, no progress
** WIP = Partially written, some progress
** Complete = Completely written, but buggy as well as potential balance issues.
** Finished = Completely written, minimal to no bugs, slight balance issues possible.

* Version campaign version on the add-ons server

* Length:

* Requirements: (only if needed)

* Difficulty:

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

** Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erratically from one scenario to the next and only people using the debug mode have seen the final, then it is.
** Easy
** Normal
** Hard

Please note: If you didn't play the campaign, write the difficulty written on the add-ons server.

* Style:

Please note: Many campaigns will feature more than one style. Please list the most significant ones. If you don't know which style is the campaign you are listing, don't write this.

** Skirmish = small to medium sized armies, your standard Wesnoth gameplay
** Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
** RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
** Survival = being exposed to changing, spawning enemies while remaining on the same map
** Large Battle = large number of units on the battlefield, sizely maps
** Simulation = campaigns feat. terrain modification, alternative resources
** Boss battle = the challenge is to defeat a single powerful enemy unit
** Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

* Faction/Era: Era for the whole campaign and more specifically the faction or unit composition you field.

* Custom units: Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

* Forum: Links to the feedback and development threads at forums.wesnoth.org

=== Blueprint for Eras ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status 1.14:
** see the list of statuses in the campaign blueprint

* Faction Descriptions: Describe your individual factions here.

* Requirements: (only if needed)

* Forum: Links to the feedback and development threads at forums.wesnoth.org

== How to play for UMC factions ==

=== Southern Nations by Elvenisko ===
[[How_to_play_Southern_Drakes|Southern Drakes]] |
[[How_to_play_Southern_Dwarves|Southern Dwarves]] |
[[How_to_play_Southern_Elves|Southern Elves]] |
[[How_to_play_Southern_Mages|Southern Mages]] |
[[How_to_play_Southern_Mercenaries|Southern Mercenaries]] |
[[How_to_play_Southern_Orcs|Southern Orcs]] |
[[How_to_play_Southern_Swamplords|Southern Swamplords]] |
[[How_to_play_Southern_Nations|Comparison]] |
[https://units.wesnoth.org/1.16/Southern_Nations/en_US/era_southern.html All units (can be out of date)]

== Battle for Wesnoth 1.14 and newer ==

=== Campaigns ===

==== After the Storm ====

''Follow the journey of Galas and his band following the events of Invasion from the Unknown''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 0.10.11

'''Length:''' 3 episodes of 13 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32091]

'''GitHub:''' [//github.com/project-ethea/After_the_Storm]

'''Note:''' (vultraz) Long, very enjoyable campaign with great story. (Knyghtmare) The best UMC campaign ever!

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#After_the_Storm Players’ Review(s)]'''

====A Beastly Tale====

''When a small village is beset by troubles, its fate rests in the hands of a young woodsman and the animals he befriends.''

'''Author:''' GloccusV

'''Status:''' Complete

'''Version:''' 2.0.3

'''Length:''' 5 scenarios

'''Difficulty:''' Intermediate

'''Custom units:''' [//units.wesnoth.org/1.14/A_Beastly_Tale/en_US/A_Beastly_Tale.html Here]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41434&p=633612&hilit=A+Beastly+Tale#p579093 Here]

====A Song of the Winds====

''Every era has its heroes and heroines. Before the song of Myra, the odyssey of Akhen Wadjet and the aria of Tenma Yozora, there was the song of the winds that echoed in the mountains and halls at the heart of the Great Continent. Follow young Maat of Hiera'Shirsha and Prince Abhai of Garet-Desh in the war that set the stage for one of the greatest upheavals Irdya has ever witnessed.
(Prequel to the Dragon Trilogy)''

'''Author:''' revansurik

'''Status:''' Complete

'''Version:''' 1.0.0

'''Length:''' 43 scenarios (some of them dialogue-only)

'''Difficulty:''' Intermediate

'''Custom units:''' War of Legends + Custom factions

'''Forum:''' [//https://forums.wesnoth.org/viewtopic.php?f=8&t=53913 Here]

==== Bad Moon Rising ====

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Complete 1.10.0

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31348]

'''GitHub:''' [//github.com/doofus-01/wesnoth-Bad_Moon_Rising]

==== The Black Cross of Aleron ====

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete 2.0.3

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[https://units.wesnoth.org/1.14/Black_Cross_of_Aleron/en_US/celmin-druid-siege.html Custom units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

==== Danse Macabre ====

''Macabre is a rare zombie who has intelligence and will. What's he like? What's his purpose?''

'''Author:''' kamikaze

'''Maintainer:''' James_The_Invisible

'''Status:''' Completed, 1.3.2

'''Length:''' 12 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Large Battle

'''Faction/Era:''' Default, undead

'''[//units.wesnoth.org/1.14/Danse_Macabre/en_US/Danse_Macabre.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=33745]

'''Note:''' While the campaign is playable on Wesnoth 1.14 without major issues, it is (still) in need of heavy re-balancing. Sadly, for various reasons I am not able to do it in near future but patches are always welcome, preferably in form of pull requests on [https://github.com/konecnyjakub/Danse_Macabre GitHub].

==== Dawn of Thunder ====

''A young elvish fighter is send to represent the Aethenwood at the Ka'lian. The adventure turns out to be bigger than expected.''

'''Author:''' Paulomat4

'''Maintainer:''' egallager

'''Status:''' [https://github.com/cooljeanius/dawn_of_thunder/issues/3 Incomplete], latest release on the BfW 1.16 add-on server is [https://github.com/cooljeanius/dawn_of_thunder/releases/tag/0.2.2 0.2.2].

'''Length:''' 18 scenarios

'''Difficulty:''' Challenging

'''Style:''' Skirmish, Large Battle, RPG-elements

'''Faction/Era:''' Default, Elves, Humans

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=39512]

==== A Fiery Birth ====

''A scholar of the Great Academy journeys to the land of the drakes to discover their secret origins.''

'''Author:''' Mathbrush

'''Status:''' Complete

'''Version:''' 1.2.0

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=47861&p=623953 Here]

'''GitHub:''' [//github.com/brirush84/AFieryBirth]

==== The Final Exam ====

''Young mage Erika must find a magic book to become a true mage. But will it really be her final exam?''

'''Author:''' Elven

'''Status:''' Complete, 2.6.1

'''Length:''' 4 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23398]

'''Note:''' Short, easy campaign with varying objectives. Features female mage as leader.

==== [[FlightToFreedom|Flight to Freedom]] ====

''Flight to Freedom chronicles the story of the drake hero Malakar, and his desperate cross-country flight out of slavery.''

'''Authors:''' MadMax, Nova

'''Maintainer:''' egallager

'''Status:''' Complete

'''Length:''' 20 playable scenarios + 1 dialogue-only, for a total of 21

'''Version:''' [https://github.com/cooljeanius/Flight_Freedom/releases/tag/5.4.1 5.4.1]

'''Difficulty:''' Expert

'''Style:''' Skirmish, Large Battle, Puzzle

'''Faction/Era:''' Drakes

'''Required Wesnoth version:''' 1.16+

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=1887]

'''GitHub:''' [//github.com/cooljeanius/Flight_Freedom]

==== Inky's Quest ====

''The Cuttlefish Campaign''

''Are the cuttlefish mere beasts or something more? What stories would they tell if they could speak? This story provides one possible answer. The easiest difficulty provides hints for novice players.''

'''Author:''' Telchin

'''Status:''' Complete

'''Length:''' 12 scenarios + story-only epilogue, for a total of 13

'''Version:''' 1.5.6

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Custom units (cuttlefish, tentacles, giant clams...). Enemies use both default era units and custom ones.

'''[//units.wesnoth.org/1.14/Inky_Quest/en_US/Inky_Quest.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32501]

==== Invasion from the Unknown ====

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 2.1.9

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=43309]

'''GitHub:''' [//github.com/project-ethea/Invasion_from_the_Unknown]

'''Walkthrough:''' [[IftU Walkthrough]]

''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players’ Review(s)]'''

==== Leader of the Drakes ====

''Leader of the drakes is killed. His son tries to defend homeland against the orcs. He choosed to ally with saurians, but other clans of drakes disagrees. Will fast and unexperienced Morin win against orcs and rebel drakes alike?''

'''Author:''' Elven

'''Status:''' Complete, 1.02b

'''Length:''' 3 scenarios

'''Difficulty:''' Easy/Medium

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Drakes

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=53951&start=15]

'''Note:''' Short, easy campaign with simple objectives. Features Drake Glider as leader and modified Drake Burner with cold and slowing blade.

==== Legend of the Invincibles ====

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish threat, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (5 chapters, 110 scenarios) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' Complete

'''Length:''' 200 (+8 talk-only) scenarios

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Forum:''' [//r.wesnoth.org/t32384]

'''GitHub:''' [//github.com/Dugy/Legend_of_the_Invincibles]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles|Players’ Review(s)]]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

==== A New Order ====

''The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Dunefolk mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?''

''Note: This campaign contains mature themes, some of which may be unsuitable for children.''

'''Author:''' szopen

'''Maintainers:''' nemaara (Yumi), egallager

'''Status:''' Finished

'''Version:''' [https://github.com/nemaara/A_New_Order/releases/tag/1.5.0.1 1.5.0.1] (4th version digit is only because [https://github.com/nemaara/A_New_Order/releases/tag/1.5.0 1.5.0] was mis-tagged; the plan is to go back to the semver-standard of 3 version digits for the next release)

'''Length:''' Hard to say as it is non-linear; it is advertised as having 45 scenarios, but the numbering only goes up to 30 due to some of the scenarios being alternates to one another.

'''Requirements:''' Requires BfW 1.16+. Also uses the "Akladian Music" add-on.

'''Difficulty:''' Advertised as intermediate; could be considered hard, though.

'''Style:''' Mostly Skirmish, some Large Battle

'''Faction/Era:''' mostly various human factions (including the Dunefolk), with the addition of the Akladian faction of humans

'''[//units.wesnoth.org/1.16/A_New_Order/en_US/A_New_Order.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=6486&sid=2e644284f54e65736b4f1543b7098ef9]

'''GitHub:''' [//github.com/nemaara/A_New_Order]

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

''' [http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#A_New_Order Players’ Review(s)]'''

==== The North Wind ====

''Wesnoth's army was occupied fighting Mal Ravanal in the East, but there were whisperings of an orcish attack in the north. Konrad II must send Deoran, now an experienced rider and commander, with a small band of knights to hold off the orcs....''

''This campaign features unique gameplay characteristics such as a lack of recruiting and a 24-turn time-of-day cycle.''

'''Author:''' aelius, Deusite; pyndragon

'''Status:''' WIP, 0.3.0

'''Length:''' 1 playable scenario, 6 intended

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish, Survival

'''Faction/Era:''' Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=42854]

==== The Ravagers====

'''Description:''' ''The Ravagers'' is a tale of pure revenge. A tale of justice served cold, told in a flashback-style point-of-view narrative, by a ranger in the Inn at Weldyn.
The campaign includes many new exciting gameplay features, fun mechanics such as drinking, hundreds of custom units, and many more.

'''Author:''' WhiteWolf

'''Status:''' Finished*

'''Length:''' 25 playable scenarios + 2 scene scenarios

'''Requirements:''' Akladian Music Pack, Underness Music Pack

'''Difficulty:''' Intermediate

'''Style:''' Skirmish + RPG / Flashback narrative

'''Faction/Era:''' Humans, Elves, Ravagers(dark humans)

'''[//units.wesnoth.org/1.14/The_Ravagers/en_US/The_Ravagers.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44930]

'''*Notes:''' The main storyline is complete, but there are unfinished side-missions that are still in development. The campaign is aimed to become finished with version 1.2.0.

==== Return from the Abyss ====

''After taking part to a disastrous expedition, Khafir and his men are lost and isolated from their people, thousands of miles away from home, bound by a pact sealed with a powerful dwarvish king. Help him escape from the depth of Irdya and finding his way back, in an adventure across two worlds during the rise of a sinister force in the Great Continent.''

'''Author:''' skeptical_troll

'''Status:''' finished

'''Length:''' 19 playable scenario + 10 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Dunefolk/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44545]

==== Rise of the Dunefolk ====

''Adventure of Siabbin and Helare from small village in desert, who step by step made the foundation of the Dunefolk nation. Play a stunning adventure against many enemies in different maps - from sandstorm to swampy areas and caves. Defeat powerful lich lord and train one of the best dark mages in the world of Wesnoth.''

'''Author:''' Elven

'''Status:''' Completed

'''Length:''' 11 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish, Minigames, Survival

'''Faction/Era:''' Default, Dunefolk and dark mage

'''Note:''' enjoable gameplay with every map different. Enough experience to upgrade your units.

==== The Return of the Darks ====

''The Darks are a race which left Wesnoth in the ancient times and lives on Isles in the sky. But now the Magic wich helped them to move the Isles in Sky got lost and the isles are about to fall down. Rumion an adventurer goes to Wesnoth and searchs for something that could help them.''

'''Author:''' thvk

'''Status:''' WIP

'''Length:''' 4 playable scenario + 2 story only

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Default + some self made units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=52731]

==== Secrets of the Ancients ====

''From the Journal of Ardonna of Tarrynth:''

''It's unfair that we humans must die after so few years. Though this is the natural order, we need not embrace it! The lords on the Green Isle knew how to live forever. Pursuit of that knowledge was declared illegal by King Haldric I, but I believe it is worth the risk: If I can rediscover the secrets of the ancients, not only will I cheat death, I will become a hero to the whole continent!''

'''Author:''' beetlenaut

'''Status:''' Mainlined (this is now one of the campaigns that is downloaded with Wesnoth itself)

'''Length:''' 18 playable scenarios + 3 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Undead/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=40545]

'''Walkthrough:''' [[Secrets of the Ancients Walkthrough]]

==== Swamplings ====

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Version:''' 1.2.0i

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction:''' Goblins

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41254]

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players’ Review(s)]'''

==== The Dark Hordes ====

''Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.''

'''Author:''' Circon

'''Maintainer:''' Various

'''Status:''' Incomplete/WIP

'''Length:''' 15 scenarios done so far

'''Version:''' 0.1.2

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[//units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=16576&]

==== The Tale of Vaniyera ====

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Finished 0.11.0

'''Length:''' 5 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=37880]

'''Walkthrough''' There is a video-walkthrough by the campaign maintainer that begins [https://www.youtube.com/watch?v=dGM1bjImvkI&list=PLZorLYWvUD7VIhaXxKwzO8iQANlp_TaF0 here].

'''Note:''' As of August 2014, all previous issues raised about this campaign have been addressed. If you've not played this campaign since 1.4 or 1.10, in this humble maintainers opinion, it's worth another go.

==== To Lands Unknown ====

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31799]

'''GitHub:''' [//github.com/inferno8/wesnoth-To_Lands_Unknown]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown|Players’ Review(s)]]'''

==== A Vision Blinded ====

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' Adamant14

'''Status:''' Complete, 1.0.14

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[//units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23463]

=== Eras ===

[[Category:Campaigns|*]]
[[Category:Eras|*]]

==== '''Southern nations''' ====

[[How_to_play_Southern_Nations|Everything about southern nations, including how to play series]]

==== '''War of Legends''' ====

'''Description:''' A multiplayer era focused on the Dark Irdya Campaigns. Contains 15 factions.

'''Author:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Maintainer:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Status:''' Complete, new features being added for the 1.15.x version of the add-on

'''Factions:'''

# Aragwaithi
# Windsong
# Human Alliance
# Orcish Union
# Southerners (Desert Elves)
# Outlaws
# Elementals
# Undead
# Drakes
# Dark Legion
# Sylvans
# Minotaurs
# Vampires
# Dunefolk
# Knalgan Alliance

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=30087 Development and Feedback Thread]

'''GitHub:''' [//github.com/knyghtmare/War_of_Legends]

==== Era of Magic(EoMa) ====

'''Description:''' Aiming at using the whole potential of Battle of Wesnoth's graphic engine, the Era of Magic is considered to have a most amazing special effects and attack animations in the BfW game. There are 8 playable factions with fully animated units and tons of special effects contained in the era, and the stories of them are told in the campaign "To Lands Unknown".

'''Author:''' Inferno8

'''Maintainer:''' Inferno8

'''Status:''' Finished, 3.1

'''Faction Descriptions:'''

Sky Kingdom - powerful magi of all kinds. Their knowledge allows them to cast amazing spells and summon creatures like unstopable Golems or mysterious Mus. Masters of Elements and Gurus are one of the most powerful human beings in the Era.

Al-Kamija - these proud people are good warriors and spell casters of the desert. They use magical circles and scrolls to summon amazing creatures like Jinns or elementals from other dimension called Abyss. These creatures can't be poisoned, which is a great advantage.
(The campaign "To Lands Unknown" is mainly about the story of this faction)

Tharis - fearsome Tharis faction is very dangerous especially at night. Cruel people of Tharis with their black magic and dreadful monsters like Hydra can demolish everything standing on their way. Being so powerful in attack, Tharis have no healer, so they need to push forward at all costs.

Kharos - this strange name is the name of a beautiful country ruled by prophets of light. These peaceful people are masters of defense and support. Their formations of healers and Shielders assisted by Silver Warriors, who can teleport between friendly villages, are very hard to destroy.

Barbarians - the best in hand-to-hand combat. This multi-cultural society divided into Goblins, Orcs, Cyclops and Trolls with their own advantages and disadvantages can be hard opponent, but separately they are very weak.

Runemasters - these Dwarves use runic magic and equipment and are well known of their protection against magic. The Runemasters create steam machines like Gyrocopters, Robots and even mighty Mechanical Dragons. Units from this faction are very resistant but slow.

Dark Blood Alliance - this faction is composed of agile lizards, giant frogs, wyverns swallowing enemies and salamanders, which have developed to perfection the art of disguise. At the head of the community stand shamans known for their water magic, which is used in the fight as well as in healing.

Destroyers - a terrifying undead creations consisting of civilizations long gone...

'''Version:''' 1.1.1 (February 18th, 2015)

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=20039 Development and Feedback Thread]

'''GitHub:''' [//github.com/inferno8/wesnoth-Era_of_Magic]

==== Ageless Era ====

'''Description:''' Ageless Era is a compilation of the most popular eras and factions on the add-on server. It is more an era pack than an era.

'''Author:''' mnewton1, Ravana and various

'''Maintainer:''' Ravana

'''Status:''' Finished, 4.19

'''Unit Tree:''' [//units.wesnoth.org/1.12/Ageless_Era/en_US/Ageless%20Era.html Ageless Unit Tree (for 1.12)]

'''Factions List:''' Currently there are 91 factions in the era:

Default: Loyalist, Rebels, Northerners, Undead, Knalgan Alliance, Drakes, Khalifate

Extended Era: Loyalist, Sylvans, Dwarves, Outlaws, Northerners, Undead, Chaos, Dark Elves

Archaic Era: Khthon, Phantoms, Despair, Primeval, South-Seas, Ukians, Northern Orcs

Era of Four Moons: Highlanders, Imperialists, Sea States, Darklanders, Dalefolk, Freemen, Pygmies, Whites

Era of the Future: Welkin, Brungar

BEEM: Anakes, Calidonians, Wood Warriors

Custom Factions: Yokai, Dark Legion, Desert Elves, Steelhive, Frozen

Era of Myths: Celestials, Devlings, Elementals, Therians, Vampires, The Warg, Windsong

Feudal Era: Aragwaithi, Ceresians, Clockwork Dwarves, High Elves, Orcish Khaganates

Imperial Era: Arendians, Cavernei, Issaelfr, Lavinian Legion, Marauders, Orcei Gladiatores, Sidhe

Era of Strife: Eventide, Triththa, Free Saurians, Eltireans, Minotaurs

Era of Magic: Barbarians, Dark Blood Alliance, Sky Kingdom, Kharos, Runemasters, Al-Kamija, Tharis, Destroyers

Mercenaries Era: Highlanders, Enchanters, Avians, Slavers, Mercenaries, Equestrians, Emperor's Guard, Oracles, Holy Order, The Cult, Fanatics, Tribalists, Hive, Infernai, Refugees, Blight

'''Git:''' [https://github.com/ProditorMagnus/Ageless-for-1-11 Ageless-for-1-11] and also for 1.12 and [https://github.com/ProditorMagnus/Ageless-for-1-14 1.14]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=25274 Development and Feedback Thread]

==== Imperial Era (IE) ====

'''Description:''' One of the oldest maintained user eras, the Imperial Era brings together seven different factions in a completely re-imagined setting, the world of Orbivm, a very lethal world indeed. The era contains both mainline and development versions of each faction and can be used to play five campaigns, each featuring a different race.

'''Author:''' Orbivm Project (but really Turin)

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete, 0.23

'''Faction Descriptions:'''

# Lavinian Legion - Based on the Roman Legion, the Lavinians have strong, versatile melee units in the legionaries and a range of support classes sourced from amongst the Lavinian population and various subjugated races. The legion are strong in the plains but weak when fighting in forested areas. The Lavinians are featured in "Fall of Silvium".
# Sidhe - The Sidhe are a group of forest-dwelling elves whose focus is stealth and fleet movement. Their mages are able to channel the lightning itself, and their various other units move almost as fast. The Sidhe feature in "Tale of Vaniyera".
# Marauders - Based on the Germanic peoples that eventually conquered Rome (hint, hint), the Marauders are equally as at home in the hills, forests and swamps of their homeland. Their hard-hitting melee units are practicalyl unstoppable during the night-time. The Marauders are the stars of the "Alfhelm the Wise" campaign.
# Orcei Gentorum - The orcs have been captured gladiators slaving away in the Lavinian arenas for generations.The life of an orc in Orbivm is harsh and brutal, just like the orcs themselves. The tale of the uprising of one such group of Orcs is told in "Up from Slavery".
# Cavernei - The Cavernei are a dwarvish race with similarities to the mainline Knalgans, but with a greater emphasis on the military uses of runesmithing. They get a campaign too, in "Gali's Contract"
# Issaelfr - The frost elves live on the fringes of the habitable lands of Evrosia, the main continent of Orbivm, and have become inured to difficult conditions and tuned in to their Fae natures. They don't have a campaign yet, but you could always write one.
# Arendians - The Arendians are horse-lords living on the Western steppes of Evrosia. A life of constant battle has developed a military-focused society where warriors are trained from a young age. They used to have a campaign, but it fell into disrepair a very long time ago.

'''Wiki:''' [[Orbivm]]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=37920 Development and Feedback Thread]

==== Lonely Era (LE) ====

'''Description:''' The Lonely Era is a new collection of six selected superior solitary sides with interesting and unusual abilities, traits and attributes.

It has been extensively revised and rebalanced over the last few years from the original era and the constituent factions.

'''Author:''' Atreides. Based on work by Shield, Desert_Shyde, Brilliand, Stern, Cloud, Grigistian, mikoc5, Stopsignal, The_Gnat, Minnakht.

'''Maintainer:''' Atreides

'''Status 1.16:''' Finished

'''Faction Descriptions:'''

1) Santa's Helpers are his Elves as well as animated pine trees. They are an updated faction based on the Merry Christmas Campaign. Beware of Elves bearing gifts though, the presents are very distracting. They are unique in not having standard levels, they each can gain up to 4 special abilities via AMLA but always remain at level 1. Of course there are also Flying Reindeer and Christmas Seals.

2) Gremlins are an all teleporting race of elusive ethereal creatures. Individually fragile they work together using their tremendous mobility to swarm and overwhelm their enemies. Their mages are perhaps the ultimate glass cannons but if you can somehow keep one alive long enough it might even get to level 5 and become immortal.

3) Vaeringjar are a Viking faction allied with Wolfkin. The vikings eschew ranged weapons as well as sissy ideas like dodging blows but are a very, very hardy lot. They also have a unique herbalist unit that can inspire berserker rage in adjacent vikings for a turn. The wolfkin are lithe and armed with bows and teeth on the other hand. They are also very agile in contrast to the vikings. As nocturnal hunters they are devastating at night and almost helpless in the day.

4) Avians are cold loving, water hating bipedal birds. Their hollow bones and feathers make them vulnerable to fire and blunt weapons. They are unique in having cheap level 0 healers. Unusually their leaders are not drawn from the ranks but form a separate class only selectable as leaders. Tamed Albatrosses to patrol the awful waters.

5) The Deep Ones - Slimy, slippery, blasphemous fish-frogs of the nameless design - living and horrible - have now been sighted on the edge of Wesnoth. Mutants who slowly evolve from human to monster these creatures are nothing to be trifled with! An all water faction they are quite capable of holding their own against the landlubbers.

6) Jephrifs live far up in the sky, miles above land. Away from even the most basic things most other races take for granted, such as solid ground, their society developed to be quite alien indeed. In recent times, jephrifs began descending from the skies to participate in combat against other races - apparently for their own amusement, seeing life as a game.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=42630 Development and Feedback Thread]

== Additional info ==
See also:
* [[Player_UMC_Reviews|Player UMC Reviews]]
* [[:Category:User-made Campaigns - Walkthroughs|Walkthroughs for user-made campaigns]]
* [//r.wesnoth.org/t37476 forum thread] for this page
* [[Guide_to_UMC_Content/1.12|Guide to user-made content (UMC) for Battle for Wesnoth 1.12]]
* [[Guide_to_UMC_Content/1.10|Guide to user-made content (UMC) for Battle for Wesnoth 1.10]]
* [//r.wesnoth.org/t36733 thread discussing 1.8 UMC that wasn't ported to 1.10]
* [//r.wesnoth.org/t48086 thread discussing all UMC that hasn't been ported to 1.14]
* [//addons.wesnoth.org the addon server]

Guide to UMC Content

2023-01-02T02:56:02Z

Atreides: /* Lonely Era (LE) */

This is a guide to current-ish user-made content for players. It provides unfamiliar players with detailed information about campaigns (including story, completion, difficulty and playing style) as well as detailed information about eras. Feel free to edit this guide, as it is a wiki.

This list covers add-ons for the latest 2 stable releases (1.14 and 1.16) of Wesnoth. There are archived versions of this page for [[Guide_to_UMC_Content/1.10|1.10]] and [[Guide_to_UMC_Content/1.12|1.12]].

For content creators who loved an add-on that hasn't been added to 1.14 or 1.16 yet, and are wondering about taking it over, please ensure that its entry on the older (1.12 or 1.10) wiki page is up to date, add a link to the add-on's feedback thread in the forums, and generally do the tidy-up that doesn't need you to start changing the campaign, and then ask the old maintainer. (You should probably also wait a bit before assuming that a maintainer isn't already porting to 1.16).

If you are looking for even more campaigns, please see the links in at the bottom of this page.

== Instructions ==
When adding a campaign to the list, please place it in its alphabetically sorted location, ignoring any initial article ("A", "An", or "The").

=== Blueprint for Campaigns ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status:
** Broken = Does not work at all
** Incomplete = Partially written, no progress
** WIP = Partially written, some progress
** Complete = Completely written, but buggy as well as potential balance issues.
** Finished = Completely written, minimal to no bugs, slight balance issues possible.

* Version campaign version on the add-ons server

* Length:

* Requirements: (only if needed)

* Difficulty:

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

** Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erratically from one scenario to the next and only people using the debug mode have seen the final, then it is.
** Easy
** Normal
** Hard

Please note: If you didn't play the campaign, write the difficulty written on the add-ons server.

* Style:

Please note: Many campaigns will feature more than one style. Please list the most significant ones. If you don't know which style is the campaign you are listing, don't write this.

** Skirmish = small to medium sized armies, your standard Wesnoth gameplay
** Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
** RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
** Survival = being exposed to changing, spawning enemies while remaining on the same map
** Large Battle = large number of units on the battlefield, sizely maps
** Simulation = campaigns feat. terrain modification, alternative resources
** Boss battle = the challenge is to defeat a single powerful enemy unit
** Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

* Faction/Era: Era for the whole campaign and more specifically the faction or unit composition you field.

* Custom units: Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

* Forum: Links to the feedback and development threads at forums.wesnoth.org

=== Blueprint for Eras ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status 1.14:
** see the list of statuses in the campaign blueprint

* Faction Descriptions: Describe your individual factions here.

* Requirements: (only if needed)

* Forum: Links to the feedback and development threads at forums.wesnoth.org

== How to play for UMC factions ==

=== Southern Nations by Elvenisko ===
[[How_to_play_Southern_Drakes|Southern Drakes]] |
[[How_to_play_Southern_Dwarves|Southern Dwarves]] |
[[How_to_play_Southern_Elves|Southern Elves]] |
[[How_to_play_Southern_Mages|Southern Mages]] |
[[How_to_play_Southern_Mercenaries|Southern Mercenaries]] |
[[How_to_play_Southern_Orcs|Southern Orcs]] |
[[How_to_play_Southern_Swamplords|Southern Swamplords]] |
[[How_to_play_Southern_Nations|Comparison]] |
[https://units.wesnoth.org/1.16/Southern_Nations/en_US/era_southern.html All units (can be out of date)]

== Battle for Wesnoth 1.14 and newer ==

=== Campaigns ===

==== After the Storm ====

''Follow the journey of Galas and his band following the events of Invasion from the Unknown''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 0.10.11

'''Length:''' 3 episodes of 13 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32091]

'''GitHub:''' [//github.com/project-ethea/After_the_Storm]

'''Note:''' (vultraz) Long, very enjoyable campaign with great story. (Knyghtmare) The best UMC campaign ever!

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#After_the_Storm Players’ Review(s)]'''

====A Beastly Tale====

''When a small village is beset by troubles, its fate rests in the hands of a young woodsman and the animals he befriends.''

'''Author:''' GloccusV

'''Status:''' Complete

'''Version:''' 2.0.3

'''Length:''' 5 scenarios

'''Difficulty:''' Intermediate

'''Custom units:''' [//units.wesnoth.org/1.14/A_Beastly_Tale/en_US/A_Beastly_Tale.html Here]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41434&p=633612&hilit=A+Beastly+Tale#p579093 Here]

====A Song of the Winds====

''Every era has its heroes and heroines. Before the song of Myra, the odyssey of Akhen Wadjet and the aria of Tenma Yozora, there was the song of the winds that echoed in the mountains and halls at the heart of the Great Continent. Follow young Maat of Hiera'Shirsha and Prince Abhai of Garet-Desh in the war that set the stage for one of the greatest upheavals Irdya has ever witnessed.
(Prequel to the Dragon Trilogy)''

'''Author:''' revansurik

'''Status:''' Complete

'''Version:''' 1.0.0

'''Length:''' 43 scenarios (some of them dialogue-only)

'''Difficulty:''' Intermediate

'''Custom units:''' War of Legends + Custom factions

'''Forum:''' [//https://forums.wesnoth.org/viewtopic.php?f=8&t=53913 Here]

==== Bad Moon Rising ====

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Complete 1.10.0

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31348]

'''GitHub:''' [//github.com/doofus-01/wesnoth-Bad_Moon_Rising]

==== The Black Cross of Aleron ====

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete 2.0.3

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[https://units.wesnoth.org/1.14/Black_Cross_of_Aleron/en_US/celmin-druid-siege.html Custom units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

==== Danse Macabre ====

''Macabre is a rare zombie who has intelligence and will. What's he like? What's his purpose?''

'''Author:''' kamikaze

'''Maintainer:''' James_The_Invisible

'''Status:''' Completed, 1.3.2

'''Length:''' 12 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Large Battle

'''Faction/Era:''' Default, undead

'''[//units.wesnoth.org/1.14/Danse_Macabre/en_US/Danse_Macabre.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=33745]

'''Note:''' While the campaign is playable on Wesnoth 1.14 without major issues, it is (still) in need of heavy re-balancing. Sadly, for various reasons I am not able to do it in near future but patches are always welcome, preferably in form of pull requests on [https://github.com/konecnyjakub/Danse_Macabre GitHub].

==== Dawn of Thunder ====

''A young elvish fighter is send to represent the Aethenwood at the Ka'lian. The adventure turns out to be bigger than expected.''

'''Author:''' Paulomat4

'''Maintainer:''' egallager

'''Status:''' [https://github.com/cooljeanius/dawn_of_thunder/issues/3 Incomplete], latest release on the BfW 1.16 add-on server is [https://github.com/cooljeanius/dawn_of_thunder/releases/tag/0.2.2 0.2.2].

'''Length:''' 18 scenarios

'''Difficulty:''' Challenging

'''Style:''' Skirmish, Large Battle, RPG-elements

'''Faction/Era:''' Default, Elves, Humans

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=39512]

==== A Fiery Birth ====

''A scholar of the Great Academy journeys to the land of the drakes to discover their secret origins.''

'''Author:''' Mathbrush

'''Status:''' Complete

'''Version:''' 1.2.0

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=47861&p=623953 Here]

'''GitHub:''' [//github.com/brirush84/AFieryBirth]

==== The Final Exam ====

''Young mage Erika must find a magic book to become a true mage. But will it really be her final exam?''

'''Author:''' Elven

'''Status:''' Complete, 2.6.1

'''Length:''' 4 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23398]

'''Note:''' Short, easy campaign with varying objectives. Features female mage as leader.

==== [[FlightToFreedom|Flight to Freedom]] ====

''Flight to Freedom chronicles the story of the drake hero Malakar, and his desperate cross-country flight out of slavery.''

'''Authors:''' MadMax, Nova

'''Maintainer:''' egallager

'''Status:''' Complete

'''Length:''' 20 playable scenarios + 1 dialogue-only, for a total of 21

'''Version:''' [https://github.com/cooljeanius/Flight_Freedom/releases/tag/5.4.1 5.4.1]

'''Difficulty:''' Expert

'''Style:''' Skirmish, Large Battle, Puzzle

'''Faction/Era:''' Drakes

'''Required Wesnoth version:''' 1.16+

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=1887]

'''GitHub:''' [//github.com/cooljeanius/Flight_Freedom]

==== Inky's Quest ====

''The Cuttlefish Campaign''

''Are the cuttlefish mere beasts or something more? What stories would they tell if they could speak? This story provides one possible answer. The easiest difficulty provides hints for novice players.''

'''Author:''' Telchin

'''Status:''' Complete

'''Length:''' 12 scenarios + story-only epilogue, for a total of 13

'''Version:''' 1.5.6

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Custom units (cuttlefish, tentacles, giant clams...). Enemies use both default era units and custom ones.

'''[//units.wesnoth.org/1.14/Inky_Quest/en_US/Inky_Quest.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32501]

==== Invasion from the Unknown ====

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 2.1.9

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=43309]

'''GitHub:''' [//github.com/project-ethea/Invasion_from_the_Unknown]

'''Walkthrough:''' [[IftU Walkthrough]]

''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players’ Review(s)]'''

==== Leader of the Drakes ====

''Leader of the drakes is killed. His son tries to defend homeland against the orcs. He choosed to ally with saurians, but other clans of drakes disagrees. Will fast and unexperienced Morin win against orcs and rebel drakes alike?''

'''Author:''' Elven

'''Status:''' Complete, 1.02b

'''Length:''' 3 scenarios

'''Difficulty:''' Easy/Medium

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Drakes

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=53951&start=15]

'''Note:''' Short, easy campaign with simple objectives. Features Drake Glider as leader and modified Drake Burner with cold and slowing blade.

==== Legend of the Invincibles ====

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish threat, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (5 chapters, 110 scenarios) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' Complete

'''Length:''' 200 (+8 talk-only) scenarios

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Forum:''' [//r.wesnoth.org/t32384]

'''GitHub:''' [//github.com/Dugy/Legend_of_the_Invincibles]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles|Players’ Review(s)]]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

==== A New Order ====

''The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Dunefolk mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?''

''Note: This campaign contains mature themes, some of which may be unsuitable for children.''

'''Author:''' szopen

'''Maintainers:''' nemaara (Yumi), egallager

'''Status:''' Finished

'''Version:''' [https://github.com/nemaara/A_New_Order/releases/tag/1.5.0.1 1.5.0.1] (4th version digit is only because [https://github.com/nemaara/A_New_Order/releases/tag/1.5.0 1.5.0] was mis-tagged; the plan is to go back to the semver-standard of 3 version digits for the next release)

'''Length:''' Hard to say as it is non-linear; it is advertised as having 45 scenarios, but the numbering only goes up to 30 due to some of the scenarios being alternates to one another.

'''Requirements:''' Requires BfW 1.16+. Also uses the "Akladian Music" add-on.

'''Difficulty:''' Advertised as intermediate; could be considered hard, though.

'''Style:''' Mostly Skirmish, some Large Battle

'''Faction/Era:''' mostly various human factions (including the Dunefolk), with the addition of the Akladian faction of humans

'''[//units.wesnoth.org/1.16/A_New_Order/en_US/A_New_Order.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=6486&sid=2e644284f54e65736b4f1543b7098ef9]

'''GitHub:''' [//github.com/nemaara/A_New_Order]

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

''' [http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#A_New_Order Players’ Review(s)]'''

==== The North Wind ====

''Wesnoth's army was occupied fighting Mal Ravanal in the East, but there were whisperings of an orcish attack in the north. Konrad II must send Deoran, now an experienced rider and commander, with a small band of knights to hold off the orcs....''

''This campaign features unique gameplay characteristics such as a lack of recruiting and a 24-turn time-of-day cycle.''

'''Author:''' aelius, Deusite; pyndragon

'''Status:''' WIP, 0.3.0

'''Length:''' 1 playable scenario, 6 intended

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish, Survival

'''Faction/Era:''' Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=42854]

==== The Ravagers====

'''Description:''' ''The Ravagers'' is a tale of pure revenge. A tale of justice served cold, told in a flashback-style point-of-view narrative, by a ranger in the Inn at Weldyn.
The campaign includes many new exciting gameplay features, fun mechanics such as drinking, hundreds of custom units, and many more.

'''Author:''' WhiteWolf

'''Status:''' Finished*

'''Length:''' 25 playable scenarios + 2 scene scenarios

'''Requirements:''' Akladian Music Pack, Underness Music Pack

'''Difficulty:''' Intermediate

'''Style:''' Skirmish + RPG / Flashback narrative

'''Faction/Era:''' Humans, Elves, Ravagers(dark humans)

'''[//units.wesnoth.org/1.14/The_Ravagers/en_US/The_Ravagers.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44930]

'''*Notes:''' The main storyline is complete, but there are unfinished side-missions that are still in development. The campaign is aimed to become finished with version 1.2.0.

==== Return from the Abyss ====

''After taking part to a disastrous expedition, Khafir and his men are lost and isolated from their people, thousands of miles away from home, bound by a pact sealed with a powerful dwarvish king. Help him escape from the depth of Irdya and finding his way back, in an adventure across two worlds during the rise of a sinister force in the Great Continent.''

'''Author:''' skeptical_troll

'''Status:''' finished

'''Length:''' 19 playable scenario + 10 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Dunefolk/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44545]

==== Rise of the Dunefolk ====

''Adventure of Siabbin and Helare from small village in desert, who step by step made the foundation of the Dunefolk nation. Play a stunning adventure against many enemies in different maps - from sandstorm to swampy areas and caves. Defeat powerful lich lord and train one of the best dark mages in the world of Wesnoth.''

'''Author:''' Elven

'''Status:''' Completed

'''Length:''' 11 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish, Minigames, Survival

'''Faction/Era:''' Default, Dunefolk and dark mage

'''Note:''' enjoable gameplay with every map different. Enough experience to upgrade your units.

==== The Return of the Darks ====

''The Darks are a race which left Wesnoth in the ancient times and lives on Isles in the sky. But now the Magic wich helped them to move the Isles in Sky got lost and the isles are about to fall down. Rumion an adventurer goes to Wesnoth and searchs for something that could help them.''

'''Author:''' thvk

'''Status:''' WIP

'''Length:''' 4 playable scenario + 2 story only

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Default + some self made units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=52731]

==== Secrets of the Ancients ====

''From the Journal of Ardonna of Tarrynth:''

''It's unfair that we humans must die after so few years. Though this is the natural order, we need not embrace it! The lords on the Green Isle knew how to live forever. Pursuit of that knowledge was declared illegal by King Haldric I, but I believe it is worth the risk: If I can rediscover the secrets of the ancients, not only will I cheat death, I will become a hero to the whole continent!''

'''Author:''' beetlenaut

'''Status:''' Mainlined (this is now one of the campaigns that is downloaded with Wesnoth itself)

'''Length:''' 18 playable scenarios + 3 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Undead/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=40545]

'''Walkthrough:''' [[Secrets of the Ancients Walkthrough]]

==== Swamplings ====

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Version:''' 1.2.0i

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction:''' Goblins

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41254]

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players’ Review(s)]'''

==== The Dark Hordes ====

''Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.''

'''Author:''' Circon

'''Maintainer:''' Various

'''Status:''' Incomplete/WIP

'''Length:''' 15 scenarios done so far

'''Version:''' 0.1.2

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[//units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=16576&]

==== The Tale of Vaniyera ====

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Finished 0.11.0

'''Length:''' 5 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=37880]

'''Walkthrough''' There is a video-walkthrough by the campaign maintainer that begins [https://www.youtube.com/watch?v=dGM1bjImvkI&list=PLZorLYWvUD7VIhaXxKwzO8iQANlp_TaF0 here].

'''Note:''' As of August 2014, all previous issues raised about this campaign have been addressed. If you've not played this campaign since 1.4 or 1.10, in this humble maintainers opinion, it's worth another go.

==== To Lands Unknown ====

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31799]

'''GitHub:''' [//github.com/inferno8/wesnoth-To_Lands_Unknown]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown|Players’ Review(s)]]'''

==== A Vision Blinded ====

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' Adamant14

'''Status:''' Complete, 1.0.14

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[//units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23463]

=== Eras ===

[[Category:Campaigns|*]]
[[Category:Eras|*]]

==== '''Southern nations''' ====

[[How_to_play_Southern_Nations|Everything about southern nations, including how to play series]]

==== '''War of Legends''' ====

'''Description:''' A multiplayer era focused on the Dark Irdya Campaigns. Contains 15 factions.

'''Author:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Maintainer:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Status:''' Complete, new features being added for the 1.15.x version of the add-on

'''Factions:'''

# Aragwaithi
# Windsong
# Human Alliance
# Orcish Union
# Southerners (Desert Elves)
# Outlaws
# Elementals
# Undead
# Drakes
# Dark Legion
# Sylvans
# Minotaurs
# Vampires
# Dunefolk
# Knalgan Alliance

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=30087 Development and Feedback Thread]

'''GitHub:''' [//github.com/knyghtmare/War_of_Legends]

==== Era of Magic(EoMa) ====

'''Description:''' Aiming at using the whole potential of Battle of Wesnoth's graphic engine, the Era of Magic is considered to have a most amazing special effects and attack animations in the BfW game. There are 8 playable factions with fully animated units and tons of special effects contained in the era, and the stories of them are told in the campaign "To Lands Unknown".

'''Author:''' Inferno8

'''Maintainer:''' Inferno8

'''Status:''' Finished, 3.1

'''Faction Descriptions:'''

Sky Kingdom - powerful magi of all kinds. Their knowledge allows them to cast amazing spells and summon creatures like unstopable Golems or mysterious Mus. Masters of Elements and Gurus are one of the most powerful human beings in the Era.

Al-Kamija - these proud people are good warriors and spell casters of the desert. They use magical circles and scrolls to summon amazing creatures like Jinns or elementals from other dimension called Abyss. These creatures can't be poisoned, which is a great advantage.
(The campaign "To Lands Unknown" is mainly about the story of this faction)

Tharis - fearsome Tharis faction is very dangerous especially at night. Cruel people of Tharis with their black magic and dreadful monsters like Hydra can demolish everything standing on their way. Being so powerful in attack, Tharis have no healer, so they need to push forward at all costs.

Kharos - this strange name is the name of a beautiful country ruled by prophets of light. These peaceful people are masters of defense and support. Their formations of healers and Shielders assisted by Silver Warriors, who can teleport between friendly villages, are very hard to destroy.

Barbarians - the best in hand-to-hand combat. This multi-cultural society divided into Goblins, Orcs, Cyclops and Trolls with their own advantages and disadvantages can be hard opponent, but separately they are very weak.

Runemasters - these Dwarves use runic magic and equipment and are well known of their protection against magic. The Runemasters create steam machines like Gyrocopters, Robots and even mighty Mechanical Dragons. Units from this faction are very resistant but slow.

Dark Blood Alliance - this faction is composed of agile lizards, giant frogs, wyverns swallowing enemies and salamanders, which have developed to perfection the art of disguise. At the head of the community stand shamans known for their water magic, which is used in the fight as well as in healing.

Destroyers - a terrifying undead creations consisting of civilizations long gone...

'''Version:''' 1.1.1 (February 18th, 2015)

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=20039 Development and Feedback Thread]

'''GitHub:''' [//github.com/inferno8/wesnoth-Era_of_Magic]

==== Ageless Era ====

'''Description:''' Ageless Era is a compilation of the most popular eras and factions on the add-on server. It is more an era pack than an era.

'''Author:''' mnewton1, Ravana and various

'''Maintainer:''' Ravana

'''Status:''' Finished, 4.19

'''Unit Tree:''' [//units.wesnoth.org/1.12/Ageless_Era/en_US/Ageless%20Era.html Ageless Unit Tree (for 1.12)]

'''Factions List:''' Currently there are 91 factions in the era:

Default: Loyalist, Rebels, Northerners, Undead, Knalgan Alliance, Drakes, Khalifate

Extended Era: Loyalist, Sylvans, Dwarves, Outlaws, Northerners, Undead, Chaos, Dark Elves

Archaic Era: Khthon, Phantoms, Despair, Primeval, South-Seas, Ukians, Northern Orcs

Era of Four Moons: Highlanders, Imperialists, Sea States, Darklanders, Dalefolk, Freemen, Pygmies, Whites

Era of the Future: Welkin, Brungar

BEEM: Anakes, Calidonians, Wood Warriors

Custom Factions: Yokai, Dark Legion, Desert Elves, Steelhive, Frozen

Era of Myths: Celestials, Devlings, Elementals, Therians, Vampires, The Warg, Windsong

Feudal Era: Aragwaithi, Ceresians, Clockwork Dwarves, High Elves, Orcish Khaganates

Imperial Era: Arendians, Cavernei, Issaelfr, Lavinian Legion, Marauders, Orcei Gladiatores, Sidhe

Era of Strife: Eventide, Triththa, Free Saurians, Eltireans, Minotaurs

Era of Magic: Barbarians, Dark Blood Alliance, Sky Kingdom, Kharos, Runemasters, Al-Kamija, Tharis, Destroyers

Mercenaries Era: Highlanders, Enchanters, Avians, Slavers, Mercenaries, Equestrians, Emperor's Guard, Oracles, Holy Order, The Cult, Fanatics, Tribalists, Hive, Infernai, Refugees, Blight

'''Git:''' [https://github.com/ProditorMagnus/Ageless-for-1-11 Ageless-for-1-11] and also for 1.12 and [https://github.com/ProditorMagnus/Ageless-for-1-14 1.14]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=25274 Development and Feedback Thread]

==== Imperial Era (IE) ====

'''Description:''' One of the oldest maintained user eras, the Imperial Era brings together seven different factions in a completely re-imagined setting, the world of Orbivm, a very lethal world indeed. The era contains both mainline and development versions of each faction and can be used to play five campaigns, each featuring a different race.

'''Author:''' Orbivm Project (but really Turin)

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete, 0.23

'''Faction Descriptions:'''

# Lavinian Legion - Based on the Roman Legion, the Lavinians have strong, versatile melee units in the legionaries and a range of support classes sourced from amongst the Lavinian population and various subjugated races. The legion are strong in the plains but weak when fighting in forested areas. The Lavinians are featured in "Fall of Silvium".
# Sidhe - The Sidhe are a group of forest-dwelling elves whose focus is stealth and fleet movement. Their mages are able to channel the lightning itself, and their various other units move almost as fast. The Sidhe feature in "Tale of Vaniyera".
# Marauders - Based on the Germanic peoples that eventually conquered Rome (hint, hint), the Marauders are equally as at home in the hills, forests and swamps of their homeland. Their hard-hitting melee units are practicalyl unstoppable during the night-time. The Marauders are the stars of the "Alfhelm the Wise" campaign.
# Orcei Gentorum - The orcs have been captured gladiators slaving away in the Lavinian arenas for generations.The life of an orc in Orbivm is harsh and brutal, just like the orcs themselves. The tale of the uprising of one such group of Orcs is told in "Up from Slavery".
# Cavernei - The Cavernei are a dwarvish race with similarities to the mainline Knalgans, but with a greater emphasis on the military uses of runesmithing. They get a campaign too, in "Gali's Contract"
# Issaelfr - The frost elves live on the fringes of the habitable lands of Evrosia, the main continent of Orbivm, and have become inured to difficult conditions and tuned in to their Fae natures. They don't have a campaign yet, but you could always write one.
# Arendians - The Arendians are horse-lords living on the Western steppes of Evrosia. A life of constant battle has developed a military-focused society where warriors are trained from a young age. They used to have a campaign, but it fell into disrepair a very long time ago.

'''Wiki:''' [[Orbivm]]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=37920 Development and Feedback Thread]

==== Lonely Era (LE) ====

'''Description:''' The Lonely Era is a new collection of six selected superior solitary sides with interesting and unusual abilities, traits and attributes.

It has been extensively revised and rebalanced over the last few years from the original era and the constituent factions.

'''Author:''' Atreides. Based on work by Shield, Desert_Shyde, Brilliand, Stern, Cloud, Grigistian, mikoc5, Stopsignal, The_Gnat, Minnakht.

'''Maintainer:''' Atreides

'''Status 1.16:''' Finished

'''Faction Descriptions:''' 1) Santa's Helpers are his Elves as well as animated pine trees. They are an updated faction based on the Merry Christmas Campaign. Beware of Elves bearing gifts though, the presents are very distracting. They are unique in not having standard levels, they each can gain up to 4 special abilities via AMLA but always remain at level 1. Of course there are also Flying Reindeer and Christmas Seals.

2) Gremlins are an all teleporting race of elusive ethereal creatures. Individually fragile they work together using their tremendous mobility to swarm and overwhelm their enemies. Their mages are perhaps the ultimate glass cannons but if you can somehow keep one alive long enough it might even get to level 5 and become immortal.

3) Vaeringjar are a Viking faction allied with Wolfkin. The vikings eschew ranged weapons as well as sissy ideas like dodging blows but are a very, very hardy lot. They also have a unique herbalist unit that can inspire berserker rage in adjacent vikings for a turn. The wolfkin are lithe and armed with bows and teeth on the other hand. They are also very agile in contrast to the vikings. As nocturnal hunters they are devastating at night and almost helpless in the day.

4) Avians are cold loving, water hating bipedal birds. Their hollow bones and feathers make them vulnerable to fire and blunt weapons. They are unique in having cheap level 0 healers. Unusually their leaders are not drawn from the ranks but form a separate class only selectable as leaders. Tamed Albatrosses to patrol the awful waters.

5) The Deep Ones - Slimy, slippery, blasphemous fish-frogs of the nameless design - living and horrible - have now been sighted on the edge of Wesnoth. Mutants who slowly evolve from human to monster these creatures are nothing to be trifled with! An all water faction they are quite capable of holding their own against the landlubbers.

6) Jephrifs live far up in the sky, miles above land. Away from even the most basic things most other races take for granted, such as solid ground, their society developed to be quite alien indeed. In recent times, jephrifs began descending from the skies to participate in combat against other races - apparently for their own amusement, seeing life as a game.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=42630 Development and Feedback Thread]

== Additional info ==
See also:
* [[Player_UMC_Reviews|Player UMC Reviews]]
* [[:Category:User-made Campaigns - Walkthroughs|Walkthroughs for user-made campaigns]]
* [//r.wesnoth.org/t37476 forum thread] for this page
* [[Guide_to_UMC_Content/1.12|Guide to user-made content (UMC) for Battle for Wesnoth 1.12]]
* [[Guide_to_UMC_Content/1.10|Guide to user-made content (UMC) for Battle for Wesnoth 1.10]]
* [//r.wesnoth.org/t36733 thread discussing 1.8 UMC that wasn't ported to 1.10]
* [//r.wesnoth.org/t48086 thread discussing all UMC that hasn't been ported to 1.14]
* [//addons.wesnoth.org the addon server]

EraWML

2023-01-02T02:50:18Z

Atreides: /* 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.
* '''description''': a short description 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''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
* '''disallow_scenario''': 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''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''force_modification''': a list of modification ids. The specified modifications must be enabled to play this era.
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. If ''addon_min_version'' is not explicitly specified, it means compatible only with the same version. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''hide_help''': {{DevFeature1.13|0}} whether this era should show up in the help browser or not. Default no.
* '''[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.
** '''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. Must be present. 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. All random_faction=yes factions are sorted before other factions.
** '''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. As of 1.16.2 at least this key has no effect and is not required to be present.
** '''recruit''': a comma-separated list of unit types this faction can recruit.
** '''extra_recruit''': a comma-separated list of unit types appended to the leader recruitlist (see [[SingleUnitWML]]).
** '''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.
** '''description''': a short description of the faction, displayed in the help browser.
* '''[event]''': any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See [[EventWML]].
* '''[lua]''': any [lua] children written inside the [era] tag will get included into scenarios that are played using this era.
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.
* '''[modify_unit_type]''': {{DevFeature1.15|2}} Applies minor modifications to existing unit types when this era is active. See entry in [[ModificationWML]] for list of possible attributes.

== See Also ==

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

[[Category: WML Reference]]

How to play Southern Orcs

2022-12-17T17:51:37Z

Atreides: /* Basic strategy */ fixed typos

== Alignment ==

Southern orcs are mostly neutral, in comparison to the standard orcs. Few units remain chaotic, so they are good during the night or in the underground.

== Core units ==

'''Goblin Pikeman I-II''' - Very basic and offense oriented unit, good against horsemen or drakes. Cheap and fragile.

'''Greenie Messenger''' - Level 0 unit, that can quickly get villages. Ineffective in combat. Patriarchs can upgrade their strength with their leadership.

'''Orcish Bowman I-III''' - Poison specialist, with ranged and melee poison weapons. Also have access to fire damage. Can be upgraded to orcish Crossbow and lose all the specialities, but gain very powerful single ranged attack.

'''Orcish Heavy Infantry I-IV''' - Core of the southern orcish army. With very good armor, these fighters are very strong and resilient, so enemy have to use cold or fire to kill them. Slow and expensive, but very useful to hold the line or attack. With hammers, they can smash skeletons. Pair heavy infantry with patriarchs and bowmen/crossbowmen.

'''Orcish Light Infantry I-III''' - Light fighter, that is hard to hit by non-magic enemies. Not very deadly, but fast. Maneuverable, but they are not heavy hitters. They are chaotic, stronger during the night.

'''Orcish Medium Infantry I-III''' - Almost like classic grunts, but stronger, with 2 very similar melee attacks, that helps a bit when needed. Many attacks, but weaker. Good all around unit, that is also faster than expected. No ranged attack.

'''Orcish Patriarch I-IV''' - Leader, not very strong in battle. leadership and cold damage make them a good combo with medium or heavy infantry, or with level 0 messengers. Chaotic. They can also heal +4 all units and hold the line, while other units are in the village or behind the patriarch.

== Level 2+ units ==

'''Orcish Crossbow II-III''' - Mixture between classic orcish crossbowman and dwarvish thunderers. Good when used correctly against the correct enemy.

'''Orcish Messenger I-II''' - Scout. Good resistances to fire and cold, so they can hunt down mages and dark adepts - or survive longer against them, when they block their retreat path.

== Basic strategy ==

As leader, you can use a partriarch. Generally a good unit that can help others gain experience faster. Also you can go for bowman to get access to poison early on. Another variant is light infantry, if you wish to take villages early on with leader.

Use messengers to get far villages. Do not buy too many of them, because they are not very strong. Many of your units are good in defending villages.

Many of your units are neutral, so try to use this to your advantage. During the night, try to attack with help of your patriarchs and bowmen.

Combine patriarchs (leadership, slowing, healing) with bowmen (poison) to weaken enemy. use your infantry to smash them. You do not have any mages and any weak units (with exception of level 0 scout), so you do not need to heal so much. However, at least one fifth of your army should be patriarchs.

Against special enemies, add these units:

* Anyone strong and not magic oriented should be slowed and killed by heavy hitters like heavy infantry.
* Mages can be killed with light infantry, medium infantry or messengers.
* Drakes are weak to cold, pierce and arcane. You have two options. Kill them in melee with your strong units, or slow them (patriarch) and damage them by poison (bowmen). Also crossbows are very effective.
* Elves in forests can be poisoned by your bowmen, same as dwarves in mountains. Poison is very good in most situations and not everyone dare to attack bowmen in melee combat. It means that you can have a lot of them, and still enemy will prefer attack your more melee oriented units, like classic infantry.

== Upgrading ==

High priority: patriarchs, bowmen

[[Guide_to_UMC_Content#How_to_play_for_UMC_factions|Other UMC factions gameplay]]

How to play Southern Orcs

2022-12-17T17:48:36Z

Atreides: /* Core units */ typos fixed

== Alignment ==

Southern orcs are mostly neutral, in comparison to the standard orcs. Few units remain chaotic, so they are good during the night or in the underground.

== Core units ==

'''Goblin Pikeman I-II''' - Very basic and offense oriented unit, good against horsemen or drakes. Cheap and fragile.

'''Greenie Messenger''' - Level 0 unit, that can quickly get villages. Ineffective in combat. Patriarchs can upgrade their strength with their leadership.

'''Orcish Bowman I-III''' - Poison specialist, with ranged and melee poison weapons. Also have access to fire damage. Can be upgraded to orcish Crossbow and lose all the specialities, but gain very powerful single ranged attack.

'''Orcish Heavy Infantry I-IV''' - Core of the southern orcish army. With very good armor, these fighters are very strong and resilient, so enemy have to use cold or fire to kill them. Slow and expensive, but very useful to hold the line or attack. With hammers, they can smash skeletons. Pair heavy infantry with patriarchs and bowmen/crossbowmen.

'''Orcish Light Infantry I-III''' - Light fighter, that is hard to hit by non-magic enemies. Not very deadly, but fast. Maneuverable, but they are not heavy hitters. They are chaotic, stronger during the night.

'''Orcish Medium Infantry I-III''' - Almost like classic grunts, but stronger, with 2 very similar melee attacks, that helps a bit when needed. Many attacks, but weaker. Good all around unit, that is also faster than expected. No ranged attack.

'''Orcish Patriarch I-IV''' - Leader, not very strong in battle. leadership and cold damage make them a good combo with medium or heavy infantry, or with level 0 messengers. Chaotic. They can also heal +4 all units and hold the line, while other units are in the village or behind the patriarch.

== Level 2+ units ==

'''Orcish Crossbow II-III''' - Mixture between classic orcish crossbowman and dwarvish thunderers. Good when used correctly against the correct enemy.

'''Orcish Messenger I-II''' - Scout. Good resistances to fire and cold, so they can hunt down mages and dark adepts - or survive longer against them, when they block their retreat path.

== Basic strategy ==

As leader, you can use a partriarch. Generally a good unit that can help others gain experience faster. Also you can go for bowman to get access to poison early on. Another variant is lifht infantry, if you wish to take villages early on with leader.

Use messengers to get far villages. Do not buy too much of them, because they are not very strong. Many of your units are good in defending villages.

Many of your units are neutral, so try to use this to your advantage. During the night, try to attack with help of your patriarchs and bowmen.

Combine patriarchs (leadership, slowing, healing) with bowmen (poison) to weaken enemy. use your infantry to smash them. You do not have any mages and any weak units (with exception of level 0 scout), so you do not need to heal so much. However, at least one fifth of your army should be patriarchs.

Against special enemies, add these units:

* Anyone strong and not magic oriented should be slowed and killed by heavy hitters like heavy infantry.
* Mages can be killed with light infantry, medium infantry or messengers.
* Drakes are weak to cold, pierce and arcane. You have two options. Kill them in melee with your strong units, or slow them (patriarch) and damage them by poison (bowmen). Also crossbows are very effective.
* Elves in forests can be poisoned by your bowmen, same as dwarves in mountains. Poison is very good in most situations and not everyone dare to attack bowmen in melee combat. It means that you can have a lot of them, and still enemy will prefer attack your more melee oriented units, like classic infantry.

== Upgrading ==

High priority: patriarchs, bowmen

[[Guide_to_UMC_Content#How_to_play_for_UMC_factions|Other UMC factions gameplay]]

ImagePathFunctions

2022-02-14T20:08:08Z

Atreides: /* SCALE_INTO_SHARP function */ typo

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image by a multiple of 90 degrees.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear interpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-and-paste ==

=== BLIT: Blit function ===
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== NO_TOD_SHIFT: Disabling ToD ===

{{DevFeature1.13|8}}

Can be used on terrain and item images to prevent them from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [http://shadowm.ai0867.net/projects/wesnoth-rcx Wesnoth RCX] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
[[Category:WML Reference]]

ImagePathFunctions

2022-02-14T19:33:42Z

Atreides: /* FL: Flip function */ typo

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, 1.12 and 1.14 add-on servers.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like
"units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)"
would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

== Changing the colors ==

=== BLEND: Color-blend function ===
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

=== BW: Black and White function ===
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

=== CS: Color-shift function ===
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

=== GS: Greyscale function ===
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

=== L: Lightmap color-shift function ===
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

=== NEG: Negative function ===
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

=== PAL: Palette-switch function ===
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

=== RC: Re-Color function ===
May be used to change some colors in an image. It is possible to use ''RC'' more than once on the same image, with different source palettes.

'''~RC(''' ''source color palette'' '''>''' ''destination color range'' ''')'''

==== source color palette ====
The first parameter is a set of colors, usually the magenta palette. Do not surround this parameter with quotes. The three standard palettes are:

* '''magenta''' - the 19 colors described in [[Team_Color_Shifting]]
* '''ellipse_red''' - all 255 colors with RGB value (n,0,0)
* '''flag_green''' - all 255 colors with RGB value (0,n,0)

The palette can also be given inline as a set of hexadecimal RGB values.

The named palettes are defined using the '''[[GameConfigWML#Color_Palettes|[color_palette]]]''' tag, and you can also define your own custom color palette using that tag.

Warning: the RC function will also accept (and not give a warning about) '''red''', '''green''' and any other defined '''[color_range]'''; however the set of RGB values for those aren't guaranteed. Using '''red''' instead of '''ellipse_red''' might be equivalent to the palette 030000,060000,0a0000,...,ff0000,ff0a0a,...,fff0f0.

==== destination color range ====
This is the second parameter, signifying the ID of a color range defined in the file [http://github.com/wesnoth/wesnoth/blob/master/data/core/team-colors.cfg data/core/team-colors.cfg] (or it may be a custom ID for a color range defined locally). You can also define a custom color range inline (the rgb key from [[GameConfigWML#Color_Palettes]]; note that RC does not use the fourth color for anything).

For this destination color range, using '''red''' or '''green''' makes sense.

==== Example ====
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The following example replaces a few of the '''magenta''' pixels with green ones:

misc/orb.png~RC(690039,c30074,ec008c > 007f00,00ff00,000000,000000)

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

=== SEPIA: Sepia function ===
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

=== SWAP: Channel Swap function ===
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

=== TC: Team-Color function ===
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Transformations ==

=== FL: Flip function ===
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizontally.
*if the argument list is empty, the image will only be flipped horizontally.

=== ROTATE: Rotate function ===
May be used to rotate an image by a multiple of 90 degrees.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

=== SCALE: Image-scaling function ===
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

=== SCALE_INTO function ===
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

=== SCALE_SHARP function ===

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

=== SCALE_INTO_SHARP function ===
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.

=== XBRZ function ===

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== Cut-and-paste ==

=== BLIT: Blit function ===
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

=== CROP: Crop function ===
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

=== MASK: Mask function ===
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Opacity ==

=== ADJUST_ALPHA ===

{{DevFeature1.13|?}}

Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.

'''~ADJUST_ALPHA(formula)'''.

The context object for the formula is a '''[[#CHAN:_General_function|pixel object]]'''.

=== O: Opacity modifying function ===
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

=== PLOT_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

=== WIPE_ALPHA ===

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

=== Background coloring function ===
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

== Miscellaneous ==

=== BL: Blurring function ===

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

=== CHAN: General function ===

{{DevFeature1.13|7}}

This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

'''~CHAN(formula, formula, formula)'''

The context object for each of the formulas is a '''pixel object''' with the following properties:

* '''x''', '''y''': coordinates of the pixel, from the top left
* '''u''', '''v''': {{DevFeature1.15|0}} normalized coordinates in the range [0,1]
* '''width''', '''height''': size of the image canvas
* '''red''', '''green''', '''blue''', '''alpha''': components of the pixel colour

=== NO_TOD_SHIFT: Disabling ToD ===

{{DevFeature1.13|8}}

Can be used on terrain and item images to prevent them from being affected by ToD lighting. This is in particular useful when placing unit images as items, as they will look the same as when placed as unit.

'''~NO_TOD_SHIFT()'''

=== DARKEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

=== BRIGHTEN: Removed function ===

{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

=== NOP: Null function ===

Does nothing.

'''~NOP()'''

== Creating an image file from IPFs ==

The big advantage of Image Path Functions is that they allow you to alter an image without needing a new image file. However, you can also save the result into a new image file using Wesnoth's command line option ''--render-image'.

Assuming you find a way to open your computer's terminal:
wesnoth --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" /tmp/new_image_file.png

Or on Windows:
"C:\Path\to\Battle for Wesnoth\wesnoth.exe" --render-image "units/human-peasants/ruffian.png~RC(magenta>green)~BLIT(units/human-peasants/woodsman.png~RC(magenta>lightblue),18,12)" new_image_file.png

Use cases include:
* Experimenting with Image Path Functions. If none of the images are from an add-on, adding ''--noaddons'' will speed this up.
* If a new Image Path Function is added to the development version of Wesnoth, add-ons for older Wesnoth versions can use a generated image instead.
* In case you want to use this anywhere out of Wesnoth. On a website, in Project Haldric, …
== See Also ==

* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string
* [http://shadowm.ai0867.net/projects/wesnoth-rcx Wesnoth RCX] - Tool to preview unit recoloring. Covers the effects of the [[#RC:_Re-Color_Function|RC]], [[#TC: Team-Color Function|TC]] and [[#PAL:_Palette-switch_Function|PAL]] functions.
[[Category:WML Reference]]

EventWML

2022-02-09T00:34:43Z

Atreides: /* enter_hex */

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
<syntaxhighlight lang='wml'>
name=<value>
</syntaxhighlight>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

<syntaxhighlight lang='wml'>
name=attacker misses,defender misses
</syntaxhighlight>

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed below, along with a description of when this value will cause the event to be triggered, in the [[#Predefined_Events_Without_Filters|Predefined Events Without Filters]] and [[#Predefined_Events_With_Filters|Predefined Events With Filters]] sections. Any value ''not'' listed there is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
<syntaxhighlight lang='wml'>
# The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

# This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# And now a fire_event tag is used to trigger the previously defined event. To use
# "speaker=unit" in the fired event, it's also necessary to specify the [primary_unit].
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]
</syntaxhighlight>

You can have more code after the '''[fire_event]''', which will run after the fired event has happened.
Example:
<syntaxhighlight lang='wml'>
# This is a standard recall event that triggers whenever a unit is recalled by side 1
[event]
name=recall
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

# Fire the custom event, exactly as the in recruit event
[fire_event]
name=unit_recruited
[primary_unit]
id=$unit.id
[/primary_unit]
[/fire_event]

# After that event has happened, the remaining code in this event is run
[message]
speaker=second_unit
message=_ "Glad to have you back"
[/message]
# As a result, every time side 1 recalls a unit, the recalled unit says
# "Reporting for duty!", and the leader replies "Glad to have you back"
[/event]
</syntaxhighlight>

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Removes an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, does the same as a [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] with the same id= value, and the other attributes of this event tag are ignored.

{{DevFeature1.13|0}} May be a comma separated list.

{{DevFeature1.15|7}} Prints a deprecation warning recommending to use [remove_event] instead.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution_2|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
* {{DevFeature1.13|10}} victory
* {{DevFeature1.13|10}} defeat
* {{DevFeature1.13|0}} scenario_end
The following are not synced:
* select
* preload
* victory {{DevFeature1.13|10}} local_victory
* defeat {{DevFeature1.13|10}} local_defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}
</syntaxhighlight>

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

<syntaxhighlight lang='wml'>
#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef
</syntaxhighlight>

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

<syntaxhighlight lang='wml'>
[event]
id=doubler_event
remove=yes
[/event]
</syntaxhighlight>

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Predefined Events Without Filters ==

These events do not take filter parameters (except [filter_condition] which works for all events).

=== preload ===

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' If a game is started, saved, and then reloaded, the preload event will fire two times while playing. However, it will only fire once when viewing the replay. If the preload event alters the gamestate the second time it fired while playing (when loading the saved game) then it can result in Out Of Sync errors.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

=== prestart ===

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== start ===

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

=== new turn ===

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

=== turn end ===

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

=== turn ''X'' end ===

Triggers at the end of turn ''X''.

=== side turn ===

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

=== ai turn ===

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event can break replays if it is used improperly. The ai turn event does not fire during replays. The intention is only to guide the AI to make choices (movements, attacks) which are then saved to the replay.''

=== turn refresh ===

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status. WML variable '''side_number''' holds the number of this side.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

=== turn ''X'' ===

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

=== side ''X'' turn ''Y'' ===

This event triggers at the start of turn ''Y'' of side X

=== side ''X'' turn ===

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn ''X'' ===

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side X turn Y refresh ===

This event triggers at the turn refresh for side X on turn Y

=== side ''X'' turn refresh ===

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== turn ''X'' refresh ===

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

=== side turn end ===

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

=== time over ===

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

=== enemies defeated ===

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

=== local_victory ===

In Wesnoth 1.12 and earlier, the event described here is '''victory''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_victory'''.

This event will be fired at the end of a scenario, if the player's side won. If it fires as a result of an '''[endlevel]''' tag, the event is processed before the line after the '''[endlevel]]''' tag. The event is not synchronized, as in networked mp it is possible to have different results for different players.

=== local_defeat ===

In Wesnoth 1.12 are earlier, the event described here is '''defeat''', {{DevFeature1.13|10}} in 1.14 the event described here is '''local_defeat'''.

Functions identically to '''local_victory''', except that the player's side lost.

=== victory ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''victory''' event is equivalent to 1.14's '''local_victory'''.

This event will be fired at the end of a scenario, if the game will proceed to the next scenario. In multiplayer, this means that it will fire on all players' clients, even for players who received a '''local_defeat''', as long as the game continues to the next scenario. This event is synchronized.

It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":next_level" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign.

Bug [https://github.com/wesnoth/wesnoth/issues/4667 #4667]: this event is treated as unsynchronized in replays, causing OOS reports when watching the replay.

=== defeat ===

This section describes a new event Wesnoth 1.14. In 1.12 and earlier, the '''defeat''' event is equivalent to 1.14's '''local_defeat'''.

This event will be fired at the end of a scenario, if the game resulted in a game-over other than victoriously reaching the end of a campaign (including single-scenario campaigns). Synchronization (including bug #4667) is the same as '''victory'''.

=== scenario_end ===

{{DevFeature1.13|10}} This event fires immediately after '''victory''' or '''defeat'''; it is synchronized, but is also affected by bug #4667.

Note: in 1.13.0 - 1.13.9 this event was added as a synchronized alternative to the events that are, since 1.13.10, called local_victory or local_defeat.

== Predefined Events With Filters ==

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables '''unit''' and '''second_unit''' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

=== moveto ===

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

=== sighted ===

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

=== enter_hex ===

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). In Wesnoth 1.12, the movement will be interrupted, stopping the unit where it is; this behavior can be avoided by using the {{tag|DirectActionsWML|allow_undo}} tag or `NO_INTERRUPT_NO_UNDO` macro. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

'''Note:''' At the time of writing (7ca5a0df, just before 1.13.11), if the hex is occupied then $unit contains the occupying unit, not the moving unit.

'''Note:''' At the time of writing (1.16.2), if the hex is occupied then $unit does contain the moving unit.

=== exit_hex ===

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is. {{DevFeature1.13|11}} movement is not interrupted unless the {{tag|DirectActionsWML|cancel_action}} tag is used.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

=== attack ===

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

=== attack end ===

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

=== attacker hits ===

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

=== attacker misses ===

Same as ''attacker hits'', but is triggered when the attacker misses.

=== defender hits ===

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

=== defender misses ===

Same as ''defender hits'', but is triggered when the defender misses.

=== petrified ===
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''petrifies'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

=== last breath ===

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

=== die ===

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

=== capture ===

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

=== recruit ===

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

=== prerecruit ===

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

=== recall ===

Triggers after the primary unit is recalled (by the secondary unit).

=== prerecall ===

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

=== advance ===

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

=== pre advance ===

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

=== post advance ===

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

=== select ===

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

=== menu item ''X'' ===

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== unit placed {{DevFeature1.13|3}}===

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units placed by :to_map in Lua (which is a shortcut for the above)
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit], when ''fire_event'' is set to ''yes'' (default is ''no'')
* Units moved on map with [move_unit] before {{DevFeature1.15|8}}
* Units matching the filter of [petrify], [unpetrify] or [harm_unit] before {{DevFeature1.15|8}}
* Units who receive a bonus from the feeding ability every time except the first, before {{DevFeature1.15|8}}
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

<syntaxhighlight lang='wml'>
[event]
name=last breath
[message]
speaker=second_unit
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker=unit
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]
</syntaxhighlight>

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]
</syntaxhighlight>

An equivalent way of doing this would be to create a single moveto event with a '''[filter_condition]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[filter_condition]''' statements. Using '''[if]''' tags is also an option especially if your event has '''first_time_only=yes'''.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]
</syntaxhighlight>

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

<syntaxhighlight lang='wml'>
[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no
[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]
</syntaxhighlight>

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.

<syntaxhighlight lang='wml'>
[event] # parent
name=turn 2
# delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event] # child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event] # great-grandchild
name=turn 5
{DEBUG_MSG $turn_number} # output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]
</syntaxhighlight>

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

WML Abilities

2022-01-21T02:31:27Z

Atreides: /* Blitz */ typo

Remember that you must include the WML ability code in every scenario where you intend them to work. Or include them in the unit file inside the [unit_type] tag.

Some abilities require macros from [[WML_Utilities|Utilities]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "Knockback:
When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
[/dummy]
#enddef

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_direction,knockback_target_hex}
[/then]
[/if]
[/event]

=== Charm ===

When a unit is hit with a ''charm'' attack, it instantly jumps to the attacker's side, and returns to it's original side at the beginning of that side's turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

#define CHARM FILTER WEAPON
[event]
name=attacker_hits
first_time_only=no

[filter]
{FILTER}
[/filter]

[special_filter]
weapon={WEAPON}
[/special_filter]

{STORE_UNIT_VAR x,y=$x1,$y1 side charmer_side}
{STORE_UNIT_VAR x,y=$x2,$y2 side charmed_side}

{IF_VAR charmer_side not_equals $charmed_side (
[then]
{MODIFY_UNIT x,y=$x2,$y2 variables.real_side $charmed_side}
{MODIFY_UNIT x,y=$x2,$y2 side $charmer_side}
{MODIFY_UNIT x,y=$x2,$y2 moves 1}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}

{VARIABLE_OP varname format "side_$charmed_side|_units_charmed"}
{VARIABLE $varname yes}

{CLEAR_VARIABLE varname}
[/then]
)}

{CLEAR_VARIABLE charmer_side}
{CLEAR_VARIABLE charmed_side}
[/event]

[event]
name=side turn
first_time_only=no

{VARIABLE_OP this_side_charmed to_variable "side_$side_number|_units_charmed"}

{IF_VAR this_side_charmed equals yes (
[then]
[store_unit]
[filter]
[not]
side=$side_number
[/not]
[/filter]

variable=possibly_charmed
kill=no
[/store_unit]

{FOREACH possibly_charmed i}
{VARIABLE_OP real_side format "0$possibly_charmed[$i].variables.real_side"}

{IF_VAR real_side not_equals "0" (
[then]
{IF_VAR side_number equals $possibly_charmed[$i].variables.real_side (
[then]
{CLEAR_VARIABLE possibly_charmed[$i].variables.real_side}
{VARIABLE possibly_charmed[$i].side $side_number}

[unstore_unit]
variable=possibly_charmed[$i]
find_vacant=no
[/unstore_unit]
[/then]
)}
[/then]
)}
{NEXT i}

{CLEAR_VARIABLE possibly_charmed}
[/then]
)}
[/event]
#enddef

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit that has bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

{MODIFY_UNIT x,y=$x2,$y2 moves 0}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}
[/event]
#enddef

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special sucessfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<code>#define WEAPON_SPECIAL_PICKPOCKET 
# Canned definition of the pickpocket ability to be included in a 
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
name_inactive= _ "pickpocket"
description= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
description_inactive= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
[/dummy]
[/specials]
[/attack]
# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer}
{CLEAR_VARIABLE pickpocketed}
[/event]
[+attack]
[+specials]
#enddef</code>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
<code>[gold]
side=$side_number
amount='''X'''
[/gold]</code>
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
<code>[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

<code>[event]
'''name=attack_end'''
first_time_only=no</code>

===Soultaker===

Any unit with this ability will gain an additional point of damage per strike every time it kills an enemy. Coder(s) unknown, made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=19&t=20100).

To give a unit the ability, place the following in any .cfg file loaded by the campaign or era:

#define ABILITY_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]

[/abilities]
[event]
name=die
first_time_only=no
[filter]
[not]
[wml_filter]
[status]
not_living="yes"
[/status]
[/wml_filter]
[/not]
[/filter]

[filter_second]
ability=soultaker
[/filter_second]

[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
range=melee
increase_damage=1
increase=1
[/effect]
[/object]
[/event]

[+abilities]
#enddef

And the following in the unit's [abilities] tag:

{ABILITY_SOULTAKER}

===Soultaker (weapon special)===

Unit with this weapon special will gain an additional point of damage per strike for that weapon every time it kills an enemy with this attack. Coder Ravana, made for ageless era (http://forums.wesnoth.org/viewtopic.php?f=19&t=25274) based on previous ability.

To give a unit the weapon special, load the following code:

#define WEAPON_SPECIAL_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_"Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]
[/specials]
[/attack]
[event]
name=die
first_time_only=no
id=soultaker_event
[filter]
[not]
[filter_wml]
[status]
not_living="yes"
[/status]
[/filter_wml]
[/not]
[/filter]
[filter_second_attack]
special=soultaker
[/filter_second_attack]
[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
name=$second_weapon.name
increase_damage=1
[/effect]
[/object]
[/event]
[+attack]
[+specials]
#enddef

And the following in the attack's [specials] tag:

{WEAPON_SPECIAL_SOULTAKER}

===Charm (Type 2)===

An attack special. If the attack hits, and the target is level 0 or 1, the target is converted to the attacker's side. However, if it misses, the attacker is converted to the defender's side. Maintainer is krotop, using 1.6.x syntax (and compatible with 1.7.x], made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=21&t=22539)

#define WEAPON_SPECIAL_CHARM
# Canned definition of the Charm ability to be included in a
# [specials] clause.

# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_charm
name= _ "charm"
name_inactive= _ "charm"
description= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
description_inactive= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
apply_to=opponent
[/dummy]

[/specials]
[/attack]

# event that creates a variable at the beginning of the fight to check if the attacker hit at least once by the end.
[event]
name=attack
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=no
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that shifts a unit to the other side
# if the defending unit
# - was not lvl1 or lvl0
# - and was not a recruiting unit
# - and was a not a "non-living" creature
# then :
# -> if the attacker missed all attacks, it goes to the defender side.
# -> if the attacker hit once at least, the defender goes to the attacker side.
[event]
name=attack_end
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[filter_wml]
[status]
not_living=yes
[/status]
[/filter_wml]
[/not]
[/and]
[/filter_second]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=charmer
mode=append
[/store_unit]

[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=charmed
mode=append
[/store_unit]

[if]
[variable]
name=charmer.variables.charm_has_worked
equals=no
[/variable]
[then]
[set_variable]
name=charmer.side
value=$charmed.side
[/set_variable]
[unstore_unit]
variable=charmer
text="Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
[set_variable]
name=charmed.side
value=$charmer.side
[/set_variable]
[unstore_unit]
variable=charmed
text="Charmed!"
{COLOR_HEAL}
[/unstore_unit]
[/else]
[/if]

{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}
[/event]

[+attack]
[+specials]

#enddef

== Works ==

Unit with ability ''works'' will produce 1 gold per turn.

Put this macro into you code before the last piece of code.
<pre>
#define ABILITY_WORKS
[leadership]
value=0
id=peasant_works
cumulative=no
name="works"
description= _ "Works:
This unit produces 1 gold per turn."
[/leadership]
#enddef
</pre>

Put this event into your code.
<pre>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
#your filter here... for example type=Peasant
[/filter]
variable=worker
kill=no
[/store_unit]

{FOREACH worker i}

[gold]
side=$side_number
amount=1
[/gold]
[unstore_unit]
variable=worker[$i]
text="1"
red,green,blue=255,255,0
[/unstore_unit]

{NEXT i}

{CLEAR_VARIABLE worker}
[/event]
</pre>

And give the unit the ability like this
<pre>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</pre>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have.
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name="Mind Flay"
description="When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
[/mindflay]
#enddef

Include these events into your scenario.
[event]
name=attack
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP second_unit.experience add -$hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
find_vacant=no
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
find_vacant=no
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]

Note: In dev version substitute "name=" instead of "weapon=".

== Initiative ==

Initiative is an aura ability. Much like Leadership, it affects adjacent allies but not the unit itself.

#define AURA_INITIATIVE TYPE
[dummy]
id=initiative
name= _ "initiative"
description= _ "Initiative:
Adjacent allies are granted Firststrike with all weapons."
[/dummy]
[/abilities]
[event]
name=attack
first_time_only=no

[filter]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]

{FOREACH unit.attack i}
{VARIABLE unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack
first_time_only=no

[filter_second]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter_second]

{FOREACH second_unit.attack i}
{VARIABLE second_unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter]

{FOREACH unit.attack i}
{CLEAR_VARIABLE unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter_second]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter_second]

{FOREACH second_unit.attack i}
{CLEAR_VARIABLE second_unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[+abilities]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== Blitz ==

Blitz is an aura ability. Much like Leadership, it affects adjacent allies but not the unit itself.

#define AURA_BLITZ TYPE
[dummy]
id=blitz
name= _ "blitz"
description= _ "Blitz:
Allies that start their turn adjacent to this unit are granted Skirmisher for that turn."
[/dummy]
[/abilities]
[event]
name=side turn
first_time_only=no

[store_unit]
[filter]

[wml_filter]
blitzed=1
[/wml_filter]
[/filter]
variable=blitz_refresh
[/store_unit]

{FOREACH blitz_refresh i}
{CLEAR_VARIABLE blitz_refresh[$i].abilities.skirmisher}
{VARIABLE blitz_refresh[$i].blitzed 0}
[unstore_unit]
variable=blitz_refresh[$i]
[/unstore_unit]
{NEXT i}

[store_unit]
[filter]
side=$side_number
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]
variable=blitzed
[/store_unit]

{FOREACH blitzed i}
[if]
[variable]
name=blitzed[$i].abilities.skirmisher.id
not_equals="skirmisher"
[/variable]
[then]
{VARIABLE blitzed[$i].blitzed 1}
{VARIABLE blitzed[$i].abilities.skirmisher.id skirmisher}
{VARIABLE blitzed[$i].abilities.skirmisher.name "skirmisher"}
{VARIABLE blitzed[$i].abilities.skirmisher.description "Skirmisher:
This unit is skilled in moving past enemies quickly, and ignores all enemy Zones of Control."}
[unstore_unit]
variable=blitzed[$i]
[/unstore_unit]
[/then]
[/if]
{NEXT i}
[/event]
[+abilities]
#enddef

== Immune to drain or plague or poison ==
This macro will grant immunity to drain for a unit. By changing a few specials' names and ability names, you can easily expand it for an immunity to plague or drain. This ''will not'' work properly if there is a unit with multiple weapon specials that might be affected (plague+drain, poison+plague, poison+drain, poison+drain+plague), in this case, it will grant immunity to all of them.

#define ABILITY_UNDRAINABLE
#This is the ability tagging the unit for the events. Use it as an ability.
[dummy]
id=undrainable
name= _ "undrainable"
description= _ "this unit is cannot be drained.
It will still be damaged by draining attacks, but the enemy will not gain any HP."
[/dummy]
#enddef

#define UNDRAINABLE
#Place those in every scenario (or era) where these units will appear.
#It makes the unit undead for the time of the attack (it cannot be seen),
#if the particular weapon special was used.
[event]
name=attack
first_time_only=no
[filter_attack]
special=drains
[/filter_attack]
[filter_second]
ability=undrainable
[/filter_second]
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[status]
not_living=yes
[/status]
[/modify_unit]
[/event]

[event]
name=attack_end
first_time_only=no
[filter_attack]
special=drains
[/filter_attack]
[filter_second]
ability=undrainable
[/filter_second]
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[status]
not_living=no
[/status]
[/modify_unit]
[/event]

[event]
name=attack
first_time_only=no
[filter_second_attack]
special=drain
[/filter_second_attack]
[filter]
ability=undrainable
[/filter]
[modify_unit]
[filter]
x,y=$x1,$y1
[/filter]
[status]
not_living=yes
[/status]
[/modify_unit]
[/event]

[event]
name=attack_end
first_time_only=no
[filter_second_attack]
special=drain
[/filter_second_attack]
[filter]
ability=undrainable
[/filter]
[modify_unit]
[filter]
x,y=$x1,$y1
[/filter]
[status]
not_living=no
[/status]
[/modify_unit]
[/event]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== Whirlwind Attack ==
This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it.
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
name_inactive= _ "whirlwind"
description= _ "Whirlwind: When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
description_inactive= _ "Whirlwind: When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
[/attacks]

This is the event.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=whirlwind
[/filter_attack]
{VARIABLE has_drain 0} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
{FOREACH weapon.specials.damage i}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain 1}

[/then]
[/if]
{NEXT i}
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}

[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}

[/then]
[/if]
[if]
[variable]
name=has_drain
equals=0
[/variable]
[else]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not] #Undead are undrainable
race=undead
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
{FOREACH units i}
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($units[$i].resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($units[$i].resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($units[$i].resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($units[$i].resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($units[$i].resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($units[$i].resistance.impact*$weapon.damage)"}
[/case]
[/switch]
{NEXT i}
[store_unit] #Float the healed amount over the unit, like if it had drained
[filter] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1
[/filter]
kill=no
variable=FLOATING_TEXT_temp
[/store_unit]
[unstore_unit]
variable=FLOATING_TEXT_temp
find_vacant=no
red,green,blue=0,255,0
text=$($healed_amount/200) #Operating with huge numbers because rounding is a problem
[/unstore_unit]
{CLEAR_VARIABLE FLOATING_TEXT_temp}
[heal_unit]
[filter]
x,y=$x1,&y1
[/filter]
amount=$($healed_amount/200)
animate=no
[/heal_unit]
{CLEAR_VARIABLE units}
{CLEAR_VARIABLE healed_amount}
[/else]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #If you want to use it in an era, use side=$unit.side instead
x,y=$x2,$y2
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow}
{CLEAR_VARIABLE has_poison}
{CLEAR_VARIABLE has_drain}
[/event]

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

WML Abilities

2022-01-21T02:30:39Z

Atreides: /* Initiative */ typo

Remember that you must include the WML ability code in every scenario where you intend them to work. Or include them in the unit file inside the [unit_type] tag.

Some abilities require macros from [[WML_Utilities|Utilities]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "Knockback:
When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
[/dummy]
#enddef

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_direction,knockback_target_hex}
[/then]
[/if]
[/event]

=== Charm ===

When a unit is hit with a ''charm'' attack, it instantly jumps to the attacker's side, and returns to it's original side at the beginning of that side's turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

#define CHARM FILTER WEAPON
[event]
name=attacker_hits
first_time_only=no

[filter]
{FILTER}
[/filter]

[special_filter]
weapon={WEAPON}
[/special_filter]

{STORE_UNIT_VAR x,y=$x1,$y1 side charmer_side}
{STORE_UNIT_VAR x,y=$x2,$y2 side charmed_side}

{IF_VAR charmer_side not_equals $charmed_side (
[then]
{MODIFY_UNIT x,y=$x2,$y2 variables.real_side $charmed_side}
{MODIFY_UNIT x,y=$x2,$y2 side $charmer_side}
{MODIFY_UNIT x,y=$x2,$y2 moves 1}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}

{VARIABLE_OP varname format "side_$charmed_side|_units_charmed"}
{VARIABLE $varname yes}

{CLEAR_VARIABLE varname}
[/then]
)}

{CLEAR_VARIABLE charmer_side}
{CLEAR_VARIABLE charmed_side}
[/event]

[event]
name=side turn
first_time_only=no

{VARIABLE_OP this_side_charmed to_variable "side_$side_number|_units_charmed"}

{IF_VAR this_side_charmed equals yes (
[then]
[store_unit]
[filter]
[not]
side=$side_number
[/not]
[/filter]

variable=possibly_charmed
kill=no
[/store_unit]

{FOREACH possibly_charmed i}
{VARIABLE_OP real_side format "0$possibly_charmed[$i].variables.real_side"}

{IF_VAR real_side not_equals "0" (
[then]
{IF_VAR side_number equals $possibly_charmed[$i].variables.real_side (
[then]
{CLEAR_VARIABLE possibly_charmed[$i].variables.real_side}
{VARIABLE possibly_charmed[$i].side $side_number}

[unstore_unit]
variable=possibly_charmed[$i]
find_vacant=no
[/unstore_unit]
[/then]
)}
[/then]
)}
{NEXT i}

{CLEAR_VARIABLE possibly_charmed}
[/then]
)}
[/event]
#enddef

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit that has bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

{MODIFY_UNIT x,y=$x2,$y2 moves 0}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}
[/event]
#enddef

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special sucessfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<code>#define WEAPON_SPECIAL_PICKPOCKET 
# Canned definition of the pickpocket ability to be included in a 
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
name_inactive= _ "pickpocket"
description= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
description_inactive= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
[/dummy]
[/specials]
[/attack]
# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer}
{CLEAR_VARIABLE pickpocketed}
[/event]
[+attack]
[+specials]
#enddef</code>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
<code>[gold]
side=$side_number
amount='''X'''
[/gold]</code>
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
<code>[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

<code>[event]
'''name=attack_end'''
first_time_only=no</code>

===Soultaker===

Any unit with this ability will gain an additional point of damage per strike every time it kills an enemy. Coder(s) unknown, made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=19&t=20100).

To give a unit the ability, place the following in any .cfg file loaded by the campaign or era:

#define ABILITY_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]

[/abilities]
[event]
name=die
first_time_only=no
[filter]
[not]
[wml_filter]
[status]
not_living="yes"
[/status]
[/wml_filter]
[/not]
[/filter]

[filter_second]
ability=soultaker
[/filter_second]

[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
range=melee
increase_damage=1
increase=1
[/effect]
[/object]
[/event]

[+abilities]
#enddef

And the following in the unit's [abilities] tag:

{ABILITY_SOULTAKER}

===Soultaker (weapon special)===

Unit with this weapon special will gain an additional point of damage per strike for that weapon every time it kills an enemy with this attack. Coder Ravana, made for ageless era (http://forums.wesnoth.org/viewtopic.php?f=19&t=25274) based on previous ability.

To give a unit the weapon special, load the following code:

#define WEAPON_SPECIAL_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_"Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]
[/specials]
[/attack]
[event]
name=die
first_time_only=no
id=soultaker_event
[filter]
[not]
[filter_wml]
[status]
not_living="yes"
[/status]
[/filter_wml]
[/not]
[/filter]
[filter_second_attack]
special=soultaker
[/filter_second_attack]
[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
name=$second_weapon.name
increase_damage=1
[/effect]
[/object]
[/event]
[+attack]
[+specials]
#enddef

And the following in the attack's [specials] tag:

{WEAPON_SPECIAL_SOULTAKER}

===Charm (Type 2)===

An attack special. If the attack hits, and the target is level 0 or 1, the target is converted to the attacker's side. However, if it misses, the attacker is converted to the defender's side. Maintainer is krotop, using 1.6.x syntax (and compatible with 1.7.x], made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=21&t=22539)

#define WEAPON_SPECIAL_CHARM
# Canned definition of the Charm ability to be included in a
# [specials] clause.

# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_charm
name= _ "charm"
name_inactive= _ "charm"
description= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
description_inactive= _ "Charm :
Turns a living level 1 or level 0 unit to your side. Beware if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an ennemy leader or a non-living creature."
apply_to=opponent
[/dummy]

[/specials]
[/attack]

# event that creates a variable at the beginning of the fight to check if the attacker hit at least once by the end.
[event]
name=attack
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=no
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]

{CLEAR_VARIABLE unit_att_with_charm}
[/event]

# event that shifts a unit to the other side
# if the defending unit
# - was not lvl1 or lvl0
# - and was not a recruiting unit
# - and was a not a "non-living" creature
# then :
# -> if the attacker missed all attacks, it goes to the defender side.
# -> if the attacker hit once at least, the defender goes to the attacker side.
[event]
name=attack_end
first_time_only=no

[filter_attack]
special=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[filter_wml]
[status]
not_living=yes
[/status]
[/filter_wml]
[/not]
[/and]
[/filter_second]

[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=charmer
mode=append
[/store_unit]

[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=charmed
mode=append
[/store_unit]

[if]
[variable]
name=charmer.variables.charm_has_worked
equals=no
[/variable]
[then]
[set_variable]
name=charmer.side
value=$charmed.side
[/set_variable]
[unstore_unit]
variable=charmer
text="Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
[set_variable]
name=charmed.side
value=$charmer.side
[/set_variable]
[unstore_unit]
variable=charmed
text="Charmed!"
{COLOR_HEAL}
[/unstore_unit]
[/else]
[/if]

{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}
[/event]

[+attack]
[+specials]

#enddef

== Works ==

Unit with ability ''works'' will produce 1 gold per turn.

Put this macro into you code before the last piece of code.
<pre>
#define ABILITY_WORKS
[leadership]
value=0
id=peasant_works
cumulative=no
name="works"
description= _ "Works:
This unit produces 1 gold per turn."
[/leadership]
#enddef
</pre>

Put this event into your code.
<pre>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
#your filter here... for example type=Peasant
[/filter]
variable=worker
kill=no
[/store_unit]

{FOREACH worker i}

[gold]
side=$side_number
amount=1
[/gold]
[unstore_unit]
variable=worker[$i]
text="1"
red,green,blue=255,255,0
[/unstore_unit]

{NEXT i}

{CLEAR_VARIABLE worker}
[/event]
</pre>

And give the unit the ability like this
<pre>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</pre>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have.
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name="Mind Flay"
description="When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
[/mindflay]
#enddef

Include these events into your scenario.
[event]
name=attack
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP second_unit.experience add -$hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
find_vacant=no
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
find_vacant=no
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]

Note: In dev version substitute "name=" instead of "weapon=".

== Initiative ==

Initiative is an aura ability. Much like Leadership, it affects adjacent allies but not the unit itself.

#define AURA_INITIATIVE TYPE
[dummy]
id=initiative
name= _ "initiative"
description= _ "Initiative:
Adjacent allies are granted Firststrike with all weapons."
[/dummy]
[/abilities]
[event]
name=attack
first_time_only=no

[filter]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]

{FOREACH unit.attack i}
{VARIABLE unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack
first_time_only=no

[filter_second]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter_second]

{FOREACH second_unit.attack i}
{VARIABLE second_unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter]

{FOREACH unit.attack i}
{CLEAR_VARIABLE unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no

[filter_second]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter_second]

{FOREACH second_unit.attack i}
{CLEAR_VARIABLE second_unit.attack[$i].specials.firststrike}
{NEXT i}

[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[+abilities]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== Blitz ==

Blitz is an aura ability. Much like Leadership, it effects adjacent allies but not the unit itself.

#define AURA_BLITZ TYPE
[dummy]
id=blitz
name= _ "blitz"
description= _ "Blitz:
Allies that start their turn adjacent to this unit are granted Skirmisher for that turn."
[/dummy]
[/abilities]
[event]
name=side turn
first_time_only=no

[store_unit]
[filter]

[wml_filter]
blitzed=1
[/wml_filter]
[/filter]
variable=blitz_refresh
[/store_unit]

{FOREACH blitz_refresh i}
{CLEAR_VARIABLE blitz_refresh[$i].abilities.skirmisher}
{VARIABLE blitz_refresh[$i].blitzed 0}
[unstore_unit]
variable=blitz_refresh[$i]
[/unstore_unit]
{NEXT i}

[store_unit]
[filter]
side=$side_number
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]
variable=blitzed
[/store_unit]

{FOREACH blitzed i}
[if]
[variable]
name=blitzed[$i].abilities.skirmisher.id
not_equals="skirmisher"
[/variable]
[then]
{VARIABLE blitzed[$i].blitzed 1}
{VARIABLE blitzed[$i].abilities.skirmisher.id skirmisher}
{VARIABLE blitzed[$i].abilities.skirmisher.name "skirmisher"}
{VARIABLE blitzed[$i].abilities.skirmisher.description "Skirmisher:
This unit is skilled in moving past enemies quickly, and ignores all enemy Zones of Control."}
[unstore_unit]
variable=blitzed[$i]
[/unstore_unit]
[/then]
[/if]
{NEXT i}
[/event]
[+abilities]
#enddef

== Immune to drain or plague or poison ==
This macro will grant immunity to drain for a unit. By changing a few specials' names and ability names, you can easily expand it for an immunity to plague or drain. This ''will not'' work properly if there is a unit with multiple weapon specials that might be affected (plague+drain, poison+plague, poison+drain, poison+drain+plague), in this case, it will grant immunity to all of them.

#define ABILITY_UNDRAINABLE
#This is the ability tagging the unit for the events. Use it as an ability.
[dummy]
id=undrainable
name= _ "undrainable"
description= _ "this unit is cannot be drained.
It will still be damaged by draining attacks, but the enemy will not gain any HP."
[/dummy]
#enddef

#define UNDRAINABLE
#Place those in every scenario (or era) where these units will appear.
#It makes the unit undead for the time of the attack (it cannot be seen),
#if the particular weapon special was used.
[event]
name=attack
first_time_only=no
[filter_attack]
special=drains
[/filter_attack]
[filter_second]
ability=undrainable
[/filter_second]
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[status]
not_living=yes
[/status]
[/modify_unit]
[/event]

[event]
name=attack_end
first_time_only=no
[filter_attack]
special=drains
[/filter_attack]
[filter_second]
ability=undrainable
[/filter_second]
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[status]
not_living=no
[/status]
[/modify_unit]
[/event]

[event]
name=attack
first_time_only=no
[filter_second_attack]
special=drain
[/filter_second_attack]
[filter]
ability=undrainable
[/filter]
[modify_unit]
[filter]
x,y=$x1,$y1
[/filter]
[status]
not_living=yes
[/status]
[/modify_unit]
[/event]

[event]
name=attack_end
first_time_only=no
[filter_second_attack]
special=drain
[/filter_second_attack]
[filter]
ability=undrainable
[/filter]
[modify_unit]
[filter]
x,y=$x1,$y1
[/filter]
[status]
not_living=no
[/status]
[/modify_unit]
[/event]
#enddef

A WML filter may be added instead of the type if you want some units of that type to not have the ability.

== Whirlwind Attack ==
This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it.
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
name_inactive= _ "whirlwind"
description= _ "Whirlwind: When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
description_inactive= _ "Whirlwind: When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
[/attacks]

This is the event.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special=whirlwind
[/filter_attack]
{VARIABLE has_drain 0} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
{FOREACH weapon.specials.damage i}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain 1}

[/then]
[/if]
{NEXT i}
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}

[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}

[/then]
[/if]
[if]
[variable]
name=has_drain
equals=0
[/variable]
[else]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not] #Undead are undrainable
race=undead
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
{FOREACH units i}
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($units[$i].resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($units[$i].resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($units[$i].resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($units[$i].resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($units[$i].resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($units[$i].resistance.impact*$weapon.damage)"}
[/case]
[/switch]
{NEXT i}
[store_unit] #Float the healed amount over the unit, like if it had drained
[filter] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1
[/filter]
kill=no
variable=FLOATING_TEXT_temp
[/store_unit]
[unstore_unit]
variable=FLOATING_TEXT_temp
find_vacant=no
red,green,blue=0,255,0
text=$($healed_amount/200) #Operating with huge numbers because rounding is a problem
[/unstore_unit]
{CLEAR_VARIABLE FLOATING_TEXT_temp}
[heal_unit]
[filter]
x,y=$x1,&y1
[/filter]
amount=$($healed_amount/200)
animate=no
[/heal_unit]
{CLEAR_VARIABLE units}
{CLEAR_VARIABLE healed_amount}
[/else]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #If you want to use it in an era, use side=$unit.side instead
x,y=$x2,$y2
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow}
{CLEAR_VARIABLE has_poison}
{CLEAR_VARIABLE has_drain}
[/event]

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

AbilitiesWML

2021-12-09T02:44:31Z

Atreides: /* Common keys and tags for every weapon special */

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} A tag matching a [[#The_.5Bspecials.5D_tag|weapon special tag]], [damage] for example, will confer that weapon special to units based on the given conditions. Most weapon specials are supported; however, '''plagues''', '''heal_on_hit''', and '''swarm''' are not.
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do not precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified.
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* '''[affect_adjacent]''': an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. This value '''must''' be set in order for [resistance] to function.
* '''add''': adds to resistance.
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''[filter_weapon]''': If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': If present, the leadership ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''max_value''': the maximum percentage bonus given.
* '''min_value''': the minimum percentage bonus given.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the tunnel tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* '''[filter_weapon]''': If present, the ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': If present, the ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': If present, the ability only takes effect on units matching this filter.
* Other keys and tags appropriate to the specific weapon special

=== Macros for common abilities ===

* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon
* '''[berserk]''': pushes the attack for more than one combat round
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
* '''[damage]''': modifies the damage of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other name is valid, but will result in an special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* '''[filter_self]''': the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* '''[filter_opponent]''': the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* '''[filter_attacker]''': the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* '''[filter_defender]''' the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value.
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

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

[[Category:WML Reference]]

AbilitiesWML

2021-11-07T16:00:14Z

Atreides: /* The [abilities] tag */

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials, but by convention only one weapon special should be assigned to any given attack.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} A tag matching a [[#The_.5Bspecials.5D_tag|weapon special tag]], [damage] for example, will confer that weapon special to units based on the given conditions. Most weapon specials are supported; however, '''plagues''', '''heal_on_hit''', and '''swarm''' are not.
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do not precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified.
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* '''[affect_adjacent]''': an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. This value '''must''' be set in order for [resistance] to function.
* '''add''': adds to resistance.
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''[filter_weapon]''': If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': If present, the leadership ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': {{DevFeature1.15|0}} If present, the ability only takes effect on units matching this filter.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''max_value''': the maximum percentage bonus given.
* '''min_value''': the minimum percentage bonus given.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the tunnel tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* '''[filter_weapon]''': If present, the ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': If present, the ability only takes effect when the opponent uses a matching weapon.
* '''[filter_student]''': If present, the ability only takes effect on units matching this filter.
* Other keys and tags appropriate to the specific weapon special

=== Macros for common abilities ===

* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon
* '''[berserk]''': pushes the attack for more than one combat round
* '''[chance_to_hit]''': modifies the chance to hit of a weapon
* '''[damage]''': modifies the damage of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other name is valid, but will result in an special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* '''[filter_self]''': the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* '''[filter_opponent]''': the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* '''[filter_attacker]''': the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* '''[filter_defender]''' the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value.
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

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

[[Category:WML Reference]]

Guide to UMC Content

2021-08-30T00:52:11Z

Atreides: /* Lonely Era (LE) */

This is a guide to the current user-made content for players. It provides unfamiliar players with detailed information about campaigns (including story, completion, difficulty and playing style) as well as detailed information about eras. Feel free to edit this guide, it is a wiki.

This list covers add-ons for the latest (1.14) release of Wesnoth. There are archived versions of this page for [[Guide_to_UMC_Content/1.10|1.10]] and [[Guide_to_UMC_Content/1.12|1.12]].

For content creators who loved an add-on that hasn't been added to 1.14 yet, and are wondering about taking it over, please ensure that its entry on the older (1.12 or 1.10) wiki page is up to date, add a link to the add-on's feedback thread in the forums, and generally do the tidy-up that doesn't need you to start changing the campaign, and then ask the old maintainer. (You should probably also wait until the end of May 2018 before assuming that a maintainer isn't already porting to 1.14).

If you are looking for even more campaigns, please see the links in at the bottom of this page.

== Instructions ==
When adding a campaign to the list, please place it in its alphabetically sorted location, ignoring any initial article ("A", "An", or "The").

=== Blueprint for Campaigns ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status:
** Broken = Does not work at all
** Incomplete = Partially written, no progress
** WIP = Partially written, some progress
** Complete = Completely written, but buggy as well as potential balance issues.
** Finished = Completely written, minimal to no bugs, slight balance issues possible.

* Version campaign version on the add-ons server

* Length:

* Requirements: (only if needed)

* Difficulty:

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

** Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erratically from one scenario to the next and only people using the debug mode have seen the final, then it is.
** Easy
** Normal
** Hard

Please note: If you didn't play the campaign, write the difficulty written on the add-ons server.

* Style:

Please note: Many campaigns will feature more than one style. Please list the most significant ones. If you don't know which style is the campaign you are listing, don't write this.

** Skirmish = small to medium sized armies, your standard Wesnoth gameplay
** Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
** RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
** Survival = being exposed to changing, spawning enemies while remaining on the same map
** Large Battle = large number of units on the battlefield, sizely maps
** Simulation = campaigns feat. terrain modification, alternative resources
** Boss battle = the challenge is to defeat a single powerful enemy unit
** Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

* Faction/Era: Era for the whole campaign and more specifically the faction or unit composition you field.

* Custom units: Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

* Forum: Links to the feedback and development threads at forums.wesnoth.org

=== Blueprint for Eras ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status 1.14:
** see the list of statuses in the campaign blueprint

* Faction Descriptions: Describe your individual factions here.

* Requirements: (only if needed)

* Forum: Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.14.x ==

=== Campaigns ===

==== After the Storm ====

''Follow the journey of Galas and his band following the events of Invasion from the Unknown''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 0.10.11

'''Length:''' 3 episodes of 13 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32091]

'''GitHub:''' [//github.com/project-ethea/After_the_Storm]

'''Note:''' (vultraz) Long, very enjoyable campaign with great story. (Knyghtmare) The best UMC campaign ever!

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#After_the_Storm Players’ Review(s)]'''

====A Beastly Tale====

''When a small village is beset by troubles, its fate rests in the hands of a young woodsman and the animals he befriends.''

'''Author:''' GloccusV

'''Status:''' Complete

'''Version:''' 2.0.3

'''Length:''' 5 scenarios

'''Difficulty:''' Intermediate

'''Custom units:''' [//units.wesnoth.org/1.14/A_Beastly_Tale/en_US/A_Beastly_Tale.html Here]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41434&p=633612&hilit=A+Beastly+Tale#p579093 Here]

====A Song of the Winds====

''Every era has its heroes and heroines. Before the song of Myra, the odyssey of Akhen Wadjet and the aria of Tenma Yozora, there was the song of the winds that echoed in the mountains and halls at the heart of the Great Continent. Follow young Maat of Hiera'Shirsha and Prince Abhai of Garet-Desh in the war that set the stage for one of the greatest upheavals Irdya has ever witnessed.
(Prequel to the Dragon Trilogy)''

'''Author:''' revansurik

'''Status:''' Complete

'''Version:''' 1.0.0

'''Length:''' 43 scenarios (some of them dialogue-only)

'''Difficulty:''' Intermediate

'''Custom units:''' War of Legends + Custom factions

'''Forum:''' [//https://forums.wesnoth.org/viewtopic.php?f=8&t=53913 Here]

==== Bad Moon Rising ====

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Complete 1.10.0

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31348]

'''GitHub:''' [//github.com/doofus-01/wesnoth-Bad_Moon_Rising]

==== The Black Cross of Aleron ====

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete 2.0.3

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[https://units.wesnoth.org/1.14/Black_Cross_of_Aleron/en_US/celmin-druid-siege.html Custom units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

==== Danse Macabre ====

''Macabre is a rare zombie who has intelligence and will. What's he like? What's his purpose?''

'''Author:''' kamikaze

'''Maintainer:''' James_The_Invisible

'''Status:''' Completed, 1.3.2

'''Length:''' 12 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Large Battle

'''Faction/Era:''' Default, undead

'''[//units.wesnoth.org/1.14/Danse_Macabre/en_US/Danse_Macabre.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=33745]

'''Note:''' While the campaign is playable on Wesnoth 1.14 without major issues, it is (still) in need of heavy re-balancing. Sadly, for various reasons I am not able to do it in near future but patches are always welcome, preferably in form of pull requests on [https://github.com/konecnyjakub/Danse_Macabre GitHub].

==== Dawn of Thunder ====

''A young elvish fighter is send to represent the Aethenwood at the Ka'lian. The adventure turns out to be bigger then expected.''

'''Author:''' Paulomat4

'''Status:''' Incomplete (guessing, based on the discussion thread), 0.1.9.5

'''Length:''' 17 scenarios

'''Difficulty:''' Challenging

'''Style:''' Skirmish, Large Battle, RPG-elements

'''Faction/Era:''' Default, Elves, Humans

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=39512]

==== A Fiery Birth ====

''A scholar of the Great Academy journeys to the land of the drakes to discover their secret origins.''

'''Author:''' Mathbrush

'''Status:''' Complete

'''Version:''' 1.2.0

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=47861&p=623953 Here]

'''GitHub:''' [//github.com/brirush84/AFieryBirth]

==== The Final Exam ====

''Young mage Erika must find a magic book to become a true mage. But will it really be her final exam?''

'''Author:''' Elven

'''Status:''' Complete, 2.6.1

'''Length:''' 4 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23398]

'''Note:''' Short, easy campaign with varying objectives. Features female mage as leader.

==== [[FlightToFreedom|Flight to Freedom]] ====

''Flight to Freedom chronicles the story of the drake hero Malakar, and his desperate cross-country flight out of slavery.''

'''Authors:''' MadMax, Nova

'''Status:''' Complete

'''Length:''' 20 playable scenarios + 1 dialogue-only, for a total of 21

'''Version:''' 5.3.3

'''Difficulty:''' Expert

'''Style:''' Skirmish, Large Battle, Puzzle

'''Faction/Era:''' Drakes

'''Required Wesnoth version:''' 1.14+

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=1887]

'''GitHub:''' [//github.com/cooljeanius/Flight_Freedom]

==== Inky's Quest ====

''The Cuttlefish Campaign''

''Are the cuttlefish mere beasts or something more? What stories would they tell if they could speak? This story provides one possible answer. The easiest difficulty provides hints for novice players.''

'''Author:''' Telchin

'''Status:''' Complete

'''Length:''' 12 scenarios + story-only epilogue, for a total of 13

'''Version:''' 1.5.6

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Custom units (cuttlefish, tentacles, giant clams...). Enemies use both default era units and custom ones.

'''[//units.wesnoth.org/1.14/Inky_Quest/en_US/Inky_Quest.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32501]

==== Invasion from the Unknown ====

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 2.1.9

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=43309]

'''GitHub:''' [//github.com/project-ethea/Invasion_from_the_Unknown]

'''Walkthrough:''' [[IftU Walkthrough]]

''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players’ Review(s)]'''

==== Leader of the Drakes ====

''Leader of the drakes is killed. His son tries to defend homeland against the orcs. He choosed to ally with saurians, but other clans of drakes disagrees. Will fast and unexperienced Morin win against orcs and rebel drakes alike?''

'''Author:''' Elven

'''Status:''' Complete, 1.02b

'''Length:''' 3 scenarios

'''Difficulty:''' Easy/Medium

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Drakes

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=53951&start=15]

'''Note:''' Short, easy campaign with simple objectives. Features Drake Glider as leader and modified Drake Burner with cold and slowing blade.

==== Legend of the Invincibles ====

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish threat, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (5 chapters, 110 scenarios) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' Complete

'''Length:''' 200 (+8 talk-only) scenarios

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Forum:''' [//r.wesnoth.org/t32384]

'''GitHub:''' [//github.com/Dugy/Legend_of_the_Invincibles]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles|Players’ Review(s)]]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

==== A New Order ====

''The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Dunefolk mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?''

''Note: This campaign contains mature themes, some of which may be unsuitable for children.''

'''Author:''' szopen

'''Status:''' Finished

'''Version:''' 1.3.0

'''Length:''' Hard to say as it is non-linear; it is advertised as having 45 scenarios, but the numbering only goes up to 30 due to some of the scenarios being alternates to one another.

'''Requirements:''' Requires BfW 1.14+. Also uses the "Akladian Music" add-on.

'''Difficulty:''' Advertised as intermediate; could be considered hard, though.

'''Style:''' Mostly Skirmish, some Large Battle

'''Faction/Era:''' mostly various human factions (including the Dunefolk), with the addition of the Akladian faction of humans

'''[//units.wesnoth.org/1.14/A_New_Order/en_US/A_New_Order.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=6486&sid=2e644284f54e65736b4f1543b7098ef9]

'''GitHub:''' [//github.com/nemaara/A_New_Order]

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

''' [http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#A_New_Order Players’ Review(s)]'''

==== The North Wind ====

''Wesnoth's army was occupied fighting Mal Ravanal in the East, but there were whisperings of an orcish attack in the north. Konrad II must send Deoran, now an experienced rider and commander, with a small band of knights to hold off the orcs....''

''This campaign features unique gameplay characteristics such as a lack of recruiting and a 24-turn time-of-day cycle.''

'''Author:''' aelius, Deusite; pyndragon

'''Status:''' WIP, 0.3.0

'''Length:''' 1 playable scenario, 6 intended

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish, Survival

'''Faction/Era:''' Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=42854]

==== The Ravagers====

'''Description:''' ''The Ravagers'' is a tale of pure revenge. A tale of justice served cold, told in a flashback-style point-of-view narrative, by a ranger in the Inn at Weldyn.
The campaign includes many new exciting gameplay features, fun mechanics such as drinking, hundreds of custom units, and many more.

'''Author:''' WhiteWolf

'''Status:''' Finished*

'''Length:''' 25 playable scenarios + 2 scene scenarios

'''Requirements:''' Akladian Music Pack, Underness Music Pack

'''Difficulty:''' Intermediate

'''Style:''' Skirmish + RPG / Flashback narrative

'''Faction/Era:''' Humans, Elves, Ravagers(dark humans)

'''[//units.wesnoth.org/1.14/The_Ravagers/en_US/The_Ravagers.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44930]

'''*Notes:''' The main storyline is complete, but there are unfinished side-missions that are still in development. The campaign is aimed to become finished with version 1.2.0.

==== Return from the Abyss ====

''After taking part to a disastrous expedition, Khafir and his men are lost and isolated from their people, thousands of miles away from home, bound by a pact sealed with a powerful dwarvish king. Help him escape from the depth of Irdya and finding his way back, in an adventure across two worlds during the rise of a sinister force in the Great Continent.''

'''Author:''' skeptical_troll

'''Status:''' finished

'''Length:''' 19 playable scenario + 10 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Dunefolk/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44545]

==== Rise of the Dunefolk ====

''Adventure of Siabbin and Helare from small village in desert, who step by step made the foundation of the Dunefolk. Nation. Play a stunning adventure against many enemies in different maps - from sandstorm to swampy areas and caves. Defeat powerful lich lord and train one of the best dark mages in the world of Wesnoth.''

'''Author:''' Elven

'''Status:''' Completed

'''Length:''' 11 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish, Minigames, Survival

'''Faction/Era:''' Default, Dunefolk and dark mage

'''Note:''' enjoable gameplay with every map different. Enough experience to upgrade your units.

==== The Return of the Darks ====

''The Darks are a race which left Wesnoth in the ancient times and lives on Isles in the sky. But now the Magic wich helped them to move the Isles in Sky got lost and the isles are about to fall down. Rumion an adventurer goes to Wesnoth and searchs for something that could help them.''

'''Author:''' thvk

'''Status:''' WIP

'''Length:''' 4 playable scenario + 2 story only

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Default + some self made units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=52731]

==== Secrets of the Ancients ====

''From the Journal of Ardonna of Tarrynth:''

''It's unfair that we humans must die after so few years. Though this is the natural order, we need not embrace it! The lords on the Green Isle knew how to live forever. Pursuit of that knowledge was declared illegal by King Haldric I, but I believe it is worth the risk: If I can rediscover the secrets of the ancients, not only will I cheat death, I will become a hero to the whole continent!''

'''Author:''' beetlenaut

'''Status:''' Mainlined (this is now one of the campaigns that is downloaded with Wesnoth itself)

'''Length:''' 18 playable scenarios + 3 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Undead/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=40545]

'''Walkthrough:''' [[Secrets of the Ancients Walkthrough]]

==== Swamplings ====

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Version:''' 1.2.0i

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction:''' Goblins

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41254]

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players’ Review(s)]'''

==== The Dark Hordes ====

''Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.''

'''Author:''' Circon

'''Maintainer:''' Various

'''Status:''' Incomplete/WIP

'''Length:''' 15 scenarios done so far

'''Version:''' 0.1.2

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[//units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=16576&]

==== The Tale of Vaniyera ====

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Finished 0.11.0

'''Length:''' 5 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=37880]

'''Walkthrough''' There is a video-walkthrough by the campaign maintainer that begins [https://www.youtube.com/watch?v=dGM1bjImvkI&list=PLZorLYWvUD7VIhaXxKwzO8iQANlp_TaF0 here].

'''Note:''' As of August 2014, all previous issues raised about this campaign have been addressed. If you've not played this campaign since 1.4 or 1.10, in this humble maintainers opinion, it's worth another go.

==== To Lands Unknown ====

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31799]

'''GitHub:''' [//github.com/inferno8/wesnoth-To_Lands_Unknown]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown|Players’ Review(s)]]'''

==== A Vision Blinded ====

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' Adamant14

'''Status:''' Complete, 1.0.14

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[//units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23463]

=== Eras ===

[[Category:Campaigns|*]]
[[Category:Eras|*]]

==== '''War of Legends''' ====

'''Description:''' A multiplayer era focused on the Dark Irdya Campaigns. Contains 15 factions.

'''Author:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Maintainer:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Status:''' Complete, new features being added for the 1.15.x version of the add-on

'''Factions:'''

# Aragwaithi
# Windsong
# Human Alliance
# Orcish Union
# Southerners (Desert Elves)
# Outlaws
# Elementals
# Undead
# Drakes
# Dark Legion
# Sylvans
# Minotaurs
# Vampires
# Dunefolk
# Knalgan Alliance

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=30087 Development and Feedback Thread]

'''GitHub:''' [//github.com/knyghtmare/War_of_Legends]

==== Era of Magic(EoMa) ====

'''Description:''' Aiming at using the whole potential of Battle of Wesnoth's graphic engine, the Era of Magic is considered to have a most amazing special effects and attack animations in the BfW game. There are 8 playable factions with fully animated units and tons of special effects contained in the era, and the stories of them are told in the campaign "To Lands Unknown".

'''Author:''' Inferno8

'''Maintainer:''' Inferno8

'''Status:''' Finished, 3.1

'''Faction Descriptions:'''

Sky Kingdom - powerful magi of all kinds. Their knowledge allows them to cast amazing spells and summon creatures like unstopable Golems or mysterious Mus. Masters of Elements and Gurus are one of the most powerful human beings in the Era.

Al-Kamija - these proud people are good warriors and spell casters of the desert. They use magical circles and scrolls to summon amazing creatures like Jinns or elementals from other dimension called Abyss. These creatures can't be poisoned, which is a great advantage.
(The campaign "To Lands Unknown" is mainly about the story of this faction)

Tharis - fearsome Tharis faction is very dangerous especially at night. Cruel people of Tharis with their black magic and dreadful monsters like Hydra can demolish everything standing on their way. Being so powerful in attack, Tharis have no healer, so they need to push forward at all costs.

Kharos - this strange name is the name of a beautiful country ruled by prophets of light. These peaceful people are masters of defense and support. Their formations of healers and Shielders assisted by Silver Warriors, who can teleport between friendly villages, are very hard to destroy.

Barbarians - the best in hand-to-hand combat. This multi-cultural society divided into Goblins, Orcs, Cyclops and Trolls with their own advantages and disadvantages can be hard opponent, but separately they are very weak.

Runemasters - these Dwarves use runic magic and equipment and are well known of their protection against magic. The Runemasters create steam machines like Gyrocopters, Robots and even mighty Mechanical Dragons. Units from this faction are very resistant but slow.

Dark Blood Alliance - this faction is composed of agile lizards, giant frogs, wyverns swallowing enemies and salamanders, which have developed to perfection the art of disguise. At the head of the community stand shamans known for their water magic, which is used in the fight as well as in healing.

Destroyers - a terrifying undead creations consisting of civilizations long gone...

'''Version:''' 1.1.1 (February 18th, 2015)

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=20039 Development and Feedback Thread]

'''GitHub:''' [//github.com/inferno8/wesnoth-Era_of_Magic]

==== Ageless Era ====

'''Description:''' Ageless Era is a compilation of the most popular eras and factions on the add-on server. It is more an era pack than an era.

'''Author:''' mnewton1, Ravana and various

'''Maintainer:''' Ravana

'''Status:''' Finished, 4.19

'''Unit Tree:''' [//units.wesnoth.org/1.12/Ageless_Era/en_US/Ageless%20Era.html Ageless Unit Tree (for 1.12)]

'''Factions List:''' Currently there are 91 factions in the era:

Default: Loyalist, Rebels, Northerners, Undead, Knalgan Alliance, Drakes, Khalifate

Extended Era: Loyalist, Sylvans, Dwarves, Outlaws, Northerners, Undead, Chaos, Dark Elves

Archaic Era: Khthon, Phantoms, Despair, Primeval, South-Seas, Ukians, Northern Orcs

Era of Four Moons: Highlanders, Imperialists, Sea States, Darklanders, Dalefolk, Freemen, Pygmies, Whites

Era of the Future: Welkin, Brungar

BEEM: Anakes, Calidonians, Wood Warriors

Custom Factions: Yokai, Dark Legion, Desert Elves, Steelhive, Frozen

Era of Myths: Celestials, Devlings, Elementals, Therians, Vampires, The Warg, Windsong

Feudal Era: Aragwaithi, Ceresians, Clockwork Dwarves, High Elves, Orcish Khaganates

Imperial Era: Arendians, Cavernei, Issaelfr, Lavinian Legion, Marauders, Orcei Gladiatores, Sidhe

Era of Strife: Eventide, Triththa, Free Saurians, Eltireans, Minotaurs

Era of Magic: Barbarians, Dark Blood Alliance, Sky Kingdom, Kharos, Runemasters, Al-Kamija, Tharis, Destroyers

Mercenaries Era: Highlanders, Enchanters, Avians, Slavers, Mercenaries, Equestrians, Emperor's Guard, Oracles, Holy Order, The Cult, Fanatics, Tribalists, Hive, Infernai, Refugees, Blight

'''Git:''' [https://github.com/ProditorMagnus/Ageless-for-1-11 Ageless-for-1-11] and also for 1.12 and [https://github.com/ProditorMagnus/Ageless-for-1-14 1.14]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=25274 Development and Feedback Thread]

==== Imperial Era (IE) ====

'''Description:''' One of the oldest maintained user eras, the Imperial Era brings together seven different factions in a completely re-imagined setting, the world of Orbivm, a very lethal world indeed. The era contains both mainline and development versions of each faction and can be used to play five campaigns, each featuring a different race.

'''Author:''' Orbivm Project (but really Turin)

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete, 0.23

'''Faction Descriptions:'''

# Lavinian Legion - Based on the Roman Legion, the Lavinians have strong, versatile melee units in the legionaries and a range of support classes sourced from amongst the Lavinian population and various subjugated races. The legion are strong in the plains but weak when fighting in forested areas. The Lavinians are featured in "Fall of Silvium".
# Sidhe - The Sidhe are a group of forest-dwelling elves whose focus is stealth and fleet movement. Their mages are able to channel the lightning itself, and their various other units move almost as fast. The Sidhe feature in "Tale of Vaniyera".
# Marauders - Based on the Germanic peoples that eventually conquered Rome (hint, hint), the Marauders are equally as at home in the hills, forests and swamps of their homeland. Their hard-hitting melee units are practicalyl unstoppable during the night-time. The Marauders are the stars of the "Alfhelm the Wise" campaign.
# Orcei Gentorum - The orcs have been captured gladiators slaving away in the Lavinian arenas for generations.The life of an orc in Orbivm is harsh and brutal, just like the orcs themselves. The tale of the uprising of one such group of Orcs is told in "Up from Slavery".
# Cavernei - The Cavernei are a dwarvish race with similarities to the mainline Knalgans, but with a greater emphasis on the military uses of runesmithing. They get a campaign too, in "Gali's Contract"
# Issaelfr - The frost elves live on the fringes of the habitable lands of Evrosia, the main continent of Orbivm, and have become inured to difficult conditions and tuned in to their Fae natures. They don't have a campaign yet, but you could always write one.
# Arendians - The Arendians are horse-lords living on the Western steppes of Evrosia. A life of constant battle has developed a military-focused society where warriors are trained from a young age. They used to have a campaign, but it fell into disrepair a very long time ago.

'''Wiki:''' [[Orbivm]]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=37920 Development and Feedback Thread]

==== Lonely Era (LE) ====

'''Description:''' The Lonely Era is a collection of six selected superior solitary sides with interesting and unusual attributes.

'''Author:''' Era: Shield and Atreides. Factions: Desert_Shyde, Brilliand, Stern, Cloud, Grigistian, mikoc5, Stopsignal, The_Gnat, Minnakht.

'''Maintainer:''' Atreides

'''Status 1.14:''' Finished

'''Faction Descriptions:''' Included are:

1) Santa's Helpers are his Elves as well as animated pine trees. They are an updated faction based on the Merry Christmas Campaign. Beware of Elves bearing gifts though, the presents are very distracting. They are unique in not having standard levels, they each can gain up to 4 special abilities via AMLA but always remain at level 1. Of course there are also Flying Reindeer and Christmas Seals.

2) Gremlins are an all teleporting race of elusive ethereal creatures. Individually fragile they work together using their tremendous mobility to swarm and overwhelm their enemies. Their mages are perhaps the ultimate glass cannons but if you can somehow keep one alive long enough it might even get to level 5 and become immortal.

3) Vaeringjar are a Viking faction allied with Wolfkin. The vikings eschew ranged weapons as well as sissy ideas like dodging blows but are a very, very hardy lot. They also have a unique herbalist unit that can inspire berserker rage in adjacent vikings for a turn. The wolfkin are lithe and armed with bows and teeth on the other hand. They are also very agile in contrast to the vikings. As nocturnal hunters they are devastating at night and almost helpless in the day.

4) Avians are cold loving, water hating bipedal birds. Their hollow bones and feathers make them vulnerable to fire and blunt weapons. They are unique in having cheap level 0 healers. Unusually their leaders are not drawn from the ranks but form a separate class only selectable as leaders. Tamed Albatrosses to patrol the awful waters.

5) The Deep Ones - Slimy, slippery, blasphemous fish-frogs of the nameless design - living and horrible - have now been sighted on the edge of Wesnoth. Mutants who slowly evolve from human to monster these creatures are nothing to be trifled with! An all water faction they are still capable of holding their own against the landlubbers.

6) Jephrifs live far up in the sky, miles above land. Away from even the most basic things most other races take for granted, such as solid ground, their society developed to be quite alien indeed. In recent times, jephrifs began descending from the skies to participate in combat against other races - apparently for their own amusement, seeing life as a game.

It can be combined with the Everfell Era if both are installed.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=42630 Development and Feedback Thread]

== Additional info ==
See also:
* [[Player_UMC_Reviews|Player UMC Reviews]]
* [[:Category:User-made Campaigns - Walkthroughs|Walkthroughs for user-made campaigns]]
* [//r.wesnoth.org/t37476 forum thread] for this page
* [[Guide_to_UMC_Content/1.12|Guide to user-made content (UMC) for Battle for Wesnoth 1.12]]
* [[Guide_to_UMC_Content/1.10|Guide to user-made content (UMC) for Battle for Wesnoth 1.10]]
* [//r.wesnoth.org/t36733 thread discussing 1.8 UMC that wasn't ported to 1.10]
* [//r.wesnoth.org/t48086 thread discussing all UMC that hasn't been ported to 1.14]
* [//addons.wesnoth.org the addon server]

WML for Complete Beginners: Chapter 1

2021-05-17T01:01:14Z

Atreides: /* Attributes */ typo

{{Translations}}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensitive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
grocery_store
::as is this:
bread

::If a standard string is more than one simple identifier, it is better for it to be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to be one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll discuss Variable Manipulation in chapter 7). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level_3_tagset]
level_4_attribute=value
[/level_3_tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

DirectActionsWML

2021-05-12T03:12:58Z

Atreides: /* [terrain] */ typo

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

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

The following tags are actions:

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

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

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

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

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

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

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

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

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

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

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

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

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

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

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

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

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

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

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

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

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

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types 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. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''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''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

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

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

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

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

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

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

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

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

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

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

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

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

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

=== [petrify] ===

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

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

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) allows the item to be removed later. By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores.
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

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

=== [remove_object] ===

{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

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

Note that remove_object worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [modify_unit] to get a list of properties that can safely be changes via [modify_unit]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.

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

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

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

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

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

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

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

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

Replaces the entire map.
* '''map''': Content of a wesnoth map file. Example:
map="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

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

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

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

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

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

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

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

== 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]]

Guide to UMC Content

2021-04-18T18:38:51Z

Atreides: Appending my era

This is a guide to the current user-made content for players. It provides unfamiliar players with detailed information about campaigns (including story, completion, difficulty and playing style) as well as detailed information about eras. Feel free to edit this guide, it is a wiki.

This list covers add-ons for the latest (1.14) release of Wesnoth. There are archived versions of this page for [[Guide_to_UMC_Content/1.10|1.10]] and [[Guide_to_UMC_Content/1.12|1.12]].

For content creators who loved an add-on that hasn't been added to 1.14 yet, and are wondering about taking it over, please ensure that its entry on the older (1.12 or 1.10) wiki page is up to date, add a link to the add-on's feedback thread in the forums, and generally do the tidy-up that doesn't need you to start changing the campaign, and then ask the old maintainer. (You should probably also wait until the end of May 2018 before assuming that a maintainer isn't already porting to 1.14).

If you are looking for even more campaigns, please see the links in at the bottom of this page.

== Instructions ==
When adding a campaign to the list, please place it in its alphabetically sorted location, ignoring any initial article ("A", "An", or "The").

=== Blueprint for Campaigns ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status:
** Broken = Does not work at all
** Incomplete = Partially written, no progress
** WIP = Partially written, some progress
** Complete = Completely written, but buggy as well as potential balance issues.
** Finished = Completely written, minimal to no bugs, slight balance issues possible.

* Version campaign version on the add-ons server

* Length:

* Requirements: (only if needed)

* Difficulty:

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

** Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erratically from one scenario to the next and only people using the debug mode have seen the final, then it is.
** Easy
** Normal
** Hard

Please note: If you didn't play the campaign, write the difficulty written on the add-ons server.

* Style:

Please note: Many campaigns will feature more than one style. Please list the most significant ones. If you don't know which style is the campaign you are listing, don't write this.

** Skirmish = small to medium sized armies, your standard Wesnoth gameplay
** Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
** RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
** Survival = being exposed to changing, spawning enemies while remaining on the same map
** Large Battle = large number of units on the battlefield, sizely maps
** Simulation = campaigns feat. terrain modification, alternative resources
** Boss battle = the challenge is to defeat a single powerful enemy unit
** Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

* Faction/Era: Era for the whole campaign and more specifically the faction or unit composition you field.

* Custom units: Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

* Forum: Links to the feedback and development threads at forums.wesnoth.org

=== Blueprint for Eras ===

* Description:

* Author:

* Maintainer: if not maintained by the author anymore.

* Status 1.14:
** see the list of statuses in the campaign blueprint

* Faction Descriptions: Describe your individual factions here.

* Requirements: (only if needed)

* Forum: Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.14.x ==

=== Campaigns ===

==== After the Storm ====

''Follow the journey of Galas and his band following the events of Invasion from the Unknown''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 0.10.11

'''Length:''' 3 episodes of 13 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32091]

'''Note:''' (vultraz) Long, very enjoyable campaign with great story. (Knyghtmare) The best UMC campaign ever!

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#After_the_Storm Players’ Review(s)]'''

====A Beastly Tale====

''When a small village is beset by troubles, its fate rests in the hands of a young woodsman and the animals he befriends.''

'''Author:''' GloccusV

'''Status:''' Complete

'''Version:''' 2.0.3

'''Length:''' 5 scenarios

'''Difficulty:''' Intermediate

'''Custom units:''' [//units.wesnoth.org/1.14/A_Beastly_Tale/en_US/A_Beastly_Tale.html Here]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41434&p=633612&hilit=A+Beastly+Tale#p579093 Here]

====A Song of the Winds====

''Every era has its heroes and heroines. Before the song of Myra, the odyssey of Akhen Wadjet and the aria of Tenma Yozora, there was the song of the winds that echoed in the mountains and halls at the heart of the Great Continent. Follow young Maat of Hiera'Shirsha and Prince Abhai of Garet-Desh in the war that set the stage for one of the greatest upheavals Irdya has ever witnessed.
(Prequel to the Dragon Trilogy)''

'''Author:''' revansurik

'''Status:''' Complete

'''Version:''' 1.0.0

'''Length:''' 43 scenarios (some of them dialogue-only)

'''Difficulty:''' Intermediate

'''Custom units:''' War of Legends + Custom factions

'''Forum:''' [//https://forums.wesnoth.org/viewtopic.php?f=8&t=53913 Here]

==== Bad Moon Rising ====

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Complete 1.10.0

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31348]

==== The Black Cross of Aleron ====

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete 2.0.3

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[https://units.wesnoth.org/1.14/Black_Cross_of_Aleron/en_US/celmin-druid-siege.html Custom units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

==== Danse Macabre ====

''Macabre is a rare zombie who has intelligence and will. What's he like? What's his purpose?''

'''Author:''' kamikaze

'''Maintainer:''' James_The_Invisible

'''Status:''' Completed, 1.3.2

'''Length:''' 12 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Large Battle

'''Faction/Era:''' Default, undead

'''[//units.wesnoth.org/1.14/Danse_Macabre/en_US/Danse_Macabre.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=33745]

'''Note:''' While the campaign is playable on Wesnoth 1.14 without major issues, it is (still) in need of heavy re-balancing. Sadly, for various reasons I am not able to do it in near future but patches are always welcome, preferably in form of pull requests on [https://github.com/konecnyjakub/Danse_Macabre GitHub].

==== Dawn of Thunder ====

''A young elvish fighter is send to represent the Aethenwood at the Ka'lian. The adventure turns out to be bigger then expected.''

'''Author:''' Paulomat4

'''Status:''' Incomplete (guessing, based on the discussion thread), 0.1.9.5

'''Length:''' 17 scenarios

'''Difficulty:''' Challenging

'''Style:''' Skirmish, Large Battle, RPG-elements

'''Faction/Era:''' Default, Elves, Humans

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=39512]

==== A Fiery Birth ====

''A scholar of the Great Academy journeys to the land of the drakes to discover their secret origins.''

'''Author:''' Mathbrush

'''Status:''' Complete

'''Version:''' 1.2.0

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=47861&p=623953 Here]

==== The Final Exam ====

''Young mage Erika must find a magic book to become a true mage. But will it really be her final exam?''

'''Author:''' Elven

'''Status:''' Complete, 2.6.1

'''Length:''' 4 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23398]

'''Note:''' Short, easy campaign with varying objectives. Features female mage as leader.

==== Flight to Freedom ====

''Flight to Freedom chronicles the story of the drake hero Malakar, and his desperate cross-country flight out of slavery.''

'''Authors:''' MadMax, Nova

'''Status:''' Complete

'''Length:''' 20 playable scenarios + 1 dialogue-only, for a total of 21

'''Version:''' 5.3.2

'''Difficulty:''' Expert

'''Style:''' Skirmish, Large Battle, Puzzle

'''Faction/Era:''' Drakes

'''Required Wesnoth version:''' 1.14+

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=1887]

==== Inky's Quest ====

''The Cuttlefish Campaign''

''Are the cuttlefish mere beasts or something more? What stories would they tell if they could speak? This story provides one possible answer. The easiest difficulty provides hints for novice players.''

'''Author:''' Telchin

'''Status:''' Complete

'''Length:''' 12 scenarios + story-only epilogue, for a total of 13

'''Version:''' 1.5.6

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Custom units (cuttlefish, tentacles, giant clams...). Enemies use both default era units and custom ones.

'''[//units.wesnoth.org/1.14/Inky_Quest/en_US/Inky_Quest.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=32501]

==== Invasion from the Unknown ====

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowm/ShikadiQueen/Iris

'''Status:''' Finished, 2.1.9

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign.

'''Walkthrough:''' [[IftU Walkthrough]]

''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players’ Review(s)]'''

==== Leader of the Drakes ====

''Leader of the drakes is killed. His son tries to defend homeland against the orcs. He choosed to ally with saurians, but other clans of drakes disagrees. Will fast and unexperienced Morin win against orcs and rebel drakes alike?''

'''Author:''' Elven

'''Status:''' Complete, 1.02b

'''Length:''' 3 scenarios

'''Difficulty:''' Easy/Medium

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Default, Drakes

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=53951&start=15]

'''Note:''' Short, easy campaign with simple objectives. Features Drake Glider as leader and modified Drake Burner with cold and slowing blade.

==== Legend of the Invincibles ====

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish threat, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (5 chapters, 110 scenarios) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' Complete

'''Length:''' 200 (+8 talk-only) scenarios

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Forum:''' [//r.wesnoth.org/t32384]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles|Players’ Review(s)]]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

==== A New Order ====

''The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Dunefolk mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?''

''Note: This campaign contains mature themes, some of which may be unsuitable for children.''

'''Author:''' szopen

'''Status:''' Finished

'''Version:''' 1.2.19

'''Length:''' Hard to say as it is non-linear; it is advertised as having 45 scenarios, but the numbering only goes up to 30 due to some of the scenarios being alternates to one another.

'''Requirements:''' Requires BfW 1.14+. Also uses the "Akladian Music" add-on.

'''Difficulty:''' Advertised as intermediate; could be considered hard, though.

'''Style:''' Mostly Skirmish, some Large Battle

'''Faction/Era:''' mostly various human factions (including the Dunefolk), with the addition of the Akladian faction of humans

'''[//units.wesnoth.org/1.14/A_New_Order/en_US/A_New_Order.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=6486&sid=2e644284f54e65736b4f1543b7098ef9]

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

''' [http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#A_New_Order Players’ Review(s)]'''

==== The North Wind ====

''Wesnoth's army was occupied fighting Mal Ravanal in the East, but there were whisperings of an orcish attack in the north. Konrad II must send Deoran, now an experienced rider and commander, with a small band of knights to hold off the orcs....''

''This campaign features unique gameplay characteristics such as a lack of recruiting and a 24-turn time-of-day cycle.''

'''Author:''' aelius, Deusite; pyndragon

'''Status:''' WIP, 0.3.0

'''Length:''' 1 playable scenario, 6 intended

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish, Survival

'''Faction/Era:''' Loyalists

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=42854]

==== The Ravagers====

'''Description:''' ''The Ravagers'' is a tale of pure revenge. A tale of justice served cold, told in a flashback-style point-of-view narrative, by a ranger in the Inn at Weldyn.
The campaign includes many new exciting gameplay features, fun mechanics such as drinking, hundreds of custom units, and many more.

'''Author:''' WhiteWolf

'''Status:''' Finished*

'''Length:''' 25 playable scenarios + 2 scene scenarios

'''Requirements:''' Akladian Music Pack, Underness Music Pack

'''Difficulty:''' Intermediate

'''Style:''' Skirmish + RPG / Flashback narrative

'''Faction/Era:''' Humans, Elves, Ravagers(dark humans)

'''[//units.wesnoth.org/1.14/The_Ravagers/en_US/The_Ravagers.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44930]

'''*Notes:''' The main storyline is complete, but there are unfinished side-missions that are still in development. The campaign is aimed to become finished with version 1.2.0.

==== Return from the Abyss ====

''After taking part to a disastrous expedition, Khafir and his men are lost and isolated from their people, thousands of miles away from home, bound by a pact sealed with a powerful dwarvish king. Help him escape from the depth of Irdya and finding his way back, in an adventure across two worlds during the rise of a sinister force in the Great Continent.''

'''Author:''' skeptical_troll

'''Status:''' finished

'''Length:''' 19 playable scenario + 10 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Dunefolk/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=44545]

==== The Return of the Darks ====

''The Darks are a race which left Wesnoth in the ancient times and lives on Isles in the sky. But now the Magic wich helped them to move the Isles in Sky got lost and the isles are about to fall down. Rumion an adventurer goes to Wesnoth and searchs for something that could help them.''

'''Author:''' thvk

'''Status:''' WIP

'''Length:''' 4 playable scenario + 2 story only

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Default + some self made units

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=52731]

==== Secrets of the Ancients ====

''From the Journal of Ardonna of Tarrynth:''

''It's unfair that we humans must die after so few years. Though this is the natural order, we need not embrace it! The lords on the Green Isle knew how to live forever. Pursuit of that knowledge was declared illegal by King Haldric I, but I believe it is worth the risk: If I can rediscover the secrets of the ancients, not only will I cheat death, I will become a hero to the whole continent!''

'''Author:''' beetlenaut

'''Status:''' Mainlined (this is now one of the campaigns that is downloaded with Wesnoth itself)

'''Length:''' 18 playable scenarios + 3 story only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Undead/Default

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=40545]

'''Walkthrough:''' [[Secrets of the Ancients Walkthrough]]

==== Swamplings ====

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Version:''' 1.2.0i

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction:''' Goblins

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=41254]

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players’ Review(s)]'''

==== The Dark Hordes ====

''Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.''

'''Author:''' Circon

'''Maintainer:''' Various

'''Status:''' Incomplete/WIP

'''Length:''' 15 scenarios done so far

'''Version:''' 0.1.2

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[//units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=16576&]

==== The Tale of Vaniyera ====

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Finished 0.11.0

'''Length:''' 5 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=37880]

'''Walkthrough''' There is a video-walkthrough by the campaign maintainer that begins [https://www.youtube.com/watch?v=dGM1bjImvkI&list=PLZorLYWvUD7VIhaXxKwzO8iQANlp_TaF0 here].

'''Note:''' As of August 2014, all previous issues raised about this campaign have been addressed. If you've not played this campaign since 1.4 or 1.10, in this humble maintainers opinion, it's worth another go.

==== To Lands Unknown ====

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=31799]

'''[[Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown|Players’ Review(s)]]'''

==== A Vision Blinded ====

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' Adamant14

'''Status:''' Complete, 1.0.14

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[//units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=8&t=23463]

=== Eras ===

[[Category:Campaigns|*]]
[[Category:Eras|*]]

==== '''War of Legends''' ====

'''Description:''' A multiplayer era focused on the Dark Irdya Campaigns. Contains 15 factions.

'''Author:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Maintainer:''' Tahsin Jahin Khalid (Lord-Knyghtmare)

'''Status:''' Complete, new features being added for the 1.15.x version of the add-on

'''Factions:'''

# Aragwaithi
# Windsong
# Human Alliance
# Orcish Union
# Southerners (Desert Elves)
# Outlaws
# Elementals
# Undead
# Drakes
# Dark Legion
# Sylvans
# Minotaurs
# Vampires
# Dunefolk
# Knalgan Alliance

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=30087 Development and Feedback Thread]

==== Era of Magic(EoMa) ====

'''Description:''' Aiming at using the whole potential of Battle of Wesnoth's graphic engine, the Era of Magic is considered to have a most amazing special effects and attack animations in the BfW game. There are 8 playable factions with fully animated units and tons of special effects contained in the era, and the stories of them are told in the campaign "To Lands Unknown".

'''Author:''' Inferno8

'''Maintainer:''' Inferno8

'''Status:''' Finished, 3.1

'''Faction Descriptions:'''

Sky Kingdom - powerful magi of all kinds. Their knowledge allows them to cast amazing spells and summon creatures like unstopable Golems or mysterious Mus. Masters of Elements and Gurus are one of the most powerful human beings in the Era.

Al-Kamija - these proud people are good warriors and spell casters of the desert. They use magical circles and scrolls to summon amazing creatures like Jinns or elementals from other dimension called Abyss. These creatures can't be poisoned, which is a great advantage.
(The campaign "To Lands Unknown" is mainly about the story of this faction)

Tharis - fearsome Tharis faction is very dangerous especially at night. Cruel people of Tharis with their black magic and dreadful monsters like Hydra can demolish everything standing on their way. Being so powerful in attack, Tharis have no healer, so they need to push forward at all costs.

Kharos - this strange name is the name of a beautiful country ruled by prophets of light. These peaceful people are masters of defense and support. Their formations of healers and Shielders assisted by Silver Warriors, who can teleport between friendly villages, are very hard to destroy.

Barbarians - the best in hand-to-hand combat. This multi-cultural society divided into Goblins, Orcs, Cyclops and Trolls with their own advantages and disadvantages can be hard opponent, but separately they are very weak.

Runemasters - these Dwarves use runic magic and equipment and are well known of their protection against magic. The Runemasters create steam machines like Gyrocopters, Robots and even mighty Mechanical Dragons. Units from this faction are very resistant but slow.

Dark Blood Alliance - this faction is composed of agile lizards, giant frogs, wyverns swallowing enemies and salamanders, which have developed to perfection the art of disguise. At the head of the community stand shamans known for their water magic, which is used in the fight as well as in healing.

Destroyers - a terrifying undead creations consisting of civilizations long gone...

'''Version:''' 1.1.1 (February 18th, 2015)

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=20039 Development and Feedback Thread]

==== Ageless Era ====

'''Description:''' Ageless Era is a compilation of the most popular eras and factions on the add-on server. It is more an era pack than an era.

'''Author:''' mnewton1, Ravana and various

'''Maintainer:''' Ravana

'''Status:''' Finished, 4.19

'''Unit Tree:''' [//units.wesnoth.org/1.12/Ageless_Era/en_US/Ageless%20Era.html Ageless Unit Tree (for 1.12)]

'''Factions List:''' Currently there are 91 factions in the era:

Default: Loyalist, Rebels, Northerners, Undead, Knalgan Alliance, Drakes, Khalifate

Extended Era: Loyalist, Sylvans, Dwarves, Outlaws, Northerners, Undead, Chaos, Dark Elves

Archaic Era: Khthon, Phantoms, Despair, Primeval, South-Seas, Ukians, Northern Orcs

Era of Four Moons: Highlanders, Imperialists, Sea States, Darklanders, Dalefolk, Freemen, Pygmies, Whites

Era of the Future: Welkin, Brungar

BEEM: Anakes, Calidonians, Wood Warriors

Custom Factions: Yokai, Dark Legion, Desert Elves, Steelhive, Frozen

Era of Myths: Celestials, Devlings, Elementals, Therians, Vampires, The Warg, Windsong

Feudal Era: Aragwaithi, Ceresians, Clockwork Dwarves, High Elves, Orcish Khaganates

Imperial Era: Arendians, Cavernei, Issaelfr, Lavinian Legion, Marauders, Orcei Gladiatores, Sidhe

Era of Strife: Eventide, Triththa, Free Saurians, Eltireans, Minotaurs

Era of Magic: Barbarians, Dark Blood Alliance, Sky Kingdom, Kharos, Runemasters, Al-Kamija, Tharis, Destroyers

Mercenaries Era: Highlanders, Enchanters, Avians, Slavers, Mercenaries, Equestrians, Emperor's Guard, Oracles, Holy Order, The Cult, Fanatics, Tribalists, Hive, Infernai, Refugees, Blight

'''Git:''' [https://github.com/ProditorMagnus/Ageless-for-1-11 Ageless-for-1-11] and also for 1.12 and 1.14

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?f=19&t=25274 Development and Feedback Thread]

==== Imperial Era (IE) ====

'''Description:''' One of the oldest maintained user eras, the Imperial Era brings together seven different factions in a completely re-imagined setting, the world of Orbivm, a very lethal world indeed. The era contains both mainline and development versions of each faction and can be used to play five campaigns, each featuring a different race.

'''Author:''' Orbivm Project (but really Turin)

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete, 0.23

'''Faction Descriptions:'''

# Lavinian Legion - Based on the Roman Legion, the Lavinians have strong, versatile melee units in the legionaries and a range of support classes sourced from amongst the Lavinian population and various subjugated races. The legion are strong in the plains but weak when fighting in forested areas. The Lavinians are featured in "Fall of Silvium".
# Sidhe - The Sidhe are a group of forest-dwelling elves whose focus is stealth and fleet movement. Their mages are able to channel the lightning itself, and their various other units move almost as fast. The Sidhe feature in "Tale of Vaniyera".
# Marauders - Based on the Germanic peoples that eventually conquered Rome (hint, hint), the Marauders are equally as at home in the hills, forests and swamps of their homeland. Their hard-hitting melee units are practicalyl unstoppable during the night-time. The Marauders are the stars of the "Alfhelm the Wise" campaign.
# Orcei Gentorum - The orcs have been captured gladiators slaving away in the Lavinian arenas for generations.The life of an orc in Orbivm is harsh and brutal, just like the orcs themselves. The tale of the uprising of one such group of Orcs is told in "Up from Slavery".
# Cavernei - The Cavernei are a dwarvish race with similarities to the mainline Knalgans, but with a greater emphasis on the military uses of runesmithing. They get a campaign too, in "Gali's Contract"
# Issaelfr - The frost elves live on the fringes of the habitable lands of Evrosia, the main continent of Orbivm, and have become inured to difficult conditions and tuned in to their Fae natures. They don't have a campaign yet, but you could always write one.
# Arendians - The Arendians are horse-lords living on the Western steppes of Evrosia. A life of constant battle has developed a military-focused society where warriors are trained from a young age. They used to have a campaign, but it fell into disrepair a very long time ago.

'''Wiki:''' [[Orbivm]]

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=37920 Development and Feedback Thread]

==== Lonely Era (LE) ====

'''Description:''' A collection of selected solitary factions with unusual characteristics.

'''Author:''' Shield

'''Maintainer:''' Atreides

'''Status 1.14:''' Finished

'''Faction Descriptions:''' Included are:

1) Santa's Helpers are his Elves as well as animated pine trees. Beware of Elves bearing gifts though, the presents are very distracting. They are unique in not having standard levels, they each can gain up to 4 special abilities via AMLA but always remain at level 1. Of course there are also Flying Reindeer and Christmas Seals.

2) Gremlins are an all teleporting race of elusive ethereal creatures. Individually fragile they work together using their tremendous mobility to swarm and overwhelm their enemies. Their mages are perhaps the ultimate glass cannons but if you can somehow keep one alive long enough it might even get to level 5 and become immortal.

3) Vaeringjar are a Viking faction allied with Wolfkin. The vikings eschew ranged weapons as well as sissy ideas like dodging blows but are a very, very hardy lot. They also have a unique herbalist unit that can inspire berserker rage in adjacent vikings for a turn. The wolfkin are lithe and armed with bows and teeth on the other hand. They are also very agile in contrast to the vikings. As nocturnal hunters they are devastating at night and almost helpless in the day.

4) Avians are cold loving, water hating bipedal birds. Their hollow bones and feathers make them vulnerable to fire and blunt weapons. They are unique in having cheap level 0 healers. Unusually their leaders are not drawn from the ranks but form a separate class only selectable as leaders. Tamed Albatrosses to patrol the awful waters.

5) The Deep Ones - Slimy, slippery, blasphemous fish-frogs of the nameless design - living and horrible - have now been sighted on the edge of Wesnoth. Mutants who slowly evolve from human to monster these creatures are nothing to be trifled with! An all water faction they are still capable of holding their own against the landlubbers.

'''Forum:''' [//forums.wesnoth.org/viewtopic.php?t=42630 Development and Feedback Thread]

== Additional info ==
See also:
* [[Player_UMC_Reviews|Player UMC Reviews]]
* [[:Category:User-made Campaigns - Walkthroughs|Walkthroughs for user-made campaigns]]
* [//r.wesnoth.org/t37476 forum thread] for this page
* [[Guide_to_UMC_Content/1.12|Guide to user-made content (UMC) for Battle for Wesnoth 1.12]]
* [[Guide_to_UMC_Content/1.10|Guide to user-made content (UMC) for Battle for Wesnoth 1.10]]
* [//r.wesnoth.org/t36733 thread discussing 1.8 UMC that wasn't ported to 1.10]
* [//r.wesnoth.org/t48086 thread discussing all UMC that hasn't been ported to 1.14]
* [//addons.wesnoth.org the addon server]