Navigation

Chapter 5. Enhancing TaxiPilot

TaxiPilot is still very limited. Although the number of levels and passengers is growing, there's still far too many - not to mention that many of the graphics distributed so far are rather bad. However, TaxiPilot allows you to configure a whole lot of things without having to dig through the code and recompile. This chapter describes the four types of XML-based configuration-files that currently exist, explaining how you can create your own levels and other game-data.

As more and more features have been added and will continue to be added over time, this documentation, too, is growing more and more complex. I try to explain all the possibilities, but chances are you will never need all of those at once. Therefore, don't get frustrated with this lengthy description - probably you can get a good start by looking at the configuration-files provided with the distribution and later check back in the documentation to find out what possibilities there are and what exactly one attribute or another does. Comments on how to make this documentation more readable are always welcome.

Version 0.3.0 introduced some sanity-checks on the configuration-files you write. Image-files are checked for being existent and readable, the parameters you can specify have been assigned upper and lower limits (for numeric attributes), that should be wide enough to allow everything that might make sense (please let me know, if they aren't) but hopefully catch a few mistakes. Default values will be assigned for missing or invalid parameters. These default values sometimes make sense, sometimes they probably don't - so look for debugging messages. Debugging messages are printed to stderr, using 5 levels:

0: Error               These are critical errors meaning that TaxiPilot will not be able to proceed with the
                           configuration selected.
1: Serious Warning     A default value was inserted that probably doesn't make a lot of sense
2: Warning             (default level) A default value was inserted that probably makes sense,
                           but you should still better fix this.
3: Info                A default value was inserted where you are explicitly allowed to omit
                           parameters, or other harmless messages.
4: Translations        A string was translated, a string could not be translated, a translations-file was not found...
                           may generate a LOT of output, that will generally only be useful for translators.

You may change the debug-level using the commandline option --debug-level (level) to change the verbosity. If your configuration does not work and you can't figure out the reason, try setting debug-level to 3. The default debug-level is 2, and I'd consider it good style for the configuration files, that no debug messages are generated at this level.

Before distributing a (large) mission, you may want to start TaxiPilot with the option --thorough_check, which will make it parse all configuration-files belonging to the mission thoroughly once the mission is selected (as opposed to parsing only the information needed at that time). This should output any errors, without having to go through all the levels.

Configuring game-data for TaxiPilot essentially consist of specifying values for a number of attributes. This section briefly explains the kinds of attributes and how they will be handled.

One type of attribute used by TaxiPilot is boolean values, i.e. attributes that turn on or off a certain behavior. Think of them as answers to yes/no-questions. These questions can be "answered" either with "yes"/"no" or with "true"/"false". Both variants have the same effect.

There are two different types of numeric attributes used in the configuration of game-data: integer values (i.e. whole numbers; e.g. "42") and decimal numbers (e.g. "2.345"). While it is always possible to specify an integer value where a decimal number is expected, this is not possible the other way around. Most of the time it should be pretty obvious, whether a numeric attribute should be and integer or a real number (e.g. you can't start out with 3.54 lives). In the examples given, however, I tried to write all decimal-parameters with a dot to make things clear.

Whenever numeric attributes are read, only a certain range of values will be allowed. Check debug-output to see, whether you violated such a boundary. Generally, the defined range of allowed values makes sense and prevents you from accidently specifying nonsense values. Sometimes, however, those boundaries may be too strict for your purposes - in that case, please contact me.

Some attributes allow you to specify a string/text. E.g. the name of the level is a string. There's little to be said about this kind of attribute, except for that strings can be translated.

While filenames are essentially strings, it is important to understand, where TaxiPilot tries to find those filenames.

All files install to the subdir "taxipilot/game_data/" (config-files) or of the KDE-Standard-data-directory (for me that's "/usr/share/apps/"). Whenever you put in a non-absoulte path in your configuration files, TaxiPilot will first try to find those files in (or rather relative to) the directory where the selected mission-configuration files resides. If the files can't be found there, TaxiPilot will append the given filename to the path given above ("/usr/share/apps/taxipilot/game_data" or similar) and check, whether the file can be found there.

What this means practically, is that you should state the file-names of your configuration-files as relative to the directory where your mission-file resides. Now, if you want to use some configuration- or image-files of the distribution (e.g. you want to create an own level, but want to use the passengers and taxi provided), you specify those file-names relative to the default installation-directory. Therefore, TaxiPilot will first check in your mission's directory and then fall back to the files provided with the distribution. (What you can not do, however, is to have some files of one single animation in your mission-directory and some other files of the same animation in the installation-directory!)

You may also use absolute paths in your configuration files. These will be left untouched, but I'd recommend to do so only for testing purposes.

Hopefully, things will get clearer, when you read on. Otherwise, please contact me.

Last modified: Apr 03 2005 17:50 (GMT)