mgs_reversing

This project aims to completely reverse engineer Metal Gear Solid Integral for PlayStation back to C source code which when compiled produces the same assembly code.

At this moment SLPM_862.47/SLPM_862.48/SLPM_862.49 main executables are 100% decompiled. However, even though this is a substantial milestone, a significant amount of work is still left to decompile overlays, clean up already decompiled code and make it all shiftable.

The repository builds or aims to build the following artifacts:

Main executables

SLPM_862.47 (main executable)
Status	✔️ 100% decompiled! The next goals for this artifact are to clean up the decompiled code, find cleaner matches and make it shiftable.
Size	626 KB
SHA256	4b8252b65953a02021486406cfcdca1c7670d1d1a8f3cf6e750ef6e360dc3a2f
Building	python build.py
SLPM_862.48 (main executable)
Status	✔️ 100% decompiled! Identical to SLPM_862.47 (main executable).
Size
SHA256
Building
SLPM_862.49 (main executable)
Status	✔️ 100% decompiled! This executable is based on SLPM_862.47 (main executable), but with many small changes, especially around chara/snake_vr (a variant of Snake actor).
Size	616 KB
SHA256	c370f8e41ec8fb78238bfe2ddbfc25a6d37ec8f0972c86ebfde075ecd4ee8dca
Building	python build.py && python build.py --variant=vr_exe

Overlays

Metal Gear Solid Integral dynamically loads additional per-stage executable code that is required to play a particular stage of the game. The main executable contains the game engine, as well as the most common actors used throughout the stages.

