ps5dbg-scanner 0.2.0__py3-none-any.whl

ps5dbg_scanner/__init__.py

@@ -0,0 +1,11 @@
+"""ps5dbg-scanner — cross-platform 'Cheat Engine for PS5' GUI built on ps5dbg.
+
+Run with ``ps5dbg-scanner`` (entry point) or ``python -m ps5dbg_scanner``.
+
+    from ps5dbg_scanner.app import main
+    main()
+"""
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__all__ = ["__version__"]

ps5dbg_scanner/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m ps5dbg_scanner``."""
+from __future__ import annotations
+
+import sys
+
+from .app import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ps5dbg_scanner/app.py

@@ -0,0 +1,362 @@
+"""ScannerApp — the tkinter root + threading-safe worker dispatch.
+
+Owns:
+  - the Tk root window and all panels
+  - the live ps5dbg.PS5Debug client (None until connected)
+  - a worker-thread pool: blocking ps5dbg calls run off the UI thread and post
+    results back via ``root.after(0, callback)`` (the only tkinter-safe path)
+  - the current scan session state (turbo resident handle, survivor count,
+    value type/length for the active session)
+
+UI thread never blocks on network I/O.
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+import tkinter as tk
+from tkinter import messagebox, ttk
+from typing import Callable, Optional
+
+from ps5dbg import PS5Debug
+from ps5dbg import turboscan as ts
+from ps5dbg.constants import ScanCompareType, ScanValueType
+
+from .freeze_manager import FreezeManager
+from .results_table import ResultsTable
+from .scan_panel import ScanPanel
+from .connection_panel import ConnectionPanel
+
+# value type -> (ps5dbg ScanValueType, fixed byte width). Bytes/string excluded
+# from the core v0.2 value scan (they use the AOB pane in v0.3).
+_VALUE_TYPES: dict[str, tuple[ScanValueType, int]] = {
+    "u8":  (ScanValueType.UINT8, 1),
+    "u16": (ScanValueType.UINT16, 2),
+    "u32": (ScanValueType.UINT32, 4),
+    "u64": (ScanValueType.UINT64, 8),
+    "i8":  (ScanValueType.INT8, 1),
+    "i16": (ScanValueType.INT16, 2),
+    "i32": (ScanValueType.INT32, 4),
+    "i64": (ScanValueType.INT64, 8),
+    "f32": (ScanValueType.FLOAT, 4),
+    "f64": (ScanValueType.DOUBLE, 8),
+}
+
+# scan type -> (ps5dbg ScanCompareType, needs_value)
+_SCAN_TYPES: dict[str, tuple[ScanCompareType, bool]] = {
+    "Exact value":            (ScanCompareType.EXACT_VALUE, True),
+    "Bigger than":            (ScanCompareType.BIGGER_THAN, True),
+    "Smaller than":           (ScanCompareType.SMALLER_THAN, True),
+    "Increased value":        (ScanCompareType.INCREASED_VALUE, False),
+    "Decreased value":        (ScanCompareType.DECREASED_VALUE, False),
+    "Changed value":          (ScanCompareType.CHANGED_VALUE, False),
+    "Unchanged value":        (ScanCompareType.UNCHANGED_VALUE, False),
+    "Unknown initial value":  (ScanCompareType.UNKNOWN_INITIAL_VALUE, False),
+}
+
+
+class ScannerApp:
+    """The scanner application. Construct, then call run()."""
+
+    def __init__(self) -> None:
+        self.root = tk.Tk()
+        self.root.title("ps5dbg-scanner — PS5 memory scanner")
+        self.root.geometry("900x600")
+        self._client: Optional[PS5Debug] = None
+        self._pid: Optional[int] = None
+
+        # scan session state
+        self._session_active = False
+        self._survivor_count = 0
+        self._value_type_name = "u32"
+        self._value_length = 4
+
+        # freeze manager (started after connect)
+        self._freeze: Optional[FreezeManager] = None
+
+        # status bar
+        self._status = tk.StringVar(value="disconnected")
+
+        # build UI
+        self._conn = ConnectionPanel(self.root, self)
+        self._scan = ScanPanel(self.root, self,
+                               value_types=list(_VALUE_TYPES),
+                               scan_types=list(_SCAN_TYPES))
+        self._table = ResultsTable(self.root, self)
+
+        self._layout()
+        self.root.protocol("WM_DELETE_WINDOW", self._on_close)
+
+    # -- layout --------------------------------------------------------------
+
+    def _layout(self) -> None:
+        self.root.grid_rowconfigure(2, weight=1)
+        self.root.grid_columnconfigure(0, weight=1)
+        self._conn.frame.grid(row=0, column=0, sticky="ew", padx=8, pady=(8, 4))
+        self._scan.frame.grid(row=1, column=0, sticky="ew", padx=8, pady=4)
+        self._table.frame.grid(row=2, column=0, sticky="nsew", padx=8, pady=4)
+        ttk.Label(self.root, textvariable=self._status,
+                  relief="sunken", anchor="w").grid(
+            row=3, column=0, sticky="ew", padx=8, pady=(0, 4))
+
+    # -- threading-safe worker dispatch -------------------------------------
+
+    def run_async(
+        self,
+        work: Callable[[], object],
+        on_done: Optional[Callable[[object], None]] = None,
+        on_error: Optional[Callable[[BaseException], None]] = None,
+    ) -> threading.Thread:
+        """Run ``work`` on a worker thread; marshal result back to the UI thread.
+
+        on_done/on_error run on the UI thread via root.after(0, ...).
+        """
+        def runner() -> None:
+            try:
+                result = work()
+            except BaseException as e:  # noqa: BLE001
+                if on_error:
+                    self.root.after(0, lambda: on_error(e))
+                else:
+                    self.root.after(0, lambda: self._fail(e))
+                return
+            if on_done:
+                self.root.after(0, lambda: on_done(result))
+
+        t = threading.Thread(target=runner, daemon=True)
+        t.start()
+        return t
+
+    # -- status / errors (UI thread) ----------------------------------------
+
+    def set_status(self, text: str) -> None:
+        self._status.set(text)
+
+    def _fail(self, e: BaseException) -> None:
+        self.set_status(f"error: {e}")
+        messagebox.showerror("ps5dbg-scanner", str(e))
+
+    # -- connection (called by ConnectionPanel) -----------------------------
+
+    def connect(self, host: str, port: int) -> None:
+        def work() -> str:
+            c = PS5Debug(host=host, port=port, timeout=10.0)
+            c.connect()
+            self._client = c
+            ver = c.version()
+            fw = c.fw_version()
+            # start the freeze supervisor against this client
+            self._freeze = FreezeManager(
+                writer=lambda a, d: c.write(self._pid or 0, a, d),
+                rate_hz=10.0,
+                on_error=lambda slot, exc: self.root.after(
+                    0, lambda: self.set_status(f"freeze failed @ {slot.address:#x}: {exc}")),
+            )
+            self._freeze.start()
+            return f"{ver} (FW {fw // 100}.{fw % 100:02d})"
+
+        self.run_async(
+            work,
+            on_done=lambda label: (
+                self.set_status(f"connected: ps5debug-NG {label}"),
+                self._conn.on_connected(),
+                self._refresh_targets(),
+            ),
+            on_error=lambda e: self._fail(e),
+        )
+
+    @property
+    def client(self) -> Optional[PS5Debug]:
+        return self._client
+
+    @property
+    def pid(self) -> Optional[int]:
+        return self._pid
+
+    @pid.setter
+    def pid(self, value: Optional[int]) -> None:
+        self._pid = value
+        if self._freeze and self._client:
+            # update the freeze writer's target pid
+            self._freeze._writer = lambda a, d: self._client.write(value or 0, a, d)  # type: ignore[union-attr]
+        self.set_status(f"target pid = {value}")
+
+    def _refresh_targets(self) -> None:
+        def work():
+            assert self._client is not None
+            fg = self._client.foreground_app()
+            procs = self._client.procs()
+            return fg, procs
+        self.run_async(work, on_done=lambda r: self._conn.populate_targets(*r))
+
+    # -- scanning (called by ScanPanel) -------------------------------------
+
+    @property
+    def value_type_name(self) -> str:
+        return self._value_type_name
+
+    def first_scan(self, value_type_name: str, scan_type_name: str, value_text: str) -> None:
+        if self._client is None or self._pid is None:
+            self._fail(RuntimeError("not connected / no target"))
+            return
+        vt, width = _VALUE_TYPES[value_type_name]
+        ct, needs_value = _SCAN_TYPES[scan_type_name]
+        # validate/encode in the UI thread so a bad value surfaces cleanly
+        # instead of crashing the Tk callback
+        try:
+            value = self._encode_value(value_type_name, value_text) if needs_value else 0
+        except ValueError as e:
+            self._fail(e)
+            return
+        self._value_type_name = value_type_name
+        self._value_length = width
+        self.set_status("first scan…")
+
+        def work():
+            assert self._client is not None
+            self._client.authenticate(flags=2)
+            # default to scanning the whole address space: pass pid's low page
+            # up; the resident scan wants a contiguous range. For v0.2 we scan
+            # each writable region and let the server keep one resident set.
+            # Simpler: scan the first RW region (where game state usually lives).
+            # (A multi-region variant is a v0.3 refinement.)
+            maps = self._client.maps(self._pid)
+            rw = [m for m in maps if "w" in m.perms and "x" not in m.perms]
+            if not rw:
+                raise RuntimeError("no writable data region found in target")
+            # pick the largest RW region — usually the main heap
+            region = max(rw, key=lambda m: m.end - m.start)
+            stored, count = ts.turboscan_start_resident(
+                self._client.connection, self._pid,
+                region.start, region.end - region.start,
+                vt, ct, width, value, ts.TS_SERVER_RESIDENT,
+            )
+            if not stored:
+                raise RuntimeError("server declined resident scan (too many hits?)")
+            self._session_active = True
+            self._survivor_count = count
+            self._table.set_session(vt, width, count)
+            return count
+
+        def on_done(count: int) -> None:
+            self.set_status(f"first scan: {count} survivors")
+            self._scan.on_scan_done(count)
+            self._table.refresh_window()
+
+        self.run_async(work, on_done=on_done, on_error=lambda e: self._fail(e))
+
+    def next_scan(self, scan_type_name: str, value_text: str) -> None:
+        if not self._session_active or self._client is None:
+            self._fail(RuntimeError("no active scan session — run First Scan first"))
+            return
+        vt, _ = _VALUE_TYPES[self._value_type_name]
+        ct, needs_value = _SCAN_TYPES[scan_type_name]
+        try:
+            value = self._encode_value(self._value_type_name, value_text) if needs_value else 0
+        except ValueError as e:
+            self._fail(e)
+            return
+        self.set_status("next scan…")
+
+        def work():
+            assert self._client is not None
+            count = ts.turboscan_count_resident(
+                self._client.connection, vt, ct, value,
+            )
+            self._survivor_count = count
+            return count
+
+        def on_done(count: int) -> None:
+            self.set_status(f"narrowed to {count} survivors")
+            self._scan.on_scan_done(count)
+            self._table.set_count(count)
+            self._table.refresh_window()
+
+        self.run_async(work, on_done=on_done, on_error=lambda e: self._fail(e))
+
+    def new_scan(self) -> None:
+        if self._session_active and self._client is not None:
+            def work():
+                ts.turboscan_end(self._client.connection)  # type: ignore[union-attr]
+            self.run_async(work, on_done=lambda _: self._reset_session())
+        else:
+            self._reset_session()
+
+    def _reset_session(self) -> None:
+        self._session_active = False
+        self._survivor_count = 0
+        self._table.clear()
+        self.set_status("new scan")
+        self._scan.on_new_scan()
+
+    def fetch_survivors(self, start: int, count: int):
+        """Called by ResultsTable on the UI thread; returns synchronously.
+
+        Used inside a worker thread spawned by the table itself.
+        """
+        assert self._client is not None
+        return ts.turboscan_get_resident(
+            self._client.connection, start, count, self._value_length,
+        )
+
+    # -- freeze (called by ResultsTable) ------------------------------------
+
+    def freeze_address(self, address: int, value_bytes: bytes) -> None:
+        if self._freeze:
+            self._freeze.freeze(address, value_bytes)
+            self.set_status(f"froze {address:#x}")
+
+    def unfreeze_address(self, address: int) -> None:
+        if self._freeze:
+            self._freeze.unfreeze(address)
+            self.set_status(f"unfroze {address:#x}")
+
+    def is_frozen(self, address: int) -> bool:
+        return bool(self._freeze and self._freeze.is_frozen(address))
+
+    # -- value encoding ------------------------------------------------------
+
+    @staticmethod
+    def _encode_value(value_type_name: str, text: str):
+        """Parse a user-entered value string into the right Python type.
+
+        Float types accept decimal notation; integer types accept decimal or
+        0x hex. Raises ValueError with a usable message on bad input (the
+        caller surfaces it via _fail rather than crashing the callback).
+        """
+        s = text.strip()
+        if not s:
+            raise ValueError("enter a value first (the scan type needs one)")
+        if value_type_name.startswith("f"):
+            return float(s)  # raises ValueError on bad input, which we want
+        # integer types: allow 0x hex or decimal; int(s, 0) handles both
+        return int(s, 0)
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def _on_close(self) -> None:
+        try:
+            if self._freeze:
+                self._freeze.stop()
+            if self._session_active and self._client is not None:
+                try:
+                    ts.turboscan_end(self._client.connection)
+                except Exception:
+                    pass
+            if self._client is not None:
+                self._client.close()
+        finally:
+            self.root.destroy()
+
+    def run(self) -> None:
+        self.root.mainloop()
+
+
+def main() -> int:
+    ScannerApp().run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ps5dbg_scanner/connection_panel.py

