PK3

PK3 is a data file format used by Doom-based games. Originally introduced for Quake III Arena and supported by SRB2 since v2.1.21, PK3 files are simply ZIP files with a different file ending. In comparison to Doom's traditional data file format, WAD, PK3 offers two advantages: Unlike WAD files, which are merely a collection of lumps, PK3 files can have a folder structure, allowing modders to properly organize their resources. Furthermore, because they are compressed, they take up less space than a WAD file containing the same data. As with WAD files, the individual files contained in a PK3 file are called lumps.

Since PK3 files are simply renamed ZIP files, they can be opened by any ZIP editing program, such as 7-Zip. However, it is recommended to use a lump editor like SLADE to edit PK3 files instead. In fact, the reason for using a different file ending than .zip is to avoid confusion with regular ZIP files and prevent users from thinking they have to extract the contents of a PK3 file before adding them to the game. Among map editors for SRB2, Zone Builder is the only one that supports PK3 files as resources. However, it cannot open or edit maps contained inside a PK3 file. To edit a map inside a PK3 file, the map must be exported into a WAD file first.

Contents

Like WAD files, PK3 files may contain any type of lump that is recognized by SRB2; see WAD file > Contents for an overview. Unlike WAD files, the name of a lump is not limited to eight characters. However, many types of resources, such as textures, music and sounds, are still limited to eight characters by SRB2 itself. In these cases, SRB2 will only read the first eight characters of the lump's name and ignore the rest.

In addition to files, PK3 files may also contain folders, which may themselves contain files or further subfolders. The slash and backslash characters are reserved for referring to a lump's path inside the folder structure, i.e., Textures/Greenflower Zone/GFZROCK or Textures\Greenflower Zone\GFZROCK. Because of this, the slash and backslash character are not allowed in lump names. For sprites, which use the backslash character as a frame designator for frame 27, the plus (+) character is accepted as a substitute for the backslash character.

Note that while it is possible for a PK3 file to contain a WAD file or another PK3 file as a lump, SRB2 will not recognize and load these files. The only exception to this are maps, which may be stored in WAD files inside a PK3 file. However, even in this case, the only data read from such a WAD file is the map data; any other lumps will be ignored.

Specific requirements

Certain types of lumps must be placed in special folders or follow a particular order to be recognized by the game. All these folders must be placed in the root directory of the PK3 file (i.e., not inside another folder). However, they may themselves contain subfolders, and files placed inside these subfolders will also be recognized.

• Flats must be placed inside the Flats/ folder.
• Single-patch textures must be placed inside the Textures/ folder. Multi-patch textures are defined in a text lump whose name must begin with TEXTURES, as with WAD files. This lump may be placed anywhere in the PK3 file. The patches used to form multi-patch textures may be placed anywhere as well, although they are commonly put into a Patches/ folder for convenience.
• Sprites (except those for custom characters) must be placed inside the Sprites/ folder.
• SOC scripts must be placed inside the SOC/ folder. Unlike in WAD files, they can have any name.
• Lua scripts must be placed inside the Lua/ folder, with the exception of init.lua described below, which may be placed in the root folder of the PK3 file. Unlike in WAD files, they can have any name.
• Maps must be placed inside the Maps/ folder, either directly as lumps or packaged inside of WAD files. In both cases, as in WAD files, the lumps of a map must follow a strict order. If placed directly as a WAD file, they must be named by the extended map number of the map inside them (e.g., a WAD containing the lumps for MAP01 must be named MAP01.wad).
• Playable characters may be placed anywhere in the PK3 file. As with maps, the character's sprites must immediately follow the S_SKIN lump.

Other folders that are commonly used for organization but are not required by the game include Graphics/ for miscellaneous graphics, Sounds/ for sounds and Music/ for music.

init.lua

A Lua script with the name init.lua may be placed inside the root directory of a PK3 file. When this script exists, SRB2 will load and execute init.lua and not load any scripts from the Lua/ folder. Instead, the dofile function may be called from init.lua, in order to load scripts in a specific order or under certain conditions.