README — Overview

← POPSLoader docs · view on GitHub ↗

POPSLoader is a PlayStation 2 PS1-game browser and launcher. It supports the original POPStarter + Sony POPS VCD workflow, and the Ember PS1 core as a separate, experimental emulator. Browse by storage device, launch titles, manage settings and artwork, or return to BOOT.ELF.

Downloads · GitHub Wiki · Website · Known issues / hardware status · Rolling archive

Choose your download

Passing CI proves builds and packages passed automated checks; it does not prove that a game, device, controller or VMC works on a physical PS2. Consult the hardware QA matrix.

Install POPSLoader with Ember Beta-2

Download the full POPSLoader 1.4.1 PS1_POPSLOADER-1.4.1.zip or the latest rolling package. Its device-root layout is:

APPS/
  PS1_POPSLOADER/
    POPSLOADER.ELF
    POPSTARTER.ELF
    icon.sys
    list.icn
    copy.icn
    del.icn
    title.cfg
    APPINFO.PBT

POPS/                      POPStarter and RiptOPL-matched support assets

EMBER/
  ember.elf                 Unmodified Ember core; beta licence included
  LICENSE-BETA.txt
  games/
    ExampleGame/
      ExampleGame.cue
      ExampleGame.bin        ZERO-BYTE illustration, not a playable disc

PS1_POPSLOADER.psu          Alternative app-only PS2 memory-card save

1. Application: Copy APPS/PS1_POPSLOADER/ to your launcher’s APPS location and run POPSLOADER.ELF. Alternatively import PS1_POPSLOADER.psu using a PS2 PSU-capable save manager. Its PS2 save header is named PS1_POPSLOADER and contains exactly those eight direct files, with no nested folder.
2. POPStarter: Copy POPS/ to the storage-device root. Add your own lawfully obtained Sony POPS files (POPS.ELF, POPS.PAK, POPS_IOX.PAK and IOPRP252.IMG) as required. Those copyrighted emulator components are not included.
3. Ember: Copy EMBER/ to the same device root. Add your own 512 KiB PlayStation BIOS at EMBER/bios.bin and your own disc images under EMBER/games/<GameFolder>/, with a .cue and matching .bin tracks. No BIOS or commercial game images are provided. The included ExampleGame.bin is intentionally empty: delete or replace this non-playable example.
4. Artwork: POPStarter uses POPS/<GameName>.VCD; Ember uses EMBER/games/<GameFolder>/. For removable storage, covers go in the device-root ART/ as <VCD-basename>_COV.png or <Ember-folder>_COV.png; _ICO.png is the optional disc icon.

For stable 1.2.3, use that release's existing installation layout, which does not include Ember. See the installation guide and release ZIP/PSU specification.

Storage and device status

HDD/PFS artwork belongs under __common/POPS/ART/. The 1.4.0 UDPFS mode uses UDPFS Assault 1.0.0 with no USB requirement; later builds use its TEST pre-release, which also plays POPS/*.cue games without conversion; end-to-end console UDPFS behavior is not hardware-certified. SMBv1 and UDPFS use mutually exclusive network stacks: restart before switching between them. See device details and UDPFS setup.

Ember options and safety

Set the bundled Ember Beta-2 core's global options under Settings → Ember PS1 Core. On an [Ember] game row, press L2 for timing, dither, shading and controller overrides; Default inherits the global option. Ember may create virtual memory cards in each game folder on writable media. Game launch, controller operation after the keep-IOP handoff and VMC persistence remain unverified on real hardware. POPStarter VCD success does not establish Ember success.

Credits and redistribution: Gageformer's Ember (unmodified core with EMBER/LICENSE-BETA.txt), RiptOPL / Open-PS2-Loader (device/backend reference), Okeanos's BDM-UDPFS Assault and israpps BDM Assault. The weekly Ember Watch verifies upstream asset digests, not hardware gameplay.

Main features

• Cover-art PS1 browser for POPStarter VCD games and separate labeled Ember games.
• USB, MX4SIO, MMCE, APA/PFS and internal exFAT device flows, plus network modes.
• Per-device game visibility, settings, game lists and RiptOPL-style artwork.
• SMBv1 and opt-in UDPFS VCD browsing with explicit network configuration.
• Adjustable video, boot page, display and menu navigation; Triangle Exit menu and BOOT.ELF chainloading.

Current limitations: Ember console game launch, controller and VMC support still require evidence; i.Link remains unsupported; UDPFS and reported device issues require physical testing. Track verified regressions and dates in STATE.md and the QA matrix.

For complete menus, controls, recovery, troubleshooting and developer details, continue below or use the maintained GitHub Wiki.

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 or optional _ICO.png disc icon in the top-level ART/ folder at the device root. For local devices this is the only artwork location; UDPFS additionally checks beside the VCD in udpfs:/POPS/. There is no user-selectable art folder. 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, 8-bit-per-channel RGBA PNG images. Release 1.2.0 can render RGB PNG covers invisible; adding an opaque alpha channel is the workaround (issue #575). Version 1.2.1 includes the RGB decoder correction; hardware validation is tracked in STATE.md.

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 remains intentionally hidden/unsupported. Ember i.Link development is deferred until RiptOPL proves reliable support on physical PS2 hardware.

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

Credits

• israpps (El_isra): Original POPSLoader project creator and BDM Assault reference work.
• Gageformer: Ember PS1 emulator, bundled unmodified with its beta licence.
• Okeanos: UDPFS Assault PS1 network read/write driver.
• Daniel Santos: Creator of the Enceladus runtime foundation.
• krHACKen: Author of POPStarter.
• AstroSnail: Recovered and contributed an original Bitbucket Git clone of ShaolinAssassin's POPStarter documentation wiki (2,140 historical commits, 2016–2024). Its complete edit history complements our Wayback-recovered pages; original authors retain credit. See provenance.
• 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 (sAGA, Sári Gábor): The complete Hungarian localization and the localization bug reports that hardened it for every language, plus 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.