Installing Call of Duty server mods: pk3, iwd and fs_game

Call of Duty mods are zip archives that overlay the stock game files. There is no installer and no manifest — the rules are entirely about filename and load order, which is why a mod that is "installed" can sit there doing nothing with no error message anywhere.

Archive extension per game

Both are plain zip files. unzip -l mymod.pk3 works on either. But the engine only scans its own extension: a correctly built .iwd in a CoD1 gamedir is ignored completely, and so is a .pk3 in a CoD2 gamedir. No warning is printed.

This is the first thing to check when a mod does nothing.

Load order: alphabetical, last wins

The engine scans the gamedir, sorts the archives by filename, and loads them in order. For any file path present in more than one archive, the archive that sorts last wins.

Stock paks are named pak0 … pakb on CoD1 and iw_00 upwards on CoD2+. So a mod named mymod.pk3 sorts before pak0.pk3 and loses every conflict.

The convention is to prefix mods so they sort last:

zz_mymod.pk3

Call of Duty 1 patch 1.1 exception: the 1.1 server does not load a zz_-prefixed pak at all. The identical bytes named zzz_ or zzzz_ load fine. This is verified behaviour, not folklore, and it costs people entire evenings. On 1.1, use zzz_ or zzzz_.

Two ways to install

1. Drop into the gamedir

/opt/cod2/main/zz_mymod.iwd

Simple, and the mod applies to every gametype. It also means every connecting client is offered the pak for download, and unloading the mod means moving the file and restarting.

2. A mod directory via fs_game

/opt/cod2/mods/zpam336/z_svr_zpam336.iwd

set fs_game "mods/zpam336"

With fs_game set, the engine mounts that directory on top of main/. This is how the serious mods ship, because it keeps main/ clean and lets you switch mods by changing one cvar.

fs_game must be set before the config is executed, so put it on the command line:

./cod2_lnxded +set fs_game mods/zpam336 +set dedicated 2 +exec server.cfg +map mp_toujane

Setting fs_game inside server.cfg is too late for some engine generations and produces a server that half-loads the mod.

sv_pure

Set sv_pure 0 when you load a mod pak, unless you have specifically tested the pure checksum path with real clients. sv_pure 1 makes the server audit the checksums of what each client has loaded and kick on mismatch, which is easy to get wrong in ways that only show up as clients being unable to join.

On Call of Duty 1 patch 1.1, sv_pure 1 is effectively unusable with any modded client because of a client-side checksum bug. The full explanation is in the fast download guide.

Getting the mod to clients

A mod that only changes server-side script needs nothing on the client. A mod that adds maps, models, sounds or menus does.

set sv_allowDownload 1
set sv_wwwDownload 1                                // CoD2 and later
set sv_wwwBaseURL "http://files.example.com/cod2"

Without HTTP, the engine's UDP download path runs at roughly 5–10 KB/s and a 20 MB mod is not a realistic join. See fast download.

Files you should not ship to clients

Vanilla Call of Duty has no way to mark a pak server-only — any referenced pak is offered for download. CodExtended adds one on CoD1: a pak whose basename contains srv, svr or server is excluded from the download list.

The file this matters most for is playeranim.script. It parses into a parse-order-indexed animation table and the server networks indices into it. A client that downloads a re-ordered or trimmed table from your server will then crash with an "animation error" when it joins a stock server. Never put a non-stock playeranim.script in a downloadable pak.

Inspecting a mod before you trust it

A pak is a zip, so you can read it:

unzip -l zz_mymod.pk3                          # what is inside
unzip -p zz_mymod.pk3 maps/mp/gametypes/dm.gsc # read a script
unzip -l zz_mymod.pk3 | grep playeranim        # check for the dangerous file

Worth doing for anything you downloaded from a forum in 2009.

Verifying the mod actually loaded

Start the server and read the console. It prints every archive it loads, and a total file count:

30172 files in pk3 files

If your pak is not in that list, the extension or the filename sort order is wrong. If it is in the list but the mod does nothing, the mod's scripts are not being reached — usually a fs_game or gametype problem rather than a packaging one.

Mod directory

Common server mods for the classic titles: