debianito-post-install/docs/retroarch.md

Installing New Cores in RetroArch on Debian

RetroArch installed via the official Debian repositories (apt) has a few key restrictions: the internal core downloader and updater are disabled by default, and cores are stored in system‑wide, read‑only directories. This guide explains two reliable ways to add new emulation cores (e.g., PPSSPP, Dolphin, MAME) to your Debian system, along with the necessary supporting files and configuration tweaks.

---

Understanding RetroArch’s Directory Structure on Debian

When installed via apt, RetroArch uses these locations:

Component	Default Path (system‑wide)
Cores (.so files)	/usr/lib/x86_64-linux-gnu/libretro/
Core info (.info files)	/usr/share/libretro/info/
System/BIOS/Assets	~/.config/retroarch/system/ (user‑writable)
Saves, States, Config	~/.config/retroarch/ (user‑writable)

Because the core and info directories are owned by root, you cannot write to them without sudo.
You have two options:

1. Manual installation: download cores and info files yourself and copy them with sudo.
2. Reconfigure RetroArch to use user‑writable folders, then use the built‑in Core Downloader.

Both methods work; choose the one that suits you best.

---

Method 1: Manual Core Installation (Recommended for Reliability)

This method works for any core, even when the online updater is blocked.

1. Download and Install the Core (.so)

The core is a shared library. For 64‑bit Linux, get it from the official Libretro buildbot:

# Example: PPSSPP core
wget https://buildbot.libretro.com/nightly/linux/x86_64/latest/ppsspp_libretro.so.zip
unzip ppsspp_libretro.so.zip
sudo mv ppsspp_libretro.so /usr/lib/x86_64-linux-gnu/libretro/
rm ppsspp_libretro.so.zip

Replace ppsspp with any core name: e.g., mame_libretro, dolphin_libretro, etc.
Browse all available cores at:
https://buildbot.libretro.com/nightly/linux/x86_64/latest/

2. Download and Install the Core Info (.info)

RetroArch will not recognise the core without its corresponding .info file.

wget https://raw.githubusercontent.com/libretro/libretro-core-info/master/ppsspp_libretro.info
sudo mkdir -p /usr/share/libretro/info/
sudo mv ppsspp_libretro.info /usr/share/libretro/info/

The .info files for all cores are maintained at:
https://github.com/libretro/libretro-core-info
You can also download directly: https://raw.githubusercontent.com/libretro/libretro-core-info/master/<core_name>.info

---

Method 2: Enable the Built‑in Core Downloader

If you prefer using RetroArch’s graphical interface to download cores, you can change the core directories to writable locations.

Step 1: Edit RetroArch Configuration

Create or edit ~/.config/retroarch/retroarch.cfg and add these lines:

libretro_directory = "~/.config/retroarch/libretro/"
libretro_info_path = "~/.config/retroarch/libretro-info/"
menu_show_core_updater = "true"

Now create the directories:

mkdir -p ~/.config/retroarch/libretro
mkdir -p ~/.config/retroarch/libretro-info

Step 2: Update Core Info Files

• Launch RetroArch.
• Go to Online Updater → Update Core Info Files.
• Wait for the update to complete.

Step 3: Download Cores

• Go to Online Updater → Core Downloader.
• Select the core you want (e.g., PPSSPP).
• The core will be downloaded to your user directory and will appear in the core list.

⚠️ Note: Some cores may require additional system files (BIOS/assets). These are still placed in ~/.config/retroarch/system/. You’ll need to obtain them separately (see below).

---

Essential Configuration for Graphics

The default video driver (gl) often causes black screens or crashes with many cores (especially PPSSPP). Change the driver to vulkan (preferred) or glcore.

1. In RetroArch, go to Settings → Drivers → Video.
2. Select vulkan (or glcore if Vulkan is not available).
3. Return to the main menu, go to Configuration File → Save Current Configuration.
4. Restart RetroArch for the change to take effect.

If you’re on older hardware, you may need to install Vulkan drivers:
sudo apt install mesa-vulkan-drivers

---

Installing Additional System Files (Assets / BIOS)

Some emulators require extra files (fonts, sound banks, BIOS images) to work correctly. These always go into your user system directory:

~/.config/retroarch/system/

For PPSSPP, you need its asset bundle:

mkdir -p ~/.config/retroarch/system/PPSSPP
wget https://buildbot.libretro.com/assets/system/PPSSPP.zip
unzip PPSSPP.zip -d ~/.config/retroarch/system/

After extraction, you should see subfolders like flash0/, lang/, themes/, etc.

For other systems (e.g., Dolphin, PCSX2), check the official Libretro documentation for required BIOS files and place them in the appropriate subdirectory under system/.
You can find many asset packs at:
https://buildbot.libretro.com/assets/system/

---

ROM / Game File Formats

• Supported formats for PPSSPP: .iso, .cso, .chd, .pbp.
• Always decompress your ROMs: do not leave them in .zip, .rar, or .7z archives; the cores cannot read compressed archives directly.

---

Useful References

Resource	URL
Core builds (nightly, Linux x86_64)	https://buildbot.libretro.com/nightly/linux/x86_64/latest/
Core info files (GitHub)	https://github.com/libretro/libretro-core-info
System assets (BIOS, firmware, etc.)	https://buildbot.libretro.com/assets/system/
Official RetroArch documentation	https://docs.libretro.com/
Debian Wiki: RetroArch	https://wiki.debian.org/RetroArch

---

Final Notes

• The Debian package disables auto‑updates and the core downloader by default: this is intentional for stability.
• Manual installation (Method 1) is the most straightforward and works for any core, regardless of distribution restrictions.
• If you choose Method 2, remember that you may still need to manually place BIOS/asset files in ~/.config/retroarch/system/.
• Always test your video driver setting; vulkan is recommended for PPSSPP and other 3D‑heavy cores.