Help:Using mods and Help:Adding items: Difference between pages

From ZeldaMods (Breath of the Wild)
(Difference between pages)
Jump to navigation Jump to search
imported>Leoetlino
m (clarify telemetry patch location)
 
imported>Ginger
m (→‎Required tools: Hyrule Builder dependency workaround)
 
Line 1: Line 1:
Welcome, players! This article will walk you through setting up BotW to play with mods. There are three different platforms you can play on:
Mods that deal with items will often edit items that already exist in the game. However, this can lead to conflicts between mods, so it is generally advised to make a new item, instead. This tutorial will cover all of the steps needed to add new items, as well as multiple methods for completing each step.


* Wii U console
==Required tools==
* Cemu, the Wii U emulator, on your computer
Adding new items requires several tools, most of which are described and are available [[Help:Setting up tools|here]].
* Switch console


Almost all Wii U mods should work on both the console and Cemu, but most Switch mods aren't cross-compatible. In addition, many mods are only compatible with version 1.5.0 of BotW.
*[https://www.python.org/downloads/release/python-374/ Python 3.7] is necessary for just about every tool (Python 3.8 exists, but is not currently compatible with [[Help:Tools/aamp|aamp]] or [[Help:Tools/BCML|BCML]])
*A text editor like [https://notepad-plus-plus.org/downloads/ Notepad++]
*Wild Bits {{Install py package help|package=wildbits}}
*Breath of the Wild Cemu Mod Loader (or <code>bcml</code>) {{Install py package help|package=bcml}}
*[https://github.com/KillzXGaming/Switch-Toolbox/releases Switch Toolbox]
*Hyrule Builder {{Install py package help|package=hyrule_builder}}
** As of version 0.3.1, Hyrule Builder is based off of an old version of one of its dependencies. After installing Hyrule Builder, uninstall the new dependency version (<code>pip uninstall oead</code>) and install the old one (<code>pip install oead==0.9.4</code>) If Hyrule Builder has since updated and this message has not been removed, please remove it.


Note that any mods which edit any of the same files as each other will probably be incompatible and cause issues. Sometimes, mods that edit different files can also be unexpectedly incompatible. If you are using multiple mods and you find glitches, please figure out which mod / combination of mods is causing the issue before reporting it to the mod creator(s).
==Tutorial==


== Wii U Console ==
===Before we begin===
'''Do not skip this section, it is very important.'''


=== Setting up homebrew ===
This tutorial will use several terms that you may not be familiar with, or will have specific definitions you may not have used before:
Follow [https://wiiu.hacks.guide/ this guide] to set up your Wii U console to use homebrew software.


=== Setting up SDCafiine ===
*File name (or FileName) - the name of a file. For example, for the file <code>Armor_001.sbfres</code>, the FileName is <code>Armor_001</code>
SDCafiine is a Wii U homebrew program that will load modded game files from your SD card.
*File extension (or FileExtension) - the type/extension of a file. For example, for the file <code>Armor_001.sbfres</code>, the FileExtension is <code>sbfres</code>
*Actor name (or ActorName) - the code name of the item, and the FileName of the actor pack. For example, the Hylian Tunic is <code>Armor_001_Upper</code>.
*<code>bfres</code> name (or BfresName) - the code name of the resource files containing the model and texture data for the actor, and the FileName of the <code>bfres</code> for an actor. For example, the Hylian Tunic is part of the Hylian Set and all Hylian Set resources are contained inside <code>Armor_001</code>. In general, an armor's BfresName is the first two parts of its ActorName (e.g. <code>Armor_001</code> out of <code>Armor_001_Upper</code>). This tutorial uses <code>sbfres</code> and <code>bfres</code> mostly interchangeably, but you can think of an <code>sbfres</code> as a ZIP archive that contains a <code>bfres</code>.
*Model name (or ModelName) - the code name of the model inside the resource files to be used. In almost all cases, this is the same as the ActorName. The only exceptions to this are for head armor models that have a mantle variant, like <code>Armor_001</code>. Their ActorName will end in <code>_Head</code>, and their ModelName will end in <code>_Head_A</code>.
*Old - if something is referred to as "old," that means any files you are using as the base files for your new item. For example, if you are creating a new shield that performs similarly to <code>Weapon_Shield_001</code> (is a shield, is wooden, etc.) and you were copying its files to your mod, then <code>Weapon_Shield_001</code> would be the "old" actor name.
*New - anything that refers to the new item you are making. If something is not referred to as "old" or "new," then it is new. For example, if you are making <code>Armor_9001_Head</code> then that will be referred to as either the NewActorName and the ActorName.


# Download the latest stable release of SDCafiine (not a "nightly" version) from [https://github.com/Maschell/SDCafiine/releases here].
Vanilla weapons have the same name as their actor, model, and <code>bfres</code> names. For example, the actor <code>Weapon_Sword_001</code> has the model name <code>Weapon_Sword_001</code> and its resource files are in <code>Weapon_Sword_001.sbfres</code>.
# Extract the contents of the .zip into the root of your SD card.
# Create a new folder in the root of your SD Card, named <code>sdcafiine</code>.
# Within that folder, create a new folder with the name of your game's Title ID. On Wii U, the JP version of BotW uses <code>00050000101C9300</code>, the US version uses <code>00050000101C9400</code>, and the EU version uses <code>00050000101C9500</code>.
# Within that folder, you can create any number of folders named after the mods you want to use. When you boot the game, a menu will appear allowing you to select one to use.
# Inside each of those folders, create a folder named <code>content</code>. Your mod files will go in here. (Mods will often include a <code>content</code> folder already to make things clear.)


To use mods, you just need to select the SDCafiine option from the Homebrew Launcher, then boot your game immediately afterwards.
Note that anytime brackets are used, this means that whatever is inside the brackets should be replaced with something else. For example, <code>Bootup_[XXxx].pack</code> could be replaced with <code>Bootup_USen.pack</code> or <code>Bootup_EUen.pack</code> or other names. Do NOT leave the brackets in there. Another example might be <code>[FileName].[FileExtension]</code> which could be replaced with just about anything, like <code>Weapon_Sword_001.bxml</code> or <code>Link.Tex1.sbfres</code>. (Note that, in this case, "Link.Tex1" is the file name and <code>sbfres</code> is the file extension)


== Cemu Emulator ==
If you are ever told to open a Powershell window and run a command, you can do that by holding shift, right-clicking somewhere inside the folder and clicking on "Open Powershell window here." Anytime you do this, it will be to run a Python script. All BotW modding Python scripts do not print '''anything''' to the Powershell window if they run successfully. If, at any time, one of the commands prints something to the Powershell window, stop right there and see if you can figure out what the problem is, or ask in the Discord.


=== Download Cemu Emulator ===
===Setting up your folder structure===
You can find the latest version of Cemu Emulator on the [http://cemu.info/ Official Cemu Website]
The folder structure is important, as BotW will only load files if they're in a certain location. To begin with, you will want to create a folder structure that looks like this:


=== Setting up homebrew ===
*BreathOfTheWild_[MyAwesomeModName]
Follow [https://wiiu.hacks.guide/ this guide] to set up your Wii U console to use homebrew software, in order to allow you to dump the game files from your console to your PC.
**content
***Actor
****Pack
***Model
***Pack
***UI
****StockItem


=== Dumping the game files ===
Note that these names are case-sensitive.
To play BotW on Cemu, you'll need to [[Help:Dumping games|dump the game files]] from the console to your computer. Then run the <code>U-King.rpx</code> file from Cemu to boot the game.


=== Installing the DLC ===
===Creating the actor===
If you dumped the game's add-on content (aoc) files, follow [http://compat.cemu.info/wiki/Tutorial:How_to_install_a_DLC this guide] to install them in Cemu.
First, figure out what item (that already exists in game) behaves closest to your new item. Find the <code>sbactorpack</code> file for that item, and copy it to <code>content\Actor\Pack</code>. You will find the original file in your dumped UPDATE files (not the base game files), in the same location. (<code>content\Actor\Pack</code>) Make sure you copy it, and don't move the original.


=== Setting up and Maximising Performance ===
Next, copy <code>ActorInfo.product.sbyml</code> to <code>content\Actor</code> in your mod files. You can find it in your dumped UPDATE files (not the base game files), in the same location. Make sure you copy it, and don't move the original.
Now that you have Cemu and your games files, it is recommended you use [http://compat.cemu.info/wiki/Serfrosts_Cemu_Setup_Guide Serfrosts Cemu Setup Guide] to maximise performance on your hardware before installing mods.


=== Installing mods with the graphic pack menu ===
Then, copy both <code>Bootup.pack</code> and <code>Bootup_[XXxx].pack</code> to <code>content\Pack</code> in your mod files. You can find them in your dumped UPDATE files (not the base game files), in the same location. There will be several <code>Bootup_[XXxx].pack</code> files. Each one is for a different region and language. For example, USen is for the US version, English language, while EUes is for the European version, Spanish language. Copy only the one(s) you will be making edits for, as any languages that you don't edit will have entries automatically copied into them by one of the later steps in the tutorial. For example, if you edit USen and EUes, EUen will receive your custom entries from USen, and USes will receive your custom entries from EUes.
Cemu uses "graphic packs" to install mods without overwriting any of the base files, allowing you to easily install or uninstall mods without leaving any trace.  


Graphic packs are installed by placing the unzipped folder in <code>Cemu/graphicPacks/</code>. Note that most newer mods will come packaged as a graphic pack, or have a graphic pack option.  
Lastly, copy your resource files to <code>content\Model</code> (models and textures) and <code>content\UI\StockItem</code> (icons). These files aren't handled by the converter, they're explained more in depth in their own section of the tutorial.


To check that the mod is a graphic pack, open the mod folder within <code>Cemu/graphicPacks/</code>. A graphic pack will have a file called <code>rules.txt</code> next to the <code>content</code> and/or <code>aoc</code> folder.
Once you have your mod files assembled navigate to the folder that contains your BreathOfTheWild_[MyAwesomeModName] folder, open a Powershell window, and run the command <code>hyrule_builder unbuild BreathOfTheWild_[MyAwesomeModName]</code>. It will take a bit of time to convert the files, and then create a new folder called BreathOfTheWild_[MyAwesomeModName]_unbuilt, which contains the files you will be editing.


===Editing the actor pack files===
The actor pack files will be located in the various folders inside <code>content\Actor</code>. There will be certain parts of the files that you need to change. All instances of the old actor, model, and BFRES names will need to be changed to the new actor, model, and BFRES names. The following is a list of many of the changes that need to be made, but note that some of these may not apply to your item, and there are some changes that may not appear in this list. Be thorough when you look through the files for things that may need to be changed.
[[File:Addingitems_aampfilenames.png|alt=Actor pack file name changes|thumb|The underlined items need to be changed for this actor pack (in addition to the actor pack name and the contents of each file)]]


If a mod is not packaged as a graphic pack you will have to package it yourself, otherwise skip to the end of this section. This method works for versions of Cemu 1.15.1+
*File/Folder names:
**changing the name of the <code>[ActorName].bmodellist</code> file inside <code>content\Actor\ModelList</code>
**changing the name of the <code>[ModelName].bphysics</code> file inside <code>content\Actor\Physics</code>
**changing the name of the <code>[ActorName].bxml</code> file inside <code>content\Actor\ActorLink</code>
**changing the name of the <code>[ActorName].bgparamlist</code> file inside <code>content\Actor\GeneralParamList</code>
**changing the name of the <code>[BfresName]</code> folder inside <code>content\Physics\SupportBone</code>
**changing the name of the <code>[ModelName].bphyssb</code> file inside <code>content\Physics\SupportBone\[BfresName]</code>
**changing the name of the <code>[BfresName]</code> folder inside <code>content\Physics\Cloth</code>
**changing the name of the <code>[ModelName].hkcl</code> file inside <code>content\Physics\Cloth\[BfresName]</code>
*Inside <code>bmodellist</code>:
**changing the line that says <code>Folder: !str64 [BfresName]</code> to the new <code>bfres</code> name
**changing the line that says <code>UnitName: !str64 [modelName]</code> to the new model name
*Inside <code>bphysics</code>:
**changing the line that says <code>support_bone_setup_file_path: !str256 [BfresName]/[ModelName].bphyssb</code> to the new <code>bfres</code> and model names
**changing the line that says <code>cloth_setup_file_path: !str256 [BfresName]/[ModelName].hkcl</code> to the new <code>bfres</code> and model names
**'''Do not change anything with "Havok" in the name as those point to data inside the hkcl file which we cannot change.''' Physics should work fine without changing data ''inside'' the <code>hkcl</code> file, as long as you do change the ''name'' of the <code>hkcl</code> file.
*Inside <code>bxml</code>:
**changing the line that says <code>ActorCaptureUser: !strRef [ActorName]</code> to the new actor name
**changing the line that says <code>GParamUser: !strRef [ActorName]</code> to the new actor name
**changing the line that says <code>ModelUser: !strRef [ActorName]</code> to the new actor name
**changing the line that says <code>PhysicsUser: !StrRef [ModelName]</code> to the new model name[[File:Addingitems_bgparamlist.jpg|thumb|Example of two parameters commonly changed, inside the bgparamlist file.]]
*Inside <code>bgparamlist</code>:
**If your armor is upgradeable, changing the line that says <code>NextRankName: [ActorName]</code> to the actor name for the actor that this one upgrades into. (In game terms, "upgradeable" means via the Great Fairies)
**The <code>bgparamlist</code> file also contains most of the information about the stats of items. For example, a weapon/shield's durability, a weapon's damage, a shield's block rate, an armor's defense, an armor's set (and therefore set bonus) are all stored here. You may want to change some of these things. A comprehensive list of the things inside the <code>bgparamlist</code> file is available [[Bgparamlist|here]]. Commonly changed parameters include: <code>Life</code> (the durability of the item, in the <code>General</code> category), <code>Power</code> (a weapons' damage, in the <code>Attack</code> category), <code>DefenceAddLevel</code> (an armor's defense rating, in the <code>Armor</code> category).


# Create a new folder inside <code>Cemu/graphicPacks/</code> named after the mod you want to use.
Once you've made your changes, '''make sure to save'''.
# Inside that folder, create a folder named <code>content</code>. Your mod files will go in here. (Mods will often include a <code>content</code> folder already to make things clear.)
# Create a file named <code>rules.txt</code> next to the <code>content</code> folder (if the downloaded mod doesn't already include one). Use this example as a template:


[Definition]
===Adding the actor info===
titleIds = 00050000101C9300,00050000101C9400,00050000101C9500
The previous step saw you creating the actual actor. This step is for creating the actor metadata that the game uses so that it knows your new actor exists. It also stores most data that appears in menus like the pause menu, crafting menu, or store menus.
name = <Mod Name>
path = "The Legend of Zelda: Breath of the Wild/Mods/<Mod Name>"
description = <Mod description here>
version = 3
fsPriority = 100
<code>version</code> must be set to 3 to work correctly. <code>fsPriority</code> determines the order in which mods are prioritized - higher numbers prioritize that mod's files over other mods. Mods without an <code>fsPriority</code> entry specified will default to 100.


Inside <code>content\Actor\ActorInfo</code>, you will find a file for each actor in the game. Find the one for the old actor that you are using as your base, and copy it, changing the name of the new file to <code>[NewActorName].info.yml</code>, then open the file in a text editor. Change the following lines:


Once a mod has been added, simply enable it from Cemu's graphic pack menu to use it. You can find this menu in <code>Options > Graphic Packs</code> or by right-clicking a game and selecting <code>Edit Graphic Packs</code>.
*<code>bfres: [BfresName]</code> to your new <code>bfres</code> name
Note that most mods should not be enabled or disabled while the game is running.
*<code>itemUseIconActorName: [ActorName]</code> to your new actor name
*<code>mainModel: [ModelName]</code> to your new model name
*Any additional information you changed in the actor pack that might be shown in any menu. For example, armor value of armor, defensive value of shields, damage of weapons, buying/selling price of items from/to a shop, crafting ingredients if the item is craftable, etc.


=== Installing mods using BCML ===
Once all the info is changed, '''make sure to save'''.
Mods that are already packaged as a graphic pack can also be installed using [[Help:Tools/BCML|BCML]], a mod loading tool. In addition to being simpler than manually extracting and enabling the mod, BCML is designed to resolve certain kinds of conflicts between different mods. Mods that modify the [[RSTB]], the same [[SARC]] files, or [[Message archives]] will not function properly together unless the changes are merged. BCML does this automatically. To install mods with BCML:


# Install BCML using the instructions [[Help:Tools/BCML#Setup|here]].
===Creating the resource files===
# '''Command line version''': Install a mod by running <code>bcml install path\to\mod.zip</code>.  {{CLI help}} BCML will ask you to specify the directory where Cemu is installed first.
This section will cover the files that actually tell the game what the 3D model of the item looks like, in game. You'll need to copy the resources for the original item that you're modifying to your mod's <code>content\Model</code> folder. You will find the original resource files in your dumped UPDATE files (not the base game files), in the same location. (<code>content\Model</code>) The files will be called <code>[OldBfresName].sbfres</code> and <code>[OldBfresName].Tex.sbfres</code>. '''If you are modding for WiiU or Cemu, there are actually three files you will need: <code>[OldBfresName].sbfres</code>, <code>[OldBfresName].Tex1.sbfres</code>, and <code>[OldBfresName].Tex2.sbfres</code>. If <code>[OldBfresName].Tex1.sbfres</code> is not present in your UPDATE files, you will need to find it in your BASE GAME dumped files. This is the case for most, if not all, vanilla (non-DLC) items.'''
# '''Graphical version''': Open the GUI by running <code>bcml-gui</code>. {{CLI help}} Select the directory where Cemu is intalled. Then click "Install" and select the mod you want to install.


BCML should automatically enable installed mods in Cemu, but check to make sure by opening the Cemu graphic pack menu and looking in the "BCML Mods" category.
Once you have copied the old files to the new location, you will rename them to your new <code>bfres</code> name. Note that this name needs to match the <code>bfres</code> name you used when editing the actor pack files.


== Switch ==
The bulk of the [[Help:Replacing models|model replacement]] and [[Help:Replacing textures|texture replacement]] is explained in other tutorials. Once you've used those tutorials to replace the bulk of the data, we can change the names that BotW uses to refer to that data. All the rest of this section assumes that you have both <code>sbfres</code> files for your actor open in Switch Toolbox. (If on WiiU, you don't need to open the Tex2 file. Switch Toolbox will read its data whenever you open the Tex1 file, as long as they are in the same folder.)


=== Setting up homebrew ===
The first thing to change is the <code>bfres</code> name. This does not happen automatically when you change the <code>sbfres</code> name. You can do this by clicking on the orange file labeled "FRES" on the left side, clicking on the name on the right side, and changing it.
Follow [https://guide.sdsetup.com this guide] to set up your Switch console to use homebrew software.


This tutorial uses Atmosphère Custom Firmware (CFW). It is strongly recommended '''not''' to use other CFWs as they tend to be outdated, unsafe and/or use stolen code from Atmosphère.  
Some important terms in modeling:
{{warning|text=Running homebrew on your console may lead to it getting banned from Nintendo's online services (including eShop and game updates). Enabling Airplane Mode will not help, as telemetry reports are saved and sent to Nintendo the next time you connect to the internet.
A "model" is the 3D data for a whole actor. The models are everything that is inside the <code>Models</code> folder of the <code>[BfresName].sbfres</code> file.
An "object" is the 3D data for a piece of an actor. The objects are everything that is inside the <code>Models\[ModelName]\Objects</code> folder.
A single model will be made up of one or more objects.
A "material" is the data the game uses to "paint" a model, so that it knows what color it is, how it reflects light, whether or not it's shiny or dull, etc. The materials are everything that is inside the <code>Models\[ModelName]\Materials</code> folder.
A "texture" (or "map") is a single picture that contains color, light reflection, metallic, or other data for a material. Textures are contained separately, in the <code>[BfresName].Tex.sbfres</code> file. (<code>[BfresName].Tex1.sbfres</code> for WiiU/Cemu)
A material will consist of one or more textures, plus shader data. (The author of this tutorial doesn't even really understand shaders. Sorry.)
Each model will contain one or more materials. Each object will be assigned one material. A single material may be assigned to any number of objects.


However, this risk is very minimal as long as you are sensible and only use a safe, sane CFW (Atmosphère) and mods on offline games (don't install NSPs or pirate games!) as Atmosphère does not leave any trace on the system and disables some system telemetry.
The ModelName is important, as the game will not load the actor if the ModelName here does not match the ModelName used in the actor pack files and actor info file! Object names can be arbitrary, but they generally follow the rule: <code>[ObjectName]__[MaterialName]</code> where <code>[ObjectName]</code> is whatever you want, and <code>[MaterialName]</code> is the name of the material assigned to it. Adhering to this naming convention is encouraged, so that if anyone else ever tries to reuse your files, they can make sense of them.
Click on the model name on the left side that you need to change. On the right side, near the top, the model name will be displayed. Click on that to edit it, and change it to your new mesh name that you used in the actor pack and actor info files. If successful, it will also change on the left side.
You may also change the names of the objects and materials in the same way.
When changing the names of the materials, on the right side, there will be a tab labeled Textures that will be selected by default. It will contain the names of all the textures being used by that material, and these will all be the names of the old textures. Switch over to the texture <code>sbfres</code> now, and change all the textures to names that fit your new actor.
When you are done changing all the names of the textures, switch back to the model <code>sbfres</code> and look at the Textures section of the material. Click on one of the entries in the table (for example, <code>[OldModelName]_Alb</code>) and then click on Edit. A new window will pop up, with a list of all the textures contained in the texture <code>sbfres</code>. Choose the one that corresponds with the new texture (for example, <code>[NewModelName]_Alb</code> or <code>[NewModelName]_Alb.0</code>) and click save. Do this for all the entries in the Textures table for this material, and then repeat the process for every other material.


If you are paranoid, turn on Airplane Mode ''before running homebrew for the first time'', then make a full system backup, and always stay offline until you restore that clean backup.}}
If you are editing an armor that is dyeable, you then need to expand the Animations folder on the left, then Texture Pattern Animations, then right-click the folder that corresponds to your item (Head for the head, Upper for the torso, Lower for the legs). Select Export, select to save as "Yet Another Markup Language" (or YAML Ain't Markup Language, if it's been since changed to the official name) and save it somewhere. Open the new <code>yaml</code> file that you just saved in a text editor. You will need to edit all the texture and material names to the new ones. For example, changing <code>[OldModelName]_Alb.0</code> to <code>[NewModelName]_Alb.0</code> and <code>[OldMaterialName]</code> to <code>[NewMaterialName]</code> (e.g. <code>Mt_Hood_001</code> to <code>Mt_Hood_9001</code>). Save it, then, back in Switch Toolbox, right-click on the folder inside Texture Pattern Animations that corresponds to your item, and select Replace. Select the <code>yaml</code> you edited.


=== Disabling telemetry reports ===
When you are done, select any file or folder from the model <code>sbfres</code>, in the list on the left, and save it. Switch Toolbox will ask if you want to Yaz0 compress the file, click Yes. Then click on any file or folder from the texture <code>sbfres</code>, in the list on the left, and save it. Switch Toolbox will again ask if you want to Yaz0 compress the file, click Yes. If you are editing a WiiU texture <code>sbfres</code>, it will then ask you to save the Tex2 sbfres, so save it and Yaz0 compress it, as well. And that's it, you are done with the files that tell the game what the new item looks like.
The Switch version of ''Breath of the Wild'' sends many [[telemetry]] reports so when you are using mods that modify gameplay in a detectable way or add new content in any way, it is strongly recommended to disable telemetry reports because they are used by Zelda developers to understand how people play BotW and also to help them fix bugs.


Mods that modify actors are especially dangerous as they might cause the game to use the ActorSystem emergency heap and trigger many memory-related play reports.
===Creating an inventory icon===
This section covers the inventory icons, the square images you see in the inventory grid in the pause menu. These files are kept in <code>content\UI\StockItem</code> for inventory items. Copy the old <code>sbitemco</code> file for the item you are using as your foundation, to the same location in your mod files (<code>content\UI\StockItem</code>). An <code>sbitemco</code> file is pretty much the same thing as an <code>sbfres</code> for textures, so you will edit it the same way, using Switch Toolbox. Make sure to change the name of the file to <code>[NewActorName].sbitemco</code>, the name of the file it contains in Toolbox to <code>[NewActorName].bitemco</code>, and the texture it contains to <code>[NewActorName]</code>


To disable problematic telemetry reports:
===Creating an inventory name and description===
For the in-game text concerning your item, you will need to navigate to <code>content\Pack\Bootup_[XXxx].pack\Message\Msg_[XXxx].product.ssarc</code>. There are many <code>msbt</code> files here, and all of them have text data for the game. For your actor, you'll look in the <code>ActorType</code> folder. Find the file that fits your item type, and open it in your text editor of choice.


* For 1.5.0, download this [http://static.zeldamods.org/patch_switch150_no_telemetry.ips patch], put it in <code>/atmosphere/exefs_patches/botw_no_telemetry/</code> (create new folders if required) and rename the file to <code>16A91992BBA71201E98756F3BC8F5D2F.ips</code>. This patch works for the Switch 1.5.0 [[executable]] only (build ID: 16A91992BBA71201E98756F3BC8F5D2F).
Find the name and description entries for the item you used as your base, and copy them to the bottom of the file. An entry in this file starts on the line that says <code>[ActorName]_Name</code> or <code>[ActorName]_Desc</code> and ends one line before the next time that appears. If your item is something that would appear in the Shiekah Slate album, so that you could take pictures of it and track it on the map with the Sheikah Radar, also add an <code>[ActorName]_PictureBook</code>.


* For 1.6.0, download this [http://static.zeldamods.org/patch_switch160_no_telemetry.ips patch], put it at <code>/atmosphere/exefs_patches/botw_no_telemetry/</code> (create new folders if required) and rename the file to <code>8E9978D50BDD20B4C8395A106C27FFDE.ips</code>. This patch works for the Switch 1.6.0 [[executable]] only (build ID: 8E9978D50BDD20B4C8395A106C27FFDE).
Change the <code>- text:</code> line of the name to be your new name, and the <code>- text:</code> line of the description to be your description. If your name or description uses apostrophes, be sure to surround it in quotes. e.g. <code>Zora Mask</code> is fine, but <code>"Zora's Mask"</code> needs the quotes because it contains an apostrophe. If you have a picture book entry as well, copy the text you made for <code>[ActorName]_Desc</code> into it.


=== Installing mods ===
When you're done, '''make sure to save'''.


# In the root of your MicroSD card, there should be a folder named <code>atmosphere</code>.
===Creating the save game data flags===
# Within that folder, there should be a folder named <code>contents</code>. Inside that, create a folder with the name of your game's Title ID. For BotW on Switch, the Title ID is <code>01007EF00011E000</code>. (In versions of Atmosphere prior to v0.10.0, the <code>contents</code> folder was instead called <code>titles</code>.)
This section covers the save game flags, which the game uses to remember whether or not you've picked up an item before. If you are adding a common item, like a material or consumable, this will make it so that the little popup that happens the first time you pick up an item, doesn't happen every single time you pick your new item up.
# Inside that, make a folder called <code>romfs</code>. Your mod files will go in here. (Mods will often include all or part of this folder structure already, to make things easy.)


To use the mod, simply boot the console into CFW, then boot the game, and the mod will be active.
Navigate to <code>content\Pack\Bootup.pack\GameData\gamedata.ssarc</code> and find the flag for your base game item. It might be contained in any of the <code>bool_data_#.bgdata.yml</code> files. The name you are looking for is <code>IsGet_[OldActorName]</code>.
[[File:Addingitems_crc32hashpython.png|thumb|After running the python command, copy the underlined result to use as your HashValue]]
Copy the entire section for the flag into the space right after that flag. Change <code>IsGet_[OldActorName]</code> to <code>IsGet_[NewActorName]</code>. Then, open a new Powershell window anywhere. Use the command <code>python</code> to enter a python command line. Run the command <code>import ctypes; import binascii; ctypes.c_int32(binascii.crc32('''IsGet_[NewActorName]''')).value</code> to obtain a positive or negative number. (Bolding has been added to distinguish the name of the flag. You need to use the actual name of the flag you're adding.)
[[File:Addingitems_booldata0.jpg|thumb|Once you've copied the boolean data section, change the DataName and HashValue to match your new item.]]
In your text editor, paste the result from your calculator into the <code>HashValue</code> after <code>IsGet_[NewActorName]</code>, and save the file.


Note that mods are not permanently installed on the console. To remove all installed mods, simply delete <code>/atmosphere/contents/01007EF00011E000</code>.
===Finishing up and installing the mod===
Now that all the files have been edited, you will need to pack them all back up. Go back to the folder that contains BreathOfTheWild_[MyAwesomeModName]_unbuilt, open a Powershell window, and run the command <code>hyrule_builder build [--be] BreathOfTheWild_[MyAwesomeModName]_unbuilt</code>. '''If you are modding for WiiU or Cemu, and don't add the --be, the error you get will seem very confusing. This is because it's looking for the Switch paths and not finding them.''' After a little bit of conversion, a new folder will be created, called BreathOfTheWild_[MyAwesomeModName]_unbuilt_build. That folder contains your completed mod. Delete the old BreathOfTheWild_[MyAwesomeModName] and rename the completed mod folder to BreathOfTheWild_[MyAwesomeModName].
 
And now you are done! To use the mod, open <code>bcml</code> via Powershell (just run the command <code>bcml</code>) and select Install... Then select Add Folder, select the <code>BreathOfTheWild_[MyAwesomeModName]</code> folder, and click OK. Wait for it to install, and you're ready to play the game with your new item!
 
==Troubleshooting==
{{Empty section}}
[[Category:Guides]]
[[Category:Guides]]

Revision as of 20:52, 16 February 2020

Mods that deal with items will often edit items that already exist in the game. However, this can lead to conflicts between mods, so it is generally advised to make a new item, instead. This tutorial will cover all of the steps needed to add new items, as well as multiple methods for completing each step.

Required tools

Adding new items requires several tools, most of which are described and are available here.

  • Python 3.7 is necessary for just about every tool (Python 3.8 exists, but is not currently compatible with aamp or BCML)
  • A text editor like Notepad++
  • Wild Bits [CLI help]
  • Breath of the Wild Cemu Mod Loader (or bcml) [CLI help]
  • Switch Toolbox
  • Hyrule Builder [CLI help]
    • As of version 0.3.1, Hyrule Builder is based off of an old version of one of its dependencies. After installing Hyrule Builder, uninstall the new dependency version (pip uninstall oead) and install the old one (pip install oead==0.9.4) If Hyrule Builder has since updated and this message has not been removed, please remove it.

Tutorial

Before we begin

Do not skip this section, it is very important.

This tutorial will use several terms that you may not be familiar with, or will have specific definitions you may not have used before:

  • File name (or FileName) - the name of a file. For example, for the file Armor_001.sbfres, the FileName is Armor_001
  • File extension (or FileExtension) - the type/extension of a file. For example, for the file Armor_001.sbfres, the FileExtension is sbfres
  • Actor name (or ActorName) - the code name of the item, and the FileName of the actor pack. For example, the Hylian Tunic is Armor_001_Upper.
  • bfres name (or BfresName) - the code name of the resource files containing the model and texture data for the actor, and the FileName of the bfres for an actor. For example, the Hylian Tunic is part of the Hylian Set and all Hylian Set resources are contained inside Armor_001. In general, an armor's BfresName is the first two parts of its ActorName (e.g. Armor_001 out of Armor_001_Upper). This tutorial uses sbfres and bfres mostly interchangeably, but you can think of an sbfres as a ZIP archive that contains a bfres.
  • Model name (or ModelName) - the code name of the model inside the resource files to be used. In almost all cases, this is the same as the ActorName. The only exceptions to this are for head armor models that have a mantle variant, like Armor_001. Their ActorName will end in _Head, and their ModelName will end in _Head_A.
  • Old - if something is referred to as "old," that means any files you are using as the base files for your new item. For example, if you are creating a new shield that performs similarly to Weapon_Shield_001 (is a shield, is wooden, etc.) and you were copying its files to your mod, then Weapon_Shield_001 would be the "old" actor name.
  • New - anything that refers to the new item you are making. If something is not referred to as "old" or "new," then it is new. For example, if you are making Armor_9001_Head then that will be referred to as either the NewActorName and the ActorName.

Vanilla weapons have the same name as their actor, model, and bfres names. For example, the actor Weapon_Sword_001 has the model name Weapon_Sword_001 and its resource files are in Weapon_Sword_001.sbfres.

Note that anytime brackets are used, this means that whatever is inside the brackets should be replaced with something else. For example, Bootup_[XXxx].pack could be replaced with Bootup_USen.pack or Bootup_EUen.pack or other names. Do NOT leave the brackets in there. Another example might be [FileName].[FileExtension] which could be replaced with just about anything, like Weapon_Sword_001.bxml or Link.Tex1.sbfres. (Note that, in this case, "Link.Tex1" is the file name and sbfres is the file extension)

If you are ever told to open a Powershell window and run a command, you can do that by holding shift, right-clicking somewhere inside the folder and clicking on "Open Powershell window here." Anytime you do this, it will be to run a Python script. All BotW modding Python scripts do not print anything to the Powershell window if they run successfully. If, at any time, one of the commands prints something to the Powershell window, stop right there and see if you can figure out what the problem is, or ask in the Discord.

Setting up your folder structure

The folder structure is important, as BotW will only load files if they're in a certain location. To begin with, you will want to create a folder structure that looks like this:

  • BreathOfTheWild_[MyAwesomeModName]
    • content
      • Actor
        • Pack
      • Model
      • Pack
      • UI
        • StockItem

Note that these names are case-sensitive.

Creating the actor

First, figure out what item (that already exists in game) behaves closest to your new item. Find the sbactorpack file for that item, and copy it to content\Actor\Pack. You will find the original file in your dumped UPDATE files (not the base game files), in the same location. (content\Actor\Pack) Make sure you copy it, and don't move the original.

Next, copy ActorInfo.product.sbyml to content\Actor in your mod files. You can find it in your dumped UPDATE files (not the base game files), in the same location. Make sure you copy it, and don't move the original.

Then, copy both Bootup.pack and Bootup_[XXxx].pack to content\Pack in your mod files. You can find them in your dumped UPDATE files (not the base game files), in the same location. There will be several Bootup_[XXxx].pack files. Each one is for a different region and language. For example, USen is for the US version, English language, while EUes is for the European version, Spanish language. Copy only the one(s) you will be making edits for, as any languages that you don't edit will have entries automatically copied into them by one of the later steps in the tutorial. For example, if you edit USen and EUes, EUen will receive your custom entries from USen, and USes will receive your custom entries from EUes.

Lastly, copy your resource files to content\Model (models and textures) and content\UI\StockItem (icons). These files aren't handled by the converter, they're explained more in depth in their own section of the tutorial.

Once you have your mod files assembled navigate to the folder that contains your BreathOfTheWild_[MyAwesomeModName] folder, open a Powershell window, and run the command hyrule_builder unbuild BreathOfTheWild_[MyAwesomeModName]. It will take a bit of time to convert the files, and then create a new folder called BreathOfTheWild_[MyAwesomeModName]_unbuilt, which contains the files you will be editing.

Editing the actor pack files

The actor pack files will be located in the various folders inside content\Actor. There will be certain parts of the files that you need to change. All instances of the old actor, model, and BFRES names will need to be changed to the new actor, model, and BFRES names. The following is a list of many of the changes that need to be made, but note that some of these may not apply to your item, and there are some changes that may not appear in this list. Be thorough when you look through the files for things that may need to be changed.

Actor pack file name changes
The underlined items need to be changed for this actor pack (in addition to the actor pack name and the contents of each file)
  • File/Folder names:
    • changing the name of the [ActorName].bmodellist file inside content\Actor\ModelList
    • changing the name of the [ModelName].bphysics file inside content\Actor\Physics
    • changing the name of the [ActorName].bxml file inside content\Actor\ActorLink
    • changing the name of the [ActorName].bgparamlist file inside content\Actor\GeneralParamList
    • changing the name of the [BfresName] folder inside content\Physics\SupportBone
    • changing the name of the [ModelName].bphyssb file inside content\Physics\SupportBone\[BfresName]
    • changing the name of the [BfresName] folder inside content\Physics\Cloth
    • changing the name of the [ModelName].hkcl file inside content\Physics\Cloth\[BfresName]
  • Inside bmodellist:
    • changing the line that says Folder: !str64 [BfresName] to the new bfres name
    • changing the line that says UnitName: !str64 [modelName] to the new model name
  • Inside bphysics:
    • changing the line that says support_bone_setup_file_path: !str256 [BfresName]/[ModelName].bphyssb to the new bfres and model names
    • changing the line that says cloth_setup_file_path: !str256 [BfresName]/[ModelName].hkcl to the new bfres and model names
    • Do not change anything with "Havok" in the name as those point to data inside the hkcl file which we cannot change. Physics should work fine without changing data inside the hkcl file, as long as you do change the name of the hkcl file.
  • Inside bxml:
    • changing the line that says ActorCaptureUser: !strRef [ActorName] to the new actor name
    • changing the line that says GParamUser: !strRef [ActorName] to the new actor name
    • changing the line that says ModelUser: !strRef [ActorName] to the new actor name
    • changing the line that says PhysicsUser: !StrRef [ModelName] to the new model name
      Example of two parameters commonly changed, inside the bgparamlist file.
  • Inside bgparamlist:
    • If your armor is upgradeable, changing the line that says NextRankName: [ActorName] to the actor name for the actor that this one upgrades into. (In game terms, "upgradeable" means via the Great Fairies)
    • The bgparamlist file also contains most of the information about the stats of items. For example, a weapon/shield's durability, a weapon's damage, a shield's block rate, an armor's defense, an armor's set (and therefore set bonus) are all stored here. You may want to change some of these things. A comprehensive list of the things inside the bgparamlist file is available here. Commonly changed parameters include: Life (the durability of the item, in the General category), Power (a weapons' damage, in the Attack category), DefenceAddLevel (an armor's defense rating, in the Armor category).

Once you've made your changes, make sure to save.

Adding the actor info

The previous step saw you creating the actual actor. This step is for creating the actor metadata that the game uses so that it knows your new actor exists. It also stores most data that appears in menus like the pause menu, crafting menu, or store menus.

Inside content\Actor\ActorInfo, you will find a file for each actor in the game. Find the one for the old actor that you are using as your base, and copy it, changing the name of the new file to [NewActorName].info.yml, then open the file in a text editor. Change the following lines:

  • bfres: [BfresName] to your new bfres name
  • itemUseIconActorName: [ActorName] to your new actor name
  • mainModel: [ModelName] to your new model name
  • Any additional information you changed in the actor pack that might be shown in any menu. For example, armor value of armor, defensive value of shields, damage of weapons, buying/selling price of items from/to a shop, crafting ingredients if the item is craftable, etc.

Once all the info is changed, make sure to save.

Creating the resource files

This section will cover the files that actually tell the game what the 3D model of the item looks like, in game. You'll need to copy the resources for the original item that you're modifying to your mod's content\Model folder. You will find the original resource files in your dumped UPDATE files (not the base game files), in the same location. (content\Model) The files will be called [OldBfresName].sbfres and [OldBfresName].Tex.sbfres. If you are modding for WiiU or Cemu, there are actually three files you will need: [OldBfresName].sbfres, [OldBfresName].Tex1.sbfres, and [OldBfresName].Tex2.sbfres. If [OldBfresName].Tex1.sbfres is not present in your UPDATE files, you will need to find it in your BASE GAME dumped files. This is the case for most, if not all, vanilla (non-DLC) items.

Once you have copied the old files to the new location, you will rename them to your new bfres name. Note that this name needs to match the bfres name you used when editing the actor pack files.

The bulk of the model replacement and texture replacement is explained in other tutorials. Once you've used those tutorials to replace the bulk of the data, we can change the names that BotW uses to refer to that data. All the rest of this section assumes that you have both sbfres files for your actor open in Switch Toolbox. (If on WiiU, you don't need to open the Tex2 file. Switch Toolbox will read its data whenever you open the Tex1 file, as long as they are in the same folder.)

The first thing to change is the bfres name. This does not happen automatically when you change the sbfres name. You can do this by clicking on the orange file labeled "FRES" on the left side, clicking on the name on the right side, and changing it.

Some important terms in modeling: A "model" is the 3D data for a whole actor. The models are everything that is inside the Models folder of the [BfresName].sbfres file. An "object" is the 3D data for a piece of an actor. The objects are everything that is inside the Models\[ModelName]\Objects folder. A single model will be made up of one or more objects. A "material" is the data the game uses to "paint" a model, so that it knows what color it is, how it reflects light, whether or not it's shiny or dull, etc. The materials are everything that is inside the Models\[ModelName]\Materials folder. A "texture" (or "map") is a single picture that contains color, light reflection, metallic, or other data for a material. Textures are contained separately, in the [BfresName].Tex.sbfres file. ([BfresName].Tex1.sbfres for WiiU/Cemu) A material will consist of one or more textures, plus shader data. (The author of this tutorial doesn't even really understand shaders. Sorry.) Each model will contain one or more materials. Each object will be assigned one material. A single material may be assigned to any number of objects.

The ModelName is important, as the game will not load the actor if the ModelName here does not match the ModelName used in the actor pack files and actor info file! Object names can be arbitrary, but they generally follow the rule: [ObjectName]__[MaterialName] where [ObjectName] is whatever you want, and [MaterialName] is the name of the material assigned to it. Adhering to this naming convention is encouraged, so that if anyone else ever tries to reuse your files, they can make sense of them. Click on the model name on the left side that you need to change. On the right side, near the top, the model name will be displayed. Click on that to edit it, and change it to your new mesh name that you used in the actor pack and actor info files. If successful, it will also change on the left side. You may also change the names of the objects and materials in the same way. When changing the names of the materials, on the right side, there will be a tab labeled Textures that will be selected by default. It will contain the names of all the textures being used by that material, and these will all be the names of the old textures. Switch over to the texture sbfres now, and change all the textures to names that fit your new actor. When you are done changing all the names of the textures, switch back to the model sbfres and look at the Textures section of the material. Click on one of the entries in the table (for example, [OldModelName]_Alb) and then click on Edit. A new window will pop up, with a list of all the textures contained in the texture sbfres. Choose the one that corresponds with the new texture (for example, [NewModelName]_Alb or [NewModelName]_Alb.0) and click save. Do this for all the entries in the Textures table for this material, and then repeat the process for every other material.

If you are editing an armor that is dyeable, you then need to expand the Animations folder on the left, then Texture Pattern Animations, then right-click the folder that corresponds to your item (Head for the head, Upper for the torso, Lower for the legs). Select Export, select to save as "Yet Another Markup Language" (or YAML Ain't Markup Language, if it's been since changed to the official name) and save it somewhere. Open the new yaml file that you just saved in a text editor. You will need to edit all the texture and material names to the new ones. For example, changing [OldModelName]_Alb.0 to [NewModelName]_Alb.0 and [OldMaterialName] to [NewMaterialName] (e.g. Mt_Hood_001 to Mt_Hood_9001). Save it, then, back in Switch Toolbox, right-click on the folder inside Texture Pattern Animations that corresponds to your item, and select Replace. Select the yaml you edited.

When you are done, select any file or folder from the model sbfres, in the list on the left, and save it. Switch Toolbox will ask if you want to Yaz0 compress the file, click Yes. Then click on any file or folder from the texture sbfres, in the list on the left, and save it. Switch Toolbox will again ask if you want to Yaz0 compress the file, click Yes. If you are editing a WiiU texture sbfres, it will then ask you to save the Tex2 sbfres, so save it and Yaz0 compress it, as well. And that's it, you are done with the files that tell the game what the new item looks like.

Creating an inventory icon

This section covers the inventory icons, the square images you see in the inventory grid in the pause menu. These files are kept in content\UI\StockItem for inventory items. Copy the old sbitemco file for the item you are using as your foundation, to the same location in your mod files (content\UI\StockItem). An sbitemco file is pretty much the same thing as an sbfres for textures, so you will edit it the same way, using Switch Toolbox. Make sure to change the name of the file to [NewActorName].sbitemco, the name of the file it contains in Toolbox to [NewActorName].bitemco, and the texture it contains to [NewActorName]

Creating an inventory name and description

For the in-game text concerning your item, you will need to navigate to content\Pack\Bootup_[XXxx].pack\Message\Msg_[XXxx].product.ssarc. There are many msbt files here, and all of them have text data for the game. For your actor, you'll look in the ActorType folder. Find the file that fits your item type, and open it in your text editor of choice.

Find the name and description entries for the item you used as your base, and copy them to the bottom of the file. An entry in this file starts on the line that says [ActorName]_Name or [ActorName]_Desc and ends one line before the next time that appears. If your item is something that would appear in the Shiekah Slate album, so that you could take pictures of it and track it on the map with the Sheikah Radar, also add an [ActorName]_PictureBook.

Change the - text: line of the name to be your new name, and the - text: line of the description to be your description. If your name or description uses apostrophes, be sure to surround it in quotes. e.g. Zora Mask is fine, but "Zora's Mask" needs the quotes because it contains an apostrophe. If you have a picture book entry as well, copy the text you made for [ActorName]_Desc into it.

When you're done, make sure to save.

Creating the save game data flags

This section covers the save game flags, which the game uses to remember whether or not you've picked up an item before. If you are adding a common item, like a material or consumable, this will make it so that the little popup that happens the first time you pick up an item, doesn't happen every single time you pick your new item up.

Navigate to content\Pack\Bootup.pack\GameData\gamedata.ssarc and find the flag for your base game item. It might be contained in any of the bool_data_#.bgdata.yml files. The name you are looking for is IsGet_[OldActorName].

After running the python command, copy the underlined result to use as your HashValue

Copy the entire section for the flag into the space right after that flag. Change IsGet_[OldActorName] to IsGet_[NewActorName]. Then, open a new Powershell window anywhere. Use the command python to enter a python command line. Run the command import ctypes; import binascii; ctypes.c_int32(binascii.crc32(IsGet_[NewActorName])).value to obtain a positive or negative number. (Bolding has been added to distinguish the name of the flag. You need to use the actual name of the flag you're adding.)

Once you've copied the boolean data section, change the DataName and HashValue to match your new item.

In your text editor, paste the result from your calculator into the HashValue after IsGet_[NewActorName], and save the file.

Finishing up and installing the mod

Now that all the files have been edited, you will need to pack them all back up. Go back to the folder that contains BreathOfTheWild_[MyAwesomeModName]_unbuilt, open a Powershell window, and run the command hyrule_builder build [--be] BreathOfTheWild_[MyAwesomeModName]_unbuilt. If you are modding for WiiU or Cemu, and don't add the --be, the error you get will seem very confusing. This is because it's looking for the Switch paths and not finding them. After a little bit of conversion, a new folder will be created, called BreathOfTheWild_[MyAwesomeModName]_unbuilt_build. That folder contains your completed mod. Delete the old BreathOfTheWild_[MyAwesomeModName] and rename the completed mod folder to BreathOfTheWild_[MyAwesomeModName].

And now you are done! To use the mod, open bcml via Powershell (just run the command bcml) and select Install... Then select Add Folder, select the BreathOfTheWild_[MyAwesomeModName] folder, and click OK. Wait for it to install, and you're ready to play the game with your new item!

Troubleshooting