Skip to content

About

Matching decompilation of Scarface: The World Is Yours (PC 1.00.2 and Xbox), verified byte for byte with MSVC 7.1. Community project; bring your own game files.

Topics

Resources

Contributing

Stars

15 stars

Watchers

1 watching

Forks

Repository files navigation

scarface_decomp

Language Compiler Target Discord

Website and live progress: scarface-decomp.pages.dev · Questions and help: Discord

A matching decompilation of Scarface: The World Is Yours (Radical Entertainment, 2006): C++ source that compiles, with the compiler the game was built with, to the same machine code as the game. It is meant for modding research, engine bug fixing and preservation.

This repository contains reconstructed source code and tools only. It contains no game executables, no game assets and no compiler. You need your own copies of the game files and of the Visual C++ Toolkit 2003 installer to verify anything.

Status

Xbox default.xbe PC Scarface.exe 1.00.2 Total
Verified functions 7,905 449 8,354

Plus 7,276 in the April 2006 Xbox prototype (game.xbe), unreleased code, counted on its own.

3,273 of them are under 10 bytes and the largest is 3,647 bytes, so the medium and large functions are where the work is.

Every number here is produced by the compiler, not typed by hand: portal/scripts/reverify_all.py recompiles every claimed function with the real compiler, and the portal adds each new match the moment it verifies. The work queue holds every function that can be read: all of the Xbox version's game code and the readable tenth of PC 1.00.2 (the rest of the PC file is encrypted), about 21,000 functions; python portal/verify.py --status prints the exact numbers, and reports/reverify_report.md lists every claimed function and why it does or does not count.

Project lead: RRutherrfordd (Founder) / RogiPogee

Help wanted

This is a community project and every bit of help counts, from your first 5-byte function to naming classes and documenting the engine. You don't need to be an expert: the portal hands you one function at a time, shows the original bytes and disassembly, and tells you exactly how close your C++ is. See CONTRIBUTING.md to get started. What still needs doing, one job at a time: HELP_WANTED.md. Working with a coding agent (Claude Code, Codex, Cursor and the like)? Tell it: read AGENTS.md in this repository and follow it. It works from the command line with portal/agent.py, under the same rules as the portal.

Game scripts: all 635 of the game's compiled TorqueScript files (the same on PS2, Xbox and PC) and all 864 of the April 2006 prototype's decompile to readable TorqueScript that compiles back to the identical file. See docs/SCRIPTS.md; the portal's Game Scripts tab shows them.

PS2: the PS2 game (SLUS_211.11) is in the portal as a fourth version. It was built with another compiler (Metrowerks CodeWarrior for PS2 3.0.1), which decomp.me runs: the portal compiles PS2 functions there and checks the result against your own copy, with the same rules. About 1,300 PS2 functions are paired with their Xbox twin, so a matched Xbox function gives its PS2 twin a head start. Its menus that load when needed (pause menu, shops, business screens, gambling) are in too: 730 functions in six code overlays the portal copies off the disc. How the compiler was found and how it works: docs/PS2.md. The Wii version is still open for anyone to start (docs/OTHER_VERSIONS.md).

What "verified" means

A function counts only when the compiled C++:

  1. has exactly the length and bytes of the original, apart from the 4-byte fields the linker fills in;
  2. passes the relocation checks: internal jumps land at the same offsets, data it defines matches what the original points at, and symbols named for an address (DAT_00439DA4) are that address;
  3. contains no 2006 address written as a number;
  4. is plain C++: no inline assembly, _emit, naked functions or section tricks.

The full procedure, with code generation notes for this compiler, is in docs/METHODOLOGY.md.

Quick start (no experience needed)

You need Python 3 and Git (both free), your own copy of the Xbox game, and about 10 minutes. We strongly recommend Visual C++ Toolkit 2003 too (the compiler the game was made with), from your own VCToolkitSetup.exe (below): with it, the portal checks your work on the spot and credits you right away. Only if you can't get it working, solve functions on decomp.me and have a maintainer check them.

