Twisted Metal Re-Arc Project

This repository is a Re-Arc (Reverse Engineering, Archaeology, and Reconstruction of Code) project for the 1995 Playstation game Twisted Metal (NTSC-J) (SIPS-60007). It uses matching decompilation techniques to ensure that the reconstructed source produces exactly identical machine code and behavior versus the original.

- WARNING! -

This repository is a work in progress, and while it can be used to make certain changes, it's
still constantly evolving. If you wish to use it for modding purposes in its current state,
please be aware that the codebase could drastically change at any time.

- WARNING! -

The project maintainer sincerely requests that others do not attempt to port this
repository's code to other platforms until the project nears completion.

Upon the project's completion, if a source port to other platforms is desired, a
unified, non-profit effort to create an open-source engine replacement should be
started to avoid any community fragmentation.

This is especially important because the original developer of this software
(SingleTrac) reused a great deal of code for most of their games (TM2, Jet Moto 1/2).

Rushing to create a port or fork before the repo is finished/documented
will result in a subpar product that will ultimately damage and fragment
the community.

AI Policy

Before using agentic LLMs or AI on this codebase, please see AI_POLICY.md for our repository's standards and requirements.

Contributing

If you'd like to contribute to the project, please join us in the #twisted-metal-psx channel on the PS1/PS2 Re-Arc Discord server. Communication is key.

Requirements

Linux/WSL

This repository currently assumes that the user is running a Debian/Ubuntu-based Linux distribution. If you are a Windows user, you should use Windows Subsystem for Linux with Ubuntu.

Note: It is highly recommended to add yourself to the kvm usergroup. This allows daze, our DOS emulator for the PsyQ compiler, to be more reliable and run at much higher speeds. If you do not do this, daze will fall back to the unicorn backend, which is much slower and prone to crashes when compiling large TUs.

System Packages

This repository requires several system packages which can be found in the tools/requirements-debian.txt file. To install all required system packages, run the following command from the root of the repository:

sudo apt update
sudo apt install -y $(cat ./tools/requirements-debian.txt)

Python Packages

This repository uses uv for Python package and virtual environment management.

After installing uv, you can install all required packages with uv sync in the root of the repository.

Building

- NOTE! -

This repository does not attempt to produce a byte-matching PSX-EXE binary
or `.SYM` file.

Our priority is to match the code and data to produce a shiftable result
that can be freely modified by downstream users.

We match our code/data against a "ROM" generated by removing the PSX-EXE
header from the rest of the original code/data. This greatly simplifies
the process of matching, as we don't need to worry about proprietary
PSY-Q formats.

To build the repository, you will need a digital copy of the Playstation game Twisted Metal (NTSC-J) (SIPS-60007). Note that this is the retail Japanese version of the game.

1. Setup your environment as defined by the Requirements section.
2. Extract the executable binary ELF file SIPS_600.07 from the Playstation disc.

• In the future, this repository will be able to perform this extraction for you. Currently, however, you will need to somehow extract this yourself.

3. Place the SIPS_600.07 file into the disks/ directory of the repository.
4. Run uv run configure.py generate at the root of the repository.

• This will split the binary into parts and generate a build.ninja file in the root of the repository.

5. Run ninja at the root of the repository to build the repo.

• On success, you should see build/SIPS_600.07.rom: OK in the logs, and an objdiff report should be successfully generated.

6. Whenever you modify the splat config, you should perform a uv run configure.py distclean before regenerating the config with uv run configure.py generate.

Known Issues / Compiler Quirks

For a list of known compiler issues / quirks to reference during the decompilation process, check QUIRKS.md.

License

This project is licensed under MIT, with the intent that the community will band together to pool their efforts for matching (and eventual porting, if desired).

See LICENSE.md for more details.

Disclaimers / Legality

This project may fall under a legal grey zone of copyright law in some locations.

This project does not and will never reference or incorporate any leaked Sony implementation source code, and contributions which do so will not be accepted. The authors of this project make no claim of copyright on any Sony proprietary APIs or structures.

This project exists primarily for educational and research purposes. The authors of this project have no desire to use this project for monetary gain.

This project contains code generated with the assistance of agentic LLMs (AI).

Acknowledgements

This project is critically reliant on tools from dedicated members of the console reversing community. Without them, this work would be impossible. Special thanks go to the teams and individuals behind:

• decomp.wiki
• decomp.me
• decomp.dev
• splat
• spimdisasm
• objdiff and asm-differ
• m2c
• daze
• All of the helpful and skilled decompers in various decomp communities and Discords; PS1/PS2, GC/Wii, N64, and decomp.me servers.

Also, SingleTrac/Incognito, for developing Twisted Metal, Jet Moto, and all of the other great games they put out during the 90s and 2000s. This project's goal is to preserve that legacy for future generations and allow others to experience what we did.