Help:Adding 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

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

• Python 3.7 (Python 3.8 exists, but is known to not work with some tools) is necessary for just about every tool.
• a text editor like Notepad++
• Wild Bits ^{[CLI help]}
• Breath of the Wild Cemu Mod Loader (or bcml) ^{[CLI help]}
• Switch Toolbox
• BotW Duplicator Tools ^{[CLI help]}
• msyt-tools if you'd rather use your own editor, or Kuriimu if you'd rather use a GUI

Tutorial

Before We Begin

Do not skip this section, it is very important.

This tutorial will use several terms that you may not be familiar with:

• 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 (Armor_001 out of Armor_001_Upper).
• 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 armor actors that end in _Head_A. Their ActorName will end in _Head, and their ModelName will end in _Head_A.

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's inside the brackets should be replaced with something else. For example, Bootup_[XXxx].pack could be replaced with Bootup_USen.pack or Bootup_EUen.pack or other names. Do NOT leave the brackets in there. Another example might be [FileName].[FileExtension] which could be replaced with just about anything, like Weapon_Sword_001.bxml or Link.Tex1.sbfres. (Note that, in this case, "Link.Tex1" is the file name and "sbfres" is the file extension)

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

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.

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

Unpack the Actor Pack

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 bxml, bmodellist, bgparamlist, and bphysics. If the item is craftable, you will also need to change the file with file extension brecipe. If the actor has physics, you will also need to change the files with file extensions bphyssb and hkcl. Other actor types may have additional files to change, so look thoroughly.

Using Switch Toolbox

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 byml_to_yml [FileName].[FileExtension] [FileName].[FileExtension].yml for each file you extracted. Then open the files in the editor of your choice.

Using Wild Bits

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.

Using SARC

Open Powershell window in the folder containing the actor pack. Use the command sarc extract [FileName].sbactorpack. 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 byml_to_yml [FileName].[FileExtension] !!.yml. Then open the files in the editor of your choice.

Editing the Actor Pack Files

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/Folder names:
  • changing the name of the [ActorName].bmodellist file inside Actor/ModelList.
  • changing the name of the [ModelName].bphysics file inside Actor/Physics.
  • changing the name of the [ActorName].bxml file inside Actor/ActorLink.
  • changing the name of the [ActorName].bgparamlist file inside Actor/GeneralParamList.
  • changing the name of the [BfresName] folder inside Physics/SupportBone.
  • changing the name of the [ModelName].bphyssb file inside Physics/SupportBone/[BfresName]
  • changing the name of the [BfresName] folder inside Physics/Cloth.
  • changing the name of the [ModelName].hkcl file inside Physics/Cloth/[BfresName]
• Inside bmodellist:
  • changing the line that says Folder: !str64 [BfresName] to the new BFRES name
  • changing the line that says UnitName: !str64 [modelName] to the new model name
• Inside bphysics:
  • changing the line that says support_bone_setup_file_path: !str256 [BfresName]/[ModelName].bphyssb" to the new BFRES and model names
  • changing the line that says cloth_setup_file_path: !str256 [BfresName]/[ModelName].hkcl" to the new BFRES and model names
  • Do not change anything with "Havok" in the name as those point to data inside the hkcl file which we cannot change. Physics should work fine without changing data inside the hkcl file, as long as you do change the name of the hkcl file.
• Inside bxml:
  • changing the line that says ActorCaptureUser: !strRef [ActorName] to the new actor name
  • changing the line that says GParamUser: !strRef [ActorName] to the new actor name
  • changing the line that says ModelUser: !strRef [ActorName] to the new actor name
  • changing the line that says PhysicsUser: !StrRef [ModelName] to the new model name
• Inside bgparamlist:
  • If your armor is upgradeable, changing the line that says NextRankName: [ActorName] to the actor name for the actor that this one upgrades into. (In game terms, "upgradeable" means via the Great Fairies)
  • The bgparamlist file also contains most of the information about the stats of items. For example, a weapon/shield's durability, a weapon's damage, a shield's block rate, an armor's defense, an armor's set (and therefore set bonus) are all stored here. You may want to change some of these things. A comprehensive list of the things inside the bgparamlist file is available here.

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

Pack the Actor Pack

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.

Using Switch Toolbox

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 yml_to_byml [FileName].[FileExtension].yml [FileName].[FileExtension] for each file you extracted. If you are modding for WiiU or Cemu, the command is, instead, yml_to_byml -b [FileName].[FileExtension].yml [FileName].[FileExtension]

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.

Using Wild Bits

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 SARC

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 yml_to_byml [FileName].yml !!.[FileExtension] for each file you extracted. If you are modding for WiiU or Cemu, the command is, instead, yml_to_byml -b [FileName].yml !!.[FileExtension]. 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 content\Actor\Pack folder of your mod, and open another Powershell window, then pack everything back into the actor pack with the command sarc create [FolderName] [FileName].sbactorpack. If you are modding for WiiU or Cemu, the command is, instead, sarc create [FolderName] [FileName].sbactorpack -b. 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.

Add the Actor Info to the ActorInfo.product file

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 content\Actor, and copy it to the same place in your mod's files. (content\Actor) 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 actorinfo_tool ActorInfo.product.sbyml duplicate [OldActorName] [NewActorName] 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, actorinfo_tool -b ActorInfo.product.sbyml duplicate [OldActorName] [NewActorName].

Using Wild Bits

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 name: [NewActorName]). Change the following lines:

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

Once all the info is changed, click save.

Using a Text Editor

Open a Powershell window where your copied ActorInfo.product is (you probably already have one open from when you ran the actorinfo_tool command) and run the command byml_to_yml ActorInfo.product.sbyml !!.yml. 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 name: [NewActorName]). Change the following lines:

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

Once all the info is changed, click save. Open another Powershell window where the ActorInfo.product.yml file is (you might have left the previous one open, you can use that), and run the command yml_to_byml ActorInfo.product.yml !!.sbyml. If you are modding for WiiU or Cemu, the command is, instead,yml_to_byml -b ActorInfo.product.yml !!.sbyml. Delete the ActorInfo.product.yml file, because it has been converted back to sbyml.

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.

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 "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) 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, 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.