PRRevers

AI-ассистированный тулз для гейм-девов: извлекает механики, ассеты и форматы данных из Windows и Android игр, чтобы учиться у них и вдохновляться на собственные проекты.

PRRevers — не декомпилятор, не дизассемблер и не замена тулзам вроде Ghidra, IDA, AssetRipper или Il2CppDumper. Это оркестратор: он связывает эти тулзы вместе, определяет движок, извлекает код/ассеты/данные и использует LLM-агента, чтобы объяснить механики и сгенерировать дизайн-доки, пригодные для использования в вашей собственной игре.

Этика и легальность. PRRevers предназначен исключительно для исследований и обучения. Анализируйте только те игры, которыми вы законно владеете или на которые у вас есть явное разрешение на реверс-инжиниринг. Не распространяйте извлечённый код или ассеты. Прочитайте docs/ETHICS.ru.md перед использованием.

English version: README.en.md

Режимы работы

PRRevers предоставляет шесть CLI-режимов, каждый как отдельная подкоманду:

Утилиты: prrevers tools install/list (установка внешних тулзов в user data dir и статус), prrevers version.

Полное описание — в docs/architecture.ru.md § Режимы работы.

Зачем это нужно?

Реверс-инжиниринг игры, чтобы у неё поучиться — это мультитулзовая, многодневная рутина:

1. Определить движок (Unity Mono / IL2CPP / Unreal / Godot / кастомный).
2. Распаковать контейнер (APK / PAK / PCK / OBB).
3. Запустить правильный экстрактор под правильный формат.
4. Открыть результат в Ghidra / dnSpy / UModel.
5. Смотреть на тысячи классов и функций, чтобы найти одну механику, которая вас интересует.

PRRevers автоматизирует шаги 1–3 и добавляет LLM-агента поверх 4–5, который может отвечать на вопросы вроде «как работает инвентарь в этой игре?» и генерировать дизайн-док.

Архитектура

Пайплайн состоит из 4 этапов плюс слой оракулов, который независимо проверяет каждый этап:

[файл] → Детекторы → Экстракторы → Анализаторы (LLM) → Синтезаторы → [ваш проект]
                                            ↑
                                       Оракулы (проверяют каждый этап)

Ключевые архитектурные решения:

• Плагин-система движков через протокол EngineAdapter + entry_points. Добавить новый движок теперь можно без правки ядра.
• Типизированная модель Citation вместо list[str] в evidence — верифицируется CitationOracle.
• Протокол LLMBackend — любой класс, реализующий протокол, можно подключить.
• Content-addressed кэш — повторный запуск на том же входе почти мгновенный.
• Сессии — интерактивный REPL с сохраняемой историей Q&A.
• Stage-level оракулы — DetectionOracle (согласованность вердикта), ExtractionOracle (заявленные файлы против реальной ФС) и RoundTripOracle (побайтовая сверка с оригинальным архивом + SHA256-integrity) проверяют этапы сразу после выполнения.
• Pure-Python экстракторы — stdlib zipfile/shutil/json+struct покрывают ZIP-контейнеры, Unity-layout и Electron app.asar без установки apktool; первая обёртка над внешним тулзом — ILSpy (prrevers tools install ilspy) — превращает Mono-сборки в читаемый C#.

Полное обоснование архитектуры: docs/architecture.ru.md.

Документация

Документационный сайт (mkdocs-material): архитектура, роадмап, внешние тулзы, этика, кейсы — с навигацией и поиском.

uv sync --extra docs   # или: pip install -e ".[docs]"
mkdocs serve           # localhost:8000
mkdocs build --strict  # проверка: битые ссылки ломают сборку (и CI)

CI собирает сайт в strict-режиме на каждый push.

Статус

