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 [[UnitTypeWML|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, 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]].
+{| style="float:right; margin-left:1em;"
+|__TOC__
+|}
+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.
+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.
+== 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 <i>data/core/units</i> 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:
-Most of a unit's properties are self-explanatory to anyone who has played Battle for Wesnoth for very long, and the tags in the WML files are brief but descriptive. It is recommended that you try editing by yourself before consulting the guide.  Otherwise, you may find the guide confusing.
+* 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.
 == Using your new unit ==
-Any unit in the game's existing data/units/*/ directories (you can't just add a new directory to data/units/) or ''[[EditingWesnoth#Where_is_my_user_data_directory.3F|userdata]]''/data/ will be recognized by the game. If you only want to use it once or twice as a special unit, that's all you need to do. However, just because you made a new unit does NOT mean that it can be recruited. Each scenario and multiplayer era has a specific recruit list. If your unit is not on the list, you can't recruit 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 [http://www.wesnoth.org/forum 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.
+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.
-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.
+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.
-* 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 ==
+=== Multiplayer factions and eras ===
-As of 1.6, unit definitions are enclosed in '''[unit_type]''' tags.
+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.
-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 [[UnitTypeWML|The Unit WML reference page]].
+<b>Note:</b> Remember that eras and factions is a construct unique to multiplayer.
-* The first attribute of a unit is the '''id''' attribute, 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 and use [movement_costs] to make it unable to move onto any terrain.
-* See [[BuildingScenariosIntermediate]] for more information on attacks.
+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 61: / Line 46: @@
 * [[CampaignServerWML]]
 * [[PblWML]]
-* [[BuildingCampaignsThePBLFile]]
 * [[Team_Color_Shifting]]
+* [[Advanced_Animation_Tutorial]]
-{{Create}}
+* [[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