Overlays on SLPM-86247
Status	🚧 Work in progress. Individual overlay progress: Click to expand abst 46 KB Load Save From Memcard ❌ Work not started brf 125 KB Briefing Menu ❌ Work not started camera 54 KB Load JPEG From Memcard 🚧 Work in progress change 12 KB Disc Change 🚧 Work in progress d00a 122 KB Docks Cutscene ❌ Work not started d01a 57 KB Heliport Cutscene 🚧 Work in progress d03a 18 KB Cell Cutscene ✔️ 100% decompiled! d11c 14 KB Communication Tower B Cutscene ✔️ 100% decompiled! d16e 65 KB Rex Hangar Cutscene ❌ Work not started d18a 96 KB Liquid Fight Cutscene ❌ Work not started d18ar 96 KB Liquid Fight Cutscene ❌ Work not started demosel 16 KB Demo Theater ❌ Work not started ending 40 KB Ending ❌ Work not started endingr 40 KB Ending ❌ Work not started opening 42 KB Intro FMV ❌ Work not started option 26 KB Options Menu ❌ Work not started preope 25 KB Previous Operations ❌ Work not started rank 139 KB Rank Screen ❌ Work not started roll 39 KB Credits ❌ Work not started s00a 120 KB Docks ✔️ 100% decompiled! s01a 137 KB Heliport 🚧 Work in progress s02a 130 KB Tank Hangar 🚧 Work in progress s02b 129 KB Tank Hangar ❌ Work not started s02c 132 KB Tank Hangar (Before Contacting Meryl) 🚧 Work in progress s02d 126 KB Tank Hangar (After Contacting Meryl) ✔️ 100% decompiled! s02e 132 KB Tank Hangar (After Torture) 🚧 Work in progress s03a 75 KB Cell ❌ Work not started s03ar 75 KB Cell ❌ Work not started s03b 66 KB Torture Room ❌ Work not started s03c 84 KB Torture Room Cell ❌ Work not started s03d 101 KB Torture Room Cell ❌ Work not started s03dr 101 KB Torture Room Cell ❌ Work not started s03e 38 KB Cell (Fight) ✔️ 100% decompiled! s03er 38 KB Cell (Fight) ✔️ 100% decompiled! s04a 94 KB Armory 🚧 Work in progress s04b 116 KB Armory Ocelot Fight ❌ Work not started s04br 116 KB Armory Ocelot Fight ❌ Work not started s04c 100 KB Armory Ocelot Fight ❌ Work not started s05a 130 KB Canyon ❌ Work not started s06a 127 KB Nuke Building 1 ✔️ 100% decompiled! s07a 130 KB Nuke Building B1 🚧 Work in progress s07b 141 KB Commanders Room ❌ Work not started s07br 141 KB Commanders Room ❌ Work not started s07c 73 KB Commanders Room ❌ Work not started s07cr 73 KB Commanders Room ❌ Work not started s08a 86 KB Nuke Building 2 ❌ Work not started s08b 133 KB Lab Gray Fox Fight ❌ Work not started s08br 133 KB Lab Gray Fox Fight ❌ Work not started s08c 60 KB Nuke Building B2 ❌ Work not started s08cr 60 KB Nuke Building B2 ❌ Work not started s09a 121 KB Cave ❌ Work not started s09ar 121 KB Cave ❌ Work not started s10a 135 KB Undeground Passage ❌ Work not started s10ar 135 KB Undeground Passage ❌ Work not started s11a 87 KB Communication Tower A ❌ Work not started s11b 97 KB Roof ❌ Work not started s11c 65 KB Communication Tower B ❌ Work not started s11d 60 KB Tower Wall A ❌ Work not started s11e 113 KB Communication Tower B Elevator Fight ❌ Work not started s11g 105 KB Roof Communication Tower ❌ Work not started s11h 97 KB Roof Communication Tower Hind D Fight ❌ Work not started s11i 75 KB Walkway ❌ Work not started s12a 107 KB Snow Field ❌ Work not started s12b 96 KB Snow Field (After Sniper Wolf Battle) ❌ Work not started s12c 95 KB Snow Field (After Sniper Wolf Battle) 🚧 Work in progress s13a 130 KB Blast Furnace ❌ Work not started s14e 108 KB Cargo Elevator ❌ Work not started s15a 89 KB Warehouse ❌ Work not started s15b 38 KB Warehouse ❌ Work not started s15c 129 KB Warehouse ❌ Work not started s16a 63 KB Rex Hangar 1st Floor ❌ Work not started s16b 10 KB Rex Hangar 2nd Floor ✔️ 100% decompiled! s16c 109 KB Rex Hangar 3rd Floor ✔️ 100% decompiled! s16d 121 KB Command Room ❌ Work not started s17a 140 KB Rex Fight ❌ Work not started s17ar 140 KB Rex Fight ❌ Work not started s18a 133 KB Liquid Fight ❌ Work not started s18ar 133 KB Liquid Fight ❌ Work not started s19a 120 KB Escape Route Meryl ❌ Work not started s19ar 120 KB Escape Route Meryl ❌ Work not started s19b 110 KB Escape Route Otacon ❌ Work not started s19br 110 KB Escape Route Otacon ❌ Work not started s20a 30 KB Ending ❌ Work not started s20ar 30 KB Ending ❌ Work not started select 8 KB Debug Menu ✔️ 100% decompiled! select1 721 B Debug Menu Stage Select ✔️ 100% decompiled! select2 721 B Debug Menu Stage Select s05a-s09a ✔️ 100% decompiled! select3 721 B Debug Menu Stage Select s10a-s14e ✔️ 100% decompiled! select4 721 B Debug Menu Stage Select s15a-s20a ✔️ 100% decompiled! selectd 721 B Debug Menu Demo Select ✔️ 100% decompiled! sound 1 KB Debug Menu Sound Test ✔️ 100% decompiled! title 89 KB Title Screen 🚧 Work in progress Individual overlay SHA256: Click to expand abst aed6a6145201850156d251618561487456e1b02d7ce26a40cf1e492b6fa30ec0 brf 95f948d72f4b2dd523c3f60b3e036db2971c5f00b3f69d7dc9b4744c48996286 camera 7e1738af3c3987b5461773cf865da803bac48820000e0e916307f29fa836f388 change d2f0afa4861278774ecc818c19e31420e3b05e96da4313ea048451bfabf780e5 d00a 3dd07b291d5bc6b58a028d012b744d9d2c8023f143474467b0259e5a5603ad0a d01a 3a8d292f250a80b708a06f3fd41ee0e6b74733390084ef5b163108ba5c8af4a1 d03a 3f3b4350dc263a088c70fa7518844ba8e5ec95a3f705ffbc5a37e6b5ff18f8b1 d11c 86edb16ecdb7319d0ad133687228a808170a50ce36f393c96678f8379c48c746 d16e bf5ab697b6d0415ba63b9aa3aaba28f387f324cd2f1b32eb46f5d3cb253e48ef d18a c388e19be2811a05075a0da664b5b4264040ecd7e2f6eb6cd761d8e579c35103 d18ar df7d5353a7b3be3d6d0f2550179181de27538c41b65b900c7f4a90068ee9d18a demosel bbf6a776efcc2631b982f920f2c9247c8b215dd7a1358b3b9f9d76484f7d43d9 ending 321c325577bb05cf68bec689083cbc9f7fc4d0b634776c1e6cad1f464ffb1da3 endingr c8eabac0fa0bde6d7bbbdba97a4b8948c3e6a0c839d2b438705345c392b43c35 opening 87a5e822f5b428376ad36fcd28ebc56f661cf340f0ea059f11489b5f24e85545 option 19e897b855f2e197e62160a8a409d2ff57a6b8588b831722fab9c3aaca324ea0 preope 3176b630b8a3f9d8cb01ed833d78fbe654054a576c1f2da0ed91007dd71bd136 rank 6a5ed242f966a4c60bba7daf9a2ba1c37482825d0786e1d77476e135030753f5 roll dfe3ca728b6e409613ef7a3dc11b48ecaa236d8ba6cd0951ce4321329842beae s00a 533cb8e9b6ffdcc442c25ba51eb3d83e90cb1ad2831d3870395333398c8402bc s01a 534f8365ad37dbb5c4753bd1720517fa4d1a92e9008597064e6b30a23dc00a75 s02a ece10d39e1d5bafee5acb4dd970bf83801128b04e4fb24ad31756e5bb4ca754d s02b 57a66e93a2028e3fb805c97c585fb6cfb5fe76c93fc4b8495ccdb2c03a1de308 s02c 7c0b12187840f60405970364a1f7c73ec96be32c1130b3f9a87ec58f6ea46915 s02d 5fe851426faf64733c1077998f9463b5455c766d3e27c9cdceed38ac338e8542 s02e cd79cd79a00e18bd5d323b0b8e153b4e8fe5548b6e0ea68f36d13f190eca0477 s03a c42bba970bdc968ee48b572efb03c41f15869cfc00d6aa0d7c8106487534f580 s03ar f34b46313625005b6aef5006b184556c4dd8f13e97a3b0c346f0f4fc7b9fbf04 s03b cd728e144c960e7419d389c81802d3de73c00a2f31e9bfd7eea33ed3ed2be083 s03c cc3b95638684f6f0a6cbcf9b0436fbc7b545ca0eeb0e6e60d6c4d0646dbc7fb4 s03d f9fa0f39352d3305b5cb2bd6c292297d4f351387b0038a27ccec29f42150d903 s03dr fa785a857655809ccf984d8c8ada626addbadfd11db31b34ef496ddce225ade1 s03e af0e15b223431977c2ad233596c37a51c0367da6470c1b760d3f211eb82e894c s03er b1e60c25c0ee92e8c347b7f6a51b2e3fdb10d9ea33a2a77e1acbd8bfc7367114 s04a 59b541a13b987478d6717643c3c146018b070fe374ffae0eaaf3f9a8bdc2ffb6 s04b bca0c362260565051a8d41ffc49d3b9ae84d1bc9dc758164ea019cae82de7fa7 s04br 3ceb35994af2c7da7955ab356cbbb7471c749ff6788ecdfbffab1c5679bb4f9b s04c 5e6bc0c9b13f009c69c2ebdfb401fe9d55a6cd6ee8610cbdd95ee9f3dd71f32a s05a fd08923d1e1ad01b8638f7e8f4a101e270a5f399f3d1afed47abca7532a8c081 s06a 766d25f927a1116d565f97479786a42b93a275398310f775304668ec191a47e7 s07a 20cb960a5d97e0b60c030ed0c17eea78bf6d7e0f5dc50945828e8c2106612546 s07b bbe527b3883ad7c41e4999a8b1d49e64265100b7d8ff6a7724e3fce5d6fb7328 s07br 04007a426525216049196b550e22fc0e922c75f78c6fcfc4b469f9d5defbbc47 s07c 03904064a3d2d2bcd83f719cf7de0d780886ebeae5645dcc7e345acd7fe8cba1 s07cr e3c3503599693be3d3729e0bfc09d364de85b46520eff3909b822a14a7dadfbd s08a 56a0d3aa551dd6eefda902497c3f0a90c458b4ab0a54b9a63b7fe3298606d4c9 s08b 21c5534dd17e5579404b2b0b2f3c47fb324b27a363a108669e3818a3dee15ded s08br 064e8dbb2af7589a7122f02a51e202d43fd3e9bf05aa18258c5cd88621a2d69c s08c 5badd1f304a57a3e55af6d5fe15694c51398c602779a31ee2b7276ad9f9aafbb s08cr 1521588d917c0558839f915191ed5b643fba37a7d1fa4dc228951b433e1070c9 s09a 4c698b375890c793c3622d410bffab7db48c01cfff393f458cd5712e316a7177 s09ar 362fbe4c139197907498e38a1f56e403fe39b4a0217d34bfcf49cf86e86cb76b s10a 95f9cb0d5def5f30bb2133c0452b3aa49438f56c95535178d61eb11a03bb2e6e s10ar 465959ab31568740a4bf30bf0958865e485e48538e449a6b3c696c5fd7d52f69 s11a 70be6cf00267ed663e29ce6b9598396e8fb7c60024b76ff86508244c56d39bf6 s11b 280920ec9559d0c836bab8995de902f227759bb7430025a650f7c20633889f51 s11c e49fbd3c76f8137fe4414699c7816143ea6c83c3dd1f8c44db9f1bd007e5ceec s11d b7e8487718b1c3dd835b3b71b785acc367469f5c84e7834d2b91518dc17da21e s11e 8400e639567b380f28320ccfc5d624b6aa16f8dafa80fdc212976ab386014a9a s11g 60c1e1882b4d9df99478a117a9bfb0d20eb58f4f37305aa46bb1658cf2761eb7 s11h de8b36f6bdeb9871b28bf53c2fd13f3f53d836cadcf26fe735358e42151a478b s11i 706e9fa4b2b2288b6967cc0e519a109f0d2fd6da01dc190996f331b28e3f57e9 s12a e99681d93e10f8cb1fd9fa0ae694bb1f5a517b18a42f8791d0df58feccdd2e1d s12b 7f7e125ea50101399608c859611515df3fb6f04c87ccfdcb10521d86a5aff71a s12c 3e22cf0791fffbef348149ba97e65b9d147488cb45992a1dd84e343414948cf1 s13a 3af85549577319540e53c789f8a20fd10d8b080f74b309a3c6e966b453b75544 s14e 0ad69a93f9aadf2e7b0b254cf6d39ad16c118d0af9686609b9df8ebcbed8986a s15a ab3bf00937e226119c4649e9aa5db7f24e4aab844cb550c752bc3ce1a06f735e s15b 5ab64d6c10801c11b0f672cbb4e68ab62ef1bf058944f5c3d32dbd073e3c8501 s15c 7a6d398f600f359a04b8d9fcb7c006fdc888f4fcbdffd761e09ef4a932195483 s16a 1bec05b1d61f2f5b6abffa1903abcea0ab9e5f4ddebb88ac64506c81548e6ccb s16b 811a2aa5d5cd7ba8673f3ca9cc3a89f07c8ac9e1f3f5843fed311557ebc0b9f6 s16c 8217a2be487140af5bbded5f0dc37ab8cabedaf9af99d16256650ce27a8a5b50 s16d c37c642eb06d7ec39364e4a1fac17e606804eee229e047102d4a2e93346e773f s17a a6b691ff0be4af526fb856847be0549dbe015b31b7fb137a1fbbe6027125d4d1 s17ar a6b691ff0be4af526fb856847be0549dbe015b31b7fb137a1fbbe6027125d4d1 s18a 4f605b802aef5c69ce4cc875165d41139acde9af1e9fdf419d0e4cee2bc7087e s18ar 17d33d059f09a7470b2e6f44efc2469f52f7ff74093542ffb4cdf52a5aa6c79d s19a 48390084a9a716bef980627c57df1867763a6502ad5109d2a6b3712e652840d7 s19ar ef64d5fdb5e8285116ee2f8c693bc20f9af802dc6c16996f815d8823127352e6 s19b d757942aca5d36ab95741801de1f68526c3a8e128018814f25655b7d72a7c249 s19br 3d2d7c04d13dd3f55a97348f74eaf891615cfa203812d15494b53f9e570fe2bd s20a d14fdf0f3b5c98f72fd9f24fd119cdf88660528930ec784dc3d021b92e796925 s20ar 4d6fee8a574d6b900eadff3925f2a38516c2d28784d6e38444ce6c9ece46e104 select 10350d22ceb73b58224a2da9cc71a87380415e304b4c161a787b491162636bc9 select1 6b101068fb3d41d9d634256f21cb094e13f331ed9fbbdb271be2a01ec631c145 select2 6b101068fb3d41d9d634256f21cb094e13f331ed9fbbdb271be2a01ec631c145 select3 6b101068fb3d41d9d634256f21cb094e13f331ed9fbbdb271be2a01ec631c145 select4 6b101068fb3d41d9d634256f21cb094e13f331ed9fbbdb271be2a01ec631c145 selectd 6b101068fb3d41d9d634256f21cb094e13f331ed9fbbdb271be2a01ec631c145 sound 4173d0fcbc7bfcd477d2e0fa6810b509bf6392efb01fd58a7fa114f003849816 title fb97721e30fd55cf6251e446d6e7d38e951049ec4703301da7fef7fe9c1afa6b
Overlays on SLPM-86248
Status	Identical to SLPM-86247 overlays.
Overlays on SLPM-86249
Status	Work on it not yet started.

