Help:Adding items: Difference between revisions

{{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, as well as multiple methods for completing each step.

Adding new items requires several tools, most of which are described and are available [[Help:Setting up tools|here]].

== Tutorial ==

'''Do not skip this section, it is very important.'''

=== Setting up your folder structure ===

Note that these names are case-sensitive.

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.

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.

===== Using Wild Bits =====

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.

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.

** changing the line that says <code>Folder: !str64 [BfresName]</code> to the new BFRES name

** changing the line that says <code>UnitName: !str64 [modelName]</code> to the new model name

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

** 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)

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

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.

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.

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.

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.

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:

* <code>itemUseIconActorName: [ActorName]</code> to your new actor name

* <code>mainModel: [ModelName]</code> to your new model name

Once all the info is changed, click save.

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>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 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 [[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 sbfres files for your actor open in Switch Toolbox.

An "object" is the 3D data for a piece of an actor. The objects are everything that is inside the <code>Models\[ModelName]\Objects</code> folder.

A "material" is the data the game uses to "paint" a model, so that it knows what color it is, how it reflects light, whether or not it's shiny or dull, etc. The materials are everything that is inside the <code>Models\[ModelName]\Materials</code> folder.

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

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.

{{Empty section}}

{{Empty section}}

{{Empty section}}

[[Category:Guides]]