Difference between revisions of "EditingWesnoth"

Latest revision as of 17:06, 21 May 2023

In order to create custom content for Wesnoth, you need to know where the game's resources are and where to put your own. This page will explain how to find both the data (core game resources) and userdata (custom content) directories, as well as an explanation as to working with each one.

The main menu

The simplest way to find your game and userdata directories is to launch the game and click on the "i" icon on the bottom left corner of the main menu, which will display the Game Version dialog with information about the game paths and build configuration. From here you can copy respective the paths to your clipboard or open them in your platform's file manager. If you want more detailed explanations on the specific locations for your specific system, you can read the How to get there sections below.

The game data directory

Wherever you installed the game, you will find these folders, among others: data, music, sounds, images. The rest are unimportant unless you're a developer looking to tweak stuff about the game itself. Besides data, they contain resources used by the game, not by campaigns.

Inside the data folder you will find , among others, these folders: campaigns, multiplayer, core. These contain the mainline campaigns, the multiplayer maps and scenarios, and all the resources used in add-ons. You may examine the contents of the former for reference on how the campaigns and maps included in mainline are coded. In core, you will find another set of music, sounds, images directories. Look in here to find resources for creating your UMC content.

NOTE: These folders are NOT the place to put your own resources when creating an add-on. You should keep them in your add-on's folder the userdata directory, as detailed below.

In this wiki, the terms "game data", wesnoth/data, or ./data refer to the wesnoth/data directory. The terms "core folder" or core refer to the wesnoth/data/core directory.

How to get there

Windows

C:\Users\<USER>\AppData\Local\Programs\Battle for Wesnoth <VERSION>\data

Note: C refers to the partition or drive where Windows is installed. If your copy of Windows is not on C, or Wesnoth is installed in a different location, the path may not match those given above. If you don't remember where you installed the game, right click on the game's shortcut, open Properties, and click on the "Find target" button.

macOS

Control+click on the application icon. Select "Show Package Contents", then navigate to "Contents" → "Resources".

Linux

Custom builds: /usr/local/share/wesnoth
Debian/Ubuntu packages, or emerge (Gentoo): /usr/share/games/wesnoth
Red Hat Linux-based distributions in general (openSUSE, Fedora): /usr/share/wesnoth
Arch Linux: /usr/share/wesnoth
Mandriva: /usr/share/games/wesnoth
Slackware Linux: /usr/local/share/wesnoth

In a terminal, the command wesnoth --path shows the game data directory.

BSD

OpenBSD package: /usr/local/share/wesnoth

The command wesnoth --path also works.

The user data directory

The user data directory in particular is the most important to a content creator. Inside are your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content. In this wiki, "user data" and userdata/ refer to this directory.

The game looks at the following paths for the respective content:

userdata/data/add-ons - add-ons you have installed via the built-in add-on manager or are designing yourself
userdata/editor - scenario and map files created via the in-game editor
userdata/saves - the directory containing all your savegame files
userdata/cache - the auto-generated game cache files
userdata/preferences - plaintext file containing all your saved user preferences

Note: This may not be totally accurate for all systems, for my Linux system the preferences file is stored in ~/.config/wesnoth

The add-ons directory is particularly useful. In order to work with custom scenarios or campaigns, you will need to have your own add-on set up here. Instructions on how to do so can be found in AddonStructure. Several pages on this wiki will assume you have done so and refer to relative paths in such.

How to get there

Windows

Documents\My Games\Wesnoth<version>

macOS

Wesnoth 1.14.6 and later: ~/Library/Containers/org.wesnoth.Wesnoth/Data/Library/Application Support/Wesnoth_<version>
Older versions: ~/Library/Application Support/Wesnoth_<version>

Note: The Library folder is hidden by default. You can press the Option key and choose Go to access it, or choose Go > Go to Folder… and type in the path there.

Linux

~/.local/share/wesnoth/<version>
If installed via flatpak: ~/.var/app/org.wesnoth.Wesnoth/data/wesnoth/<version>

In a terminal, the command wesnoth --config-path shows the user data directory.

BSD

Same place as Linux.

@@ Line 1: / Line 1: @@
+{{Translations}}
 <!-- single enters on this page are intentional -->