@@ -0,0 +1,96 @@
+"""Connection panel — host/port, connect, target picker."""
+from __future__ import annotations
+
+import os
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .app import ScannerApp
+
+
+class ConnectionPanel:
+    """Top bar: host/port entries, Connect button, target dropdown."""
+
+    def __init__(self, parent: tk.Widget, app: "ScannerApp") -> None:
+        self.app = app
+        self.frame = ttk.LabelFrame(parent, text="Connection")
+        self.frame.columnconfigure(4, weight=1)
+
+        ttk.Label(self.frame, text="Host:").grid(row=0, column=0, padx=(8, 2), pady=6)
+        default_host = os.environ.get("PS5_HOST", "")
+        self.host_var = tk.StringVar(value=default_host)
+        self.host_entry = ttk.Entry(self.frame, textvariable=self.host_var, width=18)
+        self.host_entry.grid(row=0, column=1, padx=2, pady=6)
+
+        ttk.Label(self.frame, text="Port:").grid(row=0, column=2, padx=(6, 2), pady=6)
+        self.port_var = tk.StringVar(value=os.environ.get("PS5_PORT", "744"))
+        self.port_entry = ttk.Entry(self.frame, textvariable=self.port_var, width=6)
+        self.port_entry.grid(row=0, column=3, padx=2, pady=6)
+
+        self.connect_btn = ttk.Button(self.frame, text="Connect", command=self._on_connect)
+        self.connect_btn.grid(row=0, column=4, padx=8, pady=6, sticky="w")
+
+        ttk.Label(self.frame, text="Target:").grid(row=0, column=5, padx=(12, 2), pady=6)
+        self.target_var = tk.StringVar()
+        self.target_combo = ttk.Combobox(
+            self.frame, textvariable=self.target_var, state="readonly", width=44
+        )
+        self.target_combo.grid(row=0, column=6, padx=2, pady=6)
+        self.target_combo.bind("<<ComboboxSelected>>", self._on_target_selected)
+        self._targets: list[tuple[int, str, str]] = []  # (pid, name, titleid)
+
+    # -- callbacks -----------------------------------------------------------
+
+    def _on_connect(self) -> None:
+        host = self.host_var.get().strip()
+        if not host:
+            self.app.set_status("enter a host first")
+            return
+        try:
+            port = int(self.port_var.get().strip())
+        except ValueError:
+            self.app.set_status("invalid port")
+            return
+        self.connect_btn.config(state="disabled")
+        self.app.set_status(f"connecting to {host}:{port}…")
+        self.app.connect(host, port)
+
+    def on_connected(self) -> None:
+        """Called by app (UI thread) after a successful connect."""
+        self.connect_btn.config(text="Disconnect", state="normal",
+                                command=self._on_disconnect)
+
+    def _on_disconnect(self) -> None:
+        # simple: tell user to restart for now (full disconnect/reconnect is v0.3 polish)
+        self.app.set_status("disconnect: close & reopen the app (v0.3 will add live reconnect)")
+
+    # -- targets -------------------------------------------------------------
+
+    def populate_targets(self, fg, procs) -> None:
+        """Populate the target dropdown. Runs on UI thread."""
+        self._targets = []
+        labels = []
+        # foreground app first (if any)
+        if fg.pid != 0:
+            self._targets.append((fg.pid, fg.name, fg.titleid))
+            labels.append(f"▶ {fg.name} (pid {fg.pid}, {fg.titleid}) [foreground]")
+        # then all procs, sorted, excluding kernel pid 0
+        for p in sorted(procs, key=lambda x: x.name.lower()):
+            if p.pid == 0:
+                continue
+            self._targets.append((p.pid, p.name, ""))
+            labels.append(f"  {p.name} (pid {p.pid})")
+        self.target_combo["values"] = labels
+        if labels:
+            self.target_combo.current(0 if fg.pid != 0 else 0)
+            self._select_index(0)
+
+    def _on_target_selected(self, _evt) -> None:
+        self._select_index(self.target_combo.current())
+
+    def _select_index(self, idx: int) -> None:
+        if 0 <= idx < len(self._targets):
+            pid, name, _titleid = self._targets[idx]
+            self.app.pid = pid

