PS5_RetroArch/README.md

RetroArch for PS5

Your collection on the console. Your controls in the browser.

Native Vulkan rendering · Fifteen release cores · A local WebUI

Download a release · Get started · Supported systems · Build from source

WebUI Overview · Open http://<PS5-IP>:6769 while RetroArch is running.
_{Replace <PS5-IP> with your console’s local address. Use a browser on the same network.}

Choose a frontend · RetroArch’s XMB or EmulationStation, both playing every game through RetroArch.
_{Square remembers your choice. Hold L1 while the title starts to come back to this screen.}

A native RetroArch homebrew title for jailbroken PlayStation 5 consoles, made by Mihawk. Play through XMB on your TV, then upload content, browse your library and adjust settings from your phone or computer. The purple WebUI starts with RetroArch and closes with it.

v0.6.7-alpha.6 opens on a pre-screen that starts RetroArch or EmulationStation, adds up to four controllers and verified updates from the WebUI, and fixes the Manual Scan crash. This is an alpha release; compatibility varies by core and workload. See the release notes for the tested scope.

Get started

1. Install the complete title folder. Extract a release and copy its PPSA99169 folder to the location used by your homebrew launcher. The tested location is /data/homebrew/PPSA99169/. A source build produces the same folder in dist/. A compatible jailbreak and launcher must already be set up.
2. Open the title and choose a frontend. The pre-screen starts RetroArch or EmulationStation; with Remember (Square) on, the title opens on your choice from then on, and the WebUI's Start with setting changes it. RetroArch creates its writable folders and initial configuration; existing settings are preserved. XMB is the default menu; RGUI is also available.
3. Open the WebUI. Visit http://<PS5-IP>:6769 on the same network. Choose a destination and drop your content into Upload content, or use FTP.
4. Load content on the console. Select the matching core and your file. Install any required BIOS files first, using the locations below.

No games, BIOS files, firmware or decryption keys are included. Use your own legally obtained backups and system files dumped from hardware you own. Piracy is not condoned; requests for these files are not welcome in issues or discussions.

A browser companion, built in

Page	What you can do
Overview	Check release status, read what’s new, upload content and reach your library and quick settings. Development builds identify themselves honestly.
Content	Browse folders, create subfolders, upload and download files. Uploads stream to storage, can be cancelled and never overwrite an existing filename.
Transfers	Follow upload progress and results for this browser session. Downloads use your browser’s download manager.
Settings	Edit global preferences or select a core profile. Guided categories explain each setting and offer supported choices; Advanced exposes technical keys and manual values.

Guides cover all 15 release cores, even before their first launch. Global preferences cover Video, Audio, Input, Saving, System and Interface. Core categories follow each emulator’s options. Runtime-specific choices, including BIOS lists and arcade switches, appear when the core registers them.

Save settings, then restart RetroArch to apply them. Global preferences, core options and per-core RetroArch overrides are separate. Existing game or folder overrides can take precedence. Unsaved edits survive switching categories or Guided/Advanced mode. WebUI light/dark appearance changes immediately.

The interface, fonts and artwork are served locally. Release checks and update downloads need internet access. Uploads are limited to the content folder and 64 GiB per file. Available storage is not reported because the console API does not provide a measured value.

New in source builds after Alpha 6: Update RetroArch downloads the newest published release, including alphas, directly to your console. It checks the ZIP checksum and every packaged file before enabling Install and close RetroArch. Save your progress, install, wait for the application to close, then reopen it. Content, saves, settings and existing custom BIOS/effect files are preserved. Keep enough free space for both the downloaded ZIP and its extracted files. Failed installs attempt to restore the previous files; a power loss that prevents the application from launching can still require reinstalling the release manually.

The new Alerts panel lists missing required BIOS/system files by installed core and shows the configured location. Choose Recheck after adding files. It checks presence, not BIOS authenticity; regional requirements may not apply to your content. /app0 means the RetroArch installation folder. Optional firmware is excluded from these checks. These controls are not in the published Alpha 6 package; install an updated source build once to enable future WebUI updates.

The WebUI is a local HTTP service without a login. Use a trusted network and do not forward port 6769 to the internet.

Supported systems

Release builds contain the following native cores. “GPU” means the emulator renders through Vulkan; “software” means RetroArch presents the core’s frames through Vulkan. These are supported systems, not a promise that every title works.

