Croc: Legend of Gobbos decompilation

Creates a full decompilation in C that compiles the same identical binary used the commercial video game Croc: Legend of Gobbos for PlayStation 1.

This decompilation is based on the European demo SLED-00038. This was decided as it is the only known build that contains symbols. This would theorically allow a much faster decompilation. Once the decompilation is complete, the plan is to migrate the existing symbols to the retail build SLUS-00530.

Progress

Version	File name	Progress
`SLED-00038`	`CROC.EXE`
`SLED-00038`	`DEMOFMV`	N/A

How to setup the project (assuming Ubuntu 20.04/Debian 11 or Windows with WSL)

Inside the folder of your choice git clone https://github.com/Xeeynamo/croc.git
Run sudo apt-get install -y $(cat tools/requirements-debian.txt)
Run make update-dependencies
Inside the newly created repo, create a new iso/ folder, and extract the content of the game disc

How to build

Run make extract to generate the assembly files in the asm/ directory
Run make all 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

Run make clean extract all expected at least once
Look for one of those function which hasn't successfully decompiled yet (eg. INCLUDE_ASM("asm/croc/nonmatchings/3038", BackGroundTextureLoad);)
Run FUNC=BackGroundTextureLoad make decompile to dump the decompiled code on the console
Replace the INCLUDE_ASM(...); you targeted with the console output content
and invoke python3 ./tools/asm-differ/diff.py -mwo BackGroundTextureLoad

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:

Use decomp.me with the PSY-Q 4.0 compiler.
The “context” section of decomp.me, is provided by the previous command make decompile as mentioned in the how to decompile.
Use decomp-permuter to solve some mismatches
Use this and this guide to understand how some compiler patterns work
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

Xeeynamo / croc