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 1.1.0 (released 2026-07-21). Rolling test artifacts continue to be published from the dev branch (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:)
• HDD (exFAT) (mass: via BDMA Mode ATA — an internal SATA/IDE drive formatted exFAT; new — validating on hardware)
• Disc (DKWDRV) (boot DKWDRV to play PS1 discs)

** Note
The main menu can also list i.Link, but that flow is not implemented yet — it ships Hidden by default (show it under Settings → Device List if you want it), and selecting it shows a "not implemented" notice. SMB (v1) network game browsing is now implemented (CI + Rolling green) and is validating on hardware. (HDD (exFAT)** is likewise implemented via BDMA Mode ATA and is validating on hardware.) 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: HDD (PFS) / APA partitions

This layout is for the classic HDD (PFS) drive (Sony APA partitions via the network/ATA adapter). Place VCD game files inside your dedicated POPS partitions, and system binaries inside __common/POPS/:

An exFAT internal drive is set up differently (like a USB drive, not like this). The HDD (exFAT) drive (BDMA Mode ATA) mounts as mass: and uses the same flat layout as a USB / removable drive, not APA partitions. Put a single POPS/ folder at the drive's root holding your .VCD games and the POPS system files (PATCH_5.BIN, IOPRP252.IMG, POPS.ELF, POPS.PAK, POPS_IOX.PAK, POPSTARTER.ELF), exactly like the USB / removable table above (<device>:/POPS/...), with covers under a top-level ART/ folder at the drive root (same as any removable device). Do not create __.POPS partitions or a __common/ folder on an exFAT drive.

Controls

Navigate POPSLoader using a standard PS2 controller.

Menus & Game List

On-screen Keyboard (Settings path editor)

The keyboard opens uppercase with the cursor on the first letter row and the number row sits at the top. The layout itself (QWERTY / DVORAK / ABC / AZERTY / QWERTZ / ABNT) is picked in Settings → Startup → Keyboard Layout.

Settings

Press Start on the menu to open Settings. Inside Settings, Start opens the Save Changes / Reset Defaults / Discard & Exit menu (they are no longer rows in the list); 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

Device List

Game List

Other settings

• POPSTARTER Path — which POPSTARTER.ELF to use. Leave it on Automatic (the default) and POPSLoader resolves it per device at launch: (1) the game device's own <device>:/POPS/POPSTARTER.ELF if present — on the internal PFS HDD this step is hdd0:__common/POPS/POPSTARTER.ELF instead; (2) the POPSTARTER.ELF next to where POPSLOADER.ELF launched from; (3) the mc0:/mc1:/POPSTARTER fallback. Or set an explicit path — it is tried first, and if it doesn't resolve (drive unplugged, typo) the launch silently falls back to the same Automatic order; you're only warned when no POPSTARTER.ELF is found anywhere. (The old 16-entry Profile preset list is gone — and if you had a preset selected, it's carried over into this path automatically on first boot, so nothing stops launching. No more pfsN partition numbers on screen.) Clearing the path in the editor returns it to Automatic.
• 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 / ATA (exFAT-HDD (ata) — an internal SATA/IDE drive formatted exFAT; new, validating on hardware). 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).
• Adaptive BDMA — (new, validating on hardware) stages the right BDMA drivers for the game you launch, automatically, so MMCE and USB (and MX4SIO / exFAT-HDD) games can coexist without flipping BDMA Mode between launches. It checks first and skips the write when the correct drivers are already on the card. With Adaptive BDMA on, USB launches always stage the exFAT-USB pair (USBEXFAT). That pair reads FAT32 drives too, so one variant plays every USB stick and nothing has to guess the filesystem. Using POPStarter's own built-in FAT32 stack is a manual-only choice now: set BDMA Mode to FAT32 with Adaptive Off. Default On — changed 2026-07-28 after a tester reported the BDM Assault drivers were never installed for ATA. They never were, for any device: the staging machinery was complete and correct, it simply never ran, because it sat behind a setting nobody knew to turn on. The cost of On is that every device gets a variant staged unless you opt out.
• 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 (or while Adaptive BDMA is on), and you can't enable either while this folder is off.
• Hide UI Text — On (default) / Off; clears on-screen text for a clean cover-art view (also toggled with Select). It ships On, so a fresh install starts with the on-screen text hidden.
• Keyboard Layout — on-screen keyboard layout for the path editor: QWERTY (default) / DVORAK / ABC / AZERTY / QWERTZ / ABNT. This is the only place the layout is chosen; the keyboard itself no longer carries a layout strip.
• Credits — Settings → About → Credits. (It used to be a Triangle shortcut advertised in every footer.)

SMB / Network

Browse and launch PS1 games from an SMBv1 network share via the SMB carousel entry. Networking is lazy: nothing network-related runs at boot; the stack comes up only when you open the SMB page. (Browsing and launching are confirmed working on a static IP setup. DHCP needs a build newer than bb62f2be — earlier builds deleted the address file POPStarter depends on, so a DHCP setup would list games and then fail to boot them.)

