# Obtainium Emulation Pack
An [Obtainium](https://github.com/ImranR98/Obtainium) import file that adds popular Android
emulation applications to Obtainium.
The maintainer of Obtainium also hosts a collection of Crowdsourced app configurations.
[apps.obtainium.imranr.dev](https://apps.obtainium.imranr.dev)
## Prerequisite
> [!TIP]
> Which APK you need to download will depend on your device.
> If you're unsure, you can download `app-release.apk`
Download and Install the [latest release of Obtainium](https://github.com/ImranR98/Obtainium/releases/latest)
## Setup
### Option 1. Import Method
> [!TIP]
> This is recommended installation method for beginners and/or new devices
1. On your android emulation device, navigate to the [latest release](https://github.com/RJNY/Obtainium-Emulation-Pack/releases/latest) of the Obainium Emulation Pack.
1. Download the file titled `obtainium-emulation-pack-vX.X.X.json` to your device.
1. Open Obtainium.
1. Navigate to Import/Export.
1. Select `Obtainium Import` and open `obtainium-emulation-pack-vX.X.X.json`
1. You should see packages imported to your obtainium.
### Option 2. Click-to-Install Method
1. Visit this page on your android emulation device
1. Click the "Add to Obtainium!" links of the emulators you wish to track
## Applications
### Emulator
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| ARMSX2 | Add to Obtainium! | ✅ | ✅ |
| Azahar | Add to Obtainium! | ✅ | ✅ |
| Cemu | Add to Obtainium! | ✅ | ❌ |
| Cemu (Dual-Screen) | Add to Obtainium! | ❌ | ✅ |
| Citra MMJ | Add to Obtainium! | ✅ | ✅ |
| Citron | Add to Obtainium! | ✅ | ✅ |
| Citron Nightly | Add to Obtainium! | ❌ | ❌ |
| Dolphin Emulator | Add to Obtainium! | ✅ | ✅ |
| Dolphin Emulator (Dev build) | Add to Obtainium! | ❌ | ❌ |
| Dolphin-MMJR2-VBI | Add to Obtainium! | ❌ | ❌ |
| DuckStation | Add to Obtainium! | ✅ | ✅ |
| Eden | Add to Obtainium! | ✅ | ✅ |
| Eden Nightly | Add to Obtainium! | ❌ | ❌ |
| Flycast | Add to Obtainium! | ✅ | ✅ |
| Kenji-NX | Add to Obtainium! | ❌ | ❌ |
| MelonDS | Add to Obtainium! | ✅ | ❌ |
| MelonDS (Dual-Screen) | Add to Obtainium! | ❌ | ✅ |
| MelonDS Nightly | Add to Obtainium! | ❌ | ❌ |
| NetherSX2-Classic | Add to Obtainium! | ✅ | ✅ |
| NetherSX2-Patch | Add to Obtainium! | ❌ | ❌ |
| PPSSPP | Add to Obtainium! | ✅ | ✅ |
| Pico8 Android | Add to Obtainium! | ✅ | ✅ |
| RPCSX | Add to Obtainium! | ✅ | ✅ |
| RetroArch (AArch64) | Add to Obtainium! | ✅ | ✅ |
| RetroArch Nightly (AArch64) | Add to Obtainium! | ❌ | ❌ |
| ScummVM | Add to Obtainium! | ✅ | ✅ |
| Vita3K | Add to Obtainium! | ✅ | ✅ |
| aPS3e | Add to Obtainium! | ✅ | ✅ |
### Frontend
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| Cocoonfe | Add to Obtainium! | ❌ | ✅ |
| Daijishō | Add to Obtainium! | ✅ | ✅ |
| Pegasus | Add to Obtainium! | ✅ | ✅ |
### PC Emulation
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| GameHub Lite | Add to Obtainium! | ✅ | ✅ |
| GameNative | Add to Obtainium! | ✅ | ✅ |
| Winlator | Add to Obtainium! | ✅ | ✅ |
| Winlator CMod | Add to Obtainium! | ✅ | ✅ |
| Winlator-Ludashi | Add to Obtainium! | ✅ | ✅ |
### Streaming
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| Artemis | Add to Obtainium! | ✅ | ✅ |
| Moonlight | Add to Obtainium! | ✅ | ✅ |
### Track Only
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| AdrenoToolsDrivers | Add to Obtainium! | ✅ | ✅ |
| Obtainium Emulation Pack | Add to Obtainium! | ✅ | ✅ |
### Utilities
| Application Name | Add to Obtainium | Included in export json? | Included in DS json? |
|------------------|------------------|---------------------------|----------------------|
| Bifrost | Add to Obtainium! | ✅ | ✅ |
| ES-DE Android Apps | Add to Obtainium! | ✅ | ✅ |
| ES-DE Companion | Add to Obtainium! | ❌ | ✅ |
| EmuReady Lite | Add to Obtainium! | ✅ | ✅ |
| Mjolnir | Add to Obtainium! | ❌ | ✅ |
| OdinTools | Add to Obtainium! | ✅ | ✅ |
| PixelGuide | Add to Obtainium! | ✅ | ✅ |
| Syncthing-Fork | Add to Obtainium! | ✅ | ✅ |
## FAQ
### A note about stable, beta, nightly and canary versions of the same app
You cannot install more than one version of the same app. For example: You must choose between RetroArch (stable) or RetroArch (nightly). You cannot have both.
To make things easier for beginners, I've omitted nightly, beta and canary versions where a stable
one exists.
You can manually add beta/nightly applications by using the links in the README
### How do I updated Obtainium Emulation Pack?
Same as install method. It'll update existing resources.
It will not remove any other resources you've added.
### Why do some applications say TRACK ONLY?
As the name implies, these application versions are only tracked, not pulled.
This was done because we _can't_ pull these resources, but you may still care to know when these
resources have updates so you can pull them manually. For example: NetherSX2 can't provide an APK
for legal reasons, but you'll get update notifications so you don't have to manually check or be
stuck with outdated resources.
### How do I use TRACK ONLY resources?
When you get notified of an update to your track only resource:
- visit the link to your resource
- download it manually
- in obtainium > click resource > click "Mark Updated"
### Can this break?
Yes. Absolutely it can.
Any of the scrapers that use regex can break if the application maintainers break convention.
The applications pulling from GitHub are more stable and less likely to break.
## Development & Contribution
### Prerequisites
- Python 3.11+
- Make (optional, but recommended)
- Git
### Quick Start
```bash
# Clone the repository
git clone https://github.com/RJNY/Obtainium-Emulation-Pack.git
cd Obtainium-Emulation-Pack
# Make your changes to src/applications.json
# Then regenerate all files before pushing your PR
make release
```
### Project Structure
```
src/
applications.json # Source of truth - all app definitions
scripts/
generate-table.py # Generates the README table
generate-readme.py # Stitches markdown files into README
minify-json.py # Creates release JSON files
validate-json.py # Validates applications.json
pages/
init.md # README header/intro
table.md # Generated - app tables (do not edit)
faq.md # FAQ section
development.md # This file
obtainium-emulation-pack-latest.json # Standard release
obtainium-emulation-pack-dual-screen-latest.json # Dual-screen release
```
### Adding a New Application
#### Option A: Quick Add (Recommended for GitHub apps)
Use the interactive CLI to quickly add a new app:
```bash
make add-app
```
This will:
- Prompt you for the GitHub URL
- Auto-detect the source, author, and app name
- Ask for the Android package ID and category
- Generate proper Obtainium settings
- Add the app to `applications.json`
> **Tip:** To find the package ID, open the app in Obtainium - the package ID is displayed directly below the source URL (e.g., `com.example.android`).
After running, execute `make release` to regenerate all files.
#### Option B: Manual Add (For complex configs or non-GitHub sources)
##### Step 1: Export the app config from Obtainium
1. Open Obtainium on your device
2. Add the app you want to include (configure it how you want)
3. Long-press the app and select "Export"
4. Choose "Obtainium Export" format
5. Transfer the JSON to your computer
##### Step 2: Add the app to applications.json
Open `src/applications.json` and add your app to the `apps` array:
```json
{
"id": "com.example.emulator",
"url": "https://github.com/example/emulator",
"author": "example",
"name": "Example Emulator",
"preferredApkIndex": 0,
"additionalSettings": "{...}",
"categories": ["Emulator"],
"overrideSource": "GitHub"
}
```
#### Step 3: Add meta fields (optional)
Add a `meta` object to customize how the app appears:
```json
{
"id": "com.example.emulator",
"url": "https://github.com/example/emulator",
"author": "example",
"name": "Example Emulator",
"preferredApkIndex": 0,
"additionalSettings": "{...}",
"categories": ["Emulator"],
"overrideSource": "GitHub",
"meta": {
"nameOverride": "Example Emu",
"urlOverride": "https://example-emu.org"
}
}
```
#### Step 4: Validate and regenerate
```bash
make release
```
This will:
1. Validate your JSON for errors
2. Regenerate the README table
3. Update both release JSON files
### Pre-Commit Checklist
Before committing, run `make release` and verify:
- [ ] `obtainium-emulation-pack-latest.json` has been updated
- [ ] `obtainium-emulation-pack-dual-screen-latest.json` has been updated
- [ ] `README.md` has been updated
- [ ] The README table shows a friendly application name (use `nameOverride` if not)
- [ ] The README table links to the correct homepage (use `urlOverride` if not)
- [ ] Beta apps are excluded with `meta.excludeFromExport: true`
### Available Make Commands
| Command | Description |
| ------------------------- | ----------------------------------------------------------- |
| `make help` | Show all available commands |
| `make add-app` | Interactive CLI to add a new app |
| `make release` | Run validation, generate table, README, and both JSON files |
| `make validate` | Validate applications.json for errors |
| `make table` | Generate the README table only |
| `make readme` | Generate README.md from pages |
| `make minify` | Generate standard release JSON |
| `make minify-dual-screen` | Generate dual-screen release JSON |
| `make links` | Generate click-to-install URLs (for testing) |
### Meta Field Reference
These fields in the `meta` object control how apps are processed:
| Field | Type | Default | Description |
| --------------------- | ------ | ------- | ------------------------------------------------------------------- |
| `excludeFromExport` | bool | `false` | Exclude from both release JSON files. Use for beta/unstable apps. |
| `excludeFromTable` | bool | `false` | Exclude from the README table. |
| `includeInStandard` | bool | `true` | Include in standard release. Set `false` for dual-screen-only apps. |
| `includeInDualScreen` | bool | `true` | Include in dual-screen release. Set `false` for standard-only apps. |
| `nameOverride` | string | `null` | Override the display name in the README table. |
| `urlOverride` | string | `null` | Override the homepage link in the README table. |
### Categories
Apps are organized into categories that appear as sections in the README table:
| Category | Description |
| -------------- | ---------------------------------------------------------------- |
| `Emulator` | Console/handheld emulators (Dolphin, RetroArch, PPSSPP, etc.) |
| `Frontend` | Emulator launchers and game library managers (Daijisho, Pegasus) |
| `Utilities` | Helper apps (Syncthing, OdinTools, LED controllers, etc.) |
| `Dual Screen` | Apps specifically for dual-screen devices |
| `PC Emulation` | Windows/PC game layers (Winlator, etc.) |
| `Streaming` | Game streaming clients (Moonlight, etc.) |
An app can belong to multiple categories.
### Dual-Screen vs Standard
The pack supports two variants:
- **Standard** (`obtainium-emulation-pack-latest.json`): For regular Android devices
- **Dual-Screen** (`obtainium-emulation-pack-dual-screen-latest.json`): For dual-screen devices like LG V60/Velvet
Some apps have dual-screen-specific forks (e.g., Cemu, MelonDS). Use the `includeInStandard` and `includeInDualScreen` flags to control which variant(s) include each app.
**Why this matters:** Apps with the same Android package ID (`id` field) will conflict in Obtainium. If two apps share an ID (like standard Cemu and dual-screen Cemu), they **must not** both appear in the same JSON file.
Example: Standard Cemu excluded from dual-screen, dual-screen fork excluded from standard:
```json
// Standard Cemu - exclude from dual-screen JSON
{
"id": "info.cemu.cemu",
"name": "Cemu",
"url": "https://github.com/SSimco/Cemu",
"categories": ["Emulator"],
"meta": { "includeInDualScreen": false }
}
// Dual-screen Cemu fork - exclude from standard JSON
{
"id": "info.cemu.cemu",
"name": "Cemu",
"url": "https://github.com/SapphireRhodonite/Cemu",
"categories": ["Dual Screen"],
"meta": { "includeInStandard": false }
}
```
### Choosing the Right Category and Variant
Use this decision tree:
1. **Is this app device-specific?** (e.g., AYN Thor frontend, LG dual-screen fork)
- Yes: Set `includeInStandard: false` and use appropriate category
- No: Continue to step 2
2. **Does this app share an ID with another app in the pack?** (e.g., forks, beta builds, dual-screen variants)
- Yes: Only one app per ID can be in each release JSON. Options:
- Use `includeInStandard`/`includeInDualScreen` to split between variants
- Use `excludeFromExport: true` on the less stable version (e.g., nightly builds)
- No: App can be in both variants (default)
3. **Is this app stable and ready for users?**
- Yes: Include normally
- No: Set `excludeFromExport: true` (still visible in table but not in release JSONs)