Update README.md (#2592)

* Update README.md

Changed some murky language with respect to the "mods" folder location.

* Update README.md

* Update README.md

Readme overhaul for more consistent language and some updated instruction. Truncated certain sections, removed archaic instructions, elaborated where needed.

* Update README.md

* Update README.md

Does version info belong in additional setup info? Changing that.

* Update README.md

Making suggested changes.

* Update README.md

Made recommended changes.

README.md

@@ -2,7 +2,7 @@
 
 A PC port of OoT allowing you to enjoy the game with modern controls, widescreen, high-resolution, gyroscopy and other great features! Setup is simple, let's get started!
 
-The Ship does not include assets and as such requires a prior copy of the game to play.
+The Ship does not include any copyrighted assets.  You are required to provide a supported copy of the game.
 
 ## Discord
 
@@ -12,19 +12,17 @@ Official Discord: https://discord.com/invite/BtBmd55HVH
 
 1) Download The Ship of Harkinian from [Discord](https://discord.com/invite/BtBmd55HVH).
 2) Requires a supported copy of the game (See supported games below).
-3) Use the OTRGui to generate an `oot.otr` archive file.
+3) Use `OTRGui.exe` to generate an `oot.otr` archive file.
 4) Launch `soh.exe`
 
 ### Supported Games
 #### Ocarina of Time Debug PAL GC (not Master Quest)
-> Currently the recommended option
 ```
 Build team: `zelda@srd022j`
 Build date: `03-02-21 00:49:18` (year-month-day)
 sha1: cee6bc3c2a634b41728f2af8da54d9bf8cc14099
 ```
 #### Ocarina of Time PAL GameCube
-> May lead to crashes and instability
 ```
 sha1: 0227d7c0074f2d0ac935631990da8ec5914597b4
 ```
@@ -38,39 +36,45 @@ sha1: 50bebedad9e0f10746a52b07239e47fa6c284d03 (Alternate)
 
 Congratulations, you are now sailing with the Ship of Harkinian! Have fun!
 
-## Additional Setup Information
+## About Versions
 
-The Ship of Harkinian uses a proprietary versioning system consisting of a sci-fi film character followed by a phonetic alphabet code word. The film character represents a major release version which increments with the addition of many new features and bug fixes. The code word represents a minor release version which increments with small updates mainly comprised of bug fixes. For example, `DECKARD ALFA`.
+The Ship of Harkinian's versioning system is a unique system, comprising of a three-numbered version (`x.y.z`) and a version codename.  The main version number `x` signifies major feature updates that require a new `oot.otr` file.  The version number `y` signifies major feature updates and bugfixes that do not require a new `oot.otr` file.  The version number `z` signifies minor updates such as a collection of bugfixes.
+
+The version codename consists of a sci-fi film character followed by a phonetic alphabet code word. The film character represents a major release version which increments with the major `x` or `y` version bumps. The code word represents a minor release version which increments with the minor `z` version bump.
+
+## Additional Setup Information
 
 ### Windows Rom Extraction
 
-* Open OTRGui.exe, and select one of the supported roms listed above, to generate the `oot.otr` archive file.
+* Open `OTRGui.exe` and click on "Open OOT ROM", then select your supported copy of the game (see section "Supported Games").
 * If a second button already exits then `oot.otr` already exists. To prevent overwriting the old `oot.otr` use this button to choose a new game directory. The new directory must not already contain an `oot.otr` to prevent an error.
-* When the process completes, place `oot.otr` beside `soh.exe` if it is not already.
+* When the process completes, you should have an `oot.otr` or `oot-mq.otr` file in your main directory, depending on the version of the game used to build it.
+    (*NOTE:* You can have both `.otr` files, if you want to! This even allows you to shuffle MQ and vanilla dungeons in the randomizer)
 
-This packaging process can take up to **5 minutes**.
+This process can take up to several minutes, depending on your system hardware.
 
-Close the OTRGui when the `Done!` message appears.
+Close `OTRGui.exe` when the `Done!` message appears.
-If you get another message, then you might have selected the wrong rom. Make sure to use a rom consistent with the above checksum.
+If you get another message, then you might have selected the wrong rom. See section "Supported Games".
 
 ### Linux Rom Extraction
 
