Packaging up a Map or Mod

Version 1.2 v. 1.4

Patch 1.2 does not support all the required features to get simple map or campaign mods running, nor does it provide the ability to download content from the server. Both of these issues will both be fixed in version 1.4. As a workaround for now, you can treat these simple mods as full mods as described below.

When running with text based declarations, you must set the "com_useBinaryDecls" cvar to 2, which will allow text declarations to override binary declarations. This will be the default setting in 1.4.

Pak File Configs

Addon Configs

An addon config contains meta data used to detail which maps/campaigns are held within a pk4 without the need for the engine to load any assets from the pk4.

Here is an example:

addonDef {
	0x12345678
}

mapMetaData maps/volcano {
	"pretty_name"		"Volcano"
	"mapinfo"		"volcano"
	"dz_deployInfo"		"volcano"
	"climate_skins"		"climate_skins_volcano"
	"server_shot_thumb"	"levelshots/thumbs/volcano.tga"
	"show_in_browser"	"1"
}

The file must start with the "addonDef" identifier, and then a set of braces containing a list of dependencies. This list is the checksums of any other pak files which this pak file requires to also be loaded. The list may simply be empty if the pak file is entirely stand-alone.

After this you may provide any meta data required by the game you are running. The base ETQW game will load "mapMetaData" and "campaignMetaData" blocks, but you may provide any kind of meta data and it will be loaded regardless of whether the game understands how to use the data or not.

The above example specifies that this pak file contains a map stored as "maps/volcano".

To get the checksum for a pak file, use the "path" command, this will list all loaded pak files and their checksums.

Pakmeta Configs

Pakmeta configs are named pakmeta.conf. They are similar in structure to addon configs, but they do not contain the addonDef section at the top of the file, only the meta data blocks.

When using the SDK exe you may also provide a pakmeta config in the root of your mod folder. This lets you provide additional data without having to include that of the base game.

Only one pakmeta config at a time will be loaded from within pak files, the pak file with the highest priority which contains a pakmeta config, will be used.

Binary Configs

When packaging up binaries (game code/compiled script), you need to include a binary.conf file in the pak file. This file should contain a single number, which represents which OS the binaries are being supplied for. The currently supported numbers are 0 for Windows, and 2 for Linux.

Pak File Priority

Pak files are sorted in alphabetical order within their own directory. The following is the list of directories which will be searched, from lowest priority to highest priority.

<fs_cdpath>\base
<fs_cdpath>\<fs_game_base>
<fs_cdpath>\<fs_game>
<fs_basepath>\base
<fs_basepath>\<fs_game_base>
<fs_basepath>\<fs_game>
<fs_devpath>\base
<fs_devpath>\<fs_game_base>
<fs_devpath>\<fs_game>
<fs_savepath>\base
<fs_savepath>\<fs_game_base>
<fs_savepath>\<fs_game>
<fs_userpath>\base
<fs_userpath>\<fs_game_base>
<fs_userpath>\<fs_game>

All of the values in <> are cvar names, which if blank will not be used.

Pak Files Overview

Pak files are simply zip archives with a .pk4 extension.

There are basically 4 types of pak files you may use.

Official Pak Files

These are named starting with "pak". they will always be loaded in the pure system, unless they *only* contain files which are excluded from pure requirements. A list of pure exceptions is listed below. Official pak files can never be downloaded from a server.

Addon Pak Files

These are pak files which aren't named starting with "pak", and contain a addon config within them. These files will never be included automatically for pure, but only when the game decides it needs them, and are generally used for custom maps and campaigns. The meta data from these pak files will always be loaded however, so the gamecode knows what is contained within them. Addon pak files may be downloaded from servers.

Binary Pak Files

These should contain any and all binaries you need to load for your mod, for a specific OS, as well as containing a matching binary config. These pak files may be downloaded from the server, and will warn the user that they are downloading executable code. Again, their name should not begin with "pak".

Additional Pak Files

These are any paks file not covered by the previous cases. These will be included in the pure system if and only if, the server loads any files which are not covered by pure exclusions during engine startup (or during first map load, but that is riskier, so is not recommend).The easiest way to get this to happen is to include a declaration file which is not on the pure exclusion list. This file can be empty.

Pure Mode Exclusions

The following is a list of directories and extensions for files which will not mark a pak file as being required for pure if they are loaded.

Path	Extension
localization	.lang
localization	.ogg
generated/ogg/localization	.ogg
localization	.wav
localization	.font
localization	.cfg

Mods

Addon Mod: A New Map

In the case of simply adding a new map to an existing game, all you need to do is add everything to an Addon pak file.

Addon Mod: A New Campaign

This is very similar to adding a new map. First you must again add all the required media to an Addon pak file. If this is purely a campaign using existing maps, then this will likely just be a single campaign .def file. If it is a campaign using base game maps, then you can simply supply the meta data for the new campaign and you are done. If the campaign includes custom maps, then you must make sure to include the checksums for the pak files which contain those maps in the dependencies section.

Full Mods

If you want your content to always be loaded, then you should run with the "fs_game" cvar set to the mod name, and include all of the pak files in this directory.

All binaries for the mod should be packaged up in Binary pak files, one for each OS, as described above.

All required content should be pakaged up in either Official or Additional pak files, one of which should contain a Pakmeta config if you wish to override the one from the base game.

Any optional maps should be included in Addon pak files.