Help:Tools/UKMM

UKMM

Author(s)	Nicene Nerd, Ginger
Source code	https://github.com/GingerAvalanche/ukmm
License	GPLv3+
Written in	Rust
Platform support	Cross-platform

UKMM (UKing Mod Manager) is an updated mod manager for BotW. It is used to install and uninstall mods, and solves many mod conflicts. It was created to solve bugs that fundamentally couldn't be solved by BCML, due either to limitations in the Python programming language or early design choices in BCML.

Installation

Prebuilt program

Unlike BCML, installing UKMM is simple

1. Download the executable archive for your system from the current UKMM releases page
2. Extract the executable from the archive to just about anywhere on your computer
3. Run the executable

Building from source

If for some reason the prebuilt binaries don't work for you, or you just want to build it for your own personal reasons, here are the exhaustive directions for doing so

1. Install Rust: you can do this on Linux and macOS by opening a terminal and running the command curl –proto ‘=https’ –tlsv1.2 -sSf https://sh.rustup.rs | sh - what this does is download the rustup tool for managing and building Rust applications. It will ask you to enter a number, 1-3. You want to type 1 and then hit enter. You can do this on Windows by using the setup exe located here
2. Install CMake: you can do this on macOS by installing the dmg for your system, on Linux by running the sh for your system, and on Windows by installing the msi for your system, all available from here. On macOS, you may also need to run the terminal command sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install to allow Rust to use CMake.
3. Download the source code (either zip or tar.gz) from the latest release on the releases page
4. Extract the source code somewhere. It doesn't matter where. It could be on your desktop, if you want
5. Go into the folder. You know you're in the folder when you see things like assets, book, crates, src, etc in your finder window
6. - On macOS, control-click the folder name in the path bar, and select Open in Terminal (If the path bar isn't visible, select View -> Show Path Bar). On Steam Deck, open Konsole and then use the cd [path] command (replace [path] with whatever is in the path/address bar in step 5). On Windows, shift-click in empty space inside the folder and select Open PowerShell window here.
7. Enter the command cargo build --release - wait for it to finish. This might take a while
8. Go into the target folder
9. Go into the release folder
10. Run the file called ukmm

Setup

There are three methods of setup, depending on whether you are coming from BCML or not, and if not, if you are using Cemu and have set it up already.

Note for Non-Native English Speakers

Make sure that you set the UKMM Language setting to your native language (if present). This will help you understand the program and its layout better.

(Yes, I realize that the fact that you don't speak English natively means you may not be able to read this, but hey, maybe you're translating this page, or maybe you can partially read English. I'm not judging, here.)

Importing from BCML

If you previously used BCML and it worked for you, congratulations! Your job is easy. Go to the Settings tab, click Migrate from BCML. Wait for it to finish. There you go! All done! Now go to No, really, how do I use it? to learn the simplest way to use UKMM

Not importing from BCML, using Cemu

If you're using Cemu and you've previously seen the 1.5.0 version number in the bottom right of the BotW main menu, just click Import Cemu Settings inside the Wii U Config section, and select the folder that contains the Cemu program. There you go! All done! Now go to No, really, how do I use it? to learn the simplest way to use UKMM

Manual Setup

If neither of the two previous sections applied to you, then you'll need to set UKMM up manually.

General

You should have a dump of your game on your computer. If you do not, go dump your game and come back. Help:Dumping_games

Setting	Description	What you should set it to
Current Mode	Determines which layout of the folders and files UKMM will use	Wii U console or Cemu? Use Wii U. In all other cases, use Switch.
Storage Folder	Where UKMM stores mod data, including mods, profiles, merged data, pending deployment data, etc.	Leave it as the default unless you know what you're doing.
Use System 7z	Uses the version of 7zip installed to your computer, if one is present. Recommended, because the actual 7zip program is faster than UKMM's internal 7zip code.	Checked
Show Changelog	Show a summary of recent changes after UKMM updates	Checked
Language	Which language pack UKMM merges mod text into	Whatever language you have set in your game/emulator. Make sure it is both the same language (the lower-case letters) and region (the upper-case letters).

Game Dump

Setting	Description	What you should set it to
Game Dump (Only WiiU)	How your game files are stored, as an unpacked collection of loose files or as a WUA	Self-explanatory
Base Folder (WiiU Unpacked)	Where you store your Base Game dump.	The folder named content inside your game dump. Should look like C:/some/path/content/, where C:/some/path is something only you know.
Base with Update Folder (Switch)	Where you store your Base with Update Game dump.	The folder named romfs, inside the 01007EF00011E000 folder in your game dump. Should look like C:/some/path/01007EF00011E000/romfs, where C:/some/path is something only you know.
Update Folder (WiiU Unpacked)	Where you store your Update dump.	The folder named content inside your update dump. Should look like C:/some/path/content, where C:/some/path is something only you know.
DLC Folder (WiiU Unpacked)	Where you store your DLC dump.	The folder named 0010, inside the content folder in your DLC dump. Should look like C:/some/path/content/0010, where C:/some/path is something only you know. NOTE: DO NOT END THIS PATH WITH content, IT WILL NOT WORK. END THE PATH WITH 0010!
DLC Folder (Switch)	Where you store your DLC dump.	The folder named romfs, inside the 01007EF00011F001 folder in your DLC dump. Should look like C:/some/path/01007EF00011F001/romfs, where C:/some/path is something only you know. The 01007EF00011F002 dump is not needed.
WUA Path (Only WiiU WUA)	Where you store your game WUA.	The path to your BotW WUA file. This is something only you know.

If using Cemu, the three unpacked path folders can be found by right-clicking on the game in the game list and selecting the appropriate option. For Base and Update, use the content folder. For DLC, use the 0010 folder inside the content folder.

Deployment

Setting	Description	What you should set it to
Deploy Method	How UKMM deploys the mods after they've been merged	Are you on a console? Select Copy. Are you on an emulator? Select Symlink. Do you know what Hard Links mean already? Select that if you think they're superior to Symlinks.
Deploy Layout	Whether or not UKMM includes a personalized folder when it merges mods out	Using with Atmosphere on a Switch or with the Atmosphere mod location for Switch emulators? Without Name. Otherwise, use With Name.
Auto Deploy	Whether UKMM will deploy mods automatically when you click Apply to merge them	Is your Output Folder set to a detachable drive like an SD card? Unchecked. Otherwise, checked.
Deploy rules.txt (Only WiiU)	Deploys a manifest file which allows Cemu to detect the UKMM files	Check it if you are using Cemu. Do not check it if you are not using Cemu.
Output Folder	Where to deploy the merged mod files to, for you to use	See the following list
Emulator Executable (optional)	The command to use to run open your emulator when using the Open Emulator button	A shell command for running your emulator. On Windows, this requires quotes around it at all times. On other OSes, it requires quotes around it if there are spaces in the path. As a shell command, it supports switches, e.g. "C:\path\to\Cemu.exe" -g "C:\path\to\botw\U-King.rpx" will open Cemu and skip the game selection menu, running the game immediately.

When you find the correct folder to use as your output folder, click in the address bar to highlight the path. Ctrl-C to copy the path. Ctrl-V to paste the path in the Output Folder.

Output folder locations:

• SD cards for WiiU: X:\sdcafiine\00050000101C9?00 (where X is the SD card drive letter, and ? is 4 for the US version, 5 for the EU version, 3 otherwise)
• SD cards for Switch: X:\atmosphere\contents (where X is the SD card drive letter). Do not put a title ID, UKMM adds title IDs in Switch mode
• Cemu: Click File -> Open Cemu folder. Go into the folder called graphicPacks. Use this folder.
• RyujiNX: Right-click on BotW in the game list -> Open Mod directory. In the folder that opens, go up one folder, to the contents folder. Use this folder.
• Yuzu (and derivatives): Right click on BotW in the game list -> Open Mod Data Location. In the folder that opens, go up one folder, to the load. Use this folder.

Usage

UKMM 0.15.0's UI

All tabs can be moved around and docked in one of the 4 quarters of the program, which can be resized.

• File: Contains the first method for installing mods. Also a way to exit the program.
• Tools: Contains various options related to the mod files: perform a full remerge, cancel pending changes, or open various folders set in the Settings tab.
• Window: Contains check boxes for every tab. If you close a tab, this is where you can reopen it.
• Help: Contains the About window and a link to the UKMM documentation, which contains in-depth information about just about everything involved with UKMM.
• Mods tab: Contains all of your installed mods. Columns can be clicked to change sort type and direction. Boxes can be (un)checked to (de)activate mods.
• Package tab: Allows you to package a loose file mod as a UKMM zip. NOTE: UKMM zip layout is subject to change on minor version updates, so please be wary of distributing UKMM zips, as they may become uninstallable in future versions. (We believe we're done changing the layout, but there may be unforeseen issues in the future)
• Settings tab: See the above section for explanations of everything in here.
• Info tab: Contains mod description info. Also contains a button for re-selecting options without reinstalling, for mods that include options.
• Install tab: You can either select a mod in the file picker, or use the button to select a mod directly via the classic dialog.
• Log tab: Provides in-depth info about everything that happens when UKMM does anything related to mod files. Also contains information about any errors, if they happen.
• Deploy tab: Contains information about the deploy method and folder, and a button to deploy merged mods to the output folder. NOTE: Button only appears if Auto Deploy is turned off.
• Pending Changes: Review file changes if you'd like, use the Apply button to merge. NOTE: You don't have to merge every time you change anything. Change whatever you want to change, then Apply once.

No, really, how do I use it?

Known Issues

• Certain mods distributed as BNPs will not install with UKMM, due to how they were made. If you find one, please contact Ginger.
• Certain mods distributed as BNPs that add lots of the same thing very close to each other on the map may be missing some of those things. A fix is currently being worked on.

If you can provide in-depth support to the developers on how to cause any of these issues, please contact Ginger on the discord. This would go a long way toward fixing them.

FAQ

Mod Manager-Related Questions

Do I need to use a mod manager?

Yes.

But I install mods manually all the time?

In other games you do. BotW doesn't work the same way. You need to use a mod manager.

Okay. WHY do I need to use a mod manager?

BotW contains about 17,000 archives in its standard form. When those archives are fully and completely decompressed and extracted, the game contains roughly 200,000 files. Most of those 200,000 files contain dozens, even hundreds, of parameters.

If a mod edits just one of those parameters, in one of those files, in one of those archives, then, without a mod manager, that mod will override every other mod that you have that contains that archive. Given that an archive may contain an average of several thousand parameters, you can see how often mods will conflict.

This isn’t even taking into account a special file that BotW has, called the RSTB. The RSTB contains data on almost every one of those 200,000 files, and so almost every mod needs to edit the RSTB. Most mods rely on a mod manager to edit the RSTB, so even if you don’t want to install more than one mod, the odds are still good that the mod you’re installing is assuming you’ll use a mod manager to make it work.

And to top it all off, even if the one mod you want to use includes its own RSTB? That RSTB was probably made automatically, using an outdated tool that generates bad edits for the RSTB. And nobody has ever fixed that tool, because UKMM contains a much more accurate tool for it, that everyone is using anyway.

UKMM vs. BCML Questions

When should I use UKMM as my mod manager, instead of BCML?

Except for a few very rare exceptions, you should always use UKMM.

What are the exceptions, for when I should use BCML instead?

1. You're using Dark Army Resurrection
2. You're using the online multiplayer mod

This list is not exhaustive, but it almost is. There's very few other real reasons to use BCML, after 2024 when UKMM surpassed it.

WHY should I use UKMM instead?

1. It installs BNPs just like BCML does.
2. It's easier to install.
3. If you're using Cemu, or previously used BCML, it's much easier to set up.
4. It gives you more control over where your mods are deployed and how they're deployed there.
5. It merges map changes from the DLC files into the base game, so you can install many mods that only have DLC map files even if you don't have the DLC.
6. It doesn't do unnecessary things, part 1. When you install a mod, all it does is install it. It will only combine it with other mods when you tell it to combine them.
7. It doesn't do unnecessary things, part 2. When you merge/combine mods, it only recombines those files from the mods you've changed since your last combo.
8. It merges any given file faster than BCML can merge the same file.
9. It makes mods more compatible than before, part 1. It merges more file types.
10. It makes mods more compatible than before, part 2. It fixes merging for several file types that BCML had errors with.
11. It generates proper RSTB entries for all assets, resulting in no crashes or panic blood moons related to file size. (Some panic blood moons may remain if you use certain mods that increase the system load by a large amount, but even these mods will be more stable with UKMM)
12. It supports dumps as WUA files if you're using Cemu. (The hope is to also add support for NSP and XCI files with the Switch version, but those still can't be read yet)
13. It is a lot more strict with the files it accepts than BCML is, which means that you are far less likely to see an infinite loading screen or crash.
14. When something goes wrong, it gives the list of things it was doing in a way that is mostly readable by a human, instead of just dumping a bunch of code on you.
15. If English isn't your native language, it (probably) has localization for your language, so that you can understand its UI better.

This list is not exhaustive, but it's long enough that the question is probably sufficiently answered.

But I found a bunch of tutorials for BCML!

Not a question. Also, that's because BCML needed them, because it was difficult to install and set up.

Dump-Related Questions

Do I really need a game dump?

Yes.

Do I REAAAAAALLY need a game dump???

Still yes.

Why do I need a game dump?

BotW stores almost all of its files inside archives. Any given file you can look at using your file explorer will most likely contain dozens of files or more, each of which can contain hundreds of parameters inside it.

In order to properly merge mods, UKMM (and BCML before it) needs to know what the mod actually changes. So it has to compare the mod with the vanilla files in order to determine what is different, so that it can merge only those differences.

It also only stores those differences - and a mod you download from the internet may or may not be only a list of differences. UKMM needs the dump in order to recreate the actual mod files from those differences, once the mod changes have been merged.

There is no functional way around this. Every single mod manager does this on some level. Cyberpunk 2077 mods must be merged with game files. No Man's Sky mods must be merged into game files. Even Bethesda plugins contain only changes, which their games merge directly. Any games in the Unreal Engine do this with pak files, as well. There are only 2 reasons BotW is harder than any of these other games: it doesn't have an internal mechanism for merging, and it is normally on a console so there is no specific location on your computer where the tool can expect to find it.

Where is my game dump?

I don't know. Nobody other than you knows. The guide gives possible locations where it can be found, but at the end of the day, you're the one who put it on your computer, so you're the one who knows where it is.

But I really don't know where my game dump is!

Not a question. But it shouldn't be that hard to find, considering you chose exactly where, on your computer, it went when you dumped it. The only real reason for you not to know where the dump is, is if you pirated it. And piracy is not supported, so good luck!

General UKMM Questions

What's the difference between merge/Apply and Deploy?

"Apply" and "merge" (or, "applying the merge") both mean to take the mods you have installed and combine them into one single mod. "Deploy" means to take the combined files and put them in the output folder.

UKMM splits these two concepts for multiple reasons. Maybe you want to merge a new set of mods and make sure there are no merge errors before you overwrite your deployed files. Maybe you have your output folder set to your SD card and want to merge while you look for your SD card, then plug it in to deploy. There are many reasons you might want these two operations separated.

If you don't want the operations separated, turn the Auto Deploy setting on, and it will always deploy right after merging (similar to what BCML did)

Why don't my mods show up in my emulator after deploying?

Make sure you're using the most up to date version. Go back up to the installation section and make sure you've followed the directions correctly.

Make sure your deploy folder is set correctly. Go back up to the deployment section and make sure you've followed the directions correctly.

If your mods still don't show up in your emulator, make sure that the location they're being deployed to isn't managed by OneDrive. It will delete them because it sucks. Consider uninstalling OneDrive, but at the very least, you'll need to tell it not to manage where UKMM deploys to.

Why aren't all BNPs compatible?

Some BNPs were made for BCML by directly editing log files, or by adding files to a game dump before generating the BNPs. Neither of these things were ever supported for BCML, and only worked by accident. Work is in progress to fix this in UKMM, but until then, certain BNPs cannot be installed with UKMM. If the mod has a regular graphic pack or loose file version, install that instead. Otherwise, bug the mod author about making their mods correctly.

Why can't UKMM detect my dump paths for consoles?

When you dump your game files to your PC, they go wherever you put them. There's no single location for it, so UKMM can't find it unless it scours the entirety of your computer (which would take forever and still probably not work).

Why can't UKMM detect my dump paths for Yuzu/Ryujinx?

Yuzu and Ryujinx don't use loose files to play the game, like Cemu does. They use XCI, NSP, or whatever other format, and UKMM can't read those, because there is no library for it. So UKMM could scan your Yuzu/Ryujinx settings for where your game/update/dlc archives are, but it wouldn't be able to do anything with them.

Why is UKMM so hard to use?

We've received this feedback quite a bit, but nobody has ever been able to explain exactly what is hard to use about it, so we've never had any idea what to fix. If you have concrete suggestions about how to make it easier to use, please tell us on the discord.

UKMM's UI sucks! It makes me want to kill my mother!

Believe it or not, yes, this is actual feedback we've received.

BCML's UI was based on React, a JavaScript UI framework designed for websites. UKMM's UI is based on egui, a functional UI framework designed for utilitarian programs. UKMM will likely never look as flashy as BCML did. Instead, it will look much like most other mod managers and computer programs do. We're sorry, but we take no responsibility for any harm that comes to any mothers.

Why did you write this program in Rust? Rust is the product of Lovecraftian madmen!

Yes, this was also actual feedback.

Rust is a fairly fast and easy-to-use language that is based heavily on C++, which a lot of the code libraries we needed to use were written in, so we could access the C++ code easily. C# was another choice, but it would have been more difficult to use existing code libraries.

Error-Related Questions

Why is it failing to install BNPs?

What you're seeing is the least-specific thing. It's the equivalent of UKMM saying "something went wrong." In order to find out what actually caused it, you'll need to expand the details by clicking on the little arrow next to the word Details.

Why can't it find files in my dumps?

Your dump paths may be set wrong. Go back up to the game dump section and make sure you've followed the directions correctly. Notably, on Wii U: Base Game and Update paths should end in /content and DLC path should end in /content/0010.

If you're absolutely sure your game dumps are set right, check to make sure your dumps haven't been corrupted somehow. If the file UKMM claims is missing, really is missing, then you may have to dump your game again.

If you've checked both of these things and made sure they're correct, then it's possible that the mod has corrupted files in it, which caused UKMM to write down that they exist, but was unable to open them to see what it needed to do with them. There isn't much that can be done about this: if a file is corrupted in a way that UKMM wants to read it, but can't, then the game won't be able to read it either. The mod will need to be fixed. (List of known mods this applies to: Hyrule Rebalance v8. There may be others)

What does "game flag missing key" mean?

The mod was made wrong.

A "game flag" is something the game uses to store data when you leave, for example either walking away in-game or turning off the game entirely. If a game flag is missing something, it won't work properly.

Why does it say "no platform for update"?

It can't detect what operating system you're using, in order to determine which version of the executable to download. Support for this feature is ongoing. You can just download the new version manually, from the link above in the #Prebuilt_program section.