<p align="center"> <img width="650" src="media/bar-decomp_logov2.png" alt="BAR Decomp! logo"> </p>

bar-decomp

Matching decompilation of Beetle Adventure Racing!

Check out BAR-Recomp, our companion recompilation project!

While the repository only builds the US version of BAR, we are planning to include the PAL, Japanese, and Australian versions in the future.

With the exception of BAR-Recomp, we do not endorse and we are not affiliated with any other repos or projects that also target this game. Per our contribution guidelines, we do not accept any AI-generated code.

[!IMPORTANT] This repository does not contain any game assets, assembly code, or other copyrighted materials. You must provide your own legally-obtained copy of the game in order to extract the assets necessary to build this repository.

Installation

1. Install build dependencies

Windows

For Windows 10, install WSL and a distribution by following this Windows Subsystem for Linux Installation Guide. We recommend using Debian or Ubuntu 22.04 Linux distributions.

Linux (Native or under WSL / VM)

The build process has the following package requirements:

• make
• git
• build-essential
• binutils-mips-linux-gnu
• python3
• pip3

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

sudo apt update
sudo apt install make git build-essential binutils-mips-linux-gnu python3 python3-pip clang-format-14 clang-tidy libcjson-dev curl libzstd-dev binutils-dev

MacOS

Install Homebrew and the following dependencies:

brew update
brew install make coreutils tehzz/n64-dev/mips64-elf-binutils

2. Clone the repository

git clone --recurse-submodules https://github.com/synamaxmusic/bar-decomp.git

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

cd bar-decomp

3. Install dependencies

Depending on your python version, you might need to add --break-system-packages, or use venv. The following commands will update submodules, use python venv to install dependencies, and build the toolchain.

git submodule update --init --recursive
python3 -m venv .venv
source ./.venv/bin/activate
make dependencies

4. Prepare a base ROM

Copy your ROM to the root of this new project directory, and rename the file of the baserom to reflect the version of ROM you are using. ex: baserom.us.z64

5. Make and Build the ROM

To start the extraction/build process, run the following command:

make extract

This will create the build folders, a new folder with the assembly as well as containing the disassembly of nearly all the files containing code.

From now on you should be able to build the rom by running make.

this make target will also build the ROM. If all goes well, a new ROM called "beetleadventurerac.us.z64" should be built and the following text should be printed:

build/beetleadventurerac.us.z64: OK

If you instead see the following:

build/beetleadventurerac.us.z64: FAILED

This means that something is wrong with the ROM's contents. Either the base files are incorrect due to a bad ROM, or some of the code is not matching.