How to build

1. Install Python 3 if you haven't and make sure it's in your PATH.
2. Clone down the PsyQ SDK repo from: https://github.com/FoxdieTeam/psyq_sdk.git
3. Clone down this repo.
4. Open a terminal and cd into the build directory.
5. Issue the command pip install -r requirements.txt.
6. Issue the command python build.py --psyq_path=YourPath where YourPath is the location of your cloned psyq_sdk depot.
   • Alternatively you can add PSYQ_SDK to your environment variables before invoking python build.py.
7. At the end you should see a message confirming that the built binary's hash matches the original game's binary's hash. If your code caused the compiler to emit warnings, try to fix them without breaking the match.

How to use the built executables

Once you have successfully built the executables from the source code, you may want to play it to debug or test the changes you have made. Please keep in mind that if the size of the main executable changes or addresses shift, the original overlays won't work properly. This guide does not describe how to repackage overlays (a packer tool is planned for the future).

PCSX-Redux

PCSX-Redux emulator provides a convenient way to load a modified main executable. Once you have loaded the original image of Metal Gear Solid: Integral you can load a modified executable in "File > Load binary" menu. This repository contains some helper Lua scripts that can be used with PCSX-Redux in build/pcsx-redux_scripts folder.

Other emulators - rebuilding ISO

