The Battle for Wesnoth Wiki - User contributions [en]

GermanTranslationUnitNames

2026-03-26T20:04:14Z

Octalot: /* Hinweise zur Übersetzung */ Although this page has a lot of useful information, link to the unit types database for names of unit types

== Hinweise zur Übersetzung ==

Auf dieser Seite fassen wir alle wichtigen Informationen zusammen, so dass inoffizielle Erweiterungen und der offizielle Inhalt des Spiels weitestgehend synchron sind. Hier findet ihr Informationen, die für sie wichtig sind, ebenso wie bedeutende Orte oder gebräuchliche Formulierungen, die fast in jeder Kampagne vorkommen.

Die deutschen Namen der Einheitentypen sind anderswo:
* 1.18: https://units.wesnoth.org/1.18/mainline/de_DE/mainline.html
* Dev: https://units.wesnoth.org/trunk/mainline/de_DE/mainline.html

=== Generelles ===

Die Übersetzung sollte vom Stil her der Sprache des Mittelalters entsprechen. Das bedeutet beispielsweise, dass man statt "Sie" "Ihr" verwendet. Zudem müsst und solltet ihr euch nicht strikt an das Original halten. Wenn euch eine Formulierung einfällt, die euch besser gefällt, solltet ihr diese auch verwenden, solange evtl. wichtige Informationen erhalten bleiben.

=== Zeichensetzung und Ähnliches ===

Es werden die typografisch richtigen Satzzeichen verwendet:

* Anführungszeichen: »Text«, nicht "Text" oder 'Text'
* Bindestrich: normales Minuszeichen
* Gedankenstrich: "Text – Einschub", nicht "Text - Einschub" oder "Text -- Einschub" (Halb- statt Viertel-Geviertstrich)
** Im Englischen wird stattdessen der Geviertstrich benutzt (auch bekannt als "em dash", so lang wie ein m). Dabei werden dort keine Leerzeichen davor oder danach gesetzt. Im Deutschen werden um den Halbgeviertstrich (auch "en dash") Leerzeichen eingefügt.
** Für die passende Tastenkombination, siehe hier: http://de.wikipedia.org/wiki/Halbgeviertstrich#Eingabe_bei_Computersystemen_und_-programmen
* Apostroph: "Geht’s", nicht "Geht's".
* Anrede (groß- bzw. kleingeschriebene Personal-/Possessivpronomen):
** Unterhaltung im Spiel - je nach Situation und Charakter:
*** Kleinschreibung beim Duzen (richtig: "Meiner Treu, du bist ein Lump!", falsch: "Meiner Treu, Du bist ein Lump!").
*** Großschreibung beim Ihrzen (richtig: "Meiner Treu, Ihr seid ein Lump!", falsch: "Meiner Treu, ihr seid ein Lump!").
*** Ob geduzt oder geihrzt wird, sollte für die einzelnen Charaktere über die Kampagne hinweg konsistent sein.
** Wird der Spieler angesprochen:
*** Ihrzen + Großschreibung (richtig: "Bewegt Euren Anführer über die Brücke.", falsch: "Bewegt euren Anrührer über die Brücke.").
*** Niemals Siezen!
* Die vollständige (englische) Typografie-Anleitung gibt es [[Typography_Style_Guide|hier]]; Bash-Scripts zum automatisierten Anpassen der Sonderzeichen [[TranslatorShellscript|hier]].
* Das Dach"^" ist eine Übersetzerhilfe: Alles vor diesem Zeichen wird in der Übersetzung ignoriert. Beispiel: "rod of justice^Take it!" – Der zu übersetzende String heißt eigentlich nur "Take it". Damit der Bezug von "it" klar wird, spezifiziert der Programmierer, dass es sich auf "rod of justice" bezieht. Die Übersetzung könnte also sein: "Schnapp dir das Ding!".
* $Variablen müssen im übersetzten Text genau gleich sein.
* Bei formatiertem Text (z.B. <italic>text='Battle for Wesnoth'</italic>) handelt es sich um Pango Markup. Achtet darauf, dass es für jedes öffnende < bzw. ' auch ein schließendes gibt, da solche Fehler oft schwer zu finden sind. Auch zusätzliche Leerzeichen sind innerhalb einer solchen Auszeichnung beim Übersetzen nicht erlaubt – vergesst aber nicht, dass außerhalb davon zur Worttrennung i.d.R. eins dazugehört.

== Mainline (offizieller Inhalt des Spiels) ==

=== Einheiten ===

Details zum letzten Namensüberarbeitungsprojekt finden sich [[GermanTranslationNameRework|hier]].
Die Übersetzungen wurden in die Entwicklerversion eingearbeitet.

Damit niemand 'Goblin' mit 'Goblin' übersetzt oder 'Wose' mit 'Baummensch', orientiert euch bitte an folgenden Übersichten:

[http://units.wesnoth.org/trunk/mainline/de_DE/mainline.html Mainline]

[http://units.wesnoth.org/trunk/mainline/de_DE/Sceptre_of_Fire.html Das Zepter des Feuers]

[http://units.wesnoth.org/trunk/mainline/de_DE/Delfadors_Memoirs.html Delfadors Memoiren]

[http://units.wesnoth.org/trunk/mainline/de_DE/The_Rise_of_Wesnoth.html Der Aufstieg Wesnoths]

[http://units.wesnoth.org/trunk/mainline/de_DE/The_Hammer_of_Thursagan.html Der Hammer von Thursagan]

[http://units.wesnoth.org/trunk/mainline/de_DE/Heir_To_The_Throne.html Der Thronerbe]

[http://units.wesnoth.org/trunk/mainline/de_DE/Descent_into_Darkness.html Die dunklen Künste]

[https://units.wesnoth.org/trunk/mainline/de_DE/Two_Brothers.html Die Geschichte zweier Brüder]

[http://units.wesnoth.org/trunk/mainline/de_DE/LOW.html Die Legende von Wesmere]

[http://units.wesnoth.org/trunk/mainline/de_DE/The_South_Guard.html Die Südwacht]

[https://units.wesnoth.org/trunk/mainline/de_DE/An_Orcish_Incursion.html Ein Einmarsch der Orks]

[http://units.wesnoth.org/trunk/mainline/de_DE/Liberty.html Freiheit]

[https://units.wesnoth.org/trunk/mainline/de_DE/Secrets%20of%20the%20Ancients.html Geheimnisse der Alten]

[http://units.wesnoth.org/trunk/mainline/de_DE/Eastern_Invasion.html Invasion der Finsternis]

[http://units.wesnoth.org/trunk/mainline/de_DE/Son_of_the_Black-Eye.html Schwarzauges Sohn]

[http://units.wesnoth.org/trunk/mainline/de_DE/Dead_Water.html Stille Wasser]

[http://units.wesnoth.org/trunk/mainline/de_DE/Under_the_Burning_Suns.html Unter brennenden Sonnen]

[http://units.wesnoth.org/trunk/mainline/de_DE/Northern_Rebirth.html Wiedergeburt des Nordens]

=== Gruppierungen ===
==== Rassen / Ethnien ====

{| class="wikitable"
| style="width: 300px;" | Drakes
| style="width: 300px;" | Draken
|-
| Dunefolk
| Menschen (Dünenvolk)
|-
| Dwarves
| Zwerge
|-
| Elves
| Elfen
|-
| Goblins
| Kobolde
|-
| Humans
| Menschen (Wesnoth)
|-
| Khalifate*
| Menschen (Kalifat)
|-
| Merfolk, Mermen**
| Meervolk (Rasse)
Wasserleute, -männer/-frauen (Dialoge etc.)
|-
| Mechanical
| Kriegsgerät
|-
| Monsters
| Monster
|-
| Nagas
| Nagas
|-
| Ogres
| Oger
|-
| Orcs
| Orks
|-
| Saurians / Lizards
| Saurianer / Echsen
|-
| Trolls
| Trolle
|-
| Undead
| Untote
|-
| Woses
| Waldschrate
|}

'''*''' Mit Wesnoth 1.14 wurden die 'Khalifate' in 'Dunefolk' umbenannt. 
'''**''' Im englischen Text wird als Bezeichnung für die Rasse "Merfolk" statt "Mermen" bevorzugt, aber siehe: [https://github.com/wesnoth/wesnoth/issues/2940 Issue 2940].

==== Fraktionen ====
{| class="wikitable"
| style="width: 300px;" | Alliance of Darkness
| style="width: 300px;" | Allianz der Finsternis
|-
| Alliance of Light
| Allianz des Lichtes
|-
| Drakes
| Draken
|-
| Knalgan Alliance
| Knalga Allianz
|-
| Loyalists
| Loyalisten
|-
| Northerners
| Nordmannen
|-
| Rebels
| Rebellen
|-
| Undead
| Untote
|}

=== Bedeutende Orte ===
Details zur Geographie von Wesnoth sind auf der Seite [[WesnothGeography]] zu finden (nicht auf neustem Stand).
==== Gewässer / Inseln ====
{| class="wikitable"
| style="width: 300px;" | Arkan-thoria
| style="width: 300px;" | Arkan-thoria (Fluss)
|-
| Bay of Pearls
| Perlenbucht
|-
| Bilheld (isle)
| Bilheld (Insel)
|-
| Black River
| Schwarzer Fluss
|-
| Great River
| Großer Fluss
|-
| Green Isle
| Grüne Insel
|-
| Island Vrug
| Insel von Vrug
|-
| Isle of Alduin
| Insel Alduin
|-
| Lake Aelin
| Aelin-See
|-
| River Aethen
| Aethen (Fluss)
|-
| River Bork
| Bork (Fluss)
|-
| River Listra
| Listra (Fluss)
|-
| River Oumph
| Oumph (Fluss)
|-
| River Weldyn
| Weldyn (Fluss)
|-
| Shimmering Isle
| Insel des Glanzes
|-
| Sleepless Sea
| Ruheloses Meer
|-
| The Far Sea
| Das Ferne Meer
|-
| The Ford of Abez
| Furt von Abez
|-
| The Great Ocean
| Der Große Ozean
|-
| The Lake Vrug
| Vrugsee
|-
| The Three Sisters (isle)
| Die Drei Schwestern (Insel)
|}

==== Wälder ====
{| class="wikitable"
| style="width: 300px;" | Aethenwood
| style="width: 300px;" | Aethenwälder
|-
| Black Forest
| Schwarzer Wald
|-
| Forest of Thelien
| Thelien-Wald
|-
| Glyn's Forest
| Glyns Gehölz
|-
| Greenwood
| Grüner Hain
|-
| Grey Woods
| Grauer Wald
|-
| Lintanir Forest
| Lintanir-Forst
|-
| Silent Forest
| Stiller Wald
|-
| Southwood
| Südwald
|-
| Wesmere Forest
| Wesmerewälder
|-
| Oldwood (Green Isle)
| Alter Wald (Grüne Insel)
|}

==== Gebirge / Höhlen / Täler ====
{| class="wikitable"
| style="width: 300px;" | Broken Mountains (Green Isle)
| style="width: 300px;" | Splittergebirge (Grüne Insel)
|-
| Brown Hills
| Braune Hügel
|-
| Caverns of Chaincolt
| Chaincolt-Höhlen
|-
| Caves of Knalga
| Knalga
|-
| Dulatus Hills
| Dulatushügel
|-
| Estmark Hills
| Ostmarken
|-
| Gryphon Mt.
| Berg der Greifen
|-
| Heart Mountains
| Erzgebirge
|-
| Mountains of Dorth
| Dorth-Gebirge
|-
| Mountains of Haag
| Haager Berge
|-
| Mountains of Peril
| Tückische Gipfel
|-
| Mourned Hills
| Trauerhügel
|-
| Shorbear caves
| Shorbear Höhlen
|-
| The Vale (of Blossoming Trees)
| Tal der blühenden Bäume
|}

==== Sümpfe / Moore ====
{| class="wikitable"
| style="width: 300px;" | Bitter Swamp
| style="width: 300px;" | Sumpf der Tränen
|-
| Black Marshes
| Schwarzes Moor
|-
| Swamp of Dread
| Sumpf der Furcht
|-
| Swamp of Esten (Green Isle)
| Sümpfe von Esten (Grüne Insel)
|}

=== Wüsten / Ebenen ===
{| class="wikitable"
| style="width: 300px;" | Barren Plains
| style="width: 300px;" | Karge Steppe
|-
| Desert of Death
| Todeswüste
|-
| Frosty Wastes
| Frostwüste
|-
| Horse Plains
| Ebene der Pferde
|-
| North Plains
| Nördlichen Ebenen
|}

==== Städte / Dörfer / Festen ====
{| class="wikitable"
| style="width: 300px;" | Blackmore (Green Isle)
| style="width: 300px;" | Mortingen (Grüne Insel)
|-
| Blackwater Port
| Schwarzwasserhafen
|-
| Clearwater Port (Green Isle)
| Klarwasserhafen (Grüne Insel)
|-
| Dwarven Doors
| Zwergenpforte
|-
| Elensefar
| Elensefar
|-
| Dorest
| Dorest
|-
| Fort Kerlath
| Fort Kerlath
|-
| Fort Than
| Fort Than
|-
| Halstead
| Halstead (Festung)
|-
| Jeyvan's Haven (Green Isle)
| Jeyvans Rast (Grüne Insel)
|-
| Prestim
| Prestim
|-
| Saurgrath
| Saurgrath
|-
| Shorbear Hold
| Feste Shorbear
|-
| Soradoc
| Soradoc
|-
| Southbay (Green Isle)
| Südbucht (Grüne Insel)
|-
| Spellkeep
| Bannheim
|-
| Stormvale (Green Isle)
| Sturmtal (Grüne Insel)
|-
| Weldyn
| Weldyn
|}

==== Sonstige ====
{| class="wikitable"
| style="width: 300px;" | Estmark
| style="width: 300px;" | Ostmarken
|-
| Fallen Lich Point (Green Isle)
| Platz zum gefallenen Lich (Grüne Insel)
|-
| Irdya – the wide green world
| Irdya – die weite grüne Welt
|-
| Far North
| Weiter Norden
|-
| land of the Clans
| Lande der Sippen
|-
| Midlands (Green Isle)
| Mittellande (Grüne Insel)
|-
| Northlands
| Nordlande
|-
| old eastern mines
| östliche Minen
|-
| Southern / Northern Outpost
| Südlicher / Nördlicher Außenposten
|-
| the Great Continent
| der Große Kontinent
|}

=== Waffen und Gegenstände ===

==== Waffen ====
{| class="wikitable"
| style="width: 300px;" | axe
| style="width: 300px;" | Axt
|-
| ballista
| Balliste
|-
| baneblade
| Spektralklinge
|-
| battle axe
| Streitaxt
|-
| battle claws
| Kampfkralle
|-
| beak
| Schnabelhieb
|-
| buckler
| Rundschild
|-
| berserker frenzy
| Raserei
|-
| bite
| Biss
|-
| bow
| Bogen
|-
| chill tempest
| Schattenpfeile
|-
| chill wave
| Frostwelle
|-
| claws
| Klauen
|-
| cleaver
| Fleischerbeil
|-
| club
| Keule
|-
| crossbow
| Armbrust
|-
| crush
| Zermalmen
|-
| curse
| Fluch
|-
| dagger
| Dolch
|-
| dragonstaff
| Drachenstab
|-
| ensnare
| Zorn des Waldes
|-
| entangle
| Efeumantel
|-
| faerie fire
| Feenfeuer
|-
| faerie touch
| Feenhauch
|-
| fangs
| Fänge
|-
| fire claws
| Feuerklauen
|-
| fire breath
| Feueratem
|-
| fireball
| Feuerball
|-
| fist
| Faust
|-
| gossamer
| Spinnfäden
|-
| greatsword
| Krummschwert
|-
| halberd
| Hellebarde
|-
| hammer
| Hammer
|-
| hatchet
| Wurfbeil
|-
| ink
| Tinte
|-
| javelin
| Wurfspeer
|-
| jaw
| Kiefer
|-
| knife
| Messer
|-
| lance
| Lanze
|-
| lightbeam
| Heiliges Licht
|-
| lightning bolt
| Blitzschlag
|-
| longbow
| Langbogen
|-
| mace
| Streitkolben
|-
| missile
| Magiegeschoss
|-
| morning star
| Morgenstern
|-
| mud glob
| Schlammklumpen
|-
| naia touch
| Naias Berührung
|-
| net
| Netz
|-
| pike
| Pike
|-
| pincers
| Scheren
|-
| pitchfork
| Mistforke
|-
| plague staff
| Stab der Plagen
|-
| ram
| Mauerbrecher
|-
| runic hammer
| Runenhammer
|-
| sabre
| Säbel
|-
| scimitar
| Krummsäbel
|-
| shadow wave
| Schattenwelle
|-
| short sword
| Kurzschwert
|-
| slam
| Sturzflug
|-
| sling
| Schleuder
|-
| smash (Eyestalk)
| Rankenhieb (Augenranke)
|-
| spear
| Speer
|-
| staff
| Stab
|-
| sting
| Stachel
|-
| sword
| Schwert
|-
| tail
| Schwanz
|-
| tentacle
| Tentakel
|-
| thorns
| Dornen
|-
| throwing knives
| Wurfmesser
|-
| thunderstick
| Donnerstock
|-
| torch
| Fackel
|-
| touch
| Berührung
|-
| trident
| Dreizack
|-
| wail
| Klage
|-
| war blade
| Kriegsklinge
|-
| war talon
| Kriegsklaue
|-
| water spray
| Peitschende Gischt
|-
| web
| Netz
|}

==== Waffenfähigkeiten ====
{| class="wikitable"
| style="width: 300px;" | backstab
| style="width: 300px;" | Hinterlistiger Angriff
|-
| berserk
| Kampfrausch
|-
| charge
| Ansturm
|-
| daze
|
|-
| drains
| Lebensentzug
|-
| first strike
| Erstschlag
|-
| magical
| Magie
|-
| marksman
| Treffsicherheit
|-
| petrifies
| Versteinerung
|-
| plague
| Untote Plage
|-
| poison
| Gift
|-
| slows
| Verlangsamung
|-
| swarm
| Schwarm
|-
| shock
| Blitzangriff
|-
| stun
| Lähmung
|-
|}

==== Schadenstypen ====
{| class="wikitable"
| style="width: 300px;" | arcane
| style="width: 300px;" | Arkan
|-
| blade
| Klinge
|-
| cold
| Kälte
|-
| fire
| Feuer
|-
| impact
| Wucht
|-
| pierce
| Stich
|}

=== Gegenstände===
{| class="wikitable"
| style="width: 300px;" | Flaming Sword
| style="width: 300px;" | Flammenschwert
|-
| Holy Water
| Weihwasser
|-
| Poison
| Gift
|-
| Potion of Decay
| Trank des Verfalls
|-
| Potion of Healing
| Trank der Heilung
|-
| Potion of Strength
| Trank der Stärke
|-
| Ring of Regeneration
| Ring der Regeneration
|-
| Ring of Power
| Ring der Kraft
|-
| Ring of Slowness
| Ring der Langsamkeit
|-
| Rod of Justice
| Stab der Gerechtigkeit
|-
| Sceptre of Fire
| Zepter des Feuers / Feuerzepter
|-
| Staff of righteous Flame
| Stab aufflammender Gerechtigkeit
|-
| Staff of Swiftness
| Stab der Geschwindigkeit
|-
| Storm Trident
| Dreizack des Sturms
|-
| Void Armor
| Rüstung der Leere
|}

=== Charakteristiken, Fertigkeiten ===

==== Charakteristiken ====
{| class="wikitable"
| style="width: 300px;" | aged
| style="width: 300px;" | Gealtert
|-
| dextrous
| Geschickt
|-
| dim
| Tumb
|-
| elemental
| Elementar
|-
| fearless
| Furchtlos
|-
| leral
| Wild
|-
| healthy
| Vital
|-
| intelligent
| Intelligent
|-
| loyal
| Loyal
|-
| mechanical
| Mechanisch
|-
| quick
| Schnell
|-
| resilient
| Robust
|-
| slow
| Lahm
|-
| strong
| Kräftig
|-
| undead
| Untot
|-
| weak
| Schwächlich
|}

==== Fertigkeiten ====
{| class="wikitable"
| style="width: 300px;" | ambush
| style="width: 300px;" | Waldkenntnis
|-
| concealment
| Gassenwissen
|-
| cures
| Kurieren
|-
| feeding
| Kanibalismus
|-
| heals +X
| Heilen +x
|-
| illuminates
| Lichtaura
|-
| leadership
| Führungsqualitäten
|-
| nightstalk
| Schemen
|-
| regenerates
| Regeneration
|-
| skirmisher
| Plänkler
|-
| steadfast
| Unerschütterlich
|-
| submerge
| Abtauchen
|-
| teleport
| Teleportation
|-
| disengage
|
|-
| distract
| Ablenken
|-
| formation
|
|-
| initiative
| Kampfgespür
|-
| inspire
| Begeistern
|-
| support
|
|-
| teaching
|
|}

=== Gebräuchliche Formulierungen ===

==== Missionsziele ====
{| class="wikitable"
| style="width: 300px;" | Death of X (or Y)
| style="width: 300px;" | X (oder Y) fällt in der Schlacht
|-
| Turns run out
| Rundenlimit überschritten
|-
| Defeat all enemy leaders
| Besiegt alle gegnerischen Anführer
|-
| Move X to the signpost in the Y
| Führt X zum Wegweiser im Y
|-
| Move X to the sign
| Führt X zur Markierung
|-
| Early finish bonus
| Bonus für frühzeitiges Ende
|-
| Alternative objective
| Alternative Mission
|-
| Bonus objective
| Bonusmission
|-
| Optional (objective)
| Optional / Optionale Mission
|-
| Optional Scenario
| Optionales Szenario
|}

==== Schwierigkeitsgrade / Beschreibungen ====
{| class="wikitable"
| style="width: 300px;" | (Novice / Beginner level, xx scenarios.)
| style="width: 300px;" | (Einstufung: Einfach, xx Szenarien)
|-
| (Intermediate level, xx scenarios.)
| (Einstufung: Mittel, xx Szenarien)
|-
| (Expert level, xx scenarios.)
| (Einstufung: Schwierig, xx Szenarien)
|-
| Beginner
| Sehr einfach
|-
| Easy
| Einfach
|-
| Normal
| Normal
|-
| Challenging
| Herausfordernd
|-
| Difficult
| Schwierig
|-
| Nightmare
| Alptraum
|-
| X scenarios (X story-only / dialog-only)
| x Szenarien + x Erzählung / Dialog
|-
| All scenarios are playable, but there may be bugs or balancing issues
| Alle Szenarien sind spielbar, vereinzelt können aber Fehler auftreten. Auch die Abstimmung der Schwierigkeitsgrade ist noch nicht abgeschlossen.
|-
| rated PG-13 (Parental Guidance)
| USK ab 6 (Unterhaltungssoftware Selbstkontrolle)
|-
| This campaign contains mature themes, some of which may be unsuitable for children.
This campaign depicts explicit violence which may not be appropriate for younger children.
| In dieser Kampagne werden Gewaltszenen dargestellt, die besonders für Spieler im Kindesalter ungeeignet sind!
|}

==== Credits (Herausgeber, Mitarbeiter, Danksagung) ====
{| class="wikitable"
| style="width: 300px;" | And special thanks to everyone else who I forgot to mention.
| style="width: 300px;" | Und besonderen Dank an alle, die ich vergessen habe zu erwähnen.
|-
| Artwork Support
| Mitwirkung grafische Gestaltung
|-
| Artwork and Graphics Design
| Grafik
|-
| Author (of this campaign)
| Autor (der Kampagne)
|-
| Campaign Design
| Kampagnengestaltung
|-
| Campaign Epilog and Continuity
| Kampagnenepilog und -fortsetzung
|-
| Campaign Maintenance
| Betreuung
|-
| Co-author
| Mitautor
|-
| Code
| Programmierung / Kodierung
|-
| Completion, Porting and Maintenance
| Fertigstellung, Portierung und Betreuung
|-
| Conception and Original
| Design Konzeption
|-
| Contributions Images
| Beiträge Grafiken
|-
| Contributors
| Mitwirkende
|-
| Current Maintainer
| Betreuung
|-
| Custom AI Development
| Anpassung und Entwicklung KI
|-
| Forum Support and Feedback
| Support und Rückmeldung aus dem Forum
|-
| Miscellaneous
| Verschiedenes
|-
| Music Development
| Musikkomposition
|-
| Porting
| Anpassung an aktuelle BfW-Versionen / Portierung
|-
| Prose and Grammatical Assistance
| Prosatext und Sprachhilfe
|-
| Proofreading
| Korrekturlesen
|-
| Sprites and Portraits
| Grafikdateien und Portraits
|-
| Story Art
| Handlungsillustrierung
|-
| Story Development / Corrections
| Handlungsausarbeitung
|-
| Technical Adviser
| Technischer Berater
|-
| (Gameplay) Testing / Test Beta-Version
| Testspieler
|-
| Text Revision
| Textrevision
|-
| Translators / Translations
| Übersetzungen
|-
| Translation Assistance
| Übersetzungshilfe
|-
| Unit Sprites, Halo & Animation Art
| Grafikdateien, Lichteffekte und Animationen
|-
| WML / Code Contributors
| WML Code / Code-Beiträge
|-
| WML Assistance
| WML-Entwicklung
|}

==== Verschiedenes ====
{| class="wikitable"
| style="width: 300px;" | (whispered), (whispers)
| style="width: 300px;" | (geflüstert), (flüstert)
|-
| BW (Before Wesnoth)
| im Jahr x vor Wesnoth
|-
| YW (Years Wesnoth)
| im Jahre x Wesnoths (JW)
|-
| Lord / Lady
| Ehrenanrede für Titelträger des Hochadels:
Herr/Frau + Titel (Graf/Gräfin, Herzog, Baron(in) ...)
u. U. auch: Gebieter(in), Herrscher(in), Landes- / Stadtherr(in)
|-
| mylord, my lord, milord
| (gnädiger) Herr, mein Gebieter
|-
| mylady, my lady, dear lady, milady
| gnädige Dame, meine Herrin
|-
| Minister
| (Stadt)Ratsmitglied, Hofrat
|-
| AI (Artificial Intelligence)
| KI (Künstliche Intelligenz), computergesteuerte Akteure
|-
| AMLA (After Maximum Level Advancement)
| AMLA (Sonderbonus statt Stufenaufstieg)
|-
| campaign
| Kampagne
|-
| cutscene
| Zwischensequenz
|-
| era
| Epoche
|-
| faction
| Fraktion
|-
| level
| Spielabschnitt, Stufe
|-
| mission
| Mission, Aufgabe
|-
| MP (Multiplayer) mode
| Mehrspieler- / Koop-Modus
|-
| Multiplayerlobby
| Mehrspielerlobby
|-
| NPC (non-player character)
| Nicht-Spieler-Charakter (NSC), computergesteuerte Einheit
|-
| quest
| Auftrag, Suche, Jagd, Herausforderung
|-
| scenario
| Szenarium, Szenario, Partie, (Episode, Teil)
|-
| SP (single-player) mode
| Einzelspieler- / Solo-Modus
|-
| side
| Partei
|-
| team
| Allianz (Bei »Team« wäre nicht eindeutig ob Partei/Allianz)
|-
| turn
| Runde
|-
| Whiteboard
| Planungsmodus
|-
| WML (Wesnoth Markup Language)
| WML (Wesnoth Auszeichnungssprache)
|-
| ZoC / Zone of Control
| Kontrollzone (KonZ), Sicherheitszone
|}

== AddOns (inoffizielle Erweiterungen) ==

Der folgende Bereich zeigt gängige Namen/Begriffe aus Übersetzungen von Beiträgen anderer Benutzer (UMC). Damit die gleiche Einheit/Sache möglichst nicht unter verschiedenen Bezeichnungen im Umlauf ist, könnt ihr hier Bezeichnungen veröffentlichen.

=== Einheiten ===
{| class="wikitable"
| style="width: 300px;" | Abomination (LotI L4 Ghul)
| style="width: 300px;" | Widerling
|-
| Bison
| Wisent (NF)
|-
| Mosquito
| Stechmücke (S)
|-
| Saurian Haruspex (RotW)
| Saurianischer Opferpriester
|-
| Shark (BW)
| Hai
|-
| Vampire
| Vampir
|}

=== Rassen / Ethnie / Fraktionen ===
{| class="wikitable"
| style="width: 300px;" | Animal
| style="width: 300px;" | Getier
|-
| Aquatics (BW)
| Wassertiere
|-
| Carapaces (BW)
| Panzertiere
|-
| Dark Elves
| Dunkelelfen / Dunkle Elfen
|-
| Elementals
| Elementargeister / Urgeschöpfe (FoaP)
|-
| Faerie
| Feenwesen
|-
| Northern Barbarians
| Nordbarbaren
|-
| Ungulate (FoaP)
| Huftiere
|-
| Steelhive Robots
| Geschmiedete (LotI)
|}

=== Geographie ===
{| class="wikitable"
| style="width: 300px;" | Black Isle (Far Sea, TRs)
| style="width: 300px;" | Schwarze Insel (Fernes Meer)
|-
|Oxbow Swamp (RotW)
|Sumpf der stillen Wasser
|-
| Pogo Bog (S)
| Pogo Sumpf
|-
| Xaffrasz (S - Saurian city)
| Xaffrasz
|}

=== Waffen ===
{| class="wikitable"
| style="width: 300px;" | crystal fire (BW)
| style="width: 300px;" | Kristallfeuer (BW)
|-
| explosion (S)
| Explosion
|-
| horns (FoaP)
| Hörner
|-
| quarterstaff
| Kampfstab
|-
| shield
| Schild
|}

=== Waffenfähigkeiten ===
{| class="wikitable"
| style="width: 300px;" | petrifies
| style="width: 300px;" | Versteinerung
|}
=== Gegenstände ===
{| class="wikitable"
| style="width: 300px;" | armor
| style="width: 300px;" | Rüstung
|-
| altar
| Opfertisch
|-
| caravan
| Planwagen
|-
| storm orb (BW)
| Sturmkugel
|}
=== Fertigkeiten ===
{| class="wikitable"
| style="width: 300px;" | darkens
| style="width: 300px;" | Verdunkeln
|-
| invisible
| Unsichtbar
|-
| penetrate
| Unterwandern
|}
=== Charakteristiken ===
{| class="wikitable"
| style="width: 300px;" | horrid
| style="width: 300px;" | Grauenerregend
|-
| loot (S)
| Stehlen
|}

== Siehe auch ==

* [[GermanTranslation|Hauptseite für deutsche Übersetzung]]

[[Category:Translations]]

GettextForTranslators

2026-02-28T13:11:54Z

Octalot: /* Textdomains and getting the files to translate */ Use wesnoth-tsg instead of wesnoth-httt as an example

== Gettext for translators ==

=== For the engine and mainline campaigns ===

The target audience of this page is anyone who wants to help with a language that's already in the list on [[WesnothTranslations]]. The files for these languages have already been set up, someone is already the maintainer, and the pages linked from that page say where to go and how to introduce yourself to the team. The effort is split with separate teams for each language, and each team can have its own working style.

Because each team can work in different ways, please do not submit translations as pull requests on Github. While that seems like a good idea, it causes potential complications, so we ask that everyone talks to their language's maintainer and submits changes in the way that the maintainer decides to use.

If you're starting a completely new translation, or taking over as the maintainer of a translation, then the next place to read would be the [[WesnothTranslationsHowTo]] page.

=== For add-ons ===

The target audience is anyone who wants to help translate an add-on, assuming the add-on's maintainer has already set it up for translation. Translations are shipped with the add-on, so it's up to the maintainer to choose how to receive the files and organise the workflow.

To translate an add-on, skip to the [[#Files_for_add-ons|Files for add-ons]] section.

If you are the maintainer of the add-on, the instructions for setting up the translation are on [[GettextForWesnothDevelopers]].

== Textdomains and getting the files to translate ==

The progress for each language is shown on https://www.wesnoth.org/gettext/ . Click on your language, and you'll see a breakdown into sections ''(textdomains)'', such as
* wesnoth
* wesnoth-editor
* wesnoth-help
* wesnoth-units
* wesnoth-lib (contains strings shared by game and editor)
* wesnoth-tsg (The South Guard campaign)
* wesnoth-utbs (the Under the Burning Suns campaign)
* etc

Each has a separate file with a .po extension. For example, the Swedish translation has abbreviation ''sv'', and its translation of the editor's strings is in ''wesnoth-editor/sv.po''. The page on https://www.wesnoth.org/gettext/?view=langs&version=branch&lang=sv links to the current version in the main Git repository.

Although the .po files contain text, please send the complete files as email attachments (or whichever method your team uses), rather than cutting and pasting lines from the file into an email. The translated strings are
very sensitive to formatting and whitespace changes.

=== Files when running the game ===

When the game runs it will look for an .mo file, for example ''translations/sv/LC_MESSAGES/wesnoth-editor.mo''. If you want to test your text in-game and you're happy to modify your installation:

* Some .po editors can automatically generate .mo files.
* Deleting the .mo file will make the game look for ''translations/wesnoth-editor/sv.po'' instead.

However you can also send your untested .po file to the maintainer and they should check that it looks correct in-game.

=== Files for add-ons ===

This assumes the add-on has .po files rather than .mo files. The engine supports both, but only .po are editable. For example, an add-on called Son of Haldric that has a Swedish translation would likely store it in:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric'' is where all files from the add-on are stored
* ''translations/wesnoth-Son_of_Haldric'' is configured by the maintainer
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

If it's been set up for translation but hasn't yet been translated into Swedish, it may instead have a file called ''wesnoth-Son_of_Haldric.pot''. This is a template which you can copy to "sv.po", however first try opening the .pot file directly in your [[#Tools|translation tool]], as the it will likely prompt you to create a translation from the template.

After editing the file, either refresh the cache (press F5 on the title screen) or restart Wesnoth to see the changes.

Warning: files in the add-on directory will be overwritten or deleted if it's updated using the in-game Add-on Manager, so keep backups of files in a separate directory.

== How to translate ==

Now that you have the .po file to edit, it can be worked on using any of the programs listed in the [[#Tools|Tools section]]. The general preference in Wesnoth seems to be towards Poedit, but they all work on the same .po file format.

The general concept is that the GUI will show the strings in English, along with a text-box to add the translation.

=== Hints ===

In addition to the English text, most strings have some additional information which in Poedit will be shown in the bottom-right of the screen. For example, the tutorial's "... this quintain!" has "[message]: speaker=Delfador", meaning that it's [[InterfaceActionsWML#.5Bmessage.5D|said]] by the unit with id "Delfador". Sometimes the hint is less obvious, often lines will be "[message]: speaker=unit", normally meaning the unit whose move, attack, or death has triggered an event.

Some strings will have additional hints, such as "Addressing Konrad" or "Addressing Li'sar". The level of detail varies a lot between campaigns, please don't be afraid to point out when something needs to be improved.

The .po files also say which source file the string came from, in Poedit 3.4 this is found in a right-click menu (right-click on a string in the top-left pane of the GUI).

=== Carets ===

There are ambiguous strings which should be translated in a different way depending on where they appear. For example, we have "General" in the preferences as "General preferences" and we can also have "a General". These strings can have different translations for a given language, so we use "context" to solve this. The prefix only tries to give a hint about the string, and should be not translated, for example:

<syntaxhighlight lang=po>
msgid "Prefs section^General"
msgstr "General"
</syntaxhighlight>

As another example, these lines in the tutorial both have the hint "[message]: speaker=student"; they're spoken by Konrad and Li'sar respectively:
* "A quintain? You want me to fight a dummy?"
* "female^A quintain? You want me to fight a dummy?"

When an English string has a caret (the ^ symbol) in it, then everything before the first caret is removed before showing it to the player. In the translated strings, leave out everything before the caret.

These caret hints are very commonly used in Wesnoth for strings where the translation may depend on the gender of the speaker, or the person spoken to. They're also used for strings such as "Prefs section^General", where the string is the label on the "general preferences" tab, not a military rank.

If you forget to strip out the caret hint, it will be displayed to the user unless the entire string is identical to the source text. This means that it should be stripped out even if the text is otherwise identical, to avoid breaking it if it's later determined that the text needs to be changed. For example:
<syntaxhighlight lang=po>
# wrong but seems to work (shows as "Root")
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Root"
# wrong and shows as "filesystem_path_system^Wurzel"
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Wurzel"
</syntaxhighlight>

=== Warnings ===

Some editors can automatically detect inconsistencies between the English and the translated text, for example if the original ends with a full-stop and the translation ends with an exclamation mark. Poedit defaults to showing these above even the untranslated strings, but these can be false-positives - generally someone's already looked at these and decided that the translated text is better as-is.

=== Fuzzy strings ===

One of the downsides of Gettext is that spelling and grammar corrections in the English text break the link between the original and the translated text. The tools that generate .po files try to recover from this by using the old translation for the new English text, and marking the string as ''fuzzy''; in Poedit these are sorted below the completely untranslated strings, and shown with the "Needs Work" button lit along with a note about what the previous English text was.

Be wary, this mechanism can also generate incorrect suggestions. For example it may decide that "Landar left $number troops to guard the council" is a spelling correction of "Kalenz left $number troops to guard the council".

== Parts to leave untranslated ==

Some translatable strings mix text to be translated with placeholders that are handled by the engine before displaying the text to the player. The text of the placeholder needs to be left untranslated.

=== Dollar signs ===

Most placeholders start with a dollar sign (<code>$</code>), for example, <code>$number</code> or <code>$gold_amount</code>. The details are in [[VariablesWML#Variable Substitution|VariablesWML]], but for translation the general rules are:

Characters that appear in placeholders are letters, numbers, square brackets, underscores, full stops and question marks. Square brackets always appear in balanced pairs, and often enclose a secondary (nested) placeholder.

* After a dollar sign, every character in the list above is part of the placeholder.
* A space ends the placeholder, and the space is also displayed to the player.
* A vertical bar (<code>|</code>) ends the placeholder, and the vertical bar isn't displayed to the player.
* If you need to put a full stop or question mark immediately after a placeholder that doesn't end with a vertical bar, add a vertical bar to separate them. Although it's not ''always'' necessary, it ''never'' hurts to add the vertical bar to be on the safe side.
* A dollar sign at the end of the string, or directly followed by a vertical bar (<code>$|</code>), is displayed as a dollar sign.
* Obscure cases should have a hint about the string.

=== Markup ===

Some strings contain formatting markup. This comes in two styles. The most common is [[Pango formatting|Pango markup]], which is an HTML-like formatting language. The other is the custom help page markup, which looks superficially similar but is rather different, and is documented here.

Like HTML, help markup consists of tags enclosed in angle brackets (eg <code><italic></code>), with a slash added to the closing tag. The difference lies in what comes between the tags, which takes a key=value format where the value is usually enclosed in single quotes. There can be multiple key=value pairs, separated by spaces. Generally, all of that should be left untouched, with the exception of the <code>text</code> key. If you see something like <code><italic>text='some text'</italic></code>, the only part that should be translated is "some text". Or if you see <code><nowiki><ref>dst='movement' text='zones of control'</ref></nowiki></code>, then only "zones of control" should be translated, and the rest should be left untouched.

If you need to include a single quote within <code>text='...'</code>, you can add a backslash before it. However, most of the time it's preferred to use [[Typography_Style_Guide#Character_Usage_Summary|typographic punctuation]] instead.

== FAQ ==
* '''What are "Plural-forms"?'''
** Some languages have different word forms for different numbers of things (for example in English we have "1 thing" but "2 thing'''s'''"). The rules are different for different languages. You can find them [http://translate.sourceforge.net/wiki/l10n/pluralforms here].
* '''Who can I ask for further information?'''
** You can ask in [[Support|Discord or IRC]]. Ping Ivanovic in Discord's #development or IRC's #wesnoth-dev channel. If you don't like IRC, send a mail to crazy-ivanovic AT gmx DOT net, or pm him (ivanovic) at the forum.
* '''Why is the diff from the previous version so huge? I have only made a small change to the .po file with poedit.'''
** When saving a .po file, poedit unwraps all strings. Usually, all .po files are wrapped at 80 characters, so if you want smaller diffs and less merge conflicts, you can execute the following commands each time after editing with poedit:

msgattrib file.po > file.po1
mv file.po1 file.po

== Tools ==

There are several tools to work with .po files:
* [https://pofile.net/free-po-editor Free PO editor] (Web based)
* [http://userbase.kde.org/Lokalize Lokalize] (Unix KDE) (Formerly known as [https://directory.fsf.org/wiki/KBabel KBabel])
* [https://kate-editor.org/ Kate] (Unix KDE)
* [http://wiki.gnome.org/Apps/Gtranslator GTranslator] (Unix Gnome)
* [http://virtaal.translatehouse.org Virtaal] (Multiplatform)
* [http://www.poedit.net/ poEdit] (Multiplatform)
* [http://www.gnu.org/software/emacs/emacs.html Emacs with po-mode] (Multiplatform)
* [http://www.vim.org/ Vim] with [http://www.vim.org/scripts/script.php?script_id=695 PO plug-in] (Multiplatform)
* [https://www.geany.org/ Geany] with [https://plugins.geany.org/pohelper.html PoHelper plug-in] (GTK3 / Multiplatform)
* [https://pypi.org/project/translate-toolkit/ Translate toolkit] (Python)
* [https://pootle.translatehouse.org/ Pootle] (Web-based)
* [https://transdict.com/ TransDict] (Web-based)
* [https://docs.translatehouse.org/projects/localization-guide/en/latest/guide/tools/list.html Translatehouse web page with a list of more tools]

Of course, you can edit po files with any UTF-8 capable text editor, but the tools listed above have great advantages over any text editor regarding .po translation, like going to next fuzzy/untranslated string, searching only in specific fields (msgid, msgstr, comment), ...

== See Also ==

* [[WesnothTranslations]]
* [[WesnothTranslationsHowTo]]
* [[GettextForWesnothDevelopers]]
* [[TranslatorShellscript]]
* [http://www.wesnoth.org/gettext/ Translation statistics]

[[Category:Translations]]

GUIWidgetInstanceWML

2026-02-15T13:08:08Z

Octalot: /* Tree view */ document has_minimum

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| use_markup
| | [[GUIVariable#bool|bool]]
| false
| Whether [https://docs.gtk.org/Pango/pango_markup.html Pango Markup] could be used to format the `label` of this widget (bold, italic, font color, alpha etc.)
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* '''0:''' no border.
* '''1:''' 1 pixel border.
* '''2:''' floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
{{DevFeature1.19|0}}
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.

It has no other extra fields.

== Label ==
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. This is only an approximate means of limiting the line's length, since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies '''wrap''' is true.
When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
{{DevFeature1.17|26}}

Base class for a multiline text area. Not to be used directly in a GUI, use the [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
{{DevFeature1.19|x}}

A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| padding || [[GUIVariable#int|int]] || 5 || Internal padding, used in various spaces and between different types of elements (for example, between two float image, between a header and following text and so on).
|-
| width || [[GUIVariable#f_int|f_int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll Label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scroll Text ==
{{DevFeature1.19|x}}

A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Spinner ==
{{DevFeature1.17|26}}

[[File:Spinner.png|thumb|right]]

A textbox with two repeating buttons, which allow increasing/decreasing of the numerical value inside the textbox.

{| class="wikitable"
!key
!type
!default
!description
|-
| wrap
| [[GUIVariable#bool|bool]]
| 0
| Should the contents of the textbox wrap?
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==
{{DevFeature1.19|0}}

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If true, a tree with at least one item will always have something selected (except when items are being deleted). Although this is {{DevFeature1.19|21}}, the previous behavior is equivalent to setting this to true. The GUI doesn't provide a way to unselect items, the purpose of setting this to false is to add a landing page, as the campaign menu does.
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

UnitTypeWML

2026-01-16T13:13:49Z

Octalot: /* Removed keys */ Update reference to docs for update_unit_type

{{WML Tags}}

__TOC__

== Unit Type ==

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

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences. WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub. {{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [[UnitsWML#.5Brace.5D|[race]]] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''specials_list''': {{DevFeature1.19|18}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[specials]'''. Example: ''specials_list=plague,magical''.
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== Base and variations ==
These create related unit types, for example the Walking Corpse's swimming, mounted, animal, etc. variations.

* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied and then this unit_type's WML overrides parts as documented in [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.
* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit, this tag appears inside the base type's '''[unit_type]''' tag. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]].
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.
* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base type, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.

When merging the data, subtags can be deleted with ''__remove=yes'', as documented in ''[set_variables]''.

== Other tags ==
* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]
* '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities_list=heals_8,regenerates''.

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[AddonsWML#modify_unit_type|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2026-01-15T10:37:52Z

Octalot: /* Other tags */ Make a section for [base_unit] and [variation], make it findable when searching for __remove.

{{WML Tags}}

__TOC__

== Unit Type ==

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

Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".
* '''attacks''': the number of times that this unit can attack each turn. Default is 1.
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute. {{DevFeature1.15|0}} Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences. WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug [https://github.com/wesnoth/wesnoth/issues/6258 6258] on GitHub. {{DevFeature1.17|26}} canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in [https://github.com/wesnoth/wesnoth/pull/8375 8375].
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If '''gender''' is not specified it defaults to ''male''.
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' must consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied.
* '''image''': sets the base image of the unit, which is used on the map.
* '''image_icon''': sets an alternative image to be used to represent the unit in any UI dialogs such as the recruit dialog, attack dialog and the unit image box in the sidebar. This is usually a variant of the image with any transparent padding removed, and is usually needed for images that have extra transparent padding for correct positioning on the game map. The image specified by this key will be scaled to 72x72px in the Unit Recruit/Unit Create dialog's listbox and 144x144px on the unit preview panel (the panel that shows the unit's detailed stats, located on left side on recruit/create dialog and on both sides of the attack dialog). [[ImagePathFunctions#Crop_Function|~CROP]] function can be useful here. Scaling might not be a good idea because it will be internally scaled as mentioned above. You can see Loyalists Paladin or the Fire Dragon/Skeletal Dragon units as an example.
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
* '''upkeep''': the amount of upkeep the unit costs if it differs from its level.
* '''movement''': the number of move points that this unit receives each turn.
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
* '''name''': (translatable) displayed in the Status Table for units of this type.
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [[UnitsWML#.5Brace.5D|[race]]] tag.
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. If the image width or height is equal or above 300 the engine will scale the image with a factor between 1/2 and 1. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
** If "none" is given instead of a filename, no image will be displayed.
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:
** ''scout'': Fast, mobile unit meant for exploration and village grabbing.
** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.
** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.
** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.
** ''healer'': Specialty 'heals' or 'cures'.
:Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.
* '''jamming''': the number of jamming points. Defaults to ''0'' if not present. See [[UnitsWML#.5Bmovetype.5D|[jamming_costs]]]
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
* '''die_sound''': sets the sound, which is used when the unit dies.
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).
* '''bar_offset_x''', '''bar_offset_y''': The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

== After max level advancement (AMLA) ==
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''major_amla''': (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]
** '''[filter]''': A [[StandardUnitFilter]], the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

== Attacks ==
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}). Usually this is one of ''blade'', ''pierce'', ''impact'', ''fire'', ''cold'', or ''arcane'', but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/''type''.png under your addon's images folder. For example, the icon for a damage type called ''electric'' would be at images/icons/profiles/electric.png.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].
** '''specials_list''': {{DevFeature1.19|18}} A comma-separated list of weapon special [[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]], these will be added to this attack as if their full definition was included in '''[specials]'''. Example: ''specials_list=plague,magical''.
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png'').
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are ''melee'' and ''ranged''. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using [[LanguageWML]]. {{DevFeature1.15|0}} When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/''range''_attack.png under your addon's images folder. For example, the icon for a range called ''very_long'' would be at images/icons/profiles/very_long_attack.png.
** '''max_range''': maximum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''min_range''': minimum distance (in number of hexes) to which this attack works. Default is 1.
*** This currently lacks UI and AI support.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
** '''attacks_used''': {{DevFeature1.17|12}} determines how many attacks this attack expends (default 1). This number is deducted from the unit's <tt>attacks_left</tt> when they use this attack.
** '''attack_weight''': multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until {{DevFeature1.19|2}} positive attack_weight was ignored.
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
** '''alignment''': {{DevFeature1.19|5}} decouples the attack's alignment from the unit's alignment. One of ''lawful'', ''neutral'', ''chaotic'', ''liminal'' (See [[TimeWML]]). If unspecified, the unit alignment is used. Only useful for units with multiple attacks, otherwise you can change the unit alignment instead.

== Base and variations ==
These create related unit types, for example the Walking Corpse's swimming, mounted, animal, etc. variations.

* {{anchor|base_unit|'''[base_unit]'''}}: Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied and then this unit_type's WML overrides parts as documented in [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.
* {{anchor|variation|'''[variation]'''}}: Defines a variation of a unit, this tag appears inside the base type's '''[unit_type]''' tag. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]].
** '''variation_id''': Mandatory. The value of '''variation=''' used in SingleUnitWML to choose this variant.
** '''variation_name''': Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with '''hide_help'''=yes.
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.
* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base type, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.

When merging the data, subtags can be deleted with ''__remove=yes'', as documented in ''[set_variables]''.

== Other tags ==
* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]
* '''abilities_list''': {{DevFeature1.19|18}} A comma-separated list of ability [[AbilitiesWML#Common_keys_and_tags_for_every_ability|'''unique_id''']]s. If defined in the registry [[UnitsWML#.5Babilities.5D|[units][abilities]]], these will be added to this unit type as if their full definition was included in '''[abilities]'''. Example: ''abilities_list=heals_8,regenerates''.

* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities|WML Abilities]]. {{DevFeature1.19|4}} Abilities support [event].

* '''[trait]''': Adds an additional trait to the pool. See [[UnitsWML]] for the syntax.
* '''[special_note]''' {{DevFeature1.15|2}} see [[UnitTypeWML#Special_Notes|below]].

== Special Notes ==

Use of the '''[special_note]''' tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the '''[unit_type]description''' attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has '''[modifications]'''.

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

* {{DevFeature1.15|2}} [unit_type][special_note]note=
* {{DevFeature1.15|2}} [unit][special_note]note= (these are used ''instead of'' any defined in the [unit_type])
* {{DevFeature1.15|14}} [movetype][special_note]note=
* {{DevFeature1.15|14}} [''ability tag name'']special_note=
* {{DevFeature1.15|14}} [attack][specials][''special tag name'']special_note=
* {{DevFeature1.15|14}} [language]special_note_damage_type_''TYPE''=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

== Removed keys ==

These don't work any more, the documentation is left here as an aid to porting old code.

* {{anchor|advancefrom|'''[advancefrom]'''}}: {{DevFeature1.15|4}} replaced by [[ModificationWML|[modify_unit_type]]]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.
{{DevFeature1.15|4}} '''[advancefrom]''' was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

== Deprecating units ==

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

<syntaxhighlight lang=wml>{DEPRECATED_UNIT old_id new_id version}</syntaxhighlight>

You can also set the new_id to an empty string if there is no replacement.

== See Also ==

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

[[Category: WML Reference]]

Authoring tools

2026-01-09T09:05:42Z

Octalot: /* trackplacer */ Remove the tool's documentation, leaving the file format

Authoring tools

2026-01-09T08:53:51Z

Octalot: /* CampSynt */ Removed all documentation about this obsolete tool

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML.

== tmx_trackplacer ==

{{DevFeature1.15|3}} '''tmx_trackplacer''' is a tool for editing journey tracks - the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

You'll need Tiled, a GPLv2 map editor:
* Debian / Ubuntu: install the "tiled" package
* other platforms: https://www.mapeditor.org/
* these instructions were written with version 1.2.4

=== Usage ===

Assume the campaign that we want to make a map for is Story of Wose, which is set on the Green Isle. Start by putting a copy of the map in the campaign:

mkdir Story_of_Wose/images/maps
cp WESNOTH_DIR/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Story_of_Wose/images/maps/

Create a template .tmx file with the tool:

WESNOTH_DIR/data/tools/tmx_trackplacer Story_of_Wose/images/maps/green_isle.png -o temp.tmx

=== In Tiled ===

Start Tiled with the temp.tmx file. Expect to see the Green Isle map. On the right hand side of the screen there should be two windows:
* in the top, tabs ''Minimap'', ''Objects'' and ''Layers''. The Layers tab will have only ''background''.
* in the bottom, tabs ''Terrains'' and ''Tilesets''. The Tilesets tab should have ''wesnoth journey icons'' with the red dot, battle and rest markers.
https://user-images.githubusercontent.com/101462/66930950-ac876c80-f035-11e9-9599-d5dc4301acf2.png

In Layers, create a ''New Layer'' of type ''Object Layer''. A typical name for this layer is '''JOURNEY'''. Ensure that this layer is selected.
From the menu bar at the top, select ''Insert Tile''.
From the Tilesets tab, choose dots, battles or rests, and click on the map to add them. The first two items placed will define the start of the journey; every item placed after the first two will be inserted in to the sequence based on whether it appears to be at the end or in the middle.

For Story of Wose, the journey doubles back on itself. For this we'll split the journey in to two parts - rename '''JOURNEY''' to '''JOURNEY_PART1''', and add a new layer '''JOURNEY_PART2'''. You can use the opacity control at the top of the layers window to see what's on each layer.

'''JOURNEY_PART1''' starts with a battle, and ends with a battle:
https://user-images.githubusercontent.com/101462/66930947-abeed600-f035-11e9-89e8-efde15f2a48d.png

'''JOURNEY_PART2''' starts with dots, has a battle and then ends with another battle:
https://user-images.githubusercontent.com/101462/66930949-abeed600-f035-11e9-86a0-18c90c151c76.png

Save the .tmx file.

=== Creating the .cfg ===

Convert the .tmx file to a .cfg file:

WESNOTH_DIR/data/tools/tmx_trackplacer temp.tmx -o Story_of_Wose/utils/bigmap.cfg

Expect to see:

Read data: <Journey based on map file 'Story_of_Wose/images/maps/green_isle.png', with tracks {JOURNEY_PART1,JOURNEY_PART2}>
Exporting as cfg

At the moment, tmx_trackplacer doesn't have a way to preview the animations, other than loading the .cfg with Wesnoth itself. For testing, let's put all of the journey in at the start of the first scenario, Story_of_Wose/scenarios/1_The_Oldwood.cfg

#define STORY_BACKGROUND
[background_layer]
image=maps/background.jpg
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
[/background_layer]
[background_layer]
image=maps/green_isle.png
scale_vertically=yes
scale_horizontally=no
keep_aspect_ratio=yes
base_layer=yes
[/background_layer]
#enddef

[story]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_STAGE2}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE1}
[/part]
[part]
{STORY_BACKGROUND}
{JOURNEY_PART1_COMPLETE}
{JOURNEY_PART2_STAGE2}
[/part]
[part]
story= _ "Today I want to tell you another story, a mere footnote in the history books if it is even remembered at all."

This should now show at the start of the campaign. Remember to refresh Wesnoth's cache if it doesn't appear.

=== Could this be integrated as a Tiled plugin? ===

Yes it could. Implementing it as a file converter was the easier option for development, and the code is (hopefully) modular enough for reuse.

== trackviewer ==

{{DevFeature1.15|3}} Map journey track animation preview tool, shows the journey without needing to start Wesnoth and refresh the cache. It’s a support program which assumes you’re either editing the .cfg file with a text editor or using Tiled with [[Authoring_tools#tmx_trackplacer|tmx_trackplacer]]; in other words, it's the part of the [[Authoring_tools#trackplacer|old trackplacer]] that wasn't covered by tmx_trackplacer.

At least on Linux you can have both Tiled and this open on the same file. Save the file in Tiled, alt+tab to this, and press enter to reload the file.

Keys:
* Escape quits
* Return or Enter reloads the .cfg or .tmx file, and restarts the animation
* Space pauses/unpauses

== trackplacer ==

'''UPDATE: per Elvish_Hunter in [https://forums.wesnoth.org/viewtopic.php?f=21&t=48478&p=631121#p631121 this thread]:
'''<nowiki>"trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)."</nowiki> You should either use [[Authoring tools#tmx_trackplacer|tmx_trackplacer]], or use image editing software to find the X and Y coordinates to create each dot or cross manually.
-------------

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

== Wesnoth Map Tracker ==
A standalone free and open source GUI tool that is available from here: https://github.com/babaissarkar/WesnothMapTracker

It allows you to open an image file (say the Wesnoth Map) and place markers upon it, and the corresponding macro code is generated like this:
<syntaxhighlight lang=wml>
{NEW_JOURNEY 455 300}
{NEW_REST 500 300}
</syntaxhighlight>

Note that it cannot generate a full map.cfg yet, just the part mentioned. For detailed instructions please visit the link above.

[[Category:Tools]]

AbilitiesWML

2026-01-04T11:39:41Z

Octalot: /* Common keys and tags for abilities with a value */ Arbitrary values for priority commonly use -10

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_base_value|'''[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.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[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'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[heals]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value.

=== Extra keys used by the ''[regenerate]'' ability ===
* '''value''': the amount healed.
* Use common keys and tags for abilities with a value

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a 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.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a value
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''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.
* Use Common keys and tags for abilities with a value
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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 tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''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. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[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]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== 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. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''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'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== 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. When not specified, the default is the unit type of the unit doing the plaguing. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

=== 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 ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* 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

2025-09-11T18:29:39Z

Octalot: /* Extra tags and keys used by weapon specials as abilities */ Document description_affected= and name_affected=

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[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].
* {{anchor|filter_base_value|'''[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.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'' or ''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'' or ''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''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.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student 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_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default.
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location].
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]'''
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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 tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== 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. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''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'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== 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. When not specified, the default is the unit type of the unit doing the plaguing.

=== 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 ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* 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]]

InterfaceActionsWML

2025-09-10T10:38:23Z

Octalot: /* [item] */ The image= is shown centered, not aligned to the top-left

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

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

== [inspect] ==
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will not work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side.
** {{DevFeature1.13|0}} none: display no image
* '''mirror''': {{DevFeature1.13|5}} whether to mirror the image specified by the '''image''' attribute.
* '''second_image''': {{DevFeature1.13|6}} same as the '''image''' attribute, but the image is displayed on the right of the message text. {{DevFeature1.17|7}} not working anymore {{DevFeature1.19|9}} working again
* '''second_mirror''': {{DevFeature1.13|6}} same as '''mirror''', but for the '''second_image''' attribute.
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''voice''', '''male_voice''', '''female_voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message. The gendered forms are applied the same as for '''message'''. They are never used when the speaker is the narrator - only '''voice''' is used in that case.
* {{anchor|message-option|'''[option]'''}}: No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.
* {{anchor|message-text_input|'''[text_input]'''}}: there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://docs.gtk.org/Pango/pango_markup.html#pango-markup Pango markup formatting codes].

Prefer to use single quotes (') instead of double quotes (") within the formatting string, as double quotes would need to be escaped in WML (""). Escaping markup can be done with [https://github.com/wesnoth/wesnoth/blob/9daa10a9f27c5a95520e871417bbd72aa52aa688/src/font/pango/escape.hpp#L38-L42 HTML entities].

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

<nowiki>You are victorious!</nowiki>

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

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

The following pango attributes are also available directly as attributes of the '''[message]''' tag:
{{DevFeature1.13|4}}

*'''font'''
*'''font_family'''
*'''font_size'''
*'''font_style'''
*'''font_weight'''
*'''font_variant'''
*'''font_stretch'''
*'''color'''
*'''bgcolor'''
*'''underline'''
*'''underline_color'''
*'''rise'''
*'''strikethrough'''
*'''strikethrough_color'''
*'''fallback'''
*'''letter_spacing'''
*'''gravity'''
*'''gravity_hint'''

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

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

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

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item. All menus will be sorted lexicographically by the id string. The ordering is underscores, digits, and finally letters.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item, defaults to "buttons/WML-custom.png"
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a [[StandardLocationFilter]] similar to the one found inside Single Unit Filters. The menu item will only be available on matching locations.
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:
** '''key''': a string that contains the key to assign to this.
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==

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

== Other interface tags ==

The following tags are also action tags:

=== [change_theme] ===

{{DevFeature1.13|8}}

Change the current interface theme.

* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On 1.14.2 and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).

=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the center of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' To position a small image somewhere other than the center, [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image). The image is centered since {{DevFeature1.17|7}}, previously the images were aligned to the top-left; however this difference doesn't affect any image BLITted onto blank-hex.png, as that is the same size as a hex.)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image ([https://github.com/wesnoth/wesnoth/issues/1219 #1219]). ''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per [[AnimationWML]] is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100'' or equivalently (requires Wesnoth 1.11.2+): ''halo=scenery/fire[1~8].png:100''
* '''name''' an id that can be used to remove the item.
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([https://github.com/wesnoth/wesnoth/pull/3533 #3533])
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''submerge''': float, between 0 and 1: specifies how much of the image should be submerged. Gets multiplied with [[TerrainWML|[terrain]]]<nowiki/>submerge. Default 0.
* '''z_order''': float: defines the order the items get drawn in. Default 0.
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([https://github.com/wesnoth/wesnoth/pull/3533 #3533])
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items from
* '''image''': if specified, only removes the given item if one of its 'image', 'halo' or 'name' attributes is exactly this value. (for 'halo' and 'image' this in particular means that the image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time, or when another [print] tag is encountered.
* '''text''': (translatable) the text to display. Can be an empty string to remove a previous message without showing a new one.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': the length of time to display the text for.
** (Before 1.15.4) This is measured in the number of 'frames', and the default is 50. A frame in Wesnoth is usually displayed for around 30ms.
** {{DevFeature1.15|4}} This is measured in milliseconds. Don't use the default value, because it's a mere 50ms.
** {{DevFeature1.15|14}} The default is 5000 milliseconds.
** {{DevFeature1.15|14}} The string '''unlimited''' displays the text until it's removed by another [print] tag.
* '''color''': (default '''0,0,0''') three comma-separated values giving the red, green and blue values (0-255).
* '''red''', '''green''', '''blue''': deprecated, use color=0,0,0 instead.

=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.

=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving

=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

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

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

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

{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.

=== [unlock_view] ===
Unlocks gamemap view scrolling for human players.

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

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

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]; do not use a [filter] subtag.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.

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

'''Note:''' fire_event does not appear to work in 1.14 or 1.16.

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.
* '''repeat''': repeats the sound for a specified additional number of times (default=0)

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

=== [story] ===
{{DevFeature1.13|8}}

Shows the story screen.
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.
* '''[part]''', '''[if]''', '''[switch]''', '''[wml_message]''', '''[deprecated_message]''' : See [[IntroWML]].

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

=== [music] ===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax

=== [volume] ===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.

=== [color_adjust] ===
Adjust the color tint of terrain, by adjusting time-of-day coloring.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color

=== [screen_fade] ===
{{DevFeature1.17|6}}

Overlay the game display with the given color, fading over the specified duration. This can be used for screen fade effects.
* '''red''', '''green''', '''blue''': values from 0 to 255, the final overlay color (defaults to 0,0,0)
* '''alpha''': value from 0 to 255, the strength of the effect. 0 means no effect and can be used to fade in. 255 means fully opaque and can be used to fully fade out to the given color. Intermediate values will end up with a partial overlay tint on the game screen.
* '''duration''': the length of time it will take to complete the fade, in milliseconds. If 0 the effect is immediate.

=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.

=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit
* '''object_id''': object id to use, defaults to the '''image''' key with an "overlay_" prefix; this allows using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']]
* '''duration''': object duration

=== [remove_unit_overlay] ===
Removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit
* '''object_id''': object id to use
Using [[DirectActionsWML#.5Bremove_object.5D|'''[remove_object]''']] is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271

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

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)
* '''text''': what the label should say. If you put an empty string <code>""</code> as an argument, the label will be completely removed. Use this method if you want to remove a specific label from any location.
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255. When you use Pango markup in the text, you cannot use this, but in that case you could colorize the text via Pango markup.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.
* '''tooltip''': A tooltip visible when putting the mouse over the hex the label is on
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.

=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously (do not use [filter] unless you intend to match one or more units).
* '''text''': the text to display.

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

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

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated.

The meanings of the deprecation levels are as follows:

# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.
# It will be removed no earlier than a specified version.
# It will be removed in the next stable version
# It has already been removed, leaving just a stub to inform users of how to update their code.

Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.

=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. WML wrapper of [[LuaAPI/wesnoth#wesnoth.log]], see the link for more description.
* '''message''': the message to show.
* '''to_chat''': controls whether message is visible in chat, though logger=wml means message is visible anyways. Default ''no''.
* '''logger''': one of '''info''', '''debug''', '''warning''', '''error''', '''wml'''. Default ''info''.

=== [test_condition] ===

{{DevFeature1.13|2}}

Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.

* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.
* '''logger''': Same as for [wml_message]. Defaults to "warning".

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open

Examples of ids:
* unit_Mage
* unit_Dark Adept
* weaponspecial_charge
* terrain_human_castle

The engine will print the topic ids if run from the command line with the ''--log-debug=help'' option.

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

=== [chat] ===
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

=== [zoom] ===

{{DevFeature1.13|8}}

Changes the zoom level of the map.

* '''factor''': The new zoom factor, measured as a multiple of the base zoom.
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.

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

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

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

Timeline of Wesnoth

2025-01-10T15:37:58Z

Octalot: /* 20-130 YW: The Taming of the Wild */ Cite THoT as the source for lore about all runesmiths dying in 40YW

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

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

''This page documents the official, canon timeline, as based on the mainline campaigns. UMC specific info should be in its own pages and should not be here.''

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

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

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

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

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

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

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

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

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

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

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

=== Prehistory ===
* Elves and dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [[Geography_of_Wesnoth#The_Green_Isle|Green Isle]] from a continent further to the west.

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

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

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

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

=== 5-2 BW ===
* The Green Isle is overrun with orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the orcs.
* [[CharactersStorys#Prince_Haldric|Prince Haldric]] leads the evacuation of the survivors to the Great Continent. [[Mainline_Campaigns#The_Rise_of_Wesnoth|'''The Rise of Wesnoth''']] begins.

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

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

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

=== 3 YW ===
* [[Mainline_Campaigns#Winds_of_Fate|'''Winds of Fate''']] begins.
* Drakes arrive on the Great Continent.
* Elensefar and Wesmere are raided by Drakes.
* The drakes build an eyrie north of Wesmere.

=== 4 YW ===
* [[CharactersStorys#Karron|Karron]] is banished from the Great Continent by [[CharactersStorys#Gorlack|Gorlack]]. [[Mainline_Campaigns#Winds_of_Fate|'''Winds of Fate''']] ends.

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

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

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

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

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

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

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

=== 22 YW ===
* While studying at the Academy, [[CharactersStorys#Ardonna_.2F_Ardryn-Na|Ardonna]] resolves to spend the winter researching the Lich Lords' longevity.

=== 23 YW ===
* Action of '''Secrets of the Ancients''' takes place.

=== 25-40 YW ===
* In 25 YW [[CharactersStorys#Haldric_II|Haldric II]] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a dwarven tribe to build the Sceptre of Fire with the Ruby of Fire as its centerpiece; elves associated with [[CharactersStorys#Landar|Landar's]] faction attack during the transfer. [[Mainline_Campaigns#The_Sceptre_of_Fire|'''Sceptre of Fire''']] begins.
* Action of '''The Sceptre of Fire''' takes place. Haldric II is informed that the Sceptre was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [[CharactersStorys#Thursagan|Thursagan]], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.<ref>{{Cite|reclaiming}}</ref>

=== 26-50 YW ===
* [[CharactersStorys#Landar|Landar]] declares himself High Lord of the Elves, leading to civil war.

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

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

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

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

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

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

=== 251 YW ===
* [[CharactersStorys#Cleodil|Cleodil]], wife of [[CharactersStorys#Kalenz_2|Kalenz]], dies.

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

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

=== 360 YW ===
* [[CharactersStorys#Malin_Keshar|Malin Keshar]] born in Parthyn.

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

* Village of Maghre terrorized by a minor necromancer. Action of [[Mainline_Campaigns#A_Tale_Of_Two_Brothers|'''A Tale of Two Brothers''']] takes place.

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

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

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

=== 440 YW ===
* [[CharactersStorys#Garard_II|Crown Prince Garard II]] is born.

=== 442 YW ===
* [[CharactersStorys#Delfador|Delfador]], later called "the Great", is born.

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

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

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

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

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

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

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

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

=== 501 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 534 YW ===

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

=== 535 YW ===

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

=== 550 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 628-635 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 786-826 YW: The Legacy of Black-Eye Karun ==

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

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

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

===786 YW===
* Karun is born.

===805 YW===
* Karun devised the formation of the Great Council.

===811 YW===
* A border dispute between Karun and a human enclave aligned with the Northern Alliance leaves several men and orcs dead and begins a feud that will grow into a fifteen-year war.

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

===816 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] is born

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

===829 YW===
* Frustrated by the fallout of Karun's supposed assassination, Rahul I resigns, and Howgarth III takes his place as Lord Protector.

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

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

===852 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] repels a large elvish invasion.

===858 YW===
* The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [[CharactersStorys#Kapou.27e|Kapou’e]]. [[Mainline_Campaigns#Son_of_the_Black_Eye|'''Son of the Black Eye''']] ends.

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

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

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

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

* History derived from the following [[Mainline_Campaigns|mainline campaigns]]:
** [[The Rise of Wesnoth]]
** [[Legend of Wesmere]]
** [[A Tale of Two Brothers]]
** [[Descent into Darkness]]
** [[Delfador's Memoirs]]
** [[Liberty]]
** [[Heir to the Throne]]
** [[Northern Rebirth]]
** [[The Hammer of Thursagan]]
** [[TheEasternInvasion|Eastern Invasion]]
** [[Dead Water]]
** [[UnderTheBurningSuns|Under the Burning Suns]]

== See Also ==

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

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

Timeline of Wesnoth

2025-01-10T14:57:32Z

Octalot: /* Prehistory - 20 YW: The Founding of Wesnoth */ Add citation to explain where Haldric I's repudiation of the pact is stated in canon

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

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

''This page documents the official, canon timeline, as based on the mainline campaigns. UMC specific info should be in its own pages and should not be here.''

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

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

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

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

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

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

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

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

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

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

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

=== Prehistory ===
* Elves and dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [[Geography_of_Wesnoth#The_Green_Isle|Green Isle]] from a continent further to the west.

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

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

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

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

=== 5-2 BW ===
* The Green Isle is overrun with orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the orcs.
* [[CharactersStorys#Prince_Haldric|Prince Haldric]] leads the evacuation of the survivors to the Great Continent. [[Mainline_Campaigns#The_Rise_of_Wesnoth|'''The Rise of Wesnoth''']] begins.

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

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

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

=== 3 YW ===
* [[Mainline_Campaigns#Winds_of_Fate|'''Winds of Fate''']] begins.
* Drakes arrive on the Great Continent.
* Elensefar and Wesmere are raided by Drakes.
* The drakes build an eyrie north of Wesmere.

=== 4 YW ===
* [[CharactersStorys#Karron|Karron]] is banished from the Great Continent by [[CharactersStorys#Gorlack|Gorlack]]. [[Mainline_Campaigns#Winds_of_Fate|'''Winds of Fate''']] ends.

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

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

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

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

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

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

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

=== 22 YW ===
* While studying at the Academy, [[CharactersStorys#Ardonna_.2F_Ardryn-Na|Ardonna]] resolves to spend the winter researching the Lich Lords' longevity.

=== 23 YW ===
* Action of '''Secrets of the Ancients''' takes place.

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

=== 26-50 YW ===
* [[CharactersStorys#Landar|Landar]] declares himself High Lord of the Elves, leading to civil war.

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

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

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

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

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

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

=== 251 YW ===
* [[CharactersStorys#Cleodil|Cleodil]], wife of [[CharactersStorys#Kalenz_2|Kalenz]], dies.

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

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

=== 360 YW ===
* [[CharactersStorys#Malin_Keshar|Malin Keshar]] born in Parthyn.

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

* Village of Maghre terrorized by a minor necromancer. Action of [[Mainline_Campaigns#A_Tale_Of_Two_Brothers|'''A Tale of Two Brothers''']] takes place.

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

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

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

=== 440 YW ===
* [[CharactersStorys#Garard_II|Crown Prince Garard II]] is born.

=== 442 YW ===
* [[CharactersStorys#Delfador|Delfador]], later called "the Great", is born.

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

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

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

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

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

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

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

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

=== 501 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 534 YW ===

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

=== 535 YW ===

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

=== 550 YW ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== 628-635 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 786-826 YW: The Legacy of Black-Eye Karun ==

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

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

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

===786 YW===
* Karun is born.

===805 YW===
* Karun devised the formation of the Great Council.

===811 YW===
* A border dispute between Karun and a human enclave aligned with the Northern Alliance leaves several men and orcs dead and begins a feud that will grow into a fifteen-year war.

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

===816 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] is born

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

===829 YW===
* Frustrated by the fallout of Karun's supposed assassination, Rahul I resigns, and Howgarth III takes his place as Lord Protector.

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

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

===852 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] repels a large elvish invasion.

===858 YW===
* The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [[CharactersStorys#Kapou.27e|Kapou’e]]. [[Mainline_Campaigns#Son_of_the_Black_Eye|'''Son of the Black Eye''']] ends.

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

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

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

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

* History derived from the following [[Mainline_Campaigns|mainline campaigns]]:
** [[The Rise of Wesnoth]]
** [[Legend of Wesmere]]
** [[A Tale of Two Brothers]]
** [[Descent into Darkness]]
** [[Delfador's Memoirs]]
** [[Liberty]]
** [[Heir to the Throne]]
** [[Northern Rebirth]]
** [[The Hammer of Thursagan]]
** [[TheEasternInvasion|Eastern Invasion]]
** [[Dead Water]]
** [[UnderTheBurningSuns|Under the Burning Suns]]

== See Also ==

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

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

GettextForWesnothDevelopers

2024-11-21T09:27:04Z

Octalot: /* Marking up strings in C++ */ Gettext isn't a full C++ parser

This page is used to help Wesnoth developers and UMC authors to work with the internationalization (i18n) system, based on GNU gettext.

== General design of gettext use ==

Programs using Gettext include the strings in one language (usually English) within the source code. For each target language, a separate file provides a look-up table from English to that language. If the file is missing or doesn't have a translation for that string, the system falls back to using the English text.

The translation mechanism usually involves a function or macro called ''_'' (a single underscore sign). Examples are in the programming-language specific sections below.

=== Textdomains ===

Gettext splits translations into domains. For Wesnoth, the general idea is to use distinct textdomains for each campaign or add-on, so that UMC authors can easily ship translations together with their campaigns. These domains are covered in more depth in [[GettextForTranslators]].

The convention is to name each domain using the name of the add-on, or just its initials. For example, ''wesnoth-utbs'' or ''wesnoth-Son_of_Haldric''. For UMC, it probably makes sense to use the full name to ensure that it doesn't clash with another add-on.

=== Caret hints ===

Some strings look the same in English but should not necessarily look identical in translations. To handle this, those strings can be prefixed with any descriptive string and a '''^''' character. For users viewing in '''en_US''', these hints will be automatically removed from the string before showing it to the user.

{{DevFeature1.15|2}} if the string contains more than one '''^''', the descriptive string ends at the first '''^''', everything following the first '''^''' will be shown to the user.

{{DevFeature1.15|18}} When using gettext's Plural Forms, these prefixes can and should be used in both the singular and the plural.

=== UTF-8 ===

For translation, all C++, WML and Lua files should be in UTF-8. As noted in the [[Typography_Style_Guide]], some punctuation should be used that's outside of the ASCII subset.

== Marking up strings in C++ ==

In C++, you can mark up strings for translations using the <syntaxhighlight lang=c++ inline>_("A translation")</syntaxhighlight> and <syntaxhighlight lang=c++ inline>_n("Translation", "Translations", int)</syntaxhighlight> macros. The <code>_n</code> macro is to be used if the string has a singular and plural form.

You can also add comments for translators. Single-line comments must start with <code>TRANSLATORS:</code> and be on the line ''immediately'' above the translatable string. For multi-line comments, the <code>TRANSLATORS:</code> only needs to be on the first line to include the whole comment, and the last line must be immediately above the translatable string.

If the string contains any placeholders, '''don't''' use <code>snprintf</code>. Instead use WML style variables, put their values in a <syntaxhighlight lang=c++ inline>utils::string_map</syntaxhighlight> and use the <code>VGETTEXT</code> or <code>VNGETTEXT</code> macros instead.

<syntaxhighlight lang=c++>
utils::string_map symbols;
symbols["enemies"] = std::to_string(enemy_count_);
symbols["friends"] = std::to_string(friend_count_);
std::string message;
if ( friend_count_ != 0 && enemy_count_ != 0 ) {
// Omitted from the example - see the code in src/action/move.cpp for how to handle strings with two independent ints.
} else if ( enemy_count_ != 0 ) {
// TRANSLATORS: Only enemies sighted -- bad message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Enemy unit sighted!", "$enemies enemy units sighted!", enemy_count_, symbols);
} else if ( friend_count_ != 0 ) {
// TRANSLATORS: Only friends sighted -- good message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Friendly unit sighted", "$friends friendly units sighted", friend_count_, symbols);
}
</syntaxhighlight>

The <code>string_map</code> can contain additional values that aren't used in the translated string. In the example above, it has both ''friends'' and ''enemies''.

By default, all strings in C++ belong to the "wesnoth" textdomain. If a different textdomain is required, you can add a textdomain binding at the top of the source file, before any include statements. A textdomain binding looks like this: <syntaxhighlight lang=c++>#define GETTEXT_DOMAIN "wesnoth-lib"</syntaxhighlight>

You should avoid placing translatable strings in C++ headers if at all possible. Though there are a few places where it may be unavoidable, such as if templates are in use, it creates the risk of the strings sometimes being looked up in the wrong textdomain if the header is included in multiple files with different textdomains. If possible, always factor the translatable strings out into a source file.

Don't wrap the existing macros in more macros, as the .pot files are generated by gettext. Gettext isn't a full C++ parser, it's just searching for arguments to functions and macros in this list: <code>_ N_ _n N_n VGETTEXT VNGETTEXT sgettext vgettext sngettext vngettext</code>. That list is defined in cmake/FindTranslationTools.cmake and po/SConscript.

== Marking up strings in WML ==

=== The textdomain bindings ===

All files with translatable strings must declare which textdomain they use, which is normally done by putting ''#textdomain'' on the first line of each .wml file. See the example below:

<syntaxhighlight lang=wml>
#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...
[/unit_type]
</syntaxhighlight>

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below. When parsing this, the engine will record both the visible text and the active textdomain, which can later be used to get the translation when displaying the text to the player.

<syntaxhighlight lang=wml>
name= _ "Mu"
</syntaxhighlight>

==== Notes to the translators ====

If you think a translatable string needs additional guidance to be translated properly, you can provide a special comment that will be seen by the translators. Some hints are generated automatically, but in general if you have to wonder whether a hint is needed then it probably is. The context of the scenario isn't obvious in the translation tools, and you can't assume that the strings are shown to the translator in the same order that they appear in the WML file.

Just begin the comment with '#po:' or '# po:' above the string in question. This must be on the line (or lines) immediately before the string that the hint applies to:

<syntaxhighlight lang=wml>
#po: "northern marches" is *not* a typo for "northern marshes" here.
#po: In archaic English, "march" means "border country".
story=_ "The orcs were first sighted from the north marches of the great forest of Wesmere."
</syntaxhighlight>

The wmlxgettext tool will automatically generate hints for some tags, in addition to hints from '# po:' comments:

* For ''[message]'': the ''id'', ''speaker'', ''role'' or ''type'' used to choose the speaker
* For ''[object]'': the ''id''
* For ''[unit]'': the ''id'' and ''unit_type''
* For ''[unit_type]'': the ''id'' and ''race''
* For ''[objective]'': whether it's ''condition=win'' or ''condition=lose''

==== Things to avoid ====

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

<syntaxhighlight lang=wml>
name= _ ""
</syntaxhighlight>

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

<syntaxhighlight lang=wml>
name= _ "{TYPE} Mu"
</syntaxhighlight>

To show why it will not work:

<syntaxhighlight lang=wml>
#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}
</syntaxhighlight>

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

<syntaxhighlight lang=wml>
name= _ "Sword Mu"
name= _ "Bow Mu"
</syntaxhighlight>

Since those are not in the catalogues, they will not get translated.

=== Gender-specific strings ===

Several tags, including ''[message]'', ''[abilities]'' and ''[trait]'', can choose different strings based on the gender of the unit. In English the two versions are likely to be the same, but other languages may have gender-specific words for 'I' or 'me'.

<syntaxhighlight lang=wml>
[message]
speaker=student
message= _ "Have you found an orc for me to fight, huh? A troll?"
female_message= _ "female^Have you found an orc for me to fight, huh? A troll?"
[/message]
</syntaxhighlight>

The convention in WML is, as above, to use ''message='' and ''female_message='', with the latter string including the prefix ''female^''. The mechanism also supports ''male_message='', but all units will fall back to using the plain ''message='' value if there isn't gender-specific version that matches their gender.

The message is chosen based on the gender of the speaking unit. To change the message based on the gender of another unit requires separate ''[message]'' tags:

<syntaxhighlight lang=wml>
[if]
[have_unit]
id=student
gender=male
[/have_unit]
[then]
[message]
speaker=Delfador
message= _ "Young man, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/then]
[else]
[message]
speaker=Delfador
message= _ "female^Young lady, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/else]
[/if]
</syntaxhighlight>

Using a macro to encapsulate most of that can be useful. The example above is from the tutorial, after expanding the ''GENDER'' macro which is defined in data/campaigns/tutorial/utils/utils.cfg.

=== Proper nouns in strings ===

Some languages require declensions of proper nouns - a person's name may change slightly depending on their role in a sentence. See for example [https://github.com/hrubymar10/wesnoth-cs/pull/209#issuecomment-1066163433 the Czech translators' PR 209].

Where there are a small number of units that might be addressed, for example the two in the tutorial or the four possible allies in UtBS, it's better to have a separate translatable string for each possible character instead of interpolating '''$unit.name''' into a string.

=== Reusing mainline translations ===

You can reuse translations for strings in mainline domains by using multiple textdomain bindings:

<syntaxhighlight lang=wml>
# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
# ...
[/attack]

#textdomain wesnoth-Son_of_Haldric
# ...
[/unit_type]
</syntaxhighlight>

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, and wesnoth-units.

==== The gettext helper file ====

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy, by having all strings that should use a specific textdomain in a single file. It is also more wmllint-friendly.

Here is an example of a gettext helper file. The macro names start with 'SOH_' to ensure that they don't clash with another add-on's macros (assuming that this add-on is Son_of_Haldric).

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib

#define SOH_STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define SOH_STR_SWORD
_"sword" #enddef
</syntaxhighlight>

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

<syntaxhighlight lang=wml>
[attack]
id=sword
name={SOH_STR_SWORD}
# ...
[/attack]

[terrain_type]
id=ice2
name={SOH_STR_ICE}
# ...
[/terrain_type]
</syntaxhighlight>

=== Unbalanced WML macros ===

WML macros can be ''unbalanced'', meaning that they either include a [tag] without the corresponding [/tag] or a [/tag] before the corresponding [+tag]. These macros are expected to be used in a place where the [tag] is already open. Writing new macros using this isn't recommended; instead please ask in the WML Workshop forum about better ways to do it.

When generating the .pot files for translation, wmlxgettext may stop with one of the errors
* error: Son_Of_Haldric/utils/abilities.cfg:29: unexpected closing tag '[/abilities]' outside any scope.
* error: Son_Of_Haldric/utils/abilities.cfg:300: End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [abilities])

Suppose abilities.cfg line 29 is in the definition of SOH_ABILITY_BLITZ. To get the .pot file generated, the simplest change is to use ''# wmlxgettext'' comments to add the missing opening or closing tags:

# wmllint: unbalanced-on
# wmlxgettext: [abilities]
#define SOH_ABILITY_BLITZ
[dummy]
id=soh_blitz
# ... ability definition stuff ...
[/dummy]
[/abilities]
# ... several lines of code, none of which are an ''#enddef'' ...
[+abilities] # wmlxgettext: [/abilities]
#enddef
# wmllint: unbalanced-off

== Marking up strings in Lua ==

In Lua code, textdomains are a callable object that looks up a string. This has support for both singular and plural strings. By convention, the name <code>_</code> is usually used for the textdomain object.

The following sample code demonstrates how to fetch translatable strings in Lua:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "wesnoth"

-- Look up a normal string:
local win_condition = _ "Defeat enemy leader(s)"

-- Hints for the translators start with "po:", as in WML:
-- po: Floating text shown when a unit with the "feeding" ability gets a kill
local text = stringx.vformat(_"+$value max HP", { value = feeding.value})
</syntaxhighlight>

Plural strings are supported since Wesnoth 1.14:
<syntaxhighlight lang=lua>
local turn_count = 5
turn_counter = _("this turn left", "%d turns left", turn_count)
turn_counter = tostring(turn_counter):format(turn_count)

-- For readability, the example's strings are slightly different to the real code.
-- The real strings have brackets in the text shown to the player.
</syntaxhighlight>

In Wesnoth 1.15, variables can be interpolated using names:
<syntaxhighlight lang=lua>
-- Look up a plural string, using the preferred style (as of Wesnoth 1.15.3):
local turn_count = 5
turn_counter = _("this turn left", "$remaining_turns turns left", turn_count)
turn_counter = turn_counter:vformat{remaining_turns = turn_count}
</syntaxhighlight>

== The textdomain tag ==

To tell the engine where to search for the .po and .mo files, each textdomain needs a ''[textdomain]'' tag. For add-ons and mainline campaigns, the tag is usually placed inside of the _main.cfg. This is a top-level tag, so should be outside the ''[campaign]'' or ''[modification]'' tag.

Translatable strings from C++ and Lua use the same textdomains as WML; this WML tag tells the engine where to search for these strings irrespective of which programming language the string appeared in.

<syntaxhighlight lang=wml>
[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]
</syntaxhighlight>

The .po (or .mo) files will be loaded from a subdirectory of the ''translations'' directory.

== Generating the .pot and .po files for UMC ==

For each language, Wesnoth will search for a .po file containing the translations. How to create that file will be explained below, but first the overview of where it should go. Continuing with the Son of Haldric example, the Swedish translation would be in the file:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric/translations'' comes from the ''[textdomain]'' tag's ''path''
* ''wesnoth-Son_of_Haldric'' is the textdomain's name
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

Wesnoth 1.14 (but not 1.12) supports reading .po files directly, so when you add the .po file and the new translation should appear as soon as you refresh the cache.

=== Generating the .pot file ===

The template (.pot) file contains all of the strings that need to be translated in the .po files, but without the translations.

The .pot is generated from WML and Lua files using a tool called wmlxgettext. With Wesnoth 1.14.5 and later, this is shipped with Wesnoth itself as part of the [[Maintenance_tools]] and can be used from the Maintenance Tools' GUI. At the moment it's not documented on that page, but if you follow the instructions to get GUI.pyw running then you'll see there's a wmlxgettext tab.

Pre-1.13 instructions on how to get and use it are in Nobun's [https://r.wesnoth.org/p617733 forum posting].

==== Error messages from wmlxgettext ====

If you get the error from ''wmlxgettext'' of "UTF-8 Format error. Can't decode byte 0x91 (invalid start byte).", and the line in question has a curly quotation mark, that likely means that your text editor is using the Windows-1252 character set, and you need to replace the Windows quotes with their Unicode equivalents, see [[Typography_Style_Guide]] and your editor's documentation for more info. The same applies if the error message says 0x92, 0x93 or 0x94.

If you get either "unexpected closing tag '[/''something'']' outside any scope" or "End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [''something''])" then see [[#Unbalanced_WML_macros]] above.

=== Generating the .po files for each language ===

Each .po file can start as a simple copy of the .pot file. Either the author or the translator copies the template to the language-specific filename, and then the work of [[GettextForTranslators]] happens on those copies.

Some .po editors, for example poedit, will recognise that the .pot is a template, and automatically suggest saving to a different filename. The poedit editor can also update a .po file based on changes to the .pot file.

=== Generating the .mo files for UMC ===

For Wesnoth 1.14, it's generally not necessary to compile the .po files to .mo files. The mainline translations still use .mo files for better performance, but UMC authors can skip the .mo compilation stage.

== See Also ==

* [[WesnothTranslations]]
* http://www.gnu.org/software/gettext/
* [https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html#Preparing-Strings GNU gettext manual on preparing translatable strings]
* [[GetText]]
* [https://wmlxgettext-unoff.readthedocs.io/en/latest/ wmlxgettext documentation]

[[Category:Development]]

IGNFileFormat

2024-09-14T09:48:12Z

Octalot: Default blacklist is used for access to all files

__NOTOC__
When you upload an add-on, some files and directories are ignored and not uploaded.

If you would prefer to have more control over which files and directories should be ignored, you should provide a _server.ign file containing a list of filter patterns. Each file or directory matching any entry of the _server.ign file will not be included when uploaded to the add-ons server.

{{DevFeature1.13|12}} The engine blocks WML and Lua from accessing any file that matches the built-in list. This was added as a security feature to block access to .git directories, disregards any _server.ign file, and is likely to change during the 1.19 dev cycle (see discussion in [https://github.com/wesnoth/wesnoth/pull/9325 PR 9325]).

== Where do I put the file, and what goes in it? ==

The file should be placed within the root level of your add-on (data/add-ons/addon_name/_server.ign).

A specific format is required:

* {{DevFeature1.13|0}}: Blank lines and lines beginning with '<code># </code>' (space required) are ignored.
* Each line should contain exactly one pattern.
* <code>*</code> and <code>?</code> wildcards are supported (<code>?</code> stands for any single character, <code>*</code> stands for any number of any characters).
* {{DevFeature1.13|12}}: <code>+</code> wildcards are also supported: it stands for one or more characters.
* Patterns with a trailing forward slash '<code>/</code>' will match directories; the rest only match files.

==== Default values ====

If there is no custom _server.ign file present, a default filter will be used instead, which is as follows:

.+
.+/
__MACOSX/
#*#
*~
*-bak
*.swp
*.pbl
*.ign
_info.cfg
*.exe
*.bat
*.cmd
*.com
*.scr
*.sh
*.js
*.vbs
*.o
*.ini {{DevFeature1.13|12}}
Thumbs.db
*.wesnoth
*.project

If you create a custom _server.ign, you should add these entries to it.

== See Also ==

* [[PblWML]]

[[Category:Create]]

AbilitiesWML

2024-09-08T12:50:42Z

Octalot: Add and sub work together since 1.19.4

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These "weapon specials as abilities" will give that weapon special to all attacks the unit has if they match a unit filter like '''[filter_self|filter_opponent|filter_attacker|filter_defender|filter_student]''' and an attack filter inside of that unit filter (besides [has_attack]) called '''[filter_weapon]'''.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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].
* {{anchor|filter_base_value|'''[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. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''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.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. Work like '''[filter_self]''' of specific weapon special.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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 tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].

=== 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. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''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'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== 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

2024-08-12T16:54:52Z

Octalot: /* Extra keys used by the [damage_type] special */ Note the special handling of [filter_weapon]type=

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These "weapon specials as abilities" will give that weapon special to all attacks the unit has if they match a unit filter like '''[filter_self|filter_opponent|filter_attacker|filter_defender|filter_student]''' and an attack filter inside of that unit filter (besides [has_attack]) called '''[filter_weapon]'''.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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].
* {{anchor|filter_base_value|'''[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. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Is ignored when '''sub''' is present.
* '''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.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. Work like '''[filter_self]''' of specific weapon special.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes what '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes what '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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 tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].

=== 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. Is ignored when '''sub''' is present.
* '''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 ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== 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]]

1.19 Roadmap

2024-06-30T09:49:43Z

Octalot: /* 1.19.8 (01/19/2025) */ Check for unused translatables

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

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

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

== Note on Single-Player Campaign Reworks ==

We have some campaign reworks planned and in-progress.

In-progress: The South Guard, The Deceiver's Gambit (DM replacement), The Rise of Wesnoth
In-progress but slower development: Legend of Wesmere (reworked to SP entirely), Heir to the Throne (grand overhaul)
Planned but no progress yet: Angel of Ashes (AoA) (Ashievere-centric campaign)

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

If you have inquiries on the reworks, contact SP rework team leaders (forums/discord): Nemaara/Yumi (TSG, TRoW, AoA), Dalas (TDG, HttT), Lord-Knightmare (LoW-rework).

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

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

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

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

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

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

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

== 1.19.7 (12/15/2024) ==

* GUI2 port of the Help Browser (tentative) (LumiousE)

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

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

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

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

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

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

== 1.19.13 (06/15/2025) ==

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

== 1.19.15 (08/17/2025) ==
* Play through any remaining mainline campaigns worth playing through (ie: not LoW) and add at least a minimum baseline of achievements to them (Pentarctagon)

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

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

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

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

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

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

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

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

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

* Add new screenshots for 1.20

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

[[Category:Roadmaps]]

1.19 Roadmap

2024-06-30T09:46:27Z

Octalot: /* 1.19.8 (01/19/2025) */ [damage_type]

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

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

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

== Note on Single-Player Campaign Reworks ==

We have some campaign reworks planned and in-progress.

In-progress: The South Guard, The Deceiver's Gambit (DM replacement), The Rise of Wesnoth
In-progress but slower development: Legend of Wesmere (reworked to SP entirely), Heir to the Throne (grand overhaul)
Planned but no progress yet: Angel of Ashes (AoA) (Ashievere-centric campaign)

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

If you have inquiries on the reworks, contact SP rework team leaders (forums/discord): Nemaara/Yumi (TSG, TRoW, AoA), Dalas (TDG, HttT), Lord-Knightmare (LoW-rework).

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

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

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

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

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

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

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

== 1.19.7 (12/15/2024) ==

* GUI2 port of the Help Browser (tentative) (LumiousE)

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

* [https://github.com/wesnoth/wesnoth/issues/8585 #8585], [https://github.com/wesnoth/wesnoth/issues/9035 #9035] Solve all issues with [damage_type] (octalot)

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

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

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

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

== 1.19.13 (06/15/2025) ==

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

== 1.19.15 (08/17/2025) ==
* Play through any remaining mainline campaigns worth playing through (ie: not LoW) and add at least a minimum baseline of achievements to them (Pentarctagon)

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

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

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

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

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

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

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

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

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

* Add new screenshots for 1.20

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

[[Category:Roadmaps]]

CampaignDialogue:TB1.9

2024-06-29T16:16:32Z

Octalot: Link to the campaign's .pot file on Github

{| style="float:right"
|
__TOC__
|}

This is a transcription of all dialogue from The Tale of Two Brothers (1.9.5). It is meant as a resource for Wesnoth writers. If you don't want spoilers, leave this page now.

The translation tools automatically create a [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-tb/wesnoth-tb.pot transcript of the current version], including all of the dialogue.

=== Possible Timeframe ===
This campaign, as originally written, had no definite time or place. There was a vague reference to "the eastern reaches of the kingdom of Wesnoth". In a later revision the epilog hint that Arvith may have traveled with the elf-lord Kalenz, but this is not much of a constraint as Kalenz was around in 1YW and at least until the beginning of HttT in 517 YW.

Maghre has to be within reach of the orcs, but in a time and place where there haven't been orc raids for generations. This limits us to *western* Wesnoth, orc raids having been a chronic problem in the northeast even during the Kingdom's strongest periods. The logical time would be shortly after the death of Haldric IV in 350, the beginning of the First Dark Age. It's arbitrarily set at 353; Kalenz began his wanderings ten years later, so the timing for Arvith to meet him later in life isn't bad.

Placing the campaign is a little trickier. Our main textual clue is that there is a dense wood, said by legend to be haunted, a few days' ride north. Later, the boss's keep is said to be still further north. Neither of these directions has plot importance, but they do suggest a locale for Maghre - near the Gray Woods. The battle maps exclude it from being in a featureless plain, though; there are hills to the south and west.

== Death Dialogue ==
=== Mordak ===
'''Mordak:''' Argh

=== Arvith ===
'''Arvith:''' All is lost now that I am dead... (S 1-2)

'''Arvith:''' Everything is lost now that I am dead... (S 3-4)

===Baran===
'''Baran:''' It is over, I am vanquished.

== Scenario 1: Rooting Out A Mage ==
=== Story ===
The remote freehold of Maghre in the western reaches of the kingdom of Wesnoth was once a peaceful place, its inhabitants largely unaware of the comings and goings of the wider world. Wars and the rumor of wars touched them not, until the day a dark mage settled in the region and began seeking sacrifices for his evil summonings.

Skeletons and zombies killed cattle and fired fields. "Fear and obey Mordak the Mage!" they cried in fell voices as they did their foul deeds. People vanished from isolated farmsteads. Men and women began to fear the night, and their children even the bright day. But the nearest lord was more than a day's ride distant, and messengers sent to seek his help did not return.

There was a man named Baran who had shown talent as a mage when he was young, gone to the great Academy on the Isle of Alduin, and returned to work his magic in the land where he was born. The people looked to him for help and leadership. He found weapons half-forgotten from the times of their sires and grandsires hanging in many houses, and bade the villagers to take them down and clean and oil them. He set the smiths of Maghre to making spearheads and ax-blades for the rest.

Now Baran had a brother named Arvith who had also left Maghre to seek his fortune, and had become the leader of a small band of horsemen who hired out as guards to merchant caravans. Fortunate it was for all that when Baran was but an apprentice mage, he had made a pair of amulets for himself and his brother, with which they might call to each other when in dire need. Baran sent out that call.

12 V, 363 YW
Excerpt from the journal of Baran of Maghre

If I could but face this 'Mordak'! I think my magic might prove stronger than his. But he bides in the hills, well-guarded by his servants, and I muster frightened peasants to fight his minions with blades and sticks. I need my brother; he always had a better head for battle than I.

Will he heed the call? I do not know if he has kept the amulet; we have not spoken since that evil day at Toen Caric. If he will not come for me, perhaps he will return to aid our village in its hour of desperate need.

Heeding the call of his amulet, Arvith gathered such men as he could and hurried to Maghre to help Baran.

=== Introductory Dialogue ===
'''Baran:''' Greetings, brother, and welcome home.

'''Arvith:''' Hail.

'''Baran:''' Is that all, Arvith? I understand, but...

'''Arvith:''' You called, and I came; be content with that. What ails Maghre?

'''Baran:''' A dark mage has come upon us; his creatures call him Mordak. They have been terrorizing outlying farms, and we fear they may soon attack the village itself! The villagers of Maghre have taken up weapons but they are not trained fighters; but we need your men, and you to lead them.

I can feel Mordak's foul touch on the hidden currents of the earth and air. He is somewhere due north of here, I would say not more than two days' ride.

'''Arvith:''' All right. I will do this for the village. Can you keep the mage off our backs?

'''Baran:''' I will go stealthily with a handful of our best scouts and woodsmen. While you demonstrate against him and kill his creatures, I will try to defeat Mordak himself with magic at an unguarded moment. You shall be the right hand, I the left... aye, brother?

'''Arvith:''' ... Aye. Just make sure you're there when we need you.

=== Turn 6 ===
'''Arvith:''' Baran should be in position by now. Press them, distract the adept so Baran can spring his trap!

=== Turn 10 ===
'''Arvith:''' Baran has not made his attack!

'''Mercenary:''' Could he have abandoned us?

'''Arvith:''' No... No. This is something else. I'm worried about him... but right now it means we have to deal with this Mordak ourselves.

=== Undead Leader: Last Breath ===
'''Mordak:''' Argh.

'''Arvith:''' Good work, men! But what has become of my brother?

'''Mordak:''' Worried about him, are you? E-he-he..hergh...gaargh... (dies)

'''Arvith:''' There's nothing more to be had from this one; we will have to search for Baran ourselves!

'''Reporter:''' Sir, our scouts report that Baran was seen captured and carried away further north!

'''Arvith:''' That they should dare this! We will give chase at once.

=== Time Over ===
'''Mordak:''' Your brother's plan to ambush me has failed. He is our prisoner now.

'''Arvith:''' My brother, kidnapped? I have failed you, Baran! And even now Mordak's forces descend upon the village!

=== First Attack ===
(attacks either Adept, Sorcerer, or Vampire Bat)
'''Arvith:''' I hear these creatures are nigh-immune to our weapons, let us see!

=== Player Kills First Enemy ===
(kills same as above)
'''Unit:''' That was not so hard!

== Scenario 2: The Chase ==
=== Story ===
16 V, 363 YW
Excerpt from the journal of Arvith of Maghre

We've been searching three days for Baran, and turned up nothing. My best hunch was to head north into the borderlands, where the necromancer's minions could safely hide; everywhere else is more farmland. At first I thought the search might be useless, but late in the first day we found a set of tracks. Some of them had been made by skeletal feet.

We're close enough to be certain now: those tracks are heading into the Grey Woods. No one from Maghre or any of the other villages has gone into that forest in living memory. Stories have been passed down for generations warning against it. Supposedly the place is haunted by lost souls who hunger for the living, and anyone who dies there is doomed to join them.

16 V, 363 YW
Excerpt from the journal of Arvith of Maghre

But I'm past superstitions now; I've seen enough of the world to guess at the truth behind these sorts of tales. The forest is home to elves — unfriendly ones, if the stories have any basis at all. I worry for my men; horses don't fight well in forests, and the elves will be more dangerous in their own territory. But there are things that need done and questions that need answered. Something bigger is happening. One necromancer terrorizing townsfolk is nothing new, but why didn't his servants scatter when he was killed? Where are they headed now? And most importantly, why did they take Baran with them?

Besides... I want my brother back.

=== Introductory Dialogue ===
'''Arvith:''' Come on, men. A stroll through such lovely green woods, what could be finer?

'''Nil-Galion:''' You there! Halt and explain yourself.

'''Arvith:''' We're chasing after some men who kidnapped my brother!

'''Nil-Galion:''' Those men told me their prisoner had attempted to murder their master, and wArvithd that evil men would follow him. Advance no further, or you will die.

'''Arvith:''' So much for those ghost stories. Mere elves will not stop me from freeing Baran!

'''Horseman:''' I am glad at least that we will not have to face ghosts. But those elves will have us at a disadvantage; our horses will not maneuver well in the trees.

'''Arvith:''' Bah, just stay on the paths; our spearmen and bowmen can fight in the deeper woods. We have faced and won through greater perils than those amateurs can offer.

=== Move to the North ===
'''Unit:''' I see them! There they are!

'''Muff Toras:''' Curses! If they had been an hour slower our master's reinforcements would already be here to meet us.

=== Turn 12 ===
'''Arvith:''' Come on, men, let's catch those kidnappers!

=== Undead Last Breath ===
'''Muff Toras:''' Hah! You have captured me, but it will avail you nothing. I sent your precious brother the mage north with half my men a day since; he will be safely locked away in our master's dungeons by now.

'''Arvith:''' My blade is at your throat. Give us the way to my brother now, or I will spill your wretched blood on the ground.

'''Muff Toras:''' Three days ride to the northeast, in a deserted castle. The passwords to the guards are --- and ---.

'''Arvith:''' Bind him and take him with us. If he has played us false, he will die.

'''Horseman:''' Captain, what are we riding into? I thought you wanted nothing to do with Baran any more, not since Toen Caric.

'''Arvith:''' I'm no longer sure. What's between us remains, but knowing someone else has lain hands on him changes things. Mount up, and let's get moving.

==== Easy (Iron Mauler appears) ====
'''Brena:''' Greetings. I am Brena, a knight errant. I saw you pursuing and fighting the foul undead. Are there more of them to be destroyed?

'''Arvith:''' Aye. We think there's a nest of them north-east of here. They've captured my brother.

'''Brena:''' I bear a great hatred towards their kind. I will follow and fight them with you, if you permit.

'''A Horseman:''' He would only slow us down!

'''Arvith:''' It is my place to decide this.

=====Yes=====
'''Arvith:''' Oh, all right then. Come along with us.

'''Brena:''' Thank you. My comrades and I will help you on your noble quest.

=====No=====
'''Arvith:''' I am sorry. We have not the time to spare.

'''Brena:''' Take this, then, for I see that you are on a quest. My comrades will help you whenever you call for them.

'''Narrator:''' You receive 70 pieces of gold!

=== Elf Last Breath ===
'''Nil-Galion:''' Foolish human, you have killed me but you will not catch the undead in time. I have fulfilled my contract, and will be reanimated soon to become a lord of their armies.

(dies)

'''Arvith:''' Follow their back trail!

=== Time Over ===
'''Muff Toras:''' My reinforcements are here!

'''Arvith:''' He escaped us...

== Scenario 3: Guarded Castle ==
===Story===
19 IV, 363 YW
Excerpt from the journal of Rotharik the Clanless

The last of Mordak's servants arrived this morning bearing the news of his death, as well as a bundle so well-bound it was barely recognizable as a man. Mordak was always reckless. This whole desperate scheme was his, and I suppose I could blame him for everything that we have suffered through if it still mattered. It was he who brought the wrath of the orcs down on us, too. But all the same, he managed to accomplish what he set out to do. I still cannot believe the finality of what has happened; until now we had always managed to make it through somehow.

We had hoped to deliver the mage to Tairach in return for our lives. I do not know what the warlord wants with this man, but he matches the description. I suppose that Mordak's plan would have worked perfectly if not for the appearance of the horse warriors. Now they are coming here, led by a man rumored to be this mage‚Äôs brother. If that is true, he will stop at nothing, no more than would I if they held Mordak.

19 IV, 363 YW
Excerpt from the journal of Rotharik the Clanless

I have done what I can to fortify this dilapidated castle. The orcs who came with us stand guard at the gates, and I am gathering all of my servants to me in the inner sanctum. But ill fate awaits. Whether I defeat this horse-warrior or no, the orcs will still come for me; they have been scouring the borderlands and raiding the northern farm country in search of us.

Yet for some reason I fear these brothers more. If Mordak were here it would be different, but we are broken... and these two men are whole. In each other, in the ties that bind them, they have strength.

=== Introductory Dialogue ===
'''Narrator:''' Arvith and his men halt outside of the castle, gazing for a moment at the hulking mass of stone looming in the fog. There is movement in the mist.

'''Guard Leader:''' Halt! Friend or foe? Give the password.

'''Arvith:''' The password is ----.

====Password Correct====
'''Guard Leader:''' Pass friend.

'''Arvith:''' The adept didn't lead us astray after all. I'll keep my word, distasteful as it may be; cut him loose, and let's be rid of him.

====Password Incorect====
'''Guard Leader:''' Wrong! Die!

=== Orcs Sighted ===
'''Knago-Brek:''' Haha! We not kill people for long time. Weapon wants blood. We now kill humans!!

'''Arvith:''' My sword-arm has a say in who will do the dying. Come on, men, let's kill some orcs.

===Knago-Brek Dies===
'''Arvith:''' One less braggart orc in the world.

'''Unit:''' Captain, what are orcs doing this far south?

'''Arvith:''' Good question. Perhaps my brother will have found out.

=== Second Set of Guards (Turn 3/6) ===
'''Guard Leader II:''' Are you our relief arriving? Does this mean we get to leave here now?

'''Arvith:''' Um, yes. Fine. You can go.

'''Guard Leader II:''' Um, you're supposed to give the password.

'''Arvith:''' Oh, of course. I had nearly forgotten.

====Password Correct====
'''Guard Leader:''' Thanks! Irritating little formality, isn't it?

====Password Incorrect====
'''Guard Leader II:''' That's the wrong password! These aren't our relief! Get them!

====Dialogue Continues====
'''Arvith:''' I think I should better support my men at the front to make sure we can free my brother.

===Rotharik Dies===
'''Rotharik:''' Your hand or Tairach's, death is still death... (argh)

(dies)

'''Arvith:''' 'Tairach'? Who or what is Tairach?

'''Unit:''' There's a key in his robes.

'''Arvith:''' That may well be the key to the cell they're holding Baran in! I will take it.

===Treasure===
'''Unit:''' Look what I have found in here! I can count a hundred pieces of gold.

(50 on easy, 100 on hard)

=== Baran's Cell ===
'''Unit:''' I found Baran. He is in this cell.

====If Arvith====
'''Baran:''' Good to see you, Arvith.

'''Arvith:''' And you too, brother.

====If not Arvith====
'''Baran:''' You must be one of Arvith's men. Please help me get out of this dungeon.

====Dialogue Continues====
'''Baran:''' The accursed dark sorcerer Rotharik has imprisoned me behind this magically enhanced iron gate. It can only be opened with the correct key. You must get it from him to free me.

=====If You Have Key=====
'''Baran:''' Thank you for saving me. I… was not certain you would come.

'''Arvith:''' Have you no faith in your brother, Baran?

'''Baran:''' It's not that. Perhaps I deserved to rot here. I failed you. I failed you again.

'''Arvith:''' That is as may be. But you are my brother still. And... I never doubted you would have come for me.

It was no great trial, after all. A few elves, one or two dark sorcerers, a gang of orcs and some undead. Really just a day's work for the company.

'''Baran:''' Thank you for coming to my aid. Let us return to the village.

=== Time Over ===
'''Rotharik:''' You are too late! Your brother is already dead! Muahahaha...

'''Arvith:''' Argh!!!

== Scenario 4: Return to the Village ==
===Story===
27 V, 363 YW
Excerpt from the journal of Baran of Maghre

Almost home now. The last week has been full of mixed feelings for me — blissful and difficult by turns. It was wonderful to be out of that dungeon cell and in the sunlight again without the threat of death or worse hanging over my head... but with that behind me, I turned to the almost equally daunting task of making amends with my brother.

Arvith had largely forgiven me by the time he freed me from my cell. All the same, it has taken all of the past week for us to rebuild the sense of comfort in each other we once had. It is fortunate that we have been able to take our time getting back ‚Äî we gave the Grey Woods a wide berth, and on our way around it we traveled through some truly beautiful countryside. It has given us plenty of time to talk.

27 V, 363 YW
Excerpt from the journal of Baran of Maghre

Though I am more at ease now, my thoughts often turn back to Toen Caric. We should have been able to repel the orcs without great loss — the pincer attack Arvith devised would surely have carried the day but for me. It was reckless of me to leave my men behind — I wounded the warlord and forced him to flee the field, but the cost far outweighed the gain. Those under my command could have been saved if I had remained with them.

I can hardly blame Arvith for having taken their deaths ill, and I can never undo the wrong that I have done, but I suppose that time heals some things. We return to the village as brothers once more.

But I am still troubled. I wonder... is this sense of foreboding I feel merely a remnant of my time locked away in that dungeon, or is it a sign of something real?

=== Introductory Dialogue ===
'''Arvith:''' There. Your village is just across those hills, and already I see men coming to greet us!

'''Baran:''' No, they are fleeing from something. We must find out what is happening over there!

'''Arvith:''' Men! Ready your arms!

'''Baran:''' We find Reeve Hoban. Maybe he knows what is going on here.

===Tairach Sighted===
'''Unit:''' We're almost there!

'''Baran:''' That warlord! It's...

'''Arvith:''' Yes, I'd know that face anywhere. Especially after what you did to it.

'''Baran:''' The warlord from Toen Caric.

'''Tairach:''' You! The mage who scarred me with fire! KILL THEM!

'''Baran:''' Let's finish what we started, brother.

'''Arvith:''' Aye. I'll be the right arm, and you'll be the left. Let's go!

=== Soldier of Reeve Hoban Seen ===
'''Reeve Hoban:''' I am glad to see you returned.

'''Baran:''' No gladder than I am to be here. But what has happened to Maghre?

'''Reeve Hoban:''' Soon after you departed we were beset by orcs. With half the men of Maghre gone, we could not stop them.

The orcish warlord aims to enslave us. We will not be able to hold out for much longer.

Have a care, his men are fell fighters and have killed many. Very few remain who can bear arms, but I will send them to aid you in battle.

=== Enemies Defeated ===
'''Arvith:''' It is finished. We've defeated him at last. It was good to have you at my side, Baran.

'''Baran:''' So much has been destroyed. It will be difficult to repair all that the orcs and undead have wrecked. And they could come again.

'''Arvith:''' I must go back to earning my living. But we have our amulets, little brother. If you are beset again, I will come.

===Time Over===
'''Arvith:''' I don't think we can rescue anyone from these villages. It is too late.

'''Baran:''' I was too weak to protect these people. Oh why did this happen to me?!?

==Scenario 5: Epilogue==
===Story===
22 IX, 365 YW
Excerpt from the journal of Arvith of Maghre

Maghre is looking much better than the last time I saw it. Baran has done wonders in two years. The village is rebuilt, and the surrounding farmlands are restored and reoccupied. Despite my brother's worries, our people have faced no new threats in that time.

It has been more difficult to stay away in those two years, but I have my calling and Baran has his, and we have had little opportunity to meet again. But as the company and I are passing through this part of the kingdom with a new patron, I have asked leave of him to visit my brother and he gave it.

22 IX, 365 YW
Excerpt from the journal of Arvith of Maghre

This patron is, of all things, an elf. I never thought I'd befriend one, but he is less arrogant than the rest. Kalenz, he calls himself. He's seen too much; I can tell that just by meeting his eyes. I think we will have to work for our pay soon.

In the meantime, though, it's good to relax and enjoy the peace.

==TB's Specified Unit Names==
===Humans===
*[[CharactersStorys#Arvith | Arvith]]
*[[CharactersStorys#Baran | Baran]]
*Alwyn
*Brent
*[[CharactersStorys#Brena | Brena]]
*Cadell
*Dannen
*Efran
*Fargus
*Erik
*Heine
*Magnus
*Reeve Hoban

=== Elves ===
*[[CharactersStorys#Nil-Galion | Nil-Galion]]

===Undead===
=====Human=====
*[[CharactersStorys#Mordak | Mordak]]
*[[CharactersStorys#Muff_Toras | Muff Toras]]
*[[CharactersStorys#Rotharik | Rotharik (the Clanless)]]

===Orcs===
*Knago-Brek
*[[CharactersStorys#Tairach | Tairach]]
[[Category:Create|*]]
[[Category:Writing|*]]

CharactersStorys

2024-06-29T16:10:47Z

Octalot: /* Nil-Galion */ Rewritten in 1.16 to be against the undead

{| style="float:right"
|
__TOC__
|}

'''Translator's Helpers'''

This page is intended to help Translators figure out how characters should be translated. Sometimes, you need some information about a figure, a race or a plot, that might influence the translation. Campaign designers may define their intention for a character and each translator may include his/her implementation in his/her language (e.g. look for the "German" remarks in THoT). In case you are not the author of a campaign, please state where you got the background information from.

Campaign designers: Please supply us mere translators with the flavor of your campaign to keep the high standard in all languages. Characters that do not appear repeatedly in the campaign are excluded from the character list. If they are important for translation purposes, feel free to add them.

All of the campaigns have a wiki-presentation of their [[CampaignDialogue | dialogues]] - started in 2009, a few details might change in future reworks of the po-files, but the overall story and characters should not have changed. Therefore, those pages are a good start to get a "feeling" for the characters.[[MainlineCampaigns | Storyline, Walkthrough and more]] are accessible via this page as well.

A page containing helpful shell scripts, e.g. to extract the speaker+text out of the po-file may be found [[TranslatorShellscript| here]].

== The Rise of Wesnoth ==
{{TranslatorCampaignBox
| story = TrowStoryLine
| walkthrough = TheRiseOfWesnoth
| dialogue = CampaignDialogue:TROW
| translatorlist= CampaignTROW
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10613
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=9&t=30843
| campnick = trow
| maintainer = zookeeper
}}
=== [[Haldric I|Prince Haldric]] ===
Description: He is not the educated type of prince - not a stupid brute as such, but certainly not very knowledgeable and calm either. Haldric has always seemed more like this eager hack-and-slash-fellow-made-leader than a contemplating strategist. He bears a certain hot-headed, arrogant attitude.

=== Lady Outlaw/[[Jessene]] ===
(had been changed from "Jessica" to "Jessene" during 1.6)

Description: A pretty kick-ass/bad-ass lady, she appears rather calm and patient - she is very intelligent.

=== [[Burin]] the Lost ===
Description: Burin is pretty nutty. He's been travelling and living alone for a long, long time. A hot-headed dwarf, half-crazed comic reliefed, although, he's also a bit of a whiner.

=== Commander [[Aethyr]] ===
Description: A man who gets in the thick of melee.

=== Minister [[Edren]] ===
(had been changed from "Edmond" to "Edren" during 1.6)

Description: A white priest, battling the dark forces. So, he is not too passive. He's a minor character and basically all his dialogue is in the vein of, "No you won't, you soldier of darkness!", so a little bit more restrained anger or some other kind of tension would be good for him. He has a psycho-rigid vibe which is a nice change from the usual wise-and-holy look of priests. After all, he's more country priest than archbishop.

=== Sir [[Ruddry]] ===
A knight; sole survivor of the Clearwater Port expeditionary force. He's the one you get if you take the branching path thru the Swamp of Esten.

=== Sir [[Ladoc]] ===
A knight; the equivalent of Sir Ruddry for players who take the branching path thru the Midlands instead. He is from Southbay, as opposed to Ruddry's Clearwater Port.

=== Lich-Lord [[Jevyan]] ===
Description: In TRoW, Jevyan is basically this posturing super-aggressive overconfident lich brute over half of whose spoken lines end in an exclamation mark. Jevyan never really has a deviously cunning plan or does anything subtly. He is the most powerful lich in of his time, he would probably try to show that.

=== King [[Addroran IX]] ===
The King of Southbay. He is like a captain who is willing to "go down with the ship" (so to speak), except that in this case the "ship" is Southbay.

=== King [[Eldaric IV]] ===
Description: Eldaric is the king of a small backwater kingdom and introduced as a sovereign who'll rather be in the thick of melee than parading behind his soldiers. Therefore, my take is that regalia and embellishment should be toned down as much as possible in favor of a more practical gear. I might even get as far as denting it here and there.

=== Lord [[Logalmier]] ===
Description: The local elvish warlord. He is mostly guided by prejudices and survivalist instincts, which don't take much more than a grouchy "the elves are for the elves" answer to all situations.

=== Lady [[Dionli]] ===
Description: It seems like she's the highest ranking one of the elf lords, and seems pretty well rooted in reality instead of being one of those elves who just daydream of faerie stuff and talk like a poet all the time. She is more like the underling that is trying to get things done in the absence of wise or strong leadership. She actively seeks cooperation and discussion between the different races, but can still be sat on by the rest of the lords, led by Logalmier, in breaking the pact.

=== [[Elilmaldur-Rithrandil]] ===
An ancient wose of Oldwood. Guardian of his fellow trees; deeply in touch with nature.

=== Lich-Lord [[Lenvan]] ===
Description: He's the one who's been sitting in a little cave under the Oldwood for a long time with the ruby, so the old and frail look would suit him - secretive and cunning.

=== Lord [[Typhon]] ===
Description: A mighty sea king.

=== [[Midnight Queen]] ===
An extremely beautiful vampire lady, who curses her island after being killed.

== Winds of Fate ==
{{TranslatorCampaignBox
| story = WofStoryLine
| walkthrough = WindsofFate
| dialogue = CampaignDialogue:WoF
| translatorlist= CampaignWoF
| discuss =
| forumresource =
| campnick = wof
| maintainer = name & SigurdFireDragon
}}
=== Gorlack ===

=== Reshan ===

=== Karron ===

== An Orcish Incursion ==
{{TranslatorCampaignBox
| story = An_Orcish_Incursion_story
| walkthrough = AnOrcishIncursion
| dialogue = CampaignDialogue:AOI
| translatorlist= CampaignAnOrcishIncursion
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20249
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=9&t=23420&start=192
| campnick = aoi
| maintainer = cycholka, esr
}}
=== Erlornas ===
Description: "he's a dandy, yet dangerous."

=== Linaera ===
Description: "Not real old, but grown-up and experienced, so she'll get a tad older in the process but not much."

=== Lomarfel ===
Description: Elvish Rider, "looks really surly."

=== Rualsha ===
An orcish sovereign.

== Legend of Wesmere ==
{{TranslatorCampaignBox
| story = LegendofWesmereStory
| walkthrough = LegendofWesmere
| dialogue = CampaignDialogue:LOW
| translatorlist= CampaignLegendOfWesmere
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=22465
| forumresource = yet no used
| campnick = low
| maintainer = fabi
}}
=== Kalenz ===
The same Kalenz from HttT, except that he is much younger here.

=== Olurf ===
=== Landar ===
=== Velon ===
=== Cleodil ===
=== Galtrid ===
=== Eonihar ===
=== Kior-Pur ===
=== Huraldur ===
=== Graur-Tan ===
=== Galenor ===
=== Aldar ===
=== Aquagar ===
The source of Kalenz's suffering and Landar's downfall.

== Secrets of the Ancients ==
{{TranslatorCampaignBox
| story = SotA_story
| walkthrough = Secrets_of_the_Ancients_Walkthrough
| dialogue = CampaignDialogue:SOTA
| translatorlist= Secrets_of_the_Ancients_Translators
| discuss = https://forums.wesnoth.org/viewtopic.php?f=8&t=40545
| campnick = sota
| maintainer = SigurdFireDragon
}}

=== Ardonna / Ardryn-Na ===

Ardonna renames herself Ardryn-Na in scenario 13.

Ardryn-Na's journal is the book of necromancy in the Descent Into Darkness campaign, so the text should match. However SotA has far more context for the text than DiD, so it might be better to translate SotA and then copy the text to DiD.

=== Ras-Tabahn ===

He's dying of tuberculosis, and "cough, cough" should be translated as such.

=== Vendraxis ===

He's the one who prompts Ardonna to change her name to Ardryn-Na.

=== Carcyn ===

An outlaw kept prisoner by his father until Ras-Tabahn's arrival.

=== Shynal ===

Carcyn's love interest, also kept prisoner until Ras-Tabahn's arrival. She's basically a recolored and feminized version of Harper.

=== Rudic ===

A sailor captain revived by Ardonna who uncovers her to his fellow in revenge.

== Sceptre of Fire ==
{{TranslatorCampaignBox
| story = Sceptre_of_Fire_story
| walkthrough = Sceptre_of_Fire
| dialogue = CampaignDialogue:SOF
| translatorlist= CampaignSeptreOfFire
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20255
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=9&t=32775
| campnick = sof
| maintainer = zookeeper
}}
=== Rugnur ===
Description: Dwarf fighter. "Relatively young and not of especially high rank. Not particularly bright and talks in a pretty informal manner to everyone. Not greedy or very interested in gaining status, riches or fame; probably he just wants to do his job so he can go home and work on a miniature collection or something. That is, not a very exciting protagonist but more like the average joe who gets sucked into a big mess."

=== Thursagan ===
Description: Dwarf runemaster. Thursagan is THE runemaster. He's the best and he knows it. He's a hermit living in the wilderness so his outfit should reflect that (gryphon feathers, wolf fur or something like that would fit nicely), and while his equipment should include some smithing tools, he shouldn't look like he's just been hammering away in his forge like the core runemaster portrait. And, of course, he should have a big gorgeous hammer. Karrag's portrait in The Hammer of Thursagan should feature the same hammer, so you might take inspiration from that. Having faintly glowing runes on its side would be nice. Note worthy of interest: As a general note regarding the dwarves, it seems like their clan is a relatively small one and not very rich either, so I'd suggest being rather conservative with their bling.

=== Durstorn ===
Description: Dwarf lord. He's the leader of the clan, so he should have the most bling on him. He's pretty greedy and hasty, maybe even crass. Generally not a very pleasant person, but apparently not a terribly incompetent leader either (at least until the ruby corrupts him).

=== Alanin ===
Description: Human dragoon. He's the guy Haldric sends to go with the dwarves as his personal representative of sorts, so he could have some special regalia, although of course it'll have to be something other than the sceptre symbol used in later times. The whole campaign is said to have lasted 15 years, and in the epilogue Haldric tells him he's old enough to retire, so that's a hint towards his age.

=== Baglur ===
Description: Dwarf stalwart. As he himself says, he's "a retired warrior" so a bit older than the other dwarves (except perhaps Thursagan).

=== Haldric II ===
Description: Human King.

=== Krawg ===
Description: Gryphon - intelligent, but hard to understand (Its sometimes even hard to get the meaning - check [[CampaignDialogue:SOF]] for an proper english version). For translating Krawg long for "speaking raven" rather than "Long John Silvers parrot". He's the only one that survives the last battle.

=== Glonoin ===
Description: Dwarvish Lord.

=== Kuhnar ===
Description: Dwarvish Steelclad.

== A Tale Of Two Brothers ==
{{TranslatorCampaignBox
| story = A_Tale_Of_Two_Brothers_Story
| walkthrough = ATaleOfTwoBrothers
| dialogue = CampaignDialogue:TB1.9
| translatorlist= CampaignTwoBrothers
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10339
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=9&t=23420&start=210
| campnick = tb
| maintainer = Ivanovic
}}
=== Arvith ===
(Arvith was formerly known as "Arne" until version 1.??; still referred to as "Arne" in some quotes about him)

Description: "Arvith looks a little fat, but otherwise they all look cool to me... his weight and his expression fit his character perfectly...long hair... Even Arvith's horse looks a bit smirky." Leader of a small band of horsemen who hired out as guards to merchant caravans.

=== Baran ===
(Baran was formerly known as "Bjarn" until version 1.??)

Description: Arvith's brother, a Red Mage. Feels guilty about having let his brother down in the past. Has an amulet that he uses to call Arvith for help.

=== Rotharik ===
A dark sorcerer known as "Rotharik the Clanless". Employs bandits, orcs, and undead. Seeks to deliver Baran to Tairach.

=== Nil-Galion ===
An elf who guards the Grey Woods. Sides with the undead in 1.14 and before. Rewritten in 1.16 to be against necromancy, but in either version believes that Baran is in the opposing faction.

=== Mordak ===
The initial mage antagonist. It turns out that he is actually acting on behalf of Rotharik.

=== Brena ===
A knight errant who pursues the undead. Only available on the easiest difficulty.

=== Tairach ===
The orcish warlord from Toen Caric that Baran had wounded previously. Wants revenge on Baran.

=== Muff Toras ===
A dark adept who acts as a courier between Mordak and Rotharik.

== Descent into Darkness ==
{{TranslatorCampaignBox
| story = Descent_Into_Darkness_story
| walkthrough = DescentIntoDarkness
| dialogue = CampaignDialogue:DID
| translatorlist= CampaignDescentintoDarkness
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20251
| forumresource = yet no used
| campnick = did
| maintainer = zookeeper
}}
=== Darken Volk ===
A very cold person, Darken Volk is also an excellent actor, easily able to deceive others with false sincerity, hatred, or affection. However, he is a singularly self-centered individual and does not care what, or who, gets in the way. And whatever gets in his way must be destroyed. He is well learned, and as such his speech should be one very precise and two have a very extensive vocabulary.

=== Drogan ===
Drogan is very, very loyal to that which he holds dear. Parthyn is one of these things, as well as Malin Keshar's father. He does not want anything to harm his loved ones, and so sees many an unpleasant duty as necessary for upholding the peace. His speech is plain and conventional, no long words or complicated sentences.

=== [[Malin Keshar]]/Mal Keshar ===
Malin Keshar is a young man who had his childhood and his father ripped away from him by the orcs. He now has only one goal in life: to make the orcs suffer. There is nothing he wants more and it has become his constant obsession. If he can do anything to harm the orcs, he will do so gladly, even if it harms other people. Still, he is a basically honorable person and does not enjoy the death of any save the orcs. Malin Keshar is a mix of the illiterate world of his former village and the literate world of the mages' islands. As such, he speaks almost like a reasonably educated person of today might, with a broad vocabulary but not overly complex sentence structure. At the end of the campaign he becomes an ancient lich named Mal Keshar.

=== The book of necromancy ===
The book is Ardryn-Na's journal from the Secrets of the Ancients campaign, and the text in the two campaigns should match. SotA has much more context for the book's text, so its translation is likely to be better than old translations of DiD.

=== Foolish Hero ===
Either a Dwarvish Lord, an Assassin, a Royal Guard, an Orcish Warlord or an Elvish Marshal, he's the proverbial knight in shining armor, who has come to vanquish the darkness. He is very brave, but also somewhat brash and arrogant, thinking that this is just one more battle to face. This should show in his speech as flowery and yet somewhat haughty language. He has bested many foes before, won many battles, and is very experienced. This darkness however, may be a little more than he can handle . . .

=== Dela Keshar ===
Malin Keshar's older sister, she tries to kill him after his troops killed Drogan.

=== Lady Karae ===
Lord Karres till 1.14

A noblewoman mage who guards the book of necromancy.

== Delfador's Memoirs ==
{{TranslatorCampaignBox
| story = none yet
| walkthrough = DelfadorsMemoirs
| dialogue = CampaignDialogue:DM
| translatorlist= CampaignDelfadorsMemoirs
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=25554
| forumresource = yet no used
| campnick = dm
| maintainer = [[User:Tapik|tapik]]
}}
In German: My primary goal was to create some sort of medieval sounding German without truly using the language of the german middle ages (middle high german). I tried to use so called "Archaismen" (words not or almost not used anymore) and played with the syntax; e.g. the genitive had been used a lot more in the middle ages than it is used today.

=== [[Delfador]] ===

In German: As for Delfador, in the beginning he hast just finished his apprenticeship and still is unsure of his powers and abilities. In time and through the hardships he has to undergo, he gains in self-confidence which is reflected by the way he expresses himself. Furthermore his education and literacy shows up in his phrasing and diction.

=== Methor ===

In German: He is teacher and good friend to Delfador and you can see this in his conversation with him. Towards other people he shows is wisom gained by a lifetime as a magician.

=== Lionel ===

=== Iliah-Malal ===

In German: He thinks of himself as being without any boundaries and limits and that there exists nobody who has the power to stop him on his way. In his conversations with other beings you can see his inhumane age and his arrogance. He is very well spoken but depreciatory towards people he thinks are unworthy of his attention.

=== Leollyn ===

Description: Leollyn is a good man - honest, intelligent, loyal to his king, and a friend of Delfador's mentor Methor. He takes Delfador under his wing at court. He doesn't watch his back, though, and will be murdered by a conniving rival. I imagine a man in healthy middle age with a benign, open expression, someone who would both inspire trust and deserve it. I see him wearing simpler clothing than would be normal for a man with the kind of court position he has, well-made but unostentatious. (http://forums.wesnoth.org/viewtopic.php?f=9&t=24805&start=0)

=== Garard II ===
=== Tomb Guardian ===
=== Chantal ===
One of Kalenz's grandchildren, her fate is unknown after having been unable to escape Weldyn in HttT.

=== Kalenz ===

In German: He's one of the oldest of the Elves and bears the weight and wisdom of ages. He has very refined manners and knows how to deal with different kind of people. Both vocabulary and syntax are sophisticated.

=== Sagus ===
Asheviere's father who wants to take the whole world after his mortal demise.

== Liberty ==
{{TranslatorCampaignBox
| story = Liberty_story
| walkthrough = Liberty
| dialogue = CampaignDialogue:L
| translatorlist= CampaignLiberty
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20252
| forumresource = yet no used
| campnick = l
| maintainer = esr & zookeeper
}}
=== Baldras ===
From the comments in S01: "Baldras is an old man from the country and both speaks and writes with many grammatical errors due to his relative lack of education. He is also a little bit rude and grumpy, so languages with ruder or more informal variants of words should use those where appropriate."

=== Harper ===
The nephew of Baldras, or more specifically the son of Baldras' younger sister Erwen. "Harper has a bit of an accent, but not as much as Baldras. He's a bit of a reckless kid as Baldras alludes to, but he's much more polite."

=== Relana ===
(Became a female character in 1.9, was named "Relnan" before)

The magistrate of Delwyn. Has an accent like many of the other countryfolk. Baldras and Harper go to her for help.

=== Helicrom ===
A Shadow Lord (advancement of a Shadow Mage) known as the "Crow of the Grey Woods" (since that's where he's found). Joins forces with Harper and Baldras.

=== Lord Maddock ===
Lord of [[Elensefar]]. He is nobility, so his speech is somewhat fancier than normal. He doesn't really want to help Baldras and Harper that much, but he still has a little bit of a conscience, so he agrees to provide some assistance to them.

=== Thhsthss ===
A saurian oracle who works for the orcs. Has the usual [https://tvtropes.org/pmwiki/pmwiki.php/Main/Sssssnaketalk snakelike speech patterns] that most saurians have.

== Heir to the Throne ==
{{TranslatorCampaignBox
| story = HtttStoryLine
| walkthrough = HeirToTheThrone
| dialogue = CampaignDialogue:HttTh
| translatorlist= CampaignHeirtotheThrone
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10322
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=32&t=35289
| campnick = httt
| maintainer = zookeeper
}}
Character Descriptions by vodot [http://forums.wesnoth.org/memberlist.php?mode=viewprofile&u=128239 (Forum Userpage)] [[User:Vodot|(Wiki Userpage)]]

=== [[Konrad]] ===
At the outset of ''Heir to the Throne'', Konrad is the twenty-two-year-old and last surviving nephew of King Garard II. After the king's betrayal and Asheviere's subsequent rise to power, Konrad alone was saved by Delfador from the queen's bloody purge of the royal household in Weldyn. The infant heir was taken to the Aethenwood, the great southern elvish forest, to be raised in secret and groomed by Delfador until the time was right for his accession to the throne.

Konrad is intelligent and somewhat reserved (for a human), and being raised among the elves has given him a sensitivity to living things and a compassionate spirit. Delfador has proven a diligent tutor in history, rhetoric, and military theory, and under the mage's patient wisdom the boy has learned humility and discipline as well.

As ''Heir to the Throne'' begins, Konrad is growing restless with waiting and hiding in secrecy, being eager to repay the queen and her servants for the blight they have brought to Wesnoth and the vile betrayal of his uncle. With the invasion and destruction of the Aethenwood by the queen, the time for the heir to step forward has come at last.

=== [[Delfador]] ===
Delfador the Great is the legendary and ancient archmage of Wesnoth; befriended by elves and dwarves, wielder of the Staff of An-Usrukhar, advisor to kings and slayer of traitors; the latter of which has resulted in his exile by Asheviere these past twenty-two years. In the queen's hearing he is called the Kingsbane, for Asheviere has worked feverishly to spread false tales that it was he (and not herself) that was behind the deaths of Garard II and crown prince Eldred.

After rescuing Konrad from death, Delfador has lain hidden in secret in the southern wood, instructing the growing prince and watching anxiously the movements and events of the greater kingdom. His whereabouts are still unknown to the queen, though that will not last long when his terrifying power is revealed and the heir that he has long concealed steps out of the shadows.

=== [[Asheviere]] ===
Queen of Wesnoth these 22 years; often called the 'Dark Queen' by the free peoples of the coast and by the especially courageous (or foolish) of her subjects. Executing plans laid long before, the queen caused her son Eldred to betray her husband, king Garard II, and then assured her rise to the throne by goading the crown prince into foolishly challenging Delfador the Great to solo combat.

After cleansing the palace of rivals, the queen has laid hold of Wesnoth in an iron fist, making alliances with orcs and undead alike to secure her personal wealth and the security of her throne. She is a master deceiver and worker of lies, a sorceress in her own right, and is hated and feared by her people and by the wise; scattered and helpless to stop her and her allies from plunging the realm into darkness.

=== [[Li'sar]] ===
Most of what little royal blood remains in Weldyn now flows in the veins of one of two people: Asheviere the queen and her daughter Li'sar, princess and heir-apparent. Li'sar has grown up in the palace, but her headstrong and indomitable spirit have assured her frequent escape from the cushioned pavilions and courts of royalty.

She entered the military academy of Weldyn where she graduated swiftly with honors, and as ''Heir to the Throne'' begins she has begun leading a division of her mother's loyalist army in the field. Li'sar was born for the battlefield; leading troops with uncanny skill and poise. She is a budding master of misdirection and tactics.

Like her mother, princess Li'sar is prideful and quick-witted, but to the queen's vexation she has also inherited much of her father's nobility and sense of honor. Now, her forays taking her further from the capital and into the larger countryside, the princess is slowly becoming aware of the true impact her mother's reign has had on the realm.

=== Kalenz ===
The High Lord Kalenz is a storied warrior and leader of elves and men. He is ancient even for an elf, his younger days stretching back into the shadows when men first landed on the great continent.

In ''Heir to the Throne'' Kalenz emerges from his second retirement to undertake his final adventure with his friend Delfador the Great, shepherding Garard II's last remaining heir in his journey to Find the Scepter of Fire and dethrone the wicked queen.
It's unknown if he dies between HttT ending and NR beginning.

=== Relgorn ===
Relgorn son of Ulrek is lord of the Knalgan dwarves. After being sent there as a youngster at his father's command, he has diligently safeguarded his people and tried to make inroads against the orcs and other wicked creatures that inhabit the tunnels of Knalga near those ancient caverns where the Scepter of Fire is said to rest. He bears little love for elves, men, or any other race outside his small earthen realm, but in his youth he once befriended a young Delfador. Relgorn owes the mage a debt of gratitude for saving his father and his people.

=== Moremirmu ===
A white mage and survivor of the free coast peoples that were exiled to the Three Sisters as a result of their rebellion against Asheviere's tyranny. As ''Heir to the Throne'' begins, Moremirmu and the other ''Liberty'' survivors are waging a crusade to reclaim the Isle of the Damned from the necromancer Muff-Malal.

=== Sir Kaylan ===
A Grand Knight, horse-lord, and leader of the free peoples of Blackwater Port. Kaylan and his knights have long held the port against Asheviere, but have been coming under increasing pressure as she ramps up her campaign to destroy the elves of the Aethenwood.

=== Reglok ===
Reglok is head of the Thieves Guild of Elensefar, a loyal (if dubious) band of highly skilled "traders".

=== Keh Ohn ===
A great Drake-lord of Thoria, leader of the northern race of those creatures that were previously unknown to inhabit Wesnoth.

== Northern Rebirth ==
{{TranslatorCampaignBox
| story = Northern_Rebirth_story
| walkthrough = Northern_Rebirth
| dialogue = CampaignDialogue:NR
| translatorlist= CampaignNorthernRebirth
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20253
| forumresource = http://www.wesnoth.org/forum/viewtopic.php?p=120380#p120380
| campnick = nr
| maintainer = Taurus
}}
=== Tallin ===
"The typical hero stereotype, and also the main character of this campaign. He originally starts out as a peasant, but over the course of the campaign Hamel trains him up and he switches over to being a lieutenant. He is young - between 20 and 30, and has all that usual hero stuff around him - brave, intelligent, good looking, blah blah blah."

In German: An educated but not very "upperclass" language in the beginning, but starting to be much more "noble" when courting Eryssa.

=== Hamel ===
A very wise, tough grizzled veteran Dwarvish Lord who, until recently, has been trapped in the caves of Knalga fighting an unending war with undead, trolls and orcs. He also appears in The Hammer of Thursagan, which takes place chronologically after this campaign.

In English: He has a strong Scottish accent ("In English-language folklore, the Scottish share many characteristics with fantasy dwarves. Both are tough, dour, canny mountain folk who are good at engineering and hold grudges forever; the similarity even makes sense to a Scot. This is why a Scots accent “feels right” for a dwarf.") (http://www.catb.org/~esr/wesnoth/campaign-design-howto.html#toc5)

In French: While I am not the French translator and do not know how Hamel was translated in French, in "The Three Musketeers" Dumas says that in French, the Gascons are the equivalent of the Scottish, so maybe he could be given a Gascon accent?

In German: Dwarves are speaking "medieval", as no accent fits the "dwarf"-description above. It somehow fits in the German knight tradition, especially holding grudges forever :).

In Greek: Choosing a particular dialect was difficult, since I don't know greek dialects that well. I used "village" greek for making it rougher, and added ancient greek and byzantine terms whenever I needed to sound medieval or pompous, and for many "army" and "battle" terms.

=== Camerin ===
A very powerful but crazy Arch/Great mage who loves to blow things up.

=== Father Morvin ===
(Name was changed from "Marcus" during Version 1.6)

A wise and experienced White Mage missionary who - until recently - has been a prisoner to Malifor. He has traveled a lot, knows many people, and has much experience in different lands. Husband to Sister Thera.

=== Eryssa ===
(Name was changed from "Anita" during Version 1.6)

A beautiful, virtuous, brave, but at times snobbish and stuck up, elvish princess (Elvish Sorceress). Her father holds a high position with the north elves and she has been captured and held for ransom by the orcs. Sister of Elenia.

=== Elenia ===
Eryssa's wild older sister. Elenia is a beautiful elvish Druid who had a strong desire to see the world and set off on her own. She was eventually captured and held prisoner by Malifor, only because he found her pretty.

=== Hidel ===
A middle-aged elvish marshal who is Eryssa's longtime guardian and mentor. Although he's very wise, he's at times inflicted with the typical elvish snobbishness and superiority issues. He was sent by Eryssa and Elenia's father to rescue her from the orcs.

=== Sisal ===
A lady elvish avenger, Hidel's second in command. She's brave and ferocious and will fight to the death if necessary.

=== Rakshas ===
A powerful Orcish Sovereign that likes being called "The Master". He has thrashed enough orcish Warlords into servitude that he poses as a serious threat to the entire northlands. He has a large imagination and delusions of grandeur and when combined with his power, makes him a foe to be reckoned with.

=== Malifor ===
A powerful ancient lich with more delusions of grandeur. He wields vast power over any creature that has died and has been resurrecting the long dead defenders of Knalga to carve out an underground undead empire for himself.

=== Sister Thera ===
The dedicated wife of Father Morvin (white mage of course). She doesn't quite fit the profile of a saintly subdued holy lady however, as she is very spirited and takes great pleasure in blowing evil creatures to pieces as well as occasional theatrical displays of drama.

=== Stalrag ===
A Dwarvish Lord who is the leader of the Shinsplitters - a tribe of Dwarvish Ulfserkers (same guy from HttT, in the scenario Hostile Mountains). He has a long standing feud with the liches Ro'Arthian and Ro'Sothian (see below).

=== Ro'Arthian ===
A mage that refused to die and reincarnated as an Ancient Lich instead. He and Ro'Sothian are powerful liches that have the ability to control gryphons, ogres and trolls. Although he and and his brother are good at heart they have no qualms about using dark and evil means to achieve their ends.

=== Ro'Sothian ===
The younger brother and side kick of Ro'Arthian. He was a mage until he was killed and reincarnated as a Lich. Pretty much the same profile as his brother.

(name changed from Ro'Sarthian somewhen before 1.8)

=== Abhai ===
Died as a mortal in 14318 AD, he's the former king of Garet-Desh's ghost, drawn into half-life by Malifor. At first, he believed that Tallin's army had been brought there by the High Kalian of Hiera'Shirsha.

=== Krash ===
A drake that Tallin rescues from the dungeons of Malifor, to whom Camerin immediately takes a like. Rather feral; he doesn't communicate well with humans. He has other drake friends.

== The Hammer of Thursagan ==
{{TranslatorCampaignBox
| story = TheHammerOfThursagan_story
| walkthrough = TheHammerOfThursagan
| dialogue = CampaignDialogue:THOT
| translatorlist= CampaignTheHammerofThursagan
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=20253
| forumresource = http://www.catb.org/~esr/wesnoth/thot.html
| campnick = thot
| maintainer = esr
}}
Campaign specialties: About noble titles in the Northern Alliance [http://www.wesnoth.org/forum/viewtopic.php?f=7&t=20299]. Cave-related vocabulary in 13 languages may be found [http://efs.ffspeleo.fr/stages-reglementation/124-lexique/download here]

=== Aiglondur ===
Description: A dwarf, the guard captain of the Eastern Gate. Young, intelligent, related to the clan chieftain. Dwarven society doesn't have a noble class as such, but Aiglondur is from one of its leading families and will have war-gear of the best quality. If weapons are in the portrait, his will be your standard Dwarvish double-bitted axe. Great-nephew of Lord Hamel and Captain of the east Gate. Unusual diplomatic type of dwarf.

=== Angarthing ===
Description: A junior loremaster. Young but self-conscious about being an authority figure; will dress to look older than his actual age. Very intelligent and rigidly honorable. Should be sagelike or priestly in appearance with an especially long beard. If weapons are in the portrait, he uses a bolas and a morningstar — neither of them heavy as he is not a line fighter (he will wear only partial or light armor).

In German: I let him cite "Stabreime" from time to time to introduce an old fashioned feeling. In the beginning (in Hamels court) he will stumble over the rimes but in the end he gained full authority. The biggest problem was to translate "I am a Witness" as there is no German equivalent having both flavors of jurisprudence and religion. I decided for introducing "Der Fels" -> "Ich bin Skalde - ich bin der Fels", as the mountain/rock is something set in stone.

In Greek: His translation was not as deliberate as the german one, since Middle-Age greek poetry sounds rather not-wesnoth. However his vocabulary is extended and more formal compared to the other characters. As for the "witness" part, it was a nightmare. I resorted to using an ancient greek term for witness (Προΐστωρ, Proistor) as a title (you know, like Steelclad, or Loremaster),which sounds really majestic, but translated the "I am a witness" part as it was, since the whole point was that, err, he was actually witnessing things.

=== Ratheln ===
Description: Mage, sarcastic. A human mage and teacher of magic. A scholar but a very tough and experienced one — not someone to cross lightly. Good at heart but gruff and a bit irascible.

=== Perrin ===
Description: The master of a school of magic. Wise and kindly. An Albus Dumbledore in Wesnoth, basically.

=== Ollin ===
Description: Human peasant, refugee.

In German: He may sound like a bondman/villain using a lot the term "Herr", which sounds VERY servile and is not used any more nowadays but in posh haberdashers.

=== Dulcatulos ===
Description: The dwarfish captain of Kal Kartha's guard at the West Gate, a good dwarf unknowingly working for an evil master. Aiglondur's counterpart, but a few years older and not as intelligent. Dwarvish soldier, battling through the ranks to become Captain, not born to be one.

=== Karrag ===
Description: An evil dwarf-lord who uses a mask and spells of illusion to conceal the fact that he has in fact become a lich. The wrongness in this portrait should be much clearer.

=== Pelias ===
Description: A human lancer, who serves effectively as a royal courier, even if Tallin doesn't have the title of king.

=== Elurin ===
Description: An Elvish Rider of high rank.

=== Marth Tak ===
Description: An allied orcish chieftain, member of the Northern Alliance

=== Hamel ===
Description: The same person as in Northern Rebirth, but a bit settled.

=== Locations ===
A particularly difficult point in the greek translation was the name of the city "Dwarven Doors". I finally went for Θυρόγαια (pronounced Thy-ró-ge-a), a word comprising of θυρα, ancient greek for door, and Gaia, greek for earth, soil. It should mean something like Doors of the earth, and it is the coolest-sounding word that still resembles an actual city name.

== The South Guard ==
{{TranslatorCampaignBox
| story = South_Guard_story
| walkthrough = TheSouthGuard
| dialogue = CampaignDialogue:TSG
| translatorlist= CampaignSouthGuard
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10323
| forumresource = Derived from story not the
| campnick = tsg
| maintainer = zookeeper
}}
=== Deoran ===
Description: Young, of noble birth - therefore he may appear a bit naiv in the beginning and may use a higher type of language - anyhow, he is a soldier at least by heart.

=== Sir Gerrick ===
Description: Deorans mentor. An officer and hero - rather by deeds than birth; speaking blunt, if needed.

=== Urza Afalas ===
Description: An outlaw-leader forced into the forests longing to return to civilization, even with lying. Somehow a normal person having a peasant's cunning.

=== Ethiliel ===
Description: A big-headed female elf, disciple of Mebrin. Becoming more and more self-reliant and shakes off the elvish racist arrogance while living through its foul outcomes (Mal M'Brin, Itheldens War)

=== Minister Hylas ===
Description: A white priest - high language.

In German: There seems to be no good translation for the term "minister". Neither "Vikar", "Pfarrer", "Pastor", "Prediger" works properly imaging a fighting priest. I went for "Vater" / "Bruder" or "Pater" (as in "Bruder Tuck" or "Pater Brown") and put it terminological close to moncs.

=== Jarek ===
Description: A cavalry soldier.

=== Urza Mathin ===
Description: An outlaw-leader without the brain of Urza Afalas.

=== Queen Xeila ===
Description: Queen of a Naga-clan, hostile and speaking "snakish" with interfering "Hss"-sounds.

In German: The "Hss"-sounds translate quite nice by lisping - but go for "Harry-Potter-Parselmouth" rather than "Terry-Pratchetts-Igor".

=== Mal M'Brin ===
Description: An elvish sage gone rogue and undead.

=== Ithelden ===
Description: Elvish marshal, waging the "righteous war" against the humans.

=== Eliomir ===
Description: Elvish ranger, helping Sir Gerrick.

=== Eltenmir ===

== Eastern Invasion ==
{{TranslatorCampaignBox
| story = EiStoryLine
| walkthrough = TheEasternInvasion
| dialogue = CampaignDialogue:EI
| translatorlist= CampaignEasternInvasion
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10325
| forumresource = yet no used
| campnick = ei
| maintainer = zookeeper
}}
=== Dacyn ===
Description: Dacyn is a 92 years old white mage [http://forums.wesnoth.org/viewtopic.php?f=9&t=32728&p=473275&hilit=+Eastern+Invasion+#p473275].

=== Gweddry ===
The main character of the campaign. A new commander who hasn't been trained much yet at the beginning of the campaign. Rather cowardly to start with, but experiences character growth.

=== Owaec ===
Commander of the northern outpost. A noble of the horse clans.

=== Mal-Ravanal ===
The ancient lich behind the titular Eastern Invasion and the main antagonist of the campaign. Had previously competed with Dacyn to be an advisor to the king, but then became evil and fled. In other words, the two of them have past history with one another. Mal-Ravanal is extremely powerful and can teleport. His forces also appear in Dead Water, although he himself does not.

=== Konrad II ===
King of Wesnoth at the time; successor to Haldric VII (according to the timeline). Uses the [https://en.wikipedia.org/wiki/Royal_we royal "we"] in his speech.

=== Grug ===
An ogre. Has rather stupid-sounding speech as many ogres do. In Grug's case, the stupidity comes from his mangling of syntax. Think like Yoda from Star Wars, except stupid instead of wise.

=== Engineer ===
An unnamed Red Mage found in the Northlands. Speaks with a heavy accent. Offers to blow up a bridge in exchange for protection.

=== Pelathsil ===
A xenophobic dwarf who fights against all who would encroach on what he considers dwarvish land. In English, he has the usual Scottish accent that most dwarves have.

=== Mal-Skraat ===
One of Mal-Ravanal's underlings; seeks a promotion.

=== Volas ===
Some random elf that Gweddry can possibly come across, depending on which branching story path he takes.

=== Elandin ===
A xenophobic elf who fights against all who would encroach on what he considers elvish land.

== Dead Water ==
{{TranslatorCampaignBox
| story = Dead_Water_Story
| walkthrough = Dead_Water
| dialogue = CampaignDialogue:DW
| translatorlist= CampaignDeadWater
| discuss = http://forums.wesnoth.org/viewtopic.php?f=45&t=31304
| forumresource = Derived from story not the
| campnick = dw
| maintainer = beetlenaut
}}
In German, I felt the need to introduce some more vocabulary related to the sea; mainly, I used Gwabbo for this purpose.

=== Kai Krellis ===
Kai Krellis is the son of the King of the merfolk, who succeeds to the crown while being a child.

In German, I changed the writing to "Cai", as Kai is a common Christian name in German. But changing it to "Cai" looks old fashioned and it still sounds as an abbreviation to "Kaiser" (which is "Emperor" in German). So it fits quite nice.

=== Cylanna ===
A mermaid priestess and a counselor to Kai Krellis. Should speak a high language.

=== Gwabbo ===
A veteran of the merfolk fighters and a counselor to Kai Krellis.

In German I added some "nautical wording" and went for a little north-german dialect as this one is related to the sea.

=== Growloff ===
A weired person that tames sea monsters and argues resembling "Hagrid" from "Harry Potter".

=== Tyegëa ===
A mermaid high-priestess and the unknown grandmother to Kai Krellis. She is a bit unpredictable.

In German I gave her a snobby attitude. Discussing with Cylanna, I tried to assume that they both still remember having a long lasting tiff (tendency "mother-in-law", or "elder sister").

=== Inky ===
Growloff's favourite "pet", after the former's defeat, the latter is given to Kai Krellis' army and lives in the royal castle till his old age.

=== Caladon ===
A middle aged Silver Mage who desires the Sword of Fire and to retrieve it he's willing to do anything.

=== Keshan ===
A drake who has been prisoner of the Saurians and later disowned by his fellows for being merfolk's ally. He later comes back to Bilheld and becomes Drake's new leader.

=== Siddry ===
A poacher, also kept prisoner by Saurians along with Keshan and Teelöa, who later helps merfolk to retrieve the Fire Sword.

== Son of the Black Eye ==
{{TranslatorCampaignBox
| story = Black_Eye_story
| walkthrough = SonOfThe_BlackEye
| dialogue = CampaignDialogue:SOTBE
| translatorlist= CampaignSonoftheBlackEye
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10491
| forumresource = http://forums.wesnoth.org/viewtopic.php?f=9&t=21569
| campnick = sotbe
| maintainer = zookeeper
}}

With Version 1.12, the city of "Dorset" is renamed to [http://forum.wesnoth.org/viewtopic.php?t=38187&p=548643#p549735 "Dorest"].

=== Kapou'e ===
Description: He is an young orkish Chief, more intelligent than his fellow orks, but as ruthless as they are. A natural leader.

In German: For Orks in general, I tried to stick to main clauses and tried to avoid subordinate clauses. Additionally, I aimed for ominous mystery-style-sentences (like "Wer Wind sät, wird Sturm ernten"). Of course, orcs are not "noble savages" (like Karl May's Winnetou), but the rest fits the "Böser Indianer"-stereotype (tribes, fighting each other, physical strength as important social attribute, brutality) from Karl May. Anyhow, this should not be overdone :).

=== Grüü ===
Description: Grüü is a young troll who decides to join Kapoue's quest.

In German, he uses a simplified and often wrong grammar that fits his simple approaches to reality, e.g. shown by Grüü in the scenario "Back home": "Of course. Squash elves, squash undead, squash dwarves, squash humans. Squash them all, very good plan!". He seems sometimes a little bit childish and simple, so the terms "tut/tun" and "kaputt" are used a lot.

=== Howgarth III ===
Description: "Big, fairly pot-bellied, but powerful. Bearded, something of a wild man. [..] Wielding a big greatsword or claymore. Possibly leather armour, or leather-with-plates - fairly simple. He's Northern Alliance, which (depending on which version of the history you're working from) means he's from a relatively poor group descended from slaves, and fairly far from civilisation." [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=21569&st=0&sk=t&sd=a&start=81] "Howgarth. I was aiming for a slightly wild look, a bruiser rather than a thinker." [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=21569&st=0&sk=t&sd=a&start=97]

=== Shan Taum ===
Description: "Arrogant, but smart orc with leadership qualities - opponent of Kapou'e and his late father; uses an offending and arrogant language."

=== Flar'Tar ===
Partner to Al'Brock. Prejudiced against trolls. Occasionally puts himself in more dangerous situations than Al'Brock does.

=== Vrag ===
Description: A smart goblin rider, who favors evasive maneuvers over battles and is a counselor to Kapou'e.

=== Earl Lanbec'h ===
The main antagonist of the campaign.

=== Al'Brock ===
Description: "Flar'Tar came out tall and relatively skinny. I'd like Al'Brock to be short and dumpy, just for contrasting purposes =D" [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=21569&st=0&sk=t&sd=a&start=81] "He looks like the 'GET OFF MOI LAAAAND' type =D" [http://www.wesnoth.org/forum/viewtopic.php?f=9&t=21569&st=0&sk=t&sd=a&start=87]

=== Vraurk ===
Description: A young orcish shaman

=== Pirk ===
Description: An orcish shaman

=== Gork ===
Description: An old orcish shaman

=== Jetto ===
Description: An assassin.

== Under the Burning Sun ==
{{TranslatorCampaignBox
| story = UtBSStoryLine
| walkthrough = UnderTheBurningSuns
| dialogue = CampaignDialogue:UTBS
| translatorlist= CampaignBurningSuns
| discuss = http://www.wesnoth.org/forum/viewtopic.php?f=22&t=10491
| forumresource = yet no used
| campnick = utbs
| maintainer = cycholka
}}
=== Kaleh ===
=== Nym ===
=== Zhul ===
=== Garak ===
=== Elyssa ===
=== Eloh/Yechnagoth ===
=== Melusand ===
=== Esanoo ===
=== The Explorer ===
=== Grog ===
=== Rogrimir ===
=== Cloaked Figure/Keratur ===
=== Tanstafaal ===
=== Sergeant Durstrag ===

== See Also ==

* [[ProseStyle | Some introductory words on translation philosophy]]
* [[MainlineCampaigns | Mainline campaign hub for walkthrough, storyline and the developers discussion thread]]
* [[CampaignDialogue | Central campaign dialogue page]]
* [[RaceDescriptions-backstory | Background on Wesnoths races]] but see also [[Races]] and of course their [[SecretLore | Secret Lore]]
* [[History_of_Wesnoth]]
* Detailed campaign analysis by the stalled (?) Lore Collection Project [http://www.wesnoth.org/forum/viewtopic.php?f=32&t=26384 here] or [http://forums.wesnoth.org/viewtopic.php?f=32&t=26112&start=15 here] - preliminary analyses exist for [http://www.wesnoth.org/forum/download/file.php?id=34642 EI], [http://www.wesnoth.org/forum/download/file.php?id=33837 SoF], [http://www.wesnoth.org/forum/download/file.php?id=33835 DiD], [http://www.wesnoth.org/forum/download/file.php?id=32683 TRoW].
* some technical help for translators might provide [[TranslatorShellscript]]
* [[TextdomainStatus]] will tell you, if it makes sense to translate a certain mainline campaign now, or to wait.
* Some entry points for forum discussions (from translators of different languages) about "how to translate (Wose, Naga, Merfolk, etc.)" can be found in the [[TranslatorsGuide]] or use the [http://forums.wesnoth.org/search.php "search"] function of the forum board.
* An IC-Counterpart of this page is [[WesnothFigures]] (stub).

[[Category:World of Wesnoth]]
[[Category:Translations]]
[[Category:Writing]]

A Tale Of Two Brothers Story

2024-06-29T16:03:46Z

Octalot: Note story changes in 1.16 and 1.18

This is the story of [[A Tale of Two Brothers]].

Maghre was a sleepy, remote village in the western reaches of the Kingdom of Wesnoth. The wars and intrigue that plagued the Kingdom passed Maghre by with little impact. This sleepy existence was shattered when a dark mage moved into the area and began preying on the populace to satisfy the needs of his black magic.

Baran was a local mage whom the people looked up to. He organized the villagers' defense but knew that old swords and pitchforks would not be enough. Baran contacted his brother Arvith for help; Arvith was the leader of a small troop of horsemen earning a living as caravan guards.

Arvith heeded his brother's call and he and his company rushed to Baran's assistance.

In 1.18, Baran contacts Arvith by the village's non-magical trade beacon. Older versions involved a magical amulet.

== Rooting Out a Mage ==
Baran and Arvith set off to eliminate Mordak the Dark Mage. The plan is for Arvith's forces to distract Mordak's while Baran surprises the mage with a magical attack. All is going according to plan until Baran is captured and taken away to the north.

== The Chase ==

Arvith's chase of Baran's kidnappers leads him to an elf-occupied forest. The leader of the elves refuses passage and Arvith's company must defeat them before continuing after Baran's kidnappers. Arvith captures one of the kidnappers who reveals where Baran is being held.

Since 1.16, the elves' motivation is that they suspect Baran of himself being a necromancer. In older versions, the leader of the elves had made a pact with the necromancers.

== Guarded Castle ==

With a mixture of force and cunning, Arvith's men break into the castle and rescue Baran.

== Return to the Village ==

Upon returning to Maghre, the brothers discover than an opportunistic Orcish Warlord has attacked. The village's defenders were depleted by the departure of Arvith's expedition and are barely holding. After subduing the Warlord, Baran is faced with leading his village through a time of rebuilding. It would be an arduous task, but Baran knew his brother would always respond to his call should the need arise once more.

[[Category:Campaigns - Story Material]]
[[Category:Campaigns - A Tale of Two Brothers]]

ATaleOfTwoBrothers

2024-06-29T15:52:00Z

Octalot: Cut and paste 1.19's note about the hard difficulty

This is an easy campaign that is mainly intended to introduce new players to the mechanics of the game. This page is the walkthrough for it; for a recap of the story, see [[A Tale Of Two Brothers Story]]. For the campaign's dialogue, see [[CampaignDialogue:TB]].

This campaign has only two difficulties, but with a large difference between them. The Grand Knight difficulty is intended for players who’ve already completed Liberty and Heir to the Throne.

== Rooting Out a Mage ==
* '''Objectives:''' Defeat Mordak (L2 Dark Sorcerer)
* '''Lose if:''' Arvith dies or turns run out
* '''Turns:''' 18/18 (Easy/Hard)
* '''Starting Gold:''' 40/25 (Easy/Hard)
* '''Starting units:''' Arvith and lots of loyal units

This is a plain vanilla scenario, with no surprise occurrences: Just you and the enemy leader and both your recruits. You start with a sizable advantage, though, in the form of a good number of loyal units: 4 Spearmen, 3 Horsemen, a Footpad and a Bowman (in addition to Arvith). If you level them up and recall them later, they will save you a lot of gold and enable recruiting more units throughout the game.

A fundamental rule of any scenario is to pay attention to the time-of-day. All the enemy units are chaotic, and your spearmen, bowmen, and horsemen are lawful, while your footpads are chaotic. You will have the advantage during the day in general, and footpads can protect your other units at night.

It pays to read each unit's description, especially their resistances. Some of them are obvious, like skeletons being resistant to piercing and weak to impact (it's hard to stab a bone!). But the resistances on other units are not so intuitive. In fact, impact damage is more effective than pierce against both ghouls and bats. In addition to being your only chaotic units, footpads are also your only source of impact damage, so they can actually be stronger attackers than spearmen or bowmen in this match up.

On Easy difficulty, you should be able to win this first scenario with just your initial loyal contingent and no recruiting. Hang back enough that the Undead can't reach you the first night, then attack at dawn:

{| class="wikitable"
|-
! Consider attacking the... !! Mostly with...
|-
| Dark Adepts || Spearmen
|-
| Bats || Bowmen, Footpads
|-
| Skeletons || Footpads
|}

... and you can use your Horsemen on already-wounded units, when a single hit can finish them off.

Alternatively, if you send 3 Horsemen North to lure the Undead, and the rest of your force Northwest along the river, you may be able to ambush Mordak in his castle.

Also note that there is a keep with 3 castle tiles between your starting keep and the enemy keep. For a very aggressive strategy, you can move Arvith to that position early and recruit your reinforcements there instead of at your starting keep, so they can get into combat sooner.

On Hard difficulty, you're probably going to need reinforcements: Footpads are especially useful, since the rest of your army depends on pierce attacks and struggles against skeletons. Horsemen can also be useful if you want to distract most of the enemy with your other units and send all your horse units to assassinate Mordak early.

You might have an opportunity to send in your Horsemen and take out Mordak around halfway through the scenario - if the Undead focus on a certain path of attack. But it is probably wiser to spend the extra turns gather XP towards leveling-up units with blade attacks (Horsemen to Knights, Spearmen to Swordsmen). Leveling up Arvith to a Paladin gives you access to an Arcane attack which is even more effective than impact against skeletons and ghosts. A leveled-up Footpad or two by the [[#Guarded_Castle| third scenario]] would also prove useful.

Mordak is very passive, unlike the leaders in some other scenarios. He will never attack or move. This makes it easy to give the kill to the exact unit that you want.

== The Chase ==
* '''Objectives:''' Get through the woods to the kidnappers, then defeat the Dark Adept
* '''Lose if:''' Arvith dies or turns run out
* '''Turns:''' 28/24 (easy/hard)
* '''Starting units:''' Arvith and a horseman
* '''Other:''' Remember the passwords

Time of day is less important in this scenario, since the elves are neutral and they will attack you so early that you won't really be able to choose when to engage with them. Here, managing terrain and maneuverability is more important. The elvish riders have much more movement than your units, and they are not slowed down by forests. They also get very high defense in forests, unlike your own horsemen. Use zone of control to block the riders' movement, and try to lure them onto open terrain so you can take them down quickly.

Knowing each unit's resistances is again very important. You are only facing one wose, but it will give you a very hard time if you haven't yet leveled any spearmen or horsemen to get bladed weapons. The elvish riders are weak to piercing, just like your own horsemen, so spearmen and bowmen are useful against them.

The elves are too aggressive for their own good. Keep your units in line- or V-shaped formations with one or both ends anchored on a village; Elvish Scouts/Riders will charge in by ones or twos and you should be able to swarm them.

Again, avoid fighting the undead at the north map edge at night, unless you have a lot of footpads. Otherwise, let your main body catch up with your cavalry and surround them. When you prevail, make a note of the passwords.

On hard, a good strategy is to recruit lots of Spearmen and Bowmen to wound the Elvish Riders, and finish them off with your leader or another Knight. Ideally, you'll have a Paladin by the time you hit the undead in the next scenario. Paladins are your only possible source of arcane damage, which is very useful against undead.

It might be a good idea to sacrifice some units as a distraction, but make sure you move enough troops north to take out the undead leader, which will be guarded by two skeletons (''easy mode'') or two revenants (''hard mode'').

At the start of the scenario, the top half of the map is covered by shroud. After you move a unit far enough north, it reveals a dark adept and his bodyguards, and then they will start advancing toward you. Killing the dark adept ends the scenario, but he hides behind the skeletons as much as possible so you will probably need to take them out too.

Keep in mind that Arvith can recruit at the elf leader's keep, so if you've managed your income well, you can recruit some last minute footpads before you face the skeletons. Recalling loyal units at the start of this scenario helps save up enough gold to get those new recruits 10-20 turns later.

Make sure to write down the passwords at the end of the scenario! They change every time you play through, and being able to remember them is significant for the next scenario.

On ''easy'', an Iron Mauler named Brena will show up at the end of the scenario and ask to join your party. Iron Maulers are powerful level-3 units with a very strong melee attack and good physical defense, but they lack a ranged attack, and are slow (base movement of 4). Whether it's best to accept him or not depends on your playing style, but if you think you can live with his very limited speed, letting Brena join up is probably for the best. If you do accept him, he will be available in the next scenario as a loyal unit. If you refuse his offer, he will give you 70 pieces of gold. Regardless of the choice you make, you will be given the ability to recruit Heavy Infantryman units.

== Guarded Castle ==

* '''Objectives:''' Defeat the L2 Dark Sorcerer to get the key, then have Arvith unlock Baran's cell
* '''Lose if:''' Arvith dies or turns run out
* '''Turns:''' 30/24 (Easy/Hard)
* '''Starting Gold:''' 170/120 (Easy/Hard)
* '''Starting units:''' Arvith

You start outside an enlarged castle - not 7 hexes, but half the map.

'''Castle exterior'''

The outside is just countryside with villages and nothing of interest... except for stealthy patrols. Those will accost you on two occasions, demanding a password. If you give the correct passwords, you will be left alone to prepare your troops undisturbed. However, if you're up to the challenge, and want to earn some extra experience for your units, you can deliberately give the wrong passwords, and then you'll fight the guards that asked you for them. On Hard, these are:

* First patrol: Assassin (L3), 3 Bandits (L2).
* Second patrol: Rogue (L2), 2 Bandits, 1 Thug.

If you decide to fight the first group of guards, you will be visited by the second group on turn 6, otherwise the second group will come at turn 3. Also, these fights will afford the enemy leader enough gold for a few additional recruits.

'''Castle interior'''

Inside the castle inside you have Orcish guard at the entrance: 2 Orc Warriors, 3 Orcish Grunts (on Hard), and Mordak's mournful brother, an L2 Dark Sorcerer, is deeper inside, with 100 gold to recruit Undead. Nothing you can't handle!

The castle inside is Dark, meaning that units fight as if it were night at all times of day. Fortunately, though, the position of most of the guards is still lit, and so are the castle hexes just below from which you will be attacking.

At the Northeastern edge you have a chamber with a treasure chest (50 gold); at the Northwestern edge is the cell holding Baran.

Note that the undead units will come out and attack you normally, but each orc unit will stay still until you put a unit within its movement range. This lets you take your time and lure them out into the open during daytime to take them out more easily.

'''Strategy'''

On _Easy difficulty_, one castleful of recruits should be enough to complete the scenario. Experiment with Heavy Infantry - they do well against both Orcs and Undead.

Inside the castle, you can get to Baran's cell without fighting the enemy leader, but you have to kill the leader for the key anyway. After killing the enemy leader, you're given a few extra turns, which should be enough time to move Arvith west to Baran's cell, and a fast unit east to get the treasure chest.

On _Hard difficulty_, you don't have any Heavy Infantry to hide behind. Footpads / Outlaws, are somewhat of a replacement - dealing impact damage, positively effected by the dim castle atmosphere, and even with high defense. However - they have a knack for succumbing to a sequence of several hits, dying faster than you would expect. So - if you're recruiting mostly, you'll need some cannon fodder.

Whether you've recruited or recalled - better have a Footpad or Outlaw. You can send it as a feint to one side of the castle, keeping some Undead busy chasing it, while moving Knights up along the other side (the Sorcerer's chamber has two entrances); and if you manage to level your Footpad up, you will enjoy its defensive capabilities in the final scenario.

There are several villages outside of the castle, so if you still have many loyal units you can actually accumulate some gold while you fight the orcs, and then Arvith can quickly return to his keep to recruit reinforcements for taking out the leader. One effective strategy is recruiting bowmen at first for the orcs, and then footpads later for the undead.

== Return to the Village ==
* '''Objectives:''' Find out what is happening in the village then defeat the Orcish Warlord
* '''Lose if:''' Arvith or Baran die or turns run out
* '''Turns:''' 26/24 (easy/hard)
* '''Starting units:''' Arvith and Baran

There is no need to conserve gold in the last scenario, so recall all of your veterans. Loyal units are also less relevant, since it is a fast scenario without too many villages.

North of your starting keep is your ally, the beleaguered defenders of Maghre. East of you, across the mountains, is the enemy, a lvl 3 orc warlord who recruits lots of tough lvl 2 orcish warriors and crossbowmen.

There are 2 basic approaches to this scenario. One is to take your army northward ASAP to save the defenders before they are overwhelmed by orcs, then turn east and finish off the orcish leader. The other is to abandon your ally, sneak your army around the southeast side of the map, and surprise attack the orc leader once his forces are all far away crushing your ally. If you have a lot of gold to spare, you can also try a combination of the two. There is no penalty for your ally dying in this scenario; only Baran and Arvith need to survive. Keep in mind that Horsemen and their advancements cannot travel through mountains.

Baran is a lvl 2 Red Mage, and his attack is Magical, so he is very good for attacking enemies in villages or other high defense terrain, just be sure to protect him from counterattack!

Time of day is again very important, especially for taking out the orc leader. He does ridiculous damage at night, so try using some sacrificial unit to lure him on to low-defense terrain at Dawn or Morning and then swarm him with Lawful units.

[[Category:Campaigns - Walkthroughs]]
[[Category:Campaigns - A Tale of Two Brothers]]

StandardLocationFilter

2024-05-22T21:57:59Z

Octalot: /* Attributes */ Clarify that find_in is looking for x,y= rather than location_id=

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

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

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

==Notes about Coordinate Usage==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Directions ==

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

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

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

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

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

That will cause the matched units to turn around.

== Filtering Terrains ==

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

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

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

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

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

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

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

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

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

== Wesnoth Formula Language ==

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

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

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

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

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

== See Also ==

* [[FilterWML]]

[[Category: WML Reference]]

1.19 Roadmap

2024-05-11T10:10:11Z

Octalot: /* 1.19.20 */ Search for unused translatable strings

TerrainCodesWML

2024-04-29T05:30:47Z

Octalot: /* Decoding the Terrain Codes */ P is used for Portals

{{WML Tags}}

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

== Terrain strings ==

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

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

Starting positions are defined by a number followed by 1 space and then the terrain string.

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

=== Terrain Table ===

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

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

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

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

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

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

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

== Terrain codes in map data ==

This is not the Matrix. You normally don't need to look at encoded maps. However, it can be beneficial and useful for more advanced users to understand the usage of terrain strings in raw map file.

The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
** {{DevFeature1.13|12}} These keys are now deprecated and will be ignored if present. The blank line mentioned below is not required if these keys are absent.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of terrain codes.
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each terrain code will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''.
** For Wesnoth 1.12.6, ''n'' = 1, 2, 3, ... 9, and the multiplayer server will refuse maps with more than 9 sides.
** For Wesnoth 1.14, more than 9 sides can work, discussion https://r.wesnoth.org/t48129 and https://r.wesnoth.org/t48082
* {{DevFeature1.13|12}} In addition to side numbers, terrains may be prefixed by any number of strings (which should consist of alphanumeric characters only, including underscores). All names and side numbers must be delimited by spaces and are separated from the actual terrain code by an additional space.
** This is broken according to https://r.wesnoth.org/p627595

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

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

[[Category: WML Reference]]

TerrainCodesWML

2024-04-29T04:49:48Z

Octalot: /* Decoding the Terrain Codes */ Q is used for elevation overlays

{{WML Tags}}

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

== Terrain strings ==

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

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

Starting positions are defined by a number followed by 1 space and then the terrain string.

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

=== Terrain Table ===

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

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

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

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

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

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

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

== Terrain codes in map data ==

This is not the Matrix. You normally don't need to look at encoded maps. However, it can be beneficial and useful for more advanced users to understand the usage of terrain strings in raw map file.

The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
** {{DevFeature1.13|12}} These keys are now deprecated and will be ignored if present. The blank line mentioned below is not required if these keys are absent.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of terrain codes.
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each terrain code will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''.
** For Wesnoth 1.12.6, ''n'' = 1, 2, 3, ... 9, and the multiplayer server will refuse maps with more than 9 sides.
** For Wesnoth 1.14, more than 9 sides can work, discussion https://r.wesnoth.org/t48129 and https://r.wesnoth.org/t48082
* {{DevFeature1.13|12}} In addition to side numbers, terrains may be prefixed by any number of strings (which should consist of alphanumeric characters only, including underscores). All names and side numbers must be delimited by spaces and are separated from the actual terrain code by an additional space.
** This is broken according to https://r.wesnoth.org/p627595

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

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

[[Category: WML Reference]]

GermanTranslation

2024-04-04T11:38:56Z

Octalot: /* Aktuelles Übersetzungsteam */ Add Aurelix to the current translator list

== Das Wort zum Geleit ==
Diese Seite dient dazu, die Anstrengungen des deutschen Übersetzungsteams besser zu koordinieren. Die Übersetzung ist deshalb in Unterpunkte aufgespalten worden, so dass für alle Teammitglieder und Besucher ersichtlich ist, ob momentan bereits jemand an der Übersetzung für eine Textdomain arbeitet, und ob es einen Ansprechpartner für einzelne Kampagnen gibt.

Übersetzungen basieren üblicherweise auf der aktuellen ''stable'' Version, bitte benutzt nicht die Dateien der ''master'' Version.

Es ist außerdem sinnvoll vor dem Übersetzen einmal einen Blick auf [[GermanTranslationUnitNames|diese Liste]] mit stilistischen Hinweisen, Standardbegriffen, Einheitennahmen, etc. zu werfen.

== Aktuelles Übersetzungsteam ==
{|
!style="text-align:left"| Name
!style="text-align:left"| Nickname
!style="text-align:left"| Emailadresse
!style="text-align:left"| Anm.
|-
|
|aurelix
|im Discord erreichbar
|
|-
|Aaron Winter
|bitron / byteron
|im Discord erreichbar
|
|-
|
|mcpgal
|im Discord erreichbar
|
|-
|Steve Cotton
|octalot
|im Discord erreichbar
|
|-
|
|s1m0n
|im Discord erreichbar
|
|-
|Iwan Gabovitch
|qubodup
|im Discord erreichbar
|
|}

== Inaktive Übersetzer ==
{|
!style="text-align:left"| Name
!style="text-align:left"| Nickname
!style="text-align:left"| Emailadresse
!style="text-align:left"| Anm.
|-
|Severin Glöckner
|Sevu / Shiki
|im Forum & Discord erreichbar
|Vize-Maintainer
|-
|-
|Christoph Berg
|chrber
|Christoph DOT Berg AT kpm-sport DOT de
|
|-
|Nils Kneuper
|Ivanovic
|crazy-ivanovic AT gmx DOT net
|
|-
|Oliver Lange
|Crommy
|oli-lange äd web Pünktchen de
|
|-
|Tobias Schönau
|SonIcco
|tobias DOT schoenau AT eagerbyte DOT com
|
|-
| –
|Drakefriend
|
|
|-
|David Philippi
|Torangan
|david AT torangan DOT de
|
|-
|Elias Pschernig
|Allefant
|allefant AT gmail DOT com
|
|-
| -
|vonHalenbach
|vonHalenbach Ät users.sourceforge punkt net
|
|-
|Sven Priess
|Gedankenschinder
|mail AT svenpriess DOT de
|
|-
|Andre Schmidt
|schmidta
|andre AT schmidtandre DOT de
|
|-
|Jan Greve
|Jan`ger
|Jan AT Phreeknet DOT org
|
|-
|Andre
|Hochbass
|hochbass AT gmx DOT de
|
|-
|Boris Stumm
|quijote_
|wesnoth AT bstumm DOT de
|
|-
|Jan-Heiner Laberenz
|jan-heiner
|jan-heiner AT arcor DOT de
|
|-
|Kai Ensenbach
| -
| -
|
|-
|Onno Tasler
|belchion
|onno.tasler AT spamfence DOT net
|
|-
|Ruben Philipp
|The Very Uhu
|the15thfeuergnu AT yahoo DOT de
|
|-
|Stefan
|Termimad
|steve213 AT gmx DOT de
|
|-
|Stephan Grochtmann
|Schattenstephan
|Schattenstephan AT gmx DOT com
|
|-
| -
|ammoq
|erich DOT kitzmueller AT chello DOT at
|
|-
|Arndt
| -
|muehlenf AT igi DOT tugraz DOT at
|
|-
| -
|ja-el
| -
|
|-
|Jonas
| -
|celb AT gmx DOT at
|
|-
|Michael Vondung
| -
| -
|
|-
|Olaf M.
|milamber
| -
|
|-
|Uz-Friedrich Valentin
|Uz
|uz_ AT users DOT sourceforge DOT net
|
|-
|Rhonda D'Vine
|Rhonda
|rhonda AT deb DOT at
|
|-
|Christoph Lange
|madelgijs
|christoph DOT t DOT lange AT googlemail DOT com
|
|-
|
|-
|
|Flatterdorsch
|im Discord erreichbar
|
|-
|
|Nevermore901
|im Discord erreichbar
|
|}

== Status der Übersetzung ==
Wenn bei einer Kampagne für einen Betreuer ein '''-''' angegeben ist, bedeutet das nicht, dass sie gar nicht übersetzt wird. Dies wird von einem der aktiven Übersetzer übernommen, wenn dieser Zeit findet.

Wünschenswert wäre es jedoch, wenn sich neue Übersetzer finden würden, die die Betreung einer dieser Kampagnen übernehmen würden damit die Qualität auch weiterhin auf dem hohen Niveau gesichert ist.

{|border="1"
!Name
![[GettextForTranslators#Textdomains_and_getting_the_files_to_translate | Textdomain]]
!Betreuer
!Nutzerversion 1.16
!Entwicklerversion 1.17
|-
!colspan="6"|Offizielle Kampagnen
|-
|Das Zepter des Feuers
|wesnoth-sof
| -
|Fertig
|-
|Die dunklen Künste
|wesnoth-did
| -
|Fertig
|-
|Die Geschichte zweier Brüder
|wesnoth-tb
| -
|Fertig
|-
|Die Südwacht
|wesnoth-tsg
| -
|Fertig
|-
|Der Thronerbe
|wesnoth-httt
| -
|Fertig
|-
|Der Aufstieg Wesnoths
|wesnoth-trow
| -
|Fertig
|-
|Freiheit
|wesnoth-l
| -
|Fertig
|-
|Invasion der Finsternis
|wesnoth-ei
| -
| -
|-
|Schwarzauges Sohn
|wesnoth-sotbe
| -
|Fertig
|-
|Unter brennenden Sonnen
|wesnoth-utbs
|octalot
|In Nachbearbeitung
|-
|Winds of Fate
|wesnoth-wof
|qubodup
|Korrektur
|-
|Wiedergeburt des Nordens
|wesnoth-nr
| -
| -
|-
|Der Hammer von Thursagan
|wesnoth-thot
| -
|Fertig
|-
|Die Legende von Wesmere
|wesnoth-low
| -
| -
|-
|Delfadors Memoiren
|wesnoth-dm
| -
|Unklar
|-
|Stille Wasser
|wesnoth-dw
| -
|Fertig
|-
|Geheimnisse der Ahnen
|wesnoth-sota
| -
|Fertig
|-
|World Conquest
|wesnoth-wc
| -
|Unklar
|große Korrektur des englische Text gebietet
|-
!colspan="6"|Einheiten
|-
|Alle Einheiten
|wesnoth-units
| -
|Fertig
|-
!colspan="6"|Sonstiges
|-
|Einführung
|wesnoth-tutorial
| -
|Fertig
|-
|Eine neue Heimat
|wesnoth-anl
| -
|Fertig
|-
|Steam Store Seite
| -
| -
| -
|-
!colspan="6"|Benutzeroberfläche
|-
|Allgemeines
|wesnoth
|Bitron
|Fertig
|-
|Allgemeines
|wesnoth-lib
|Bitron
|Fertig
|-
|Hilfe
|wesnoth-help
| -
|Fertig
|-
|Mehrspieler
|wesnoth-multiplayer
| -
|Fertig
|-
|Editor
|wesnoth-editor
|Bitron
|Fertig
|-
!colspan="6"|Dokumentation
|-
|Handbuch
|wesnoth-manual
| -
|Fertig
|-
|Handbuchseiten
|wesnoth-manpages
| -
|Fertig
|-
|}

== Statusbeschreibungen ==
{| style="margin-top: 1em; text-align: left" border="1"
! scope="row"| Unklar
| Die Zuweisung der Übersetzung ist unklar. Sie kann also bereits vergeben sein oder an einen neuen Übersetzer vergeben werden.
|-
! scope="row"| Nicht Begonnen
| Es werden noch ÜbersetzerInnen gesucht. Bei Interesse einfach melden.
|-
! scope="row"| In Bearbeitung
| An der Übersetzung wird gearbeitet.
|-
! scope="row"| Korrektur
| Die Übersetzung ist beim Korrekturlesen.
|-
! scope="row"| Fertig
| Die Übersetzung ist abgeschlossen.
|-
! scope="row"| In Nachbearbeitung
| Größtenteils fertig, nur einzelne Teile fehlen.
|}

== Gesucht ==

Manche Kampagnen haben bessere Übersetzungen als andere. An manchen Stellen ist die Übersetzung zwischendurch unpassend, teils fehlt der Kontextbezug. Auch Rechtschreibfehler existieren, welche jedem zweiten Spieler auffallen, jedoch niemand meldet oder korrigiert. Und manchmal ist der Wortlaut der Übersetzung auch einfach zu sehr ans Englische angelehnt.

Es werden Leute gesucht, welche Interesse daran haben eine Kampagne zu übernehmen und auszugestalten. Dies kann z.B. heißen, die Kampagne selber zu spielen und dabei Screenshots von seltsamen Dialogen zu machen um diese später auszubessern, oder andere Dinge zu ändern. Ggf. findet man dabei auch Sachen welche man im Englischen ebenfalls ändern könnte, sei es der Text, die Story oder anderes.
Es ist verlockend, relativ wortgetreu zu Übersetzen, aber freiere Übersetzungen sind in der Regel deutlich besser.

Aus technischer Sicht kann nur eine Person an einer Textdomain arbeiten, ohne dass man Gefahr läuft, Änderungen von jmd. anderem zu überschreiben(*). Am besten du sagst Bescheid wenn du daran arbeitest, und wirst in die Liste eingetragen.

Es wäre schön wenn du eine Kampagne langfristig übernehmen würdest und als Ansprechpartner für Spieler zu Verfügung stehst.

(*): Die Vorteile von Git, welches erlaubt, dass mehrere Personen gleichzeitig an etwas arbeiten, wobei jeder seine eigene Version der Datei ohne die Änderungen des Anderen hat, lassen sich hier nur umständlich anwenden. Es kann nur eine neuste Version der Datei geben. Poeditor [nicht zu Verwechseln mit Poedit] ist ein webbasiertes Tool, welches es erlaubt, dass mehrere Leute gleichzeitig dieselbe Datei bearbeiten.

Einzelne Fehler können, nach einer Registrierung im Wiki, auch hier eingetragen werden, am besten mit einer korrigierten Variante:
[[GermanTranslationErrors]]

== Kontakt ==

* Siehe "Aktuelles Übersetzungsteam".
* Am besten in Wesnoths Discord Server im Channel #German -> https://discord.gg/battleforwesnoth
* irc.libera.chat #wesnoth-de (irgendwer wird schon da sein, einfach warten und hin und wieder was sagen, das sollte in dem leisen Kanal auffallen...)
* Der Discord und IRC Channel sind mit einem Bot verbunden.

== Siehe auch ==
* [[GermanTranslationErrors|Fehler]] - Eine Sammlung der bekannten und noch nicht behobenen Fehler.
* [[GermanTranslationUnitNames|Liste mit Standardbegriffen, Einheitennamen, usw]]
* [https://www.wesnoth.org/gettext/?view=langs&version=master&lang=de Statistiken der deutschen Übersetzung (Entwicklerversion)]
* [https://www.wesnoth.org/gettext/?view=langs&version=branch&lang=de Statistiken der deutschen Übersetzung (aktuelle Nutzerversion)]
* [[GettextForTranslators|Gettext für Übersetzer (nur auf Englisch)]] - Werkzeugen für .po Dateien (Poedit, Lokalize, uzw)
* [[WesnothTranslations]] - Liste der Wikiseiten aller Wesnoth-Übersetzungen

== Sonstiges ==
* [[GermanTranslationMPCampaign|Die Chroniken von Elvenmar ~ Das zweite Zeitalter (Mehrspieler Kampagne)]] - nicht mehr betreut
* [[Zeit der Mythen]]: Übersetzung des Add-Ons Era of Myths

[[Category:Translations]]

AbilitiesWML

2024-04-02T00:23:16Z

Octalot: /* [damage_type] */ The known bug won't be fixed in 1.18, so won't cause OOS

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for [plague], [heal_on_hit], and [swarm] can be placed in the [abilities] tag. These "weapon specials as abilities" will give that weapon special to all attacks the unit has if matches with [filter_student/opponent/etc][filter_weapon].
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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].
* {{anchor|filter_base_value|'''[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. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''add''': adds to resistance. Is ignored when '''sub''' is present.
* '''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.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. Work like '''[filter_self]''' of specific weapon special.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes what '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes what '''[attacks]''' and '''[chance_to_hit]'''
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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
* '''[damage_type]''' {{DevFeature1.17|23}}: type of damage changed by replacement or addition of another type
Any other tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].

=== 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. Is ignored when '''sub''' is present.
* '''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 ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

{{note|In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.}}

=== 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

2024-03-31T09:42:35Z

Octalot: /* [damage_type] special */ Don't use in multiplayer, as OOS is expected

{{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.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== 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}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for [plague], [heal_on_hit], and [swarm] can be placed in the [abilities] tag. These "weapon specials as abilities" will give that weapon special to all attacks the unit has if matches with [filter_student/opponent/etc][filter_weapon].
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== 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; if affect_self=yes, this is also unit who has 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. If omitted, the ability will be a hidden 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. You should thus set ''female_name'' as well!
* '''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. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[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].
* {{anchor|filter_base_value|'''[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. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''add''': adds to resistance. Is ignored when '''sub''' is present.
* '''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.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== 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.
* '''add''': the cumulative percentage bonus to damage. Is ignored when '''sub''' is present.
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== 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][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon special abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. Work like '''[filter_self]''' of specific weapon special.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* 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, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes what '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes what '''[attacks]''' and '''[chance_to_hit]'''
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes what '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[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
* '''[damage_type]''' {{DevFeature1.17|23}}: type of damage changed by replacement or addition of another type
Any other tag is valid, but will result in a 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. If omitted, the special will be hidden from the player.
* '''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].
* {{anchor|filter_self|'''[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.
* {{anchor|filter_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.
* {{anchor|filter_attacker|'''[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.
* {{anchor|filter_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.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].

=== 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. Is ignored when '''sub''' is present.
* '''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 ''[damage_type]'' special {{DevFeature1.17|23}} ===

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

{{note|Don't use [damage_type] in multiplayer for Wesnoth 1.18. It's getting bugfixes during the 1.18 stable branch, which will cause out of sync errors in multiplayer.}}

=== 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]]

CampaignDialogue

2024-03-07T17:43:21Z

Octalot: Mention the POT files

{| style="float:right"
|
__TOC__
|}

This page is the hub for the transcription of campaign dialogue into the wiki as a resource for writers. As such, it consists entirely of spoilers.

These Wiki pages aren't automatically updated when the text in the campaign changes. However, files with all the text in each campaign are automatically generated as part of the support for translations. [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-tutorial/wesnoth-tutorial.pot Link to the one for the tutorial]. The others can be found by following that link and then replacing both ''tutorial''s in the URL with the campaign acronym (completely lowercase).

The campaigns are ordered chronologically. Each has a relevant year (generally beginning) listed.

==Tutorial==
''Main article: [[CampaignDialogue:Tutorial]]

==The Rise Of Wesnoth==
''Main article: [[CampaignDialogue:TROW]]

5 BW - 1 YW.

==Winds of Fate==
''Main article: [[CampaignDialogue:WoF]]

3-4 YW.

==An Orcish Incursion==
''Main Article: [[CampaignDialogue:AOI]]

8-9 YW.

==Legend of Wesmere==
''Main Article: [[CampaignDialogue:LOW]]

12-93 YW.

==Secrets of the Ancients==
''Main article: [[CampaignDialogue:SOTA]]

23 YW.

==Sceptre of Fire==
''Main article: [[CampaignDialogue:SOF]]

25-40 YW.

==Two Brothers==
''Main article: [[CampaignDialogue:TB1.9]]

363 YW.

==Descent into Darkness==
''Main article: [[CampaignDialogue:DID]]

389 YW.

==Delfador's Memoirs==
''Main article: [[CampaignDialogue:DM]]

468-470 YW.

==Liberty==
''Main Article: [[CampaignDialogue:L]]

501 YW.

==Heir to the Throne==
''Main Article: [[CampaignDialogue:HttT]]

517-518 YW.

==Northern Rebirth==
''Main Article: [[CampaignDialogue:NR]]

534-535 YW.

==The Hammer of Thursagan==
''Main Article: [[CampaignDialogue:THOT]]

550-551 YW.

==The South Guard==
''Main Article: [[CampaignDialogue:TSG]]

607-608 YW.

==Eastern Invasion==
''Main Article: [[CampaignDialogue:EI]]

625-627 YW.

==Dead Water==
''Main Article: [[CampaignDialogue:DW]]

626 YW.

==Son of the Black Eye==
''Main Article: [[CampaignDialogue:SOTBE]]

742-758 YW.

==Under the Burning Suns==
''Main article: [[CampaignDialogue:UTBS]]

??? AF.

[[Category:Create|*]]
[[Category:Writing|*]]
[[Category:Campaigns|*]]

WesnothTranslationsHowTo

2024-03-02T15:54:14Z

Octalot: /* Tools */ updating all the files needs "po4a-update" and "manual" too

This page contains information on how-to translate and submit translation updates.

== How to submit your translations ==

Important: Please '''do not submit translations as pull requests''' on the Wesnoth github repository site. While that seems like a good idea, it causes potential complications that we cannot always easily resolve. As a result, we cannot accept translations submitted via pull request and will close such PRs immediately.

'' ''' Translation Maintainers ''' ''

The translation maintainers should send the updated/new translation
po-files to the language coordinator:
Ivanovic (crazy-ivanovic AT gmx DOT net).
Additionally they have to quickly check over other people's translations
(other people translating the same language) as the other translators
(if any) will have to send their translations to their language maintainer
before inclusion in the source-code repository. You should also subscribe to the [http://www.wesnoth.org/wiki/WesnothTranslations#Mailing_List wesnoth-i18n mailinglist].

Send the files as an archive containing the complete .po files (no .mo or .gmo files) and ensure that they follow the directory structure used in version control. For example, the archive with the German (de) translations should therefore be structured as follows:
wesnoth/de.po
wesnoth-httt/de.po
wesnoth-tutorial/de.po
etc.

'' ''' Translators ''' ''

The other translators (those who are not maintainers) should contact
the maintainer for their language to see if there is some work to do.
After you have done some work on the translation you should email it
to your language maintainer. They will then (if needed) check it over
before sending it on to the language coordinators. A list of all translators
currently working on a language is found on each language page.

'' ''' NEW Translators ''' ''

If you want to help out with the translation of an language already started on,
contact the translation maintainer for the language.
If you want to start translation of Wesnoth to a new language,
first contact Ivanovic.
And then just follow the instructions written in '' Translators '' .

== Translations How-To ==

If you are a translator, see [[GettextForTranslators]] for more information.

If you are a developer or UMC author, gettext internals for Wesnoth are discussed here: [[GettextForWesnothDevelopers]]. For UMC authors, the tool for generating .po files is linked to from [[GettextForWesnothDevelopers#Generating the_.pot_and_.po_files_for_UMC]].

=== Files ===

We will use the Swedish (sv) language and the ''wesnoth-editor'' domain as an example. There are three important files for each text-domain:
* ''wesnoth-editor/wesnoth-editor.pot'' file, which is a template containing all the strings used in the domain, but with empty strings instead of a translation. You can see how a ''.pot'' file looks like in the repository : [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/wesnoth-editor.pot#L50 Current repository version].
* ''wesnoth-editor/sv.po'', the file containing the translation, you can see how a ''.po'' file looks like in the repository: [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/sv.po#L50 Current repository version].
* ''{translations_dir}/sv/LC_MESSAGES/wesnoth-editor.mo'', which is a binary version of <lang>.po that the game will use for efficiency reasons. This is not found in the repo, but is created during compilation of the game.

The first of these files, we update every once in a while, when there is new or modified text,
for instance when a new campaign scenario hits the repository.

=== Tools ===

For the main Wesnoth repository, the build system can handle updating these files.
* Using SCons, '''scons pot-update po4a-update manual''' will do everything. This can be done without building the Wesnoth executables.
** '''scons -j8 pot-update po4a-update manual''' is quicker, because it does it in parallel.
** '''scons -j8 pot-update''' will do all in-game text, omitting the manpages and manual
* Using CMake, enable '''ENABLE_NLS''' and '''ENABLE_POT_UPDATE_TARGET''', then run '''make -C po pot-update''' to generate the files.

Some notes on the individual steps that are used during the build:

C++ and Python files are parsed with ''xgettext'', WML and Lua files are parsed with ''wmlxgettext''. The results are then combined to generate the ''.pot'' file.

Then, ''msgmerge'' is used to merge this new "state of the game strings" with your current translations, and generate a new, up-to-date, ''sv.po''.

Then, a tool called ''msgfmt'' is called, which generates a new ''wesnoth.mo'' file from your ''wesnoth.po'' file, which will be used by the game once installed.

=== Summary ===

That was for the "Big Picture".
But you really just need to be concerned with the po file:
translating new strings, checking "fuzzy" entries.
We can handle the administrative tasks of updating etc.
You really don't need to bother with any of these commands, unless you want to compile .mo files to check in-game.

Ivanovic is now responsible for integrating translations into Wesnoth, with the help of Torangan and ott.
You should contact Ivanovic (crazy-ivanovic AT gmx DOT net), and he'll put them in the game.

== Specifying typefaces and fonts for a translation ==

Translations in a language which use characters outside of the Latin, Greek and Cyrillic character sets may want to specify different typefaces. There are some translatable strings in data/hardwired/fonts.cfg which specify the fonts to use; these strings appear in the ''wesnoth'' text domain, and can be configured by putting the required fonts' names as the translations.

Note the documentation in data/hardwired/fonts.cfg.

== See Also ==
* [[GettextForTranslators]]
* [[WesnothTranslations]]
* [[TranslatorsGuide]]
* [http://gettext.wesnoth.org Translation statistics]

[[Category:Translations]]

EffectWML

2024-03-02T14:50:06Z

Octalot: /* [effect]apply_to=variation */ Remove mention of the type+variation bug, it was fixed in 1.14.10 and 1.15.3

{{WML Tags}}

== [effect] ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [[DirectActionsWML#.5Bobject.5D|[object]]] with a limited ''duration'' to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects. New effect types can be added with [[LuaWML/Units#wesnoth.effects]].
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* {{anchor|apply_to-new_attack|'''new_attack'''}}: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* {{anchor|apply_to-remove_attacks|'''remove_attacks'''}}: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* {{anchor|apply_to-attack|'''attack'''}}: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_range''': change the attack range. The standard values are '''ranged''' and '''melee'''.
** '''set_icon''': change the attack's icon.
** {{anchor|set_specials|'''[set_specials]'''}}: change the attack's specials. The specials to add are given exactly as in the [[AbilitiesWML#The_.5Bspecials.5D_tag|[specials]]] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
**** {{DevFeature1.15|3}} A deprecation warning is triggered unless the '''mode''' attribute is set, although the effect will still be '''replace'''. This is to allow the default to change in the 1.17.x series.
** '''remove_specials''': remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''increase_attacks_used''': {{DevFeature1.17|13}} increases the attack points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''set_attacks_used''' {{DevFeature1.17|13}} like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
* {{anchor|apply_to-max_attacks|'''max_attacks'''}}: {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* {{anchor|apply_to-hitpoints|'''hitpoints'''}}: modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* {{anchor|apply_to-movement|'''movement'''}}: modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
** '''apply_to_vision''': {{DevFeature1.15|13}} if set to '''yes''' (which is the default), then the vision points will change by the same amount. See [[#Movement_and_Vision|Movement and Vision]].
* {{anchor|apply_to-vision|'''vision'''}}: {{DevFeature1.13|2}} modifies the unit's vision points. Note: this has side effects described in [[#Movement_and_Vision|Movement and Vision]].
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* {{anchor|apply_to-jamming|'''jamming'''}}: {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* {{anchor|apply_to-experience|'''experience'''}}: affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* {{anchor|apply_to-max_experience|'''max_experience'''}}: affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
** '''set''': current max XP is set to a specific value.
* {{anchor|apply_to-loyal|'''loyal'''}}: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* {{anchor|apply_to-fearless|'''fearless'''}}: Add/Remove fearless attribute.
** '''set''': new value for fearless (boolean). Defaults to '''yes'''.
* {{anchor|apply_to-healthy|'''healthy'''}}: Add/Remove healthy attribute.
** '''set''': new value for healthy (boolean). Defaults to '''yes'''.
* {{anchor|apply_to_movement_costs|'''movement_costs'''}}: speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[movement_costs]''': a subtag that describes the new movement costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes".
* {{anchor|apply_to-vision_costs|'''vision_costs'''}}: vision through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[vision_costs]''': a subtag that describes the new vision costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes".
* {{anchor|apply_to-jamming_costs|'''jamming_costs'''}}: jamming through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to '''no'''.
** '''[jamming_costs]''': a subtag that describes the new jamming costs just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes".
* {{anchor|apply_to-defense|'''defense'''}}: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to '''no'''.
** '''[defense]''': a subtag that describes the new defense just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes".
* {{anchor|apply_to-resistance|'''resistance'''}}: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to '''no'''.
** '''[resistance]''': a subtag that describes the new resistance just like under [[UnitsWML#.5Bmovetype.5D|[movetype]]] if replace is set to "yes".
* {{anchor|apply_to-variation|'''variation'''}}: switches the unit into one of its variations. Similar to the '''type''' effect below, this might not behave properly outside of [advancement].
** '''name''': the id of the variation to invoke.
* {{anchor|apply_to-type|'''type'''}}: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
** '''name''': the id of the unit_type to invoke.
* {{anchor|apply_to-status|'''status'''}}: modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* {{anchor|apply_to-zoc|'''zoc'''}}: toggle the zone of control.
** '''value''': new value for zoc (boolean).
* {{anchor|apply_to-profile|'''profile'''}}: customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
** '''[special_note]''': {{DevFeature1.15|2}} Adds or removes a special note in the unit's description.
*** '''remove''': A boolean value specifying whether to add or remove a note. Defaults to '''no'''.
*** '''note''' (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
*** Since the tag name is the same, notes can also be added using the standard special note macros, eg '''{NOTE_HEALS}'''.
*** To remove a note, you can simply suffix '''{NOTE_REMOVE}''' to the regular note macro, eg '''{NOTE_HEALS}{NOTE_REMOVE}'''.
* {{anchor|apply_to-new_ability|'''new_ability'''}}: Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. {{DevFeature1.17|17}} This is now deprecated, use [filter_ability] instead.
** {{DevFeature1.17|17}} '''[filter_ability]''': A subtag that contains the ability definitions like type of abilities, id, or other attributes like affect_self or [affect_adjacent] but not generic filter.
* {{anchor|apply_to-new_animation|'''new_animation'''}}: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See [[AnimationWML]] for further reference.
* {{anchor|apply_to-image_mod|'''image_mod'''}}: modify the image path function ([[ImagePathFunctions]]) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
** If needed, you can also define new [[GameConfigWML#Color_Palettes|color palettes]] here.
* {{anchor|apply_to-ellipse|'''ellipse'''}}: Change the image used for the unit's ellipse.
** '''ellipse''' : the new image to use. Can be set to "none" to disable the ellipse.
* {{anchor|apply_to-halp|'''halo'''}}: Change the image used for the unit's halo.
** '''halo''': the new image to use.
* {{anchor|apply_to-overlay|'''overlay'''}}: Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
**'''remove''': {{DevFeature1.15|0}} the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
** {{DevFeature1.15|0}} [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
* {{anchor|apply_to-recall_cost|'''recall_cost'''}}: {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* {{anchor|apply_to-alignment|'''alignment'''}}: {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* {{anchor|apply_to-new_advancement|'''new_advancement'''}}: {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* {{anchor|apply_to-remove_advancement|'''remove_advancement'''}}: {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed
* {{anchor|apply_to-level|'''level'''}}: {{DevFeature1.17|15}} change a unit's level. '''Note:''' this key is incompatible with ''times=per level''; if this combination is used, the engine reports a warning and uses ''times=1'' as fallback value
** '''set''': set level to a specific value; can be positive or negative, but not a percentage
** '''increase''': alter level relative to original value; can be positive or negative, but not a percentage

== Movement and Vision ==

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:
* It has (effectively) 5 mp and 5 vp.
* After (mp + 1), it will have 6 mp and 6 vp.
* After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

{{DevFeature1.15|13}}, [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:
* After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
* After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.
[effect]
apply_to=movement
increase=50%
[/effect]

=== Examples ===
== Effect: apply_to = new_animation ==
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.

[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y = 1,5
[/filter]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]

If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable = stored_unit
[/store_unit]
[set_variables]
name = stored_unit.modifications.object
[value]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable = stored_unit
[/unstore_unit]
[/event]

== Where to Use Effects ==

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: '''[trait]''', '''[object]''', or '''[advancement]'''. Which tag to use depends on the goal of the modification.

* [[UnitsWML#.5Btrait.5D|Traits]] are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
* [[UnitTypeWML#After_max_level_advancement_.28AMLA.29|Advancements]] are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
* [[DirectActionsWML#.5Bobject.5D|Objects]] are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in '''[modify_unit]''' [[DirectActionsWML#.5Bmodify_unit.5D|ActionWML]] to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

== See Also ==

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

[[Category: WML Reference]]

GettextForTranslators

2024-02-21T11:52:16Z

Octalot: /* Format strings */ Add a new section of basic rules

== Gettext for translators ==

=== For the engine and mainline campaigns ===

The target audience of this page is anyone who wants to help with a language that's already in the list on [[WesnothTranslations]]. The files for these languages have already been set up, someone is already the maintainer, and the pages linked from that page say where to go and how to introduce yourself to the team. The effort is split with separate teams for each language, and each team can have its own working style.

Because each team can work in different ways, please do not submit translations as pull requests on Github. While that seems like a good idea, it causes potential complications, so we ask that everyone talks to their language's maintainer and submits changes in the way that the maintainer decides to use.

If you're starting a completely new translation, or taking over as the maintainer of a translation, then the next place to read would be the [[WesnothTranslationsHowTo]] page.

=== For add-ons ===

The target audience is anyone who wants to help translate an add-on, assuming the add-on's maintainer has already set it up for translation. Translations are shipped with the add-on, so it's up to the maintainer to choose how to receive the files and organise the workflow.

To translate an add-on, skip to the [[#Files_for_add-ons|Files for add-ons]] section.

If you are the maintainer of the add-on, the instructions for setting up the translation are on [[GettextForWesnothDevelopers]].

== Textdomains and getting the files to translate ==

The progress for each language is shown on https://www.wesnoth.org/gettext/ . Click on your language, and you'll see a breakdown into sections ''(textdomains)'', such as
* wesnoth
* wesnoth-editor
* wesnoth-help
* wesnoth-units
* wesnoth-lib (contains strings shared by game and editor)
* wesnoth-httt (the Heir to the Throne campaign)
* wesnoth-utbs (the Under the Burning Suns campaign)
* etc

Each has a separate file with a .po extension. For example, the Swedish translation has abbreviation ''sv'', and its translation of the editor's strings is in ''wesnoth-editor/sv.po''. The page on https://www.wesnoth.org/gettext/?view=langs&version=branch&lang=sv links to the current version in the main Git repository.

Although the .po files contain text, please send the complete files as email attachments (or whichever method your team uses), rather than cutting and pasting lines from the file into an email. The translated strings are
very sensitive to formatting and whitespace changes.

=== Files when running the game ===

When the game runs it will look for an .mo file, for example ''translations/sv/LC_MESSAGES/wesnoth-editor.mo''. If you want to test your text in-game and you're happy to modify your installation:

* Some .po editors can automatically generate .mo files.
* Deleting the .mo file will make the game look for ''translations/wesnoth-editor/sv.po'' instead.

However you can also send your untested .po file to the maintainer and they should check that it looks correct in-game.

=== Files for add-ons ===

This assumes the add-on has .po files rather than .mo files. The engine supports both, but only .po are editable. For example, an add-on called Son of Haldric that has a Swedish translation would likely store it in:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric'' is where all files from the add-on are stored
* ''translations/wesnoth-Son_of_Haldric'' is configured by the maintainer
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

If it's been set up for translation but hasn't yet been translated into Swedish, it may instead have a file called ''wesnoth-Son_of_Haldric.pot''. This is a template which you can copy to "sv.po", however first try opening the .pot file directly in your [[#Tools|translation tool]], as the it will likely prompt you to create a translation from the template.

After editing the file, either refresh the cache (press F5 on the title screen) or restart Wesnoth to see the changes.

Warning: files in the add-on directory will be overwritten or deleted if it's updated using the in-game Add-on Manager, so keep backups of files in a separate directory.

== How to translate ==

Now that you have the .po file to edit, it can be worked on using any of the programs listed in the [[#Tools|Tools section]]. The general preference in Wesnoth seems to be towards Poedit, but they all work on the same .po file format.

The general concept is that the GUI will show the strings in English, along with a text-box to add the translation.

=== Hints ===

In addition to the English text, most strings have some additional information which in Poedit will be shown in the bottom-right of the screen. For example, the tutorial's "... this quintain!" has "[message]: speaker=Delfador", meaning that it's [[InterfaceActionsWML#.5Bmessage.5D|said]] by the unit with id "Delfador". Sometimes the hint is less obvious, often lines will be "[message]: speaker=unit", normally meaning the unit whose move, attack, or death has triggered an event.

Some strings will have additional hints, such as "Addressing Konrad" or "Addressing Li'sar". The level of detail varies a lot between campaigns, please don't be afraid to point out when something needs to be improved.

The .po files also say which source file the string came from, in Poedit 3.4 this is found in a right-click menu (right-click on a string in the top-left pane of the GUI).

=== Carets ===

These lines in the tutorial both have the hint "[message]: speaker=student"; they're spoken by Konrad and Li'sar respectively:
* "A quintain? You want me to fight a dummy?"
* "female^A quintain? You want me to fight a dummy?"

When an English string has a caret (the ^ symbol) in it, then everything before the first caret is removed before showing it to the player. In the translated strings, leave out everything before the caret.

These caret hints are very commonly used in Wesnoth for strings where the translation may depend on the gender of the speaker, or the person spoken to. They're also used for strings such as "Prefs section^General", where the string is the label on the "general preferences" tab, not a military rank.

=== Warnings ===

Some editors can automatically detect inconsistencies between the English and the translated text, for example if the original ends with a full-stop and the translation ends with an exclamation mark. Poedit defaults to showing these above even the untranslated strings, but these can be false-positives - generally someone's already looked at these and decided that the translated text is better as-is.

=== Fuzzy strings ===

One of the downsides of Gettext is that spelling and grammar corrections in the English text break the link between the original and the translated text. The tools that generate .po files try to recover from this by using the old translation for the new English text, and marking the string as ''fuzzy''; in Poedit these are sorted below the completely untranslated strings, and shown with the "Needs Work" button lit along with a note about what the previous English text was.

Be wary, this mechanism can also generate incorrect suggestions. For example it may decide that "Landar left $number troops to guard the council" is a spelling correction of "Kalenz left $number troops to guard the council".

== Parts to leave untranslated ==

Some translatable strings mix text to be translated with placeholders that are handled by the engine before displaying the text to the player. The text of the placeholder needs to be left untranslated.

=== Dollar signs ===

Most placeholders start with a dollar sign (<code>$</code>), for example, <code>$number</code> or <code>$gold_amount</code>. The details are in [[SyntaxWML]], but for translation the general rules are:

Characters that appear in placeholders are letters, numbers, square brackets, underscores, full stops and question marks.

* After a dollar sign, every character in the list above is part of the placeholder.
* A space ends the placeholder, and the space is also displayed to the player.
* A vertical bar (<code>|</code>) ends the placeholder, and the vertical bar isn't displayed to the player.
* If you need to put a full stop or question mark immediately after a placeholder that doesn't end with a vertical bar, add a vertical bar to separate them.
* A dollar sign at the end of the string, or directly followed by a pipe (<code>$|</code>), is displayed as a dollar sign.
* Obscure cases should have a hint about the string.

==== More details about dollar signs ====

Anything that isn't covered by the basic rules in the previous section should have a po hint.

A format variable is introduced by a dollar sign (<code>$</code>), which is followed by a unique name. The name can be any sequence of letters, numbers, and underscores. For example, <code>$number</code>, <code>$gold_amount</code>, and <code>$1st_name</code> are all valid examples of placeholders. This unique name '''''must not be translated''''' and should be rendered exactly as-is in the translated text, as the engine needs to be able to match it exactly to substitute in the correct replacement.

In some rare cases, the name may also contain a period (<code>.</code>) or square brackets (<code>[]</code>). For example, <code>$houses[3].title</code> would be valid. Names can also be nested within each other, so <code>$house_$colour</code> and <code>$houses[$n]</code> can also occasionally occur.

The <code>|</code> character is used if the end of the name needs to be disambiguated (because the following character could otherwise also be part of the name). For example, in <code>$some|where</code>, the variable is only <code>$some|</code>. This can also be used in nesting, so you could have something complicated like <code>$the_$colour|_town.houses[$n].owner</code>.

The <code>?</code> character following a variable indicates a default value. The text between the <code>?</code> and the following <code>|</code> should be translated as normal, but the framing characters (<code>?|</code>) and the preceding variable name '''''must''''' be left untouched.

You may also see a dollar sign immediately followed by a parenthesized formula from time to time (for example, <code>$($n + $m)</code>. In this case, the entire formula should be left untouched in the translated text. Formulas normally only evaluate to numerical values. They should not be used very often in translatable strings, however.

A dollar sign at the end of the string, or directly followed by a pipe (<code>$|</code>), is displayed as just a dollar sign and does not indicate any formatting placeholder.

=== Markup ===

Some strings contain formatting markup. This comes in two styles. The most common is [[Pango formatting|Pango markup]], which is an HTML-like formatting language. The other is the custom help page markup, which looks superficially similar but is rather different, and is documented here.

Like HTML, help markup consists of tags enclosed in angle brackets (eg <code><italic></code>), with a slash added to the closing tag. The difference lies in what comes between the tags, which takes a key=value format where the value is usually enclosed in single quotes. There can be multiple key=value pairs, separated by spaces. Generally, all of that should be left untouched, with the exception of the <code>text</code> key. If you see something like <code><italic>text='some text'</italic></code>, the only part that should be translated is "some text". Or if you see <code><nowiki><ref>dst='movement' text='zones of control'</ref></nowiki></code>, then only "zones of control" should be translated, and the rest should be left untouched.

== FAQ ==
* '''What are "Plural-forms"?'''
** Some languages have different word forms for different numbers of things (for example in English we have "1 thing" but "2 thing'''s'''"). The rules are different for different languages. You can find them [http://translate.sourceforge.net/wiki/l10n/pluralforms here].
* '''How do I use ' within a single-quote delimited string when translating text= in help screen texts?'''
** Add a backslash before it, however the preferred method now is to use [[Typography_Style_Guide#Character_Usage_Summary|typographic punctuation]] instead.
* '''What should I do with strings like "Prefs section^General"?'''
** There are ambiguous strings which should be translated in a different way depending on where they appear. For example, we have "General" in the preferences as "General preferences" and we can also have "a General". These strings can have different translations for a given language, so we use "context" to solve this. The prefix only tries to give a hint about the string, and should be not translated, for example:
msgid "Prefs section^General"
msgstr "General"
* '''My PO file already has that translated to "Prefs section^General", should it work?'''
** It does, but probably shouldn't. For strings that have no translation, the part before the "^" will be removed. This is also done when the PO's msgstr is exactly the same as the msgid, which will later break if someone makes any change to the text. For example:
# wrong but seems to work (shows as "Root")
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Root"
# wrong and shows as "filesystem_path_system^Wurzel"
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Wurzel"
* '''Who can I ask for further information?'''
** You can ask in [[Support|Discord or IRC]]. Ping Ivanovic in Discord's #development or IRC's #wesnoth-dev channel. If you don't like IRC, send a mail to crazy-ivanovic AT gmx DOT net, or pm him (ivanovic) at the forum.
* '''Why is the diff from the previous version so huge? I have only made a small change to the .po file with poedit.'''
** When saving .po file poedit unwraps all strings. Usually, all .po files are wrapped at 80 characters so if you want smaller diffs and less merge conflicts you can execute the following commands each time after editing with poedit:

msgattrib file.po > file.po1
mv file.po1 file.po

== Tools ==

There are several tools to work with .po files:
* [https://pofile.net/free-po-editor Free PO editor] (Web based)
* [http://userbase.kde.org/Lokalize Lokalize] (Unix KDE) (Formerly known as [https://directory.fsf.org/wiki/KBabel KBabel])
* [https://kate-editor.org/ Kate] (Unix KDE)
* [http://wiki.gnome.org/Apps/Gtranslator GTranslator] (Unix Gnome)
* [http://virtaal.translatehouse.org Virtaal] (Multiplatform)
* [http://www.poedit.net/ poEdit] (Multiplatform)
* [http://www.gnu.org/software/emacs/emacs.html Emacs with po-mode] (Multiplatform)
* [http://www.vim.org/ Vim] with [http://www.vim.org/scripts/script.php?script_id=695 PO plug-in] (Multiplatform)

Of course, you can edit po files with any UTF-8 capable text editor, but the tools listed above have great advantages over any text editor regarding .po translation, like going to next fuzzy/untranslated string, searching only in specific fields (msgid, msgstr, comment), ...

== See Also ==

* [[WesnothTranslations]]
* [[WesnothTranslationsHowTo]]
* [[GettextForWesnothDevelopers]]
* [[TranslatorShellscript]]
* [http://www.wesnoth.org/gettext/ Translation statistics]

[[Category:Translations]]

GettextForTranslators

2024-02-21T11:01:32Z

Octalot: /* How to translate */ Describe the po hints and caret hints

== Gettext for translators ==

=== For the engine and mainline campaigns ===

The target audience of this page is anyone who wants to help with a language that's already in the list on [[WesnothTranslations]]. The files for these languages have already been set up, someone is already the maintainer, and the pages linked from that page say where to go and how to introduce yourself to the team. The effort is split with separate teams for each language, and each team can have its own working style.

Because each team can work in different ways, please do not submit translations as pull requests on Github. While that seems like a good idea, it causes potential complications, so we ask that everyone talks to their language's maintainer and submits changes in the way that the maintainer decides to use.

If you're starting a completely new translation, or taking over as the maintainer of a translation, then the next place to read would be the [[WesnothTranslationsHowTo]] page.

=== For add-ons ===

The target audience is anyone who wants to help translate an add-on, assuming the add-on's maintainer has already set it up for translation. Translations are shipped with the add-on, so it's up to the maintainer to choose how to receive the files and organise the workflow.

To translate an add-on, skip to the [[#Files_for_add-ons|Files for add-ons]] section.

If you are the maintainer of the add-on, the instructions for setting up the translation are on [[GettextForWesnothDevelopers]].

== Textdomains and getting the files to translate ==

The progress for each language is shown on https://www.wesnoth.org/gettext/ . Click on your language, and you'll see a breakdown into sections ''(textdomains)'', such as
* wesnoth
* wesnoth-editor
* wesnoth-help
* wesnoth-units
* wesnoth-lib (contains strings shared by game and editor)
* wesnoth-httt (the Heir to the Throne campaign)
* wesnoth-utbs (the Under the Burning Suns campaign)
* etc

Each has a separate file with a .po extension. For example, the Swedish translation has abbreviation ''sv'', and its translation of the editor's strings is in ''wesnoth-editor/sv.po''. The page on https://www.wesnoth.org/gettext/?view=langs&version=branch&lang=sv links to the current version in the main Git repository.

Although the .po files contain text, please send the complete files as email attachments (or whichever method your team uses), rather than cutting and pasting lines from the file into an email. The translated strings are
very sensitive to formatting and whitespace changes.

=== Files when running the game ===

When the game runs it will look for an .mo file, for example ''translations/sv/LC_MESSAGES/wesnoth-editor.mo''. If you want to test your text in-game and you're happy to modify your installation:

* Some .po editors can automatically generate .mo files.
* Deleting the .mo file will make the game look for ''translations/wesnoth-editor/sv.po'' instead.

However you can also send your untested .po file to the maintainer and they should check that it looks correct in-game.

=== Files for add-ons ===

This assumes the add-on has .po files rather than .mo files. The engine supports both, but only .po are editable. For example, an add-on called Son of Haldric that has a Swedish translation would likely store it in:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric'' is where all files from the add-on are stored
* ''translations/wesnoth-Son_of_Haldric'' is configured by the maintainer
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

If it's been set up for translation but hasn't yet been translated into Swedish, it may instead have a file called ''wesnoth-Son_of_Haldric.pot''. This is a template which you can copy to "sv.po", however first try opening the .pot file directly in your [[#Tools|translation tool]], as the it will likely prompt you to create a translation from the template.

After editing the file, either refresh the cache (press F5 on the title screen) or restart Wesnoth to see the changes.

Warning: files in the add-on directory will be overwritten or deleted if it's updated using the in-game Add-on Manager, so keep backups of files in a separate directory.

== How to translate ==

Now that you have the .po file to edit, it can be worked on using any of the programs listed in the [[#Tools|Tools section]]. The general preference in Wesnoth seems to be towards Poedit, but they all work on the same .po file format.

The general concept is that the GUI will show the strings in English, along with a text-box to add the translation.

=== Hints ===

In addition to the English text, most strings have some additional information which in Poedit will be shown in the bottom-right of the screen. For example, the tutorial's "... this quintain!" has "[message]: speaker=Delfador", meaning that it's [[InterfaceActionsWML#.5Bmessage.5D|said]] by the unit with id "Delfador". Sometimes the hint is less obvious, often lines will be "[message]: speaker=unit", normally meaning the unit whose move, attack, or death has triggered an event.

Some strings will have additional hints, such as "Addressing Konrad" or "Addressing Li'sar". The level of detail varies a lot between campaigns, please don't be afraid to point out when something needs to be improved.

The .po files also say which source file the string came from, in Poedit 3.4 this is found in a right-click menu (right-click on a string in the top-left pane of the GUI).

=== Carets ===

These lines in the tutorial both have the hint "[message]: speaker=student"; they're spoken by Konrad and Li'sar respectively:
* "A quintain? You want me to fight a dummy?"
* "female^A quintain? You want me to fight a dummy?"

When an English string has a caret (the ^ symbol) in it, then everything before the first caret is removed before showing it to the player. In the translated strings, leave out everything before the caret.

These caret hints are very commonly used in Wesnoth for strings where the translation may depend on the gender of the speaker, or the person spoken to. They're also used for strings such as "Prefs section^General", where the string is the label on the "general preferences" tab, not a military rank.

=== Warnings ===

Some editors can automatically detect inconsistencies between the English and the translated text, for example if the original ends with a full-stop and the translation ends with an exclamation mark. Poedit defaults to showing these above even the untranslated strings, but these can be false-positives - generally someone's already looked at these and decided that the translated text is better as-is.

=== Fuzzy strings ===

One of the downsides of Gettext is that spelling and grammar corrections in the English text break the link between the original and the translated text. The tools that generate .po files try to recover from this by using the old translation for the new English text, and marking the string as ''fuzzy''; in Poedit these are sorted below the completely untranslated strings, and shown with the "Needs Work" button lit along with a note about what the previous English text was.

Be wary, this mechanism can also generate incorrect suggestions. For example it may decide that "Landar left $number troops to guard the council" is a spelling correction of "Kalenz left $number troops to guard the council".

== Parts to leave untranslated ==

=== Format strings ===

Some strings contain formatting markup. A few strings use the C format style, documented [https://www.gnu.org/software/gettext/manual/html_node/c_002dformat.html here], or the Lua format style, documented [https://www.lua.org/manual/5.1/manual.html#pdf-string.format here]. However, most format strings in Wesnoth use a custom formatting language, which is described here.

A format variable is introduced by a dollar sign (<code>$</code>), which is followed by a unique name. The name can be any sequence of letters, numbers, and underscores. For example, <code>$number</code>, <code>$gold_amount</code>, and <code>$1st_name</code> are all valid examples of placeholders. This unique name '''''must not be translated''''' and should be rendered exactly as-is in the translated text, as the engine needs to be able to match it exactly to substitute in the correct replacement.

In some rare cases, the name may also contain a period (<code>.</code>) or square brackets (<code>[]</code>). For example, <code>$houses[3].title</code> would be valid. Names can also be nested within each other, so <code>$house_$colour</code> and <code>$houses[$n]</code> can also occasionally occur.

The <code>|</code> character is used if the end of the name needs to be disambiguated (because the following character could otherwise also be part of the name). For example, in <code>$some|where</code>, the variable is only <code>$some|</code>. This can also be used in nesting, so you could have something complicated like <code>$the_$colour|_town.houses[$n].owner</code>.

The <code>?</code> character following a variable indicates a default value. The text between the <code>?</code> and the following <code>|</code> should be translated as normal, but the framing characters (<code>?|</code>) and the preceding variable name '''''must''''' be left untouched.

You may also see a dollar sign immediately followed by a parenthesized formula from time to time (for example, <code>$($n + $m)</code>. In this case, the entire formula should be left untouched in the translated text. Formulas normally only evaluate to numerical values. They should not be used very often in translatable strings, however.

A dollar sign at the end of the string, or directly followed by a pipe (<code>$|</code>), is displayed as just a dollar sign and does not indicate any formatting placeholder.

=== Markup ===

Some strings contain formatting markup. This comes in two styles. The most common is [[Pango formatting|Pango markup]], which is an HTML-like formatting language. The other is the custom help page markup, which looks superficially similar but is rather different, and is documented here.

Like HTML, help markup consists of tags enclosed in angle brackets (eg <code><italic></code>), with a slash added to the closing tag. The difference lies in what comes between the tags, which takes a key=value format where the value is usually enclosed in single quotes. There can be multiple key=value pairs, separated by spaces. Generally, all of that should be left untouched, with the exception of the <code>text</code> key. If you see something like <code><italic>text='some text'</italic></code>, the only part that should be translated is "some text". Or if you see <code><nowiki><ref>dst='movement' text='zones of control'</ref></nowiki></code>, then only "zones of control" should be translated, and the rest should be left untouched.

== FAQ ==
* '''What are "Plural-forms"?'''
** Some languages have different word forms for different numbers of things (for example in English we have "1 thing" but "2 thing'''s'''"). The rules are different for different languages. You can find them [http://translate.sourceforge.net/wiki/l10n/pluralforms here].
* '''How do I use ' within a single-quote delimited string when translating text= in help screen texts?'''
** Add a backslash before it, however the preferred method now is to use [[Typography_Style_Guide#Character_Usage_Summary|typographic punctuation]] instead.
* '''What should I do with strings like "Prefs section^General"?'''
** There are ambiguous strings which should be translated in a different way depending on where they appear. For example, we have "General" in the preferences as "General preferences" and we can also have "a General". These strings can have different translations for a given language, so we use "context" to solve this. The prefix only tries to give a hint about the string, and should be not translated, for example:
msgid "Prefs section^General"
msgstr "General"
* '''My PO file already has that translated to "Prefs section^General", should it work?'''
** It does, but probably shouldn't. For strings that have no translation, the part before the "^" will be removed. This is also done when the PO's msgstr is exactly the same as the msgid, which will later break if someone makes any change to the text. For example:
# wrong but seems to work (shows as "Root")
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Root"
# wrong and shows as "filesystem_path_system^Wurzel"
msgid "filesystem_path_system^Root"
msgstr "filesystem_path_system^Wurzel"
* '''Who can I ask for further information?'''
** You can ask in [[Support|Discord or IRC]]. Ping Ivanovic in Discord's #development or IRC's #wesnoth-dev channel. If you don't like IRC, send a mail to crazy-ivanovic AT gmx DOT net, or pm him (ivanovic) at the forum.
* '''Why is the diff from the previous version so huge? I have only made a small change to the .po file with poedit.'''
** When saving .po file poedit unwraps all strings. Usually, all .po files are wrapped at 80 characters so if you want smaller diffs and less merge conflicts you can execute the following commands each time after editing with poedit:

msgattrib file.po > file.po1
mv file.po1 file.po

== Tools ==

There are several tools to work with .po files:
* [https://pofile.net/free-po-editor Free PO editor] (Web based)
* [http://userbase.kde.org/Lokalize Lokalize] (Unix KDE) (Formerly known as [https://directory.fsf.org/wiki/KBabel KBabel])
* [https://kate-editor.org/ Kate] (Unix KDE)
* [http://wiki.gnome.org/Apps/Gtranslator GTranslator] (Unix Gnome)
* [http://virtaal.translatehouse.org Virtaal] (Multiplatform)
* [http://www.poedit.net/ poEdit] (Multiplatform)
* [http://www.gnu.org/software/emacs/emacs.html Emacs with po-mode] (Multiplatform)
* [http://www.vim.org/ Vim] with [http://www.vim.org/scripts/script.php?script_id=695 PO plug-in] (Multiplatform)

Of course, you can edit po files with any UTF-8 capable text editor, but the tools listed above have great advantages over any text editor regarding .po translation, like going to next fuzzy/untranslated string, searching only in specific fields (msgid, msgstr, comment), ...

== See Also ==

* [[WesnothTranslations]]
* [[WesnothTranslationsHowTo]]
* [[GettextForWesnothDevelopers]]
* [[TranslatorShellscript]]
* [http://www.wesnoth.org/gettext/ Translation statistics]

[[Category:Translations]]

AddonsWML

2024-01-23T13:02:51Z

Octalot: /* Which add-ons are active during gameplay */ Note that [units] isn't an add-on module

{{WML Tags}}
== Creating add-ons in WML ==

An add-on is defined by a directory structure, there is no tag called '''[addon]'''. The directory must contain a '''_main.cfg''', and the name of the directory is treated as its '''id'''. There are different rules for add-ons that define a custom core, which are described in [[CoreWML]] and ignored for the purposes of this page.

The description of a downloaded add-on is found in '''_info.cfg''', the data for a locally authored add-on is in '''_server.pbl''' (see [[PblWML]]).

An add-on typically contains other files, see for example [[AddonStructure]] or [[BuildingCampaignsTheCampaignFile]].

== Which add-ons are active during gameplay ==

To help prevent clashes between add-ons, when starting a scenario the engine only loads the active add-ons. An add-on is active if one or more "add-on modules" is used by the game. If a game does not use any add-on module from your add-on, then your add-on won't be parsed at all. On the other hand, if the game uses any add-on module from your add-on, then your entire add-on will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the add-on module that is to be loaded.

Several toplevel tags are used to define an "add-on module":

* [[EraWML|'''[era]''']] - A multiplayer era
* [[CampaignWML|'''[campaign]''']] - A campaign, either single-player or multiplayer
* [[ScenarioWML|'''[scenario]''']] - A campaign scenario
* [[ScenarioWML|'''[multiplayer]''']] - A multiplayer scenario
* [[ScenarioWML|'''[test]''']] - A test or demo scenario
* [[ModificationWML|'''[modification]''']] - A modification that can be selected in the campaign or multiplayer menu
* [[ModificationWML|'''[resource]''']] - A resource that can be requested by any other add-on module

Notably, that list doesn't contain the [[UnitsWML|'''[units]''']] tag. For example, a multiplayer scenario which allows the player to choose any era but has scripted events that spawn Ageless Era units needs to activate those units' add-on by loading a resource from it.

== Common Tags and Keys ==

The following tags and keys are supported in most types of addon modules:

* '''id''': The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a '''[scenario]''' and a '''[multiplayer]''' with the same ID.
* '''addon_min_version''': The minimum version of your add-on with which this content is backwards compatible. Compared 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 each others' content in order to play, and will be prompted to update otherwise.
* '''name''': (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for '''[resource]''' since it is never visible anywhere.)
* '''description''': (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for '''[resource]''', nor for '''[scenario]''' or '''[test]'''.)
* '''define'''='''''SYMBOL''''' When this addon module is active, the preprocessor symbol '''''SYMBOL''''' will be defined. See [[PreprocessorRef#.23ifdef_and_.23ifndef|ifdef]] for how this can be used to isolate parts of the file from other addon modules. Besides the addon module tag, only the tags '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Note: If for some reason you don't want to place your '''[binary_path]''' outside your '''#ifdef ''SYMBOL''''' (perhaps it's causing conflicts with other addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module tag. This looks like '''icon=data/add-ons/whatever/something.png''' – essentially, any path beginning with '''data/'''.
* '''[event]''' - An event handler that will be registered when the addon module is active. See [[EventWML]].
* '''[lua]''' - Lua code that will be run when the addon module is loaded, before the '''preload''' event is fired. See [[LuaWML]].
* '''[ai]''': Defines an AI algorithm that can be selected by players at the join game screen. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|here]] for details. This is not used in single-player.
** Note: This is not the place to define faction-specific AI parameters in an era. For that, place the '''[ai]''' tag in '''[multiplayer_side]'''.
** Note: This tag may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[options]''': Custom options. See [[OptionWML]] for details. Note: This may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[load_resource]''': Indicates a resource to load when this addon module is loaded.
** '''id''': The ID of the resource.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== See Also ==

* [[BinaryPathWML]] - Toplevel tag to define search paths for assets.
* [[UnitsWML]] - Toplevel tag to define units and unit-related data.
* [[TerrainWML]] - Toplevel tag to define terrain types.
* [[TerrainGraphicsWML]] - Toplevel tag to define how terrain is drawn.

AddonsWML

2024-01-23T12:25:18Z

Octalot: /* Creating add-ons in WML */ Correct file extension for .pbl files

{{WML Tags}}
== Creating add-ons in WML ==

An add-on is defined by a directory structure, there is no tag called '''[addon]'''. The directory must contain a '''_main.cfg''', and the name of the directory is treated as its '''id'''. There are different rules for add-ons that define a custom core, which are described in [[CoreWML]] and ignored for the purposes of this page.

The description of a downloaded add-on is found in '''_info.cfg''', the data for a locally authored add-on is in '''_server.pbl''' (see [[PblWML]]).

An add-on typically contains other files, see for example [[AddonStructure]] or [[BuildingCampaignsTheCampaignFile]].

== Which add-ons are active during gameplay ==

To help prevent clashes between add-ons, when starting a scenario the engine only loads the active add-ons. An add-on is active if one or more "add-on modules" is used by the game. If a game does not use any add-on module from your add-on, then your add-on won't be parsed at all. On the other hand, if the game uses any add-on module from your add-on, then your entire add-on will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the add-on module that is to be loaded.

Several toplevel tags are used to define an "add-on module":

* [[EraWML|'''[era]''']] - A multiplayer era
* [[CampaignWML|'''[campaign]''']] - A campaign, either single-player or multiplayer
* [[ScenarioWML|'''[scenario]''']] - A campaign scenario
* [[ScenarioWML|'''[multiplayer]''']] - A multiplayer scenario
* [[ScenarioWML|'''[test]''']] - A test or demo scenario
* [[ModificationWML|'''[modification]''']] - A modification that can be selected in the campaign or multiplayer menu
* [[ModificationWML|'''[resource]''']] - A resource that can be requested by any other addon module

== Common Tags and Keys ==

The following tags and keys are supported in most types of addon modules:

* '''id''': The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a '''[scenario]''' and a '''[multiplayer]''' with the same ID.
* '''addon_min_version''': The minimum version of your add-on with which this content is backwards compatible. Compared 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 each others' content in order to play, and will be prompted to update otherwise.
* '''name''': (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for '''[resource]''' since it is never visible anywhere.)
* '''description''': (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for '''[resource]''', nor for '''[scenario]''' or '''[test]'''.)
* '''define'''='''''SYMBOL''''' When this addon module is active, the preprocessor symbol '''''SYMBOL''''' will be defined. See [[PreprocessorRef#.23ifdef_and_.23ifndef|ifdef]] for how this can be used to isolate parts of the file from other addon modules. Besides the addon module tag, only the tags '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Note: If for some reason you don't want to place your '''[binary_path]''' outside your '''#ifdef ''SYMBOL''''' (perhaps it's causing conflicts with other addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module tag. This looks like '''icon=data/add-ons/whatever/something.png''' – essentially, any path beginning with '''data/'''.
* '''[event]''' - An event handler that will be registered when the addon module is active. See [[EventWML]].
* '''[lua]''' - Lua code that will be run when the addon module is loaded, before the '''preload''' event is fired. See [[LuaWML]].
* '''[ai]''': Defines an AI algorithm that can be selected by players at the join game screen. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|here]] for details. This is not used in single-player.
** Note: This is not the place to define faction-specific AI parameters in an era. For that, place the '''[ai]''' tag in '''[multiplayer_side]'''.
** Note: This tag may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[options]''': Custom options. See [[OptionWML]] for details. Note: This may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[load_resource]''': Indicates a resource to load when this addon module is loaded.
** '''id''': The ID of the resource.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== See Also ==

* [[BinaryPathWML]] - Toplevel tag to define search paths for assets.
* [[UnitsWML]] - Toplevel tag to define units and unit-related data.
* [[TerrainWML]] - Toplevel tag to define terrain types.
* [[TerrainGraphicsWML]] - Toplevel tag to define how terrain is drawn.

AddonsWML

2024-01-23T12:15:33Z

Octalot: /* Creating add-ons in WML */ Fixed some links

{{WML Tags}}
== Creating add-ons in WML ==

An add-on is defined by a directory structure, there is no tag called '''[addon]'''. The directory must contain a '''_main.cfg''', and the name of the directory is treated as its '''id'''. There are different rules for add-ons that define a custom core, which are described in [[CoreWML]] and ignored for the purposes of this page.

An add-on typically contains other files, see for example [[AddonStructure]] or [[BuildingCampaignsTheCampaignFile]].

The description of a downloaded add-on is found in '''_info.cfg''', the data for a locally authored add-on is in '''_server.cfg''' (see [[PblWML]]).

== Which add-ons are active during gameplay ==

To help prevent clashes between add-ons, when starting a scenario the engine only loads the active add-ons. An add-on is active if one or more "add-on modules" is used by the game. If a game does not use any add-on module from your add-on, then your add-on won't be parsed at all. On the other hand, if the game uses any add-on module from your add-on, then your entire add-on will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the add-on module that is to be loaded.

Several toplevel tags are used to define an "add-on module":

* [[EraWML|'''[era]''']] - A multiplayer era
* [[CampaignWML|'''[campaign]''']] - A campaign, either single-player or multiplayer
* [[ScenarioWML|'''[scenario]''']] - A campaign scenario
* [[ScenarioWML|'''[multiplayer]''']] - A multiplayer scenario
* [[ScenarioWML|'''[test]''']] - A test or demo scenario
* [[ModificationWML|'''[modification]''']] - A modification that can be selected in the campaign or multiplayer menu
* [[ModificationWML|'''[resource]''']] - A resource that can be requested by any other addon module

== Common Tags and Keys ==

The following tags and keys are supported in most types of addon modules:

* '''id''': The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a '''[scenario]''' and a '''[multiplayer]''' with the same ID.
* '''addon_min_version''': The minimum version of your add-on with which this content is backwards compatible. Compared 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 each others' content in order to play, and will be prompted to update otherwise.
* '''name''': (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for '''[resource]''' since it is never visible anywhere.)
* '''description''': (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for '''[resource]''', nor for '''[scenario]''' or '''[test]'''.)
* '''define'''='''''SYMBOL''''' When this addon module is active, the preprocessor symbol '''''SYMBOL''''' will be defined. See [[PreprocessorRef#.23ifdef_and_.23ifndef|ifdef]] for how this can be used to isolate parts of the file from other addon modules. Besides the addon module tag, only the tags '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Note: If for some reason you don't want to place your '''[binary_path]''' outside your '''#ifdef ''SYMBOL''''' (perhaps it's causing conflicts with other addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module tag. This looks like '''icon=data/add-ons/whatever/something.png''' – essentially, any path beginning with '''data/'''.
* '''[event]''' - An event handler that will be registered when the addon module is active. See [[EventWML]].
* '''[lua]''' - Lua code that will be run when the addon module is loaded, before the '''preload''' event is fired. See [[LuaWML]].
* '''[ai]''': Defines an AI algorithm that can be selected by players at the join game screen. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|here]] for details. This is not used in single-player.
** Note: This is not the place to define faction-specific AI parameters in an era. For that, place the '''[ai]''' tag in '''[multiplayer_side]'''.
** Note: This tag may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[options]''': Custom options. See [[OptionWML]] for details. Note: This may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[load_resource]''': Indicates a resource to load when this addon module is loaded.
** '''id''': The ID of the resource.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== See Also ==

* [[BinaryPathWML]] - Toplevel tag to define search paths for assets.
* [[UnitsWML]] - Toplevel tag to define units and unit-related data.
* [[TerrainWML]] - Toplevel tag to define terrain types.
* [[TerrainGraphicsWML]] - Toplevel tag to define how terrain is drawn.

ReferenceWML

2024-01-23T12:12:57Z

Octalot: Move AddonsWML into the "How WML works" section

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

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

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

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

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

== How WML works ==

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

== WML toplevel tags ==

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

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

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

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

== Other WML tags ==

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

== Predefined macros ==

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

== Other ==

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

== See Also ==

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

[[Category: WML Reference]]

AddonsWML

2024-01-23T12:07:41Z

Octalot: How directory structure fills the role of an [addon] tag

{{WML Tags}}
== Creating add-ons in WML ==

An add-on is defined by a directory structure, there is no tag called '''[addon]'''. The directory must contain a '''_main.cfg''', and the name of the directory is treated as its '''id'''. There are different rules for add-ons that define a custom core, which are described in [[CoreWML]] and ignored for the purposes of this page.

An add-on typically contains other files, see for example AddonStructure or BuildingCampaignsTheCampaignFile.

The description of a downloaded add-on is found in '''_info.cfg''', the data for a locally authored add-on is in '''_server.cfg''' (see [[PblWML]]).

== Which add-ons are active during gameplay ==

To help prevent clashes between add-ons, when starting a scenario the engine only loads the active add-ons. An add-on is active if one or more "add-on modules" is used by the game. If a game does not use any add-on module from your add-on, then your add-on won't be parsed at all. On the other hand, if the game uses any add-on module from your add-on, then your entire add-on will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the add-on module that is to be loaded.

Several toplevel tags are used to define an "add-on module":

* [[EraWML|'''[era]''']] - A multiplayer era
* [[CampaignWML|'''[campaign]''']] - A campaign, either single-player or multiplayer
* [[ScenarioWML|'''[scenario]''']] - A campaign scenario
* [[ScenarioWML|'''[multiplayer]''']] - A multiplayer scenario
* [[ScenarioWML|'''[test]''']] - A test or demo scenario
* [[ModificationWML|'''[modification]''']] - A modification that can be selected in the campaign or multiplayer menu
* [[ModificationWML|'''[resource]''']] - A resource that can be requested by any other addon module

== Common Tags and Keys ==

The following tags and keys are supported in most types of addon modules:

* '''id''': The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a '''[scenario]''' and a '''[multiplayer]''' with the same ID.
* '''addon_min_version''': The minimum version of your add-on with which this content is backwards compatible. Compared 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 each others' content in order to play, and will be prompted to update otherwise.
* '''name''': (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for '''[resource]''' since it is never visible anywhere.)
* '''description''': (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for '''[resource]''', nor for '''[scenario]''' or '''[test]'''.)
* '''define'''='''''SYMBOL''''' When this addon module is active, the preprocessor symbol '''''SYMBOL''''' will be defined. See [[PreprocessorRef#.23ifdef_and_.23ifndef|ifdef]] for how this can be used to isolate parts of the file from other addon modules. Besides the addon module tag, only the tags '''[textdomain]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Note: If for some reason you don't want to place your '''[binary_path]''' outside your '''#ifdef ''SYMBOL''''' (perhaps it's causing conflicts with other addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module tag. This looks like '''icon=data/add-ons/whatever/something.png''' – essentially, any path beginning with '''data/'''.
* '''[event]''' - An event handler that will be registered when the addon module is active. See [[EventWML]].
* '''[lua]''' - Lua code that will be run when the addon module is loaded, before the '''preload''' event is fired. See [[LuaWML]].
* '''[ai]''': Defines an AI algorithm that can be selected by players at the join game screen. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|here]] for details. This is not used in single-player.
** Note: This is not the place to define faction-specific AI parameters in an era. For that, place the '''[ai]''' tag in '''[multiplayer_side]'''.
** Note: This tag may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[options]''': Custom options. See [[OptionWML]] for details. Note: This may not be supported in '''[resource]''', '''[scenario]''', or '''[test]'''.
* '''[load_resource]''': Indicates a resource to load when this addon module is loaded.
** '''id''': The ID of the resource.
* '''[modify_unit_type]''' {{DevFeature1.15|2}}: Changes a unit type while this modification is active. The supported attributes are:
** '''type''' : the id of the unit type to change.
** '''set_experience''' : changes the unit type's max experience.
** '''set_cost''' : changes the unit type's recruit cost.
** '''set_advances_to''' : changes the unit type's advancements.
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

== See Also ==

* [[BinaryPathWML]] - Toplevel tag to define search paths for assets.
* [[UnitsWML]] - Toplevel tag to define units and unit-related data.
* [[TerrainWML]] - Toplevel tag to define terrain types.
* [[TerrainGraphicsWML]] - Toplevel tag to define how terrain is drawn.

GettextForWesnothDevelopers

2024-01-23T10:46:52Z

Octalot: /* The translatable strings */ Explain a bit about where the textdomain is used

This page is used to help Wesnoth developers and UMC authors to work with the internationalization (i18n) system, based on GNU gettext.

== General design of gettext use ==

Programs using Gettext include the strings in one language (usually English) within the source code. For each target language, a separate file provides a look-up table from English to that language. If the file is missing or doesn't have a translation for that string, the system falls back to using the English text.

The translation mechanism usually involves a function or macro called ''_'' (a single underscore sign). Examples are in the programming-language specific sections below.

=== Textdomains ===

Gettext splits translations into domains. For Wesnoth, the general idea is to use distinct textdomains for each campaign or add-on, so that UMC authors can easily ship translations together with their campaigns. These domains are covered in more depth in [[GettextForTranslators]].

The convention is to name each domain using the name of the add-on, or just its initials. For example, ''wesnoth-utbs'' or ''wesnoth-Son_of_Haldric''. For UMC, it probably makes sense to use the full name to ensure that it doesn't clash with another add-on.

=== Caret hints ===

Some strings look the same in English but should not necessarily look identical in translations. To handle this, those strings can be prefixed with any descriptive string and a '''^''' character. For users viewing in '''en_US''', these hints will be automatically removed from the string before showing it to the user.

{{DevFeature1.15|2}} if the string contains more than one '''^''', the descriptive string ends at the first '''^''', everything following the first '''^''' will be shown to the user.

{{DevFeature1.15|18}} When using gettext's Plural Forms, these prefixes can and should be used in both the singular and the plural.

=== UTF-8 ===

For translation, all C++, WML and Lua files should be in UTF-8. As noted in the [[Typography_Style_Guide]], some punctuation should be used that's outside of the ASCII subset.

== Marking up strings in C++ ==

In C++, you can mark up strings for translations using the <syntaxhighlight lang=c++ inline>_("A translation")</syntaxhighlight> and <syntaxhighlight lang=c++ inline>_n("Translation", "Translations", int)</syntaxhighlight> macros. The <code>_n</code> macro is to be used if the string has a singular and plural form.

You can also add comments for translators. Single-line comments must start with <code>TRANSLATORS:</code> and be on the line ''immediately'' above the translatable string. For multi-line comments, the <code>TRANSLATORS:</code> only needs to be on the first line to include the whole comment, and the last line must be immediately above the translatable string.

If the string contains any placeholders, '''don't''' use <code>snprintf</code>. Instead use WML style variables, put their values in a <syntaxhighlight lang=c++ inline>utils::string_map</syntaxhighlight> and use the <code>VGETTEXT</code> or <code>VNGETTEXT</code> macros instead.

<syntaxhighlight lang=c++>
utils::string_map symbols;
symbols["enemies"] = std::to_string(enemy_count_);
symbols["friends"] = std::to_string(friend_count_);
std::string message;
if ( friend_count_ != 0 && enemy_count_ != 0 ) {
// Omitted from the example - see the code in src/action/move.cpp for how to handle strings with two independent ints.
} else if ( enemy_count_ != 0 ) {
// TRANSLATORS: Only enemies sighted -- bad message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Enemy unit sighted!", "$enemies enemy units sighted!", enemy_count_, symbols);
} else if ( friend_count_ != 0 ) {
// TRANSLATORS: Only friends sighted -- good message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Friendly unit sighted", "$friends friendly units sighted", friend_count_, symbols);
}
</syntaxhighlight>

The <syntaxhighlight lang=c++ inline>string_map</syntaxhighlight> can contain additional values that aren't used in the translated string. In the example above, it has both ''friends'' and ''enemies''.

By default, all strings in C++ belong to the "wesnoth" textdomain. If a different textdomain is required, you can add a textdomain binding at the top of the source file, before any include statements. A textdomain binding looks like this: <syntaxhighlight lang=c++>#define GETTEXT_DOMAIN "wesnoth-lib"</syntaxhighlight>

You should avoid placing translatable strings in C++ headers if at all possible. Though there are a few places where it may be unavoidable, such as if templates are in use, it creates the risk of the strings sometimes being looked up in the wrong textdomain if the header is included in multiple files with different textdomains. If possible, always factor the translatable strings out into a source file.

== Marking up strings in WML ==

=== The textdomain bindings ===

All files with translatable strings must declare which textdomain they use, which is normally done by putting ''#textdomain'' on the first line of each .wml file. See the example below:

<syntaxhighlight lang=wml>
#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...
[/unit_type]
</syntaxhighlight>

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below. When parsing this, the engine will record both the visible text and the active textdomain, which can later be used to get the translation when displaying the text to the player.

<syntaxhighlight lang=wml>
name= _ "Mu"
</syntaxhighlight>

==== Notes to the translators ====

If you think a translatable string needs additional guidance to be translated properly, you can provide a special comment that will be seen by the translators. Some hints are generated automatically, but in general if you have to wonder whether a hint is needed then it probably is. The context of the scenario isn't obvious in the translation tools, and you can't assume that the strings are shown to the translator in the same order that they appear in the WML file.

Just begin the comment with '#po:' or '# po:' above the string in question. This must be on the line (or lines) immediately before the string that the hint applies to:

<syntaxhighlight lang=wml>
#po: "northern marches" is *not* a typo for "northern marshes" here.
#po: In archaic English, "march" means "border country".
story=_ "The orcs were first sighted from the north marches of the great forest of Wesmere."
</syntaxhighlight>

The wmlxgettext tool will automatically generate hints for some tags, in addition to hints from '# po:' comments:

* For ''[message]'': the ''id'', ''speaker'', ''role'' or ''type'' used to choose the speaker
* For ''[object]'': the ''id''
* For ''[unit]'': the ''id'' and ''unit_type''
* For ''[unit_type]'': the ''id'' and ''race''
* For ''[objective]'': whether it's ''condition=win'' or ''condition=lose''

==== Things to avoid ====

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

<syntaxhighlight lang=wml>
name= _ ""
</syntaxhighlight>

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

<syntaxhighlight lang=wml>
name= _ "{TYPE} Mu"
</syntaxhighlight>

To show why it will not work:

<syntaxhighlight lang=wml>
#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}
</syntaxhighlight>

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

<syntaxhighlight lang=wml>
name= _ "Sword Mu"
name= _ "Bow Mu"
</syntaxhighlight>

Since those are not in the catalogues, they will not get translated.

=== Gender-specific strings ===

Several tags, including ''[message]'', ''[abilities]'' and ''[trait]'', can choose different strings based on the gender of the unit. In English the two versions are likely to be the same, but other languages may have gender-specific words for 'I' or 'me'.

<syntaxhighlight lang=wml>
[message]
speaker=student
message= _ "Have you found an orc for me to fight, huh? A troll?"
female_message= _ "female^Have you found an orc for me to fight, huh? A troll?"
[/message]
</syntaxhighlight>

The convention in WML is, as above, to use ''message='' and ''female_message='', with the latter string including the prefix ''female^''. The mechanism also supports ''male_message='', but all units will fall back to using the plain ''message='' value if there isn't gender-specific version that matches their gender.

The message is chosen based on the gender of the speaking unit. To change the message based on the gender of another unit requires separate ''[message]'' tags:

<syntaxhighlight lang=wml>
[if]
[have_unit]
id=student
gender=male
[/have_unit]
[then]
[message]
speaker=Delfador
message= _ "Young man, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/then]
[else]
[message]
speaker=Delfador
message= _ "female^Young lady, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/else]
[/if]
</syntaxhighlight>

Using a macro to encapsulate most of that can be useful. The example above is from the tutorial, after expanding the ''GENDER'' macro which is defined in data/campaigns/tutorial/utils/utils.cfg.

=== Proper nouns in strings ===

Some languages require declensions of proper nouns - a person's name may change slightly depending on their role in a sentence. See for example [https://github.com/hrubymar10/wesnoth-cs/pull/209#issuecomment-1066163433 the Czech translators' PR 209].

Where there are a small number of units that might be addressed, for example the two in the tutorial or the four possible allies in UtBS, it's better to have a separate translatable string for each possible character instead of interpolating '''$unit.name''' into a string.

=== Reusing mainline translations ===

You can reuse translations for strings in mainline domains by using multiple textdomain bindings:

<syntaxhighlight lang=wml>
# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
# ...
[/attack]

#textdomain wesnoth-Son_of_Haldric
# ...
[/unit_type]
</syntaxhighlight>

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, and wesnoth-units.

==== The gettext helper file ====

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy, by having all strings that should use a specific textdomain in a single file. It is also more wmllint-friendly.

Here is an example of a gettext helper file. The macro names start with 'SOH_' to ensure that they don't clash with another add-on's macros (assuming that this add-on is Son_of_Haldric).

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib

#define SOH_STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define SOH_STR_SWORD
_"sword" #enddef
</syntaxhighlight>

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

<syntaxhighlight lang=wml>
[attack]
id=sword
name={SOH_STR_SWORD}
# ...
[/attack]

[terrain_type]
id=ice2
name={SOH_STR_ICE}
# ...
[/terrain_type]
</syntaxhighlight>

=== Unbalanced WML macros ===

WML macros can be ''unbalanced'', meaning that they either include a [tag] without the corresponding [/tag] or a [/tag] before the corresponding [+tag]. These macros are expected to be used in a place where the [tag] is already open. Writing new macros using this isn't recommended; instead please ask in the WML Workshop forum about better ways to do it.

When generating the .pot files for translation, wmlxgettext may stop with one of the errors
* error: Son_Of_Haldric/utils/abilities.cfg:29: unexpected closing tag '[/abilities]' outside any scope.
* error: Son_Of_Haldric/utils/abilities.cfg:300: End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [abilities])

Suppose abilities.cfg line 29 is in the definition of SOH_ABILITY_BLITZ. To get the .pot file generated, the simplest change is to use ''# wmlxgettext'' comments to add the missing opening or closing tags:

<syntaxhighlight lang=wml>
# wmllint: unbalanced-on
# wmlxgettext: [abilities]
#define SOH_ABILITY_BLITZ
[dummy]
id=soh_blitz
# ... ability definition stuff ...
[/dummy]
[/abilities]
# ... several lines of code, none of which are an ''#enddef'' ...
[+abilities] # wmlxgettext: [/abilities]
#enddef
# wmllint: unbalanced-off
</syntaxhighlight>

== Marking up strings in Lua ==

In Lua code, textdomains are a callable object that looks up a string. This has support for both singular and plural strings. By convention, the name <code>_</code> is usually used for the textdomain object.

The following sample code demonstrates how to fetch translatable strings in Lua:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "wesnoth"

-- Look up a normal string:
local win_condition = _ "Defeat enemy leader(s)"

-- Hints for the translators start with "po:", as in WML:
-- po: Floating text shown when a unit with the "feeding" ability gets a kill
local text = stringx.vformat(_"+$value max HP", { value = feeding.value})
</syntaxhighlight>

Plural strings are supported since Wesnoth 1.14:
<syntaxhighlight lang=lua>
local turn_count = 5
turn_counter = _("this turn left", "%d turns left", turn_count)
turn_counter = tostring(turn_counter):format(turn_count)

-- For readability, the example's strings are slightly different to the real code.
-- The real strings have brackets in the text shown to the player.
</syntaxhighlight>

In Wesnoth 1.15, variables can be interpolated using names:
<syntaxhighlight lang=lua>
-- Look up a plural string, using the preferred style (as of Wesnoth 1.15.3):
local turn_count = 5
turn_counter = _("this turn left", "$remaining_turns turns left", turn_count)
turn_counter = turn_counter:vformat{remaining_turns = turn_count}
</syntaxhighlight>

== The textdomain tag ==

To tell the engine where to search for the .po and .mo files, each textdomain needs a ''[textdomain]'' tag. For add-ons and mainline campaigns, the tag is usually placed inside of the _main.cfg. This is a top-level tag, so should be outside the ''[campaign]'' or ''[modification]'' tag.

Translatable strings from C++ and Lua use the same textdomains as WML; this WML tag tells the engine where to search for these strings irrespective of which programming language the string appeared in.

<syntaxhighlight lang=wml>
[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]
</syntaxhighlight>

The .po (or .mo) files will be loaded from a subdirectory of the ''translations'' directory.

== Generating the .pot and .po files for UMC ==

For each language, Wesnoth will search for a .po file containing the translations. How to create that file will be explained below, but first the overview of where it should go. Continuing with the Son of Haldric example, the Swedish translation would be in the file:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric/translations'' comes from the ''[textdomain]'' tag's ''path''
* ''wesnoth-Son_of_Haldric'' is the textdomain's name
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

Wesnoth 1.14 (but not 1.12) supports reading .po files directly, so when you add the .po file and the new translation should appear as soon as you refresh the cache.

=== Generating the .pot file ===

The template (.pot) file contains all of the strings that need to be translated in the .po files, but without the translations.

The .pot is generated from WML and Lua files using a tool called wmlxgettext. With Wesnoth 1.14.5 and later, this is shipped with Wesnoth itself as part of the [[Maintenance_tools]] and can be used from the Maintenance Tools' GUI. At the moment it's not documented on that page, but if you follow the instructions to get GUI.pyw running then you'll see there's a wmlxgettext tab.

Pre-1.13 instructions on how to get and use it are in Nobun's [https://r.wesnoth.org/p617733 forum posting].

==== Error messages from wmlxgettext ====

If you get the error from ''wmlxgettext'' of "UTF-8 Format error. Can't decode byte 0x91 (invalid start byte).", and the line in question has a curly quotation mark, that likely means that your text editor is using the Windows-1252 character set, and you need to replace the Windows quotes with their Unicode equivalents, see [[Typography_Style_Guide]] and your editor's documentation for more info. The same applies if the error message says 0x92, 0x93 or 0x94.

If you get either "unexpected closing tag '[/''something'']' outside any scope" or "End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [''something''])" then see [[#Unbalanced_WML_macros]] above.

=== Generating the .po files for each language ===

Each .po file can start as a simple copy of the .pot file. Either the author or the translator copies the template to the language-specific filename, and then the work of [[GettextForTranslators]] happens on those copies.

Some .po editors, for example poedit, will recognise that the .pot is a template, and automatically suggest saving to a different filename. The poedit editor can also update a .po file based on changes to the .pot file.

=== Generating the .mo files for UMC ===

For Wesnoth 1.14, it's generally not necessary to compile the .po files to .mo files. The mainline translations still use .mo files for better performance, but UMC authors can skip the .mo compilation stage.

== See Also ==

* [[WesnothTranslations]]
* http://www.gnu.org/software/gettext/
* [https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html#Preparing-Strings GNU gettext manual on preparing translatable strings]
* [[GetText]]
* [https://wmlxgettext-unoff.readthedocs.io/en/latest/ wmlxgettext documentation]

[[Category:Development]]

1.19 Roadmap

2024-01-05T13:39:43Z

Octalot: Rough outline of the roadmap, milestone headings are only 1.19.5, .10, .20, Beta 1 and release

WesnothTranslationsHowTo

2023-10-20T11:11:02Z

Octalot: /* Files */ Split the section into Files, Tools and Summary. Mention SCons and CMake before individual tools.

This page contains information on how-to translate and submit translation updates.

== How to submit your translations ==

Important: Please '''do not submit translations as pull requests''' on the Wesnoth github repository site. While that seems like a good idea, it causes potential complications that we cannot always easily resolve. As a result, we cannot accept translations submitted via pull request and will close such PRs immediately.

'' ''' Translation Maintainers ''' ''

The translation maintainers should send the updated/new translation
po-files to the language coordinator:
Ivanovic (crazy-ivanovic AT gmx DOT net).
Additionally they have to quickly check over other people's translations
(other people translating the same language) as the other translators
(if any) will have to send their translations to their language maintainer
before inclusion in the source-code repository. You should also subscribe to the [http://www.wesnoth.org/wiki/WesnothTranslations#Mailing_List wesnoth-i18n mailinglist].

Send the files as an archive containing the complete .po files (no .mo or .gmo files) and ensure that they follow the directory structure used in version control. For example, the archive with the German (de) translations should therefore be structured as follows:
wesnoth/de.po
wesnoth-httt/de.po
wesnoth-tutorial/de.po
etc.

'' ''' Translators ''' ''

The other translators (those who are not maintainers) should contact
the maintainer for their language to see if there is some work to do.
After you have done some work on the translation you should email it
to your language maintainer. They will then (if needed) check it over
before sending it on to the language coordinators. A list of all translators
currently working on a language is found on each language page.

'' ''' NEW Translators ''' ''

If you want to help out with the translation of an language already started on,
contact the translation maintainer for the language.
If you want to start translation of Wesnoth to a new language,
first contact Ivanovic.
And then just follow the instructions written in '' Translators '' .

== Translations How-To ==

If you are a translator, see [[GettextForTranslators]] for more information.

If you are a developer or UMC author, gettext internals for Wesnoth are discussed here: [[GettextForWesnothDevelopers]]. For UMC authors, the tool for generating .po files is linked to from [[GettextForWesnothDevelopers#Generating the_.pot_and_.po_files_for_UMC]].

=== Files ===

We will use the Swedish (sv) language and the ''wesnoth-editor'' domain as an example. There are three important files for each text-domain:
* ''wesnoth-editor/wesnoth-editor.pot'' file, which is a template containing all the strings used in the domain, but with empty strings instead of a translation. You can see how a ''.pot'' file looks like in the repository : [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/wesnoth-editor.pot#L50 Current repository version].
* ''wesnoth-editor/sv.po'', the file containing the translation, you can see how a ''.po'' file looks like in the repository: [https://github.com/wesnoth/wesnoth/blob/master/po/wesnoth-editor/sv.po#L50 Current repository version].
* ''{translations_dir}/sv/LC_MESSAGES/wesnoth-editor.mo'', which is a binary version of <lang>.po that the game will use for efficiency reasons. This is not found in the repo, but is created during compilation of the game.

The first of these files, we update every once in a while, when there is new or modified text,
for instance when a new campaign scenario hits the repository.

=== Tools ===

For the main Wesnoth repository, the build system can handle updating these files.
* Using SCons, '''scons pot-update''' will do everything. '''scons -j8 pot-update''' is quicker, because it does it in parallel. This can be done without building the Wesnoth executables.
* Using CMake, enable '''ENABLE_NLS''' and '''ENABLE_POT_UPDATE_TARGET''', then run '''make -C po pot-update''' to generate the files.

Some notes on the individual steps that are used during the build:

C++ and Python files are parsed with ''xgettext'', WML and Lua files are parsed with ''wmlxgettext''. The results are then combined to generate the ''.pot'' file.

Then, ''msgmerge'' is used to merge this new "state of the game strings" with your current translations, and generate a new, up-to-date, ''sv.po''.

Then, a tool called ''msgfmt'' is called, which generates a new ''wesnoth.mo'' file from your ''wesnoth.po'' file, which will be used by the game once installed.

=== Summary ===

That was for the "Big Picture".
But you really just need to be concerned with the po file:
translating new strings, checking "fuzzy" entries.
We can handle the administrative tasks of updating etc.
You really don't need to bother with any of these commands, unless you want to compile .mo files to check in-game.

Ivanovic is now responsible for integrating translations into Wesnoth, with the help of Torangan and ott.
You should contact Ivanovic (crazy-ivanovic AT gmx DOT net), and he'll put them in the game.

== Specifying typefaces and fonts for a translation ==

Translations in a language which use characters outside of the Latin, Greek and Cyrillic character sets may want to specify different typefaces. There are some translatable strings in data/hardwired/fonts.cfg which specify the fonts to use; these strings appear in the ''wesnoth'' text domain, and can be configured by putting the required fonts' names as the translations.

Note the documentation in data/hardwired/fonts.cfg.

== See Also ==
* [[GettextForTranslators]]
* [[WesnothTranslations]]
* [[TranslatorsGuide]]
* [http://gettext.wesnoth.org Translation statistics]

[[Category:Translations]]

CampaignDialogue:TB

2023-08-24T11:45:59Z

Octalot: Add a note that this page is outdated

{| style="float:right"
|
__TOC__
|}

This is a transcription of all dialogue from [[A Tale of Two Brothers]]. It is meant as a resource for Wesnoth writers. If you don't want spoilers, leave this page now.

{{Note|This page needs updating, most of the text is from the 1.8 version of Wesnoth}}

=== Possible Timeframe ===
This campaign, as originally written, had no definite time or place. There was a vague reference to "the eastern reaches of the kingdom of Wesnoth". In a later revision the epilog hint that Arvith may have traveled with the elf-lord Kalenz, but this is not much of a constraint as Kalenz was around in 1YW and at least until the beginning of HttT in 517 YW.

Maghre has to be within reach of the orcs, but in a time and place where there haven't been orc raids for generations. This limits us to *western* Wesnoth, orc raids having been a chronic problem in the northeast even during the Kingdom's strongest periods. The logical time would be shortly after the death of Haldric IV in 350, the beginning of the First Dark Age. It's arbitrarily set at 353; Kalenz began his wanderings ten years later, so the timing for Arvith to meet him later in life isn't bad.

Placing the campaign is a little trickier. Our main textual clue is that there is a dense wood, said by legend to be haunted, a few days' ride north. Later, the boss's keep is said to be still further north. Neither of these directions has plot importance, but they do suggest a locale for Maghre - near the Gray Woods. The battle maps exclude it from being in a featureless plain, though; there are hills to the south and west.

== Death Dialogue ==
=== Mordak ===
'''Mordak:''' Argh

=== Arvith ===
'''Arvith:''' All is lost now that I am dead...

'''Arvith:''' Everything is lost now that I am dead...

== Scenario 1: Rooting Out A Mage ==
=== Story ===
Translation hints: The first paragraph is shown with the journey map as a background, showing the village in the foothills along the route between Aldril and Dan’Tonk. I'm assuming the beacons either use smoke signals or basic fire signals, with a few agreed ones to request goods or indicate that surplus is for sale.

The remote freehold of Maghre in the western reaches of the Kingdom of Wesnoth was once a peaceful place, its inhabitants largely unaware of the comings and goings of the wider world. Wars and the rumor of wars touched them not. Even merchants were rarely seen, although caravans between Aldril and Dan’Tonk might send a wagon when called by the beacon tower.

Then came the day that a dark mage settled in the region and began seeking sacrifices for his summonings.

Skeletons and zombies killed cattle and fired fields. 'Fear and obey Mordak the Mage!' they cried in fell voices as they did their foul deeds. People vanished from isolated farmsteads. Men and women began to fear the night, and their children even the bright day. But the nearest lord was more than a day’s ride distant, and messengers sent to seek his help did not return.

There was a man named Baran who had shown talent as a mage when he was young, gone to the great Academy on the Isle of Alduin, and returned to work his magic in the land where he was born. The people looked to him for help and leadership. He found weapons half-forgotten from the times of their sires and grandsires hanging in many houses, and bade the villagers to take them down and clean and oil them. He set the smiths of Maghre to making spearheads and ax-blades for the rest.

Now Baran had a brother named Arvith who had also left Maghre to seek his fortune, and had become the leader of a small band of horsemen who hired out as guards to merchant caravans. Fortunate it was for all that, in better times, the brothers had talked of using trade beacons for other signals when in dire need. Baran sent out that call.

12 V, 363 YW
Excerpt from the journal of Baran of Maghre

If I could but face this ‘Mordak’! I think my magic might prove stronger than his. But he bides in the hills, well-guarded by his servants, and I muster frightened peasants to fight his minions with blades and sticks.

I need my brother; he always had a better head for battle than I. Yet we have not spoken since that evil day at Toen Caric. If he will not come for me, perhaps he will return to aid our village in its hour of desperate need.

Heeding the call, Arvith gathered such men as he could and hurried to Maghre to help Baran.

=== Introductory Dialogue ===
'''Arvith:''' Greetings, my brother! How may my men and I be of aid?"

'''Baran:''' A dark mage has come upon us; his creatures call him Mordak. They have been terrorizing outlying farms, and we fear they may soon attack the village itself! The villagers of Maghre have taken up weapons but they are not trained fighters; but we need your men, and you to lead them.

'''Baran:''' I can feel Mordak's foul touch on the hidden currents of the earth and air. He is somewhere due north of here, I would say not more than two days' ride.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Baran:''' You shall be the right hand, I the left. I will go stealthily with a handful of our best scouts and woodsmen. While you demonstrate against him and kill his creatures, I will try to defeat Mordak himself with magic at an unguarded moment. Together we may accomplish what either alone may not.

=== Turn 6 ===
'''Arvith:''' Baran should be in position by now. Press them, distract the adept so Baran can spring his trap!

=== Turn 10 ===
'''Arvith:''' Baran has not made his attack! I begin to fear for him... and it means we must deal with this Mordak ourselves!

=== Undead Leader: Last Breath ===
'''Mordak:''' Argh.

'''Arvith:''' Good work, men! But what has become of my brother?

'''Mordak:''' Worried about him, are you? E-he-he..hergh...gaargh...

'''Arvith:''' There's nothing more to be had from this one; we will have to search for Baran ourselves!

'''Unit:''' Sir, our scouts report that Baran was seen captured and carried away further north!

'''Arvith:''' That they should dare this! We will give chase at once.

=== Time Over ===
'''Mordak:''' Your brother's plan to ambush me has failed. He is our prisoner now.

'''Arvith:''' My brother, kidnapped? I have failed you, Baran! And even now Mordak's forces descend upon the village!

=== First Attack ===
'''Arvith:''' I hear these creatures are nigh-immune to our weapons, let us see!

=== Player Kills First Enemy ===
'''Unit:''' That was not so hard!

== Scenario 2: The Chase ==
=== Story ===
The pursuit had already run for several days when the pursuers came to the bounds of the huge forest known as the Gray Woods. Ancient tales wArvithd of lost souls haunting the wood, hunting and killing anyone brave enough to enter it.

Heedless of those rumors, Arvith followed them. His only worry was that his horsemen would be at disadvantage if attacked in the forest.

=== Introductory Dialogue ===
'''Narrator:''' Sounds of a scuffle were heard from the forest.

'''Arvith:''' Come on, men. A stroll through such lovely green woods, what could be finer?

'''Unit:''' It is whispered that hungry ghosts rule this forest, and kill everyone who dares to enter.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Nil-Galion:''' You there! Halt and explain yourself.

'''Arvith:''' We're chasing after some men who kidnapped my brother!

'''Nil-Galion:''' Those men told me their prisoner had attempted to murder their master, and wArvithd that evil men would follow him. Advance no further, or you will die.

'''Arvith:''' So much for those ghost stories. Mere elves will not stop me from freeing my brother!

'''Unit:''' I am glad at least that we will not have to face ghosts. But those elves will have us at a disadvantage; our horses will not maneuver well in the trees.

'''Arvith:''' Bah, just stay on the paths; our spearmen and bowmen can fight in the deeper woods. We have faced and won through greater perils than those amateurs can offer.

=== Move to the North ===
'''Unit:''' I see them! There they are!

'''Muff Toras:''' Curses! If they had been an hour slower our master's reinforcements would already be here to meet us.

=== Turn 12 ===
'''Arvith:''' Come on, men, let's catch those kidnappers!

=== Elf Last Breath ===
'''Nil-Galion:''' Foolish human, you have killed me but you will not catch the undead in time. I have fulfilled my contract, and will be reanimated soon to become a lord of their armies.

'''Arvith:''' Follow their back trail!

=== Undead Last Breath ===
'''Muff Toras:''' Hah! You have captured me, but it will avail you nothing. I sent your precious brother the mage north with half my men a day since; he will be safely locked away in our master's dungeons by now.

'''Arvith:''' My blade is at your throat. Give us the way to my brother now, or I will spill your wretched blood on the ground.

'''Muff Toras:''' Three days ride to the northeast, in a deserted castle. The passwords to the guards are --- and ---.

'''Arvith:''' Bind him and take him with us. If he has played us false, he will die.

=== Time Over ===
'''Muff Toras:''' My reinforcements are here!

'''Arvith:''' He escaped us...

=== Victory: Easy ===
'''Brena:''' Greetings. I am Brena, a knight errant. I saw you pursuing and fighting the foul undead. Are there more of them to be destroyed?

'''Arvith:''' Aye. We think there's a nest of them north-east of here. They've captured my brother.

'''Brena:''' I bear a great hatred towards their kind. I will follow and fight them with you, if you permit.

'''Unit:''' He would only slow us down!

'''Arvith:''' It is my place to decide this.

''Option 1''

'''Arvith:''' All right, come along with us.

'''Brena:''' Thank you. My comrades and I will help you on your noble quest.

''Option 2''

'''Arvith:''' I am sorry. We have not the time to spare.

'''Brena:''' Take this, then, for I see that you are on a quest. My comrades will help you whenever you call for them.

== Scenario 3: Guarded Castle ==

=== Introductory Dialogue ===
'''Narrator:''' Arvith's men arrived at the castle and were immediately challenged by some guards.

'''Guard Leader:''' Halt! Friend or foe? Give the password.

'''Arvith:''' The password is ----.

'''Guard Leader:''' Pass friend.

=== Orcs Sighted ===

'''Knago-Brek:''' Haha! We not kill people for long time. Weapon wants blood. We now kill humans!!

'''Arvith:''' My sword-arm has a say in who will do the dying. Come on, men, let's kill some orcs.

=== Second Set of Guards (Turn 6) ===

'''Guard Leader:''' Are you our relief arriving? Does this mean we get to leave here now?

'''Arvith:''' Um, yes. Fine. You can go.

'''Guard Leader:''' Um, you're supposed to give the password.

'''Arvith:''' Oh, of course. I had nearly forgotten.

'''Guard Leader:''' Thanks! Irritating little formality, isn't it?

'''Arvith:''' I think I should better support my men at the front to make sure we can free my brother.

=== Undead Last Breath ===
'''Rotharik:''' Nooo! This is the end...

'''Unit:''' There's a key in his robes.

'''Arvith:''' That may well be the key to the cell they're holding Baran in! I will take it.

=== Baran's Cell ===
'''Unit:''' I found Baran. He is in this cell.

IF Arvith

'''Baran:''' Good to see you, Arvith. Now can you get me out of this dungeon, please?

IF ANOTHER UNIT

'''Baran:''' You must be one of Arvith's men. Please help me get out of this dungeon.

THEN

IF PLAYER DOES NOT HAVE KEY

'''Baran:''' The accursed dark sorcerer Rotharik has imprisoned me behind this magically enhanced iron gate. It can only be opened with the correct key. You must get it from him to free me.

IF PLAYER HAS KEY

'''Baran:''' Thank you for saving me. I had almost given up hope you would free me.

'''Arvith:''' Oh it was nothing, a few elves, one or two dark sorcerers, a bunch of orcs and some undead. Really just a day's work for us mercenaries.

'''Baran:''' Thank you for coming to my aid. Let us return to the village.

=== Time Over ===
'''Rotharik:''' You are too late! Your brother is already dead! Muhahahaha...

'''Arvith:''' Argh!!!

== Scenario 4: Return to the Village ==

=== Introductory Dialogue ===
'''Arvith:''' There. Your village is just across those hills, and already I see men coming to greet us!

'''Baran:''' No, they are fleeing from something. We must find out what is happening over there!

'''Arvith:''' Men! Ready your weapons!

'''Baran:''' We should go there and talk to Counselor Hoban. Maybe he knows what is going on here.

=== Sighted by Councillor Hoban ===
'''Councillor Hoban:''' I am glad to see you returned.

'''Baran:''' No gladder than I am to be here. But what has happened to Maghre?

'''Councillor Hoban:''' Soon after you departed we were beset by orcs. With half the men of Maghre gone, we could not stop them.

'''Councillor Hoban:''' The orcish warlord aims to enslave us. We will not be able to hold out for much longer.

'''Councillor Hoban:''' Have a care, his men are fell fighters and have killed many. Very few remain who can bear arms, but I will send them to aid you in battle.

=== Enemies Defeated ===
'''Arvith:''' Finally the warlord is killed. Now you can go back to Maghre.

'''Baran:''' So much has been destroyed. It will be difficult to repair all that the orcs and undead have wrecked. And they could come again.

'''Arvith:''' I must go back to earning my living. But you have my word, little brother; if you are beset again, I will come.

=== Baran's Last Breath ===
'''Baran:''' It is over, I am vanquished.

===Time Over===
'''Arvith:''' I don't think we can rescue anyone from these villages. It is too late.

'''Baran:''' I was too weak to protect these people. Oh why did this happen to me?!?

==Scenario 5: Epilogue==
===Story===
It took years to rebuild the village and restore the surrounding farms. The people of Maghre had to work very hard, but felt better knowing Arvith's men would be their firm allies in troubled times.

Arvith and his men left the village assured that it would be well guided by Baran. On their journeys they faced many challenges and battles. Some tales even mention Arvith's name together with that of the famous elvish lord Kalenz, but this is a different story...

==TB's Specified Unit Names==

===Humans===
*[[CharactersStorys#Arvith | Arvith]]
*[[CharactersStorys#Baran | Baran]]
*Alwyn
*Brent
*[[CharactersStorys#Brena | Brena]]
*Cadell
*Dannen
*Efran
*Fargus
*Erik
*Heine
*Magnus
*Councillor Hoban

=== Elves ===
*[[CharactersStorys#Nil-Galion | Nil-Galion]]

===Undead===
=====Human=====
*[[CharactersStorys#Mordak | Mordak]]
*[[CharactersStorys#Muff_Toras | Muff Toras]]
*[[CharactersStorys#Rotharik | Rotharik]]

===Orcs===
*Knago-Brek
*[[CharactersStorys#Tairach | Tairach]]

[[Category:Create|*]]
[[Category:Writing|*]]

CampaignDialogue:TB

2023-08-24T11:41:39Z

Octalot: /* Enemies Defeated */ More amulet removal

{| style="float:right"
|
__TOC__
|}

This is a transcription of all dialogue from [[A Tale of Two Brothers]]. It is meant as a resource for Wesnoth writers. If you don't want spoilers, leave this page now.

=== Possible Timeframe ===
This campaign, as originally written, had no definite time or place. There was a vague reference to "the eastern reaches of the kingdom of Wesnoth". In a later revision the epilog hint that Arvith may have traveled with the elf-lord Kalenz, but this is not much of a constraint as Kalenz was around in 1YW and at least until the beginning of HttT in 517 YW.

Maghre has to be within reach of the orcs, but in a time and place where there haven't been orc raids for generations. This limits us to *western* Wesnoth, orc raids having been a chronic problem in the northeast even during the Kingdom's strongest periods. The logical time would be shortly after the death of Haldric IV in 350, the beginning of the First Dark Age. It's arbitrarily set at 353; Kalenz began his wanderings ten years later, so the timing for Arvith to meet him later in life isn't bad.

Placing the campaign is a little trickier. Our main textual clue is that there is a dense wood, said by legend to be haunted, a few days' ride north. Later, the boss's keep is said to be still further north. Neither of these directions has plot importance, but they do suggest a locale for Maghre - near the Gray Woods. The battle maps exclude it from being in a featureless plain, though; there are hills to the south and west.

== Death Dialogue ==
=== Mordak ===
'''Mordak:''' Argh

=== Arvith ===
'''Arvith:''' All is lost now that I am dead...

'''Arvith:''' Everything is lost now that I am dead...

== Scenario 1: Rooting Out A Mage ==
=== Story ===
Translation hints: The first paragraph is shown with the journey map as a background, showing the village in the foothills along the route between Aldril and Dan’Tonk. I'm assuming the beacons either use smoke signals or basic fire signals, with a few agreed ones to request goods or indicate that surplus is for sale.

The remote freehold of Maghre in the western reaches of the Kingdom of Wesnoth was once a peaceful place, its inhabitants largely unaware of the comings and goings of the wider world. Wars and the rumor of wars touched them not. Even merchants were rarely seen, although caravans between Aldril and Dan’Tonk might send a wagon when called by the beacon tower.

Then came the day that a dark mage settled in the region and began seeking sacrifices for his summonings.

Skeletons and zombies killed cattle and fired fields. 'Fear and obey Mordak the Mage!' they cried in fell voices as they did their foul deeds. People vanished from isolated farmsteads. Men and women began to fear the night, and their children even the bright day. But the nearest lord was more than a day’s ride distant, and messengers sent to seek his help did not return.

There was a man named Baran who had shown talent as a mage when he was young, gone to the great Academy on the Isle of Alduin, and returned to work his magic in the land where he was born. The people looked to him for help and leadership. He found weapons half-forgotten from the times of their sires and grandsires hanging in many houses, and bade the villagers to take them down and clean and oil them. He set the smiths of Maghre to making spearheads and ax-blades for the rest.

Now Baran had a brother named Arvith who had also left Maghre to seek his fortune, and had become the leader of a small band of horsemen who hired out as guards to merchant caravans. Fortunate it was for all that, in better times, the brothers had talked of using trade beacons for other signals when in dire need. Baran sent out that call.

12 V, 363 YW
Excerpt from the journal of Baran of Maghre

If I could but face this ‘Mordak’! I think my magic might prove stronger than his. But he bides in the hills, well-guarded by his servants, and I muster frightened peasants to fight his minions with blades and sticks.

I need my brother; he always had a better head for battle than I. Yet we have not spoken since that evil day at Toen Caric. If he will not come for me, perhaps he will return to aid our village in its hour of desperate need.

Heeding the call, Arvith gathered such men as he could and hurried to Maghre to help Baran.

=== Introductory Dialogue ===
'''Arvith:''' Greetings, my brother! How may my men and I be of aid?"

'''Baran:''' A dark mage has come upon us; his creatures call him Mordak. They have been terrorizing outlying farms, and we fear they may soon attack the village itself! The villagers of Maghre have taken up weapons but they are not trained fighters; but we need your men, and you to lead them.

'''Baran:''' I can feel Mordak's foul touch on the hidden currents of the earth and air. He is somewhere due north of here, I would say not more than two days' ride.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Baran:''' You shall be the right hand, I the left. I will go stealthily with a handful of our best scouts and woodsmen. While you demonstrate against him and kill his creatures, I will try to defeat Mordak himself with magic at an unguarded moment. Together we may accomplish what either alone may not.

=== Turn 6 ===
'''Arvith:''' Baran should be in position by now. Press them, distract the adept so Baran can spring his trap!

=== Turn 10 ===
'''Arvith:''' Baran has not made his attack! I begin to fear for him... and it means we must deal with this Mordak ourselves!

=== Undead Leader: Last Breath ===
'''Mordak:''' Argh.

'''Arvith:''' Good work, men! But what has become of my brother?

'''Mordak:''' Worried about him, are you? E-he-he..hergh...gaargh...

'''Arvith:''' There's nothing more to be had from this one; we will have to search for Baran ourselves!

'''Unit:''' Sir, our scouts report that Baran was seen captured and carried away further north!

'''Arvith:''' That they should dare this! We will give chase at once.

=== Time Over ===
'''Mordak:''' Your brother's plan to ambush me has failed. He is our prisoner now.

'''Arvith:''' My brother, kidnapped? I have failed you, Baran! And even now Mordak's forces descend upon the village!

=== First Attack ===
'''Arvith:''' I hear these creatures are nigh-immune to our weapons, let us see!

=== Player Kills First Enemy ===
'''Unit:''' That was not so hard!

== Scenario 2: The Chase ==
=== Story ===
The pursuit had already run for several days when the pursuers came to the bounds of the huge forest known as the Gray Woods. Ancient tales wArvithd of lost souls haunting the wood, hunting and killing anyone brave enough to enter it.

Heedless of those rumors, Arvith followed them. His only worry was that his horsemen would be at disadvantage if attacked in the forest.

=== Introductory Dialogue ===
'''Narrator:''' Sounds of a scuffle were heard from the forest.

'''Arvith:''' Come on, men. A stroll through such lovely green woods, what could be finer?

'''Unit:''' It is whispered that hungry ghosts rule this forest, and kill everyone who dares to enter.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Nil-Galion:''' You there! Halt and explain yourself.

'''Arvith:''' We're chasing after some men who kidnapped my brother!

'''Nil-Galion:''' Those men told me their prisoner had attempted to murder their master, and wArvithd that evil men would follow him. Advance no further, or you will die.

'''Arvith:''' So much for those ghost stories. Mere elves will not stop me from freeing my brother!

'''Unit:''' I am glad at least that we will not have to face ghosts. But those elves will have us at a disadvantage; our horses will not maneuver well in the trees.

'''Arvith:''' Bah, just stay on the paths; our spearmen and bowmen can fight in the deeper woods. We have faced and won through greater perils than those amateurs can offer.

=== Move to the North ===
'''Unit:''' I see them! There they are!

'''Muff Toras:''' Curses! If they had been an hour slower our master's reinforcements would already be here to meet us.

=== Turn 12 ===
'''Arvith:''' Come on, men, let's catch those kidnappers!

=== Elf Last Breath ===
'''Nil-Galion:''' Foolish human, you have killed me but you will not catch the undead in time. I have fulfilled my contract, and will be reanimated soon to become a lord of their armies.

'''Arvith:''' Follow their back trail!

=== Undead Last Breath ===
'''Muff Toras:''' Hah! You have captured me, but it will avail you nothing. I sent your precious brother the mage north with half my men a day since; he will be safely locked away in our master's dungeons by now.

'''Arvith:''' My blade is at your throat. Give us the way to my brother now, or I will spill your wretched blood on the ground.

'''Muff Toras:''' Three days ride to the northeast, in a deserted castle. The passwords to the guards are --- and ---.

'''Arvith:''' Bind him and take him with us. If he has played us false, he will die.

=== Time Over ===
'''Muff Toras:''' My reinforcements are here!

'''Arvith:''' He escaped us...

=== Victory: Easy ===
'''Brena:''' Greetings. I am Brena, a knight errant. I saw you pursuing and fighting the foul undead. Are there more of them to be destroyed?

'''Arvith:''' Aye. We think there's a nest of them north-east of here. They've captured my brother.

'''Brena:''' I bear a great hatred towards their kind. I will follow and fight them with you, if you permit.

'''Unit:''' He would only slow us down!

'''Arvith:''' It is my place to decide this.

''Option 1''

'''Arvith:''' All right, come along with us.

'''Brena:''' Thank you. My comrades and I will help you on your noble quest.

''Option 2''

'''Arvith:''' I am sorry. We have not the time to spare.

'''Brena:''' Take this, then, for I see that you are on a quest. My comrades will help you whenever you call for them.

== Scenario 3: Guarded Castle ==

=== Introductory Dialogue ===
'''Narrator:''' Arvith's men arrived at the castle and were immediately challenged by some guards.

'''Guard Leader:''' Halt! Friend or foe? Give the password.

'''Arvith:''' The password is ----.

'''Guard Leader:''' Pass friend.

=== Orcs Sighted ===

'''Knago-Brek:''' Haha! We not kill people for long time. Weapon wants blood. We now kill humans!!

'''Arvith:''' My sword-arm has a say in who will do the dying. Come on, men, let's kill some orcs.

=== Second Set of Guards (Turn 6) ===

'''Guard Leader:''' Are you our relief arriving? Does this mean we get to leave here now?

'''Arvith:''' Um, yes. Fine. You can go.

'''Guard Leader:''' Um, you're supposed to give the password.

'''Arvith:''' Oh, of course. I had nearly forgotten.

'''Guard Leader:''' Thanks! Irritating little formality, isn't it?

'''Arvith:''' I think I should better support my men at the front to make sure we can free my brother.

=== Undead Last Breath ===
'''Rotharik:''' Nooo! This is the end...

'''Unit:''' There's a key in his robes.

'''Arvith:''' That may well be the key to the cell they're holding Baran in! I will take it.

=== Baran's Cell ===
'''Unit:''' I found Baran. He is in this cell.

IF Arvith

'''Baran:''' Good to see you, Arvith. Now can you get me out of this dungeon, please?

IF ANOTHER UNIT

'''Baran:''' You must be one of Arvith's men. Please help me get out of this dungeon.

THEN

IF PLAYER DOES NOT HAVE KEY

'''Baran:''' The accursed dark sorcerer Rotharik has imprisoned me behind this magically enhanced iron gate. It can only be opened with the correct key. You must get it from him to free me.

IF PLAYER HAS KEY

'''Baran:''' Thank you for saving me. I had almost given up hope you would free me.

'''Arvith:''' Oh it was nothing, a few elves, one or two dark sorcerers, a bunch of orcs and some undead. Really just a day's work for us mercenaries.

'''Baran:''' Thank you for coming to my aid. Let us return to the village.

=== Time Over ===
'''Rotharik:''' You are too late! Your brother is already dead! Muhahahaha...

'''Arvith:''' Argh!!!

== Scenario 4: Return to the Village ==

=== Introductory Dialogue ===
'''Arvith:''' There. Your village is just across those hills, and already I see men coming to greet us!

'''Baran:''' No, they are fleeing from something. We must find out what is happening over there!

'''Arvith:''' Men! Ready your weapons!

'''Baran:''' We should go there and talk to Counselor Hoban. Maybe he knows what is going on here.

=== Sighted by Councillor Hoban ===
'''Councillor Hoban:''' I am glad to see you returned.

'''Baran:''' No gladder than I am to be here. But what has happened to Maghre?

'''Councillor Hoban:''' Soon after you departed we were beset by orcs. With half the men of Maghre gone, we could not stop them.

'''Councillor Hoban:''' The orcish warlord aims to enslave us. We will not be able to hold out for much longer.

'''Councillor Hoban:''' Have a care, his men are fell fighters and have killed many. Very few remain who can bear arms, but I will send them to aid you in battle.

=== Enemies Defeated ===
'''Arvith:''' Finally the warlord is killed. Now you can go back to Maghre.

'''Baran:''' So much has been destroyed. It will be difficult to repair all that the orcs and undead have wrecked. And they could come again.

'''Arvith:''' I must go back to earning my living. But you have my word, little brother; if you are beset again, I will come.

=== Baran's Last Breath ===
'''Baran:''' It is over, I am vanquished.

===Time Over===
'''Arvith:''' I don't think we can rescue anyone from these villages. It is too late.

'''Baran:''' I was too weak to protect these people. Oh why did this happen to me?!?

==Scenario 5: Epilogue==
===Story===
It took years to rebuild the village and restore the surrounding farms. The people of Maghre had to work very hard, but felt better knowing Arvith's men would be their firm allies in troubled times.

Arvith and his men left the village assured that it would be well guided by Baran. On their journeys they faced many challenges and battles. Some tales even mention Arvith's name together with that of the famous elvish lord Kalenz, but this is a different story...

==TB's Specified Unit Names==

===Humans===
*[[CharactersStorys#Arvith | Arvith]]
*[[CharactersStorys#Baran | Baran]]
*Alwyn
*Brent
*[[CharactersStorys#Brena | Brena]]
*Cadell
*Dannen
*Efran
*Fargus
*Erik
*Heine
*Magnus
*Councillor Hoban

=== Elves ===
*[[CharactersStorys#Nil-Galion | Nil-Galion]]

===Undead===
=====Human=====
*[[CharactersStorys#Mordak | Mordak]]
*[[CharactersStorys#Muff_Toras | Muff Toras]]
*[[CharactersStorys#Rotharik | Rotharik]]

===Orcs===
*Knago-Brek
*[[CharactersStorys#Tairach | Tairach]]

[[Category:Create|*]]
[[Category:Writing|*]]

CampaignDialogue:TB

2023-08-24T11:39:53Z

Octalot: /* Story */ Revised text from 1.17.20, removing the amulets.

{| style="float:right"
|
__TOC__
|}

This is a transcription of all dialogue from [[A Tale of Two Brothers]]. It is meant as a resource for Wesnoth writers. If you don't want spoilers, leave this page now.

=== Possible Timeframe ===
This campaign, as originally written, had no definite time or place. There was a vague reference to "the eastern reaches of the kingdom of Wesnoth". In a later revision the epilog hint that Arvith may have traveled with the elf-lord Kalenz, but this is not much of a constraint as Kalenz was around in 1YW and at least until the beginning of HttT in 517 YW.

Maghre has to be within reach of the orcs, but in a time and place where there haven't been orc raids for generations. This limits us to *western* Wesnoth, orc raids having been a chronic problem in the northeast even during the Kingdom's strongest periods. The logical time would be shortly after the death of Haldric IV in 350, the beginning of the First Dark Age. It's arbitrarily set at 353; Kalenz began his wanderings ten years later, so the timing for Arvith to meet him later in life isn't bad.

Placing the campaign is a little trickier. Our main textual clue is that there is a dense wood, said by legend to be haunted, a few days' ride north. Later, the boss's keep is said to be still further north. Neither of these directions has plot importance, but they do suggest a locale for Maghre - near the Gray Woods. The battle maps exclude it from being in a featureless plain, though; there are hills to the south and west.

== Death Dialogue ==
=== Mordak ===
'''Mordak:''' Argh

=== Arvith ===
'''Arvith:''' All is lost now that I am dead...

'''Arvith:''' Everything is lost now that I am dead...

== Scenario 1: Rooting Out A Mage ==
=== Story ===
Translation hints: The first paragraph is shown with the journey map as a background, showing the village in the foothills along the route between Aldril and Dan’Tonk. I'm assuming the beacons either use smoke signals or basic fire signals, with a few agreed ones to request goods or indicate that surplus is for sale.

The remote freehold of Maghre in the western reaches of the Kingdom of Wesnoth was once a peaceful place, its inhabitants largely unaware of the comings and goings of the wider world. Wars and the rumor of wars touched them not. Even merchants were rarely seen, although caravans between Aldril and Dan’Tonk might send a wagon when called by the beacon tower.

Then came the day that a dark mage settled in the region and began seeking sacrifices for his summonings.

Skeletons and zombies killed cattle and fired fields. 'Fear and obey Mordak the Mage!' they cried in fell voices as they did their foul deeds. People vanished from isolated farmsteads. Men and women began to fear the night, and their children even the bright day. But the nearest lord was more than a day’s ride distant, and messengers sent to seek his help did not return.

There was a man named Baran who had shown talent as a mage when he was young, gone to the great Academy on the Isle of Alduin, and returned to work his magic in the land where he was born. The people looked to him for help and leadership. He found weapons half-forgotten from the times of their sires and grandsires hanging in many houses, and bade the villagers to take them down and clean and oil them. He set the smiths of Maghre to making spearheads and ax-blades for the rest.

Now Baran had a brother named Arvith who had also left Maghre to seek his fortune, and had become the leader of a small band of horsemen who hired out as guards to merchant caravans. Fortunate it was for all that, in better times, the brothers had talked of using trade beacons for other signals when in dire need. Baran sent out that call.

12 V, 363 YW
Excerpt from the journal of Baran of Maghre

If I could but face this ‘Mordak’! I think my magic might prove stronger than his. But he bides in the hills, well-guarded by his servants, and I muster frightened peasants to fight his minions with blades and sticks.

I need my brother; he always had a better head for battle than I. Yet we have not spoken since that evil day at Toen Caric. If he will not come for me, perhaps he will return to aid our village in its hour of desperate need.

Heeding the call, Arvith gathered such men as he could and hurried to Maghre to help Baran.

=== Introductory Dialogue ===
'''Arvith:''' Greetings, my brother! How may my men and I be of aid?"

'''Baran:''' A dark mage has come upon us; his creatures call him Mordak. They have been terrorizing outlying farms, and we fear they may soon attack the village itself! The villagers of Maghre have taken up weapons but they are not trained fighters; but we need your men, and you to lead them.

'''Baran:''' I can feel Mordak's foul touch on the hidden currents of the earth and air. He is somewhere due north of here, I would say not more than two days' ride.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Baran:''' You shall be the right hand, I the left. I will go stealthily with a handful of our best scouts and woodsmen. While you demonstrate against him and kill his creatures, I will try to defeat Mordak himself with magic at an unguarded moment. Together we may accomplish what either alone may not.

=== Turn 6 ===
'''Arvith:''' Baran should be in position by now. Press them, distract the adept so Baran can spring his trap!

=== Turn 10 ===
'''Arvith:''' Baran has not made his attack! I begin to fear for him... and it means we must deal with this Mordak ourselves!

=== Undead Leader: Last Breath ===
'''Mordak:''' Argh.

'''Arvith:''' Good work, men! But what has become of my brother?

'''Mordak:''' Worried about him, are you? E-he-he..hergh...gaargh...

'''Arvith:''' There's nothing more to be had from this one; we will have to search for Baran ourselves!

'''Unit:''' Sir, our scouts report that Baran was seen captured and carried away further north!

'''Arvith:''' That they should dare this! We will give chase at once.

=== Time Over ===
'''Mordak:''' Your brother's plan to ambush me has failed. He is our prisoner now.

'''Arvith:''' My brother, kidnapped? I have failed you, Baran! And even now Mordak's forces descend upon the village!

=== First Attack ===
'''Arvith:''' I hear these creatures are nigh-immune to our weapons, let us see!

=== Player Kills First Enemy ===
'''Unit:''' That was not so hard!

== Scenario 2: The Chase ==
=== Story ===
The pursuit had already run for several days when the pursuers came to the bounds of the huge forest known as the Gray Woods. Ancient tales wArvithd of lost souls haunting the wood, hunting and killing anyone brave enough to enter it.

Heedless of those rumors, Arvith followed them. His only worry was that his horsemen would be at disadvantage if attacked in the forest.

=== Introductory Dialogue ===
'''Narrator:''' Sounds of a scuffle were heard from the forest.

'''Arvith:''' Come on, men. A stroll through such lovely green woods, what could be finer?

'''Unit:''' It is whispered that hungry ghosts rule this forest, and kill everyone who dares to enter.

'''Arvith:''' I will lead my men, and such villagers as can keep up with us, north to slay this Mordak! What will you do?

'''Nil-Galion:''' You there! Halt and explain yourself.

'''Arvith:''' We're chasing after some men who kidnapped my brother!

'''Nil-Galion:''' Those men told me their prisoner had attempted to murder their master, and wArvithd that evil men would follow him. Advance no further, or you will die.

'''Arvith:''' So much for those ghost stories. Mere elves will not stop me from freeing my brother!

'''Unit:''' I am glad at least that we will not have to face ghosts. But those elves will have us at a disadvantage; our horses will not maneuver well in the trees.

'''Arvith:''' Bah, just stay on the paths; our spearmen and bowmen can fight in the deeper woods. We have faced and won through greater perils than those amateurs can offer.

=== Move to the North ===
'''Unit:''' I see them! There they are!

'''Muff Toras:''' Curses! If they had been an hour slower our master's reinforcements would already be here to meet us.

=== Turn 12 ===
'''Arvith:''' Come on, men, let's catch those kidnappers!

=== Elf Last Breath ===
'''Nil-Galion:''' Foolish human, you have killed me but you will not catch the undead in time. I have fulfilled my contract, and will be reanimated soon to become a lord of their armies.

'''Arvith:''' Follow their back trail!

=== Undead Last Breath ===
'''Muff Toras:''' Hah! You have captured me, but it will avail you nothing. I sent your precious brother the mage north with half my men a day since; he will be safely locked away in our master's dungeons by now.

'''Arvith:''' My blade is at your throat. Give us the way to my brother now, or I will spill your wretched blood on the ground.

'''Muff Toras:''' Three days ride to the northeast, in a deserted castle. The passwords to the guards are --- and ---.

'''Arvith:''' Bind him and take him with us. If he has played us false, he will die.

=== Time Over ===
'''Muff Toras:''' My reinforcements are here!

'''Arvith:''' He escaped us...

=== Victory: Easy ===
'''Brena:''' Greetings. I am Brena, a knight errant. I saw you pursuing and fighting the foul undead. Are there more of them to be destroyed?

'''Arvith:''' Aye. We think there's a nest of them north-east of here. They've captured my brother.

'''Brena:''' I bear a great hatred towards their kind. I will follow and fight them with you, if you permit.

'''Unit:''' He would only slow us down!

'''Arvith:''' It is my place to decide this.

''Option 1''

'''Arvith:''' All right, come along with us.

'''Brena:''' Thank you. My comrades and I will help you on your noble quest.

''Option 2''

'''Arvith:''' I am sorry. We have not the time to spare.

'''Brena:''' Take this, then, for I see that you are on a quest. My comrades will help you whenever you call for them.

== Scenario 3: Guarded Castle ==

=== Introductory Dialogue ===
'''Narrator:''' Arvith's men arrived at the castle and were immediately challenged by some guards.

'''Guard Leader:''' Halt! Friend or foe? Give the password.

'''Arvith:''' The password is ----.

'''Guard Leader:''' Pass friend.

=== Orcs Sighted ===

'''Knago-Brek:''' Haha! We not kill people for long time. Weapon wants blood. We now kill humans!!

'''Arvith:''' My sword-arm has a say in who will do the dying. Come on, men, let's kill some orcs.

=== Second Set of Guards (Turn 6) ===

'''Guard Leader:''' Are you our relief arriving? Does this mean we get to leave here now?

'''Arvith:''' Um, yes. Fine. You can go.

'''Guard Leader:''' Um, you're supposed to give the password.

'''Arvith:''' Oh, of course. I had nearly forgotten.

'''Guard Leader:''' Thanks! Irritating little formality, isn't it?

'''Arvith:''' I think I should better support my men at the front to make sure we can free my brother.

=== Undead Last Breath ===
'''Rotharik:''' Nooo! This is the end...

'''Unit:''' There's a key in his robes.

'''Arvith:''' That may well be the key to the cell they're holding Baran in! I will take it.

=== Baran's Cell ===
'''Unit:''' I found Baran. He is in this cell.

IF Arvith

'''Baran:''' Good to see you, Arvith. Now can you get me out of this dungeon, please?

IF ANOTHER UNIT

'''Baran:''' You must be one of Arvith's men. Please help me get out of this dungeon.

THEN

IF PLAYER DOES NOT HAVE KEY

'''Baran:''' The accursed dark sorcerer Rotharik has imprisoned me behind this magically enhanced iron gate. It can only be opened with the correct key. You must get it from him to free me.

IF PLAYER HAS KEY

'''Baran:''' Thank you for saving me. I had almost given up hope you would free me.

'''Arvith:''' Oh it was nothing, a few elves, one or two dark sorcerers, a bunch of orcs and some undead. Really just a day's work for us mercenaries.

'''Baran:''' Thank you for coming to my aid. Let us return to the village.

=== Time Over ===
'''Rotharik:''' You are too late! Your brother is already dead! Muhahahaha...

'''Arvith:''' Argh!!!

== Scenario 4: Return to the Village ==

=== Introductory Dialogue ===
'''Arvith:''' There. Your village is just across those hills, and already I see men coming to greet us!

'''Baran:''' No, they are fleeing from something. We must find out what is happening over there!

'''Arvith:''' Men! Ready your weapons!

'''Baran:''' We should go there and talk to Counselor Hoban. Maybe he knows what is going on here.

=== Sighted by Councillor Hoban ===
'''Councillor Hoban:''' I am glad to see you returned.

'''Baran:''' No gladder than I am to be here. But what has happened to Maghre?

'''Councillor Hoban:''' Soon after you departed we were beset by orcs. With half the men of Maghre gone, we could not stop them.

'''Councillor Hoban:''' The orcish warlord aims to enslave us. We will not be able to hold out for much longer.

'''Councillor Hoban:''' Have a care, his men are fell fighters and have killed many. Very few remain who can bear arms, but I will send them to aid you in battle.

=== Enemies Defeated ===
'''Arvith:''' Finally the warlord is killed. Now you can go back to Maghre.

'''Baran:''' So much has been destroyed. It will be difficult to repair all that the orcs and undead have wrecked. And they could come again.

'''Arvith:''' I must go back to earning my living. But we have our amulets, little brother. If you are beset again, I will come.

=== Baran's Last Breath ===
'''Baran:''' It is over, I am vanquished.

===Time Over===
'''Arvith:''' I don't think we can rescue anyone from these villages. It is too late.

'''Baran:''' I was too weak to protect these people. Oh why did this happen to me?!?

==Scenario 5: Epilogue==
===Story===
It took years to rebuild the village and restore the surrounding farms. The people of Maghre had to work very hard, but felt better knowing Arvith's men would be their firm allies in troubled times.

Arvith and his men left the village assured that it would be well guided by Baran. On their journeys they faced many challenges and battles. Some tales even mention Arvith's name together with that of the famous elvish lord Kalenz, but this is a different story...

==TB's Specified Unit Names==

===Humans===
*[[CharactersStorys#Arvith | Arvith]]
*[[CharactersStorys#Baran | Baran]]
*Alwyn
*Brent
*[[CharactersStorys#Brena | Brena]]
*Cadell
*Dannen
*Efran
*Fargus
*Erik
*Heine
*Magnus
*Councillor Hoban

=== Elves ===
*[[CharactersStorys#Nil-Galion | Nil-Galion]]

===Undead===
=====Human=====
*[[CharactersStorys#Mordak | Mordak]]
*[[CharactersStorys#Muff_Toras | Muff Toras]]
*[[CharactersStorys#Rotharik | Rotharik]]

===Orcs===
*Knago-Brek
*[[CharactersStorys#Tairach | Tairach]]

[[Category:Create|*]]
[[Category:Writing|*]]

EventWML

2023-08-11T06:58:29Z

Octalot: /* Optional Keys and Tags */ Add the priority attribute

{{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] 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 term "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).

==== Variables in the name ====

If the name contains variables, they will be substituted each time the event is triggered. For example, '''name=turn $disaster_turn''' will only trigger if the turn number is currently equal to whatever number is stored in the variable '''$disaster_turn'''; updating the variable will adjust the turn that the event triggers on. However, if the variable contents contains a comma, it won't be parsed after substitution. Since an event name can't contain a comma, this means the event will never trigger.

{{DevFeature1.17|6}}

Commas resulting from variable substitution are now parsed. If you write '''name=$important_event''' and the variable '''$important_event''' contains the text "capture,die", the event will trigger on either a death or a village capture.

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

==== priority ====
: {{DevFeature1.17|20}} If several '[event]' tags have the same name, then any with a high priority value will be triggered before events with a lower priority value. Negative numbers are also supported, to run after events without a priority (as the attribute defaults to zero). For events with equal priority, the order is determined by the order in which the events were added.

==== [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_id''': filter on the attack's weapon special id.
:* '''special_type''': filter on the attack's weapon special type.
:* {{DevFeature1.17|15}} '''special_id_active''': filter on the attack's weapon special id active(encoded in [specials] or [abilities] tags).
:* {{DevFeature1.17|15}} '''special_type_active''': filter on the attack's weapon special type active(encoded in [specials] or [abilities] tags).

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

==== [insert_tag] ====
: An '''[insert_tag]''' that expands to any of the above filter tags will result in the filter being loaded from the variable each time the game checks if the event should fire. This can result in the event's filter varying from turn to turn.

==== filter_formula ====
:{{DevFeature1.17|6}}
: Similar to [filter_condition], but the condition is expressed in [[Wesnoth Formula Language]]. The formula has access to the following keys:
:*Event information:
:**'''event''' - the event name
:**'''event_id''' - the event's unique ID
:**'''event_data''' - additional information specific to the event, such as owner_side or damage_inflicted, or anything passed in '''[fire_event][data]'''.
:**'''loc''', '''unit''' - primary event location and unit
:**'''second_loc''', '''second_unit''' - secondary event location and unit
:**'''weapon''', '''second_weapon''' - primary and secondary weapon
:*Gamestate information:
:**'''turn_number'''
:**'''time_of_day''' - the time of day ID
:**'''side_number''' - currently active side
:**'''sides''' - a list of all sides
:**'''units''' - a list of all units on the map
:**'''map''' - the entire game map as a two-dimensional array

==== 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]]. Actions can also be dynamically inserted via '''[insert_tag]'''.

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.

=== pre attack {{DevFeature1.17|7}}===

Similar to '''attack''', but is triggered before calculating the number of attacks and the movement of the unit. Can be used for modifications, which affect these values.

=== 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]]

ScenarioWML

2023-07-05T10:26:06Z

Octalot: /* The [test] tag */ Remove mention of macros, as their availability is based on the file inclusion order

{{WML Tags}}

The top level tags '''[multiplayer]''', '''[test]''', and '''[scenario]''' are [[AddonsWML|addon module]] tags that are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios (without ''allow_new_game=no'') are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
* Any '''[test]''' scenario is an initial scenario. A test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test followed by an optional scenario ID which defaults to 'test'.) {{DevFeature1.13|8}} It can also be accessed by assigning a hotkey to the "Test Scenario" command in hotkey preferences, then pressing that hotkey at the title screen. This will bring up a list of interactive test scenarios to choose from. (Automated test scenarios used for unit testing are excluded from this list but can still be run from the command-line.)
* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

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

* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.
* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.
* '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
** {{DevFeature1.15|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D|[replace_map]]].
** {{DevFeature1.15|4}} the file can be a WML file with the contents of a '''[scenario]''' tag, which will be merged in to the current scenario. For example, the map file can include named '''[time_area]'''s. There's more detail in PR #4999.
* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. Default value is ''-1'' on wesnoth-1.13 and ''100'' on wesnoth-1.12. See also [[EventWML]]
* '''turn_at''': the turn to start on (default=1)
*: Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn [[EventWML|WML events]] will still be fired, however.
* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default depends on version and mp/sp, better include this key)
* '''music''': the music file relative to ''./music/'' to play during the scenario
* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].
* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''theme''': the name of the UI theme that should be used when playing this scenario. Valid ids to use can be found in the files in data/themes. Cutscene and Cutscene_Minimal can be useful for dialog only scenarios.
* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) See Also [[SideWML]]. When this value is true the following keys can be used:
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''remove_from_carryover_on_defeat''': when this is set to '''yes''' (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.
* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.
* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.
* '''do_healing''': {{DevFeature1.15|0}} when set to yes, the engine will not skip healing at the first sides turn and will do the healing just like every other turn.
* '''[story]''': describes the intro screen. See [[IntroWML]]
* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label
* '''[item]''': places an item on map. See [[InterfaceActionsWML#.5Bitem.5D|InterfaceActionsWML]].
* '''[time]''': how a day should progress. See [[TimeWML]]
* '''current_time''': The time of day slot number (starting from zero) active at scenario start.
* '''[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
** takes x and y coordinates.
** '''[time]''': how a day should progress in those locations. See [[TimeWML]]
** '''current_time''': The time slot number (starting with zero) active at the creation of the area.
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].
* '''[side]''': describes one player. See [[SideWML]]
* '''map_generation''': another way to generate a map. The map will be generated randomly
** '''default''': the default random map generator
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]
* [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.
* [[GameConfigWML#Color_Palettes|Color palettes]]

== The [multiplayer] tag ==

The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:

* '''force_lock_settings''': provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=yes'' in [[SideWML]].
* '''new_game_title''': if provided will be used instead of '''name''' for campaign entry points.
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.
* '''allow_era''': a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.
* '''disallow_era''': a list of era ids. Eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.
* '''ignore_incompatible_era''': a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.
* '''allow_modification''': same as allow_era, but for modifications.
* '''disallow_modification''': same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': same as ignore_incompatible_era, but for modifications.
* '''force_modification''': a list of modification ids (id key in [modification]). The specified modifications must be enabled to play this scenario.
* '''require_scenario''': {{DevFeature1.13|0}} In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the '''addon_min_version''' attribute will control the minimum version number of your add-on which is compatible with this version.
* '''mp_village_gold''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_village_support''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_shroud''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_fog''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''

== The [test] tag ==

The following keys and subtags are additionally recognized in '''[test]''' scenarios:

* '''is_unit_test''': {{DevFeature1.13|8}} If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.

The tags documented in [[TestWML]] are enabled by an #ifdef TEST conditional, and it's a reasonable assumption that any [test] tag will itself be inside an #ifdef TEST conditional.

== Defining the Map ==

There are several possible ways to define the map for a scenario. First of all, the game supports two different types of map: a "plain map", which typically has a .map extension (or occasionally .mask when used as a terrain mask), and a "scenario map", which has a .cfg extension.

A common practice is to include the map data directly into the scenario. If you're using a plain map, that looks like this:

<syntaxhighlight lang=wml>
[scenario]
map_data="{~add-ons/Your_Addon/maps/the-file.map}"
[/scenario]
</syntaxhighlight>

This uses the WML preprocessor to directly include the contents of the map file. If you're using a scenario map, it instead looks like this:

<syntaxhighlight lang=wml>
[scenario]
{~add-ons/Your_Addon/maps/the-file.cfg}
[/scenario]
</syntaxhighlight>

Another way to specify the map is to use '''map_file''', which resolves the map against the [[BinaryPathWML|binary path]] to locate the file. This looks the same for either a plain map or a scenario map:

<syntaxhighlight lang=wml>
[scenario]
map_file="the-file.map"
[/scenario]
</syntaxhighlight>

The last way to specify a map is to use a [[MapGeneratorWML|generator]].

== Scenario End Conditions ==

In this section we will give a more precise explanation of things that can cause a scenario to end.

* At the '''end of every turn''', the turn number will be compared with the turn limit.
** If we pass the limit, the ''time over'' event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. [[EventWML#The_.27name.27_Key_.28Mandatory.29]]
* At the '''beginning of any turn''', and at '''the end of any user or ai action''', the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:
** Every side will have its ''defeat_condition'' evaluated based on the units it currently has on the board. [[SideWML]]
*** At this time, villages of defeated sides will be unflagged, and if ''remove_from_carryover_on_defeat = yes'' then their carryover will be cleared as well.
** If any two not-defeated sides are enemies, the scenario will continue.
*** At this time, the ''enemies defeated'' event will fire.
** Furthermore, if ''victory_when_enemies_defeated=no'' and there exists a human controlled side, then the scenario will continue.
*** The human controlled side may be local or remote, for networked mp play.
** If neither of these conditions is met then the scenario will end.
***In victory or defeat according to whether a local human-controlled side is not defeated.

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ScenarioWML

2023-07-05T10:19:03Z

Octalot: /* The [test] tag */ Link to TestWML

{{WML Tags}}

The top level tags '''[multiplayer]''', '''[test]''', and '''[scenario]''' are [[AddonsWML|addon module]] tags that are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios (without ''allow_new_game=no'') are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
* Any '''[test]''' scenario is an initial scenario. A test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test followed by an optional scenario ID which defaults to 'test'.) {{DevFeature1.13|8}} It can also be accessed by assigning a hotkey to the "Test Scenario" command in hotkey preferences, then pressing that hotkey at the title screen. This will bring up a list of interactive test scenarios to choose from. (Automated test scenarios used for unit testing are excluded from this list but can still be run from the command-line.)
* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

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

* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.
* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.
* '''map_file''': {{DevFeature1.14|3}} path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
** {{DevFeature1.15|3}} the file can be found via [binary_path], as documented for [[DirectActionsWML#.5Breplace_map.5D|[replace_map]]].
** {{DevFeature1.15|4}} the file can be a WML file with the contents of a '''[scenario]''' tag, which will be merged in to the current scenario. For example, the map file can include named '''[time_area]'''s. There's more detail in PR #4999.
* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. Default value is ''-1'' on wesnoth-1.13 and ''100'' on wesnoth-1.12. See also [[EventWML]]
* '''turn_at''': the turn to start on (default=1)
*: Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn [[EventWML|WML events]] will still be fired, however.
* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default depends on version and mp/sp, better include this key)
* '''music''': the music file relative to ''./music/'' to play during the scenario
* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].
* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.
* '''theme''': the name of the UI theme that should be used when playing this scenario. Valid ids to use can be found in the files in data/themes. Cutscene and Cutscene_Minimal can be useful for dialog only scenarios.
* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) See Also [[SideWML]]. When this value is true the following keys can be used:
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''remove_from_carryover_on_defeat''': when this is set to '''yes''' (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.
* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.
* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.
* '''do_healing''': {{DevFeature1.15|0}} when set to yes, the engine will not skip healing at the first sides turn and will do the healing just like every other turn.
* '''[story]''': describes the intro screen. See [[IntroWML]]
* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label
* '''[item]''': places an item on map. See [[InterfaceActionsWML#.5Bitem.5D|InterfaceActionsWML]].
* '''[time]''': how a day should progress. See [[TimeWML]]
* '''current_time''': The time of day slot number (starting from zero) active at scenario start.
* '''[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
** takes x and y coordinates.
** '''[time]''': how a day should progress in those locations. See [[TimeWML]]
** '''current_time''': The time slot number (starting with zero) active at the creation of the area.
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].
* '''[side]''': describes one player. See [[SideWML]]
* '''map_generation''': another way to generate a map. The map will be generated randomly
** '''default''': the default random map generator
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]
* [[TerrainGraphicsWML]]: Scenarios can define custom terrain rules for the rendering of the map.
* [[GameConfigWML#Color_Palettes|Color palettes]]

== The [multiplayer] tag ==

The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:

* '''force_lock_settings''': provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=yes'' in [[SideWML]].
* '''new_game_title''': if provided will be used instead of '''name''' for campaign entry points.
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.
* '''allow_era''': a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.
* '''disallow_era''': a list of era ids. Eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.
* '''ignore_incompatible_era''': a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.
* '''allow_modification''': same as allow_era, but for modifications.
* '''disallow_modification''': same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': same as ignore_incompatible_era, but for modifications.
* '''force_modification''': a list of modification ids (id key in [modification]). The specified modifications must be enabled to play this scenario.
* '''require_scenario''': {{DevFeature1.13|0}} In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the '''addon_min_version''' attribute will control the minimum version number of your add-on which is compatible with this version.
* '''mp_village_gold''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_village_support''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_shroud''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''
* '''mp_fog''': {{DevFeature1.13|9}} default value for the corresponding attribute in '''[side]'''

== The [test] tag ==

The following keys and subtags are additionally recognized in '''[test]''' scenarios:

* '''is_unit_test''': {{DevFeature1.13|8}} If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.

The tags and macros documented in [[TestWML]] are recognized when '''#ifdef TEST''' is true. It's a reasonable assumption that any '''[test]''' tag will itself be inside an '''#ifdef TEST''' conditional.

== Defining the Map ==

There are several possible ways to define the map for a scenario. First of all, the game supports two different types of map: a "plain map", which typically has a .map extension (or occasionally .mask when used as a terrain mask), and a "scenario map", which has a .cfg extension.

A common practice is to include the map data directly into the scenario. If you're using a plain map, that looks like this:

<syntaxhighlight lang=wml>
[scenario]
map_data="{~add-ons/Your_Addon/maps/the-file.map}"
[/scenario]
</syntaxhighlight>

This uses the WML preprocessor to directly include the contents of the map file. If you're using a scenario map, it instead looks like this:

<syntaxhighlight lang=wml>
[scenario]
{~add-ons/Your_Addon/maps/the-file.cfg}
[/scenario]
</syntaxhighlight>

Another way to specify the map is to use '''map_file''', which resolves the map against the [[BinaryPathWML|binary path]] to locate the file. This looks the same for either a plain map or a scenario map:

<syntaxhighlight lang=wml>
[scenario]
map_file="the-file.map"
[/scenario]
</syntaxhighlight>

The last way to specify a map is to use a [[MapGeneratorWML|generator]].

== Scenario End Conditions ==

In this section we will give a more precise explanation of things that can cause a scenario to end.

* At the '''end of every turn''', the turn number will be compared with the turn limit.
** If we pass the limit, the ''time over'' event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. [[EventWML#The_.27name.27_Key_.28Mandatory.29]]
* At the '''beginning of any turn''', and at '''the end of any user or ai action''', the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:
** Every side will have its ''defeat_condition'' evaluated based on the units it currently has on the board. [[SideWML]]
*** At this time, villages of defeated sides will be unflagged, and if ''remove_from_carryover_on_defeat = yes'' then their carryover will be cleared as well.
** If any two not-defeated sides are enemies, the scenario will continue.
*** At this time, the ''enemies defeated'' event will fire.
** Furthermore, if ''victory_when_enemies_defeated=no'' and there exists a human controlled side, then the scenario will continue.
*** The human controlled side may be local or remote, for networked mp play.
** If neither of these conditions is met then the scenario will end.
***In victory or defeat according to whether a local human-controlled side is not defeated.

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Template:WML Tags

2023-07-02T17:36:42Z

Octalot: Link to test_do_attack_by_id

{| class="reference-sidebar"
|-
|
[[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit]]'''WML Tags'''
|-
|''A:''
[[AbilitiesWML|abilities]],
[[CreditsWML#.5Babout.5D|about]],
[[AchievementsWML|achievement]],
[[AchievementsWML|achievement_group]],
[[Creating_Custom_AIs#Behavior_Candidate_Actions|add_ai_behavior]],
[[SingleUnitWML|advance]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML|advancefrom]],
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|affect_adjacent]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],
[[StandardSideFilter|allied_with]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta-Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML|animation]],
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],
attack ([[ReplayWML|replay]], [[UnitTypeWML#Attacks|weapon]]),
[[AnimationWML|attack_anim]],
attacks ([[AbilitiesWML#The_.5Bspecials.5D_tag|special]], [[StatisticalScenarioWML#The_.5Bteam.5D_tag|stats]]),
[[AiWML#List_of_AI_Aspects|avoid]];
|-
|''B:''
[[UnitTypeWML#Other_tags|base_unit]],
[[IntroWML#.5Bbackground_layer.5D|background_layer]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|berserk]],
[[BinaryPathWML|binary_path]],
[[InternalActionsWML#Flow_control_actions|break]],
[[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcancel_action.5D|cancel_action]],
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]],
[[InterfaceActionsWML#.5Bchange_theme.5D|change_theme]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[OptionWML|checkbox]],
[[OptionWML|choice]],
[[ReplayWML|choose]],
[[PersistenceWML|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],
[[GameConfigWML#Color_Palettes|color_palette]],
[[GameConfigWML#Color_Palettes|color_range]],
command ([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),
[[InternalActionsWML#Flow_control_actions|continue]],
[[CreditsWML#.5Bcredits_group.5D|credits_group]],
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];
|-
|''D:''
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],
[[AnimationWML#death|death]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],
[[AnimationWML#default|default]],
[[AnimationWML#defend|defend]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],
[[UnitsWML#.5Bmovetype.5D|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML|destination]],
[[CampaignWML|difficulty]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|disable]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]],
[[DirectActionsWML#.5Bdo_command.5D|do_command]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]],
[[AnimationWML#draw_weapon_anim|draw_weapon_anim]];
|-
|''E:''
[[EditorWML#The_.5Beditor_group.5D_tag|editor_group]],
[[EditorWML#The_.5Beditor_music.5D_tag|editor_music]],
[[EditorWML#The_.5Beditor_times.5D_tag|editor_times]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML|replay]]),
[[StandardSideFilter|enemy_of]],
[[Wesnoth_AI_Framework#Available_Engines|engine]],
entry ([[CreditsWML#.5Bentry.5D|credits]], [[OptionWML|options]]),
[[EraWML|era]],
[[EventWML|event]],
[[AnimationWML#Simplified_animation_blocks|extra_anim]];
|-
|''F:''
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]],
[[ConditionalActionsWML#.5Bfalse.5D|false]],
[[PblWML#.5Bfeedback.5D|feedback]],
[[UnitTypeWML#Other_tags|female]],
filter ([[FilterWML|concept]], [[EventWML#.5Bfilter.5D|event]]),
[[StandardUnitFilter|filter_adjacent]],
[[StandardLocationFilter|filter_adjacent_location]],
[[FilterWML#Filtering_Weapons|filter_attack]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_attacker]],
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|filter_base_value]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_defender]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_enemy]],
[[StandardLocationFilter|filter_location]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_opponent]],
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_own]],
[[StandardLocationFilter|filter_owner]],
[[StandardLocationFilter|filter_radius]],
[[SingleUnitWML|filter_recall]],
[[StandardUnitFilter|filter_second]],
[[FilterWML#Filtering_Weapons|filter_second_attack]],
[[AbilitiesWML|filter_self]],
[[StandardSideFilter|filter_side]],
[[AbilitiesWML|filter_student]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_weapon]],
[[FilterWML#Filtering_on_WML_data|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[ConditionalActionsWML#.5Bfound_item.5D|found_item]],
[[ConditionalActionsWML#.5Bfor.5D|for]],
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],
[[AnimationWML#Frames|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[PersistenceWML|get_global_variable]],
[[AiWML#The_.5Bgoal.5D_Tag|goal]],
[[DirectActionsWML#.5Bgold.5D|gold]],
[[InterfaceActionsWML#.5Bobjectives.5D|gold_carryover]];
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[StandardSideFilter|has_ally]],
[[StandardUnitFilter|has_attack]],
[[StandardSideFilter|has_unit]],
[[ConditionalActionsWML#.5Bhas_achievement.5D|has_achievement]],
[[ConditionalActionsWML#.5Bhave_location.5D|have_location]],
[[ConditionalActionsWML#.5Bhave_unit.5D|have_unit]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[AnimationWML#healed|healed_anim]],
[[AnimationWML#healing|healing_anim]],
[[AbilitiesWML|heals]],
[[UnitsWML#.5Bhide_help.5D|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],
[[AbilitiesWML|hides]];
|-
|''I:''
[[AnimationWML#idling|idle_anim]],
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]], [[IntroWML|intro]]),
[[AbilitiesWML|illuminates]],
image ([[IntroWML#.5Bimage.5D|intro]], [[TerrainGraphicsWML|terrain]]),
[[ReplayWML|init_side]],
[[InternalActionsWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[InterfaceActionsWML#.5Bitem.5D|item]],
[[EditorWML#The_.5Bitem_group.5D_tag|item_group]];
|-
|''J:''
[[UnitsWML#.5Bmovetype.5D|jamming_costs]],
[[InternalActionsWML#.5Bset_variable.5D|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML|killed]];
|-
|''L:''
[[InterfaceActionsWML#.5Blabel.5D|label]],
[[LanguageWML|language]],
[[SideWML|leader]],
[[AiWML#List_of_AI_Aspects|leader_goal]],
[[AbilitiesWML|leadership]],
[[AnimationWML#leading|leading_anim]],
[[AnimationWML#levelin|levelin_anim]],
[[AnimationWML#levelout|levelout_anim]],
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],
[[AI_Recruitment#Aspect_recruitment_instructions|limit]],
[[InternalActionsWML#.5Bset_variables.5D|literal]],
[[AddonsWML|load_resource]],
[[LocaleWML|locale]],
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],
[[LuaWML|lua]];
|-
|''M:''
[[UnitTypeWML#Other_tags|male]],
[[SavefileWML|menu_item]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[Micro AIs|micro_ai]],
[[AnimationWML#The_content_of_a_frame|missile_frame]],
[[ModificationWML|modification]],
[[SingleUnitWML|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[AddonsWML|modify_unit_type]],
[[ReplayWML|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[AnimationWML#movement|movement_anim]],
[[UnitsWML#.5Bmovetype.5D|movement costs]],
[[UnitsWML#.5Bmovetype.5D|movetype]],
[[ScenarioWML|multiplayer]],
[[EraWML#Defining_Factions|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
[[ConditionalActionsWML#Meta-Condition_Tags|not]],
[[InterfaceActionsWML#.5Bobjectives.5D|note]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[DirectActionsWML#.5Bon_undo.5D|on_undo]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML#.5Bmessage.5D|option]],
[[OptionWML|options]],
[[ConditionalActionsWML#Meta-Condition_Tags|or]];
|-
|''P:''
[[IntroWML|part]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]],
[[DirectActionsWML#.5Bpetrify.5D|petrify]],
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]],
[[UnitTypeWML#Other_tags|portrait]],
[[AnimationWML#post_movement|post_movement_anim]],
[[AnimationWML#pre_movement|pre_movement_anim]],
[[InternalActionsWML#.5Bfire_event.5D|primary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|primary_unit]],
[[InterfaceActionsWML#.5Bprint.5D|print]],
[[DirectActionsWML#.5Bprogress_achievement.5D|progress_achievement]],
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];
|-
|''R:''
[[UnitsWML#.5Brace.5D|race]],
[[InternalActionsWML#.5Brandom_placement.5D|random_placement]],
recall ([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML|replay]]),
[[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]],
[[AnimationWML#recruited|recruit_anim]],
[[AnimationWML#recruiting|recruiting_anim]],
[[StatisticalScenarioWML|recruits]],
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[AbilitiesWML|regenerate]],
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]],
[[DirectActionsWML#.5Bremove_object.5D|remove_object]],
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]],
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]],
[[DirectActionsWML#.5Bremove_trait.5D|remove_trait]],
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]],
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]],
[[ReplayWML|replay]],
[[SavefileWML|replay_start]],
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]],
resistance ([[AbilitiesWML|ability]], [[UnitsWML#.5Bmovetype.5D|unit]]),
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],
[[InternalActionsWML#Flow_control_actions|return]],
[[InternalActionsWML#.5Brole.5D|role]],
[[TerrainMaskWML|rule]];
|-
|''S:''
[[SavefileWML|save]],
[[ScenarioWML|scenario]],
[[InterfaceActionsWML#.5Bscreen_fade.5D|screen_fade]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]],
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_attack]],
[[InternalActionsWML#.5Bfire_event.5D|secondary_unit]],
[[HelpWML|section]],
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]],
[[ReplayWML|sequence]],
[[DirectActionsWML#.5Bset_achievement.5D|set_achievement]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[PersistenceWML|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]],
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[EffectWML|set_specials]],
[[InternalActionsWML#.5Bset_variable.5D|set_variable]],
[[InternalActionsWML#.5Bset_variables.5D|set_variables]],
[[AnimationWML#sheath_weapon|sheath_weapon_anim]],
show_if ([[InterfaceActionsWML#.5Bmessage.5D|message]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]],
[[AbilitiesWML|skirmisher]],
[[OptionWML|slider]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]],
[[SavefileWML|snapshot]],
[[InterfaceActionsWML#.5Bsound.5D|sound]],
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]],
source ([[ReplayWML|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),
[[UnitTypeWML#Other_tags|special_note]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]],
[[InternalActionsWML#.5Bset_variables.5D|split]],
[[Wesnoth_AI_Framework#Available_Stages|stage]],
[[AnimationWML#standing|standing_anim]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[SingleUnitWML|status]],
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]],
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]],
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]],
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]],
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]],
[[InternalActionsWML#.5Bstore_unit_defense.5D|store_unit_defense]],
[[InternalActionsWML#.5Bstore_unit_defense_on.5D|store_unit_defense_on]],
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],
[[IntroWML|story]],
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]],
[[AchievementsWML|sub_achievement]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]],
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];
|-
|''T:''
[[DirectActionsWML#.5Btunnel.5D|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[AbilitiesWML|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),
[[AnimationWML#pre_teleport|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]],
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],
[[TerrainGraphicsWML|terrain_graphics]],
[[TerrainMaskWML|terrain_mask]],
[[TerrainWML|terrain_type]],
[[ScenarioWML#The_.5Btest.5D_tag|test]],
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],
[[TestWML#The_.5Btest_do_attack_by_id.5D_tag|test_do_attack_by_id]],
[[InterfaceActionsWML#.5Bmessage.5D|text_input]],
[[GettextForWesnothDevelopers#The_textdomain_tag|textdomain]],
[[ThemeWML|theme]],
[[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]],
[[TimeWML|time]],
[[DirectActionsWML#.5Btime_area.5D|time_area]],
[[HelpWML|topic]],
[[HelpWML|toplevel]],
[[UnitsWML#.5Btrait.5D|trait]],
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]],
[[InternalActionsWML#.5Bfind_path.5D|traveler]],
[[ConditionalActionsWML#.5Btrue.5D|true]],
[[DirectActionsWML#.5Btunnel.5D|tunnel]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]],
[[SingleUnitWML|unit]],
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]],
[[UnitTypeWML|unit_type]],
[[InternalActionsWML#.5Bunit_worth.5D|unit_worth]],
[[UnitsWML|units]],
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]],
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]],
[[InternalActionsWML#.5Bunsynced.5D|unsynced]];
|-
| ''V:''
[[InternalActionsWML#.5Bset_variables.5D|value]],
[[ConditionalActionsWML#.5Bvariable.5D|variable]],
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],
[[TerrainGraphicsWML|variant]],
[[UnitTypeWML#Other_tags|variation]],
[[AnimationWML#victory|victory_anim]],
[[SideWML|village]],
[[UnitsWML#.5Bmovetype.5D|vision_costs]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]],
[[SchemaWML|wml_schema]];
|-
| ''Z:''
[[InterfaceActionsWML#.5Bzoom.5D|zoom]];
|}<includeonly>[[Category:WML Reference]]</includeonly><noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the WML reference pages.</noinclude>

TestWML

2023-07-02T17:35:10Z

Octalot: Document [test_do_attack_by_id]

{{WML Tags}}

The tags and macros on this page are for use in unit tests, they're defined in data/test and enabled when '''#ifdef TEST''' is true.

The main '''[test]''' tag is documented on the [[ScenarioWML#The_.5Btest.5D_tag|ScenarioWML]] page.

== The [test_do_attack_by_id] tag ==

The '''[test_do_attack_by_id]''' tag is a wrapper for [[ReplayWML|[do_command][attack]]], taking unit ids instead of map coordinates. It has the following attributes:

* '''attacker''' the unit that initiates the attack
* '''defender''' the unit being attacked
* '''weapon''' (unset by default) if set, is used as the value for [do_command][attack]weapon=
* '''defender_weapon''' (unset by default) if set, is used as the value for [do_command][attack]defender_weapon=
* '''resupply_attacks_left''' (unset by default) if set to an integer higher than attacker.attacks_left, then attacker.attacks_left will be set to this value before calling [do_command][attack]

The reason for making this a test-only tag is that it can handle errors by failing the test, or by doing nothing and having the test fail later. Using unit IDs helps avoid hardcoding map coordinates in tests, and in tests the author is expected to know exactly which units should be involved. Even if this was a generic tag, it's likely that its only use outside tests would only be in events that already auto-store '''$unit''', and either auto-store '''$second_unit''' or already include a hardcoded '''x,y=''' filter.

An alternative would be a generic tag taking SUFs for attacker and defender, but outside unit tests, there's a possibility of there being no unit matching the SUF, many units matching the SUF, or that the two units aren't adjacent to each other.

== See Also ==

* [[LuaAPI/unit_test|LuaAPI for unit tests]]

[[Category: WML Reference]]