ps5dbg_scanner/freeze_manager.py

@@ -0,0 +1,125 @@
+"""Freeze manager — keeps a set of addresses pinned to fixed values.
+
+A single supervisor thread wakes at a configurable interval (default 10 Hz) and
+re-writes every frozen address via the ps5dbg client. This is the classic
+"freeze health/ammo at 999" feature.
+
+The manager is pure logic + one background thread; it takes a write callable so
+it's unit-testable with a fake. All ps5dbg calls happen on the supervisor
+thread, never on the tkinter UI thread.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass
+class FrozenSlot:
+    """One frozen address: where, what value, and the encoded bytes to write."""
+
+    address: int
+    value_bytes: bytes
+    label: str = ""
+
+
+class FreezeManager:
+    """Supervisor that periodically re-writes frozen addresses.
+
+    Args:
+        writer: callable(address:int, data:bytes) -> None. Typically
+            ``lambda a, d: client.write(pid, a, d)``. Raised exceptions are
+            swallowed and reported via ``on_error`` (a freeze failing should
+            not crash the supervisor or the UI).
+        rate_hz: how often per second to re-write. Default 10.
+        on_error: optional callback(slot, exc) invoked when a write raises.
+    """
+
+    def __init__(
+        self,
+        writer: Callable[[int, bytes], None],
+        rate_hz: float = 10.0,
+        on_error: Optional[Callable[[FrozenSlot, BaseException], None]] = None,
+    ) -> None:
+        self._writer = writer
+        self._period = 1.0 / rate_hz if rate_hz > 0 else 0.1
+        self._on_error = on_error
+        self._slots: dict[int, FrozenSlot] = {}
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    # -- slot management (UI thread calls these) ----------------------------
+
+    def freeze(self, address: int, value_bytes: bytes, label: str = "") -> None:
+        """Add or replace a frozen slot. Idempotent on address."""
+        with self._lock:
+            self._slots[address] = FrozenSlot(
+                address=address, value_bytes=value_bytes, label=label
+            )
+
+    def unfreeze(self, address: int) -> None:
+        with self._lock:
+            self._slots.pop(address, None)
+
+    def is_frozen(self, address: int) -> bool:
+        with self._lock:
+            return address in self._slots
+
+    def frozen_addresses(self) -> list[int]:
+        with self._lock:
+            return list(self._slots.keys())
+
+    def set_value(self, address: int, value_bytes: bytes) -> None:
+        """Update the frozen value without toggling freeze state."""
+        with self._lock:
+            slot = self._slots.get(address)
+            if slot is not None:
+                self._slots[address] = FrozenSlot(
+                    address=address, value_bytes=value_bytes, label=slot.label
+                )
+
+    # -- supervisor thread ---------------------------------------------------
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name="ps5dbg-scanner-freeze", daemon=True
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        t = self._thread
+        self._thread = None
+        if t and t.is_alive():
+            t.join(timeout=1.0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            with self._lock:
+                slots = list(self._slots.values())
+            for slot in slots:
+                if self._stop.is_set():
+                    break
+                try:
+                    self._writer(slot.address, slot.value_bytes)
+                except BaseException as e:  # noqa: BLE001 — supervisor must survive
+                    if self._on_error:
+                        try:
+                            self._on_error(slot, e)
+                        except Exception:
+                            pass
+            # precise-ish sleep, wake early on stop
+            self._stop.wait(self._period)
+
+    @property
+    def rate_hz(self) -> float:
+        return 1.0 / self._period if self._period > 0 else 0.0
+
+
+__all__ = ["FreezeManager", "FrozenSlot"]

ps5dbg_scanner/results_table.py

@@ -0,0 +1,260 @@
+"""Results table — virtualized ttk.Treeview over the server-resident survivor set.
+
+The naive "insert every survivor as a row" approach freezes tkinter past ~50k
+rows. This widget instead keeps a sliding window of rows (PAGE_SIZE) and
+re-fills them as the user scrolls, fetching survivors from the PS5 on demand
+via ``app.fetch_survivors(start, count)`` in a worker thread.
+
+Columns: Address | Current | Previous | Frozen.
+"""
+from __future__ import annotations
+
+import threading
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING, Optional
+
+from ps5dbg.constants import ScanValueType
+
+if TYPE_CHECKING:
+    from .app import ScannerApp
+
+PAGE_SIZE = 500  # rows materialized in the Treeview at once
+MAX_ROWS = 5000  # cap to keep the scrollbar honest; full count shown in status
+
+
+class ResultsTable:
+    """Virtualized survivor table. Fetches windows from the PS5."""
+
+    def __init__(self, parent: tk.Widget, app: "ScannerApp") -> None:
+        self.app = app
+        self.frame = ttk.LabelFrame(parent, text="Results")
+        self.frame.columnconfigure(0, weight=1)
+        self.frame.rowconfigure(0, weight=1)
+
+        columns = ("address", "current", "previous", "frozen")
+        self.tree = ttk.Treeview(self.frame, columns=columns, show="headings",
+                                 selectmode="browse")
+        for col, text, width in (
+            ("address", "Address", 160),
+            ("current", "Current", 120),
+            ("previous", "Previous", 120),
+            ("frozen", "Frozen", 60),
+        ):
+            self.tree.heading(col, text=text)
+            self.tree.column(col, width=width, anchor="w")
+        self.tree.grid(row=0, column=0, sticky="nsew")
+
+        vsb = ttk.Scrollbar(self.frame, orient="vertical", command=self.tree.yview)
+        vsb.grid(row=0, column=1, sticky="ns")
+        self.tree.configure(yscrollcommand=self._on_scroll)
+        self._vsb = vsb
+
+        # right-click context menu
+        self.menu = tk.Menu(self.tree, tearoff=0)
+        self.menu.add_command(label="Freeze / Unfreeze", command=self._toggle_freeze)
+        self.menu.add_command(label="Edit value…", command=self._edit_value)
+        self.menu.add_command(label="Copy address", command=self._copy_address)
+        self.tree.bind("<Button-3>", self._on_right_click)
+
+        # session state
+        self._value_type: ScanValueType = ScanValueType.UINT32
+        self._value_length: int = 4
+        self._count: int = 0
+        self._fetch_lock = threading.Lock()
+        self._last_fetch_start: int = -1
+
+    # -- session wiring (called by app on UI thread) ------------------------
+
+    def set_session(self, value_type: ScanValueType, value_length: int, count: int) -> None:
+        self._value_type = value_type
+        self._value_length = value_length
+        self._count = count
+        self.clear()
+
+    def set_count(self, count: int) -> None:
+        self._count = count
+        self.clear()
+
+    def clear(self) -> None:
+        self.tree.delete(*self.tree.get_children())
+        self._last_fetch_start = -1
+
+    # -- virtualized window fetch -------------------------------------------
+
+    def refresh_window(self, start: int = 0) -> None:
+        """Fetch the [start, start+PAGE_SIZE) survivor window and re-fill rows.
+
+        Runs the fetch on a worker thread; re-fills the Treeview on the UI thread.
+        """
+        if self._count == 0 or self.app.client is None:
+            return
+        start = max(0, min(start, max(0, self._count - 1)))
+        fetch_count = min(PAGE_SIZE, self._count - start)
+        if start == self._last_fetch_start:
+            return  # already showing this window
+
+        def work():
+            return self.app.fetch_survivors(start, fetch_count)
+
+        def on_done(rows):
+            self._fill_rows(start, rows)
+            self._last_fetch_start = start
+
+        self.app.run_async(work, on_done=on_done)
+
+    def _fill_rows(self, start: int, rows) -> None:
+        """Replace the Treeview contents with ``rows`` starting at ``start``."""
+        self.tree.delete(*self.tree.get_children())
+        for i, (addr, cur, prev, _first) in enumerate(rows):
+            idx = start + i
+            frozen = "🔒" if self.app.is_frozen(addr) else ""
+            self.tree.insert(
+                "", "end", iid=str(idx),
+                values=(f"{addr:#018x}", self._fmt(cur), self._fmt(prev), frozen),
+            )
+
+    def _fmt(self, raw: bytes) -> str:
+        """Format a raw value bytes according to the session's value type."""
+        try:
+            if self._value_type in (ScanValueType.UINT8, ScanValueType.UINT16,
+                                    ScanValueType.UINT32, ScanValueType.UINT64):
+                return str(int.from_bytes(raw, "little", signed=False))
+            if self._value_type in (ScanValueType.INT8, ScanValueType.INT16,
+                                    ScanValueType.INT32, ScanValueType.INT64):
+                return str(int.from_bytes(raw, "little", signed=True))
+            if self._value_type is ScanValueType.FLOAT:
+                import struct
+                return f"{struct.unpack('<f', raw)[0]:.4g}"
+            if self._value_type is ScanValueType.DOUBLE:
+                import struct
+                return f"{struct.unpack('<d', raw)[0]:.4g}"
+        except Exception:
+            pass
+        return raw.hex()
+
+    # -- scroll handling -----------------------------------------------------
+
+    def _on_scroll(self, *args) -> None:
+        """Treeview yview callback — detect when the user nears a window edge."""
+        self._vsb.set(*args)
+        if not args:
+            return
+        # args = (first, last); if last close to 1.0, page forward; first close to 0, back
+        first = float(args[0])
+        # figure out which survivor index is at the top of the visible area
+        children = self.tree.get_children()
+        if not children:
+            return
+        top_idx = int(children[0])
+        visible = len(children)
+        # if the user has scrolled to near the bottom of the current window, fetch next
+        if first > 0.7 and top_idx + visible < self._count:
+            self.refresh_window(top_idx + visible - 20)
+        elif first < 0.2 and top_idx > 0:
+            self.refresh_window(max(0, top_idx - PAGE_SIZE + 20))
+
+    # -- context menu actions -----------------------------------------------
+
+    def _on_right_click(self, event) -> None:
+        row = self.tree.identify_row(event.y)
+        if row:
+            self.tree.selection_set(row)
+            self.menu.tk_popup(event.x_root, event.y_root)
+
+    def _selected_address(self) -> Optional[int]:
+        sel = self.tree.selection()
+        if not sel:
+            return None
+        idx = int(sel[0])
+        # we need the actual address; re-fetch this single survivor
+        if self.app.client is None:
+            return None
+        rows = self.app.fetch_survivors(idx, 1)
+        if not rows:
+            return None
+        return rows[0][0]
+
+    def _toggle_freeze(self) -> None:
+        addr = self._selected_address()
+        if addr is None:
+            return
+        if self.app.is_frozen(addr):
+            self.app.unfreeze_address(addr)
+        else:
+            # freeze at the current value
+            rows = self.app.fetch_survivors(int(self.tree.selection()[0]), 1)
+            if rows:
+                _, cur, _prev, _first = rows[0]
+                self.app.freeze_address(addr, cur)
+        # refresh the visible window to update the lock icon
+        self.refresh_window(self._last_fetch_start)
+
+    def _edit_value(self) -> None:
+        sel = self.tree.selection()
+        if not sel or self.app.client is None or self.app.pid is None:
+            return
+        idx = int(sel[0])
+        rows = self.app.fetch_survivors(idx, 1)
+        if not rows:
+            return
+        addr, cur, _prev, _first = rows[0]
+        new = self._prompt("New value", "Edit value", self._fmt(cur))
+        if new is None:
+            return
+        try:
+            data = self._encode(new)
+        except ValueError:
+            from tkinter import messagebox
+            messagebox.showerror("ps5dbg-scanner", f"invalid value for {self._value_type.name}")
+            return
+        # write synchronously off the UI thread
+        def work():
+            self.app.client.write(self.app.pid, addr, data)  # type: ignore[union-attr]
+        self.app.run_async(work, on_done=lambda _: (
+            self.app.set_status(f"wrote {data.hex()} -> {addr:#x}"),
+            self.refresh_window(self._last_fetch_start),
+        ))
+
+    def _copy_address(self) -> None:
+        addr = self._selected_address()
+        if addr is None:
+            return
+        self.frame.clipboard_clear()
+        self.frame.clipboard_append(f"{addr:#x}")
+        self.app.set_status(f"copied {addr:#x}")
+
+    # -- helpers -------------------------------------------------------------
+
+    def _prompt(self, title, prompt, initial="") -> Optional[str]:
+        from tkinter import simpledialog
+        return simpledialog.askstring(title, prompt, initialvalue=initial,
+                                      parent=self.frame)
+
+    def _encode(self, text: str) -> bytes:
+        import struct
+        vt = self._value_type
+        n = int(text, 0) if not text.lstrip("-").replace(".", "", 1).isdigit() else (
+            float(text) if "." in text else int(text, 0)
+        )
+        if vt in (ScanValueType.UINT8,):
+            return struct.pack("<B", int(n) & 0xFF)
+        if vt in (ScanValueType.INT8,):
+            return struct.pack("<b", int(n))
+        if vt in (ScanValueType.UINT16,):
+            return struct.pack("<H", int(n) & 0xFFFF)
+        if vt in (ScanValueType.INT16,):
+            return struct.pack("<h", int(n))
+        if vt in (ScanValueType.UINT32,):
+            return struct.pack("<I", int(n) & 0xFFFFFFFF)
+        if vt in (ScanValueType.INT32,):
+            return struct.pack("<i", int(n))
+        if vt in (ScanValueType.UINT64,):
+            return struct.pack("<Q", int(n) & 0xFFFFFFFFFFFFFFFF)
+        if vt in (ScanValueType.INT64,):
+            return struct.pack("<q", int(n))
+        if vt is ScanValueType.FLOAT:
+            return struct.pack("<f", float(n))
+        if vt is ScanValueType.DOUBLE:
+            return struct.pack("<d", float(n))
+        raise ValueError(f"unsupported value type {vt}")