To rebuild an ISO with your modified executable, you need a tool called mkpsxiso: download and extract it to a folder of your choice.

Next, you need the original files of Metal Gear Solid: Integral from the CD-ROMs. If you have dumped the discs into .bin/.cue pairs, you need to unpack them into a folder using mkpsxiso. The following commands show how to do this for the first disc, but the same applies to the other two.

Open a terminal, cd into a folder of your choice and run the following command:

<mkpsxiso_folder_path>\bin\dumpsxiso.exe <path\to\mgsi_d1.bin> -x MGSI_D1 -s mgsi_d1.xml

This will create a folder named MGSI_D1 (containing the files of the first disc of the game), and an additional file, mgsi_d1.xml.

Open mgsi_d1.xml and replace

<file name="SLPM_862.47" source="MGSI_D1/MGS/SLPM_862.47" type="data"/>

with

<file name="SLPM_862.47" source="<path/to/_mgsi.exe>" type="data"/>

where _mgsi.exe is the output of the build process.

Optionally, you can also edit the attributes image_name and cue_sheet of the iso_project element to give them more appropriate values, like mgsi_d1.bin and mgsi_d1.cue, which are the output files of the next step.

Finally, run

<mkpsxiso_folder_path>\bin\mkpsxiso.exe mgsi_d1.xml

