Difference between revisions of "BuildingUnits"

Latest revision as of 03:48, 8 November 2024

Creator's Guide

Add-on Structure • Maps • Scenarios • Campaigns • Multiplayer • Units • Distributing Content

Creating a new unit

The easiest way to make a new unit is to make a copy of an existing unit's configuration file and modify it. All units shipped with the game can be found in the game's data/core/units directory (see EditingWesnoth for how to find it).

When you are editing the file, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game.

For complete reference on unit properties see UnitTypeWML. Most of them are self-explanatory to anyone who has played Wesnoth for very long, and are brief but descriptive.

There are a few important basics:

The first attribute of a unit type is the id= key, which is a unique identifier for that type. Whenever referring to a unit type via in a scenario, you use this id. It is not translatable. The name= key is the displayed name of the unit type in places such as help, the status table, and the sidebar, and is translatable. You can have a complex id, but a simple name. Remember that this is NOT the same as the name of a specific instance of a unit created in a scenario via [unit].
When referencing the unit type, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the game will throw Unknown Unit errors.
Do not set movement= to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.

Using your new unit

Custom unit configuration files should be put in your add-on's units directory, and their custom graphics in the images/units directory. Be sure to have the units directory included from your _main.cfg. The include for this directory, however, should be wrapped in a [units][/units] tag pair. See AddonStructure for an example.

All units in this directory will now be accessible in any content loaded under the same #ifdef conditional. You can now allow sides to recruit the unit by listing it in the recruit= key in [side] (see SideWML, place instances of it on the map with their own custom stats via [unit], or anything else you please.

Multiplayer factions and eras

Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.

Note: Remember that eras and factions is a construct unique to multiplayer.

More detailed instructions on factions and eras can be found in the EraWML article. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.

