Platform Notes: Android

Pegasus is available for Android devices running at least Android 4.1 (Jelly Bean). For proper multimedia support, Android 4.4 (KitKat) or newer is recommended.

Directories

Config files are stored under <storage>/pegasus-frontend, where <storage> the internal storage, if you have one, otherwise the SD card. The directory will be created automatically when you first launch Pegasus (or you can create it yourself).

Then you can continue with creating your game_dirs.txt and other files as usual (see here). You'll need to know the absolute path to the storage device -- most file browser apps can tell you this. For example, on my phone it's /storage/emulated/0, but it may differ on yours. A game_dirs.txt would then look like this:

/storage/emulated/0/roms/NES
/storage/emulated/0/roms/SNES
/storage/emulated/0/roms/PSP

Loading games

Compared to desktop systems, launching other applications is slightly different on Android. Instead of directly calling a program, you'll need to ask the Activity Manager (am) to open a file or start an app, optionally with additional parameters.

Here's how it looks in practice:

Open a file with the default app

The best case is when you have a file format associated with an app already. To open a file with its default app, invoke the Activity Manager like this:

am start --user 0 -a android.intent.action.VIEW -d "file://<path-to-file>"

Here is an example collections.txt that will open ISO files with the default app:

collection: PSP
extension: iso
launch: am start --user 0
  -a android.intent.action.VIEW
  -d "file://{file.path}"

Help

  • am is the Activity Manager program
  • the start command sends an app launching request ("intent") to the Activity Manager
  • --user 0 selects the user (by ID) that sends this request. Without this parameter I've got permission denied errors on my devices.
  • -a stands for "action"; if an app supports opening files (android.intent.action.VIEW ie. "open with"), it will react to this action. There are other possible actions, like "take a photo" or "call a taxi", but we probably won't need them for our use.
  • -d is the parameter (data) of the action, and must be in such URI format (file://...)

The full documentation of am can be found here and here.

Note that not every app supports opening arbitrary files, or opening files at all (for example, RetroArch). In addition, there seems to be a glich on some systems where a file may get opened with something else when there are multiple apps that can handle the file type. Which leads to...

Open a file with a specific app

Unfortunately opening a file with anything else than the default is a bit painful. To open the file, you have to know the exact name of the app component ("activity") that handles file opening requests. For example, for the Android version of the PPSSPP emulator, this is org.ppsspp.ppsspp/.PpssppActivity.

I haven't found a good app yet that could tell this about the installed apps, so I guess the best bet for now is either asking the developers for a particular app or looking into its source code (tip: it's always in AndroidManifest.xml). I've also made a small collection which you can find at the bottom of this page.

Anyway, once you know the Activity you want to call, the command is

am start --user 0 -a android.intent.action.VIEW -n <activity-name> -d "file://<path-to-file>"

Help

-n stands for "name"

Here is an example collections.txt that will open ISO files with PPSSPP:

collection: PSP
extension: iso
launch: am start --user 0
  -a android.intent.action.VIEW
  -n org.ppsspp.ppsspp/.PpssppActivity
  -d "file://{file.path}"

Run a custom command

Some apps simply don't support opening files, for example because they rely on a built-in file browser or some other reasons. The way to call these apps may differ from what's described above, or they might need additional parameters. You'll have to ask the developers or look around the source code in this case. See below for some examples.

App-specific notes

RetroArch

RetroArch happens to use a number of custom parameters. It can be launched like this:

collection: NES
extensions: zip
launch: am start --user 0
  -n com.retroarch/.browser.retroactivity.RetroActivityFuture
  -e ROM "{file.path}"
  -e LIBRETRO /data/data/com.retroarch/cores/fceumm_libretro_android.so
  -e CONFIGFILE /storage/emulated/0/Android/data/com.retroarch/files/retroarch.cfg
  -e IME com.android.inputmethod.latin/.LatinIME
  -e DATADIR /data/data/com.retroarch
  -e APK /data/app/com.retroarch-1/base.apk
  -e SDCARD /storage/emulated/0
  -e DOWNLOADS /storage/emulated/0/Download
  -e SCREENSHOTS /storage/emulated/0/Pictures
  -e EXTERNAL /storage/emulated/0/Android/data/com.retroarch/files
  --activity-clear-top

(based on the source code of their Android port at the time of writing).

The important parts here are the core and the storage paths. Make sure you correct the paths of the above example to match your system and collection:

Help

-e KEY VALUE defines an extra parameter, specific to the app. Unlike the file opening before, RetroArch does not need file:// for the ROM path.

Apps that can open files

Here's an incomplete list of emulators that can open external files using android.intent.action.VIEW. If you think some some of the entries are incorrect, or you'd like to extend this list, feel free to open an Issue here.

App nameActivity
2600.emucom.explusalpha.A2600Emu/com.imagine.BaseActivity
C54.emucom.explusalpha.C64Emu/com.imagine.BaseActivity
ClassicBoycom.portableandroid.classicboyLite/com.portableandroid.classicboy.EntryActivity
DraSticcom.dsemu.drastic/.DraSticActivity
Emulator for NES/SNES - Arcade Classic Gamesno support
ePSXecom.epsxe.ePSXe/com.dropbox.client2.android.AuthActivity
GBA.emucom.explusalpha.GbaEmu/com.imagine.BaseActivity
GBC.emucom.explusalpha.GbcEmu/com.imagine.BaseActivity
John emulatorsno support
MD.emucom.explusalpha.MdEmu/com.imagine.BaseActivity
MegaN64no support
MSX.emucom.explusalpha.MsxEmu/com.imagine.BaseActivity
Mupen64 Plus AEpaulscode.android.mupen64plusae/.MainActivity
Neo.emucom.explusalpha.NeoEmu/com.imagine.BaseActivity
NES.emucom.explusalpha.NesEmu/com.imagine.BaseActivity
NGP.emucom.explusalpha.NgpEmu/com.imagine.BaseActivity
Nostalgia.NEScom.nostalgiaemulators.neslite/com.nostalgiaemulators.nes.NesSlotImportActivity
PPSSPPorg.ppsspp.ppsspp/.PpssppActivity
Reicastcom.reicast.emulator/.MainActivity
Snes9xPluscom.explusalpha.Snes9xPlus/com.imagine.BaseActivity
SuperRetro16com.bubblezapgames.supergnes/.IntentFilterActivity
SuperRetro16 Litecom.bubblezapgames.supergnes_lite/com.bubblezapgames.supergnes.IntentFilterActivity

Additional notes