Metadata-Version: 2.4
Name: ps5dbg-scanner
Version: 0.2.1
Summary: Cross-platform 'Cheat Engine for PS5' GUI built on the ps5dbg library.
Author: Darkatek7
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/Darkatek7/ps5dbg-scanner
Project-URL: Repository, https://github.com/Darkatek7/ps5dbg-scanner
Project-URL: Issues, https://github.com/Darkatek7/ps5dbg-scanner/issues
Keywords: ps5,playstation5,ps5debug,memory scanner,cheat engine,homebrew,jailbreak
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
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 :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ps5dbg>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ps5dbg[dev]>=0.1.1; extra == "dev"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Dynamic: license-file

# ps5dbg-scanner

> A cross-platform **"Cheat Engine for PS5"** built on the [`ps5dbg`](https://github.com/Darkatek7/ps5dbg) library. Scan a game's memory, narrow down to the values you care about, then freeze or edit them — from any OS, no Windows required.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE)
[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#roadmap)

`ps5dbg-scanner` is a desktop GUI for the classic memory-editor loop:

1. **Pick the foreground app** (or any process) on your jailbroken PS5.
2. **First scan** — find all addresses holding a value (e.g. your current gold = 1000).
3. **Next scan** — change the value in-game, then narrow the survivor list (now it's 1050 → only addresses that went from 1000 → 1050).
4. Repeat until you have a handful of candidates, then **freeze** or **edit** the value.

It uses ps5debug-NG's **server-resident turbo scan**, so survivors live on the PS5 and narrow scans are fast even when the first scan returns hundreds of thousands of hits.

Runs anywhere Python 3.10+ runs (Linux, macOS, Windows) with **no extra runtime dependencies** beyond `ps5dbg` (tkinter ships with Python).

---

## Why it exists

Every existing PS5 memory scanner is **Windows-only** (`PS_Trainer_Viewer`, the PS4-era `PS4CheaterNeo`). Mac and Linux users have nothing. `ps5dbg-scanner` is the cross-platform answer — built on the [`ps5dbg`](https://pypi.org/project/ps5dbg/) library, which implements the full ps5debug-NG wire protocol.

---

## Install

```bash
pip install ps5dbg-scanner
# or
pipx install ps5dbg-scanner

# then run
export PS5_HOST=192.168.1.10       # your PS5's LAN IP
ps5dbg-scanner
```

Requires a PS5 running [ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG) reachable on your LAN.

---

## Quick start

1. Launch the app: `ps5dbg-scanner`
2. Enter your PS5's IP, click **Connect**.
3. Pick the target from the dropdown (the foreground app is marked `▶`).
4. Choose a **value type** (u32 is the common case for game state) and **scan type**.
5. Enter the current value, click **First Scan**.
6. Change the value in-game, enter the new value, click **Next Scan**.
7. Repeat until the survivor count is small.
8. Right-click a row → **Freeze** (lock it) or **Edit value**.

---

## Features

- **Value scan** across u8/u16/u32/u64, i8/i16/i32/i64, float, double.
- **Scan types**: exact, bigger/smaller, increased/decreased, changed/unchanged, unknown-initial-value.
- **Server-resident narrow loop** — survivors stay on the PS5; no re-upload per scan.
- **Virtualized results table** — scrolls smoothly through millions of hits.
- **Freeze** values at a fixed number (the classic "infinite health" — re-written 10×/sec).
- **Edit** any survivor's value directly.
- **Foreground-app detection** — pick the running game with one click.

---

## How it works

```
┌─────────────────────────────────────────────┐
│  tkinter GUI (UI thread only)               │
│    Connection panel   Scan panel   Results  │
└──────────────────┬──────────────────────────┘
                   │ worker threads (blocking I/O off the UI thread)
                   ▼
            ┌─────────────────┐
            │  ps5dbg library │  ← PyPI: pip install ps5dbg
            └────────┬────────┘
                     │ TCP wire protocol (port 744)
                     ▼
            ┌─────────────────┐
            │  PS5 (jailed)   │
            │  ps5debug-NG    │
            └─────────────────┘
```

All blocking network calls run off the UI thread; results are marshaled back via `root.after`. The scan engine uses the turbo-resident path so narrow scans stay fast at scale.

---

## Requirements

- **Python** 3.10+ (tkinter ships with standard CPython).
- **ps5dbg** ≥ 0.1.0 (auto-installed as a dependency).
- **Console** any PS5 running ps5debug-NG with the turbo-scan family advertised.

---

## Roadmap

- **v0.2** — core scanner: value scan → narrow → freeze/edit (this release, alpha)
- **v0.3** — hex viewer pane, AOB pattern scanner, bookmark/address-list manager
- **v0.4** — debugger UI (breakpoints/registers) on top of ps5dbg's `DebugSession`

Contributions welcome — see [`AGENTS.md`](./AGENTS.md) for architecture and conventions.

---

## Acknowledgments

- **[ps5dbg](https://github.com/Darkatek7/ps5dbg)** — the library this is built on.
- **[OpenSourcereR-dev/ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG)** — the debugger payload and wire protocol.
- **[etaHEN](https://github.com/etaHEN/etaHEN)** — the HEN chain that loads it.

## License

[GPL-3.0-only](./LICENSE) — matching ps5dbg and ps5debug-NG.
