Merge branch 'release/2.0.1'

.gitignore

@@ -1 +1,2 @@
 *.pyc
+quakestarter-*.zip

devtools/release.py

@@ -8,7 +8,7 @@
 import urllib.request
 import zipfile
 
-VERSION = "2.0.0"
+VERSION = "2.0.1"
 ROOT_FOLDER = "Quake"
 QSS_VERSION = "2020-10-17"
 QSS_URL = "https://fte.triptohell.info/moodles/qss/quakespasm_spiked_win64_dev.zip"
@@ -51,6 +51,27 @@ def handle_zip(url, localfile):
     os.remove(localfile)
     return zip_contents, timestamp
 
+def gen_readme(readme_contents, qss_timestamp, sql_timestamp, timestamp):
+    new_readme_contents= []
+    skip_next = False
+    for line in readme_contents:
+        if skip_next:
+            skip_next = False
+            continue
+        if (qss_timestamp == "") and ("###QSS_VERSION###" in line):
+            skip_next = True
+        else:
+            new_line = line.replace(
+                "###QSS_VERSION###", QSS_VERSION).replace(
+                "###QSS_TIMESTAMP###", qss_timestamp).replace(
+                "###SQL_VERSION###", SQL_VERSION).replace(
+                "###SQL_TIMESTAMP###", sql_timestamp).replace(
+                "###VERSION###", VERSION).replace(
+                "###TIMESTAMP###", timestamp)
+            new_readme_contents.append(new_line)
+    with open(os.path.join(ROOT_FOLDER, "quakestarter_readme.txt"), 'w') as f:
+        f.writelines(new_readme_contents)
+
 def gen_release():
     script_path = os.path.abspath(sys.argv[0])
     src = os.path.realpath(os.path.dirname(os.path.dirname(script_path)))
@@ -59,34 +80,26 @@ def exclusions_for_copy(dir, contents):
             return []
         return EXCLUSIONS
     shutil.copytree(src, ROOT_FOLDER, ignore=exclusions_for_copy)
-    qss_zip_contents, qss_timestamp = handle_zip(QSS_URL, QSS_LOCALFILE)
-    print("QSS version: {}".format(QSS_VERSION))
-    print("QSS timestamp: {}".format(qss_timestamp))
     _, sql_timestamp = handle_zip(SQL_URL, SQL_LOCALFILE)
     print("SQL2 version: {}".format(SQL_VERSION))
     print("SQL2 timestamp: {}".format(sql_timestamp))
-    qss_manifest = [ l + '\r\n' for l in qss_zip_contents ]
-    qss_manifest.insert(0, "\r\n")
-    qss_manifest.insert(0, "manifest of Quakespasm-Spiked files:\r\n")
-    with open(os.path.join(ROOT_FOLDER, "qss_manifest.txt"), 'w') as f:
-        f.writelines(qss_manifest)
     timestamp = time.strftime("%B %Y")
     print("Quakestarter version: {}".format(VERSION))
     print("Quakestarter timestamp: {}".format(timestamp))
     with open(os.path.join(ROOT_FOLDER, "quakestarter_readme.txt"), 'r', newline='\r\n') as f:
         readme_contents = f.readlines()
-    new_readme_contents = []
-    for line in readme_contents:
-        new_line = line.replace(
-            "###QSS_VERSION###", QSS_VERSION).replace(
-            "###QSS_TIMESTAMP###", qss_timestamp).replace(
-            "###SQL_VERSION###", SQL_VERSION).replace(
-            "###SQL_TIMESTAMP###", sql_timestamp).replace(
-            "###VERSION###", VERSION).replace(
-            "###TIMESTAMP###", timestamp)
-        new_readme_contents.append(new_line)
-    with open(os.path.join(ROOT_FOLDER, "quakestarter_readme.txt"), 'w') as f:
-        f.writelines(new_readme_contents)
+    gen_readme(readme_contents, "", sql_timestamp, timestamp)
+    release_name = "quakestarter-noengine-" + VERSION
+    shutil.make_archive(release_name, "zip", base_dir=ROOT_FOLDER)
+    qss_zip_contents, qss_timestamp = handle_zip(QSS_URL, QSS_LOCALFILE)
+    print("QSS version: {}".format(QSS_VERSION))
+    print("QSS timestamp: {}".format(qss_timestamp))
+    gen_readme(readme_contents, qss_timestamp, sql_timestamp, timestamp)
+    qss_manifest = [ l + '\r\n' for l in qss_zip_contents ]
+    qss_manifest.insert(0, "\r\n")
+    qss_manifest.insert(0, "manifest of Quakespasm-Spiked files:\r\n")
+    with open(os.path.join(ROOT_FOLDER, "qss_manifest.txt"), 'w') as f:
+        f.writelines(qss_manifest)
     release_name = "quakestarter-" + VERSION
     shutil.make_archive(release_name, "zip", base_dir=ROOT_FOLDER)
     shutil.rmtree(ROOT_FOLDER)

