Packaging up a Map or Mod - Revision history

Digibob: /* Pak Files Overview */

2007-12-14T12:57:08Z

‎Pak Files Overview

Digibob at 12:54, 14 December 2007

2007-12-14T12:54:50Z

Digibob at 12:52, 14 December 2007

2007-12-14T12:52:03Z

New page

== 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.

The first is 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.

The second is 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.

The third is 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".

The last form of pak file is any not covered by the previous cases, and shall be refered to as Additional pak files. 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.

@@ Line 77: / Line 77: @@
 There are basically 4 types of pak files you may use.
-The first is 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.
+=== Official Pak Files ===
-The second is 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.
+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.
-The third is 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".
+=== Addon Pak Files ===
-The last form of pak file is any not covered by the previous cases, and shall be refered to as Additional pak files. 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.
+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.
 == Pure Mode Exclusions ==

@@ Line 89: / Line 89: @@
 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.
+{| style="border: 1px solid #AAAAAA;"
 |-
 ! Path
@@ Line 111: / Line 111: @@
 | localization
 | .cfg
+|}
 == Mods ==