Jarom: fixed heading

2021-11-25T15:24:29Z

fixed heading

Jarom: Created page with "'''Expanding the campaign definition (and macros)''' In the previous part of this tutorial we made a minimal working example that could be run and pla..."

2021-11-25T15:09:19Z

Created page with "'''Expanding the campaign definition (and macros)''' In the previous part of this tutorial we made a minimal working example that could be run and pla..."

New page

'''Expanding the campaign definition (and macros)'''

In the [[MakingCampaignInWML|previous part]] of this tutorial we made a minimal working example that could be run and played, but it's far from the usual content of a campaign. If you have ADHD or for some other reason don't want to read all the descriptions, jump to the [[#TL;DR|TL;DR]].

== Textdomain ==
Let's start by introducing the very common content of add-on's _main.cfg file, that is the textdomain. It allows your campaign to be translated and it's better to do that at the very start than try to add it later, especially since it's mostly unobtrusive and doesn't take much time. First, let's add a [[GettextForWesnothDevelopers#The_textdomain_tag|'''[textdomain]''']] tag, it's typically located before [[CampaignWML|'''[campaign]''']] and looks like:

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

The '''name=''' key is most important. Your textdomain name should start with ''wesnoth-'', and after that it typically uses your add-on's folder name for a good reason - this name will be used as folder name again.

The '''path=''' key contains the path to your translation root relative to the userdata folder, typically it's the same as in ''[binary_path]'' but with ''/translations'' at the end.
:You don't have to add /translations at the end but you should. Although having your main folder as translation root will flatten your folder structure for translation, which can possibly make access to it faster, it'll be confusing for others, so it's discouraged.

The reference advises to create translations folder now, but it doesn't need to have content for now and actually everything will work even if you don't.

Note that mainline campaigns have different content in this tag because their translations are handled by game core, so don't copy their way.

Now, we're going to add a '''#textdomain''' directive. It's typically the first line of any ''.cfg'' file containing translatable strings. For our example it'll be:

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
</syntaxhighlight>

'''#texdomain''' is a fixed part, and after a space there should be your textdomain name, exactly the same as in ''name='' key in ''[textdomain]'' tag. You should place the exact same line in your scenario file, but not in your map file. If you have a .cfg file that you're sure that it won't have any translatable strings, you can use '''#wmllint: no translatables''' instead, but if you're not sure, just add the full ''#textdomain'' directive or leave nothing. Don't put any of these in files other than those with .cfg extension.

== Visuals ==

Your campaign entry in the campaigns menu looks very barebones for now. Let's add a little variety.
First, an icon. It will show on campaigns list and is considered pretty mandatory. It's customary to use an image that's usually displayed on the map, like an item or a unit. In this example we're going to use a book from mainline as an icon:

<syntaxhighlight lang=wml>
icon = "items/book3.png"
</syntaxhighlight>

Place this inside your ''[campaign]'' tag. If you're planning to use custom images, see the [[#Note about custom images|note about paths]] below. Note that it's customary to wrap file paths and certain other strings in double quotes, but usually they are not necessary. Don't add the _ (underscore) before though, because this is NOT translatable.

Other images also go inside ''[campaign]'' tag but are much more optional, even mainline campaigns not always use them:

<syntaxhighlight lang=wml>
image = "portraits/humans/longbowman.png"
</syntaxhighlight>

This will show below the description (we'll add one soon) and it's usually a unit/character portrait. It's optional, but quite common. We're using the portrait of Wesnoth's longbowman as an example.

<syntaxhighlight lang=wml>
background = "story/grim-altar.jpg"
</syntaxhighlight>

This is a new feature, introduced in 1.15 versions, so it's not commonly used. It replaces the default background of the campaign menu when our campaign is selected. Typically uses story/cutscene background images. Note that Wesnoth backgrounds in the story folder have atypical .jpg extension, but it's not necessarily the case for other background images.

:=== Note about custom images ===
:Usually you could access an image, e.g. "snow-golem.png" in your add-on's images folder by just writing "snow-golem.png". But that's because you use [binary_path] to access it. However, our [binary_path] is inside #ifdef, which only loads AFTER we start the campaign, so the game doesn't know about it when we're in campaign selection menu.
:To use custom images in your [campaign] tag you have to use fully qualified names, relative to userdata folder, that is, the same as you used in [binary_path] and [textdomain]. For the afforementioned snow golem image you'd have to write ''data/add-ons/WML_Tutorial/images/snow-golem.png''.
:There's a trick that can simplify it, but you'll learn it later.

Now, let's move to the '''description'''. In mainline campaigns it's usually splitted into two parts, the actual description and difficulty/length addition, for translation purposes. Don't forget to mark each part as translatable whether you split or not.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario.)"
</syntaxhighlight>

Note that you mustn't tabulate the description inside quotes in multiline description, as it'll be added to the string and shown in the game. You can use fancy formatting, as described [[InterfaceActionsWML#Formatting|here]].
:Centering the description
:There exists a key description_alignment= if you want to center your description like the one in The Sceptre of Fire. It doesn't add the italics though.
:<syntaxhighlight lang=wml>
description_alignment = center
</syntaxhighlight>
:It won't appear in code examples later.

There's one more purely visual thing, but it only shows in save filenames - the '''abbrev'''. It's recommended to set that. First derive an abbreviation of your campaign from its name. For example, The Rise of Wesnoth is abbreviated TRoW and Under the Burning Suns is UtBS. For this example add-on, we'll use WMLT. Note that abbreviations vary between languages, so this is translatable.

<syntaxhighlight lang=wml>
abbrev = _"WMLT"
</syntaxhighlight>

:You should, but don't have to avoid clashes in the abbrev= key.
:It's preferable, but not necessary that it doesn't clash with other add-ons. However, as it only affects save filenames, it's unlikely to cause problems for the game itself - it could at most overwrite saves if for some reason scenario names are the same. It might affect the community though.
:Example: the abbreviation conflict between Era of Magic and Era of Myths, causing the former to use the abbreviation EoMa. But you don't have to bother about it at this point that much.

== Sorting ==
There's a default order of campaigns appearing in the menu and ours will probably be last for now. Set your campaign's rank to something bigger than 300, the lower it is, the bigger priority on default sorting it's going to have, if not set it will appear somewhere near the end. Check in [[CampaignWML]] for a detailed explanation.

<syntaxhighlight lang=wml>
rank = 970
</syntaxhighlight>

Note that you can also sort by name (alphabetically) and by time. For the former, set ''start_year='' and ''end_year='' keys, for example:

<syntaxhighlight lang=wml>
start_year = "10 BW"
end_year = "10 YW"
</syntaxhighlight>

In this campaign we're going to use a simpler form that replaces both of them to set our campaign to happen a year after "The Story of Two Brothers":

<syntaxhighlight lang=wml>
year = "364 YW"
</syntaxhighlight>

As it was said, it only affects sorting by timeline and nothing else, so if your campaign for some reason isn't placed in the Wesnoth universe or the date is not determined, just omit this key.

== Difficulty ==

Difficulty in campaigns is currently added using '''[difficulty]''' tags. It was different before, so not all add-ons follow this convention. The tag looks as follows:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

It should be placed inside the ''[campaign]'' tag, like ''[side]'' in ''[scenario]''. Don't forget about correct indentation.

First key, '''define=''' works similarly to the one in ''[campaign]'' tag, and is also checked with ''#ifdef''. But instead of only loading resources when campaign starts, it will only put certain parts of code in the campaign when it's started with the right difficulty, so it doesn't have effect on the ''[campaign]'' tag itself and will be used in scenarios (or units) instead. Example:

<syntaxhighlight lang=wml>
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
</syntaxhighlight>

This code if put inside the enemy's ''[side]'' tag will cause their leader to be a Dark Sorcerer if the difficulty is set to ''EASY'', and a Necromancer otherwise. Note that it'll show in examples later.

It's strongly recommended to use a set of: ''EASY, NORMAL, HARD'' if you have three difficulties and add ''NIGHTMARE'' if you have four, because there are some improvements (namely macros) that make use of those.

Second key, '''image=''' should point to an image illustrating the difficulty. It usually follows level progression for a unit or several similar units of different levels. For example, Liberty uses a Peasant (lvl 0) for ''EASY'', Outlaw (lvl 2) for ''NORMAL'' and Fugitive (lvl 3) for ''HARD''. It's purely visual.

Third key, '''label=''' is a translatable string with a flavour text representing the difficulty. It's often the name of the unit on image, but not necessarily.

Fourth key, '''description=''' is also translatable, and it serves as the actual user-visible difficulty name for the ones confused by flavour texts. Note, that you might want to choose from the ones used in mainline and save time on translating and devising a clever descriptive name. Just start the game and look at what was used so far.

Having a single difficulty doesn't really change anything so we'll add two more:

<syntaxhighlight lang=wml>
[difficulty]
define = NORMAL
image = "units/human-loyalists/longbowman.png"
label = _"Veteran"
description = _"Intermediate"
[/difficulty]
[difficulty]
define = HARD
image = "units/human-loyalists/masterbowman.png"
label = _"Commander"
description = _"Hard"
[/difficulty]
</syntaxhighlight>

We'll now use a little trick and append '''~RC(magenta>blue)''' to the images, so their paths will look like:

<syntaxhighlight lang=wml>
image = "units/human-loyalists/longbowman.png~RC(magenta>blue)"
</syntaxhighlight>

It'll cause their images to be coloured like units of default side 2. Again, it's purely visual. See [[ImagePathFunctions#RC: Re-Color function|documentation]] for more.

Note that players can change difficulty mid-campaign by default. To prevent that, you can add '''allow_difficulty_change = no''' to your ''[campaign]'' tag.

== MACROS ==

Now we're going to use another trick. We'll replace those tags with macros. Macro is literally telling the game to put a certain code in a certain place when loading the files. So in our code we're going to replace this:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

With this:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
</syntaxhighlight>

And the game will swap it back for us. Note, that the order of values in macros (they are called '''arguments''' in this context), unlike keys, does matter and has to be strictly followed. You also have to watch out for spaces, as anything that's not within () parentheses or "" double quotes and contains a space will count as two separate arguments. If we used the Wesnoth core's syntax for translatables the third argument would have to look like that: ''( _ "Recruit")''

Macros are great for saving time on typing and space on the screen when developing. You can also make your own macros but we'll do that later. There's a big collection of macros already made in Wesnoth and most are documented in [https://www.wesnoth.org/macro-reference.html the reference], along with the one we just used.

We'll also replace the other two with macros to save space. Usually you'd use a macro from the beginning and never write the tag in full. Note that we treat macros like keys for the purpose of indentation.

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

== Credits ==
Those will appear when the player finishes the campaign, just before mainline credits. They look like that:

<syntaxhighlight lang=wml>
[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
</syntaxhighlight>

The '''[about]''' tag describes a section in credits, its '''title=''' key is usually translatable and describes what the people inside did (usually role name), '''[entry]''' describes a single person, its '''name=''' key shouldn't be translatable and does what says on the tin, '''comment=''' is optional, provides an extra insight in their achievements and shouldn't be bothered to be translated.

That's it. You don't even need those at all, but you probably will add them anyway, for fame and future generations, or something.

Alternatively you can use '''end_credits = no''' instead and this will cause the game to display no credits at the end of your campaign, obviously, including mainline credits.

Consult [[CreditsWML]] for more. Or just check any other campaign's credits. It's actually the least important thing for your campaign.

== TL;DR ==
[[#Troubleshooting|Skip]]
In this part we added a '''[textdomain]''' tag to ''_main.cfg'' file and '''#textdomain''' definition at the beginning.

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]
</syntaxhighlight>

In the ''[campaign]'' tag:
We added an '''icon''' to display next to the campaign's name, and '''abbrev''' for prefixing save filenames.

<syntaxhighlight lang=wml>
icon = "items/book3.png"
abbrev = _"WMLT"
</syntaxhighlight>

We also added the '''description''', along with its optional visuals - '''image''' and '''background'''.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"
</syntaxhighlight>

We also added '''rank''' and '''year''' for sorting purposes. Both are optional and almost unnoticeable for the average user. You can replace the latter with '''start_year''' and '''end_year'''.

<syntaxhighlight lang=wml>
rank = 970
year = "364 YW"
</syntaxhighlight>

We added three '''difficulties''' using '''macros''' in place of tags and keys:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

Macros are good and [https://www.wesnoth.org/macro-reference.html here's] the list.

We also added '''credits''' but if you're reading the TL;DR you're not worthy to put those yet. Go back after actually making your own campaign.

== Troubleshooting ==
Campaign doesn't appear on the list anymore
:Probably macros are badly written or your tags are not opened/closed properly. Error message shown when running the game might say more.
Images don't show
:Assuming your [binary_path] is correct (this was done in the previous part), check your paths and. They should be relative to the game's 'images' folder, or have full path relative to userdata folder. Watch out for typos and extensions.
Code so far:
:_main.cfg
<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]

[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
icon = "items/book3.png"
abbrev = _"WMLT"

description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"

rank = 970
year = "364 YW"

first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL

{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}

[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:scenarios/01_Initial_Scenario.cfg

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

[[MakingCampaignInWML3|Part 3: Improving the first scenario]]

@@ Line 55: / Line 55: @@
 This is a new feature, introduced in 1.15 versions, so it's not commonly used. It replaces the default background of the campaign menu when our campaign is selected. Typically uses story/cutscene background images. Note that Wesnoth backgrounds in the story folder have atypical .jpg extension, but it's not necessarily the case for other background images.
-:=== Note about custom images ===
+=== Note about custom images ===
 :Usually you could access an image, e.g. "snow-golem.png" in your add-on's images folder by just writing "snow-golem.png". But that's because you use [binary_path] to access it. However, our [binary_path] is inside #ifdef, which only loads AFTER we start the campaign, so the game doesn't know about it when we're in campaign selection menu.
 :To use custom images in your [campaign] tag you have to use fully qualified names, relative to userdata folder, that is, the same as you used in [binary_path] and [textdomain]. For the afforementioned snow golem image you'd have to write ''data/add-ons/WML_Tutorial/images/snow-golem.png''.
@@ Line 374: / Line 374: @@
 [/scenario]
 </syntaxhighlight>
 [[MakingCampaignInWML3|Part 3: Improving the first scenario]]

MakingCampaignInWML2 - Revision history

Jarom: fixed heading

Jarom: Created page with "'''Expanding the campaign definition (and macros)''' In the previous part of this tutorial we made a minimal working example that could be run and pla..."