WML for Complete Beginners: Chapter 2

From The Battle for Wesnoth Wiki
Revision as of 18:59, 29 January 2023 by Celtic Minstrel (talk | contribs) (Nicer index and navigation)

Chapter 2: The Userdata Directory and the Campaign Folder

So now that you understand the basic syntax of WML, it's time to learn where The Battle for Wesnoth stores files so that we can begin creating our campaign.

The Userdata Directory

There are two main directories that Wesnoth creates on your computer. The installation directory contains all the files for the core game. The userdata directory stores all your personal Wesnoth data, which includes your installed add-ons, your settings and preferences, and your saved games. The userdata directory is where we will store your work throughout this tutorial.

The location of your userdata directory differs depending on your operating system, and in the case of Microsoft Windows, the version of your operating system. Refer to the following table to determine where your userdata directory is located:


Windows XP ~/My Documents/My Games/Wesnoth 1.16/
Windows Vista and above ~/Documents/My Games/Wesnoth 1.16/
Mac OS X ~/Library/Application Support/Wesnoth 1.16/
Linux ~/.local/share/wesnoth/1.16/

Note: On Windows, if you chose 'Store userdata in the install location' during setup, the userdata directory is usually in
~/AppData/Local/VirtualStore/Program Files (x86)/Battle for Wesnoth 1.12.6


Now navigate to your userdata folder. Provided that you have already run the Wesnoth application at least once before, you should see a total of five folders ("cache", "data", "editor", "persist", and "saves") in this directory, along with two files ("preferences" and "save_index.gz"). If you see all seven of these, everything is good. If you do not see all seven, try running the Wesnoth application. If that does not work, try restarting your computer. If neither of these steps work, reinstall Wesnoth.

Of the seven objects contained in the userdata folder, you will only ever need to directly interact with two: the "data" folder and the "editor" folder.

The data folder

The data folder (more exactly the data/add-ons/ folder) is where all installed add-ons are kept. This is where we will be building our campaign, when we get to that. If you have previously installed any Wesnoth add-ons, they should show up in this folder.

The editor folder

The editor folder is where all maps created with the in-game map editor are stored. If you have ever created and saved a map in-game, you should see the map file in this directory.

The Campaign Folder

Like I told you earlier, all add-ons are installed in the data/add-ons folder inside the userdata directory. That means that your campaign will also be located inside the data/add-ons folder. If you're not already there, enter the data/add-ons folder now.

Next, create a new folder inside the data/add-ons folder. Name this new folder "my_first_campaign" exactly as I wrote it here (but don't include the quotation marks). Make sure you spelled it right, that you didn't accidentally capitalize any letters and that you included the underscores between the words in the folder name, because if you don't your campaign won't work when you try to play it.

Now enter the "my_first_campaign" folder and create seven new folders. Name these folders "images", "macros", "maps", "scenarios", "translations", "units" and "utils" (again, make sure you spelled everything right, that you didn't accidentally capitalize anything, and that you didn't include the quotation marks).

All campaigns share this common folder structure.

Navigation
Chapter 1
Syntax
WML for Complete Beginners: Chapter 2 Chapter 3
The _main.cfg