id1/autoexec-cfg-example-annotated.txt

@@ -198,12 +198,31 @@
 
 // Originally Quake didn't have transparent liquids. These days however,
 // most Quake engines do support transparent liquids, and maps can take
-// advantage of that. You can set r_wateralpha to your desired amount of
-// transparency (where 1 is opaque and 0 is completely clear) and that will
-// take effect unless the map itself forces some other value explicitly.
+// advantage of that. If a map was created with transparency enabled for its
+// liquids, then you can set r_wateralpha to your desired amount of
+// transparency (where 1 is opaque and 0 is completely clear). That will
+// take effect unless the map itself explicitly forces some other value.
 
-//   Default is 0.5. Uncomment the following line to set some other value.
-//r_wateralpha 0.4
+//   Default is 1. Uncomment the following line to set some other value.
+//r_wateralpha 0.5
+
+// Quakespasm and related engines also support the following variables for
+// individually setting transparency for lava, slime, and teleporters (unless
+// the map itself forces some other value). These values range from 1 to 0,
+// with 1 as opaque and smaller values being more transparent, except that a
+// value of zero is treated specially. A zero is interpreted as "take the same
+// value as r_wateralpha".
+
+//   Default is 0. Uncomment the following line(s) to set some other value.
+//r_lavaalpha 0.5
+//r_slimealpha 0.5
+//r_telealpha 0.5
+
+// Note that if a map was NOT created with transparent liquids enabled, then
+// setting values for these transparency variables won't matter, unless you
+// also set "r_novis 1" to disable the use of visibility tests in the renderer.
+// However doing this can hurt performance and may alter the gameplay of the
+// map (by letting you see things you weren't intended to see).
 
 
 // animations

id1/autoexec.cfg.example

@@ -99,8 +99,18 @@
 // transparency, or some decimal value in between. Note that the map itself
 // may force some other value.
 
-//   Default is 0.5. Uncomment the following line to set some other value.
-//r_wateralpha 0.4
+//   Default is 1. Uncomment the following line to set some other value.
+//r_wateralpha 0.5
+
+
+// Set these variables to determine other material transparencies. 0 means
+// to use whatever the r_wateralpha value is. Otherwise, values up to 1 will
+// set the amount of transparency with 1 being fully opaque.
+
+//   Default is 0. Uncomment the following line(s) to set some other value.
+//r_lavaalpha 0.5
+//r_slimealpha 0.5
+//r_telealpha 0.5
 
 
 // Set r_lerpmove to 0 for old jerky enemy animations, 1 for smoothed.

quakestarter_docs/basic/1_installation.txt

@@ -6,7 +6,18 @@ 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 "upgrading_quakestarter.txt" doc in the "quakestarter_docs\other_stuff" folder!
 
