A WIP decompilation of PAL build of the PS1 game Vib-Ribbon (ビブリボン).
The objective is to produce a free and open-source reverse-engineered version of the game.

Documentation about this game and project can be found here.
Join our Discord server to discuss the project.

Decompilation Progress

File name	Progress	Description
MAIN_T.EXE		Title screen
MAIN_K.EXE	N/A	Kiosk—Tutorial level
MAIN_G.EXE	N/A	Main menu and gameplay
SCES_028.73	N/A	Module (.EXE) loader

General info

Vib-Ribbon was written in C++, which was uncommon for games in the 90s, especially on the PSX.
However, due to current limitations, this decompilation is written in C.

How to build

Place all the necessary PSX executable files in the iso directory (e.g. MAIN_G.EXE) first. If you don't currently have the executables needed to decompile the game, please follow this guide on how to extract the files from your copy of Vib-Ribbon.

1. Run make extract to generate the assembly files in the asm/ directory
2. Run make to compile the binaries in the build/ directory

In case there are any changes in the config/ folder, you might need to run make clean to reset the extraction.

Some non-matching functions are present in the source preprocessed by the macro NON_MATCHING. You can still compile the game binaries by running CPP_FLAGS=-DNON_MATCHING make. In theory, they might be logically equivalent in-game, but I cannot promise that. Few of them could match by tuning or changing the compiler.

How to decompile

1. Run make clean extract all expected at least once
2. Look for a function which hasn't been successfully decompiled yet (eg. INCLUDE_ASM("asm/game/nonmatchings/4D58", VideoSys__FlipBuffer);)
3. Run FUNC=VideoSys__FlipBuffer FILE=VideoSys make decompile to dump the decompiled code on the console
4. Replace the INCLUDE_ASM(...); you targeted with the console output content
5. and invoke python3 ./tools/asm-differ/diff.py -mwo VideoSys__FlipBuffer

You will probably have some differences from your compiled code to the original; keep refactoring the code and move variables around until you have a 100% match.

There are a few tricks to make the process more streamlined:

1. Use decomp.me with the vib-ribbon preset.
2. The “context” section of decomp.me, is provided by the previous command make decompile as mentioned in the how to decompile.
3. Use decomp-permuter to solve some mismatches.
4. Use this and this guide to understand how some compiler patterns work.
5. Use the #ifndef NON_MATCHING if your code is logically equivalent but you cannot yet fully match it.

Troubleshooting

Not getting an "OK" on Ubuntu 22.04

Debian>=12 and Ubuntu>=22.04 uses binutils-mipsel-linux-gnu>=2.38 which, for some unknown reasons, it generates broken binaries. You need to downgrade to 2.34 or 2.35 with the following:

curl -L -o binutils-mipsel-linux-gnu_2.35.2-2cross2_amd64.deb http://ftp.de.debian.org/debian/pool/main/b/binutils-mipsen/binutils-mipsel-linux-gnu_2.35.2-2cross2_amd64.deb
dpkg -i binutils-mipsel-linux-gnu_2.35.2-2cross2_amd64.deb
rm binutils-mipsel-linux-gnu_2.35.2-2cross2_amd64.deb

Contributors

Avatar	Username
	polybiusproxy
	mkst
	unclamped
	sys128
	AnOpenSauceDev