Systems	Core	Rendering
NES / Famicom	FCEUmm	Software
Game Boy / Game Boy Color / Game Boy Advance	mGBA	Software
SNES / Super Famicom	Snes9x	Software
Arcade, including Neo Geo and Sega System 16/32	FinalBurn Neo	Software
Mega Drive / Genesis, Master System, Game Gear, SG-1000, Sega CD	Genesis Plus GX	Software
PlayStation Portable	PPSSPP	GPU
GameCube / Wii	Dolphin	GPU
PlayStation 2	LRPS2	GPU
PlayStation	Beetle PSX HW	GPU
Nintendo 64	Mupen64Plus-Next	GPU
Sega Saturn	Beetle Saturn	Software
Commodore 64	VICE x64sc	Software
Arcade	MAME	Software
Nintendo DS	DeSmuME	Software
Nintendo 3DS	Azahar	GPU

Use matching arcade sets: MAME currently targets 0.289, and FBNeo requires sets compatible with its pinned version. Azahar requires decrypted content. Core binaries must be built for this native SDK and loader; desktop cores or cores from another PS5 distribution are not interchangeable.

Balanced graphics for a 4K display

RetroArch presents at the display resolution. Internal rendering is chosen to leave room for emulation and memory use; it need not reach native 4K. Saved core, folder and game options take priority over these compiled defaults.

Core	Default internal resolution	Anti-aliasing
PPSSPP	6× · 2880 × 1632	8× MSAA
Dolphin	4×	No MSAA
LRPS2	4× · approximately 1440p	Core default
Beetle PSX HW	8×	MSAA off
Mupen64Plus-Next	4×	Core default
Azahar	6× · 2400 × 1440 top screen	Core default
DeSmuME	4× · 1024 × 768 per screen	Core default

Other cores retain native rendering, scaled for the display. MAME uses a 4K target for vector output; that path still needs console acceptance.

PPSSPP’s 6× / 8× MSAA default passed the recorded save/load checks. At 10× / 8× MSAA, the tested workload exhausted device memory. Failed framebuffer allocations are now cleaned up and retried once; an unrecoverable failure returns to the menu instead of using a missing image. This improves recovery, not the amount of memory available. Disabling MSAA leaves more headroom.

To adopt these defaults on an existing installation, change the listed options in the WebUI or Quick Menu → Core Options. Reset Core Options resets every option for that core, so use individual controls if you want to keep other choices.

Shaders, filters and bezels

Release builds bundle offline Slang shaders, Mega Bezel, koko-aio and standard overlays. Load GPU presets through Quick Menu → Shaders, choose a CPU filter in Settings → Video, or choose artwork in Settings → On-Screen Display → On-Screen Overlay. CPU filters apply to software-rendered cores; hardware-rendered cores use GPU shaders.

The package retains the upstream collections and their notices. Exact versions, path corrections and the five upstream file exclusions are recorded in video-assets.json. Development overlay fixtures are excluded from both the staged title and its ZIP. Representative presets and overlay layouts have been tested on PS5. Bundling does not imply every preset is verified; see the release notes for limitations.

Your files

/app0 is the running title’s mount. Over FTP, use your installed title folder, usually /data/homebrew/PPSA99169/.

Folder or file	Purpose
content/	Your content; available to WebUI uploads and downloads
content/Saturn/	Saturn disc images; created automatically
system/	General BIOS and system data
system/Saturn/	Saturn BIOS files; created automatically
system/pcsx2/bios/	PlayStation 2 BIOS
system/fbneo/	FinalBurn Neo system files
cores/ and info/	Native cores and their metadata
config/retroarch.cfg	Live RetroArch configuration
config/webui.cfg	Saved global WebUI preferences
config/<core>/	Core options and RetroArch overrides
savefiles/ and savestates/	Save RAM and save states
shaders/shaders_slang/	GPU presets, including Mega Bezel and koko-aio
filters/	Built-in CPU filter configurations
overlays/	Standard overlay artwork and configurations
radv-shader-cache/	Reusable compiled graphics pipelines

Saturn setup: place mpr-17933.bin (US/Europe) or sega_101.bin (Japan) in system/Saturn/. Keep a disc’s .cue and all referenced tracks together, then load the .cue. The default system path is routed to the Saturn folder; an explicitly selected custom system directory remains unchanged.

Genesis Plus GX’s Sega CD BIOS files and Beetle PSX HW’s optional BIOS files belong in the general system folder, with the filenames listed by their metadata. BIOS uploads use FTP; the WebUI only exposes content/.

Ordinary scripted updates preserve content and saved settings. Back up your files before replacing or removing a title. The file browser has INTERNAL for the title folder and EXTERNAL for /mnt; the current title sandbox hides external mounts, so EXTERNAL may be empty.

What has been verified

Saturn now loads its BIOS from system/Saturn/. Console testing reached controlled gameplay with clean rendering and a normal exit. The fixes cover executable memory for its JITs and ownership of cropped video frames. This is a short gameplay check, not a full compatibility or long-session guarantee.

