DOCSEARCHbyAlgolia
Submit Docs

PPSSPP Emulator

repository·master·Indexed 12 days ago

https://github.com/hrydgard/ppsspp

A high-performance, portable PlayStation Portable (PSP) emulator using High-Level Emulation (HLE). Includes documentation for building the emulator on iOS and macOS, contributing language translations, and using PPSSPPHeadless for automated testing, GE frame dump (.ppdmp) replay, and screenshot comparison in CI pipelines.

Tokens
24K
Snippets
65
Records
116
Agent score
93%

What's inside PPSSPP

  1. Overview of PPSSPP Emulator

    master

    PPSSPP is a fast and portable PlayStation Portable (PSP) emulator. It is an 'HLE' (High-Level Emulation) emulator, meaning it does not require a BIOS file to play games. Default settings are designed to provide a balance between compatibility and performance.

    Key Resources

  3. Compare Text Output

    master

    The --compare flag also performs line-based comparison of emulated debug output (via printf or sceIoWrite) against an .expected text file.

    • File Location: For .prx files, the tool looks for <filename>.expected.
    • Behavior: If a screenshot reference exists but no .expected file is found, the test passes as long as there is no unexpected text output.
    • Exit Codes: The process exits with 0 if all tests pass and 1 if any fail.

  4. Use the ImDebugger for PSP debugging

    master
    PPSSPP includes a new debugger called ImDebugger, built using the Dear ImGui library. It is designed for rapid development of debugging features and includes a functional GE (Graphics Engine) debugger for stepping through draw calls. Unlike the legacy Win32 debugger, ImDebugger is cross-platform and works on all supported platforms, though it may be difficult to use on touchscreen devices.

  5. Reference image specifications and MSE comparison

    master

    Framedump tests use PNG images for reference and comparison.

    Image Properties:

    • Format: PNG, 512×272 (representing a 480×272 display in a 512-wide framebuffer).
    • Orientation: Stored top-down (row 0 is the top of the screen).
    • Alpha Channel: The alpha channel is forced to 255 when writing PNGs to prevent transparency issues. To preserve alpha, pass the --screenshot-keep-alpha flag to the PPSSPPHeadless binary via a variant configuration.
    • Determinism: Images generated with --graphics=software are byte-identical on subsequent runs, allowing maxMse to be set to 0.

    Comparison Logic:

    • Comparison is performed using MSE (Mean Squared Error) over the R, G, and B channels per pixel. The alpha channel is ignored during comparison.
    • A FAIL status occurs on a mismatch, a crash, or a timeout.
    • If a FAIL occurs without an MSE report, it typically indicates the headless binary crashed before a screenshot could be taken.

  6. Configure HLE (High Level Emulation) modules

    master

    Users can now disable HLE on a per-module basis if the game provides the necessary module. This is particularly useful for fixing issues in games that ship with their own modules. Currently, this capability is enabled for:

    • sceCcc
    • scePsmf

  7. Replay GE Frame Dumps (.ppdmp)

    master

    A .ppdmp file is a recording of a single frame's GE graphics commands. When passed to PPSSPPHeadless:

    1. The GE commands are replayed through the selected GPU backend.
    2. The framebuffer is automatically captured (512×272 stride, 480×272 visible).
    3. The output can be saved or compared using screenshot flags.

    Output Formats:

    • BMP: 512×272 with 32-bit BGRA pixel data (fixed size: 557,110 bytes).
    • PNG: 512×272 RGBA.

  8. Message Protocol: Requests, Responses, and Errors

    master

    The debugger uses a request/response pattern for most operations, supplemented by unsolicited broadcast events.

    Requests

    Send a JSON object with an event name. You can include an optional "ticket" field (any JSON value). PPSSPP will echo this ticket back in the response, allowing you to correlate asynchronous responses with your requests.

    { "event": "cpu.status", "ticket": 123 }

    Responses

    Responses use the same event name as the request and include the echoed ticket.

    { "event": "cpu.status", "ticket": 123, "status": "running" }

    Errors

    Errors are sent using the error event.

    { "event": "error", "message": "Invalid address", "level": 2, "ticket": 123 }

    Error Levels (LogLevel):

    • 1: NOTICE
    • 2: ERROR
    • 3: WARN
    • 4: INFO
    • 5: DEBUG
    • 6: VERBOSE

  9. Define rendering variants and shared references

    master

    The variants object in the configuration allows you to run the same test dump through different rendering backends (e.g., OpenGL, Vulkan, Software). Each variant uses a suffix and a compare-suffix to manage output and reference matching.

    • suffix: Appended to the variant's output filenames (actuals, diffs, logs). Defaults to the variant name.
    • compare-suffix: Determines which reference image the variant compares against, using the pattern <name>-<compare-suffix>.png. Defaults to the suffix.

    Reference Generation Rule: Reference images are only automatically generated for variants where suffix == compare-suffix. This allows multiple hardware variants (like Vulkan or OpenGL) to share a single set of reference images generated by a deterministic software renderer.

    Shorthand Syntax: A plain string value in the variants map is shorthand for an object where suffix and compare-suffix both equal the key name.

    Example: Sharing Software references across Vulkan and OpenGL:

    "variants": {
	"soft": { "args": "--graphics=software" },
	"gl":   { "args": "--graphics=opengl", "compare-suffix": "soft" },
	"vul":  { "args": "--graphics=vulkan", "compare-suffix": "soft" }
}

  10. Use the Software Renderer for maximum compatibility

    master
    PPSSPP provides a software renderer to achieve 100% game compatibility. This is necessary for certain games that use rendering techniques that cannot be accurately emulated via hardware acceleration. The software renderer is also useful for running homebrew applications that mix software and accelerated rendering.

  11. Configure Infrastructure Multiplayer

    master
    PPSSPP supports Infrastructure multiplayer, which includes automatic DNS configuration. To use this feature, you must connect to a game that has an existing 'revival server'. Note that standard local multiplayer may require different configurations. For a list of supported servers, refer to the official PPSSPP documentation on infrastructure servers.

  12. Understand test diff output notation

    master

    When running with the --compare flag, the output shows a line-by-line diff between the real PSP output (the .expected file) and the PPSSPP output.

    PrefixMeaning
    OExpected-only: Line present in the .expected file but missing from PPSSPP output.
    EPPSSPP-only: Line produced by PPSSPP that was not in the .expected file.
    +Context: A line where both outputs matched, provided for context around a diff.
    =Match: (Only visible with --print-equal-lines) A line where both outputs matched.
    [r]Rescheduling: A rescheduling event occurred since the last line.
    [x]No Rescheduling: No rescheduling event occurred since the last line.