miles/OmniEmu2.0
1
0
Fork 0
mirror of https://github.com/mileswolfallen2/OmniEmu2.0.git synced 2026-09-08 11:23:17 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
cc14a72f9c67df8f2d1d717bcc65040909d46355
OmniEmu2.0/SPEC.md
T

21 KiB
Raw Blame History

OmniEmu 2.0 — Project Specification

All your games. One place.

OmniEmu is a cross-platform desktop application for managing emulators, launching games, and organizing ROM libraries. Built with Electron, React, and TypeScript.

Repository: github.com/mileswolfallen2/OmniEmu2.0 Version: 0.2.1 License: MIT (Copyright 2026 mileswa1q22)

Table of Contents

  1. Tech Stack
  2. Licenses
  3. Architecture
  4. Supported Emulators
  5. Supported Frontends
  6. Supported Systems
  7. ROM Format Support
  8. Configuration Presets
  9. IPC API Reference
  10. File Structure
  11. Build & Development
  12. Release Artifacts
  13. Security
  14. Contributing

Tech Stack

Technology Version Purpose License
Electron 43.1.0 Desktop app shell MIT
React 19.2.7 UI framework MIT
React DOM 19.2.7 DOM rendering MIT
TypeScript 5.9.3 Type-safe language Apache-2.0
Vite 6.4.3 Renderer bundler MIT
electron-builder 25.1.8 Packaging & distribution MIT
electron-updater 6.8.9 Auto-update support MIT
@vitejs/plugin-react 4.7.0 React Fast Refresh for Vite MIT
concurrently 9.2.3 Parallel dev scripts MIT
7zip-bin 5.2.0 Archive extraction (7z) MIT

All dependencies are MIT-licensed except TypeScript (Apache-2.0).

Licenses

OmniEmu

MIT License

Copyright (c) 2026 mileswa1q22

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Third-Party Licenses

Component License SPDX
Electron MIT MIT
React MIT MIT
React DOM MIT MIT
TypeScript Apache-2.0 Apache-2.0
Vite MIT MIT
electron-builder MIT MIT
electron-updater MIT MIT
@vitejs/plugin-react MIT MIT
concurrently MIT MIT
7zip-bin MIT MIT

External Software (Not Bundled)

OmniEmu can install and configure the following third-party software. Each has its own license:

Software License Website
RetroArch GPLv3 https://retroarch.com
Dolphin GPLv2+ https://dolphin-emu.org
RPCS3 GPLv2 https://rpcs3.net
Eden GPLv3 https://eden-emu.dev
PCSX2 GPLv2+ https://pcsx2.net
MAME GPLv2+ https://mamedev.org
DuckStation GPLv3 https://github.com/stenzek/duckstation
PPSSPP GPLv2+ https://ppsspp.org
melonDS GPLv2 https://melonds.kuribo64.net
Flycast GPLv2 https://github.com/flyinghead/flycast
ES-DE GPLv3 https://es-de.org
NeoStation MIT https://neostation.dev
Pegasus Frontend MIT https://pegasus-frontend.org
EmuBuddy Unknown https://github.com/computerex/EmuBuddy

Architecture

OmniEmu uses a standard Electron two-process architecture:

+------------------+     IPC (ipcMain/ipcRenderer)     +------------------+
|                  | <---------------------------------> |                  |
|   Main Process   |                                     | Renderer Process |
|   (Node.js)      |                                     | (Chromium)       |
|                  |                                     |                  |
| - Emulator mgmt  |                                     | - React UI       |
| - ROM scanning   |                                     | - Pages          |
| - Installation   |                                     | - Components     |
| - Config writing |                                     | - Gamepad nav    |
| - Auto-updater   |                                     | - Modals         |
| - Settings       |                                     |                  |
| - RetroAchieve.  |                                     |                  |
| - BIOS checks    |                                     |                  |
+------------------+                                     +------------------+
         |                                                          |
         v                                                          v
   File system                                              window.omni API
   (settings, configs,                                        (contextBridge)
    ROMs, cache, emulators)

Main Process (src/main/)

