Difference between revisions of "BuildingUnits"

From The Battle for Wesnoth Wiki
(more prelim)
(migration)
Line 1: Line 1:
 
Making new units is fairly easy.  This page will walk you through the creation of a new unit and discuss how you can use it in-game.  You should already understand where the game stores its data files and have a text editor handy.  You will need to become familiar with [[UnitWML|WML]] in order to make a new unit.
 
Making new units is fairly easy.  This page will walk you through the creation of a new unit and discuss how you can use it in-game.  You should already understand where the game stores its data files and have a text editor handy.  You will need to become familiar with [[UnitWML|WML]] in order to make a new unit.
 +
 +
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.
 +
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''.
 +
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.
 +
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.
 +
* 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.
 +
''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.
 +
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.
 +
 +
Terrains:
 +
 +
* 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.
 +
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.
 +
* 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''.
 +
''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?).
 +
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,
 +
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).
  
 
== See Also ==
 
== See Also ==
  
 
* [[Create]]
 
* [[Create]]
* [[UnitWML]]
+
* [[EditingWesnoth]]

Revision as of 14:51, 17 September 2005

Making new units is fairly easy. This page will walk you through the creation of a new unit and discuss how you can use it in-game. You should already understand where the game stores its data files and have a text editor handy. You will need to become familiar with WML in order to make a new unit.

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

Terrains:

  • 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. 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.
  • 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. 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?). 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, 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).

See Also