Last updated: 2026-05-13

POPSLoader is a PlayStation 2 launcher for POPStarter, built on Enceladus runtime components and driven primarily by embedded Lua scripts.

This repository contains:

• the launcher (POPSLOADER.ELF),
• embedded runtime Lua and asset data,
• embedded IOP modules,
• the POPStarter packaging payload used by CI,
• documentation for current code state and validation status,
• repository automation workflows for build/package CI and comment-triggered AI assistance.

The CI workflow packages an exact ZIP layout:

PS1_POPSLOADER/
  POPSLOADER.ELF
  POPSTARTER.ELF
  APPINFO.PBT
  BUILD_INFO.txt
  title.cfg
  icon.sys
  list.icn
  copy.icn
  del.icn
POPS/
  PATCH_5.BIN

That package contract is enforced by .github/workflows/compilation.yml. Current CI also verifies that the built enceladus.elf still contains the expected embedded Lua runtime markers and that the generated embedded-loader blob was regenerated before packaging. The separate .github/workflows/opencode.yml workflow is repository automation for comment-triggered AI assistance; it is not a build/package validation gate.

Reported hardware issues currently being tracked are:

• HDD-backed POPSTARTER.ELF handoff (D-10, D-14)
  • latest recorded hardware outcomes still fail when POPSTARTER.ELF itself is HDD-backed.
  • the historical D-15 pass isolated the remaining blocker to HDD-backed POPSTARTER execution, not HDD games in general; the 2026-05-20 latest-artifact D-15 regression is now a guardrail failure to retest first.
  • one 2026-03-29 artifact briefly moved D-10 from a black screen to rc=-1 (returned after 22618 ms), but later artifacts returned to a black screen, so that boundary was not stable.
  • current repo line now simplifies the default HDD-backed POPSTARTER attempt: it keeps the real resolved executable path, passes only the legacy selector arg, uses the direct non-reboot System.loadELF(...) path, skips the Lua partition-aware gate/remount layer, and removes the direct-path HDD-only pre-ExecPS2 PFS/SIF cleanup so the parent handoff matches the working non-HDD POPSTARTER path more closely.
  • HDD_POPSTARTER_HANDOFF.md contains the 2026-05-19 source audit, current suspected failure path, known bad attempts, and recommended fix order.
  • detailed per-artifact experiment chronology lives in QA_REGRESSION_MATRIX.md and DECISIONS.md.
• HDD game with non-HDD POPSTARTER (D-15)
  • user later confirmed on 2026-03-28 that USB boot + USB Profile 1 sidecar/cwd POPSTARTER.ELF + HDD game now passes on hardware.
  • user reported a 2026-05-20 latest-artifact regression: USB boot with USB sidecar/cwd POPSTARTER.ELF, then launching an HDD title, black-screened.
  • current source restores legacy System.loadELF(path, reboot_iop, selector) one-argument selector behavior for normal/non-HDD POPSTARTER launches; hardware result is Unknown (verify on hardware).
  • a follow-up 2026-05-20 report narrowed the non-HDD regression to default/cwd sidecar resolution: explicit mass:/POPS/POPSTARTER.ELF launches, but default POPSTARTER.ELF could stop at Cant find POPSTARTER ELF. Current source expands default sidecar lookup to the live current directory plus boot/app directories; hardware result is Unknown (verify on hardware).
• BOOT.ELF after HDD runtime (U-10)
  • BOOT.ELF is reached, but later reported hardware said it could still misbehave after HDD runtime had already been initialized.
  • current working inference is that U-10 may share the same underlying handoff/state-poisoning boundary as D-10, but that is not yet proven and must not be treated as an automatic fix dependency.
  • current line uses BOOT.ELF-specific cold prep plus conditional reboot_iop, but hardware on that exact line is still Unknown (verify on hardware).