-* Place one of the supported roms in the same folder as the appimage.
+* Place one of the supported roms in the same folder as the appimage (See section "Supported Games").
-* When you run the soh appimage, it should begin generating the `oot.otr` archive file.
+* Execute `soh.appimage`.  You may have to `chmod +x` the appimage via terminal.
-* When the process completes, place `oot.otr` in the same folder as the appimage, if it is not already, then run the appimage.
+* When the process completes, you should have an `oot.otr` or `oot-mq.otr` file in the same directory as the appimage, and the game should start automatically.
+    (*NOTE:* You can provide both a vanilla and MQ ROM, if you want to! This even allows you to shuffle MQ and vanilla dungeons in the randomizer)
 
-The packaging process can take up to **5 minutes**.
+This process can take up to several minutes, depending on your system hardware.
 
-If you get any errors, then you might have selected the wrong rom. Make sure to use a rom consistent with the above checksum.
+If you get any errors, then you might have selected the wrong rom. See section "Supported Games".
 
 ### MacOS Rom Extraction
 
 * Run `soh.app`, and when prompted, select one of the supported roms listed above.
 * You should see a notification saying `Processing OTR`, then, once the process is complete, you should get a notification saying `OTR Successfully Generated`, then the game should start.
 
-The packing process can take up to **5 minutes**.
+This process can take up to several minutes, depending on your system hardware.
 
-If you get an error saying `Incompatible ROM hash`, you have selected the wrong rom, make sure the checksum matches one of the ones listed above.
+If you get an error saying `Incompatible ROM hash`, you have selected the wrong rom. See section "Supported Games".
 
 ### Nintendo Switch Rom Extraction
 
@@ -84,11 +88,11 @@ If you get an error saying `Incompatible ROM hash`, you have selected the wrong
 
 ---
 
