I finally got a system up and running for setting and storing configuration settings. It wasn’t easy, since many of the functions I had to use weren’t exactly very well documented. Everything works now, so here’s a tutorial on how I did it. I’m gonna start with XML files, since that’s what I use to store the settings. I tried using a simple text file first but that was kinda tricky and not very stable; a small glitch could cause the entire game to go into an endless loop, freezing it. I’m not gonna explain what XML files are, there are plenty of websites already that do that. From now on, I’ll assume that you know what they are.
The XML file I used for my settings contains three sections: display, keyboard and joystick settings. Later on a highscore section will probably be added as well. Here’s what the file looks like:

<?xml version=”1.0″ encoding=”utf-8″ standalone=”yes” ?>
<DisplaySettings>
<Width>1440</Width>
<Height>900</Height>
<Fullscreen></Fullscreen>
<Autosize></Autosize>
</DisplaySettings>
<KeyboardSettings>
<Leftkey>left</Leftkey>
<Rightkey>right</Rightkey>
<Upkey>up</Upkey>
<Downkey>down</Downkey>
<Subfire>lcontrol</Subfire>
<Shipfire>lalt</Shipfire>
</KeyboardSettings>
<JoystickSettings>
<Subfire>button0</Subfire>
<Shipfire>button1</Shipfire>
</JoystickSettings>

The name of the file is CustomConfig.xml. Now, before I start explaining how to read and write this file, here’s something very important, especially if you’re using Windows Vista: make sure you have the most recent version of Torque Game Builder! In Vista, the older version (before 1.6) won’t work. This is because of a security feature in Vista that doesn’t allow a program to write to files anywhere on the system (unless you save a document, of course). On XP, you could write to any directory, but on Vista you can only write to the application data directory, wich is hidden in the “Documents and Settings” directory. This article explains everything in detail. Old versions of Torque will attempt to write to the game directory, wich won’t work on Vista. Also, you’ll need to call the setCompanyAndProduct function as soon as possible in your game to make sure you’ll put the config file in a unique location.
Another thing to keep in mind is that while you won’t be able to write to the game directory, you are able to read from it. Torque will first look in the application data directory and if the file isn’t found there, it will go to the game directory. Why is this important? When you distribute the game, you don’t need to copy the config file to the application data directory. Instead, you can leave it in the game directory. The first time your game runs, it will read the settings from the file in the game directory. The first time the player changes one of the settings, it is written automatically to the application data directory.
Okay, enough about the Torque file system, and let’s start coding! Torque contains a class for reading and writing XML files: SimXMLDocument. Unfortunately, this class is mostly undocumented. Fortunately, however, there’s a wrapper class that does everything you need! This class is, conveniently, called “XML” and is located in the common/gameScripts directory of your game, in the file xml.cs. Here’s some sample code on how to use it. It reads the display settings from the file.

%Xml = new ScriptObject() {class = “XML”;};
%Xml.beginRead(ExpandFilename(”~/CustomConfig.xml”));
%Xml.readClassBegin(”DisplaySettings”);
%Width = %Xml.readField(”Width”);
%Height = %Xml.readField(”Height”);
%Fullscreen = %Xml.readField(”Fullscreen”);
%Autosize = %Xml.readField(”Autosize”);
%Xml.readClassEnd();
%Xml.delete();

Here’s how it works. Line 1 creates a ScriptObject instance and assigns the XML class to it. Line 2 opens the configuration file. The ExpandFilename function is necessary to turn the filename into a valid path; you don’t have to worry about the exact path, this happens automatically. Line 3 tells Torque to start reading the DisplaySettings section of the XML document. By sorting the config data into sections, you’ll first of all keep the file easy to read, and second it allows you to use values with the same names in different sections, wich could come in handy in large config files. Lines 4 to 7 read four different settings from the file. The last two lines stop reading the DisplaySettings section and then delete the XML object.
Writing to an XML file happens in more or less the same way. You create an XML object and open the file in the same way, and here’s how you write data:

%Xml.writeClassBegin(”DisplaySettings”);
%Xml.writeField(”Width”,%Width);
%Xml.writeField(”Height”,%Height);
%Xml.writeField(”Fullscreen”,%Fullscreen);
%Xml.writeField(”Autosize”,%Autosize);
%Xml.writeClassEnd();

Pretty much self-explaining. This method can be used to store all kinds of data in an XML-style format. I used it for configuration settings now, but it can also be used, for example, for custom level builders. The possibilities are unlimited.
In the next tutorial, I will explain how to remap input keys.