Filesystem

From Unvanquished
Jump to: navigation, search

Unvanquished stores its resources (maps, sounds, textures, models etc) in packages. To be able to use your own resources in the game you must put them in a package.

Note: The Unvanquished filesystem rules differ from Tremulous and Quake.

Overview

A package is simply a zip-file or a folder containing resources. When a package is loaded its contents are extracted into a virtual filesystem (analogous to a hidden folder). If two packages have the same file, the file that was first extracted always wins out -- files cannot be overwritten once they are in the filesystem (this differs greatly to the traditional quake behavior).

The game only loads packages as it needs them:

  • Main unvanquished package (containing base game resources) is always loaded first.
  • Map packages as they are necessary
  • Any packages that the above say they depend on (eg texture-packs)

Other packages can be forced to load using fs_extrapaks (detailed below).

Every package has a version number. When a package is loaded the latest version is used. For example:

 tex-awesometextures_2016-04-25.pk3dir

In this case an enterprising author made their package version an ISO date (YYYY-MM-DD) to ensure that the latest version always has the 'largest' version number. There are recommended versioning guidelines that go into more detail. To load multiple version of the same package, the one with the 'largest' version number must list the ones with 'smaller' version number as dependencies in DEPS file.

There are two ways packages can be stored: as pk3s or pk3dirs. Packages ending in .pk3dir are plain folders whilst .pk3's are zip-compressed files. Generally it's easier to work with a pk3dir folder and then make a compressed copy only when needed to send over the web.

Locations

Packages can be stored in the 'pkg' folder found in two places: the game installation path (fs_basepath) or the user's own personal path (fs_homepath).

Platform Variant Default Binary Directory (fs_libpath) Default Data Directory (fs_basepath) Default User Directory (fs_homepath) Notes
Windows 32 bit C:\Program Files\Unvanquished My Documents\My Games\Unvanquished The actual directories depends on where the game was installed.
64 bit C:\Program Files (x86)\Unvanquished
Mac Unvanquished/Unvanquished.app/Contents/MacOS Unvanquished/ ~/Library/Application Support/Unvanquished The data directory is the directory containing Unvanquished.app.
Linux Compiled from source Path containing binaries ~/.unvanquished The default user directory is a hidden dotfile.
Installed from repo /usr/lib/unvanquished /usr/share/unvanquished


Filesystem priority

Once a file is in the filesystem, nothing can change it or replace it. If two packages have the same file then the first one to be loaded becomes dominant. The moment a package is loaded, if it contains a DEPS file, its dependencies are loaded recursively in the order of the DEPS file.

Packages are loaded from:

  1. fs_extrapaks if set: each pak in the space-separated values is loaded starting from the left.
  2. main unvanquished package hardcoded to be "unvanquished"
  3. map, as needed.

Dependencies are loaded immediately after their parent package, in the order specified in the DEPS file Please verify!

Whole-game modifications can still use the main unvanquished package by listing it as one of their dependencies. Otherwise fs_extrapaks can just be used.

Packaging Details

Naming

Map package names must start with map- prefix or the engine will not list and not load them. The package name after the map- prefix must be the bsp base name, for example map-station15_1.0.pk3 contains the maps/station15.bsp file. As best practice, it's recommended texture package names start with the tex- prefix. It's recommended packages shipping mixed resources (map models, sounds, gfx…) are named using a res- prefix. More similar prefixes would be defined in the future if needed.

Packages have three parts to their filename:

  • the package basename (eg map-nano)
  • the version (eg 2)
  • the extension (eg .pk3)

In this case our filename would be map-nano_2.pk3

Rules:

  • Underscores must be used to separate the name from the version, but may not be used anywhere else
  • Authors intending to release their work should follow the Packaging Version Guidelines

Sometimes a fourth section (a checksum) is included when auto-downloading maps. This should never be added manually.

Types

  • .pk3dir is for folders
  • .pk3 is for zip-compressed packages

To convert from a pk3dir to a pk3:

  1. Compress the contents of a pk3dir (not the folder itself) into a zip-file
  2. Rename this zip file so that it ends with .pk3

Filesystem layout

Every package is 'extracted' into the same root folder in the filesystem.

It is recommended you follow the traditional folder-structure for your packages. When there is a chance files from another package may have similiar names, you should make a subfolder with your packages name to avoid a clash. Examples of this are below.

Recommended folder structure

Folder Description and notes Example
/about Info and licensing about your package. /about/map-parpax.txt
/textures .crn texture files /textures/parpax_evillair/
/sound .opus sound files /sound/parpax
/scripts .shader, .particle files

/scripts/parpax_custom.shader /scripts/parpax.particle

/minimaps .crn picture, .minimap description file

/minimaps/parpax_upper.crn /minimaps/parpax_lower.crn /minimaps/parpax.minimap

/map .map, .bsp, .navMesh (for bots) /map/parpax.bsp
/meta "Loading screen" picture of a map level (.jpg so it can be use by third party tools), .arena metadata file containing the real name

/meta/parpax/parpax.jpg /meta/parpax/parpax.arena

/gfx Colorgrade (lossless) /gfx/parpax/colorgrading.png
/DEPS (file) Depedencies file. See next section. /DEPS

DEPS file

A DEPS file in the root of a package tells the game what dependencies are required for this package. Dependant packages are loaded after the current package, so if any files clash then the dependencies 'lose out'.

Example contents of a DEPS file (from map-parpax_d03a.pk3):

tex-common
tex-ex
tex-exm
tex-pk01
tex-pk02
tex-space
tex-trak5

Guides

Creating your own package

Find your user's package directory

Dir homepkg.png

Create a pk3dir folder

Dir homepkg newfolder.png

Place inside the files you want to use. Make sure you follow the filesystem organisation guidelines, or kangz will eat you.

Dir inpackage.png

If your package is a map, you can /devmap mapname in the console to load it. Otherwise you may want to force it to be loaded with fs_extrapacks. See Running_the_game#Advanced_options for more details.

$ unvanquished +set fs_extrapaks tutorialexample

Using the latest resources from git

See Using Unvanquished from git