README — Overview

← POPSLoader docs · view on GitHub ↗

POPSLoader is a graphical PlayStation 2 homebrew launcher designed to easily browse and launch your PS1 games (using POPStarter) from various storage devices. It features a clean, responsive layout, cover art support, sound effects, an on-screen keyboard, and direct memory card exit shortcuts.

The current public release is BETA-12 (released 2026-06-18). Development continues on the BETA-13-PLAY branch (the BETA-12-PLAY branch is now frozen/archival); rolling test artifacts are published continuously (see Development & Building).

Highlights

POPSLoader's stable backbone, hardware-confirmed across an extended validation pass:

• Fixed HDD POPSTARTER Handoff (D-10): Resolved the long-standing "D-10" black-screen hang when launching games using an HDD-backed POPStarter configuration. Hardware-confirmed.
• Fixed Cross-Device POPSTARTER (D-14 / D-15): HDD-backed POPSTARTER with non-HDD games and non-HDD POPSTARTER with HDD games both launch cleanly. Hardware-confirmed.
• DKWDRV from Memory Card and custom HDD path: Both launch routes work — the MC route via a reboot-IOP path with synthesized argv, the HDD custom path via a partition-aware route. Hardware-confirmed.
• BOOT.ELF Exit from POPSLoader: Returns to wLaunchELF / BOOT.ELF via the embedded-loader route, including the previously broken HDD-launched case (U-10). Hardware-confirmed.
• Single-device Settings parity: Every install — USB / MX4SIO / MMCE and the internal HDD — saves settings to .pldrs next to the launcher. HDD installs write it on the HDD's own boot partition (read-write mount take-over), no mc0: fallback (see Settings Storage on HDD Installs).
• In-app HDD game hiding, PAL full-screen, BDMA + MC-folder controls: The newer Settings work — see the Settings section below.
• Polished User Interface: Layout alignment corrections, cleaner typography, dynamic menu box adjustments, text wrapping, and notification toast hardening.

ℹ️ Note
The canonical, always-current Known Issues list and hardware-verification status live in STATE.md > Known Issues (with the full ledger in QA_REGRESSION_MATRIX.md). The current open item is the config-specific "Failed to load HDD" from a non-HDD boot; the 2026-06 HDD/PAL/BDMA features are implemented and boot on PCSX2 (HDD confirmed read-write on hardware by provato) and are still validating on hardware.

Supported Devices

POPSLoader's main menu exposes the following backends:

• MMCE (Multi-Memory Card Emulator, e.g. MemoryCard PRO / SD2PSX)
• MX4SIO (SD card via memory card slot adapter)
• HDD (PFS) (internal HDD via the PS2 network/ATA adapter)
• USB (mass:)
• Disc (DKWDRV) (boot DKWDRV to play PS1 discs)

ℹ️ Note
The main menu also lists HDD (exFAT), i.Link, and SMB (v1), but these flows are not implemented yet — selecting them shows a "not implemented" notice. See Known Issues & Planned Improvements.

ℹ️ Note
Game compatibility and drive loading performance may vary depending on your specific console model, adapter type, and the quality of your POPStarter/POPS binaries.

Quick Install

To set up POPSLoader:

1. Download the Release: Download and extract the latest POPSLOADER.zip package.
2. Copy Launcher Files: Copy the PS1_POPSLOADER/ folder to the device or memory card from which you want to launch POPSLoader.
3. Place POPS Files: Put the PATCH_5.BIN file (included in the POPS/ directory of the ZIP) into your active POPS folder (see directory structures below).
4. Add POPStarter & POPS Files: Add your POPStarter executable (POPSTARTER.ELF) and the required POPS support files (IOPRP252.IMG, POPS.ELF, POPS.PAK, POPS_IOX.PAK) to your POPS folder. These copyrighted Sony POPS files are not included in the release package.
5. Add Games: Copy your PS1 game images in .VCD format into the same POPS folder. Keep filenames reasonably short — roughly 73 characters is the safe maximum for a standard POPS/ folder; longer names can fail to launch (see Troubleshooting).
6. Launch: Run POPSLOADER.ELF using wLaunchELF, Free McBoot, or your preferred ELF launcher.

Folder Layout

Ensure your directories and files match these paths exactly depending on your storage device:

USB / MX4SIO / MMCE Setup

Place all files on the root of your storage device (mass:/, mx4sio:/, mmce0:/, etc.) in a folder named POPS:

Internal HDD Setup

Place VCD game files inside your dedicated POPS partitions, and system binaries inside __common/POPS/:

Controls

Navigate POPSLoader using a standard PS2 controller.

Menus & Game List

On-screen Keyboard (Settings path editor)

Settings

