ppsspp_session
Start, stop, and inspect PPSSPP debug sessions, and wait for the emulated CPU to boot before memory access. Prevents early-read failures with a clear boot-ready check.
Instructions
PURPOSE: Start / stop / inspect PPSSPP debug sessions — action=start / stop / get / wait_ready; wait_ready blocks until the emulated CPU is up.
USAGE: action='start' needs iso_path (pass wait_ready=true to block until the CPU is up in the same call); stop/get/wait_ready need session_id. Call wait_ready AFTER start and BEFORE any memory tool — PPSSPP answers WebSocket before the CPU boots. start(resilient=true) self-heals boot wedges (blacklist quarantine + relaunch with the same session_id, ≤2 retries).
BEHAVIOR: STATE-CHANGE. start spawns a PPSSPP subprocess + WS debugger; stop terminates it (never taskkill the process yourself); wait_ready polls the probe lock-free and fails [BOOT_TIMEOUT] on wedge suspicion; get is read-only.
RETURNS: SessionResponse {session_id, iso_path, pid, ws_url, created_at, last_active_at, exec_count, ws_connected, recovered, ppsspp_version} — or, for wait_ready, {action, ready, elapsed_s, probe_addr, probe_value, note}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Session operation. Valid values: - 'start': launch a new PPSSPP session (requires iso_path). Set wait_ready=true to block until the emulated CPU is up (same probe/budget semantics as 'wait_ready'). - 'stop': terminate an existing session (requires session_id). - 'get': query session health (requires session_id). - 'wait_ready': block until the emulated CPU has started (requires session_id). Call this after 'start' BEFORE any memory/disassembly tool — PPSSPP answers WebSocket before the ISO finishes booting, and early reads fail with 'CPU not started'. | |
| iso_path | No | Absolute path to the ISO file (required when action=start). | |
| resilient | No | action=start only: self-healing boot — on wedge evidence (CPU-ready probe exhausted, handshake never accepted, process died) the launcher is torn down, the GPU-backend failure blacklist is quarantined (rename), and the session relaunches with the SAME session_id up to 2 retries; the response carries recovered=N (0 = first launch). Exhaustion raises [BOOT_TIMEOUT]. Ignored in fake mode. | |
| timeout_s | No | Boot budget in seconds (action=wait_ready, action=start with wait_ready=true, or the per-attempt CPU-ready budget when action=start with resilient=true; default 75, clamped to [1, 300]). | |
| probe_addr | No | Hex address polled by the readiness probe (action=wait_ready, action=start with wait_ready=true, or the resilient-start gate; default '0x08804000', the project's top.prx load base). | 0x08804000 |
| session_id | No | Session ID (required when action=stop / get / wait_ready). | |
| wait_ready | No | action=start only: block until the emulated CPU is ready before returning (same probe/budget as action=wait_ready; raises [BOOT_TIMEOUT] on wedge suspicion). Fake test mode is ready immediately. Default false keeps the historical two-call flow. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | PPSSPP process PID (None if stopped). | |
| ws_url | No | WebSocket URL (ws://host:port/debugger). | |
| iso_path | No | Absolute path to the ISO file. | |
| restored | No | F-6(a): 1 when this session was restored from sessions.json (a previous server run left it behind) rather than started fresh in this process — its game state may be stale. | |
| recovered | No | H2: resilient-start relaunch count (0 = the first launch succeeded; >0 means the game state was reset by a wedge heal — breakpoints need re-arming). | |
| created_at | No | ISO 8601 timestamp of session creation. | |
| exec_count | No | Number of tool calls made against this session. | |
| session_id | No | Session UUID-like identifier. | |
| ws_connected | No | True if WebSocket is currently connected. | |
| last_active_at | No | ISO 8601 timestamp of last tool call. | |
| ppsspp_version | No | PPSSPP build fingerprint captured from the version handshake (None until the session transport binds). |