Page 1 of 1

Understanding the file system (PK3, etc.)

Posted: Thu Jun 11, 2020 4:56 pm
by 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?