WML for Complete Beginners: Chapter 6

Chapter 6: Building and Including a Custom Unit

Sometimes campaign authors only use mainline units in their campaigns. Other times, however, they may want to include a custom unit that isn't found in default Wesnoth. Thankfully, including a custom unit is quite easy.

Creating the Unit .cfg File

Create a new text file in the "units" folder inside the campaign folder. You could name this "my_first_unit.cfg".

As usual, start with the textdomain and toplevel tag:

#textdomain wesnoth-my_first_campaign

[unit_type]
[/unit_type]

A somewhat minimal set of initial keys might be:

id=
name=
image=
movement=
hitpoints=

"id" and "name" work like usual. "movement" is interesting, because by default a unit will have no movement; quite a boring unit! The same goes for hitpoints; you would have 1 hitpoint if unset.

Filling these out, you might end up with:

#textdomain wesnoth-my_first_campaign

[unit_type]
    id=My First Unit
    name= _ "My First Unit"
    image=
    movement=10
    hitpoints=10
[/unit_type]

Creating Unit Images

If you were to spawn this unit now, it would look quite strange, because we have not yet assigned an image. Creating Unit Art describes how to do this in some detail. When you have a reasonably suitable image, you should save this in add-ons/my_first_campaign/images/units.

Update your my_first_unit.cfg:

image="units/my_first_art.png"

If you don't have a perfectly sized image, you'll notice your unit looks strange in menus and when placed on the map. You can also play with the SCALE and CROP functions to adjust this:

image="units/my_first_art~SCALE_SHARP(72,72)"

This is described in more detail in ImagePathFunctionWML

Including the Custom Unit in your Campaign

You can now add your units to _main.cfg:

[+units]
   {~add-ons/my_first_campaign/units}
[/units]

You might also want to make this unit recruitable by your human-controlled leader in scenarios/my_first_scenario.cfg:

recruit="Elvish Fighter, My First Unit"

Further reading

• UnitTypeWML reference for the unit_type tag shown in this article
• SingleUnitWML

Continue

Next Chapter: WML for Complete Beginners: Chapter 7

Previous Chapter: WML for Complete Beginners: Chapter 5

Return to Main Index: WML for Complete Beginners