Share layout: \\server\share\POPS\Game.VCD (plus the usual POPS support files). Launches hand POPStarter an SB.<name>.ELF selector and it streams the .VCD from the share using the installed pack's SMBCONFIG.DAT.

SMB fails to connect? The error names the failing step. "No network link" = cable/adapter; "DHCP failed" = try Static; "Can't reach the server" = check Server IP and Port (stock servers = 445); "Server refused SMBv1" = enable SMBv1 support on the host (modern Windows/Samba disable it by default); "SMB login failed" = credentials; "Share not found" = share name (or use the blank-Share picker).

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.

Loading extra IRX drivers

At boot POPSLoader loads every .irx file sitting in its own folder, next to POPSLOADER.ELF, in directory order. If it finds none there it then tries an IRX/ subfolder. That is how you add a driver POPSLoader does not ship — put the .irx beside the ELF and it is loaded.

There is no allow-list and no prompt, so anything with an .irx extension in that folder is loaded, whether or not you meant it. Two consequences worth knowing:

• Keep the folder tidy. A driver you copied there once to test is still being loaded every boot, months later.
• A driver that hangs waiting on hardware you do not have will hang the boot. The most common way to hit this is running POPSLoader from a downloads folder that still contains loose drivers, or under an emulator where the hardware a driver probes is only a stub. If POPSLoader boots on a real console but hangs in an emulator, move the loose .irx files out of the folder and try again — that is the first thing to check.

Use the IRX/ subfolder if you want the drivers kept but not tangled up with whatever else lands in your download directory.

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.
• This is the most common reason art does not appear after updating. The PNG filename must match the .VCD game filename with the OPL _COV suffix (e.g. Crash Bandicoot.VCD requires Crash Bandicoot_COV.png). The _COV is not optional and will not be made optional: it is OPL's convention, and matching it is what lets one art folder serve both OPL and POPSLoader. Accepting a bare <name>.png here would break that sharing. Note the details sidecar does NOT take the suffix -- it is <name>.txt -- so it is easy to get one right and the other wrong. Only the exact game filename is tried, so a multi-disc game needs one cover per disc (Game (Disc 1)_COV.png, Game (Disc 2)_COV.png). A single shared cover for the whole set no longer works.
• Place the cover in a top-level ART/ folder at the device root. That is the only location that is read; there is no setting and no fallback, so a cover in POPS/ or POPS/ART/ will not show. On the internal HDD covers live in __common/POPS/ART/.
• Confirm cover-art preview is enabled in Settings → Game List → Cover art (default On). Square is not bound in the game list.
• 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: the "Failed to load HDD" from a non-HDD boot case, and the SMB connect failure whose root cause is fixed in code and awaiting its first hardware run — the full 2026-07-07 audit and fixes are in docs/REPO_AUDIT_2026-07-07.md).

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 was declined (2026-06-22): both hard-import usbd and the only available defer trigger is the boot device family — not the same as pad transport — so deferring them would strand USB / Bluetooth controller input (unrecoverable without a reboot) for a small boot-time gain. They are kept loaded eagerly; the Layer C effort is closed at the mmceman win.
* 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) menu flow: now implemented as a mass: backend via BDMA Mode ATA (built, CI/Rolling green) — validating on hardware.
* SMB (v1) network game browsing: now implemented (settings, an "SMB modules" install toggle, lazy connect, share browse, launch, and disconnect-on-exit; built, CI/Rolling green) — browse + launch hardware-confirmed on a static IP config; the DHCP path was fixed in bb62f2be and is not yet confirmed.
* i.Link menu flow: currently surfaces 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, scripting, and hardware testing.
• Hugopocked: POPStarter fixes.
• saildot4k (R3Z3N): BDMA-ATA (exFAT internal-HDD / ATA backend), the wLaunchELF_R3Z reference work our USB fixes are built on, the settings-UI review rounds, fixes, feedback, and oversight.
• oldman63 (Sári Gábor): The complete Hungarian localization, plus the localization bug reports that hardened it for every language.
• sAGA: Relentless hardware testing and pin-sharp reports — the USB enumeration saga, the internal-HDD freeze diagnosis rounds, and UI suggestions that shipped.
• CosmicScale: exFAT internal-HDD hardware verification and the per-device POPSTARTER idea.
• FifthFox: The per-device USB-delay POPSTARTER report that shaped the launch resolver.
• Ripto / NathanNeurotic: Maintenance, UI polishing, and release engineering.
• P4NCHOL1NO, VizoR, provato, TnA-Plastic, and the community: Hardware testing.

(GitHub's sidebar can't be trusted to show this repo's contributors — it omits the contributors box on forked repositories — so this list is the canonical one. If you contributed and aren't here, that's a bug: open an issue.)

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 dev. Pull-request events build and run the same gates but no longer publish: the publish step is gated on github.event_name == 'push' (PR #511, 2026-07-16). 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

Permanent archive (MEGA): the GitHub rolling-release pre-release only ever holds the latest build; every push overwrites it. So every branch rolling build is also archived permanently to MEGA as one self-contained zip, each in its own immutable run_<number> folder (nothing is ever overwritten there). Click the MEGA Rolling Archive badge at the top of this README, or browse the archive here, to grab any past build.