EditingWesnoth
Contents
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: command-click on the application icon. Select "Show Package Contents." Select "Contents" then "Resources."
Command line build: /usr/local/share/wesnoth
Linux
/usr/local/share/wesnoth
From apt-get: /usr/share/games/wesnoth
other distributions?
Where is my user data directory?
Windows
c:\Program Files\Wesnoth\userdata
Mac OS X
Downloaded from sourceforge: ~/Library/Preferences/Wesnoth
Command line build: ~/.wesnoth
Linux
~/.wesnoth
Game data
The major directories you need to know about are wesnoth/data, wesnoth/data/units, wesnoth/data/campaigns, wesnoth/data/maps, wesnoth/data/scenarios, wesnoth/images
Become familiar with what is in ./data/campaigns, ./data/scenarios, and ./data/maps. 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/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.
Game Configuration
Some information is stored in files in the ./data directory itself:
- amla.cfg - global definition for After Max-Level Advancement (currently 3 hp per 100 XP)
- fonts.cfg - defines which fonts the game can use
- game.cfg
- help.cfg - the entire help system document
- items.cfg - macros for common objects and items used in the game, also available for campaign writer use
- multiplayer.cfg - defines the multiplayer eras and factions
- names.cfg - lists of name fragments that are randomly put together to create random-sounding names. Segregated by race and gender
- scenario-test.cfg - a simple test scenario. Run it with the command wesnoth -t
- schedules.cfg - defines the global day-night cycle
- terrain.cfg - defines the terrain types
- terrain-graphics.cfg - defines terrain layering and usage of random terrain
- tips.cfg - the contents of the Tome of Wesnoth
- traits.cfg - defines all traits used globally in the game
- utils.cfg - some common macros used in the game, also available for campaign writer use
- units.cfg - defines the races, which traits each race has, and the movement types (which set defenses, resistances, and movement costs)
For more information about game configuration:
- themes/: ThemeSystem
- maps/: BuildingMaps
- scenarios/: BuildingScenarios
- translations/: WesnothTranslations
- units/: BuildingUnits
- game.cfg: WesnothGameConfigure
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/data/editor/maps - multiplayer standalone maps (map data only)
- userdata/data/units - drop your custom units here, and they will be visible to the game
- userdata/data/images - drop your custom images here, and they will be visible to the game
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. Content included in the campaigns directory won't be loaded unless the game is told to do it.
For example, assume you have a campaign called MyCampaign. This is what the userdata/data/campaigns directory looks like:
- userdata/data/campaigns/MyCampaign.cfg - a text file
- userdata/data/campaigns/MyCampaign/ - a subdirectory
- 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
MyCampaign.cfg will have something called the "campaign ifdef", which is a syntax structure that instructs the game to search userdata/data/campaigns/MyCampaign/ for data. More about this is found in BuildingCampaigns. However, it is important to understand the different capabilites of the user data directory.