From 48180070899b44d2451ce16f1ae244c17cb7ae61 Mon Sep 17 00:00:00 2001 From: Zach Hilman Date: Tue, 2 Oct 2018 16:30:34 -0400 Subject: [PATCH] Add new guides --- site/content/help/features/modding.md | 42 +++++++++++ site/content/help/quickstart/quickstart.md | 54 ++++++++++++++ site/content/help/reference/errors.md | 84 ++++++++++++++++++++++ 3 files changed, 180 insertions(+) create mode 100644 site/content/help/features/modding.md create mode 100644 site/content/help/quickstart/quickstart.md create mode 100644 site/content/help/reference/errors.md diff --git a/site/content/help/features/modding.md b/site/content/help/features/modding.md new file mode 100644 index 00000000..a07c3b36 --- /dev/null +++ b/site/content/help/features/modding.md @@ -0,0 +1,42 @@ +# Game Modding + +Yuzu has a powerful modding framework allowing for multiple formats of patches, flexibility in distribution, and easy organization and change. + +### Directory Structure + +The following is an example of a mod in yuzu. Each one is its own directory within the Mod Data dir that can be opened by right-clicking on the game in yuzu (alternatively `%YUZU_DIR%/load/`) +``` +mod_directory + - exefs + - romfs + - romfs_ext + ``` + + ##### ExeFS + The ExeFS dir contains patches for the game's executable(s). These types of mods typically alter game behavior or logic. Currently this translates to two types of patches: IPS and IPSwitch. To use an IPS patch, create a file with the NSO build ID as the name and `.ips` as the extension and put it in the ExeFS dir. For IPSwitch, the filename can be whatever you want as long as the extension is `.pchtxt` and it contains a NSO build ID. + + More details on the IPS format can be found on [ZeroSoft](https://zerosoft.zophar.net/ips.php) and [SMWiki](http://old.smwiki.net/wiki/IPS_file_format) and details on the IPSwitch format can be found on the creator's [GitHub repo](https://github.com/3096/ipswitch). + + ##### RomFS + The RomFS dir contains replacements for the game's assets and general files. These types of mods typically alter a game's textures, text, fonts, sounds, or other graphical assets. If this directory is not empty, yuzu will combine the contents of it with the base game with files from this directory taking precedence over the base. This technique is called LayeredFS. It is important to note that for this to work properly the directory structure of the game has to be mirrored in this dir. + + It is much easier to get started with a RomFS mod than an ExeFS mod. To dump the game's RomFS, right-click on the game and select `Dump RomFS`. Selecting full will extract everything while skeleton will only create the directories. The output of this will be opened after the dump and can be found at `%YUZU_DIR%/dump/`. + + ##### RomFS Extension (romfs_ext) + The RomFS Extension dir contains patches and stubs for romfs files. This allows modders to delete files within the romfs if a file of the same name but the extension `.stub` is found at the same directory within `romfs_ext`. Similarly, if a file with the same name but with extension `.ips` is found at the same directory within `romfs_ext`, the base game file will be patched with it. + + ### Example + + For example, lets examine Splatoon 2, a popular game for modding. + + Since Splatoon 2's title id is `01003BC0000A0000`, all of our mods for this game will go in `%YUZU_DIR%/load/01003BC0000A0000`. + + Say we have two mods to play with, Mod X and Mod Y. Therefore, we would make two directories in the `01003BC0000A0000` folder, one called "Mod X" and one called "Mod Y". + + Within the "Mod X" folder, there are the `exefs`, `romfs`, and `romfs_ext` directories provided by the author. It is okay to omit one (or more) of them if it is empty. Additionally, if the mod folder is empty yuzu will ignore it. + + ### Conclusion + If you are a modder looking to distribute mods for yuzu and have another question or found part of this guide confusing, feel free to come ask in out discord. + + If you are a user trying to install a mod for yuzu and it seems like a critical piece of the puzzle is missing, try asking the mod author for help. Otherwise, feel free to come ask in the discord. + diff --git a/site/content/help/quickstart/quickstart.md b/site/content/help/quickstart/quickstart.md new file mode 100644 index 00000000..b5a19e7e --- /dev/null +++ b/site/content/help/quickstart/quickstart.md @@ -0,0 +1,54 @@ +# yuzu Quickstart Guide + +To start playing games, yuzu needs a couple of different files and directoires from your switch in order to play them properly. + +This guide will help you copy all of your system files, games, updates, and DLC from your switch to your computer and organize them in a format yuzu understands. This process should take about an hour to an hour and a half. + +## Prerequisites +- A Nintendo Switch vulnerable to fusee-gelee +- An SD card with at least ~29 GB of free space (an almost empy 32GB card will work) +- [biskeydump](https://files.sshnuke.net/biskeydumpv6.zip) +- [hekate](https://github.com/CTCaer/hekate/releases/download/v3.2/hekate_ctcaer_3.2.bin) +- [Joiner Scripts](https://github.com/CTCaer/hekate/releases/download/v3.2/joiner_scripts_for_windows_linux_macos.zip) +- [HacDiskMount](https://files.sshnuke.net/HacDiskMount1055.zip) + +You will also need to know how to run RCM payloads on your switch, which is detailed [here](https://gbatemp.net/threads/how-to-boot-hekate-ipl-using-ctcaers-hekate-mod.507619/), except in that guide when it says to use hekate's bin use the one required by that step in this guide. + +`%YUZU_DIR%` is the home directory for yuzu on your computer: + - For Windows, this is `C:\Users\<YourUserName>\AppData\Roaming\yuzu` + - For Linux, this is `~/.local/share/yuzu` + +## Directions +1. Download this [keys template](). It will help make sure you don't miss anything in the next steps. +2. Launch biskeydump on your switch using RCM (Follow the guide in prerequisites but replace the hekate bin with biskeydump.bin). If the background of the QR code is red, retry until it is blue. You can scan the QR code for convenience or copy the codes by typing them into your computer. Copy the keys template from step 1 into `%YUZU_DIR%/keys` and make sure it is still named `console.keys`. In it, replace the large `XXXX...XXX` strings with the corresponding key from biskeydump. + You should have copied: + - `tsec_key` + - `bis_key_0_crypt` + - `bis_key_0_tweak` + - `bis_key_1_crypt` + - `bis_key_1_tweak` + - `bis_key_2_crypt` + - `bis_key_2_tweak` +3. Launch hekate on your switch using RCM (Follow the guide in prerequisites exactly, using hekate's bin). + - 3a. Go to the tools menu and select `Tools > Dump package1`. Once that is complete select `Tools > Backup > Dump eMMC BOOT`. Then select `Console > Dump fuses`. Finally select `Tools > Backup > Dump eMMC GPP`. This last one will take 20-40 minutes depending on your sd card. Go get a latte and come back then. + - 3b. Open your sd card on your computer side by side with `%YUZU_DIR%/sysdata` + - 3c. Copy the following files from your sd card into `sysdata`: + - `fuse.bin` + - 3d. Open the folder called backup on your sd card and then open the first directory in that. Copy the following files from that directory into `sysdata`: + - `BOOT0` + - `pkg1/secmon.bin` + - `pkg1/pkg1_decr.bin` + - 3d. Copy all of the files starting with `rawnand.bin.` and ending in a two-digit number to a folder somewhere on your computer. +4. Select all of the rawnand.bin files from step 3d and drag them onto the joiner script downloaded earlier. This should take some time depending on you system, but you will be left with a single `rawnand.bin`. You can delete any of the files ending in two-digits at this point. +5. Open HacDiskMount and go to File > Open and select the rawnand.bin from step 4. + - 5a. Double-click on the row marked `PRODINFO`. Under the export to file area, click browse and locate your yuzu sysdata dir (`%YUZU_DIR%/sysdata`). Save the file as `PRODINFO.bin`. Click start and wait for it to complete. Then close the dialog. (NOTE: There is no need to enter any keys in the boxes at the top of the dialog at this moment.) + - 5b. Repeat step 5a with the row named `BCPKG2-1-Normal-Main`. Save it into the same directory with the name `BCPKG2-1-Normal-Main.bin`. Again, no keys are necessary at this point. + - 5c. Double-click on the row named `SYSTEM`. In the keys boxes, enter `bis_key2_crypt` in the top one and `bis_key2_tweak` in the bottom one and click test. If the text is red, double check your keys. Click on `Install Driver` and then click `Mount`. The application may become unresponsive for a moment. In the new drive (default Z:), there will be a couple of folders with some named `Contents`, `save`, and `saveMeta`. Copy all of these into `%YUZU_DIR%/nand/system`. + - 5d. Repeat step 5c with the row named `USER`. Enter the same key. This time you should not have to install the driver again. Once this mounts, copy the `Contents` and `save` folders to `%YUZU_DIR%/nand/user`. +6. (OPTIONAL) If you have games or game data stored on your sd card, copy the `Nintendo` folder of your sd card into `%YUZU_DIR%/sdmc`. +7. Open yuzu. You should see a dialog with a progress bar informing you that your keys are being derived. If you get a missing file error message, double check the files in your `sysdata` dir and try again. If there is no errors, a message informing you that it was successful will show and then yuzu will refresh to show you your games. + +### If you need any help during this process or get a strange error during or while using yuzu, feel free to ask for help on the yuzu discord! Happy Emulating! + +## Notes +- Should you need to re-run this process (in the event of a firmware update or new games), you can simply update the sysdata files and then go to `Help > Reinitialize keys...`. \ No newline at end of file diff --git a/site/content/help/reference/errors.md b/site/content/help/reference/errors.md new file mode 100644 index 00000000..fc553305 --- /dev/null +++ b/site/content/help/reference/errors.md @@ -0,0 +1,84 @@ +#### To use this list, press Ctrl-F and then type in the error code from yuzu. This should look similar to `XXXX-XXXX` where the Xs represent numbers and letters. + +#### Key Errors +##### Please use the general how-to guide, which includes instructions on dumping the necessary files from your switch to have yuzu derive all of your keys, +##### For all: If you try to run recent games and you haven't done the key derivation process recently, you may need to redump and rerun it as newer games use newer keys only available on newer firmwares. Getting an incorrect key means you might have a bad dump of your switch's files. Try again and if it persists, contact the discord. If you are missing the titlekey or an update won't load, sometimes updates change the titlekey between versions -- either way redump and if that doesn't work contact the discord/devs. +| Error Code | Name | +| ---------- | ---- | +| `0008-000C` | `ErrorMissingProductionKeyFile` | +| `0008-000D` | `ErrorMissingHeaderKey` | +| `0008-000E` | `ErrorIncorrectHeaderKey` | +| `0008-0011` | `ErrorMissingTitlekey` | +| `0008-0012` | `ErrorMissingTitlekek` | +| `0008-0014` | `ErrorMissingKeyAreaKey` | +| `0008-0015` | `ErrorIncorrectKeyAreaKey` | +| `0008-0016` | `ErrorIncorrectTitlekeyOrTitlekek` | +| `0008-0018` | `ErrorNCANotProgram` | + +#### Other Common Errors +| Error Code | Name | +| ---------- | ---- | +| `0008-001C` | `ErrorNullFile` <br> The file your are trying to use is empty and contains no data. This is a sign of a bad copy or corrupt storage device. | +| `0008-001D` | `ErrorMissingNPDM` <br> Ensure that your rom directory has a file called `main.npdm`. This is used to determine key info about how to run the game and is required to run. You may need to redump if you deleted this. | +| `0008-001E` | `Error32BitISA` <br> The game you are trying to run uses the 32-bit ARM architecture, which is not currently supported by yuzu. | +| `0008-0029` | `ErrorNAXInconvertibleToNCA` <br> The NAX file you are trying to run is not a game but in fact a save file. Double check your files. | +| `0008-002A` | `ErrorBadNAXFilePath` <br> You can only execute games that are NAX encrypted if they are left in the original directory structure from the SD card (`registered/<hex digits>.nca/00`). The hex digits contain needed data to decrypt the game properly. | +| `0008-0039` | `ErrorMissingBKTRBaseRomFS` <br> You are trying to run a game update, which isn't possible. To use a game update, instead go to File > Install file to NAND... and select the update from that menu. After it's done, launch the base game and yuzu will apply the update. | + +#### Corruption Errors - All of these errors are indicative of a bad/corrupt dump. If there are no special instructions, try redumping. Should the error persist contact the devs/discord for help. +| Error Code | Name | +| ---------- | ---- | +| `0008-0004` | `ErrorBadNPDMHeader` | +| `0008-0005` | `ErrorBadACIDHeader` | +| `0008-0006` | `ErrorBadACIHeader` | +| `0008-0007` | `ErrorBadFileAccessControl` | +| `0008-0008` | `ErrorBadFileAccessHeader` | +| `0008-0009` | `ErrorBadPFSHeader` | +| `0008-000A` | `ErrorIncorrectPFSFileSize` | +| `0008-0013` | `ErrorInvalidRightsID` | +| `0008-0017` | `ErrorXCIMissingProgramNCA` <br> In some rare cases, this has been known to appear with missing keys. Try rederiving your keys and if that dosen't work contact the devs. | +| `0008-0019` | `ErrorNoExeFS` | +| `0008-001A` | `ErrorBadXCIHeader` | +| `0008-001B` | `ErrorXCIMissingPartition` <br> If you trimmed your XCI, it might have been done improperly. Try avoiding trimming. | +| `0008-001F` | `ErrorNoRomFS` | +| `0008-0020` | `ErrorIncorrectELFFileSize` | +| `0008-0021` | `ErrorLoadingNRO` | +| `0008-0022` | `ErrorNoIcon` | +| `0008-0023` | `ErrorNoControl` | +| `0008-0024` | `ErrorBadNAXHeader` | +| `0008-0025` | `ErrorIncorrectNAXFileSize` | +| `0008-0031` | `ErrorNSPMissingProgramNCA` | +| `0008-0032` | `ErrorBadBKTRHeader` | + +#### Less Common General Errors - You should not expect to see these unless you are doing more than just playing games +| Error Code | Name | +| ---------- | ---- | +| `0008-000F` | `ErrorNCA2` <br> The NCA you are attempting to load is using an older format that is not currently supported. If you would like support to be added, consider filing an issue. | +| `0008-0010` | `ErrorNCA0` <br> The NCA you are attempting to load is using an older format that is not currently supported. If you would like support to be added, consider filing an issue. | + +#### Less Common Key Errors - Below errors should not be obtained if using the normal key derivation process (which is highly encouraged for newcomers), but if you are not using it these errors will make sense to you. +| Error Code | Name | +| ---------- | ---- | +| `0008-002B` | `ErrorMissingSDSeed` | +| `0008-002C` | `ErrorMissingSDKEKSource` | +| `0008-002D` | `ErrorMissingAESKEKGenerationSource` | +| `0008-002E` | `ErrorMissingAESKeyGenerationSource` | +| `0008-002F` | `ErrorMissingSDSaveKeySource` | +| `0008-0030` | `ErrorMissingSDNCAKeySource` | + +#### Internal Errors - Should never be seen ever. Report to the devs immediately. +| Error Code | Name | +| ---------- | ---- | +| `0008-0000` | `Success` | +| `0008-0001` | `ErrorAlreadyLoaded` | +| `0008-0002` | `ErrorNotImplemented` | +| `0008-0003` | `ErrorNotInitialized` | +| `0008-0026` | `ErrorNAXKeyHMACFailed` | +| `0008-0027` | `ErrorNAXValidationHMACFailed` | +| `0008-0028` | `ErrorNAXKeyDerivationFailed` | +| `0008-0033` | `ErrorBKTRSubsectionNotAfterRelocation` | +| `0008-0034` | `ErrorBKTRSubsectionNotAtEnd` | +| `0008-0035` | `ErrorBadRelocationBlock` | +| `0008-0036` | `ErrorBadSubsectionBlock` | +| `0008-0037` | `ErrorBadRelocationBuckets` | +| `0008-0038` | `ErrorBadSubsectionBuckets` |