The Battle for Wesnoth Wiki - User contributions [en]

BuildingUnits

2010-02-08T19:44:39Z

Sderose: /* Recommended procedure */

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.

== 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 or data/core/units directory (see [[EditingWesnoth]]) 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]].

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.

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

Note: for people using 1.7 and later, this section is out-of-date. Mainly, the campaigns/ directory is now called add-ons, but also the syntax for the main .cfg and .pbl files has changed: put _main.cfg '''inside''' your add-on directory, and put _server.pbl inside as well. Also, use ~ instead of @ for includes.

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.

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

As of 1.6, unit definitions are enclosed in '''[unit_type]''' 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 [[UnitTypeWML|The Unit WML reference page]].
* 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.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]
* [[Team_Color_Shifting]]

{{Create}}

BuildingUnits

2010-02-08T19:42:23Z

Sderose: /* Recommended procedure */

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.

== 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 (see [[EditingWesnoth]]) 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]].

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.

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

Note: for people using 1.7 and later, this section is out-of-date. Mainly, the campaigns/ directory is now called add-ons, but also the syntax for the main .cfg and .pbl files has changed: put _main.cfg '''inside''' your add-on directory, and put _server.pbl inside as well. Also, use ~ instead of @ for includes.

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.

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

As of 1.6, unit definitions are enclosed in '''[unit_type]''' 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 [[UnitTypeWML|The Unit WML reference page]].
* 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.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]
* [[Team_Color_Shifting]]

{{Create}}

EditingWesnoth

2010-02-08T19:39:56Z

Sderose: /* Mac OS X */ command != control

== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally do not need to modify these files, but you can if you want to modify a unit or something.

The user data directory allows you to add custom content without modifying the game's own files. Each OS puts its user data directory in a different place. In this wiki, "user data", ''userdata''/''subdirectory'', or (occasionally) ~wesnoth/ refer to this directory.

=== Where is my '''game''' data directory? ===

====Windows====
Usually C:\Program Files\Wesnoth\data but it will be different if you installed the game in a different location: look for the data folder in the folder where you installed the game.

====Mac OS X====
Downloaded from sourceforge: control-click on the application icon. Select "Show Package Contents." Select "Contents" then "Resources.

If you did not download from sourceforge what do you do?

Command line build: /usr/local/share/wesnoth

====Linux====
/usr/local/share/wesnoth 
From apt-get (Debian and Ubuntu) or emerge (Gentoo): /usr/share/games/wesnoth 
SUSE 10.0 (pre-installed): /usr/share/wesnoth 
Fedora 5 (Installed from yum repository RPM): /usr/share/wesnoth 
Mandriva 2006.0: /usr/share/games/wesnoth 
Slackware 12 (Installed from .tgz package at LinuxPackages.net): /usr/local/share/wesnoth 
If you don't find it, or if you use another distribution, try <code>find / -iname '*wesnoth*'</code>. (as yourself, not as superuser)

=== Where is my '''user''' data directory? ===

====Windows====
c:\Program Files\Wesnoth\userdata

or c:\Users\USERNAME\AppData\Local\VirtualStore\Program Files\Wesnoth\userdata
on Vista, which has virtual folders. The AppData folder is hidden.
Or if you don`t remember where you installed it right click on the game`s shortcut open properties and click on the `Find target` button,then search for the `data` folder.

Starting from Wesnoth 1.6 it can be in MyDocuments\My Games\Wesnoth1.6 on Windows XP or Documents\My Games\Wesnoth1.6 on Vista.

====Mac OS X====
Downloaded from sourceforge: ~/Library/Preferences/Wesnoth 
For Wesnoth 1.7.x : ~/Library/Application Support/Wesnoth_1.x/ 
Command line build: ~/.wesnoth (same as Linux; see below for details)

====Linux====
~/.wesnoth 
For newer wesnoth versions it can also be ~/.wesnoth<version>. I.e. ~/.wesnoth1.6 
If unsure you can check stdout of wesnoth (run from a terminal) on startup where the used directory is mentioned.

== Game data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/core/units/ and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

== User Data ==
The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/campaigns - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/campaigns directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/campaigns directory might look like:
* ''userdata''/data/campaigns/MyCampaign/ - your campaign's directory
* ''userdata''/data/campaigns/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/campaigns/MyCampaign/scenarios
** ''userdata''/data/campaigns/MyCampaign/units
** ''userdata''/data/campaigns/MyCampaign/images
** ''userdata''/data/campaigns/MyCampaign/music
** ''userdata''/data/campaigns/MyCampaign/sounds
** ''userdata''/data/campaigns/MyCampaign/utils

{{DevFeature}} Note that in 1.7.0 and later versions, ''add-ons'' replaces ''campaigns'' for these paths.

== See Also ==

* [[Create]]

<div style="border:1px solid #5599FF; margin-top: 10px; margin-bottom: 5px; padding: 5px;">
- [[EditingWesnoth|English]] - [[Editer Wesnoth vf|Français]] -
</div>
[[Category:Create]]