🕹️ PSP-Programming

C and SDL2 homebrew you can build for a PlayStation Portable.
The psp_projects/ folder is a set of PSPSDK and SDL2 samples, each with its own build notes, plus a minimal rust-psp crate. A VS Code extension and a Model Context Protocol server live in this repo for local use. Marketplace publishing for the extension is still on the roadmap.

_{If a sample here gets an EBOOT onto your PSP, a star helps the next person find it.}

---

Start here: Hello World (PSPSDK debug screen) and SDL2 square (one source tree for PSP and desktop). Follow the README in the sample folder. The command-line steps below match those tutorials.

On screen

Screenshots from the sample folders, as run in PPSSPP. Open a tile for that sample's tutorial.

3D Cube C / GU · analog rotate	Texture Map C / GU · UV binding	Colored Triangle C / GU	Sprite C / GU · PNG texture
SDL2 TTF SDL2_ttf · PSP and desktop	SDL2 Image SDL2_image · PNG	SDL2 Square SDL2 · PSP and desktop	SDL2 Mixer SDL2_mixer · pause and resume
Audio Synth native audio · sine, square, triangle	Controller C / buttons and analog	Rectangle C / GU primitive	Hello World C / debug screen

Also under psp_projects/

Project	What is in the folder
debug_screen_colors_psp	Debug-screen colors, kernel callbacks, and controller exit. No screenshot is checked in.
rust_sample_psp	Minimal rust-psp 0.3 crate: #![no_std], home button enabled, one vblank wait.
crossplay_net_psp	Early UDP sketch that uses the Wi-Fi guard in shared/. Finished cross-play is still on the roadmap.

---

Build

Command line

1. Navigate to a project: cd psp_projects/hello_world_psp
2. Generate build files (run one of these from the project directory):
   • For PSP: mkdir build && cd build && psp-cmake ..
   • For desktop SDL2 samples (sdl_square_psp, sdl_image_psp, sdl_mixer_psp, sdl_ttf_psp): mkdir build && cd build && cmake ..
3. Compile: make
4. Deploy:
   • On Emulator: Launch build/EBOOT.PBP in PPSSPP.
   • On Physical PSP: Copy build/EBOOT.PBP to X:/PSP/GAME/<PROJECT_NAME>/EBOOT.PBP.

psp-cmake is the same entry the GitHub Actions workflow uses. Several sample READMEs also show cmake .. -DCMAKE_TOOLCHAIN_FILE=~/pspdev/psp/share/pspdev.cmake followed by cmake --build .. Either PSP form is fine when the PSPSDK is on your machine. Per-sample notes (assets, controls, and the desktop packages to install) stay in that sample's README.

VS Code extension

The extension source and a local package are in extensions/vscode-psp-toolkit/. Install that package, then use the title-bar buttons. Publishing to the Marketplace is still on the roadmap.

code --install-extension extensions/vscode-psp-toolkit/vscode-psp-toolkit-1.0.0.vsix

1. Open this repository in VS Code or Antigravity.
2. Open any source file in psp_projects/<project_name>/.
3. Click the device icon in the editor title bar for the in-editor preview.
4. Click the play icon, or run PSP: Run in PPSSPP, to build and launch desktop PPSSPP.

The preview switches among frameless, PSP-1000, PSP Go, and PSP Street frames. Its screen is a built-in canvas scene: the D-pad (or arrow keys) moves it, and the face buttons change its color. The play command is what builds the open sample and starts PPSSPP. It looks for CMakeLists.txt, Cargo.toml, or build.zig above the active file.

PSP: Auto-Install PPSSPP & Tools checks a few known PPSSPP paths, then tries winget (Windows), brew (macOS), or flatpak (Linux). PSP: Open Dev Studio Dashboard opens the dashboard page shipped with the extension. setup_windows.ps1 installs PPSSPP with winget when it is missing and installs this same .vsix.

---

Also in this repo

Hardware helpers

shared/ targets the PSP-1000 32MB baseline and exposes pspCompatHasExtendedRam() and pspCompatHasWifi() so a build can scale on 64MB models and skip Wi-Fi init on the Street (E1000).

PS2-to-PSP notes

PS2 to PSP porting notes compare the Emotion Engine and Allegrex: 128-bit SIMD versus the 32-bit VFPU, 4MB GS eDRAM versus 2MB GE eDRAM, and the shared little-endian MIPS layout.

CI

.github/workflows/build.yml runs on pushes to main, on pull requests, and on manual dispatch. The pspdev/pspdev container builds every psp_projects/* directory that has a CMakeLists.txt and uploads EBOOT.PBP files as the psp-homebrew-nightly-eboot-pack artifact (kept for 14 days). The rust-psp sample has no CMakeLists, so this workflow skips it.

MCP server

mcp-server-psp/ is a stdio JSON-RPC server (tools/list, tools/call) for an agent on your machine. It is not a published package.

Tool	What the handler does
psp_hardware_lint	Reads the snippet for sceDisplayWaitVblankStart or SDL_RenderPresent, for a Home-button exit callback, and for optional texture width/height (power of two, max 512).
ps2_to_psp_transpile_advice	Returns a short checklist: 128-bit EE ops toward the VFPU, GS 4MB toward GE 2MB, little-endian struct layout, and 640×448 toward 480×272.
psp_scaffold_project	Returns a status payload naming the requested language (c, sdl2, rust, or zig). Copy a folder under psp_projects/ when you want a real tree.
psp_launch_emulator	Returns a status payload naming the project path. Launching PPSSPP is the play command above, or opening build/EBOOT.PBP yourself.

graph LR
    subgraph Samples ["psp_projects"]
        C["C and SDL2 samples"]
        Rust["rust-psp sample"]
    end
    subgraph Host ["On your machine"]
        Ext["vscode-psp-toolkit"]
        Preview["Handheld-frame preview"]
        PPSSPP["PPSSPP"]
        MCP["mcp-server-psp"]
    end
    subgraph Actions ["GitHub Actions"]
        Docker["pspdev/pspdev"]
        Pack["EBOOT.PBP artifact"]
    end
    C --> Ext
    Ext --> Preview
    Ext --> PPSSPP
    C --> MCP
    C --> Docker --> Pack
    Pack --> PPSSPP
    Rust --> Ext

Loading

---

Roadmap

• CI builds: CMake samples compile in pspdev/pspdev, with EBOOT.PBP artifacts attached to the workflow run.
• PS2-to-PSP notes: Architecture comparison for Allegrex porting work.
• 32MB baseline helpers: shared/ model, RAM, and Wi-Fi checks.
• In-repo MCP server: hardware lint and a PS2-to-PSP checklist over stdio.
• In-repo VS Code extension: local .vsix, handheld-frame preview, and PPSSPP launch.
• Marketplace publish: list the extension so install does not depend on the .vsix in this repo.
• Windows installer: setup_windows.ps1 covers PPSSPP and the local extension; a fuller toolchain installer is still open.
• PSP and PC cross-play: crossplay_net_psp is an early sketch, not a finished multiplayer demo.

Acknowledgments

• Special thanks to the PSPDev Community, the developers of rust-psp and Zig-PSP, and the PPSSPP project.
• Created and maintained by Robert Fernandez.
• MIT License.