Help:Adding items: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
imported>Ginger
(Formatting changes, save game data section, inventory icon section, installing section)
(Updated the Python Versions and the name of BCML.)
 
(30 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{in creation}}
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.
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 ==
Two methods are provided. Using BotW Actor Tool is much simpler, but it is in a beta state and may have bugs.
 
==Required tools==
Adding new items requires several tools, most of which are described and are available [[Help:Setting up tools|here]].
Adding new items requires several tools, most of which are described and are available [[Help:Setting up tools|here]].


* [https://www.python.org/downloads/release/python-374/ Python 3.7] (Python 3.8 exists, but is known to not work with some tools) is necessary for just about every tool.
Both methods require the following:
* a text editor like [https://notepad-plus-plus.org/downloads/ Notepad++]
*[https://www.python.org/downloads/release/python-379/ Python 3.7] (64-bit) or [https://www.python.org/downloads/release/python-3810/ Python 3.8] (64-bit) is necessary for just about every tool.
* Wild Bits {{Install py package help|package=wildbits}}
*[https://github.com/KillzXGaming/Switch-Toolbox/releases Switch Toolbox]
* Breath of the Wild Cemu Mod Loader (or <code>bcml</code>) {{Install py package help|package=bcml}}
*BOTW Cross-Platform Mod Loader (or <code>bcml</code>) {{Install py package help|package=bcml}}
* [https://github.com/KillzXGaming/Switch-Toolbox/releases Switch Toolbox]
 
* BotW Duplicator Tools {{Install py package help|package=botw-duplicator-tools}}
The new method requires:
* [https://github.com/polarbunny/msyt-tools/releases/latest msyt-tools] if you'd rather use your own editor, or [https://github.com/IcySon55/Kuriimu/releases/latest Kuriimu] if you'd rather use a GUI
*BotW Actor Tool {{Install py package help|package=botw_actor_tool}}
 
The old method requires:
*A text editor like [https://notepad-plus-plus.org/downloads/ Notepad++]
*Wild Bits {{Install py package help|package=wildbits}}
*Hyrule Builder {{Install py package help|package=hyrule_builder}}
*BOTW Flag Utilities {{Install py package help|package=botw_flag_util}}
 
==Using BotW Actor Tool==
 
===Creating a mod directory===
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
 
Starred folders will be created by the actor tool if they don't already exist. Note that the folder names are case-sensitive.
 
===Setting up the tool===
Open a command prompt (WinKey + R, enter <code>cmd</code>) and use the command <code>botw_actor_tool</code> to open it.
 
If this is your first time using the actor tool, set your paths in the settings menu. If you set them wrong, the tool will warn you. They should be set as follows:
* Game directory should be the content folder of your base game dump. Example: <code>C:\Games\BotW\basegame\content</code>
* Update directory should be the content folder of your update dump. Example: <code>C:\Games\BotW\update\content</code>
* DLC directory should be the 0010 folder of your DLC dump. Example: <code>C:\Games\BotW\DLC\content\0010</code>
* Language should be set to the region and language you use. For example, USen is for United States English, while EUes is for European Spanish.
 
===Opening the base actor===
Use File -> Open Vanilla Actor to open a list of all actors from vanilla BotW. Pick the actor from the list that most closely matches your new desired item. (e.g. if you want to create a wooden shield, you would pick an actor for one of the base game's wooden shields).
 
Use https://github.com/MrCheeze/botw-tools/blob/master/botw_names.json for help finding item
 
Once the tool has loaded the actor data, click on the Model button in the Actor Property box at the top, then scroll to the bottom. There should be a single line that says <code>Folder</code>. Take note of what it says after that, as that is the name of the <code>sbfres</code> file that you will need in [[#Creating your item's resource files]]. Then switch back to the Actor Link tab by clicking on the Actor Link button in the Actor Property box.
 
===The Actor Link tab===
The Actor Link tab contains the name of your item, the names of the unique files your actor uses, plus some other tidbits. Click on the Actor Name field, and change the name to whatever new name you want, then hit the Apply button to the right of that text field.
 
Make sure your item's tags (at the bottom) are correct. The tag for a dyable armor is <code>ArmorDye</code>, the tag for a weapon that can have a picture taken for the compendium is <code>ZukanWeapon</code>, anything that can be equipped has the tag <code>CanEquip</code>, etc. If you make a change, make sure to hit the Apply button to the right before moving on.
 
===The General Param tab===
This tab 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 that can appear in this tab 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)
 
If your item is an armor that is upgradable, change the line that says <code>NextRankName: !str64 [ActorName]</code> to the actor name for the actor that this one upgrades into. (In game terms, "upgradable" means via the Great Fairies. If your armor is not upgradable, put <code>!str64 ""</code>)
 
Make sure to click the save button at the bottom before moving on.
 
===The Model tab===
On this tab, there will be a line toward the bottom that says <code>Folder:</code>.
 
If your item is an armor piece, this may not match your new armor name. Be sure to check, and change it, if necessary. Note that, if you do need to change it for an armor, you should not include the <code>_Head</code>, <code>_Upper</code>, or <code>_Lower</code> as part of the new Folder.
 
Whether or not your item is an armor piece, take note of what the Folder field now says. This will be the name for your resource files.
 
If you changed anything, make sure to click the save button at the bottom before moving on.
 
===The Texts tab===
This tab contains the entries for what text will be shown by the game.
*If your item is a cookable that has more than one recipe result (like a mushroom skewer) then you should set the BaseName to what you want displayed for its name. Otherwise, the BaseName is not used.
*Set the Name to what you want your item to be named.
*Set the Desc to what you want the inventory to display as the description of your item, when you select it.
*If your item can have a picture taken of it and be put in the compendium, set the PictureBook to field to what you want the compendium summary of the item to be. This is often a copy of Desc.
 
Again, if you changed anything, make sure to click the save button at the bottom before moving on.


== Tutorial ==
===Saving your item===
Click File -> Save, and then pick the <code>content</code> folder you created in the [[#Creating the mod directory]] step. The tool should freeze for a little less than 10 seconds while it packages all the item's data and saves all the necessary files. This should properly create <code>Actor/ActorInfo.product.sbyml</code>, <code>Pack/Bootup.pack</code>, <code>Pack/Bootup_XXxx.pack</code> (where XXxx is your region/language), and your item's <code>sbactorpack</code> file.


=== Before we begin ===
===Creating your item's resource files===
'''Do not skip this section, it is very important.'''
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 you're looking for are the ones that whose names match the <code>Folder</code> field you took note of during the [[#Opening the base actor]] step. There should be two files, one with an <code>sbfres</code> extension (the model) and one with a <code>Tex.sbfres</code> extension. '''If you are modding for WiiU or Cemu, there are actually three files you will need: <code>sbfres</code>, <code>Tex1.sbfres</code>, and <code>Tex2.sbfres</code>. If <code>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.'''
 
Once you have copied the old files to the new location, you need to rename them to whatever it said in the <code>Folder</code> field you took note of during [[#The Model tab]] step.


This tutorial will use several terms that you may not be familiar with, or will have specific definitions you may not have used before:
The bulk of the [[Help:Replacing models|model replacement]] and [[Help:Replacing textures|texture replacement]] is explained in the tutorials linked there. 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.)


* 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>
The first thing to change is the <code>bfres</code> name. This did not happen automatically when you renamed the file. 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.
* 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.


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>.
Some important terms in modeling:
A "model" is the 3D data for a whole actor. The models are everything that is inside the <code>Models</code> folder inside the <code>sbfres</code> file.
An "object" is the 3D data for a piece of an actor. The objects are everything that is inside the <code>Objects</code> folders inside the <code>Models</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>Materials</code> folders inside the <code>Models</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>Tex.sbfres</code> file. (<code>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.


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)
The name of the model (inside the <code>Models</code> folder) is important, as the game will not load the actor if the model name doesn't match your item's actor name as you entered it in the actor tool! 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 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. If you try to continue on, then 99% of the time you won't be able to, and the other 1% of the time, everything will have broken horribly. If worse comes to worst, you can also try one of the other methods. That's why this tutorial contains multiple, wherever possible.
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.


=== Setting up your folder structure ===
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 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]
===Creating an inventory icon===
** content
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].sbitemico</code>, the name of the file it contains in Toolbox to <code>[NewActorName].bitemico</code>, and the texture it contains to <code>[NewActorName]</code>
*** Actor
**** Pack
*** Model
*** Pack
*** UI
**** StockItem


Note that these names are case-sensitive.
===Installing the mod===
And now you are done! Basically! Use the directions located [[Help:Using_mods#Installing_mods_with_the_graphic_pack_menu|here]] to make a rules.txt if you haven't already. To use the mod, open <code>bcml</code> via command prompt (just run the command <code>bcml</code>) and click the blue circle in the bottom right. Then select Browse, select the rules.txt inside your <code>BreathOfTheWild_[MyAwesomeModName]</code> folder, and click Install. Wait for it to install, and you're ready to play the game with your new item!


=== Create the actor ===
==Using text editors and WildBits==
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.


==== Unpack the actor pack ====
===Before we begin===
Not every file in the actor pack will need to be edited, and there are multiple ways to obtain the file from the actor pack. Any of the following three ways should work. You need only use one method. If one doesn't work for you, try another one. You will be editing any file that contains the actor name as its file name, or contains that actor name inside it. For most actors, that means the files with file extensions <code>bxml</code>, <code>bmodellist</code>, <code>bgparamlist</code>, and <code>bphysics</code>. If the item is craftable, you will also need to change the file with file extension <code>brecipe</code>. If the actor has physics, you will also need to change the files with file extensions <code>bphyssb</code> and <code>hkcl</code>. Other actor types may have additional files to change, so look thoroughly.
'''Do not skip this section, it is very important.'''


===== Using Switch Toolbox =====
This tutorial will use several terms that you may not be familiar with, or will have specific definitions you may not have used before:
Open Switch Toolbox, and then open the actor pack file in it. Expand the folders on the left side to find the files you need to edit, right click on them, and select Export Raw Data To File Location. You can then find the files in the same folder as the actor pack. Then, open a Powershell window in that folder, and use the command <code>byml_to_yml [FileName].[FileExtension] [FileName].[FileExtension].yml</code> for each file you extracted. Then open the files in the editor of your choice.


===== Using Wild Bits =====
*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>
Open Wild Bits, navigate to the SARC Tools tab, then open the actor pack file in it. You will see a hierarchy of the folders. Search for one of the files you need to modify, right-click on it, and open it in the AAMP editor. Wild Bits will automatically take you to the YAML Tools tab and open the file for editing.
*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.


===== Using <code>sarc</code> =====
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>.
Open Powershell window in the folder containing the actor pack. Use the command <code>sarc extract [FileName].sbactorpack</code>. This will create a new folder with all of the individual files. For each file you modify, you will need to open another Powershell window in that folder and use the command <code>byml_to_yml [FileName].[FileExtension] !!.yml</code>. Then open the files in the editor of your choice.


==== Editing the actor pack files ====
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)
Once you've got the actor files opened in the editor you want, 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)]]File/Folder names:
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.
** changing the name of the <code>[ActorName].bmodellist</code> file inside <code>Actor/ModelList</code>
** changing the name of the <code>[ModelName].bphysics</code> file inside <code>Actor/Physics</code>
** changing the name of the <code>[ActorName].bxml</code> file inside <code>Actor/ActorLink</code>
** changing the name of the <code>[ActorName].bgparamlist</code> file inside <code>Actor/GeneralParamList</code>
** changing the name of the <code>[BfresName]</code> folder inside <code>Physics/SupportBone</code>
** changing the name of the <code>[ModelName].bphyssb</code> file inside <code>Physics/SupportBone/[BfresName]</code>
** changing the name of the <code>[BfresName]</code> folder inside <code>Physics/Cloth</code>
** changing the name of the <code>[ModelName].hkcl</code> file inside <code>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).


Once you've made your changes, '''make sure to save'''.
===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:


==== Pack the actor pack ====
*BreathOfTheWild_[MyAwesomeModName]
Once all the edits have been made, you are ready to put everything back into the actor pack. As with unpacking it, each method has its own way of packing it again.
**content
***Actor
****Pack
***Model
***Pack
***UI
****StockItem


===== Using Switch Toolbox =====
Note that these names are case-sensitive.
First you will need to convert the text actor files back to their corresponding types. Open a Powershell window in the folder that contains the files you changed, and use the command <code>yml_to_byml [FileName].[FileExtension].yml [FileName].[FileExtension]</code> for each file you extracted. '''If you are modding for WiiU or Cemu, the command is, instead, <code>yml_to_byml -b [FileName].[FileExtension].yml [FileName].[FileExtension]</code>'''


Open the actor pack in Switch Toolbox again. Switch Toolbox is kind of wonky, and doesn't like replacing data for existing files, but it can import new data just fine. So, for every file you're going to add back into the actor pack, you will delete the original file, then right-click on the folder that contained it, and select to import the new file. Then click to save the file. Make sure you change the name of the file to the new actor name! You will be asked to Yaz0 compress the file. Click yes. And now you're done.
===Creating the actor===
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.


===== Using Wild Bits =====
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.
When you've made your changes to the files in the YAML Tools tab and saved them, just click the button to save the actor pack, then change the name of the actor pack file to the new actor name. That's it, you're done.


===== Using <code>sarc</code> =====
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.
First, convert the text actor files back to their corresponding types. Open a Powershell window in the folder that contains the files you changed, and use the command <code>yml_to_byml [FileName].yml !!.[FileExtension]</code> for each file you extracted. '''If you are modding for WiiU or Cemu, the command is, instead, <code>yml_to_byml -b [FileName].yml !!.[FileExtension]</code>'''. Once you have converted a yml file back to its original file type, make sure you delete the yml file. If you do not, it will be packed into the actor pack and that will cause errors and crashes.


Once you have converted all of the files back to their original types and deleted all the yml files, return to the <code>content\Actor\Pack</code> folder of your mod, and open another Powershell window, then pack everything back into the actor pack with the command <code>sarc create [FolderName] [FileName].sbactorpack</code>. '''If you are modding for WiiU or Cemu, the command is, instead, <code>sarc create [FolderName] [FileName].sbactorpack -b</code>'''. Once you have done so, make sure you change the name of the actor pack to the new actor name (you can also just use the new actor name as the FileName in the Powershell command). After that, make sure you delete the folder of un-sarc'ed actor files, and the old actor pack, if applicable. And you are now done.
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.


=== Add the actor info to the ActorInfo.product file ===
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.
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. There are two main ways to do this, but first we need to copy the file so we can edit it. Find the original ActorInfo.product.sbyml file in your dumped UPDATE files (not the base game files), in <code>content\Actor</code>, and copy it to the same place in your mod's files. (<code>content\Actor</code>) Make sure you copy it, and don't move the original.


Then, open a Powershell window where your copied ActorInfo.product file is, and run the command <code>actorinfo_tool ActorInfo.product.sbyml duplicate [OldActorName] [NewActorName]</code> where the old actor name is the actor you copied during the Create the Actor step of this tutorial. '''If you are modding for WiiU or Cemu, the command is, instead, <code>actorinfo_tool -b ActorInfo.product.sbyml duplicate [OldActorName] [NewActorName]</code>'''.
===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)]]


==== Using Wild Bits ====
*File/Folder names:
Open Wild Bits, and go to the YAML Tools tab. Open your ActorInfo.product file. Find the entry you duplicated (it will have your new actor name on the line <code>name: [NewActorName]</code>). Change the following lines:
**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: [ActorName]</code> to the new actor name
**changing the line that says <code>GParamUser: [ActorName]</code> to the new actor name
**changing the line that says <code>ModelUser: [ActorName]</code> to the new actor name
**changing the line that says <code>PhysicsUser: [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 item is an armor that is upgradeable, changing the line that says <code>NextRankName: !str64 [ActorName]</code> to the actor name for the actor that this one upgrades into. (In game terms, "upgradeable" means via the Great Fairies. If your armor is not upgradable, put <code>!str64</code> noting the extra space after the 4)
**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).


* <code>bfres: [BfresName]</code> to your new <code>bfres</code> name
Once you've made your changes, '''make sure to save'''.
* <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.


Once all the info is changed, click 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.


==== Using a text editor ====
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:
Open a Powershell window where your copied ActorInfo.product is (you probably already have one open from when you ran the <code>actorinfo_tool</code> command) and run the command <code>byml_to_yml ActorInfo.product.sbyml !!.yml</code>. Open the new ActorInfo.product.yml file in your file editor of choice. Find the entry you duplicated (it will have your new actor name on the line <code>name: [NewActorName]</code>). Change the following lines:


* <code>bfres: [BfresName]</code> to your new <code>bfres</code> name
*<code>bfres: [BfresName]</code> to your new <code>bfres</code> name
* <code>itemUseIconActorName: [ActorName]</code> to your new actor name
*<code>itemUseIconActorName: [ActorName]</code> should have the [ActorName] replaced with just '''""''' if you're using your own icon, otherwise replace it with the actor name of the icon you'll be using
* <code>mainModel: [ModelName]</code> to your new model 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.
*<code>name: [ActorName]</code> to your new actor 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, click save. Open another Powershell window where <code>ActorInfo.product.yml</code> is (you might have left the previous one open, you can use that), and run the command <code>yml_to_byml ActorInfo.product.yml !!.sbyml</code>. '''If you are modding for WiiU or Cemu, the command is, instead,<code>yml_to_byml -b ActorInfo.product.yml !!.sbyml</code>'''. Delete <code>ActorInfo.product.yml</code>, because it has been converted back and is no longer needed.
Once all the info is changed, '''make sure to save'''.


=== Creating the resource files ===
===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 <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.'''
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.'''


Line 141: Line 216:
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.)
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.)


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 right-clicking on the orange file labeled "FRES" on the left side and selecting Rename.
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.


Some important terms in modeling:
Some important terms in modeling:
Line 157: Line 232:
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 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.
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.
[[File:Addingitems_bftxp.png|alt=Bftxp file editing|thumb|Some of the parts of a bftxp file that need to be edited (underlined in red)]]
 
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, and save it somewhere. Open the new <code>bftxp</code> file that you just saved in a text editor. It will contain a lot of gibberish and empty space. '''Make sure you only edit data that is in plain English, editing anything else will break the file.''' 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>bftxp</code> you edited.
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.


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.
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.


=== Creating an inventory icon ===
===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>
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].sbitemico</code>, the name of the file it contains in Toolbox to <code>[NewActorName].bitemico</code>, and the texture it contains to <code>[NewActorName]</code>
 
===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.
 
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>.
 
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.
 
When you're done, '''make sure to save'''.


=== Creating an inventory name and description ===
===Converting back===
{{Empty section}}
Now that almost 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, add the --be. If you don't, 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].


=== Creating the save game data flags ===
===Creating the save game data flags===
[[File:Addingitems crc32hash.png|thumb|Click on the three lines (1) to select Programmer, then click on (3) until it says DWORD, then click on HEX in (2), paste your CRC-32 result, and click on DEC in (2) to get the value you need.]]
'''You should ignore this section if you are making something that never goes into Link's inventory.'''
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.


Save flags are all stored in <code>Bootup.pack</code>, so you're going to copy that file from your UPDATE data's <code>content\Pack</code> to the same place in your mod files. You will then open a Powershell window in that folder, and use the command <code>sarc extract Bootup.pack</code> to extract it. This will extract all the data inside the file into folders. Navigate to the new <code>content\Pack\Bootup\GameData</code> and find <code>gamedata.ssarc</code>. Open a new Powershell window here and use the command <code>sarc extract gamedata.ssarc</code>. This will create a new folder named <code>gamedata</code>. Go inside that folder and find <code>bool_data_0.bgdata</code>. Open yet another Powershell window here and run the command <code>byml_to_yml bool_data_0.bgdata !!.yml</code> to convert it to text, and then open the new <code>bool_data_0.yml</code> in a text editor.
This section covers the save game flags, which the game uses to remember certain things about your item. 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. It also remembers other things, like whether or not a picture has been taken of your item, whether or not you decided to save that picture, how big the picture is, how long it's been in your inventory, and how long you've had it equipped.


Inside that file, find the text <code>IsGet_[OldActorName]</code> and copy the entire section into the space right after it. Change <code>IsGet_[OldActorName]</code> to <code>IsGet_[NewActorName]</code>. Then, go to [https://crccalc.com/ this website] and paste <code>IsGet_[NewActorName]</code> into the field, and click Calc CRC-32. Copy the result in the Result column for the CRC-32 row.
Navigate to the folder that contains your BreathOfTheWild_[MyAwesomeModName] folder you made, open a Powershell window, and run the command <code>botw_flag_util generate BreathOfTheWild_[MyAwesomeModName] -a [-b]</code>. '''If you are modding for WiiU or Cemu, add the -b. If modding for Switch, don't add it. If you run it the wrong way by accident, just run it again the right way. It will let you know that nothing changed, and then write the file for the other console.'''


Next, open the standard Windows calculator, for example by pressing WindowsKey+R, typing "calc" and hitting enter. Change your calculator to programmer mode by clicking on the 3 horizontal lines on the top left, and selecting Programmer. There should be a big 0 near the top middle, and, below that and to the left, four labels: HEX, DEC, OCT, and BIN, all of which should be 0. Right below those and to the right should be either QWORD, DWORD, WORD, or BYTE. Click on that until it says DWORD.
===Installing the mod===
And now you are done! Basically! Use the directions located [[Help:Using_mods#Installing_mods_with_the_graphic_pack_menu|here]] to make a rules.txt if you haven't already. 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!


Click on HEX to enter hexadecimal mode, and then paste the CRC-32 you copied. Click on DEC, and it will convert that to a number. Remove the commas from the result.
==Troubleshooting==
[[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.


Open a Powershell window in the folder with <code>bool_data_0.yml</code> and run the command <code>byml_to_yml bool_data_0.yml !!.bgdata</code> . '''If you are modding for WiiU or Cemu, the command is, instead,<code>byml_to_yml -b bool_data_0.yml !!.bgdata</code>'''. Once it's converted, delete <code>bool_data_0.yml</code>.
===My actor isn't appearing in the game!===
Make sure the actor's info entry (part 5 of the tutorial) is correct. Formatting is important here. It's also important to make sure your actor's name is valid. If it isn't, the game won't know what to do with it, so it won't create it. For example, weapons need to be named <code>Weapon_[WeaponProfile]_[AnythingElseYouWant]</code>, while armors need to be named <code>Armor_[ThreeDigitNumber]_[AnythingElseYouWant]_[Head/Upper/Lower]</code> (Except <code>Armor_001_Head</code> or <code>Armor_001_G_Head</code> both work, but <code>Armor_001__Head</code> doesn't because it has two underscores between 001 and Head)


Go up one folder, to <code>content\Pack\Bootup\GameData</code> and open a new Powershell window. Run the command <code>sarc create gamedata gamedata.ssarc</code>. '''If you are modding for WiiU or Cemu, the command is, instead,<code>sarc create gamedata gamedata.ssarc -b</code>'''. Once it's converted, delete the gamedata folder.
===My weapon/armor actor is appearing in my inventory, but it doesn't equip and disappears if I try to drop it from my inventory!===
This one's difficult: Something, somewhere, in the actor or in one of the resource files, is broken. It could be just about anything except for the text and flags. Whenever the game encounters something it doesn't expect, it silently fails and doesn't create the actor, but doesn't tell you why. There isn't really any better way to pinpoint what could be causing the issue.


Go up two folders, to <code>content\Pack</code>, and open a new Powershell window. Run the command <code>sarc create Bootup Bootup.pack</code>. '''If you are modding for WiiU or Cemu, the command is, instead,<code>sarc create Bootup Bootup.pack -b</code>'''. Once it's converted, delete the Bootup folder.
===My game is crashing when loading the item!===
Another difficult one, but typically this is because the way you placed the item in the world (which is not covered by this tutorial) was wrong, or, if it's crashing when equipping it (if an item) or when loading it into the world (if it's a field object), it's because the model is broken. Check the [[Help:Replacing models|model replacement tutorial]] for info on the "vertex buffers" and what to do about them.


=== Finishing up and installing the mod ===
===My game is crashing after shaders compile!===
And now you are done! There is a file that remains to be edited, called the RSTB, but you should not manually edit that file anymore, as there are so many other mods that edit it, along with the ActorInfo.product file, the Bootup and Bootup_XXxx packs, that it is not going to be compatible with any other mod that also does so. Instead we use <code>bcml</code> to install mods, merge the changes made to those files, and edit the RSTB for us. 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!
Depending on how many mods you have installed, the number of game data flags your game has can cause it to crash. The game loads all flags into a special section of memory when booting up, and if too many flags are loaded, the game doesn't have enough memory to hold them all, and crashes. The Wii U version is limited to about 650 more flags than the vanilla game has. We don't know the limit of the Switch version, but we do know that it is much higher, due to the much larger amount of memory the Switch has.


== Troubleshooting ==
Alternatively, the [[RSTB]] may have not been edited correctly, or it may be getting overridden by a file from another mod, if you're using more than one (or not using BCML to install ''all'' of your mods). 99.9% of the time, BCML will generate things correctly, but if you've ruled out every other option, then check the BCML merged mod's RSTB entries against those found in BCML's data folder's log files.
{{Empty section}}
[[Category:Guides]]
[[Category:Guides]]

Latest revision as of 23:59, 29 August 2022

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.

Two methods are provided. Using BotW Actor Tool is much simpler, but it is in a beta state and may have bugs.

Required tools

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

Both methods require the following:

The new method requires:

The old method requires:

Using BotW Actor Tool

Creating a mod directory

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

Starred folders will be created by the actor tool if they don't already exist. Note that the folder names are case-sensitive.

Setting up the tool

Open a command prompt (WinKey + R, enter cmd) and use the command botw_actor_tool to open it.

If this is your first time using the actor tool, set your paths in the settings menu. If you set them wrong, the tool will warn you. They should be set as follows:

  • Game directory should be the content folder of your base game dump. Example: C:\Games\BotW\basegame\content
  • Update directory should be the content folder of your update dump. Example: C:\Games\BotW\update\content
  • DLC directory should be the 0010 folder of your DLC dump. Example: C:\Games\BotW\DLC\content\0010
  • Language should be set to the region and language you use. For example, USen is for United States English, while EUes is for European Spanish.

Opening the base actor

Use File -> Open Vanilla Actor to open a list of all actors from vanilla BotW. Pick the actor from the list that most closely matches your new desired item. (e.g. if you want to create a wooden shield, you would pick an actor for one of the base game's wooden shields).

Use https://github.com/MrCheeze/botw-tools/blob/master/botw_names.json for help finding item

Once the tool has loaded the actor data, click on the Model button in the Actor Property box at the top, then scroll to the bottom. There should be a single line that says Folder. Take note of what it says after that, as that is the name of the sbfres file that you will need in #Creating your item's resource files. Then switch back to the Actor Link tab by clicking on the Actor Link button in the Actor Property box.

The Actor Link tab

The Actor Link tab contains the name of your item, the names of the unique files your actor uses, plus some other tidbits. Click on the Actor Name field, and change the name to whatever new name you want, then hit the Apply button to the right of that text field.

Make sure your item's tags (at the bottom) are correct. The tag for a dyable armor is ArmorDye, the tag for a weapon that can have a picture taken for the compendium is ZukanWeapon, anything that can be equipped has the tag CanEquip, etc. If you make a change, make sure to hit the Apply button to the right before moving on.

The General Param tab

This tab 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 that can appear in this tab 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)

If your item is an armor that is upgradable, change the line that says NextRankName: !str64 [ActorName] to the actor name for the actor that this one upgrades into. (In game terms, "upgradable" means via the Great Fairies. If your armor is not upgradable, put !str64 "")

Make sure to click the save button at the bottom before moving on.

The Model tab

On this tab, there will be a line toward the bottom that says Folder:.

If your item is an armor piece, this may not match your new armor name. Be sure to check, and change it, if necessary. Note that, if you do need to change it for an armor, you should not include the _Head, _Upper, or _Lower as part of the new Folder.

Whether or not your item is an armor piece, take note of what the Folder field now says. This will be the name for your resource files.

If you changed anything, make sure to click the save button at the bottom before moving on.

The Texts tab

This tab contains the entries for what text will be shown by the game.

  • If your item is a cookable that has more than one recipe result (like a mushroom skewer) then you should set the BaseName to what you want displayed for its name. Otherwise, the BaseName is not used.
  • Set the Name to what you want your item to be named.
  • Set the Desc to what you want the inventory to display as the description of your item, when you select it.
  • If your item can have a picture taken of it and be put in the compendium, set the PictureBook to field to what you want the compendium summary of the item to be. This is often a copy of Desc.

Again, if you changed anything, make sure to click the save button at the bottom before moving on.

Saving your item

Click File -> Save, and then pick the content folder you created in the #Creating the mod directory step. The tool should freeze for a little less than 10 seconds while it packages all the item's data and saves all the necessary files. This should properly create Actor/ActorInfo.product.sbyml, Pack/Bootup.pack, Pack/Bootup_XXxx.pack (where XXxx is your region/language), and your item's sbactorpack file.

Creating your item's resource files

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 you're looking for are the ones that whose names match the Folder field you took note of during the #Opening the base actor step. There should be two files, one with an sbfres extension (the model) and one with a Tex.sbfres extension. If you are modding for WiiU or Cemu, there are actually three files you will need: sbfres, Tex1.sbfres, and Tex2.sbfres. If 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 need to rename them to whatever it said in the Folder field you took note of during #The Model tab step.

The bulk of the model replacement and texture replacement is explained in the tutorials linked there. 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 did not happen automatically when you renamed the file. 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 inside the sbfres file. An "object" is the 3D data for a piece of an actor. The objects are everything that is inside the Objects folders inside the Models 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 Materials folders inside the Models 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 Tex.sbfres file. (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 name of the model (inside the Models folder) is important, as the game will not load the actor if the model name doesn't match your item's actor name as you entered it in the actor tool! 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].sbitemico, the name of the file it contains in Toolbox to [NewActorName].bitemico, and the texture it contains to [NewActorName]

Installing the mod

And now you are done! Basically! Use the directions located here to make a rules.txt if you haven't already. To use the mod, open bcml via command prompt (just run the command bcml) and click the blue circle in the bottom right. Then select Browse, select the rules.txt inside your BreathOfTheWild_[MyAwesomeModName] folder, and click Install. Wait for it to install, and you're ready to play the game with your new item!

Using text editors and WildBits

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.

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: [ActorName] to the new actor name
    • changing the line that says GParamUser: [ActorName] to the new actor name
    • changing the line that says ModelUser: [ActorName] to the new actor name
    • changing the line that says PhysicsUser: [ModelName] to the new model name
      Example of two parameters commonly changed, inside the bgparamlist file.
  • Inside bgparamlist:
    • If your item is an armor that is upgradeable, changing the line that says NextRankName: !str64 [ActorName] to the actor name for the actor that this one upgrades into. (In game terms, "upgradeable" means via the Great Fairies. If your armor is not upgradable, put !str64 noting the extra space after the 4)
    • 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] should have the [ActorName] replaced with just "" if you're using your own icon, otherwise replace it with the actor name of the icon you'll be using
  • mainModel: [ModelName] to your new model name
  • name: [ActorName] to your new actor 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].sbitemico, the name of the file it contains in Toolbox to [NewActorName].bitemico, 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.

Converting back

Now that almost 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, add the --be. If you don't, 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].

Creating the save game data flags

You should ignore this section if you are making something that never goes into Link's inventory.

This section covers the save game flags, which the game uses to remember certain things about your item. 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. It also remembers other things, like whether or not a picture has been taken of your item, whether or not you decided to save that picture, how big the picture is, how long it's been in your inventory, and how long you've had it equipped.

Navigate to the folder that contains your BreathOfTheWild_[MyAwesomeModName] folder you made, open a Powershell window, and run the command botw_flag_util generate BreathOfTheWild_[MyAwesomeModName] -a [-b]. If you are modding for WiiU or Cemu, add the -b. If modding for Switch, don't add it. If you run it the wrong way by accident, just run it again the right way. It will let you know that nothing changed, and then write the file for the other console.

Installing the mod

And now you are done! Basically! Use the directions located here to make a rules.txt if you haven't already. 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

My actor isn't appearing in the game!

Make sure the actor's info entry (part 5 of the tutorial) is correct. Formatting is important here. It's also important to make sure your actor's name is valid. If it isn't, the game won't know what to do with it, so it won't create it. For example, weapons need to be named Weapon_[WeaponProfile]_[AnythingElseYouWant], while armors need to be named Armor_[ThreeDigitNumber]_[AnythingElseYouWant]_[Head/Upper/Lower] (Except Armor_001_Head or Armor_001_G_Head both work, but Armor_001__Head doesn't because it has two underscores between 001 and Head)

My weapon/armor actor is appearing in my inventory, but it doesn't equip and disappears if I try to drop it from my inventory!

This one's difficult: Something, somewhere, in the actor or in one of the resource files, is broken. It could be just about anything except for the text and flags. Whenever the game encounters something it doesn't expect, it silently fails and doesn't create the actor, but doesn't tell you why. There isn't really any better way to pinpoint what could be causing the issue.

My game is crashing when loading the item!

Another difficult one, but typically this is because the way you placed the item in the world (which is not covered by this tutorial) was wrong, or, if it's crashing when equipping it (if an item) or when loading it into the world (if it's a field object), it's because the model is broken. Check the model replacement tutorial for info on the "vertex buffers" and what to do about them.

My game is crashing after shaders compile!

Depending on how many mods you have installed, the number of game data flags your game has can cause it to crash. The game loads all flags into a special section of memory when booting up, and if too many flags are loaded, the game doesn't have enough memory to hold them all, and crashes. The Wii U version is limited to about 650 more flags than the vanilla game has. We don't know the limit of the Switch version, but we do know that it is much higher, due to the much larger amount of memory the Switch has.

Alternatively, the Resource system may have not been edited correctly, or it may be getting overridden by a file from another mod, if you're using more than one (or not using BCML to install all of your mods). 99.9% of the time, BCML will generate things correctly, but if you've ruled out every other option, then check the BCML merged mod's RSTB entries against those found in BCML's data folder's log files.