-If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, especially an existing Quakespasm or Quakespasm-Spiked, then the Quakespasm-Spiked files bundled in this package can conflict with those. This is a "power user" situation for people already familiar with modern Quake engines, so I won't try to make detailed recommendations here. One thing to note however is that the "qss_manifest.txt" file lists all of the Quakespasm-Spiked files in this package, which is helpful if you want to discard them.
+If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, especially an existing Quakespasm or Quakespasm-Spiked, then you might want to consider using the "noengine" version of this bundle if you aren't already doing that. Otherwise the Quakespasm-Spiked files bundled in this package can conflict with existing files in your Quake directory. One thing to note is that the "qss_manifest.txt" file lists all of the Quakespasm-Spiked files in this package, which is helpful if you need to discard them. (If you don't have "qss_manifest.txt", then you are using the "noengine" bundle already.)
+
+
+**** Quake engine
+
+If you're using the normal Quakestarter bundle, it already includes Quakespasm-Spiked. So you don't have anything else to do here & can skip to the next section!
+
+However if you decided to use the "noengine" bundle, you need to provide the Quake engine that Quakestarter will launch. This is a "power user" situation so the process of finding and installing a Quake engine won't be described here; we'll just cover the bits specific to Quakestarter.
+
+By default Quakestarter is configured to use Quakespasm-Spiked, specifically "quakespasm-spiked-win64.exe". So if that's what you have or plan to install, you're good to go.
+
+If you want Quakestarter to launch some other program for playing Quake, you'll need to configure it to do so. The process of configuring Quakestarter is described in the "advanced_quakestarter_cfg.txt" doc in the "quakestarter_docs\other_stuff" folder.
 
 
 **** .Net Framework
@@ -36,7 +47,7 @@ The first option in the main Quakestarter menu can usually locate and copy the n
 
 **** Soundtrack
 
-The bundled Quakespasm-Spiked program (and several other Quake engines) can play the soundtrack from mp3 or ogg files if the physical Quake CD is not in your CD drive. To get the soundtrack files installed, run Quakestarter and choose the second menu option. This will give you the option to install soundtrack files for the original Quake campaign, and also for the official missionpacks if you have those.
+Quakespasm-Spiked (and several other Quake engines) can play the soundtrack from mp3 or ogg files if the physical Quake CD is not in your CD drive. To get the soundtrack files installed, run Quakestarter and choose the second menu option. This will give you the option to install soundtrack files for the original Quake campaign, and also for the official missionpacks if you have those.
 
 
 **** Additional singleplayer content

quakestarter_docs/basic/2_configuration.txt

@@ -2,7 +2,9 @@
 
 It's good to run Quake at least once before playing any custom content, to set up your desired Quake configuration. You can do this from the third option of the main Quakestarter menu. Or you can just run your Quake executable (e.g. "quakespasm-spiked-win64.exe") from Windows.
 