to re-pack the MGSI_D1 folder into a .bin/.cue pair that now contains the new executable instead of the original one. From now on, this is the only command to be executed every time you want to test a different version of the executable.

Now you are ready to play the game with your favorite emulator by starting the file mgsi_d1.cue.

How to decompile a function

Now that the work is moving onto overlays, this section is no longer up to date. Please join our Discord and ask for help in #metal_gear_dev.

Using IDA or Ghidra (with the ghidra_psx_ldr extension) disassemble the original game binary (SLPM-86247), or use one that you compiled yourself provided that the output was OK. Now choose a .s file from the asm directory where that function isn’t part of psyq.

Given the address of the function go to this location in your reversing tool. Delete the .s file and search for a .c file which has a #pragma INCLUDE_ASM() directive pointing to the former .s file; if none exists, create a .c file with the name of the function and open it. Now write an empty C function that has the same name as the former assembly function as well as a suitable signature; when you re-execute python build.py, the build will not be OK as your empty function will no longer build a matching binary.

Now comes the hard part: implement the function such that it matches the functionality of the assembly and build again. Repeat this until your build is OK – ie your C code is functionally the same and produces exactly the same assembly as the original function.

Iterative building is currently unreliable and it is highly recommended to run python clean.py && python build.py to be certain that your binary is truly a match.

Help, I am totally stuck?

Join our Discord and ask for help in #metal_gear_dev.

There are various Ghidra scripts in build/ghidra_scripts/ to help with decompilation:

• import_map.py: when you have produced a matching build, this imports the symbols from the map file into Ghidra;
• update_data.py: make sure to read the instructions to this script, which updates data in accordance with declared data types provided they have been imported from header files;
• update_functions.py: updates function return types and parameters according to the declarations of matched functions.

It is highly recommended to re-run auto-analysis whenever you have executed these scripts.

We make extensive use of decomp.me, which has a Metal Gear Solid preset, to help match functions; before working on a function, search for it on the website and if you don't find it, go to the build folder and run python decompme_asm.py [path to .s file] to have the assembly instructions in your clipboard ready to paste into a new decomp.me scratch.