On Windows, the short way: download scarface-setup.bat and double-click it. It installs Python and Git if they are missing, puts the project on your Desktop and starts the portal; it replaces steps 1, 2 and 5 below.

  1. Install Python 3 from python.org. On Windows, tick Add python.exe to PATH on the installer's first screen. Install Git too, from git-scm.com (the default options are fine).
  2. Get this project with Git: open a terminal (PowerShell on Windows) where you want the folder and run git clone https://github.com/scarface-decomp/scarface_decomp.git. To update later, run git pull in that folder: it keeps your work. (Rather not use Git? Press Code, then Download ZIP on GitHub. It works, but it gets more complicated later: there's no one-command update, and a new ZIP replaces your work, so copy reports/verified_registry.json out first, or connect the folder to Git: docs/CONTRIBUTING.md.)
  3. Add your game files: put the game, or the downloads it came in, in the binaries folder. The portal takes out what it needs when it starts, with nothing to install or unpack first: default.xbe from the Xbox disc image (.iso, .zip or .7z), Scarface.exe from the official PC 1.00.2 patch, game.xbe from the prototype's .zip, and the game's scripts from all of them (see binaries/README.md). The US Xbox disc is the one that matters: the whole Xbox game can be read, while most of the PC file is encrypted, and both run the same game code. The PC game and the April 20, 2006 Xbox prototype are optional extras. Only the exact US versions are accepted, and the portal checks: see docs/GAME_VERSIONS.md. Your files never leave your computer. The goal is the released game plus the code that never shipped; prototype matches are saved in reconstructed_src/proto/ and counted on their own row. The work queue only lists the prototype's own code: functions that are also in the released game are matched along with it (same code) or are older versions of it, so they wait in a separate list ("Prototype: also in retail") instead.
  4. Start the portal: on Windows double-click START_PORTAL.bat; on macOS or Linux run sh start_portal.sh. The first time it installs what it needs, unpacks your files and lists every function (a few minutes), then opens http://localhost:8085. Something not working? Run python portal/doctor.py in the project folder: it checks Python, Git, your game files, the compiler and the portal's port, and says how to fix each problem (--share gives a copy that's safe to paste in #help).
  5. Pick a small function. The editor starts you off with C++ written from the game's own code (calls and globals already named for their addresses); for many small functions it matches as it is. Change it until it does.
  6. Press Compile & Verify to record it under your name. That needs the compiler (below); set it up once, before you start.
  7. Press Submit your work when you're done for now. Your matches are saved on your computer as you go, so nothing is lost if you close the portal; submitting packs the new ones into one file to post in the Discord or a GitHub issue, and a maintainer adds them under your name (every function is compiled again first).

Backup: decomp.me. No compiler yet, or it's acting up? The portal's decomp.me button opens the function on decomp.me, which runs the same compiler in your browser. Get it to 100% there and post the link in a GitHub issue or in #help on Discord; a maintainer will verify it and credit you. Only that one function's bytes leave your computer, the same as any decomp.me scratch, and the portal's check is still the one that counts. Every scratch is filed under the Scarface preset, where everyone's can be found.

The compiler

From your own VCToolkitSetup.exe (Visual C++ Toolkit 2003; Microsoft gave it away for free and no longer offers it for download; the Internet Archive keeps a copy). The setup accepts only the real one. Put it in the project folder (scarface_decomp) and start the portal: START_PORTAL.bat and start_portal.sh set the compiler up by themselves the first time (they also look in binaries/, source_archives/ and your Downloads folder). To do it by hand instead, in a terminal in the project folder:

python portal/scripts/setup_msvc71.py VCToolkitSetup.exe

