PURPOSE: Verify that the PPSSPP WebSocket debugger is reachable and responding. USAGE: Call once at start-of-session before any other tool calls; if it succeeds, the WebSocket handshake worked and PPSSPP's debugger is available. BEHAVIOR: No side effects — calls the 'version' event to learn PPSSPP's release version. Times out after ~10 seconds if PPSSPP isn't running, doesn't have 'Allow remote debugger' enabled (Settings → Tools → Developer Tools), or the host:port isn't reachable. RETURNS: Single line 'pong (PPSSPP VERSION)'.

PURPOSE: Get the loaded game's title, disc ID, and version, plus PPSSPP's run state. USAGE: Call after ppsspp_ping to learn what game is loaded and whether emulation is currently running or stepping. BEHAVIOR: No side effects — pure read. Returns 'no game loaded' fields if PPSSPP is at the home menu / not currently emulating. RETURNS: Multi-line text with Title, Disc ID, Version, and run state (running / paused / stepping).

PURPOSE: Read an unsigned 8-bit byte from PSP memory at the given physical address. USAGE: Use for single-byte status flags, counters, and 8-bit fields. For 16/32-bit values use ppsspp_read16/read32 (one call instead of multi-byte assembly); for spans use ppsspp_read_range. BEHAVIOR: No side effects — pure read. Returns an error if the address isn't a valid PSP memory address (PPSSPP validates against the PSP's mapped regions). RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.

PURPOSE: Read an unsigned 16-bit little-endian value from PSP memory at the given physical address. USAGE: Use for 16-bit game-state fields (most counters, IDs, small numerics). For single bytes use ppsspp_read8; for 32-bit use ppsspp_read32; for arbitrary byte spans use ppsspp_read_range. BEHAVIOR: No side effects — pure read. PSP is little-endian (MIPS Allegrex). Returns an error if address+2 exceeds the valid memory region. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.

PURPOSE: Read an unsigned 32-bit little-endian value from PSP memory at the given physical address. USAGE: Use for 32-bit fields — timestamps, large counters, pointers, RGBA colors. For 8/16-bit use ppsspp_read8/read16; for spans use ppsspp_read_range. BEHAVIOR: No side effects — pure read. PSP is little-endian. Returns an error if address+4 exceeds the valid memory region. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.

PURPOSE: Read a contiguous range of bytes from PSP memory and return as a hex dump. USAGE: Use whenever you need more than ~4 bytes — one round-trip vs N typed reads. PPSSPP returns the data base64-encoded over the wire; this tool decodes and formats as space-separated hex bytes. No hard size limit from the WebSocket but stay reasonable (≤16 KiB per call) for response sizes. BEHAVIOR: No side effects — pure read. Reads size consecutive bytes starting at address. Returns an error if any byte in the range is outside the valid PSP memory map. RETURNS: 'ADDR_HEX [N bytes]:' header + space-separated 2-digit uppercase hex bytes.

PURPOSE: Read a null-terminated UTF-8 string from PSP memory at the given address. USAGE: Use for in-game text, character names, dialogue, file names — anywhere the PSP stores a C-style null-terminated string. Stops at the first 0x00 byte. BEHAVIOR: No side effects — pure read. Reads bytes until null terminator, decodes as UTF-8. Returns an error if the address is outside valid memory, or if the string runs past valid memory before hitting a null. RETURNS: Single line 'ADDR_HEX: "STRING"'.

PURPOSE: Write an unsigned byte (0-255) to PSP memory at the given physical address. USAGE: Use for single-byte cheats, debug pokes, game-state mutations. For 16/32-bit use ppsspp_write16/write32; for spans use ppsspp_write_range. BEHAVIOR: DESTRUCTIVE: overwrites whatever was at address with no undo. Direct memory write — no hardware mediation. Returns an error if the address is outside valid memory or value > 255. RETURNS: Single line 'Wrote VAL → ADDR_HEX'.

