Document command-line switches and update wishlist

README.md

@@ -16,7 +16,7 @@ However, it also means that unlike the other implementations, a custom CD image
 --- |--- | --- | ---
 |Requires `dat` file | `Music.dat` | `Music.dat` | `AMBIENTS.DAT` (only for MIDI tracks) |
 |Requires custom CD-ROM / Image | No | No | Yes |
-|Includes extra MIDI tracks from PS1 | Yes | Yes | Yes! |
+|Extra MIDI tracks from PS1 | Play at set times | Play at set times | Play in the exact locations they should (and can be turned off) |
 |Can be used with custom Dosbox builds | No (unless you search for pointers and [compile TPLS yourself](https://github.com/Snaggly/Rayman1Dos-TPLS/blob/master/OffsetList.h)) | No (unless you apply the [patch](https://raymanpc.com/forum/viewtopic.php?f=89&t=28341) and compile Dosbox yourself) | Yes, no recompilation needed! |
 |Can be used on Windows 3.x / 9x | No | No | Yes |
 |Can be used on pure DOS | No | No | Yes |
@@ -46,6 +46,7 @@ These are all existing Rayman versions of which I am aware, and the TSR has been
 * Download and extract a release from the [releases page](https://github.com/PluMGMK/rayman-tpls-tsr/releases).
 * Change the `IMGMOUNT` command in the `autoexec` section of your config file to mount the `TPLSTSR4.cue` file, rather than the game's original CD image.
 * Before the invocation of `RAYMAN.EXE` in the `autoexec` section, add `D:\TPLSTSR4.EXE` (where `D` is your CD drive letter).
+ * You can add command-line switches as described below, if desired.
 * Run Dosbox with your new config file and enjoy TPLS!
 
 ### If on native DOS or Windows 3.x / 9x (having used Ubi Soft's installer to install _Rayman_)
@@ -55,11 +56,26 @@ These are all existing Rayman versions of which I am aware, and the TSR has been
 * Use the `tplstsr4.cue` (or `tplstsr4.toc`) and `tplstsr4.bin` files to burn a CD-R – it should be possible to do this with `cdrdao` on Linux (**using the `--swap` option!**), or perhaps [ImgBurn](https://www.imgburn.com/) on Windows.
 * Insert the new CD into your PC running DOS or Windows.
 * Before running Rayman, run `D:\TPLSTSR4.EXE` (where `D` is your CD drive letter).
+ * You can add command-line switches as described below, if desired.
 * Run `C:\RAYMAN.BAT` and enjoy TPLS!
 
+### Command-line switches
+
+`TPLSTSR4.EXE` supports the following command line switches on invocation:
+
+|Switch |Meaning |Effect |
+--- |--- | --- | ---
+|/E |[EMS](https://en.wikipedia.org/wiki/Expanded_memory#EMS) |The TSR stores the payload in Expanded Memory rather than Conventional Memory, while waiting for you to run _Rayman_. This seemed like a good idea when I first wrote this version, but when I actually tried it out it was a bit flaky… Maybe someday I'll go back to figure out what I did wrong, and fix it. (PRs also welcome!) |
+|/N |NO "Yeah!" or "Oh No!" music |Turns off the option to use CD audio when Rayman reaches the exit sign or dies. |
+|/C |CD Audio only |Turns off Ambient ("MIDI") tracks. |
+|/M |Music only |Turns off the visual bug fixes, i.e. Bad Rayman's fist and the Curse Stars in Candy Château. |
+|/F |Fist kills |Turns on an optional feature whereby Bad Rayman's fist kills Rayman when it hits him (rather than just passing through). This was intended behaviour at some point during the game's development, and it's not clear to me whether it was deliberately disabled or just not correctly implemented. It doesn't really make it _that_ much harder! ;) |
+
+All switches except `/E` can be toggled by re-invoking the TSR. So, for example, if you run `TPLSTSR4 /C`, then the TSR will be resident with Ambient tracks turned off, then if you run `TPLSTSR4 /C` again, it will toggle Ambient tracks back on. Each time you do this, it will print out a report of which options are currently enabled. :)
+
 ## Compilation
 
-`TPLSTSR4` (unlike the previous version) is a plain old `MZ` executable. However, because of the peculiar way I've used groups in the code, a lot of assemblers seem to miscalculate certain offsets. [JWasm](https://github.com/Baron-von-Riedesel/JWasm) v2.14 or greater will assemble the TSR correctly, and it can run on Windows, DOS or Linux.
+`TPLSTSR4` (unlike the old `TPLSTSR3` from 2021) is a plain old `MZ` executable. However, because of the peculiar way I've used groups in the code, a lot of assemblers seem to miscalculate certain offsets. [JWasm](https://github.com/Baron-von-Riedesel/JWasm) v2.14 or greater will assemble the TSR correctly, and it can run on Windows, DOS or Linux.
 
 ```
 jwasm -mz TPLSTSR4.ASM
@@ -73,6 +89,8 @@ In order for the game to play the ambient tracks, the file `AMBIENTS.DAT` needs
 
 Currently it works by taking some of the 44.1-kHz 32-bit stereo FLAC files available in an archive on [RayTunes](https://raytunes.raymanpc.com), down-sampling them to 10-kHz 16-bit mono, and saving them as raw PCM data suitable for loading by the game itself. Given that the originals are MIDI, I suppose this doesn't really degrade the quality too badly…
 
+If you burn a CD to play on a retro PC, it is probably wise to copy the TSR and `AMBIENTS.DAT` to your hard drive before playing, as otherwise it will have to read the entire file from the CD into memory while the game is booting up, which can take a while…
+
 ## How does it work?
 
 Unlike v1.x (using the DOS32 extender), since v2.0 this is a normal Real Mode TSR.
@@ -86,10 +104,8 @@ It then transfers control to the actual sound driver, which is able to operate n
 
 ## Wishlist (possible future additions)
 
-* Make the exit sign fanfare work in Candy Château (Currently it doesn't work because my code relies on the game entering a "frozen" state to hold Rayman in his pose until the fanfare finishes. For some reason, the game does not enter this "frozen" state in Candy Château, so my code wouldn't work in its current iteration.)
-* More fine-grained configuration: perhaps command-line switches to choose whether or not to play the ambient tracks, or the exit sign fanfare, or the CD track for when Rayman dies.
- * Or perhaps even an in-game menu? (This would be **very** tricky though!)
+* Add support for _Rayman Designer_ and the educational games. Although these don't need a Per-Level Soundtrack, most of the additional features are applicable to them and would be worthwhile enhancements. I don't want to bloat it too much though…
+* Complement / replace the command-line switches an in-game menu? (This would be **very** tricky though!)
 * Option to replace the "popping" sound used for Tings with the "ting" sound from PS1
-* [Not strictly related to the soundtrack, but would be nice] Fix the bugged curse stars in Candy Château so that they actually appear on Rayman like in the PS1 version. (The code for them does exist in the PC version, but – at least in _Rayman Designer_ – it only works when there are two curses at once, which never happens in the original game.)
 
 I'm not promising at this point that any of these features will appear in a future version, but it's a possibility! :)