PS2Recomp README

README проекта с github.com/ran-j/PS2Recomp. Одним файлом markdown: README.md.

PS2Recomp: PlayStation 2 Static Recompiler (Experimental)

Discord

Also check our WIKI

This project statically recompiles PS2 ELF binaries into C++ and provides a runtime to execute the generated code.

Modules

Features

How It Works

PS2Recomp works by:

The translated code is very literal, with each MIPS instruction mapping to a C++ operation. For example, addiu $r4, $r4, 0x20 becomes ctx->r4 = ADD32(ctx->r4, 0X20);.

Current Behavior

Requirements

Build

git clone --recurse-submodules https://github.com/ran-j/PS2Recomp.git
cd PS2Recomp

cmake -S . -B out/build
cmake --build out/build --config Debug

Usage

Preferred workflow for retail or stripped games:

  1. Open the ELF in Ghidra.
  2. Run ps2xRecomp/tools/ghidra/ExportPS2Functions.java.
  3. Use the exported TOML and CSV map.
  4. Recompile with the exported TOML:
./ps2_recomp config.toml

Fallback workflow for quick local experiments or ELFs with debug symbol :

./ps2_analyzer your_game.elf config.toml

See the Ghidra Workflow for ghdira instructions.

Then build generated output and link with ps2xRuntime.

Configuration

Main fields in config.toml:

Address binding for stripped ELFs:

Example:

# stripped function binding by address:
stubs = ["sceCdRead@0x00123456", "SifLoadModule@0x00127890"]
# temporary return handlers:
stubs = ["ret0@0x001D9410", "ret1@0x001D5BC8", "reta0@0x0024B7C0"]
# mixed example:
stubs = ["printf", "sceCdRead@0x00123456", "SifLoadModule@0x00127890"] 

Runtime

To execute the recompiled code.

ps2xRuntime currently provides:

See IOP emulation for module execution and the service boundary.

Game Override Hooks

Game overrides are runtime-side, build-scoped patch modules.

A game override is C++ code that runs during loadELF and can replace EE function bindings by address for one specific game build. IOP RPC/DMA behavior is handled by the ps2xIOP emulator and its runtime transport. This is separate from recompilation output and separate from global runtime stubs/syscalls.

API:

Use Game Override modules when:

  1. Run with minimal config and no aggressive skipping.
  2. Fix hard blockers first (function not found, syscall TODO, critical IO stubs).
  3. Use temporary return stubs only to classify call importance.
  4. Promote temporary fixes to real implementations.
  5. Move per-game hacks into game overrides keyed by ELF metadata.
  6. Re-test from cold boot after each batch.

Describing Your Game Project

A game project built with PS2Recomp can describe itself in a .recomp.json file at the root of its repository. Lists of recomp and decomp projects, such as recomp.board, read that file instead of guessing the game, system and status from the README.

[!NOTE] This file is optional: PS2Recomp does not read it and works the same without it. .recomp.json and recomp.board are third-party projects; the PS2Recomp developers have no ties to them.

Starter file:

{
  "$schema": "https://recomp.fyi/schema/v1.json",
  "game": "<title as it shipped>",
  "system": "PS2",
  "type": "recomp",
  "toolchain": "PS2Recomp",
  "status": "in-progress",
  "original": { "region": "USA", "serial": "SLUS-20312" }
}

Other fields (Wikidata item, target platforms, maintainers, links, what help is wanted) and the JSON Schema are in the specification.

Limitations

Acknowledgments

PS2Recomp (ran-j/PS2Recomp)

Ищем в базе…

Что это?PS2Recomp статически перекомпилирует ELF-файлы PlayStation 2 в исходный код на C++ и поставляет среду выполнения, которая запускает сгенерированный код. Так можно собрать нативные порты игр PS2 для ПК.
Это эмулятор или набор инструментов для компиляции?Это набор инструментов, а не эмулятор вроде PCSX2: ps2xRecomp переводит инструкции MIPS R5900 в буквальный код на C++, ps2xRuntime выполняет этот сгенерированный код на реальном железе, а ps2xIOP запускает оригинальные модули IOP с запасными HLE-реализациями.
Как мне превратить ELF-файл игры PS2 в C++ с помощью этого инструмента?Для коммерческих игр или игр без отладочных символов откройте ELF в Ghidra, запустите входящий скрипт ExportPS2Functions.java, чтобы получить карту функций в формате TOML/CSV, затем перекомпилируйте игру, используя экспортированный TOML, и слинкуйте сгенерированный результат с ps2xRuntime.
Что нужно установить перед сборкой?Нужны CMake 3.20 или новее, компилятор с поддержкой C++20 (пока тестировался в основном с MSVC) и процессор с поддержкой SSE4/AVX для некоторых путей трансляции векторных инструкций. Для коммерческих игр также понадобится Ghidra.
Работает ли сгенерированный код на полной скорости?Нет, производительность сейчас очень низкая для путей выполнения кода VU и GS, а аппаратная эмуляция реализована лишь частично: многие функции пока остаются заглушками, которые нужно реализовать отдельно для каждой игры.
На какой ОС это собирается и работает?Сборка основана на CMake и пока тестировалась в основном на Windows с MSVC. Поддержка других компиляторов и платформ не подтверждена.
В чём разница между записью stub и записью skip в конфигурации?Записи stub генерируют вызовы-обёртки к известным обработчикам системных вызовов и заглушек среды выполнения, включая привязки к адресам вида sceCdRead@0xADDRESS для игр без символов. Записи skip не перекомпилируются и выводят только явные обёртки-вызовы с пометкой TODO.
Для чего нужны Game Override hooks?Это модули на C++, привязанные к конкретной сборке. Они выполняются во время loadELF и позволяют заменить определённые привязки функций EE по адресу для одной точной сборки игры. Так хаки под конкретный проект отделены от общих заглушек и системных вызовов среды выполнения.
Зачем использовать это вместо простого запуска игры в PCSX2?PS2Recomp стремится создать нативный автономный порт для ПК, преобразуя MIPS-код игры в скомпилированный C++ (по духу похоже на N64Recomp). Он не эмулирует исходные инструкции PS2 во время работы, как это делает PCSX2. PCSX2 используется лишь как эталон для поведения среды выполнения.
Для чего нужен файл .recomp.json?Это необязательный файл метаданных, который портированный проект игры может включать, чтобы описать её оригинальный релиз, серийный номер, регион и статус порта. PS2Recomp сам этот файл никогда не читает, но сторонние каталоги, например recomp.board, используют его вместо догадок о деталях проекта.
Какие есть похожие проекты?re4, console-skill, wowdecomp, EQAI, Atmosphere, Fable-2-Recomp, awesome-decomp-games, ATBGamePort
Автор
ran-j
Размер
5.6 MB
Звёзды
3.9K
Обновлён
КоммитOct 23
Возраст
1 г
Коммиты · 90 дней