Native startup and exit, Vulkan presentation, controller input, stereo audio, configuration persistence and representative core loading have console evidence. Save-state and memory-pressure results cover the recorded workloads, not every core or firmware. Controller rumble uses synthesized DualSense haptics with an ordinary-rumble fallback; physical feel still awaits owner confirmation.

The title uses PS5_Vulkan’s RADV port. CPU and GPU allocations share the console’s direct-memory pool; each core does not receive a separate 11.65 GiB allowance. A selectable CPU video backend remains available. RetroAchievements and netplay remain disabled. Broader BIOS, disc swapping, shader-preset and long-session coverage is still in progress.

Recorded evidence accompanies verified changes. For a bug report, include the core, file format, settings and reproduction steps. Preserve retroarch.log and trace.txt before reopening RetroArch: the frontend log is replaced on each launch. Remove private paths, addresses and credentials before sharing captures.

---

Build from source

The current build uses Linux host tools and the project's cached public PS5 SDK. Start with bash tools/doctor.sh for host-tool checks. You also need curl, patch, pkg-config, ELF utilities such as readelf, and working host C/C++ compilers with sanitizer support for the tests. The target scripts currently use /usr/bin/clang through the SDK wrappers.

Prepare and build PS5_Vulkan following its own instructions, normally as a sibling directory:

workspace/
├── PS5_RetroArch/
├── PS5_Vulkan/       # The RADV release archive, its link recipe and dependencies
├── PS5_Mesa/         # My Mesa fork, which PS5_Vulkan builds RADV from
└── PS5_PayloadSDK/   # My payload SDK fork and its platform layer, at a pinned revision

The cores that needed changes for the console build from my forks of them (PS5_LRPS2, PS5_BeetlePSX, PS5_Mupen64Plus, PS5_BeetleSaturn, PS5_VICE, PS5_MAME, PS5_DeSmuME, PS5_Azahar with PS5_Dynarmic), each pinned by revision in its build script. The script uses the sibling checkout when there is one, and github.com/mihawk-99/<fork> otherwise.

The title build consumes PS5_Vulkan's RADV release archive (tools/build-radv.sh release there, built from PS5_Mesa at the revision it pins) and links it with that project's tools/radv-link.sh; it does not build the driver for you. PS5_VULKAN_DRIVER=ps5vk links ps5vk's driver, Vulkan runtime and shader-compiler archives instead, and RADV_ARCHIVE names another RADV archive. PS5_VULKAN_DIR can select an alternative checkout for the build; some host tests currently require the sibling layout above. Driver dependencies and setup requirements are documented in the driver repository.

From the RetroArch repository root:

make deps
export PS5_PAYLOAD_SDK="$PWD/.deps/native/ps5-payload-sdk"
export PS5_CLANG=/usr/bin/clang
bash tools/fetch-retroarch.sh
bash tools/build-title.sh     # Create the artifacts inspected by the host tests
bash tools/verify.sh

The five gates are format → unit → build → integration → evidence. The build pins RetroArch 1.22.2, fetches core sources/metadata with checked hashes, builds the frontend and fifteen cores, and stages the native title in dist/PPSA99169/. The initial dependency/source fetch requires network access.

For an already configured checkout:

bash tools/build-title.sh     # Build/stage the frontend and all shipped cores
make genesis-plus-gx         # Build and ABI-check one core only
# Other core targets: fceumm, mgba, snes9x, fbneo
bash tools/build-ppsspp.sh   # The larger cores have scripts of their own:
                             # build-ppsspp.sh, build-dolphin.sh, build-lrps2.sh,
                             # build-beetle-psx.sh, build-mupen64plus.sh,
                             # build-beetle-saturn.sh, build-vice.sh,
                             # build-mame.sh, build-desmume.sh, build-azahar.sh

When adding or updating a core, rebuild the title too: the frontend's native import table and build identity depend on the shipped core binaries. Source patches live in patches/; fetched and generated trees stay in ignored vendor/, .deps/, build/ and dist/ directories.

Authors and acknowledgements

This port builds on substantial upstream and PS5 homebrew work. Credits below identify project authors and teams; their repositories retain the full contributor lists and original notices.

Frontend, platform and graphics

