Help:Tools/BCML: Difference between revisions

BCML
Author(s)	Nicene Nerd
Source code	https://github.com/NiceneNerd/BCML
License	GLPv3+
Written in	Python
Platform support	Cross-platform

VisualWikitext

Latest revision as of 20:52, 18 October 2024

BCML (Breath of the Wild Cross-platform Mod Loader) is the mod manager for BotW. It is used to install and uninstall mods, and solves many mod conflicts.

Setup

BCML requires Python 3.8.10 or 3.7.9, and the x64 Visual C++ redistributable. When you open the Python installer, there will be a checkbox that says Add Python to PATH. You MUST check this box, or else BCML can't be installed. From here, continue as normal, and install the x64 Visual C++ redistributable.

Open a command prompt anywhere (if you don't know how, just type cmd into Windows Search).

Most people will want to use BCML version 3.10.4 in order to support more mods. BCML version 3.10.5 and up removed support for older BCML V2 mods in order to allow newer python versions.

To install BCML 3.10.4 open a cmd prompt and run pip install bcml==3.10.4 (to install latest bcml type pip install bcml)

You should see a bunch of progress bars, and then a success message.

To run BCML all you need to do is type bcml into a cmd prompt.

If you would like to have a shortcut made, BCML has that option on the settings page.

Linux Extra Setup

BCML only has partial support for Linux, so some extra steps are needed to make it work for Linux. (This includes Steam Deck)

First, check the BCML setting to use without a Cemu installation, even if you are using it with Cemu. If Cemu is installed on a different drive than BCML is (e.g. flash drive) then also check the setting to disable links for the master mod.

Second, set the merged export directory to the path that Cemu will read the BCML graphic pack from. Depending on your distro and the app binary you use, this can be different places, so you may need to find the location, yourself. Two examples would be ~/.config/cemu/BreathOfTheWild_BCML or ~/.local/share/cemu/BreathOfTheWild_BCML. (Note that ~ is Linux shorthand for /home/<username> for all non-root accounts)

Do NOT set the merged export directory to the base graphic pack folder! E.g. ~/.config/cemu. Do NOT. If you do, BCML will delete things it shouldn't whenever you install or uninstall a mod.

Last, install your first mod with BCML. Once it is installed, go to the merged export directory in your file viewer and add a file called rules.txt based on the format described on this page.

Usage

BCML 3.4.9's UI

+ (in the bottom right): Installs a mod. Note that BCML supports mods in ZIP, RAR, 7z, or BNP formats. It also supports loose file format, in which case you select the rules.txt or info.json to install.
Hamburger button (bottom left): Show sort handles in the mod list, to drag and drop, which changes mod load order. Changes the load priority of a mod and then adjusts any RSTB, pack, or text merges as needed.
Circular Arrow (bottom left): Remakes all merged mod files. Use this as a first option when you run into mod conflicts.
Export: Exports all installed mods as a single mod. The exported zip file will be in a graphics pack format, or Atmosphere format (if in Switch mode)
Explore: Opens the folder where the selected mod is installed.
Hamburger button (top right): Dropdown menu that includes the BCML in-app help. Refer to this menu, first, if you have any issues.

If the in-app help does not solve your issue, try consulting the BCML troubleshooting page. It's a bit out of date, but it has some useful information.

Known Issues

Certain game files are too complex for the basic merging logic, and custom logic will have to be written for them. Almost all mods made as of Oct 17, 2020 are currently supported, but future mods may not be.
Cemu 2.1+ isn't supported since Cemu moved most of it data to AppData rather than next of the exe, you can use Cemu 1.26.2f, follow this workaround or simply use UKMM.

Merge All the Mods: Getting Started with BCML 3 Instructional Video

Merge All the Mods: Getting Started with BCML 3 Instructional Video on YouTube

@@ Line 1: / Line 1: @@
-[[Category:Tools]]
 {{Tool infobox
 | name = BCML
@@ Line 6: / Line 5: @@
 | license = GLPv3+
 | written_in = Python
-| win_only = 1
 }}
-BCML ('''B'''reath of the Wild '''C'''emu '''M'''od '''L'''oader) is a mod installer and merging tool for BotW graphic pack mods. It can be used to install and uninstall mods by priority and merge conflicts in the [[ResourceSizeTable.product.rsizetable|RSTB]], [[SARC]] (pack) files, or [[Message_archives|game texts]].
+BCML ('''B'''reath of the Wild '''C'''ross-platform '''M'''od '''L'''oader) is the mod manager for BotW. It is used to install and uninstall mods, and solves many mod conflicts.
 ==Setup==
-There are two primary ways to install BCML. Both options also require you to install the Microsoft Visual C++ Redistributable located [https://aka.ms/vs/16/release/vc_redist.x64.exe here].
+BCML requires Python [https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe 3.8.10] or [https://www.python.org/ftp/python/3.7.9/python-3.7.9-amd64.exe 3.7.9], and the [https://aka.ms/vs/17/release/vc_redist.x64.exe x64 Visual C++ redistributable]. When you open the Python installer, there will be a checkbox that says <code>Add Python to PATH</code>. You MUST check this box, or else BCML can't be installed. From here, continue as normal, and install the x64 Visual C++ redistributable.
-'''Option 1'''
+Open a command prompt anywhere (if you don't know how, just type <code>cmd</code> into Windows Search).
-#Download the latest BCML setup executable from [https://gamebanana.com/tools/6624 GameBanana].
+Most people will want to use BCML version 3.10.4 in order to support more mods. BCML version 3.10.5 and up removed support for older BCML V2 mods in order to allow newer python versions.
-#Run the setup and install BCML.
-'''Option 2'''
+To install BCML 3.10.4 open a cmd prompt and run <code>pip install bcml==3.10.4</code> (to install latest bcml type <code>pip install bcml</code>)
-#Ensure you have a '''64 bit version''' of Python 3.7+ installed and added to your PATH.
+You should see a bunch of progress bars, and then a success message.
-#Install the <code>bcml</code> pip package. {{Install py package help|package=bcml}}
+To run BCML all you need to do is type <code>bcml</code> into a cmd prompt.
+If you would like to have a shortcut made, BCML has that option on the settings page.
+===Linux Extra Setup===
+BCML only has partial support for Linux, so some extra steps are needed to make it work for Linux. (This includes Steam Deck)
+First, check the BCML setting to use without a Cemu installation, even if you are using it with Cemu. If Cemu is installed on a different drive than BCML is (e.g. flash drive) then also check the setting to disable links for the master mod.
+Second, set the merged export directory to the path that Cemu will read the BCML graphic pack from. Depending on your distro and the app binary you use, this can be different places, so you may need to find the location, yourself. Two examples would be <code>~/.config/cemu/BreathOfTheWild_BCML</code> or <code>~/.local/share/cemu/BreathOfTheWild_BCML</code>. (Note that ~ is Linux shorthand for <code>/home/<username></code> for all non-root accounts)
+* Do NOT set the merged export directory to the base graphic pack folder! E.g. <code>~/.config/cemu</code>. Do NOT. If you do, BCML will delete things it shouldn't whenever you install or uninstall a mod.
+Last, install your first mod with BCML. Once it is installed, go to the merged export directory in your file viewer and add a file called <code>rules.txt</code> based on the format described on [[Help:Using_mods#Installing_mods_with_the_graphic_pack_menu|this page]].
 ==Usage==
-[[File:BCML GUI Preview.png|thumb|right|BCML GUI Interface]]
+[[File:BCML-3.png|thumb|right|BCML 3.4.9's UI]]
-If installed by the setup executable, BCML can be launched from the Start Menu or desktop shortcut(s). If installed using <code>pip</code>, BCML can be launched with the <code>bcml</code> command for the CLI version or the <code>bcml-gui</code> command for the graphical version. {{CLI help}} A desktop shortcut can also be made pointing to the executable in Python's <code>Scripts</code> directory.
+*'''+''' (in the bottom right): Installs a mod. Note that BCML supports mods in ZIP, RAR, 7z, or BNP formats. It also supports loose file format, in which case you select the <code>rules.txt</code> or <code>info.json</code> to install.
+*'''Hamburger button (bottom left)''': Show sort handles in the mod list, to drag and drop, which changes mod load order. Changes the load priority of a mod and then adjusts any RSTB, pack, or text merges as needed.
+*'''Circular Arrow (bottom left)''': Remakes all merged mod files. Use this as a first option when you run into mod conflicts.
+*'''Export''': Exports all installed mods as a single mod. The exported zip file will be in a graphics pack format, or Atmosphere format (if in Switch mode)
+*'''Explore''': Opens the folder where the selected mod is installed.
+*'''Hamburger button (top right)''': Dropdown menu that includes the BCML in-app help. Refer to this menu, first, if you have any issues.
+If the in-app help does not solve your issue, try consulting the [https://github.com/NiceneNerd/BCML/wiki/Troubleshooting BCML troubleshooting] page. It's a bit out of date, but it has some useful information.
-The commands between the CLI and GUI version are the same, for more information about them, consult the [https://github.com/NiceneNerd/BCML/blob/master/docs/README.md readme on GitHub]. A basic overview:
+==Known Issues==
-*'''Install/Uninstall''': Installs or uninstalls a mod. Note that BCML only supports graphic pack mods in ZIP, RAR, or 7z format.
+*Certain game files are too complex for the basic merging logic, and custom logic will have to be written for them. Almost all mods made as of Oct 17, 2020 are currently supported, but future mods may not be.
-*'''Change Priority''': Changes the load priority of a mod and then adjusts any RSTB, pack, or text merges as needed.
+*Cemu 2.1+ isn't supported since Cemu moved most of it data to AppData rather than next of the exe, you can [https://wiki.cemu.info/wiki/Release_1.26.2f use Cemu 1.26.2f], follow [https://discord.com/channels/316759222207643649/606813647674540032/1278361320160235581 this workaround] or simply [https://nicenenerd.github.io/UKMM use UKMM].
-*'''Update''': Manually triggers a fresh merge of the RSTB, packs, and texts.
-*'''Export''': Exports all installed mods as a single mod. Can export using different folder structures for use as a graphic pack, an SDCaffiine mod, or mlc file replacement.
-*'''Explore''': GUI only, opens the folder where the selected mod is installed.
-==Known Issues==
+==Merge All the Mods: Getting Started with BCML 3 Instructional Video==
-*There is currently no option to change the path to your Cemu directory where the modded graphic packs will be installed. If you need to change this, edit or delete the file <code>%LOCALAPPDATA%\bcml\.cdir</code>.
+[https://www.youtube.com/watch?v=8gKRifYyA68 Merge All the Mods: Getting Started with BCML 3 Instructional Video on YouTube]
-*Only the US English game is fully supported. Some mods installed through BCML may crash other versions, especially mods that change game texts.