Twisted Metal: Black

You build the game yourself, on your PC, from your own disc: nothing of the game is in the download.

1. Download the release zip from the Releases page. Each release publishes the zip's SHA-256: check it before running anything (Get-FileHash .\TMB_Recomp-<version>.zip in PowerShell, or certutil -hashfile <zip> SHA256).
2. Unzip it anywhere with about 10 GB free (into D:\Games, say: the zip holds a TMB_Recomp folder), but not in Program Files (the launcher writes the game next to itself). Keep its folders together: TMB Launcher.exe, source\ (our code), kit\ (the compiler and tools that build the game), README.txt (these steps, English and French), LICENSES\.
3. Double-click TMB Launcher.exe. The launcher is not signed, so Windows may say "Windows protected your PC": click More info, then Run anyway.
4. Click Select your disc image… and pick your image of the USA disc (SCUS-97101): a .iso, or a .bin with its .cue. The launcher checks it at once (the European disc and other games are refused with a message saying so).
5. Click Prepare the game. It takes a few minutes, once (about 3.5 minutes on an 8-core PC); you can stop it and it continues where it left off next time.
6. Click Play. In the game, F2 opens the settings (controls, video, cheats). Your memory cards, settings and logs are in %APPDATA%\TMB_Recomp (the launcher's Maintenance tab opens it).

The launcher says when a newer release is out (it asks GitHub for the latest version number at start; Settings turns that off; nothing is downloaded by itself). Its Update button downloads the new release's zip, checks it against the release's SHA-256, installs it over this one and restarts (tools/apply_update.py); unzipping the new release where the old one was (replacing the files) does the same by hand. The launcher then sees the code changed since the game was built and offers Rebuild now (also Rebuild in the Maintenance tab); only what changed is built again, the files the new release no longer has are removed, and the saves stay. To uninstall, delete the folder (and %APPDATA%\TMB_Recomp for the saves and settings). Releases are Windows only for now; on Linux the port builds from source (below), but has not been tested there since the native work of November 2026.

Picking the work up elsewhere: docs/HANDOFF.md (state, how to measure, next steps).

Playable, at full speed, as a native port, at NTSC's 60 frames per second. The game boots, runs its own IOP modules, plays the movies with their sound, goes through the menus and level loading, and plays matches and story levels: driving, weapons, bots, HUD, music and effects, deaths, respawns, saving and loading. Natively (the default, at twice the PS2's resolution) a match holds 57.7 to 60.4 fps (4 players split screen: 55.8 to 60.4) on a Ryzen 7 7800X3D with an RTX 5070 Ti. Every Challenge arena has been played; still being checked: story levels 2 to 8 to the endings, and some effects against the PS2 picture (issues found while playing are fixed as they come: docs/RECOMP_NOTES.md).