-If you still cannot get the tool to work, join our [Discord Server](https://discord.com/invite/BtBmd55HVH) and ask for help in the `#support` text channel. Keep-in-mind that we do not condone piracy in any way.
+If you're having any trouble, feel free to join our [Discord Server](https://discord.com/invite/BtBmd55HVH) and ask for help in the Support text channels. Please keep in mind that we do not condone piracy.
 
 ### Running The Ship of Harkinian
 
-Launch the game. If the window immediately closes, or if there are visual artifacts, you may have selected the wrong rom in the OTRGui tool.
+For Windows, launch `soh.exe`.  For Linux, execute the appimage. For MacOS, launch the app. For Switch, launch the app via Atmosphere's `Game+R` launcher method. For Wii U, launch the `.rpx` file through the homebrew Mii Maker exploit.
 
 Default keyboard configuration:
 | N64 | A | B | Z | Start | Analog stick | C buttons | D-Pad |
@@ -106,15 +110,15 @@ Other shortcuts:
 | Alt+Enter | Fullscreen (DirectX) |
 | Ctrl+R | Reset |
 
-Currently, DirectX 11 and OpenGL are supported. Change the renderer by opening the `shipofharkinian.json` configuration file in notepad and add `sdl` to the quotes in `"GfxBackend": ""` for OpenGL or leave blank for DirectX.
+Currently, there are three rendering APIs supported: DirectX11 (Windows), OpenGL (all platforms), and Metal (MacOS). You can change which API to use in the `Settings` menu of the menubar, which requires a restart.  If you're having an issue with crashing, you can change the API in the `shipofharkinian.json` file by finding the line `gfxbackend:""` and changing the value to `sdl` for OpenGL. DirectX 11 is the default on Windows.
 
 ### Custom Music
 
-We support importing custom [Seq64](https://github.com/sauraen/seq64) files to replace the in game music and fanfares (Not sound effects yet currently).
+We support importing custom [Seq64](https://github.com/sauraen/seq64) files to replace the in game music and fanfares (Sound effect and instrument replacement is currently not supported).
 
-First you will need to prepare a folder with the desired sequences, in which every sequence will have two files with the same name and different extensions, a `.seq` Seq64 file and a `.meta` plaintext file. These files can be categorically nested in folders if desired, they will still be consumed as if they were all at the top level.
+First you will need to prepare a folder with the desired sequences. Every sequence requires two files with the same name and different extensions - a `.seq` Seq64 file and a `.meta` plaintext file. These files can be categorically nested in folders if desired, - Retro will recursively search each subfolder it finds.
 
-The meta file will have two lines, the first line is the name that will be displayed in the SFX editor, and the second line will be the instrument set number, in base 16. For example, if there is a sequence file `Foo.seq` then you need a meta file `Foo.meta` that could contain:
+The `.meta` file requires two lines - the first line is the name that will be displayed in the SFX editor, and the second line is the instrument set number in `base16` format. For example, if there is a sequence file `Foo.seq` then you need a meta file `Foo.meta` that could contain:
 ```
 Awesome Name
 C
@@ -122,28 +126,31 @@ C
 
 Once you have prepared your sequences folder:
 1. Download and open [Retro](https://github.com/HarbourMasters/retro/releases). 
-1. Choose the "Create OTR" option 
+1. Choose the "Create OTR" option. 
-1. Choose the "Custom Sequences" option
+1. Choose the "Custom Sequences" option.
-1. Using the file select, choose the sequences folder you prepared in the previous instructions.
+1. Using the file selection screen, choose the sequences folder you prepared in the previous instructions.
-1. Click the "Stage Files" button (Reminder: SoH can handle 1024 custom sequence in total, this number include the count of the original music with it so be sure to take this into account)
+1. Click the "Stage Files" button.
+    (*NOTE:* SoH can handle 1024 custom sequence in total. This includes the original music. Keep that in mind!)
 1. Click the "Finalize OTR" text in the green footer.
-1. Finally click "Generate OTR" and for the source destination it needs to go in the `mods` folder of your SoH installation.
+1. Click "Generate OTR" and, using the file selection screen, save the file to the `mods` folder of your SoH installation.
-    - This `mods` folder should be a sibling of your `oot.otr` file.
+    - This `mods` folder should be in the same folder as your `oot.otr` file.
 
-Assuming you have done everything correctly, boot up SoH and open up the SFX Editor (In the Enhancements dropdown). You should now be able to swap out any of the in game sequences/fanfares for the sequences added in your newly generated OTR file. If you have any trouble with this process please reach out in the support section of the Discord
+Assuming you have done everything correctly, boot up SoH and select the SFX Editor from the enhancements dropdown menu. You should now be able to swap out any of the in game sequences/fanfares for the sequences added in your newly generated OTR file. If you have any trouble with this process, please reach out in the support section of the Discord.
 
 ## Building The Ship of Harkinian
 
-Refer to the [building instructions](BUILDING.md) to compile SoH.
+If you want to manually compile SoH, please consult the [building instructions](BUILDING.md).
 
 ## Nightly Builds
+If you want to playtest a nightly build, you can find them at the links below. However, keep in mind that these are for playtesting only, and you will likely encounter bugs.  Rarely, these builds will crash.
+
 Nightly builds of Ship of Harkinian are available here: [Windows](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-windows.zip), [macOS](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-mac.zip), [Linux (compatibility*)](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-linux-compatiblity.zip), [Linux (performance*)](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-linux-performance.zip), [Switch](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-switch.zip), [Wii U](https://nightly.link/HarbourMasters/Shipwright/workflows/generate-builds/develop/soh-wiiu.zip)
 
 _*compatibility: compatible with most Linux distributions, but may not be as performant as the perf build._\
-_*performance: requires glibc 2.35 or newer, but will be more performant than the compat build._
+_*performance: requires `glibc 2.35` or newer, but will be more performant than the compat build._
 
 ## Take The Survey
-Want to use cartridge readers in tandem with the OTRGui?
+Want to use cartridge readers in tandem with OTRGui?
 Take [this survey](https://retroarchopenhardware.com/survey.php) to increase chances of this becoming reality.
 
 ## The Harbour Masters Are...