• Boot/runtime Lua is embedded into the ELF.
• Required runtime modules are:
  • boot.lua
  • system.lua
  • ui.lua
  • images.lua
  • pops_profiles.lua
• Filesystem Lua loaders are disabled at runtime.

• Settings are persisted at mc0:/POPSTARTER/.pldrs.
• Settings edits are staged in UI first, then committed on confirm/leave.
• Current persisted settings include:
  • POPSTARTER path,
  • DKWDRV path,
  • video standard,
  • hide-text mode,
  • keyboard layout,
  • BDMA mode.

• Startup backend auto-init is implemented.
• The launcher now decides which backends to initialize from:
  • boot path / argv0,
  • current app directory,
  • configured POPSTARTER path,
  • configured DKWDRV path,
  • selected profile path.
• When HDD is a startup target, auto-init now runs the same PLDR.LoadHDDModules() path used by the HDD page instead of only the lower-level exec helper.
• USB vs MX4SIO identity is determined from the mount-driver name, not from the path text.

• The old runtime device-lock gate is no longer active.
• Opening one backend page does not intentionally block opening another backend page through a session lock.

• Standard cover lookup uses a sidecar PNG next to the selected .VCD.
• HDD entries can also load cover art from:
  • hdd0:__common/POPS/ART/<title>.png
• bin/POPSLDR/IMG/default.png is optional at compile time. If it is absent from the GitHub Actions checkout, IMG.default falls back to the required embedded MISSING.png asset.

• The on-screen keyboard supports:
  • ABC
  • QWERTY
  • DVORAK
• Keyboard layout is persisted in settings.
• The editor includes:
  • visible cursor movement,
  • backspace/delete support,
  • save/done behavior,
  • button-bar help specific to keyboard mode.

• Exit modal offers:
  • OSDSYS
  • Cancel
  • BOOT.ELF
• BOOT.ELF resolution order is:
  • mc0:/BOOT/BOOT.ELF
  • mc1:/BOOT/BOOT.ELF
• External launch prep uses tracked HDD/PFS unmount logic before handoff.

1. Obtain a current POPSLOADER.zip build.
2. Extract it without changing the directory structure.
3. Copy:
   • PS1_POPSLOADER/ to the device/location you want to boot from,
   • POPS/ to the backend location expected by your chosen setup.
4. Place PS1 .VCD files in the backend POPS/ location you actually intend to browse from.

• Sidecar cover rule:
  • GAME.VCD -> GAME.png
• HDD common art rule:
  • hdd0:__common/POPS/ART/GAME.png

• HDD scan code currently looks for POPS game partitions in the configured POPS partition set (__.POPS, __.POPS0, __.POPS1 ... __.POPS9).
• HDD dependency checks look for runtime files under hdd0:__common/POPS/.

Use the same environment as CI:

make clean elfloader all

The build/package workflow uses the ps2dev/ps2dev container and validates packaging after build.

bin/POPSLDR/IMG/default.png is optional for CI/artifact builds. Add it to the checkout only when a custom default-cover image should be embedded; otherwise MISSING.png is compiled and used as the fallback.

• PS2 toolchain environment (PS2DEV, PS2SDK, gsKit/ports libs)
• ps2-packer
• make
• standard build tools

• bin/enceladus.elf
• bin/POPSLOADER.ELF
• POPSLOADER.zip in CI packaging flow

• HDD (exFAT) menu flow
• SMB (v1) menu flow
• ILINK menu flow

• PAL/NTSC menu asset proportions (U-06)
• BOOT.ELF after HDD page init (U-10)
• boot-device label across all boot sources (U-11)

• U-05 OSDSYS exit:
  • reported fixed.
