Improve advanced contribution readme and experience

ASM/.gitignore

@@ -1,5 +1,6 @@
 /inject
 /roms/*
+/tools/*
 /c/*.o
 armips*
 !.gitkeep

ASM/README.md

@@ -1,11 +1,55 @@
-- Download the armips assembler: <https://github.com/Kingcom/armips>, build it if necessary, and put the executable in the `tools` directory, or somewhere in your PATH.
+Advanced modifications to the Randomzier source require a bit more software than what is needed for running it.
+
+## Assembly: armips
+### Windows Prerequisite
+- Download and install the [Visual Studio 2015-202x Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022) package.
+  - You will want the x64 Architecture version.
+  - This is to run the automated build of armips. If you plan to compile it yourself you can ignore this, but that is an advanced setup not covered here.
+### Running
+- Download the armips assembler: <https://github.com/Kingcom/armips>
+  - [Windows automated builds](https://buildbot.orphis.net/armips/)
+  - On other platforms you'll need either `clang` or `gcc`, `cmake`, and either `ninja` or `make` installed. All of these should be available in the package repositories of every major Linux distribution and Homebrew on macOS. After, follow the [building from source instructions](https://github.com/Kingcom/armips#22-building-from-source).
+- Put the armips executable in the `tools` directory, or somewhere in your PATH.
 - Put the ROM you want to patch at `roms/base.z64`. This needs to be an uncompressed ROM; OoTRandomizer will produce one at ZOOTDEC.z64 when you run it with a compressed ROM.
 - Run `python build.py`, which will:
   - create `roms/patched.z64`
   - update some `txt` files in `build/` and in `../data/generated/`. Check `git status` to see which ones have changed. Make sure you submit them all together!
 
-To recompile the C modules, use the `--compile-c` option. This requires the N64 development tools to be installed: <https://github.com/glankk/n64>
+## C: n64 toolchain
+### Prerequisites
+Recompiling the C code for randomizer requires the N64 development tools to be installed: <https://github.com/glankk/n64>. There are several ways to do this depending on your platform.
+- **Windows**:
+  - **Without WSL**: [Download this zip archive](https://discord.com/channels/274180765816848384/442752384834469908/1085678948614144081) and extract the `n64` folder into the `tools` directory alongside armips.
+    - Download and install [MSYS2](https://www.msys2.org/#installation).
+      1. Accept the defaults in the installer.
+      2. After the installer completes a terminal window will open.
+      3. In the terminal type `pacman -Syy make` and press Enter.
+      4. Make sure it lists `make` for installation and press Enter again to confirm.
+      5. After the installation finishes you can close the terminal window.
+      6. In the Start search bar type "Environment Variables" and click "Edit the system environment variables".
+      7. Near the bottom click on the button labeled "Environment Variables...".
+      8. In the new window in the top section look for the variable called "Path" and click it.
+      9. Click the "Edit..." button below the box you selected "Path" in.
+      10. Click on "New" on the right side of the new window.
+      11. Type `C:\msys64\usr\bin` and press Enter.
+      12. Click "OK" on all three windows.
+      13. You will now be able to compile the randomizer's C code from CMD, PowerShell, and MSYS2's terminal.
+  - **Using WSL**: Install the latest Debian Linux from the Windows Store and follow the below instructions for Debian.
+- **Debian**: [Follow this how-to](https://practicerom.com/public/packages/debian/howto.txt) on adding the toolchain's package repository and installing the pre-built binaries.
+  - You will also need to run `apt install build-essential` or `apt install make` if `make` is not installed.
+- **Any platform with a gcc compiler**: Build from source from the [glankk/n64](https://github.com/glankk/n64) repository. Simply follow the readme.
+  - The dependency install script may not install all the necessary libraries depending on your OS version. Take a look at the output from the configure step to see if anything is missing.
+  - It is easiest if you use `--prefix=/the/path/to/OoT-Randomizer/ASM/tools` for the `./configure` step. This will install all the toolchain in a way the build script can use, however this is inconvenient if you plan to use the toolchain for other projects as well.
+  - If you are trying to update the toolchain this way, it is easiest to just delete your local copy of the repository and clone it again to ensure all the packages get updated and are compatible.
+
+
+You can substitute using the `tools` folder with adding the `n64/bin` folder to your environment PATH if you need an advanced setup.
+### Running
+To recompile the C modules, use `python build.py --compile-c` in this directory, or adjust the path to `build.py` relative to your terminal's working directory.
+
+## Debugging Symbols for Project64
+To generate symbols for the Project64 debugger, use the `--pj64sym` option:
 
-To generate symbols for the Project 64 debugger, use the `--pj64sym` option:
+    python build.py --pj64sym 'path_to_pj64/Saves/THE LEGEND OF ZELDA.sym'
 
-    python build.py --pj64sym 'path_to_pj64/Saves/THE LEGEND OF ZELDA.sym'
+You'll need to disable `Unique Game Save Directory` in Project64 for these to work without copying them into each unique save folder. Remember that some changes in code will not be reflected in an existing save, and they need to be deleted and a new save created with this setting disabled.

ASM/build.py

@@ -12,7 +12,7 @@
 from crc import calculate_crc
 
 parser = argparse.ArgumentParser()
-parser.add_argument('--pj64sym', help="Output path for PJ64 debugging symbols")
+parser.add_argument('--pj64sym', help="Output path for Project64 debugging symbols")
 parser.add_argument('--compile-c', action='store_true', help="Recompile C modules")
 parser.add_argument('--dump-obj', action='store_true', help="Dumps extra object info for debugging purposes. Does nothing without --compile-c")
 parser.add_argument('--diff-only', action='store_true', help="Creates diff output without running armips")
@@ -25,7 +25,11 @@
 
 root_dir = os.path.dirname(os.path.realpath(__file__))
 tools_dir = os.path.join(root_dir, 'tools')
-os.environ['PATH'] = tools_dir + os.pathsep + os.environ['PATH']
+# Makes it possible to use the "tools" directory as the prefix for the toolchain
+tools_bin_dir = os.path.join(tools_dir, 'bin')
+# Makes it possible to copy the full toolchain prefix into the "tools" directory
+n64_bin_dir = os.path.join(tools_dir, "n64", "bin")
+os.environ['PATH'] = tools_dir + tools_bin_dir + n64_bin_dir + os.pathsep + os.environ['PATH']
 
 run_dir = root_dir
 

README.md

@@ -36,7 +36,7 @@ the user wishes a pre-decompressed ROM may be supplied as input. Please be sure
 playing via any means other than on real N64 hardware, the use of the "Compress patched ROM" flag is strongly encouraged as uncompressed ROMs are
 impossible to inject for the Virtual Console and have random crashing problems on all emulators.
 
-For general use, there are four recommended emulators: [Project 64 (v3.0+)](https://wiki.ootrandomizer.com/index.php?title=Project64), [Bizhawk](https://wiki.ootrandomizer.com/index.php?title=Bizhawk), [RetroArch](https://wiki.ootrandomizer.com/index.php?title=Retroarch) and [Dolphin (latest beta)](https://wiki.ootrandomizer.com/index.php?title=Dolphin). All are race-legal when configured appropriately.
+For general use, there are four recommended emulators: [Project64 (v3.0+)](https://wiki.ootrandomizer.com/index.php?title=Project64), [Bizhawk](https://wiki.ootrandomizer.com/index.php?title=Bizhawk), [RetroArch](https://wiki.ootrandomizer.com/index.php?title=Retroarch) and [Dolphin (latest beta)](https://wiki.ootrandomizer.com/index.php?title=Dolphin). All are race-legal when configured appropriately.
 In a nutshell the differences are:
 * Project64 is the lightest emulator and the easiest to setup, however, you will need the 3.0.0 version or later to run OoTR well (and earlier versions are not permitted for use in OoTR races).
 * Bizhawk is the most resource-intensive, but easier to set up than RetroArch and the only race-legal emulator to support [Multiworld](https://wiki.ootrandomizer.com/index.php?title=Multiworld).
@@ -101,7 +101,7 @@ Unfortunately, a few known issues exist. These will hopefully be addressed in fu
 * The fishing minigame sometimes refuses to allow you to catch fish when playing specifically on Bizhawk. Save and Hard Reset (NOT savestate) and return to fix the
 issue. You should always Hard Reset to avoid this issue entirely.
 * Versions older than 3.0 of Project64 have known compatablity issues with OoTR. To avoid this either 
-[update to v3.0 and follow the rest of our PJ64 guide](https://wiki.ootrandomizer.com/index.php?title=Project64) or change to one of our other two supported emulators.
+[update to v3.0 and follow the rest of our Project64 guide](https://wiki.ootrandomizer.com/index.php?title=Project64) or change to one of our other two supported emulators.
 * Executing the collection delay glitch on various NPCs may have unpredictable and undesirable consequences.
 * This randomizer is based on the 1.0 version of _Ocarina of Time_, so some of its specific bugs remain.