Help:Setting up tools: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
VisualWikitext
imported>Leoetlino
(→‎Common requirements: Python 3.9 incompatibility)
 
(47 intermediate revisions by 6 users not shown)
Line 1: Line 1:
''Breath of the Wild'' uses a very flexible, custom game engine. Many aspects of the game are not hardcoded and are instead configured by a large amount of files. To edit these files, a certain number of tools are required.
''Breath of the Wild'' uses a very flexible game engine, so many aspects of the game can be configured with files. Since BotW uses a lot of custom formats, special tools are required for editing them.


== A note about file formats ==
== Common requirements ==
The most common formats that one would want to be able to decode and also modify are:
=== Python ===
Many of the tools for these formats require [[wikipedia:Python (programming language)|Python]] 3.7+ ('''64 bit version''') to be installed.


* [[AAMP]] for [[actor parameters]], [[normal.bwinfo|world config (climate, lighting, ...)]], etc.
On Linux, Python 3 is surely already installed. Just make sure you have a recent enough version (3.7+). Ubuntu 16.04 and Debian stretch are too old; the latest Ubuntu LTS (18.04) and rolling distros such as Arch and Debian sid have 3.7+ in their repos.
* [[BFRES]] for cosmetic (textures, models, ...) changes
* [[BFEVFL]] for in-game events (which includes things like talking to people and also full-blown cutscenes)
* [[BYML]] for [[actor]]s, [[map unit]]s, [[difficulty scaling]] config, etc.
* [[RSTB]] when adding new resources or making existing files larger because of how the game works internally
* [[SARC]] for archives since many resource files are packed


