A mod merging and managing tool for The Legend of Zelda: Breath of the Wild
Why a mod loader for BOTW? Installing a mod is usually easy enough once you have a homebrewed console or an emulator. Is there a need for a special tool?
Yes. As soon as you start trying to install multiple mods, you will find complications. The BOTW game ROM is fundamentally structured for performance and storage use on a family console, without any support for modification. As such, files like the resource size table or TitleBG.pack will almost inevitably begin to clash once you have more than a mod or two. Symptoms can include mods simply taking no effect, odd bugs, actors that don't load, hanging on the load screen, or complete crashing. BCML exists to resolve this problem. It identifies, isolates, and merges the changes made by each mod into a single modpack that just works.
- Windows 10+ (7-8 might work but are not officially supported) or basically any modern Linux distribution
- A legal, unpacked game dump of The Legend of Zelda: Breath of the Wild for Switch (version 1.6.0) or Wii U (version 1.5.0)
- The latest x64 Visual C++ redistributable
- Cemu (optional)
There are two main ways to install BCML.
Install Python 3.7 - 3.10 (64 bit version), making sure to add it to your PATH, and then
run pip install bcml.
Note for Linux users: Because of the ways different distros handle Python packaging,
it often works better to install BCML in some contained environment. There are a few options for
this. The easiest would be to use pipx. You can install pipx
through pip, and then run pipx install bcml. In some cases you might need to also run pipx inject bcml pywebview[qt].
Note for Linux white screen bug: Try setting the environmental variable: QTWEBENGINE_DISABLE_SANDBOX=1.
Another option for Linux users is using a virtual environment ("venv"). To do so, you can run something like this:
python -m venv bcml_env
source bcml_env/bin/activate # will activate the venv
pip install bcmlFull Linux Example with CEMU
sudo pacman -S python39 Adjust for you distribution, arch defaults to a newer python
python3.9 -m venv /.local/bcml_env
source ~/.local/bcml_env/bin/activate
python3.9 -m pip install bcml
~/.local/bcml_env/bin/bcml
to launch BCML in the future
source ~/.local/bcml_env/bin/activate; ~/.local/bcml_env/bin/bcml
- In BCML, check 'without cemu' and set export path to '~/.local/share/cemu/graphicPacks/BreathOfTheWild_BCML'
- install your mods
- execute
curl https://pastebin.com/raw/igCLK2tz -o ~/.local/share/cemu/graphicPacks/BreathOfTheWild_BCML/rules.txt
- If your mods still don't load, verify that ~/.local/share/cemu/graphicPacks/BreathOfTheWild_BCML/rules.txt exist and try 'disable links for master mod' in BCML settings
Building from source requires, in addition to the general prerequisites:
-
Python 3.7 - 3.10 64 bit
-
Rust 1.60+ (nightly)
-
Node.js v14+
-
mkdocs and mkdocs-material
Run
pip install mkdocs mkdocs-materialin venv if not usingbootstrap.sh
Steps to build from source:
-
Create and activate a Python virtual environment (venv)
- Open terminal to repo root folder
python -m venv venv- Activate the venv (usually
venv/bin/activateon Linux orvenv\Scripts\activate.ps1on Windows)
-
Install Python requirements
- Open terminal to repo root folder
- Run
pip install -r requirements.txt - Also install Maturin:
pip install maturin
-
Build Rust extension module
- Open terminal to repo root folder
- Run
maturin develop(ormaturin develop --releasefor performance)
-
Prepare the webpack bundle
- Open terminal to
bcml/assets - Run
npm install - Run
npm run build(ornpm run testto watch while editing)
- Open terminal to
-
Build the docs
- Open terminal to repo root folder
- Run
mkdocs build
-
Create an installable wheel with
maturin buildor run without installing withpython -m bcml
Note that on Linux, you can simply run bootstrap.sh to perform these steps
automatically unless you would like more control.
For information on how to use BCML, see the Help dialog in-app or read the documentation on the repo. For issues and troubleshooting, please check the official Troubleshooting page.
BOTW is an immensely complex game, and there are a number of new mergers that could be written. If you find an aspect of the game that can be complicated by mod conflicts, but BCML doesn't yet handle it, feel free to try writing a merger for it and submitting a PR.
Python and JSX code for BCML is subject to formatting standards. Python should be formatted with Black. JSX should be formatted with Prettier, using the following settings:
{
"prettier.arrowParens": "avoid",
"prettier.jsxBracketSameLine": true,
"prettier.printWidth": 88,
"prettier.tabWidth": 4,
"prettier.trailingComma": "none"
}This software is licensed under the terms of the GNU General Public License, version 3 or later. The source is publicly available on GitHub.
This software includes the 7-Zip console application 7z.exe and the library 7z.dll,
which are licensed under the GNU Lesser General Public License. The source code for this
application is available for free at https://www.7-zip.org/download.html.
This software includes part of a modified copy of the pywebview Python package,
copyright 2020 Roman Sirokov under the BSD-3-Clause License. The source code for the
original library is available for free at https://github.com/r0x0r/pywebview.