File Purpose
index.ts App entry point. Creates window (1200x800, min 900x600), system tray, single-instance lock, startup tasks
emulators.ts Core emulator registry. 14 emulators with download URLs, detection, version checking, ROM scanning, game launching
configurator.ts Configuration engine. Presets, config file writing, ES-DE XML generation, NeoStation JSON generation, Pegasus collection generation, controller bindings, RetroAchievements setup
ipc.ts IPC handler registry. 35+ channels exposed to the renderer
preload.ts Context bridge. Exposes window.omni API with typed wrappers
platform.ts Platform detection (win32/darwin/linux, x64/arm64)
settings.ts Settings persistence (settings.json in userData)
installer.ts Download, extract, and install emulators (zip, 7z, tar.gz, DMG, NSIS, AppImage, Homebrew, snap)
scraper.ts Cover art (libretro-thumbnails) and metadata (MobyGames) scraping with local cache
updater.ts Auto-update via electron-updater
bios.ts BIOS file detection and management
ra.ts RetroAchievements integration (game lookup, achievement data)

Renderer Process (src/renderer/)

File Purpose
App.tsx Root component. Page routing, theme application, gamepad nav
main.tsx React entry point
index.html HTML shell with CSP
styles.css Complete CSS design system (dark/light themes)
types.ts window.omni type declarations

Pages

Page Purpose
Dashboard.tsx System info, emulator overview, recent games, quick actions
EmulatorsPage.tsx Emulator cards with install/configure/launch/uninstall actions
LibraryPage.tsx ROM library grid with cover art, auto-scan
ControllerPage.tsx Gamepad detection, button states, controller config
SettingsPage.tsx Directories, BIOS, emulator assignments, appearance, beta features, updates, about
UtilitiesPage.tsx ROM folder structure, RetroAchievements credentials

Components

Component Purpose
Sidebar.tsx Navigation sidebar (6 items + version)
BiosCheckPanel.tsx BIOS file scanner
GameDetailModal.tsx Game detail view with metadata, achievements, screenshots
ReleaseNotesModal.tsx Markdown release notes display

Hooks

Hook Purpose
useGamepadNav.ts 60fps gamepad polling, D-Pad/button navigation, controller detection

Supported Emulators

Core Emulators

Emulator ID Description Systems Download Formats
RetroArch retroarch Multi-system emulator frontend NES, SNES, N64, GB, GBC, GBA, PS1, PCE, Sega MD, Sega Saturn, Dreamcast 7z
Dolphin dolphin GameCube & Wii emulator GC, Wii 7z, DMG, AppImage
RPCS3 rpcs3 PlayStation 3 emulator PS3 7z, AppImage (no macOS)
Eden eden Nintendo Switch emulator Switch ZIP, DMG, AppImage
PCSX2 pcsx2 PlayStation 2 emulator PS2 7z, tar.xz, AppImage
DuckStation duckstation PlayStation 1 emulator PS1 ZIP, AppImage
MAME mame Multi Arcade Machine Emulator Arcade EXE, ZIP (no macOS download)
PPSSPP ppsspp PlayStation Portable emulator PSP 7z, ZIP, AppImage
melonDS melonds Nintendo DS emulator NDS ZIP, AppImage
Flycast flycast Dreamcast/Naomi/Atomiswave emulator Dreamcast ZIP, AppImage

Frontends

Frontend ID Description Gated
ES-DE esde EmulationStation Desktop Edition Beta
NeoStation neostation Flutter-based frontend with ScreenScraper Beta
Pegasus pegasus Themeable game launcher Beta
EmuBuddy emubuddy Automated emulation frontend No

Detection

OmniEmu detects installed emulators via:

  1. Default hardcoded paths per platform
  2. Marker file (userData/emulators/<id>/.installed)
  3. Alternative common paths (Homebrew, snap, Flatpak, etc.)
  4. System which/where lookup

Supported Systems

System ID Name Primary Emulator Alternatives
nes Nintendo Entertainment System RetroArch (Nestopia) RetroArch (Mesen, FCEUX)
snes Super Nintendo RetroArch (Snes9x) RetroArch (bsnes HD)
n64 Nintendo 64 RetroArch (Mupen64Plus-Next) RetroArch (Parallel)
gb Game Boy RetroArch (Gambatte) RetroArch (SameBoy)
gbc Game Boy Color RetroArch (Gambatte) RetroArch (SameBoy)
gba Game Boy Advance RetroArch (mGBA) RetroArch (VBA-M)
nds Nintendo DS melonDS RetroArch (melonDS)
ps1 PlayStation 1 DuckStation RetroArch (SwanStation)
ps2 PlayStation 2 PCSX2 —
ps3 PlayStation 3 RPCS3 —
psp PlayStation Portable PPSSPP —
gc Nintendo GameCube Dolphin —
wii Nintendo Wii Dolphin —
switch Nintendo Switch Eden —
arcade Arcade MAME RetroArch (MAME)
dreamcast Sega Dreamcast Flycast RetroArch (Flycast)
sega-md Sega Mega Drive / Genesis RetroArch (Genesis Plus GX) —
sega-saturn Sega Saturn RetroArch (Yaba Sanshiro) —
pce PC Engine / TurboGrafx-16 RetroArch (Mednafen PCE) —