-Wesnoth data is stored in 11 different directories, but most of the information is in '''data/'''.
-== data/ == is divided into 5 subdirectories.
-To understand how '''data/''' works, it is suggested that you read [[BuildingScenariosWML]].
+In order to create custom content for Wesnoth, you need to know where the game's resources are and where to put your own. This page will explain how to find both the <b>data</b> (core game resources) and <b>userdata</b> (custom content) directories, as well as an explanation as to working with each one.
-This page contains links explaining how data in each subdirectory of '''data/|| and the ||game.cfg''' file work.
+<div class="thumb tright"><div>
+[http://www.wesnoth.org/images/sshots/wesnoth-1.14.0-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.14.0-1-192.jpg]
+<div class="thumbcaption">The main menu</div></div>
+</div>
-== Links ==
+The simplest way to find your game and userdata directories is to launch the game and click on the "i" icon on the bottom left corner of the main menu, which will display the Game Version dialog with information about the game paths and build configuration. From here you can copy respective the paths to your clipboard or open them in your platform's file manager. If you want more detailed explanations on the specific locations for your specific system, you can read the <i>How to get there</i> sections below.
-** themes/: [[ThemeSystem]]
+== The game data directory ==
-** maps/: [[BuildingMaps]]
-** scenarios/: [[BuildingScenarios]]
-** translations/: [[WesnothTranslations]]
-** units/: [[CreatingNewUnits]]
-** game.cfg: [[WesnothGameConfigure]]
-Some information is stored in files in the data/ directory itself. These are explained on this page.
+Wherever you installed the game, you will find these folders, among others: <b>data, music, sounds, images</b>. The rest are unimportant unless you're a developer looking to tweak stuff about the game itself. Besides <b>data</b>, they contain resources used by the game, not by campaigns.
-battleworld.cfg:
+Inside the <i>data</i> folder you will find , among others, these folders: <b>campaigns, multiplayer, core</b>. These contain the mainline campaigns, the multiplayer maps and scenarios, and all the resources used in add-ons. You may examine the contents of the former for reference on how the campaigns and maps included in mainline are coded. In <b>core</b>, you will find another set of <b>music, sounds, images</b> directories. Look in here to find resources for creating your UMC content.
-This is a multiplayer scenario (See '''multiplayer.cfg''')
-convert.pl:
+<b>NOTE: These folders are NOT the place to put your own resources when creating an add-on. You should keep them in your add-on's folder the userdata directory, as detailed below.</b>
-!(What does this file do?)
-deaths.cfg:
+In this wiki, the terms <i>"game data"</i>, <i>wesnoth/data</i>,  or <i>./data</i> refer to the wesnoth/data directory. The terms <i>"core folder"</i> or <i>core</i> refer to the wesnoth/data/core directory.
-This is a partial scenario file (See [[BuildingScenarios]])
-used as a shortcut that makes death of Delfador, Kalenz, or Li'sar
-cause the player's defeat on any scenario in the Heir to the Throne campaign.
-See [[BuildingScenariosWML]] for information on how to make shortcuts.
-intro.cfg:
+=== How to get there ===
-This is a partial scenario file containing a [story] tag.
-It is accessed only once, in the file '''scenarios/Elves_Besieged'''.
-See [[BuildingScenariosAdvanced]] for info on [story] tags.
-items.cfg:
+==== Windows====
-This contains macros for objects and items
-(Objects and items are subelements of scenario files.
-See [[BuildingScenariosReference]] for further information).
-multiplayer.cfg:
+C:\Users\<USER>\AppData\Local\Programs\Battle for Wesnoth <VERSION>\data
-This file contains all multiplayer scenarios except Battleworld.
-Multiplayer scenarios have the same format as normal scenarios
-but are contained within a '''[multiplayer]|| tag instead of a ||[scenario]''' tag.
-== multiplayer.cfg''' also contains '''[era] == tags which contain information about the possible eras a multiplayer game
-can take place in. Each era contains '''[multiplayer_side]''' tags which contain information about the different sides
-available in that area.
-names.cfg:
+<b>Note:</b> C refers to the partition or drive where Windows is installed. If your copy of Windows is not on C, or Wesnoth is installed in a different location, the path may not match those given above. If you don't remember where you installed the game, right click on the game's shortcut, open Properties, and click on the <b>"Find target"</b> button.
-Names in Wesnoth are generated by randomly combining parts
-of the base names, which are contained in this file.
-sample_translation.cfg:
+==== macOS ====
-This is not a data file.
-It is a template for translations.
-scenario-test.cfg:
+* Control+click on the application icon.  Select <b>"Show Package Contents"</b>, then navigate to  <b>"Contents"</b> → <b>"Resources"</b>.
-This file contains a test scenario (accessed by the command '''wesnoth -t''').
-Any scenario enclosed in [test] tags with the attribute '''id=test'''
-is interpreted by Wesnoth as being the test scenario.
-schedules.cfg:
+==== Linux ====
-This file contains the definitions for the different times of day.
-terrain.cfg:
+* <b>Custom builds:</b> /usr/local/share/wesnoth
-This file contains a series of '''[terrain]''' tags, each of which creates a new terrain.
+* <b>Debian/Ubuntu packages, or emerge (Gentoo)</b>: /usr/share/games/wesnoth
+* <b>Red Hat Linux-based distributions in general (openSUSE, Fedora):</b> /usr/share/wesnoth
+* <b>Arch Linux:</b> /usr/share/wesnoth
+* <b>Mandriva:</b> /usr/share/games/wesnoth
+* <b>Slackware Linux:</b> /usr/local/share/wesnoth
-tutorial.cfg:
+In a terminal, the command <code>wesnoth --path</code> shows the game data directory.
-This file contains the tutorial (accessed by the button 'tutorial' in-game).
-Any scenario enclosed in [tutorial] tags with the attribute '''id=tutorial'''
-is interpreted by Wesnoth as being the tutorial.
-utils.cfg:
+====BSD====
-This contains macros for scenario files.
+* <b>OpenBSD package:</b> /usr/local/share/wesnoth
-Syntax for '''[multiplayer_side]|| and ||[terrain]''' tags:
+The command <code>wesnoth --path</code> also works.
-The first keys in '''[multiplayer_side]''' are
+== The user data directory ==
-== name''', ||type||, ||recruit||, and '''recruitment_pattern ==.
-These work the same way as in a normal '''[side]''' tag (See [[BuildingScenariosSimple]]).
-The '''music''' key is the music to play for that team.
+The user data directory in particular is the most important to a content creator. Inside are your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content. In this wiki, <i>"user data"</i> and <i>userdata/</i> refer to this directory.
-The '''terrain_liked''' key !(does what?)
-The only neccessary keys in a '''[terrain]''' tag are
+The game looks at the following paths for the respective content:
-== name''', ||char||, ||image||, and '''aliasof ==.
-All instances of the character '''char''' in a map file will be replaced by this terrain.
+* <b><i>userdata</i>/data/add-ons</b> - add-ons you have installed via the built-in add-on manager or are designing yourself
-This terrain is gameplay-equivalent to the terrain
+* <b><i>userdata</i>/editor</b> - scenario and map files created via the in-game editor
-with character equal to the value of '''aliasof'''
+* <b><i>userdata</i>/saves</b> - the directory containing all your savegame files
+* <b><i>userdata</i>/cache</b> - the auto-generated game cache files
+* <b><i>userdata</i>/preferences</b> - plaintext file containing all your saved user preferences
-== name == is displayed in the terrain descriptor corner (top-right)
+''Note: This may not be totally accurate for all systems, for my Linux system the preferences file is stored in ~/.config/wesnoth''
-when this terrain is selected.
-== image == is the image displayed for this terrain.
-All other keys for '''[terrain]''' affect the image in some way.
-(not documented)
-== See Also ==
+The add-ons directory is particularly useful. <b>In order to work with custom scenarios or campaigns, you <i>will need</i> to have your own add-on set up here.</b> Instructions on how to do so can be found in [[AddonStructure]]. Several pages on this wiki will assume you have done so and refer to relative paths in such.
+=== How to get there ===
+==== Windows ====
+* Documents\My Games\Wesnoth<version>
-*
+==== macOS ====
+* <b>Wesnoth 1.14.6 and later:</b> ~/Library/Containers/org.wesnoth.Wesnoth/Data/Library/Application Support/Wesnoth_<version>
+* <b>Older versions:</b> ~/Library/Application Support/Wesnoth_<version>
+<!-- gotta keep mentioning the old path until 1.16.0 since not all macOS users update every stable release -->
+<b>Note:</b> The Library folder is hidden by default. You can press the Option key and choose Go to access it, or choose Go > Go to Folder… and type in the path there.
+==== Linux ====
+* ~/.local/share/wesnoth/<version>
+* <b>If installed via flatpak:</b> ~/.var/app/org.wesnoth.Wesnoth/data/wesnoth/<version>
+In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.
+==== BSD ====
+* Same place as Linux.
+== See Also ==
+* [[Create]]
+[[Category:Create]]