Press Start on the menu to open Settings; changes save when you confirm. Settings persist per install with single-device parity — every device, including the internal HDD, saves a .pldrs file next to the launcher. HDD installs write that sidecar on the HDD boot partition itself (POPSLoader remounts its own boot partition read-write to do so — there is no mc0: fallback for HDD installs). For the full rules, see STATE.md > Settings.

Startup

Carousel Devices

Game List

Other settings

• Profile / POPSTARTER mode / POPSTARTER path — which POPSTARTER.ELF to use (a per-device profile, or a custom path).
• DKWDRV Path — path to DKWDRV.ELF used by the Disc option.
• Video Standard — Auto (default — matches your console's region) / NTSC / PAL. On PAL the UI now renders natively at 640×512 so it fills the whole screen with no letterbox (NTSC is 640×448). A display-mode change shows a confirm prompt that auto-reverts if you don't confirm, so a bad mode can't strand you; you can also hold Start during boot to skip past a bad video mode.
• Overscan (CRT inset) — Off (default) up to a numeric inset, adjusted in steps of 5 (OPL-style render inset, same math as OPL's overscan). Pulls the whole UI slightly toward the center of the screen so nothing is lost in a CRT's overscan border. The change previews live as you adjust it; backing out of Settings without saving restores the previous value. (Mainly useful on a real CRT; on a flat panel you'll usually leave it Off.)
• Boot sound — On (default) / Off. Plays the startup chime over the boot splash. Turn it Off for a silent boot. (Hardware-confirmed to save and survive a reboot.)
• BDMA Mode — mass-storage backend mode: FAT32 (FAT32-USB (None)) / USBEXFAT (exFAT-USB) / MX4SIO / MMCE. The installed mode is recorded in a bdma_mode.txt marker file in the POPSTARTER pack folder (older .pldr_bdma_mode markers are still read for compatibility).
• POPSTARTER Memory Card Folder — toggles the mc:/POPSTARTER folder. Turning it off deletes mc:/POPSTARTER (with a confirm prompt). It is interlocked with BDMA Mode: you can't turn this folder off while BDMA Mode is on, and you can't enable BDMA Mode while this folder is off.
• Hide UI Text — clears on-screen text for a clean cover-art view (also toggled with Select).
• Keyboard Layout — on-screen keyboard layout for the path editor.

BOOT.ELF / wLaunchELF Exit

Selecting BOOT.ELF in the exit menu (or pressing the Triangle shortcut) will look for:
1. mc0:/BOOT/BOOT.ELF
2. mc1:/BOOT/BOOT.ELF

If found, BOOT.ELF launches through the embedded-loader handoff with a clean BRAM setup and an explicit argv[0]. If you do not have wLaunchELF installed at these paths, this option will fail to boot.

Hardware-confirmed working when POPSLoader was launched from USB, MC, MMCE, MX4SIO, OSDmenu, Browser, PSBBN, or HDD.

The U-10 case (BOOT.ELF exit from an HDD-launched POPSLoader) previously black-screened; it was fixed in PR #479 (reboot_iop=0), hardware-confirmed by Nuno 2026-05-31. History in docs/archive/U10_INVESTIGATION.md.

Internal HDD Notes

• Internal HDD setups received major reliability improvements in BETA-10-5 (the "B2" PFS-unmount fix at commit 4ae6679), correcting the partition mount handoffs that previously prevented games from loading.
• Ensure that your game partition is named matching the __.POPS convention, and that the __common/POPS/ directory contains all necessary POPStarter/POPS emulator binaries.
• Existing USB/MX4SIO/MMCE setups are unaffected by the HDD fixes and should continue to work normally.

Settings Storage on HDD Installs

HDD-installed POPSLoader saves its .pldrs settings file on the HDD itself, in the launcher's boot partition — same single-device behavior as USB / MX4SIO / MMCE, which keep the sidecar at <install dir>/.pldrs. To do this POPSLoader takes over its own boot partition's mount and remounts it read-write (the OPL "own your mount" pattern), so there is no mc0: fallback for HDD installs. The same read-write mount is what lets in-app .hide markers (toggled with L3) be written on the HDD. See STATE.md > Settings for the canonical rules.

Troubleshooting

Game does not appear in the menu list

• Using uppercase .VCD is recommended if your games are not being detected, especially on case-sensitive setups.
• Verify that VCD files are placed directly in the POPS (or __.POPS) folder, not inside subfolders.

Game launches to a black screen

• Verify that IOPRP252.IMG, POPS.ELF, and the .PAK files are present in the POPS folder.
• Check that your game image .VCD is healthy and uncorrupted.

A game appears in the list but won't launch

• The most common cause is the .VCD filename being too long. POPStarter — not POPSLoader — performs the actual launch and enforces a hard length limit. In testing, a 73-character filename launches while a 74-character one does not.
• POPStarter's own documentation lists an 89-character limit, but that ceiling appears to count the full path string POPStarter builds (POPSLoader hands it something like mass:/POPS/XX.<name>.ELF), not just the bare filename. So the usable filename length is shorter than 89, and a deeper folder path leaves room for fewer characters — which is why ~73 is the safe target for a standard POPS/ folder.
• Fix: shorten the filename (and, if needed, use a shorter folder path). This is a POPStarter constraint and cannot be raised from POPSLoader.

Cover art is not showing up

• Check that the cover image is in .png format.
• The PNG filename must match the .VCD game filename exactly (e.g. Crash Bandicoot.VCD requires Crash Bandicoot.png).
• Ensure the cover art is placed in the same folder as the VCD (or __common/POPS/ART/ on HDD).
• Confirm cover-art preview is enabled — press Square (□) in the game list to toggle it.
• For best compatibility and performance, use 200x200 pixel images.

BOOT.ELF exit option fails or hangs

• Confirm that a valid wLaunchELF executable is installed on your physical memory card at mc0:/BOOT/BOOT.ELF or mc1:/BOOT/BOOT.ELF.

Known Issues & Planned Improvements

Confirmed broken: see the single canonical STATE.md > Known Issues list (currently just the "Failed to load HDD" from a non-HDD boot case).

Planned for subsequent updates:
* Layer C Lazy IRX Loading: Defer device-specific IRX modules so they only load when the boot device family needs them, reducing boot time. The mmceman portion has landed (PR #471): it is now loaded eagerly only when POPSLoader is booted from an MMCE device, and deferred everywhere else. Further deferral of ds34bt / usbd remains future work — they are still loaded at boot today.
* Settings UI Redesign (Berion): Visual overhaul replacing the current OPL-style focused-list with per-category Settings pages. Awaiting Berion's mockup PNGs.
* GUI Themes: Customizable colors / skins / fonts and a setting to skip the boot splash.
* In-Game Features: Support for per-game fixes, cheat codes, Virtual Memory Card (VMC) setups, and multi-disc swap prompts.
* HDD (exFAT), SMB (v1), i.Link menu flows: currently surface as "Not Implemented Yet" until feature work lands.

See STATE.md "Known Open Work" and ROADMAP.md for the prioritized backlog.

Credits

• israpps (El_isra): Original POPSLoader project creator.
• Daniel Santos: Creator of the Enceladus runtime foundation.
• krHACKen: Author of POPStarter.
• Berion: User interface design and theme assets.
• nuno6573: Cover-art engine integrations and scripting.
• Hugopocked: POPStarter fixes.
• Ripto / NathanNeurotic: Maintenance, UI polishing, and release engineering.
• P4NCHOL1NO, VizoR, provato, nuno6573, TnA-Plastic, saildot4k, and the community: Hardware testing.

Development & Building

GitHub Actions is the canonical build path. The pinned CI image is ps2dev/ps2dev:v2.0.0. Every change must pass the CI workflow in .github/workflows/compilation.yml before merging; rolling release artifacts for testing are produced by .github/workflows/rolling-release.yml on push to BETA-13-PLAY and on pull request events. CI now runs a live luac syntax gate over the embedded Lua (bin/POPSLDR/*.lua + etc/boot.lua) and hard-fails on a syntax error — note this catches syntax only; runtime and load-order errors still only surface on real PS2 / PCSX2.

POPSLoader is an EE C/C++ application (src/) with the entire front-end UI and launch logic written as embedded Lua (bin/POPSLDR/*.lua, etc/boot.lua) and an embedded IOP-side child ELF loader (src/elf_loader/). The Lua scripts, PNG art, IRX modules, and the child loader are all baked directly into the EE ELF at build time via bin2c, so the on-card scripts are not read at runtime — building from source is required to change them.

Developer documentation, repository architecture details, and the current state are maintained in:

• STATE.md: Current code and hardware status, the canonical Known Issues list, Behavioral Invariants, and Preservation Contracts.
• QA_REGRESSION_MATRIX.md: Complete ledger of CI gates and hardware test outcomes.
• ROADMAP.md: Prioritized backlog.
• DECISIONS.md: Decision log with rationale and evidence.
• ARCHITECTURE.md: Structural data-flow documentation.

To build the launcher binary locally (optional; CI is canonical), run:

make clean elfloader all

This cleans, force-regenerates the embedded child ELF loader (elfloader), then compiles every EE/IOP object, embeds all assets, links, strips, and runs ps2-packer to produce the packed bin/POPSLOADER.ELF. It requires a configured PS2DEV SDK environment (ps2dev/ps2dev:v2.0.0 toolchain) with ps2-packer and the bin2c tool on PATH.

To grab the latest test build, download from the rolling release URL:
https://github.com/NathanNeurotic/POPSLoader/releases/download/rolling-release/POPSLOADER-rolling-release.zip