_{The USA release, native (the default), drawn at twice the PS2's resolution.}

Native port (no PS2 hardware emulation left, not even a small part: the shared goal of the fork's ports). Native means the game's draws built straight from its own data (vertices, matrices, materials), with no GIF packet, no GS state machine and no copy of GS memory in between.

✅ works · 🔧 in progress · ⏳ not reached yet

docs/RECOMP_NOTES.md records how the port is brought up, every fix and how it was found, and what remains open.

A fully playable Twisted Metal: Black as a true PC program, from the intro to the endings: no PS2 hardware simulated where the PC can do the job itself. Accuracy first; then widescreen and frame rates above the PS2's.

The port started as a static recompilation on a reimplementation of the PS2 hardware, and is becoming a native PC program piece by piece. Each piece below replaces a part of the PS2 that was simulated:

disc files (game_us/) ──► ps2_analyzer ──► recomp/tmb_scus97101.toml (+ recomp/tmb_manual.toml)
                                           │
                     ps2_recomp + the ELF's own symbol table ──► C++ (one file per function, generated_us/)
   the disc's IOP modules, loaded offline ──► iop_recomp.py ──► C++ (generated_us/iop/)
                                           │
                 CMakeLists.txt ──► PS2Recomp runtime + generated code + runtime/ (TMB's overrides, native adapter)
                                           │
   native renderer · texture cache · native sound mixer on the PC clock ──────┼─► ps2EntryRunner
   native display (field, mode) · window presentation on the GPU, at 2x (no GS front end; diagnostics: the GS native back end)
   what is left of the PS2: EE kernel HLE · DMAC (kicks to the GIF / VIF complete unread) · IPU · IOP kernel layer

• The USA executable's addresses. The build is game_us/ -> generated_us/ -> build/game_us; runtime/'s hooks use the USA executable's addresses and its generated function names directly, and recomp/tmb_manual.toml holds the recompiler's hand-written settings by symbol name. NTSC draws a 640 x 224 field, which the native renderer follows.
• The executable ships its full symbol table (3,572 named functions, .mdebug), so no Ghidra pass is needed: ps2_analyzer reads the symbols, recognises the Sony SDK functions that have runtime handlers and writes the config.
• PS2Recomp turns every function into C++ and emits the address-indexed function table.
• runtime/tmb_meshes.cpp (3D at the game's hooks), runtime/tmb_particles.cpp (effects from the particle lists), runtime/tmb_2d.cpp (2D builders), runtime/tmb_textures.cpp, runtime/tmb_vu0.cpp draw the game natively; runtime/tmb_native.cpp sets the native switches, publishes the frame, and keeps the old VIF1-stream adapter for the comparison modes (TMB_NATIVE_VIF=1). The generic parts live in the fork (ps2xRuntime/src/lib/native/: renderer, texture cache, GIF translation; docs/native.md), shared with the other ports.
• runtime/tmb_overrides.cpp holds the other game-specific bindings.

The PS2Recomp fork lives in PS2Recomp/ (git submodule, TheBozos/PS2Recomp), shared with the other recompilations built on it (Valkyrie Profile 2, Drakengard, The Lord of the Rings: The Third Age, Jade Cocoon 2, Soulcalibur III and others). Fixes made for this port land there.

Players need none of this: the release's launcher and build kit bring everything ("For players" above). To build from the repository:

• Windows 10/11 with MSYS2 (UCRT64, see below), or Linux (developed on Arch at first; not tested since November 2026)
• CMake 3.21+, Ninja, GCC 13+ or Clang with C++20
• FFmpeg development libraries (libavcodec, libavutil, libswscale) and pkg-config (or a static FFmpeg folder: PS2X_FFMPEG_ROOT)
• X11/Wayland and OpenGL development headers (raylib is fetched and built by the fork)
• A CPU with AVX2 (the runtime is built for x86-64-v3)
• Your own copy of SCUS-97101 (check the hash above)

tools/tmb_build.py goes from your own disc image to a game folder that runs, with nothing derived from the game ever downloaded: it checks the disc (the USA release, SCUS-97101: SCUS_971.01's SHA-1; the European disc and other images are refused with a message saying so), extracts it with its own ISO9660 reader (.iso, .bin / .cue; no bsdtar), recompiles the game's code and VU1 microcode, converts the textures and models into their packs, recompiles the IOP modules straight from the disc's MOD/*.IRX (no boot of the game), compiles the runner and stages it.

python tools\tmb_build.py --disc "D:\Games\Twisted Metal - Black (USA).iso" --out D:\TMB
"D:\TMB\TMB\Play TMB.cmd"

• Python: the standard library only, so the Windows embeddable Python (python-3.x-embed-amd64.zip) runs it; every build-time tool it calls is stdlib-only too.
• Compiler: --toolchain <dir> (a folder whose bin has g++, gcc, cmake, ninja and pkg-config), else the PATH, else C:\msys64\ucrt64 (MSYS2 UCRT64 with the packages below). No bash, MSYS2 shell, bsdtar or rsync.
• --tools <dir>: prebuilt ps2_recomp / ps2_vu_aot (otherwise built from PS2Recomp). --fetch-cache <dir>: the libraries CMake fetches (raylib-src, imgui-src, ... as CMake left them) instead of downloading them with git.
• --disc also takes an extracted disc folder; its .iso is still needed (in it or a folder above), as the game reads raw sectors from the image.
• The game ends up in <out>/TMB: ps2EntryRunner.exe, the DLLs it loads, the two packs, disc/ (the disc's files), disc.iso (a hard link to your image on the same drive, else a copy) and Play TMB.cmd.
• --game <dir> stages the game somewhere else; --check only checks the disc (OK ..., or ERROR verify ... and exit code 1). --debug-info no (the default with the build kit: a player's build) compiles the runner without debug information, the same code as RelWithDebInfo: 45 MB instead of 613, and the compile about a third faster.
• Resumable: a step finished with the same inputs is skipped (--redo <step> runs it and the ones after again, --stop-after <step> stops there). For a launcher, stdout has one line per event: PROGRESS <step> <i>/<n> <message>, PERCENT <step> <0-100>, SKIP <step> <i>/<n>, DONE <step> <i>/<n> <seconds>, ERROR <step> <message> (exit code 1), RESULT <game folder> <launcher>; each step's full output is in <out>/logs/.
• From an empty folder on a Ryzen 7 7800X3D: about 9 minutes (the compile 5, the recompiler's build and CMake's downloads 1.5 each).

tools/make_build_kit.py assembles, once on a developer's PC (MSYS2 UCRT64 installed, network), the folder that lets tmb_build.py run on a PC with nothing installed: no MSYS2, no git, no network, no Python.

python tools\make_build_kit.py --out D:\tmb_kit\kit --zip D:\tmb_kit\tmb_build_kit.zip
rem on the player's PC: TMB_Recomp\ (this repository's files) and kit\ side by side
kit\python\python.exe -I TMB_Recomp\tools\tmb_build.py --disc "D:\Games\Twisted Metal - Black (USA).iso" --out D:\TMB

• tmb_build.py uses the kit when it sits in TMB_Recomp\kit or next to the TMB_Recomp folder (or --kit <dir>; --no-kit ignores it): the kit's compiler, recompilers and sources, FFmpeg through PS2X_FFMPEG_ROOT (no pkg-config) and PS2X_ENABLE_PARALLEL_GS=OFF (paraLLEl-GS, a GS-emulation diagnostic the native port does not use). The game folder then holds the runner and three DLLs (libstdc++, libgcc, winpthread) instead of 81.
• Size: 468 MB unpacked, 142 MB as a zip; assembled in about 2.5 minutes. From an empty folder with the kit and a PATH of only the Windows folders: 4 minutes to the game folder (compile 3.4), no recompiler build, no downloads.
• The kit is build output, never committed. GCC, binutils and the other MSYS2 binaries are redistributed unmodified: a release ships their sources alongside (make_release.py --with-sources: MSYS2's source packages of the versions in the manifest) and lists them in LICENSES\SOURCES.txt.

launcher/ is TMB Launcher.exe, what a player double-clicks: its own small CMake project (raylib, Dear ImGui and rlImGui at the fork's tags, linked static: a 4 MB GUI exe that loads only Windows' DLLs).

cmake -S launcher -B build\launcher -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build\launcher
rem offline, with the kit: -DFETCHCONTENT_SOURCE_DIR_RAYLIB=<kit>\deps\raylib-src (IMGUI, RLIMGUI likewise)
rem                        -DLAUNCHER_FONT_DIR=<folder with Exo2[wght].ttf and OFL.txt>

• It expects the release folder: TMB Launcher.exe, source\ (this repository without .git), kit\ (the build kit); it makes build\ (tmb_build's work folder) and game\ (the game: ps2EntryRunner.exe, disc\, disc.iso, the packs). --release <dir> points it elsewhere.
• Disc check: kit\python\python.exe -I -X utf8 source\tools\tmb_build.py --check --disc <image>; build: the same with --disc <image> --out build --game game, in a job object with no console window (Stop ends the whole tree; tmb_build resumes). Its PROGRESS / PERCENT / SKIP / DONE / ERROR / RESULT lines drive the step list, the progress bar and the time estimate; an error shows tmb_build's message, the step's log and "Copy details".
• Play starts game\ps2EntryRunner.exe game\disc\SCUS_971.01 with nothing set (the runner's defaults), hides the launcher until the game exits, then offers the crash report if one appeared in the user folder.
• Settings: the window mode and size written to the user folder's video.ini in the runner's own format; launcher.ini (disc, language, background motion, build state) sits next to it. English and French.
• The look is the team's, from RecompWatcher: the PS2 BIOS's radial blue, glowing boot towers (motion can be turned off), glass cards, Exo 2 (SIL OFL 1.1, google/fonts at a pinned commit, embedded with its licence; downloaded at configure time, never committed). The icon is TMB's variant of The Bozos' logo, the clown with its head on fire (launcher/tmb.ico; the game's window uses the same, runtime/app/tmb.ico; drawn by docs/branding/make_logo.py). No game art.
• Updates: at start (Settings: "Check for updates at start") and from Maintenance's "Check for updates", one HTTPS GET of api.github.com/repos/TheBozos/TMB_Recomp/releases/latest through WinHTTP; a newer tag_name shows "Version X is available" with a link to its release page (built from the tag). Offline or no release: silent. Update downloads releases/download/<tag>/TMB_Recomp-<version>.zip and its .sha256 (addresses built from the tag, not read from the API's answer) into update\, then runs source\tools\apply_update.py with the kit's Python: it checks the SHA-256 and every name in the zip (one TMB_Recomp\ folder, no .., nothing under build\ or game\, the version asked for), unpacks it whole to update\staging, then moves the files over the release; a file in use (the launcher itself) is renamed *.tmb-old first and deleted at the next start. The launcher then starts its new exe. When source\release.ini's commit differs from the one in game\built_from.ini (written by tmb_build), the Play tab offers "Rebuild now".
• --selftest <iso> --shots <dir> [--wrong <image>] [--error-demo] [--cancel] [--play-seconds s] [--crash-seconds s]: the whole flow unattended, a screenshot of each screen and selftest.log (with PS2X_USER_DIR set, the real user folder is untouched). --screens: the tabs' screenshots only; --ui-scale <x>: another DPI scale; --update-url <url>: the update check asks another address (a test server); --download-prefix <url> downloads the release from there, --update-now presses Update once a newer release is found.

tools/make_release.py makes the player's download from a commit (committed files only; standard library, the kit's Python runs it too):

python tools\make_release.py --version 0.1.0 --kit D:\tmb_kit\kit --out D:\tmb_release --with-sources
python tools\make_release.py --out D:\tmb_release --kit D:\tmb_kit\kit --with-sources --publish --dry-run

• The version is the commit's tag (v0.1.0 → 0.1.0) or --version; x.y.z-pre makes a pre-release.
• A release needs its changelog: CHANGELOG.md at the commit must have a ## [x.y.z] section with content (checked first; --allow-missing-changelog for a test build). The section is the notes' "What's new"; CHANGELOG.md is shipped at the zip's top, and the launcher shows the installed version's section ("What's new" in its footer, and next to Rebuild now after an update). --check-changelog --version x.y.z prints it.
• --verify-zip <zip> audits a zip again on its own; --publish-only makes the draft from a release already in --out (the workflow checks the zip in between).
• Nothing of the game: the export and the release folder are audited (no ELF, IRX, ISO volume, disc file names, generated/ / game/ / disc/ / build/ folders) and the zip's names again; the script stops on any.
• The kit's prebuilt recompilers must be the fork's at the commit (kit_manifest.json tools.fork_commit): when they are not, the release's copy of the kit gets them rebuilt (the original kit stays as it is).
• --publish creates a draft GitHub release with gh (the zips, their .sha256, the notes); --dry-run prints the command. It never pushes: the commit has to be on GitHub first, and the owner publishes the draft.
• Before each release: docs/RELEASE_CHECKLIST.md on a clean Windows.

Releases are built by GitHub Actions (.github/workflows/release.yml), and only when the owner asks: on a pushed version tag, or a manual run with a tag. Nothing runs on ordinary pushes or pull requests.

1. Move the entries under ## [Unreleased] in CHANGELOG.md to a new ## [0.1.0] - <date> section (players first, plain words; Added / Changed / Fixed), update the links at the bottom, and commit. Push the branch.
2. Tag that commit and push the tag: git tag v0.1.0 && git push origin v0.1.0. Or, with the tag already pushed: Actions → Release → Run workflow, tag v0.1.0.
3. The workflow (its first run, with nothing cached, is the longest) checks the tag against CHANGELOG.md, installs the pinned MSYS2 packages, makes the build kit, runs make_release.py --with-sources, checks the result without any game data (--verify-zip, the hashes, tmb_build.py --check and the launcher's --self-check on a file of zeros refused as "not an ISO9660 disc image"), then creates a draft release with the zip, its .sha256, the sources zip and the changelog section as its body.
4. Download the draft's zip and run docs/RELEASE_CHECKLIST.md on a clean PC.
5. Publish the draft on GitHub. The workflow never publishes anything itself; a published release then pings RecompWatcher (only if the WATCHER_DISPATCH_TOKEN secret is set). A failed or wrong draft: delete it (and the tag if the commit was wrong), fix, tag again; a second run for a tag that has a release is refused.

The kit is the same one a developer makes here: tools/build_kit_packages.json pins its 51 MSYS2 UCRT64 packages (exact versions, the files' SHA-256 on repo.msys2.org); make_build_kit.py --install-packages installs exactly those with pacman, and the kit refuses an MSYS2 holding other versions. To move to newer packages: update MSYS2, make_build_kit.py --pin-packages, make a kit, test, commit the file. The same release by hand, on this PC:

python tools\make_build_kit.py --install-packages
python tools\make_build_kit.py --out D:\tmb_kit\kit
python tools\make_release.py --version 0.1.0 --kit D:\tmb_kit\kit --out D:\tmb_release --with-sources --publish

git clone --recurse-submodules https://github.com/TheBozos/TMB_Recomp.git
cd TMB_Recomp
scripts/extract_iso.sh "/path/to/Twisted Metal - Black (USA).iso"      # disc files -> game_us/
scripts/build_tools.sh                                                  # ps2_recomp, ps2_analyzer, ps2_vu_aot -> build/tools
scripts/recomp.sh                                                       # ELF + recomp/tmb_scus97101.toml -> generated_us/ (VU1 microcode -> generated_us/vu1/)
scripts/build_runtime.sh                                                # runtime + generated code -> build/game_us
scripts/iop_recomp.sh                                                   # the IOP modules from game_us/MOD, loaded offline -> generated_us/iop/ (then rebuild)
scripts/run_native.sh                                                   # the native port (native renderer, recompiled sound driver, sound on the PC clock), with the fps counter
scripts/run.sh                                                          # the PS2 path only (VU1 and GS simulated, TMB_NATIVE=0), for comparison
scripts/pgo.sh                                                          # optional, experimental: profile-guided rebuild (~200 s of scripted play)

The same scripts run in an MSYS2 UCRT64 shell, with MSYS2's GCC (MSVC is not supported for this port).

pacman -S --needed mingw-w64-ucrt-x86_64-{gcc,cmake,ninja,pkgconf,ffmpeg,python} git rsync
git clone --recurse-submodules https://github.com/TheBozos/TMB_Recomp.git

Then follow the steps above. scripts/stage_dlls.sh copies the DLLs the runner needs next to ps2EntryRunner.exe, so it can also be started outside the MSYS2 shell. The native port draws with OpenGL 3.3; the PS2 path (scripts/run.sh) draws the GS with paraLLEl-GS, which needs a Vulkan driver (any recent NVIDIA, AMD or Intel driver ships one).

scripts/regress.sh <build-dir> <out-dir> is the fork's port regression run for TMB: boot movies, menus and a Skyscrapers match under the bench lock, with a summary.txt (route reached, exit, fps mean and p10, frames over 25 ms, errors) and the last frame.

scripts/analyze.sh regenerates the TOML from scratch; it discards manual edits, so diff before committing. The runner build compiles about 70 MB of generated C++ and takes a while the first time.

Run the game with the extracted disc folder as cdrom0: (that is what scripts/run_native.sh does):

build/game_us/PS2Recomp/ps2xRuntime/ps2EntryRunner game_us/SCUS_971.01

The runner started with nothing set (a double-click on ps2EntryRunner.exe) is the full native port, the same game as scripts/run_native.sh: everything that script sets (TMB_NATIVE=1, the native renderer, the recompiled sound driver, the sound and the IOP on the PC's clock) is the runner's default, and the variables below still change it (TMB_NATIVE=0: the PS2 path). The frame rate counter is off (F3 shows it, PS2X_SHOW_FPS=1 starts with it, as scripts/run_native.sh does).

• Game data. With no argument the runner looks for game/SCUS_971.01 next to it, then in the user folder; game/ holds the disc's files and the disc image (.iso, for the raw sector reads: the sound banks). With neither, a message box says the data was not found (run the launcher, or see this README) and where it looked.

• Window. Titled Twisted Metal: Black, with TMB's flaming-clown icon (runtime/app/tmb.ico; no game art). No console window on Windows: the runner is a GUI-subsystem program. Started from a terminal (MSYS2, cmd, PowerShell) or with its output redirected, it prints there as before.

• User folder. %APPDATA%\TMB_Recomp on Windows, $XDG_DATA_HOME/tmb_recomp (~/.local/share/tmb_recomp) on Linux, created on the first run (PS2X_USER_DIR=<dir> for another one):

  What	Where in the user folder
  Memory cards	mc0/, mc1/
  Settings (F2)	input.ini, video.ini (PS2X_INPUT_CONFIG, PS2X_VIDEO_CONFIG still name other files), imgui.ini
  Log	logs/TMB_Recomp.log, the two runs before as TMB_Recomp.1.log, TMB_Recomp.2.log: everything the runner prints (PS2X_LOG_FILE=<file> another file, =0 none)
  Crash reports	crashes/crash-<date>-<time>.txt

  The first run copies the cards and settings kept next to the ELF until now (game_us/mc0, mc1, input.ini, video.ini) into it, once per old folder (migrated.txt lists them): a save already on the new card is not overwritten, nothing is deleted.

• Crashes (Windows). A crash writes a report (the exception, its address and module, the stack as module+offset with the address addr2line -f -C -e ps2EntryRunner.exe takes, the last 200 log lines) and a message box points at it and at the log: what a player attaches to a bug report. PS2X_TEST_CRASH=<s> crashes on purpose after s seconds to try it; PS2X_NO_DIALOGS=1 keeps message boxes out of unattended runs (the log has their text).

Player 1 plays with the keyboard and the first controller, player 2 with the second controller. The default keys (US key positions):

The Cheats tab of the settings window (F2) switches them while playing, each at once, in a match (one player or split screen); the variables give their state at launch (runtime/tmb_cheats.cpp).

<players>: digits 1 to 4 (12: players 1 and 2), any other value but 0 every player.

Everything derived from the game (game_us/, game/, generated_us/, generated/, build/, disc images, captures) is git-ignored. Never commit or redistribute it.

• The Bozos: boubou666 and Arzaroth, who make this port and the PS2Recomp fork it runs on (RecompWatcher shows our projects).
• PS2Recomp by ran-j and contributors (GPL-3.0), the recompiler and runtime this port is built on.
• The other recompilations on the same fork (Valkyrie Profile 2: Silmeria, Dark Cloud, Soulcalibur III, Drakengard, The Lord of the Rings: The Third Age, Jade Cocoon 2 and others): runtime fixes are shared, and DC_Recomp's native sound mixer plays TMB's sound.
• Twisted Metal: Black © Sony Interactive Entertainment, developed by Incognito Entertainment. This is an unofficial fan project, not affiliated with or endorsed by them.