PK3

PK3 is an archive format first used in Quake III Arena and later adopted by many Doom source ports[1]. For Weissblatt, it poses a more modern, more flexible alternative to WAD.

Building PK3s

PK3 files are actually just ZIP files, so theoretically any compression program can be used to create PK3 packages. There are however some specialty tools to make building Weissblatt (addon) PK3s easier:

In general, we recommend testing small changes first using SLADE before translating the final result into a PK3Make structure.

Automated building using PK3Make

PK3Make is a specialty tool developed for building complex PK3 projects, such as Weissblatt. It can automatically build complex PK3 files with byte-for-byte determinism using a single command:

user@devdir$ pk3make

Writing PK3Makefiles

PK3Make's build behavior is determined by a configuration file called a PK3Makefile. The exact syntax and options for writing PK3Makefiles may vary by version, but in general PK3Make works in three steps:

Source files --[build]--> Engine-friendly build files --[pack]--> Finished PK3 file

During these steps, PK3Make will attempt to find files within the source/build files and mirror the required file tree structure in the following build step.

For the sake of safe backups, you should try to keep your project's assets as well as it's PK3Makefile under version control, for example using Git.

Manual test using SLADE

SLADE is a tried and time-tested tool for building Doom mods. It's a graphical WAD/PK3 editor that allows manually inspecting, building and debugging add-ons.

Note: SLADE's internal Picture converter is not byte-for-byte compatible with that of PK3Make. This is due to unused padding bytes within the Picture format specification being handled differently. Expect different hash values when comparing a PK3 generated by SLADE to one made using PK3Make. This has no effect on engine-behavior regarding Pictures.

Directory structure

Weissblatt's directory structure is based on the ZDoom PK3 structure. The table below explains each directory expected by Weissblatt's engine, it's purpose and it's typically expected file format:

Weissblatt PK3 structure
Directory	Contains	File Format
`Characters/`	Images	S_SKIN (Plain Text) Picture
`Fades/`	Screen Fades	Fade (Flat)
`Flats/`	Floor textures	Flats
`Lua/`	Lua scripts	`.lua` (Plain Text)
`Maps/`	Maps	WAD
`Models/`	3D Models	MD3 PNG (Textures)
`Music/`	Music files	OGG WAV (General) MIDI MOD XM S3M IT
`Patches/`	Patch graphics	Picture
`SOC/`	Configuration	SOC (Plain Text)
`Sounds/`	Sounds	OGG WAV
`Sprites`	Sprite graphics	Picture
`Textures/`	Wall textures	Picture

There are also additional files which are also expected, but typically stored in the PK3 root directory:

Special lumps
File	Type
`ANIMDEFS`	ANIMDEFS
`COLORMAP` `WATERMAP` `CLMxxxx`	COLORMAP
`PLAYPAL` `PALxxxx`	Color palette
`TEXTURES`	TEXTUREDEF
`TRANSxx`	TINTTAB