# Space Station Silicon Valley N64

![build](https://github.com/mkst/sssv/workflows/build/badge.svg)
![progress](https://img.shields.io/badge/dynamic/json?color=blue&label=us&query=$.message&logo=github&logoColor=white&link=https://github.com/mkst/sssv&url=https%3A%2F%2Fsssv.deco.mp%2Fus.json)

A work-in-progress decompilation of the **Space Station Silicon Valley** game for the Nintendo 64.

> **Note:** You must legally own a copy of the original game to use this repository.

Check out the [wiki](https://github.com/mkst/sssv/wiki/) for more detailed information.

# Building

The instructions below assume that you will be using `Ubuntu 24.04`; either natively, via [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10), or via [Docker](https://docs.docker.com/get-docker/).
Please check the [Dockerfile](Dockefile) for instructions of how to install the prerequisite system packages and Python libraries.

## Natively

Clone the repository; note the `--recursive` flag to fetch submodules at the same time:

```sh
git clone --recursive git@github.com:mkst/sssv.git
```

Navigate into the freshly cloned repo

```sh
cd sssv
```

Place the **US 1.0** SSSV ROM in the root of this repository, name it `baserom.us.z64`, and then run the first `make` command to extract the ROM:

```sh
make extract
```

Now build the ROM:

```sh
make --jobs
```

If you did everything correctly, you'll be greeted with the following:

```sh
build/sssv.us.z64: OK
```

## Docker

Clone this repository, place the `baserom.us.z64` at its root, and then run the Docker image via:

```sh
docker run --rm -ti -v $(pwd):/sssv ghcr.io/mkst/sssv:latest
```

From here you can run the `make extract` and `make --jobs` commands.

## Building `EU` Version

Place `baserom.eu.z64` in the root of the repository, and suffix each `make` command with `VERSION=eu`. Note that whilst this will build the EU ROM, minimal effort has been made to decompile this version.

## Building `NON_MATCHING` Version

A number of functions within the ROM have been decompiled to a state where they are functionally equivalent, but are not a byte-perfect match. Progress is approximately **14%** ahead of the fully matching build. In order to build/test the non-matching, pass `NON_MATCHING=1` to the `make` commands.

# Contributing

Once you have built an :ok: ROM you are ready to begin.

Create a copy of the `build` folder:

```sh
mkdir -p expected && cp -r build/ expected/
```

Run `asm-differ` and pass in the name of the function you want to tackle:

```sh
python3 tools/asm-differ/diff.py -mwo3 function_name_here
```

Edit the corresponding `.c` file and keep working until the function matches.

# ROM Versions

There are 5 known versions of the ROM:

| Country Code      |      CRC1/CRC2      |                  ROM SHA1                  | Notes                                                                          | Version |
| :---------------- | :-----------------: | :----------------------------------------: | :----------------------------------------------------------------------------- | :-----: |
| E - North America | `BFE23884/EF48EAAF` | `e5e09205aa743a9e5043a42df72adc379c746b0b` | US 1.0                                                                         | `1.37`  |
| J - Japanese      | `BFE23884/EF48EAAF` | `7320f08474c011fc7781093bf1a6818c37ce51e2` | JP (Unreleased)                                                                | `1.37`  |
| E - North America | `FC70E272/08FFE7AA` | `c968bba6a90db9ecbd957e910684a80726b0497d` | US 1.1                                                                         | `1.37`  |
| P - European      | `FC70E272/08FFE7AA` | `23710541bb3394072740b0f0236a7cb1a7d41531` | EU                                                                             | `1.37`  |
| ???               |         ???         |                    ???                     | [NES World](http://www.nesworld.com/prototype-details.php?system=n64&data=124) | `1.26B` |

Only US and EU versions were released to the public. If you are in possession of a beta/prototype ROM, please let me know - `mkst#4741`.

# ROM Info

## Layout

The layout of the ROM has been mapped out in the [splat](sssv.us.yaml) configuration. Three sections of code have been identified along with a mix of compressed and non-compressed data.

### Main

This is the code that is loaded when the ROM first starts up, it is responsible for spawning the various game threads, handling controller input, playing sound effects etc. Also includes the `libultra` library code.

### Overlay1

This is the code for the language select, intro cinematics and not much else.

**Note:** In the EU ROM this section is compiled without optimisation!

### Overlay2

Overlay2 contains the core Space Station Silicon Valley game logic.

## Compression

The project used [RNC](https://segaretro.org/Rob_Northen_compression) for a number of assets.

In order to decompress the game assets, run `make decompress` after you have performed the `make extract` step. Running `make compress` will then overwrite the original data in the `assets` directory with byte-perfectly compressed versions.

# Repo layout

```
asm/             ; transient assembly files (not checked in)
assets/          ; transient binary files (not checked in)
build/           ; build folder (not checked in)
include/
  2.0I/          ; libultra 2.0I headers
lib/libultra.a   ; libultra 2.0I static library
src.{us|eu}/
  core/          ; core code
  data/          ; game data e.g. DisplayLists, Vtx + more
  libultra/      ; customised libultra code
  sssv/          ; game code
tools/
  ido5.3_recomp/ ; static recompilation of IDO 5.3 compiler
  splat_ext      ; custom splat extensions
  svle           ; work-in-progress level data viewer
```

# Tools

- [asm-processor](https://github.com/simonlindholm/asm-processor); allows `GLOBAL_ASM` pragma - replacing assembly inside C files
- [asm-differ](https://github.com/simonlindholm/asm-differ); rapidly diff between source/target assembly
- [decomp-permuter](https://github.com/simonlindholm/decomp-permuter); tweaks code, rebuilds, scores; helpful for weird regalloc issues
- [ido-static-recomp](https://github.com/Emill/ido-static-recomp); no need to use qemu-irix anymore!
- [m2c](https://github.com/matt-kempster/m2c); assembly to C code translator
- [rnc_propack_source](https://github.com/lab313ru/rnc_propack_source); open-source compressor/decompressor for RNC file format
- [splat](https://github.com/ethteck/splat); successor to n64split

# Useful Links

- [SSSV at TCRF](<https://tcrf.net/Space_Station_Silicon_Valley_(Nintendo_64)>)
- [SSSV at romhacking.net](<http://datacrystal.romhacking.net/wiki/Space_Station_Silicon_Valley_(Nintendo_64)>)
- [Music video based on SSSV Prototype build](https://www.youtube.com/watch?v=IAJ4OT6-5GU)
- [ScriptHawk lua for SSSV](https://github.com/Isotarge/ScriptHawk/blob/master/games/sssv.lua)
- [EverDrive Forum thread](https://krikzz.com/forum/index.php?topic=6946.0)
- [NESWORLD Prototype ROM](http://nesworld.com/prototype-details.php?system=n64&data=124)
- [Magazine scans of reviews of SSSV](https://www.nintendo64ever.com/Tests-Nintendo-64-Game,321,Space-Station-Silicon-Valley,1.html)