This installs the compiler with its headers and libraries into portal/tools/msvc71/. Either release of the Toolkit works: 1.0 (cl.exe 13.10.3052) or 1.01 (13.10.3077), which Microsoft only renumbered. The script says which one you have, and every verified match records it. On Windows it runs natively. On Linux and macOS it runs under Wine with a 32-bit prefix, for example export WINEPREFIX=$HOME/.wine32 WINEARCH=win32 WINEDEBUG=-all (extraction needs msitools). Set SCARFACE_MSVC_BIN to use a compiler somewhere else. The Toolkit is not redistributable, so portal/tools/msvc71/ is never committed. The SHA-256 of the game files the registry was verified against is in reports/verified_registry.json under binaries.

Working on functions

In the portal (http://localhost:8085): sign in with a handle and a PIN of at least 8 characters, claim a function from the queue, write the C++ in the editor (it starts with a draft written from the function's machine code; you can also use your own AI key, or decomp.me if the compiler isn't set up), and press Compile & Verify. A match is recorded in reports/verified_registry.json, and the generated source files are rewritten. About 4,600 functions are look-alikes of another (the same machine code with different addresses); after a match the portal swaps the addresses and names into your code, verifies it on each look-alike and credits you for every exact match (portal/tools/lookalikes.py). The queue lists one function of each group first. Match the easy ones (next to Batch Run) needs no AI and no key: the portal compiles its own draft for every function that is still open, smallest first, in the background, and records each one that matches byte for byte with every address checked. Those are matched, not yet named; the workbench says how many things each matched function still has to name, and Ask the AI to name them tidies one with your own AI while the bytes stay fixed (docs/NAMES.md). Manual start: pip install -r portal/requirements.txt, then python portal/decomp_portal_server.py.

Variable Default What it does
SCARFACE_HOST 127.0.0.1 interface to listen on; the portal is local-only by default
SCARFACE_PORT 8085 port the portal listens on
SCARFACE_MAINTAINERS RRutherrfordd (Founder) handles allowed to use "Sync to GitHub"
SCARFACE_NO_BROWSER unset 1 stops it opening a browser
SCARFACE_DECOMPME_URL https://decomp.me where the decomp.me button sends functions
SCARFACE_DECOMPME_PRESET 266 the decomp.me preset scratches are filed under (Scarface's); none turns it off
SCARFACE_LOOKALIKE_MAX 1000 how many look-alikes a new match is tried on
SCARFACE_EASY_MAX 0 how many functions one "Match the easy ones" run tries (0: all that are open)
SCARFACE_NO_CATCHUP unset 1 stops the portal trying earlier matches on their look-alikes when it starts
SCARFACE_MSVC_BIN portal/tools/msvc71/bin where cl.exe (13.10.3052 or 13.10.3077) is, if not there

From the command line, with the same rules:

python portal/verify.py my_func.cpp --va 0x00011F20 --bin xb --match vfunc_03@Collidable@ --show-diff
python portal/verify.py my_func.cpp --va 0x006DE620 --bin pc

Maintenance:

python portal/scripts/reverify_all.py     # recheck every claim, rewrite the registry, report and generated files
python portal/tools/queue_builder.py      # rebuild the work queue from the binaries

Game files for your own use

The portal's Game files section copies everything out of your own copies of the game (sounds, textures and models, animations, videos, scripts, all of it) for modding and looking around. It reads the Xbox disc, the PS2 disc, the April 2006 prototype and the PC disc. Nothing needs installing: the PC disc image (.iso) is read as it is, its cabinet files unpacked and named by the disc's own installer database, and with the 1.00.2 patch in binaries/ its patch01.rcf is added, as a patched install has it. The game's .rcf archives are unpacked too, including the ones packed inside them (that is where the dialogue is), each into a folder named after the archive.

Choose a layout:

  • No duplicates: a file that is identical in several versions is copied once, into Shared/, and each version's folder keeps only what is unique to it.
  • Every version complete: each version in its own folder.
  • Best version of each file: one copy of every file, in Best/. Where the versions have it in different forms, the highest quality wins: sounds by sample rate, then channels, then codec; videos by picture size; models and textures by texture size, then by how much each pixel really stores (the Xbox's and the PC's textures are the same size; the PC keeps many in full colour where the Xbox compresses them). That is mostly the PC's (Ogg Vorbis sounds at 44.1 to 48 kHz, 1280x720 videos, its textures), the Xbox's 5.1 surround sounds, and some of the prototype's map files (they hold more textures: mostly ones the final game keeps in shared files instead). INDEX - Best.txt says where each file came from and why.
  • The PC first, then what only the others have: the whole PC version in PC/ (patched, if the patch is there), and from the Xbox, PS2 and prototype only what the PC doesn't have: what only one of them has in its Exclusive to folder, and what several of them have, once, in Not on the PC/. The PC's copies are the ones Blender shows best for models and animations, so this is the one for Blender: Copy everything, PC first at the top of the Game files tab does it in one click.

And how to arrange the folders: as in the game, or by type (Sounds, Textures, Models, Animations, Videos, Scripts & text, Other) with the game's folders inside. By type, sounds get their original names back (every sound stores the name it had on the developers' machines, so art/sound/rsd/8/85657545f63b9543.rsd becomes art/sound/music/world_streams_mono/miami/dj/03.rsd).

The portal then lists, for each version, the files only it has and the ones it has in a different form, sorted by type (sounds, textures, models, animations, videos, scripts and text) under a heading for each. Sounds play right in the list (Play, with their subtitles), movies too (Watch: Bink and the PS2's movies are made playable once with your own FFmpeg), and Open on a Pure3D file says what it holds and offers what fits: its pictures, its subtitle text, or Blender. Every version's own formats are decoded: the PC's Ogg and PNG, the Xbox's ADPCM (the cutscenes' 5.1 too) and DXT, and the PS2's VAG and its palette pictures, which the portal puts back in order from the PS2 graphics chip's block layout. That is all done on your computer, only for a browser on that computer (Xbox WMA music can be saved and played in a media player). View here shows a model or a map area in the page itself, to turn and fly through, with nothing to install. Open in Blender starts your Blender with a file as a scene (and saves it as a .blend): characters with their skeletons, skin weights and the game's animations, cameras with their moves, guns, cars with their moving parts, and map areas with the trees, lamps and benches the game places on them, as the game first shows them, on any version. The In Blender box does a whole map area at once, or the whole city into extracted/blender/, one file per area, then opens it all as one scene. For the city you pick a Time of day (As stored, or an hour from midnight to midnight: the sky's colours and the fog of that hour) and a Weather (Clear or Rain); export the city again after changing them. portal/tools/p3d_gltf.py does it from the command line (FORMATS.md).

Cutscenes are in the same box: every one of the game's cutscenes, listed once, opens in Blender as the game stages it, with everybody in the scene standing where the script puts them, Tony in the suit it gives him with his lips, brows and eyes moving, the weapons it hands out, the vehicles and the game's camera (Numpad 0), on the street or in the room where it happens. Pick 30, 60 or 120 frames a second; cutscenes the game plays one straight after another come as one. Props a cutscene spawns, effects and sound aren't in yet (FORMATS.md).

Export every texture writes all the game's textures out as .png into extracted/textures/: the PC's, in a folder named after the file each is in, then what only the other versions have in their own Exclusive to folders. Where another version has the same picture at a higher resolution, that one is used: checked against all of them, the Xbox's textures are the same size as the PC's, the PS2's the same or smaller, and 48 of the 2006 prototype's are bigger, of which the world textures (a garbage bag, stone, metal, a shelf of tapes) are the same pictures at twice the size, and the menu icons and a carpet are different pictures under the same name, so those go in the prototype's own folder.

Speed: with every processor core on, a copy reads the versions at the same time, one process each, when the discs are on a fast drive (an SSD; on a hard drive that would be slower, so it doesn't), and the city export does several areas at once. Small files (99% of them) are fingerprinted before they are written, so a file several versions share is written once. With your graphics card on, movies are made playable on it (NVIDIA, Intel or AMD, through FFmpeg). Copying itself can't use a graphics card: it's reading, fingerprinting and writing files. All four versions take about 12.4 GB without duplicates, the best versions about 4.4 GB. The files stay on your computer: binaries/ is never committed, and they must not be shared. From the command line: python portal/tools/game_assets.py --extract best --folders type.

What's in the folder

START_PORTAL.bat      double-click to start (Windows)
start_portal.sh       the same for macOS and Linux:  sh start_portal.sh
binaries/             put your game files here (never uploaded)
reconstructed_src/    the rebuilt C++ source: the result of the project
reports/              what is verified, and the progress numbers
docs/                 the website and the guides
portal/               the portal itself and its tools (you don't need to open it)
Path What it is
reconstructed_src/Original_Binary_Order_*.cpp, pc/, xbox/, proto/ Generated from the registry: every verified function in address order, and grouped by subsystem and class.
reconstructed_src/*.cpp, *.h Hand-written translation units. Methods carry their address in a comment, e.g. // PC VA 0x006E7EB0 (11 B).
reconstructed_src/include/ Shared headers. reconstructed_src/CMakeLists.txt lets an IDE index the sources.
reconstructed_src/Partial_Proven_Checkpoints.cpp Best partial attempts saved by the portal. Not verified.
reports/verified_registry.json The record of what is verified, with the code, flags and who verified it.
reports/reverify_report.md Every claimed function, its status and the reason.
docs/index.html The public website: live progress and every verified function (see docs/README.md).
docs/CONTRIBUTING.md, docs/GAME_VERSIONS.md How to help, and which copies of the game are accepted.
docs/METHODOLOGY.md, docs/SCRIPTS.md, docs/PS2.md, docs/OTHER_VERSIONS.md Verification rules, the game's scripts, the PS2 lane, the Wii version.
docs/FORMATS.md, docs/NAMES.md, docs/VERSIONS.md The game's file formats; function names for Ghidra and IDA; what differs between the versions.
docs/LEGAL.md, docs/PROVENANCE.md, docs/CREDITS.md Legal notes, where code and names may come from, credits.
docs/CLEAN_ROOM.md, docs/cleanroom/ How research done next to leaked code becomes a written spec that someone who never saw it builds from, the record of who read what, and the specs.
docs/function_guide.json What the specs say each named function does, and whether that was checked on the Xbox. The portal shows it beside the function you open.
docs/SCARFACE_DECOMP_AI_HANDOFF.md, docs/AGENTS.md Brief for AI assistants (served by the portal at /download/ai-handoff), and how an agent uses the portal API.
portal/decomp_portal_server.py, portal/website_kit/ The portal: its server and its page.
portal/verify.py The command-line checker.
portal/tools/ Verifier (msvc_verify.py), binary reader, queue builder, C++ policy, decomp.me export, look-alike grouping, game-file checks (game_files.py), copying the game's files out (game_assets.py, with ms_cab.py for the PC disc's cabinets), script-format tools.
portal/scripts/ Compiler setup, script extraction, re-verification, repository checks, and the Ghidra and IDA name scripts.
portal/tests/ Test suite (python -m pytest -q portal/tests).

Contributing: see CONTRIBUTING.md.

License and legal

The code in this repository is licensed under the GNU General Public License v3.0 or later, with an additional permission for linking with the Microsoft runtime and SDK libraries the game uses (see LEGAL.md). The license covers the contributors' own work only: it grants nothing over the game, its assets, or the names and marks of its owners.

No game executables, assets, compiler or SDK files are included or distributed; bring your own legally obtained copies. The project is not affiliated with or endorsed by the game's developer, publishers or rights holders. Where code and names come from, and how AI tools may be used, is set out in PROVENANCE.md. Credits are in CREDITS.md. None of this is legal advice.

About

Matching decompilation of Scarface: The World Is Yours (PC 1.00.2 and Xbox), verified byte for byte with MSVC 7.1. Community project; bring your own game files.

Topics

Resources

Contributing

Stars

15 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages