Prerequisites

Before you install WSL, you will need to have virtualisation enabled on your PC. The steps from this vary depending on your hardware, as you’ll likely need to enable it in your BIOS if it is not enabled. Easiest way to find out is to just google your motherboard model (or laptop/prebuilt PC model) along with “enabling virtualization”.

WSL Setup

Command Prompt

There’s some commands here to run so first step is to open an Administrator command prompt. You can just right-click your start menu (the Windows icon) and click either “Terminal (Admin)” or “Command Prompt (Admin)” depending on which you see.

Automatic WSL installation (preferred)

Setting up WSL in Windows 11 and later versions of Windows 10 after enabling virtualization should be as simple as just opening an Administrator command prompt and typing wsl –install.

This doesn’t always work as intended and there are some manual steps that can be used instead.

Manual WSL installation (only if auto fails)

First, run this command to enable the feature:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

This will install the first version of WSL (this is a built-in Windows command for managing OS and features).
Now, run this command to enable the Virtual Machine feature in Windows:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

If you get any errors stating the operation couldn't be started, you may also need to run this (and reboot after) to enable Hyper-V

DISM /Online /Enable-Feature /All /FeatureName:Microsoft-Hyper-V

Then try the above commands again.

Next you will need to download and install the WSL2 kernal from Microsoft: https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

Close and re-open your command prompt and run this command: wsl --set-default-version 2 - this will set WSL to use version 2.

OS Install

After installing WSL, you now need to install a linux distribution into it. We’ll just use Ubuntu 22.04 in this case, you can follow this link to find it or search for “Ubuntu” in the Windows Store app: https://www.microsoft.com/store/apps/9PN20MSR04DW

Once installed, you can open the Ubuntu terminal by searching for it on your PC (click the search bar in your taskbar or open the Start menu and just start typing Ubuntu):

The first time it opens it will prompt you to setup a username and password – do this and remember the credentials, you will need them later. Your username must be lowercase and alphanumeric, or you will receive a Regular Expression error.

NOTE If you don't setup a user, you will be pushed to use the root user which is not recommended and will differ from these instructions.

If you run into issues, see the troubleshooting steps from Microsoft: https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#installation-issues or check their official manual installation guide here: https://learn.microsoft.com/en-us/windows/wsl/install-manual

Visual Studio Code

Next, lets setup the code editor we’ll be using. First, lets install it. Head here: https://code.visualstudio.com/Download and download the Windows installer for VS Code. Once downloaded, run the installer and set it up.
Once done, open VS Code, click the Extensions icon in the sidebar:

Now search for and install the WSL extension:

Now, click the Remote tab:

Make sure you have WSL selected:

You should see your Ubuntu in the list. Click the arrow to connect.

Once connected, click the file explorer in the sidebar and click Open Folder:

The box that pops up should default to your home directory, click OK.

Now, in the top menu bar open a new terminal:

This’ll open a terminal in your WSL instance:

Cloning Decomp

Cloning git repository

Now we’ll pull down the BK repository to work on.

In that terminal, paste the following command (you can right-click to paste, don’t use ctrl+v):

git clone https://gitlab.com/banjo.decomp/banjo-kazooie.git

This will pull down a copy of the BK decomp repository into the banjo-kazooie directory.

Now, type cd banjo-kazooie.

Setup BK dependencies

Working on the repository requires some dependencies to be installed and some submodules to be pulled down. So now we’re in the banjo-kazooie directory lets run all the commands.

Before continuing, make sure you're in the banjo-kazooie directory we cloned into, or the commands may not work correctly:

cd ~/banjo-kazooie/

You should be able to see "banjo-kazooie" in your terminal prompt:

Now lets install our dependencies.

First, run this to install system dependencies:

sudo apt-get update && sudo apt-get install -y $(cat packages.txt)

Note, this command will ask you for a password. You need to enter the password you used when you installed Ubuntu earlier. You won't see the characters in the terminal as you type, this is normal.

Once done, run this to install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Press 1 for default installation and hit enter.

Then run this to pull down the child git repositories needed:

git submodule update --init --recursive

And this to install the Python dependencies:

python3 -m pip install -r requirements.txt

Note If you get an error regarding an externally managed environment, you can force the installation:

python3 -m pip install -r requirements.txt --break-system-packages

Or if you're a little skilled with Python commands, you can create a virtual environment to work in.

Before we continue, we need to run a command to get rust into our PATH:

source ~/.profile

VS Code

Before we continue, it's worth opening the Banjo-Kazooie folder in VS Code.

(Note in WSL you should also be able to type code . into the terminal and hit enter when you are CD'd into the banjo-kazooie directory to launch VS Code there, but the following instructions will show you how to use the UI to get there)

Go File -> Open Folder:

Add banjo-kazooie onto the path as seen below and click Okay. This will open banjo-kazooie as the root folder in VS Code.

Rom

This part is trickier. I can’t provide a Banjo-Kazooie US 1.0 rom for you nor tell you how to get one. You need to supply this yourself.

Once you have the rom (ending in .z64), rename it to baserom.us.v10.z64. Bring up your Visual Studio Code instance and drag baserom.us.v10.z64 from your PC to the file explorer. Be sure to drop it on the area with files per the highlighted screenshot below, do NOT drop it into any of the directories at the top:

(You can see I have the baserom.us.v10.z64 in my list there, you should see it there in yours once it finishes copying).

In your terminal, run the following command:

sha1sum baserom.us.v10.z64

Per the BK decomp instructions, the hash returned from this should match the following: 1fe1632098865f639e22c11b9a81ee8f29c75d7a

If it doesn’t, you likely have an incorrect rom and need to find another one.

Building

Now all this is done you can try typing make into your terminal and you should get a BK rom built into the build folder:

Note the first time you build the terminal will likely end with baserom.us.v10.z64 OK, once you have made changes to the code it will end with baserom.us.v10.z64 differs. This is normal.

So, now your rom is built, how do you get it out? You can actually browse your Ubuntu files directly from the Windows file explorer, with the Linux option in the sidebar of an explorer window:

Browse to Linux -> Ubuntu -> Home -> YOURUSERNAME -> banjo-kazooie -> build, grab your rom and load it up in an emulator to see how you did!

Your first mod

Let's create a simple mod that takes you straight to the file select when you open the game. In your VS code, browse to core1 -> code_0.c.
At the bottom of this file we have a function called setBootMap. We're going to change the gBootMap value to MAP_91_FILE_SELECT. Your function should now look like this:

void setBootMap(enum map_e map_id){
    gBootMap = MAP_91_FILE_SELECT;
}

Now run make in your terminal, find the rom, launch the game and you should be in the file select with no intro!

Thanks

Thanks to giantjigglypuff3 for helping me get this setup.