@@ Line 1: / Line 1: @@
-Making new units is fairly easy.  Unit configuration files are plain text files that you can edit with any editor such as Notepad, TextEdit, gedit, pico, vi, emacs, etc.  You will need to become familiar with [[UnitWML|WML]] in order to make a new unit.  This page contains a more in-depth discussion of Unit WML syntax and will walk you through the creation of a new unit and discuss how you can use it in-game.
+{{Translations}}
-== Recommended procedure ==
+{{Create}}
-The easiest way to make a new unit is to copy and paste an existing unit, then modify it.  Navigate to the game's data/units directory and copy any unit.  When you are editing the unit, attention to detail is key.  If you forget to modify each key (for example, the unique id key), problems will result.
-== Using your new unit ==
+{| style="float:right; margin-left:1em;"
-Any unit in the game's ./data/units directory or ''userdata''/data/units will be recognized by the game.  However, just because you made a new unit does NOT mean you can use it in game yet.  Each scenario and multiplayer era has a specific recruit list.  If your unit is not on the list, you can't use it.  This means you need to modify the ''recruit='' key in the appropriate configuration file.  [[BuildingMultiplayer]] describes different ways you do this for multiplayer.  To add a unit to a campaign, read about scenarios, sides, and recruit lists in [[BuildingScenarios]].
+|__TOC__
+|}
-== Unit WML discussion ==
+When creating custom content, you might want to create a cool new unit. This page will walk you through the creation of a new unit and discuss how you can use it in-game.
-Units are enclosed in '''[unit]''' tags.
-The first attribute of a unit is the ''id'' key, which is a unique identifier for the unit. As value of the ''type'' attribute for these units, the ''id'' key is used. (See [[BuildingScenarios]]).
-It also has a ''name'' key, which is the (translatable) name of the unit, and is f ex displayed on the Status Table when a unit of this type is selected.
-The ''race'' and ''gender'' keys indicate f ex what kind of names and traits units of this type should have.
+Before you begin, you should be remember that the <b>[[UnitTypeWML | [unit_type]]]</b> tag will create a new type of unit, while the <b>[[SingleUnitWML | [unit]]]</b> tag allows you to use the unit in your scenario. This article will focus on the use of the former.
-Races are specified by the '''[race]''' tag, and the common set is found in '''data/game.cfg'''.
-Values for ''gender'' are ''male'' and ''female'' (Default is ''male'').
-The next attributes are ''image'', ''image_defensive'', and ''profile''.
+== Creating a new unit ==
-These are the images of the unit when it is resting, defending, and talking, respectively.
-The default for the keys ''image_defensive'' and ''profile'' is the value for ''image''.
-Next is the ''ability'' key.
+The easiest way to make a new unit is to make a copy of an existing unit's configuration file and modify it. All units shipped with the game can be found in the game's <i>data/core/units</i> directory (see [[EditingWesnoth]] for how to find it).
-This is a list of strings which are listed as the abilities of the unit.
-The following strings give the unit an ability:
-* illuminates: Units surrounding this unit recieve 25% lawful bonus.
+When you are editing the file, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game.
-* leadership: Units surrounding this unit recieve +1 damage.
-* heals: Units surrounding this unit regenerate 4 HP per turn.
-* cures: Units surrounding this unit regenerate as if they were on a villages.
-* regenerates: The unit regenerates each turn as if it were on a village.
-* teleport: Whenever it is on a village, the unit can use 1 move point to move to any allied village.
-* skirmisher: The unit is unaffected by ZoC.
-* ambush: The unit becomes invisible on forest.
-* nightstalk: The unit becomes invisible during night.
-The ''hitpoints'' and ''movement'' keys input numbers.
+For complete reference on unit properties see [[UnitTypeWML]]. Most of them are self-explanatory to anyone who has played Wesnoth for very long, and are brief but descriptive.
-''hitpoints'' is the amount of HP the unit has, and ''movement'' is the number of move points it receives each turn.
-The ''movement_type'' key is a shortcut to information found in game.cfg.
+There are a few important basics:
-After (or replacing) the ''movement_type'' key, tags can be used to modify the unit's movement.
-The '''[movement costs]''' tag has keys equal to the name of the various terrains, and values equal to the number of move points it takes to move onto a tile of that terrain type.
+* The first attribute of a unit type is the <b>id=</b> key, which is a unique identifier for that type. Whenever referring to a unit type via in a scenario, you use this id. It is not translatable. The <b>name=</b> key is the displayed name of the unit type in places such as help, the status table, and the sidebar, and is translatable. You can have a complex id, but a simple name. Remember that this is <b>NOT</b> the same as the name of a specific instance of a unit created in a scenario via [unit].
+* When referencing the unit type, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the game will throw Unknown Unit errors.
+* Do not set <b>movement=</b> to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.
-Terrains:
+== Using your new unit ==
-* village
-* castle
-* grassland
-* forest
-* tundra
-* hills
-* mountains
-* cave
-* cavewall
-* sand
-* swamp water
-* shallow water
-* deep water
-The '''[defense]''' tag also has keys equal to the name of the various terrains, and values equal to the percent chance the unit has of being hit while on a tile of that terrain type.
-The '''[resistance]''' tag has keys equal to attack types, and values equal to the percent damage that the unit takes from attacks of that type. The attack types are:
-* blade
-* pierce
-* impact
-* fire
-* cold
-* holy
-The next keys are ''experience'' and ''advanceto''.
-''experience'' is the amount of experience the unit needs to advance to the unit with the id specified as value of the ''advanceto'' key.
-If ''advanceto'' has multiple entries, the player will choose which unit to advance to.
-If ''advanceto=null'', then the unit cannot advance.
-The next keys are ''cost'' and ''level''.
-''cost'' is how much gold the unit costs to recruit, and ''level'' is the upkeep cost of the unit.
-''level'' is also the amount of XP another unit gets for fighting this one, and the multiplier for the amount of XP the other unit gets for killing this one (multiplied with the ''kill_experience'' value set in '''game.cfg''').
-The next keys are ''alignment'' and ''usage''.
-''alignment'' tells how the unit's damage should be affected by the current time of day (lawful: <better during day>, chaotic: <better during night>, neutral: unaffected by time of day changes).
-''usage'' is the AI's interpretation of this unit.
-Values are 'fighter', 'scout', 'archer', 'mixed fighter', and 'null' (Default is null).
-The last keys are ''unit_description'' and ''get_hit_sound''.
-''unit_description'' is the (translatable) text that is displayed in the unit description box.
-''get_hit_sound'' is a .wav file in '''sounds/ ''' that is played when the unit is hit.
-The '''[death]''' tag is used to specify an animation of the unit dying, and consists of a set of '''[frame]''' tags, which are similar to all animation '''[frame]''' tags (see description of how these are used below), but is used outside an '''[attack]''' tag.
-Next are the '''[attack]''' tags.
-The ''name'' key is the displayed name of the attack. (Is this not now divided up into ''id'' and ''name'' ??)
-The ''name'' key also affects the ''has_weapon'' filter
-(See [[BuildingScenariosIntermediate]]).
-Next are the ''type'' and ''range'' keys.
-''type'' is an attack type.
-''range'' is either '''short''' or '''long'''.
-'range=short' means melee, 'range=long' means ranged.
-The ''special'' key is similar to the ''ability'' key.
+Custom unit configuration files should be put in your add-on's <i>units</i> directory, and their custom graphics in the <i>images/units</i> directory. Be sure to have the <i>units</i> directory included from your _main.cfg. The include for this directory, however, should be wrapped in a <b>[units][/units]</b> tag pair. See [[AddonStructure]] for an example.
-The values are:
-* backstab: Whenever there is a unit allied with this unit "behind" the unit that this attack attacks, then this attack does +100% damage.
+All units in this directory will now be accessible in any content loaded under the same <b>#ifdef</b> conditional. You can now allow sides to recruit the unit by listing it in the <b>recruit=</b> key in [side] (see [[SideWML]], place instances of it on the map with their own custom stats via [unit], or anything else you please.
-* charge: Whenever the unit attacks with this attack, both it and the unit it attacks do +100% damage.
-* drain: The unit gains health (?)% of the time whenever this attack hits.
-* first-strike: This attack always strikes first, even if defending
-* magical: This attack is guaranteed a 70% chance of hitting.
-* marksman: This attack is guaranteed a 60% chance of hitting.
-* plague: The unit is copied onto the tile that any unit this attack killed was on.
-* poison: All units this attack hits become poisoned.
-* slows: All units this attack hits become slowed for 1 turn.
-* steadfast: (what is the current effect of steadfast?)
-The last keys are ''damage'' and ''number''.
+=== Multiplayer factions and eras ===
-''damage'' is the amount of damage the attack does;
-''number'' is the number of times it can try to hit with each attack.
-Next are the animation tags (Note: these are inside the '''[attack]''' tags) (Has the set of keys not been extended?).
+Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.
-The '''[frame]''' tag contains the keys ''begin'', ''end'', and ''image''.
-''begin'' and ''end'' specify in what period of time the frame should exist.
-These times are in milliseconds. 0 is when the attack hits.
-The ''image'' key is the unit image to switch to during this time.
-The '''[missile_frame]''' tag is like the '''[frame]''' tag,
+<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.
-but ''image'' represents the image of the projectile.
-Also ''image_diagonal'' is the image when the attack is not north-south aligned.
-The '''[sound]''' tag takes the keys ''time'' (the time to play the sound) and ''sound'' (the sound to play).
+More detailed instructions on factions and eras can be found in the [[EraWML]] article. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.
 == See Also ==
@@ Line 133: / Line 43: @@
 * [[Create]]
 * [[EditingWesnoth]]
+* [[Creating Unit Art]]
+* [[CampaignServerWML]]
+* [[PblWML]]
+* [[Team_Color_Shifting]]
+* [[Advanced_Animation_Tutorial]]
+* [[BuildingScenariosIntermediate]]
+* [[BuildingFactions]]

Difference between revisions of "BuildingUnits"

Latest revision as of 03:48, 8 November 2024

Contents

Creating a new unit

Using your new unit

Multiplayer factions and eras

See Also