PURPOSE: Write an unsigned 16-bit little-endian value to PSP memory. USAGE: Use for 16-bit cheats and pokes (HP, score, coordinates). For single bytes use ppsspp_write8; for 32/larger use ppsspp_write32/write_range. BEHAVIOR: DESTRUCTIVE: overwrites two bytes with no undo. PSP is little-endian (low byte at address, high at address+1). Returns an error if address+2 exceeds valid memory or value > 65535. RETURNS: Single line 'Wrote VAL → ADDR_HEX'.

PURPOSE: Write an unsigned 32-bit little-endian value to PSP memory. USAGE: Use for 32-bit cheats and pokes — timestamps, large counters, pointers. For 8/16-bit use ppsspp_write8/write16; for spans use ppsspp_write_range. BEHAVIOR: DESTRUCTIVE: overwrites four bytes with no undo. PSP is little-endian. Returns an error if address+4 exceeds valid memory or value > 4294967295. RETURNS: Single line 'Wrote VAL → ADDR_HEX'.

PURPOSE: Write a contiguous byte sequence to PSP memory starting at the given address. USAGE: Use for installing cheat tables, patching code blocks, or seeding regions. Bytes are sent base64-encoded over the wire. BEHAVIOR: DESTRUCTIVE: overwrites N bytes with no undo. Direct memory write. Returns an error if address+N exceeds valid memory or any byte value is outside 0-255. RETURNS: Single line 'Wrote N bytes → ADDR_HEX'.

PURPOSE: Set the PSP joypad button state — the buttons in the map are 'held' until you send another buttons command. USAGE: Drive games with input. Unlike one-frame-only schemes on other emulators, PPSSPP's input.buttons.send updates the persistent button state — the buttons stay held until you call ppsspp_press_buttons again with them set false (or use ppsspp_press_button for a timed one-shot). To release all buttons, call with all keys set to false. BEHAVIOR: Modifies emulator input state until changed. PSP buttons (case-sensitive): cross, circle, triangle, square, up, down, left, right, start, select, ltrigger, rtrigger, home. Unrecognized button names return an error. RETURNS: Single line 'Set buttons: BUTTON+BUTTON+...' or '... (all released)' if nothing was pressed.

PURPOSE: Press a PSP button for a fixed number of frames, then auto-release. USAGE: Use for discrete actions like pressing Start to skip a cutscene, or Cross to confirm a menu. For longer holds across many frames use ppsspp_press_buttons (persistent state) instead. BEHAVIOR: Modifies emulator input state. PPSSPP queues the press internally and releases the button after duration frames; the tool call returns immediately. Returns an error if the button name isn't recognized. RETURNS: Single line 'Pressed BUTTON for N frames (auto-released)'.

PURPOSE: Set the PSP analog stick state (one of left/right; the PSP only has one stick natively but PPSSPP exposes both for forward-compat). USAGE: Drive games that need analog input — character movement, camera control. X and Y are signed in [-1.0, 1.0]; (0, 0) = neutral, (1, 0) = full right, (0, -1) = full up. BEHAVIOR: Modifies emulator analog input. State persists until updated. RETURNS: Single line 'Set analog stick STICK to (X, Y)'.

PURPOSE: Pause PSP emulation (the debugger calls this 'stepping mode'). USAGE: Use before a sequence of memory inspects when you need a stable game state across calls. Memory r/w tool calls still work while paused. Use ppsspp_resume to continue. BEHAVIOR: Modifies emulator run state. Pauses the MIPS CPU; rendering may continue at last frame. Idempotent — pausing already-paused is a no-op. RETURNS: Single line 'Emulation paused'.

PURPOSE: Resume PSP emulation from a paused/stepping state. USAGE: Counterpart to ppsspp_pause. Use after a paused inspection sequence. To step a single frame instead, use ppsspp_step. BEHAVIOR: Modifies emulator run state. Idempotent — resuming already-running is a no-op. RETURNS: Single line 'Emulation resumed'.

