This is an example mod for Banjo-Kazooie: Recompiled that can be used as a template for creating mods. It has a basic build system, headers, sample code, and a mod config toml.

Writing mods

See this document for an explanation of the modding framework, including how to write function patches and perform interop between different mods.

Tools

You'll need to install clang and make to build this template.

On Windows, using chocolatey to install both is recommended. The packages are llvm and make respectively.
- The LLVM 19.1.0 llvm-project release binary, which is also what chocolatey provides, does not support MIPS correctly. The solution is to install 18.1.8 instead, which can be done in chocolatey by specifying --version 18.1.8 or by downloading the 18.1.8 release directly.
On Linux, these can both be installed using your distro's package manager.
On MacOS, these can both be installed using Homebrew. Apple clang won't work, as you need a mips target for building the mod code.

On Linux and MacOS, you'll need to also ensure that you have the zip utility installed.

You'll also need a copy of the RecompModTool utility from the N64Recomp repository. A prebuilt version is available for Windows and Linux in the GitHub release.

Building

First, run make (with an optional job count) to build the mod code itself.
Next, run the RecompModTool utility with mod.toml as the first argument and the build dir (build in the case of this template) as the second argument.
- This will produce your mod's .nrm file in the build folder.
- If you're on MacOS, you may need to specify the path to the clang and ld.lld binaries using the CC and LD environment variables, respectively.

Updating the Banjo-Kazooie Decompilation Submodule

Mods can also be made with newer versions of the Banjo-Kazooie decompilation instead of the commit targeted by this repo's submodule. To update the commit of the decompilation that you're targeting, follow these steps:

Build the N64Recomp repo and copy the N64Recomp executable to the root of this repository.
Build the version of the Banjo-Kazooie decompilation that you want to update to and copy the resulting .elf file to the root of this repository.
Update the bk-decomp submodule in your clone of this repo to point to the commit you built in the previous step.
Run N64Recomp generate_symbols.toml --dump-context
Rename dump.toml and data_dump.toml to bk.us.rev1.syms.toml and bk.us.rev1.datasyms.toml respectively.
- Place both files in the BanjoRecompSyms folder.
Try building.
- If it succeeds, you're done.
- If RecompModTool fails due to a function being "marked as a patch but not existing in the original ROM", it's likely that function you're patching was renamed in the Banjo-Kazooie decompilation.
  - Find the relevant function in the map file for the old decomp commit, then go to that address in the new map file, and update the reference to this function in your code with the new name.