Understanding the file system (PK3, etc.)

[Soh Raun]

This FAQ aims to clarify the functioning of the Jedi Academy file system, which is based on the id Tech 3 game engine.

It is meant to be useful to any player, and particularly to modders who need to understand how it works with greater details.

Questions/answers are ordered from the simplest to the most advanced, with some little-known tips at the end.


What is a PK3 file?

• A PK3 file is just a ZIP file renamed to .pk3, as such you can create/open/edit it with any general-purpose archive tool such as 7-zip (no need for specific tools like PakScape).

Where should I put a PK3 file I downloaded?

• Generally, you will have 2 directories in your GameData directory: base, and the mod (here rpmod).

• JEDI also makes use of a 3rd directory, JEDI, which is enabled by the startup argument "+set fs_basegame JEDI" (automatically set by the RPMod Launcher).

• For the best results, the general rules are the following:
  • rpmod: original mod files and specific customizations (nothing else!)
  • JEDI: any official pack, map or skin from the JEDI community
  • base: anything you download that was not made by the JEDI community (other maps, skin packs, etc.)

How should I name my PK3 file?

• If you are making your own standalone PK3 file (that contains everything it needs to work), you are free to name it as you want. Please keep the same name every time you update it so that users can simply overwrite it.

• If you wish to "patch" files that already exist in a different PK3, you should give it a name that comes after the original PK3 in the alphabetical order. Please avoid adding random "zzz" at the beginning, which only make things a mess.
  
  Example:

  Code: Select all

  mymap.pk3        <- original file
  mymap_patch.pk3  <- modifications only

• Most importantly, make sure to place it in the same directory or a directory of higher priority (see "How are PK3 files loaded?").

• This technique can also be used to customize RPMod assets (e.g. crosshair, HUD, etc.) - be careful not to break anything though!

Why are some PK3 conflicting?

• Conflicts may occur when different PK3 contain the same files at the same path. When this occurs, the PK3 with the highest priority wins (see "How are PK3 files loaded?").

• This typically happens in maps when shader files are overridden and textures become black with white lines.

• When this occurs, remove all non-essential PK3 files and re-add those you need one by one (or only a few at once), starting with the file that displayed the problem.

• If you still want to keep 2 conflicting PK3 in the same directory, you may try renaming one of them to change the load order (see below).

How are PK3 files loaded?

• The game will consider all PK3 files as a single "virtual file system", as if their contents were merged together (imagine extracting them all under the same directory).

• To do so, it will load them with the following priority order (highest to lowest):
  • rpmod ("game" directory), reverse alphabetical order (Z->A)
  • JEDI ("basegame" directory), reverse alphabetical order (Z->A)
  • base ("base" directory), reverse alphabetical order (Z->A)
  Example:

  Code: Select all

  rpmod/zzz.pk3    <- highest priority
  rpmod/aaa.pk3
  JEDI/zzz.pk3
  JEDI/aaa.pk3
  base/zzz.pk3
  base/aaa.pk3     <- lowest priority

• Note that when 2 PK3 files have the same name, one does NOT replace the other: only the content matters.

How are directory files loaded (outside a PK3)?

• By default, any file found in a directory will be loaded after the PK3 files, as such they will have lower priority. The directory ordering rules are still preserved.
  
  Example:

  Code: Select all

  rpmod/zzz.pk3    <- highest priority
  rpmod/aaa.pk3
  rpmod/custom.cfg <- high priority
  JEDI/zzz.pk3
  JEDI/aaa.pk3
  JEDI/custom.cfg  <- ignored
  base/zzz.pk3
  base/aaa.pk3     <- lowest priority

• However, it is possible to force the loading of directory files before PK3 files by using the "+set fs_dirbeforepak 1" startup argument. This can be particularly useful while developing a mod, if you don't want to update the PK3 for every modification.
  
  Example:

  Code: Select all

  rpmod/custom.cfg <- highest priority
  rpmod/zzz.pk3    <- high priority
  rpmod/aaa.pk3
  JEDI/custom.cfg  <- ignored
  JEDI/zzz.pk3
  JEDI/aaa.pk3
  base/zzz.pk3
  base/aaa.pk3     <- lowest priority

How can I see the actual load order?

• In game, you can use the "/path" command to see the actual load order at any time.

• On a server, you may run the same command over Rcon.

• It is also printed to the console during startup.

How can I load files from a different GameData directory?

• The main GameData directory can be changed by adding the "+set fs_basepath C:\Path\To\GameData" startup argument.

• A more advanced possibility is to use additional GameData directories, with the following priority order (highest to lowest):
  • homepath directory: read-write, high-priority layer (default: same as basepath on Windows, "~/.ja" on Linux)
  • basepath directory: read-only, intermediate-priority layer (default: usual GameData directory)
  • cdpath directory: read-only, low-priority layer (default: empty)

• This can be useful when running multiple instances without having to copy the entire GameData directory.

• To do so, you may add the "+set fs_homepath C:\Path\To\Extra\GameData" startup argument. Note that the aforementioned priority rules still apply.
  
  Example:

  Code: Select all

  homepath/rpmod/zzz.pk3  <- highest priority
  homepath/rpmod/aaa.pk3
  basepath/rpmod/zzz.pk3
  basepath/rpmod/aaa.pk3
  cdpath/rpmod/zzz.pk3
  cdpath/rpmod/aaa.pk3
  homepath/JEDI/zzz.pk3
  homepath/JEDI/aaa.pk3
  basepath/JEDI/zzz.pk3
  basepath/JEDI/aaa.pk3
  cdpath/JEDI/zzz.pk3
  cdpath/JEDI/aaa.pk3
  homepath/base/zzz.pk3
  homepath/base/aaa.pk3
  basepath/base/zzz.pk3
  basepath/base/aaa.pk3
  cdpath/base/zzz.pk3
  cdpath/base/aaa.pk3     <- lowest priority

• Remember to copy your jampconfig.cfg or openjk.cfg file from its original location to the new homepath to keep your config, binds, etc.

Where can I find more details?

• Please refer to the game source:
  • OpenJK: https://github.com/JACoders/OpenJK/blob ... es.cpp#L56
  • Quake III: https://github.com/id-Software/Quake-II ... iles.c#L39