ps5dbg_scanner/scan_panel.py

@@ -0,0 +1,92 @@
+"""Scan panel — value type, scan type, value entry, scan buttons."""
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .app import ScannerApp
+
+
+class ScanPanel:
+    """Middle bar: value-type / scan-type dropdowns, value entry, scan buttons."""
+
+    def __init__(
+        self,
+        parent: tk.Widget,
+        app: "ScannerApp",
+        value_types: list[str],
+        scan_types: list[str],
+    ) -> None:
+        self.app = app
+        self.frame = ttk.LabelFrame(parent, text="Scan")
+        self.frame.columnconfigure(3, weight=1)
+
+        ttk.Label(self.frame, text="Value type:").grid(row=0, column=0, padx=(8, 2), pady=8)
+        self.value_type_var = tk.StringVar(value="u32")
+        self.value_type_combo = ttk.Combobox(
+            self.frame, textvariable=self.value_type_var, state="readonly",
+            width=6, values=value_types,
+        )
+        self.value_type_combo.grid(row=0, column=1, padx=2, pady=8)
+
+        ttk.Label(self.frame, text="Scan type:").grid(row=0, column=2, padx=(10, 2), pady=8)
+        self.scan_type_var = tk.StringVar(value="Exact value")
+        self.scan_type_combo = ttk.Combobox(
+            self.frame, textvariable=self.scan_type_var, state="readonly",
+            width=22, values=scan_types,
+        )
+        self.scan_type_combo.grid(row=0, column=3, sticky="w", padx=2, pady=8)
+        self.scan_type_combo.bind("<<ComboboxSelected>>", self._on_scan_type_changed)
+
+        ttk.Label(self.frame, text="Value:").grid(row=0, column=4, padx=(10, 2), pady=8)
+        self.value_var = tk.StringVar()
+        self.value_entry = ttk.Entry(self.frame, textvariable=self.value_var, width=14)
+        self.value_entry.grid(row=0, column=5, padx=2, pady=8)
+
+        self.first_btn = ttk.Button(self.frame, text="First Scan", command=self._on_first)
+        self.first_btn.grid(row=0, column=6, padx=(10, 2), pady=8)
+        self.next_btn = ttk.Button(self.frame, text="Next Scan", command=self._on_next, state="disabled")
+        self.next_btn.grid(row=0, column=7, padx=2, pady=8)
+        self.new_btn = ttk.Button(self.frame, text="New Scan", command=self._on_new, state="disabled")
+        self.new_btn.grid(row=0, column=8, padx=(2, 8), pady=8)
+
+        self._set_buttons(post_first=False)
+
+    # -- callbacks -----------------------------------------------------------
+
+    def _on_scan_type_changed(self, _evt) -> None:
+        # valueless scan types (Increased/Decreased/Changed/Unknown) disable the entry
+        valueless = {"Increased value", "Decreased value", "Changed value",
+                     "Unchanged value", "Unknown initial value"}
+        state = "disabled" if self.scan_type_var.get() in valueless else "normal"
+        self.value_entry.config(state=state)
+
+    def _on_first(self) -> None:
+        self.app.first_scan(self.value_type_var.get(), self.scan_type_var.get(),
+                            self.value_var.get())
+
+    def _on_next(self) -> None:
+        self.app.next_scan(self.scan_type_var.get(), self.value_var.get())
+
+    def _on_new(self) -> None:
+        self.app.new_scan()
+
+    # -- state transitions (called by app on UI thread) ---------------------
+
+    def on_scan_done(self, survivor_count: int) -> None:
+        self._set_buttons(post_first=True)
+
+    def on_new_scan(self) -> None:
+        self._set_buttons(post_first=False)
+
+    def _set_buttons(self, post_first: bool) -> None:
+        if post_first:
+            self.first_btn.config(state="disabled")
+            self.next_btn.config(state="normal")
+            self.new_btn.config(state="normal")
+        else:
+            self.first_btn.config(state="normal")
+            self.next_btn.config(state="disabled")
+            self.new_btn.config(state="disabled")

