These are the scripts (and associated optional sounds) used to do the heavy lifting for the features described in the top-level readme.
Once these are installed and working you can go over to the desktop_integration directory and follow the instructions in the readme there to hook up the desired right-click and double-click behaviors.
Five steps are needed to get these scripts working. Those steps are numbered and called out below, with some other context and discussion around them.
1. Install utilities
Technically each of these utilities used by the "quakelaunch" script are optional, but at least the first two of these are involved in implementing fundamental features of the script and are therefore highly recommended.
If you want to use the auto-install feature -- which unlocks a huge part of the convenience of using these scripts -- you will need to have installed the utility "aunpack", which is part of atool.
In my case I installed that utility and its dependencies with:
sudo apt-get install atool
(You may then also want/need to install some of the various tools mentioned at the bottom of the atool webpage. For example, I already had tar, zip, gzip, and p7zip on my system... but I needed to install rar as well in order to handle .rar archives.)
Next, if you want the script to generate notifications when errors happen, the "notify-send" utility needs to be present. In some cases your system may already include this utility by default; if not, you can find a package to install that will include it. For example on Pop!_OS 22.04 LTS I needed to do this:
sudo apt-get install libnotify-bin
That package should also be appropriate for other Ubuntu-like systems.
Finally, you may want to install a utility for playing a sound when a notification is generated. By default the "paplay" utility will be used. However, you can change that in your configuration file (as described below) if you don't have or wish to install "paplay", or if you just want to use some other sound player.
2. Install Python module "expak" (optional)
The main script can also optionally use my Python module expak to look inside pak files and make better decisions about things like what map to launch and whether a gamedir is "standalone" (has its own progs.dat). To use this module, you will need Python 2 or Python 3 installed; the script will use whatever executable has the name "python". (In the case of Pop!_OS 22.04 LTS, which only has "python3", I needed to install the "python-is-python3" package in order to have a "python" executable available.)
The expak module will need to be installed for that version of Python using the Python package manager "pip", e.g.:
sudo pip install expak
If you can't or don't want to install this module globally, there are various ways to tackle that, but I think that -- and any other instruction about installing or using "pip" -- is outside the scope of this doc.
3. Put "quakelaunch" somewhere in your PATH
The "quakelaunch" script from this directory must be copied to some directory that is in your PATH for executables. Make sure that the "quakelaunch" script in that location is marked as executable.
4. Put the error sounds somewhere safe (optional)
The "sounds" directory contains a selection of error beeps. If you want to use these sounds, make sure they are placed in a location where they will not get deleted. (Leaving them here among the files you downloaded for this repo is fine, if you're going to keep them intact.) Or find some other sounds you want to use.
5. Edit "quakelaunch.conf"
If this is your first time using the "quakelaunch" script on this system, at this point you should run it once. Just invoke "quakelaunch" from a shell prompt. "quakelaunch" will exit with a message about needing to edit your "quakelaunch.conf". Normally, "quakelaunch.conf" will be in the location "~/.config/quakelaunch/quakelaunch.conf". In any case, its location will be printed out as part of that message.
Open that "quakelaunch.conf" file in a text editor, read through it, and modify it as necessary to reflect your own Quake setup. This includes customizing the paths that locate things such as Quake and the above error sounds, and other options to customize the behavior of the scripts. You will need to initially modify at least some of the settings in this file before the scripts will work. This file is commented thoroughly enough that it should be pretty self-explanatory, but the "Usage notes" section below covers some interesting bits.
If you ever want to find out what the default value is for some setting, you can reference the "quakelaunch-defaults.conf" file that lives in the same directory as "quakelaunch.conf". (Don't modify that defaults file.)
The scripts are meant to be used through desktop integration, but you can also run them manually. Each script can take one argument, which should be an absolute path to some file or directory.
"quakelaunch" with zero arguments will just launch Quake.
"quakelaunch" with one argument represents what will happen when you use the desktop integration to "open a file" for "Quake". The argument to "quakelaunch" can be a zip archive, some other kind of archive, a Quake gamedir, a ".quake" shortcut, or a bsp file inside the maps directory of a gamedir. This will trigger the various features/behaviors described in the top-level readme.
"quakelaunch --cleanup" with one additional argument represents what will happen when you use the desktop integration to "open a file" for "Quake mod cleanup". That final argument can be a Quake gamedir or a ".quake" shortcut. It will delete a gamedir and its associated shortcut(s).
The sections below cover some of the interesting parts of these behaviors that can affect how you want to set up the "quakelaunch.conf" config file, and how you will use the features once they are installed.
Basically a gamedir is a directory whose name can be used with the "-game" argument when launching Quake, to make Quake see the files in that directory. In the original Quake and in many new Quake engines, this is simply a directory that exists within the "basedir" directory, i.e. next to "id1".
In some Quake engines however, the directory for the gamedir may instead be located within a "userdata" directory, somewhere under your own home directory. Or there may be a directory of that name both in the basedir and also in the userdata, with Quake loading files from both locations. If your Quake engine makes use of a userdata directory then you'll need to set a couple of options in quakelaunch.conf accordingly. More about that in the userdata readme.
When the text below talks about a "gamedir" it is referring to the directory under "basedir" as well as the userdata subdirectory of the same name (if that exists). If there's any confusion about what that might mean in a particular context then the userdata readme will hopefully clear that up. To be clear though, if your Quake engine doesn't do the userdata thing (e.g. if you're using an official Quakespasm build) then you can ignore all that userdata stuff.
A shortcut is a file with the ".quake" extension. They're nice as a way to launch a Quake mod or maps with a double-click (once you've done the desktop integration). A directory full of shortcuts is basically your menu of Quake stuff you can play.
You can define a value for shortcuts_dir in the config file if you want the launcher to automatically create a shortcut file in a specified directory whenever it creates a new gamedir. You can also create shortcut files yourself by whatever means you want.
Generally you won't need to know much about how shortcuts work, but here's some details that might come in handy at some point:
- If a shortcut file contains the path to a gamedir, opening the shortcut (with "quakelaunch") will launch that gamedir. Shortcuts created by the launcher are like this.
- If a shortcut file is empty (doesn't contain any non-whitespace), then opening it will just launch the gamedir that has the same basename as the shortcut.
- If you use "quakelaunch --cleanup" on a shortcut, it will also delete the gamedir that the shortcut points to.
- If you use "quakelaunch --cleanup" on a gamedir, it will also delete any shortcuts in the current shortcuts_dir that point to that gamedir.
Note about "empty" shortcuts: you will want to make sure that they do contain some whitespace, even just a single space or carriage return character. This is because some Linux configurations will not correctly recognize the filetype of zero-length files, which undermines the desired shortcut behavior. So for example if you wanted to manually create an "empty"-style shortcut for the "hwjam2" gamedir, you could do:
echo > hwjam2.quake
to create a shortcut file that has a carriage return in it.
If a launched gamedir contains any savegames, the most recent one will be loaded. (Unless you had launched it by opening a specific bsp file.)
If your Quake engine is using a userdata directory, only savegames in userdata subdirectories can be loaded, so only those savegames will be considered here.
If you launch a gamedir that contains no savegames, "quakelaunch" will try to choose a good initial map to load. The rules it goes by are:
- If there are pak files in the gamedir, and expak is not installed, then we can't figure out what maps there might be. Just activate the gamedir and don't load any map.
- Otherwise build a list of maps in any "loose" bsp files in the gamedir and in any of its paks.
- If there's only one map, load that.
- If there's a "start" map or some map that ends with "start", load that.
- Otherwise just activate the gamedir and don't load any map.
This is only a small convenience, so we don't want to make a mistake and accidentally skip the actual first map... I intentionally didn't get into more complicated map-picking rules that would be more likely to occasionally misfire.
If the script can't figure out which map to load, just use the console as usual to list and load maps.
If a gamedir does not come with its own progs.dat (game logic), then it might depend on assets that need to be loaded from some other gamedir (a "base" gamedir). "quakelaunch" will do its best to figure out whether such a dependency exists.
For example, if the files in the archive were originally organized so that Quake-specific folders like "maps" were inside a folder named "quoth", "hipnotic", or "rogue", then quakelaunch will assume that this release has a dependency on Quoth, missionpack 1, or missionpack 2 respectively.
If the folder organization didn't reveal any dependency -- or if this is a first-time launch of a gamedir that was not unpacked and installed by "quakelaunch" itself -- then "quakelaunch" will also check to see if the gamedir contains a document that mentions quoth, hipnotic, or rogue.
An attempt to launch a gamedir with such a dependency will stop with an error if the necessary base gamedir is not present.
"quakelaunch" will similarly look for dependencies on Arcane Dimensions, Copper, and Alkaline. As with the Quoth/missionpacks stuff described above, if the "maps" etc. folders were originally contained in a folder named "ad", "copper", or "alkaline" then that will signal a dependency.
If necessary "quakelaunch" will also look in docs for mentions of Copper or Alkaline. For Arcane Dimensions, instead of examining the docs it will look to see if there is a bsp filename that starts with the "ad_" prefix... that turns out to be an almost completely reliable indicator (so far) of a dependency on AD.
Unlike the situation with Quoth and missionpack dependencies however, not all Quake engines can handle launching non-standalone AD/Copper/Alkaline-dependent content that is installed in its own separate gamedir. If you have a Quake engine that can do it, you can set the relevant options in your "quakelaunch.conf" file. I do know that recent releases of FTE, Quakespasm-Spiked, vkQuake, Ironwail, and DarkPlaces can do it, and I've included examples in the conf file that work with those engines.
(BTW if you are making your own build of Quakespasm, multigame-support.md describes how you can add this capability to Quakespasm.)
If you try to launch a non-standalone gamedir that depends on AD/Copper/Alkaline, and you are not set up in quakelaunch.conf to handle AD/Copper/Alkaline as a base gamedir, you'll get an error message and the gamedir will not be launched. You can override this behavior if you want, by editing the per-gamedir config (see below).
A "quakelaunch.conf" file inside a gamedir folder can be used to set behaviors specific to that gamedir. If such a file does not exist when a gamedir is launched, then the script will create it.
Note: If your Quake engine makes use of a "userdata" directory, this gamedir-specific quakelaunch.conf file will end up in the relevant subdirectory there. See userdata.md for details.
You can edit this file as you wish. Many of the options in the main "quakelaunch.conf" file can affect how a gamedir is launched, and if you specify a value for any of those options in this gamedir-specific config then that value will override the value from the main config.
This file will also contain a "basegame_args" option that specifies how any base gamedir dependecies (described above) affect the launch arguments for Quake. You can edit this value if it looks like the script has made the wrong conclusions. For example, if you have a gamedir that requires Quoth but doesn't mention that fact in any of its docs, then the script will initially set the "basegame_args" value to emptystring (nothing) since it couldn't detect the dependency. In that case you would want to manually change the "basegame_args" value to "-quoth".
You can also set an "extra_quake_args" option in this file if you want to specify additional command-line arguments to use with this gamedir. For example, if a gamedir is a "bots" mod that requires being launched with listen-server settings, then in its gamedir-specific config you can insert a line that sets the "extra_quake_args" option to a value of "-listen 16".
There are other options you might wish to set in this file. If you use the "readme and config preview" feature described below, you'll get to see more commentary about those options.
If you set the value of "preview_readme_and_config" to true, this activates a feature that triggers on the first launch of any gamedir. Before Quake starts, you will get the chance to view any readme files or other documents in the gamedir. You will also get a chance to view and edit the gamedir-specific "quakelaunch.conf" file. Quake will not start until you have closed the editor window for that config file.
So for example you could look at the readme to note any base gamedir dependencies. Then you could check the "basegame_args" value in the config to see if it is correct, and fix it if not.
(Subsequent runs of the gamedir will skip the viewing/editing stuff and go straight to launching Quake.)
If "preview_readme_and_config" is true, you must also provide a value for "config_editor". This value describes how to launch an editor program for the gamedir-specific "quakelaunch.conf" file. The comments in the main "quakelaunch.conf" file describe the requirements for how you set this up. In the provided example I've chosen to use the "gedit" editor, which is a nice GUI text editor available on many Linux variants. If you don't have gedit, you could install it ("sudo apt install gedit")... or use some other editor as long as you can meet the requirements.
You can also provide values for txt_viewer, html_viewer, doc_viewer, pdf_viewer, and md_viewer to define how those document types can be viewed. In my example I use gedit again for .txt files, and xdg-open for all other file types to just use whatever the system default is.
Some packs of maps don't include a custom start map; or maybe they do, but it's just a giant collection of slipgates and it's annoying to keep track of where you've already been. In these cases I usually just want to play through the maps in some order, so I would use the Quake console to get a list of maps and manually load the next map.
This script provides an optional helper to make that process a bit nicer. If you define a value for jam_keybind in "quakelaunch.conf", that key will be bound to an alias that will load the "next map" in a list of maps from the gamedir. So when you first load up the map pack, press that key to be taken to the first non-startmap map in the pack. Or if you're just in the Quake console rather than in a startmap, you can enter the "jam" command in the console.
When you're done with that first map (either before or after you go through its exit portal), press the key again to go to the next map. Etc. If you've played through the whole list then pressing the key will just generate a beep and the message "All Done" in the upper-left-hand corner of the screen.
If you make a savegame and then come back later to pick up where you left off, using the autoload-latest-savegame feature, the mapjam helper will be set up correctly so that it starts at your current spot in the map list. The same is true if you use the launch-from-bsp feature to directly load a specific map.
Note that the config-scripting for this behavior doesn't have any magic way to know what map you are currently on; it just starts on a particular map and then works through a list as you press the key repeatedly. So if you manually load a different map or savegame after launching Quake you will not change its idea of what the "next map" is.
If you want to test whether you've installed the expak module correctly, cd into your id1 directory and execute the following command. (Long line here, be sure to copy it all.)
python -c "import expak;print(' '.join([r for r in expak.resource_names(['pak0.pak','pak1.pak']) if r.lower().startswith('maps/')]))"
You should see this output:
maps/e4m8.bsp maps/e4m1.bsp maps/e3m2.bsp maps/dm1.bsp maps/b_rock1.bsp maps/b_shell1.bsp maps/b_bh25.bsp maps/e1m7.bsp maps/e4m7.bsp maps/e3m5.bsp maps/e4m5.bsp maps/e2m3.bsp maps/dm3.bsp maps/end.bsp maps/start.bsp maps/e1m1.bsp maps/dm4.bsp maps/e2m4.bsp maps/dm6.bsp maps/e2m5.bsp maps/b_exbox2.bsp maps/e1m2.bsp maps/e2m6.bsp maps/b_bh10.bsp maps/b_batt1.bsp maps/dm5.bsp maps/e4m6.bsp maps/b_rock0.bsp maps/b_bh100.bsp maps/e1m6.bsp maps/e3m4.bsp maps/e4m3.bsp maps/e1m5.bsp maps/e3m6.bsp maps/e2m1.bsp maps/e4m4.bsp maps/e3m7.bsp maps/e4m2.bsp maps/b_batt0.bsp maps/e2m7.bsp maps/e3m1.bsp maps/e1m3.bsp maps/b_shell0.bsp maps/dm2.bsp maps/e3m3.bsp maps/e1m4.bsp maps/b_nail1.bsp maps/b_explob.bsp maps/e2m2.bsp maps/e1m8.bsp maps/b_nail0.bsp
There's no need to check that that is the exact list you get, the idea is just that you should be shown a long list of bsp files rather than some Python error.
Next, you can test the scripts from the shell command line.
Give the "quakelaunch" script one argument that is an absolute path to a bsp file within an existing Quake gamedir. It should launch Quake with that gamedir activated and that bsp file loaded.
Now try running it with an argument that is a path to an existing gamedir. It should launch Quake with that gamedir activated, and possibly choosing a map to load as described above.
Finally, try running it with an argument that is a path to a zipfile containing a downloaded Quake mod or maps. It should install and then launch it.
If these tests work you're probably good to go, but you can certainly also test "quakelaunch" with other arguments like a ".quake" shortcut file, or archives of other types. You can also try out "quakelaunch --cleanup" with a path to a shortcut or gamedir to check that it does the necessary deletions.
If you ever want to get rid of these scripts you can just delete the files (scripts, conf, and sounds) from wherever you put them.
If you installed the prereqs as above, and you need to uninstall them, you can do so with
sudo apt-get remove atool
sudo pip uninstall expak