Q3Offline Document Templates
Introduction to Q3Offline Templates
As well as playing Quake III Arena with Q3Offline, you can also use Q3Offline with other retail games based on the Quake III Arena engine, such as Star Trek Voyager: Elite Force.
For each game you want to configure using Q3Offline, you must have a template (.q3t) file in the Templates sub directory below the main Q3Offline run time directory. The template file tells Q3Offline important information about the configuration of the game.
Q3Offline is provided with template files for a number of games, including Quake III Arena itself, Quake III Team Arena and Star Trek Voyager: Elite Force. If you have created a template file for other games not already supported, please send the template file to me and I will posted it onto the Q3Offline web site, on the Download page.
To install a new template, simply copy it to the Templates sub directory below the main Q3Offline run time directory. Q3Offline will automatically pick up the template the next time you create a new document using the File, New command.
If you have one or more templates (.q3t) files in the Templates sub directory, then the Q3Offline File, New command results in the New dialog being displayed. The New dialog allows you to pick from the available templates. If you only have one template file, then Q3Offline will automatically use it instead. If you do not have any template files, then Q3Offline will use a default template that is suitable for Quake III Arena.
When you open an existing document in Q3Offline, Q3Offline reads the template for that document. This means then when you make a change to a template, it will affect existing documents, as well as new ones that you create.
Q3Offline templates have been tested with Quake III Arena, Quake III Team Arena, and Star Trek Voyager: Elite Forces, the three games I own that use the Quake III Arena engine. I want to make sure it works with other Quake III Arena based games too. If you think you have spotted a problem with the templates, or something that the templates don't cover, then please contact me and I'll try my best to fix it.
Format of Q3Offline Templates
Q3Offline templates use the Windows ini file format. You can edit them using any text editor, such as Notepad.
A template has a number of sections.
[General]
Main settings.
Version: Mandatory. Always set to 1.
Default: Optional. Defaults to N. If Y then this is the default template.
The default template is used:
The File, New menu option will always prompt you to pick a template, using the New dialog.
There should only be one default template; Q3Offline will ignore any other default templates except for the last one it finds in the Templates sub directory. If there are no default templates, then Q3Offline will always prompt you to choose a template.
Name: Mandatory. The name that will appear in the New dialog from the File New menu. This can be any suitable text.
ShortName: Mandatory. The name Q3Offline uses internally to refer to the game, e.g., as part of the registry key to store information about the game. Use a short string, with no spaces or punctuation characters.
ExeFileName: Mandatory. The name of the executable file for the game, e.g., quake3.exe. Do not include the directory.
MainGameSubDir: Mandatory. The main game folder; for Quake III Arena this is baseq3.
DefaultGameSubDir: Mandatory. The default game folder, if different to MainGameSubDir. Defaults to MainGameSubDir. The DefaultGameSubDir is the folder that will appear in the Folder combo box on the Game page when creating a new document based on this template. The DefaultGameSubDir is also the folder from which maps and bots will be automatically imported, if Auto import is ticked on the Game page.
Define DefaultGameSubDir if you are creating a template for a mod that is installed into a folder other than baseq3.
DefaultGameType: Optional. Defaults to 0. The default game type (i.e., the value of the g_gametype variable). Must match a game type value defined in one of the [GameType] sections (see below).
CfgFileName: Mandatory. The cfg file the game uses to store its configuration. For Quake III Arena this is q3config.cfg. Q3Offline needs to able to write to this file.
Levelshots: Optional. The location of map levelshots for the game. The location may be in a pk3 file in the game folder, or in a sub-directory below the game folder. Use %map% to substitute for the map name. jpgs and tga files are support.
If the levelshot is in a different pk3 file to the map then prefix the levelshot name with the pk3 name, e.g., main\pak1.pk3\textures\mohmenu\dmloading\%map%.tga.
If the levelshot name cannot be automatically derived from the map name, then specify the levelshot name for each individual map (see DefaultMap Location below).
The levelshot for a map is displayed by Q3Offline when you select the map on the Maps page.
BotIcon: Optional. The location of bot icons for the game. The location may be in a pk3 file in the game folder, or in a sub-directory below the game folder. Use %model%, %skin%, and %bot% to substitute for the bot's model, skin and name, respectively.
The bot icon is displayed by Q3Offline when you select the bot on the Bots page.
BotTaunt: Optional. The location of bot sound files for the game. The location may be in a pk3 file in the game folder, or in a sub-directory below the game folder. Use %model%, %skin%, and %bot% to substitute for the bot's model, skin and name, respectively.
The bot taunt is played by Q3Offline when you select the bot on the Bots page.
MapLongnameKey: Optional. Defaults to longname. This is the name of the field in the arenas.txt file that defines the long name for the map. Normally this field is called longname, but some games supply long names in other languages. For example, Star Trek Voyager: Elite Forces defines long names in English, German and French. Thus the map hm_dn1 in the arenas.txt file is defined as follows:
map "hm_dn1"
longname "The Machine"
longname_deutsch "Die Maschine"
longname_francais "La Machine"
To get Q3Offline to display the German long names for maps, set MapLongnameKey=longname_deutsch.
GameAnnounceSound: Optional. Used by Q3Offline to announce the start of the game. You can optionally include the name of the pak file which contains the sound file, e.g.,
GameAnnounceSound=baseq3\pak0.pk3,sound\feedback\intro_01.wav
If you omit the name of the pak file, it defaults to MainGameSubDir\pak0.pk3.
ExePathRegKey: This is the name of the Windows registry key and value that holds the location of the main exe file for the game. Prefix the key with either HKLM (for HKEY_LOCAL_MACHINE) or HKCU (for HKEY_CURRENT_USER).
For example, installing Quake III Arena creates the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Id\Quake III Arena, which has a value called INSTALLEXEPATH which holds the installation location of the quake3.exe. In the template file this key should be specified as:
ExePathRegKey=HKLM\SOFTWARE\Id\Quake III Arena\INSTALLEXEPATH
If the value in the registry key points does not include the name of the exe file, but just the directory, then Q3Offline will automatically append the name of the game exe, as defined by the ExeFileName setting.
ExeSubDir: If the game executable is in a sub-directory to the location pointed at by the ExePathRegKey registry key, then use ExeSubDir to define the sub-directory.
BotFilesDir: The location for bot files in the pak files. Defaults to botfiles.
BotsDir: The location for bot AI files in the pak files. Defaults to botfiles\bots.
BotAIFileExt: The extension of bot AI files
in the pak files. Defaults to _?.c.
[OptionFiles]
This section defines the Q3Offline Option Files that will be loaded by this template, which in turn determines the options that will appear in the Advanced Page.
Each line in this section is the name of a Q3Offline Option File. The name must not include the directory name. Q3Offline will load the file from the Templates sub directory below the main Q3Offline directory. If present, Q3Offline will also automatically load the AutoExec.q3v file from the Templates directory. Do not include AutoExec.q3v in the [OptionFiles] section, otherwise it will be loaded twice.
[GameTypes]
This section defines the game types (e.g., Free for all, CTF) that are supported by this template.
Each line in this section is the name of another section in the template that defines the settings for one particular game type.
[GameType]
Each [GameType] section defines the settings for one particular game type.
The settings are:
The original Quake III Arena offers the following game types:
- 0 - Free for all.
- 1 - Tournament.
- 3 - Deathmatch.
- 4 - Capture the flag.
Quake III Team Arena added the following game types:
- 5 - One flag capture the flag.
- 6 - Overload.
- 7 - Harvester.
In Return to Castle Wolfenstein the game types are:
- 5 - Objective.
- 6 - Stopwatch.
- 7 - Checkpoint.
The original Quake III Arena offers the following map types:
- single
- ffa
- tourney
- ctf
Quake III Team Arena added the following map types:
- oneflag
- overload
- harvester
When Q3Offline imports a map, it uses the type field in the arena file for the map to determine for which game types the map will be available. For example, the arenas.txt in the orginal Quake III Arena baseq3\pak0.pk3 file, defines the q3dm1 map ("Arena Gate") as follows:
{
map "q3dm1"
bots "ranger"
longname "Arena Gate"
fraglimit 10
type "single ffa tourney"
}
Q3Offline will import the q3dm1 map into all game types that support one or more of the single, ffa, or tourney map types.
[DefaultMaps]
Each DefaultMaps section in the template defines the default maps for a particular game type. These are the default maps that Q3Offline will display on the Maps page when this game type is selected in the Game Type combo box on the Game page.
Each line in the section contains the settings for one map, as a list of comma separated items. Do not use any space characters between the items.
The items are:
[DefaultBots]
This section contains the default bots that Q3Offline will display on the Bots page. This information can usually be obtained from a scripts/bots.txt file in the game's pk3 files.
Each line in the section contains the settings for one bot, as a list of comma separated items. Do not use any space characters between the items.
The items are:
[BotSkills]
This section defines how Q3Offline displays the names for the bot skill levels, from 1 to 5:
Skill1=defaults to I Can Win
Skill2=defaults to Bring It On
Skill3=defaults to Hurt Me Plenty
Skill4=defaults to Hardcore
Skill5=defaults to Nightmare
Sound Files
Some of the options in the template define the type and location of sound files. Q3Offline can play back wave files (.wav) and Mpeg audio files (mpg, mp1, mp2 and mp3).
The sound files are normally stored in the game's pk3 files. But you can also choose to play your own sounds files that are not in any pk3. Create a sub directory of the game folder (e.g., baseq3\sound) and put your sound files in there. Then in the template, give the location of the sub directory relative to the game folder, e.g.,
GameAnnounceSound=sound\timetodie.mp3
will play baseq3\sound\timetodie.mp3 when you launch Quake III Arena from Q3Offline.