ps5dbg_scanner-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ps5dbg-scanner
+Version: 0.2.0
+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.

ps5dbg_scanner-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+ps5dbg_scanner/__init__.py,sha256=Wy7pBDj2AhqyAVWXGNwdGDfgNjQfQEjSkXgAQiDqYig,308
+ps5dbg_scanner/__main__.py,sha256=M7YujKbHQTdwcSIdRUsKTd5p-71mCUlqOaEneHVVbHg,161
+ps5dbg_scanner/app.py,sha256=RjICsrjPQS4CeE1Usezssueu0XxjZNCRUG3UiU3Zfek,13760
+ps5dbg_scanner/connection_panel.py,sha256=-u4S3FxIFGC3_UdziKTJsLPCG_J8PKZpcKaZMAZlavo,4053
+ps5dbg_scanner/freeze_manager.py,sha256=2d8wf4z_VvRsu38jnvjysfzDpNAnANMxK4sx8LXPZsE,4307
+ps5dbg_scanner/results_table.py,sha256=zbsVVCTkEaWHrKJAdYP0WkgQQySgcbODFHwyI8ERc6g,10384
+ps5dbg_scanner/scan_panel.py,sha256=wVktXI9U88YMkzc1gjCFbOte-TXznOsxail0MvIIZ8w,3805
+ps5dbg_scanner-0.2.0.dist-info/licenses/LICENSE,sha256=94ywdt7ckRTD9PK0pT2rDm65LFNFo7q-1G1KZGlW_wc,958
+ps5dbg_scanner-0.2.0.dist-info/METADATA,sha256=9AG1SSY_c_8al3x-buXjXPdJDX05j5bCTRr741PcO8Q,6738
+ps5dbg_scanner-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ps5dbg_scanner-0.2.0.dist-info/entry_points.txt,sha256=YDbYUMdtl84N-izWmctBa1xNYmytXnFyavE53jtjgu0,59
+ps5dbg_scanner-0.2.0.dist-info/top_level.txt,sha256=cbgQHV0pCsDiruadhmauLKi8-IPhMAyRqZboX-SjQPA,15
+ps5dbg_scanner-0.2.0.dist-info/RECORD,,

ps5dbg_scanner-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ps5dbg_scanner-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ps5dbg-scanner = ps5dbg_scanner.app:main

ps5dbg_scanner-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ps5dbg-scanner is licensed under GPL-3.0-only, matching the ps5dbg library
+and ps5debug-NG it builds upon.
+
+The full text of the GPL-3.0 is available at:
+https://www.gnu.org/licenses/gpl-3.0.txt
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.

ps5dbg_scanner-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ps5dbg_scanner