Tutorials/Modifying paks

When working on changes to Unvanquished game paks, it is inconvenient to work directly with the .dpk package file format (see DPK) used in production, since it is a Zip archive. Hence, the Dæmon engine supports the .dpkdir package directory format for working in the native filesystem. This article details a couple of possible workflows for development using a dpkdir.

Method 1: Quick and dirty modifications to an existing zipped package

1. Find the package you want to modify in the pakpath. Let's say it's res-weapons and the file is called res-weapons_0.51.dpk.
2. Extract res-weapons_0.51.dpk into a folder named res-weapons_src.dpkdir. (src is a version string which is arbitrary, but must be "greater" than 0.51). res-weapons_src.dpkdir should be in the same directory as the original dpk.
3. Make your modifications inside the dpkdir directory tree.
4. Start/restart the game. A /devmap (map change) suffices—it is not necessary to restart the entire program.

A disadvantage of this method: it is easy to forget to delete the dpkdir when you are done.

Method 2: Working from the source Git repository

This section describes a workflow for working from source for the unvanquished package.

🚧️ TODO: How well does this work with the other repositories under UnvanquishedAssets?

1. Check out the Git repository. If you have already checked out the Unvanquished repository, then the unvanquished package source exists as a submodule located at Unvanquished/pkg/unvanquished_src.dpkdir. Alternatively, you can check out any dpkdir repository directly.
2. Ensure your repo is up to date:

   cd pkg/unvanquished_src.dpkdir
   git fetch origin && git checkout origin/master

3. Make your modifications in the directory tree of the Git repository.
4. Launch Unvanquished, specifying the parent directory of the repository as a pakpath. Supposing you checked out the Unvanquished repository at ~/code/Unvanquished, the command might be ~/code/Unvanquished/build/daemon -pakpath ~/code/Unvanquished/pkg. Adding the pakpath requires a full restart, but subsequent pak reloads can be done via a map change.

Tips

• Use the which command to verify that files are being loaded from your dpkdir:

/which scripts/blaster.shader
File "scripts/blaster.shader" found in "C:\Users\slipher\Documents\My Games\Unvanquished\pkg/res-weapons_0.51.dpk"

• In your operating system's settings you can associate the .dpk file extension with a zip archive browser such as 7-Zip to enable convenient inspection of paks (DPK packages make use of Zip format).

• If you want to create a new package rather than modify an existing one, set the cvar fs_extrapaks to the package name. This will not work reliably if you need to override a file that exists in another package. 🚧️ TODO: Why? Is it still true?