hoborg/Obtainium-Emulation-Pack

Fork 0

Files

Richard Macias 5550def9a4 add pico8, update dev docs, new add-app CLI tool, add validation tool

2026-01-10 20:36:10 -06:00

87 KiB

Raw Blame History

Obtainium Emulation Pack

An 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

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

Setup

Option 1. Import Method

Tip

This is recommended installation method for beginners and/or new devices

On your android emulation device, navigate to the latest release of the Obainium Emulation Pack.
Download the file titled obtainium-emulation-pack-vX.X.X.json to your device.
Open Obtainium.
Navigate to Import/Export.
Select Obtainium Import and open obtainium-emulation-pack-vX.X.X.json
You should see packages imported to your obtainium.

Option 2. Click-to-Install Method

Visit this page on your android emulation device
Click the "Add to Obtainium!" links of the emulators you wish to track

Applications

Dual Screen

Application Name	Add to Obtainium	Included in export json?	Included in DS json?
Cemu	Add to Obtainium!	❌	✅
MelonDS	Add to Obtainium!	❌	✅

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!	✅	❌
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 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!	✅	✅
Vita3K ZX	Add to Obtainium!	✅	✅
aPS3e	Add to Obtainium!	✅	✅

Frontend

Application Name	Add to Obtainium	Included in export json?	Included in DS json?
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?
ES-DE Android Apps	Add to Obtainium!	✅	✅
OdinTools	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

# 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:

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

Open Obtainium on your device
Add the app you want to include (configure it how you want)
Long-press the app and select "Export"
Choose "Obtainium Export" format
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:

{
  "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:

{
  "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

make release

This will:

Validate your JSON for errors
Regenerate the README table
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.

Category	Description
`Emulator`	Console/handheld emulators (Dolphin, RetroArch, PPSSPP, etc.)
`Frontend`	Emulator launchers and game library managers (Daijisho, Pegasus)
`Utility`	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.)

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:

// 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:

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
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)
Is this app stable and ready for users?
- Yes: Include normally
- No: Set excludeFromExport: true (still visible in table but not in release JSONs)

87 KiB Raw Blame History

Obtainium Emulation Pack

Prerequisite

Setup

Option 1. Import Method

Option 2. Click-to-Install Method

Applications

Dual Screen

Emulator

Frontend

PC Emulation

Streaming

Track Only

Utilities

FAQ

A note about stable, beta, nightly and canary versions of the same app

How do I updated Obtainium Emulation Pack?

Why do some applications say TRACK ONLY?

How do I use TRACK ONLY resources?

Can this break?

Development & Contribution

Prerequisites

Quick Start

Project Structure

Adding a New Application

Option A: Quick Add (Recommended for GitHub apps)

Option B: Manual Add (For complex configs or non-GitHub sources)

Step 1: Export the app config from Obtainium

Step 2: Add the app to applications.json

Step 3: Add meta fields (optional)

Step 4: Validate and regenerate

Pre-Commit Checklist

Available Make Commands

Meta Field Reference

Categories

Dual-Screen vs Standard

Choosing the Right Category and Variant

87 KiB

Raw Blame History