== Installing tools ==
{{alert|class=primary|text=<b><i class="fa fa-download"></i> Setup instructions</b>
In general, there are several tools you can use for a given file format. This guide will only mention the recommended tools; a more complete list of utils can be found in the article for each [[:Category:File formats|file format]].


Some are unfortunately Windows-only, but many &mdash; especially the newer ones &mdash; are cross platform and work on Windows, macOS and Linux (with Linux even being the best supported platform for some tools).
On Windows, follow the below instructions to install Python:
# Uninstall any existing Python version to avoid conflicts.
# Download the [https://www.python.org/ftp/python/3.7.7/python-3.7.7-amd64.exe Python 3.7 installer] (latest version as of July 2019).
# Run the installer: do a ''system-wide install'' and tick the "''add Python to environment variables / PATH''" option. Note that if you install to the Program Files folder, you may occasionally run into permission issues with certain Python programs. To avoid this, install Python somewhere that does not require administrator permissions, such as <code>C:\Python37</code>.
# Verify that <code>py -3 --version</code> works and gives the correct version (3.7 or higher). {{CLI help}}


=== Common requirements ===
If you have any trouble installing Python, or need more detailed instructions, you can use [https://www.youtube.com/watch?v=ndrCfBJkkvE this video tutorial].
Many of the tools for these formats require [[wikipedia:Python (programming language)|Python]] 3.6+ ('''64 bit version''') to be installed.
}}


'''On Linux''', Python 3 is almost surely already installed. Just make sure you have a recent enough version (3.6+). Ubuntu 16.04 and Debian stretch are too old; The latest Ubuntu LTS (18.04) and rolling distros such as Arch as Debian sid have 3.6+ in their repos.
{{alert|class=warning|text=Several tools and libraries (e.g. oead) are not compatible with Python 3.9 yet [https://bugs.python.org/issue41237 because of CPython issue #41237]. 3.9 compatibility will be added when Python 3.9.1 is released with the bug fix, which is due to happen in December 2020.  
}}


'''On Windows''', follow the below instructions for installing Python:
=== For Windows users: Visual C++ redistributable for Visual Studio 2019 ===
# Uninstall any existing Python 3 version to avoid conflicts.
Several tools require the [https://aka.ms/vs/16/release/vc_redist.x64.exe 64-bit Visual C++ redistributable for Visual Studio 2019] to be installed. To be clear, Visual Studio is '''not''' required.
# Download the [https://www.python.org/ftp/python/3.7.0/python-3.7.0-amd64.exe Python 3.7 installer] (latest version as of September 2018).
 
# Run the installer: do a ''system-wide install'' and tick the "''add Python to environment variables / PATH''" option.
Failure to install the redistributable will cause several Python tools to fail with the error "ImportError: DLL load failed".
# Verify that <code>py -3 --version</code> works and gives the correct version (3.6 or higher). {{CLI help}}
 
== Tools ==
=== Yaz0 ===
Many files in the game are compressed with the [[Yaz0]] format. Compressed files generally have the letter <code>s</code> prefixed to their file extension. Use {{ltool|wszst}} to compress or decompress these files.


=== AAMP ===
=== AAMP ===
Two choices: [https://github.com/Zer0XoL/BotW-aampTool aamptool] or [https://github.com/leoetlino/aamp aamp].
[[AAMP]] is used for configuration files, such as [[actor parameters]], the [[normal.bwinfo|world configuration (climate, lighting, ...)]], etc. Convert them to an editable format (and back) with {{ltool|aamp}}. {{ltool|Wild Bits}} can also edit AAMP files.


'''Warning''': aamptool does not handle child parameter lists properly. This means some files will appear to have an incorrect structure. Additionally, Nintendo sometimes starts parameter structure names with numbers. aamptool converts structures into XML tags; however leading numbers in tag names are explicitly disallowed by the XML specification. As a result files with such nodes cannot be converted back to XML correctly as of September 2018.
Note: Unlike most other files, AAMP files are exactly the same on both Wii U and Switch.


For ''aamptool'':
=== BYML ===
# Download the tool from [https://github.com/Zer0XoL/BotW-aampTool/releases GitHub] (note: only built for Windows).
[[BYML]] files contain game parameters for [[actor]]s, [[map unit]]s, etc. Convert them to an editable format (and back) with {{ltool|byml-v2}}. {{ltool|Wild Bits}} can also edit BYML files.
 
For ''aamp'':
# Install the <code>aamp</code> package. {{Install py package help|package=aamp}}


=== BFRES ===
=== BFRES ===
{{empty section}}
[[BFRES]] files contain the game's animations, models and textures. The format is different on and on Switch and Wii U. These can be edited on Switch and Wii U using [https://github.com/KillzXGaming/Switch-Toolbox Switch Toolbox] (this tool is still under active development and receives very frequent updates, so expect some bugs in some features). Tutorials on another, older method of editing these for (Wii U only) 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). They can be edited with Switch Toolbox (when editing a Tex1 manually, it automatically edits any Tex2 in the same folder with the same filename). Alternatively, they can be disabled with [https://github.com/CEObrainz/Botw-AutoMipping Auto MipMap removal] (has the side effect of making the textures take a moment to load correctly).
* <code>.Tex.sbfres</code> files contain both textures and mipmaps (Switch). Unlike on Wii U, mipmaps don't cause any problems here.


=== BFEVFL ===
=== BFEVFL ===
# Install PyQt5. (If you're on Windows, install the <code>PyQt5</code> package. {{Install py package help|package=PyQt5}})
[[BFEVFL]] is used for in-game events (which includes things like talking to people and also full-blown cutscenes).
# Install the <code>eventeditor</code> package. {{Install py package help|package=eventeditor}}


=== BYML ===
Use {{ltool|EventEditor}} to edit event flowcharts.
Two choices: [https://github.com/arbiter34/ninten-file-tool ninten-file-tool] (for Wii U '''only''') or [https://github.com/leoetlino/byml-v2 byml-v2] (Wii U and Switch, and supports all new node types)


For ''ninten-file-tool'':
=== RSTB ===
# Install the Java runtime environment (JRE).
[[ResourceSizeTable.product.rsizetable]] (known as the RSTB) contains sizes 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. The recommended tool for manipulating the RSTB is {{ltool|rstb}}. {{ltool|Wild Bits}} also provides a GUI frontend for <code>rstb</code>.
# Download the [https://github.com/arbiter34/ninten-file-tool/releases latest release from GitHub].


For ''byml-v2'':
=== SARC ===
# Install the <code>byml</code> package. {{Install py package help|package=byml}}
[[SARC]] archives contain collections of other files and folders, like .zip folders.


=== RSTB ===
Use {{ltool|sarc}} to create or modify archives. {{ltool|Wild Bits}} also provides a GUI frontend for <code>sarc</code>.
# Install the <code>rstb</code> package. {{Install py package help|package=rstb}}


=== SARC ===
=== Map units ===
Three choices: [https://github.com/Shadsterwolf/BotWUnpacker BotW Unpacker] (for Wii U '''only''') or [https://github.com/leoetlino/sarc sarc] (Wii U and Switch, heavily tested on BotW archives) or [https://github.com/aboood40091/SARC-Tool SARC Tool] (Wii U and Switch). '''We strongly advise against using other tools because they do not handle file alignment properly.'''
[[Map unit]]s can be edited directly by modifying the map unit [[BYML]]s or with a graphical tool such as Ice-Spear.


For ''BotW Unpacker'':
For the first method, refer to [[#BYML]].
# Download the [https://github.com/Shadsterwolf/BotWUnpacker/releases latest release from GitHub].


For ''sarc'':
For the second method, follow [https://gitlab.com/ice-spear-tools/ice-spear-builds the instructions in the official repo for Ice-Spear builds].
# Install the <code>sarc</code> package. {{Install py package help|package=sarc}}


For ''SARC Tool'':
=== MSBT ===
# Install the <code>sarclib</code> package. {{Install py package help|package=sarclib}}
[[MSBT]] files contain game texts. Convert them to an editable YAML format (and back) with {{ltool|msyt}} or (built on top of msyt) [https://github.com/polarbunny/msyt-tools msyt-tools]. Wild Bits also provides a GUI frontend for msbt.
# Install the <code>libyaz0</code> package. {{Install py package help|package=libyaz0}}
# Download the [https://github.com/aboood40091/SARC-Tool/releases latest release from GitHub].


== Reverse engineering ==
== Reverse engineering ==

Latest revision as of 16:31, 5 November 2020

Breath of the Wild uses a very flexible game engine, so many aspects of the game can be configured with files. Since BotW uses a lot of custom formats, special tools are required for editing them.

Common requirements

Python

Many of the tools for these formats require Python 3.7+ (64 bit version) to be installed.

On Linux, Python 3 is surely already installed. Just make sure you have a recent enough version (3.7+). Ubuntu 16.04 and Debian stretch are too old; the latest Ubuntu LTS (18.04) and rolling distros such as Arch and Debian sid have 3.7+ in their repos.

For Windows users: Visual C++ redistributable for Visual Studio 2019

Several tools require the 64-bit Visual C++ redistributable for Visual Studio 2019 to be installed. To be clear, Visual Studio is not required.

Failure to install the redistributable will cause several Python tools to fail with the error "ImportError: DLL load failed".

Tools

Yaz0

Many files in the game are compressed with the Yaz0 format. Compressed files generally have the letter s prefixed to their file extension. Use wszst to compress or decompress these files.

AAMP

AAMP is used for configuration files, such as actor parameters, the world configuration (climate, lighting, ...), etc. Convert them to an editable format (and back) with aamp. Wild Bits can also edit AAMP files.

Note: Unlike most other files, AAMP files are exactly the same on both Wii U and Switch.

BYML

BYML files contain game parameters for actors, map units, etc. Convert them to an editable format (and back) with byml-v2. Wild Bits can also edit BYML files.

BFRES

BFRES files contain the game's animations, models and textures. The format is different on and on Switch and Wii U. These can be edited on Switch and Wii U using Switch Toolbox (this tool is still under active development and receives very frequent updates, so expect some bugs in some features). Tutorials on another, older method of editing these for (Wii U only) can be found in Fooni's Tutorials.

  • .sbfres files contain models.
  • .Tex1.sbfres files contain textures (Wii U).
  • .Tex2.sbfres files contain mipmaps for textures (Wii U). They can be edited with Switch Toolbox (when editing a Tex1 manually, it automatically edits any Tex2 in the same folder with the same filename). Alternatively, they can be disabled with Auto MipMap removal (has the side effect of making the textures take a moment to load correctly).
  • .Tex.sbfres files contain both textures and mipmaps (Switch). Unlike on Wii U, mipmaps don't cause any problems here.

BFEVFL

BFEVFL is used for in-game events (which includes things like talking to people and also full-blown cutscenes).

Use EventEditor to edit event flowcharts.

RSTB

ResourceSizeTable.product.rsizetable (known as the RSTB) contains sizes 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. The recommended tool for manipulating the RSTB is rstb. Wild Bits also provides a GUI frontend for rstb.

SARC

SARC archives contain collections of other files and folders, like .zip folders.

Use sarc to create or modify archives. Wild Bits also provides a GUI frontend for sarc.

Map units

Map units can be edited directly by modifying the map unit BYMLs or with a graphical tool such as Ice-Spear.

For the first method, refer to #BYML.

For the second method, follow the instructions in the official repo for Ice-Spear builds.

MSBT

msbt files contain game texts. Convert them to an editable YAML format (and back) with msyt or (built on top of msyt) msyt-tools. Wild Bits also provides a GUI frontend for msbt.

Reverse engineering

To reverse engineer the game executable, it is strongly recommended to have a copy of IDA Pro 7.0+ because the main executable is fairly large and IDA is as of September 2018 the only serious option for analysing such binaries. It is also the only tool with a usable decompiler for AArch64 (Switch).

To get a copy of an IDC for Switch 1.5.0, ping leoetlino.

Retrieved from "https://zeldamods.org/w_botw/index.php?title=Help:Setting_up_tools&oldid=10909"