Custom Emulator (With Code)

When LaunchBox launches a game through a custom emulator, it does so by building a small Android "intent." Think of this as the message your phone sends to an emulator app, telling it:

"Hey, open this exact game file, and do it in this specific way."

Everything that goes into that message is written inside your Launch Command, also known as the am start command.

Below, we will go through each piece so you can build your own working commands.

1. The Structure of a Launch Command

A full command might look like this:

-n org.ppsspp.ppsspp/.PpssppActivity -a android.intent.action.VIEW -d {file.uri} --activity-clear-task --activity-clear-top 

Let's break it down piece by piece.

2. -n The Activity Name

This tells Android exactly which app and which part of that app to launch.

Format: -n package.name/.ActivityName
Example: -n org.ppsspp.ppsspp/.PpssppActivity
Meaning: "Open the main activity inside the PPSSPP app."

Every app has at least one Activity. Some emulators may have multiple (like separate activities for launching games versus opening settings).

How to Find It

You can discover an app's Activity Name with free tools:

• Activity Launcher Lists all Activities in every installed app and lets you copy them.

• Package Name Viewer 2.0 Shows package names, Activities, and other metadata.

• App Manager or APK Analyzer Lets you explore the internal manifest of an APK to find Activities and supported file types.

3. -a The Action

The "action" tells Android what you want the app to do with your request.
The most common is:

-a android.intent.action.VIEW 

This simply means "open or view this file."
Most emulators recognize this and treat it as "load this game."

Other possible actions include:

In nearly all emulator cases, VIEW is what you want.

4. -d The Data

The data section provides the actual game file to launch.

You will often see placeholders here, which LaunchBox replaces at runtime with your real file info.

When to use which

Use {file.path} if your emulator expects a normal file path (most older apps).
Use {file.uri} if your emulator supports Android's newer file-access system or refuses to open direct paths.
If unsure, try {file.uri} first since it is generally safer in newer Android versions.

5. -e, --es, --ez The Extras

Extras are optional key-value pairs that tell the emulator how to open the game.

Some emulators need specific parameters, like a "ROM" key or a "Core" path.

Every emulator uses different keys here. These are usually discovered through community examples or log output from tools like MatLog Libre or Logcat Reader (both free).

6. Activity Flags

Flags modify how Android opens or reuses the app.

These are optional but helpful if an emulator sometimes reopens in the background or stacks multiple copies of itself.

7. Complete Examples

Example 1: RetroArch with Core

-n com.retroarch/.browser.retroactivity.RetroActivityFuture -e ROM {file.path} -e LIBRETRO /data/data/com.retroarch/cores/snes9x_libretro_android.so --activity-clear-task --activity-clear-top 

What this does:
Launches RetroArch, tells it which game to open and which core to use.

Example 2: Simple Emulator that Accepts File URI

-n xyz.emu.app/.MainActivity -a android.intent.action.VIEW -d {file.uri} --activity-clear-top 

What this does:
Opens the emulator's main activity and tells it to "view" the selected game file.

Example 3: App that Needs a ROM Extra Instead of Data

-n com.cool.emulator/.MainActivity -e ROM {file.path} --activity-clear-task 

What this does:
Some emulators do not use -d for the file and instead expect an extra parameter named "ROM."

8. Putting It All Together

When you set up a Custom Emulator (With Code) in LaunchBox for Android, all you need to enter is your launch code, which is everything inside the am start command. You do not need to type am start itself.

So, if your emulator requires:

am start -n org.ppsspp.ppsspp/.PpssppActivity -a android.intent.action.VIEW -d {file.uri} 

You would only enter:

-n org.ppsspp.ppsspp/.PpssppActivity -a android.intent.action.VIEW -d {file.uri} 

9. Tools That Make This Easier

Here are a few free Android apps that can help you identify what to use:

• Activity Launcher Lists all launchable activities for each app. Copy them directly.

• Package Name Viewer 2.0 Great for getting package names and launcher classes.

• MatLog Libre or Logcat Reader Shows log output when you launch a game, sometimes revealing what extras the emulator expects.

10. Quick Reference: Common Flags and What They Do

11. Tips and Troubleshooting

• Game does not load? Try swapping {file.path} for {file.uri}.

• Emulator opens but does not start the game? It might require an extra like -e ROM {file.path}.

• App opens twice? Add both --activity-clear-task and --activity-clear-top.

• Still stuck? Look up the emulator's official intent examples online or try a log viewer to see what arguments it expects.