ppsspp-dfx

by AstralVoidZ

Overview Schema Source Related Servers Discussions Admin

Python

Local

ppsspp_step

Control PPSSPP CPU run state for debugging: pause, resume, reset, run until address, step to next HLE.

Instructions

PURPOSE: Aggregate CPU run-state control (pause / resume / reset / run_until / next_hle).

USAGE: action='pause' / 'resume' / 'reset' / 'next_hle' take only session_id (optional when exactly one session is active); 'run_until' requires address.

NOTE (v0.1.6): single-stepping (into/over/out) moved to ppsspp_batch_step's cpu_step step type — this tool no longer accepts those actions.

ROUTING: single run-state operations -> here (run_until for run-to-address); multi-step press/wait/probe sequences and cpu_step -> ppsspp_batch_step. BEHAVIOR: STATE-CHANGE. Advances or changes CPU run state. 'reset' reboots the game (lost in-memory state). 'run_until' sets a temp breakpoint and resumes.

RETURNS: {action, address, pc, ticks, reason, related_address}. pc is stepping-verified (HIGH trust) for 'pause'; for 'resume' pc/ticks are a best-effort LOW-trust cpu.status snapshot of the running CPU (0/0.0 if that read failed); 'reset' reports 0.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`action`	Yes	CPU step / run-state operation. Valid values: - 'pause': pause CPU (enter stepping mode). - 'resume': resume CPU (exit stepping mode); the response pc/ticks are a LOW-trust snapshot of the running CPU (inaccurate unless stepping), not a precise resume location. - 'reset': reset the game (reboot). - 'run_until': run until the specified address is reached (requires address). - 'next_hle': step to next HLE callback. NOTE: single-stepping (into/over/out) lives in ppsspp_batch_step as the 'cpu_step' step type (mode='into'\|'over'\|'out', count 1..1000) — it requires the CPU to enter stepping mode, which the executor handles automatically.
`address`	No	Required for action='run_until'. Target address, as a hex string (e.g. '0x08804000'). Not used by the other actions. The schema default of '0x0' exists for legacy callers -- do NOT rely on it when the action is 'run_until'. run_until is fire-and-forget: it returns immediately with no hit confirmation — poll PC or set a breakpoint to observe arrival.	0x0
`session_id`	No	Active session ID; omit to auto-resolve when exactly one session is active.

Output Schema

TableJSON Schema

Name	Required	Description
`pc`	Yes	Program counter after step, hex string. For into/over/out/run_until/next_hle this comes from the cpu.stepping broadcast. For pause, extracted via safe_get_pc after CPU enters stepping. For resume, a best-effort LOW-trust cpu.status snapshot of the running CPU (inaccurate unless stepping — CPUCoreSubscriber.cpp:105). '0x00000000' for reset.
`ticks`	Yes	CPU ticks at step completion (from cpu.stepping broadcast). For resume, a best-effort LOW-trust cpu.status snapshot. 0.0 for pause/reset.
`action`	Yes	'into' / 'over' / 'out' / 'pause' / 'resume' / 'reset' / 'run_until' / 'next_hle'.
`reason`	Yes	Step reason from cpu.stepping broadcast (e.g. 'cpu.stepInto'). Empty for pause/resume/reset.
`address`	Yes	Target address for run_until, hex string (e.g. '0x08804000'); '0x00000000' for other actions.
`related_address`	Yes	Related address for temporary breakpoints, hex string. '0x00000000' when absent.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.1.7Oct 7, 2026

changedInput schema / properties / action / description

Previous value: -"CPU step / run-state operation. Valid values:\n- 'pause': pause CPU (enter stepping mode).\n- 'resume': resume CPU (exit stepping mode).\n- 'reset': reset the game (reboot).\n- 'run_until': run until the specified address is reached (requires address).\n- 'next_hle': step to next HLE callback.\nNOTE: single-stepping (into/over/out) lives in ppsspp_batch_step as the 'cpu_step' step type (mode='into'|'over'|'out', count 1..1000) — it requires the CPU to enter stepping mode, which the executor handles automatically."New value: +"CPU step / run-state operation. Valid values:\n- 'pause': pause CPU (enter stepping mode).\n- 'resume': resume CPU (exit stepping mode); the response pc/ticks are a LOW-trust snapshot of the running CPU (inaccurate unless stepping), not a precise resume location.\n- 'reset': reset the game (reboot).\n- 'run_until': run until the specified address is reached (requires address).\n- 'next_hle': step to next HLE callback.\nNOTE: single-stepping (into/over/out) lives in ppsspp_batch_step as the 'cpu_step' step type (mode='into'|'over'|'out', count 1..1000) — it requires the CPU to enter stepping mode, which the executor handles automatically."

