Difference between revisions of "WML for Complete Beginners: Chapter 6"

From The Battle for Wesnoth Wiki
m (I love tabs)
(Use syntax highlighting)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Translations}}<div style="float:right">{{:WML for Complete Beginners}}</div>
 +
 
==Chapter 6: Building and Including a Custom Unit==
 
==Chapter 6: Building and Including a Custom Unit==
  
Line 8: Line 10:
  
 
As usual, start with the textdomain and toplevel tag:
 
As usual, start with the textdomain and toplevel tag:
 +
<syntaxhighlight lang=wml>
 +
#textdomain wesnoth-my_first_campaign
  
#textdomain wesnoth-my_first_campaign
+
[unit_type]
+
[/unit_type]
[unit_type]
+
</syntaxhighlight>
[/unit_type]
 
  
 
A somewhat minimal set of initial keys might be:
 
A somewhat minimal set of initial keys might be:
 
+
<syntaxhighlight lang=wml>
id=
+
id=
name=
+
name=
image=
+
image=
movement=
+
movement=
hitpoints=
+
hitpoints=
 +
</syntaxhighlight>
  
 
"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.
 
"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:
 
Filling these out, you might end up with:
 +
<syntaxhighlight lang=wml>
 +
#textdomain wesnoth-my_first_campaign
  
#textdomain wesnoth-my_first_campaign
+
[unit_type]
 
+
    id=My First Unit
[unit_type]
+
    name= _ "My First Unit"
    id=My First Unit
+
    image=
    name= _ "My First Unit"
+
    movement=10
    image=
+
    hitpoints=10
    movement=10
+
[/unit_type]
    hitpoints=10
+
</syntaxhighlight>
[/unit_type]
 
  
 
===Creating Unit Images===
 
===Creating Unit Images===
Line 41: Line 46:
  
 
Update your my_first_unit.cfg:
 
Update your my_first_unit.cfg:
 
+
<syntaxhighlight lang=wml>
image="units/my_first_art.png"
+
image="units/my_first_art.png"
 +
</syntaxhighlight>
  
 
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:
 
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:
 
+
<syntaxhighlight lang=wml>
image="units/my_first_art~SCALE_SHARP(72,72)"
+
image="units/my_first_art.png~SCALE_SHARP(72,72)"
 +
</syntaxhighlight>
  
 
This is described in more detail in [[ImagePathFunctionWML]]
 
This is described in more detail in [[ImagePathFunctionWML]]
Line 53: Line 60:
  
 
You can now add your units to <code>_main.cfg</code>:
 
You can now add your units to <code>_main.cfg</code>:
 
+
<syntaxhighlight lang=wml>
[+units]
+
[units]
 
     {~add-ons/my_first_campaign/units}
 
     {~add-ons/my_first_campaign/units}
[/units]
+
[/units]
 +
</syntaxhighlight>
  
 
You might also want to make this unit recruitable by your human-controlled leader in <code>scenarios/my_first_scenario.cfg</code>:
 
You might also want to make this unit recruitable by your human-controlled leader in <code>scenarios/my_first_scenario.cfg</code>:
 
+
<syntaxhighlight lang=wml>
recruit="Elvish Fighter, My First Unit"
+
recruit="Elvish Fighter, My First Unit"
 +
</syntaxhighlight>
  
 
Try recruiting your first unit!
 
Try recruiting your first unit!
Line 67: Line 76:
  
 
You will notice quickly that your unit is not able to attack, because we have not assigned it any attacks.  
 
You will notice quickly that your unit is not able to attack, because we have not assigned it any attacks.  
 +
<syntaxhighlight lang=wml>
 +
[attack]
 +
    name=sword
 +
    type=blade
 +
    range=melee
 +
    damage=4
 +
    number=1
 +
    icon=attacks/dagger-human.png
 +
[/attack]
 +
</syntaxhighlight>
  
[attack]
+
This is a simple sword attack, reusing mainline art for the attack icon.
    name=sword
 
    type=blade
 
    range=melee
 
    damage=4
 
    number=1
 
    icon=attacks/dagger-human.png
 
[/attack]
 
 
 
This also uses an icon from mainline art.
 
 
 
Your complete unit file should now look like this:
 
  
[unit_type]
+
Your complete unit_type tag should now look like this:
    id=My First Unit
+
<syntaxhighlight lang=wml>
    name= _ "My First Unit"
+
[unit_type]
    image="units/my_first_art.png"
+
    id=My First Unit
    movement=10
+
    name= _ "My First Unit"
    hitpoints=10     
+
    image="units/my_first_art.png"
   
+
    movement=10
    [attack]
+
    hitpoints=10     
        name=sword
+
   
        type=blade
+
    [attack]
        range=melee
+
        name=sword
        damage=4
+
        type=blade
        number=1
+
        range=melee
        icon=attacks/sword-human.png
+
        damage=4
    [/attack]
+
        number=1
[/unit_type]
+
        icon=attacks/sword-human.png
 +
    [/attack]
 +
[/unit_type]
 +
</syntaxhighlight>
  
 
===Further reading===
 
===Further reading===
Line 102: Line 113:
 
* [[UnitTypeWML]] reference for the unit_type tag shown in this article
 
* [[UnitTypeWML]] reference for the unit_type tag shown in this article
 
* [[SingleUnitWML]]
 
* [[SingleUnitWML]]
 +
* [[BuildingFactions]] sum up your units to a faction
  
 
After reading more about UnitTypeWML, you might try extending your first unit with advancement options and variations.
 
After reading more about UnitTypeWML, you might try extending your first unit with advancement options and variations.
  
===Continue===
+
{{Navigation|[[WML for Complete Beginners: Chapter 5|'''Chapter 5'''<br>Events]]|[[WML for Complete Beginners: Chapter 7|'''Chapter 7'''<br>Creating Your First Scenario]]}}
 
 
Next Chapter:
 
[[WML for Complete Beginners: Chapter 7]]
 
 
 
Previous Chapter:
 
[[WML for Complete Beginners: Chapter 5]]
 
 
 
Return to Main Index:
 
[[WML for Complete Beginners]]
 
  
 
[[Category:WML_for_Complete_Beginners]]
 
[[Category:WML_for_Complete_Beginners]]

Latest revision as of 20:37, 29 January 2023

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.png~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"

Try recruiting your first unit!

Attacks

You will notice quickly that your unit is not able to attack, because we have not assigned it any attacks.

[attack]
    name=sword
    type=blade
    range=melee
    damage=4
    number=1
    icon=attacks/dagger-human.png
[/attack]

This is a simple sword attack, reusing mainline art for the attack icon.

Your complete unit_type tag should now look like this:

[unit_type]
    id=My First Unit
    name= _ "My First Unit"
    image="units/my_first_art.png"
    movement=10
    hitpoints=10    
    
    [attack]
        name=sword
        type=blade
        range=melee
        damage=4
        number=1
        icon=attacks/sword-human.png
    [/attack]
[/unit_type]

Further reading

After reading more about UnitTypeWML, you might try extending your first unit with advancement options and variations.

Navigation
Chapter 5
Events
WML for Complete Beginners: Chapter 6 Chapter 7
Creating Your First Scenario
This page was last edited on 29 January 2023, at 20:37.