Skip to main content

A mod manager for The Legend of Zelda: Breath of the Wild

Project description

BCML Logo

BCML: BOTW Cross-Platform Mod Loader

A mod merging and managing tool for The Legend of Zelda: Breath of the Wild

BCML Banner

Purpose

Why a mod loader for BOTW? Installing a mod is usually easy enough once you have a homebrewed console or a 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 inevtiably 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.

Prerequisites

  • Windows 10 (7-8 might work but are not 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)

Setup

There are three ways to install BCML.

PyPI

Install Python 3.7+ (64 bit version), making sure to add it to your PATH, and then run pip install bcml. Note that, because of the cefpython3 dependency, on Windows only Python 3.7 is supported, but 3.8+ can be used on Linux.

Windows Installer

Download the setup executable from the latest GitHub release or from GameBanana. Double click to run and install BCML.

Building from Source

Building from source requires, in addition to the general prerequisites:

  • Python 3.7+ 64 bit

    (Note: 3.8+ will not work on Windows until cefpython3 is updated.)

  • Node.js v14

Steps to build from source:

  1. Install Python requirements

    1. Open terminal to repo root folder
    2. Run pip install -r requirements.txt
  2. Prepare the webpack bundle

    1. Open terminal to bcml/assets
    2. Run npm install
    3. Run npm run build (or npm run test to watch while editing)
  3. Build the docs

    1. Open terminal to repo root folder
    2. Run mkdocs build -d bcml/assets/help
  4. Install BCML with python setup.py install or run without installing with python -m bcml

Note that on Linux, you can simply run bootstrap.sh to perform these steps automatically unless you would like more control.

Building the Windows Installer

The Windows installer is a Powershell script. It can be executed directly with Powershell, but BCML distributes an executable binary made with ps2exe. Instructions to build:

  1. Open Powershell.
  2. Install ps2exe: Install-Module ps2exe.
  3. CD to the repo root folder.
  4. Create a build folder if it does not already exist.
  5. Run:
    ps2exe -inputFile .\installer.ps1 -outputFile .\build\installer.exe -x64 -iconFile .\bcml\data\bcml.ico -title BCML -description "BOTW Cross-Platform Mod Loader" -version 0.9.0.0 -supportOS
    
  6. The installer binary will be located under build\installer.exe.

Usage and Troubleshooting

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.

Contributing

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"
}

License

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 a fork of the console application msyt.exe by Kyle Clemens, copyrighted 2018 under the MIT License. The source code for this application is available for free at https://github.com/NiceneNerd/msyt/tree/bcml.

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.

Project details


Release history Release notifications | RSS feed

This version

3.3.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bcml-3.3.1.tar.gz (28.8 MB view hashes)

Uploaded Source

Built Distribution

bcml-3.3.1-py3-none-any.whl (28.9 MB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page