From d5e29d1a89a2c7c42921c1b98faa9985ec0e09c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Rydg=C3=A5rd?= Date: Mon, 19 Oct 2026 10:05:17 +0200 Subject: [PATCH 1/4] wsdbg: Exit non-zero when the debugger answers with an error One-shot mode and --sync treated any reply carrying the request's ticket as success, so a rejected memory write or resume looked like it worked. Co-Authored-By: Claude Opus 5.5 (1M context) --- Tools/wsdbg/README.md | 5 +++++ Tools/wsdbg/src/main.rs | 36 ++++++++++++++++++++---------------- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/Tools/wsdbg/README.md b/Tools/wsdbg/README.md index 5fa4b7dec4..bdd2e90b4b 100644 --- a/Tools/wsdbg/README.md +++ b/Tools/wsdbg/README.md @@ -74,6 +74,9 @@ to "print everything that arrives for `--wait` seconds", which is what you want when watching broadcasts (log lines, `gpu.stats.feed`) rather than asking a question. +An `error` reply carrying the request's ticket makes it exit non-zero too (with `--wait-all`, +once the interval is up). + Type `:help` in the REPL for a quick reminder, `:quit` to disconnect. ## Scripting a multi-step sequence @@ -89,6 +92,8 @@ prints as it arrives; this only changes when the *next* line gets sent. A breakp trips would otherwise hang the script forever, so it gives up after `--sync-timeout` seconds (default 30), reports it, and makes the run exit non-zero. +An `error` reply to a line doesn't stop the script, but makes the run exit non-zero at the end. + Matching is by ticket, always - `--sync` never waits for "whatever message arrives next", which is what used to quietly desynchronise a script. So prefer the `key=value` form for nested parameters too: values are parsed as JSON, and single quotes keep the inner double quotes intact, as in diff --git a/Tools/wsdbg/src/main.rs b/Tools/wsdbg/src/main.rs index daaa1c241c..c8d441878d 100644 --- a/Tools/wsdbg/src/main.rs +++ b/Tools/wsdbg/src/main.rs @@ -504,8 +504,8 @@ fn is_would_block(e: &tungstenite::Error) -> bool { ) } -// Returns false if the request went unanswered within the timeout, so one-shot mode can exit -// non-zero rather than looking successful after having printed nothing useful. +// Returns false if the request failed or went unanswered within the timeout, so one-shot mode +// can report that through its exit status. // // With deferred acks turned on (see request_deferred_acks) every request is answered, including // the ones whose result arrives later, so waiting for this request's ticket beats sleeping for a @@ -524,20 +524,22 @@ fn run_one_shot( socket.get_ref().set_read_timeout(Some(Duration::from_millis(50)))?; let deadline = Instant::now() + Duration::from_secs_f64(wait_secs.max(0.0)); - // Without a ticket (--raw with none supplied) there's nothing to match, so fall back to - // draining until the deadline, same as --wait-all. - let Some(ticket) = ticket.filter(|_| !wait_all) else { - pump_until(&mut socket, deadline, |_| false); - return Ok(true); - }; - - let answered = pump_until(&mut socket, deadline, |v| { - v.get("ticket").and_then(|t| t.as_u64()) == Some(ticket) + // Without a ticket (--raw with none supplied) there's nothing to match. --wait-all still + // watches for this request's errors, but keeps draining until the deadline either way. + let wait_for_ticket = ticket.is_some() && !wait_all; + let mut answered = false; + let mut failed = false; + pump_until(&mut socket, deadline, |v| { + if ticket.is_some() && v.get("ticket").and_then(|t| t.as_u64()) == ticket { + answered = true; + failed |= v.get("event").and_then(|e| e.as_str()) == Some("error"); + } + answered && wait_for_ticket }); - if !answered { - eprintln!("! timed out after {wait_secs}s waiting for a reply (ticket {ticket})"); + if wait_for_ticket && !answered { + eprintln!("! timed out after {wait_secs}s waiting for a reply (ticket {})", ticket.unwrap()); } - Ok(answered) + Ok(!failed && (!wait_for_ticket || answered)) } fn print_help() { @@ -652,7 +654,7 @@ fn handle_repl_line(socket: &mut WebSocket, line: &str) -> Result, ticket: u64, @@ -662,6 +664,7 @@ fn wait_for_sync_response( let wants_stepping = RESUME_FAMILY.contains(&event); let mut got_ticket = false; let mut got_stepping = !wants_stepping; + let mut failed = false; let deadline = Instant::now() + Duration::from_secs_f64(timeout_secs.max(0.0)); let done = pump_until(socket, deadline, |v| { @@ -669,6 +672,7 @@ fn wait_for_sync_response( got_ticket = true; // An error reply is a final answer - there'll be no cpu.stepping to follow. if v.get("event").and_then(|e| e.as_str()) == Some("error") { + failed = true; got_stepping = true; } } @@ -686,7 +690,7 @@ fn wait_for_sync_response( if got_ticket { ", acknowledged but never stopped" } else { "" } ); } - done + done && !failed } // Send a ticketed request and block until its response arrives (or timeout), returning the From b000d557e2e3dab94442c1fe7f420f7811d97b49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Rydg=C3=A5rd?= Date: Mon, 19 Oct 2026 10:05:43 +0200 Subject: [PATCH 2/4] Debugger: Never drop stepping and game events when the queue is full A log-only breakpoint in a hot loop fills the per-connection queue, and the cap then also discarded the cpu.stepping that followed, so the client never heard that the CPU stopped. Only cap breakpoint hits. Co-Authored-By: Claude Opus 5.5 (1M context) --- Core/Debugger/WebSocket.cpp | 18 +++++++++++++----- docs/WebSocketDebugger.md | 5 +++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/Core/Debugger/WebSocket.cpp b/Core/Debugger/WebSocket.cpp index e0d9ecf999..adfc515c23 100644 --- a/Core/Debugger/WebSocket.cpp +++ b/Core/Debugger/WebSocket.cpp @@ -123,7 +123,9 @@ static void UpdateConnected(int delta) { // cap the queue grows without bound and the connection falls further and further behind. Dropping // is the only sane answer; cpu.breakpoint.hit carries a sequence number so a client can tell // exactly how many it missed rather than silently believing it saw everything. -static constexpr size_t MAX_PENDING_EVENTS = 4096; +// Only breakpoint hits are capped. Game and stepping events come one per transition, and dropping +// one would leave the client believing the CPU is still running. +static constexpr size_t MAX_PENDING_BREAKPOINT_EVENTS = 4096; struct DebuggerEventSink { std::mutex lock; @@ -131,10 +133,15 @@ struct DebuggerEventSink { // A debugger that connects while the CPU is already stopped still wants to hear about it. bool needsSteppingPrime = true; - void Push(const char *category, std::string json) { + int pendingBreakpoints = 0; + + void Push(const char *category, std::string json, bool isBreakpoint = false) { std::lock_guard guard(lock); - if (pending.size() >= MAX_PENDING_EVENTS) - return; + if (isBreakpoint) { + if (pendingBreakpoints >= (int)MAX_PENDING_BREAKPOINT_EVENTS) + return; + pendingBreakpoints++; + } pending.emplace_back(category, std::move(json)); } @@ -142,6 +149,7 @@ struct DebuggerEventSink { std::lock_guard guard(lock); out->swap(pending); pending.clear(); + pendingBreakpoints = 0; } }; @@ -187,7 +195,7 @@ void WebSocketNotifyBreakpointHit(const BreakpointHit &hit) { const std::string json = j.str(); for (DebuggerEventSink *sink : g_sinks) - sink->Push("breakpoint", json); + sink->Push("breakpoint", json, true); } void WebSocketDebuggerTick() { diff --git a/docs/WebSocketDebugger.md b/docs/WebSocketDebugger.md index 4a25bd0249..4054ae7a15 100644 --- a/docs/WebSocketDebugger.md +++ b/docs/WebSocketDebugger.md @@ -257,8 +257,9 @@ reporting the range start; `hit.address` is the accurate one. `sequence` counts hits *produced*, not delivered. A connection whose queue backs up (easy to do with a log-only breakpoint in a hot loop - one can produce tens -of thousands of hits per second) drops events rather than growing without bound, -so a gap in `sequence` tells a client exactly how many it missed. Turning the +of thousands of hits per second) drops hits rather than growing without bound, +so a gap in `sequence` tells a client exactly how many it missed. Game and +stepping events are never dropped. Turning the `breakpoint` category off via `broadcast.config.set` avoids the traffic entirely. From 681a60b3ca7880c257d4650c95478fd9fed28e11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Rydg=C3=A5rd?= Date: Mon, 19 Oct 2026 10:07:30 +0200 Subject: [PATCH 3/4] Debugger: Fail game.state.load/save when the savestate is refused SaveState::Load and Save silently drop the operation when the network or achievements hardcore mode forbids it, but the debugger still answered as if it had been queued. Return whether it was, and check the boot state in the same CPU-thread call. Co-Authored-By: Claude Opus 5.5 (1M context) --- Core/Debugger/WebSocket/GameSubscriber.cpp | 40 ++++++++++++++-------- Core/SaveState.cpp | 19 +++++----- Core/SaveState.h | 8 ++--- 3 files changed, 40 insertions(+), 27 deletions(-) diff --git a/Core/Debugger/WebSocket/GameSubscriber.cpp b/Core/Debugger/WebSocket/GameSubscriber.cpp index 4c1c223a7d..10739b20b9 100644 --- a/Core/Debugger/WebSocket/GameSubscriber.cpp +++ b/Core/Debugger/WebSocket/GameSubscriber.cpp @@ -136,24 +136,30 @@ void WebSocketGameStatus(DebuggerRequest &req) { // Parameters: // - path: string, path to the .ppst file. // -// Response (same event name) with no extra data, once queued. +// Response (same event name) with no extra data, once queued, or an error if the network or +// achievements hardcore mode refuses it. void WebSocketGameStateLoad(DebuggerRequest &req) { std::string path; if (!req.ParamString("path", &path)) return; bool running = false; + bool queued = false; Core_RunOnCPUThread([&] { running = PSP_GetBootState() == BootState::Complete; + if (running) { + queued = SaveState::Load(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { + if (status == SaveState::Status::FAILURE) { + ERROR_LOG(Log::System, "game.state.load: %.*s", STR_VIEW(message)); + } + }); + } }); if (!running) return req.Fail("Game not running"); - - SaveState::Load(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { - if (status == SaveState::Status::FAILURE) { - ERROR_LOG(Log::System, "game.state.load: %.*s", STR_VIEW(message)); - } - }); + if (!queued) { + return req.Fail("Could not queue savestate load"); + } req.Respond(); } @@ -164,24 +170,30 @@ void WebSocketGameStateLoad(DebuggerRequest &req) { // Parameters: // - path: string, path to write the .ppst file to. // -// Response (same event name) with no extra data, once queued. +// Response (same event name) with no extra data, once queued, or an error if the network or +// achievements hardcore mode refuses it. void WebSocketGameStateSave(DebuggerRequest &req) { std::string path; if (!req.ParamString("path", &path)) return; bool running = false; + bool queued = false; Core_RunOnCPUThread([&] { running = PSP_GetBootState() == BootState::Complete; + if (running) { + queued = SaveState::Save(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { + if (status == SaveState::Status::FAILURE) { + ERROR_LOG(Log::System, "game.state.save: %.*s", STR_VIEW(message)); + } + }); + } }); if (!running) return req.Fail("Game not running"); - - SaveState::Save(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { - if (status == SaveState::Status::FAILURE) { - ERROR_LOG(Log::System, "game.state.save: %.*s", STR_VIEW(message)); - } - }); + if (!queued) { + return req.Fail("Could not queue savestate save"); + } req.Respond(); } diff --git a/Core/SaveState.cpp b/Core/SaveState.cpp index 6be636c0e7..630d231119 100644 --- a/Core/SaveState.cpp +++ b/Core/SaveState.cpp @@ -201,17 +201,17 @@ int g_screenshotFailures; pspFileSystem.DoState(p); } - void Enqueue(const SaveState::Operation &op) { + bool Enqueue(const SaveState::Operation &op) { // These two both refuse the operation, and both say so - dropping it silently just // looks like the hotkey didn't work. Callers that ask the same questions themselves // return before getting here, so nothing shows a message twice. if (NetworkWarnUserIfOnlineAndCantSavestate()) { - return; + return false; } // Hardcore mode bans loading savestates outright, and saving too unless the user opted // back into that. if (Achievements::WarnUserIfHardcoreModeActive(op.type == OperationType::Save)) { - return; + return false; } std::lock_guard guard(mutex); @@ -220,28 +220,29 @@ int g_screenshotFailures; // Don't actually run it until next frame. // It's possible there might be a duplicate but it won't hurt us. needsProcess = true; + return true; } - void Load(const Path &filename, int slot, Callback callback) { + bool Load(const Path &filename, int slot, Callback callback) { if (NetworkWarnUserIfOnlineAndCantSavestate()) { - return; + return false; } rewindStates.NotifyState(); if (coreState == CoreState::CORE_RUNTIME_ERROR) Core_Break(BreakReason::SavestateLoad, 0); - Enqueue(Operation(OperationType::Load, filename, slot, callback)); + return Enqueue(Operation(OperationType::Load, filename, slot, callback)); } - void Save(const Path &filename, int slot, Callback callback) { + bool Save(const Path &filename, int slot, Callback callback) { if (NetworkWarnUserIfOnlineAndCantSavestate()) { - return; + return false; } rewindStates.NotifyState(); if (coreState == CoreState::CORE_RUNTIME_ERROR) Core_Break(BreakReason::SavestateSave, 0); - Enqueue(Operation(OperationType::Save, filename, slot, callback)); + return Enqueue(Operation(OperationType::Save, filename, slot, callback)); } void Verify(Callback callback) { diff --git a/Core/SaveState.h b/Core/SaveState.h index 746c4c3f11..cfbda4ec1a 100644 --- a/Core/SaveState.h +++ b/Core/SaveState.h @@ -88,12 +88,12 @@ namespace SaveState { std::string GetTitle(const Path &filename); // Load the specified file into the current state (async.) - // Warning: callback will be called on a different thread. - void Load(const Path &filename, int slot, Callback callback = Callback()); + // Returns true if queued. The callback may run on a different thread. + bool Load(const Path &filename, int slot, Callback callback = Callback()); // Save the current state to the specified file (async.) - // Warning: callback will be called on a different thread. - void Save(const Path &filename, int slot, Callback callback = Callback()); + // Returns true if queued. The callback may run on a different thread. + bool Save(const Path &filename, int slot, Callback callback = Callback()); CChunkFileReader::Error SaveToRam(std::vector &state); CChunkFileReader::Error LoadFromRam(std::vector &state, std::string *errorString); From 4bfeb59fcd9364b29d518f7679cdd43cf0649c69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Rydg=C3=A5rd?= Date: Mon, 19 Oct 2026 10:10:25 +0200 Subject: [PATCH 4/4] Debugger: Add wait to game.state.load/save With wait: true, respond once the savestate operation has finished (with its message), or with an error if it failed or was dropped without running. Otherwise a client only learns the operation was queued. Co-Authored-By: Claude Opus 5.5 (1M context) --- Core/Debugger/WebSocket/GameSubscriber.cpp | 189 +++++++++++++-------- Core/Debugger/WebSocket/GameSubscriber.h | 2 - docs/WebSocketDebugger.md | 2 +- 3 files changed, 118 insertions(+), 75 deletions(-) diff --git a/Core/Debugger/WebSocket/GameSubscriber.cpp b/Core/Debugger/WebSocket/GameSubscriber.cpp index 10739b20b9..909942b4d6 100644 --- a/Core/Debugger/WebSocket/GameSubscriber.cpp +++ b/Core/Debugger/WebSocket/GameSubscriber.cpp @@ -29,6 +29,9 @@ #include #endif +#include +#include + #include "Common/System/System.h" #include "Core/Config.h" #include "Core/Core.h" @@ -46,6 +49,116 @@ // DebuggerParamType::OPTIONAL, exactly the problem the note above is avoiding. bool NetworkAllowSpeedControl(); +namespace { + +// Filled in by the savestate callback, on the emu thread. +struct SaveStateResult { + std::mutex lock; + bool done = false; + SaveState::Status status = SaveState::Status::FAILURE; + std::string message; +}; + +struct WebSocketGameState : public DebuggerSubscriber { + void StateLoadSave(DebuggerRequest &req, bool save); + void Broadcast(net::WebSocketServer *ws) override; + +private: + struct Waiting { + const char *event; + std::string ticket; + std::shared_ptr result; + }; + std::vector waiting_; +}; + +} // namespace + +// Load a savestate file (game.state.load), or save one (game.state.save) +// +// The operation is queued, and happens at the end of the next frame the CPU runs, so follow this +// with something that runs it, like cpu.runUntilTime. +// +// Parameters: +// - path: string, path to the .ppst file. +// - wait: optional boolean, respond when the operation has finished rather than when queued. +// +// Response (same event name) once queued, or an error if the network or achievements hardcore +// mode refuses it. With wait, it's sent once done instead, with a message string, or an error +// if the load or save failed. +void WebSocketGameState::StateLoadSave(DebuggerRequest &req, bool save) { + const char *event = save ? "game.state.save" : "game.state.load"; + std::string path; + bool wait = false; + if (!req.ParamString("path", &path) || !req.ParamBool("wait", &wait, DebuggerParamType::OPTIONAL)) + return; + + // The queued operation holds the only other reference, so Broadcast() can also tell when it's + // dropped without ever running (at shutdown, for one). + std::shared_ptr result; + if (wait) + result = std::make_shared(); + auto callback = [event, result](SaveState::Status status, std::string_view message, std::string_view) { + if (status == SaveState::Status::FAILURE) { + ERROR_LOG(Log::System, "%s: %.*s", event, STR_VIEW(message)); + } + if (result) { + std::lock_guard guard(result->lock); + result->status = status; + result->message = message; + result->done = true; + } + }; + + bool running = false; + bool queued = false; + Core_RunOnCPUThread([&] { + running = PSP_GetBootState() == BootState::Complete; + if (running) { + queued = save ? SaveState::Save(Path(path), -1, callback) : SaveState::Load(Path(path), -1, callback); + } + }); + if (!running) + return req.Fail("Game not running"); + if (!queued) { + return req.Fail(save ? "Could not queue savestate save" : "Could not queue savestate load"); + } + + if (!wait) { + req.Respond(); + return; + } + const JsonNode *ticket = req.data.get("ticket"); + waiting_.push_back({ event, ticket ? json_stringify(ticket) : "", result }); +} + +void WebSocketGameState::Broadcast(net::WebSocketServer *ws) { + for (auto it = waiting_.begin(); it != waiting_.end(); ) { + // Check this first: if the callback ran, it was done before letting go. + bool dropped = it->result.use_count() == 1; + std::lock_guard guard(it->result->lock); + if (!it->result->done && !dropped) { + ++it; + continue; + } + + bool failed = !it->result->done || it->result->status == SaveState::Status::FAILURE; + JsonWriter j; + j.begin(); + j.writeString("event", failed ? "error" : it->event); + j.writeString("message", it->result->done ? it->result->message : "Savestate operation was dropped"); + if (failed) { + j.writeInt("level", (int)LogLevel::LERROR); + } + if (!it->ticket.empty()) { + j.writeRaw("ticket", it->ticket); + } + j.end(); + ws->Send(j.str()); + it = waiting_.erase(it); + } +} + static uint32_t GetOwnProcessID() { #if PPSSPP_PLATFORM(UWP) return (uint32_t)GetCurrentProcessId(); @@ -57,15 +170,16 @@ static uint32_t GetOwnProcessID() { } DebuggerSubscriber *WebSocketGameInit(DebuggerEventHandlerMap &map) { + auto p = new WebSocketGameState(); map["game.reset"] = &WebSocketGameReset; map["game.status"] = &WebSocketGameStatus; - map["game.state.load"] = &WebSocketGameStateLoad; - map["game.state.save"] = &WebSocketGameStateSave; + map["game.state.load"] = [p](DebuggerRequest &req) { p->StateLoadSave(req, false); }; + map["game.state.save"] = [p](DebuggerRequest &req) { p->StateLoadSave(req, true); }; map["game.speed.get"] = &WebSocketGameSpeedGet; map["game.speed.set"] = &WebSocketGameSpeedSet; map["version"] = &WebSocketVersion; - return nullptr; + return p; } // Reset emulation (game.reset) @@ -128,75 +242,6 @@ void WebSocketGameStatus(DebuggerRequest &req) { }); } -// Load a savestate file (game.state.load) -// -// The load is queued, and happens at the end of the next frame the CPU runs, so follow this with -// something that runs it, like cpu.runUntilTime. -// -// Parameters: -// - path: string, path to the .ppst file. -// -// Response (same event name) with no extra data, once queued, or an error if the network or -// achievements hardcore mode refuses it. -void WebSocketGameStateLoad(DebuggerRequest &req) { - std::string path; - if (!req.ParamString("path", &path)) - return; - - bool running = false; - bool queued = false; - Core_RunOnCPUThread([&] { - running = PSP_GetBootState() == BootState::Complete; - if (running) { - queued = SaveState::Load(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { - if (status == SaveState::Status::FAILURE) { - ERROR_LOG(Log::System, "game.state.load: %.*s", STR_VIEW(message)); - } - }); - } - }); - if (!running) - return req.Fail("Game not running"); - if (!queued) { - return req.Fail("Could not queue savestate load"); - } - req.Respond(); -} - -// Save a savestate file (game.state.save) -// -// Like game.state.load, the save is queued and happens at the end of the next frame the CPU runs. -// -// Parameters: -// - path: string, path to write the .ppst file to. -// -// Response (same event name) with no extra data, once queued, or an error if the network or -// achievements hardcore mode refuses it. -void WebSocketGameStateSave(DebuggerRequest &req) { - std::string path; - if (!req.ParamString("path", &path)) - return; - - bool running = false; - bool queued = false; - Core_RunOnCPUThread([&] { - running = PSP_GetBootState() == BootState::Complete; - if (running) { - queued = SaveState::Save(Path(path), -1, [](SaveState::Status status, std::string_view message, std::string_view) { - if (status == SaveState::Status::FAILURE) { - ERROR_LOG(Log::System, "game.state.save: %.*s", STR_VIEW(message)); - } - }); - } - }); - if (!running) - return req.Fail("Game not running"); - if (!queued) { - return req.Fail("Could not queue savestate save"); - } - req.Respond(); -} - // Percentages are relative to 60 FPS, matching how the in-app settings present the alternative // speeds (see GameSettingsScreen.cpp) - so a client and the UI agree on what "200%" means. static int PercentToFps(int percent) { diff --git a/Core/Debugger/WebSocket/GameSubscriber.h b/Core/Debugger/WebSocket/GameSubscriber.h index 220ba2ecf2..68943c1af7 100644 --- a/Core/Debugger/WebSocket/GameSubscriber.h +++ b/Core/Debugger/WebSocket/GameSubscriber.h @@ -23,8 +23,6 @@ DebuggerSubscriber *WebSocketGameInit(DebuggerEventHandlerMap &map); void WebSocketGameReset(DebuggerRequest &req); void WebSocketGameStatus(DebuggerRequest &req); -void WebSocketGameStateLoad(DebuggerRequest &req); -void WebSocketGameStateSave(DebuggerRequest &req); void WebSocketGameSpeedGet(DebuggerRequest &req); void WebSocketGameSpeedSet(DebuggerRequest &req); void WebSocketVersion(DebuggerRequest &req); diff --git a/docs/WebSocketDebugger.md b/docs/WebSocketDebugger.md index 4054ae7a15..3ca6b81899 100644 --- a/docs/WebSocketDebugger.md +++ b/docs/WebSocketDebugger.md @@ -271,7 +271,7 @@ file - this is just an index. | Category | Events | File | |---|---|---| -| Game/version | `game.reset`, `game.status`, `game.state.load` (queue loading a `.ppst` file, applied at the end of the next frame the CPU runs), `game.state.save` (the same for saving one), `game.speed.get/set` (emulation speed - unlimited fast-forward, or a percentage of 60 FPS; see below), `version` | `GameSubscriber.cpp` | +| Game/version | `game.reset`, `game.status`, `game.state.load` (queue loading a `.ppst` file, applied at the end of the next frame the CPU runs; with `wait: true` the response comes once it's done, or as an error if it failed), `game.state.save` (the same for saving one), `game.speed.get/set` (emulation speed - unlimited fast-forward, or a percentage of 60 FPS; see below), `version` | `GameSubscriber.cpp` | | CPU core | `cpu.stepping`, `cpu.resume`, `cpu.status` (reports `ticks` plus `us`, emulated microseconds, and `clockHz` - use `us` to line up with wall-clock timings, since games change the clock frequency and the ticks-per-second ratio isn't fixed), `cpu.getAllRegs`, `cpu.getReg`, `cpu.setReg`, `cpu.evaluate` | `CPUCoreSubscriber.cpp` | | Stepping | `cpu.stepInto`, `cpu.stepOver`, `cpu.stepOut`, `cpu.runUntil`, `cpu.runUntilTime` (run until a point in emulated time - `us` absolute or `relativeUs` from now - and break there; this is how to get a scripted repro reproducibly "N seconds into the game" instead of polling `cpu.status` in a loop), `cpu.nextHLE` | `SteppingSubscriber.cpp` | | Breakpoints | `cpu.breakpoint.add/update/remove/list`, `memory.breakpoint.add/update/remove/list`, `cpu.regBreakpoint.add/update/remove/list` (break when a register is written to, by any instruction anywhere - currently GPRs only; interpreter-only, no effect under a JIT backend) | `BreakpointSubscriber.cpp` |