Difference between revisions of "EditingWesnoth"

From The Battle for Wesnoth Wiki
m (Windows)
(23 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{EditingWesnoth/Translations}}
+
{{Translations}}
 
<!-- single enters on this page are intentional -->
 
<!-- single enters on this page are intentional -->
  
 
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.
 
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.
  
== The game data directory ==
+
<div class="thumb tright"><div>
 +
[http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.11.7-1-175.jpg]
 +
<div class="thumbcaption">Game paths</div></div>
 +
</div>
  
The data directory will be wherever you installed the game, alongside there subdirectories: <i>music, sounds, images</i>. There are several others, but these are the important ones. You don't need to pay attention to them right now.
+
The simplest way to find your game and userdata directories is to go to <b>Preferences → General → Paths</b> (shown on the right). 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.
  
Inside the <i>data</i> folder you will find a folder called <i>core</i>. This folder contains another set of <i>music, sounds, images</i> (as well as others) folders. These contain all the resources shipped with the game for use in mainline and UMC campaigns. These are the ones you'll usually look for resources in when designing your content.
+
== The game data directory ==
  
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 director.
+
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.
  
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
+
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.
  
Become familiar with what is in wesnoth/data/campaigns and wesnoth/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.
+
<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>
  
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.
+
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.
  
 
=== How to get there ===
 
=== How to get there ===
  
====Windows====
+
==== Windows====
 +
 
 +
* <b>On 32-bit computers:</b> C:\Program Files\Battle for Wesnoth <version>\data
 +
* <b>On 64-bit computers:</b> C:\Program Files (x86)\Battle for Wesnoth <version>\data
  
* ''X:\Program Files\Battle for Wesnoth <version>\data'', where X: corresponds to the drive where Windows is installed (normally C:).
+
<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.
* On 64-bit computers, it will be in ''X:\Program Files (x86)\Battle for Wesnoth <version>\data''.
 
* The path may be different if you originally chose to install the game in a different location. In such case, look for the data folder in the folder where you installed the game.
 
  
====Mac OS X====
+
====Mac OS X ====
  
* SourceForge.net bundle or XCode builds: Control+click on the application icon.  Select "Show Package Contents.Select "Contents", then "Resources".
+
* Control+click on the application icon.  Select <b>"Show Package Contents"</b>, then navigate to <b>"Contents"</b> → <b>"Resources"</b>.
* Custom builds: ''/usr/local/share/wesnoth''
 
  
====Linux====
+
==== Linux ====
  
* Custom builds: ''/usr/local/share/wesnoth''
+
* <b>Custom builds:</b> /usr/local/share/wesnoth
* Debian/Ubuntu packages, or emerge (Gentoo): ''/usr/share/games/wesnoth''
+
* <b>Debian/Ubuntu packages, or emerge (Gentoo)</b>: /usr/share/games/wesnoth
* Red Hat Linux-based distributions in general (openSUSE, Fedora): ''/usr/share/wesnoth''
+
* <b>Red Hat Linux-based distributions in general (openSUSE, Fedora):</b> /usr/share/wesnoth
* Mandriva: ''/usr/share/games/wesnoth''
+
* <b>Arch Linux:</b> /usr/share/wesnoth
* Slackware Linux: ''/usr/local/share/wesnoth''
+
* <b>Mandriva:</b> /usr/share/games/wesnoth
 +
* <b>Slackware Linux:</b> /usr/local/share/wesnoth
  
 
In a terminal, the command <code>wesnoth --path</code> shows the game data directory.
 
In a terminal, the command <code>wesnoth --path</code> shows the game data directory.
Line 43: Line 47:
 
====BSD====
 
====BSD====
  
* OpenBSD package: ''/usr/local/share/wesnoth''
+
* <b>OpenBSD package:</b> /usr/local/share/wesnoth
  
 
The command <code>wesnoth --path</code> also works.
 
The command <code>wesnoth --path</code> also works.
Line 51: Line 55:
 
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 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 user data directory can do a lot of things. The game looks here for several things:
+
The game looks at the following paths for the respective content:
* <i>userdata</i>/data/add-ons - add-ons you have installed via the built-in add-on manager or are designing yourself
 
* <i>userdata</i>/editor/maps - multiplayer standalone maps (map data only)
 
 
 
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. Several pages on this wiki will assume you have done so and refer to relative paths in such.</b>
 
  
The following files and directories are mandatory for a simple add-on (assuming your add-on is called MyCampaign):
+
* <b><i>userdata</i>/data/add-ons</b> - add-ons you have installed via the built-in add-on manager or are designing yourself
 +
* <b><i>userdata</i>/editor</b> - scenario and map files created via the in-game editor
 +
* <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
  
