Skip to content

Latest commit

 

History

History
137 lines (88 loc) · 4.89 KB

INSTALLATION.md

File metadata and controls

137 lines (88 loc) · 4.89 KB

Installation

We recommend using WSL on Windows, or native Linux, which the rest of this readme describes. We currently have instructions for

(These will also depend on the Linux instructions.) Some of these may also be out of date or unmaintained; usually our contributors use WSL, Linux, and macOS, so these instructions should be up to date.

Compiler

The compiler to use is automatically detected by the build system. We recommend using Modern SDK.

Windows

For Windows 10 or 11, install WSL and a distribution by following this WSL Installation Guide. We recommend using Ubuntu 20.04 as the Linux distribution.

For older versions of Windows, install a Linux VM or refer to either Cygwin or Docker instructions.

Linux (Native or under WSL / VM)

1. Install build dependencies

The build process has the following package requirements:

  • git
  • build-essential
  • binutils-mips-linux-gnu
  • python3
  • python3-pip
  • python3-venv
  • libpng-dev
  • gcc-mips-linux-gnu

Under Debian / Ubuntu (which we recommend using), you can install them with the following commands:

sudo apt-get update
sudo apt-get install git build-essential binutils-mips-linux-gnu python3 python3-pip python3-venv libpng-dev gcc-mips-linux-gnu

2. Clone the repository

N.B. If using WSL, we strongly encourage you to clone into WSL's Linux filesystem using Linux's git. Cloning into the Windows filesystem will result in much slower read/write speeds, and often causes issues when Windows copies the files with the wrong line endings, which the compiler IDO cannot handle correctly.

Clone https://github.com/HackerN64/HackerOoT.git where you wish to have the project, with a command such as:

git clone https://github.com/HackerN64/HackerOoT.git

This will copy the GitHub repository contents into a new folder in the current directory called HackerOoT. Change into this directory before doing anything else:

cd HackerOoT

3. Prepare a base ROM

Place a copy of the Master Quest (Debug) ROM inside the baseroms/hackeroot-mq/ folder.

Rename the file to baserom.z64, baserom.n64 or baserom.v64, depending on the original extension.

NOTE: to make a Wii VC build you will need to place a copy of the Ocarina of Time.wad file in this folder too, with the common-key.bin file. This project won't provide both.

4. Setup the ROM and build process

Setup and extract everything from your ROM with the following command:

make setup

This downloads some dependencies (from pip), and compiles tools for the build process. Then it generates a new ROM "baseroms/hackeroot-mq/baserom-decompressed.z64" that will have the overdump removed and the header patched. It will also extract the individual assets from the ROM. This command will also setup F3DEX3 binaries.

NOTE: the decompressed baserom will be copied to baseroms/gc-eu-mq-dbg/, this is a temporary solution.

5. Build the ROM

Run make to build the ROM. Make sure your path to the project is not too long, otherwise this process may error.

make

If all goes well, a new ROM should be built at build/hackeroot-mq/hackeroot-mq.z64.

NOTE: to speed up the build, you can either:

  • pass -jN to make setup and make, where N is the number of threads to use in the build. The generally-accepted wisdom is to use the number of virtual cores your computer has.
  • pass -j to make setup and make, to use as many threads as possible, but beware that this can use too much memory on lower-end systems.

Both of these have the disadvantage that the ordering of the terminal output is scrambled, so for debugging it is best to stick to one thread (i.e. not pass -j or -jN).

6. Other targets

Compressing the rom

To compress the rom, run the following command:

make compress
Building for Wii VC

To build a .wad for Wii VC, run the following command:

make wad

NOTE: this is assuming you followed the instructions for Wii VC in step 3.

Creating a BPS patch

To generate a .bps patch you can run the following command:

make patch

The patch will be in the build/hackeroot-mq/ folder.

7. Toggle HackerOoT Features

You can customize which HackerOoT features you want in your project and which not in the include/config/ folder. Just define the features as true or false or, if necessary, put in the value you want (e.g. Text speed).

TIP: if you are using VS Code, look at vscode.md for useful customization that make working with this project easier.