Metadata-Version: 2.5
Name: prrevers
Version: 1.4.0
Summary: AI-assisted reverse engineering toolkit for game developers — Windows & Android.
Project-URL: Homepage, https://github.com/Pradushkoai/PRRevers
Project-URL: Repository, https://github.com/Pradushkoai/PRRevers
Project-URL: Issues, https://github.com/Pradushkoai/PRRevers/issues
Project-URL: Changelog, https://github.com/Pradushkoai/PRRevers/releases
Author: Pradushkoai
License: MIT License
        
        Copyright (c) 2026 Pradushkoai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: android,decompilation,games,godot,llm,mcp,reverse-engineering,unity,unreal,windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Disassemblers
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: assets
Requires-Dist: unitypy>=1.20; extra == 'assets'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff~=0.6.9; extra == 'dev'
Requires-Dist: types-click; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: frida
Requires-Dist: frida>=16.0.0; extra == 'frida'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Description-Content-Type: text/markdown

# PRRevers

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

[![CI](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml/badge.svg)](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)

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

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

> **English version:** [README.en.md](README.en.md)

---

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

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

| Команда | Что делает | Когда использовать |
|---|---|---|
| `prrevers inspect <file>` | Разовый прогон: детект движка → экстракция → декомпиляция → анализ → дизайн-док | Быстрый обзор одной игры |
| `prrevers session <file>` | Интерактивный REPL: детект + экстракция один раз, дальше задаёте вопросы | Глубокое изучение игры |
| `prrevers compare <a> <b>` | Side-by-side сравнение двух игр: таблица механик, diff дизайн-доков, отчёт `compare/<a>-vs-<b>.md` | Выбор между стратегиями реализации |
| `prrevers trace <file>` | Динамика: аттач к запущенной игре (Frida), хуки из статики, трейс → дизайн-док | Наблюдение механик в рантайме |
| `prrevers mcp serve` | MCP-сервер: инструменты PRRevers для Claude Code / Cursor | LLM-агент вместо CLI |
| `prrevers catalog <dir>` | Batch-детект движка для каждого файла в директории, таблица | Кураторская библиотека референсов |

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

Полное описание — в [docs/architecture.ru.md § Режимы работы](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](docs/architecture.ru.md).

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

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

```bash
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/cases/web-gold-rush.md)). См. [docs/ROADMAP.ru.md](docs/ROADMAP.ru.md) и [CHANGELOG.md](CHANGELOG.md).

## Установка

```bash
# из 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](docs/external-tools.ru.md); `prrevers tools install <name>` ставит их в user data dir автоматически):

| Тулз | Назначение | Требуется для |
| --- | --- | --- |
| `ILSpy` (ilspycmd) | Декомпиляция .NET / Unity Mono в C# | Unity Mono-игры (`prrevers tools install ilspy`) |
| `apktool` | Распаковка APK | Android-игры (смелали/ресурсы) |
| `Il2CppDumper` | Дамп метадаты Unity IL2CPP | Unity IL2CPP-игры |
| `AssetRipper` | Экспорт Unity-ассетов | Unity-ассеты |
| `Ghidra` (headless) | Анализ нативного кода | Кастомные движки / IL2CPP |
| `jadx` | DEX → Java | не-Unity Android-игры |

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

```bash
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](CONTRIBUTING.md). Участвуя, вы соглашаетесь следовать [Code of Conduct](CODE_OF_CONDUCT.md).

## Лицензия

[MIT](LICENSE) © Pradushkoai