PURPOSE: Step the MIPS CPU forward by ONE instruction (cpu.stepInto). USAGE: For instruction-level debugging — set a breakpoint, hit it, then step. NOT a frame-advance — one MIPS instruction is much smaller than one frame. To advance a frame's worth of execution, set a breakpoint at the start of the next frame's render and use ppsspp_resume. BEHAVIOR: Modifies emulator run state. Executes one MIPS instruction, then returns to stepping mode. Returns an error if emulation isn't currently in stepping mode (call ppsspp_pause first). RETURNS: Single line 'Stepped one instruction. PC: 0xADDR'.

PURPOSE: Reset the loaded PSP game — equivalent to soft-resetting the console. USAGE: Use to start fresh from the game's intro. To return to a specific point, set up a savestate via PPSSPP's UI and load it (savestate API is not in the WebSocket interface, so this must be done via PPSSPP's keybinds — typically F1-F8 for slots). BEHAVIOR: DESTRUCTIVE: RAM contents cleared, CPU returns to game entry point, framecount/game-state lost. The ISO/EBOOT stays loaded. RETURNS: Single line 'Game reset'.

PURPOSE: Capture the current PSP framebuffer as a PNG-encoded screenshot. USAGE: For visual inspection or sequence documentation. Default 'render' source reads the active GPU render target — safer, native 480x272, what the PSP CPU asked the GPU to draw. Opt-in 'output' source reads PPSSPP's final composited output (post scaling/shaders) but can crash PPSSPP on games whose output framebuffer state confuses GPU_GetOutputFramebuffer (a real upstream bug — an assert that should be a graceful failure). Prefer 'render' unless you specifically need the post-processed image. BEHAVIOR: Transparently pauses the CPU (cpu.stepping), captures, then resumes — both PPSSPP buffer events require stepping. If the emulator was already paused, leaves it paused. Returns an error if no game is loaded. The 'output' source CAN crash PPSSPP on certain games; if it does, MCP auto-reconnects to the relaunched PPSSPP cleanly. RETURNS: Text confirmation + inline PNG image block.

PURPOSE: Read all MIPS Allegrex CPU registers (general-purpose + FPU + special). USAGE: For reverse engineering and debugging — inspect function arguments, return values, PC, stack pointer. PSP's calling convention puts args in $a0-$a3, return in $v0, stack in $sp, return address in $ra. BEHAVIOR: No side effects — pure read. Most informative when called while emulation is paused (ppsspp_pause first); on a running CPU the snapshot is from whenever PPSSPP samples it. RETURNS: Multi-line text with all register names + hex values, grouped by class (GPR, FPU, special).

PURPOSE: Add a CPU execution breakpoint at the given PSP physical address. Emulation halts when PC reaches that address. USAGE: For RE work and HLE intercepts. Combine with ppsspp_resume + (later) ppsspp_get_registers to inspect state at the breakpoint. BEHAVIOR: Modifies PPSSPP's breakpoint table. The breakpoint persists until removed via ppsspp_breakpoint_remove or PPSSPP restarts. Returns an error if the address isn't executable memory. RETURNS: Single line 'Breakpoint added at ADDR_HEX'.

PURPOSE: Remove a previously-added CPU execution breakpoint. USAGE: Clean up breakpoints when done debugging. To remove all, query ppsspp_breakpoint_list first. BEHAVIOR: Modifies PPSSPP's breakpoint table. Idempotent for non-existent breakpoints (no error). RETURNS: Single line 'Breakpoint removed at ADDR_HEX'.

PURPOSE: List all currently-set CPU execution breakpoints. USAGE: Inventory before bulk-removing, or sanity-check what's set. BEHAVIOR: No side effects — pure read. RETURNS: Multi-line text, one line per breakpoint with its address and any conditions.