Difference between revisions of "EditingWesnoth"

From The Battle for Wesnoth Wiki
(margin change)
(Linux)
 
(70 intermediate revisions by 27 users not shown)
Line 1: Line 1:
 +
{{Translations}}
 
<!-- single enters on this page are intentional -->
 
<!-- single enters on this page are intentional -->
  
== Game and User Directories ==
+
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.
  
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.
+
<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 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.
 +
 
 +
== The game data directory ==
 +
 
 +
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.
 +
 
 +
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.
 +
 
 +
<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>
 +
 
 +
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.
  
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.
+
=== How to get there ===
  
=== Where is my '''game''' data directory? ===
+
==== Windows====
  
====Windows====
+
* <b>On 32-bit computers:</b> C:\Program Files\Battle for Wesnoth <version>\data
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.
+
* <b>On 64-bit computers:</b> C:\Program Files (x86)\Battle for Wesnoth <version>\data
  
====Mac OS X====
+
<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.
Downloaded from sourceforge: command-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====
+
====Mac OS X ====
/usr/local/share/wesnoth <br>
 
From apt-get (Debian and Ubuntu) or emerge (Gentoo): /usr/share/games/wesnoth <br>
 
SUSE 10.0 (pre-installed): /usr/share/wesnoth<br>
 
Fedora 5 (Installed from yum repository RPM): /usr/share/wesnoth<br>
 
Mandriva 2006.0: /usr/share/games/wesnoth<br>
 
Slackware 12 (Installed from .tgz package at LinuxPackages.net): /usr/local/share/wesnoth<br>
 
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? ===
+
* Control+click on the application icon.  Select <b>"Show Package Contents"</b>, then navigate to  <b>"Contents"</b> → <b>"Resources"</b>.
  
====Windows====
+
==== Linux ====
c:\Program Files\Wesnoth\userdata
 
  
or c:\Users\USERNAME\AppData\Local\VirtualStore\Program Files\Wesnoth\userdata
+
* <b>Custom builds:</b> /usr/local/share/wesnoth
on Vista, which has virtual folders. The AppData folder is hidden.
+
* <b>Debian/Ubuntu packages, or emerge (Gentoo)</b>: /usr/share/games/wesnoth
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.
+
* <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
  
====Mac OS X====
+
In a terminal, the command <code>wesnoth --path</code> shows the game data directory.
Downloaded from sourceforge: ~/Library/Preferences/Wesnoth <br>
 
Command line build: ~/.wesnoth
 
  
====Linux====
+
====BSD====
~/.wesnoth
 
  
== Game data ==
+
* <b>OpenBSD package:</b> /usr/local/share/wesnoth
  
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
+
The command <code>wesnoth --path</code> also works.
  
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.
+
== The user data directory ==
  
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.
+
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.
  
=== Game Configuration ===
+
The game looks at the following paths for the respective content:
  
Some information is stored in files in the ./data directory itself:
+
* <b><i>userdata</i>/data/add-ons</b> - add-ons you have installed via the built-in add-on manager or are designing yourself
* amla.cfg - global definition for After Max-Level Advancement (currently 3 hp per 100 XP)
+
* <b><i>userdata</i>/editor</b> - scenario and map files created via the in-game editor
* fonts.cfg - defines which fonts the game can use
+
* <b><i>userdata</i>/saves</b> - the directory containing all your savegame files
* game.cfg
+
* <b><i>userdata</i>/cache</b> - the auto-generated game cache files
* help.cfg - the entire help system document
+
* <b><i>userdata</i>/preferences</b> - plaintext file containing all your saved user preferences
* 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:
+
''Note: This may not be totally accurate for all systems, for my Linux system the preferences file is stored in ~/.config/wesnoth''
* themes/: [[ThemeSystem]]
 
* maps/: [[BuildingMaps]]
 
* scenarios/: [[BuildingScenarios]]
 
* translations/: [[WesnothTranslations]]
 
* units/: [[BuildingUnits]]
 
* game.cfg: [[WesnothGameConfigure]]
 
  
== User Data ==
+
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.
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.
+
=== How to get there ===
  
For example, assume you have a campaign called MyCampaign.  This is what the ''userdata''/data/campaigns directory looks like:
+
==== Windows ====
* ''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.
+
* <b>Windows 2000/XP:</b> My Documents\My Games\Wesnoth<version>
 +
* <b>Windows Vista/7/8/10:</b> Documents\My Games\Wesnoth<version>
 +
 
 +
<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.
 +
 
 +
==== Mac OS X ====
 +
 
 +
* ~/Library/Application Support/Wesnoth_<version>
 +
 
 +
<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.
 +
 
 +
==== 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 ==
 
== See Also ==
Line 102: Line 95:
 
* [[Create]]
 
* [[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]]
 
[[Category:Create]]

Latest revision as of 11:34, 2 November 2019


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>
  • 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.

See Also

This page was last edited on 2 November 2019, at 11:34.