Help:Creating mods: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
imported>Leoetlino
No edit summary
(Added a proper guide to creating mods with BCML. Updated some of the other notes.)
(20 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Welcome, modders! This page is intended to be a collection of useful information for anybody who wants to create mods. If you want to simply use other people's mods, see [[Help:Playing with mods]].
Welcome, modders! This page contains useful information for anybody who wants to create mods. If you just want to use other people's mods, see [[Help:Using mods]].


<div class="toclimit-3">__TOC__</div>
== What can currently be modded? ==
 
* Textures
* Models
* Actor parameters, including enemies, weapons, and armors
* Adding new actors
* Overworld and dungeon map files
* Event flows, and as a direct consequence: cutscenes, NPC interactions, quests, minigames, etc.
* Animations and various animation parameter files
* Rigid body collisions
* Text / dialogue
* UI elements (HUD, title screen, logos, etc.)
* Music and audio (cannot add new tracks, only edit/replace existing)
* Effects and shaders (limited)


== Getting set up ==
== Getting set up ==
To make mods, you'll need to start by dumping the unedited game files from your copy of BotW.
<br>
* [[Help:Playing with mods#Wii U/Cemu|Dumping the game files (Wii U)]]
{{linkbox
* [[Help:Dumping games|Dumping the game files (Switch)]]
| title = [[help:Dumping games|Dumping the game files]]
| text = To make mods, you'll need to start by dumping the unedited game files from your copy of BotW.
| faiconc = fas fa-copy
}}
{{linkbox
| title = [[help:Setting up tools|Setting up tools]]
| text = Since BotW uses a lot of Nintendo's own file formats, you'll need tools to be able to edit them.
| faiconc = fas fa-toolbox
}}
 
== About BNPs ==
 
Modding has come a long way, and creating them has never been easier with BCML and the BNP (BOTW Nano Patch) format.
 
BNPs are a crucial part of modding Breath of the Wild, as they allow for small package distribution and accurate merging when used with BCML.
 
For more information on BNPs, check out [https://github.com/Torphedo/BOTW-ModdingGuide/blob/main/BCML-development.md this detailed guide] by Torphedo.
 
=== Creating BNPs ===
BNPs can be made using the BCML BNP Creator in the Dev Tools tab.
 
The BNP Creator requires two fields to create a BNP, a name, and a mod folder.


== Files, Tools and Tutorials ==
<br>
Since BotW uses a lot of Nintendo's own file formats, you'll need tools to be able to edit them. To use leoetlino's tools, you need to install the latest version of Python (64 bit version), and tick the "Add to PATH" / "Add to environment variables" box in the installer. Then, to install the tool, run <code>pip install TOOL_NAME</code> in the command line.


If you're not sure which tool to use on a file, search for its extension on this wiki to find what file format that extension is used for.
==== Name ====
The name can be anything you choose, usually something that tells people what the mod is.<br>
Example: "Invisible Majora's Mask" implies that it makes Majora's mask invisible, which it does.


=== Yaz0 compression ===
<br>
Many files in the game are compressed with [[Yaz0]]. Compressed files generally have the letter <code>s</code> prefixed to their file extension.


The recommended tool for manipulating these files is [[Help:Tools/wszst|wszst]].
==== Mod Folder ====
{{tool guide|tool=wszst}}
The mod folder is the <i>contents</i> of the mod. This folder requires at least one of the following folders (case sensitive):
<ul>
<li><u>content</u>: Holds general content such as game models, effects, sounds, etc. (WiiU)</li>
<li><u>aoc</u>: Has similar files as <u>content</u>, but this folder overwrites the DLC files instead of the base-game/update ones.</li>
<li><u>01007EF00011E000/romfs</u>: This is the Switch equivalent of content.</li>
<li><u>01007EF00011F001/romfs</u>: This is the Switch equivalent of aoc.</li>
<li><u>patches</u>: Is used to load code patches with BCML. More info on code patches is available on [https://github.com/Torphedo/BOTW-ModdingGuide/blob/main/Code-BNPs.md Torphs GitHub].</li>
</ul>


=== SARC archives ===
<br>
[[SARC]] archives contain collections of other files and folders, like .zip folders. Unpack, edit and re-pack them with leoetlino's [https://pypi.org/project/sarc/ <code>sarc</code> tool]. This tool automatically decompresses Yaz0-encoded archives, and re-compresses them when you repack if the extension starts with an <code>s</code>.
* <code>sarc extract INPUT_FILE.pack</code>
* <code>sarc create [-b] INPUT_FOLDER OUTPUT_FILE.sbactorpack</code> (Use <code>-b</code>for Wii U only).


=== BYML files ===
The mod folder can also contain these other files/folders (case sensitive):
[[BYML]] files contain game parameters. Convert them to an editable format (and back) with leoetlino's [https://pypi.org/project/byml/ <code>byml</code> tool]. This tool automatically decompresses Yaz0-encoded files, and re-compresses them if the extension starts with an <code>s</code>.
<ul>
* <code>byml_to_yml INPUT_FILE.byml OUTPUT_FILE.yml</code>
<li><u>logs</u>: Contains BCML log files; these should not be edited and are only for BCML to read/write.</li>
* <code>yml_to_byml [-b] INPUT_FILE.yml OUTPUT_FILE.sbyml</code> (Use <code>-b</code> for Wii U only).
<li><u>options</u>: Can be used to add sub-mods as selectable options to your final mod.</li>
<li><u>info.json</u>: Holds the mods meta-data; BCML will create this automatically when you make a BNP.</li>
</ul>


=== AAMP files ===
<br>
[[AAMP]] files also contain game parameters. Convert them to an editable format (and back) with leoetlino's [https://pypi.org/project/aamp/ <code>aamp</code> tool]. Unlike most other files, AAMP files are exactly the same on both Wii U and Switch.
* <code>aamp_to_yml INPUT_FILE.bxml OUTPUT_FILE.yml</code>
* <code>yml_to_aamp INPUT_FILE.yml OUTPUT_FILE.bgparamlist</code>


=== BFRES files ===
There is no limit to how many files you can add to the mod folder, but you should only be placing files strictly necessary to your mod in the BNP to keep file sizes down.
[[BFRES]] files contain the game's models and textures. Tutorials on how to edit these for Wii U can be found in [https://drive.google.com/drive/folders/1Z1_A3w0VvPHp22H_Yh_dSdzI5hr4OAv9 Fooni's Tutorials].
* <code>.sbfres</code> files contain models.
* <code>.Tex1.sbfres</code> files contain textures (Wii U).
* <code>.Tex2.sbfres</code> files contain mipmaps for textures (Wii U). Since we can't edit these on Wii U yet, they need to be disabled.
* <code>.Tex.sbfres</code> files contain both textures and mipmaps (Switch). Unlike on Wii U, mipmaps don't cause any problems here.


== Rules ==
To make sure of this, I use a different folder layout than is standard to keep organized.<br>
It adds an extra sub-directory to the mod folder that can store assets only used by the mod creator.
 
Mod Folder/
├── Assets/
│  ├── textures/
│  │  ├── MyModel_Alb.dds
│  │  ├── MyModel_Spm.dds
│  │  └── MyModel_Nrm.dds
│  └── MyModel.blend
└── Build/
    ├── content/
    │  ├── Actor/
    │  │  ├── Pack/
    │  │  │  └── FldObj_MyModel_A_01.sbactorpack
    │  │  └── ActorInfo.product.sbyml
    │  └── Model/
    │      ├── FldObj_MyModel_A.sbfres
    │      └── FldObj_MyModel_A.Tex1.sbfres
    └── aoc/
        └── 0010/
            └── Map/
                └── MainField/
                    └── A-8/
                        └── A-8_Dynamic.smubin
 
When creating a mod in this format, point the BNP Creator to the <code style="background: #E6E4E4; border-radius: 5px;>Build</code> folder.
 
<br>
 
==== Mod Structure ====
A general rule when making mods is if it exists in the game dump, it can go in your mod in the relative location.
 
For example, the WiiU game file <code style="background: #E6E4E4; border-radius: 5px;">UpdateDump/content/Model/Animal_Bear.sbfres</code> would go in <code style="background: #E6E4E4; border-radius: 5px;>ModFolder/content/Model/Animal_Bear.sbfres</code>; when this mod is loaded, Animal_Bear.sbfres will be overwritten by the file in your mod.
 
UpdateDump and ModFolder are both relative to your PC.
 
<br>
 
===== WiiU/Cemu Folder Structure =====
Mod Folder/
├── content/
│  ├── Model/
│  │  └── Animal_Bear.sbfres
│  └── Effect/
│      └── Weapon_Sword_070.seselist
├── aoc/
│  └── 0010/
│      └── Map/
│          └── MainField/
│              └── A-2/
│                  └── A-2_Dynamic.smubin
└── info.json
 
<br>
 
===== Switch/Yuzu Folder Structure =====
Mod Folder/
├── 01007EF00011E000/
│  └── romfs/
│      ├── Model/
│      │  └── Animal_Bear.sbfres
│      └── Effect/
│          └── Weapon_Sword_070.seselist
├── 01007EF00011F001/
│  └── romfs/
│      └── Map/
│          └── MainField/
│              └── A-2/
│                  └── A-2_Dynamic.smubin
└── info.json
 
<br>
 
==== Other/Misc ====
Everything else in the BNP Creator is pretty straightforward, but just in case you don't understand something, here's a brief on each optional field.<br>
 
<ul>
<li>Image | A direct HTTP link to an image file or a path relative to the root of your mod folder. For example, image.png will try to load a file named image.png in your Mod Folder.</li>
<li>URL | An HTTP link to your mod page.</li>
<li>Version | The current version of your mod.</li>
<li>Description | An extended description of your mod. (Markdown text is supported)</li>
<li>Dependencies | A list of mods required for this mod.</li>
<li>Options | A list of options in the mod.</li>
</ul>
 
<br>
 
==== Create It ====
Once you have filled out all the fields you need for your mod, click the Create BNP button in the bottom right.
 
You will get prompted to save a BNP file; save it where you like. But be careful not to store it in the Mod Folder beside content, aoc, etc. It will get added to the BNP the next time you build it.
 
<br>
 
== Modding Rules ==


=== The RSTB file ===
=== The RSTB file ===
The file [[ResourceSizeTable.product.rsizetable]] (referred to as the RSTB file) contains a list of size limits for almost every file in the game (calculated from the non-Yaz0-compressed file sizes). If you edit a file to make its filesize bigger, you'll need to edit this file to prevent errors. For details, see [[Help:Editing the RSTB]].
<b style="color: #D11448"><u>Note</u>: Manual RSTB editing is not required when using BCML</b><br>
The file [[ResourceSizeTable.product.rsizetable]] (referred to as the RSTB file) contains a list of size limits for almost every file in the game (calculated from the non-Yaz0-compressed file sizes). If you edit a file to make its filesize bigger, you'll need to edit this file to prevent errors. For details, see [[Help:Updating the RSTB]].


=== File names and caching ===
=== File names and caching ===
The game assumes that any 2 files with the exact same filename also have the exact same contents. If you don't follow this rule when editing files, the game might load the wrong version of the file, leading to errors.
The game assumes that any files with the same filename also have the same contents. If you don't follow this rule when editing files, the game might load the wrong version of the file, leading to errors. The same rule applies to texture names - all unique textures should have unique names, even if they're located in different files.
 
=== File extensions for compressed resources ===
 
In most cases, file extensions that start with <code style="background: #E6E4E4; border-radius: 5px;">.s</code> are expected to be [[Yaz0]]-compressed files. Ensure that any file with such extensions is compressed. Most tools will automatically compress files when needed.
 
Example: <code style="background: #E6E4E4; border-radius: 5px;">.bactorpack</code> -> <code style="background: #E6E4E4; border-radius: 5px;">.sbactorpack</code> (after compression)
 
=== Edit priority ===
If a file exists in your <u>update dump</u>, edit that copy of it.<br>
If it doesn't exist there, edit the one in your <u>DLC dump</u>.<br>
If it doesn't exist in either the update files or the DLC files, edit the one from the base <u>game dump</u>.

Revision as of 22:05, 13 April 2022

Welcome, modders! This page contains useful information for anybody who wants to create mods. If you just want to use other people's mods, see Help:Using mods.

What can currently be modded?

  • Textures
  • Models
  • Actor parameters, including enemies, weapons, and armors
  • Adding new actors
  • Overworld and dungeon map files
  • Event flows, and as a direct consequence: cutscenes, NPC interactions, quests, minigames, etc.
  • Animations and various animation parameter files
  • Rigid body collisions
  • Text / dialogue
  • UI elements (HUD, title screen, logos, etc.)
  • Music and audio (cannot add new tracks, only edit/replace existing)
  • Effects and shaders (limited)

Getting set up


About BNPs

Modding has come a long way, and creating them has never been easier with BCML and the BNP (BOTW Nano Patch) format.

BNPs are a crucial part of modding Breath of the Wild, as they allow for small package distribution and accurate merging when used with BCML.

For more information on BNPs, check out this detailed guide by Torphedo.

Creating BNPs

BNPs can be made using the BCML BNP Creator in the Dev Tools tab.

The BNP Creator requires two fields to create a BNP, a name, and a mod folder.


Name

The name can be anything you choose, usually something that tells people what the mod is.
Example: "Invisible Majora's Mask" implies that it makes Majora's mask invisible, which it does.


Mod Folder

The mod folder is the contents of the mod. This folder requires at least one of the following folders (case sensitive):

  • content: Holds general content such as game models, effects, sounds, etc. (WiiU)
  • aoc: Has similar files as content, but this folder overwrites the DLC files instead of the base-game/update ones.
  • 01007EF00011E000/romfs: This is the Switch equivalent of content.
  • 01007EF00011F001/romfs: This is the Switch equivalent of aoc.
  • patches: Is used to load code patches with BCML. More info on code patches is available on Torphs GitHub.


The mod folder can also contain these other files/folders (case sensitive):

  • logs: Contains BCML log files; these should not be edited and are only for BCML to read/write.
  • options: Can be used to add sub-mods as selectable options to your final mod.
  • info.json: Holds the mods meta-data; BCML will create this automatically when you make a BNP.


There is no limit to how many files you can add to the mod folder, but you should only be placing files strictly necessary to your mod in the BNP to keep file sizes down.

To make sure of this, I use a different folder layout than is standard to keep organized.
It adds an extra sub-directory to the mod folder that can store assets only used by the mod creator.

Mod Folder/
├── Assets/
│   ├── textures/
│   │   ├── MyModel_Alb.dds
│   │   ├── MyModel_Spm.dds
│   │   └── MyModel_Nrm.dds
│   └── MyModel.blend
└── Build/
    ├── content/
    │   ├── Actor/
    │   │   ├── Pack/
    │   │   │   └── FldObj_MyModel_A_01.sbactorpack
    │   │   └── ActorInfo.product.sbyml
    │   └── Model/
    │       ├── FldObj_MyModel_A.sbfres
    │       └── FldObj_MyModel_A.Tex1.sbfres
    └── aoc/
        └── 0010/
            └── Map/
                └── MainField/
                    └── A-8/
                        └── A-8_Dynamic.smubin

When creating a mod in this format, point the BNP Creator to the Build folder.


Mod Structure

A general rule when making mods is if it exists in the game dump, it can go in your mod in the relative location.

For example, the WiiU game file UpdateDump/content/Model/Animal_Bear.sbfres would go in ModFolder/content/Model/Animal_Bear.sbfres; when this mod is loaded, Animal_Bear.sbfres will be overwritten by the file in your mod.

UpdateDump and ModFolder are both relative to your PC.


WiiU/Cemu Folder Structure
Mod Folder/
├── content/
│   ├── Model/
│   │   └── Animal_Bear.sbfres
│   └── Effect/
│       └── Weapon_Sword_070.seselist
├── aoc/
│   └── 0010/
│       └── Map/
│           └── MainField/
│               └── A-2/
│                   └── A-2_Dynamic.smubin
└── info.json


Switch/Yuzu Folder Structure
Mod Folder/
├── 01007EF00011E000/
│   └── romfs/
│       ├── Model/
│       │   └── Animal_Bear.sbfres
│       └── Effect/
│           └── Weapon_Sword_070.seselist
├── 01007EF00011F001/
│   └── romfs/
│       └── Map/
│           └── MainField/
│               └── A-2/
│                   └── A-2_Dynamic.smubin
└── info.json


Other/Misc

Everything else in the BNP Creator is pretty straightforward, but just in case you don't understand something, here's a brief on each optional field.

  • Image | A direct HTTP link to an image file or a path relative to the root of your mod folder. For example, image.png will try to load a file named image.png in your Mod Folder.
  • URL | An HTTP link to your mod page.
  • Version | The current version of your mod.
  • Description | An extended description of your mod. (Markdown text is supported)
  • Dependencies | A list of mods required for this mod.
  • Options | A list of options in the mod.


Create It

Once you have filled out all the fields you need for your mod, click the Create BNP button in the bottom right.

You will get prompted to save a BNP file; save it where you like. But be careful not to store it in the Mod Folder beside content, aoc, etc. It will get added to the BNP the next time you build it.


Modding Rules

The RSTB file

Note: Manual RSTB editing is not required when using BCML
The file ResourceSizeTable.product.rsizetable (referred to as the RSTB file) contains a list of size limits for almost every file in the game (calculated from the non-Yaz0-compressed file sizes). If you edit a file to make its filesize bigger, you'll need to edit this file to prevent errors. For details, see Help:Updating the RSTB.

File names and caching

The game assumes that any files with the same filename also have the same contents. If you don't follow this rule when editing files, the game might load the wrong version of the file, leading to errors. The same rule applies to texture names - all unique textures should have unique names, even if they're located in different files.

File extensions for compressed resources

In most cases, file extensions that start with .s are expected to be Yaz0-compressed files. Ensure that any file with such extensions is compressed. Most tools will automatically compress files when needed.

Example: .bactorpack -> .sbactorpack (after compression)

Edit priority

If a file exists in your update dump, edit that copy of it.
If it doesn't exist there, edit the one in your DLC dump.
If it doesn't exist in either the update files or the DLC files, edit the one from the base game dump.