• D-12 startup backend auto-init:
  • a 2026-03-27 hardware report said booting from HDD did not auto-init the HDD driver stack.
  • current source now routes HDD startup targets through PLDR.LoadHDDModules() instead of only EnsureHddRuntimeReadyForExec().
  • current source also keeps startup HDD init limited to runtime readiness; it no longer scans HDD POPS partitions or builds the HDD game list during boot.
  • the HDD page still scans partitions and builds the games list on page entry, and if HDD cache is enabled it now writes that cache from the page-built list instead of rebuilding during startup.
  • user previously confirmed the earlier HDD startup auto-init correction on hardware, but later 2026-03-28 reports on the narrowed boot-time split sources said HDD-backed startup/Profile POPSTARTER could still not be found after entering the USB page before the HDD page.
  • the raw boot APP_DIR fallback alone did not restore that case.
  • current source now also pre-resolves any HDD-backed startup/configured exec paths immediately after PLDR.LoadHDDModules() so HDD POPSTARTER/Profile paths are mounted and recorded without reintroducing HDD page work at boot.
  • current source also routes on-demand HDD path mounts through PLDR.LoadHDDModules() instead of only the lower-level EnsureHddRuntimeReadyForExec() gate, so HDD POPSTARTER/Profile probes from USB or other pages use the same runtime init path as HDD page entry.
  • current source also fixes the startup warm-path classification for Profile 1/default relative POPSTARTER.ELF, which had previously been skipped because only explicit hdd: / pfs: paths were being marked for HDD warm-up.
  • because etc/boot.lua establishes HDD boot on a dedicated pfs1: mount before system.lua runs, current source now also carries that exact boot partition/slot metadata into system.lua, seeds the HDD mount tracker from it, and rebuilds HDD sidecar/partition context from mounted pfs1: candidates instead of relying only on later rediscovery.
  • user later confirmed on 2026-03-28 that the exact-boot-mount/source-context source restored the USB-before-HDD-page Profile 1 lookup repro on hardware.
  • latest recorded hardware on this line is therefore PASS; preserve that behavior through further D-10 work.
• D-16 first-entry USB backend discovery:
  • a 2026-03-27 hardware report said the first USB page entry reported no backend, but backing out and re-entering then worked.
  • current source now adds a bounded wait between failed USB root probes in BuildUsbIdentityDeferred().
  • MX4SIO discovery code was not changed by this correction.
  • user later confirmed that corrected source fixed the first-entry USB issue on hardware.
• D-10 HDD POPSTARTER on HDD:
  • reported failing.
  • latest recorded hardware outcomes still fail when POPSTARTER.ELF itself is HDD-backed.
  • D-15 passing again isolates the remaining blocker to HDD-backed POPSTARTER execution.
  • a 2026-05-20 artifact screenshot returned to the launcher with a pre-exec gate partition-context failure for pfs3:/POPS/POPSTARTER.ELF; the follow-up source change is repo-verified only until the next artifact is tested on hardware.
  • a later readable screenshot showed the next pre-exec gate issue: the gate checked generic pfs:/POPS/POPSTARTER.ELF instead of a real mounted path.
  • current source pivots away from that over-engineered default path: normal X keeps the mounted/resolved POPSTARTER path, uses direct non-reboot System.loadELF(...) with the legacy selector, reports minimal-legacy-load, and does not send Lua partition context.
  • after a further black-screen result on that direct path, current source also removes the HDD-only parent cleanup immediately before ExecPS2 in LoadELFFromFileExecPS2(), because the working non-HDD POPSTARTER handoff does not call fileXioUmount, SifExitIopHeap, SifExitRpc, or SifExitCmd there.
  • one 2026-03-29 artifact briefly returned rc=-1 (returned after 22618 ms) instead of black-screening, but later artifacts returned to black screen, so that boundary is not treated as the stable current state.
  • the partition-aware reboot path remains in source for comparison, but it is no longer the normal X route for HDD-backed POPSTARTER.
  • see QA_REGRESSION_MATRIX.md and DECISIONS.md for the detailed experiment chronology.
