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.
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:
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.
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||Installed with updater||Unvanquished/Unvanquished.app/Contents/MacOS||Unvanquished/||~/Library/Application Support/Unvanquished||The data directory is the directory containing Unvanquished.app.|
|Linux||Installed with updater||~/.local/share/unvanquished/base||~/.local/share/unvanquished||The default user directory is an XDG Base Directory.|
|Installed from distribution repository||/usr/lib/unvanquished||/usr/share/unvanquished|
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:
- fs_extrapaks if set: each pak in the space-separated values is loaded starting from the left.
- main unvanquished package hardcoded to be "unvanquished"
- 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.
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
- 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.
- .pk3dir is for folders
- .pk3 is for zip-compressed packages
To convert from a pk3dir to a pk3:
- Compress the contents of a pk3dir (not the folder itself) into a zip-file
- Rename this zip file so that it ends with .pk3
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||
|/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||
|/DEPS (file)||Depedencies file. See next section.||/DEPS|
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
Creating your own package
Find your user's package directory
Create a pk3dir folder
Place inside the files you want to use. Make sure you follow the filesystem organisation guidelines, or kangz will eat you.
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