ROM Format Support

Extension System(s)
.nes NES
.sfc, .smc SNES
.n64, .z64, .v64 N64
.gb Game Boy
.gbc Game Boy Color
.gba Game Boy Advance
.nds Nintendo DS
.iso, .bin, .cue PS1, PS2, PS3, PSP, GC, Wii, Saturn
.chd PS1, PS2, PSP, Dreamcast, Saturn
.pbp PSP
.cso PSP
.gcm, .gcz, .rvz GameCube
.wbfs, .wad Wii
.nsp, .xci Switch
.pkg PS3
.m3u Multi-disc games
.zip, .7z Arcade (MAME), various
.gdi, .cdi Dreamcast
.rom Various

Platform is guessed from file extension, with directory name as override (e.g. .iso in ps2/ is classified as PS2).

Configuration Presets

Built-In Presets

Emulator Preset Name Config Files
RetroArch OmniEmu Recommended retroarch.cfg
RetroArch OmniEmu Performance retroarch.cfg
Dolphin OmniEmu Recommended Config/Dolphin.ini, Config/GFX.ini
RPCS3 OmniEmu Recommended config.yml
Eden OmniEmu Recommended Config.json
PCSX2 OmniEmu Recommended inis/PCSX2.ini
DuckStation OmniEmu Recommended settings.ini
MAME OmniEmu Recommended mame.ini
melonDS OmniEmu Recommended melonDS.ini
Flycast OmniEmu Recommended emu.cfg
ES-DE OmniEmu Recommended Generates es_settings.xml, es_find_rules.xml
NeoStation OmniEmu Recommended Generates omniemu_config.json
Pegasus OmniEmu Recommended Generates metadata.pegasus.txt per ROM dir