• D-14 HDD-backed POPSTARTER with non-HDD game:
  • reported failing.
  • 2026-03-27 user hardware also black-screened when launching a USB game with Profile 2 pointing POPSTARTER.ELF to HDD.
  • later recorded hardware still failed when POPSTARTER.ELF itself was on HDD, confirming the broader blocker is HDD-backed POPSTARTER execution rather than HDD game routing alone.
  • current repo line uses the same partition-aware HDD reboot contract as D-10; a current-line hardware re-test is still Unknown (verify on hardware).
• D-15 HDD game with non-HDD sidecar POPSTARTER:
  • a later 2026-03-27 hardware report said booting from another device and launching an HDD game with sidecar POPSTARTER.ELF on that boot device also black-screened.
  • that was reported as a regression on the EE-side HDD direct-load attempt, which has now been reverted in source.
  • a later 2026-03-27 hardware report said the broader stripped-handoff HDD-game path also black-screened.
  • current source now removes Lua-side HDD game pre-mount/CWD preservation from this path and leaves only the normal selector handoff unless POPSTARTER.ELF itself is HDD/PFS-backed.
  • user later confirmed on 2026-03-28 that USB boot + USB sidecar/cwd POPSTARTER.ELF + HDD game passes on hardware.
  • user reported a 2026-05-20 latest-artifact regression where that same shape black-screened.
  • current source restores the legacy one-argument System.loadELF selector handoff for this normal/non-HDD POPSTARTER path; hardware result is Unknown (verify on hardware).
  • user then reported explicit mass:/POPS/POPSTARTER.ELF launches still work, while default/cwd sidecar resolution can stop at Cant find POPSTARTER ELF; current source expands the default sidecar candidates without changing the selector handoff.
• Shared default/Profile 1 local POPSTARTER baseline:
  • reported failing with Cant find POPSTARTER ELF on 2026-03-27 when booted from USB with USB sidecar/cwd/Profile 1.
  • current source was rolled back to BETA-10-play-CHECKPOINT2 shared resolver behavior for this path after the later unverified common-path changes failed to restore launch.
  • user confirmed that rolled-back source fixed the baseline on hardware.
• U-10 BOOT.ELF after HDD page init:
  • one prior artifact was reported good,
  • repo history shows the BOOT.ELF modal later changed from its older non-reboot direct System.loadELF(elf_path, 0, elf_path) path to a reboot-I/O path with launch-CWD setup.
  • a later 2026-03-29 hardware report said BOOT.ELF still behaved incorrectly once HDD had been initialized, which points more specifically at carried HDD runtime state than BOOT.ELF lookup.
  • current working inference is that U-10 may share the same underlying handoff/state-poisoning boundary as D-10, but that is not yet proven and U-10 still requires its own hardware re-check after any D-10 change.
  • current source therefore keeps the no-launch-CWD rollback, re-enables reboot_iop = 1 only when HDD runtime has already been loaded, and uses a BOOT.ELF-specific cold external-launch prep that clears the exec keep mask and unmounts tracked HDD slots instead of preserving boot PFS state.
  • current-source hardware status is still Unknown (verify on hardware).

If you need details instead of a summary:

• STATE.md: current repo and hardware status in plain language
• QA_REGRESSION_MATRIX.md: test matrix and current reported validation status
• ARCHITECTURE.md: runtime/data-flow overview
• COMPONENTS.md: ownership map by file/component
• DECISIONS.md: explicit project decisions and open investigations
• ROADMAP.md: active priorities and deferred work
• RULES.md: hard constraints for changes
• TRUTHSHEET.md: invariants that should not drift silently

• Original POPSLoader lineage by El_isra / israpps.
• Derived from Enceladus by DanielSant0s.

• israpps (El_isra) for POPSLoader.
• Daniel Santos for Enceladus.
• Berion for graphics/design work.
• nuno6573 for cover-art related work.
• Hugopocked for POPStarter fixes.
• Ripto / NathanNeurotic for continuation and release work.

This project retains the GNU General Public License v3.0.