# Super Bowling 64 decompilation

[![Build](https://github.com/CalenCyr/superbowling64-decomp/actions/workflows/build.yml/badge.svg)](https://github.com/CalenCyr/superbowling64-decomp/actions/workflows/build.yml)
[![Code](https://bytematch.dev/CalenCyr/superbowling64-decomp.svg?label=Code&measure=matched_code_percent)](https://bytematch.dev/CalenCyr/superbowling64-decomp)
[![Functions](https://bytematch.dev/CalenCyr/superbowling64-decomp.svg?label=Functions&measure=matched_functions)](https://bytematch.dev/CalenCyr/superbowling64-decomp)

A work-in-progress matching decompilation of **Super Bowling 64** (Nintendo 64, USA, `NBWE`). The goal is C source
that, built with the original compiler, reproduces the retail ROM byte for byte.

This repository contains no game code, assets or ROM. You need your own copy of the game.

## Status

| | matched under the rules | bytes matched |
|---|---|---|
| all code | 449 / 906 functions | 91,412 / 335,856 bytes (27.2%) |
| game | 120 / 577 functions | 16,296 / 260,740 bytes (6.2%) |
| libultra | 329 / 329 functions | 75,116 / 75,116 bytes (100%) |

"Matched under the rules" counts functions whose bytes match *and* whose source passes the project's code rules
(no fake matches); 10 hand-written assembly helpers are listed separately as original assembly. Run `make report` for current numbers; live progress is on
[ByteMatch](https://bytematch.dev/CalenCyr/superbowling64-decomp), updated by CI on every push to `main`.

## What's known about the ROM

- **Compiler:** KMC GCC 2.7.2 from the N64 SDK, flags `-O2 -G0 -mips3 -mgp32 -mfp32`.
- **Library:** libultra 2.0K (`libgultra_rom`), built from source: the
  [ultralib](https://github.com/decompals/ultralib) submodule in `lib/ultralib`, compiled with the same compiler and
  linked at the retail addresses.
- **Layout:** a main segment at `0x80025C60`, plus seven code overlays that all load at `0x80112350`. The game finds
  its files through its own `BW64FAT` file table. The full ROM map is in [AGENTS.md](AGENTS.md).

## Setup

You need Linux (or WSL), Python 3, and these tools:

1. **Your ROM.** Place it at `rom.z64` (big-endian). Its SHA-1 must be
   `56937a9e9536af55ebed06480413265848c4a04a`.
2. **MIPS binutils** for linking. On Fedora: `sudo dnf install binutils-mips64-linux-gnu`.
3. **KMC GCC 2.7.2 and binutils 2.6.** Extract both into `tools/gcc_2.7.2/`:
   ```sh
   mkdir -p tools/gcc_2.7.2
   curl -L https://github.com/decompals/mips-gcc-2.7.2/releases/download/v0.1/gcc-2.7.2-linux.tar.gz | tar xz -C tools/gcc_2.7.2
   curl -L https://github.com/decompals/mips-binutils-2.6/releases/download/v0.3/binutils-2.6-linux.tar.gz | tar xz -C tools/gcc_2.7.2
   ```
4. **Python tools:** `pip install splat64[mips]`.
5. **objdiff** (optional, for diffs and progress): put
   [objdiff-cli](https://github.com/encounter/objdiff/releases) at `tools/objdiff/objdiff-cli`.

Then fetch ultralib, split the ROM and check that the build matches:

```sh
git submodule update --init
make split      # disassemble the ROM into asm/ and assets/
make gate       # clean rebuild; prints "GATE OK" if the output matches the retail SHA-1
make expected   # snapshot the matching build as objdiff's target
```

## Commands

| command | what it does |
|---|---|
| `make` | build `build/superbowling.z64` |
| `make gate` | clean rebuild and SHA-1 check; the test every change must pass |
| `make diff UNIT=src/<unit> FUNC=<func>` | side-by-side disassembly of one function: yours vs retail |
| `make report` | progress: matched functions and bytes, game and libultra |
| `make rules [UNIT=src/<unit>]` | the code-rule checker: fake-match findings and naming/style notes |

## Working on a function

1. Pick an `INCLUDE_ASM("asm/nonmatchings/<unit>", <func>);` line in a `src/` file; its assembly is in
   `asm/nonmatchings/<unit>/<func>.s`.
2. Replace the line with C, then iterate with `make diff UNIT=src/<unit> FUNC=<func>` until it prints `identical`.
3. Run `make rules UNIT=src/<unit>` and `make gate` before committing.

Read [AGENTS.md](AGENTS.md) first. The campaign follows the Claude Code skills from
[Game-Decompilation-Skill-For-Claude](https://github.com/lemiur/Game-Decompilation-Skill-For-Claude) (`matcher`,
`decomp-code-rules`, `orchestrator` and others); install them from there if you work with Claude Code. It holds the project's conventions: naming and layout style, headers, how to
convert an assembly unit to C, and what counts as a match.

## Layout

```
superbowling.yaml   splat config: segments, overlays, file splits
symbol_addrs.txt    known symbol names and addresses
src/                reconstructed C
include/            shared headers (types, globals, prototypes)
lib/ultralib/       libultra source (submodule)
tools/              diff, progress, objdiff config and the rule checker
asm/, assets/       generated by `make split` (not committed)
```

## Legal

This project contains only original reconstructed source and tooling. It includes no ROM, game code or assets.
Use it with a copy of the game you own.