Pack a DarkPlaces mod: PK3 load order and file overrides

A PK3 is a ZIP archive that DarkPlaces reads as part of a game directory. Packing a mod is easy; knowing which copy of a file wins is the part that causes confusion. This guide gives you a small, repeatable test before you ship real maps, sounds, or textures.

Put game paths at the root of the PK3

Create a mod directory beside your Quake id1 directory, then place PK3 files inside the mod directory. The paths inside each PK3 must start where the game expects them. For example, if DarkPlaces requests docs/marker.txt, the archive must contain exactly that path—not mymod/docs/marker.txt or stage/docs/marker.txt.

The marker is just a test file. For real content, use the path the engine will request, such as maps/yourmap.bsp or sound/mymod/chime.wav. A PK3 is a normal ZIP file with the .pk3 extension; you do not need to convert its contents into another format.

The rule: first matching path wins

DarkPlaces searches an ordered list of directories and packages. In the current official engine, a later -game directory has priority over an earlier one; the final mod directory is the primary directory. Within a single physical game directory, the order is:

1. Loose files in that directory.
2. PK3 archives, with later names taking priority over earlier names.
3. PAK archives, also with later names taking priority within the PAK group.

DarkPlaces scans PAKs and PK3s in separate passes, so a PK3 outranks a PAK in the same directory even if the PAK has a name that sorts later. If the same game directory exists in both the installation and a separate user-data location, the user-data copy is searched first. That can explain an override that appears to come from nowhere.

Build two tiny PK3s and check the result

In PowerShell, run these commands from the directory that contains id1. They create two ZIP archives with the same internal path, then rename them to PK3. Compress-Archive receives the contents of stage, so the archive root starts at docs.

Open either PK3 with a ZIP tool and confirm it contains docs/marker.txt at the root. Launch DarkPlaces with -game mymod. In the engine console, run:

It should report z_patch.pk3. Now create a loose copy at mymod/docs/marker.txt and run which docs/marker.txt again: the loose file should win. Move that loose copy out of the mod directory, and the answer should return to z_patch.pk3. If you add a PK3 while the engine is already running, run fs_rescan or restart before checking it.

What usually goes wrong

• Extra parent folder inside the ZIP: stage/docs/marker.txt and mymod/docs/marker.txt are not the requested path docs/marker.txt.
• Wrong game directory: make sure mymod is beside id1 under the active base directory, and that the launch command actually selects it.
• An unnoticed loose file: a loose copy in the selected game directory can mask every PK3 version below it.
• Assuming archive extensions share one alphabetic queue: in a single directory, PK3s are above PAKs regardless of their names.
• Assuming an empty file always deletes an older asset: DarkPlaces has fs_empty_files_in_pack_mark_deletions for this, but its default is 0. Leave this advanced behavior out of a normal patch workflow unless you deliberately enable and test it.

The search order answers which source supplies an exact virtual filename. An image or model loader may also try several different filenames or extensions in its own order. If a visual asset is still unexpected, inspect the precise path the loader requests rather than relying only on the archive name.

Sources and scope

The priority and console commands above were checked against the current official DarkPlaces filesystem source and DarkPlaces README. The archived Blood Wiki virtual file system page supplied the original topic; its automatic empty-file deletion claim does not match the current default. Other engines and older forks may differ, so check their own file search rules.