main — закрыты v0.1.0 (Unity Mono + web-игры end-to-end), v0.2.0 (IL2CPP: Il2CppDumper + Ghidra headless), v0.3.0 (LLM-анализатор: Ollama / OpenAI / Anthropic / GigaChat / LiteLLM, цитаты file:line), v0.4.0 (REPL-сессии + MCP-сервер), v0.5.0 (Unity-ассеты: AssetRipper → UnityPy fallback + манифест + AssetRoundTripOracle), v0.6.0 (синтез для game-dev: clean-room скелеты Unity C# / Godot GDScript + переводчик шейдеров HLSL→GLSL→AGSL + импортёр уровней (схема v1 → .tscn / C#, LevelRoundTripOracle)), v0.7.0 (Unreal и нативные движки: UnrealPakExtractor + UModelExtractor + GhidraNativeExtractor для кастомных C++ движков + фингерпринтинг кастомных движков — Ren'Py/Cocos2d-x/MonoGame/LÖVE/RGSS/Clickteam → нативная Ghidra-дорога), v0.8.0 (динамический анализ: prrevers trace — аттач к живому процессу через Frida (опциональный extras [frida]), хуки по адресам из собственной статики (дамп Il2CppDumper / Ghidra-манифест), подсистемы inventory/combat/save_load, JSONL-трейс + TraceOracle + trace-to-doc дизайн-док из событий [ts Метод]; без живой игры — честный отказ, трейсы не выдумываются). Экстракция без внешних тулзов: ZIP-контейнеры (APK / OBB / raw ZIP), Windows-установки Unity (Mono / IL2CPP layout), Electron app.asar; декомпиляция Assembly-CSharp.dll → C# через ILSpy (prrevers tools install ilspy; без тулза — честный warning, не тихая деградация); распаковка Unreal .pak — тулзом из установки движка ($UNREAL_PAK), экспорт ассетов — UModel (gildor.org, вручную). Детекция движков реальная (Unity Mono/IL2CPP, Unreal, Godot, GameMaker, Web — Cordova/Capacitor/Electron, известные кастомные — фингерпринтингом строковых маркеров). Анализ — реален при подключённом LLM-бэкенде; синтез — дизайн-доки + clean-room скелеты под целевой движок (Unity C# / Godot GDScript, --target-engine) + переводы шейдеров + импорт уровней, v0.9.0 (compare mode: две игры через один пайплайн — сравнительная таблица механик, diff дизайн-доков по секциям, ComparisonOracle), v1.0.0 (стабильный API: заморожены top-level экспорты, CLI-команды и имена MCP-инструментов; цикл депрекации; PyPI-релиз-инженерия — pip install prrevers после проставленного владельцем тега; документационный сайт mkdocs; первый опубликованный end-to-end кейс «Gold Rush» — своя Electron-игра, docs/cases/web-gold-rush.md). См. docs/ROADMAP.ru.md и CHANGELOG.md.

Установка

# из PyPI (начиная с v1.0.0)
pip install prrevers

# опциональные возможности — extras (см. ниже)
pip install "prrevers[mcp]"   # MCP-сервер для Claude Code / Cursor
pip install "prrevers[assets]" # pure-Python fallback Unity-ассетов
pip install "prrevers[frida]" # динамический анализ (живой процесс игры)

# из репозитория (разработка)
git clone https://github.com/Pradushkoai/PRRevers.git
cd PRRevers
pip install -e ".[dev]"
pre-commit install

# опционально: pure-Python fallback экстракции Unity-ассетов
# (AssetRipper остаётся внешним тулзом — см. таблицу ниже)
pip install -e ".[assets]"

# опционально: динамический анализ (v0.8.0) — аттач к живой игре
# через Frida: локально Windows/macOS/Linux или Android по USB
pip install -e ".[frida]"

Внешние тулзы, которые оркестрирует PRRevers (см. docs/external-tools.ru.md; prrevers tools install <name> ставит их в user data dir автоматически):

Быстрый старт

prrevers inspect path/to/game.apk
prrevers inspect path/to/game.exe --engine auto
prrevers session path/to/game.apk --name mygame
prrevers catalog /path/to/games/folder

# опционально: C# из Assembly-CSharp.dll (нужен .NET SDK)
prrevers tools install ilspy

# динамический анализ (v0.8.0): игра должна быть ЗАПУЩЕНА
pip install -e ".[frida]"
prrevers trace path/to/game.apk --list-processes   # найти pid/name игры
prrevers trace path/to/game.apk --pid 4242 --duration 120 \
    --subsystem inventory --subsystem combat
# → трейс prrevers-out/traces/*.jsonl + дизайн-док
# prrevers-out/synthesized/*-trace.md (с LLM — анализ механик по событиям,
# без LLM — честный stub из таблицы частот)

Контрибьюшн

Контрибьюшны приветствуются. Сначала прочитайте CONTRIBUTING.md. Участвуя, вы соглашаетесь следовать Code of Conduct.

Лицензия

MIT © Pradushkoai