* <i>userdata</i>/data/add-ons/MyCampaign/ - your campaign's directory
+
''Note: This may not be totally accurate for all systems, for my Linux system the preferences file is stored in ~/.config/wesnoth''
* <i>userdata</i>/data/add-ons/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
 
* <i>userdata</i>/data/add-ons/MyCampaign/scenarios
 
* <i>userdata</i>/data/add-ons/MyCampaign/maps
 
  
The following are optional, and are used if you create your own custom units, images, etc:
+
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.
 
 
* <i>userdata</i>/data/add-ons/MyCampaign/units
 
* <i>userdata</i>/data/add-ons/MyCampaign/images
 
* <i>userdata</i>/data/add-ons/MyCampaign/music
 
* <i>userdata</i>/data/add-ons/MyCampaign/sounds
 
* <i>userdata</i>/data/add-ons/MyCampaign/macros
 
  
 
=== How to get there ===
 
=== How to get there ===
  
====Windows====
+
==== Windows ====
  
* BfW 1.8 and later, if you did not choose "Store userdata in the install location" when installing the game and you launch the game using the start menu shortcut:
+
* <b>Windows 2000/XP:</b> My Documents\My Games\Wesnoth<version>
** Windows 2000/XP: <code>My Documents\My Games\Wesnoth<version></code>
+
* <b>Windows Vista/7/8/10:</b> Documents\My Games\Wesnoth<version>
** Windows Vista/7/8: <code>Documents\My Games\Wesnoth<version></code>
 
* If any of the above does not apply:
 
** The <code>userdata</code> subdirectory of the install location (usually <code>C:\Program Files\Battle for Wesnoth <version>\userdata</code>).
 
** ''Note (Windows Vista/7):'' Writes to this directory may be silently redirected to the "Virtual Store", typically <code>C:\Users\<yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version></code>
 
  
''Note:'' 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.
+
<b>Note:</b> The above only applies if you did not select "Store userdata in the install location" when installing the game. If you did, keep in mind that on Windows Vista and later writes to the userdata directory in the install location may be silently redirected to the "Virtual Store", typically <code>C:\Users\yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version></code>. Virtual Store is hidden by default; it can be accessed by by typing <i>"shell:local appdata"</i> in Explorer's address bar.
  
''Note:'' To find the Virtual Store using Windows Explorer, you need to make hidden files visible. This can be done from Explorer's "Folder Options" menu option -> "View" tab -> "Show hidden files, folders, and drives". Alternatively, the hidden directory can be accessed by typing "shell:local appdata" in Explorer's address bar.
+
==== Mac OS X ====
  
====Mac OS X====
+
* ~/Library/Application Support/Wesnoth_<version>
  
* SourceForge.net bundle: ''~/Library/Application Support/Wesnoth_1.x/'' (1.8 and later), or ''~/Library/Preferences/Wesnoth'' (older versions). As of OS X 10.7, this location is hidden by default. Push "alt" (⌥) and use "Go" to access the Library then find ''~/Library/Application Support/Wesnoth_1.x/''
+
<b>Note:</b> As of OS X 10.7, 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.
* Custom builds: same as Linux - see below for details.
 
  
====Linux====
+
==== Linux ====
* Wesnoth 1.10: ''~/.local/share/wesnoth/1.10''
+
* ~/.local/share/wesnoth/<version>
* Wesnoth 1.9: ''~/.local/share/wesnoth/1.9''
 
* Wesnoth 1.8: ''~/.wesnoth1.8''
 
* Older versions: ''~/.wesnoth''
 
  
 
In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.
 
In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.
  
====BSD====
+
==== BSD ====
 
* Same place as Linux.
 
* Same place as Linux.
  

Revision as of 03:43, 12 August 2017


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.

wesnoth-1.11.7-1-175.jpg

Game paths

The simplest way to find your game and userdata directories is to go to Preferences → General → Paths (shown on the right). 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

  • On 32-bit computers: C:\Program Files\Battle for Wesnoth <version>\data
  • On 64-bit computers: C:\Program Files (x86)\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.

Mac OS X

  • 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

  • Windows 2000/XP: My Documents\My Games\Wesnoth<version>
  • Windows Vista/7/8/10: Documents\My Games\Wesnoth<version>

Note: The above only applies if you did not select "Store userdata in the install location" when installing the game. If you did, keep in mind that on Windows Vista and later writes to the userdata directory in the install location may be silently redirected to the "Virtual Store", typically C:\Users\yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version>. Virtual Store is hidden by default; it can be accessed by by typing "shell:local appdata" in Explorer's address bar.

Mac OS X

  • ~/Library/Application Support/Wesnoth_<version>

Note: As of OS X 10.7, 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>

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

BSD

  • Same place as Linux.

See Also