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)

1. Inside the folder of your choice git clone https://github.com/Xeeynamo/croc.git
2. Run sudo apt-get install -y $(cat tools/requirements-debian.txt)
3. Run make update-dependencies
4. Copy the content of the disk inside disks/{game_version}

How to build

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

1. Run make clean extract all expected at least once
2. Look for one of those function which hasn't successfully decompiled yet (eg. INCLUDE_ASM("asm/croc/nonmatchings/3038", BackGroundTextureLoad);)
3. Run FUNC=BackGroundTextureLoad 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 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:

1. Use decomp.me with the PSY-Q 4.0 compiler.
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