Preset Loading Priority

  1. Remote URL (https://raw.githubusercontent.com/mileswolfallen2/OmniEmu2.0/main/presets.json)
  2. Local file (userData/presets.json)
  3. Built-in presets (compiled into the app)

Remote Preset Source

Configurable in Settings > Presets. Point to any JSON file following the presets.json schema.

IPC API Reference

System

Channel Arguments Returns
system:info — SystemInfo
system:platform-name — string

Emulators

Channel Arguments Returns
emulators:list — EmulatorConfig[]
emulators:states — EmulatorState[]
emulators:check id: string EmulatorState
emulators:install id: string EmulatorState
emulators:configure id, installPath { success, state }
emulators:presets id: string ConfigPreset[]
emulators:configured id, installPath? boolean
emulators:launch id: string boolean
emulators:uninstall id: string { removed, state }
emulators:open-website id: string boolean
emulators:system-assignments — Record<string, string[]>
emulators:update-controller-config id, installPath, controllerName? boolean

ROMs / Games

Channel Arguments Returns
roms:scan directory?: string GameEntry[]
roms:select-directory — string | null
game:launch emulatorId, romPath boolean
games:recent — GameEntry[]
games:clear-recent — boolean
games:scrape-art title, platform string | undefined
games:cache-covers { romPath, coverUrl }[] boolean
games:scrape-metadata romPath, title, platform GameMetadata
games:achievements romPath, title, platform AchievementInfo | null

Settings

Channel Arguments Returns
settings:get — AppSettings
settings:save Partial<AppSettings> AppSettings
settings:reset — AppSettings

BIOS

Channel Arguments Returns
bios:list-known — BiosEntry[]
bios:scan directory?: string BiosCheckResult[]
bios:select-directory — string | null
bios:configure-retroarch configDir, biosDir boolean

RetroAchievements

Channel Arguments Returns
retroachievements:save username, password Record<string, boolean>

Utilities

Channel Arguments Returns
utilities:regenerate-roms-structure — boolean

Updates

Channel Arguments Returns
updates:check — boolean
updates:download — boolean
updates:quit-and-install — boolean

Outbound Events (Main -> Renderer)

Event Data
emulators:install-progress InstallProgress
updates:status { status, version, releaseNotes, message, manualLink }
updates:download-progress { percent, bytesPerSecond, transferred, total }

File Structure

OmniEmu2.0/
├── src/
│   ├── main/                  # Electron main process
│   │   ├── index.ts           # Entry point
│   │   ├── emulators.ts       # Emulator registry & ROM scanning
│   │   ├── configurator.ts    # Config presets & emulator setup
│   │   ├── ipc.ts             # IPC handler registration
│   │   ├── preload.ts         # Context bridge (window.omni)
│   │   ├── platform.ts        # OS/arch detection
│   │   ├── settings.ts        # Settings persistence
│   │   ├── installer.ts       # Download & install emulators
│   │   ├── scraper.ts         # Art & metadata scraping
│   │   ├── updater.ts         # Auto-update
│   │   ├── bios.ts            # BIOS detection
│   │   └── ra.ts              # RetroAchievements
│   ├── renderer/              # React UI
│   │   ├── App.tsx            # Root component
│   │   ├── main.tsx           # React entry point
│   │   ├── index.html         # HTML shell
│   │   ├── styles.css         # Design system
│   │   ├── types.ts           # window.omni types
│   │   ├── pages/             # Page components
│   │   ├── components/        # Shared components
│   │   ├── hooks/             # Custom hooks
│   │   └── utils/             # Utilities (markdown)
│   └── shared/
│       └── types.ts           # Shared TypeScript types
├── assets/                    # App icons
├── scripts/                   # Build & install scripts
├── presets.json               # Remote preset source
├── package.json               # Project config & electron-builder
├── vite.config.ts             # Vite build config
├── tsconfig.json              # Base TS config
├── tsconfig.main.json         # Main process TS config
├── tsconfig.renderer.json     # Renderer TS config
├── LICENSE                    # MIT
└── README.md                  # Project docs

Runtime Directories

Path Platform Contents
userData/settings.json All App settings
userData/cache/scrape-cache.json All Cover art cache
userData/cache/metadata-cache.json All Game metadata cache
userData/cache/ra-game-list-cache.json All RetroAchievements game lists
userData/emulators/<id>/.installed All Installed emulator marker
userData/configs/ All Config state markers
~/Documents/roms/ Default ROM library root
~/Documents/roms/<system>/ Default System-specific ROM folders

Build & Development

Prerequisites

  • Node.js 18+
  • npm
  • Python 3 (for icon generation)
  • Platform-specific tools:
    • macOS: Xcode Command Line Tools
    • Windows: NSIS (for installer)
    • Linux: libfuse2 (for AppImage)

Commands

# Install dependencies
npm install

# Development (hot reload)
npm run dev

# Build renderer + main
npm run build

# Type checking
npm run typecheck

# Package for current platform
npm run package:mac      # macOS universal
npm run package:win      # Windows x64
npm run package:linux    # Linux x64

# Package all platforms
npm run build:all        # macOS universal + Win x64/arm64 + Linux x64/arm64

Build Configuration

  • App ID: com.omniemu.app
  • Product Name: OmniEmu
  • Output: release/
  • Renderer: Vite builds to dist/renderer/
  • Main: TypeScript compiles to dist/main/
  • Publish: GitHub Releases

Release Artifacts

Platform Format Architecture Filename Pattern
macOS DMG Universal (x64 + ARM64) OmniEmu-{ver}-mac-universal.dmg
macOS ZIP Universal OmniEmu-{ver}-mac-universal.zip
Windows NSIS EXE x64 OmniEmu-{ver}-win-x64.exe
Windows NSIS EXE ARM64 OmniEmu-{ver}-win-arm64.exe
Windows ZIP x64 OmniEmu-{ver}-win-x64.zip
Windows ZIP ARM64 OmniEmu-{ver}-win-arm64.zip
Linux AppImage x86_64 OmniEmu-{ver}-linux-x86_64.AppImage
Linux AppImage ARM64 OmniEmu-{ver}-linux-arm64.AppImage

.yml files in releases are for electron-updater and can be ignored for manual installs.

Security

  • Context Isolation: Enabled
  • Node Integration: Disabled
  • Sandbox: Disabled (required for native module access)
  • CSP: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'
  • Single Instance: Enforced via app.requestSingleInstanceLock()
  • No secrets or API keys are committed to the repository

Contributing

Code Style

  • TypeScript strict mode
  • React functional components with hooks
  • No comments unless requested
  • Follow existing patterns and naming conventions

Key Conventions

  • Emulators are defined in knownEmulators array in src/main/emulators.ts
  • Config presets are in builtInPresets in src/main/configurator.ts
  • All IPC channels are registered in src/main/ipc.ts
  • All renderer API calls go through window.omni (defined in src/main/preload.ts)
  • Shared types are in src/shared/types.ts

Testing Changes

  1. Run npm run typecheck to verify types
  2. Run npm run build to verify compilation
  3. Run npm run dev to test in development mode
  4. Test on all target platforms if possible

Last updated: July 2026

Reference in New Issue View Git Blame Copy Permalink