Project / author	Contribution
Mihawk — PS5_RetroArch, PS5_Vulkan, PS5_Mesa, PS5_PayloadSDK	This native RetroArch port and core integration; the PS5 Vulkan drivers (the RADV port and ps5vk); the Mesa fork with the PS5 winsys; the payload SDK fork and its platform layer; the PS5 forks of the cores below
RetroArch / libretro contributors	Frontend, libretro API, menus, video pipeline and shared libraries
BlackBearReloaded — ProsperoLight	Project starting point and reference for native PS5 input and audio integration
BlackBearReloaded — PS5 Native App Boilerplate	Underlying native title tooling, ELF/FSELF conversion and runtime-shim foundation
John Törnblom and ps5-payload-dev contributors	Public PS5 Payload SDK, toolchain and API stubs; PacBrew ports infrastructure
John Törnblom / ps5-payload-dev — websrv	Reference for per-core fetch/build/stage scripts; this port uses a separate native title pipeline
BlackBearReloaded — ps5-opengl	Shader-compiler and graphics foundations consumed by PS5_Vulkan; not the active RetroArch video backend
Mesa contributors	RADV, the Vulkan driver the title renders through, with its ACO compiler, NIR, the Vulkan runtime and utilities
Khronos Group	Vulkan API headers and specification
RetroArch assets contributors and the M+ Fonts project	Packaged XMB assets and font; original notices retained
LLVM / Clang contributors, zlib authors Jean-loup Gailly and Mark Adler	Compilation and compression tooling

Emulator cores

Core	Authors / maintainers credited by upstream
FCEUmm	FCEU Team, CaH4e3 and contributors
mGBA	endrift and contributors
Snes9x	Snes9x Team and contributors
FinalBurn Neo	Team FBNeo and contributors
Genesis Plus GX	Charles MacDonald, Eke-Eke and contributors
PPSSPP	Henrik Rydgård and contributors
Dolphin, libretro/dolphin	Dolphin Emulator Project and contributors; libretro core maintainers
PCSX2, LRPS2	PCSX2 Dev Team and contributors; libretro LRPS2 maintainers
Beetle PSX HW, Beetle Saturn	The Mednafen authors and contributors; libretro Beetle maintainers
Mupen64Plus-Next	Mupen64Plus team and contributors; libretro core maintainers; ParaLLEl-RDP and ParaLLEl-RSP by Hans-Kristian Arntzen (Themaister) and contributors
VICE	The VICE Team and contributors; libretro core maintainers
MAME	MAMEdev and contributors
DeSmuME	DeSmuME team and contributors
Azahar, Dynarmic	Azahar contributors, building on Citra; Dynarmic by merryhime and contributors
libretro core-info	Metadata maintainers and contributors

License and third-party terms

This repository's own code is GPL-3.0-or-later (LICENSE). Most source files carry a copyright and SPDX notice; the ones that do not (for example src/memory_ps5.cpp and the build scripts in tools/) are under the same licence. Code inherited from BlackBearReloaded's ps5-native-app-boilerplate and ProsperoLight is Copyright (C) 2026 BlackBearReloaded, GPL-3.0-or-later. The title's sce_module/libc.prx is generated by this repository (runtime/).

Every built title folder carries LEGAL.txt (the legal notice above) and licenses/: the licence texts each part requires, and components.json, which ties every executable file to the source revision it was built from (tooling/notices/components.json). Each release also carries the source archives of everything in it. Releases up to v0.5.0-alpha.5 were published without licenses/.

The cores keep their own licences, and they differ:

Licence	Cores
GPL-2.0-or-later	FCEUmm, PPSSPP, Dolphin, Beetle PSX HW, Beetle Saturn, Mupen64Plus-Next (with MIT and LGPL parts), VICE, DeSmuME, Azahar (Dynarmic is 0BSD), MAME (as a whole; many files BSD-3-Clause)
GPL-3.0-or-later	LRPS2 (PCSX2)
MPL-2.0	mGBA
Non-commercial licences	Snes9x, FinalBurn Neo, Genesis Plus GX: they may not be sold or used commercially, and FBNeo's forbids asking for donations for a project that uses its code

Assets and fonts keep their licences too: the XMB theme is CC-BY-4.0 with the M+ font licence, PPSSPP's fonts are OFL-1.1, and Dolphin's Sys files carry theirs. The launcher backgrounds (sce_sys/pic0.dds, pic1.dds) are drawn by tools/make-title-art.py, under this repository's licence.

No games, BIOS files, firmware or keys are included, and piracy is not condoned. Use only legally obtained backups of games you own and system files dumped from hardware you own.

This is an independent homebrew project, not affiliated with or endorsed by Sony Interactive Entertainment, the Khronos Group or the libretro project. PlayStation and PS5 are Sony trademarks. Vulkan is a registered trademark of the Khronos Group Inc.; the RADV port this title uses is not a Khronos-conformant product (see PS5_Vulkan). RetroArch is the libretro project's name and logo, used here to name the frontend this port is built from.

made by Mihawk · Built on the work of the RetroArch, libretro and PS5 homebrew communities.