Content locationsMay 24, 2022
Sauerbraten uses overlaying to enable loading content from different locations. I say locations because not only can you tell Sauer to use certain directories, it can also use .zip files directly!
There are four types of content locations:
- zip archives (added using the
- the user directory (only one, defined using
- package directories (zero or more, added using
- the installation root directory
In sauer, pretty much everything except the game binary and libraries qualifies as “content”: maps, textures, models, scripts, demos, screenshots, configuration files, cubescript files, shaders, everything. Yes, you could have your config.cfg loaded from a .zip file! (You really shouldn’t though: it would be impossible to change any settings…)
A content file is loaded by first looking for it inside all zip archives (in the order they were added), then in the user directory, then inside all package directories (in the order they were added), and lastly in the installation directory.
Sauerbraten only ever writes files to your user directory. (Unless there is no user directory configured, then it writes to the installation directory. This should only be the case if you explicitly changed the launch script, see below.)
That way, you should in theory never need to reinstall, provided you never touch the original content files in the installation directory. Deleting the user directory would reset everything to the state of a fresh installation.
This means you can not override the contents of a .zip file by placing an updated version of a file in your user directory! Zip archives are always preferred when loading content.
The easiest way to add content to your Sauerbraten installation is to add it directly as .zip file. For this to work, the contents of the .zip has to be structured the same way as the installation directory, i.e. a map .ogz needs to be in packages/base/ inside the archive. Most content you find online is already correctly packaged. Just put
addzip C:\Users\Tom\Downloads\my-awesome-shiny-inky-models.zip into your autoexec.cfg and restart Sauer.
The path to the user directory is set by the OS-specific launch script, for example sauerbraten.bat on Windows, by passing a
-q<path> command-line argument to the game binary. By default, sauerbraten.bat uses
$HOME is (unintuitively) not substituted with the path to your user folder, for example
C:\Users\Tom, but with the path to your “My Documents” folder, for example
C:\Users\Tom\My Documents, so the actual location becomes
C:\Users\Tom\My Documents\My Games\Sauerbraten.
On Linux, the launch script is called sauerbraten_unix and it uses
$HOME/.sauerbraten as user directory. On macOS, the script is at Sauerbraten.app/Contents/MacOS/sauerbraten, and uses
$HOME/Library/Application Support/Sauerbraten. (On these systems,
$HOME is substituted with what you think it is, your home directory.)
By letting the launch script define the user content directory, you are very flexible with your setup. For example, you can have several Sauer installations that each use a different user directory by opening the sauerbraten.bat file and changing the path. (This is very much advised for parallel installations of different editions of Sauer, since Sauer overwrites config.cfg every time you quit and configs are not compatible between editions.)
To load content from additional directories, you can pass
-k<path> to the game binary. Content is only loaded from, never written to a package directory. If the path you specify contains
/packages/bla, only files starting with that prefix are tried to be loaded from that package directory.