changedInput schema / properties / address / description

Previous value: -"Target address, as a hex string (e.g. '0x08804000'). Required for action='run_until'; ignored for all other actions. run_until is fire-and-forget: it returns immediately with no hit confirmation — poll PC or set a breakpoint to observe arrival."New value: +"Required for action='run_until'. Target address, as a hex string (e.g. '0x08804000'). Not used by the other actions. The schema default of '0x0' exists for legacy callers -- do NOT rely on it when the action is 'run_until'. run_until is fire-and-forget: it returns immediately with no hit confirmation — poll PC or set a breakpoint to observe arrival."

changedOutput schema / properties / pc / description

Previous value: -"Program counter after step, hex string. For into/over/out/run_until/next_hle this comes from the cpu.stepping broadcast. For pause, extracted via safe_get_pc after CPU enters stepping. '0x00000000' for resume/reset (no trustworthy PC available)."New value: +"Program counter after step, hex string. For into/over/out/run_until/next_hle this comes from the cpu.stepping broadcast. For pause, extracted via safe_get_pc after CPU enters stepping. For resume, a best-effort LOW-trust cpu.status snapshot of the running CPU (inaccurate unless stepping — CPUCoreSubscriber.cpp:105). '0x00000000' for reset."

changedOutput schema / properties / ticks / description

Previous value: -"CPU ticks at step completion (0.0 for pause/resume/reset)."New value: +"CPU ticks at step completion (from cpu.stepping broadcast). For resume, a best-effort LOW-trust cpu.status snapshot. 0.0 for pause/reset."

Changed3 schema fields changedv0.1.6Oct 4, 2026

changedInput schema / properties / action / description

Previous value: -"CPU step / run-state operation. Valid values:\n- 'into': step into (including delay slot).\n- 'over': step over (skip function calls).\n- 'out': step out of current function.\n- 'pause': pause CPU (enter stepping mode).\n- 'resume': resume CPU (exit stepping mode).\n- 'reset': reset the game (reboot).\n- 'run_until': run until the specified address is reached (requires address).\n- 'next_hle': step to next HLE callback."New value: +"CPU step / run-state operation. Valid values:\n- 'pause': pause CPU (enter stepping mode).\n- 'resume': resume CPU (exit stepping mode).\n- 'reset': reset the game (reboot).\n- 'run_until': run until the specified address is reached (requires address).\n- 'next_hle': step to next HLE callback.\nNOTE: single-stepping (into/over/out) lives in ppsspp_batch_step as the 'cpu_step' step type (mode='into'|'over'|'out', count 1..1000) — it requires the CPU to enter stepping mode, which the executor handles automatically."

changedInput schema / properties / action / enum

Previous value: -[
-  "into",
-  "over",
-  "out",
-  "pause",
-  "resume",
-  "reset",
-  "run_until",
-  "next_hle"
-]New value: +[
+  "pause",
+  "resume",
+  "reset",
+  "run_until",
+  "next_hle"
+]

changedInput schema / properties / address / description

Previous value: -"Target address, as a hex string (e.g. '0x08804000'). Required for action='run_until'; ignored for all other actions."New value: +"Target address, as a hex string (e.g. '0x08804000'). Required for action='run_until'; ignored for all other actions. run_until is fire-and-forget: it returns immediately with no hit confirmation — poll PC or set a breakpoint to observe arrival."

First observedv0.1.0Sep 16, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Declares the tool as STATE-CHANGE, discloses that 'reset' reboots the game and loses in-memory state, that 'run_until' sets a temp breakpoint and is fire-and-forget with no hit confirmation, and that resume pc/ticks are LOW-trust. This goes well beyond the readOnly/destructive/idempotent annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with PURPOSE/USAGE/ROUTING labels and tightly organized, but it is dense and partially duplicates the enum descriptions in the schema, which costs a little economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, routing, per-action behavior, and even return-field trust levels. With an output schema already present, nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3, but the description adds genuine nuance: the schema default '0x0' should not be relied on for run_until, run_until returns immediately with no confirmation, and resume pc/ticks are a best-effort snapshot. This meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Aggregate CPU run-state control') and enumerates the exact actions. It also contrasts itself with the sibling ppsspp_batch_step, so an agent can distinguish the two without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: single run-state operations go here, multi-step press/wait/probe sequences and cpu_step go to ppsspp_batch_step. It also states per-action requirements ('run_until' requires address) and the session_id omission rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.