open-ribbon / open-ribbon

vib-ribbon decompilation (PAL version)

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

open-ribbon's Issues

Just trying to help

I am not sure If i am able to help since you are trying to decompile the PSX file of Vib Ribbon (Are they different compared to the .cue & .bin files used by emulators

Here are some informations that may help (somehow):
MAIN_T.EXE [AKA Title] Is the main menu of the game
MAIN_K.EXE [AKA Kioske] is the tutorial of the game (How to play)
MAIN_G.EXE [AKA Game] is the game itself.

I am not an expert in decompilation, but here are some informations about some of the game structure I found while digging (C++)
Title:
Starting Function name is Title main()

game/Movie.h <- The only header file of the Title

game/VideoSys.cpp
game/CdSys.cpp
game/MemorySys.cpp
game/AudioSys.cpp
game/InputSys.cpp
game/FileSys.cpp
game/PackedFiles.cpp <- Probably has the list of the packed files of the game [.PAK] (Thoses have already been succesfully extracted)
game/InputControl.cpp
game/TmdLineObj.cpp
game/Message.cpp
game/FontHack.cpp
[ Maybe are there more ? probably ]

Game:
Starting Function name is Game main()

game/StaticQueue.h <- The only header file of the Game

game/GameCamera.cpp <- Probably handling the inclinaison of the camera, I found a residue of a probably matching method
~ CGameCamera::Update() Extra Residue: warning: CGameCamera::Update() before first camera event
game/FbStream.cpp
game/VideoSys.cpp
game/CdSys.cpp
~ PlayTrack() <- Probably a method to start a game Extra Residues: CdSys::PlayTrack(): requested track out of range
game/AudioSys.cpp
game/Thread.cpp
game/InputSys.cpp
game/MemorySys.cpp <- I found the residues of probably matching methods
~ malloc()
~ Info()
game/FileSys.cpp
game/AudioStream.cpp
game/SignalModule.cpp <- Maybe is kind of of an event system ? I found the residues of probably matching methods
~ BufferTrackEnd() <- Not sure for this one
~ SignalGameOver()
~ SignalUserAbort()
~ SignalGameClear()
game/InputControl.cpp
game/FastAllocator.cpp < - I may have found something related to the FastAllocator, the .cpp has probably multiples classes
~ MemoryPool::~MemoryPool()

game/Forms.cpp <- Maybe related to the character form ? Vibri, Snake, Worm, Princess
game/TitleDraw.cpp
game/AnalysisScript.cpp <- The program that convert the cd audio in waves ? or related to the PAK'ed file named script/system3.fsl
game/Gameplay.cpp I found the residue of a probably matching function
~ Gameplay::AddEvent() Extra Residue: Gameplay::AddEvent() : part event rejected (before start pos)
game/SceneDraw.cpp
game/RoadSelect.cpp <- Roads are maps, since the game was created originally for Mercedez, they didnt renamed thoses I think
game/Glue.cpp
~ Potential file Extra Residue: BufferTrackEnd(): bad state
game/FontHack.cpp
game/Message.cpp
[ Maybe are there more ? probably ]

Hope my informations may be usefull, some of my informations are just guesses and should be taken carefully.

Licensing?

Currently both this repository and the documentation don't have an open-source license. I propose doing something similar to the Super Mario 64 Decompilation, and go with a license such as CC0 or MIT. Otherwise, it might be a legal issue to port to PC/release modded ROMs based off this project for anyone outside of the organization.