hoborg/Obtainium-Emulation-Pack
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

add pico8, update dev docs, new add-app CLI tool, add validation tool

Browse Source
This commit is contained in:
Richard Macias
2026-01-10 20:36:10 -06:00
parent 2066a51894
commit 5550def9a4
16 changed files with 1192 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
pages/development.md
View File

@@ -1,44 +1,226 @@
## Development & Contribution
### Contributing
### Prerequisites
You are welcome to make a PR with a contribution.
- Python 3.11+
- Make (optional, but recommended)
- Git
#### 1. Making changes to the pack
### Quick Start
##### Adding / Removing Applications
```bash
# Clone the repository
git clone https://github.com/RJNY/Obtainium-Emulation-Pack.git
cd Obtainium-Emulation-Pack
To add, update or remove an application, you need to:
# Make your changes to src/applications.json
# Then regenerate all files before pushing your PR
make release
```
1. make edits to `src/applications.json`.
1. run `make release` in the root directory
### Project Structure
#### 2. Pre-Commit
```
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
```
Before you commit, make sure to run `make release`.
This will:
- template the README and update the table
- update the minified json release file
- 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`
After running `make release`, please check for the following:
> **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`).
- `obtainium-emulation-pack-latest.json` has been updated
- `README.md` has been updated.
- Does the README table generate a friendly application name? If not, see documentation for `nameOverride`
- Does the README table generate a friendly applicaation URL? If not, see documentation for `urlOverride`
- Is the application in beta? If so, please exclude it from the JSON using `meta.excludeFromExport`
After running, execute `make release` to regenerate all files.
### Developer Documentation
#### Option B: Manual Add (For complex configs or non-GitHub sources)
#### Meta field options
##### Step 1: Export the app config from Obtainium
My scripts will do specific actions if specific application keys are present in the
`application.json`
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
| key | type | default | description |
| --------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| meta.exludeFromExport | bool | false | Excludes the app from the release export json. |
| meta.exludeFromTable | bool | false | Excludes the app from the README table. |
| meta.nameOverride | string | null | Overwrite emulator name, useful if the default name is not human friendly |
| meta.urlOverride | string | null | Overwrite the application preview link. If empty, the readme table will use the application scraper link as the homepage. |
##### 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) |
| `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.) |
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)