DEV Community

Bizzycola
Bizzycola

Posted on • Edited on

Setup Banjo-Kazooie Decomp in WSL with VS Code

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.

Terminal

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Ubuntu

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):

Ubuntu App

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.

Ubuntu Terminal

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:

VSCode Sidebar

Now search for and install the WSL extension:

WSL Extension

Now, click the Remote tab:

WSL Remote

Make sure you have WSL selected:

Targets

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

Ubuntu connect

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

Open folder

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

Home folder

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

Open Terminal

This’ll open a terminal in your WSL instance:

Terminal

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Press 1 for default installation and hit enter.

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

git submodule update --init --recursive
Enter fullscreen mode Exit fullscreen mode

And this to install the Python dependencies:

python3 -m pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

File Menu

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

Open Folder

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:

File List

(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
Enter fullscreen mode Exit fullscreen mode

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:

Built rom

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:

Ubuntu explorer

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;
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (2)

Collapse
 
bridgeheadland profile image
BridgeHeadland

When modding, how do I know what each function and value does? For example, how do I know if "MAP_91_FILE_SELECT" (without quotes) is sending you to file select without intro? Is there a concrete list of such things on the web - when it comes to N64 games, I mean?
I can understand MAP_91_FILE_SELECT is related to file select somehow, but gBootMap tells me nothing.

Collapse
 
bizzycola profile image
Bizzycola

Some stuff may just be a matter of trial and error learning, but there is some documentation available here: hack64.net/wiki/doku.php?id=banjo_...