-(If this fails because you have a 32-bit OS, you're going to need to use a different, 32-bit Quake engine. Changing your Quake engine is covered in the "advanced_quakestarter_cfg.txt" doc in "quakestarter_docs\other_stuff" folder. Note that Quakespasm-Spiked does have a 32-bit version if you want to use that.)
+If this fails with an error dialog about "W_LoadWadFile: couldn't load gfx.wad" then your pak files (game data) are not present. You might need to go back to the "Game data" section of the "1_installation.txt" doc.
+
+(If this fails because you have a 32-bit OS, you're going to need to use a different, 32-bit Quake engine. Changing your Quake engine is covered in the "advanced_quakestarter_cfg.txt" doc in the "quakestarter_docs\other_stuff" folder. Note that Quakespasm-Spiked does have a 32-bit version if you want to use that.)
 
 Any settings that you configure in the default Quake game will be used as a starting point when you later launch custom content.
 
@@ -28,4 +30,4 @@ Several other settings are available, beyond the ones described in that file. Yo
 
 Besides configuring Quake itself, you may also want to change the behavior of Quakestarter. This includes changing what Quake engine you want to use (if you don't want to use Quakespasm-Spiked) and several other things about how addons are downloaded, installed, and launched.
 
-Quakestarter should work fine out-of-the-box without changing any of that configuration, but if you want to dig in, see the "advanced_quakestarter_cfg.txt" doc in "quakestarter_docs\other_stuff" folder.
+Quakestarter should work fine out-of-the-box without changing any of that configuration, but if you want to dig in, see the "advanced_quakestarter_cfg.txt" doc in the "quakestarter_docs\other_stuff" folder.

quakestarter_docs/maps_and_mods/1_mod_folders.txt

@@ -20,6 +20,6 @@ Any Quake mod folder can be "uninstalled" by just deleting it.
 
 The menu options presented by Quakestarter for an installed mod include a choice to "uninstall"; this choice will delete the relevant mod folder. It doesn't matter whether you uninstall a mod through Quakestarter or manually delete its folder using the Windows Explorer: the result is the same.
 
-If you haven't modified your Quakestarter configuration (see the "advanced_quakestarter_cfg.txt" doc in "quakestarter_docs\other_stuff" folder) then that's really all there is to it.
+If you haven't modified your Quakestarter configuration (see the "advanced_quakestarter_cfg.txt" doc in the "quakestarter_docs\other_stuff" folder) then that's really all there is to it.
 
 If however you have changed your Quakestarter configuration: you might have chosen to preserve the downloaded zipfile(s) that were used to install mods and/or patches. If this is the case, then at the time of uninstalling a mod you will be given the option to also delete those zipfiles. If you choose to delete a mod _without_ deleting its saved zipfiles, they will remain until either a) you manually delete them, or b) you reinstall the mod and then eventually delete it through the Quakestarter menus again, this time choosing to remove the zipfiles.

quakestarter_docs/maps_and_mods/3_running_with_sql2.txt

@@ -5,9 +5,9 @@ One general thing to keep in mind is that the box at the bottom of the launcher
 
 **** Game
 
-The "Game" label for this setting in Simple Quake Launcher 2 might be somewhat confusing because it does NOT refer to the "game directory" (mod folder), but rather to the basic set of content that any mod will then build on.
+The "Game" setting in Simple Quake Launcher 2 refers to the basic set of content that any mod will then build on.
 
-Most addons just use "Quake" for the "Game" setting, indicating that they build on the original Quake campaign content. But in some cases an included readme file may tell you differently.
+Most addons just use "Quake" for the "Game" setting, indicating that they build on the original Quake campaign content (from the "id1" folder). But in some cases an included readme file may tell you differently.
 
 A readme that mentions the "-hipnotic" command-line argument is an indicator that you should specify "MP1: Scourge of Armagon" as the "Game" in the launcher. A mention of "-rogue" is an indicator to specify "MP2: Dissolution of Eternity" as the "Game".
 

quakestarter_docs/maps_and_mods/4_explore_more.txt

@@ -6,7 +6,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 "advanced_quakestarter_cfg.txt" doc in "quakestarter_docs\other_stuff" folder. 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 the "Engine Configuration" dialog. The downloads location for Quakestarter is described in the "advanced_quakestarter_cfg.txt" doc in the "quakestarter_docs\other_stuff" folder. 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.
 

quakestarter_docs/other_stuff/advanced_quakestarter_cfg.txt

@@ -15,9 +15,12 @@ The "_quakestarter_cfg_defaults.cmd" file describes these settings in detail, so
 
 **** Engine choice
 
-If you do modify the quake_exe value as described above, it's not guaranteed that your choice of Quake engine will be able to properly run every selection from the Quakestarter menus.
+If you do modify the quake_exe value as described above, the following things are _not_ 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 the downloaded soundtrack files
+* that all the settings in the example autoexec.cfg will work for your choice of Quake engine, or have the indicated defaults
 
-vkQuake should be a safe alternative. And 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 should be a safe alternative choice that avoids such issues. And 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.
 
 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).
 

quakestarter_docs/other_stuff/changelog.txt

@@ -1,3 +1,10 @@
+**** v2.0.1 (Dec 2020)
+
+- Improve the documentation of transparency-related settings in the example autoexec.cfg files.
+
+- Provide a bundle WITHOUT Quakespasm-Spiked as an alternative download for power users.
+
+
 **** v2.0.0 (Nov 2020)
 
 Before we get into the bullet-point changelist, a general note:

quakestarter_docs/other_stuff/quake_engines.txt

@@ -11,7 +11,7 @@ Currently Quakespasm is a sort of "reference standard" for playing new singlepla
 
 **** Why Quakespasm-Spiked?
 
-For this package I've chosen to include only the Quakespasm-Spiked engine, from https://fte.triptohell.info/moodles/qss/
+By default Quakestarter uses the Quakespasm-Spiked engine, from https://fte.triptohell.info/moodles/qss/
 
 Quakespasm-Spiked essentially matches Quakespasm for compatibility, and it adds important usability improvements that can smooth out the experience of playing or managing many existing addons... like supporting higher framerates and the ability to load multiple mod folders. It also implements features like advanced particle systems and customizable HUD/menus that newer addons can take advantage of. Arcane Dimensions is one example of a recent mod that can make use of these QSS features.