From 286dfd84c096c2cf6e3b594722a82b38a2a4601d Mon Sep 17 00:00:00 2001 From: Yussur Mustafa Oraji Date: Thu, 23 Nov 2023 19:10:32 +0100 Subject: [PATCH] sm64ex: Replace old launcher tutorial (#2383) --- worlds/sm64ex/docs/setup_en.md | 87 ++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 41 deletions(-) diff --git a/worlds/sm64ex/docs/setup_en.md b/worlds/sm64ex/docs/setup_en.md index 38edeb2c4ab6..2817d3c324c0 100644 --- a/worlds/sm64ex/docs/setup_en.md +++ b/worlds/sm64ex/docs/setup_en.md @@ -2,71 +2,77 @@ ## Required Software -- Super Mario 64 US Rom (Japanese may work also. Europe and Shindou not supported) +- Super Mario 64 US or JP Rom (Europe and Shindou not supported) - Either of - - [sm64pclauncher](https://github.com/N00byKing/sm64pclauncher/releases) or + - [SM64AP-Launcher](https://github.com/N00byKing/SM64AP-Launcher/releases) or - Cloning and building [sm64ex](https://github.com/N00byKing/sm64ex) manually - Optional, for sending [commands](/tutorial/Archipelago/commands/en) like `!hint`: the TextClient from [the most recent Archipelago release](https://github.com/ArchipelagoMW/Archipelago/releases) -NOTE: The above linked sm64pclauncher is a special version designed to work with the Archipelago build of sm64ex. +NOTE: The above linked launcher is a special version designed to work with the Archipelago build of sm64ex. You can use other sm64-port based builds with it, but you can't use a different launcher with the Archipelago build of sm64ex. ## Installation and Game Start Procedures -### Installation via sm64pclauncher (For Windows) +### Installation via SM64AP-Launcher + +*Windows Preparations* First, install [MSYS](https://www.msys2.org/) as described on the page. DO NOT INSTALL INTO A FOLDER PATH WITH SPACES. -Do all steps up to including step 6. -Best use default install directory. -Then follow the steps below - -1. Go to the page linked for sm64pclauncher, and press on the topmost entry -3. Scroll down, and download the zip file -4. Unpack the zip file in an empty folder -5. Run the Launcher and press build. -6. Set the location where you installed MSYS when prompted. Check the "Install Dependencies" Checkbox -7. Set the Repo link to `https://github.com/N00byKing/sm64ex` and the Branch to `archipelago` (Top two boxes). You can choose the folder (Secound Box) at will, as long as it does not exist yet -8. Point the Launcher to your Super Mario 64 US/JP Rom, and set the Region correspondingly -9. Set Build Options and press build. - - Recommended: To build faster, use `-jn` where `n` is the number of CPU cores to use (e.g., `-j4` to use 4 cores). - - Optional: Add options from [this list](https://github.com/sm64pc/sm64ex/wiki/Build-options), separated by spaces (e.g., `-j4 BETTERCAMERA=1`). -10. SM64EX will now be compiled. The Launcher will appear to have crashed, but this is not likely the case. Best wait a bit, but there may be a problem if it takes longer than 10 Minutes - -After it's done, the Build list should have another entry titled with what you named the folder in step 7. - -NOTE: For some reason first start of the game always crashes the launcher. Just restart it. -If it still crashes, recheck if you typed the launch options correctly (Described in "Joining a MultiWorld Game") +It is extremely encouraged to use the default install directory! +Then continue to `Using the Launcher` + +*Linux Preparations* + +You will need to install some dependencies before using the launcher. +The launcher itself needs `qt6`, `patch` and `git`, and building the game requires `sdl2 glew cmake python make` (If you install `jsoncpp` as well, it will be linked dynamically). +Then continue to `Using the Launcher` + +*Using the Launcher* + +1. Go to the page linked for SM64AP-Launcher, and press on the topmost entry +2. Scroll down, and download the zip file for your OS. +3. Unpack the zip file in an empty folder +4. Run the Launcher. On first start, press `Check Requirements`, which will guide you through the rest of the needed steps. + - Windows: If you did not use the default install directory for MSYS, close this window, check `Show advanced options` and reopen using `Re-check Requirements`. You can then set the path manually. +5. When finished, use `Compile default SM64AP build` to continue + - Advanced user can use `Show advanced options` to build with custom makeflags (`BETTERCAMERA`, `NODRAWINGDISTANCE`, ...), different repos and branches, and game patches such as 60FPS, Enhanced Moveset and others. +6. Press `Download Files` to prepare the build, afterwards `Create Build`. +7. SM64EX will now be compiled. This can take a while. + +After it's done, the build list should have another entry with the name you gave it. + +NOTE: If it does not start when pressing `Play selected build`, recheck if you typed the launch options correctly (Described in "Joining a MultiWorld Game") ### Manual Compilation (Linux/Windows) -*Windows Instructions* +*Windows Preparations* First, install [MSYS](https://www.msys2.org/) as described on the page. DO NOT INSTALL INTO A FOLDER PATH WITH SPACES. -After launching msys2, and update by entering `pacman -Syuu` in the command prompt. Next, install the relevant dependencies by entering `pacman -S unzip mingw-w64-x86_64-gcc mingw-w64-x86_64-glew mingw-w64-x86_64-SDL2 git make python3 mingw-w64-x86_64-cmake`. SM64EX will link `jsoncpp` dynamic if installed. If not, it will compile and link statically. +After launching msys2 using a MinGW x64 shell (there should be a start menu entry), update by entering `pacman -Syuu` in the command prompt. Next, install the relevant dependencies by entering `pacman -S unzip mingw-w64-x86_64-gcc mingw-w64-x86_64-glew mingw-w64-x86_64-SDL2 git make python3 mingw-w64-x86_64-cmake`. -After this, obtain the code base by cloning the relevant repository manually via `git clone --recursive https://github.com/N00byKing/sm64ex`. Ready your ROM by copying your legally dumped rom into your sm64ex folder (if you are not sure where your folder is located, do a quick Windows search for sm64ex). The name of the ROM needs to be `baserom.REGION.z64` where `REGION` is either `us` or `jp` respectively. +Continue to `Compiling`. -After all these preparatory steps have succeeded, type `make` in your command prompt and get ready to wait for a bit. If you want to speed up compilation, tell the compiler how many CPU cores to use by using `make -jn` where n is the number of cores you want. +*Linux Preparations* -After the compliation was successful, there will be a binary in your `sm64ex/build/REGION_pc/` folder. +Install the relevant dependencies `sdl2 glew cmake python make patch git`. SM64EX will link `jsoncpp` dynamic if installed. If not, it will compile and link statically. -*Linux Instructions* +Continue to `Compiling`. -Install the relevant dependencies `sdl2 glew cmake python make`. SM64EX will link `jsoncpp` dynamic if installed. If not, it will compile and link statically. +*Compiling* -After this, obtain the code base by cloning the relevant repository manually via `git clone --recursive https://github.com/N00byKing/sm64ex`. Ready your ROM by copying your legally dumped rom into your sm64ex folder. The name of the ROM needs to be `baserom.REGION.z64` where `REGION` is either `us` or `jp` respectively. +Obtain the code base by cloning the relevant repository via `git clone --recursive https://github.com/N00byKing/sm64ex`. Copy your legally dumped rom into your sm64ex folder (if you are not sure where your folder is located, do a quick Windows search for sm64ex). The name of the ROM needs to be `baserom.REGION.z64` where `REGION` is either `us` or `jp` respectively. -After all these preparatory steps have succeeded, type `make` in your command prompt and get ready to wait for a bit. If you want to speed up compilation, tell the compiler how many CPU cores to use by using `make -jn` where n is the number of cores you want. +After all these preparatory steps have succeeded, type `cd sm64ex && make` in your command prompt and get ready to wait for a bit. If you want to speed up compilation, tell the compiler how many CPU cores to use by using `make -jn` instead, where n is the number of cores you want. After the compliation was successful, there will be a binary in your `sm64ex/build/REGION_pc/` folder. ### Joining a MultiWorld Game To join, set the following launch options: `--sm64ap_name YourName --sm64ap_ip ServerIP:Port`. +For example, if you are hosting a game using the website, `YourName` will be the name from the Settings Page, `ServerIP` is `archipelago.gg` and `Port` the port given on the Archipelago room page. Optionally, add `--sm64ap_passwd "YourPassword"` if the room you are using requires a password. -The Name in this case is the one specified in your generated .yaml file. -In case you are using the Archipelago Website, the IP should be `archipelago.gg`. +Should your name or password have spaces, enclose it in quotes: `"YourPassword"` and `"YourName"`. Should the connection fail (for example when using the wrong name or IP/Port combination) the game will inform you of that. Additionally, any time the game is not connected (for example when the connection is unstable) it will attempt to reconnect and display a status text. @@ -81,7 +87,7 @@ Create a room and download the `.apsm64ex` file, and start the game with the `-- ### Optional: Using Batch Files to play offline and MultiWorld games -As an alternative to launching the game with sm64pclauncher, it is also possible to launch the completed build with the use of Windows batch files. This has the added benefit of streamlining the join process so that manual editing of connection info is not needed for each new game. However, you'll need to be somewhat comfortable with creating and using batch files. +As an alternative to launching the game with SM64AP-Launcher, it is also possible to launch the completed build with the use of Windows batch files. This has the added benefit of streamlining the join process so that manual editing of connection info is not needed for each new game. However, you'll need to be somewhat comfortable with creating and using batch files. IMPORTANT NOTE: The remainder of this section uses copy-and-paste code that assumes you're using the US version. If you instead use the Japanese version, you'll need to edit the EXE name accordingly by changing "sm64.us.f3dex2e.exe" to "sm64.jp.f3dex2e.exe". @@ -91,7 +97,7 @@ Open Notepad. Paste in the following text: `start sm64.us.f3dex2e.exe --sm64ap_f Go to File > Save As... -Navigate to the folder you selected for your SM64 build when you followed the Build guide for SM64PCLauncher earlier. Once there, navigate further into `build` and then `us_pc`. This folder should be the same folder that `sm64.us.f3dex2e.exe` resides in. +Navigate to the folder you selected for your SM64 build when you followed the Build guide for SM64AP-Launcher earlier. Once there, navigate further into `build` and then `us_pc`. This folder should be the same folder that `sm64.us.f3dex2e.exe` resides in. Make the file name `"offline.bat"` . THE QUOTE MARKS ARE IMPORTANT! Otherwise, it will create a text file instead ("offline.bat.txt"), which won't work as a batch file. @@ -120,8 +126,8 @@ To use this batch file, double-click it. A window will open. Type the five-digi - The port number is provided on the room page. The game host should share this page with all players. - The slot name is whatever you typed in the "Name" field when creating a config file. All slot names are visible on the room page. -Once you provide those two bits of information, the game will open. If the info is correct, when the game starts, you will see "Connected to Archipelago" on the bottom of your screen, and you will be able to enter the castle. -- If you don't see this text and crash upon entering the castle, try again. Double-check the port number and slot name; even a single typo will cause your connection to fail. +Once you provide those two bits of information, the game will open. +- If the game only says `Connecting`, try again. Double-check the port number and slot name; even a single typo will cause your connection to fail. ### Addendum - Deleting old saves @@ -170,6 +176,5 @@ Should the problem still be there after about a minute or two, just save and res ### How do I update the Game to a new Build? +When using the Launcher follow the normal build steps, but when choosing a folder name use the same as before. The launcher will recognize this, and offer to replace it. When manually compiling just pull in changes and run `make` again. Sometimes it helps to run `make clean` before. - -When using the Launcher follow the normal build steps, but when choosing a folder name use the same as before. Then continue as normal.