Difference between revisions of "BuildingUnits"

Revision as of 14:13, 2 February 2006

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

Recommended procedure

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

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.

Distributing your unit

If you made a single unit, post it on the forum. If you made a whole group of units, you can make them into a multiplayer faction or you can upload a unit pack.

If you want to make a faction, follow the instructions in the BuildingFactions article. You should create a new era and add your units as one of the factions. You will not be able to add your units to any era that ships with the game.

If you want to make a unit pack, the procedure is easier. Unit packs are distributed for campaign writers who want to use your units in their campaigns/eras. They download your unit pack and copy/paste the units and images into their campaign/era.

Navigate to the userdata/data/campaigns directory. Everything from now on will occur relative to here. The era we'll use as an example will be called MyUnitPack
Create a text file called MyUnitPack.cfg. Add the following lines:

#		#define USE_MYUNITS		#<- replace MYUNITS with something descriptive
#		#enddef
#		#ifdef USE_MYUNITS		#<- replace MYUNITS with something descriptive
#		{@campaigns/MyUnitPack/}
#		#endif

These lines are commented out (with the #). That way when the unit pack ships it won't affect the game. If someone wants the game to be able to see these units, he can uncomment those lines and it will work. However, this usually causes problems in multiplayer (you will be using units no one else has), but it can be fun for campaigns.
NOTE: the commenting/uncommenting trick will only work if the units branch off of an existing unit. Custom L1 units will NOT show up in game automatically without editing another configuration file somewhere (scenario config file or multiplayer.cfg)

Create another text file called MyUnitPack.pbl. (See PblWML for more details about *.pbl files.) Add the following lines to it:

author="your name"
icon="any image file in the game's ./images directory"
version="1.0"
title="My Awesome Unit Pack"
description="New race of lizard men."

Create a folder called MyUnitPack. Navigate to it.
Create two subdirectories: units and images. Place your unit cfg files and artwork into those subdirectories
Create a text file called MyUnitPack.cfg (or another name of your choosing). Add the following lines:

[binary_path]
path=data/campaigns/MyUnitPack
[/binary_path]
[+units]
{@campaigns/MyUnitPack/units}
[/units]

You should be ready to distribute your unit pack on the campaign server now
PLEASE change the names to something unique before you publish

Unit WML discussion

Units are enclosed in [unit] tags.

This section only provides some tips and pointers in making a unit. Feel free to add pointers of your own. For the full, current, complete WML reference on what to put in your [unit], see and frequently revisit The Unit WML reference page.

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).
When referencing the unit in a type key, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the key won't work. If you can't recruit in a scenario, it's probably because you have a typo in one of the unit ids and the recruit key was invalidated.
It also has a name key, which is the (translatable) name of the unit, and is displayed on the Status Table when a unit of this type is selected. It does not need to be unique (but it helps).
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 use [movement_costs] to make it unable to move onto any terrain.
Also, make sure you give the unit at least one [attack]. If not, there is a bug in the game code that will cause the game to crash when it attempts to find attacks. This may also be fixed in the future.
See BuildingScenariosIntermediate for more information on attacks.

@@ Line 41: / Line 41: @@
 == Unit WML discussion ==
 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 displayed on the Status Table when a unit of this type is selected.
-The ''race'' and ''gender'' keys indicate 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 a 25% times the level difference between them and the highest level adjacent leader on the same side, bonus to damage. Only units that are higher level than the unit involved in combat provide a bonus.
-* 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: Unit takes half damage when defending.
-* stone: Units this attack hits turn into stone (the stoned unit is lost)
-* berserk: Combat continues until either the attacked or the defender is killed.
-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).
+This section only provides some tips and pointers in making a unit.  Feel free to add pointers of your own.  For the full, current, complete WML reference on what to put in your [unit], see and frequently revisit [[UnitWML|The Unit WML reference page]].
+* 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]]).
+* When referencing the unit in a ''type'' key, the id must be reproduced verbatim, without typos, and in a case-sensitive manner.  If you don't do this, the key won't work.  If you can't recruit in a scenario, it's probably because you have a typo in one of the unit ids and the ''recruit'' key was invalidated.
+* It also has a ''name'' key, which is the (translatable) name of the unit, and is displayed on the Status Table when a unit of this type is selected.  It does not need to be unique (but it helps).
+* 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 use [movement_costs] to make it unable to move onto any terrain.
+* Also, make sure you give the unit at least one [attack].  If not, there is a bug in the game code that will cause the game to crash when it attempts to find attacks.  This may also be fixed in the future.
+* See [[BuildingScenariosIntermediate]] for more information on attacks.
 == See Also ==