diff --git a/docsource/basic/installation.rst b/docsource/basic/installation.rst index bdb6f88..c24e94f 100644 --- a/docsource/basic/installation.rst +++ b/docsource/basic/installation.rst @@ -10,7 +10,7 @@ Another option however is to take the folders and files from inside this "Quake" If the existing Quake installation already contains an older version of Quakestarter, please see the the :doc:`Updating Quakestarter<../other_stuff/upgrading_quakestarter>` chapter (under Other Topics). -If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, then you might want to consider using the "noengine" version of this bundle if you aren't already doing that. Otherwise the engine files bundled in this package can overwrite and perhaps conflict with existing files in your Quake directory. One thing to note is that the "engines_manifest.txt" file lists all of the vkQuake and Ironwail files in this package, which is helpful if you need to discard them. (If you don't have "engines_manifest.txt", then you are using the "noengine" bundle already.) +If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, then you might want to consider using the "noengine" version of this bundle if you aren't already doing that. Otherwise the engine files bundled in this package can overwrite and perhaps conflict with existing files in your Quake directory. In this particular situation you definitely want to read the next section below about Quake engines! Quake engine diff --git a/docsource/basic/running.rst b/docsource/basic/running.rst index fdf2735..b07bdb5 100644 --- a/docsource/basic/running.rst +++ b/docsource/basic/running.rst @@ -6,7 +6,11 @@ Launching with Quakestarter Quakestarter is meant to help you get your Quake installation set up and then to manage and play various addons. -Other than the "Basic setup" section of the main menu (whose options were already described in :doc:`Installation` and :doc:`Configuration`), the rest of the choices in the main Quakestarter menu will take you to pages where you can choose to install and play these addons. There are two other main sections: +Other than the "Basic setup" section of the main menu (whose options were already described in :doc:`Installation` and :doc:`Configuration`), the rest of the choices in the main Quakestarter menu will take you to pages where you can choose to install and play these addons. There are three other main sections: + + * In "The Latest Greatest" list, you'll see a subjective selection of the buzz-iest releases of the past six months. (Depending on the rating that a release has accumulated so far, it may also appear in one of the other sections below.) + +|br| * Each choice in "Additional episodes/hubs" leads to a list of good-sized map collections that include a starting map, which either leads you into a linear sequence of other maps or else acts as a hub from which you can explore the other maps of the addon in any order. diff --git a/docsource/maps_and_mods/explore_more.rst b/docsource/maps_and_mods/explore_more.rst index 27501ca..6026f96 100644 --- a/docsource/maps_and_mods/explore_more.rst +++ b/docsource/maps_and_mods/explore_more.rst @@ -10,7 +10,7 @@ Quake Injector will *not* automatically apply the patches/fixes that Quakestarte Note that Quake Injector likes to keep around the zipfiles that it downloads, even if you uninstall a mod, until you explicitly delete the zipfile. If you're going to be using both Quakestarter and Quake Injector then you may want to configure them to share the same downloads folder. -The downloads location for Quake Injector is configured in the "Engine Configuration" dialog. The downloads location for Quakestarter is described in the :doc:`Advanced Configuration<../other_stuff/advanced_quakestarter_cfg>` chapter (under Other Topics). You can change one or the other of these locations so that they both point to the same folder. If you do this, you'll probably also want to configure Quakestarter to leave zipfiles in that folder and *not* delete them after they are installed, to match the behavior of Quake Injector. +The downloads location for Quake Injector is configured in its "Engine Configuration" dialog. The downloads location for Quakestarter is described in the :doc:`Advanced Configuration<../other_stuff/advanced_quakestarter_cfg>` chapter (under Other Topics). You can change one or the other of these locations so that they both point to the same folder. If you do this, you'll probably also want to configure Quakestarter to leave zipfiles in that folder and *not* delete them after they are installed, to match the behavior of Quake Injector. One thing to look out for though is that Quakestarter doesn't work exactly the same as Quake Injector when it comes to choosing the name for a mod folder. Quakestarter will always use the name of the zipfile to determine the name of the folder, while Quake Injector may have other ideas. So to avoid confusion and wasted disk space on duplicate stuff, it's best to eventually settle on using only one of these install methods. diff --git a/docsource/other_stuff/advanced_quakestarter_cfg.rst b/docsource/other_stuff/advanced_quakestarter_cfg.rst index 577792b..22dd27e 100644 --- a/docsource/other_stuff/advanced_quakestarter_cfg.rst +++ b/docsource/other_stuff/advanced_quakestarter_cfg.rst @@ -18,41 +18,83 @@ Let's say you would rather not do that, so that you can quickly re-install previ You should always handle any preferences like this through your own "_quakestarter_cfg.cmd" file, *not* by modifying the "_quakestarter_cfg_defaults.cmd" file. That way, your preferences won't get overwritten when you take in the files for some future release of Quakestarter. -The "_quakestarter_cfg_defaults.cmd" file describes these settings in detail, so most of them don't need extra description here. We'll cover a couple of them below though. +The "_quakestarter_cfg_defaults.cmd" file describes these settings in detail, so most of them don't need extra description here. -Engine choice -------------- +Download behavior +----------------- -If you want Quakestarter to launch a particular Quake engine of your choice -- other than the options of vkQuake and Ironwail which are usually bundled with Quakestarter -- then the files for that Quake engine need to be placed in the Quake folder along with Quakestarter. It's easiest to do this if you're using a "noengine" installation of Quakestarter, to start from a blank slate without vkQuake/Ironwail getting in the way, but we'll discuss various options here. +Quakestarter will use "curl.exe" to download zipfiles, if that utility is in a directory included in your Windows PATH environment variable. This will be the case in current versions of Windows 10 (or later). -If you're intending to keep multiple Quake engine choices in this same folder, be careful about the files from one engine overwriting the files from another. For Quakespasm-family engines, they use the same library files which are often either identical among the various engine releases or differing only by minor version. In that case you can often get away with just keeping the latest version of each such library in the Quake folder, along with the various engine executables. But this is definitely a "power user" situation where you need to be careful about what you are doing (and be aware of what happens to Quake engine files when :doc:`Quakestarter is updated`). Engines that use notably different versions of the same library file cannot be kept in the same folder together. +If Quakestarter can't find that curl utility, it will use a .Net assembly to do the download instead. This should work fine. One downside though is that this approach will not show a progress bar during the download. -If you're *not* using the "noengine" bundle, and you need to get rid of the vkQuake and Ironwail files before installing some other engine, check "engines_manifest.txt" to see what to delete. If you're in this situation it's recommended to overwrite your current Quakestarter installation with the files from a "noengine" bundle so that Quakestarter knows that vkQuake and Ironwail are gone... that way it won't still try to delete vkQuake/Ironwail files on some future Quakestarter update. +If you don't have "curl.exe" in one of your PATH directories and you really do want that progress bar -- or if for some reason the .Net assembly isn't working and you want to try using curl instead -- then you could install curl yourself. You can get a perfectly good "curl.exe" from `its website`_. Then you can either place that utility into some directory that is already in your PATH, or edit your PATH value to include the directory where you put curl. -Once you have your desired Quake engine installed into this Quake folder, you can set a new quake_exe value in your "_quakestarter_cfg.cmd" file to indicate the Quake program that should be launched by Quakestarter. +(How to edit system environment variables like PATH is outside the scope of this chapter, but is well-covered in Google results.) -The easiest way to do this is by using the third item in the main Quakestarter menu. That will give you a selection of executables to choose from, and then Quakestarter will handle making the necessary changes to "_quakestarter_cfg.cmd". -However you can also just manually edit "_quakestarter_cfg.cmd" to make the change yourself, if you want to. One reason you might want to do this is if you need to add some command-line arguments that should always be used whenever launching your Quake program. For example, if you are launching qbism Super8, its default "heapsize" value is quite low and on modern systems there's no downside to always cranking it up, so that more maps will work correctly. So you could choose to specify this in your "_quakestarter_cfg.cmd":: +.. _its website: https://curl.se/windows/ - set quake_exe=qbismS8.exe -heapsize 256000 -Note however that if you use the Quakestarter menu item to change your Quake engine executable, then any extra arguments like this will be discarded. +Engine choice +------------- + +If you want Quakestarter to launch a particular Quake engine of your choice -- other than the options of vkQuake and Ironwail which are usually bundled with Quakestarter -- you can certainly do that! Let's talk about what other Quake engines you might use, describe the easy/common way to install them, and then finally cover a few power-user things. + +Which engine +~~~~~~~~~~~~ -In any case, if you do set your own quake_exe (through the menu or manually) then the following things are *not* always guaranteed: +The :doc:`Quake Engines` chapter talks a bit about the variety of Quake-playing programs out there. vkQuake and Ironwail are great general-purpose singleplayer Quake engines, but they might not work on your computer for some reason. Or some other engine may have that one special feature that makes it a must-have for you. + +You can use other Quake engines through Quakestarter, but keep in mind that for other Quake engines the following things are *not* always guaranteed: * that your choice of Quake engine will be able to properly run every selection from the Quakestarter menus * that your choice of Quake engine will be able to play soundtrack files * that all the settings in the example autoexec.cfg will work for your choice of Quake engine, or have the indicated defaults * that existing savegames will work for your choice of Quake engine -vkQuake and Ironwail are safe engine choices, and Quakespasm-Spiked usually is too. The original Quakespasm engine is also widely compatible, although since the original Quakespasm lacks multigame support (see below) there will be a small number of Quakestarter items that it cannot launch. +vkQuake and Ironwail are safe engine choices, and Quakespasm-Spiked usually is too. The original Quakespasm engine is also widely compatible, although since the original Quakespasm lacks multigame support (:ref:`see below`) there will be a small number of Quakestarter items that Quakespasm cannot launch. Beyond those choices, it's more on your shoulders to look into compatibility issues and be aware that something might go wrong. Even some Quake engine that is a perfectly fine piece of software engineering may have troubles running a particular map release if the map was never tested against that engine, and FWIW most releases are tested against a Quakespasm-family engine. A map may even malfunction in ways that are not immediately apparent if you haven't played it before (e.g. missing monsters, lighting errors). That said, there are many players who are perfectly happy with their preference for a specialty engine like FTE or DarkPlaces, willing to do a bit of troubleshooting if necessary in order to benefit from unique features that those engines provide. The only inarguable "bad choice" for a Quake engine, when it comes to the purpose of playing custom addons, would be a multiplayer-focused engine like ezQuake. +Installing an engine - easy mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to use some other Quake engine, then the files that make up that engine need to be placed in the Quake folder along with Quakestarter. + +If you're interested in doing this, it's highly recommended to start with a "noengine" installation of Quakestarter. That way you won't have to worry about dealing with the vkQuake/Ironwail files from the normal Quakestarter bundle, and you also won't be in danger of a Quakestarter update doing anything unexpected to the files of your own Quake engine of choice. + +This "easy mode" section will assume that you are working with a "noengine" Quakestarter installation. + +If you're intending to manually place multiple Quake engine choices into this Quake folder, be careful about the files from one engine overwriting the files from another. For Quakespasm-family engines, they use the same library files which are often either identical among the various engine releases or differing only by minor version. In that case you can often get away with just keeping the latest version of each such library file in the Quake folder, along with the various engine executables. But this is definitely a situation where you need to be careful about what you are doing. Engines that use notably different versions of the same library file cannot be kept in the same folder together. + +Once you have your desired Quake engine(s) installed into this Quake folder, you can set a new quake_exe value in your "_quakestarter_cfg.cmd" file to indicate the Quake program that should be launched by Quakestarter. + +The easiest way to do this is by using the third item in the main Quakestarter menu. That will give you a selection of executables to choose from, and then Quakestarter will handle making the necessary changes to "_quakestarter_cfg.cmd" to honor your choice. + +However you can also just manually edit "_quakestarter_cfg.cmd" to make the change yourself, if you want to. One reason you might want to do this is if you need to add some command-line arguments that should always be used whenever launching your Quake program. For example, if you are launching qbism Super8, its default "heapsize" value is quite low and on modern systems there's no downside to always cranking it up, so that more maps will work correctly. So you could choose to specify this in your "_quakestarter_cfg.cmd":: + + set quake_exe=qbismS8.exe -heapsize 256000 + +**Note:** If you use the Quakestarter menu item to change your Quake engine executable, then any extra arguments like those will be discarded. + +Installing an engine - hard mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Let's say you *don't* have a "noengine" installation, but you still want to install some other Quake engines. + +If you are OK with transforming your current Quakestarter installation into a "noengine" form, there's a couple of ways to do that. One way to do this is to get the "noengine" bundle for the same version of Quakestarter and unzip it over top of your current Quakestarter files. Another way is to use Quakestarter's update process to install a "noengine" variant of a newer version of Quakestarter, choosing to "detach" or "erase" your current engine files as part of that process. These things are described in the chapter :doc:`Updating Quakestarter`. Once you've achieved a "noengine" setup, you can go back to the "easy mode" process described above. + +But OK, maybe you want to keep the vkQuake/Ironwail files and keep them "managed" by Quakestarter, but you also want to add some new engine... + +If this new engine is a single executable, that is still pretty easy. You can just drop its exe into the Quake folder and it will now be available as a Quakestarter engine choice. + +If this new engine is made up of multiple files, that is trickier. If those files overlap with any of the vkQuake/Ironwail files, they can be affected when Quakestarter updates. And even if they don't currently overlap, conceivably they still might be affected by some future Quakestarter update in which vkQuake/Ironwail use different library files. This is less of a "power user" situation and more of a "don't do this" situation, generally speaking. But... do what you like! Just be aware of what happens to the managed vkQuake/Ironwail files :doc:`when Quakestarter is updated`. + +FYI if you have vkQuake/Ironwail files that were installed by Quakestarter, those files will be listed in "engines_manifest.txt". + Multigame support ----------------- @@ -88,20 +130,3 @@ Finally, you can choose to use the multigame_support value to explicitly define That last example would result in the following command line for running the "udob_v1_1" release based on Copper:: my_quake_program.exe -game2 copper_v1_17 -game udob_v1_1 +map start - - -Download behavior ------------------ - -And finally, a consideration that is outside of that configuration file: - -Quakestarter will use "curl.exe" to download zipfiles, if that utility is in a directory included in your Windows PATH environment variable. This will be the case in current versions of Windows 10 (or later). - -If Quakestarter can't find that curl utility, it will use a .Net assembly to do the download instead. This should work fine. One downside though is that this approach will not show a progress bar during the download. - -If you don't have "curl.exe" in one of your PATH directories and you really do want that progress bar -- or if for some reason the .Net assembly isn't working and you want to try using curl instead -- then you could install curl yourself. You can get a perfectly good "curl.exe" from `its website`_. Then you can either place that utility into some directory that is already in your PATH, or edit your PATH value to include the directory where you put curl. - -(How to edit system environment variables like PATH is outside the scope of this chapter, but is well-covered in Google results.) - - -.. _its website: https://curl.se/windows/ diff --git a/docsource/other_stuff/auto_setup_logic.rst b/docsource/other_stuff/auto_setup_logic.rst index 74677b7..7e125c2 100644 --- a/docsource/other_stuff/auto_setup_logic.rst +++ b/docsource/other_stuff/auto_setup_logic.rst @@ -9,7 +9,7 @@ If you already have an installation of the original Quake game somewhere on the Stores cheat-sheet ------------------ -If you just want to know how Quake installations from various stores can help the Quakestarter auto-setup, here's the bottom line about the files that those store installations provide (as of the last time this doc was updated, April 2022). +If you just want to know how Quake installations from various stores can help the Quakestarter auto-setup, here's the bottom line about the files that those store installations provide (as of the last time this doc was updated, August 2022). * The original Quake pak files (game data) are provided by Steam and GOG. diff --git a/docsource/other_stuff/not_windows.rst b/docsource/other_stuff/not_windows.rst index 9b55435..42ed46e 100644 --- a/docsource/other_stuff/not_windows.rst +++ b/docsource/other_stuff/not_windows.rst @@ -3,7 +3,7 @@ Beyond Windows If you would rather play Quake on macOS or some Linux distro, you can do that! The same Quake pak files and custom content will work on any OS. -vkQuake_ does have Linux builds available. It will also work on macOS but in that case you'd need to `build it yourself from source`_. +vkQuake_ does have Linux builds available. It will also work on macOS but doesn't have official Mac builds; for macOS you can either `build it yourself from source`_ or, if you have a GitHub account, click on a recent `automated macOS build`_ from the "master" branch and download the "vkQuake archive" from the bottom of its page. Ironwail_ does not work on macOS at all because of OpenGL driver limitations there. On Linux you can build it yourself if you like; just run "make" inside the Quake directory of its source code. @@ -20,6 +20,7 @@ Finally, if you're playing on Ubuntu Linux (or an Ubuntu-like) and consider your .. _vkQuake: https://github.com/Novum/vkQuake .. _build it yourself from source: https://github.com/Novum/vkQuake#macos +.. _automated macOS build: https://github.com/Novum/vkQuake/actions/workflows/build-mac.yml .. _Ironwail: https://github.com/andrei-drexler/ironwail .. _sourcecode repo: https://github.com/Shpoike/Quakespasm .. _Steam guide: http://steamcommunity.com/sharedfiles/filedetails/?id=119489135 diff --git a/docsource/other_stuff/quake_engines.rst b/docsource/other_stuff/quake_engines.rst index 06a7019..2c1ffc5 100644 --- a/docsource/other_stuff/quake_engines.rst +++ b/docsource/other_stuff/quake_engines.rst @@ -58,6 +58,7 @@ And a blurb about each of these features: If you want to use some engine other than vkQuake or Ironwail, the :doc:`Advanced Configuration` chapter has details about how to set that up. +(And for a comparison of singleplayer engines, `Quake Engines & Source Ports`_ on Slipgate Sightseer is a good quick reference.) Why not the "enhanced" Quake rerelease? --------------------------------------- @@ -75,3 +76,4 @@ You can have both the Quake rerelease and also a community-developed Quake engin .. _Mark V: http://quakeone.com/markv/ .. _FTE: https://fte.triptohell.info/ .. _DarkPlaces: https://icculus.org/twilight/darkplaces/ +.. _Quake Engines & Source Ports: https://www.slipseer.com/index.php?threads/quake-engines-source-ports-a-beginners-guide.11/ diff --git a/docsource/other_stuff/upgrading_quakestarter.rst b/docsource/other_stuff/upgrading_quakestarter.rst index bd8387a..187b796 100644 --- a/docsource/other_stuff/upgrading_quakestarter.rst +++ b/docsource/other_stuff/upgrading_quakestarter.rst @@ -6,6 +6,7 @@ Read this part first! The update logic in Quakestarter was introduced in version 3.3.0. If you are updating from an earlier version of Quakestarter, skip to the :ref:`"Completely manual update"` section at the bottom of this page. +If you're updating from version 3.1.0 or earlier, where Quakespasm Spiked is the bundled Quake engine, you'll also want to read the notes for version 3.2.0 in the :doc:`Changelog` so that you can decide how you want to handle the transition to vkQuake/Ironwail. Autoupdate ---------- @@ -22,7 +23,7 @@ If you do turn off autoupdates, you should skip ahead to one of the sections bel But if you leave autoupdates enabled, then sooner or later when you run Quakestarter you will see the message "A newer version of Quakestarter is available!" at the top of the window. Before proceeding to the normal Quakestarter menus, you'll be given the option to open the new changelog in your web browser to see info about the new release, and then you can choose whether or not to update to that new version of Quakestarter. -**Note:** If you say "no" to updating, Quakestarter will ask you again the next time you run it on some later date. There's currently no way to record a preference of "permanently skip that version and stop asking me". If you want Quakestarter to stop telling you that there is a new version available, you'll need to turn off autoupdates as described above. +**Note:** If you say "no" to updating, Quakestarter will ask you again when you run it on a later day. There's currently no way to record a preference of "permanently skip that version and stop asking me". If you want Quakestarter to stop telling you that there is a new version available, you'll need to turn off autoupdates as described above. Once you've decided to get the new version, Quakestarter will ask you if you want to include the Quake engine files (for vkQuake and Ironwail) in the downloaded update package. Normally you will want to enter **y** for "yes", especially if you are currently using the Quakestarter-installed vkQuake and Ironwail engines. Even if the engine versions haven't changed in this new update, they're small files and it's simplest just to get them again. @@ -33,7 +34,7 @@ Quake engine management Quakestarter keeps track of which Quake engine files it is responsible for dealing with when autoupdating. We'll call these the "Quakestarter-managed" Quake engines. A normal Quakestarter installation is managing the files for vkQuake and Ironwail; a "noengine" installation is not managing anything. -The autoupdater allows you to choose whether to download the engine files that are part of the incoming update. If you enter **y** for "yes", then Quakestarter will first delete any engine files it is currently managing, then put the new engine files into place and start managing those. If you enter **n** for "no", things are still straightforward if Quakestarter is *not* currently managing any engine files (it just... continues to not manage anything). +The autoupdater allows you to choose whether to download the engine files that are part of the incoming update. If you enter **y** for "yes", Quakestarter will first delete any engine files it is currently managing, then put the new engine files into place and start managing those. If you enter **n** for "no", things are still straightforward if Quakestarter is *not* currently managing any engine files (it just... continues to not manage anything). But what if Quakestarter *is* currently managing some engine files and you say "no" you don't want to download the new ones? What does that mean for the currently managed files? In that case the autoupdater will give you three choices; the choices are summarized in the menu there, but here's more detail about them. diff --git a/docsource/quakestarter_readme.rst b/docsource/quakestarter_readme.rst index 8d05761..f573aac 100644 --- a/docsource/quakestarter_readme.rst +++ b/docsource/quakestarter_readme.rst @@ -51,6 +51,8 @@ The tools included in this package are: * If you got the normal Quakestarter bundle (not the "noengine" bundle), then it also includes the vkQuake_ and Ironwail_ "Quake engines", i.e. programs for playing Quake that replace the original programs like WinQuake and GLQuake. Note that there are several other Quake engines out there; see the :doc:`Quake Engines` chapter (under Other Topics) if you're curious. +Finally, Quakestarter also includes an optional autoupdate feature to keep all of the above up-to-date. + Note that the programs in this package are meant to be used on Windows 7, 8, 10, or 11. If you are using a different OS then the programs here won't be as useful, but these docs might be. See the :doc:`Beyond Windows` chapter (under Other Topics) for some specific pointers.