# Welcome
Provenance โ the best free iOS game emulator for iPhone, iPad, and Apple TV. Play 38+ classic gaming systems including SNES, N64, PlayStation, GBA, and Dreamcast. Open source, no jailbreak required.
**The premier multi-system emulator for iOS, iPadOS, macOS, and tvOS.**
Play games from 38+ classic systems with beautiful library management, native Apple TV support, and museum-quality presentation. Available now on the **App Store**.
***
{% hint style="success" %}
**New to emulation?** Not sure what any of this is? โ [**What is an Emulator?**](/getting-started/what-is-an-emulator) โ a friendly explainer for everyone, including what you can play and why you'd want to.
{% endhint %}
## ๐ New Here? Start Here
### Get Provenance
**Recommended:** [Download from the App Store](https://apps.apple.com/us/app/provenance-app/id1596862805) (easiest, automatic updates)
**Alternative methods:** [Sideloading](/getting-started/installing-provenance/advanced/sideloading) or [Building from source](/getting-started/installing-provenance/advanced/building-from-source) (advanced users)
### First Time Setup
1. **Install** from App Store
2. **Add games** - See [Importing ROMs](/using-provenance/importing-roms)
3. **Start playing!**
Need help? Check the [FAQ](/faqs) or visit our [Discord](https://discord.gg/provenance).
***
## โจ What Makes Provenance Special
### ๐บ Premier Apple TV Emulator
The **only** emulator built natively for tvOS. Play retro games on your big screen with proper controller support, TopShelf integration, and optimized performance.
### ๐จ Museum-Quality Library
Automatic artwork, manuals, and game information. Your collection looks beautiful.
### ๐ฎ 38+ Systems Supported
From Atari 2600 to Nintendo 3DS, PlayStation to Sega Saturn. [See all systems โ](/platforms-and-performance/supported-systems)
### ๐ 100% Open Source
Fully transparent, no tracking, community-driven. Free forever when sideloaded or built from source.
### โ๏ธ iCloud Sync
Seamlessly sync your library, saves, and settings across all your devices (Provenance Plus).
***
## ๐ Quick Navigation
### Getting Started
* [Getting Started Guide](/getting-started/getting-started) - Install, import, and play in under 10 minutes
* [Installing Provenance](/getting-started/installing-provenance) - App Store, sideloading, building
* [BIOS Requirements](/getting-started/bios-requirements) - Required files for certain systems
* [Importing ROMs](/using-provenance/importing-roms) - Add games to your library
* [FAQ](/faqs) - Common questions answered
### Using Provenance
* [Supported Systems](/platforms-and-performance/supported-systems) - Full compatibility list
* [In-Game Menu](/using-provenance/in-game-menu) - Pause menu features and shortcuts
* [Controllers & Controls](/using-provenance/controllers-and-controls) - Supported controllers and setup
* [Skins Guide](/using-provenance/skins-guide) - Custom controller overlays
* [Game Saves](/using-provenance/saves) - Save states and battery saves
* [Quick Continue](/using-provenance/quick-continue) - Core picker and save previews
* [Screen Filters & Shaders](/using-provenance/shaders-and-filters) - CRT, LCD, VHS effects
* [Cheats](/using-provenance/cheats) - Game Genie, Action Replay, GameShark
* [Fast Forward](/using-provenance/fast-forward) - Speed up gameplay
* [Multiplayer](/using-provenance/multiplayer) - Local and online play
* [RetroAchievements](/using-provenance/retroachievements) - Earn achievements in retro games
### Platforms
* [Performance Optimization](/platforms-and-performance/performance-optimization) - Get the best experience
* [Apple TV / tvOS Guide](/platforms-and-performance/tvos-guide) - Big-screen gaming
* [iPad Features](/platforms-and-performance/ipad-features) - CRT bezel skins and keyboard support
* [Provenance Plus](/platforms-and-performance/provenance-plus) - iCloud sync and premium features
### Advanced
* [System-Specific Guides](/platforms-and-performance/system-guides) - N64, 3DS, GameCube/Wii deep dives
* [Building from Source](/getting-started/installing-provenance/advanced/building-from-source) - For developers
* [Contributing](/help-and-community/contribute) - Help improve Provenance
* [Troubleshooting](/help-and-community/troubleshooting) - Fix common issues
***
## ๐ What's New
### Recent Features
* ๐จ **Skins** โ Custom controller overlays from DeltaStyles.com (free for all users)
* ๐ฌ **Metal Shader Filters** โ 7 built-in filters: Simple CRT, Complex CRT, Mega Tron, ulTron, LCD, Game Boy, VHS
* ๐ **RetroAchievements** โ Earn achievements in retro games
* โฉ **Fast Forward** โ Speed up gameplay with a pause menu toggle or controller shortcut
* ๐ฎ **Multiplayer** โ Local multiplayer with up to 4 controllers
* ๐งฉ **Cheats** โ Game Genie, GameShark, Action Replay across 12+ native cores
* ๐ **Quick Continue** โ Save state previews and core picker on game launch
[See full changelog โ](https://github.com/Provenance-Emu/Provenance/releases)
***
## ๐ Provenance Plus
**Optional Provenance Plus upgrade** โ $3.99/month, $39.99/year, or a $99.99 one-time lifetime purchase to support development and unlock premium features:
* โ๏ธ **iCloud Sync** - Seamless library and save sync across devices
* ๐งช **Beta Access** - Test new features early via TestFlight
* ๐ฏ **Priority Support** - Get help faster
* โค๏ธ **Support Development** - Keep Provenance improving
**Note:** Provenance is **free forever** when sideloaded or built from source. Plus features support ongoing development.
***
## ๐ฌ Community
* **Discord:** [discord.gg/provenance](https://discord.gg/provenance)
* **GitHub:** [github.com/Provenance-Emu/Provenance](https://github.com/Provenance-Emu/Provenance)
* **Issues:** [Report bugs](https://github.com/Provenance-Emu/Provenance/issues)
* **Reddit:** [r/Provenance](https://www.reddit.com/r/Provenance/)
***
## ๐ Documentation Structure
This wiki is organized into sections:
* **Installation & Usage** - Getting Provenance installed and adding games
* **Info** - System compatibility, controllers, technical details
* **Help** - FAQ, troubleshooting, contributing
* **Development** - Building from source, contributing code
Use the sidebar navigation to explore, or search for specific topics.
***
**Last updated:** March 2026 **Provenance version:** Latest (App Store) **Wiki maintained by:** Provenance community
***
**๐ Main website:** [provenance-emu.com](https://provenance-emu.com) โ Download the best free iOS game emulator for iPhone, iPad, and Apple TV.
# Frequently Asked Questions
Common questions about Provenance โ free multi-system emulator for iOS, iPadOS, macOS, and tvOS with 38+ supported systems
Welcome to Provenance! Whether you just downloaded from the App Store or are a longtime user, this FAQ covers everything you need to know.
**Looking for advanced installation help?** See [Advanced Installation FAQ](/advanced/faqs-advanced) (sideloading, building from source)
***
## Getting Started
### Is Provenance really free?
{% hint style="success" %}
**Yes, 100% free!** You can download from the App Store and play all 38 systems without paying a cent.
{% endhint %}
**Provenance Plus** is an optional subscription or lifetime purchase ($3.99/month, $39.99/year, or $99.99 lifetime) that adds premium features like iCloud sync, but it's not required to enjoy the full emulation experience.
### What is Provenance Plus?
**Provenance Plus is your ticket to seamless multi-device gaming.**
**The experience:**
* Start playing on your Apple TV (big screen, couch gaming)
* Save your progress (automatic cloud backup)
* Pick up your iPhone on the commute
* Continue exactly where you left off
**How it works:**
* **Apple TV:** FREE CloudKit sync (no permanent storage, needs cloud backup)
* **iPhone/iPad/Mac:** Provenance Plus unlocks sync ($3.99/month, $39.99/year, or $99.99 lifetime)
| Feature | Free | Provenance Plus |
| --------------------------------- | ------ | --------------- |
| All 38 systems | โ
| โ
|
| Unlimited games | โ
| โ
|
| Save states | โ
| โ
|
| Controller support | โ
| โ
|
| Skins | โ
| โ
|
| **Apple TV CloudKit sync** | โ
FREE | โ
|
| **iPhone/iPad/Mac CloudKit sync** | โ | โ
|
| **Multi-device save sync** | โ | โ
|
| **Early access to new cores** | โ | โ
|
| **TestFlight beta access** | โ | โ
|
| **Priority support** | โ | โ
|
**What syncs:** โ
Your entire game library โ
Save states (freeze time, resume anywhere) โ
Battery saves (in-game progress) โ
Custom artwork and metadata โ
Skins (controller overlays) โ
BIOS files
**Pricing:** $3.99/month, $39.99/year, or $99.99 lifetime (with free trial)
### Do I need Provenance Plus to play games?
**No.** All emulation features are completely free. Provenance Plus only adds optional cloud sync and early access features.
### How do I install Provenance?
**From the App Store (recommended):**
1. Open the **App Store** on your iPhone, iPad, Mac, or Apple TV
2. Search for **"Provenance"**
3. Tap **Get** โ **Install**
4. โ
Done! Launch the app and start adding games
**Alternative methods:** See [Installing Provenance](/getting-started/installing-provenance) for sideloading or building from source.
### How do I update Provenance?
**App Store users:** Updates are automatic! Just keep automatic updates enabled in Settings โ App Store.
**Manual update:** App Store โ Provenance โ **Update** button (if available)
**Sideloaders/builders:** See [Updating Guide](/getting-started/installing-provenance/updating)
***
## Using Provenance
### How do I import ROMs?
{% tabs %}
{% tab title="AirDrop" %}
**Easiest method:**
1. AirDrop ROM files from Mac/iPhone to your device
2. Tap files โ Open in Provenance
3. Games appear in your library automatically
{% endtab %}
{% tab title="Files App" %}
1. Save ROMs to iCloud Drive or local Files
2. Navigate to the ROM file
3. Tap Share โ Open in Provenance
{% endtab %}
{% tab title="Safari Download" %}
1. Download ROM file in Safari
2. Tap the downloaded file in the downloads menu
3. Choose Open in Provenance
{% endtab %}
{% tab title="Mac Finder (USB)" %}
1. Connect device to Mac via USB
2. Open **Finder** โ Select your device
3. **Files** tab โ **Provenance**
4. Drag ROMs into the folder
{% endtab %}
{% endtabs %}
**Full guide:** [Importing ROMs](/using-provenance/importing-roms)
### Where can I get ROMs or BIOS files?
**We cannot provide ROMs or links** due to copyright law.
**Legal options:**
* โ
Create backups of games you own
* โ
Homebrew ROMs (free, legal games created by fans)
* โ
Public domain titles
{% hint style="danger" %}
**DO NOT** ask us or the community where to obtain copyrighted ROMs or BIOS files.
{% endhint %}
**BIOS files:** Some systems require BIOS files to work. See [BIOS Requirements](/getting-started/bios-requirements) for details.
### What systems are supported?
**38+ systems** including:
* Nintendo: NES, SNES, N64, Game Boy, GBA, GameCube, 3DS, DS
* PlayStation: PS1, PSP
* Sega: Genesis, Dreamcast, Saturn, Game Gear, Sega CD
* Atari, Neo Geo, TurboGrafx-16, and many more!
**Full list:** [Supported Systems](/platforms-and-performance/supported-systems)
### Which systems work best on my device?
{% tabs %}
{% tab title="iPhone / iPad" %}
* โ
**Perfect:** NES, SNES, GB, GBA, Genesis (all supported devices โ iPhone 8 or iPhone SE (2nd/3rd gen) or newer)
* โ
**Great:** PlayStation, N64 (iPhone 8 or iPhone SE (2nd/3rd gen) or newer)
* โ ๏ธ **Demanding:** GameCube, Dreamcast, PSP (iPhone 11+ or M1 iPad)
{% endtab %}
{% tab title="Apple TV" %}
* โ
**All systems** run great on Apple TV 4K
* โ ๏ธ **Apple TV HD** โ stick to 16-bit and earlier for best performance
{% endtab %}
{% tab title="Mac (Apple Silicon)" %}
* โ
All systems run perfectly on M1/M2/M3/M4 Macs
* No performance concerns on any Apple Silicon Mac
{% endtab %}
{% endtabs %}
**Full guide:** [Performance Optimization](/platforms-and-performance/performance-optimization)
### Can I use a controller?
**Yes!** Provenance supports nearly every modern controller:
**Fully supported:**
* ๐ฎ PlayStation 4 / PlayStation 5 DualShock / DualSense
* ๐ฎ Xbox One / Xbox Series X|S Controller
* ๐ฎ MFi (Made for iOS) controllers
* ๐ฎ 8BitDo controllers (most models)
* ๐ฎ Nintendo Switch Pro Controller
* ๐ฑ Siri Remote (tvOS 17+, basic games only)
**How to pair:** Settings โ Bluetooth โ Put controller in pairing mode
**Full guide:** [Controllers & Controls](/using-provenance/controllers-and-controls)
### What are skins? How do I use them?
**Skins** are custom controller overlays that change the look of on-screen buttons.
**Features:**
* ๐จ Hundreds of free designs (DeltaStyles.com)
* ๐ Classic console aesthetics, modern minimalist, game-themed
* ๐ฑ Compatible with Delta/Manic skins (`.deltaskin` format)
* โ
Free for all users (no Plus required)
**How to get skins:**
1. Visit [DeltaStyles.com](https://deltastyles.com) on your device
2. Download a `.deltaskin` file
3. Tap file โ Open in Provenance
4. Apply in Settings โ Controller Skins
**Full guide:** [Skins Guide](/using-provenance/skins-guide)
### How do I enable iCloud sync?
**Requires:** Provenance Plus subscription
**Setup:**
1. Subscribe to Provenance Plus in-app
2. Provenance โ **Settings** โ **iCloud Sync**
3. Toggle **ON**
4. Wait for initial sync (may take hours for large libraries)
5. Enable on all devices with the same Apple ID
**What syncs:** ROMs, save states, battery saves, custom artwork, skins, BIOS files
**What doesn't sync:** App settings only
**Full guide:** [Advanced ROM Management - iCloud Sync](/using-provenance/roms/advanced-management#icloud-sync-for-large-collections)
***
## Troubleshooting
Why is the app crashing?
**Common fixes:**
1. **Force quit and restart**
* Double-tap Home โ Swipe up on Provenance
* Relaunch the app
2. **Update to latest version**
* App Store โ Provenance โ Update (if available)
3. **Restart your device**
* Power off completely โ Wait 10 seconds โ Power on
4. **Check for corrupted database**
* If crashes persist, see [Troubleshooting Guide](/help-and-community/troubleshooting)
**Still crashing?** Join our [Discord](https://discord.gg/provenance) for live help.
Why is [specific game] slow or stuttering?
**Quick fixes:**
1. โ
**Close background apps** - Free up RAM
2. โ
**Disable visual filters** - Settings โ Turn off Smoothing/CRT
3. โ
**Update cores** - Newer cores often have performance improvements
4. โ
**Try alternate core** - Some games work better with different cores
5. โ
**Check device compatibility** - GameCube/Wii need iPhone 11+ or M1 iPad
**Detailed guide:** [Performance Optimization](/platforms-and-performance/performance-optimization)
Controller not working / buttons not responding
**Solutions:**
1. โ
**Re-pair controller**
* Settings โ Bluetooth โ Forget device โ Pair again
2. โ
**Update controller firmware**
* Connect to PS5/Xbox console to update firmware
* Or use manufacturer's app (8BitDo Firmware Updater, etc.)
3. โ
**Check battery**
* Low battery causes connection issues
4. โ
**Reduce interference**
* Move WiFi routers away from device
* Use Ethernet on Apple TV (improves Bluetooth stability)
**Full guide:** [Controllers & Controls](/using-provenance/controllers-and-controls)
ROMs won't import / games missing from library
**Checklist:**
1. โ
**Check file format** - See [Formatting ROMs](/using-provenance/roms/formatting-roms)
2. โ
**Verify BIOS files** - Some systems require BIOS: [BIOS Requirements](/getting-started/bios-requirements)
3. โ
**Restart app** - Force quit โ Relaunch
4. โ
**Re-import** - Delete file โ Re-add to Provenance
5. โ
**Check ROM hash** - Bad/corrupted ROMs won't import
**Multi-disc games:** Create M3U playlists - see [Advanced ROM Management](/using-provenance/roms/advanced-management#multi-disc-games-advanced)
iCloud sync not working
**Requirements:**
* โ
Provenance Plus active subscription
* โ
Available iCloud storage (Settings โ \[Your Name] โ iCloud)
* โ
Active internet connection
**Fixes:**
1. โ
**Disable โ Re-enable sync** - Settings โ iCloud Sync โ OFF โ ON
2. โ
**Force quit Provenance** - Restart app
3. โ
**Check iCloud storage** - May be full
4. โ
**Wait 10-15 minutes** - Large libraries take time
**Full guide:** [iCloud Sync Troubleshooting](/using-provenance/roms/advanced-management#troubleshooting-icloud-issues)
Dark mode not working on Apple TV
Provenance uses **system-wide Dark Mode**:
1. Apple TV **Settings** โ **General** โ **Appearance**
2. Select **Dark โ**
3. Provenance will update automatically
***
## Migration & Switching
Can I migrate from Delta or RetroArch?
**Yes!** Your ROMs and saves are compatible.
**From Delta:**
1. Export saves from Delta (if needed)
2. Import ROMs into Provenance (same files work)
3. BIOS files: Copy to Provenance if needed
4. โ
Delta skins work in Provenance (same `.deltaskin` format)
**From RetroArch:**
1. Export save files (.srm, .state)
2. Import ROMs into Provenance
3. Copy saves to Provenance saves folder (via Finder)
Can I switch from sideloaded Provenance to App Store version?
**Yes!** Your data transfers automatically:
1. Install **Provenance from App Store**
2. Launch app - library appears automatically (same data container)
3. (Optional) Delete sideloaded version
**iCloud note:** If using Provenance Plus, only enable sync on ONE version to avoid conflicts.
Can I use both App Store and sideloaded versions?
**Yes, but not recommended** - can cause iCloud sync conflicts.
**If you must:**
* Use different bundle IDs when building from source
* Only enable iCloud sync on ONE version
* Data won't automatically transfer between versions
***
## Provenance Plus
Why is CloudKit sync free on Apple TV but paid on iOS?
It's about the platform constraints:
**Apple TV has no permanent storage** - when you delete Provenance, your games and saves are gone. We include FREE CloudKit sync on tvOS so you never lose progress. It's not a premium feature, it's a necessity.
**iPhone/iPad have permanent storage** - your games and saves persist even if you delete the app. CloudKit sync is a premium convenience feature that lets you access your library on multiple devices.
**Bottom line:** tvOS sync = survival feature (free). iOS sync = premium multi-device experience (Plus).
Is Provenance Plus worth it?
**Worth it if you:**
* โ
**Own an Apple TV + iPhone/iPad** (seamless gaming across devices)
* โ
Want to start games on your couch, continue on your commute
* โ
Never want to lose save progress (automatic cloud backup)
* โ
Have multiple Apple devices (library syncs to all of them)
* โ
Want early access to new features
**Not worth it if you:**
* โ Only use Apple TV (sync is already free!)
* โ Only use one iOS device (manual backups work fine)
* โ Don't care about multi-device gaming
**The killer feature:** Start Final Fantasy VII on your TV, pick it up on your iPhone during lunch break, continue on your iPad in bed. All without manually transferring saves.
**Try it free:** We offer an App Store trial so you can experience seamless multi-device gaming before subscribing.
How do I cancel Provenance Plus?
**iOS/iPadOS:**
1. Settings โ \[Your Name] โ Subscriptions
2. Tap **Provenance Plus**
3. **Cancel Subscription**
**Mac:**
1. App Store โ \[Your Name] (top left) โ Settings
2. Manage Subscriptions โ Provenance Plus
3. Cancel
**Your subscription remains active until the end of the billing period.**
Does Provenance Plus work when sideloading?
**Yes!** But you need to use a **unique bundle ID** when building from Xcode.
**How:**
1. In Xcode, change bundle ID to something unique (e.g., `com.yourname.provenance`)
2. Build and install
3. Subscribe to Provenance Plus in-app
4. โ
Plus features will work
**Default bundle ID:** Won't work - app thinks it's App Store version but can't verify subscription.
***
## Advanced Topics
What if I don't have a Mac?
**App Store users:** No Mac needed! Just install from the App Store on your device.
**Advanced users:** See [Advanced Installation FAQ](/advanced/faqs-advanced) for sideloading without a Mac.
Is jailbreak required?
**No.** Provenance works on all non-jailbroken devices via the App Store.
Can I install without a computer?
**Yes!** Just download from the App Store directly on your device.
**Sideloading without a computer:** See [Advanced Installation FAQ](/advanced/faqs-advanced#no-computer) for alternative methods.
When is the next release?
Check our [GitHub Releases](https://github.com/Provenance-Emu/Provenance/releases) and [Milestones](https://github.com/Provenance-Emu/Provenance/milestones) for development status.
**App Store users:** Updates are automatic - no need to track releases manually!
***
## Community & Contributing
### How can I contribute?
We're always looking for help!
**Ways to contribute:**
* ๐ป **Development** - Browse [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues) and submit PRs
* ๐งช **Beta Testing** - Join Provenance Plus for TestFlight access
* ๐ **Documentation** - Improve this wiki on GitHub
* ๐ฅ **Content Creation** - Create YouTube tutorials
* ๐ฌ **Community Support** - Help users on [Discord](https://discord.gg/provenance)
**Full guide:** [Contributing](/help-and-community/contribute)
### Where can I get help?
**Need help?** We're here for you:
1. ๐ **Search this FAQ** - Most questions answered here
2. ๐ **Check Troubleshooting** - [Troubleshooting Guide](/help-and-community/troubleshooting)
3. ๐ฌ **Join Discord** - Live community support: [discord.gg/provenance](https://discord.gg/provenance)
4. ๐ **Report bugs** - [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
**Before asking:**
* โ
Search existing GitHub issues
* โ
Update to latest version
* โ
Read relevant wiki guides
***
## Still Have Questions?
{% hint style="success" %}
๐ฌ Join our [Discord](https://discord.gg/provenance) for live community support!
๐ Found a bug? Report it on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
๐ Advanced installation help? See [Advanced Installation FAQ](/advanced/faqs-advanced)
{% endhint %}
***
*Last updated: March 2026*
# What is an Emulator?
New to emulation? Here's what it is, why you want it, and what you can play โ explained for everyone.
Never heard of emulation before? You're in the right place. This page explains what emulators are, why people love them, and why right now โ with **Provenance** on your iPhone or Apple TV โ is the best time in history to discover them.
***
## The short version
An emulator is software that **pretends to be old gaming hardware**. Your iPhone runs the same game code that used to require a real Super Nintendo, PlayStation, or Game Boy โ no cartridges, no hardware, just software.
The result: **every game ever made for those systems**, playable on your phone, iPad, Mac, or Apple TV.
***
## What games are we talking about?
Decades of games across 38+ classic systems. If you've ever heard of any of these, emulation is for you:
**Nintendo systems**
* Super Mario World, Donkey Kong Country, Yoshi's Island *(SNES)*
* The Legend of Zelda: Ocarina of Time, GoldenEye, Mario Kart 64 *(N64)*
* Pokรฉmon Red/Blue/Gold/Silver, Tetris, Kirby *(Game Boy / GBC)*
* Pokรฉmon FireRed, Metroid Fusion, Castlevania: Aria of Sorrow *(GBA)*
* Zelda: A Link to the Past, Super Metroid, Chrono Trigger *(SNES)*
**PlayStation**
* Final Fantasy VII, VIII, IX, Tactics *(PS1)*
* Metal Gear Solid, Resident Evil, Crash Bandicoot, Spyro *(PS1)*
* God of War, GTA: San Andreas, Kingdom Hearts *(PS2)*
* Crisis Core, God of War: Chains of Olympus *(PSP)*
**Sega systems**
* Sonic the Hedgehog 1/2/3, Streets of Rage *(Genesis)*
* Phantasy Star, Shining Force, Ecco the Dolphin *(Genesis)*
* Sonic CD, Final Fight CD *(Sega CD)*
* Nights into Dreams, Panzer Dragoon Saga *(Saturn)*
* Sonic Adventure, Crazy Taxi, Jet Grind Radio *(Dreamcast)*
**And much more:** Atari 2600 through Jaguar, Neo Geo, TurboGrafx-16, PC Engine, WonderSwan, Virtual Boy, Nintendo DS, 3DS, GameCube, Wii, and dozens more.
***
## Why would I want this?
### 1. Play your collection anywhere
If you have a shelf of old cartridges or a box of discs in a closet, emulation lets you actually use them again โ on your phone, on your TV, without digging out aging hardware. You can make a digital backup of a cartridge or disc you own and play that backup in **Provenance**. Your games, on your terms.
### 2. The history of gaming, all in one place
Video games have a 50-year history. Emulation is how that history stays alive and accessible. Discovering classic games is like discovering an entire movie era you missed โ there are thousands of genuinely great games you've never heard of.
### 3. It's actually better than the original hardware
This sounds crazy but it's true. Emulators add things the original hardware never had:
* **Save anywhere** โ pause mid-level and come back later, no memory cards
* **Fast forward** โ skip slow cutscenes or grinding at 2ร or 4ร speed
* **Save states** โ rewind mistakes as if they never happened
* **CRT filters** โ recreate the warm scanline look of old TVs if you want it
* **Widescreen and HD rendering** โ some games support enhanced resolutions
* **Any controller you want** โ DualSense, Xbox controller, or clip-on iPhone gamepad
### 4. It fits in your pocket
Before smartphones, emulation required a computer, janky software, and some technical know-how. That kept it niche. Now you tap **Get** on the App Store and you're done. **Provenance** changed what's possible.
***
## What's a ROM?
You'll hear this word a lot. A **ROM** is a digital backup of a game โ the same data that used to live on a cartridge or disc, stored as a file.
* A Game Boy game is typically 256KBโ2MB โ smaller than a single photo
* A PlayStation disc is 500MBโ700MB
* An N64 cartridge is 8MBโ64MB
Think of it like ripping a CD to MP3 for your own use, but for games. **Provenance** is the player โ game files are what you play on it.
**Making backups from cartridges and discs you own** is the right way to build your library. It's a bit like ripping your DVD collection to a hard drive โ you already own the content, you're just making it usable in a modern way. We have a full guide on how to do this for cartridges, CDs, and DVDs:
โ [Ripping ROMs from Physical Media](/using-provenance/roms/ripping-roms)
***
## Is this legal?
**Emulators themselves are fully legal.** This has been confirmed in US courts (*Sega v. Accolade*, *Sony v. Connectix*). Software that recreates hardware behavior is protected.
**Game backups** occupy the same space as ripping CDs or DVDs โ making a personal backup of media you own for your own use is widely considered fair use, though copyright law in this area was written before digital media existed and hasn't fully caught up. The consensus: make backups of games you own, keep them for personal use.
**Provenance** doesn't include games and doesn't help you obtain them. What you do with your own collection is your business.
***
## What is Provenance, specifically?
**Provenance** is a **multi-system emulator** โ one app that handles 38+ different gaming systems. Most emulators only do one system (one for SNES, one for PlayStation, etc.). **Provenance** brings them all together with:
* A beautiful, unified game library with automatic cover art
* Native iPhone, iPad, Mac, and **Apple TV** support
* iCloud sync across all your devices
* CRT and LCD filters, controller skins, cheats, RetroAchievements
* 100% free and open source
***
## I'm sold. Now what?
{% tabs %}
{% tab title="Never played retro games before" %}
Start with something approachable:
1. **SNES** โ the best starting point. Perfect games, no BIOS needed.
* *Super Mario World* if you like platformers
* *The Legend of Zelda: A Link to the Past* if you like adventure
* *Chrono Trigger* or *Final Fantasy VI* if you like RPGs
2. **Game Boy Advance** โ surprisingly deep library. No BIOS needed.
* *Pokรฉmon FireRed/LeafGreen* โ the classic reimagined
* *Metroid Fusion* โ atmosphere, exploration, action
* *Castlevania: Aria of Sorrow* โ gothic action RPG
**Next step:** [Getting Started โ](/getting-started/getting-started)
{% endtab %}
{% tab title="I played games growing up" %}
Go straight to the stuff you remember:
* Played SNES or Genesis as a kid โ those work perfectly, no BIOS needed
* Had a PlayStation โ grab some PS1 BIOS files first โ [BIOS Requirements](/getting-started/bios-requirements)
* Had a Game Boy or GBA โ no BIOS needed, just drop ROMs in
Then explore what you *missed* โ there are entire systems and genres you've never touched.
**Next step:** [Getting Started โ](/getting-started/getting-started)
{% endtab %}
{% tab title="I know what I" %}
You're here for one reason. Skip the tour:
* [Install from App Store](/getting-started/installing-provenance/app-store)
* [BIOS Requirements](/getting-started/bios-requirements)
* [Importing ROMs](/using-provenance/importing-roms)
* [Supported Systems](/platforms-and-performance/supported-systems)
{% endtab %}
{% endtabs %}
***
## See Also
* [Getting Started Guide](/getting-started/getting-started) โ install, import, and play in 10 minutes
* [Supported Systems](/platforms-and-performance/supported-systems) โ full list of every system **Provenance** supports
* [Ripping ROMs from Physical Media](/using-provenance/roms/ripping-roms) โ make ROMs from cartridges you own
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ which controllers work and how to set them up
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Getting Started
Go from zero to playing your first game in under 10 minutes
New to Provenance? This walkthrough takes you from installation to playing your first game, step by step.
***
## Step 1: Install Provenance
{% tabs %}
{% tab title="iPhone / iPad" %}
1. Open the **App Store**
2. Search for **"Provenance"** or tap: [Provenance on App Store](https://apps.apple.com/us/app/provenance-app/id1596862805)
3. Tap **Get** (it's free โ \~2.5 GB download)
4. Once installed, tap **Open**
{% endtab %}
{% tab title="Apple TV" %}
1. On your Apple TV, open the **App Store**
2. Search for **"Provenance"**
3. Select **Get** (it's free)
4. Once installed, open Provenance from the Home Screen
**Tip:** You'll need a Bluetooth controller โ the Siri Remote can navigate menus but not play games. See [Apple TV Guide](/platforms-and-performance/tvos-guide).
{% endtab %}
{% tab title="Mac (Apple Silicon)" %}
1. Open the **App Store** on your Mac
2. Search for **"Provenance"**
3. Click **Get** (it's free)
4. Launch from Applications or Launchpad
**Requires:** macOS 13.0+ on Apple Silicon (M1 or later).
{% endtab %}
{% endtabs %}
{% hint style="success" %}
That's it for installation. No developer account, no sideloading, no Xcode required.
{% endhint %}
**Want to sideload or build from source instead?** See [Alternative Installation Methods](/getting-started/installing-provenance/advanced).
***
## Step 2: Get Your Game Files Ready
Provenance plays ROMs โ digital copies of game cartridges and discs. You'll need:
1. **ROM files** for the games you want to play
2. **BIOS files** (only for certain systems โ see below)
### Which systems need BIOS files?
Most systems work without any BIOS. These popular systems **do NOT need BIOS** โ just drop in ROMs and play:
* NES, SNES, N64, Game Boy, GBC, GBA, Genesis, Game Gear, Neo Geo Pocket, Atari 2600/7800
These systems **require BIOS files** before games will run:
* PlayStation (3 BIOS files)
* Sega CD (3 BIOS files)
* Sega Saturn (3 BIOS files)
* TurboGrafx-CD, Atari Lynx, Atari 5200, ColecoVision
**Full list with filenames and MD5 hashes:** [BIOS Requirements](/getting-started/bios-requirements)
{% hint style="warning" %}
Import BIOS files **before** importing ROMs for that system. Provenance auto-detects them by MD5 hash โ filenames don't matter.
{% endhint %}
### Supported ROM formats
| Format | Type | Best for |
| --------------- | --------------------- | ----------------------------------------- |
| `.zip` | Compressed single ROM | Most cartridge games |
| `.7z` | Compressed single ROM | Most cartridge games |
| `.chd` | Compressed disc image | CD-based games (PS1, Sega CD, etc.) |
| `.cue` + `.bin` | Disc image pair | CD-based games (keep both files together) |
| `.iso` | Disc image | PSP, some CD systems |
**Full formatting guide:** [Formatting ROMs](/using-provenance/roms/formatting-roms)
***
## Step 3: Import Your First Game
Pick the method that works best for you:
{% tabs %}
{% tab title="AirDrop (Fastest)" %}
**Mac to iPhone/iPad โ the quickest way to get started.**
1. On your Mac, find your ROM file (e.g., `SuperMarioWorld.zip`)
2. Right-click โ **Share** โ **AirDrop**
3. Select your iPhone/iPad
4. On your device, tap **Provenance** when prompted
5. The game appears in your library automatically
{% endtab %}
{% tab title="Files App" %}
**Works with iCloud Drive, Dropbox, Google Drive, or local storage.**
1. Save your ROM to the **Files** app (iCloud Drive, local, or any cloud provider)
2. Open **Files**, find your ROM
3. Tap and hold โ **Share** โ **Copy to Provenance**
4. The game appears in your library
{% endtab %}
{% tab title="Web Browser" %}
**Import from built-in web server (great for bulk transfers).**
1. Open Provenance and tap the **+** button (or Settings โ Import/Export)
2. Note the IP address shown (e.g., `http://192.168.1.42`)
3. On your computer, open that URL in a browser
4. Click **Imports**, then drag and drop ROM files
5. Games appear in your library when the upload finishes
**WebDAV option:** Connect to `http://[device-ip]:81` from Finder (Mac) or any WebDAV client.
{% endtab %}
{% tab title="Safari Download" %}
**Download directly on your device.**
1. Open Safari on your iPhone/iPad
2. Download a ROM file from your source
3. Tap the downloaded file in Safari's download bar
4. Choose **Open in Provenance**
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Importing BIOS files** works the same way โ just AirDrop, copy, or upload them. Provenance auto-detects BIOS files by their contents and puts them in the right place.
{% endhint %}
**Detailed guide:** [Importing ROMs](/using-provenance/importing-roms)
***
## Step 4: Play!
1. Your imported game appears in the **Library** with cover art (auto-matched)
2. **Tap the game** to launch it
3. Use **on-screen controls** or a connected **Bluetooth controller**
4. To pause, tap the **Menu** button (top of screen) for save states, settings, and quit options
### Essential controls while playing
| Action | On-screen | Controller |
| --------------- | -------------------- | -------------------- |
| Pause / Menu | Tap pause button | Press Menu / Options |
| Save state | Pause โ Save State | โ |
| Load state | Pause โ Load State | โ |
| Fast forward | Pause โ Fast Forward | โ |
| Quit to library | Pause โ Quit | โ |
***
## Step 5: Make It Yours
Now that you're playing, here are ways to improve the experience:
### Connect a controller
Physical controllers make a huge difference. Any MFi or Bluetooth controller works:
* **Best overall:** PlayStation DualSense, Xbox Wireless Controller
* **Best for iPhone:** Razer Kishi V2, Backbone One (clip-on style)
* **Budget-friendly:** 8BitDo SN30 Pro
**Full guide:** [Controllers & Controls](/using-provenance/controllers-and-controls)
### Customize your on-screen controls
Don't like the default buttons? **Skins** are free custom controller overlays:
1. Visit [DeltaStyles.com](https://deltastyles.com) on your device
2. Download a skin for your system (`.deltaskin` file)
3. Tap the file โ **Open in Provenance**
4. Apply in Settings โ Controller Skins
**Full guide:** [Skins Guide](/using-provenance/skins-guide)
### Sync across devices (optional)
**Provenance Plus** ($3.99/month, $39.99/year, or $99.99 lifetime) syncs your library, saves, and settings across iPhone, iPad, Mac, and Apple TV via iCloud.
**Apple TV users:** iCloud sync is included free!
***
## Quick Reference
| Task | Where |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| Import games | **+** button in Library, or AirDrop / Files |
| Change controls | Settings โ Controller Skins |
| Connect controller | Pair via Bluetooth (Settings โ Bluetooth) |
| Save/load state | Pause menu during gameplay |
| Check BIOS status | Settings โ Cores โ \[System name] |
| Get help | [Troubleshooting](/help-and-community/troubleshooting) or [Discord](https://discord.gg/provenance) |
***
## Troubleshooting First-Time Setup
Game doesn't appear after importing
1. Check the file format โ must be a [supported ROM format](/using-provenance/roms/formatting-roms)
2. Pull down to refresh the library
3. Force quit Provenance and reopen
4. If importing via web server, wait for the upload to fully complete before navigating away
"Missing BIOS" or game shows black screen
The system requires BIOS files. Check [BIOS Requirements](/getting-started/bios-requirements) for the exact files needed, then import them the same way you imported ROMs. Verify in Settings โ Cores that the BIOS shows as detected (green).
Game runs slowly
* Close other apps running in the background
* Try a different emulator core (long-press game โ Game Settings โ Core)
* Some systems (N64, PSP, Dreamcast, 3DS) need newer hardware โ see [Performance Optimization](/platforms-and-performance/performance-optimization)
No sound
* Check your device isn't in Silent Mode (flip the side switch on iPhone)
* Make sure volume is up
* Check that no Bluetooth audio device is connected unexpectedly
Controller not working
* Ensure the controller is paired in Settings โ Bluetooth
* Open a game, pause โ check controller is assigned to Player 1
* See [Controllers Guide](/using-provenance/controllers-and-controls) for setup details
***
{% hint style="success" %}
**Need more help?** Check the [Troubleshooting Guide](/help-and-community/troubleshooting), browse the [FAQ](/faqs), or join the [Provenance Discord](https://discord.gg/provenance).
{% endhint %}
# Installing Provenance
How to install Provenance on your Apple device
Provenance supports **38+ retro gaming systems** and runs on iPhone, iPad, Apple TV, and Mac. Choose the installation method that works best for you.
## ๐ฑ Recommended: App Store (Easiest)
**The simplest way to install Provenance is directly from the App Store.**
โ
**Benefits:**
* โก One-tap installation
* ๐ Automatic updates
* โ๏ธ iCloud sync (with Provenance Plus)
* ๐ **100% FREE** (with optional Provenance Plus subscription)
* โจ No technical setup required
๐ [**Get Provenance from the App Store โ**](/getting-started/installing-provenance/app-store)
***
## ๐ง Alternative Installation Methods
For advanced users who want more control or need specific features:
* [**Alternative Installation Guide**](/getting-started/installing-provenance/advanced) - Overview of sideloading and building options
* [Sideloading](/getting-started/installing-provenance/advanced/sideloading) - Install pre-built .ipa files (free, requires re-signing every 7 days)
* [Building from Source](/getting-started/installing-provenance/advanced/building-from-source) - Compile directly from GitHub (for developers)
โ ๏ธ **Note:** Alternative methods require a (free) Apple Developer account and periodic re-signing. Most users should use the App Store version.
***
## ๐ Updating Provenance
* **App Store users:** Updates are automatic through the App Store
* **Sideloaders/builders:** See [Updating Guide](/getting-started/installing-provenance/updating)
***
## โ Frequently Asked Questions
**Is Provenance really free?**\
Yes! Provenance is 100% free to download and use. Provenance Plus is an optional subscription that adds premium features like iCloud sync and beta access.
**What's Provenance Plus?**\
An optional subscription ($3.99/month, $39.99/year, or $99.99 lifetime) that unlocks:
* โ๏ธ iCloud library and save sync across devices
* ๐ Early access to new cores and features
* ๐ฎ Priority support
See the [App Store installation guide](/getting-started/installing-provenance/app-store) for full details.
**Do I need to sideload?**\
No! The App Store version is recommended for 90%+ of users. Sideloading is only necessary if you want bleeding-edge development builds.
**Can I migrate from sideload to App Store?**\
Yes! Your saves and ROMs will transfer. See the [App Store guide](/getting-started/installing-provenance/app-store) for migration instructions.
***
## ๐ Next Steps
After installation:
1. ๐ [BIOS Requirements](/getting-started/bios-requirements) - Required system files for certain emulators
2. ๐ฎ [Importing ROMs](/using-provenance/importing-roms) - Add your game library
3. ๐ฎ [Controllers & Controls](/using-provenance/controllers-and-controls) - Connect your favorite controller
4. โ๏ธ [Troubleshooting](/help-and-community/troubleshooting) - Common issues and solutions
# App Store (Recommended)
Install Provenance for free from the App Store on iPhone, iPad, Mac, and Apple TV โ the easiest way to play retro games on iOS and tvOS
**The easiest way to get Provenance on your iPhone, iPad, or Apple TV.**
***
## โ
Installation Steps
### 1. Open the App Store
On your iOS device:
* Tap the **App Store** icon
* Search for **"Provenance"** or **"Provenance Emulator"**
* Or visit directly: [Provenance on App Store](https://apps.apple.com/us/app/provenance-app/id1596862805)
### 2. Download
* Tap **Get** (it's free)
* Authenticate with Face ID, Touch ID, or password
* Wait for download to complete (\~2.5 GB)
### 3. Launch
* Tap **Open** from App Store, or find Provenance on your home screen
* Grant any permissions requested (Files access, notifications)
* You're ready to add games!
***
## ๐ฑ Supported Devices
**Provenance works on:**
* โ
iPhone (iOS 16.0+) โ iPhone 8 or newer, including iPhone SE (2nd & 3rd generation)
* โ
iPad (iPadOS 16.0+) โ iPad 5th gen, iPad Air 3rd gen, iPad mini 5th gen, or any iPad Pro
* โ
Apple TV (tvOS 16.0+) โ Apple TV HD (4th gen) or Apple TV 4K
* โ
Apple Vision Pro (visionOS 1.0+)
* โ
Mac (macOS 13.0+ with Apple Silicon)
**Note:** Some systems (like 3DS, PSP, Dreamcast) require more powerful devices for good performance.
***
## ๐ Free vs Provenance Plus
**Free (App Store version):**
* All 38+ systems supported
* Full emulation features
* On-screen controls and controller support
* Save states and battery saves
* Local library management
**Provenance Plus ($3.99/month, $39.99/year, or $99.99 lifetime):**
* โ๏ธ **iCloud Sync** - Library, saves, and settings across all devices
* ๐งช **Beta Access** - Test new features early via TestFlight
* ๐ฏ **Priority Support** - Get help faster
* โค๏ธ **Support Development** - Keep Provenance improving
**You decide:** The free version is fully functional. Plus supports the project and adds convenience features.
***
## โฌ๏ธ Automatic Updates
**App Store version updates automatically:**
* New features arrive seamlessly
* Bug fixes applied without manual work
* Just keep "Automatic Downloads" enabled in Settings โ App Store
**Manual update:**
1. Open App Store
2. Tap your profile icon (top right)
3. Scroll to Provenance
4. Tap **Update** if available
***
## โ Troubleshooting
### "This app is not available in your region"
Provenance may not be available in all App Store regions due to Apple's policies. **Alternatives:**
* Use a different Apple ID with a supported region
* [Sideload](/getting-started/installing-provenance/advanced/sideloading) using AltStore (no region restrictions)
* [Build from source](/getting-started/installing-provenance/advanced/building-from-source) (developers)
### "Cannot download - not enough storage"
Provenance is \~2.5 GB and needs additional space for games:
* Free up space by deleting unused apps/files
* Move photos/videos to iCloud or computer
* Recommended: 10+ GB free for comfortable use
### Installation stuck or won't complete
1. Force-close App Store app
2. Restart your device
3. Try downloading again
4. If still stuck, check Apple's [System Status](https://www.apple.com/support/systemstatus/) for App Store issues
### App crashes on launch
1. Ensure your device is on iOS 16.0+ (Settings โ General โ About)
2. Restart your device
3. Delete and reinstall Provenance
4. If still crashing, [report the issue](https://github.com/Provenance-Emu/Provenance/issues)
***
## ๐ฎ Next Steps
**After installing:**
1. [Import ROMs](/using-provenance/importing-roms) - Add games to your library
2. [BIOS Requirements](/getting-started/bios-requirements) - Some systems need BIOS files
3. [Controllers](/using-provenance/controllers-and-controls) - Connect a gamepad for best experience
**Optional:**
* Subscribe to **Provenance Plus** for iCloud sync
* Join the [Discord community](https://discord.gg/provenance)
* Follow [@provenanceapp](https://twitter.com/provenanceapp) for updates
***
## ๐ Switching from Sideloaded Version
**Already using a sideloaded version?** You can switch:
1. **Backup your data** (library, saves) - see [Restoring Files](/advanced/restoring-files)
2. Delete the sideloaded app
3. Install from App Store
4. Restore your data
**Note:** App Store and sideloaded versions use different data directories. Manual migration needed.
***
## ๐ App Store vs Sideloading Comparison
| Feature | App Store | Sideloading |
| ------------------- | -------------------------------------------- | ----------------------------------------- |
| **Installation** | One-tap from App Store | Requires AltStore or computer |
| **Updates** | Automatic | Manual re-sideload |
| **Revocation risk** | None (official app) | Possible (7-day limit with free AltStore) |
| **Provenance Plus** | $3.99/month, $39.99/year, or $99.99 lifetime | Not available (all features free) |
| **iCloud Sync** | Requires Plus subscription | Requires custom setup |
| **Best for** | Most users (easiest) | Power users, free alternative |
**Recommendation:** Use App Store unless you specifically need free alternative or custom builds.
***
{% hint style="info" %}
Need help? Check the [Troubleshooting Guide](/help-and-community/troubleshooting) or ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Alternative Installation Methods
Sideloading and building from source as alternatives to the App Store
**For advanced users who prefer alternatives to the App Store.**
***
## Why Use Alternative Methods?
**Most users should use the** [**App Store**](/getting-started/installing-provenance/app-store) - it's easiest and updates automatically.
**Consider alternatives if you:**
* Want Provenance completely free (no Provenance Plus subscription)
* Need custom builds or modifications
* Are in a region where Provenance isn't on the App Store
* Prefer open-source transparency (build from source)
* Want to contribute to development
***
## Installation Options
### 1. Sideloading (Easiest Alternative)
**Use AltStore to install Provenance IPA files without a computer (after initial setup).**
[๐ Full Sideloading Guide โ](/getting-started/installing-provenance/advanced/sideloading)
**Best for:** Users who want free alternative to App Store without development setup.
**Pros:**
* No Xcode or development knowledge needed
* Can install on any iOS device
* All features unlocked (no Provenance Plus subscription)
* Updates available (manual re-sideload)
**Cons:**
* Initial setup requires computer
* 7-day limit with free Apple Developer account (AltStore auto-refreshes)
* Manual updates (not automatic like App Store)
***
### 2. Building from Source (Developers)
**Compile Provenance yourself from the GitHub source code.**
[๐ Full Building Guide โ](/getting-started/installing-provenance/advanced/building-from-source)
**Best for:** Developers, contributors, or users who want maximum control.
**Pros:**
* 100% free and open-source
* Can modify code and customize
* Can contribute improvements back to project
* Latest features before official release
**Cons:**
* Requires macOS, Xcode, and development knowledge
* More complex setup
* Must rebuild for updates
* Requires Apple Developer account (free or paid)
***
## Comparison: Installation Methods
| Method | Difficulty | Cost | Updates | Best For |
| --------------- | ------------ | -------------------- | -------------- | ---------------- |
| **App Store** | โญ Easiest | Free (Plus optional) | Automatic | Most users |
| **Sideloading** | โญโญ Moderate | Free | Manual | Free alternative |
| **Building** | โญโญโญ Advanced | Free | Manual rebuild | Developers |
***
## Feature Comparison
| Feature | App Store | Sideloading | Building from Source |
| ---------------------- | ----------------- | ------------ | -------------------- |
| **All systems** | โ
| โ
| โ
|
| **Save states** | โ
| โ
| โ
|
| **Controllers** | โ
| โ
| โ
|
| **Auto updates** | โ
| โ Manual | โ Manual |
| **iCloud sync** | Plus only | Custom setup | Custom setup |
| **Beta access** | Plus only | Manual IPA | Latest code |
| **No subscription** | โ (Plus optional) | โ
| โ
|
| **Code modifications** | โ | โ | โ
|
***
## Switching Between Methods
You can switch between installation methods, but note:
**Data is NOT automatically shared:**
* App Store version stores data separately
* Sideloaded/built versions use different directories
* Manual backup/restore needed when switching
**To migrate:**
1. Backup library and saves from current installation
2. Install new version via preferred method
3. Restore backup to new installation
[See backup guide โ](/advanced/restoring-files)
***
## Recommendation
**For 90% of users:** Use the [**App Store version**](/getting-started/installing-provenance/app-store)
* Easiest installation
* Automatic updates
* Official support
* Optional Plus features
**For power users:** Try [**sideloading**](/getting-started/installing-provenance/advanced/sideloading) if you want free alternative
**For developers:** [**Build from source**](/getting-started/installing-provenance/advanced/building-from-source) to contribute or customize
***
## Next Steps
**Choose your method:**
* [๐ฑ App Store Installation](/getting-started/installing-provenance/app-store) - Recommended for most users
* [๐ง Sideloading Guide](/getting-started/installing-provenance/advanced/sideloading) - Free alternative
* [๐ป Building from Source](/getting-started/installing-provenance/advanced/building-from-source) - Developers
**After installation:**
* [Import ROMs](/using-provenance/importing-roms)
* [BIOS Requirements](/getting-started/bios-requirements)
* [Controller Setup](/using-provenance/controllers-and-controls)
***
{% hint style="info" %}
Need help? Check the [Advanced Installation FAQ](/advanced/faqs-advanced) or ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Sideloading
Easy. Install pre-built releases (or pre-releases).
Prebuilt .ipa releases can be sideloaded onto your devices and must be re-signed using your own developer profile(s).
## **Download Provenance**
1. First, download a [Release](https://github.com/Provenance-Emu/Provenance/releases) or Prerelease of Provenance (unless using AltStore, direct source download link in AltStore instructions).
2. Choose a sideloading method:
### **Sideloading Options:**
* โ๏ธ [**AltStore**](#altstore) ยท macOS/Windows
* ๐ [**iOS App Signer**](#ios-app-signer) ยท macOS + Xcode or Configurator
* ๐งช [**AltDeploy**](#altdeploy) ยท macOS
{% hint style="success" %}
**Requirements**
* *Free* [Apple Developer](https://9to5mac.com/2016/03/27/how-to-create-free-apple-developer-account-sideload-apps/) account (at a minimum) or a *paid* account.
๐ **DO NOT** enroll to join the full Developer Program or you will be locked into a *Pending* payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.
* Connections:
* iPhone / iPad: `Lightning` โ `USB-A / USB-C` cableยน
* Apple TV 4: `USB-C` โ `USB-A / USB-C` cableยน
* Apple TV 4K: `WiFi`ยฒ ([Instructions](http://www.redmondpie.com/how-to-wirelessly-connect-apple-tv-4k-to-xcode-on-mac/))ยณ
ยน Depends on which [ports](https://support.apple.com/en-us/HT201736) you have. *WiFi can be setup after.* ยฒ USB ports have been discontinued on Apple TV 4K+. ยณ If using a virtual machine, you may need to [configure your network settings](/advanced/virtualizing-macos#cannot-detect-apple-tv-4k-over-wifi).
{% endhint %}
{% hint style="danger" %}
Sideloading from 3rd party sources ***is not supported***.
{% endhint %}
๐ข If you get stuck, check out [Troubleshooting](#troubleshooting).
{% tabs %}
{% tab title="โ๏ธ AltStore" %}
AltStore source is available at [this link](altstore://source?url=https://provenance-emu.com/apps.json) โ click in Mobile Safari once you have AltStore installed.
1. Download and launch [AltStore](https://altstore.io).
2. Connect your device (you may need to open **Finder** and choose `Trustโฆ` when it pops up).
3. Follow instructions via altstore.io and the app as it guides you.
4. Put the Provenance .ipa in your iCloud Drive somewhere and install via AltStore app by using the `+` button in the upper left of the My Apps screen.
{% hint style="info" %}
Free Apple developer provisioning expires *every 7 days*, but AltStore can keep track of and handle renewal for you. Re-sideloading will not cause you to lose any data.
{% endhint %}
{% hint style="warning" %}
Windows AltStore has not been tested by the Provenance team. Support may be limited.
{% endhint %}
{% endtab %}
{% tab title="๐ iOS App Signer" %}
1. Download and launch [iOS App Signer](https://dantheman827.github.io/ios-app-signer/).
2. Select `.ipa` file and resign it to yourself, selecting the Provenance Bundle ID you've used in the past. If you don't have one, create one: ๐ Bundle ID: `com.[change-this].provenance` โ replace `[change-this]` with something unique like your username.
3. Connect your device. โ ๏ธ If you haven't yet, register your device to your Apple ID in Xcode. Easiest way is to make a dummy app in Xcode and have it automatically create the provisioning ([Example](https://dantheman827.github.io/ios-app-signer/#tab-bar)).
4. Install:
* [Xcode](https://apps.apple.com/us/app/xcode/id497799835): Window โ Devices and Simulators โ Select your device โ Drop the `.ipa` onto Installed Apps.
* [Configurator](https://support.apple.com/apple-configurator): Double-click your device โ Apps โ Drop the `.ipa` here.
5. On device: Go to `Settings` โ `General` โ `Profiles & Device Management`, tap on your certificate and then `Trust`.
6. *Done.* (If using a free developer account, repeat from step 4 after it **expires in 7 days**)
{% hint style="info" %}
Free Apple developer provisioning expires *every 7 days*, requiring reloading, but you will not lose any data.
{% endhint %}
{% endtab %}
{% tab title="๐งช AltDeploy" %}
1. Download and launch [AltDeploy](https://github.com/pixelomer/AltDeploy/releases).
2. Connect your device (you may need to open **Finder** and choose `Trustโฆ` when it pops up).
3. Select your device in AltDeploy.
4. Drag & drop `.ipa` file onto Impactor.
5. Enter your Apple ID.
6. If *not* using 2-Factor Authentication, enter your account password, otherwise:
1. Login to your [Apple ID](https://appleid.apple.com/) online and `Generate` an App-Specific Password under Security section.
2. Enter your App-Specific Password in AltDeploy, verbatim.
7. Install:
* [Xcode](https://apps.apple.com/us/app/xcode/id497799835): Window โ Devices and Simulators โ Select your device โ Drop the `.ipa` onto Installed Apps.
* [Configurator](https://support.apple.com/apple-configurator): Double-click your device โ Apps โ Drop the `.ipa` here.
8. On device: Go to `Settings` โ `General` โ `Profiles & Device Management`, tap on your certificate and then `Trust`.
9. *Done.* (If using a free developer account, repeat from step 4 after it **expires in 7 days**)
{% hint style="info" %}
Free Apple developer provisioning expires *every 7 days*, requiring reloading, but you will not lose any data.
{% endhint %}
{% endtab %}
{% endtabs %}
## ๐ข Troubleshooting
Cannot authenticate
If using 2-Factor Authentication, you will need to go to [Apple ID](https://appleid.apple.com/) settings and generate an App-Specific Password. Enter it verbatim in your sideloading tool.
Unable to code-sign / install
* If you are using a free Apple developer account, you can only install a total of 3 apps per Apple ID at a time. Delete some apps you are signing, or install with a different Apple ID and Bundle IDs.
* If you used to have a free Safari Developer Account (no longer supported by Apple):
1. Upgrade to a *paid* [Apple Developer](https://developer.apple.com/programs/) account, or
2. Use a different Apple ID that *is not* an expired and deprecated Safari Developer account.
โapplication-identifier entitlement does not matchโฆ
This means you need to match the Bundle IDs with the ones from your previous sideload or build on your device. If you don't know it, or used a 3rd party web-sign (unsupported), we recommend you [backup your files](/advanced/restoring-files), delete the app and try to clean-install.
Your maximum App ID limit has been reachedโฆ
You have made too many Bundle IDs (App IDs) in one week on a free Apple developer account. Stop making new Bundle IDs and revert to one you already made. If all else fails, use a different Apple ID, and make only one new, unique Bundle ID with it (and save it for later when you need to re-sign in 7 days).
Duplicate app
If app installs or updates as a duplicate instead of updating existing installation, you need to delete it and use the *same* Bundle ID as your original build or you'll end up with a double installation.
App installs but crashes immediately on launch
This is the most common issue with Sideloadly, LiveContainer, ATVLoadly, and Raspberry Pi-based signing tools. The app appears to install fine but quits to the home screen within 1โ2 seconds of opening.
**Most likely cause: entitlement stripping**
When third-party tools re-sign the IPA, they sometimes strip or fail to re-inject entitlements that Provenance requires (Metal GPU access, game controller support, background audio, JIT, etc.). iOS and tvOS silently kill the app the moment it tries to use a capability it's not entitled to.
**What to try, in order:**
1. **Check the crash log first** โ see the [Reading Crash Logs](#reading-crash-logs) section below. The crash reason tells you exactly what failed.
2. **Try a different signing tool** โ if ATVLoadly or Sideloadly crashed it, try AltStore instead (or vice versa). Different tools handle entitlement injection differently.
3. **Use a paid Apple Developer account ($99/year)** โ free accounts have restrictions on which entitlements can be granted. Some capabilities (like certain background modes) are blocked entirely on free accounts.
4. **Re-download the IPA** โ a partially downloaded or corrupt IPA can produce a valid-looking install that crashes. Delete and re-download from [GitHub Releases](https://github.com/Provenance-Emu/Provenance/releases).
5. **Delete the app fully and reinstall** โ stale data from a previous install with a different bundle ID can cause conflicts.
**Tool-specific notes:**
| Tool | Common cause | Workaround |
| ---------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Sideloadly** | May strip some entitlements by default | Enable "Advanced Options โ Remove Support Files" = OFF; try "Normal" signing mode |
| **LiveContainer** | No JIT support; Metal access restricted in container sandbox | LiveContainer is not officially supported โ use AltStore instead |
| **ATVLoadly / Raspberry Pi** | Community tool; entitlement handling is inconsistent | Update to latest ATVLoadly; check the [ATVLoadly GitHub](https://github.com/ipa-meister/atvloadly) for known issues |
| **AltStore (free)** | Free account entitlement limits | Works best; use the official [Provenance AltStore source](altstore://source?url=https://provenance-emu.com/apps.json) |
{% hint style="warning" %}
**LiveContainer** runs apps in a sandboxed container without installing them. Provenance uses Metal for rendering and requires real GPU access. LiveContainer's sandboxing actively interferes with this and is **not supported**. Install Provenance normally via AltStore instead.
{% endhint %}
***
## ๐ Reading Crash Logs
When Provenance crashes on launch, the device records exactly why. Finding that log tells you (and us) precisely what went wrong โ this is far more useful than "it just crashes."
### macOS โ Console.app (easiest)
1. Connect your iPhone/iPad or Apple TV via USB (or WiFi for Apple TV 4K)
2. Open **Console.app** (in `/Applications/Utilities/`)
3. Select your device in the left sidebar under **Devices**
4. In the search bar, type `Provenance` and press Enter
5. Launch Provenance on the device โ watch the log fill in real time
6. Look for lines marked `fault` or `error`, especially around process termination
To save the log: **File โ Export** or select all and copy.
{% hint style="info" %}
For crash reports specifically: in Console.app, go to **Crash Reports** in the left sidebar, find `Provenance` entries, and open them. They contain the full stack trace.
{% endhint %}
### macOS โ Xcode
1. Connect your device
2. Open Xcode โ **Window โ Devices and Simulators**
3. Select your device โ click **View Device Logs**
4. Filter by `Provenance` in the search box
5. The most recent crash will be at the top
You can also stream live logs: in Terminal, run:
```bash
xcrun devicectl device syslog stream --device-name "My iPhone" 2>&1 | grep -i provenance
```
(Replace `My iPhone` with your device name as shown in Finder.)
### Windows โ Apple Devices App + libimobiledevice
There is no Windows equivalent of Console.app, but you can get logs via:
**Option A โ iMazing** (paid, easiest on Windows)
* Install [iMazing](https://imazing.com/) and connect your device
* Go to **Manage Apps โ Provenance โ Logs**
**Option B โ libimobiledevice** (free, command line)
1. Install [libimobiledevice for Windows](https://github.com/libimobiledevice-win32/imobiledevice-net/releases) or use the binaries at [libimobiledevice.org](https://libimobiledevice.org/)
2. Connect device, trust the computer when prompted
3. Run in Command Prompt:
```
idevicesyslog.exe | findstr Provenance
```
4. Launch Provenance and watch the output
**Option C โ 3uTools** (free GUI)
* Install [3uTools](http://www.3u.com/), connect device
* Go to **Toolbox โ Real-time Log** and filter by `Provenance`
### Linux โ libimobiledevice
```bash
# Install
sudo apt install libimobiledevice-utils # Debian/Ubuntu
sudo pacman -S libimobiledevice # Arch
# Stream logs
idevicesyslog | grep -i provenance
```
Connect your device via USB and trust the computer first (`idevicepair pair`).
### On-Device โ Settings Analytics (no computer needed)
iOS saves crash reports locally:
1. **Settings โ Privacy & Security โ Analytics & Improvements**
2. Tap **Analytics Data**
3. Look for files starting with `Provenance-` โ sort by date, the most recent crash is at the top
4. Tap to open โ scroll to the `Exception Type` and `Termination Reason` lines near the top
The key fields to share when asking for help:
* `Exception Type` (e.g., `EXC_CRASH`, `EXC_BAD_ACCESS`)
* `Termination Reason` (e.g., `Namespace CODESIGNING, Code 0x1` = entitlement issue)
* `Application Specific Information`
### Apple TV โ Reading Logs ๐๐บ
Apple TV has no touchscreen and no USB port on the 4K models, so this is trickier.
**Method 1: Mac Console.app over WiFi (recommended)**
1. On Apple TV: **Settings โ Remotes and Devices โ Remote App and Devices** โ make sure your Mac appears
2. On Mac: Open **Xcode โ Window โ Devices and Simulators**, wait for your Apple TV to appear (may take a moment on WiFi)
3. Once it appears in Xcode, it will also show up in **Console.app** under Devices
4. In Console.app, select the Apple TV and filter by `Provenance`
5. Launch Provenance on the Apple TV โ the crash reason appears in real time
**Method 2: Xcode Device Logs over WiFi**
1. Xcode โ **Window โ Devices and Simulators** โ select Apple TV
2. Click **View Device Logs**
3. Recent crashes appear here within a few seconds of happening
**Method 3: Apple TV 4 (USB-C only) โ direct cable**
The original Apple TV 4 has a USB-C port. Connect it to your Mac and it shows up in Console.app and Xcode the same as an iPhone.
**Method 4: Pair via ideviceinstaller (ATVLoadly users)**
If you set up ATVLoadly, your Raspberry Pi is already paired. You can stream logs from the Pi:
```bash
idevicesyslog | grep -i provenance
```
{% hint style="warning" %}
Apple TV 4K (2nd gen+) has no physical port. You **must** use WiFi pairing via Xcode or Console.app. If Xcode hasn't paired with your Apple TV before, go to **Xcode โ Preferences โ Accounts** and add your Apple ID first.
{% endhint %}
***
## ๐ External Resources
If you're still stuck, these guides cover sideloading in depth:
**Sideloading tools:**
* [AltStore Setup Guide (altstore.io)](https://altstore.io) โ official, regularly updated
* [Sideloadly Guide (iosgods.com)](https://iosgods.com/topic/130167-how-to-use-sideloadly-to-sideload-ipa-files/) โ step-by-step with screenshots
* [ATVLoadly GitHub](https://github.com/ipa-meister/atvloadly) โ includes Raspberry Pi setup and known issues
**Crash log reading:**
* [How to Get Crash Logs from iPhone โ iGeeksBlog](https://www.igeeksblog.com/how-to-get-crash-logs-from-iphone/) โ Console.app walkthrough with screenshots
* [libimobiledevice project](https://libimobiledevice.org/) โ cross-platform device tools (Windows/Linux log streaming)
**Community help:**
* [Provenance Discord](https://discord.gg/provenance) โ `#sideloading-help` channel; include your crash log excerpt
{% hint style="info" %}
๐ฏ If you are still stuck ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# Building from Source
Build Provenance from source with Xcode โ get the latest in-development features on iOS, tvOS, and macOS
To get the very latest in-development build, you will need to build from source with Xcode. There are no shortcuts. Provenance is a large project with required dependencies and submodules that help enable efficient development. Check that you meet the requirements. Follow each and every step. Make no assumptions. **Do not** skip *anything.*
1. [**Get Source**](#get-source)
2. [**Setup**](#setup) (install requirements and dependencies)
3. [**Build Source**](#build-source) to device (Xcode)
4. *(Optional)* [**Enable Advanced Features**](#advanced-features)
{% hint style="warning" %}
The beta is in active-development.
{% endhint %}
{% hint style="danger" %}
DO NOT expect to use a beta without issues, losing your saves, or bugs.
{% endhint %}
{% hint style="success" %}
**Requirements**
* macOS 13.5+ (Ventura) minimum; macOS 14.0+ (Sonoma) recommended
* on a Mac, Hackintosh or virtual machine ([Virtualizing macOS](https://wiki.provenance-emu.com/info/miscellaneous/virtualizing-macos))
* [Xcode](https://apps.apple.com/us/app/xcode/id497799835) 15.0+
* iOS 16+ / tvOS 16+ SDKs
* *Free* [Apple Developer](https://9to5mac.com/2016/03/27/how-to-create-free-apple-developer-account-sideload-apps/) account (at a minimum) or a *paid* account.
๐ **DO NOT** enroll to join the full Developer Program or you will be locked into a *Pending* payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.
* Connections:
* iPhone / iPad: `Lightning` โ `USB-A / USB-C` cableยน
* Apple TV 4: `USB-C` โ `USB-A / USB-C` cableยน
* Apple TV 4K: `WiFi`ยฒ ([Instructions](http://www.redmondpie.com/how-to-wirelessly-connect-apple-tv-4k-to-xcode-on-mac/))ยณ
ยน Depends on which [ports](https://support.apple.com/en-us/HT201736) you have. *WiFi can be setup after.* ยฒ USB ports have been discontinued on Apple TV 4K+. ยณ If using a virtual machine, you may need to [configure your network settings](/advanced/virtualizing-macos#cannot-detect-apple-tv-4k-over-wifi).
{% endhint %}
๐ข If you get stuck, check out [Troubleshooting](#troubleshooting).
## Get Source
**Source Options**
* ๐ [**Clone**](#clone) usingโฆ
*  [Terminal](#terminal)
*  [Tower](#tower)
### Clone
Cloning is how you pull the source code from GitHub. Choose your preferred method:
{% tabs %}
{% tab title="Terminal" %}
{% hint style="info" %}
The Terminal app can be found in: */Applications/Utilities*
{% endhint %}
1. Make sure you have the latest version of the Xcode command-line tools installed: `xcode-select --install`
2. *(Optional)* Choose an install directory with `cd [path]` (drag & drop a folder on Terminal after `cd` to get directory path).
3. Download source with HTTPS:
```
git clone --recurse-submodules -j4 https://github.com/Provenance-Emu/Provenance.git
```
4. Continue to [Setup](#setup)โฆ
{% endtab %}
{% tab title="Tower (Git Client)" %}
Tower is a powerful commercial git client that can automate a lot of the tasks you'd otherwise be using commandline for, such as stashing changes. It is however, *not free.*
1. Purchase/Download [Tower](https://www.git-tower.com/mac/)
2. Launch Tower and Add Your Service Account: `GitHub`
3. *(Optional)* In Menubar: Select `Tower` โ `Preferences` (or use `โ,` shortcut):
* Set a 'default directory for clone repositories' such as `~Documents/GitHub`
4. In Menubar: Select `File` โ `Clone Git Repository` (or use `โโC` shortcut):
* Remote URL: `https://github.com/Provenance-Emu/Provenance.git`
* โ๏ธ Initialize Submodules
5. Continue to [Setup](#setup)โฆ
{% endtab %}
{% endtabs %}
~~**Download**~~
๐ซ Due to the inclusion of submodules this method no longer works. **Do not** manually download source as `.zip`โฆ
{% hint style="danger" %}
If building from active develop branch, we *will not* be held responsible for any loss of your game data! Install ***at your own risk!*** โฆand back up your files.
{% endhint %}
## Build Source
1. Open the Provenance Xcode workspace:  `Provenance.xcworkspace`
โ ๏ธ **Do not** use the .xcodeproj file or you will have build errors!
2. Go to Preferences via Menubar: `Xcode` โ `Preferences` or use `โ,` shortcut.
* Select Accounts tab.
* Click `+`
* Sign in with your personal or developer Apple ID. If you don't have one, click `Create Apple ID` or go to [appleid.apple.com](https://appleid.apple.com/).
{% hint style="warning" %}
At minimum, sign up as a free [Apple Developer](https://9to5mac.com/2016/03/27/how-to-create-free-apple-developer-account-sideload-apps/) and do no more than agree to the terms.
๐ DO NOT enroll to join the full Developer Program or you will be locked into a *Pending* payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.
{% endhint %}
Copy `CodeSigning.xcconfig.sample` to `CodeSigning.xcconfig` and modify the file replacing `DEVELOPMENT_TEAM` with your Team ID and `ORG_IDENTIFIER` with a bundle identifier that is registered to you.
If you have a paid Apple Developer account, you can find your Team ID at
If you have a free Apple Developer account, you need to generate a new signing certificate. To do so, follow the steps in \[iOS App Signer]\[3] to create a new Xcode project and generate a provisioning profile. After saving the project, open `project.pbxproj` inside your newly created `.xcproj` and look for `DEVELOPMENT_TEAM`. Copy this value to `CodeSigning.xcconfig` and your unique identifier to `ORG_IDENTIFIER`.
Set `DEVELOPER_ACCOUNT_PAID = YES` if you used a paid Apple Developer account in order to automatically request the increased memory limit entitlement from Apple.
After updating `CodeSigning.xcconfig`, re-open the project (remember to use `Provenance.xcworkspace` when opening the project).
{% hint style="info" %}
You can install a duplicate app for testing by using a different bundle ID than your previous/main install.
{% endhint %}
* If using a free Apple Developer account, **Turn OFF** these Capabilities for *all* targets:
*  App Groups
*  iCloud
*  Multipath
*  Push Notifications
*  Siri
* Select a `-Release` profile from the Scheme Menu and connect your device(s) and select in the Destination Menu:
* If you areโฆ
* Paid Apple Developer: Continue to [Enable Advanced Featuresโฆ](#advanced-features)
* Free Apple Developer: Hit the `โถ๏ธ` (Run) button.
* Provenance will compile and run on your device. Unless testing, hit `โผ๏ธ` (Stop). *Done.*
{% hint style="success" %}
**Build successful!** Provenance is now installed on your device. Free Apple developer provisioning expires every 7 days, but your data is preserved when re-signing.
{% endhint %}
๐ข If you get stuck, check out [Troubleshooting](#troubleshooting).
{% hint style="info" %}
Free Apple developer provisioning expires *every 7 days*, requiring reloading, but you will not lose any data.
*Paid* Apple Developer provisioning may only require re-signing once a year.
{% endhint %}
## Advanced Features
{% hint style="warning" %}
**Requires** a *paid* [Apple Developer](https://developer.apple.com/programs/) account.
{% endhint %}
1. If you haven't made one previously, add a new App Group ID: `group.[change-this].provenance` to your [Apple Developer](https://developer.apple.com/programs/) portal, or continue to next step and see if it allows you to add an App Group ID automatically when using `+` in App Groups.
2. \[Re-]enable Capabilities on your target(s), with the following settings:
* **iOS:**
* Provenance:
*  App Groups
* ๐ฒ `group.provenance-emu.provenance`
* โ๏ธ `group.[change-this].provenance`
*  iCloud
*  Multipath
*  Push Notifications
*  Siri
* Spotlight:
*  App Groups
*  iCloud
* ๐Specify custom containers:
* ๐ฒ \`iCloud.com.provenance-emu.provenance\`
โ๏ธ \`iCloud.com.\[change-this].provenance\`
* **tvOS:**
* ProvenanceTV:
*  App Groups
* ๐ฒ `group.provenance-emu.provenance`
* โ๏ธ `group.[change-this].provenance`
*  iCloud
*  Push Notifications
* TopShelf:
*  App Groups
* ๐ฒ `group.provenance-emu.provenance`
* โ๏ธ `group.[change-this].provenance`
3. Define the value for `PVAppGroupId` in `PVAppConstants.swift` with your App Group ID.
4. Hit the `โถ๏ธ` (Run) button to build to your device.
5. Provenance will compile and run on your device. Unless testing, hit `โผ๏ธ` (Stop). Done
{% hint style="warning" %}
If all else fails, delete Provenance folder and start over.
{% endhint %}
## Troubleshooting
If you are having trouble building or sideloading the app, check for your issue here or below in Known Issues.
xcrun: error: unable to find utility "xcodebuild"
Go to Xcode Preferences โ Locations, and make sure to select an Xcode version for Command Line Tools.
Unable to code-sign / install
* Change the Bundle IDs of the app targets and extensions, as described in Build Source steps.
* If you are using a free Apple developer account, you can only install a total of 3 apps per Apple ID at a time. You must delete some apps you are signing, or install with different Apple ID and Bundle IDs.
* If you used to have a free Safari Developer Account which is no longer supported by Apple:
1. Upgrade to a *paid* [Apple Developer](https://developer.apple.com/programs/) account, or
2. Use a different Apple ID that *is not* an expired and deprecated Safari Developer account.
Can't install after changing fork / pulling
1. Check the Bundle IDs haven't been reset to the project defaults.
2. If not, select your team dropdown and reselect your team/name. Sometimes Xcode gets out of sync with the identity being used after a merge/pull/branch change, especially in the extension targets.
Cycle in dependencies between targetsโฆ error
Circular dependency error. Clean Build Folder (โงโK) and/or nuke Xcode's derived data: `rm -rf ~/Library/Developer/Xcode/DerivedData` and restart Xcode.
Stuttering sound or lag
This probably means you built the *debug version* by mistake (app will be named `Prov Debug` on Home Screen and Settings will show `DEBUG`). Re-build using `Provenance-Release` (iOS) or `ProvenanceTV-Release` (tvOS) option in Xcode.
โapplication-identifier entitlement does not matchโฆ
This means you need to match the Bundle IDs with the ones from your previous sideload or build on your device. If you don't know it, or used a 3rd party web-sign (unsupported), we recommend you [backup your files](/advanced/restoring-files), delete the app and try to clean-install.
Your maximum App ID limit has been reachedโฆ
You have made too many Bundle IDs (App IDs) in one week on a free Apple developer account. Stop making new Bundle IDs and revert to one you already made. If all else fails, use a different Apple ID, and make only one new, unique Bundle ID with it (and save it for later when you need to re-sign in 7 days).
Mupen build error / missing submodules
You are missing submodules. **Do not** download .zip from GitHub. Use Terminal. Go back to [Get Source](#get-source) and **do not** skip any steps.
Unsupported arch
You are probably trying to build for a 32-bit device. Provenance only supports 64-bit devices. As a **workaround**: Remove the mupen64plus framework from the app's `Embed` and `Link` stages and from the `Build โ Targets` list in the `Edit Schemeโฆ` settings.
Duplicate app
If app installs or updates as a duplicate app instead of updating existing installation, you need to delete it and use the *same* Bundle ID as your original build or you'll end up with a double installation.
Linkingโฆ Failed
Fails when switching from one target to another. In Xcode: Run `Clean` and/or `Clean Build Folder` and rebuild.
git@github.com: Permission denied (publickey)
Setup an [SSH Key on your GitHub account](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/), or add the following to your git config via `nano ~/.gitconfig`:
```bash
[url "https://github.com"]
insteadOf = ssh://git@github.com
```
conflicting provisioning settingsโฆDistribution
In Build Settings for the targets with errors, manually reset all the Code Signing Identities that are `iOS Distribution` to be `iOS Developer`, and try building again.
## โ ๏ธ Known Issues
**Database model incompatibility error**
* This means there have been changes to the database model which is no longer compatible with your previous build. In order to update you ***must*** clean install (delete app and re-install, not build or install over over existing app). If you would like to migrate your save games and states, you can refer to [Restoring Files](https://github.com/Provenance-Emu/Provenance/wiki/Restoring-Files).
๐ You can install a duplicate app for testing by using a different bundle ID than your previous/main install.
{% hint style="info" %}
๐ฏ If you are still stuck try [debugging](/help-and-community/troubleshooting) on your own or ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# Updating Provenance
How to update your Provenance installation
How you update depends on how you installed Provenance:
{% tabs %}
{% tab title="App Store (Automatic)" %}
**App Store updates are automatic** โ no action needed.
To verify you're on the latest version:
1. Open the **App Store**
2. Tap your profile icon (top right)
3. Scroll to Provenance โ tap **Update** if available
**Tip:** Make sure **Automatic Downloads** is enabled in Settings โ App Store so updates install in the background.
{% endtab %}
{% tab title="Sideloaded (.ipa)" %}
To update a sideloaded installation:
1. Download the latest `.ipa` from [GitHub Releases](https://github.com/Provenance-Emu/Provenance/releases)
2. Re-sign and install using your sideloading tool ([AltStore](/getting-started/installing-provenance/advanced/sideloading), Sideloadly, iOS App Signer)
3. Install **over** your existing version โ use the **same Bundle ID** to preserve data
{% hint style="info" %}
Installing over an existing sideloaded version preserves your ROMs, saves, and settings. Using a different Bundle ID creates a separate installation.
{% endhint %}
Full guide: [Sideloading](/getting-started/installing-provenance/advanced/sideloading)
{% endtab %}
{% tab title="Built from Source (Terminal)" %}
If you built from source, pull the latest changes and rebuild:
1. Navigate to your Provenance directory:
```bash
cd /path/to/Provenance
```
2. Pull the latest source:
**Option A โ Overwrite local changes** (easiest, reapply Bundle ID after):
```bash
git pull origin develop
```
**Option B โ Preserve local changes** (keeps your Bundle ID and code modifications):
```bash
git stash
git reset --hard HEAD
git pull origin develop
git stash pop
```
3. Update submodules and open in Xcode:
```bash
make update
make open
```
4. In Xcode:
* If you used Option A, reapply your Bundle ID and signing settings
* If you used Option B, just press **Run** (your settings are preserved)
5. Provenance compiles and installs on your device
{% endtab %}
{% tab title="Built from Source (Tower)" %}
If you use [Tower](https://www.git-tower.com/) as your Git client:
1. Open Provenance in Tower (Repositories โ double-click **Provenance**)
2. With the `develop` branch selected (HEAD), click **Fetch**
3. If the branch shows pending changes, click **Pull**
4. Click **Stash Changes** if you have local modifications
5. After pulling, click **Apply Stash** to restore your changes
6. In Terminal:
```bash
cd /path/to/Provenance
make update
make open
```
7. In Xcode, press **Run** to build and install
{% endtab %}
{% endtabs %}
***
## Command-Line Build Shortcuts
If you've already completed the [first-time setup](/getting-started/installing-provenance/advanced/building-from-source), you can update and build entirely from Terminal:
```bash
# iPhone / iPad
make ios
# Apple TV
make tvos
```
These commands pull the latest source, update submodules, and build in one step.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# BIOS Requirements
Certain emulator cores require specific BIOS files in order to play.
โ
[**Systems**](#systems) requiring/utilizing BIOS โน๏ธ [**Specifications**](#specifications) per System ๐ [**Importing**](#importing) BIOS files
{% hint style="warning" %}
**DO NOT** ask us where to obtain BIOS files. Distributing BIOS files violates copyright law.
{% endhint %}
{% hint style="info" %}
**Interactive Reference:** [eduo.info/pvl](https://eduo.info/pvl/) โ Community-built searchable database of all Provenance systems, cores, BIOS requirements, and supported file extensions (parsed directly from Provenance's source code).
{% endhint %}
## Systems
**BIOS**: โ
= Required ๐ถ = Optional
| Manufacturer | System | BIOS |
| ------------ | --------------------------------------------------- | ---- |
| Atari | 2600 | |
| | 5200 | โ
|
| | 7800 | |
| | Lynx | โ
|
| | Jaguar | |
| | ST | โ
|
| Bandai | WonderSwan | |
| | WonderSwan Color | |
| CBS | ColecoVision | โ
|
| NEC | PC Engine / TurboGrafx-16 | |
| | PC Engine Super CD-ROMยฒ System / TurboGrafx-CD | โ
|
| | PC Engine SuperGrafx | |
| | PC-FX | โ
|
| Nintendo | Famicom / Nintendo Entertainment System | |
| | Famicom Disk System | โ
|
| | Game Boy | |
| | Super Famicom / Super Nintendo Entertainment System | |
| | Game Boy Color | |
| | Virtual Boy | |
| | Nintendo 64 | |
| | Game Boy Advance | ๐ถ |
| | Pokemon mini | |
| Palm | PalmOS | โ
|
| Philips | CD-i | โ
|
| Sega | SG-1000 | |
| | Master System | |
| | Mega Drive / Genesis | |
| | Game Gear | |
| | Mega-CD / CD | โ
ร3 |
| | 32X | |
| | Saturn | โ
ร3 |
| SNK | Neo Geo Pocket | |
| | Neo Geo Pocket Color | |
| Sony | PlayStation | โ
ร3 |
## Specifications
{% hint style="info" %}
Filenames are arbitrary as long as the MD5s match. Provenance will rename files on import.
{% endhint %}
### Atari 5200
| Filename | MD5 Hash |
| ---------- | -------------------------------- |
| `5200.rom` | 281f20ea4320404ec820fb7ec0693b38 |
### Atari Lynx
| Filename | MD5 Hash |
| -------------- | -------------------------------- |
| `lynxboot.img` | fcd403db69f54290b51035d82f835e7b |
### CBS ColecoVision
| Filename | MD5 Hash |
| ------------------ | -------------------------------- |
| `colecovision.rom` | 2c66f5911e5b42b8ebe113403548eee7 |
### Nintendo Famicom Disk System
| Filename | MD5 Hash |
| ------------- | -------------------------------- |
| `disksys.rom` | ca30b50f880eb660a320674ed365ef7a |
### Nintendo Game Boy Advance
| Filename | MD5 Hash |
| ---------- | -------------------------------- |
| `gba.bios` | a860e8c0b6d573d191e4ec7db1b1e4f6 |
{% hint style="info" %}
Game Boy Advance BIOS is optional.
{% endhint %}
### NEC PC Engine Super CD-ROMยฒ System / TurboGrafx-CD
| Filename | MD5 Hash |
| -------------- | -------------------------------- |
| `syscard3.pce` | ff1a674273fe3540ccef576376407d1d |
### NEC PC-FX
| Filename | MD5 Hash |
| ---------- | -------------------------------- |
| `pcfx.rom` | 08e36edbea28a017f79f8d4f7ff9b6d7 |
### Palm PalmOS
| Filename | BIOS Name / Version | MD5 Hash |
| ---------------------- | ------------------- | -------- |
| `palmos41-en-m515.rom` | Palm OS 4.1 | |
| `palmos40-en-m500.rom` | Palm OS 4.0 | |
| `palmos52-en-t3.rom` | Palm OS 5.2 | |
| `palmos60-en-t3.rom` | Palm OS 6.0 | |
| `bootloader-dbvz.rom` | UART Bootloader | |
{% hint style="info" %}
Only `palmos41-en-m515.rom` is required
{% endhint %}
### Philips CD-i
| Filename | MD5 Hash | Notes | Required |
|---|
| cdimono1.zip | c59f92647701428bc453976740eb75cf | Must manually put in RetroArch/system/same_cdi/bios/ | true |
| cdimono2.zip | | | false |
| cdibios.zip | | | false |
{% hint style="warning" %}
Must manually put in \`RetroArch/system/same\_cdi/bios/\`
{% endhint %}
### Sega Mega-CD / CD
| Filename | BIOS Name / Version | Region | MD5 Hash |
| --------------- | -------------------------------------- | ------ | -------------------------------- |
| `bios_CD_U.bin` | Sega CD Model 1 (US 921011) BIOS 1.10 | US | 2efd74e3232ff260e371b99f84024f7f |
| `bios_CD_E.bin` | Mega-CD Model 1 (EU 921027) BIOS 1.00 | EU | e66fa1dc5820d254611fdcdba0662372 |
| `bios_CD_J.bin` | Mega-CD Model 1 (JP 911217) BIOS 1.00p | JP | bdeb4c47da613946d422d97d98b21cda |
{% hint style="success" %}
All 3 BIOS are required.
{% endhint %}
### Sega Saturn
| Filename | BIOS Name / Version | Region | MD5 Hash |
| ----------------- | ----------------------- | ------ | -------------------------------- |
| `saturn_bios.bin` | Sega Saturn BIOS v1.00 | JP/US | af5828fdff51384f99b3c4926be27762 |
| `mpr-17933.bin` | Sega Saturn BIOS v1.01a | EU | 3240872c70984b6cbfda1586cab68dbe |
| `sega_101.bin` | Sega Saturn BIOS v1.01 | JP | 85ec9ca47d8f6807718151cbcca8b964 |
{% hint style="success" %}
All 3 BIOS are required. Filenames online may vary. If the MD5s match, Provenance will correctly rename for you on import.
{% endhint %}
### Sony PlayStation
| Filename | BIOS Name / Version | Region | MD5 Hash |
| -------------- | ------------------- | ------ | ---------------------------------- |
| `scph5500.bin` | SCPH-5500 / v3.0J | JP | `8dd7d5296a650fac7319bce665a6a53c` |
| `scph5501.bin` | SCPH-5501 / v3.0A | USA | `490f666e1afb15b7362b406ed1cea246` |
| `scph5502.bin` | SCPH-5502 / v3.0E | EU | `32736f17079d0b2b7024407c39bd3050` |
{% hint style="success" %}
All 3 BIOS are required.
{% endhint %}
## Importing
BIOS files are imported exactly the same as ROMs: [Importing ROMs](/using-provenance/importing-roms). When you have the correct BIOS successfully imported they will shown in Settings โ Cores or they show as missing/red/required, otherwise you have the wrong files. You need the exact ROMs files matching the MD5 hashes above.
### MD5
Though not required, you can verify the MD5 hashes of your files to be certain. To obtain the MD5 hash of your BIOS files, you can use `md5 [path to file, or drag and drop file here]` in Terminal. Check that it matches the MD5 hash of the file listed above.
Alternatively, BIOS files can be force [uploaded](/using-provenance/importing-roms#uploading) manually into `/BIOS/com.provenance.[system]` via WebUI or WebDav (iOS, tvOS) or the Apple Files app (iOS only).
{% hint style="info" %}
๐ฏ If you are still stuck ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# Importing ROMs
How to import ROMs into Provenance.
Provenance supports multiple ways to import ROMs and BIOSes, including *single-drop* mass-uploading:
* โฌ๏ธ [**Uploading**](#uploading)ยน (via built-in Web Server) ยท for iOS & tvOS
* Web Server UI
* WebDav Clients
* โฌ๏ธ [**Downloading**](#downloading) (from Mobile Browsers) ยท for iOS *only*
* โก๏ธ [**Copying**](#copying) ยท for iOS *only*
* Mobile Apps
* AirDrop ยท macOS โ iOSยน *or* iOS โ iOS
* โคต๏ธ [**Injecting**](#injecting) (with Desktop Apps) ยท for iOS and ATV4 *only*
* ~~iTunes~~ (discontinued; use Finder on macOS or third-party tools)
* Other Tools
ยน Mass-uploading ROM libraries or uploading multiple ROMs simultaneously is supported.ยฒ\
ยฒ Avoid mass-uploading multi-disc ROMs.
{% hint style="success" %}
**Requirements**
* ๐ *All* ROMs ***must*** be [formatted correctly](/using-provenance/roms/formatting-roms) before importing. ([Formatting ROMs](/using-provenance/roms/formatting-roms))
* โ๏ธ Certain systems ***require*** [BIOS](/getting-started/bios-requirements) files in order to play ROMs. ([BIOS Requirements](/getting-started/bios-requirements))
{% endhint %}
{% hint style="warning" %}
Please refer to the [Known Issues](#known-issues) regarding Importing ROMs, and read [Issues Usage](https://github.com/Provenance-Emu/Provenance/wiki/Issues-Usage) *before* posting a new one.
{% endhint %}
๐ข If you run into any problems, check out [Troubleshooting](#troubleshooting).
{% tabs %}
{% tab title="โฌ๏ธ Uploading (Web Server)" %}
**For iOS & tvOS** ยท Supports mass-uploading
1. Make sure your device's WiFi is turned on and connected to the *same network as your computer.*
2. In Provenance: Turn on the Web Server:
* Select the `+` button in the Game Library, orโฆ
* In Settings, select the `Import/Export` option.
3. Web Server Active. Make note of the `[device-ip]`:
* Web UI: `http://[device-ip]`
* WebDAV: `http://[device-ip]:81`
**Web Server UI:**
1. On computer, go to `http://[device-ip]` in your browser.
2. Open the `Imports` folder.
3. Upload ROMs โ `Upload Filesโฆ` button supports multiple file selections, and Drag & Drop works too.
**WebDAV Clients:**
1. macOS Finder: `Menu Bar` โ `Go` โ `Connect to Server...`
2. Enter `http://[device-ip]:81` โ `Connect as Guest` โ Provenance mounts as a new drive.
3. Drag & Drop or Copy/Paste ROMs into the `Imports` folder.
โฉ๏ธ [Restoring](/advanced/restoring-files) files (ROMs, BIOS, Saves, Cover Art) is also supported via both methods.
{% endtab %}
{% tab title="โฌ๏ธ Downloading (Browser)" %}
**For iOS only**
1. Open a Mobile Browser (Safari, Chrome, etc).
2. Navigate to your preferred ROM host site, find your ROM and download it.
3. Once downloaded, tap the ROM file and choose:
* `Open in "Provenance"` โ Done. orโฆ
* `Moreโฆ` โ `Copy to Provenance` โ Done.
{% endtab %}
{% tab title="โก๏ธ Copying (Files/AirDrop)" %}
**For iOS only**
**From Mobile Apps:**
1. Open app where ROMs are stored or accessible (Apple Files, [iCloud Drive](https://www.apple.com/icloud/icloud-drive), [Dropbox](https://apps.apple.com/us/app/dropbox/id327630330), [Google Drive](https://apps.apple.com/us/app/google-drive/id507874739), [Nextcloud](https://apps.apple.com/us/app/nextcloud/id1125420102), [FileBrowser](https://apps.apple.com/us/app/filebrowser-computers-cloud/id364738545), etc.)
2. Navigate to your ROM and tap `Share` or `Export`.
3. Tap `Copy to Provenance`. Done.
**Via AirDrop:**
1. Open AirDrop window via macOS Finder.
2. Drag & Drop file(s) onto yourself/your device.
3. Tap `Copy to Provenance`. Done.
๐ค If you don't see yourself in AirDrop, try setting to `Contacts Only` or `Everyone` on both devices. โฌ Mass-copying is supported โ drag & drop multiple files.
{% endtab %}
{% tab title="โคต๏ธ Injecting (Desktop)" %}
**For iOS and Apple TV 4 only**
โ ๏ธ iTunes was discontinued with macOS Catalina (2019). Use **Finder** on macOS Catalina+ (connect device via USB, open Finder, select device, go to the Files tab), or use a third-party tool:
**Third-party tools:**
1. Connect device to computer and open [DiskAid](https://imazing.com/diskaid), [iExplorer](https://macroplant.com/iexplorer), [iPhone Explorer](https://www.macblurayplayer.com/iphone-explorer-mac.htm), or similar app.
2. Locate Provenance App.
3. Navigate to `Documents/Imports`. Create the folder if it doesn't exist.
4. Drag your ROMs into the folder. Done.
โฉ๏ธ [Restoring](/advanced/restoring-files) files (ROMs, saves, cover art) is usually supported in these apps.
{% endtab %}
{% endtabs %}
## Troubleshooting & Known Issues
Multiple ROMs from one archive?
You may be using a Region Pack ROM, meaning more than one version of the same ROM is in your archive. Unarchive the set, isolate single region ROM file(s), [re-archive](/using-provenance/roms/formatting-roms#archiving), and re-import the single region ROM individually.
Loose .bin files detected as wrong system
Sometimes loose `.bin` files for CD-based games are picked up as Sega Genesis/MegaDrive ROMs. Use `.cue + .bin` pairs or `.chd` format instead. See [Multi-file ROMs](/using-provenance/roms/formatting-roms#multi-file-roms) and [Multi-disc Games](/using-provenance/roms/formatting-roms#multi-disc-games).
CD-based / multi-disc ROMs breaking on import
CD-based, multi-file ROMs and especially multi-disc games need to be uploaded and processed *one at a time*. If yours are broken, delete the game(s) from the app UI, delete any file remnants in the file system (ROMs and Imports folders) using the WebUI, WebDAV, or a file manager, and re-upload.
ROM metadata not matching
* Failed checksum ROMs (translations, hacks, etc.) will not be matched automatically.
* Exhaustive metadata web-scraping fallbacks are not currently implemented.
* Uploading ROMs + [Custom Cover Art](/using-provenance/roms/customizing-roms) in one archive may not yield a replacement until Provenance is quit and relaunched.
{% hint style="info" %}
๐ฏ If you are still stuck ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# ROMs
Managing your ROM library in Provenance
Provenance makes it easy to build and manage your game library. This section covers everything from importing your first ROM to managing large collections with advanced tools.
## ๐ฅ Getting ROMs Into Provenance
[**Importing ROMs**](/using-provenance/importing-roms) โ The starting point for adding games. Covers all import methods:
* Wi-Fi Web Server (upload from your computer)
* Downloading directly from Safari on iOS
* AirDrop from Mac to iPhone/iPad
* File manager apps (Apple Files, Dropbox, etc.)
* USB via Finder (Mac) or third-party tools
## ๐ Supported Formats
[**Formatting ROMs**](/using-provenance/roms/formatting-roms) โ Supported file extensions for every system, plus how to:
* Format cartridge and CD-based ROMs correctly
* Package multi-file ROMs (`.cue + .bin`) into archives
* Create `.m3u` playlists for multi-disc games
* Archive ROMs with `.zip` or `.7z` for import
## ๐จ Customizing Your Library
[**Customizing ROMs**](/using-provenance/roms/customizing-roms) โ Personalize game entries with:
* Custom or replacement cover art (paste or upload)
* Rename games
* Edit metadata: title, description, genre, release date
## ๐ง Advanced ROM Management
[**Advanced ROM Management**](/using-provenance/roms/advanced-management) โ Power-user guide for large libraries:
* Organizational strategies for 1,000+ ROMs
* CHD format conversion (40โ70% space savings)
* iCloud sync strategies with Provenance Plus
* Backup and migration between devices
* Database maintenance
## ๐ฟ Ripping & Dumping Physical Media
[**Ripping ROMs**](/using-provenance/roms/ripping-roms) โ Legally dump games from cartridges and discs you own. Covers cartridge readers (GB Operator, Retrode 2, INLretro), disc ripping tools for macOS/Windows/Linux, network/softmod dumping methods, save data backup, and format conversion.
## ๐ฉน Mods & Patches
[**Applying Mods / Patches**](/using-provenance/roms/mods) โ Apply fan translations, ROM hacks, and bug fixes:
* IPS/BPS patching tools (Mac & Windows)
* PSX SBI files for PAL game compatibility
* N64 high-resolution texture packs
***
## Quick Tips
* **All ROMs must be formatted correctly** before importing โ see [Formatting ROMs](/using-provenance/roms/formatting-roms).
* **Some systems require BIOS files** โ see [BIOS Requirements](/getting-started/bios-requirements).
* **Multi-file ROMs** (CD-based games) must be zipped into a single archive before import.
* **Stuck?** See [Troubleshooting](/help-and-community/troubleshooting) or ask on [Discord](https://discord.gg/provenance).
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Ripping ROMs from Physical Media
How to legally dump ROMs, disc images, and save data from your own physical media for use with Provenance.
This guide covers how to create digital backups of game cartridges and discs you **legally own**, for use in Provenance. "Ripping" or "dumping" a ROM means copying the game data from physical media onto your computer or device.
{% hint style="danger" %}
**Legal Notice:** In some regions, creating ROM backups of games you legally own for your own personal use may be permitted, but laws and anti-circumvention rules vary by country and may change over time. Downloading or sharing ROMs for games you do not own, or distributing copyrighted game files, may infringe copyright or other rights. Always research and follow the laws in your jurisdiction before dumping, using, or distributing game files. This guide is for informational purposes and focuses on personal backups only.
{% endhint %}
## Quick Navigation
* [Cartridge Dumping](#cartridge-dumping) โ Game Boy, GBA, NES, SNES, N64, Genesis, and more
* [Disc Ripping](#disc-ripping) โ PlayStation, PS2, PSP, GameCube, Wii, Dreamcast
* [Network / Softmod Ripping](#network--softmod-ripping) โ 3DS, NDS, PS2, SNES/NES Classic
* [Save Data Dumping](#save-data-dumping) โ GB/GBA saves, PS1 memory cards, PS2, N64
* [Format Conversion](#format-conversion) โ CHD, M3U playlists, format table
***
## Cartridge Dumping
Cartridge-based games require dedicated hardware โ a "cart dumper" โ to read the ROM data. Most dumpers connect to your computer via USB and come with software to save the game file.
### Hardware Overview
| Hardware | Systems Supported | Approx. Price | Open Source | URL |
| ---------------------------------- | ---------------------------------------------------- | --------------- | ----------- | ------------------------------------------------------------------ |
| **GB Operator** (Epilogue) | GB, GBC, GBA | \~$50 | No | [epilogue.co](https://epilogue.co) |
| **GBxCart RW** (insideGadgets) | GB, GBC, GBA | \~$35 | Yes | [insidegadgets.com](https://insidegadgets.com) |
| **Joey Jr** (BennVenn) | GB, GBC, GBA | \~$45 | No | [bennvenn.myshopify.com](https://bennvenn.myshopify.com) |
| **Retrode 2** | SNES, Genesis, N64/GB/GBA (adapters) | \~$80 used | Yes | [retrode.org](https://retrode.org) |
| **INLretro Dumper-Programmer** | NES, SNES, N64, Genesis, GB, GBA+ | \~$80 | Yes | [inlretro.com](https://inlretro.com) |
| **Open Source Cart Reader (OSCR)** | 50+ systems (NES, SNES, N64, Genesis, GB, GBA, etc.) | \~$50 DIY | Yes | [github.com/sanni/cartreader](https://github.com/sanni/cartreader) |
| **GodMode9** (3DS CFW) | DS, 3DS | Free (software) | Yes | [github.com/d0k3/GodMode9](https://github.com/d0k3/GodMode9) |
***
### Game Boy / GBC / GBA
Three well-supported options exist for dumping Game Boy family cartridges. All produce standard `.gb`, `.gbc`, or `.gba` ROM files and `.sav` save files compatible with Provenance.
GB Operator (Epilogue) โ Recommended for beginners
The GB Operator is the easiest plug-and-play solution. It connects via USB-C and uses Epilogue's desktop app (macOS/Windows/Linux).
**What you need:**
* GB Operator device
* Epilogue desktop app
* USB-C cable
**Steps:**
1. Download and install the Epilogue app.
2. Insert your Game Boy, GBC, or GBA cartridge into the GB Operator.
3. Connect the GB Operator to your computer via USB-C.
4. Open the Epilogue app โ your cartridge should be detected automatically.
5. Click **Backup ROM** to dump the game ROM to your computer.
6. Optionally click **Backup Save** to dump any existing save data.
The app saves files to a folder of your choice. ROM files use standard extensions (`.gb`, `.gbc`, `.gba`) and save files use `.sav`.
{% hint style="success" %}
`.sav` files dumped from a cartridge are directly compatible with Provenance's save system. Copy them alongside your ROM file when importing.
{% endhint %}
GBxCart RW (insideGadgets) โ Open source option
The GBxCart RW is an open-source, lower-cost alternative. It uses the **FlashGBX** software (community-developed, cross-platform).
**What you need:**
* GBxCart RW device
* FlashGBX app (available at [github.com/lesserkuma/FlashGBX](https://github.com/lesserkuma/FlashGBX))
* USB cable (included with device)
**Steps:**
1. Download FlashGBX from the GitHub releases page.
2. Insert your cartridge into the GBxCart RW and connect to your computer.
3. Open FlashGBX โ the device should be auto-detected.
4. Select **Backup ROM** to dump the game.
5. Select **Backup Save Data** if you want to preserve the cartridge save.
FlashGBX also supports writing ROMs and saves back to cartridges (useful for restoring saves).
Joey Jr (BennVenn) โ Windows-focused
The Joey Jr is a compact USB dumper from BennVenn. It uses BennVenn's own companion software.
**Steps:**
1. Download the BennVenn software from [bennvenn.myshopify.com](https://bennvenn.myshopify.com) (check the product page for the latest version).
2. Insert your cartridge and connect the Joey Jr via USB.
3. Open the companion app and select **Dump ROM**.
4. Save the resulting file to your computer.
{% hint style="warning" %}
The BennVenn companion software is **Windows-only**. macOS/Linux users should consider the GB Operator or GBxCart RW instead.
{% endhint %}
***
### NES / SNES / N64 / Genesis / SMS / Game Gear
Several hardware options support cartridge-based home consoles. The right choice depends on which systems you need and your budget.
Retrode 2 โ No software required
The Retrode 2 appears as a **USB mass storage device** โ your computer mounts it like a flash drive and the ROM is directly readable. No driver or app installation required.
**Supported natively (with included slots):**
* SNES / Super Famicom
* Sega Genesis / Mega Drive
**Supported with optional adapters:**
* N64, Game Boy (GB/GBC/GBA), Sega Master System, Game Gear, and more
**Steps:**
1. Insert the cartridge into the appropriate slot on the Retrode 2.
2. Connect the Retrode 2 to your computer via USB.
3. Your computer mounts a virtual drive โ open it in Finder (macOS) or Explorer (Windows).
4. Copy the `.sfc`, `.md`, or other ROM file directly to your computer.
{% hint style="warning" %}
The Retrode 2 is **discontinued** but available used (eBay, forums). The N64 adapter has known compatibility issues with some cartridges โ CIC/lockout chips may cause partial or failed dumps. Use INLretro or OSCR for more reliable N64 dumping.
{% endhint %}
INLretro Dumper-Programmer โ Active development, NES native support
The INLretro is actively maintained and supports a wide range of cartridge formats including NES (with native mapper support), SNES, N64, Genesis, and many others.
**Steps:**
1. Download the INLretro client software from [inlretro.com](https://inlretro.com).
2. Connect the INLretro device via USB.
3. Insert your cartridge into the appropriate adapter/slot.
4. Open the client software and select your system.
5. Click **Dump** to read the ROM to your computer.
INLretro is especially recommended for NES โ it handles many mappers and PCB variants natively.
Open Source Cart Reader (OSCR) โ Broadest system support
The OSCR (by sanni) is a DIY Arduino-based cart reader that supports 50+ systems. It dumps directly to an SD card โ no computer software required during the dump.
**What you need:**
* OSCR hardware (build from [GitHub](https://github.com/sanni/cartreader), or buy pre-assembled from community vendors)
* SD card (FAT32 formatted)
* Appropriate cart slot/adapter for your system
**Steps:**
1. Insert a FAT32-formatted SD card into the OSCR.
2. Insert the game cartridge into the correct slot.
3. Power on the OSCR and navigate the menu to select your system.
4. Select **Dump ROM** โ the file is written directly to the SD card.
5. Transfer the SD card to your computer and copy the ROM file.
{% hint style="info" %}
The OSCR has the broadest system support of any cart reader. Community slot adapters are available for Neo Geo MVS/AES, WonderSwan, PC Engine HuCard, Atari 2600/5200/7800, and many more. Check the OSCR GitHub wiki for a full adapter list.
{% endhint %}
***
### Nintendo DS & 3DS
Dumping DS and 3DS cartridges requires a hacked 3DS running **GodMode9**, a powerful homebrew tool.
{% hint style="warning" %}
**Prerequisites:** Your 3DS must have custom firmware (CFW) installed before using GodMode9. Follow the complete CFW setup guide at [3ds.hacks.guide](https://3ds.hacks.guide) โ this installs Luma3DS and enables homebrew. This process is outside the scope of this wiki.
{% endhint %}
GodMode9 โ Dumping DS & 3DS cartridges
GodMode9 is a full-access file system browser for the 3DS. It can dump game cartridges to the SD card.
**What you need:**
* Nintendo 3DS with Luma3DS CFW installed
* GodMode9 installed (typically already included with a standard CFW setup via 3ds.hacks.guide)
* SD card with sufficient free space (3DS games can be up to 4 GB)
**Steps:**
1. Power off your 3DS.
2. Insert the game cartridge you want to dump.
3. Hold the **Start** button and power on the 3DS to boot into GodMode9.
4. Navigate to **`[C:] GAMECART`** using the D-pad.
5. Select the `.trim.3ds` or `.nds` file shown (this is your cartridge).
6. Press **A** to open the options menu, then select **`Copy to 0:/gm9/out`** (or your preferred output location on the SD card).
7. Wait for the dump to complete, then power off the 3DS.
8. Remove the SD card and transfer the dumped ROM file to your computer.
For **DS cartridges** inserted into a 3DS, the same process applies โ GodMode9 will show the `.nds` file under `[C:] GAMECART`.
{% hint style="info" %}
3DS ROM dumps (`.3ds` files) may need to be decrypted before Provenance can use them. See the [Nintendo 3DS Guide](/platforms-and-performance/system-guides/3ds) for details on decrypted ROMs and compatible formats.
{% endhint %}
***
### Other Systems
Other systems with OSCR adapter support
The OSCR ([GitHub](https://github.com/sanni/cartreader)) supports adapters for many additional systems:
| System | Method | Notes |
| ------------------------------------ | ----------------------------------- | -------------------------------------- |
| **Neo Geo MVS / AES** | OSCR with Neo Geo adapter | MVS (arcade) and AES (home) cartridges |
| **Atari 2600 / 5200 / 7800** | INLretro or OSCR with Atari adapter | Check INLretro system support page |
| **WonderSwan / WonderSwan Color** | OSCR with WonderSwan adapter | Community-built adapter |
| **PC Engine / TurboGrafx-16 HuCard** | OSCR with PCE adapter | HuCard only (not CD-ROMยฒ) |
| **Sega Master System / Game Gear** | Retrode 2 adapter or OSCR | Both use similar cartridge pinouts |
For systems not listed here, search the OSCR GitHub issues and wiki โ the community frequently adds new adapter designs.
***
## Disc Ripping
Use the table below to find the right method for your system, then follow the instructions in the relevant section.
### Equipment Overview
| Method | Works For | What You Need |
| ---------------------------- | --------------------------------------------------- | ------------------------------------------------ |
| Standard CD-ROM drive | PS1, Sega CD, Saturn, 3DO, TG-CD, PC-FX, Neo Geo CD | Any modern optical drive |
| DVD-ROM drive | PS2 | DVD-capable drive |
| Specialized GD-ROM drive | Dreamcast | Yamaha CRW2200 or Plextor PX-W4012 (rare) |
| Console-side dump (CleanRip) | GameCube, Wii | Wii with Homebrew Channel + SD card or USB drive |
| Network dump | PS2, Dreamcast, PSP | Softmodded console + network |
{% hint style="info" %}
**Xbox not supported:** Original Xbox backups are out of scope for this guide โ Provenance does not support the original Xbox.
{% endhint %}
***
### Standard CD Games (PS1, Sega CD, Saturn, 3DO, TG-CD, PC-FX, Neo Geo CD)
Most CD-based games can be ripped with any standard optical drive. The output is a `.bin + .cue` pair โ see [Formatting ROMs โ Multi-file ROMs](/using-provenance/roms/formatting-roms#multi-file-roms) for how to package them for import.
{% tabs %}
{% tab title="macOS" %}
**Tool:** cdrdao (free, command-line)
1. Install [Homebrew](https://brew.sh) if you haven't already.
2. Install cdrdao:
```bash
brew install cdrdao
```
3. Insert the disc and find the device path:
```bash
drutil status
```
Note the device (typically `/dev/disk2`).
4. Rip the disc as a raw image:
```bash
cdrdao read-cd --read-raw --datafile "game.bin" --device /dev/disk2 --driver generic-mmc-raw game.toc
```
5. Convert the `.toc` file to `.cue`:
```bash
toc2cue game.toc game.cue
```
You now have `game.bin` and `game.cue`. Archive both in a single `.zip` or `.7z` before importing.
{% endtab %}
{% tab title="Windows" %}
**Tool:** ImgBurn (free GUI)
1. Download and install [ImgBurn](https://www.imgburn.com).
2. Insert the disc.
3. Select **Mode โ Read Disc**.
4. Set the **Destination** to a folder on your PC.
5. For PlayStation 1 discs, click the **Options** tab and set:
* **Read Sub Channel Data from Disc:** Yes
* **Type:** User Data + Sub-Channel Q
6. Click the **Read** button (disc-to-folder icon).
ImgBurn outputs a `.bin` and `.cue` file. Archive both before importing into Provenance.
{% endtab %}
{% tab title="Linux" %}
**Tool:** cdrdao (same commands as macOS)
1. Install cdrdao via your package manager:
```bash
sudo apt install cdrdao # Debian/Ubuntu
sudo dnf install cdrdao # Fedora
```
2. Find your disc device:
```bash
lsblk
```
It's usually `/dev/sr0`.
3. Rip the disc:
```bash
cdrdao read-cd --read-raw --datafile game.bin --device /dev/sr0 --driver generic-mmc-raw game.toc
toc2cue game.toc game.cue
```
For scratched or damaged **data-only** discs, `ddrescue` can attempt a more robust read. This produces a single-track `.bin`; for mixed-mode or audio CDs (PS1, Sega CD, Saturn), use `cdrdao` above instead:
```bash
sudo apt install gddrescue
ddrescue -d -r3 /dev/sr0 game.bin game.log
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Verify your rip with Redump:** Calculate the MD5 hash of your `.bin` file (`md5 game.bin` on macOS, `md5sum game.bin` on Linux, `certutil -hashfile game.bin MD5` on Windows) and search [redump.org](https://redump.org) to confirm it matches the known-good dump. A matching hash means your rip is accurate.
{% endhint %}
{% hint style="warning" %}
**TurboGrafx-CD / PC Engine CD:** These systems require a System Card BIOS file to run. See [BIOS Requirements](/getting-started/bios-requirements) for the correct files.
{% endhint %}
**Saturn multi-disc games:** Saturn titles that span multiple discs need an `.m3u` playlist file. See [Formatting ROMs โ Multi-disc Games](/using-provenance/roms/formatting-roms#multi-disc-games) for instructions.
**Sega CD:** All three regional BIOS files are required (USA, Europe, Japan) depending on the game's region. See [BIOS Requirements](/getting-started/bios-requirements).
***
### PlayStation 2
PS2 discs are standard DVDs and can be ripped with a DVD-ROM drive. Dual-layer discs (larger games) may fail on macOS optical drives โ a USB DVD drive or network dump is more reliable.
**Method A: DVD drive on PC**
{% tabs %}
{% tab title="Windows" %}
Use ImgBurn in **Mode โ Read Disc**. Output format: **ISO**. No special subchannel settings needed.
{% endtab %}
{% tab title="Linux" %}
```bash
# Install (Debian/Ubuntu): sudo apt install gddrescue
# Then run:
ddrescue -d -r3 /dev/sr0 game.iso game.log
```
`ddrescue` handles read errors better than a simple `dd`, which is important for dual-layer discs.
{% endtab %}
{% endtabs %}
**Method B: Network dump (OPL/FreeMcBoot)**
If you have a softmodded PS2 running FreeMcBoot and Open PS2 Loader (OPL), you can dump discs over the network without a PC DVD drive. See the [Network / Softmod Ripping](#network--softmod-ripping) section below.
Output format for PS2: `.iso`
### Network Dump (PS2, Dreamcast, PSP)
A *network dump* means using a modified console to stream game data over your local network to a computer, instead of reading the disc directly with a PC drive.
Typical flow:
* Softmod or homebrew-enable your console (e.g. FreeMcBoot/OPL on PS2, homebrew loader on Dreamcast/PSP).
* Run a dumping utility on the console that exposes the disc or UMD over the network.
* Connect from your computer (often via a small helper app or web interface) and save the disc image to storage.
* Import the resulting ISO/CSO (or other supported format) into Provenance as you would any other ROM.
For consoles without a reliable PC-compatible drive (like Dreamcast GD-ROM or UMD-based systems), network dumping is often the most practical way to get a complete image of your own discs. See [Network / Softmod Ripping](#network--softmod-ripping) below for step-by-step instructions.
***
### Dreamcast GD-ROM
{% hint style="danger" %}
**GD-ROM is a proprietary format.** Standard PC optical drives can only read the low-density area (\~1 GB) of a GD-ROM disc โ the game data lives in the high-density area and is **inaccessible** to ordinary drives. You need a specialized drive or a network dump method.
{% endhint %}
**Method A: Specialized GD-ROM drive (rare)**
Two drives are known to work with GD-ROM ripping tools:
* **Yamaha CRW2200** โ most common recommended drive
* **Plextor PX-W4012** โ also works
These drives typically cost $100โ$300+ and are hard to find. If you have one, use **GD-ROM Explorer** or other compatible GD-ROM ripping software with the appropriate PC tools.
**Method B: Network dump via httpd-ism (recommended)**
httpd-ism network dump method
This method uses an original Dreamcast equipped with the official Broadband Adapter and the **httpd-ism** boot disc to serve GD-ROM data over HTTP.
**Requirements:**
* Dreamcast console
* Dreamcast Broadband Adapter (HIT-0400)
* httpd-ism boot disc (burned CD-R)
* PC on the same local network
**Steps:**
1. Boot the httpd-ism disc on the Dreamcast.
2. Note the IP address displayed on screen.
3. On your PC, open a browser and navigate to `http://[dreamcast-ip]/` โ you'll see a file listing of the GD-ROM tracks.
4. Download all track files (typically `track01.iso`, `track02.raw`, etc.) to a folder on your PC.
5. Download the accompanying `.gdi` descriptor file.
**Alternative:** **DreamShell** is a more modern alternative that also supports network dumping via SD card or network adapter. Consult the DreamShell documentation for setup details.
**Output format:** `.gdi` (a descriptor file referencing multiple track files)
After dumping, convert to a single `.chd` file for easier import:
```bash
chdman createcd -i game.gdi -o game.chd
```
See [Advanced ROM Management โ CHD Format](/using-provenance/roms/advanced-management#chd-format-recommended) for more on `chdman`.
***
### GameCube & Wii
Nintendo optical discs use a proprietary format that standard PC drives cannot read directly. **CleanRip** is the recommended homebrew tool that runs on the Wii itself.
CleanRip (recommended) โ dump from the console
**Requirements:**
* Wii console with the **Homebrew Channel** installed
* SD card or USB drive formatted as **FAT32** with 8+ GB free. FAT32 is required โ the Wii cannot read exFAT or NTFS. CleanRip automatically splits Wii ISOs (\~4.7 GB) into 4 GB chunks to work around FAT32's file size limit; the split files can be rejoined with a tool like **wit** (Wiimms ISO Tools) after transfer to your PC.
* CleanRip homebrew app
**Steps:**
1. Download CleanRip and copy it to your SD card: `SD:/apps/CleanRip/boot.dol`
2. Boot the Wii and launch the Homebrew Channel.
3. Launch **CleanRip**.
4. Select your dump destination (SD or USB).
5. When prompted, insert the GameCube or Wii disc.
6. Select the disc type and confirm settings (leave defaults unless you know otherwise).
7. CleanRip will dump the disc โ allow 10โ40 minutes depending on disc size.
8. Copy the resulting `.iso` file to your PC.
PC drive alternative (less reliable)
Specific LG and Asus drives with certain firmware can read Wii/GameCube discs using raw read commands.
**Known compatible drives (partial list):**
* LG GH22NS30 (with patched firmware)
* Asus DRW-24B1ST
**Tools:**
* **Friidump** โ open-source, reads via raw SCSI commands
* **Rawdump** โ Windows-only alternative
This method is less reliable than CleanRip, requires finding a compatible drive, and may fail on dual-layer Wii discs. CleanRip is strongly preferred.
Output format: `.iso` (for both GameCube and Wii)
For folder structures and further configuration, see the [GameCube & Wii system guide](/platforms-and-performance/system-guides/gamecube-wii).
***
### PSP UMD
UMD discs cannot be read by a standard PC drive. Dumping requires **Custom Firmware (CFW)** running on the PSP itself. See the [Network / Softmod Ripping](#network--softmod-ripping) section for details.
***
### Other Disc Systems
| System | Method | Notes |
| -------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **3DO** | Standard CD drive | Same as PS1 section above. Output: `.bin + .cue` |
| **Neo Geo CD** | Standard CD drive | Same as PS1 section above. Output: `.bin + .cue` |
| **PC Engine CD / TurboGrafx-CD** | Standard CD drive | Same as PS1 section above. Requires System Card BIOS โ see [BIOS Requirements](/getting-started/bios-requirements) |
| **PC-FX** | Standard CD drive | Same as PS1 section above. Requires PC-FX BIOS โ see [BIOS Requirements](/getting-started/bios-requirements) |
| **Sega CD / Mega CD** | Standard CD drive | Same as PS1 section above. All 3 regional BIOS files required โ see [BIOS Requirements](/getting-started/bios-requirements) |
***
{% hint style="info" %}
After ripping, convert disc images to CHD format for smaller files and single-file convenience. See [Advanced ROM Management](/using-provenance/roms/advanced-management#chd-format-recommended) for chdman commands.
{% endhint %}
***
## Network / Softmod Ripping
Some systems can dump games directly from the console using custom firmware (CFW) or homebrew software โ no dedicated hardware dumper required.
### Nintendo 3DS
Using GodMode9 on a CFW 3DS (Luma3DS)
3DS ROM dumping requires a 3DS running custom firmware. The most common CFW is **Luma3DS**, installed via the [3ds.hacks.guide](https://3ds.hacks.guide/) process.
**What you need:**
* A 3DS/2DS with Luma3DS CFW installed
* **GodMode9** (included with most CFW setups)
**Steps:**
1. Power on your 3DS and hold **Start** to boot into GodMode9
2. Navigate to `[C:] GAMECART` if you have a physical card inserted, or `[A:] SYSNAND SD` for installed titles
3. Select your game and choose **Copy to 0:/gm9/out**
4. The output is a `.3ds` file (encrypted) or use the **Decrypt** option for a decrypted `.cia`
5. Transfer the file to your computer via the SD card
6. Import into Provenance โ see the [Nintendo 3DS Guide](/platforms-and-performance/system-guides/3ds) for compatible formats
### Nintendo DS
Dumping DS cards via flashcard
DS game cards require a flashcard (such as an R4) and a homebrew dumping tool on a DS or DSi.
{% hint style="warning" %}
DS card dumping via homebrew requires a homebrew-enabled DS/DSi. Refer to [dsi.cfw.guide](https://dsi.cfw.guide/) for setup guides.
{% endhint %}
**Steps:**
1. Enable homebrew on your DS/DSi using the guide above
2. Use a DS ROM dumping homebrew app (search GBAtemp for current tools)
3. Dump the card to your SD card as a `.nds` file
4. Transfer to your computer and import into Provenance
### PlayStation 2 (FreeMcBoot)
{% hint style="warning" %}
**PS2 support is in development** โ PlayStation 2 emulation in Provenance is currently experimental and not fully available in stable releases. These instructions are provided for when PS2 support ships.
{% endhint %}
Using FreeMcBoot + Open PS2 Loader (OPL)
PS2 can dump disc images to a USB drive or network share using homebrew tools via a modded memory card.
**What you need:**
* PS2 console with **FreeMcBoot** memory card
* **Open PS2 Loader (OPL)** installed on the memory card
* USB drive (FAT32 formatted)
**Steps:**
1. Boot your PS2 with the FreeMcBoot memory card
2. Launch OPL from the FreeMcBoot menu
3. Insert your PS2 disc
4. Use OPL's **Install Game** feature to rip the disc to a USB drive or network share
5. The output is an `.iso` file
6. Transfer to your computer and import into Provenance (or convert to `.chd` โ see [Format Conversion](#format-conversion))
### SNES / NES Classic (hakchi)
Exporting ROMs from a Nintendo Classic Mini
If you own a SNES Classic or NES Classic, you can export the pre-installed ROMs using **hakchi2 CE** or **hakchi** (a console mod tool).
**What you need:**
* SNES Classic or NES Classic console
* **hakchi2 CE** (Windows/macOS via Wine)
* USB cable (Micro-USB for NES Classic, USB-C for SNES Classic)
**Steps:**
1. Follow the hakchi2 CE setup guide to install custom firmware on your Classic console
2. Connect the console to your computer via USB
3. In hakchi2 CE, go to **Synchronize selected games** to view installed ROMs
4. Export the ROM files from the hakchi2 CE working directory (found in your Documents folder)
5. Import the exported ROMs into Provenance
{% hint style="info" %}
SNES Classic ROMs are standard `.sfc` files; NES Classic ROMs are standard `.nes` files โ both work directly in Provenance.
{% endhint %}
***
## Save Data Dumping
Backing up save data lets you preserve progress from your original cartridges and memory cards.
### Game Boy / GBA Saves
| Tool | Method | Notes |
| --------------- | --------------------------------- | ------------------------------------ |
| **GB Operator** | Open Epilogue app โ **Dump Save** | Easiest; saves as `.sav` |
| **GBxCart RW** | Open FlashGBX โ **Read Save** | Open-source; supports all GB/GBC/GBA |
To use a dumped save in Provenance: place the `.sav` file in the same folder as your ROM with the same base filename (e.g., `Pokemon Red.gb` โ `Pokemon Red.sav`).
### PS1 Memory Cards
Using MemcardRex
**MemcardRex** is a free tool for reading PS1 memory cards via a USB memory card reader.
**What you need:**
* PS1 memory card reader (e.g., a PS1-to-USB adapter)
* [MemcardRex](https://github.com/ShendoXT/memcardrex) (Windows/Linux via Wine)
**Steps:**
1. Connect your PS1 memory card reader to your computer
2. Open MemcardRex and select **Open Memory Card**
3. Choose your memory card reader device
4. MemcardRex reads the card and displays all save slots
5. Export individual saves as `.mcd` or the full card as a memory card image
6. Provenance can use these saves for PS1 games (place alongside the ROM)
### PlayStation 2 Saves
PS2 save data can be exported using **Open PS2 Loader (OPL)** or **uLaunchELF** on a FreeMcBoot-enabled console, then transferred via USB.
Using uLaunchELF to copy saves
1. Boot your PS2 with the FreeMcBoot memory card
2. Launch **uLaunchELF** from the FreeMcBoot menu
3. Navigate to `mc0:/` (Memory Card slot 1) or `mc1:/`
4. Find your save folder (named by game ID, e.g., `BASLUS-12345`)
5. Copy it to `mass:/` (USB drive) using the file manager
6. Transfer to your computer
### Nintendo 64 Saves
N64 saves are stored on the cartridge itself (SRAM or EEPROM) or on a Controller Pak (memory pak). Most cart dumpers also dump the save:
| Dumper | Save Method |
| --------- | --------------------------------------------------------------- |
| INLretro | **Dump RAM** option dumps SRAM/EEPROM alongside the ROM |
| Retrode 2 | The mounted drive includes a `.srm` save file alongside the ROM |
Controller Pak saves require a dedicated tool โ search GBAtemp for current N64 Controller Pak reader projects.
***
## Format Conversion
When you obtain disc images from your own physical media, they may not always be in a format that Provenance accepts directly. This section covers converting between common formats.
{% hint style="info" %}
**Already covered elsewhere:**
* CHD conversion (BIN/CUE โ CHD): [Advanced ROM Management](/using-provenance/roms/advanced-management#chd-format-recommended)
* UnECM (.ecm file restoration): [Formatting ROMs](/using-provenance/roms/formatting-roms#unecm)
* Multi-file ROM archiving: [Formatting ROMs](/using-provenance/roms/formatting-roms#multi-file-roms)
{% endhint %}
### Quick Reference
| Source Format | Target Format | Tool | Platform | Notes |
| ------------------------- | ---------------------------------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `.bin + .cue` | `.chd` | chdman | All | See [Advanced ROM Management](/using-provenance/roms/advanced-management#chd-format-recommended) |
| `.gdi` (Dreamcast) | `.chd` | chdman | All | `chdman createcd -i game.gdi -o game.chd` |
| `.iso` (CD / DVD) | `.chd` | chdman | All | CD: `chdman createcd -i game.iso -o game.chd` ยท DVD: `chdman createdvd -i game.iso -o game.chd` |
| `.nrg` (Nero) | `.iso` | nrg2iso | All | Free CLI tool |
| `.mdf + .mds` (Alcohol) | `.bin + .cue` (preferred) / `.iso` (data-only) | IsoBuster / mdf2iso | Win / All | Prefer BIN/CUE for mixed-mode or audio; use ISO only for pure data discs |
| `.cdi` (DiscJuggler) | `.gdi` | cdirip | All | Mainly for Dreamcast dumps |
| `.bin.ecm` | `.bin` | unecm | All | See [Formatting ROMs](/using-provenance/roms/formatting-roms#unecm) |
| `.pbp` (PSP game EBOOT) | โ (no conversion) | โ | All | PSP titles in `.pbp` can be used as-is |
| `.pbp` (PSX-on-PSP EBOOT) | `.bin + .cue` | PSX2PSP | Win | For PS1 games packaged as PSP EBOOTs |
### Format Reference Table
| System | Raw Dump Format | Recommended Provenance Format |
| --------- | ---------------- | ------------------------------- |
| PS1 | `.bin` + `.cue` | `.chd` |
| PS2 | `.iso` | `.chd` |
| PSP | `.iso` | `.iso` or `.cso` |
| GameCube | `.iso` | `.iso`, `.gcm`, `.gcz`, `.ciso` |
| Wii | `.iso` | `.iso` or `.wbfs` |
| Dreamcast | `.gdi` or `.cdi` | `.chd` |
| Sega CD | `.bin` + `.cue` | `.chd` |
| Saturn | `.bin` + `.cue` | `.chd` |
See [Formatting ROMs](/using-provenance/roms/formatting-roms) for the complete extension list for all systems.
***
### NRG โ ISO (Nero Image Format)
Nero Burning ROM creates `.nrg` disc images that are not directly usable with Provenance. Use **nrg2iso** to convert them to standard ISO files.
**Install nrg2iso:**
{% tabs %}
{% tab title="macOS" %}
```bash
brew install nrg2iso
```
{% endtab %}
{% tab title="Linux" %}
```bash
sudo apt install nrg2iso
```
{% endtab %}
{% tab title="Windows" %}
Download from SourceForge: search "nrg2iso" and download the Windows binary.
{% endtab %}
{% endtabs %}
**Convert:**
```bash
nrg2iso game.nrg game.iso
```
After converting, you can import the `.iso` directly into Provenance, or convert it further to `.chd` for better compression (see [Advanced ROM Management](/using-provenance/roms/advanced-management#chd-format-recommended)).
***
### MDF/MDS โ BIN/CUE (or ISO for data-only discs)
Alcohol 120% creates `.mdf` (image data) + `.mds` (metadata) pairs. For best compatibility, convert to `.bin + .cue` (then optionally to `.chd` for compression). Only convert to `.iso` if you are sure the disc is data-only (no CD audio tracks).
{% hint style="info" %}
Saturn and other mixed-mode CD dumps often come as `.mdf + .mds`. Keep both files in the same folder and, if you run into issues, convert the dump to a standard format like BIN/CUE or CHD.
{% endhint %}
**Option 1: IsoBuster (Windows, GUI)**
1. Open IsoBuster and load the `.mds` file
2. Right-click the disc icon โ **Extract CD Image** โ **Extract RAW**
3. Save as `.bin` โ a `.cue` file is generated automatically
**Option 2: mdf2iso (Cross-platform CLI)**
```bash
mdf2iso game.mdf game.iso
```
mdf2iso converts the MDF/MDS pair to a standard `.iso` image. For CD-based games, use `createcd` to convert the ISO to CHD; for DVD-based games, use `createdvd`:
```bash
# Install chdman first (brew install rom-tools on macOS)
# CD-based ISO โ CHD
chdman createcd -i game.iso -o game.chd
# DVD-based ISO โ CHD
chdman createdvd -i game.iso -o game.chd
```
***
### CDI โ GDI (DiscJuggler / Dreamcast)
DiscJuggler `.cdi` files are a proprietary Dreamcast disc format. Use **cdirip** to extract them into a GDI layout, which can then be converted to CHD.
**Install and run cdirip:**
```bash
# Download cdirip from its project page (cross-platform binary)
cdirip game.cdi
```
This outputs track files in GDI layout (a `.gdi` file plus `.raw`/`.bin` tracks). Then convert to CHD:
```bash
chdman createcd -i "game.gdi" -o "game.chd"
```
See [Advanced ROM Management](/using-provenance/roms/advanced-management#chd-format-recommended) for full chdman documentation.
***
### PBP (PSP EBOOT.PBP)
`.pbp` files come in two distinct types โ handle them differently:
**PSP games (CFW backups)**
PSP games ripped from UMD typically produce `.iso` files. Provenance's PPSSPP core accepts both `.iso` and `.pbp` formats directly โ no conversion needed.
**PSX-on-PSP titles**
Some PSP firmware allowed playing PS1 games packaged as `EBOOT.PBP`. These wrap a PS1 game inside a PSP container.
Recommended approach:
1. Import the `EBOOT.PBP` directly into Provenance **as a PlayStation game** (not as PSP/PPSSPP).
If a particular PSX-on-PSP `.pbp` does not work correctly when imported as a PlayStation title, you can extract the underlying PS1 disc image:
1. Use **PSX2PSP** (Windows) in reverse/extract mode
2. Point it at the `EBOOT.PBP`
3. Extract to `.bin + .cue`
4. Import the `.bin + .cue` (or convert to `.chd`) into Provenance as a PS1 game
{% hint style="warning" %}
Do not import PSX-on-PSP `.pbp` files as PSP games โ the PPSSPP core will not run PS1 content correctly. Always treat them as PlayStation titles; only extract to `.bin + .cue` as a fallback if a specific `.pbp` has issues.
{% endhint %}
***
### GDI โ CHD (Dreamcast)
GDI is the standard ripping format for Dreamcast discs. Convert to CHD for better compression and single-file convenience.
**Install chdman:**
{% tabs %}
{% tab title="macOS" %}
```bash
brew install rom-tools
```
{% endtab %}
{% tab title="Windows" %}
Download `chdman.exe` from the MAME project at mamedev.org.
{% endtab %}
{% endtabs %}
**Convert:**
```bash
chdman createcd -i "game.gdi" -o "game.chd"
```
For batch conversion of a folder of Dreamcast GDI dumps:
```bash
find . -type f -name '*.gdi' -print0 | while IFS= read -r -d '' f; do
chdman createcd -i "$f" -o "${f%.gdi}.chd"
done
```
### Multi-Disc M3U Playlists
Games that span multiple discs (e.g., Final Fantasy VII) need an `.m3u` playlist file so Provenance can switch discs mid-game.
**Create an `.m3u` file** in the same folder as your disc images with one line per disc:
```
Final Fantasy VII (Disc 1).chd
Final Fantasy VII (Disc 2).chd
Final Fantasy VII (Disc 3).chd
```
Name the `.m3u` file after the game: `Final Fantasy VII.m3u`. Import the `.m3u` file into Provenance โ it will appear as a single game entry.
See [Formatting ROMs](/using-provenance/roms/formatting-roms) for more details on multi-disc setup.
***
## After Dumping
Once you have your ROM files:
1. **Check the format** โ Review [Formatting ROMs](/using-provenance/roms/formatting-roms) to confirm you have the correct file extension for your system
2. **Convert if needed** โ CD-based games may need conversion to `.chd` for space savings (see [Advanced ROM Management](/using-provenance/roms/advanced-management))
3. **Import into Provenance** โ See [Importing ROMs](/using-provenance/importing-roms) for all import methods
4. **Check BIOS requirements** โ Some systems need BIOS files โ see [BIOS Requirements](/getting-started/bios-requirements)
{% hint style="success" %}
Dumped ROMs from your own hardware are the highest quality source โ no compression artifacts, correct region, and exact checksums. These will produce the best results in Provenance.
{% endhint %}
***
## Troubleshooting
My dumper isn't recognized by my computer
* Try a different USB cable (use a data cable, not a charge-only cable)
* Try a different USB port โ avoid USB hubs for dumpers
* On macOS, check System Settings โ Privacy & Security if the driver is blocked
* Install any required drivers from the manufacturer's site (some dumpers need CH340 or FTDI drivers)
* Restart your computer after installing drivers
The ROM dump seems too small or is obviously wrong
* The cartridge may have dirty contacts โ clean with isopropyl alcohol (90%+) and a cotton swab, then retry
* Reseat the cartridge โ remove and reinsert it firmly
* Some cartridges have battery-backed SRAM; the battery may be dead, but this shouldn't affect ROM dumping
* Verify the mapper setting if using the INLretro โ an incorrect mapper produces garbled output
The dumped ROM doesn't work in Provenance
* Check that the file extension is correct for your system (see [Formatting ROMs](/using-provenance/roms/formatting-roms))
* Compare the file size against known-good values โ a 4 MB SNES ROM should be exactly 4,194,304 bytes
* For CD-based games, ensure you have both the `.bin` and `.cue` files, or convert to `.chd`
* Try renaming the file to remove special characters โ stick to alphanumeric names
GB Operator / GBxCart shows "No cartridge detected"
* Clean the cartridge contacts with isopropyl alcohol
* Ensure the cartridge is fully inserted and seated
* Try a different USB port or cable
* Some aftermarket or bootleg cartridges may not be recognized โ official Nintendo cartridges should always work
***
## See Also
* [Importing ROMs](/using-provenance/importing-roms) โ How to get your dumped ROMs into Provenance
* [Formatting ROMs](/using-provenance/roms/formatting-roms) โ Correct file formats for every system
* [BIOS Requirements](/getting-started/bios-requirements) โ BIOS files needed for certain systems
* [Advanced ROM Management](/using-provenance/roms/advanced-management) โ CHD conversion, organizing large libraries
* [Game Saves](/using-provenance/saves) โ Managing save files and save states in Provenance
* [Nintendo 3DS Guide](/platforms-and-performance/system-guides/3ds) โ 3DS-specific setup in Provenance
* [GameCube & Wii Guide](/platforms-and-performance/system-guides/gamecube-wii) โ Dolphin folder structure for GameCube/Wii ROMs
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Formatting ROMs
How to format, convert, archive, or batch process ROMs.
To avoid any issues with [Importing ROMs](https://github.com/Provenance-Emu/Provenance/wiki/Importing-ROMs), check to make sure your files are formatted correctly.
* โ
[**Supported Formats**](#supported-formats)\*\*\*\*
* [ROMs](#roms) ยท *by system*
* [ROM Archives](#rom-archives)
* [Multi-file ROMs](#multi-file-roms)
* [Multi-disc Games](#multi-disc-games)
* ๐ [**Converting Formats**](#converting-formats)\*\*\*\*
* [Converting ROMs](#converting-roms)
* [Editing Memory Cards](#converting-and-editing-memory-cards)
* [UnECM](#unecm) ยท *restore original format from* `.ecm` *files*
* โฌ [**Archiving**](#archiving)\*\*\*\*
* โฉ [**Batching**](#batching) ยท *batch renaming and (re)archiving*
{% hint style="warning" %}
Please refer to the [Known Issues](#known-issues) regarding Formatting ROMs, and read [Issues Usage](https://github.com/Provenance-Emu/Provenance/wiki/Issues-Usage) *before* posting a new one.
{% endhint %}
{% hint style="info" %}
**Interactive Reference:** [eduo.info/pvl](https://eduo.info/pvl/) โ Community-built searchable database of all Provenance systems, cores, BIOS requirements, and supported file extensions (parsed directly from Provenance's source code).
{% endhint %}
## Supported Formats
### ROMs
| Manufacturer | System | Supported Format(s) / Extensions |
| ------------ | ------ | -------------------------------- |
| Atari | 2600 | `.a26` *(.bin)* |
| ----- | ---- | --------------- |
| | 5200 | `.a52` *(.bin)* |
| - | ---- | --------------- |
| | 7800 | `.a78` *(.bin)* |
| - | ---- | --------------- |
| | Jaguar | `.j64`, `.jag` *(.bin, .rom)* |
| - | ------ | ----------------------------- |
| | Lynx | `.lnx` |
| - | ---- | ------ |
| Bandai | WonderSwan | `.ws` |
| ------ | ---------- | ----- |
| | WonderSwan Color | `.wsc` |
| - | ---------------- | ------ |
| NEC | PC Engine / TurboGrafx-16 | `.pce` |
| --- | ------------------------- | ------ |
| | PC Engine Super CD-ROMยฒ System / TurboGrafx-CD | `.cue + .bin/iso`, `.ccd + .img + .sub` *multi-file ROM* |
| - | ---------------------------------------------- | -------------------------------------------------------- |
| | PC Engine SuperGrafx | |
| - | -------------------- | - |
| | PC-FX | `.cue + .bin/iso`, `.ccd + .img + .sub` *multi-file ROM* |
| - | ----- | -------------------------------------------------------- |
| Nintendo | Famicom /
Nintendo Entertainment System
| `.nes` |
| -------- | ---------------------------------------------------- | ------ |
| | Famicom Disk System | `.fds` |
| - | ------------------- | ------ |
| | Game Boy | `.gb` |
| - | -------- | ----- |
| | Super Famicom / Super Nintendo Entertainment System | `.snes`, `.smc`, `.sfc`, `.fig` |
| - | --------------------------------------------------- | ------------------------------- |
| | Game Boy Color | `.gbc`, `.sgb` |
| - | -------------- | -------------- |
| | Virtual Boy | `.vb` |
| - | ----------- | ----- |
| | Nintendo 64 | `.n64`, `.z64` |
| - | ----------- | -------------- |
| | Game Boy Advance | `.gba` |
| - | ---------------- | ------ |
| | Pokemon mini | `.min` |
| - | ------------ | ------ |
| Sega | SG-1000 | `.sg` |
| ---- | ------- | ----- |
| | Master System | `.sms` |
| - | ------------- | ------ |
| | Mega Drive / Genesis | `.md`, `.smd`, `.gen` *(.bin)* |
| - | -------------------- | ------------------------------ |
| | Game Gear | `.gg` |
| - | --------- | ----- |
| | Mega CD / Sega CD | `.cue + .bin` *multi-file ROM* |
| - | ----------------- | ------------------------------ |
| | 32X | `.32X`, `.32x` |
| - | --- | -------------- |
| | Saturn | `.iso`, `.cue + .bin/iso`, `.ccd + .img + .sub`, `.mds + .mdf` *multi-file ROM* |
| - | ------ | ------------------------------------------------------------------------------- |
| SNK | Neo Geo Pocket | `.ngp` |
| --- | -------------- | ------ |
| | Neo Geo Pocket Color | `.ngc`, `.ngpc`, `.npc` |
| - | -------------------- | ----------------------- |
| Sony | Playstation | `.cue + .bin/img/iso`, `.ccd + .img + .sub` *multi-file ROM* |
| ---- | ----------- | ------------------------------------------------------------ |
* DO NOT rename multi-file ROMs unless you alter `.cue` file contents as well.
* *All* multi-file ROMs ***must*** be contained in a single-file archives.ยฐ ([Instructions](#multi-file-roms))
* *All* multi-disc games ***must*** include a `.m3u` file in their archive. ([Instructions](#multi-disc-games))
ยฐ Though not required, it's recommended to archive *all* ROMs, individually.
### ROM Archives
| Supported Formats |
| ----------------- |
| `.zip`, `.7z` |
{% hint style="danger" %}
Loose files *only*. DO NOT contain folder(s) within an archive (this is a known issue and will result in a crash)!
{% endhint %}
### Multi-file ROMs
A ROM consisting of multiple files such as `.bin` + `.cue` for CD-based games (Sega CD, Playstation, etcโฆ) ***must*** be contained together in a *single* `.zip` or `.7z` archive *before* importing and *both files are required*.ยน
**Examples of ROM archive contents:**
```
[game].bin
[game].cue
```
```
[game] (Track 1).bin
[game] (Track 2).bin
[game].cue
```
```
[game].ccd
[game].img
[game].sub
```
{% hint style="warning" %}
If **.ccd** based ROMs are not importing correctly, move files into the system directory, manually, when left behind in Imports or Conflicts.
{% endhint %}
{% hint style="danger" %}
Loose files *only*. DO NOT contain folder(s) within an archive (this is a known issue and will result in a crash)!
{% endhint %}
#### **.cue Files:**
`.cue` files are plain text and will generally look something like this (unless it specifies additional audio track details). The name of the referenced file: `.bin`, `.img`, `.iso`โฆ specified file ***must*** match verbatim the name of the actual file.ยฒ
**Contents of \[game].cue**:
```
FILE "[game].bin" BINARY
TRACK 01 MODE2/2352
INDEX 01 00:00:00
```
ยน If you need to restore a missing/damaged `.cue` file, check out the archives at [redump.org](http://redump.org).\
ยฒ If you rename any files of a`.cue` based multi-file ROM, you ***must*** change the contents of the `.cue` file *or they won't work.*
โฆarchive filenames, however, are irrelevant as they are discarded after unarchiving.
{% hint style="info" %}
For a quick way to preview **.cue** files on macOS, install the [qlstephen QuickLook plugin](https://github.com/whomwah/qlstephen/releases).
{% endhint %}
### Multi-disc Games
All multi-disc games ***must*** include a `.m3u` file *in* their `.zip` or `.7z` multi-file ROM archive. Disc numbering in filenames needs to be formatted *exactly* as: `โฆ(Disc #).ext`
{% hint style="warning" %}
If renaming and using **\*\*a** .cue **based \*\***ROM make sure to read the requirements for **.cue** files in [Multi-file ROMs](#multi-file-roms).
{% endhint %}
**Contents of Final Fantasy VII (USA).7z**:
```
Final Fantasy VII (USA) (Disc 1).bin
Final Fantasy VII (USA) (Disc 1).cue
Final Fantasy VII (USA) (Disc 2).bin
Final Fantasy VII (USA) (Disc 2).cue
Final Fantasy VII (USA) (Disc 3).bin
Final Fantasy VII (USA) (Disc 3).cue
Final Fantasy VII (USA).m3u
```
`.m3u` files can be created as plain text and ***must*** *contain* and *match exactly* the names of *all* and *only* the `.cue` or `.ccd` files for the game.ยณ
**Contents of Final Fantasy VII (USA).m3u**:
```
Final Fantasy VII (USA) (Disc 1).cue
Final Fantasy VII (USA) (Disc 2).cue
Final Fantasy VII (USA) (Disc 3).cue
```
ยณ `.m3u` filenames are independent of the `.bin/.cue` files, but a truncated name is recommended, removing " (Disc #)" from the .m3u filename (including the space).
{% hint style="info" %}
For a quick way to preview **.m3u** files on macOS, install the [qlstephen QuickLook plugin](https://github.com/whomwah/qlstephen/releases).
{% endhint %}
## Converting Formats
### Converting ROMs
* **Cartridge-based ROMs** generally do not need converting. Formats like `.bin` vs `.md` or `.gen` (Sega Genesis) or `.sfc` vs `.smc` (Super Nintendo) are generally just different filename extensions for the same format to simplify identifying shared formats across systems and avoid conflicts. They are basically interchangeable and you can simply rename them to a supported extension.
* **CD-based ROMs** require certain supported formatsโฆ
* If you have part of a supported multi-file ROM, but are missing the additional file(s) such as `.cue` , `.ccd`, `.sub`โฆ to complete it, you may want to check out the archives at [redump.org](http://redump.org) in order to restore it properly, or try replacing the ROM entirely from a different source.
* If your filetypes are not supported, you may need to convert them with a disc image conversion app.
* If your files have been restructured via **ecm** (ie. `.bin.ecm`) they will need to be reverted: [unECM](#unecm).
### Converting & Editing Memory Cards
* PSX memory card formats can be converted to `.mcr` and edited with apps like [MemcardRex](https://github.com/ShendoXT/memcardrex).
### UnECM
**Mac**
1. Install [Homebrew](https://brew.sh) *(if you don't have it)* in Terminal with:
`/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
2. Install via Homebrew with: `brew install ecm`
3. Use `unecm [path to .ecm file]` to restore the original format.
The Terminal app can be found in: */Applications/Utilities*
**Windows**
Use these [Instructions](https://www.lifewire.com/ecm-file-2620956), for now.
## Archiving
#### Mac
**Requirements:**
* [Keka](http://www.kekaosx.com)
**Setup**
1. Set your default app unarchiving (`.zip`, `.7z`, `.rar`, etcโฆ) to Keka:
1. Select a single archive per filetype and FileโGet Info (`โI`)
2. Change `Open with:` to Keka and hit `Change Allโฆ`.
2. Open Keka and select `.7z` or .`zip` and the following settings:
โ๏ธSolid archive `.7z`
โ๏ธExclude Mac resource forks
โ๏ธDelete file(s) after compression
**Archive**
1. Drag & Drop ROM file (or files if multi-file ROM, such as `.cue + .bin`) onto Keka. Done.
{% hint style="danger" %}
Loose files *only*. DO NOT contain folder(s) within an archive (this is a known issue and will result in a crash)!
{% endhint %}
#### Windows
Use [7-Zip](https://www.7-zip.org/) (free) to create `.7z` archives:
1. Download and install [7-Zip](https://www.7-zip.org/).
2. Right-click your ROM file(s) โ **7-Zip** โ **Add to archiveโฆ**
3. Set **Archive format** to `7z`.
4. Click **OK**. Done.
{% hint style="danger" %}
Loose files *only*. DO NOT include folder(s) inside the archive (this will cause a crash)!
{% endhint %}
## Batching
โ ๏ธ This only applies to single file ROMs. DO NOT batch process multi-file ROMs using the methods below.
**Mac**
1. Setup and Requirements from Archiving.
**If Unarchiving, firstโฆ**
1. In Finder, Select all (`โA`) ROM archives and FileโOpen (`โO`) to unarchive all.
2. When complete, the Finder should still have all the archives selected. Delete them all (`โโก`).
**If Renaming filesโฆ**
1. In Finder, Select all (`โA`) ROMs and Right-Click to `Rename itemsโฆ` *Example:* `Replace Text:` Find: `.bin` Replace withโฆ `.md`
**If Re-archivingโฆ**
1. In Keka, enable: โ๏ธArchive as single files
2. In Finder, Select all (`โA`) ROMs and drop them all onto Keka. Done.
#### Windows
**If Renaming filesโฆ**
1. Open the Command Prompt with `โR` and type `cmd`
2. Enter `cd` and the \[file-path] to a set of ROMs. \[file-path]: right-click the folder and select "Properties" and apply via copy/paste.
3. *Example:* `rename *.bin *.md`
## **โ ๏ธ Known Issues**
* Folders within an archive will result in crash. Archive loose files *only.*
{% hint style="info" %}
๐ฏ If you are still stuck ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# Customizing ROMs
Rename games, replace cover art, and edit game metadata
Provenance lets you personalize your game library. You can replace cover art, rename games, and edit detailed game metadata โ all from within the app.
**Customizable fields:** Cover Art, Title, Description, Genre, Publisher, Release Date, Region, Play History
{% hint style="warning" %}
Please refer to the [Known Issues](#known-issues) regarding customizing ROMs before posting a new one.
{% endhint %}
***
## Replacing Cover Art
{% tabs %}
{% tab title="Paste from Clipboard (iOS)" %}
The quickest way to replace a single game's artwork:
1. **Find an image** in Safari, Photos, Files, or any app
2. **Tap and hold** the image โ **Copy**
3. Open **Provenance** โ **long-press** the game you want to update
4. Select **Paste Custom Artwork**
5. The cover art updates immediately
{% endtab %}
{% tab title="Upload via Web Server" %}
Best for **bulk replacement** and **tvOS** (which doesn't support pasting).
1. Start the Web Server in Provenance:
* Tap the **+** button in the Game Library, or
* Settings โ **Import/Export**
2. On your computer, open `http://[device-ip]` in a browser
3. Open the **Imports** folder
4. Upload your image files (`.png` or `.jpg`)
5. Provenance matches images to ROMs by filename
**WebDAV alternative:**
1. Connect to `http://[device-ip]:81` via Finder (Mac) or a WebDAV client
2. Drop images into the **Imports** folder
{% endtab %}
{% tab title="Mass Replacement" %}
Replace artwork for your entire library at once:
1. On your computer, gather all cover art files in **one folder**
2. Name each image to match its ROM filename (see [Formatting](#formatting) below)
3. Upload all images to the **Imports** folder via Web Server or WebDAV
4. Provenance auto-matches images to games
{% hint style="info" %}
Mass replacement via upload is the recommended method for large libraries. Pasting works one game at a time.
{% endhint %}
{% endtab %}
{% endtabs %}
### Formatting
For cover art to auto-match, image filenames must correspond to ROM filenames:
**ROM file:**
```
Super Mario World.sfc
```
**Matching cover art:**
```
Super Mario World.png
```
**Requirements:**
* Image format must be `.png` or `.jpg`
* Filename (minus extension) must match the ROM filename exactly
* Images without a matching ROM will remain in the directory until matched or manually deleted
***
## Renaming Games
{% tabs %}
{% tab title="iOS" %}
1. **Long-press** the game in your library
2. Select **Rename**
3. Type the new name โ tap **Done**
{% endtab %}
{% tab title="tvOS" %}
1. **Select** the game and **press and hold** the Remote or Controller action button
2. Select **Rename**
3. Type the new name โ select **Done**
{% endtab %}
{% tab title="Via Game Info (iOS)" %}
1. **Long-press** the game โ select **Game Info**
2. **Long-press** the Title field
3. Edit the title โ tap **Done**
{% endtab %}
{% endtabs %}
***
## Editing Game Info
Edit detailed metadata for any game (iOS only):
1. **Long-press** a game in your library
2. Select **Game Info** (or 3D Touch and swipe up)
3. **Long-press** any editable field:
* Title
* Description
* Genre
* Publisher
* Release Date
* Region
4. Type, paste, or reset the field โ tap **Done**
{% hint style="info" %}
**Play History** (play count, time spent) can be **reset** but not manually edited.
{% endhint %}
***
## Known Issues
Cover art lost on "Refresh Library"
Custom cover art [is not retained](https://github.com/Provenance-Emu/Provenance/issues/730) when using the Refresh Library option in Settings. If you use custom artwork, keep backups of your image files so you can re-upload them via the Web Server after a refresh.
Cover art doesn't appear after uploading
* Upload **ROMs first**, then cover art โ uploading art before its matching ROM may not match immediately
* Uploading ROMs + cover art in a single archive may delay matching
* **Fix:** Force quit Provenance and relaunch to trigger re-matching
Custom game names reset on Refresh Library
Custom names are [not currently preserved](https://github.com/Provenance-Emu/Provenance/issues/514) during Refresh Library. Avoid refreshing if you've renamed many games.
Files with extra dots in filename cause a crash
Filenames with multiple `.` characters (e.g., `Game.v2.1.zip`) can cause issues. Rename the file to use only one dot before the extension (e.g., `Game v2-1.zip`).
Metadata not auto-matching for some ROMs
ROMs that fail checksum matching (translations, hacks, homebrew) won't auto-populate metadata. You can manually edit game info from the Game Info view.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Advanced ROM Management
Advanced techniques for managing large ROM libraries
This guide covers power-user workflows for managing 100+ games, multi-disc collections, custom metadata, backups, and optimization strategies for large libraries.
**For basic ROM importing**, see [Importing ROMs](/using-provenance/importing-roms) | **For file formats**, see [Formatting ROMs](/using-provenance/roms/formatting-roms)
***
## Table of Contents
* [Managing Large Libraries](#managing-large-libraries)
* [Multi-Disc Games](#multi-disc-games-advanced)
* [Metadata & Artwork](#metadata--artwork-optimization)
* [iCloud Sync Strategies](#icloud-sync-for-large-collections)
* [Backup & Migration](#backup--migration)
* [ROM Hacks & Patches](#rom-hacks--patches)
* [Performance Optimization](#performance-optimization)
***
## Managing Large Libraries
### Organizational Strategies
**Recommended structure for 1000+ ROMs:**
```
ROMs/
โโโ NES/ (250 games)
โโโ SNES/ (300 games)
โโโ GBA/ (200 games)
โโโ PlayStation/ (150 games)
โ โโโ Multi-Disc/ (Final Fantasy, Metal Gear Solid)
โ โโโ Single-Disc/ (Crash, Spyro)
โโโ N64/ (100 games)
```
**Benefits:**
* โก Faster library loading (Provenance indexes by system)
* ๐ Easier to find specific games
* โ๏ธ Better iCloud sync organization
* ๐ Clearer storage usage tracking
### Naming Conventions
**Use consistent naming for automatic metadata matching:**
โ
**Good:** `Final Fantasy VII (USA).chd`\
โ
**Good:** `Super Mario World (USA) (Rev 1).smc`\
โ **Bad:** `ff7_disk1.bin`\
โ **Bad:** `mario[!].sfc`
**Best practices:**
* Include region codes: `(USA)`, `(Europe)`, `(Japan)`
* Use No-Intro or Redump naming standards
* Avoid special characters: `[`, `]`, `!`, `+`
* Be consistent with revision markers: `(Rev 1)`, `(v1.1)`
**Why this matters:**
* ๐จ Automatic artwork matching via OpenVGDB
* ๐ Accurate metadata (publisher, release date, genre)
* ๐ Better game database recognition
* ๐พ Proper multi-disc grouping
### Filtering & Searching
**Use Provenance's search features:**
1. **Library Search** - Tap magnifying glass
* Search by title, system, or genre
* Filters: Favorites, Recently Played, System
2. **Custom Collections** (Favorites)
* Long-press game โ "Add to Favorites"
* Quick access to frequently played games
3. **System-Specific Views**
* Browse by console for focused game selection
* Faster scrolling than mixed library view
**Pro tip:** Mark 10-20 favorite games for quick access - much faster than scrolling through 1000+ titles.
***
## Multi-Disc Games (Advanced)
### M3U Playlists
**What are M3U files?**\
Plain text files that group multi-disc games into a single library entry with disc-swapping support.
**Example: Final Fantasy VII**
Create `Final Fantasy VII (USA).m3u`:
```
Final Fantasy VII (USA) (Disc 1).chd
Final Fantasy VII (USA) (Disc 2).chd
Final Fantasy VII (USA) (Disc 3).chd
```
**How to create:**
1. Use a text editor (Notes, TextEdit, VS Code)
2. List each disc file (one per line)
3. Save as `.m3u` with the **same name** as disc 1
4. Import the M3U + all disc files into Provenance
**Supported systems:**
* โ
PlayStation (most common use case)
* โ
Sega CD
* โ
Saturn
* โ
PC Engine CD / TurboGrafx-CD
* โ
PC-FX
### CHD Format (Recommended)
**What is CHD?**\
Compressed Hunks of Data - a lossless compression format that reduces disc images by 40-70%.
**Benefits:**
* ๐พ **Massive space savings** (700MB BIN/CUE โ 300MB CHD)
* โก **Faster loading** (less data to read from storage)
* ๐ฆ **Single file** (no more .cue + .bin + .sub mess)
* โ
**Full compatibility** (PlayStation, Sega CD, Saturn, Dreamcast)
**Conversion:**
**Mac/Linux:**
```bash
# Install chdman (part of MAME tools)
brew install rom-tools
# Convert BIN/CUE to CHD
chdman createcd -i "game.cue" -o "game.chd"
# Batch convert all CUE files
for f in *.cue; do chdman createcd -i "$f" -o "${f%.cue}.chd"; done
```
**Windows:**
```powershell
# Download chdman.exe from MAME website
# Run in command prompt
chdman.exe createcd -i "game.cue" -o "game.chd"
```
**After conversion:**
1. Verify CHD loads in Provenance
2. Delete original BIN/CUE files
3. Update M3U playlists to reference `.chd` files
**Storage comparison (real examples):**
| Game | BIN/CUE | CHD | Savings |
| --------------------------- | ------- | ------ | ------- |
| Final Fantasy VII (3 discs) | 2.1 GB | 1.2 GB | 43% |
| Metal Gear Solid | 702 MB | 287 MB | 59% |
| Resident Evil 2 (2 discs) | 1.4 GB | 623 MB | 55% |
### Disc Swapping During Gameplay
**How to swap discs:**
1. **Open pause menu** (pause button)
2. **Tap "Change Disc"** (only appears for multi-disc games)
3. **Select the next disc** from the list
4. **Resume gameplay**
**When to swap:**
* Game prompts "Insert Disc 2"
* After major story progression (e.g., end of disc 1)
* For side content on bonus discs
**Pro tip:** Create save states **before** disc swap prompts - makes retrying easier if swap fails.
***
## Metadata & Artwork Optimization
### Automatic Metadata Matching
Provenance uses **OpenVGDB** to automatically fetch:
* ๐ฎ Game title (cleaned up)
* ๐จ Box art and screenshots
* ๐
Release date
* ๐ข Publisher/Developer
* ๐ญ Genre
**To trigger re-matching:**
1. Long-press game in library
2. Tap "More Info"
3. Tap "Refresh Metadata"
**Improving match accuracy:**
* Use No-Intro or Redump naming standards
* Include region codes: `(USA)`, `(Japan)`
* Remove ROM hack tags: `[T+Eng]`, `[h1]`
* Verify ROM hash matches database (use `md5sum`)
### Custom Artwork
**Add your own box art/screenshots:**
1. Long-press game โ **"Edit"**
2. Tap **"Artwork"** thumbnail
3. Choose source:
* ๐ท **Take Photo** - Capture physical box art
* ๐ผ๏ธ **Photo Library** - Use downloaded images
* ๐ **Files** - Import from iCloud/Downloads
4. Crop and adjust
5. **Save**
**Recommended artwork specs:**
* **Format:** JPEG or PNG
* **Dimensions:** 512x512 minimum (1024x1024 ideal)
* **Aspect ratio:** Match original box art (varies by system)
* **File size:** Under 500KB for faster loading
**Where to find high-quality artwork:**
* [MobyGames](https://www.mobygames.com) - Comprehensive database
* [TheGamesDB](https://thegamesdb.net) - Community-curated
* [LaunchBox Database](https://gamesdb.launchbox-app.com) - High-res scans
* Physical box scans (your own collection)
### Metadata Editing
**Edit game information manually:**
1. Long-press game โ **"Edit"**
2. Modify fields:
* **Title** - Display name in library
* **Publisher** - Company that released the game
* **Developer** - Studio that created the game
* **Release Date** - Original launch date
* **Genre** - Category (RPG, Action, Platformer)
* **Description** - Game summary
**Use cases:**
* ๐ฎ ROM hacks: `Super Mario World โ Kaizo Mario World`
* ๐ Fan translations: Add `(English Patched)` to title
* ๐ง Homebrew: Set proper developer credit
* ๐ Custom collections: Genre organization
***
## iCloud Sync for Large Collections
### Enable iCloud Sync (Provenance Plus)
**Requirements:**
* ๐ฑ Provenance Plus subscription
* โ๏ธ Available iCloud storage (check Settings โ \[Your Name] โ iCloud)
* ๐ถ WiFi connection (recommended for large libraries)
**Setup:**
1. Provenance โ **Settings** โ **iCloud Sync**
2. Toggle **ON**
3. Wait for initial upload (may take hours for 50+ GB)
4. Verify sync status: **Settings โ iCloud Sync โ Status**
### What Syncs?
โ
**Synced:**
* ๐ฎ ROM files
* ๐พ Save states
* ๐ฏ Battery saves
* ๐จ Custom artwork
* ๐ Metadata edits
* ๐ BIOS files
โ **Not synced:**
* โ๏ธ App settings
* ๐ฎ Controller mappings
### Optimizing for Large Libraries
**Best practices:**
1. **Use CHD format** - 40-70% smaller files = faster sync
2. **Delete duplicates** - Remove (Europe) ROMs if you have (USA)
3. **Clean up old saves** - Delete unused save states
4. **Schedule uploads** - Enable sync overnight when on WiFi
5. **Monitor storage** - Check iCloud storage usage monthly
**Storage tiers:**
* 50 GB: $0.99/month - Fits \~200 games (CHD format)
* 200 GB: $2.99/month - Fits \~800 games
* 2 TB: $9.99/month - Fits entire collection + backups
**Sync speed expectations:**
| Library Size | Initial Upload | Incremental Sync |
| ------------------- | -------------- | ---------------- |
| 10 GB (50 games) | 1-2 hours | 5-10 minutes |
| 50 GB (250 games) | 6-12 hours | 15-30 minutes |
| 200 GB (1000 games) | 24-48 hours | 30-60 minutes |
**Pro tip:** Import ROMs in batches of 20-30 games, let iCloud sync, then import next batch. Avoids overwhelming the sync queue.
### Troubleshooting iCloud Issues
**Sync stuck or slow:**
1. Force quit Provenance
2. Disable iCloud Sync
3. Re-enable iCloud Sync
4. Restart device
5. Wait 10-15 minutes for queue to process
**"Not enough iCloud storage":**
1. Check usage: Settings โ \[Your Name] โ iCloud
2. Delete old device backups
3. Upgrade iCloud plan
4. Or disable iCloud sync for less-played systems
***
## Backup & Migration
### Backing Up Your Library
**Method 1: Mac/PC File Sharing (Best)**
1. Connect iOS device to Mac via USB
2. Open **Finder** โ Select device
3. **Files** tab โ **Provenance**
4. Drag **entire folder** to Mac desktop
5. Store backup on external drive or cloud storage
**Backup includes:**
* All ROMs
* Save states
* Battery saves
* BIOS files
* Custom artwork
* Metadata database
**Method 2: iCloud Drive (If Sync Enabled)**
Your data is already backed up to iCloud. To export:
1. Mac **Finder** โ **iCloud Drive** โ **Provenance**
2. Copy folder to external drive
3. Store as secondary backup
**Method 3: File Sharing via Finder (or iTunes on older Macs)**
On macOS Catalina and later (iTunes was removed in 2019):
1. Connect iOS device to Mac via USB
2. Open **Finder** โ Select device in sidebar
3. **Files** tab โ **Provenance**
4. Save files to Mac
On older Macs with iTunes (macOS Mojave and earlier):
1. iTunes โ Device โ **File Sharing**
2. Select **Provenance**
3. Save files to Mac
### Migrating to a New Device
**Transfer everything from old iPhone/iPad to new one:**
**Option A: iCloud Sync (Easiest)**
1. Old device: Enable iCloud Sync, wait for upload
2. New device: Install Provenance, log in with same Apple ID
3. Enable iCloud Sync โ Wait for download
4. โ
Done - library appears automatically
**Option B: Mac Backup/Restore**
1. Backup old device via Finder (see above)
2. Install Provenance on new device
3. Connect new device to Mac
4. Finder โ New device โ Files โ Provenance
5. Drag backup folder into Provenance container
6. Restart Provenance on new device
**Option C: AirDrop (Small Libraries Only)**
1. Export ROMs from old device (Share โ AirDrop)
2. On new device, accept files
3. Open in Provenance
4. Repeat for all games
***
## ROM Hacks & Patches
### Applying IPS/BPS Patches
**What are ROM patches?**\
Modification files that transform original ROMs into:
* ๐ Fan translations (Japanese โ English)
* ๐ฎ ROM hacks (Kaizo Mario, Pokรฉmon randomizers)
* ๐ Bug fixes (community patches)
**How to patch:**
**Mac/Linux:**
```bash
# Install Flips patcher
brew install flips
# Apply IPS patch
flips --apply "patch.ips" "original-rom.smc" "patched-rom.smc"
# Apply BPS patch (more reliable)
flips --apply "patch.bps" "original-rom.gba" "patched-rom.gba"
```
**Windows:**
* Download **Floating IPS (Flips)** or **Lunar IPS**
* Open patcher โ Select original ROM โ Select patch file โ Apply
* Save output with descriptive name
**After patching:**
1. Import patched ROM into Provenance
2. Edit metadata to reflect patch name
3. Add custom artwork if desired
**Popular ROM hacks:**
* **Super Mario World** โ Kaizo Mario World (extreme difficulty)
* **Pokรฉmon FireRed** โ Pokรฉmon Unbound (new story)
* **Zelda: A Link to the Past** โ Parallel Worlds (new dungeons)
* **Final Fantasy VI** โ Brave New World (rebalanced)
***
## Performance Optimization
### Large Library Loading Speed
**If your library is slow to load:**
1. โ
**Delete unused ROMs** - Remove games you never play
2. โ
**Optimize artwork** - Compress images under 500KB
3. โ
**Clear cache** - Settings โ Advanced โ Clear Cache
4. โ
**Restart device** - Frees up memory
5. โ
**Disable iCloud sync temporarily** - Re-enable after cleanup
### Database Maintenance
**Rebuild game database (if corrupted):**
โ ๏ธ **Warning:** Only do this if library loading is broken
1. Force quit Provenance
2. Delete database file via Finder (Mac):
* Connect device
* Finder โ Device โ Files โ Provenance
* Delete `Provenance.realm` file
3. Restart Provenance
4. Library will rebuild (may take 10-30 minutes)
**Symptoms of corrupted database:**
* Games appear duplicated
* Metadata missing
* Artwork not loading
* Crashes on library screen
### Storage Management
**Find biggest files:**
1. Settings โ General โ iPhone Storage โ Provenance
2. See total usage breakdown
3. Identify largest ROMs
**Systems ranked by typical storage:**
| System | Avg per Game | 100 Games |
| ----------------- | ------------ | --------- |
| NES | 200 KB | 20 MB |
| SNES | 2 MB | 200 MB |
| GBA | 8 MB | 800 MB |
| N64 | 12 MB | 1.2 GB |
| PlayStation (CHD) | 300 MB | 30 GB |
| Dreamcast (CHD) | 600 MB | 60 GB |
| PSP (ISO) | 1.2 GB | 120 GB |
**Space-saving tips:**
* ๐พ Convert to CHD (PlayStation, Dreamcast, Saturn)
* ๐๏ธ Delete (Europe) duplicates if you have (USA)
* ๐ฆ Use 7z compression for cartridge ROMs
* ๐ฎ Keep only games you actively play
***
## Quick Reference
### Essential Tools
**Mac:**
* **Flips** - ROM patcher (IPS/BPS)
* **chdman** - CHD converter
* **The Unarchiver** - Extract 7z, RAR
**Windows:**
* **Floating IPS** - ROM patcher
* **CHDman** - CHD converter
* **7-Zip** - Archive extraction
**Cross-platform:**
* **EmulationStation** - Test ROMs before importing
* **RomCenter** - ROM collection manager
* **ClrMAME Pro** - ROM verification
### File Format Cheat Sheet
| Format | System | Use Case |
| ------------- | ---------------------- | ----------------------------------- |
| `.chd` | PS1, Dreamcast, Saturn | **Best** - Compressed disc images |
| `.m3u` | PS1, Sega CD | **Required** - Multi-disc grouping |
| `.7z` | Cartridge ROMs | Compression (extract before import) |
| `.cue + .bin` | PS1, Sega CD | Legacy - Convert to CHD |
| `.iso` | PlayStation, PSP | Uncompressed - Convert to CHD |
### Common Issues & Solutions
| Problem | Solution |
| ------------------------------- | --------------------------------------------------------------- |
| Multi-disc game shows 3 entries | Create M3U playlist |
| ROMs won't import | Check [Formatting ROMs](/using-provenance/roms/formatting-roms) |
| Metadata incorrect | Use proper naming convention |
| Library slow to load | Delete unused games, optimize artwork |
| iCloud sync stuck | Disable/re-enable sync |
| Duplicate games | Delete extras, rebuild database |
***
## Next Steps
* ๐ [**Importing ROMs**](/using-provenance/importing-roms) - Basic import methods
* ๐ฆ [**Formatting ROMs**](/using-provenance/roms/formatting-roms) - Supported file formats
* ๐จ [**Customizing ROMs**](/using-provenance/roms/customizing-roms) - Artwork and metadata basics
* ๐ง [**Applying Mods & Patches**](/using-provenance/roms/mods) - ROM modification guide
* โ๏ธ [**Troubleshooting**](/help-and-community/troubleshooting) - Fix common issues
***
**Managing a massive collection?** Join the [Provenance Discord](https://discord.gg/provenance) to share tips with other power users! ๐ฎ
*Advanced features like iCloud sync require Provenance Plus. Multi-disc support and CHD format available in all versions.*
# Applying Mods / Patches
Apply ROM hacks, patches, translations, and mods to your games โ IPS/BPS patching, SBI files for PSX, and high-resolution N64 texture packs
**#๏ธโฃ** [**Patching**](#patching) \*\*\*\*ยท *applying translations, hacks, etcโฆ*\
โ๏ธ [**High Resolution Textures**](#high-resolution-textures-n-64) (N64)
## Patching
A great resource for ROM hacks and translations can be found at [romhacking.net](https://www.romhacking.net). Note that usually the target ROM version needed is specified with MD5, CRC32 or SHA-1 checksum for the exact ROM to patchโmake sure it matches your target file.
To apply the patches you will need a patcher for the various formats:
* Mac:
* [MultiPatch](http://projects.sappharad.com/tools/multipatch.html): `.ips`, `.bps`, `.ups`, `.ppf`, `.bsdiff`, `.bdf`, `.xdelta`, `.dat`
* Windows:
* [Floating IPS](https://github.com/Alcaro/Flips): `.ips`, `.bps`
* [XDelta](https://sourceforge.net/projects/xdelta3-gui): `.xdelta`
#### Hash Checksums
To obtain the hash checksum of a ROM, you can use the following commands in Terminalโฆ
```
md5 [path to file or drag and drop file here]
```
```
crc32 [path to file or drag and drop file here]
```
```
shasum [path to file or drag and drop file here]
```
{% hint style="info" %}
Although it's best to use the exact ROM required as listedโฆ*sometimes* a patch will still work without an exact match, but cannot be guaranteed to work 100% even if it seems to have successfully patched. This might be necessary as there are some exact ROMs that are nearly impossible to obtain, but *do this as a last resort and at your own risk.*
{% endhint %}
## **SBI Files (PSX)**
SBI Files are archives that contains the protection information that those PAL games got and that are needed to run those protected games in emulators.
SBI Files are not copyrighted, as they're not the ROM itself.
### Obtaining
These are supplied by a 3rd party, use at your own risk.
### Usage
Simply copy the obtained .SBI file and place it in the same directory as the game you wish to patch, with matching filename.
```sh
My Game.bin
My Game.cue
My Game.sbi
```
## **High Resolution Textures (N64)**
The option is enabled by default since if it doesn't find textures for the current ROM nothing happens. To use hi-res texture packs you need to copy them to the directory `com.provenance.n64/hires_texture/{ROM NAME}` The ROM NAME isn't the file name, but instead the identifier for the ROM in the header of the ROM file. If you don't know what it is, you can view the console output at load where it says something like, `Mupen (3): Name: SUPER MARIO 64` So in this example, if I wanted to load hi res textures for Mario 64 I would put them in, `com.provenance.n64/hires_texture/SUPER MARIO 64`โ
Hi-Res packs come in folders with sub-folders. Just copy all the folders in the path as described above, mupen will find the right textures in sub folders.โ
Texture packs can be downloaded at [textures.emulation64.com](http://textures.emulation64.com/index.php?id=downloads)โ
For some reason this site splits larger texture packs into multiple zips. Just download all the zips and copy all their contents into the directory for your ROM as described above.โ
Hi-Res texture pack don't seem to noticeably degrade performance (on original ATV4 testing). For me Mario 64 runs at 100% with dips here and there, and with hi-res texture packs applied, frame rates were the same as far as I could tell but visually everything was crisper. It seems that texture handling is not the bottle neck of performance for glupen64plus on iOS.โ
โ
{% hint style="info" %}
๐ฏ If you are still stuck ask for [help](https://discord.gg/provenance) on our Discord.
{% endhint %}
# In-Game Menu
Everything you can do from the pause menu while playing a game
The **pause menu** is your control center during gameplay. Access save states, fast forward, cheats, screen filters, controller settings, and more โ all without leaving your game.
***
## Opening the Pause Menu
| Method | How |
| ----------------------- | ------------------------------------------------------------- |
| **On-screen** | Tap the **Menu** / **Pause** button on the controller overlay |
| **Physical controller** | Press the **Menu** / **Options** button |
| **Keyboard** | Press `~` (tilde) |
***
## Menu Options
### Save States
Create, load, and manage save state snapshots:
* **Save State** โ Freeze the game at this exact moment
* **Load State** โ Resume from a previously saved snapshot
* **Auto Save** โ Provenance automatically creates a save state when you leave a game or background the app
* **Overwrite / Delete** โ Manage existing states (each shows a screenshot preview)
{% hint style="info" %}
Save states are tied to specific emulator cores. If you switch cores, old save states won't work. Use **in-game saves** (battery saves) for long-term progress. See [Game Saves](/using-provenance/saves) for details.
{% endhint %}
### Fast Forward
Speed up gameplay โ useful for grinding, slow cutscenes, or text-heavy RPGs:
* **Toggle Fast Forward** โ Increases emulation speed (typically 2-4x, varies by core)
* Fast forward stays active until you toggle it off or exit the game
See [Fast Forward](/using-provenance/fast-forward) for full details.
### Screen Filters
Change visual filters without leaving your game:
* Switch between CRT, LCD, smoothing, and other shader effects
* Preview how each filter looks in real-time
* Per-game filter settings override global defaults
See [Screen Filters & Shaders](/using-provenance/shaders-and-filters) for all available filters.
### Cheats
Enable or disable cheat codes mid-game:
* Toggle individual cheats on/off
* Access the RetroArch cheats interface (RetroArch-based cores)
* Changes take effect immediately
See [Cheats](/using-provenance/cheats) for setup instructions and code formats.
### Controller Settings
Adjust controller configuration during gameplay:
* **Player assignment** โ Reassign controllers to different player slots
* **Controller skin** โ Switch to a different on-screen skin
* View current controller mapping
### RetroArch Settings
For games running on **RetroArch-based cores**, access the full RetroArch settings interface:
* Advanced shader configuration
* Core-specific options (resolution scaling, audio settings)
* RetroAchievements settings
* Netplay / online multiplayer configuration
* Save/load RetroArch core overrides
{% hint style="info" %}
RetroArch settings are only available for RetroArch-based cores. Native cores (emuThreeDS, Dolphin) have their own configuration systems.
{% endhint %}
### Screenshot
Capture a screenshot of the current game frame.
### Reset
Restart the game from the beginning (simulates a console power cycle). Your save states and battery saves are preserved โ this only resets the current play session.
### Quit to Library
Return to the game library. If auto-save is enabled, a save state is created automatically before quitting.
***
## Quick Actions
Some actions can also be triggered without opening the full pause menu:
| Action | Method |
| ----------------------- | -------------------------------- |
| **Quick Save** | Configurable controller shortcut |
| **Quick Load** | Configurable controller shortcut |
| **Fast Forward Toggle** | Configurable controller shortcut |
| **Screenshot** | Configurable controller shortcut |
Check Settings โ Controllers to configure quick action shortcuts for your physical controller.
***
## See Also
* [Fast Forward](/using-provenance/fast-forward) โ Speed up gameplay
* [Game Saves](/using-provenance/saves) โ Save states vs battery saves
* [Screen Filters & Shaders](/using-provenance/shaders-and-filters) โ Visual filter options
* [Cheats](/using-provenance/cheats) โ Cheat code support
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ Controller setup
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Quick Continue
The Quick Continue UI โ pick your core, preview saves, and jump right back in
When you launch a game, Provenance's **Quick Continue** interface helps you get back into your game as fast as possible. It shows your save states with screenshot previews, lets you pick between emulator cores, and handles cloud sync automatically.
***
## How It Works
### Single Core Games
For games with only one compatible core:
1. **Tap a game** in your library
2. If you have save states, the **Quick Continue screen** appears showing:
* Save state thumbnails with screenshots
* Timestamps for each save
* Cloud sync status indicators
3. **Tap a save state** to resume from that point
4. Or tap **New Game** to start fresh
### Multi-Core Games
For games compatible with multiple emulator cores (e.g., a SNES game can run on bsnes or Snes9x):
1. **Tap a game** in your library
2. The **Core Picker** appears listing each compatible core:
* Core name and version
* Number of save states for that game in each core
3. **Select a core**
4. The Quick Continue screen shows save states for the selected core
5. Choose a save state or start a new game
{% hint style="info" %}
Save states are **core-specific** โ a save made with one core can only be loaded with the same core. Battery saves (in-game saves) work across cores.
{% endhint %}
***
## Save State Previews
Each save state in the Quick Continue screen shows:
| Element | Description |
| -------------- | -------------------------------------------------------------- |
| **Screenshot** | A preview image captured at the moment the state was saved |
| **Timestamp** | When the save was created (date and time) |
| **Cloud icon** | Shows if the save needs to sync from iCloud (Plus subscribers) |
| **Core label** | Which emulator core the save was made with |
***
## Cloud Sync Integration
For **Provenance Plus** subscribers (and all Apple TV users), Quick Continue integrates with iCloud sync:
### Sync Status Indicators
| Icon | Meaning |
| -------------------- | ---------------------------------------- |
| **Cloud with arrow** | Save state needs to download from iCloud |
| **Checkmark** | Save is available locally, ready to load |
| **Syncing** | Currently downloading or uploading |
### Auto-Sync on Launch
When you tap a game, Quick Continue automatically:
1. **Checks for missing saves** โ Downloads any save states that exist in iCloud but not on this device
2. **Checks for missing BIOS** โ If the system requires BIOS files and they're in iCloud, downloads them
3. **Checks for missing ROM** โ If the ROM was deleted by the OS (common on tvOS), re-downloads it from iCloud
{% hint style="info" %}
**Why this matters on Apple TV:** tvOS can silently delete app data to reclaim storage space. Quick Continue's auto-sync ensures you never lose progress โ your saves, BIOS files, and even ROMs are restored from iCloud on demand.
{% endhint %}
***
## Changing the Default Core
If you prefer a specific core for a system or game:
### Per-Game Core
1. **Long-press** a game in your library
2. Select **Game Settings**
3. Under **Emulator Core**, choose your preferred core
4. This game will always launch with the selected core
### Per-System Core
1. Open **Settings**
2. Go to **Cores** โ select a system
3. Choose the default core for all games on that system
4. Individual per-game settings override this
### Resetting Core Settings
To reset per-game or per-system core overrides back to defaults:
1. Open **Settings** โ **Cores**
2. Select the system or game
3. Choose **Reset to Default**
***
## Tips
* **Use Quick Continue for convenience** โ Jump right back into your last session with one tap
* **Multiple cores = more options** โ Try different cores for the same game to compare speed, accuracy, and features
* **Keep iCloud Sync enabled** โ Ensures your saves are always available, even if your device clears storage
* **Battery saves transfer between cores** โ If you want to switch cores, use in-game saves (not save states) as your transfer mechanism
***
## See Also
* [Game Saves](/using-provenance/saves) โ Battery saves vs save states
* [Provenance Plus](/platforms-and-performance/provenance-plus) โ iCloud sync details
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ Choosing the right core for your device
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Fast Forward
Speed up gameplay for grinding, cutscenes, and text-heavy sections
Fast forward lets you speed up emulation โ perfect for RPG grinding, slow dialogue, unskippable cutscenes, or just getting through menus quickly.
***
## How to Use
### Toggle from Pause Menu
1. Open the **pause menu** during gameplay (Menu button / `~` key)
2. Select **Fast Forward**
3. The game runs at increased speed
4. Open the pause menu again and toggle off to return to normal speed
### Controller Shortcut
You can assign a fast forward toggle to a physical controller button:
1. Go to Settings โ **Controllers**
2. Set a **Fast Forward** shortcut button
3. Press the assigned button during gameplay to toggle fast forward on/off without opening the pause menu
***
## Speed
Fast forward speed varies by core and device performance:
| Factor | Impact |
| ------------------- | ------------------------------------------------- |
| **Emulator core** | Each core has its own maximum fast forward speed |
| **Device hardware** | Newer devices can sustain higher speeds |
| **Game complexity** | Simple 2D games fast forward faster than 3D games |
| **Screen filters** | Disabling filters increases maximum speed |
**Typical speeds:**
* **Simple systems** (NES, Game Boy, GBA): 4-8x or higher
* **Medium systems** (SNES, Genesis, PS1): 2-4x
* **Complex systems** (N64, PSP, Dreamcast): 1.5-3x
* **Heavy systems** (3DS, GameCube): Limited speed increase
{% hint style="info" %}
Fast forward runs the emulator as fast as your device can handle โ there's no configurable speed cap. The actual speed depends on how much headroom your device has beyond real-time emulation.
{% endhint %}
***
## Core Support
Most cores support fast forward:
| Core Type | Fast Forward | Notes |
| -------------------------- | ------------ | --------------------- |
| **RetroArch cores** | Yes | Most systems |
| **PPSSPP** (PSP) | Yes | |
| **emuThreeDS** (3DS) | Limited | Performance-dependent |
| **Dolphin** (GameCube/Wii) | Limited | Performance-dependent |
| **Native cores** | Varies | Check per-core |
***
## Tips
* **RPG grinding** โ Fast forward through random battles and level-up animations
* **Visual novels / text games** โ Speed through already-read dialogue
* **Unskippable cutscenes** โ Get past long intros and transitions
* **Save before fast forwarding** โ Create a save state first in case you need to go back
* **Disable filters for max speed** โ Turning off CRT/LCD filters frees up GPU for faster emulation
{% hint style="warning" %}
**RetroAchievements Hardcore Mode** disables fast forward. If you're achievement hunting in Hardcore, you'll need to play at normal speed. Switch to Softcore mode to use fast forward while still earning achievements.
{% endhint %}
***
## Rewind
Provenance does **not** currently support rewind (frame-by-frame backwards playback). Use **save states** as an alternative โ save before difficult sections and reload if needed.
***
## See Also
* [In-Game Menu](/using-provenance/in-game-menu) โ All pause menu features
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ Get better performance for higher fast forward speeds
* [RetroAchievements](/using-provenance/retroachievements) โ Hardcore mode disables fast forward
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Controllers & Controls
Connect and configure controllers for Provenance
Provenance supports a wide range of physical controllers on iPhone, iPad, Apple TV, and Mac โ from certified MFi gamepads to Bluetooth classics. This section covers everything you need to connect a controller and understand the button mappings for each system.
## ๐ฎ Supported Controllers
[**Supported Controllers**](/using-provenance/controllers-and-controls/controllers) โ Full compatibility guide covering:
* **MFi controllers** โ Apple-certified gamepads (recommended for best compatibility)
* **Steam Controller** โ Valve's Bluetooth controller used as a pseudo-MFi Extended2+ gamepad
* **iCade controllers** โ Legacy Bluetooth controllers using key mappings
* Controller form factors: form-fitting (GameVice, Kishi) vs. standalone (SteelSeries, Rotor Riot)
* Compatibility ratings for iPhone, iPad, and Apple TV
## โญ Controller Reviews
[**Controller Reviews**](/using-provenance/controllers-and-controls/controller-reviews) โ Individual reviews with pros, cons, and recommendations to help you choose the right controller.
## ๐บ Control Maps
[**Control Maps**](/using-provenance/controllers-and-controls/control-maps) โ Button mappings for every supported system, organized by MFi gamepad profile (Micro, Standard, Extended, Extended2).
***
## Quick Tips
* **MFi controllers** offer the best experience and can navigate tvOS system menus.
* **iCade controllers** cannot be used simultaneously with MFi controllers.
* For systems requiring more buttons than your controller has (PSX, N64), Provenance provides **MFi+ combos** and on-screen UI buttons to cover missing inputs.
* On Apple TV, a **standalone Bluetooth controller** (not form-fitting) is recommended.
* See [Skins](/using-provenance/skins-guide) to customize the on-screen overlay for touch controls.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Supported Controllers
Supported controllers and gamepads for Provenance โ PlayStation, Xbox, MFi, 8BitDo, Steam, and iCade with compatibility ratings and setup guides
* **๐ฒ** [**Controller Types**](#controller-types)
* [MFi](#mfi-controllers)
* [Steam](#steam-controller-pseudo-mfi)
* [iCade](#icade-controllers)
* **๐น** [**Controller Forms**](#controller-forms)
* **๐ฎ** [**Controllers**](#profiles) ยท Supported, Classified & Rated
* **๐** [**Controls**](#controls)
## Controller Types
### MFi Controllers
Certified MFi Controllers are the standard complying to Apple's Gamepad profile(s). They are the easiest and most compatible controllers to use not just for Provenance, but iOS and tvOS in general.
#### **MFi Profiles**
MFi controllers exist in a few different formats made distinct as profiles in Apple's SDK.
| Profile | โโ | โ | A | B | X | Y | -- | == | โโ | โขโข | โ๏ธ | โถ๏ธ |
| ----------- | -- | - | - | - | - | - | -- | -- | -- | -- | -- | -- |
| Micro | โ | โ | โ | โ | | | | | | | | |
| Standard | โ | โ | โ | โ | โ | โ | โ | | | | | |
| Extended | โ | โ | โ | โ | โ | โ | โ | โ | โ | | | |
| Extended2\* | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | | |
{% hint style="info" %}
Technically, there is only one Extended profile in the SDK, but we make the previous generation (which excluded L3 and R3) distinct within Provenance and refer to the updated profile as Extended2.
{% endhint %}
Due to Apple's shortsightedness, all MFi controllers lack certain buttons to be equivalent to any modern gaming standard (PS4, Xbox, etcโฆ) made accessible in Provenance in various ways:
1. For systems without trigger buttons:
* L2: Select, R2: Start
2. For PSX, N64, and onโฆ
* MFi+ Combos
* UI Buttons within Pause Menu
3. Missing Buttons Always On-Screen (iOS only) *Beta, not all systems supported*
### Steam Controller (pseudo MFi)
Valve's Steam Controller uses its own protocol different from MFi, and not a virtual keyboard hack like iCade types, but we can conform it to the MFi Extended Gamepad protocol and still obtain input from the extra buttons as a sort of MFi hybrid, however limited to use only within the app (cannot navigate the system such as MFi can do with tvOS).
{% hint style="info" %}
Currently, Steam Controller will not reconnect automatically, requiring app relaunch.
{% endhint %}
| Profile | โโ | โ | A | B | X | Y | -- | == | โโ | โขโข | โ๏ธ | โถ๏ธ |
| ---------- | -- | - | - | - | - | - | -- | -- | -- | -- | -- | -- |
| Extended2+ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ |
**Trackpad Modes:**
* Button Mode (default): like d-pad, c-buttons
* Touch Mode: like touch analog
**Stick Modes:**
* Analog Mode (default)
* D-Pad Mode
```
L-Pad Toggle = โ L-Pad Click + โ๏ธ (Back)
R-Pad Toggle = โ R-Pad Click + โถ๏ธ (Forward)
Stick Toggle = โ Stick Click + โ๏ธ (Back)
```
Currently, โ๏ธ (Back) / Select and โถ๏ธ (Forward) / Start are supported for PSX and N64 via MFi+.
{% hint style="info" %}
Requires [Steam Controller BLE firmware](https://support.steampowered.com/kb_article.php?ref=7728-QESJ-4420) via Steam Beta program.
{% endhint %}
### iCade Controllers
Before MFi, there were various controllers using non-standardized virtual keyboard hacks to get gamepad input. Because of this they are not as fluid or as granular as you can get from MFi or a Steam controller as they are using key mappings and not variable numerical data (as would be needed for thumbstick coordinates and trigger sensitivity, etcโฆ), however they tend to have more buttons available. Another drawback is that you cannot use two iCades simultaneously, as Apple only allows one 'keyboard' connected at a timeโฆ
{% hint style="warning" %}
iCade and MFi can **not** be used together simultaneously without conflict/bugs, currently.
{% endhint %}
{% hint style="info" %}
iCade controllers use key mappings rather than variable numerical data, so thumbstick coordinates and trigger sensitivity are not supported. See [Control Maps](/using-provenance/controllers-and-controls/control-maps) for available iCade button mappings.
{% endhint %}
## Controller Forms
### Form-fitting
Form fitting controllers attach to your devices, in either a PSP sort of way (GameVice) or with a clamp that mounts the device above the controller. Some are powered by the device, others self-powered via battery and connect over bluetooth. Great for iPhone. Decent for iPads. Generally useless for Apple TV, unless you have a bluetooth device with remove-able or collapse-able clamp.
### Standalone
Standalone controllers are familiar to that of Playstation or Xbox. Recommended for iPads, and the absolute for Apple TV.
## Controllers
### Profiles
**Key**: โ = Supported
| Profile | โโ | โ | A | B | X | Y | -- | == | โโ | โขโข | โ๏ธ | โถ๏ธ |
| ---------- | -- | - | - | - | - | - | -- | -- | -- | -- | -- | -- |
| Micro | โ | โ | โ | โ | | | | | | | | |
| Standard | โ | โ | โ | โ | โ | โ | โ | | | | | |
| Standard+ | โ | โ | โ | โ | โ | โ | โ | | | | โ | โ |
| Extended | โ | โ | โ | โ | โ | โ | โ | โ | โ | | | |
| Extended+ | โ | โ | โ | โ | โ | โ | โ | โ | โ | | โ | โ |
| Extended2 | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | | |
| Extended2+ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ |
### Controllers
**Key**: โ = Supported / Ideal | โ = Supported
| Controller | iPhone | iPad | aTV | Type | Profile | Rating |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- | --- | ----- | ---------- | ------ |
| [Razer Kishi Controller for iPhone](https://www.amazon.com/Razer-Kishi-Controller-iPhone-Passthrough-mac/dp/B08FFPKRYW) | โ | | | MFi | Extended2+ | โโโโโ |
| [GameVice: iPhone](https://www.amazon.com/Gamevice-Controller-Gamepad-iPhone-Certified-Compatible/dp/B077LZJ679/) Xส not supported | โ | | | MFi | Extended | โโโโโ |
| [GameVice: iPad Pro 12.9"](https://www.amazon.com/Gamevice-Controller-Gamepad-12-9-inch-Certified-Accessories/dp/B01MFCXJZD/) | | โ | | MFi | Extended | โโโโโ |
| [GameVice: iPad Mini](https://www.amazon.com/Controller-Gamepad-Gamevice-Certified-Accessories-Patented/dp/B01MR4VLJW/) | | โ | | MFi | Extended | โโโโโ |
| [Rotor Riot](https://www.amazon.com/Rotor-Riot-Certified-Controller-Compatible/dp/B07J1J7D6Z/) | โ | โ | โ | MFi | Extended2 | โโโโโ |
| [Steam Controller](https://www.amazon.com/Steam-Controller-SteamOS/dp/B016KBVBCS/) | โ | โ | โ | pMFi | Extended2+ | โโโโโ |
| [SteelSeries Nimbus](https://www.amazon.com/SteelSeries-Nimbus-Wireless-Gaming-Controller/dp/B01AZC3III/) + [clamp](https://www.amazon.com/TPFOON-Smartphone-Cellphone-Steelseries-Controller/dp/B07DLY5PB4/) | โ | โ | โ | MFi | Extended | โโโโโ |
| [SteelSeries Stratus XL: iOS](https://www.amazon.com/SteelSeries-Bluetooth-Wireless-Controller-69026/dp/B00QTSR5GO/) | โ | โ | โ | MFi | Extended | โโโโโ |
| [SteelSeries Stratus XL](https://www.amazon.com/SteelSeries-Stratus-Bluetooth-Wireless-Controller/dp/B015WKY3IM/)\* | โ | โ | โ | iCade | Extended+ | โโโโโ |
| [SteelSeries Stratus](https://www.amazon.com/SteelSeries-Stratus-Wireless-Gaming-Controller/dp/B00HSB2EZI/) | โ | โ | โ | MFi | Extended | โโโโโ |
| [Horipad Ultimate](https://www.amazon.com/HORI-HORIPAD-ULTIMATE-Wireless-Controller/dp/B06Y2512L8/) | โ | โ | โ | MFi | Extended | โโโโโ |
| [8bitdo N30](https://www.amazon.com/Wireless-Controller-bluetooth-Android-windows/dp/B01N4M9LQY/) / [F30](https://www.amazon.com/FC30-Game-Controller-PC-Mac-Linux/dp/B00FEEGZVU/)^\* | โ | โ | โ | iCade | Standard+ | โโโโโ |
| [8bitdo SN30](https://www.amazon.com/8bitdo-Wireless-Bluetooth-Controller-Joystick/dp/B014QP2H1E/) / [SF30](https://www.amazon.com/8Bitdo-SF30-Controller-Windows-macOS-Android/dp/B0748S3GXG/)^\* + [clamp](https://www.amazon.com/8Bitdo-Xstander-Holder-SFC30-SNES30/dp/B017SFNW0E/) | โ | โ | โ | iCade | Standard+ | โโโโโ |
| [8bitdo N30](https://www.amazon.com/Wireless-Bluetooth-Controller-Classic-Joystick/dp/B018K3Q4KS/) / [F30Pro](https://www.amazon.com/FC30-Game-Controller-PC-Mac-Linux/dp/B00FEEGZVU/)^\* + [clamp A](https://www.amazon.com/Xtander-Wireless-8Bitdo-Controller-Gamepad/dp/B01N9PWDZ3/) , [B](https://www.amazon.com/Gam3Gear-Xtander-Wireless-NES30-Pro-Controller/) | | | | iCade | Extended+ | โโโโโ |
| [8bitdo Zero](https://www.amazon.com/8BITDO-Wireless-Controller-Android-Windows/dp/B0156IC8M8/) | โ | โ | โ | iCade | Standard+ | โโโโโ |
| [Logitech Powershell](https://www.amazon.com/Logitech-PowerShell-Controller-Battery-Generation/dp/B00FHREO8K/) 5/5s/SE/iPod5T only | โ | | | MFi | Standard | โโโโโ |
| [MOGA Ace](https://www.amazon.com/PowerA-MOGA-Ace-Power-Electronic-Games/dp/B00H01EXM8/) 5/5c/5s/SE only | โ | | | MFi | Standard | โโโโโ |
| [MOGA Rebel](https://www.amazon.com/MOGA-Rebel-Premium-iOS-Gaming-Controller/dp/B00PG0C85Y)^ | โ | โ | โ | iCade | Extended | โโโโโ |
| [Mad Catz Micro C.T.R.L.i](https://www.amazon.com/C-T-R-L-i-Mobile-Gamepad-not-machine-specific/dp/B00NSGA1K2)^ | โ | โ | โ | MFi | Extended | โโโโโ |
^ Discontinued, some can still be obtained.\
\* Requires [legacy firmware](http://support.8bitdo.com/) to work with iOS/tvOS.
{% hint style="info" %}
Check out the controller phone mounts made by [UtorCase](https://utorcase.com/).
{% endhint %}
See [Controller Reviews](/using-provenance/controllers-and-controls/controller-reviews) for recommendations by use case and platform.
## Controls
A full list of mapped controls for Standard and Extended MFi gamepad profiles per system can be found in [MFi Controls](https://bit.ly/2LDZNzI).
# Controller Reviews
Controller recommendations by platform and use case
Choosing the right controller depends on your device and play style. Here are our top picks based on community experience and compatibility testing.
## Best Overall
### PlayStation DualSense / DualShock 4
* **Platforms:** iPhone, iPad, Apple TV, Mac
* **Profile:** Extended2+ (full button set including L3/R3)
* **Why:** Native Apple support since iOS 14.5 / tvOS 14.5. Excellent d-pad, analog sticks, and triggers. Touchpad not used. Widely available and affordable.
* **Tip:** Update firmware via a PS5 or the [DualSense firmware updater](https://controller.dl.playstation.net/controller/lang/en/fwupdater.html) for best Bluetooth stability.
### Xbox Series X|S Controller
* **Platforms:** iPhone, iPad, Apple TV, Mac
* **Profile:** Extended2+ (full button set)
* **Why:** Native Apple support since iOS 14.5 / tvOS 14.5. Familiar layout, excellent triggers, long battery life with AAs or rechargeable pack. Share button supported on newer models.
* **Tip:** Bluetooth model required (has no 3.5mm jack on bottom = Bluetooth). Older Xbox One controllers without Bluetooth won't pair.
***
## Best for iPhone (Form-Fitting)
### Razer Kishi (v1 / v2)
* **Rating:** โโโโโ
* **Profile:** Extended2+
* **Why:** Turns your iPhone into a handheld console. USB-C passthrough charging, low latency (wired connection), comfortable grip. The best portable experience.
* **Limitations:** iPhone only (no iPad/Apple TV). Device size must fit the cradle.
### Backbone One
* **Profile:** Extended2+
* **Why:** Excellent build quality, Lightning and USB-C versions available. Includes its own app with social features. Low latency wired connection.
* **Limitations:** iPhone only. Backbone app features are separate from Provenance.
***
## Best for Apple TV
### PlayStation or Xbox Controller (above)
The best Apple TV controllers are the same standalone controllers you'd use with a console. Both PlayStation and Xbox controllers are excellent choices โ pick whichever layout you prefer.
### Siri Remote (Basic Games Only)
* **Profile:** Micro (limited buttons)
* **Requires:** tvOS 17+
* **Use for:** Simple games (NES, Game Boy, Atari) where you only need a d-pad and two buttons
* **Not recommended for:** Anything requiring shoulder buttons, analog sticks, or more than 2 face buttons
***
## Best for iPad
### 8BitDo Pro 2
* **Profile:** Extended2+ (with firmware update)
* **Why:** Retro aesthetic, excellent d-pad, multi-platform support. Switch between Apple, Android, and PC modes.
* **Tip:** Update to latest firmware for best iOS/iPadOS compatibility.
### SteelSeries Nimbus+
* **Rating:** โโโโโ
* **Profile:** Extended (with L3/R3)
* **Why:** MFi certified, reliable pairing, includes iPhone mount. Good all-around option for iPad and Apple TV.
* **Limitations:** No Select/Start buttons โ Provenance maps L2/R2 as Select/Start for systems that need them.
***
## Budget Options
### 8BitDo SN30 / SF30
* **Rating:** โโโโโ
* **Profile:** Standard+ (iCade mode)
* **Why:** Affordable retro-styled controllers. Great for 8-bit and 16-bit systems that don't need analog sticks.
* **Limitations:** iCade mode โ less fluid than MFi. Requires [legacy firmware](http://support.8bitdo.com/) for iOS/tvOS. Cannot use two iCade controllers simultaneously.
### 8BitDo Zero 2
* **Rating:** โโโโโ
* **Profile:** Standard+ (iCade mode)
* **Why:** Ultra-compact, keychain-sized. Fun novelty for basic games.
* **Limitations:** Tiny size makes extended play uncomfortable. iCade mode only. Limited button count.
***
## Legacy / Discontinued (Still Available Used)
| Controller | Type | Profile | Notes |
| ------------------- | ---------- | ---------- | ---------------------------------------------------------------- |
| GameVice (iPhone) | MFi | Extended | Great form-fitting option, check model compatibility |
| MOGA Rebel | iCade | Extended | Decent standalone, iCade limitations apply |
| Logitech Powershell | MFi | Standard | iPhone 5/5s/SE (1st gen) / iPod Touch 5th gen only |
| Steam Controller | pseudo-MFi | Extended2+ | Requires BLE firmware. Won't auto-reconnect (needs app relaunch) |
***
## Quick Reference
| Use Case | Top Pick | Runner-Up |
| ------------------- | ---------------- | ---------------------- |
| iPhone (portable) | Razer Kishi | Backbone One |
| iPhone (standalone) | DualSense | Xbox Series Controller |
| iPad | DualSense / Xbox | SteelSeries Nimbus+ |
| Apple TV | DualSense / Xbox | SteelSeries Nimbus+ |
| Mac | DualSense / Xbox | 8BitDo Pro 2 |
| Budget | 8BitDo SN30 | 8BitDo Zero 2 |
| Retro purist | 8BitDo SN30 | 8BitDo Pro 2 |
***
## Tips for All Controllers
* **Firmware updates matter** โ Update your controller firmware for the best Bluetooth stability and compatibility
* **Pair one at a time** โ When adding a new controller, disconnect others to avoid conflicts
* **MFi vs iCade** โ MFi controllers are strongly recommended. iCade controllers use keyboard hacks and have limitations (no analog input, only one at a time)
* **Bluetooth range** โ \~30 feet / 10 meters line of sight. Walls and interference reduce range
* **Apple TV + Ethernet** โ Using wired Ethernet on Apple TV improves Bluetooth controller performance by reducing WiFi/Bluetooth interference
For full button mapping details, see [Control Maps](/using-provenance/controllers-and-controls/control-maps). For the complete compatibility table, see [Supported Controllers](/using-provenance/controllers-and-controls/controllers).
# Smart Keyboard Mapping
Keyboard button mappings for playing games with a Smart Keyboard or external keyboard
Provenance supports playing games with a **Smart Keyboard** (iPad), **Magic Keyboard**, or any **external Bluetooth/USB keyboard**. This is useful when you don't have a controller available.
{% hint style="info" %}
Keyboard mappings are currently hard-coded and cannot be customized. Custom key remapping is planned for a future update.
{% endhint %}
***
## Button Mappings
### D-Pad
| Direction | Key |
| --------- | ------------- |
| Up | `Up Arrow` |
| Down | `Down Arrow` |
| Left | `Left Arrow` |
| Right | `Right Arrow` |
### Analog Sticks
| Left Stick | Key | | Right Stick | Key |
| ---------- | --- | - | ----------- | --- |
| Up | `W` | | Up | `=` |
| Down | `S` | | Down | `-` |
| Left | `A` | | Left | `[` |
| Right | `D` | | Right | `]` |
### Face Buttons
| Button | Key |
| ------ | ---------- |
| A | `Spacebar` |
| B | `F` |
| X | `Q` |
| Y | `E` |
### Shoulder Buttons / Triggers
| Button | Key |
| ------ | ------------ |
| L1 | `Tab` |
| L2 | `Left Shift` |
| R1 | `R` |
| R2 | `V` |
### System Buttons
| Button | Key |
| ------------ | ----------- |
| Menu (Pause) | `~` (tilde) |
| Options | `1` |
***
## Tips
* **iPad Smart Keyboard / Magic Keyboard** works seamlessly โ just connect and play
* **Bluetooth keyboards** pair in Settings โ Bluetooth like any other accessory
* Keyboard input works alongside on-screen controls โ both can be active simultaneously
* For the best experience with keyboard, use **landscape orientation** so the game fills more of the screen
***
## See Also
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ Full controller guide
* [Supported Controllers](/using-provenance/controllers-and-controls/controllers) โ Bluetooth and MFi controller list
* [Control Maps](/using-provenance/controllers-and-controls/control-maps) โ Button mappings for all systems
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Control Maps
Controller mappings for gamepad profiles per system.
## MFi Controller Maps
{% tabs %}
{% tab title="Extended2" %}
Full extended gamepad with dual analog sticks, triggers, and thumbstick buttons (Lโข/Rโข). Matches modern controllers such as Xbox, PlayStation, or 8BitDo pads with clickable sticks.
| System | | โ | A | B | X | Y | L1 | R1 | L2 | R2 | โ | โ | Lโข | Rโข | โ๏ธ | โถ๏ธ |
| ------------ | --------------------------------------------------- | --------- | -------- | -------- | - | - | -------- | -------- | -- | ---- | -------- | --------- | -- | -- | ------ | ----- |
| Atari | 2600 | Joystick | Fire | | | | | | | | | | | | Select | Reset |
| | 5200 | | Fire 2 | Fire 1 | | | | | | | Joystick | | | | Pause | Start |
| | 7800 | Joystick | Button 2 | Button 1 | | | | | | | | | | | Select | Reset |
| | Lynx | โ | A | B | | | Option 1 | Option 2 | | | | | | | Flip | Start |
| | Jaguar | โ | B | C | A | | L | R | | | | | | | Option | Pause |
| Bandai | WonderSwan, WonderSwan Color | X Buttons | A | B | | | | | | | | Y Buttons | | | | Start |
| NEC | PC Engine (TurboGrafx-16) | โ | II | I | | | | | | | | | | | Select | Run |
| | PC Engine CD / TurboGrafx-CD | โ | II | I | | | | | | | | | | | Select | Run |
| | PC Engine SuperGrafx | โ | II | I | | | | | | | | | | | Select | Run |
| Nintendo | Nintendo Entertainment System / Famicom | โ | A | B | | | | | | | | | | | Select | Start |
| | Famicom Disk System | โ | A | B | | | | | | | | | | | Select | Start |
| | Game Boy | โ | A | B | | | | | | | | | | | Select | Start |
| | Super Famicom (Super Nintendo Entertainment System) | โ | B | A | X | Y | L | R | | | | | | | Select | Start |
| Sega | SG-1000 | โ | Button 2 | Button 1 | | | | | | | | | | | | Start |
| | Master System | โ | Button 2 | Button 1 | | | | | | | | | | | | Pause |
| | Mega Drive / Genesis | โ | B | C | A | X | Y | Z | | Mode | | | | | | Start |
| | Game Gear | โ | Button 2 | Button 1 | | | | | | | | | | | | Start |
| | Mega-CD / Sega CD | โ | B | C | A | X | Y | Z | | Mode | | | | | | Start |
| | 32X | โ | B | C | A | X | Y | Z | | Mode | | | | | | Start |
| | Saturn | โ | B | C | A | Y | L | R | Z | X | | | | | | Start |
| {% endtab %} | | | | | | | | | | | | | | | | |
{% tab title="Extended" %}
Extended gamepad with dual analog sticks and triggers, but without clickable thumbstick buttons (no Lโข/Rโข). Matches most common MFi gamepads.
| System | | โ | A | B | X | Y | L1 | R1 | L2 | R2 | โ | โ | โ๏ธ | โถ๏ธ |
| ------------ | --------------------------------------------------- | --------- | -------- | -------- | - | - | -------- | -------- | -- | -- | -------- | --------- | ------ | ----- |
| Atari | 2600 | Joystick | Fire | | | | | | | | | | Select | Reset |
| | 5200 | | Fire 2 | Fire 1 | | | | | | | Joystick | | Pause | Start |
| | 7800 | Joystick | Button 2 | Button 1 | | | | | | | | | Select | Reset |
| | Lynx | โ | A | B | | | Option 1 | Option 2 | | | | | Flip | Start |
| | Jaguar | โ | B | C | A | | L | R | | | | | Option | Pause |
| Bandai | WonderSwan, WonderSwan Color | X Buttons | A | B | | | | | | | | Y Buttons | | Start |
| NEC | PC Engine (TurboGrafx-16) | โ | II | I | | | | | | | | | Select | Run |
| | PC Engine CD / TurboGrafx-CD | โ | II | I | | | | | | | | | Select | Run |
| | SuperGrafx | โ | II | I | | | | | | | | | Select | Run |
| Nintendo | Nintendo Entertainment System / Famicom | โ | A | B | | | | | | | | | Select | Start |
| | Famicom Disk System | โ | A | B | | | | | | | | | Select | Start |
| | Game Boy | โ | A | B | | | | | | | | | Select | Start |
| | Super Famicom (Super Nintendo Entertainment System) | โ | B | A | X | Y | L | R | | | | | Select | Start |
| Sega | SG-1000 | โ | Button 2 | Button 1 | | | | | | | | | | Start |
| | Master System | โ | Button 2 | Button 1 | | | | | | | | | | Pause |
| | Mega Drive / Genesis | โ | B | C | A | X | Y | Z | | | | | Mode | Start |
| | Game Gear | โ | Button 2 | Button 1 | | | | | | | | | | Start |
| | Mega-CD / Sega CD | โ | B | C | A | X | Y | Z | | | | | Mode | Start |
| | 32X | โ | B | C | A | X | Y | Z | | | | | Mode | Start |
| | Saturn | โ | B | C | A | Y | L | R | Z | X | | | | Start |
| {% endtab %} | | | | | | | | | | | | | | |
{% tab title="Standard" %}
Standard gamepad with D-pad, four face buttons, and two shoulder buttons. No analog sticks or triggers.
| System | | โ | A | B | X | Y | L1 | R1 | โ๏ธ | โถ๏ธ |
| ------------ | --------------------------------------------------- | --------- | -------- | -------- | - | - | -------- | -------- | ------ | ----- |
| Atari | 2600 | Joystick | Fire | | | | | | Select | Reset |
| | 5200 | โ | Fire 2 | Fire 1 | | | | | Pause | Start |
| | 7800 | Joystick | Button 2 | Button 1 | | | | | Select | Reset |
| | Lynx | โ | A | B | | | Option 1 | Option 2 | Flip | Start |
| | Jaguar | โ | B | C | A | | L | R | Option | Pause |
| Bandai | WonderSwan, WonderSwan Color | X Buttons | A | B | | | | | | Start |
| NEC | PC Engine (TurboGrafx-16) | โ | II | I | | | | | Select | Run |
| | PC Engine CD / TurboGrafx-CD | โ | II | I | | | | | Select | Run |
| | SuperGrafx | โ | II | I | | | | | Select | Run |
| Nintendo | Nintendo Entertainment System / Famicom | โ | A | B | | | | | Select | Start |
| | Famicom Disk System | โ | A | B | | | | | Select | Start |
| | Game Boy | โ | A | B | | | | | Select | Start |
| | Super Famicom (Super Nintendo Entertainment System) | โ | B | A | X | Y | L | R | Select | Start |
| Sega | SG-1000 | โ | Button 2 | Button 1 | | | | | | Start |
| | Master System | โ | Button 2 | Button 1 | | | | | | Pause |
| | Mega Drive / Genesis | โ | B | C | A | X | Y | Z | Mode | Start |
| | Game Gear | โ | Button 2 | Button 1 | | | | | | Start |
| | Mega-CD / Sega CD | โ | B | C | A | X | Y | Z | Mode | Start |
| | 32X | โ | B | C | A | X | Y | Z | Mode | Start |
| | Saturn | โ | B | C | A | Y | L | R | | Start |
| {% endtab %} | | | | | | | | | | |
{% tab title="Micro" %}
Micro gamepad (e.g., Apple TV Siri Remote). Only D-pad, A, X, and Menu button available. Limited to basic gameplay.
| System | | โ | A | X | โถ๏ธ |
| ------------- | --------------------------------------------------- | --------- | -------- | -------- | ----- |
| Atari | 2600 | Joystick | Fire | | Reset |
| | 5200 | โ | Fire | | Start |
| | 7800 | Joystick | Button 1 | Button 2 | Reset |
| | Lynx | โ | A | B | Start |
| | Jaguar | โ | B | A | Pause |
| Bandai | WonderSwan, WonderSwan Color | X Buttons | A | B | Start |
| NEC | PC Engine (TurboGrafx-16) | โ | II | I | Run |
| | PC Engine CD / TurboGrafx-CD | โ | II | I | Run |
| | SuperGrafx | โ | II | I | Run |
| Nintendo | Nintendo Entertainment System / Famicom | โ | A | B | Start |
| | Famicom Disk System | โ | A | B | Start |
| | Game Boy | โ | A | B | Start |
| | Super Famicom (Super Nintendo Entertainment System) | โ | B | A | Start |
| Sega | SG-1000 | โ | Button 1 | Button 2 | Start |
| | Master System | โ | Button 1 | Button 2 | Pause |
| | Mega Drive / Genesis | โ | B | A | Start |
| | Game Gear | โ | Button 1 | Button 2 | Start |
| | Mega-CD / Sega CD | โ | B | A | Start |
| | 32X | โ | B | A | Start |
| | Saturn | โ | B | A | Start |
| {% endtab %} | | | | | |
| {% endtabs %} | | | | | |
### iCade Controller Maps
iCade controllers use key mappings rather than analog data. They support basic directional input and buttons, but do not support analog thumbsticks or variable trigger sensitivity.
For iCade-mode controllers (e.g., 8bitdo N30, SteelSeries Stratus XL\*), refer to your controller's manual for the key mapping layout, as iCade mappings vary per device.
# Skins
Customize on-screen controls with skins for every system
**Skins** are custom controller overlays that let you personalize the look and feel of Provenance's on-screen controls. Choose from hundreds of community-created designs, from classic console aesthetics to modern minimalist layouts.
## What Are Skins?
Skins change the visual appearance of your on-screen controller buttons and d-pad while you play. Each skin is designed for a specific system (e.g., NES, Game Boy, PlayStation) and can completely transform your gaming experience.
**Examples of popular skin styles:**
* ๐จ **Console-accurate** - Recreates the original hardware's button layout and colors
* ๐ **Custom colors** - Transparent, neon, retro themes
* ๐ฑ **Minimalist** - Simple, clean buttons that don't obstruct gameplay
* ๐ฎ **Game-themed** - Styled after specific games (Pokรฉmon, Mario, Sonic)
* ๐ป **Invisible** - For Backbone/Kishi users who want physical controls only
## โจ Key Features
**Skins are 100% FREE for all users!** No Provenance Plus subscription required.
**Highlights:**
* โก Fast rendering and loading
* ๐ Smooth orientation changes
* ๐พ Optimized memory usage
* ๐ฎ Full support for all RetroArch cores
* ๐ฑ Works on iPhone, iPad, and Apple TV
* ๐จ **Multi-theme variants** โ multiple color schemes in one skin file
* ๐ **Animated backgrounds** โ frame sequences, APNG, or GIF
* โจ๏ธ **Keyboard overlays** โ for C64, Atari, ZX Spectrum and other keyboard systems
* ๐ณ **Per-button haptics** โ custom haptic intensity per button
## Supported Systems
Skins work with **all systems except**:
* โ Nintendo DS (not currently supported)
**Fully supported systems include:**
* โ
NES, SNES, N64
* โ
Game Boy, GBC, GBA
* โ
Nintendo 3DS (iOS/iPadOS/macOS only โ not supported on tvOS)
* โ
Genesis, Sega CD, Dreamcast
* โ
PlayStation, PSP
* โ
Atari, Neo Geo, TurboGrafx-16
* โ
And 30+ more!
***
## How to Get Skins
### Download from DeltaStyles.com
[**DeltaStyles**](https://deltastyles.com) is the largest community repository for Provenance-compatible skins.
**What's available:**
* ๐จ Hundreds of free skins
* ๐ฎ Organized by system (NES, GBA, PlayStation, etc.)
* ๐ Multiple color themes per system
* ๐ฅ Community uploads and ratings
**File format:** `.deltaskin`
**Compatibility:** Provenance supports both **Delta skins** and **Manic skins** - they're the same format!
### Other Sources
* **PlayCase.gg** - Curated skin collection
* **Reddit** (r/EmulationOniOS) - Community-shared skins
* **Discord** - Provenance community often shares custom skins
***
## How to Import Skins
{% tabs %}
{% tab title="Safari Download" %}
1. **Visit DeltaStyles.com** on your iPhone/iPad
2. **Browse by system** (e.g., Game Boy Advance)
3. **Tap "Download"** on a skin you like
4. Safari will download the `.deltaskin` file
5. **Tap the downloaded file** in Safari's download manager
6. **Select "Open in Provenance"**
7. โ
Skin is now imported!
{% endtab %}
{% tab title="AirDrop" %}
1. Download skins on your Mac/another device
2. **AirDrop the `.deltaskin` files** to your iPhone/iPad
3. **Tap the file** when it arrives
4. **Select "Open in Provenance"**
{% endtab %}
{% tab title="Files App" %}
1. Save `.deltaskin` files to iCloud Drive or local storage
2. Open **Files app**
3. Navigate to the skin file
4. **Tap and hold** โ **Share** โ **Provenance**
{% endtab %}
{% tab title="Import via Settings" %}
1. Open **Provenance**
2. Tap **Settings** (gear icon)
3. Scroll to **Controller Skins**
4. Tap a system (e.g., "Game Boy Advance")
5. Tap **"+"** to import from Files app
{% endtab %}
{% endtabs %}
***
## How to Apply Skins
{% tabs %}
{% tab title="Global Default (Per System)" %}
Apply a skin to **all games** for a specific system:
1. Open **Provenance**
2. Tap **Settings** โ **Controller Skins**
3. **Select a system** (e.g., "Super Nintendo")
4. **Tap the skin** you want to use
5. **Select "Set as Default"**
6. โ
This skin will now be used for all SNES games
{% endtab %}
{% tab title="Per-Game Skin" %}
Apply a unique skin to a **specific game only**:
1. **Long-press a game** in your library
2. Tap **"Game Settings"**
3. Scroll to **Controller Skin**
4. **Select a skin** from the list
5. โ
This game will now use that skin (overrides global default)
{% endtab %}
{% tab title="Switch Mid-Game" %}
Change skins without exiting your game:
1. While playing, **open the pause menu** (pause button)
2. Tap **Settings**
3. Tap **Controller Skin**
4. **Select a new skin**
5. Resume playing with the new skin applied
{% endtab %}
{% endtabs %}
***
## Skin Browser
Provenance includes a built-in **skin browser** for managing your collection:
**How to access:**
* Settings โ Controller Skins โ \[System Name]
**Features:**
* ๐ธ **Preview thumbnails** - See what each skin looks like
* ๐๏ธ **Delete skins** - Swipe left to remove unwanted skins
* ๐ **Mark favorites** - Star your most-used skins for quick access
* ๐ **Organize by system** - Automatic sorting by console
**Performance tip:** The skin browser features smooth, responsive scrolling even with large collections.
***
## Creating Custom Skins
### Can I Make My Own Skins?
**Yes!** Custom skin creation is supported, but it requires design tools and familiarity with the `.deltaskin` file format.
**What you need:**
* ๐จ **Image editor** (Photoshop, GIMP, Affinity Designer)
* ๐ **Understanding of JSON** (skin configuration file)
* ๐ฑ **iOS device resolution knowledge** (different layouts for iPhone/iPad)
### File Structure
A `.deltaskin` file is actually a **ZIP archive** containing:
```
MySkin.deltaskin/
โโโ info.json # Skin metadata (name, author, system)
โโโ portrait.png # Portrait mode controller image
โโโ landscape.png # Landscape mode controller image
โโโ edgeToEdge.png # (Optional) Full-screen layout
โโโ assets/ # (Optional) Additional graphics
โโโ preview.png # Thumbnail for skin browser
โโโ bg001.png # (Optional) Animated background frames
```
### `info.json` Structure
```json
{
"name": "My Custom Skin",
"identifier": "com.yourname.myskin",
"gameTypeIdentifier": "public.aoshuang.game.gba",
"author": "Your Name",
"version": "1.0",
"orientation": "portrait",
"mappings": {
"a": { "x": 280, "y": 380, "width": 60, "height": 60 },
"b": { "x": 340, "y": 320, "width": 60, "height": 60 },
"dpad": { "x": 40, "y": 360, "width": 100, "height": 100 }
}
}
```
**Key fields:**
* `gameTypeIdentifier` - System this skin is for (see [System Identifiers](#system-identifiers) below)
* `mappings` - Button positions (x, y coordinates + dimensions)
* `orientation` - "portrait", "landscape", or both
### System Identifiers
Common system identifiers for `info.json` โ use the Provenance/ManicEmu identifiers (`public.aoshuang.game.*`) for broadest compatibility:
| System | Identifier |
| ----------------- | ----------------------------- |
| NES | `public.aoshuang.game.nes` |
| SNES | `public.aoshuang.game.snes` |
| Nintendo 64 | `public.aoshuang.game.n64` |
| Nintendo DS | `public.aoshuang.game.ds` |
| Game Boy | `public.aoshuang.game.gb` |
| Game Boy Color | `public.aoshuang.game.gbc` |
| Game Boy Advance | `public.aoshuang.game.gba` |
| PlayStation | `public.aoshuang.game.ps1` |
| PSP | `public.aoshuang.game.psp` |
| Sega Genesis / MD | `public.aoshuang.game.md` |
| Sega CD | `public.aoshuang.game.mcd` |
| Sega 32X | `public.aoshuang.game.32x` |
| Game Gear | `public.aoshuang.game.gg` |
| Dreamcast | `public.aoshuang.game.dc` |
| PC Engine / TG-16 | `public.aoshuang.game.pce` |
| Atari 2600 | `public.aoshuang.game.2600` |
| Atari 7800 | `public.aoshuang.game.7800` |
| Neo Geo | `public.aoshuang.game.neogeo` |
| Commodore 64 | `public.aoshuang.game.c64` |
Delta-compatible skins (`com.rileytestut.delta.game.*`) also work in Provenance.
**For a complete list**, check the [Provenance skin catalog](https://provenance-emu.com/skins/) source code.
***
## Advanced ManicSkin Features
Provenance supports advanced skin capabilities that go beyond static button layouts. These features are configured in `info.json` and give skin creators powerful new options.
{% hint style="info" %}
These features require the latest version of Provenance. Check [App Store](/getting-started/installing-provenance/app-store) or [advanced installs](/getting-started/installing-provenance/advanced) for the most current builds.
{% endhint %}
### Multi-Theme Variants
A single skin file can contain multiple visual themes (e.g., light mode / dark mode / game-specific palettes). Users select themes via a segmented control in the skin picker.
```json
{
"name": "Lux GBA",
"themes": [
{ "identifier": "dark", "displayName": "Dark Mode" },
{ "identifier": "light", "displayName": "Light Mode" },
{ "identifier": "purple", "displayName": "Purple Haze" }
]
}
```
Each theme identifier corresponds to asset variants bundled inside the `.deltaskin` ZIP. The skin validator will catch missing theme assets before import.
### Animated Backgrounds
Skins can include animated backgrounds behind the game screen using frame sequences, APNG, or GIF files.
{% tabs %}
{% tab title="Frame Sequence" %}
```json
"backgroundAnimation": {
"type": "frames",
"frames": ["bg001.png", "bg002.png", "bg003.png", "bg004.png"],
"fps": 12,
"loops": 0
}
```
`loops: 0` means loop infinitely. Include the frame images inside your `.deltaskin` ZIP.
{% endtab %}
{% tab title="APNG / GIF" %}
```json
"backgroundAnimation": {
"type": "apng",
"source": "background.png"
}
```
Or for GIF:
```json
"backgroundAnimation": {
"type": "gif",
"source": "background.gif"
}
```
{% endtab %}
{% endtabs %}
**Supported `blendMode` values:** `normal`, `multiply`, `screen`, `overlay` (optional field, defaults to `normal`).
### Keyboard Overlay
For systems with keyboard input (Commodore 64, Atari 8-bit, ZX Spectrum, etc.), skins can include an on-screen keyboard overlay.
```json
"keyboardOverlay": {
"layout": "full",
"position": "bottom",
"opacity": 0.85,
"autoShow": true
}
```
**Layout variants:**
| `layout` | Description |
| ------------- | ------------------------------------ |
| `full` | Standard QWERTY keyboard |
| `compact` | Condensed layout for smaller screens |
| `functionRow` | Function keys only (F1โF12) |
| `c64` | Commodore 64 key layout |
| `zxSpectrum` | ZX Spectrum key layout |
| `amstradCPC` | Amstrad CPC key layout |
| `atariST` | Atari ST key layout |
* `position`: `"top"` or `"bottom"` โ where the keyboard appears on screen
* `autoShow`: `true` to show keyboard automatically when a text input is focused
### Per-Button Haptics
Individual buttons can have custom haptic feedback intensity, letting skin creators match haptic feel to button importance or game genre.
Add `hapticStrength` to any button mapping:
```json
"mappings": {
"a": { "x": 280, "y": 380, "width": 60, "height": 60, "hapticStrength": "heavy" },
"b": { "x": 340, "y": 320, "width": 60, "height": 60, "hapticStrength": "medium" },
"start": { "x": 180, "y": 450, "width": 44, "height": 44, "hapticStrength": "light" }
}
```
**Haptic strength values:** `none`, `light`, `medium`, `heavy`, `rigid`, `soft`
### Skin Validator
Provenance automatically validates `.deltaskin` files on import:
* **Errors** (block import): missing `info.json`, invalid `gameTypeIdentifier`, referenced image files not found in ZIP, malformed JSON
* **Warnings** (shown after import): missing optional fields, deprecated field names, oversized assets
The validator helps skin creators catch issues before distributing their work.
***
### Tools for Skin Creation
**Recommended workflow:**
1. **Download an existing skin** as a template
2. **Unzip the `.deltaskin` file** (rename to `.zip` โ extract)
3. **Edit PNG images** in your image editor
4. **Adjust `info.json` mappings** if needed
5. **Re-zip the folder** โ rename to `.deltaskin`
6. **Import into Provenance** and test
**Advanced tools:**
* **Delta Skin Editor** (web-based tool) - Simplifies mapping button coordinates
* **Skin Template PSDs** - Pre-made Photoshop templates (search GitHub/Reddit)
**External skin creation guides:**
* [**Manic EMU Homemade Skin Guide**](https://manicemu.site/Homemade-Skin-Guide-EN/) โ Extremely detailed guide covering press animations, custom function buttons, and advanced skin features (uses the same `.deltaskin` format)
* [**DeltaCore Skins Spec**](https://github.com/rileytestut/DeltaCore/wiki/Skins) โ Official technical specification for the `.deltaskin` format (JSON schema, coordinate systems, image requirements)
***
## Tips & Best Practices
### For Best Performance
1. โ
**Use optimized PNGs** - Compress images to reduce file size (tinypng.com)
2. โ
**Avoid overly complex designs** - Simple graphics load faster
3. โ
**Test on your device** - Preview how skins look at actual screen size
4. โ
**Delete unused skins** - Keep your collection organized
### For Better Gameplay
1. ๐ฎ **Match button placement to your grip** - Different layouts feel better for different hand sizes
2. ๐ **Consider transparency** - Semi-transparent buttons let you see more of the game
3. ๐ฑ **Test both orientations** - Some games play better in portrait vs landscape
4. ๐ **Check button visibility** - Make sure buttons are easy to see against game graphics
### Popular Community Recommendations
**Best all-around skins (per DeltaStyles ratings):**
* **GBA:** "Atomic Purple" (classic transparent purple)
* **SNES:** "Classic Gray" (original SNES controller recreation)
* **PlayStation:** "DualShock" (authentic PS1 button layout)
* **Game Boy:** "DMG Original" (1989 gray brick aesthetic)
***
## Troubleshooting
Skin Not Showing in Browser
**Problem:** Imported skin doesn't appear in the skin list
**Solutions:**
1. โ
**Check file extension** - Must be `.deltaskin` (not `.zip`)
2. โ
**Verify system** - Skin must match a supported system (DS not yet supported; 3DS not supported on tvOS)
3. โ
**Restart Provenance** - Force quit app and reopen
4. โ
**Re-import** - Delete and re-download the skin
Skin Looks Corrupted or Glitchy
**Problem:** Buttons are misaligned, missing, or stretched
**Solutions:**
1. โ
**Re-download skin** - File may have been corrupted during download
2. โ
**Check device compatibility** - Some skins are iPhone-only or iPad-only
3. โ
**Update Provenance** - Ensure you're on the latest version from the App Store
4. โ
**Report to skin creator** - Leave feedback on DeltaStyles or GitHub
Buttons Don't Respond
**Problem:** Tapping skin buttons doesn't register input
**Solutions:**
1. โ
**Check `info.json` mappings** - Button coordinates may be wrong
2. โ
**Disable "Touch Controls"** - Settings โ ensure touch controls are enabled
3. โ
**Try a different skin** - Test if the issue is skin-specific
4. โ
**Restart game** - Close and relaunch the game
Performance Slowdown with Skins
**Problem:** Game lags or stutters after applying a skin
**Solutions:**
1. โ
**Use simpler skins** - Complex, high-resolution graphics add overhead
2. โ
**Update to the latest version** - Contains skin performance improvements
3. โ
**Close background apps** - Free up memory
4. โ
**Disable visual filters** - Turn off CRT/Smoothing in settings
***
## Storage & File Management
### Where Are Skins Stored?
Skins are stored on your device in Provenance's app container.
**iCloud sync:** On Apple TV (tvOS), iCloud/CloudKit sync is included for free. On iPhone, iPad, and Mac, **Provenance Plus** is required for iCloud sync of skins, your game library, save states, BIOS files, and custom artwork. [Learn more about Provenance Plus โ](/faqs#what-is-provenance-plus)
**File size:** Most skins are 500KB - 2MB each (negligible storage impact).
### How to Organize Many Skins
**Recommended workflow:**
1. **Delete unused skins** - Swipe left in skin browser
2. **Name skins clearly** - Use descriptive names when creating custom skins
3. **Keep backups** - Save favorite skins to iCloud Drive or Files app
### Sharing Skins
**How to share your custom skins:**
1. Export the `.deltaskin` file from Provenance
2. Upload to DeltaStyles.com (create free account)
3. Or share via AirDrop, Discord, Reddit
**Community etiquette:**
* ๐ Credit original artists if you modify their work
* ๐ Include a preview screenshot when sharing
* ๐ Share source files (PSD/Figma) for easier community remixing
***
## Frequently Asked Questions
Do skins work on Apple TV?
Yes, for most systems! Skins render on Apple TV when using touch-based systems (though most users prefer physical controllers). Note: Nintendo 3DS skins are not supported on tvOS.
Can I use the same skin on multiple systems?
No โ each skin is designed for a specific system's button layout (SNES skins won't work for GBA).
Are animated skins supported?
Yes! Animated backgrounds are supported via the `backgroundAnimation` field in `info.json`. Skin creators can use frame sequences (PNG), APNG, or GIF files. See [Animated Backgrounds](#animated-backgrounds) above.
Do skins affect game performance?
Minimal impact thanks to optimized rendering in current versions.
Can I disable skins entirely?
Yes โ select the default "Standard" skin for any system to use Provenance's built-in controls.
Where can I request a specific skin design?
Check the [Provenance Discord](https://discord.gg/provenance) or r/EmulationOniOS โ community designers often take requests!
***
## Next Steps
* ๐จ [**Browse skins at DeltaStyles โ**](https://deltastyles.com)
* ๐ฎ [**Controllers & Controls Guide**](/using-provenance/controllers-and-controls) - Optimize your control setup
* ๐ฑ [**Performance Optimization**](/platforms-and-performance/performance-optimization) - Get the best gameplay experience
* โ๏ธ [**Troubleshooting Guide**](/help-and-community/troubleshooting) - Fix common issues
***
**Have an amazing skin to share?** Submit it to the [Skin Catalog](/using-provenance/skins-guide/skin-catalog-contributing) so it appears in the built-in Skin Browser for everyone โ or join the [Provenance community on Discord](https://discord.gg/provenance) and show off your creations!
*Update to the latest version from the App Store for the best skins experience.*
# Contributing to the Skin Catalog
How to submit your skin to the Provenance community catalog so it appears in the built-in Skin Browser
Provenance includes a built-in **Skin Browser** (Settings โ Skins โ Browse Catalog) that lets users discover and install community skins directly from the app. The catalog is maintained at [github.com/Provenance-Emu/skins](https://github.com/Provenance-Emu/skins) โ a dedicated open-source repo anyone can contribute to.
[**๐ฎ Browse the catalog โ**](https://provenance-emu.com/skins)
{% hint style="info" %}
Skins must be in `.deltaskin` or `.manicskin` format and hosted at a **publicly accessible URL** to be included.
{% endhint %}
***
## Submission Methods
### Option 1 โ Web form (easiest)
Visit [**provenance-emu.com/skins/submit.html**](https://provenance-emu.com/skins/submit.html), paste your skin URL, and click **Fetch Metadata**. The page will auto-extract the name and system from your skin file, then let you submit with one click. A bot opens the PR for you within \~60 seconds.
### Option 2 โ GitHub Issue
[Open a skin submission issue](https://github.com/Provenance-Emu/skins/issues/new?template=submit-skin.yml) and paste your URL. The bot processes it automatically and comments back with a link to the pull request.
Supported URL types:
* Direct `.deltaskin` or `.manicskin` file
* GitHub repo containing skin files (all skins imported at once)
* GitHub release URL (all skin assets imported)
### Option 3 โ Pull Request (advanced)
Fork [Provenance-Emu/skins](https://github.com/Provenance-Emu/skins), add a JSON file to `skins/{system}/`, and open a PR. CI validates your entry automatically on submission.
**Generate a unique ID:**
```bash
# Shell
printf 'manual:https://example.com/MySkin.deltaskin' | shasum -a 256 | cut -c1-16
# Python
import hashlib
hashlib.sha256("manual:https://example.com/MySkin.deltaskin".encode()).hexdigest()[:16]
```
**Minimal JSON entry** (`skins/gba/my-skin-name.json`):
```json
{
"id": "a1b2c3d4e5f60718",
"name": "My GBA Skin",
"author": "yourname",
"systems": ["gba"],
"gameTypeIdentifier": "com.rileytestut.delta.game.gba",
"downloadURL": "https://github.com/you/skins/raw/main/MySkin.deltaskin",
"thumbnailURL": null,
"screenshotURLs": [],
"tags": [],
"source": "manual"
}
```
### Option 4 โ Register your repo for auto-crawl
If you maintain a GitHub repo of skins, [register it](https://github.com/Provenance-Emu/skins/issues/new?template=register-source.yml). The weekly crawler will scan your repo every Monday and automatically open PRs for any new skins it finds โ no manual submission needed per skin.
***
## Hosting Your Own Skins on GitHub (Free)
GitHub is the best place to host skin files โ it's free, permanent, and gives you stable download URLs.
1. **Create a public repo** at github.com (e.g. `yourname/skins`)
2. **Upload your `.deltaskin` / `.manicskin` files** โ drag and drop in the GitHub web UI
3. **Get the raw URL**: click a file โ **Raw** โ copy the URL
4. **Submit** the repo or individual file URL via any method above
Raw URLs look like:
```
https://raw.githubusercontent.com/yourname/skins/main/MySkin.deltaskin
```
These URLs never change as long as the file stays in the same place. You can use GitHub Releases for versioned bundles.
{% hint style="success" %}
**Advantages over DeltaStyles:** instant updates, version history, no account required on a third-party site, and new systems supported by Provenance are added to the catalog before DeltaStyles updates their system list.
{% endhint %}
***
## Catalog JSON Schema
| Field | Type | Required | Description |
| -------------------- | ------ | -------- | --------------------------------------------------------------- |
| `id` | string | **Yes** | 16-char hex. Generate with `sha256("source:downloadURL")[:16]`. |
| `name` | string | **Yes** | Display name in the Skin Browser. |
| `systems` | array | **Yes** | System codes โ see table below. |
| `downloadURL` | string | **Yes** | Direct `.deltaskin` or `.manicskin` URL. |
| `source` | string | **Yes** | Short identifier, e.g. `"manual"` or `"yourname/repo"`. |
| `author` | string | No | Creator's name or handle. |
| `gameTypeIdentifier` | string | No | Delta-compatible GTI (auto-detected from skin file). |
| `thumbnailURL` | string | No | Preview image URL โ strongly recommended. |
| `screenshotURLs` | array | No | Additional screenshots. |
| `tags` | array | No | e.g. `"dark"`, `"minimal"`, `"landscape"`. |
| `version` | string | No | Skin version string. |
| `fileSize` | number | No | File size in bytes. |
| `lastUpdated` | string | No | ISO 8601 date. |
***
## Supported Systems
Provenance supports skins for all single-screen systems it emulates. The `systems` field in the JSON entry uses the short code below. The `gameTypeIdentifier` is the value inside the skin's `info.json` โ both Delta (`com.rileytestut.delta.game.*`) and Manic (`public.aoshuang.game.*`) formats are accepted.
**Nintendo**
| Code | System | `gameTypeIdentifier` |
| ------------- | ------------------------------ | --------------------------------- |
| `gb` | Game Boy | `com.rileytestut.delta.game.gbc` |
| `gbc` | Game Boy Color | `com.rileytestut.delta.game.gbc` |
| `gba` | Game Boy Advance | `com.rileytestut.delta.game.gba` |
| `nes` | NES / Famicom | `com.rileytestut.delta.game.nes` |
| `snes` | Super Nintendo / Super Famicom | `com.rileytestut.delta.game.snes` |
| `n64` | Nintendo 64 | `com.rileytestut.delta.game.n64` |
| `nds` | Nintendo DS | `com.rileytestut.delta.game.ds` |
| `virtualBoy` | Virtual Boy | `public.aoshuang.game.vb` |
| `threeDS` | Nintendo 3DS | `public.aoshuang.game.3ds` |
| `gamecube` | GameCube | `public.aoshuang.game.gc` |
| `wii` | Wii | `public.aoshuang.game.wii` |
| `pokemonMini` | Pokรฉmon Mini | `public.aoshuang.game.pm` |
**Sega**
| Code | System | `gameTypeIdentifier` |
| -------------- | -------------------- | ------------------------------------ |
| `genesis` | Genesis / Mega Drive | `com.rileytestut.delta.game.genesis` |
| `gamegear` | Game Gear | `com.rileytestut.delta.game.gg` |
| `masterSystem` | Master System | `com.rileytestut.delta.game.ms` |
| `sg1000` | SG-1000 | `public.aoshuang.game.sg1000` |
| `segaCD` | Sega CD / Mega-CD | `public.aoshuang.game.mcd` |
| `sega32X` | 32X | `public.aoshuang.game.32x` |
| `saturn` | Saturn | `public.aoshuang.game.ss` |
| `dreamcast` | Dreamcast | `public.aoshuang.game.dc` |
**Sony**
| Code | System | `gameTypeIdentifier` |
| ----- | ----------------------------- | -------------------------------- |
| `psx` | PlayStation (PS1 / PS2 / PS3) | `com.rileytestut.delta.game.psx` |
| `psp` | PlayStation Portable | `public.aoshuang.game.psp` |
**NEC**
| Code | System | `gameTypeIdentifier` |
| ------- | ------------------------- | ----------------------- |
| `pce` | PC Engine / TurboGrafx-16 | *(Provenance internal)* |
| `pcecd` | PC Engine CD-ROM | *(Provenance internal)* |
| `pcfx` | PC-FX | *(Provenance internal)* |
| `sgfx` | SuperGrafx | *(Provenance internal)* |
**Atari**
| Code | System |
| ----------- | --------------------------- |
| `atari2600` | Atari 2600 |
| `atari5200` | Atari 5200 |
| `atari7800` | Atari 7800 |
| `jaguar` | Atari Jaguar |
| `jaguarcd` | Atari Jaguar CD |
| `lynx` | Atari Lynx |
| `atari8bit` | Atari 8-bit (400/800/XL/XE) |
| `atarist` | Atari ST |
**SNK**
| Code | System |
| -------- | -------------------- |
| `neogeo` | Neo Geo |
| `ngp` | Neo Geo Pocket |
| `ngpc` | Neo Geo Pocket Color |
**Bandai**
| Code | System |
| ----------------- | ---------------- |
| `wonderswan` | WonderSwan |
| `wonderswancolor` | WonderSwan Color |
**Other Classics**
| Code | System |
| --------------- | -------------------- |
| `vectrex` | Vectrex |
| `_3do` | 3DO |
| `appleII` | Apple II |
| `c64` | Commodore 64 |
| `cdi` | Philips CD-i |
| `colecovision` | ColecoVision |
| `cps1` | Capcom CPS1 |
| `cps2` | Capcom CPS2 |
| `cps3` | Capcom CPS3 |
| `intellivision` | Intellivision |
| `macintosh` | Mac Classic |
| `mame` | MAME arcade |
| `megaduck` | Mega Duck |
| `msx` | MSX |
| `msx2` | MSX2 |
| `odyssey2` | Odyssey 2 |
| `supervision` | Supervision |
| `zxspectrum` | ZX Spectrum |
| `retroarch` | RetroArch (any core) |
{% hint style="info" %}
Don't see your system? The catalog covers all 66 Provenance-supported systems. If you're targeting a system not in this list, open a GitHub issue on the [skins repo](https://github.com/Provenance-Emu/skins) and we'll add it. The `unofficial` system code is deprecated โ all systems now have proper identifiers.
{% endhint %}
***
## See Also
* [Skins Guide](/using-provenance/skins-guide) โ Installing and using skins in Provenance
* [Contributing](/help-and-community/contribute) โ General contribution guide
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Game Saves
Battery saves, save states, and syncing your game progress
There are two ways to save progress in Provenance:
* **Battery Saves** โ The game's native save system (in-game save). Portable and reliable across updates.
* **Save States** โ Emulator snapshots that freeze the exact state of the game at any moment. Powerful but fragile across updates.
***
## Battery Saves
A **battery save** is created by the game itself when you use its built-in save feature (e.g., saving at a save point in an RPG, or choosing "Save" from a game's menu). These are the most reliable way to preserve progress.
### How to Save
Use the game's own save menu โ this varies by game. For example:
* **Pokemon (Game Boy):** Start menu โ Save
* **Legend of Zelda (SNES):** In-game save screen
* **Final Fantasy (PlayStation):** Save at a save point
The save file is stored at: `Battery States/[ROM-Filename]/[ROM-Filename].sav`
### Supported Formats
| System | Save Format(s) |
| ------------------------- | ------------------------------ |
| Game Boy / Game Boy Color | `.sav` |
| Game Boy Advance | `.sav` |
| SNES / Super Famicom | `.srm`, `.sav` |
| Nintendo 64 | `.eep`, `.sra`, `.fla`, `.mpk` |
| Nintendo DS | `.sav`, `.dsv` |
| Genesis / Mega Drive | `.srm`, `.sav` |
| PlayStation | `.mcr` (memory card) |
| Most other systems | `.sav` |
### Importing Saves from Other Emulators
Battery saves are portable โ you can move them between emulators (unlike save states):
1. Start the Web Server in Provenance (tap **+** or Settings โ Import/Export)
2. Navigate to `Battery States/[ROM-Filename]/`
3. Upload your save file into this folder
4. Rename it to `[ROM-Filename].sav` (must match the ROM filename exactly)
5. Stop the Web Server and load the game
6. Use the game's in-game **Load** option
{% hint style="warning" %}
If the game doesn't recognize the save, verify the filename matches exactly. Saves from a different ROM region or version may be incompatible.
{% endhint %}
### Converting PlayStation Memory Cards
If you have PlayStation memory card files from another emulator, convert them to `.mcr` format:
* **Windows:** [MemcardRex](https://github.com/ShendoXT/memcardrex)
* **Cross-platform:** [MemCard PRO](https://8bitmods.com/) or similar tools
***
## Save States
**Save states** are emulator-level snapshots that capture the exact state of the game โ every pixel, every register, every byte of memory. They let you save anywhere, even mid-battle or during a cutscene.
{% hint style="danger" %}
**Save states are NOT guaranteed to survive app updates.** Emulator core changes can break compatibility. Always keep **battery saves** (in-game saves) for your important progress. See [Save State Version Mismatches](/using-provenance/saves/save-state-version-mismatches) for details.
{% endhint %}
### Saving a State
1. While playing, tap the **pause/menu** button
2. Select **Save States**
3. Tap **+** to create a new save state
4. Or tap an existing state โ **Overwrite** to replace it
**Auto-save:** Provenance can automatically create a save state when the app is backgrounded or when you return to the library. Enable this in Settings.
### Loading a State
1. While playing, tap the **pause/menu** button
2. Select **Save States**
3. Tap a save state โ **Load**
When launching a game, Provenance may offer to resume from the most recent auto-save state.
### Deleting a State
1. Open **Save States** from the pause menu
2. Tap a state โ **Delete**
{% hint style="warning" %}
Deleting a save state is permanent. Back up important states before deleting โ see [Restoring Files](/advanced/restoring-files).
{% endhint %}
***
## Syncing Saves Across Devices
{% tabs %}
{% tab title="Provenance Plus (iCloud)" %}
**Provenance Plus** subscribers get automatic iCloud sync of:
* Battery saves
* Save states
* ROM library
* Settings and preferences
Enable in Settings โ **iCloud Sync**. Progress syncs automatically across iPhone, iPad, Mac, and Apple TV.
{% hint style="info" %}
**Apple TV users:** iCloud sync is included free โ no Provenance Plus subscription required.
{% endhint %}
{% endtab %}
{% tab title="Manual Sync" %}
Without Provenance Plus, you can manually transfer saves:
1. **Export** saves via Web Server, Files app, or AirDrop
2. **Import** on the other device using the same method
Full guide: [Restoring Files](/advanced/restoring-files)
{% endtab %}
{% endtabs %}
***
## Best Practices
1. **Use battery saves for important progress** โ They survive app updates and core changes
2. **Use save states for convenience** โ Quick-save before a hard boss fight, risky decision, etc.
3. **Don't rely solely on save states** โ Create an in-game save periodically as a safety net
4. **Back up before updating** โ Especially if you have save states you can't afford to lose
5. **Enable iCloud Sync** โ If you have Provenance Plus, let it handle backups automatically
***
## See Also
* [Save State Version Mismatches](/using-provenance/saves/save-state-version-mismatches) โ What to do when a save state is incompatible after an update
* [Quick Continue](/using-provenance/quick-continue) โ Save state previews and core picker on game launch
* [In-Game Menu](/using-provenance/in-game-menu) โ Create and load save states from the pause menu
* [Provenance Plus](/platforms-and-performance/provenance-plus) โ iCloud sync for saves across devices
* [Restoring Files](/advanced/restoring-files) โ Backup and restore instructions
***
{% hint style="info" %}
Need help with save management? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Save State Version Mismatches
What save state version mismatches are, why they happen, and how to protect your progress
Save states are powerful for convenience, but they are **not safe long-term backups**. When an emulator core is updated, the internal save state format can change โ and states created with an older version may not load correctly with a newer one.
{% hint style="danger" %}
**Do not rely on save states as long-term backups.** Use the game's own in-game battery save system for any progress you cannot afford to lose.
{% endhint %}
***
## What Is a Version Mismatch?
Every save state records the core version that created it. When you try to load a save state, Provenance compares:
* **Saved version** โ The core version that created the state
* **Current version** โ The core version installed now
If they differ, Provenance shows a **version mismatch warning** before loading.
***
## Why Does This Happen?
Emulator cores are actively developed. Updates can:
* Change how save state data is serialized or compressed
* Add or remove internal state fields
* Fix bugs that alter CPU or memory layout
* Upgrade to a new upstream core release with a different save format
Save states are snapshots of raw emulator internals โ they are **not** a standardized or portable format. Even a small core update can make old states incompatible.
***
## Battery Saves Are Better for Long-Term Storage
For progress you need to keep across app updates, use the **game's own save system** instead of save states:
* Go to an in-game save point and save normally (e.g., a save room in Metroid, a Pokemon Center, a Final Fantasy save point)
* Battery saves (`.sav`, `.srm`, memory cards, etc.) use the game's own format โ they are stable across emulator updates
* Battery saves can also be transferred between emulators
Save states are best used for **short-term convenience** โ quick-saving before a boss fight, pausing mid-cutscene, or experimenting. Do not treat them as a permanent archive.
***
## The Version Mismatch Warning
When Provenance detects a version mismatch, it will show an alert before loading the state. You have two options:
| Option | What it does |
| --------------- | ---------------------------------------------------------- |
| **Cancel** | Does not load the state. Your game stays as-is. |
| **Load Anyway** | Attempts to load the state despite the version difference. |
### "Load Anyway" โ Risks
Loading a mismatched save state is **best effort**. Provenance will try to boot the state, but results may include:
* **Successful load** โ The core may handle the difference gracefully (especially for minor version bumps)
* **Visual or audio glitches** โ Corrupted graphics, wrong sounds, missing sprites
* **Game logic errors** โ Progress flags, inventory, or position may be wrong
* **Crash or hard failure** โ The core rejects the state and the game does not start
* **Emulator instability** โ In some cases, resetting after a failed load may leave the emulator in a bad state requiring a force-quit
There is no way to predict in advance whether a mismatched state will load cleanly. The warning exists so you can make an informed choice.
***
## Before and After a Core Update
**Before updating Provenance:**
1. Create an in-game battery save at a stable point (save menu, save point, etc.)
2. If you have critical save states, export them as a backup โ see [Restoring Files](/advanced/restoring-files)
**After updating Provenance:**
1. Load the game from a battery save or start fresh
2. Create a new save state with the updated core
3. Old save states may no longer load reliably โ the new ones replace them as your working snapshots
***
## Frequently Asked Questions
Will all my save states break after every update?
Not necessarily. Minor core updates may not change the save state format at all, and existing states will continue to work. The version mismatch warning only appears when the recorded version differs from the current one. The risk depends on how significant the core change was.
Can I convert an old save state to the new format?
No. Save state formats are internal to each core and there is no general conversion tool. Your best option is to load the old state (accepting the risk), immediately create an in-game battery save, then create a fresh save state with the new core.
I loaded a mismatched state and now the game is glitched. What do I do?
Return to the game library and relaunch the game without loading the state. If you have a battery save, use the in-game load option to restore your progress cleanly. If not, the game will start from the beginning or the last battery save point.
Does iCloud sync protect me from this?
iCloud sync (Provenance Plus) backs up your save states and battery saves across devices, but it does not protect against version mismatches caused by a core update. Sync preserves your files โ it does not change the fact that an old save state may be incompatible with a new core version. Battery saves synced via iCloud remain fully usable.
***
## See Also
* [Game Saves](/using-provenance/saves) โ Overview of battery saves and save states
* [Quick Continue](/using-provenance/quick-continue) โ Using save states to resume games on launch
* [Restoring Files](/advanced/restoring-files) โ How to back up and restore save files
* [Provenance Plus](/platforms-and-performance/provenance-plus) โ iCloud sync for saves across devices
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Screen Filters & Shaders
Visual filters and shader effects for retro games โ CRT scanlines, LCD grids, VHS tape, and Game Boy effects with 7 built-in Metal filters
Provenance includes built-in Metal screen filters that let you enhance or authentically reproduce the look of retro games. From CRT scanlines to LCD grids to VHS tape effects, these filters transform how games are displayed.
***
## Overview
Provenance supports multiple types of visual filters:
| Type | Technology | Availability |
| --------------------- | ----------------------------------------- | --------------------- |
| **Built-in filters** | Custom Metal shaders | All cores |
| **RetroArch shaders** | Core-specific shader support | RetroArch-based cores |
| **PPSSPP filters** | Built-in to PPSSPP core | PSP games |
| **Auto mode** | Automatic filter selection by screen type | All cores |
{% hint style="info" %}
**Coming soon:** Slang shader support (ported from RetroArch) is in active development, bringing hundreds of additional shader presets with a custom SwiftUI parameter preview and editing UI. Shaders are pre-converted to Metal for maximum performance.
{% endhint %}
***
## How to Apply Filters
### Global Filter Setting
Apply a filter to **all games**:
1. Open Provenance โ **Settings**
2. Scroll to **Video / Display**
3. Select **Screen Filter**
4. Choose a filter from the list
5. The filter applies to all games immediately
### Per-Game Filter
Apply a filter to a **specific game only**:
1. **Long-press** a game in your library
2. Select **Game Settings**
3. Under **Video**, select **Screen Filter**
4. Choose a filter โ this overrides the global setting for this game only
### Auto Mode
Provenance can **automatically select** the appropriate filter based on the emulated system's screen type:
| Screen Type | Auto Filter | Example Systems |
| ------------------ | ------------------------- | ---------------------------- |
| **CRT** | Simple CRT or Complex CRT | NES, SNES, Genesis, PS1, N64 |
| **Color/Mono LCD** | LCD | GBA, Game Gear, Lynx, PSP |
| **Dot Matrix** | Game Boy | Game Boy, GBC |
| **Modern/Unknown** | None | โ |
***
## Available Filters
### CRT Filters
Recreate the look of playing on a classic CRT television:
| Filter | Description | Configurable Parameters |
| --------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| **Simple CRT** | Lightweight CRT simulation โ great balance of look and performance | Curvature, vignette, brightness, zoom |
| **Complex CRT** | Full-featured CRT with bloom, shadow mask, and TV line density | Bloom, scanlines, shadow mask, warp/curvature, gamma, TV line density |
| **Mega Tron** | CRT with mask intensity, scanline thinness, and Trinitron curve | Mask intensity, scanline thinness, scan blur, curvature, corner rounding |
| **ulTron** | CRT with hard scan/pixel effects and shadow mask | Hard scan, hard pixel, warp, shadow mask (dark/light), bright boost, bloom |
**Best for:** Console games (NES, SNES, Genesis, PS1, N64) โ these were designed for CRT displays and look most authentic with CRT filters.
### LCD Filter
Simulate handheld LCD screens:
| Filter | Description | Configurable Parameters |
| ------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **LCD** | Pixel grid simulation with ghosting and scanline effects | Grid density, grid brightness, contrast, saturation, ghosting, scanline depth, bloom |
**Best for:** Handheld games (GBA, Game Gear, Lynx, PSP) โ recreates the original handheld LCD experience.
### Specialty Filters
| Filter | Description | Configurable Parameters |
| ------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Game Boy** | Dot-matrix LCD with classic 4-color green palette | Ghosting, contrast, scanline depth. Palette auto-adjusts based on screen type (dot matrix vs monochromatic LCD) |
| **VHS** | Animated VHS tape effect with noise and tracking artifacts | Noise, scanline jitter, color bleed, tracking noise, tape wobble, ghosting, vignette |
**Game Boy** is great for authentic DMG Game Boy aesthetics. **VHS** adds a fun retro TV recording look โ the effect is animated with time-based noise and wobble.
***
## RetroArch Core Shaders
Games running on **RetroArch-based cores** can access additional shader options through the RetroArch settings interface:
1. Launch a game using a RetroArch core
2. Open the **pause menu**
3. Navigate to **RetroArch Settings** โ **Shaders**
4. Browse and apply shader presets
RetroArch shaders offer more advanced effects including:
* Multi-pass shader chains
* Color correction and palette adjustments
* Phosphor glow effects
* Composite video simulation
* Integer scaling
***
## Performance Impact
| Filter | Performance Impact | Notes |
| ----------------------- | ------------------ | -------------------------------------- |
| None (Nearest Neighbor) | None | Default, no processing |
| Simple CRT | Low | Lightweight โ good for older devices |
| LCD | Low | Grid overlay + ghosting |
| Game Boy | Low | Palette swap + dot matrix |
| Complex CRT | Low-Medium | Bloom + shadow mask + multiple effects |
| Mega Tron / ulTron | Low-Medium | Multiple CRT effects |
| VHS | Medium | Animated โ time-based noise and wobble |
| RetroArch multi-pass | Medium-High | Depends on shader complexity |
{% hint style="info" %}
All built-in Metal filters are highly optimized and have minimal performance impact on modern devices. RetroArch multi-pass shaders may reduce performance on older devices.
{% endhint %}
***
## Tips
* **Match the filter to the system** โ CRT for console games, LCD for handhelds, Game Boy for DMG games, or use Auto mode
* **Try before committing** โ Change filters mid-game from the pause menu to compare
* **Auto mode is smart** โ It picks CRT, LCD, or Game Boy filter based on the system's original screen type
* **Disable on slower devices** โ If you're getting frame drops on older hardware, use Simple CRT or disable filters
* **Per-game is powerful** โ Set Complex CRT for your SNES games but Game Boy filter for GB, without changing anything globally
* **VHS for fun** โ The animated VHS effect is great for screenshots and streams
***
## Troubleshooting
Filters not appearing in settings
Make sure you're on the latest version of Provenance. Filter options are in Settings โ Video / Display. If using a RetroArch core, additional shaders are in the RetroArch settings interface (accessible from the pause menu).
Game runs slowly with filters enabled
Try simpler filters (Simple CRT, LCD) or disable filters entirely. The VHS filter and RetroArch multi-pass shaders are the most demanding. Built-in Metal filters have minimal overhead on iPhone 11+ and Apple TV 4K.
Filter looks different in portrait vs landscape
Some filters (like CRT scanlines) are orientation-dependent. The filter adjusts to the screen orientation automatically โ horizontal scanlines in landscape, which matches real CRT behavior.
***
## See Also
* [In-Game Menu](/using-provenance/in-game-menu) โ Change filters mid-game from the pause menu
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ Filter impact on performance
* [Skins Guide](/using-provenance/skins-guide) โ Customize on-screen controls
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Cheats
Use cheat codes in Provenance โ Game Genie, Action Replay, GameShark, and Pro Action Replay across 12+ native cores and all RetroArch cores
Provenance supports cheat codes across many systems โ both through native emulator cores and RetroArch-based cores. Apply Game Genie, Action Replay, GameShark, and other cheat formats to your games.
{% hint style="info" %}
Provenance has a **native cheat UI** for managing and applying cheats. An improved UI with search and input validation is in development for a future update.
{% endhint %}
***
## How to Use Cheats
### Enabling Cheats
1. Launch a game
2. Open the **pause menu**
3. Tap **Cheats**
4. Load or enter cheat codes
5. Toggle cheats **ON** and resume gameplay
For RetroArch-based cores, cheats are also accessible via **RetroArch Settings** โ **Cheats** in the pause menu.
### Cheat Code Formats
| Format | Systems | Example |
| ----------------------------- | ------------------------------ | ---------------------- |
| **Game Genie** | NES, SNES, Genesis, Game Boy | `SXIOPO` (NES) |
| **Action Replay / GameShark** | GBA, N64, PlayStation, DS, PS2 | `0100A2C5` (GBA) |
| **Pro Action Replay** | SNES, Genesis, PS2 | `7E0DBE:09` (SNES) |
| **GameShark V3** | PS2 | Various |
| **Code Breaker** | GBA, PS2 | Various |
| **Gecko** | GameCube, Wii | Various |
| **Gateway** | 3DS | Various |
| **CWCheat** | PSP | Various |
| **Raw / Memory Address** | Most systems | `address:value` format |
### Loading Cheat Files
Cores support `.cht` cheat files:
1. Place `.cht` files in the appropriate cheats directory
2. In the cheats menu, select **Load Cheat File**
3. Browse and select your cheat file
4. Enable individual cheats from the list
{% hint style="warning" %}
Cheats modify game memory in real-time. Some cheats may cause crashes or save corruption. **Save your game before enabling cheats** as a precaution.
{% endhint %}
***
## Supported Cores & Systems
Cheat support is available in both **native cores** and **RetroArch-based cores**.
### Native Cores
| Core | System(s) | Cheat Formats |
| ------------------ | --------------------- | ----------------------------------------------- |
| **Stella** | Atari 2600 | Enabled |
| **Gambatte** | Game Boy / GBC | Game Genie, GameShark |
| **SNES9x** | SNES | Game Genie, Pro Action Replay, Gold Finger, Raw |
| **Mednafen** | GB, SNES, PlayStation | Game Genie, GameShark, Pro Action Replay |
| **VBA-M** | GBA | Action Replay, GameShark |
| **mGBA** | GBA | GameShark, Code Breaker, Pro Action Replay |
| **Mupen64Plus-NX** | N64 | Supported |
| **DuckStation** | PlayStation | GameShark |
| **PPSSPP** | PSP | CWCheat |
| **Dolphin** | GameCube / Wii | Action Replay, Gecko |
| **Azahar (Citra)** | 3DS | Gateway |
| **Play!** | PS2 | Code Breaker, GameShark V3, Pro Action Replay |
### RetroArch Cores
All **RetroArch-based cores** support cheats through the standard libretro cheat interface. This covers 80+ sub-cores including NES, SNES, Genesis, PlayStation, N64, Dreamcast, arcade systems (MAME, FinalBurn Neo), and more.
{% hint style="info" %}
If cheats aren't working with one core, try switching to an alternative core for that system. Some cores support more cheat formats than others.
{% endhint %}
***
## Finding Cheat Codes
Popular sources for cheat codes and `.cht` files:
* [**GameHacking.org**](https://gamehacking.org/) โ Large database organized by system and game
* [**RetroArch Cheats Database**](https://github.com/libretro/libretro-database/tree/master/cht) โ Official `.cht` files for RetroArch cores
* **Game-specific wikis** โ Search for "\[game name] cheat codes \[system]"
***
## Tips
* **Save before cheating** โ Create a save state before enabling cheats so you can revert if something breaks
* **Disable before saving** โ Some cheats should be turned off before creating in-game saves to avoid corrupted save data
* **One at a time** โ Enable cheats one at a time to identify which ones work and which cause issues
* **Core matters** โ If cheats don't work with one core, try a different core for that system
***
## Troubleshooting
Cheats option not available in pause menu
Not all cores support cheats. Check the [supported cores table](#native-cores) above. If your current core doesn't support cheats, try switching to a different core โ long-press the game โ Game Settings โ Core.
Cheat code doesn't work
* Verify the code matches your ROM's **region** (US/EU/JP codes are different)
* Check that the code format matches what the core expects
* Some codes only work with specific ROM versions (v1.0, v1.1, etc.)
* Try a different cheat source โ codes from some databases may be inaccurate
Game crashes after enabling cheats
Some cheat codes are unstable or incompatible with certain core versions. Disable all cheats, reload from a clean save state, and try enabling them one at a time to identify the problematic code.
***
## See Also
* [In-Game Menu](/using-provenance/in-game-menu) โ Pause menu features and shortcuts
* [Game Saves](/using-provenance/saves) โ Save before enabling cheats
* [RetroAchievements](/using-provenance/retroachievements) โ Earn achievements (cheats may disable achievements in Hardcore mode)
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ If cheats cause slowdown
***
{% hint style="info" %}
Need help with cheats? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Multiplayer
Local and online multiplayer setup โ connect multiple controllers and play together
Provenance supports **local multiplayer** for most systems and **online multiplayer** for RetroArch-based cores. Grab some controllers and play together on the couch, or connect with friends online.
***
## Local Multiplayer
### How It Works
Connect multiple Bluetooth or MFi controllers and Provenance automatically assigns them to player slots. Most systems that originally supported multiplayer work in Provenance.
### Setup
1. **Pair controllers** โ Connect 2-4 Bluetooth controllers via Settings โ Bluetooth
2. **Launch a multiplayer game**
3. **Assign players** โ From the pause menu, verify controller assignments:
* Player 1, Player 2, Player 3, Player 4
* Reassign if needed by selecting a controller and changing its player slot
{% hint style="info" %}
**On-screen controls** are always Player 1. To play local multiplayer, at least Player 2 needs a physical controller.
{% endhint %}
### Supported Player Counts
Player support depends on the system and the specific game. Here are the maximum players per system:
| System | Max Players | Notes |
| ------------------------ | ----------- | ------------------------------------------------------- |
| **NES / Famicom** | 2 | Most games support 2 players |
| **SNES / Super Famicom** | 4-5 | Up to 5 with Multitap (Bomberman, Secret of Mana) |
| **Nintendo 64** | 4 | Native 4-player (GoldenEye, Mario Kart 64, Smash Bros.) |
| **Game Boy Advance** | 4 | Link cable games via core support |
| **Genesis / Mega Drive** | 4 | Up to 4 with Team Player adapter |
| **Sega Saturn** | 6 | Up to 6 with multitap |
| **Dreamcast** | 4 | Native 4-player |
| **PlayStation** | 4-8 | Up to 8 with Multitap (varies by game) |
| **Neo Geo** | 2 | Most fighting games |
| **Atari 2600** | 2 | Most games |
| **NES / Famicom** | 2 | Standard |
| **TurboGrafx-16** | 5 | Up to 5 with Multitap |
{% hint style="info" %}
The actual player count for each game depends on the game itself, not just the system. A 2-player system can still have single-player-only games.
{% endhint %}
### Recommended Controller Setups
{% tabs %}
{% tab title="Couch Co-op (2 Players)" %}
**iPhone/iPad:**
* Player 1: On-screen controls or clip-on controller (Backbone, Kishi)
* Player 2: Bluetooth controller (DualSense, Xbox, 8BitDo)
**Apple TV:**
* Player 1 + 2: Two Bluetooth controllers
* Siri Remote can navigate menus but not play games
{% endtab %}
{% tab title="Party Gaming (3-4 Players)" %}
**Apple TV (best for groups):**
* 3-4 Bluetooth controllers
* Great for N64 (Mario Kart, Smash Bros., GoldenEye)
* PS1 Multitap games (Bomberman, Crash Bash)
**iPad (works too):**
* 3-4 Bluetooth controllers
* Larger screen helps for split-screen games
{% endtab %}
{% endtabs %}
***
## Online Multiplayer
{% hint style="warning" %}
Online multiplayer is currently available through **RetroArch-based cores only** and requires using the native RetroArch settings interface. A native Provenance UI for online play is in development.
{% endhint %}
### How to Access
1. Launch a game using a **RetroArch-based core**
2. Open the **pause menu**
3. Select **RetroArch Settings**
4. Navigate to **Netplay** settings
5. Configure host/client settings
### Online Play Options
| Option | Description |
| ---------------- | ---------------------------------------------- |
| **Host** | Start a netplay session that others can join |
| **Client** | Join an existing netplay session by IP address |
| **Relay Server** | Use a relay server if direct connection fails |
### Requirements
* Both players must use the **same ROM** (identical file, same region)
* Both players must use the **same RetroArch core**
* Stable internet connection (wired or strong WiFi recommended)
* Low latency between players for best experience
### Tips for Online Play
* **Use wired internet** when possible โ WiFi adds latency
* **Same ROM version** โ Both players must have an identical ROM file (same CRC/MD5)
* **Start fresh** โ Don't load save states before connecting
* **Fighting and puzzle games** work best โ they require less bandwidth than fast-action games
***
## Troubleshooting
Second controller not detected
* Verify the controller is paired in Settings โ Bluetooth
* Open the pause menu and check controller assignments
* Try disconnecting and reconnecting the controller
* Some controllers need a firmware update to work with iOS โ check the manufacturer's app
Controller assigned to wrong player
From the pause menu, you can reassign controllers to different player slots. If controllers keep swapping, try turning on controllers in the order you want them assigned (Player 1 first, then Player 2, etc.).
Multiplayer game only shows 1 player
* Verify the game actually supports multiplayer (not all games do)
* Some games require selecting "2 Player" mode from the game's main menu
* Check that the correct core is being used โ some cores have better multiplayer support than others
Online netplay is laggy
* Use a wired connection if possible
* Choose a server closer to both players
* Try increasing the netplay input latency frames in RetroArch settings
* Simpler games (puzzle, turn-based) are more tolerant of latency
***
## See Also
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ Controller setup and pairing
* [Supported Controllers](/using-provenance/controllers-and-controls/controllers) โ Compatible controllers list
* [Apple TV Guide](/platforms-and-performance/tvos-guide) โ Best platform for local multiplayer
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# RetroAchievements
Earn achievements in retro games with RetroAchievements integration โ badges, leaderboards, and progress tracking across thousands of classic titles
Provenance integrates with [RetroAchievements](https://retroachievements.org/) โ a community-driven project that adds achievement systems to retro games. Earn badges, track progress, and compete on leaderboards across thousands of classic titles.
***
## Overview
RetroAchievements works by monitoring game memory for specific conditions (e.g., "defeat boss X without taking damage"). When a condition is met, you earn an achievement โ just like modern console achievements.
**What you get:**
* Achievements and badges for thousands of retro games
* Progress tracking across your entire retro library
* Leaderboards and community rankings
* Mastery awards for 100% completion
{% hint style="info" %}
RetroAchievements is available for **RetroArch-based cores only**. Not all systems or games have achievement sets โ check [retroachievements.org](https://retroachievements.org/) for the full game list.
{% endhint %}
***
## Setup
### 1. Create a RetroAchievements Account
1. Visit [retroachievements.org](https://retroachievements.org/)
2. Click **Register** and create a free account
3. Note your **username** and **password**
### 2. Log In from Provenance
1. Open Provenance โ **Settings**
2. Scroll to **RetroAchievements**
3. Enter your **username** and **password**
4. Tap **Log In**
5. A confirmation appears when you're connected
### 3. Play!
Launch any supported game using a RetroArch-based core. Achievements trigger automatically during gameplay โ no additional setup needed per game.
***
## Supported Systems
RetroAchievements are available for these systems (when using RetroArch-based cores):
| System | Achievement Sets Available |
| ------------------------- | -------------------------- |
| NES / Famicom | 1,500+ games |
| SNES / Super Famicom | 1,200+ games |
| Game Boy | 600+ games |
| Game Boy Color | 400+ games |
| Game Boy Advance | 900+ games |
| Nintendo 64 | 300+ games |
| Nintendo DS | 200+ games |
| Genesis / Mega Drive | 700+ games |
| Master System | 200+ games |
| Game Gear | 100+ games |
| Sega CD | 50+ games |
| Sega Saturn | 50+ games |
| PlayStation | 900+ games |
| PSP | 300+ games |
| Atari 2600 | 100+ games |
| Atari 7800 | 50+ games |
| Atari Lynx | 30+ games |
| PC Engine / TurboGrafx-16 | 100+ games |
| Neo Geo Pocket | 30+ games |
| WonderSwan | 20+ games |
**Total:** 7,000+ games with achievement support across all systems.
{% hint style="info" %}
Achievement counts are approximate and growing โ the RetroAchievements community actively creates new achievement sets.
{% endhint %}
***
## How Achievements Work
### During Gameplay
* Achievements **pop up automatically** when conditions are met
* No need to pause or check manually
* Progress towards achievements can be tracked on the RetroAchievements website
### Hardcore Mode
RetroAchievements offers two modes:
| Mode | Save States | Cheats | Fast Forward | Leaderboards |
| ------------ | ----------- | -------- | ------------ | ------------ |
| **Softcore** | Allowed | Allowed | Allowed | No |
| **Hardcore** | Disabled | Disabled | Disabled | Yes |
**Hardcore mode** proves you earned achievements legitimately โ no save-scumming or cheating. It also enables leaderboard submissions.
### Checking Your Progress
* **In-app:** Achievements display during gameplay
* **Online:** Visit your profile at `retroachievements.org/user/[YourUsername]`
* **Stats:** Track completion percentage, points earned, and rankings
***
## Tips
* **Check game compatibility first** โ Search your game at [retroachievements.org](https://retroachievements.org/) to see if it has achievements
* **Use the correct ROM** โ Achievements are tied to specific ROM versions (usually No-Intro verified dumps). Hacked, translated, or bad dump ROMs may not trigger achievements
* **Hardcore for competition** โ Enable Hardcore mode if you want to appear on leaderboards
* **One game at a time** โ Achievement tracking works for the currently active game
***
## Troubleshooting
Achievements not triggering
* Verify you're logged in (Settings โ RetroAchievements)
* Check that you're using a **RetroArch-based core** โ native cores don't support RetroAchievements
* Verify your ROM is the correct version โ achievements require specific ROM dumps (usually No-Intro). Check the game's page on retroachievements.org for supported hashes
* Make sure the game actually has an achievement set
Can't log in
* Double-check your username and password at [retroachievements.org](https://retroachievements.org/) first
* Ensure you have an internet connection
* Try logging out and back in from Settings โ RetroAchievements
Achievements not available for my game
Not all games have achievement sets. The RetroAchievements community creates them over time. You can:
* Check if someone is working on a set at [retroachievements.org](https://retroachievements.org/)
* Request a set on the RetroAchievements forums
* Learn to create achievement sets yourself (the community welcomes new developers!)
Hardcore mode is too restrictive
You can disable Hardcore mode in the RetroArch settings (pause menu โ RetroArch Settings โ Achievements). Softcore mode lets you use save states and fast forward while still earning achievements (but no leaderboards).
***
## See Also
* [Game Saves](/using-provenance/saves) โ Battery saves and save states
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ Ensure smooth gameplay for achievement hunting
* [Cheats](/using-provenance/cheats) โ Note: cheats disable Hardcore mode achievements
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance) or check the [RetroAchievements Discord](https://discord.gg/retroachievements).
{% endhint %}
# Supported Systems
Complete list of 38+ supported gaming systems in Provenance โ compatibility, cores, save support, and feature details for every system
*๐ฑ Note: Most systems are available in the App Store. Some systems have limitations on certain devices due to performance requirements.*
{% hint style="info" %}
**Interactive Reference:** [eduo.info/pvl](https://eduo.info/pvl/) โ Community-built searchable database of all Provenance systems, cores, BIOS requirements, and supported file extensions (parsed directly from Provenance's source code).
{% endhint %}
| Manufacturer | System | Released | Emulator | Working Status | Saves | Rumble | Microphone | Camera | Gyro |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------ | ---------------------- | ------------------------------------------------- | ----- | ------ | ---------- | ------ | ---- |
| Atari | [2600 / Video Computer System](https://en.wikipedia.org/wiki/Atari_2600) | 9/11 ยท 1977 | Stella | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [5200 / SuperSystem](https://en.wikipedia.org/wiki/Atari_5200) | 11/ ยท 1982 | Atari800 | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [7800 / ProSystem](https://en.wikipedia.org/wiki/Atari_7800) | 5/ ยท 1986 | | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [Lynx](https://en.wikipedia.org/wiki/Atari_Lynx) | 9/1 ยท 1989 | Mednafen | โ๏ธ | N/A | โ๏ธ | N/A | N/A | N/A |
| | [Jaguar](https://en.wikipedia.org/wiki/Atari_Jaguar) | 11/23 ยท 1993 | Some bugs, NO CD | โ๏ธ | โ | N/A | N/A | N/A | N/A |
| Bandai | [WonderSwan](https://en.wikipedia.org/wiki/WonderSwan) | 3/4 ยท 1999 | | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [WonderSwan Color](https://en.wikipedia.org/wiki/WonderSwan) | 12/9 ยท 2000 | | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| CBS | [ColecoVision](https://en.wikipedia.org/wiki/ColecoVision) | 8/1 ยท 1982 | CrabEMU / Retroarch | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| Magnavox | [Odyssey2](https://en.wikipedia.org/wiki/Magnavox_Odyssey_2) | 9/1 ยท 1978 | O2EM | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| Mattel | [Intellivision](https://en.wikipedia.org/wiki/Intellivision) | 1/1 ยท 1980 | FreeIntv & Bliss | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| NEC | [PC Engine / TurboGrafx-16 Entertainment SuperSystem](https://en.wikipedia.org/wiki/TurboGrafx-16) | 10/30 ยท 1987 | Mednafen | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [PC Engine Super CD-ROMยฒ System / TurboGrafx-CD](https://en.wikipedia.org/wiki/TurboGrafx-16#CD-ROM_add-ons) | 12/4 ยท 1988 | Mednafen | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [PC Engine SuperGrafx](https://en.wikipedia.org/wiki/PC_Engine_SuperGrafx) | 12/8 ยท 1989 | Mednafen | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [PC-FX](https://en.wikipedia.org/wiki/PC-FX) | 12/23 ยท 1994 | Mednafen | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| Nintendo | [Famicom / Nintendo Entertainment System](https://en.wikipedia.org/wiki/Nintendo_Entertainment_System) | 7/15 ยท 1983 | | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [Famicom Disk System](https://en.wikipedia.org/wiki/Family_Computer_Disk_System) | 2/21 ยท 1986 | | โ๏ธ | โ๏ธ | N/A | โ | N/A | N/A |
| | [Game Boy](https://en.wikipedia.org/wiki/Game_Boy) | 4/21 ยท 1989 | | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [Super Famicom / Super Nintendo Entertainment System](https://en.wikipedia.org/wiki/Super_Nintendo_Entertainment_System) | 11/21 ยท 1990 | Snes9x | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [Game Boy Color](https://en.wikipedia.org/wiki/Game_Boy_Color) | 10/21 ยท 1998 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Virtual Boy](https://en.wikipedia.org/wiki/Virtual_Boy) | 7/21 ยท 1995 | Mednafen | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Nintendo 64](https://en.wikipedia.org/wiki/Nintendo_64) | 6/23 ยท 1996 | Mupen64Plus/GLideN64 | โ๏ธ | โ๏ธ | N/A | N/A | N/A | N/A |
| | [Game Boy Advance](https://en.wikipedia.org/wiki/Game_Boy_Advance) | 3/21 ยท 2001 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Pokemon mini](https://en.wikipedia.org/wiki/Pokรฉmon_Mini) | 11/16 ยท 2001 | PokeMini | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [DS](https://en.wikipedia.org/wiki/Nintendo_DS) | 9/1 ยท 2004 | threeDS | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| | [3DS](https://en.wikipedia.org/wiki/Nintendo_3DS) | 2/26 ยท 2011 | Citra | โ๏ธ | โ๏ธ | โ | โ | โ | โ |
| Panasonic | [3DO](https://en.wikipedia.org/wiki/3DO_Interactive_Multiplayer) | 3/4 ยท 1993 | FreeDO/3DO / Retroarch | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| Sega | [SG-1000](https://en.wikipedia.org/wiki/SG-1000) | 7/15 ยท 1983 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Master System](https://en.wikipedia.org/wiki/Master_System) | 10/20 ยท 1985 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Mega Drive / Genesis](https://en.wikipedia.org/wiki/Sega_Genesis) | 10/29 ยท 1988 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Game Gear](https://en.wikipedia.org/wiki/Game_Gear) | 10/6 ยท 1990 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Mega-CD / CD](https://en.wikipedia.org/wiki/Sega_CD) | 12/12 ยท 1991 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [32X](https://en.wikipedia.org/wiki/32X) | 11/21 ยท 1994 | PicoDrive | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Saturn](https://en.wikipedia.org/wiki/Sega_Saturn) | 11/22 ยท 1994 | Mednafen | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Dreamcast](https://en.wikipedia.org/wiki/Sega_Dreamcast) | 11/27 ยท 1998 | Reicast | โ ๏ธ Demanding โ requires iPhone 11+ or Apple TV 4K | โ๏ธ | โ | โ | โ | N/A |
| Smith Engineering | [Vectrex](https://en.wikipedia.org/wiki/Vectrex) | 11/1 ยท 1982 | VecX / Retroarch | โ๏ธ | โ๏ธ | โ | โ | โ | โ |
| SNK | [Neo Geo Pocket](https://en.wikipedia.org/wiki/Neo_Geo_Pocket) | 10/28 ยท 1998 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| | [Neo Geo Pocket Color](https://en.wikipedia.org/wiki/Neo_Geo_Pocket_Color) | 3/16 ยท 1999 | | โ๏ธ | N/A | N/A | N/A | N/A | N/A |
| Sony | [PlayStation](https://en.wikipedia.org/wiki/PlayStation_\(console\)) | 12/3 ยท 1994 | Mednafen | โ๏ธ | โ๏ธ | โ | โ | โ | N/A |
| | [PlayStation Portable (PSP)](https://en.wikipedia.org/wiki/PlayStation_Portable) | 12/12 ยท 2005 | PPSSPP | โ๏ธ | โ๏ธ | โ | โ | โ | โ |
| Various | [Arcade](https://en.wikipedia.org/wiki/List_of_arcade_emulators) | N/A | MAME, FinalBurn Neo | โ๏ธ | โ๏ธ | โ | โ | โ | โ |
| Watara | [SuperVision](https://en.wikipedia.org/wiki/Watara_Supervision) | N/A | | โ๏ธ | โ๏ธ | โ | โ | โ | โ |
\| **Manufacturer** | **System** | **Released** | **Emulator** | **Status** | **Saves** | **Rumble** | **Microphone** | **Camera** | **Gyro** |
For system requirements, refer to [BIOS Requirements](/getting-started/bios-requirements). For supported file formats, refer to [Formatting ROMs](/using-provenance/roms/formatting-roms).
## Systems in development
**โ ๏ธ Please do not ask when these will be ready โ ๏ธ**
| Manufacturer | System | Released | Emulator | Status | Saves | Rumble | Microphone | Camera | Gyro |
| ---------------- | ----------------------------------------------------------------- | ------------ | ------------- | ------------------------------------- | --------- | ---------- | -------------- | ---------- | -------- |
| Various | [TIC-80](https://en.wikipedia.org/wiki/TIC-80) | 4/4 ยท 2017 | TIC-80 | โ ๏ธ In Development | โ | โ | โ | โ | N/A |
| Various | [FinalBurn Neo](https://en.wikipedia.org/wiki/FinalBurn_Neo) | N/A | FinalBurn Neo | โ ๏ธ In Development | โ | โ | โ | โ | N/A |
| Welback Holdings | [Mega Duck / Cougar Boy](https://en.wikipedia.org/wiki/Mega_Duck) | N/A | SameDuck | โ ๏ธ In Development | โ | โ | โ | โ | N/A |
| Atari | [Atari ST](https://en.wikipedia.org/wiki/Atari_ST) | 6/ ยท 1985 | Hatari | โ ๏ธ In Development | โ | โ | โ | โ | N/A |
| Sony | [PlayStation 2](https://en.wikipedia.org/wiki/PlayStation_2) | 3/4 ยท 2000 | Play! | โ ๏ธ (Requires JIT, Graphical Glitches) | โ๏ธ | โ | โ | โ | โ |
| **Manufacturer** | **System** | **Released** | **Emulator** | **Status** | **Saves** | **Rumble** | **Microphone** | **Camera** | **Gyro** |
# System Reference (Auto-Generated)
Auto-generated system and core reference from Provenance source code
{% hint style="info" %}
**Auto-generated** from [Provenance source code](https://github.com/Provenance-Emu/Provenance) on August 03, 2026. Do not edit manually โ changes will be overwritten by the [sync workflow](https://github.com/Provenance-Emu/wiki/actions/workflows/sync-from-source.yml).
{% endhint %}
**Quick links:** [Systems](#systems) | [BIOS Requirements](#bios-requirements) | [File Extensions](#supported-file-extensions) | [Core Matrix](#core-to-system-matrix) | [Cheat Support](#cheat-support) | [Skin Identifiers](#skin-identifiers)
***
## Systems
Provenance supports **49 systems** (24 additional in development or disabled).
| Manufacturer | System | Short | Year | Bits | Screen | Portable | CD | Rumble | BIOS |
| ----------------- | ------------------------- | ----------------- | ---- | ---- | --------- | -------- | --- | ------ | ----------- |
| Atari | Atari 2600 | 2600 | 1977 | 8 | CRT | | | | |
| Atari | Atari 5200 | 5200 | 1982 | 8 | CRT | | | | โ
Required |
| Atari | Atari 8bit Computer | 8Bit | 1982 | 8 | CRT | | | | โ
Required |
| Atari | Atari 7800 | 7800 | 1986 | 8 | CRT | | | | |
| Atari | Atari Lynx | LYNX | 1989 | 8 | ColorLCD | Yes | | | โ
Required |
| Atari | Atari Jaguar | Jaguar | 1993 | 32 | CRT | | | | ๐ถ Optional |
| Atari | Atari Jaguar CD | Jaguar CD | 1993 | 32 | CRT | | Yes | | ๐ถ Optional |
| Bandai | WonderSwan | WS | 1999 | 16 | DotMatrix | Yes | | | |
| Bandai | WonderSwan | WSC | 2000 | 16 | ColorLCD | Yes | | | |
| CBS | CBS ColecoVision | ColecoVision | 1982 | 8 | CRT | | | | โ
Required |
| Capcom | CPS-1 | CPS1 | 0000 | 32 | CRT | | | | |
| Capcom | CPS-2 | CPS2 | 0000 | 32 | CRT | | | | |
| Capcom | CPS-3 | CPS3 | 0000 | 32 | CRT | | | | |
| Enterprise | Enterprise 128 | ep128 | 1985 | 8 | CRT | | | | |
| Libretro | RetroArch | RetroArch | 2010 | 64 | CRT | Yes | Yes | | |
| MAME | MAME | Arcade | 1997 | 32 | MonoLCD | | | | ๐ถ Optional |
| Magnavox | Magnavox Odyssey2 | Odyssey2 | 1978 | 8 | CRT | | | | โ
Required |
| Mattel | Mattel Intellivision | Intellivision | 1979 | 8 | CRT | | | | โ
Required |
| NEC | PC98 | PC98 | 1982 | 16 | CRT | | Yes | | |
| NEC | TurboGrafx-16 | TG16 | 1987 | 16 | CRT | | | | |
| NEC | TurboGrafx-CD | TG16CD | 1988 | 16 | CRT | | Yes | | โ
Required |
| NEC | SuperGrafx | SGRFX | 1989 | 16 | CRT | | | | |
| NEC | PCFX | PCFX | 1994 | 32 | CRT | | Yes | | โ
Required |
| Nintendo | Nintendo | NES | 1983 | 8 | CRT | | | | |
| Nintendo | Famicom Disk System | FDS | 1986 | 8 | CRT | | | | โ
Required |
| Nintendo | Game Boy | GB | 1989 | 8 | DotMatrix | Yes | | | |
| Nintendo | Super Nintendo | SNES | 1990 | 16 | CRT | | | | |
| Nintendo | Virtual Boy | Virtual Boy | 1995 | 32 | MonoLCD | Yes | | | |
| Nintendo | Nintendo 64 | N64 | 1996 | 64 | CRT | | | Yes | |
| Nintendo | Game Boy Color | GBC | 1998 | 8 | ColorLCD | Yes | | | |
| Nintendo | Game Boy Advance | GBA | 2001 | 32 | ColorLCD | Yes | | | ๐ถ Optional |
| Nintendo | Pokรฉmon mini | Pm | 2001 | 8 | DotMatrix | Yes | | | ๐ถ Optional |
| Panasonic | 3DO | 3DO | 1993 | 32 | CRT | | | | โ
Required |
| SNK | Neo Geo | NeoGeo | 1990 | 24 | MonoLCD | | | | โ
Required |
| SNK | Neo Geo CD | NeoGeoCD | 1994 | 24 | CRT | | Yes | | โ
Required |
| SNK | Neo Geo Pocket | NGP | 1998 | 8 | MonoLCD | Yes | | | |
| SNK | Neo Geo Pocket Color | NeoGeoPocketColor | 1999 | 16 | ColorLCD | Yes | | | |
| Sega | SG-1000 | SG-1000 | 1983 | 8 | CRT | | | | |
| Sega | Master System | SMS | 1985 | 8 | CRT | | | | |
| Sega | Genesis | SG | 1988 | 16 | CRT | | | | |
| Sega | Game Gear | Game Gear | 1990 | 8 | ColorLCD | Yes | | | |
| Sega | Sega CD | SCD | 1991 | 16 | CRT | | Yes | | โ
Required |
| Sega | 32X | 32X | 1994 | 32 | CRT | | | | |
| Sega | Saturn | Saturn | 1995 | 32 | CRT | | Yes | | โ
Required |
| Smith Engineering | Smith Engineering Vectrex | Vectrex | 1982 | 8 | CRT | | | | |
| Sony | PlayStation | PSX | 1994 | 32 | CRT | | Yes | Yes | โ
Required |
| Various | Game Music | GME | 1980 | 0 | CRT | | | | |
| Watara | Supervision | Supervision | 1992 | 8 | DotMatrix | Yes | | | |
| ZX | ZX Spectrum | Z80 | 1980 | 16 | CRT | | | | |
Systems in Development / Disabled
| Manufacturer | System | Year | Status |
| ----------------------- | -------------------- | ---- | ------------------ |
| Nintendo | 3DS | 2011 | In development |
| Apple | Apple II | 1977 | App Store disabled |
| Atari | Atari ST | 1985 | In development |
| Sammy | Atomiswave | 2003 | In development |
| Philips | CD-i | 2010 | App Store disabled |
| Commodore International | Commodore 64 | 1982 | In development |
| Nintendo | DS | 2004 | In development |
| Id Software | Doom | 1993 | In development |
| Sega | Dreamcast | 1999 | In development |
| Nintendo | GameCube | 2001 | In development |
| IBM | IBM PC DOS | 1980 | In development |
| Microsoft | MSX | 1983 | In development |
| Microsoft | MSX2 | 1983 | In development |
| Apple | Macintosh | 1984 | App Store disabled |
| Sega | NAOMI | 1998 | In development |
| Sega | NAOMI 2 | 2000 | In development |
| Palm | PalmOS | 2010 | App Store disabled |
| Sony | PlayStation 2 | 2000 | In development |
| Sony | PlayStation Portable | 2004 | In development |
| Id Software | Quake | 1996 | App Store disabled |
| Id Software | Quake II | 1996 | App Store disabled |
| Nesbox | TIC-80 | 2017 | In development |
| Nintendo | Wii | 2006 | App Store disabled |
| Id Software | Wolfenstein 3D | 1992 | App Store disabled |
***
## BIOS Requirements
{% hint style="warning" %}
**DO NOT** ask us where to obtain BIOS files. Distributing BIOS files violates copyright law.
{% endhint %}
| System | File | Description | MD5 | Size | Status |
| -------------------- | ------------------------------------ | ------------------------------------------------------- | ---------------------------------- | ------ | ----------- |
| Atari 5200 | `5200.rom` | Atari 5200 BIOS | `281f20ea4320404ec820fb7ec0693b38` | 2 KB | โ
Required |
| Atari 8bit Computer | `ATARIBAS.ROM` | BIOS for the BASIC interpreter | `0bac0c6a50104045d902df4503a4c30b` | 8 KB | โ
Required |
| | `ATARIXL.ROM` | BIOS for Atari XL/XE OS | `06daac977823773a3eea3422fd26a703` | 16 KB | โ
Required |
| | `ATARIOSA.ROM` | BIOS for Atari 400/800 PAL | `eb1f32f5d9f382db1bbfb8d7f9cb343a` | 10 KB | โ
Required |
| | `ATARIOSB.ROM` | BIOS for Atari 400/800 NTSC | `a3e8d617c95d08031fe1b20d541434b2` | 10 KB | โ
Required |
| Atari Lynx | `lynxboot.img` | Lynx boot ROM | `fcd403db69f54290b51035d82f835e7b` | 512 B | โ
Required |
| Atari Jaguar | `jagboot.rom` | Jaguar BIOS | `bcfe348c565d9dedb173822ee6850dea` | 128 KB | ๐ถ Optional |
| Atari Jaguar CD | `jagboot.rom` | Jaguar BIOS | `bcfe348c565d9dedb173822ee6850dea` | 128 KB | ๐ถ Optional |
| | `[BIOS] Atari Jaguar CD (World).j64` | Jaguar CD BIOS | `77cd95c7ad06a39f4c59995094aa10f9` | 256 KB | ๐ถ Optional |
| CBS ColecoVision | `coleco.rom` | ColecoVision BIOS | `2c66f5911e5b42b8ebe113403548eee7` | 8 KB | โ
Required |
| MAME | `neogeo.zip` | NeoGeo BIOS (MAME 0.258 BIOS) | `00dad01abdbf8ea9e79ad2fe11bdb182` | 1.8 MB | ๐ถ Optional |
| Magnavox Odyssey2 | `o2rom.bin` | Odyssey2 BIOS - G7000 model BIOS | `562d5ebf9e030a40d6fabfc2f33139fd` | 1 KB | โ
Required |
| | `c52.bin` | Videopac+ French BIOS - G7000 model | `f1071cdb0b6b10dde94d3bc8a6146387` | 1 KB | ๐ถ Optional |
| | `g7400.bin` | Videopac+ European BIOS - G7400 model | `c500ff71236068e0dc0d0603d265ae76` | 1 KB | ๐ถ Optional |
| | `jopac.bin` | Videopac+ French BIOS - G7400 model | `279008e4a0db2dc5f1c048853b033828` | 1 KB | ๐ถ Optional |
| Mattel Intellivision | `exec.bin` | Executive ROM | `62e761035cb657903761800f4437b8af` | 8 KB | โ
Required |
| | `grom.bin` | Graphics ROM | `0cd5946c6473e42e8e4c2137785e427f` | 2 KB | โ
Required |
| | `ecs.bin` | Entertainment Computer System (ECS) ROM | `2e72a9a2b897d330a35c8b07a6146c52` | 24 KB | ๐ถ Optional |
| | `ivoice.bin` | Intellivoice RESROM | `d5530f74681ec6e0f282dab42e6b1c5f` | 2 KB | ๐ถ Optional |
| TurboGrafx-CD | `syscard3.pce` | TurboGrafx-CD/PC Engine CD BIOS | `ff1a674273fe3540ccef576376407d1d` | 256 KB | โ
Required |
| PCFX | `pcfx.rom` | PC-FX BIOS | `08e36edbea28a017f79f8d4f7ff9b6d7` | 1.0 MB | โ
Required |
| Famicom Disk System | `disksys.rom` | Disk System BIOS | `ca30b50f880eb660a320674ed365ef7a` | 8 KB | โ
Required |
| Game Boy Advance | `GBA.BIOS` | Game Boy Advance BIOS | `a860e8c0b6d573d191e4ec7db1b1e4f6` | 16 KB | ๐ถ Optional |
| Pokรฉmon mini | `bios.min` | Pokรฉmon mini BIOS | `1e4fb124a3a886865acb574f388c803d` | 4 KB | ๐ถ Optional |
| 3DO | `panafz1.bin` | Panasonic FZ-1 BIOS | `f47264dd47fe30f73ab3c010015c155b` | 1.0 MB | ๐ถ Optional |
| | `panafz10.bin` | Panasonic FZ-10 BIOS | `51f2f43ae2f3508a14d9f56597e2d3ce` | 1.0 MB | โ
Required |
| | `panafz10-norsa.bin` | Panasonic FZ-10 BIOS (encryption check disabled) | `1477bda80dc33731a65468c1f5bcbee9` | 1.0 MB | ๐ถ Optional |
| | `panafz10e-anvil.bin` | Panasonic FZ-10E ANVIL BIOS | `a48e6746bd7edec0f40cff078f0bb19f` | 1.0 MB | ๐ถ Optional |
| | `panafz10e-anvil-norsa.bin` | Panasonic FZ-10E ANVIL BIOS (encryption check disabled) | `cf11bbb5a16d7af9875cca9de9a15e09` | 1.0 MB | ๐ถ Optional |
| | `goldstar.bin` | Goldstar GDO-101M BIOS | `8639fd5e549bd6238cfee79e3e749114` | 1.0 MB | ๐ถ Optional |
| | `sanyotry.bin` | Sanyo Try IMP-21J BIOS | `35fa1a1ebaaeea286dc5cd15487c13ea` | 1.0 MB | ๐ถ Optional |
| | `3do_arcade_saot.bin` | 3DO Arcade โ Shootout at Old Tucson BIOS | `8970fc987ab89a7f64da9f8a8c4333ff` | 512 KB | ๐ถ Optional |
| | `panafz1-kanji.bin` | Panasonic FZ-1 Kanji font ROM | `b8dc97f778a6245c58e064b0312e8281` | 912 KB | ๐ถ Optional |
| | `panafz10ja-anvil-kanji.bin` | Panasonic FZ-10JA ANVIL Kanji font ROM | `428577250f43edc902ea239c50d2240d` | 1.0 MB | ๐ถ Optional |
| | `panafz1j.bin` | Panasonic FZ-1J BIOS | `a496cfdded3da562759be3561317b605` | 1.0 MB | ๐ถ Optional |
| | `panafz1j-norsa.bin` | Panasonic FZ-1J BIOS (encryption check disabled) | `f6c71de7470d16abe4f71b1444883dc8` | 1.0 MB | ๐ถ Optional |
| | `panafz1j-kanji.bin` | Panasonic FZ-1J Kanji font ROM | `c23fb5d5e6bb1c240d02cf968972be37` | 1.0 MB | ๐ถ Optional |
| | `rom2.rom` | Japanese character ROM (FreeDO / legacy filename) | `428577250f43edc902ea239c50d2240d` | 1.0 MB | ๐ถ Optional |
| Neo Geo | `neogeo.zip` | NeoGeo BIOS (MAME 0.258 BIOS) | `00dad01abdbf8ea9e79ad2fe11bdb182` | 1.8 MB | ๐ถ Optional |
| | `aes.zip` | NeoGeo AES BIOS | `ad9585c72130c56f04ae26aae87c289d` | 830 KB | ๐ถ Optional |
| Neo Geo CD | `neocdz.zip` | Neo Geo CD BIOS | `f39572af7584738b76f87a8e88cc5540` | 512 KB | โ
Required |
| | `neogeo.zip` | NeoGeo BIOS (MAME 0.258 BIOS, for CD titles) | `00dad01abdbf8ea9e79ad2fe11bdb182` | 1.8 MB | ๐ถ Optional |
| Sega CD | `bios_CD_E.bin` | Mega-CD Model 1 (EU 921027) BIOS 1.00 | `e66fa1dc5820d254611fdcdba0662372` | 128 KB | โ
Required |
| | `bios_CD_U.bin` | Sega CD Model 1 (US 921011) BIOS 1.10 | `2efd74e3232ff260e371b99f84024f7f` | 128 KB | โ
Required |
| | `bios_CD_J.bin` | Mega-CD Model 1 (JP 911217) BIOS 1.00p | `bdeb4c47da613946d422d97d98b21cda` | 128 KB | โ
Required |
| Saturn | `saturn_bios.bin` | Sega Saturn BIOS v1.00 (JAP/US) | `af5828fdff51384f99b3c4926be27762` | 512 KB | โ
Required |
| | `mpr-17933.bin` | Sega Saturn BIOS (EU) | `3240872c70984b6cbfda1586cab68dbe` | 512 KB | โ
Required |
| | `sega_101.bin` | Sega Saturn BIOS v1.01 (JAP) | `85ec9ca47d8f6807718151cbcca8b964` | 512 KB | โ
Required |
| PlayStation | `scph5500.bin` | PlayStation (JP) SCPH-5500 BIOS | `8dd7d5296a650fac7319bce665a6a53c` | 512 KB | โ
Required |
| | `scph5501.bin` | PlayStation (NA) SCPH-5501 BIOS | `490f666e1afb15b7362b406ed1cea246` | 512 KB | โ
Required |
| | `scph5502.bin` | PlayStation (EU) SCPH-5502 BIOS | `32736f17079d0b2b7024407c39bd3050` | 512 KB | โ
Required |
***
## Supported File Extensions
| System | Extensions |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Atari 2600 | `.a26`, `.bin`, `.zip` |
| Atari 5200 | `.a52`, `.atr`, `.atx`, `.bin`, `.cas`, `.cdm`, `.xex`, `.xfd`, `.zip` |
| Atari 8bit Computer | `.a52`, `.atr`, `.atx`, `.bas`, `.bin`, `.cas`, `.cdm`, `.xex`, `.xfd`, `.zip` |
| Atari 7800 | `.a78`, `.bin`, `.cdf`, `.zip` |
| Atari Lynx | `.lnx`, `.o`, `.zip` |
| Atari Jaguar | `.abs`, `.bin`, `.cof`, `.j64`, `.jag`, `.prg`, `.rom`, `.zip` |
| Atari Jaguar CD | `.cdi`, `.cue` |
| WonderSwan | `.ws` |
| WonderSwan | `.wsc` |
| CBS ColecoVision | `.col`, `.cv`, `.rom` |
| CPS-1 | `.zip` |
| CPS-2 | `.zip` |
| CPS-3 | `.zip` |
| Enterprise 128 | `.128`, `.bas`, `.cdt`, `.dsk`, `.dtf`, `.img`, `.tap`, `.trn` |
| RetroArch | `.CFG`, `.cfg`, `.opt` |
| MAME | `.7z`, `.chd`, `.cmd`, `.zip` |
| Magnavox Odyssey2 | `.od2`, `.ody` |
| Mattel Intellivision | `.bin`, `.int`, `.rom` |
| PC98 | `.2HD`, `.2hd`, `.88D`, `.88d`, `.98D`, `.98d`, `.CMD`, `.D88`, `.D98`, `.FDD`, `.FDI`, `.HDD`, `.HDI`, `.HDM`, `.LZH`, `.NHD`, `.RAR`, `.ZIP`, `.cmd`, `.d88`, `.d98`, `.dup`, `.fdd`, `.fdi`, `.hdd`, `.hdi`, `.hdm`, `.hdn`, `.lzh`, `.nhd`, `.rar`, `.tfd`, `.thd`, `.xdf`, `.zip` |
| TurboGrafx-16 | `.pce`, `.zip` |
| TurboGrafx-CD | `.ccd`, `.chd`, `.cue`, `.m3u`, `.toc`, `.zip` |
| SuperGrafx | `.sgx`, `.zip` |
| PCFX | `.ccd`, `.chd`, `.cue`, `.zip` |
| Nintendo | `.nes`, `.unf`, `.unif`, `.zip` |
| Famicom Disk System | `.fds` |
| Game Boy | `.gb`, `.zip` |
| Super Nintendo | `.fig`, `.sfc`, `.smc`, `.snes`, `.zip` |
| Virtual Boy | `.bin`, `.vb`, `.vboy`, `.zip` |
| Nintendo 64 | `.n64`, `.z64`, `.zip` |
| Game Boy Color | `.gbc`, `.sgb`, `.zip` |
| Game Boy Advance | `.agb`, `.bin`, `.gba`, `.zip` |
| Pokรฉmon mini | `.min` |
| 3DO | `.chd`, `.cue`, `.iso`, `.m3u`, `.zip` |
| Neo Geo | `.cmd`, `.neo`, `.ng`, `.zip` |
| Neo Geo CD | `.chd`, `.cue`, `.iso`, `.m3u` |
| Neo Geo Pocket | `.ngp`, `.zip` |
| Neo Geo Pocket Color | `.ngc`, `.ngpc`, `.npc`, `.zip` |
| SG-1000 | `.sg` |
| Master System | `.sms` |
| Genesis | `.68k`, `.bin`, `.bms`, `.chd`, `.gen`, `.gg`, `.m3u`, `.md`, `.mdx`, `.sgd`, `.smd`, `.sms`, `.zip` |
| Game Gear | `.gg`, `.zip` |
| Sega CD | `.chd`, `.cue`, `.iso`, `.zip` |
| 32X | `.32X`, `.32x` |
| Saturn | `.ccd`, `.chd`, `.cue`, `.iso`, `.m3u`, `.mds`, `.toc`, `.zip` |
| Smith Engineering Vectrex | `.vec` |
| PlayStation | `.ccd`, `.chd`, `.cue`, `.m3u`, `.pbp`, `.toc`, `.zip` |
| Game Music | `.ay`, `.gbs`, `.gym`, `.hes`, `.kss`, `.nsf`, `.nsfe`, `.sap`, `.spc`, `.vgm`, `.vgz` |
| Supervision | `.bin`, `.sv` |
| ZX Spectrum | `.tzx`, `.z80` |
***
## Core-to-System Matrix
Shows which emulator cores are available for each system.
| System | Available Cores | Versions |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Atari 2600 | [Atari 2600 (RetroArch)](https://docs.libretro.com/library/stella/), [Stella](https://stella-emu.github.io), [Stella (Current) (RetroArch)](https://stella-emu.github.io), [Stella 2023 (RetroArch)](https://stella-emu.github.io) | 6.6, 3.4.1, Nightly, Nightly |
| Atari 5200 | [Atari 5200 (RetroArch)](https://docs.libretro.com/library/atari800/), [Atari 800](https://atari800.github.io) | 3.1.0, 3.1.0 |
| Atari 8bit Computer | [Atari 400/800/600XL/800XL/130XE (RetroArch)](https://docs.libretro.com/library/atari800/), [Atari 800](https://atari800.github.io) | 3.1.0, 3.1.0 |
| Atari 7800 | [Atari 7800 (RetroArch)](https://docs.libretro.com/library/prosystem/), [ProSystem](https://gstanton.github.io/ProSystem1_3/) | 1.3e, 1.3 |
| Atari Lynx | [Atari Lynx (RetroArch)](https://docs.libretro.com/library/beetle_lynx/), [Handy (Atari Lynx) (RetroArch)](https://github.com/libretro/libretro-handy), [Mednafen](https://mednafen.github.io) | 1.24.0, Nightly, 1.32.1 |
| Atari Jaguar | [Atari Jaguar (Virtual Jaguar) (RetroArch)](https://docs.libretro.com/library/virtual_jaguar/) | 2.1.0 |
| Atari Jaguar CD | [Atari Jaguar (Virtual Jaguar) (RetroArch)](https://docs.libretro.com/library/virtual_jaguar/) | 2.1.0 |
| WonderSwan | [Beetle WonderSwan (RetroArch)](https://github.com/libretro/beetle-wswan-libretro), [Mednafen](https://mednafen.github.io) | Nightly, 1.32.1 |
| WonderSwan | [Beetle WonderSwan (RetroArch)](https://github.com/libretro/beetle-wswan-libretro), [Mednafen](https://mednafen.github.io) | Nightly, 1.32.1 |
| CBS ColecoVision | [Gearcoleco](https://github.com/drhelius/Gearcoleco), [Gearcoleco (RetroArch)](https://github.com/drhelius/Gearcoleco), [MSX/SVI/ColecoVision/SG-1000 (blueMSX) (RetroArch)](https://github.com/libretro/blueMSX) | 1.0.1, Nightly, Nightly |
| CPS-1 | [FBAlpha CPS1 (RetroArch)](https://github.com/libretro/fbalpha) | Nightly |
| CPS-2 | [FBAlpha CPS2 (RetroArch)](https://github.com/libretro/fbalpha) | Nightly |
| CPS-3 | [FBAlpha CPS3 (RetroArch)](https://github.com/libretro/fbalpha) | Nightly |
| Enterprise 128 | [EP128Emu](http://ep128emu.sourceforge.net/about.html) | 2.0.11 |
| RetroArch | [2048 (RetroArch)](https://github.com/libretro/2048), [Atari 400/800/600XL/800XL/130XE (RetroArch)](https://docs.libretro.com/library/atari800/), [Commodore - C128 (RetroArch)](https://github.com/libretro/vice), [Commodore - C64 (RetroArch)](https://github.com/libretro/vice), [Commodore - C64 (x64sc) (RetroArch)](https://github.com/libretro/vice), [Commodore - PET (RetroArch)](https://github.com/libretro/vice), [Commodore - Plus/4 (RetroArch)](https://github.com/libretro/vice), [Commodore - VIC-20 (RetroArch)](https://github.com/libretro/vice), [DosBox-Pure (RetroArch)](https://github.com/schellingb/dosbox-pure), [MAME (Current) (RetroArch)](https://docs.libretro.com/development/cores/core-specific/mame/), [MSX/SVI/ColecoVision/SG-1000 (blueMSX) (RetroArch)](https://github.com/libretro/blueMSX), [MelonDS DS (RetroArch)](https://docs.libretro.com/library/melonds_ds/), [Mr.Boom (RetroArch)](https://docs.libretro.com/library/mrboom/), [NooDS (RetroArch)](https://github.com/Hydr8gon/NooDS), [Opera (RetroArch)](https://github.com/libretro/opera-libretro), [PUAE (Amiga) (RetroArch)](https://github.com/libretro/libretro-uae), [PUAE 2021 (Amiga) (RetroArch)](https://github.com/libretro/libretro-uae), [PalmOS (Mu) (RetroArch)](https://docs.libretro.com/library/mu/), [Philips - P2000T (RetroArch)](https://github.com/libretro/m2000), [Rick Dangerous (RetroArch)](https://github.com/libretro/xrick), [Sharp X1 (RetroArch)](https://github.com/libretro/x1), [Sinclair - ZX Spectrum (RetroArch)](https://github.com/libretro/fuse) | Nightly, 3.1.0, Nightly, Nightly, Nightly, Nightly, Nightly, Nightly, 0.9.2, v0.258, Nightly, git, Nightly, git, 1.0.0, Nightly, Nightly, Nightly, Nightly, Nightly, Nightly, Nightly |
| MAME | [FBNeo (RetroArch)](https://github.com/libretro/FBNeo), [MAME (Current) (RetroArch)](https://docs.libretro.com/development/cores/core-specific/mame/), [MAME 2000 (RetroArch)](https://github.com/libretro/mame2000-libretro), [MAME 2003 (RetroArch)](https://github.com/libretro/mame2003-libretro), [MAME 2003 Plus (RetroArch)](https://github.com/libretro/mame2003-plus-libretro), [MAME 2010 (RetroArch)](https://github.com/libretro/mame2010-libretro) | v1.0.0.02, v0.258, v0.139, v0.139, v0.139, v0.139 |
| Magnavox Odyssey2 | [O2EM (Odyssey 2) (RetroArch)](https://github.com/libretro/libretro-o2em) | Nightly |
| Mattel Intellivision | [FreeINTV (RetroArch)](https://github.com/libretro/FreeIntv), [FreeIntv](https://github.com/libretro/FreeIntv) | Nightly, 2018.1.5 |
| PC98 | [NP2Kai (PC-98) (RetroArch)](https://github.com/AZO234/NP2kai) | rev.22-145 |
| TurboGrafx-16 | [Beetle PC Engine (RetroArch)](https://github.com/libretro/beetle-pce-libretro), [Beetle PC Engine Fast (RetroArch)](https://github.com/libretro/beetle-pce-fast-libretro), [Beetle Supergrafx (PC Engine) (RetroArch)](https://github.com/libretro/beetle-supergrafx-libretro), [Mednafen](https://mednafen.github.io) | Nightly, Nightly, v1.29.0, 1.32.1 |
| TurboGrafx-CD | [Beetle PC Engine (RetroArch)](https://github.com/libretro/beetle-pce-libretro), [Beetle PC Engine Fast (RetroArch)](https://github.com/libretro/beetle-pce-fast-libretro), [Beetle Supergrafx (PC Engine) (RetroArch)](https://github.com/libretro/beetle-supergrafx-libretro), [Mednafen](https://mednafen.github.io) | Nightly, Nightly, v1.29.0, 1.32.1 |
| SuperGrafx | [Beetle PC Engine (RetroArch)](https://github.com/libretro/beetle-pce-libretro), [Beetle Supergrafx (PC Engine) (RetroArch)](https://github.com/libretro/beetle-supergrafx-libretro), [Mednafen](https://mednafen.github.io) | Nightly, v1.29.0, 1.32.1 |
| PCFX | [Beetle PC-FX (RetroArch)](https://github.com/libretro/beetle-pcfx-libretro), [Mednafen](https://mednafen.github.io) | Nightly, 1.32.1 |
| Nintendo | [FCEUX](http://sourceforge.net/projects/fceultra/), [FCEUmm (RetroArch)](https://github.com/libretro/fceumm), [Mednafen](https://mednafen.github.io), [Nestopia (RetroArch)](https://github.com/libretro/nestopia), [QuickNES (RetroArch)](https://github.com/libretro/QuickNES_Core) | 2.6.2, nightly, 1.32.1, v1.51.1, Nightly |
| Famicom Disk System | [FCEUX](http://sourceforge.net/projects/fceultra/), [FCEUmm (RetroArch)](https://github.com/libretro/fceumm), [Mednafen](https://mednafen.github.io), [Nestopia (RetroArch)](https://github.com/libretro/nestopia) | 2.6.2, nightly, 1.32.1, v1.51.1 |
| Game Boy | [Gambatte](https://github.com/sinamas/gambatte), [Gambatte (RetroArch)](https://github.com/libretro/gambatte-libretro), [Mednafen](https://mednafen.github.io), [SameBoy (RetroArch)](https://github.com/libretro/SameBoy), [TGBDual](https://github.com/libretro/tgbdual-libretro), [VBA-M (RetroArch)](https://docs.libretro.com/library/vba_m/), [mGBA (RetroArch)](https://github.com/libretro/mgba) | 0.5.0, Nightly, 1.32.1, v0.14.7, v0.8.3, nightly, v0.10-dev |
| Super Nintendo | [BSNES (RetroArch)](https://docs.libretro.com/library/bsnes/), [BSNES HD (RetroArch)](https://docs.libretro.com/library/bsnes/), [BSNES Mercury (Accuracy) (RetroArch)](https://docs.libretro.com/library/bsnes/), [BSNES Mercury (Balanced) (RetroArch)](https://docs.libretro.com/library/bsnes/), [BSNES Mercury (Performance) (RetroArch)](https://github.com/libretro/bsnes-mercury), [Beetle SNES (RetroArch)](https://github.com/libretro/beetle-bsnes-libretro), [Mednafen](https://mednafen.github.io), [Snes9x](http://www.snes9x.com), [Snes9x (RetroArch)](https://docs.libretro.com/library/snes9x/), [Snes9x 2002 (RetroArch)](https://github.com/libretro/snes9x2002), [Snes9x 2005 (RetroArch)](https://github.com/libretro/snes9x2005), [Snes9x 2005 Plus (RetroArch)](https://github.com/libretro/snes9x2005), [Snes9x 2010 (RetroArch)](https://github.com/libretro/snes9x2010), [Snesticle](https://github.com/iaddis/SNESticle) | nightly, nightly, nightly, nightly, nightly, Nightly, 1.32.1, 1.60, 1.61, Nightly, Nightly, Nightly, Nightly, 1.0 |
| Virtual Boy | [Beetle VB (RetroArch)](https://github.com/libretro/beetle-vb-libretro), [Mednafen](https://mednafen.github.io) | v0.9.36.1, 1.32.1 |
| Nintendo 64 | [Mupen64Plus](https://github.com/mupen64plus), [Mupen64Plus-Next](https://github.com/libretro/mupen64plus-libretro-nx), [Mupen64Plus-Next (RetroArch)](https://github.com/libretro/mupen64plus-libretro-nx) | 2.5, 2.4, 2024.10.29 |
| Game Boy Color | [Gambatte](https://github.com/sinamas/gambatte), [Gambatte (RetroArch)](https://github.com/libretro/gambatte-libretro), [Mednafen](https://mednafen.github.io), [SameBoy (RetroArch)](https://github.com/libretro/SameBoy), [TGBDual](https://github.com/libretro/tgbdual-libretro), [VBA-M (RetroArch)](https://docs.libretro.com/library/vba_m/), [mGBA (RetroArch)](https://github.com/libretro/mgba) | 0.5.0, Nightly, 1.32.1, v0.14.7, v0.8.3, nightly, v0.10-dev |
| Game Boy Advance | [Beetle GBA (RetroArch)](https://github.com/libretro/beetle-gba-libretro), [Mednafen](https://mednafen.github.io), [VBA Next (RetroArch)](https://github.com/libretro/vba-next), [VBA-M (RetroArch)](https://docs.libretro.com/library/vba_m/), [VisualBoyAdvance](https://sourceforge.net/projects/vba/), [gpSP (RetroArch)](https://github.com/libretro/gpsp), [mGBA](https://mgba.io/), [mGBA (RetroArch)](https://github.com/libretro/mgba) | v0.9.36, 1.32.1, Nightly, nightly, 1.8.0, Nightly, 0.10.3, v0.10-dev |
| Pokรฉmon mini | [PokeMini](http://sourceforge.net/projects/pokemini/), [PokeMini (RetroArch)](https://docs.libretro.com/library/pokemini/) | v0.60, Nightly |
| 3DO | [Opera](https://github.com/libretro/opera-libretro), [Opera (RetroArch)](https://github.com/libretro/opera-libretro) | 1.0.0, 1.0.0 |
| Neo Geo | [FBNeo (RetroArch)](https://github.com/libretro/FBNeo), [Geolith (RetroArch)](https://github.com/libretro/geolith-libretro), [MAME (Current) (RetroArch)](https://docs.libretro.com/development/cores/core-specific/mame/) | v1.0.0.02, 2015.02.16, v0.258 |
| Neo Geo CD | [NeoCD (RetroArch)](https://github.com/libretro/neocd_libretro) | Nightly |
| Neo Geo Pocket | [Beetle Neopop (RetroArch)](https://docs.libretro.com/library/beetle_neopop/), [Mednafen](https://mednafen.github.io), [RACE (RetroArch)](https://docs.libretro.com/library/race/) | v0.9.36.1, 1.32.1, v2.16 |
| Neo Geo Pocket Color | [Beetle Neopop (RetroArch)](https://docs.libretro.com/library/beetle_neopop/), [Mednafen](https://mednafen.github.io), [RACE (RetroArch)](https://docs.libretro.com/library/race/) | v0.9.36.1, 1.32.1, v2.16 |
| SG-1000 | [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX), [Genesis Plus GX (RetroArch)](https://github.com/libretro/Genesis-Plus-GX), [Genesis Plus GX (Wide) (RetroArch)](https://github.com/libretro/Genesis-Plus-GX-Wide), [MSX/SVI/ColecoVision/SG-1000 (blueMSX) (RetroArch)](https://github.com/libretro/blueMSX) | v1.7.4, 1.7.4, nightly, Nightly |
| Master System | [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX), [Genesis Plus GX (RetroArch)](https://github.com/libretro/Genesis-Plus-GX), [Genesis Plus GX (Wide) (RetroArch)](https://github.com/libretro/Genesis-Plus-GX-Wide), [SMS Plus GX (RetroArch)](https://github.com/libretro/smsplus-gx) | v1.7.4, 1.7.4, nightly, Nightly |
| Genesis | [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX), [Genesis Plus GX (RetroArch)](https://github.com/libretro/Genesis-Plus-GX), [Genesis Plus GX (Wide) (RetroArch)](https://github.com/libretro/Genesis-Plus-GX-Wide) | v1.7.4, 1.7.4, nightly |
| Game Gear | [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX), [Genesis Plus GX (RetroArch)](https://github.com/libretro/Genesis-Plus-GX), [Genesis Plus GX (Wide) (RetroArch)](https://github.com/libretro/Genesis-Plus-GX-Wide), [SMS Plus GX (RetroArch)](https://github.com/libretro/smsplus-gx) | v1.7.4, 1.7.4, nightly, Nightly |
| Sega CD | [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX), [Genesis Plus GX (RetroArch)](https://github.com/libretro/Genesis-Plus-GX), [Genesis Plus GX (Wide) (RetroArch)](https://github.com/libretro/Genesis-Plus-GX-Wide) | v1.7.4, 1.7.4, nightly |
| 32X | [PicoDrive](https://github.com/notaz/picodrive) | 2.03 |
| Saturn | [Beetle Saturn (RetroArch)](https://github.com/libretro/beetle-saturn-libretro), [Mednafen](https://mednafen.github.io), [Yabause](https://yabause.org), [Yabause (Saturn) (RetroArch)](https://github.com/libretro/yabause) | v0.9.45.1, 1.32.1, v0.9.15, v0.9.15 |
| Smith Engineering Vectrex | [VecX (RetroArch)](https://docs.libretro.com/library/vecx/) | Nightly |
| PlayStation | [Beetle PSX (HW Renderer) (RetroArch)](https://github.com/libretro/beetle-psx-libretro), [Beetle PSX (SW Renderer) (RetroArch)](https://github.com/libretro/beetle-psx-libretro), [BeetlePSX](https://github.com/libretro/beetle-psx-libretro), [DuckStation](https://github.com/stenzek/duckstation/), [Mednafen](https://mednafen.github.io), [PCSX (Rearmed)](https://github.com/notaz/pcsx_rearmed), [PCSX ReARMed (RetroArch)](https://docs.libretro.com/library/pcsx_rearmed/) | 0.9.44.1, 0.9.44.1, 0, 2023.01.11, 1.32.1, r23l, r21 |
| Game Music | [GME](https://github.com/libretro/libretro-gme), [Game Music Emu (RetroArch)](https://docs.libretro.com/library/game_music_emu/) | v0.6.1, v0.6.3 |
| Supervision | [Potator](https://github.com/alekmaul/potator), [Potator (RetroArch)](https://github.com/libretro/potator) | 1.1, v20200223 |
| ZX Spectrum | [EP128Emu](http://ep128emu.sourceforge.net/about.html), [Fuse](http://fuse-emulator.sourceforge.net), [Sinclair - ZX Spectrum (RetroArch)](https://github.com/libretro/fuse) | 2.0.11, 0, Nightly |
***
## Cheat Support
Cores declaring cheat support in their `Core.plist` metadata:
| Core | Systems | Cheat Formats |
| ---------------- | -------------------------------- | -------------------------------------------------------------- |
| DuckStation | PSX | Game Shark |
| FCEUX | FDS, NES | Game Genie |
| Gambatte | GB, GBC | Game Genie, Game Shark |
| Genesis Plus GX | Game Gear, SG, SMS, SCD, SG-1000 | Game Genie, Pro Action Replay |
| Mupen64Plus | N64 | Game Shark |
| Mupen64Plus-Next | N64 | Game Shark |
| PicoDrive | 32X | Game Genie, Pro Action Replay |
| VisualBoyAdvance | GBA | GameShark, Code Breaker, Action Replay v3, Action Replay v1/v2 |
| mGBA | GBA | Game Shark, Code Breaker, Pro Action Replay |
{% hint style="info" %}
Additional cores support cheats through code-level protocol conformance not declared in Core.plist. See [Cheats Guide](/using-provenance/cheats) for the complete list including Stella, Dolphin, PPSSPP, Azahar, and Play!.
{% endhint %}
***
## Skin Identifiers
Use these identifiers when creating `.deltaskin` files. Browse column links directly to system-filtered skins on DeltaStyles.
| System | Provenance ID | Delta Skin ID | Browse Skins |
| ------------------------- | ------------------------------ | ------------------------------------ | ------------------------------------------------------------ |
| Atari 2600 | `com.provenance.2600` | โ | โ |
| Atari 5200 | `com.provenance.5200` | โ | โ |
| Atari 8bit Computer | `com.provenance.atari8bit` | โ | โ |
| Atari 7800 | `com.provenance.7800` | โ | โ |
| Atari Lynx | `com.provenance.lynx` | โ | โ |
| Atari Jaguar | `com.provenance.jaguar` | โ | โ |
| Atari Jaguar CD | `com.provenance.jaguarcd` | โ | โ |
| WonderSwan | `com.provenance.ws` | โ | โ |
| WonderSwan | `com.provenance.wsc` | โ | โ |
| CBS ColecoVision | `com.provenance.colecovision` | โ | โ |
| CPS-1 | `com.provenance.cps1` | โ | โ |
| CPS-2 | `com.provenance.cps2` | โ | โ |
| CPS-3 | `com.provenance.cps3` | โ | โ |
| Enterprise 128 | `com.provenance.ep128` | โ | โ |
| RetroArch | `com.provenance.retroarch` | โ | โ |
| MAME | `com.provenance.mame` | โ | โ |
| Magnavox Odyssey2 | `com.provenance.odyssey2` | โ | โ |
| Mattel Intellivision | `com.provenance.intellivision` | โ | โ |
| PC98 | `com.provenance.pc98` | โ | โ |
| TurboGrafx-16 | `com.provenance.pce` | โ | โ |
| TurboGrafx-CD | `com.provenance.pcecd` | โ | โ |
| SuperGrafx | `com.provenance.sgfx` | โ | โ |
| PCFX | `com.provenance.pcfx` | โ | โ |
| Nintendo | `com.provenance.nes` | `com.rileytestut.delta.game.nes` | [DeltaStyles](https://deltastyles.com/?search=nes) |
| Famicom Disk System | `com.provenance.fds` | โ | โ |
| Game Boy | `com.provenance.gb` | `com.rileytestut.delta.game.gbc` | [DeltaStyles](https://deltastyles.com/?search=gameboy) |
| Super Nintendo | `com.provenance.snes` | `com.rileytestut.delta.game.snes` | [DeltaStyles](https://deltastyles.com/?search=snes) |
| Virtual Boy | `com.provenance.vb` | โ | โ |
| Nintendo 64 | `com.provenance.n64` | `com.rileytestut.delta.game.n64` | [DeltaStyles](https://deltastyles.com/?search=n64) |
| Game Boy Color | `com.provenance.gbc` | `com.rileytestut.delta.game.gbc` | [DeltaStyles](https://deltastyles.com/?search=gameboy+color) |
| Game Boy Advance | `com.provenance.gba` | `com.rileytestut.delta.game.gba` | [DeltaStyles](https://deltastyles.com/?search=gba) |
| Pokรฉmon mini | `com.provenance.pokemonmini` | โ | โ |
| 3DO | `com.provenance.3DO` | โ | โ |
| Neo Geo | `com.provenance.neogeo` | โ | โ |
| Neo Geo CD | `com.provenance.neogeocd` | โ | โ |
| Neo Geo Pocket | `com.provenance.ngp` | โ | โ |
| Neo Geo Pocket Color | `com.provenance.ngpc` | โ | โ |
| SG-1000 | `com.provenance.sg1000` | โ | โ |
| Master System | `com.provenance.mastersystem` | `com.rileytestut.delta.game.ms` | [DeltaStyles](https://deltastyles.com/?search=master+system) |
| Genesis | `com.provenance.genesis` | `com.rileytestut.delta.game.genesis` | [DeltaStyles](https://deltastyles.com/?search=genesis) |
| Game Gear | `com.provenance.gamegear` | `com.rileytestut.delta.game.gg` | [DeltaStyles](https://deltastyles.com/?search=game+gear) |
| Sega CD | `com.provenance.segacd` | โ | [DeltaStyles](https://deltastyles.com/?search=sega+cd) |
| 32X | `com.provenance.32X` | โ | โ |
| Saturn | `com.provenance.saturn` | โ | [DeltaStyles](https://deltastyles.com/?search=saturn) |
| Smith Engineering Vectrex | `com.provenance.vectrex` | โ | โ |
| PlayStation | `com.provenance.psx` | `com.rileytestut.delta.game.psx` | [DeltaStyles](https://deltastyles.com/?search=playstation) |
| Game Music | `com.provenance.music` | โ | โ |
| Supervision | `com.provenance.supervision` | โ | โ |
| ZX Spectrum | `com.provenance.zxspectrum` | โ | โ |
***
{% hint style="info" %}
For the interactive community database, see [eduo.info/pvl](https://eduo.info/pvl/). Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# System-Specific Guides
System-specific setup guides for systems that need extra configuration
Most systems in Provenance work out of the box โ import a ROM and play. However, some systems have extra configuration options, additional file requirements, or unique features worth knowing about.
* [Nintendo 64](/platforms-and-performance/system-guides/n64) โ Custom texture packs, Mupen64Plus settings
* [Nintendo 3DS](/platforms-and-performance/system-guides/3ds) โ emuThreeDS native core, system files, performance tips
* [GameCube & Wii](/platforms-and-performance/system-guides/gamecube-wii) โ Dolphin native core, system folder, HD textures
***
## RetroArch Core Folder Structure
Many systems in Provenance use **RetroArch-based cores**. These cores support additional files and configuration through RetroArch's standard folder structure:
* **System files** โ BIOS, firmware, and other required files
* **Cheats** โ `.cht` cheat code files
* **Shader presets** โ Custom visual filter configurations
* **Core overrides** โ Per-core and per-game settings
Files placed in the RetroArch system directories are automatically available to the corresponding cores. Access these folders via the [Web Server](/advanced/restoring-files) or Files app.
***
{% hint style="info" %}
Need help with a specific system? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Nintendo 64
Nintendo 64 setup โ custom texture packs, core configuration, and performance tips
The N64 is one of the more demanding systems to emulate, but Provenance offers strong support through **Mupen64Plus** (RetroArch-based). This guide covers setup, custom texture packs, and optimization.
***
## Basics
| Detail | Info |
| ----------------- | ------------------------------------- |
| **Core** | Mupen64Plus (RetroArch) |
| **BIOS required** | No |
| **ROM formats** | `.z64`, `.n64`, `.v64`, `.zip`, `.7z` |
| **Max players** | 4 |
| **Save format** | `.eep`, `.sra`, `.fla`, `.mpk` |
***
## Custom Texture Packs
Mupen64Plus supports **high-resolution custom texture packs** that replace the original low-res N64 textures with community-created HD versions. Games like Ocarina of Time, Mario 64, and GoldenEye have stunning texture packs available.
### Installing Texture Packs
1. Download a texture pack for your game (common formats: `.htc`, `.hts`, or folders of PNG files)
2. Start the Web Server in Provenance (tap **+** or Settings โ Import/Export)
3. Navigate to the RetroArch system folder:
```
RetroArch/system/Mupen64Plus/hires_texture/[GameName]/
```
4. Upload the texture pack files into the game-specific folder
5. Launch the game โ HD textures load automatically
{% hint style="info" %}
Texture pack folder names must match the game's internal ROM name. Check the Mupen64Plus documentation or the texture pack's README for the correct folder name.
{% endhint %}
### Finding Texture Packs
* [**Emulation King Texture Packs**](https://evilgames.eu/texture-packs.htm) โ Large collection organized by game
* [**N64 Texture Packs Reddit**](https://www.reddit.com/r/n64/) โ Community-shared packs
* [**Mollymutt's Texture Packs**](https://www.mollymutt.net/) โ High-quality packs for popular games
### Popular Texture Packs
| Game | Pack | Description |
| --------------- | ------------------- | ----------------------------- |
| Ocarina of Time | Community Retexture | Complete HD overhaul |
| Super Mario 64 | HD Texture Pack | Clean, upscaled textures |
| GoldenEye 007 | GoldenEye HD | Modernized textures |
| Majora's Mask | HD Pack | Faithful HD recreation |
| Mario Kart 64 | HD Pack | Updated tracks and characters |
***
## Core Configuration
Access advanced Mupen64Plus settings through the RetroArch interface:
1. Launch an N64 game
2. Open the **pause menu**
3. Select **RetroArch Settings**
### Key Settings
| Setting | Options | Recommendation |
| ------------------------- | ------------------------- | ---------------------------------------------- |
| **Resolution** | Native, 2x, 4x | 2x for most devices, native for older hardware |
| **GFX Plugin** | GLideN64, Angrylion, Rice | GLideN64 (best balance of speed and accuracy) |
| **RSP Plugin** | HLE, LLE | HLE (faster), LLE (more accurate) |
| **Framebuffer emulation** | On/Off | On (fixes graphical glitches in many games) |
| **Texture filtering** | None, xBRZ, 3-point | 3-point (authentic N64 look) |
***
## Performance Tips
The N64 is one of the more demanding systems:
* **Newer devices recommended** โ iPhone 11+ / iPad Air 3+ for smooth performance
* **Use the Release build** if building from source โ Debug builds are 5-10x slower
* **Lower resolution** if needed โ Drop from 2x to native in RetroArch settings
* **Close background apps** โ Free up RAM for the emulator
* **Disable HD texture packs** โ They look great but increase memory usage and loading times
***
## Known Quirks
Some games have graphical glitches
N64 emulation isn't perfect. Try different GFX plugins (GLideN64 vs Rice vs Angrylion) in RetroArch settings. Some games work better with specific plugins.
Controller Pak saves not working
Some N64 games use the Controller Pak (memory card) instead of EEPROM/SRAM. Make sure the core's Controller Pak emulation is enabled in RetroArch settings โ Options.
Audio crackles or pops
Increase the audio buffer size in RetroArch settings โ Audio. This trades slight audio latency for smoother playback. Also ensure no background apps are competing for CPU.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Nintendo 3DS
Nintendo 3DS setup โ emuThreeDS core, system files, and performance tips
Provenance supports Nintendo 3DS emulation through **emuThreeDS**, a native core (not RetroArch-based). The 3DS is one of the most demanding systems to emulate and requires specific setup.
{% hint style="warning" %}
3DS emulation is **iOS, iPadOS, and macOS only** โ it is not supported on tvOS (Apple TV).
{% endhint %}
***
## Basics
| Detail | Info |
| -------------------- | ------------------------------------------- |
| **Core** | emuThreeDS (native) |
| **BIOS required** | No (but system files improve compatibility) |
| **ROM formats** | `.3ds`, `.cia`, `.cxi`, `.app`, `.elf` |
| **Platform support** | iPhone, iPad, Mac (not tvOS) |
| **Max players** | 1 (local) |
***
## System Files
emuThreeDS uses its own native folder structure (not RetroArch's). System files improve game compatibility and are required for some titles.
### NAND and System Data
The 3DS core maintains a virtual NAND (internal storage) that some games require. System archives and shared fonts are among the files that can be placed here for better compatibility.
Access the core's file structure via the Web Server or Files app:
```
emuThreeDS/
โโโ nand/ # Virtual NAND storage
โโโ sdmc/ # Virtual SD card
โโโ sysdata/ # System data files
โโโ config/ # Core configuration
```
### Encrypted vs Decrypted ROMs
* **Decrypted ROMs** (`.3ds` decrypted, `.cia`) work directly
* **Encrypted ROMs** may require AES keys placed in the `sysdata/` folder
* Decrypted ROMs are recommended for the best compatibility
***
## Performance
3DS emulation is **very demanding**. Recommended hardware:
| Device | Performance |
| --------------------------- | ------------------------------------- |
| **iPhone 15 Pro / Pro Max** | Good โ most games playable |
| **iPhone 14 Pro / 13 Pro** | Fair โ simpler 3DS games playable |
| **iPad Pro (M-series)** | Good โ best iPad experience |
| **iPad Air (M-series)** | Good |
| **Older devices** | Poor โ expect slowdowns in most games |
### Optimization Tips
1. **Close all background apps** โ 3DS needs maximum CPU/RAM
2. **Use Low Power Mode cautiously** โ it can throttle performance
3. **Avoid Sleep Mode throttling** โ keep the screen active during gameplay
4. **Simpler games first** โ 2D titles (Kirby, Pokemon X/Y overworld) run better than 3D-heavy games (Monster Hunter, Zelda)
5. **Reduce resolution** if the core supports it โ lower internal resolution improves frame rate
***
## Controls
The 3DS has unique inputs that map to on-screen controls:
| 3DS Input | Provenance Mapping |
| ------------- | -------------------------------------------------------------------------- |
| Circle Pad | Left analog stick |
| D-Pad | D-Pad |
| A / B / X / Y | Face buttons |
| L / R | Shoulder buttons |
| Touch Screen | Tap the bottom screen area |
| Microphone | Device microphone (enable in Settings โ Privacy โ Microphone โ Provenance) |
| Gyroscope | Device gyroscope (for games like Ocarina of Time 3D) |
{% hint style="info" %}
**Touch screen games** require tapping on the bottom screen area of the display. Some games rely heavily on touch input (e.g., Professor Layton, Zelda: Phantom Hourglass).
{% endhint %}
***
## Dual Screen Layout
The 3DS has two screens. Provenance handles the layout automatically:
* **Portrait mode** โ Screens stacked vertically (top screen above, bottom/touch below)
* **Landscape mode** โ Screens side-by-side or with focus on the primary screen
Custom skins can change the dual-screen layout โ check [DeltaStyles](https://deltastyles.com) for 3DS-specific skins.
***
## Known Limitations
Not all games are playable
3DS emulation is still maturing. Some games may have graphical glitches, audio issues, or crash. Check community compatibility lists for your specific game. The emuThreeDS core is actively being improved.
No tvOS support
The 3DS core is not available on Apple TV due to performance and input requirements (touch screen). Use iPhone, iPad, or Mac instead.
Online features not supported
3DS online services (Nintendo Network) are not emulated. Single-player and local features only.
Microphone not working
Go to your device's Settings โ Privacy & Security โ Microphone โ enable Provenance. Some 3DS games (like Nintendogs) require microphone input.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# GameCube & Wii
GameCube & Wii setup โ Dolphin native core, system folder, HD textures, and configuration
Provenance supports GameCube and Wii emulation through **Dolphin**, a native core (not RetroArch-based). Dolphin brings excellent compatibility and advanced features like HD texture support, custom system configurations, and Wii NAND emulation.
***
## Basics
| Detail | GameCube | Wii |
| ----------------- | ------------------------------- | -------------------------------- |
| **Core** | Dolphin (native) | Dolphin (native) |
| **BIOS required** | No (built-in HLE) | No (built-in HLE) |
| **ROM formats** | `.iso`, `.gcm`, `.gcz`, `.ciso` | `.iso`, `.wbfs`, `.gcz`, `.ciso` |
| **Max players** | 4 | 4 |
| **Controller** | Physical controller recommended | Physical controller recommended |
{% hint style="info" %}
A **physical controller** is strongly recommended for GameCube and Wii games. On-screen controls work but many games benefit from analog sticks and shoulder buttons.
{% endhint %}
***
## Dolphin Folder Structure
Dolphin uses its own native folder structure (not RetroArch's). Access via the Web Server or Files app:
```
Dolphin/
โโโ Config/ # Dolphin configuration files
โโโ GameSettings/ # Per-game INI overrides
โโโ GC/ # GameCube system data
โ โโโ USA/ # Region-specific memory cards
โ โโโ EUR/
โ โโโ JAP/
โโโ Wii/ # Wii NAND (virtual internal storage)
โ โโโ title/ # Installed Wii channels and saves
โโโ Load/
โ โโโ Textures/ # HD texture packs (per game ID)
โโโ Maps/ # Symbol maps for debugging
โโโ ResourcePacks/ # Custom resource packs
โโโ Shaders/ # Custom shader files
โโโ StateSaves/ # Dolphin save states
```
***
## HD Texture Packs
Dolphin supports custom HD textures for both GameCube and Wii games:
### Installing Texture Packs
1. Download a texture pack for your game
2. Start the Web Server (tap **+** or Settings โ Import/Export)
3. Navigate to:
```
Dolphin/Load/Textures/[GameID]/
```
4. Upload the texture files into the game-specific folder
5. Launch the game โ textures load automatically
### Finding the Game ID
Each GameCube/Wii game has a unique 6-character ID (e.g., `GALE01` for Super Smash Bros. Melee). You can find it:
* In the game info within Provenance (long-press โ Game Info)
* On [GameTDB](https://www.gametdb.com/) โ search your game
### Finding Texture Packs
* [**Dolphin Forums - Custom Textures**](https://forums.dolphin-emu.org/Forum-custom-texture-projects) โ Community texture pack projects
* **GitHub** โ Search for "\[game name] dolphin texture pack"
***
## Wii NAND
Some Wii games require or benefit from NAND data (virtual internal storage):
* **Wii System Menu** โ Can be installed for accessing system settings
* **Save data** โ Some games store saves in NAND rather than the virtual memory card
* **Wii Channels** โ Can be installed for games that require them
The NAND is stored in the `Dolphin/Wii/` folder and is managed automatically by the core.
***
## GameCube Memory Cards
Dolphin emulates GameCube memory cards automatically:
* Virtual memory cards are stored in `Dolphin/GC/[Region]/`
* Each region (USA, EUR, JAP) has its own memory card
* Save data persists across play sessions
***
## Performance
GameCube and Wii are demanding to emulate:
| Device | GameCube | Wii |
| --------------------------- | -------- | --------- |
| **iPhone 15 Pro / Pro Max** | Good | Fair-Good |
| **iPad Pro (M-series)** | Good | Good |
| **iPhone 14 Pro / 13 Pro** | Fair | Fair |
| **Older devices** | Poor | Poor |
### Optimization Tips
1. **Use a modern device** โ M-series or A16+ chips handle Dolphin best
2. **Close background apps** โ GameCube/Wii emulation needs all available resources
3. **Skip EFB access** โ Improves performance in some games (Dolphin settings)
4. **Lower internal resolution** โ Reduces GPU load
5. **Disable V-Sync** if experiencing stuttering
***
## Wii Motion Controls
Wii games that require motion controls have limited support through device sensors:
* **Pointer** โ Touch screen simulates the Wii Remote pointer
* **Accelerometer/Gyroscope** โ Device sensors can simulate Wii Remote motion
* **Physical controller** โ Map Wii Remote buttons to a standard controller
{% hint style="warning" %}
Games that rely heavily on Wii Remote motion (Wii Sports, Skyward Sword) may not play well. Games with Classic Controller support (Smash Bros. Brawl, Mario Kart Wii) work best with a standard controller.
{% endhint %}
***
## Known Quirks
Some games have audio stuttering
Dolphin is demanding on CPU. If audio stutters, try closing background apps, lowering resolution, or enabling audio stretching in Dolphin settings.
Game crashes on boot
Some games may need specific Dolphin settings. Check the [Dolphin Wiki](https://wiki.dolphin-emu.org/) for game-specific compatibility notes and recommended settings.
Wii Remote games don't work with my controller
Not all Wii games support Classic Controller input. Check if the game supports Classic Controller or GameCube controller โ those map most naturally to standard Bluetooth controllers.
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Performance Optimization
Get the best performance from Provenance across all systems and devices
Provenance is highly optimized for Apple devices, but performance can vary based on your device, the emulated system, and your settings. This guide helps you get smooth, full-speed emulation across all 38+ supported systems.
## Quick Performance Checklist
โ
**5-Minute Performance Boost:**
1. **Close background apps** - Double-tap Home, swipe up to close
2. **Disable visual effects** - Settings โ Turn off Smoothing and CRT filters
3. **Use recommended cores** - See [per-system recommendations](#by-system) below
4. **Enable Low Power Mode** - For longer gaming sessions (slight performance trade-off)
5. **Update to latest version** - Performance improvements in every release
**Still slow?** Continue reading for system-specific optimizations.
***
## Understanding Performance
### What Affects Performance?
**Device Age (Most Important):**
* ๐ฑ **iPhone 11 or newer** - Full speed for all systems including Dreamcast and PSP
* ๐ฑ **iPhone 8/8 Plus/X/XS/XR** - Full speed for all systems up to PlayStation/N64; Dreamcast/PSP may struggle
* ๐ฑ **iPad Air 3 / Pro 2018 or newer** - Excellent for all supported systems
* ๐บ **Apple TV 4K** - Best performance, especially for demanding systems like Dreamcast
**Emulated System Complexity:**
* ๐ข **Easy:** NES, Game Boy, SNES, Genesis (full speed on any supported device)
* ๐ก **Moderate:** GBA, PlayStation, N64 (full speed on iPhone 8 or newer)
* ๐ด **Demanding:** Dreamcast, PSP (requires iPhone 11 or newer / Apple TV 4K)
**App Settings:**
* โ๏ธ **Visual filters** (Smoothing, CRT) add processing overhead
* โ๏ธ **Save states** can cause brief frame drops when created
* โ๏ธ **Audio sync** affects timing accuracy vs performance
***
## Device-Specific Recommendations
### iPhone
**Modern (iPhone 11 and newer):**
* โ
All systems run at full speed
* โ
Enable all visual enhancements without performance loss
* โ
Dreamcast, PSP playable
**Entry Level (iPhone 8/8 Plus/X/XS/XR):**
* โ
All systems up to PlayStation/N64 at full speed
* โ ๏ธ Disable visual filters for demanding games
* โ ๏ธ Dreamcast/PSP may be slow
**Note:** Provenance requires iOS 16+, which supports iPhone 8 or later. Older devices cannot run Provenance.
### iPad
**Modern (iPad Air 3 / Pro 2018 and newer):**
* โ
All systems at maximum performance
* โ
Best screen size for retro gaming
* โ
No compromises needed
**Entry Level (iPad 5th gen, iPad mini 5th gen and newer):**
* โ
All systems up to PlayStation/N64
* โ ๏ธ Some demanding games (Dreamcast, PSP) may need frameskip
**Note:** Provenance requires iPadOS 16+, which supports iPad 5th gen, iPad Air 3rd gen, iPad mini 5th gen, and all iPad Pro models.
### Apple TV
See the dedicated [**Apple TV / tvOS Guide**](/platforms-and-performance/tvos-guide#performance-tips) for detailed performance optimization on tvOS.
**Summary:**
* **Apple TV 4K (2nd/3rd gen):** Perfect performance, all systems
* **Apple TV 4K (1st gen):** Full speed up to N64/PlayStation
* **Apple TV HD:** Good for 16-bit and earlier systems
***
## Performance by System
### 8-Bit Systems (Full Speed Everywhere)
**Systems:** NES, Game Boy, Game Boy Color, Sega Master System, Game Gear, Atari 2600, Atari 7800, Atari Lynx
**Performance:** โ
Full speed on all supported devices (iPhone 8 or newer)
**Tips:**
* No optimization needed
* All visual filters work without slowdown
* Lowest impact on battery life
***
### 16-Bit Systems (Full Speed on All Supported Devices)
**Systems:** SNES, Genesis/Mega Drive, Sega CD, TurboGrafx-16, Neo Geo Pocket, WonderSwan
**Performance:** โ
Full speed on all supported devices (iPhone 8 or newer)
**Tips:**
* **SNES:** Some special chip games (Star Fox, Yoshi's Island) may need minor tweaks on entry-level devices
* **Genesis:** Multiple cores available - use "Genesis Plus GX" for best compatibility
* **Sega CD:** Requires BIOS + CHD format for multi-disc games
**Optimization:**
* Use save states instead of in-game saves (faster loading)
***
### Portable Systems
#### Game Boy Advance
**Performance:** โ
Full speed on all supported devices (iPhone 8 or newer)
**Tips:**
* **Core:** Use "mGBA" core (most accurate, good performance)
* **Alternative:** "VBA-M" core for older devices (slightly faster)
* **Battery:** GBA games drain battery faster than GB/GBC (3D effects)
**Optimization:**
* Disable "Solar Sensor" if not using Boktai games (saves CPU)
#### Nintendo DS
**Performance:** โ ๏ธ Requires iPhone 8 or newer for full speed
**Tips:**
* **3D games** (Mario 64 DS, Mario Kart DS) need iPhone 11+ for smooth play
* **2D games** (Pokรฉmon, Advance Wars) run well on iPhone 8/8 Plus/X/XS/XR
* **Screen layout:** Vertical layout recommended (one screen above the other)
**Optimization:**
* Lower internal resolution in settings (3x โ 2x)
* Disable "High-Res 3D" for 3D games
#### PSP
**Performance:** ๐ด Requires iPhone 11 or newer
**Tips:**
* **Most demanding system** in Provenance
* Works best on iPhone 12 Pro or newer with active cooling
* Apple TV 4K recommended for best experience
**Optimization:**
* Set frameskip to "Auto" or "1" if needed
* Lower internal resolution to 2x (still looks great)
* Disable texture filtering if slow
* Close all background apps
***
### 3D Systems
#### Nintendo 64
**Performance:** ๐ก Full speed on iPhone 8 and newer
**Tips:**
* **Multiple cores available:** "Mupen64Plus" (recommended) and "ParaLLEl"
* **ParaLLEl core:** Better accuracy, requires iPhone 11+ for full speed
* **Mupen64Plus:** Faster, works on all supported devices
**Game-Specific:**
* โ
**Works great:** Super Mario 64, Ocarina of Time, Mario Kart 64
* โ ๏ธ **Needs newer device:** Perfect Dark, Conker's Bad Fur Day, Donkey Kong 64
* โ **Problematic:** GoldenEye 007 (slowdown even on newest devices)
**Optimization:**
* Use "Rice" video plugin on entry-level devices (faster but less accurate)
* Disable "widescreen hack" for performance
* Lower resolution multiplier: 2x โ 1x (native N64 resolution)
#### PlayStation
**Performance:** โ
Full speed on iPhone 8 and newer
**Tips:**
* **Best core:** "PCSX-ReARMed" (excellent compatibility + speed)
* **CHD support:** Multi-disc games work great in CHD format (faster loading)
* **Memory cards:** Provenance auto-creates, no setup needed
**Game-Specific:**
* โ
**Perfect:** Final Fantasy VII-IX, Crash Bandicoot, Spyro, Metal Gear Solid
* โ ๏ธ **May need frameskip:** Ridge Racer Type 4, Gran Turismo 2
**Optimization:**
* Use CHD format instead of BIN/CUE (20-40% smaller, faster)
* Enable "Enhanced Resolution" on iPhone 11+ (sharper graphics, minimal performance hit)
#### Dreamcast
**Performance:** ๐ด Requires iPhone 11 or newer
**Tips:**
* Use **Flycast JIT-less core**
* Apple TV 4K recommended for best experience
* Not all games are compatible (core still in development)
**Game-Specific:**
* โ
**Works well:** Sonic Adventure, Shenmue, Soulcalibur, Jet Set Radio, THPS 1+2
* โ ๏ธ **Slow/buggy:** Crazy Taxi 1 & 2, DOA2
* โ **Incompatible:** Some titles don't boot
**Optimization:**
* Disable "Widescreen" mode (adds overhead)
* Lower internal resolution if needed
* Use "Frameskip: Auto" for demanding games
***
## Advanced Optimization
### Battery Life vs Performance
**Best Battery Life:**
1. โ
Enable **Low Power Mode** (Settings โ Battery)
2. โ
Lower screen brightness (biggest battery drain)
3. โ
Play 8-bit/16-bit systems (NES, SNES, GB, Genesis)
4. โ
Use wired headphones (Bluetooth drains faster)
5. โ
Disable background app refresh for Provenance
**Battery Impact by System:**
* ๐ข **Low drain:** NES, GB, GBC, SNES, Genesis (\~4-6 hours)
* ๐ก **Moderate:** GBA, PlayStation (\~3-4 hours)
* ๐ด **High drain:** N64, Dreamcast, PSP (\~2-3 hours)
### Visual Quality vs Performance
**Maximum Quality (iPhone 11+ recommended):**
* โ
Smoothing filter ON
* โ
CRT filter ON
* โ
Enhanced resolution (PlayStation, N64)
* โ
Shader effects (specific cores)
**Balanced (iPhone 8/8 Plus/X/XS/XR):**
* โ๏ธ Smoothing: OFF
* โ๏ธ CRT filter: OFF
* โ๏ธ Enhanced resolution: ON (PlayStation only)
**Maximum Performance (entry-level supported devices):**
* โ All filters OFF
* โ Native resolution only
* โ Frameskip: Auto
### Recommended Cores by System
When multiple cores are available, these are the best performance/compatibility balance:
| System | Recommended Core | Alternative | Notes |
| --------------- | ---------------- | ----------- | ------------------------- |
| **Genesis** | Genesis Plus GX | PicoDrive | Plus GX = better accuracy |
| **SNES** | Snes9x | bsnes | Snes9x = faster |
| **GBA** | mGBA | VBA-M | mGBA = best accuracy |
| **N64** | Mupen64Plus | ParaLLEl | ParaLLEl needs iPhone 11+ |
| **PlayStation** | PCSX-ReARMed | Beetle PSX | ReARMed = faster |
***
## Troubleshooting Performance Issues
### Game is Slow or Stuttering
**Symptoms:** Framerate drops, audio crackling, sluggish controls
**Solutions (try in order):**
1. โ
**Close background apps**
* Double-tap Home button
* Swipe up on all apps except Provenance
2. โ
**Disable visual filters**
* Provenance Settings โ Smoothing: OFF
* Provenance Settings โ CRT Filter: OFF
3. โ
**Check core selection**
* In-game menu โ Core Info
* Try alternative core if available
4. โ
**Lower internal resolution**
* Settings โ Video โ Resolution Multiplier: 1x or 2x
5. โ
**Enable frameskip**
* Settings โ Frameskip: Auto
6. โ
**Restart device**
* Power off โ Wait 10 seconds โ Power on
### Specific Game is Slow, Others Are Fine
**Cause:** Game-specific compatibility or CPU-intensive content
**Solutions:**
1. Check online compatibility lists for that core
2. Try alternative ROM dump (bad ROM = poor performance)
3. Some games are just demanding (GoldenEye 007, Conker, etc.)
4. Update to latest Provenance version (cores improve over time)
### Audio Crackling or Popping
**Cause:** CPU can't keep up with audio buffer
**Solutions:**
1. Enable frameskip (lets audio stay smooth)
2. Close background audio apps (Music, Spotify)
3. Disable Bluetooth audio (use wired headphones)
4. Lower in-game audio settings if available
### Performance Got Worse After Update
**Cause:** New settings default, cache issue, or regression
**Solutions:**
1. Check if new visual settings were enabled automatically
2. Delete and reinstall Provenance (backup saves first!)
3. Report regression on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
***
## Performance Testing Results
### Real-World Benchmarks
Tested on **iPhone 12** with default settings:
| System | Test Game | FPS | Performance |
| ----------- | ------------------- | -------- | ----------- |
| NES | Super Mario Bros. 3 | 60/60 | โ
Perfect |
| SNES | Super Metroid | 60/60 | โ
Perfect |
| GBA | Metroid Fusion | 60/60 | โ
Perfect |
| Genesis | Sonic 3 & Knuckles | 60/60 | โ
Perfect |
| PlayStation | Final Fantasy VII | 60/60 | โ
Perfect |
| N64 | Ocarina of Time | 60/60 | โ
Perfect |
| N64 | GoldenEye 007 | 25-45/60 | โ ๏ธ Slow |
| Dreamcast | Sonic Adventure | 55-60/60 | โ
Great |
| PSP | Crisis Core | 30-50/60 | โ ๏ธ Playable |
*Note: Results vary by device. iPhone 11 and newer recommended for 3D systems.*
***
## Tips from the Community
**From Discord/Reddit/App Store reviews:**
1. ๐ก **"Airplane mode improves battery life by 30%"** - Disables background sync
2. ๐ก **"CHD format loads 2-3x faster than BIN/CUE"** - Especially for multi-disc PlayStation games
3. ๐ก **"Close Music app before playing"** - Prevents audio interference
4. ๐ก **"Delete old save states"** - Too many save states can slow library loading
5. ๐ก **"Use iPad for PSP games"** - Bigger screen + better cooling = smoother performance
***
## See Also
* [Screen Filters & Shaders](/using-provenance/shaders-and-filters) โ Filter types and their performance impact
* [Fast Forward](/using-provenance/fast-forward) โ Speed up gameplay in supported cores
* [System-Specific Guides](/platforms-and-performance/system-guides) โ N64 texture packs, 3DS settings, GameCube/Wii optimization
* [Apple TV / tvOS Guide](/platforms-and-performance/tvos-guide#performance-tips) โ tvOS-specific optimization
* [Troubleshooting](/help-and-community/troubleshooting) โ Fix common issues
* [ROM Formatting](/using-provenance/roms/formatting-roms) โ Convert ROMs to optimal formats (CHD)
***
**Still having performance issues?** Ask in the [Provenance Discord](https://discord.gg/provenance) or check the [FAQ](/faqs).
# Apple TV / tvOS Guide
Complete guide to Provenance on Apple TV โ setup, controllers, iCloud sync, performance tips, and the best tvOS emulator experience
Provenance is the premier multi-system emulator for Apple TV, bringing classic gaming to the big screen with support for **38+ game systems** from Atari to PlayStation. This guide covers everything you need to know to get the best experience on tvOS.
## Why Provenance on Apple TV?
โจ **Unique Features:**
* ๐ฎ **Native tvOS app** - Built specifically for big-screen gaming
* ๐ฏ **Full controller support** - PlayStation, Xbox, MFi, and Siri Remote
* โ๏ธ **iCloud sync** - Seamlessly continue games across iPhone, iPad, and Apple TV
* ๐ฑ **TopShelf integration** - Quick access to recently played games
* ๐ **Premium performance** - All Apple TV models run classic systems at full speed
**Supported on:** Apple TV HD (4th gen), Apple TV 4K (all generations)
***
## Getting Started
### Installation
**From the App Store (Recommended):**
1. Open the **App Store** on your Apple TV
2. Search for **"Provenance"**
3. Download and install (100% free)
4. Optional: Upgrade to **Provenance Plus** for iCloud sync ($3.99/month, $39.99/year, or $99.99 lifetime)
**Alternative:** [Sideload from Xcode](/getting-started/installing-provenance/advanced/sideloading) (requires Mac + Apple Developer account)
### First Launch
1. **Grant permissions** - Allow file access when prompted
2. **Pair a controller** (recommended) - See [Controller Setup](#controller-setup) below
3. **Add BIOS files** - Some systems require BIOS (see [BIOS Requirements](/getting-started/bios-requirements))
4. **Import ROMs** - See [Importing ROMs](#importing-roms) below
***
## Controller Setup
### Supported Controllers
Provenance supports nearly every modern game controller on Apple TV:
**Recommended Controllers:**
* ๐ฎ **PlayStation 4/5 DualShock/DualSense** - Best overall compatibility
* ๐ฎ **Xbox One/Series X|S Controller** - Excellent button mapping
* ๐ **MFi (Made for iOS) Controllers** - Native Apple support
* ๐ฑ **Siri Remote** (tvOS 17+) - Basic control for simple games
**Not Recommended:**
* โ ๏ธ Siri Remote on older tvOS - Limited buttons, awkward for most games
### Pairing Your Controller
**PlayStation or Xbox Controller:**
1. Put controller in pairing mode:
* **PS4/PS5:** Hold **Share + PS** button until light flashes
* **Xbox:** Hold **Pairing** button until Xbox logo flashes
2. On Apple TV: **Settings** โ **Remotes and Devices** โ **Bluetooth**
3. Select your controller from the list
4. โ
Controller is now paired!
**MFi Controller:**
* Usually pairs automatically when turned on near Apple TV
* If not: Settings โ Remotes and Devices โ Bluetooth โ Select controller
### Controller Tips
* ๐ **Battery:** Most controllers last 8-12 hours per charge
* ๐ **Multi-device:** Controllers can pair with multiple devices (hold pairing button to switch)
* ๐ถ **Range:** Bluetooth range \~30 feet / 10 meters (line of sight)
* โก **Latency:** Wired Ethernet connection improves Bluetooth performance (see [Performance Tips](#performance-tips))
***
## Importing ROMs
### Method 1: iCloud Sync (Provenance Plus)
If you have Provenance Plus and multiple Apple devices:
1. **On iPhone/iPad:**
* Import ROMs using [any standard method](/using-provenance/importing-roms)
* Enable iCloud sync in Provenance settings
2. **On Apple TV:**
* Open Provenance
* Your library will automatically sync via iCloud
* โ
All saves and game states sync across devices!
### Method 2: Direct Transfer
**Via AirDrop (easiest):**
1. On Mac/iPhone: Select ROM files
2. AirDrop to your Apple TV
3. Open files in Provenance
**Via File Sharing (Finder):**
1. Connect Apple TV to Mac via USB-C
2. Open **Finder** โ Select Apple TV
3. **Files** tab โ Drag ROMs to **Provenance**
4. ROMs appear in library on next app launch
**Via Xcode (for developers):**
1. Connect Apple TV to Mac
2. In Xcode: **Window** โ **Devices and Simulators**
3. Select Apple TV โ **Installed Apps** โ **Provenance**
4. Drag ROMs into the file container
### Method 3: Cloud Services
* Import from **Dropbox, Google Drive, OneDrive** via Files app
* Select ROM โ **Share** โ **Provenance**
***
## Best Systems for Big-Screen Gaming
### Highly Recommended (Perfect on TV)
These systems were designed for TVs and translate perfectly to Apple TV:
* ๐ฎ **Nintendo 64** (1996-2002) - *Super Mario 64, GoldenEye 007, The Legend of Zelda: Ocarina of Time*
* ๐ฎ **PlayStation** (1994-2006) - *Final Fantasy VII, Crash Bandicoot, Metal Gear Solid*
* ๐ฎ **Sega Dreamcast** (1998-2001) - *Sonic Adventure, Shenmue, Crazy Taxi*
* ๐ฎ **SNES** (1990-2003) - *Super Metroid, Chrono Trigger, Super Mario World*
* ๐ฎ **Sega Genesis** (1988-1997) - *Sonic the Hedgehog, Streets of Rage 2, Phantasy Star IV*
### Also Great
* ๐น๏ธ **Arcade** (MAME, FinalBurn Neo) - *Street Fighter II, Pac-Man, Metal Slug*
* ๐ฎ **NES** - *Super Mario Bros. 3, The Legend of Zelda, Metroid*
* ๐ฎ **Game Boy Advance** - Better on TV than you'd expect! (*Metroid Fusion, Pokรฉmon Emerald*)
### Less Ideal for TV
* ๐ฑ **Game Boy / Game Boy Color** - Tiny screen designed for handhelds, hard to see on TV
* ๐ฑ **DS / 3DS** - Dual-screen layouts don't translate well to single TV screen
***
## Performance Tips
### Optimize for Big-Screen Gaming
**Reduce Input Latency:**
1. ๐ **Use Ethernet instead of WiFi** - Dramatically improves Bluetooth controller performance
2. ๐บ **Enable "Game Mode" on your TV** - Reduces display lag (check TV settings)
3. ๐จ **Turn off Dolby Vision** - Adds processing delay (Settings โ Video and Audio)
4. ๐ **Disconnect unused Bluetooth devices** - Reduces interference
5. ๐ก **Position Apple TV in open space** - Avoid thick walls, metal objects near device
**Graphics & Performance:**
* โ๏ธ **Disable "Smoothing" and "CRT filters"** - Slight performance gain (Provenance Settings)
* ๐๏ธ **Use native resolution** - Don't force 4K upscaling on non-4K TVs
**System-Specific:**
* **N64 on older Apple TV HD:** Some games may need frameskip enabled
* **PlayStation:** Runs full speed on all Apple TV models
* **Dreamcast:** Requires Apple TV 4K for best performance
### Expected Performance
| Apple TV Model | Recommended Systems | Performance Notes |
| ----------------------------- | ------------------------------------------- | ----------------------------------------- |
| **Apple TV 4K (2nd/3rd gen)** | All systems up to PlayStation/N64/Dreamcast | Full speed, no compromises |
| **Apple TV 4K (1st gen)** | All systems up to PlayStation/N64 | Dreamcast playable, some slowdown |
| **Apple TV HD (4th gen)** | All systems up to PlayStation | N64 mostly full speed with minor slowdown |
***
## Provenance Plus on Apple TV
**iCloud Library & Save Sync:**
* ๐ฎ Start a game on iPhone during your commute
* ๐ Continue exactly where you left off on Apple TV at home
* ๐พ All save states, game saves, and settings sync automatically
* ๐ Your entire ROM library syncs across devices
**Other Plus Features:**
* ๐ Early access to new cores and features
* ๐ ๏ธ Priority support
* ๐ฌ TestFlight beta access
**Cost:** $3.99/month or $39.99/year (App Store free trial available for subscriptions), or $99.99 lifetime
***
## TopShelf Integration
Provenance integrates with tvOS TopShelf for quick access to your games:
**What is TopShelf?**
* The top row of your Apple TV home screen
* Shows your most recently played games
* Launch games directly without opening Provenance first
**How to Use:**
1. Move Provenance to the **top row** of your Apple TV home screen
2. Swipe to Provenance (don't open it)
3. See your recently played games in the expanded TopShelf view
4. Select a game to launch directly into gameplay
***
## Troubleshooting
### Controller Not Pairing
**Problem:** Controller won't connect or keeps disconnecting
**Solutions:**
1. โ
**Forget and re-pair:**
* Settings โ Remotes and Devices โ Bluetooth โ Select controller โ Forget Device
* Re-pair from scratch
2. โ
**Check battery:** Low battery causes connection issues
3. โ
**Reduce interference:** Move WiFi routers, microwave ovens away from Apple TV
4. โ
**Update firmware:** PS5/Xbox controllers may need firmware updates (connect to console first)
5. โ
**Use Ethernet:** Wired connection improves Bluetooth stability
### Games Running Slow or Stuttering
**Problem:** Lag, framerate drops, audio stuttering
**Solutions:**
1. โ
**Check build type:** App should say "Provenance" not "Prov Debug" (debug builds are slow)
2. โ
**Disable visual effects:** Turn off Smoothing, CRT filters in settings
3. โ
**Enable Game Mode on TV:** Check your TV's picture settings
4. โ
**Close other apps:** Double-tap TV button, swipe up to close unused apps
5. โ
**Restart Apple TV:** Hold Home button โ Sleep, then wake Apple TV
### iCloud Sync Not Working
**Problem:** Games or saves not syncing between devices
**Solutions:**
1. โ
**Verify Provenance Plus:** Active subscription required for sync
2. โ
**Check iCloud storage:** Settings โ Accounts โ iCloud โ Manage Storage (need available space)
3. โ
**Enable iCloud in Provenance:** App Settings โ iCloud Sync โ ON (on all devices)
4. โ
**Check network:** iCloud sync requires active internet connection
5. โ
**Force sync:** Close and reopen Provenance to trigger manual sync
### ROM Not Showing in Library
**Problem:** Imported ROM doesn't appear
**Solutions:**
1. โ
**Check file format:** See [supported formats](/using-provenance/roms/formatting-roms)
2. โ
**Verify ROM hash:** Corrupted downloads won't import (re-download)
3. โ
**Check BIOS:** Some systems require BIOS files (see [BIOS Requirements](/getting-started/bios-requirements))
4. โ
**Re-import:** Delete and re-add the ROM
5. โ
**Restart app:** Force quit Provenance and relaunch
### Black Screen After Launching Game
**Problem:** Game starts but shows only black screen (audio may work)
**Solutions:**
1. โ
**BIOS missing:** PlayStation, Sega CD, Saturn, Dreamcast require BIOS files
2. โ
**Try different ROM:** File may be corrupted
3. โ
**Update cores:** Settings โ Core Management โ Check for updates
4. โ
**Report bug:** If persistent, report on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
***
## Advanced: Dark Mode
Provenance respects tvOS system-wide Dark Mode:
**Enable Dark Mode:**
1. Apple TV **Settings** โ **General** โ **Appearance**
2. Select **Dark โ**
3. Provenance UI will update automatically
***
## Tips for the Best Experience
### For Multiplayer
* ๐ฎ **Pair multiple controllers** - Up to 4 players (system-dependent)
* ๐ฅ **Use same controller types** - Mixing controllers can cause mapping issues
* ๐ **Check all batteries** - Nothing worse than dying mid-game!
* ๐ **Full guide:** [Multiplayer](/using-provenance/multiplayer)
### For Save States
* ๐พ **Use incremental saves** - Create multiple save states per game
* โ๏ธ **iCloud backup** - Enable iCloud sync to never lose progress
* ๐ฏ **Quick save before bosses** - Save state right before difficult sections
### For Streaming/Recording
* ๐บ **Use AirPlay** - Stream your Apple TV to Mac for recording
* ๐ฅ **Built-in screen recording** - Requires Xcode + connected Mac
* ๐ฌ **Capture cards** - HDMI capture cards work great with Apple TV 4K
***
## See Also
* [BIOS Requirements](/getting-started/bios-requirements) โ Required system files
* [Importing ROMs](/using-provenance/importing-roms) โ Add games to your library
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ Full controller compatibility list
* [Multiplayer](/using-provenance/multiplayer) โ Local and online play guide
* [Performance Optimization](/platforms-and-performance/performance-optimization) โ System-specific optimization
* [Provenance Plus](/platforms-and-performance/provenance-plus) โ iCloud sync details
* [Troubleshooting](/help-and-community/troubleshooting) โ Common issues and solutions
***
**Enjoy retro gaming on the big screen! ๐ฎ๐บ**
*For support, visit the* [*Provenance Discord*](https://discord.gg/provenance) *or check the* [*FAQ*](/faqs)*.*
# iPad Features
iPad-specific features โ skins, bezels, keyboard support, and big-screen gaming
Provenance runs natively on iPad and takes advantage of the larger display. From immersive CRT TV bezel skins to Smart Keyboard support, here's what makes iPad a great retro gaming platform.
***
## iPad-Specific Skins
The iPad's larger screen enables **unique skin designs** that aren't possible on iPhone. The community has created stunning iPad-exclusive skins including:
### CRT TV Bezel Skins
Some of the most popular iPad skins simulate playing on a **retro CRT television** โ complete with a realistic TV frame, curved screen effect, and era-appropriate bezels. The game renders inside the "TV screen" while the bezel fills the rest of the iPad display.
**Popular styles:**
* **Retro wood-grain TV** โ 1970s/80s console aesthetic
* **90s tube TV** โ Curved screen with volume knobs
* **Modern CRT monitor** โ Clean frame with scanline overlay
* **Arcade cabinet** โ Full arcade bezel experience
### Where to Find iPad Skins
* [**DeltaStyles.com**](https://deltastyles.com) โ Filter by device type to find iPad-optimized skins
* [**Discord**](https://discord.gg/provenance) โ Community-shared iPad skins
* **Reddit** (r/EmulationOniOS) โ User-created designs
{% hint style="info" %}
When browsing skins on DeltaStyles, look for skins that specify iPad support. Many skins include both iPhone and iPad layouts in a single `.deltaskin` file.
{% endhint %}
### Applying iPad Skins
1. Download a `.deltaskin` file on your iPad
2. Tap the file โ **Open in Provenance**
3. Settings โ **Controller Skins** โ select your system โ choose the iPad skin
4. The skin applies in both portrait and landscape orientations (if the skin supports both)
***
## Landscape and Portrait Modes
The iPad's aspect ratio works well for both orientations:
| Orientation | Best For |
| ------------- | ------------------------------------------------------------------------------- |
| **Landscape** | Console games (NES, SNES, Genesis, PS1, N64) โ matches original TV aspect ratio |
| **Portrait** | Handheld games (Game Boy, GBA, DS, 3DS) โ stacked screens feel natural |
Provenance automatically adjusts the game display and controls based on orientation. Skins can provide different layouts for each orientation.
***
## Keyboard Support
iPad users with a **Smart Keyboard**, **Magic Keyboard**, or any Bluetooth keyboard can play games without on-screen controls:
| Input | Key |
| ------------- | ----------------- |
| D-Pad | Arrow keys |
| Left Stick | W/A/S/D |
| A / B / X / Y | Space / F / Q / E |
| L1 / R1 | Tab / R |
| L2 / R2 | Left Shift / V |
| Menu (Pause) | \~ (tilde) |
Full mappings: [Smart Keyboard Mapping](/using-provenance/controllers-and-controls/smartkeyboard)
***
## External Controller
For the best experience, pair a Bluetooth controller:
* **PlayStation DualSense** โ Full feature support
* **Xbox Wireless Controller** โ Wide compatibility
* **8BitDo controllers** โ Compact, great for travel with iPad
The larger iPad screen combined with a controller makes for an excellent portable retro gaming setup โ especially for games that benefit from a bigger display (RPGs with small text, strategy games, DS games).
***
## Multitasking
Provenance works alongside iPad multitasking features:
* **Slide Over** โ Quick-access Provenance alongside another app
* **Picture in Picture** โ Not available (games require active rendering)
{% hint style="info" %}
For the best gaming performance, use Provenance in full-screen mode and close other apps to maximize available CPU and RAM.
{% endhint %}
***
## Display Considerations
| iPad Feature | Impact |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| **ProMotion (120Hz)** | Smoother UI and menu navigation |
| **Retina display** | Sharp pixel art and crisp skin graphics |
| **Larger screen** | Better for systems with small text (RPGs, strategy) |
| **True Tone** | Warm color adjustment โ disable for more accurate game colors (Settings โ Display & Brightness) |
***
## See Also
* [Skins Guide](/using-provenance/skins-guide) โ Full skin importing and customization guide
* [Controllers & Controls](/using-provenance/controllers-and-controls) โ Bluetooth controller setup
* [Smart Keyboard Mapping](/using-provenance/controllers-and-controls/smartkeyboard) โ Full keyboard controls reference
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Provenance Plus
iCloud sync, beta access, and more โ what Provenance Plus unlocks
**Provenance Plus** is an optional subscription that supports ongoing development and unlocks premium convenience features. Provenance is fully functional without it โ Plus adds cloud sync and early access.
***
## Free vs Plus Comparison
| Feature | Free | Provenance Plus |
| ---------------------------------------------------------------- | ---- | --------------- |
| **All 38+ emulated systems** | Yes | Yes |
| **Full emulation** (save states, cheats, fast forward, shaders) | Yes | Yes |
| **On-screen controls & controller support** | Yes | Yes |
| **Controller skins** | Yes | Yes |
| **RetroAchievements** | Yes | Yes |
| **Multiplayer** | Yes | Yes |
| **Local library management** | Yes | Yes |
| | | |
| **iCloud Sync** (library, saves, settings, skins, BIOS, artwork) | -- | Yes |
| **TestFlight Beta Access** (test new features early) | -- | Yes |
| **Priority Support** (faster help from the team) | -- | Yes |
{% hint style="success" %}
**Every emulation feature is free.** Plus is purely for convenience (cloud sync) and early access (betas). You never need to pay to play games.
{% endhint %}
***
## Pricing
| Plan | Price | Best For |
| ------------ | ----------------- | ------------------------ |
| **Monthly** | $3.99/month | Try it out |
| **Annual** | $39.99/year | Regular users (save 17%) |
| **Lifetime** | $99.99 (one-time) | Long-term supporters |
Subscribe from within the Provenance app โ Settings โ Provenance Plus.
***
## iCloud Sync
The headline Plus feature. Sync your entire Provenance setup across iPhone, iPad, Mac, and Apple TV:
**What syncs:**
* Game library (ROMs)
* Battery saves and save states (with screenshot previews)
* BIOS files
* Controller skins
* Custom cover art
* Settings and preferences
**How it works:**
1. Subscribe to Plus on any device
2. Enable **iCloud Sync** in Settings
3. Your library syncs automatically in the background
4. Sign in on another device โ enable iCloud Sync โ everything downloads
**Smart sync features:**
* Save states show cloud sync status indicators
* Missing saves, BIOS files, and ROMs auto-download when needed
* Sync works across all Apple platforms
{% hint style="info" %}
**Apple TV gets iCloud sync for free** โ no Plus subscription required. tvOS can clear app storage at any time to reclaim space, so CloudKit sync is enabled by default to prevent data loss.
{% endhint %}
***
## TestFlight Beta Access
Plus subscribers get early access to new features and updates via Apple's TestFlight:
* **New cores and systems** โ Test upcoming system support before public release
* **UI improvements** โ Preview interface changes
* **Bug fixes** โ Get fixes faster than the App Store review cycle
* **Feedback channel** โ Direct input on features in development
**How to join:**
1. Subscribe to Provenance Plus
2. Check for TestFlight invitation in the app or your email
3. Install [TestFlight](https://apps.apple.com/us/app/testflight/id899247664) from the App Store
4. Accept the beta invitation
{% hint style="warning" %}
Beta builds may be unstable. Don't use a beta build as your only installation โ keep the stable App Store version for important game sessions.
{% endhint %}
***
## Managing Your Subscription
**View or cancel:**
1. Open **Settings** on your device
2. Tap your **Apple ID** at the top
3. Tap **Subscriptions**
4. Select **Provenance Plus**
5. Modify or cancel
**Restore purchases:**
* If you reinstall Provenance or set up a new device, your subscription restores automatically when you sign in with the same Apple ID
* In-app: Settings โ Provenance Plus โ **Restore Purchases**
**Family Sharing:**
* Provenance Plus subscriptions support Apple Family Sharing โ one subscription covers up to 6 family members
***
## Frequently Asked Questions
Do I lose my data if I cancel Plus?
No. All your local data (ROMs, saves, settings) stays on your device. You just lose the ability to sync across devices. Previously synced data remains on each device where it was downloaded.
Can I use Plus on multiple devices?
Yes โ your subscription is tied to your Apple ID. Sign in on any device and your Plus benefits follow you.
Why is Apple TV sync free?
tvOS aggressively reclaims storage from apps, which can delete your ROMs and saves without warning. To protect users from unexpected data loss, iCloud sync is included free and enabled by default on Apple TV.
Is sideloading free forever?
Yes. If you [sideload](/getting-started/installing-provenance/advanced/sideloading) or [build from source](/getting-started/installing-provenance/advanced/building-from-source), all features (including those that are Plus-only on the App Store) are free. Provenance is open source โ Plus subscriptions on the App Store support development.
***
## See Also
* [Installing from the App Store](/getting-started/installing-provenance/app-store) โ Get Provenance
* [Game Saves](/using-provenance/saves) โ How saves and sync work together
* [Restoring Files](/advanced/restoring-files) โ Manual backup without Plus
***
{% hint style="success" %}
**Thank you for supporting Provenance!** Plus subscriptions fund ongoing development, new system support, and the infrastructure behind iCloud sync.
{% endhint %}
# Virtualizing macOS
Run macOS in a virtual machine to build Provenance from source without a Mac
If you don't have a Mac but want to build Provenance from source, you can run macOS in a virtual machine. This guide covers setting up a macOS VM on Windows or Linux.
{% hint style="info" %}
**Most users don't need this.** Install Provenance from the [App Store](/getting-started/installing-provenance/app-store) or [sideload a pre-built .ipa](/getting-started/installing-provenance/advanced/sideloading) instead. A macOS VM is only needed for building from source.
{% endhint %}
***
## Virtualization Options
{% tabs %}
{% tab title="VMware (Windows)" %}
**Best for:** Windows users with Intel processors
#### Requirements
* **CPU:** Intel processor with VT-x/VT-d support (AMD works but requires extra patches)
* **RAM:** 8 GB minimum (16 GB recommended)
* **Storage:** 80+ GB free disk space
* **Software:** [VMware Workstation Player](https://www.vmware.com/products/workstation-player.html) (free for personal use) or Workstation Pro
#### Setup
1. **Install VMware Workstation** and the [VMware Unlocker](https://github.com/DrDonk/unlocker) (enables macOS as a guest OS option)
2. **Create a new VM:**
* Select **Apple Mac OS X** as the guest OS
* Allocate at least **4 GB RAM** (8 GB recommended for Xcode)
* Set disk size to at least **80 GB** (Xcode alone is \~35 GB)
3. **Configure hardware:**
* **Processors:** 2+ cores
* **USB Controller:** Set to USB 2.0 (required for iOS device detection โ USB 3.0 passthrough is unreliable in VMs)
* Enable:
* Automatically connect new USB devices
* Show all USB input devices
* Share Bluetooth devices with the virtual machine
4. **Install macOS** from your installation media
5. **Install VMware Tools** after macOS boots (improves graphics, clipboard sharing, and performance)
#### Post-Install
1. **Update macOS** โ Open System Settings โ General โ Software Update
2. **Install Xcode** โ Download from the App Store (free, \~35 GB)
3. **Open Terminal** โ Applications โ Utilities โ Terminal
Continue to [Building from Source](/getting-started/installing-provenance/advanced/building-from-source).
{% endtab %}
{% tab title="VirtualBox (Windows/Linux)" %}
**Best for:** Free, cross-platform option
#### Requirements
* **CPU:** Intel or AMD with virtualization support
* **RAM:** 8 GB minimum
* **Storage:** 80+ GB free
* **Software:** [VirtualBox](https://www.virtualbox.org/) (free and open source)
#### Setup
1. **Install VirtualBox** and the Extension Pack
2. **Create a new VM:**
* Type: **Mac OS X**, Version: **macOS 64-bit**
* RAM: **4096 MB** minimum (8192 MB recommended)
* Create a virtual hard disk: **80 GB** or more (VDI, dynamically allocated)
3. **Configure VM settings:**
* **System โ Processor:** 2+ CPUs
* **Display โ Video Memory:** 128 MB
* **USB:** Enable USB 2.0 (EHCI) Controller
4. **Apply required patches** โ VirtualBox needs command-line tweaks to run macOS:
```bash
VBoxManage modifyvm "YourVMName" --cpuidset 00000001 000106e5 00100800 0098e3fd bfebfbff
VBoxManage setextradata "YourVMName" VBoxInternal/Devices/efi/0/Config/DmiSystemProduct "iMac19,1"
VBoxManage setextradata "YourVMName" VBoxInternal/Devices/efi/0/Config/DmiBoardProduct "Mac-AA95B1DDAB278B95"
VBoxManage setextradata "YourVMName" VBoxInternal/Devices/smc/0/Config/DeviceKey "ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc"
VBoxManage setextradata "YourVMName" VBoxInternal/Devices/smc/0/Config/GetKeyFromRealSMC 1
```
5. **Install macOS** and then install Xcode
{% hint style="warning" %}
VirtualBox macOS performance is generally worse than VMware. Expect longer build times.
{% endhint %}
{% endtab %}
{% tab title="UTM (macOS Host)" %}
**Best for:** Running a second macOS version on an existing Mac (Apple Silicon or Intel)
If you have a Mac but need a different macOS version for Xcode compatibility:
1. Download [UTM](https://mac.getutm.app/) (free from GitHub, or paid on App Store)
2. Download a macOS IPSW from [Apple](https://developer.apple.com/macos/) or use the built-in installer
3. Create a new VM โ **Virtualize** โ **macOS**
4. Allocate RAM and storage, then install
{% hint style="info" %}
On Apple Silicon Macs, UTM uses Apple's native Virtualization.framework for near-native performance.
{% endhint %}
{% endtab %}
{% endtabs %}
***
## Performance Tips
Virtual machines are slower than native hardware. These tips help:
* **Allocate adequate RAM** โ 8 GB for the VM if your host has 16+ GB
* **Use an SSD** โ VM disk I/O on a spinning hard drive is painfully slow
* **Close unnecessary host apps** โ Free up CPU and RAM for the VM
* **Use Release builds** โ When building Provenance in Xcode, always use the Release scheme (Debug builds are 5-10x slower and even more so in a VM)
* **Disable Spotlight indexing** inside the VM โ System Settings โ Siri & Spotlight โ uncheck categories
***
## Troubleshooting
iOS device not detected over USB
* Make sure VMware/VirtualBox is **in focus** (click inside the macOS window) before plugging in your device โ otherwise the host OS grabs the USB connection
* Set USB Controller to **USB 2.0** (not 3.0) in VM settings
* On the device, tap **Trust** when the "Trust This Computer?" dialog appears
* In VMware: VM menu โ Removable Devices โ verify your device is connected to the VM
Cannot detect Apple TV 4K over WiFi
Apple TV 4K uses WiFi for Xcode pairing (no USB port). VMs default to NAT networking, which blocks local network discovery.
**Fix:** Change the VM's network adapter from **NAT** to **Bridged** (or **Custom โ VMnet0**) so the VM connects directly to your local network. This enables Bonjour/mDNS discovery needed for Apple TV pairing.
macOS won't boot or shows a black screen
* Verify your CPU supports hardware virtualization (Intel VT-x / AMD-V) โ enable it in BIOS settings
* For VMware: Ensure the [Unlocker](https://github.com/DrDonk/unlocker) is properly installed
* For VirtualBox: Verify all command-line patches were applied correctly
* Try a different macOS version โ some versions work better with certain VM software
Display resolution is wrong or too small
* **VMware:** Install VMware Tools, then use View โ Autosize โ Autofit Guest
* **VirtualBox:** Install Guest Additions (limited macOS support), or set resolution manually:
```bash
VBoxManage setextradata "YourVMName" VBoxInternal2/EfiGraphicsResolution 1920x1080
```
* **In macOS:** System Settings โ Displays โ choose "Default for Display" or select a specific resolution
Xcode build is extremely slow
* Allocate more CPU cores and RAM to the VM
* Use an SSD for VM storage
* Build the **Release** scheme (not Debug)
* Close Xcode's Simulator โ it's not needed when deploying to a physical device
* Consider using a pre-built .ipa via [sideloading](/getting-started/installing-provenance/advanced/sideloading) instead
***
## Alternative: Hackintosh
Instead of a VM, you can install macOS directly on compatible PC hardware (a "Hackintosh"). This gives near-native performance but requires compatible hardware and more setup effort.
**Resources:**
* [OpenCore Install Guide](https://dortania.github.io/OpenCore-Install-Guide/) โ Modern Hackintosh bootloader
* [tonymacx86](https://www.tonymacx86.com/) โ Hardware compatibility lists and guides
{% hint style="warning" %}
Hackintosh setups are not officially supported by Apple and require specific hardware. Research compatibility before attempting.
{% endhint %}
***
{% hint style="success" %}
**Reminder:** Most users should install from the [App Store](/getting-started/installing-provenance/app-store) or [sideload](/getting-started/installing-provenance/advanced/sideloading) instead of building from source. A macOS VM is only needed for compiling Provenance yourself.
{% endhint %}
# Launch ROMs via URL
Open games directly using Provenance's URL scheme
Provenance registers a custom URL scheme (`provenance://`) that lets you launch games directly from Safari, Shortcuts, home screen bookmarks, or other apps.
***
## URL Scheme Syntax
```
provenance://open?[parameter]=[value]
```
### Parameters
You can identify a game using any of these parameters (or combine them):
| Parameter | Description | Example |
| --------- | ------------------------------------- | ------------------------------------------------------------- |
| `md5` | Game's MD5 hash (exact match) | `provenance://open?md5=85260599FDADA2E137053A8647AA0D06` |
| `title` | Game title (exact match, URL-encoded) | `provenance://open?title=Super%20Mario%20World` |
| `system` | System identifier (use with `title`) | `provenance://open?title=Sonic&system=com.provenance.genesis` |
### Combining Parameters
Use `title` + `system` together when you have games with the same name on different systems:
```
provenance://open?title=Tetris&system=com.provenance.gb
provenance://open?title=Tetris&system=com.provenance.nes
```
{% hint style="info" %}
If `system` is provided but invalid, the game will **not** open โ even if a title match exists. Double-check your system identifier.
{% endhint %}
***
## System Identifiers
Use these identifiers with the `system` parameter:
| System | Identifier |
| ------------------------- | ----------------------------- |
| **Nintendo** | |
| NES / Famicom | `com.provenance.nes` |
| Famicom Disk System | `com.provenance.fds` |
| SNES / Super Famicom | `com.provenance.snes` |
| Nintendo 64 | `com.provenance.n64` |
| Game Boy | `com.provenance.gb` |
| Game Boy Color | `com.provenance.gbc` |
| Game Boy Advance | `com.provenance.gba` |
| Virtual Boy | `com.provenance.vb` |
| Pokemon mini | `com.provenance.pokemonmini` |
| Nintendo DS | `com.provenance.nds` |
| Nintendo 3DS | `com.provenance.3ds` |
| **Sega** | |
| SG-1000 | `com.provenance.sg1000` |
| Master System | `com.provenance.mastersystem` |
| Genesis / Mega Drive | `com.provenance.genesis` |
| Game Gear | `com.provenance.gamegear` |
| Sega CD / Mega-CD | `com.provenance.segacd` |
| Sega 32X | `com.provenance.32x` |
| Sega Saturn | `com.provenance.saturn` |
| Dreamcast | `com.provenance.dreamcast` |
| **Sony** | |
| PlayStation | `com.provenance.psx` |
| PSP | `com.provenance.psp` |
| **Atari** | |
| Atari 2600 | `com.provenance.2600` |
| Atari 5200 | `com.provenance.5200` |
| Atari 7800 | `com.provenance.7800` |
| Atari Lynx | `com.provenance.lynx` |
| Atari Jaguar | `com.provenance.jaguar` |
| **NEC** | |
| PC Engine / TurboGrafx-16 | `com.provenance.pce` |
| TurboGrafx-CD | `com.provenance.pcecd` |
| PC Engine SuperGrafx | `com.provenance.sgx` |
| PC-FX | `com.provenance.pcfx` |
| **SNK** | |
| Neo Geo Pocket | `com.provenance.ngp` |
| Neo Geo Pocket Color | `com.provenance.ngpc` |
| **Bandai** | |
| WonderSwan | `com.provenance.ws` |
| WonderSwan Color | `com.provenance.wsc` |
| **Other** | |
| ColecoVision | `com.provenance.colecovision` |
***
## Use Cases
### Add a Game to Your Home Screen
Create a "shortcut" icon that launches directly into a game:
1. Open **Safari** on your iPhone/iPad
2. Type the URL in the address bar:
```
provenance://open?title=Super%20Mario%20World
```
3. Tap **Share** (the share icon) โ **Add to Home Screen**
4. Name it (e.g., "Super Mario World") and tap **Add**
5. Tap the new icon to launch directly into the game
{% hint style="info" %}
The home screen icon will use a generic Safari bookmark icon. For a custom icon, use the Shortcuts app method below.
{% endhint %}
### iOS Shortcuts Automation
Build Shortcuts workflows that launch games:
{% tabs %}
{% tab title="Simple Game Launcher" %}
1. Open the **Shortcuts** app
2. Tap **+** to create a new shortcut
3. Add action: **Open URLs**
4. Enter: `provenance://open?title=Your%20Game%20Name`
5. Tap the shortcut name โ **Add to Home Screen**
6. Choose a custom icon and name
{% endtab %}
{% tab title="Game Picker Menu" %}
Create a menu that lets you choose from your favorite games:
1. Open **Shortcuts** โ tap **+**
2. Add action: **Choose from Menu**
3. Add options for each game (e.g., "Mario", "Zelda", "Sonic")
4. Under each option, add **Open URLs** with the matching URL:
* `provenance://open?title=Super%20Mario%20World`
* `provenance://open?title=Legend%20of%20Zelda`
* `provenance://open?title=Sonic%20the%20Hedgehog&system=com.provenance.genesis`
5. Add to Home Screen with a custom icon
{% endtab %}
{% endtabs %}
### Link from Other Apps
Use the URL scheme anywhere that supports links:
* **Notes app** โ Paste URLs as tappable links to organize your game collection
* **Reminders** โ Link a game for "play later" lists
* **Web pages** โ Create an HTML page with links to your games
* **Other automation apps** โ Scriptable, Toolbox Pro, etc.
***
## URL Encoding
Game titles with special characters must be URL-encoded:
| Character | Encoded | Example |
| ----------- | ----------- | ----------------------- |
| Space | `%20` | `Super%20Mario%20Bros` |
| Apostrophe | `%27` | `Kirby%27s%20Adventure` |
| Colon | `%3A` | `Castlevania%3A%20SOTN` |
| Ampersand | `%26` | `Toejam%20%26%20Earl` |
| Parentheses | `%28` `%29` | `Pokemon%20%28Red%29` |
{% hint style="info" %}
**Tip:** The Shortcuts app handles URL encoding automatically when you use the "URL Encode" action. Safari also auto-encodes when you type in the address bar.
{% endhint %}
***
## Troubleshooting
URL opens Provenance but no game launches
* **Title mismatch:** The title must match exactly as it appears in your Provenance library (including capitalization and punctuation). Check your library for the exact name.
* **Invalid system ID:** If using the `system` parameter, verify the identifier from the table above. An invalid system ID causes the lookup to fail silently.
* **Game not imported:** The game must already be in your library. URLs don't import games โ they only open existing ones.
"Cannot Open Page" error in Safari
* Provenance must be installed on the device
* Make sure the URL starts with `provenance://` (not `http://`)
* Check for typos in the URL
Shortcut doesn't work
* In Shortcuts, make sure you're using the **Open URLs** action (not "Open App")
* Verify the URL is correct by testing it in Safari first
* Ensure Provenance is allowed in Settings โ Shortcuts
***
{% hint style="success" %}
**Pro tip:** Use the `md5` parameter for the most reliable matching โ it uniquely identifies a ROM regardless of title or system. Find a game's MD5 in Provenance by long-pressing โ Game Info.
{% endhint %}
# Restoring Files
How to back up and restore ROMs, saves, BIOS files, and other data
Whether you're switching devices, reinstalling Provenance, or migrating from a sideloaded build to the App Store version, this guide covers how to back up and restore your data.
***
## What Can Be Backed Up?
| Data | Location | Notes |
| --------------------------------- | ---------------------------------- | --------------------------------------------------------- |
| **Battery saves** (in-game saves) | `Battery/` | Most important โ these are your actual game progress |
| **Save states** | `Save States/` | Quick-save snapshots; may not survive app version changes |
| **ROMs** | `com.provenance.[system]/` folders | Your game files |
| **BIOS files** | `BIOS/` | System firmware files |
| **Cover art** | `Custom Artwork/` | Any custom images you've added |
| **Controller skins** | Skins storage | Custom `.deltaskin` files |
{% hint style="warning" %}
**Save states are not guaranteed to be compatible across app versions.** Core updates can break save state compatibility. Always create **in-game saves** (battery saves) before updating Provenance.
{% endhint %}
***
## Option 1: iCloud Sync (Easiest)
If you use **Provenance Plus**, iCloud automatically syncs your library, saves, BIOS files, custom artwork, and skins across all your devices.
**What syncs:**
* ROMs and game library
* Battery saves and save states
* BIOS files
* Controller skins
* Custom cover art
* Settings and preferences
**How to enable:**
1. Open Provenance โ Settings
2. Enable **iCloud Sync**
3. Data syncs automatically in the background
**Restoring on a new device:**
1. Install Provenance from the App Store
2. Sign in with the same Apple ID
3. Subscribe to Provenance Plus (or restore your subscription)
4. Enable iCloud Sync โ your library will download automatically
{% hint style="info" %}
**Apple TV users:** iCloud/CloudKit sync is included free โ no Provenance Plus subscription required.
{% endhint %}
***
## Option 2: Manual Backup via Files App (iOS/iPadOS)
### Backing up
1. Open the **Files** app on your device
2. Navigate to **On My iPhone** (or **On My iPad**) โ **Provenance**
3. You'll see folders like `Battery/`, `Save States/`, and system-specific ROM folders
4. **Select the folders you want to back up** โ tap **Share** โ save to:
* iCloud Drive
* A computer via AirDrop
* Any cloud storage (Dropbox, Google Drive, etc.)
### Restoring
1. Install Provenance (fresh install or update)
2. **Launch Provenance once** and open a game briefly โ this creates the folder structure
3. Open the **Files** app โ navigate to **Provenance**
4. Copy your backed-up files back into the matching folders:
* Battery saves โ `Battery/`
* Save states โ `Save States/`
* ROMs โ import via normal [import methods](/using-provenance/importing-roms)
{% hint style="warning" %}
**Do NOT rename files.** ROM filenames must match exactly โ Provenance links saves to ROMs by filename. If a filename changes, the app won't associate your saves with the correct game.
{% endhint %}
***
## Option 3: Manual Backup via Web Server
Best for **bulk transfers** and **Apple TV** (which doesn't have the Files app).
### Backing up
1. Open Provenance โ tap **+** (or Settings โ Import/Export) to start the Web Server
2. Note the IP address shown (e.g., `http://192.168.1.42`)
3. On your computer:
{% tabs %}
{% tab title="Web Browser" %}
1. Go to `http://[device-ip]` in your browser
2. Browse to `Battery/`, `Save States/`, and ROM folders
3. Download the files you need
{% endtab %}
{% tab title="WebDAV (Finder/Explorer)" %}
1. **Mac:** Finder โ Go โ Connect to Server โ `http://[device-ip]:81`
2. **Windows:** Map Network Drive โ `http://[device-ip]:81`
3. Connect as Guest
4. Provenance mounts as a drive โ copy files to your computer
{% endtab %}
{% endtabs %}
### Restoring
1. Start the Web Server in Provenance (same steps as above)
2. Upload your files back:
* **ROMs and BIOS:** Upload to the `Imports/` folder โ Provenance auto-sorts them
* **Battery saves:** Place directly into `Battery/`
* **Save states:** Place directly into `Save States/`
***
## Option 4: Desktop File Manager (USB)
For direct USB access to Provenance's files:
1. Connect your device to your computer via USB
2. **macOS (Catalina+):** Open **Finder** โ select your device โ **Files** tab โ **Provenance**
3. **Windows/older macOS:** Use a third-party tool:
* [iMazing](https://imazing.com/) (recommended)
* [iExplorer](https://macroplant.com/iexplorer)
* [DiskAid](https://imazing.com/diskaid)
4. Browse Provenance's file structure and copy files in either direction
***
## Migrating Between Install Methods
### Sideloaded โ App Store
The App Store and sideloaded versions use **separate data directories**. To migrate:
1. **Back up** from the sideloaded version (Files app, Web Server, or USB โ see above)
2. **Delete** the sideloaded version
3. **Install** from the App Store
4. **Restore** your backed-up files into the new installation
5. If using Provenance Plus, enable iCloud Sync to prevent future data loss
### App Store โ Sideloaded (or vice versa with different Bundle IDs)
Same process โ back up, install the new version, restore files.
***
## Folder Structure Reference
```
Provenance/
โโโ Imports/ โ Drop ROMs and BIOS here for auto-import
โโโ Battery/ โ In-game saves (most important!)
โโโ Save States/ โ Quick-save state files
โโโ BIOS/ โ System firmware files
โ โโโ com.provenance.[system]/
โโโ Custom Artwork/ โ User-added cover art
โโโ com.provenance.[system]/ โ ROM storage by system
โโโ com.provenance.nes/
โโโ com.provenance.snes/
โโโ com.provenance.gba/
โโโ ...
```
***
## Troubleshooting
Saves don't appear after restoring
* Verify filenames match exactly (including extensions and capitalization)
* Launch the game once to create the folder structure, then quit and place your save files
* Force quit Provenance and reopen to refresh the database
Save states crash or don't load
Save states are tied to specific emulator core versions. If you've updated Provenance (or switched cores), old save states may be incompatible. **Battery saves** (in-game saves) are always compatible โ use those for long-term game progress.
ROMs show as "Unknown" after restoring
Provenance matches ROMs by checksums (MD5/CRC). If you see unmatched games:
1. Long-press the game โ **Game Settings** โ manually assign the system
2. Or delete and re-import the ROM through the standard [import process](/using-provenance/importing-roms)
Can't access Provenance folder in Files app
* Make sure you're looking under **On My iPhone/iPad**, not iCloud Drive (unless you have iCloud Sync enabled)
* If the Provenance folder doesn't appear, launch and quit Provenance once to create it
* Check Settings โ Provenance โ ensure file access is enabled
***
{% hint style="success" %}
**Best practice:** Enable **Provenance Plus iCloud Sync** and let backups happen automatically. For extra safety, create in-game saves (not just save states) for your most important games.
{% endhint %}
# Advanced Installation FAQ
Advanced installation FAQ for sideloading, building from source, and developer workflows
This FAQ is for advanced users who are sideloading or building Provenance from source. **Most users should install from the App Store** - see the main [FAQ](/faqs) instead.
***
## Sideloading
What if I don't have a Mac?
**Sideloading (cross-platform):**
* โ
Windows, Mac, Linux all supported
* Use [AltStore](https://altstore.io/) or [Sideloadly](https://sideloadly.io/)
* Download `.ipa` from [GitHub Releases](https://github.com/Provenance-Emu/Provenance/releases)
**Building from source (requires macOS):**
* โ Windows/Linux cannot build iOS apps
* โ
Use a Hackintosh or macOS virtual machine ([Virtualizing macOS](/advanced/virtualizing-macos))
* โ
Or sideload the pre-built release instead
Can I install without a computer?
**Officially: No safe method exists.**
โ **DO NOT** use 3rd-party signing services - they:
* Install malware, adware, or tracking profiles
* Get revoked by Apple (you lose your games/saves)
* Violate Apple's terms (can brick your device)
* Steal your Apple ID credentials
**Legitimate options:**
1. โ
**App Store** - Install directly on device (no computer needed)
2. โ
**Borrow a friend's computer** - Sideload once, re-sign every 7 days
3. โ
**Use a paid Apple Developer account** - Provisioning lasts 1 year
Why does Provenance not install?
**Common issues:**
1. **Certificate error / "Untrusted Developer"**
* Settings โ General โ VPN & Device Management
* Trust the developer profile
2. **"App is already installed"**
* Delete existing Provenance first
* Or use a different bundle ID when building
3. **"Provisioning profile expired"**
* Free Apple Developer accounts expire every 7 days
* Re-sign with AltStore/Sideloadly
* Or upgrade to paid account ($99/year)
4. **AltStore/Sideloadly errors**
* Make sure the [Apple Devices app](https://apps.microsoft.com/detail/9NP83LWLPZ9K) (formerly iTunes) and iCloud are installed (Windows)
* Update AltServer to latest version
* Check firewall isn't blocking connection
**Full guide:** [Sideloading](/getting-started/installing-provenance/advanced/sideloading)
How do I re-sign every 7 days?
**Free Apple Developer accounts** expire provisioning profiles every 7 days.
**Options:**
1. **AltStore (easiest)**
* Install AltServer on your Mac/PC
* Keep it running - auto-refreshes every 6 days
* No manual work needed!
2. **Manual re-signing**
* Use Sideloadly, iOS App Signer, or Xcode
* Re-install `.ipa` every 6-7 days
* Data/saves are preserved
3. **Upgrade to paid account**
* $99/year Apple Developer Program
* Provisioning lasts 1 year (re-sign annually)
What is a provisioning profile?
A **provisioning profile** is a file that allows an app to run on a specific device. It contains:
* Your Apple Developer certificate
* App bundle ID
* List of authorized devices (UDIDs)
* Expiration date
**Free accounts:**
* Max 3 apps simultaneously
* 7-day expiration
* Max 10 devices per year
**Paid accounts:**
* Unlimited apps
* 1-year expiration
* Unlimited devices
**Where to find:** Xcode โ Preferences โ Accounts โ \[Your Apple ID] โ Manage Certificates
***
## Building from Source
Is there a Cydia repo?
**No.** Provenance is not distributed via Cydia.
If you're jailbroken, you can still install Provenance via:
* App Store (recommended)
* Sideloading (works on jailbroken devices)
* Building from source
Will you release an .ipa of the beta?
**Beta builds are available** on GitHub:
* [Releases](https://github.com/Provenance-Emu/Provenance/releases) - Stable releases
* [Actions](https://github.com/Provenance-Emu/Provenance/actions) - Dev builds (requires GitHub login)
**Note:** Beta builds may be unstable. Use at your own risk.
**App Store users:** Subscribe to Provenance Plus for TestFlight beta access (official, stable betas).
When is the next release?
**Check development status:**
* [Milestones](https://github.com/Provenance-Emu/Provenance/milestones) - Planned releases
* [Projects](https://github.com/Provenance-Emu/Provenance/projects) - Current work
* [Discord](https://discord.gg/provenance) - Community discussion
**We don't commit to release dates** - small team, releases when ready.
**App Store users:** Updates are automatic - no need to track releases!
Why is my build slower than the App Store version?
**You probably built the DEBUG version.**
**How to tell:**
* App name: **Prov Debug** (not "Provenance")
* Settings โ Version shows `DEBUG`
**Fix:**
1. Open project in Xcode
2. Select scheme: **Provenance-Release** (iOS) or **ProvenanceTV-Release** (tvOS)
3. Build and run
4. โ
Release version is 5-10x faster!
**Why debug is slow:**
* Extra logging and validation
* No compiler optimizations
* Memory leak detection overhead
* Designed for development, not gameplay
***
## Developer Workflows
How do I use Provenance Plus features when sideloading?
**Requirement:** Use a **unique bundle ID** when building.
**Steps:**
1. Open project in Xcode
2. Select **Provenance** target
3. **Signing & Capabilities** tab
4. Change **Bundle Identifier** to something unique:
* Default: `com.provenance-emu.provenance`
* Yours: `com.yourname.provenance` (or anything unique)
5. Build and install
6. Subscribe to Provenance Plus in-app
7. โ
Plus features (iCloud sync, etc.) now work
**Why?** App Store version uses the default bundle ID. Sideloaded apps with the same ID can't verify subscriptions.
Can I run beta and stable side-by-side?
**Yes!** Use different bundle IDs for each.
**Setup:**
1. **Stable:** Keep default bundle ID
2. **Beta:** Change to `com.yourname.provenance-beta`
3. Build and install both
**Result:** Two separate apps, independent data.
**Note:** Only enable iCloud sync on ONE version to avoid conflicts.
### Where did you install the app from?
**Why we ask:**
3rd-party signing services are dangerous:
* โ Inject malware, adware, tracking
* โ Steal Apple ID credentials
* โ Get revoked by Apple (lose all data)
* โ Violate Apple ToS
**Official sources only:**
* โ
**App Store** (safest)
* โ
**GitHub Releases** (sideload yourself)
* โ
**Build from source** (Xcode)
**If you used a 3rd-party service:**
1. Delete the app immediately
2. Remove any profiles (Settings โ General โ VPN & Device Management)
3. Change your Apple ID password
4. Re-install from official source
**We cannot support 3rd-party builds** - they cause:
* Broken features
* Crashes
* Security vulnerabilities
* Data loss when profiles are revoked
***
## Troubleshooting Advanced Installation
App crashes at launch after 7 days
**Cause:** Free Apple Developer provisioning expired.
**Solutions:**
1. โ
**Re-sign with AltStore** - Automatic refresh every 6 days
2. โ
**Re-sign with Sideloadly** - Manual re-install every 6-7 days
3. โ
**Upgrade to paid account** - Lasts 1 year
**Data safe?** Yes! Saves/ROMs are preserved when re-signing.
App crashes immediately after install (Sideloadly / LiveContainer / ATVLoadly)
Crashes within 1โ2 seconds of launch โ before any UI appears โ almost always means an **entitlement problem** introduced during re-signing. The tool stripped or failed to re-inject a capability Provenance needs (Metal GPU, game controller access, JIT, background audio, etc.) and iOS/tvOS silently kills the app.
**Quick steps:**
1. Get the crash log โ it tells you exactly what failed ([how to read crash logs](/getting-started/installing-provenance/advanced/sideloading#reading-crash-logs))
2. In the log, look for `Termination Reason` โ a code like `CODESIGNING 0x1` confirms an entitlement issue
3. Try AltStore instead โ it handles Provenance's entitlements more reliably than most tools
4. If using **LiveContainer**: this is not supported โ LiveContainer restricts Metal GPU access and JIT, which Provenance requires. Install normally via AltStore.
5. If using **ATVLoadly on Raspberry Pi**: update to the latest version and check the [ATVLoadly GitHub issues](https://github.com/ipa-meister/atvloadly) for Provenance-specific notes
**Full troubleshooting guide:** [Sideloading โ Crash on Launch](/getting-started/installing-provenance/advanced/sideloading#app-installs-but-crashes-immediately-on-launch)
"Unable to install Provenance"
**Fixes:**
1. **Check storage space** โ Provenance is 2.5 GB, need \~5 GB free for installation
2. **Delete existing version** โ Remove old Provenance first, or use different bundle ID
3. **Update Xcode / signing tools** โ Xcode โ Check for Updates; Update AltStore/Sideloadly
4. **Verify Apple ID** โ Xcode โ Preferences โ Accounts โ Remove and re-add Apple ID
Xcode says "Signing certificate expired"
**Cause:** Your Apple Developer certificate expired.
**Fix (free account):**
1. Xcode โ Preferences โ Accounts
2. Select your Apple ID
3. Click **Manage Certificates**
4. Delete old certificate
5. Click **+** โ **iOS Development**
6. โ
New certificate created
**Fix (paid account):**
1. Go to [developer.apple.com](https://developer.apple.com)
2. Certificates โ Revoke old one
3. Create new certificate
4. Download and install in Xcode
Can't find my UDID
**UDID** = Unique Device Identifier (only needed for sideloading/development)
**How to find:**
1. Connect device to Mac
2. Open **Finder** โ Select device
3. Click serial number โ Changes to UDID
4. Right-click โ **Copy**
**Or use online tools:**
* [ipsw.me/device-finder](https://ipsw.me/device-finder)
* [udid.tech](https://udid.tech)
**Full guide:** [UDID Registration](/help-and-community/udid)
***
## Beta Testing
How do I become a beta tester?
**Option 1: Provenance Plus (recommended)**
* Subscribe to Provenance Plus
* Get TestFlight beta access
* Official, stable betas
* Priority support
**Option 2: Build from source**
* Clone `develop` branch from GitHub
* Build in Xcode
* Very latest code (may be unstable)
* Report bugs on GitHub Issues
**Beta tester requirements:**
1. โ
Read [Issues Usage](https://github.com/Provenance-Emu/Provenance/wiki/Issues-Usage)
2. โ
Only report against latest build
3. โ
Check existing issues before reporting
4. โ
Follow #git-updates on Discord
**Note:** Using beta โ beta testing. Active participation required!
***
## Still Need Help?
{% hint style="success" %}
๐ฌ Join our [Discord](https://discord.gg/provenance) - #advanced-help channel
๐ Found a bug? Report on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
๐ General questions? See main [FAQ](/faqs)
{% endhint %}
***
*For most users, we recommend installing from the App Store instead of sideloading or building from source.*
# Troubleshooting
Solutions for common issues with Provenance on iOS, iPadOS, macOS, tvOS, and visionOS
{% hint style="warning" %}
**Provenance-Emu is a small team of volunteers.** Before reaching out, check this guide and the [FAQ](/faqs) โ your answer is probably here.
{% endhint %}
**Quick links:** [Crashes](#app-crashes) | [Performance](#performance-issues) | [ROMs & Import](#rom-and-import-issues) | [Controllers](#controller-issues) | [iCloud Sync](#icloud-sync-issues) | [Saves](#save-issues) | [Skins](#skin-issues) | [Installation](#installation-issues) | [Advanced Debugging](#advanced-debugging)
***
## App Crashes
Crashes on Launch
**App Store users:**
1. Ensure your device is on **iOS 16.0+** (Settings โ General โ About)
2. Restart your device (full power off โ wait 10 seconds โ power on)
3. Delete and reinstall Provenance from the App Store
4. If it persists, report on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues)
**Sideloaders:** If the app worked before but crashes after \~7 days, your provisioning profile has expired. Free Apple Developer accounts expire every 7 days โ re-sign with AltStore or Sideloadly. Your saves and ROMs are safe. See [Advanced Installation FAQ](/advanced/faqs-advanced) for details.
Crashes When Importing ROMs
* **Archives containing folders will crash the app.** Archive only loose files โ do not include folder structure inside a .zip.
* **Filenames with extra periods** (e.g., `Game.v1.2.rom`) can cause crashes. Rename to remove extra dots before the extension.
* **CD-based / multi-file ROMs** should be uploaded one at a time. If importing breaks, delete the game from the app and from the file system (ROMs and Imports folders), then re-upload.
Crashes on Library Screen
This may indicate a **corrupted database**. Symptoms:
* Games appear duplicated
* Metadata or artwork missing
* Consistent crashes when browsing library
**Fix:** See [Corrupted Database](#corrupted-database) under Large Library Issues.
General Crash Steps
1. **Force quit and restart** โ Double-tap Home โ Swipe up on Provenance โ Relaunch
2. **Update to latest version** โ App Store โ Provenance โ Update
3. **Restart device** โ Full power cycle
4. **Reinstall** โ Delete app โ Reinstall from App Store (saves in iCloud are preserved with Provenance Plus)
***
## Performance Issues
Game is Slow or Stuttering
Try these fixes in order:
1. **Close background apps** โ Double-tap Home, swipe up on all other apps
2. **Disable visual filters** โ Settings โ Turn off Smoothing and CRT Filter
3. **Lower internal resolution** โ Settings โ Resolution Multiplier โ 1x or 2x
4. **Enable frameskip** โ Settings โ Frameskip โ Auto
5. **Try an alternate core** โ If available, some cores perform better for certain games
6. **Restart device** โ Power off for 10 seconds, then power on
**Check your build:** If the app is named "Prov Debug" on the Home Screen or Settings shows "DEBUG", you built the debug version by mistake. Debug builds have extra logging and no compiler optimizations โ they're significantly slower. Rebuild using the `Provenance-Release` (iOS) or `ProvenanceTV-Release` (tvOS) scheme.
Specific Game is Slow, Others Are Fine
* Some games are inherently demanding (e.g., GoldenEye 007, Conker's Bad Fur Day on N64)
* Try a different ROM dump โ bad/corrupted ROMs can hurt performance
* Check online compatibility lists for the emulator core
* Update Provenance โ cores improve with each release
Audio Crackling or Popping
This means the CPU can't keep up with the audio buffer.
1. Enable frameskip (Settings โ Frameskip โ Auto)
2. Close apps playing background audio
3. Switch from Bluetooth to wired headphones/speakers (Bluetooth audio adds latency)
4. Disable in-game audio settings if available
### Device Performance Guide
| Device | What Runs Well | May Struggle |
| ----------------------------- | -------------------------------- | -------------------------------------- |
| **iPhone 8 / SE 2nd-3rd gen** | NES, SNES, GB, GBA, Genesis, PS1 | N64 (some titles), GameCube |
| **iPhone 11-13** | All above + N64, PSP | GameCube, Dreamcast (demanding titles) |
| **iPhone 14+ / M1 iPad** | All systems | โ |
| **Apple TV HD** | 16-bit and earlier, PS1 | N64 (minor slowdown) |
| **Apple TV 4K** | All systems | โ |
| **Mac (Apple Silicon)** | All systems | โ |
**Full guide:** [Performance Optimization](/platforms-and-performance/performance-optimization)
***
## ROM and Import Issues
ROMs Won't Import
1. **Check file format** โ See [Formatting ROMs](/using-provenance/roms/formatting-roms) for supported formats per system
2. **Don't include folders in archives** โ Zip only the ROM files, not a folder containing them
3. **Check for extra dots in filenames** โ Files like `Game.v1.2.rom` can cause issues; rename to `Game v1-2.rom`
4. **Verify the ROM isn't corrupted** โ Re-download if the file hash doesn't match known good dumps
5. **Restart Provenance** โ Force quit and relaunch after importing
Games Missing from Library After Import
* **Wrong file format** โ Loose `.bin` files from CD-based games may be detected as Sega Genesis ROMs. Use `.cue + .bin` pairs or `.chd` format instead.
* **Missing BIOS** โ Some systems won't show games without BIOS files. See [BIOS Requirements](/getting-started/bios-requirements).
* **ROM in Conflicts folder** โ If auto-detection fails, the ROM may be in the Conflicts folder. Check via the web server or Files app and move it to the correct system folder.
* **Re-import** โ Delete the game from the library, then re-add the ROM.
Multi-Disc Games Not Working
Multi-disc games (e.g., Final Fantasy VII on PS1) require an M3U playlist file:
1. Create a text file named `GameName.m3u`
2. List each disc on its own line:
```
GameName (Disc 1).chd
GameName (Disc 2).chd
GameName (Disc 3).chd
```
3. Import the `.m3u` file along with all disc files
**Full guide:** [Advanced ROM Management](/using-provenance/roms/advanced-management#multi-disc-games-advanced)
Region Pack ROMs (Multiple Versions in One Archive)
If importing an archive creates multiple identical-looking games, the archive likely contains multiple region versions. Extract the archive, keep only the region you want, re-archive, and re-import.
Black Screen After Launching Game
1. **Missing BIOS** โ PlayStation, Sega CD, Saturn, and Dreamcast require BIOS files. Check [BIOS Requirements](/getting-started/bios-requirements).
2. **Corrupted ROM** โ Try a different dump of the same game.
3. **Wrong core** โ If multiple cores are available, try switching to an alternate core.
4. **Report it** โ If the issue persists, report on [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues) with the game name and system.
***
## Controller Issues
Controller Won't Pair
**PlayStation / Xbox controllers:**
1. Put controller in pairing mode:
* **PS4/PS5:** Hold **Share + PS button** until light flashes rapidly
* **Xbox:** Hold **Pairing button** (top edge) until Xbox logo flashes
2. On device: **Settings โ Bluetooth** โ Select controller
3. If it doesn't appear, power cycle the controller and try again
**MFi controllers:** Usually pair automatically when turned on near the device. If not, check Settings โ Bluetooth.
Controller Keeps Disconnecting
1. **Check battery** โ Low battery is the #1 cause of disconnects
2. **Reduce Bluetooth interference** โ Move WiFi routers, microwave ovens, and other Bluetooth devices away
3. **Apple TV: Use Ethernet** โ Wired internet frees up the WiFi/Bluetooth antenna, improving stability
4. **Forget and re-pair** โ Settings โ Bluetooth โ Tap (i) on controller โ Forget This Device โ Re-pair
Buttons Not Responding or Wrong Mapping
1. **Update controller firmware** โ Connect to PS5/Xbox console to update, or use the manufacturer's app (8BitDo Firmware Updater, etc.)
2. **Check MFi profile limitations** โ MFi controllers lack Select/Start; Provenance maps L2 = Select, R2 = Start for systems that need them
3. **iCade controllers** โ These use keyboard hacks and have limitations. Only one iCade controller can be used at a time. Cannot use iCade and MFi simultaneously.
4. **Restart the game** โ Close and relaunch the current game
**Full guide:** [Controllers & Controls](/using-provenance/controllers-and-controls/controllers) | [Controller Recommendations](/using-provenance/controllers-and-controls/controller-reviews)
***
## iCloud Sync Issues
Sync Not Working
**Requirements:**
* Active **Provenance Plus** subscription (Apple TV gets free CloudKit sync)
* Available iCloud storage
* Active internet connection on all devices
* Same Apple ID signed in on all devices
**Fixes:**
1. Toggle sync off and back on โ Settings โ iCloud Sync โ OFF โ wait 10 seconds โ ON
2. Force quit Provenance and relaunch
3. Check iCloud storage โ Settings โ \[Your Name] โ iCloud (may be full)
4. Wait 10-15 minutes โ Large libraries take time to sync initially
Sync is Stuck or Slow
1. Force quit Provenance
2. Disable iCloud Sync in Provenance settings
3. Re-enable iCloud Sync
4. Restart device
5. Wait 10-15 minutes for the queue to process
"Not Enough iCloud Storage"
1. Check usage: Settings โ \[Your Name] โ iCloud โ Manage Storage
2. Delete old device backups you no longer need
3. Upgrade iCloud plan ($0.99/month for 50 GB)
4. Disable sync for less-played systems to reduce usage
Sync Conflicts Between Devices
* Only enable iCloud sync on **one version** of Provenance (don't sync both App Store and sideloaded versions)
* If using multiple devices, let one device finish syncing before starting the other
* If saves conflict, the most recent save wins
**Full guide:** [iCloud Sync Troubleshooting](/using-provenance/roms/advanced-management#troubleshooting-icloud-issues)
***
## Save Issues
Battery Save Not Loading
* Filename must match exactly: `[ROM-Filename].sav`
* The save must be from the same region/version of the ROM โ saves are not compatible across different ROM versions
* Try re-importing the save file
Save States Not Working After Update
{% hint style="danger" %}
**Save state compatibility between app updates is NOT guaranteed.** Core updates can change how save states are stored, making old states incompatible.
{% endhint %}
**Best practices:**
* Before updating Provenance, launch important games and create **in-game saves** (battery saves) โ these are more portable than save states
* Save states are tied to the specific emulator core version โ switching cores means old states won't load
* Battery saves (`.sav` / `.srm`) are the safest long-term save format
Save States from Other Emulators
Save states from RetroArch or other emulators generally won't work unless they use the **exact same core version**. Battery saves (`.srm`, `.sav`) are much more compatible across emulators.
**Full guide:** [Game Saves](/using-provenance/saves)
***
## Skin Issues
Skin Not Showing in Browser
1. Check file extension โ must be `.deltaskin`, not `.zip`
2. Verify system compatibility โ not all skins support all systems (DS not supported; 3DS not supported on tvOS)
3. Force quit Provenance and reopen
4. Re-import the skin
Skin Looks Corrupted or Glitchy
1. Re-download the skin (may have been corrupted during download)
2. Check device compatibility (some skins are iPhone-only or iPad-only)
3. Update Provenance to the latest version
4. Report to the skin creator via DeltaStyles or GitHub
Buttons Don't Respond with Custom Skin
1. Check that the skin's `info.json` has correct button mappings
2. Toggle "Touch Controls" off and back on in Settings
3. Try a different skin to isolate if it's skin-specific
4. Restart the game
Performance Slowdown with Skins
Complex skins with detailed graphics can add overhead. Try a simpler skin, close background apps, and disable CRT/Smoothing filters.
**Full guide:** [Skins Guide](/using-provenance/skins-guide)
***
## Installation Issues
{% tabs %}
{% tab title="App Store" %}
| Problem | Solution |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| "Not available in your region" | Use different Apple ID from supported region, or sideload instead |
| "Not enough storage" | Provenance needs \~2.5 GB + space for games. Free up 10+ GB recommended |
| Installation stuck | Force-close App Store โ Restart device โ Try again. Check [Apple System Status](https://www.apple.com/support/systemstatus/) |
| Crashes immediately on launch | Ensure iOS 16.0+ โ Restart device โ Delete and reinstall |
| {% endtab %} | |
{% tab title="Sideloading" %}
| Problem | Solution |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| "Untrusted Developer" | Settings โ General โ VPN & Device Management โ Trust your profile |
| App expires after 7 days | Free accounts expire weekly. Re-sign with AltStore/Sideloadly or upgrade to paid $99/year account |
| "App is already installed" | Delete existing version first, or use a different bundle ID |
| Cannot authenticate (2FA) | Create an App-Specific Password at appleid.apple.com โ Security |
| Max App ID limit reached | Too many bundle IDs this week. Reuse an existing one, or use a different Apple ID |
| Duplicate app installed | Use the **same** bundle ID as original build to update in place |
| {% endtab %} | |
{% tab title="Building from Source" %}
| Problem | Solution |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `xcrun: error: unable to find utility "xcodebuild"` | Xcode โ Preferences โ Locations โ Select Command Line Tools |
| Cycle in dependencies error | Clean Build Folder (Shift+Cmd+K) and delete DerivedData: `rm -rf ~/Library/Developer/Xcode/DerivedData` |
| Stuttering/slow after build | You built debug. Use `Provenance-Release` or `ProvenanceTV-Release` scheme |
| Missing submodules / Mupen error | Don't download .zip from GitHub. Clone with `git clone --recursive` |
| `Linking... Failed` | Clean Build Folder (Shift+Cmd+K) and rebuild |
| Signing certificate issues | Xcode โ Preferences โ Accounts โ Manage Certificates โ Delete old โ Create new |
| {% endtab %} | |
| {% endtabs %} | |
**Full guides:** [Building from Source](/getting-started/installing-provenance/advanced/building-from-source) | [Sideloading](/getting-started/installing-provenance/advanced/sideloading) | [Advanced FAQ](/advanced/faqs-advanced)
***
## Large Library Issues
Library Loading is Slow
1. Delete ROMs you no longer play
2. Optimize artwork โ compress cover images under 500 KB
3. Clear cache: Settings โ Advanced โ Clear Cache
4. Restart device
5. Temporarily disable iCloud sync while loading
Corrupted Database
**Symptoms:** Duplicated games, missing metadata, crashes on library screen.
{% hint style="danger" %}
**Last resort** โ this rebuilds your entire library index. Only do this if other fixes haven't worked.
{% endhint %}
**Fix:**
1. Force quit Provenance
2. Open Files app โ On My Device โ Provenance
3. Delete the `Provenance.realm` file
4. Restart Provenance โ the library will rebuild automatically (may take 10-30 minutes for large collections)
{% hint style="info" %}
This does NOT delete your ROMs or saves โ only the library index. Your games will be re-scanned and re-imported.
{% endhint %}
***
## Advanced Debugging
If you're comfortable with developer tools, you can dig deeper into issues:
Viewing Crash Logs (iPhone/iPad)
1. Go to **Settings โ Privacy & Security โ Analytics & Improvements โ Analytics Data**
2. Search for `Provenance` log files and tap to view
3. Use the share button to send logs to the [Discord](https://discord.gg/provenance) #help channel
Live Logging with NSLogger (Preferred)
Provenance uses [CocoaLumberjack](https://github.com/CocoaLumberjack/CocoaLumberjack) for logging. You can view logs in real time using [NSLogger](https://github.com/fpillet/NSLogger/):
1. Download [NSLogger.app](https://github.com/fpillet/NSLogger/releases) on your Mac
2. Open NSLogger
3. Ensure your device and Mac are on the same network
4. Open Provenance on your device
5. The NSLogger window will populate automatically
**Tips:**
* Filter with the search bar (upper right)
* Filter by severity: Cmd+0 through Cmd+4 (0 = Error, 1 = Warning, 2 = Info, 3 = Debug, 4 = Verbose)
* Toggle the **f** button on the bottom toolbar to see source file and line numbers
Crash Reports via Xcode
1. Open Xcode
2. **Window โ Devices and Simulators**
3. Select your device (connect via USB if not available over WiFi)
4. Click **View Device Logs** (may take a minute to download)
Live Logging via Xcode
1. Build and run Provenance from Xcode
2. If the console isn't visible: **View โ Debug Area โ Show Debug Area**
3. Provenance debug output will appear as you use the app
{% hint style="info" %}
The app must be started from within Xcode for live logging to work.
{% endhint %}
***
## Still Need Help?
{% hint style="success" %}
**We're here to help!**
1. **Search** [**GitHub Issues**](https://github.com/Provenance-Emu/Provenance/issues) โ Your problem may already be reported
2. **Join** [**Discord**](https://discord.gg/provenance) โ Live community support in the #help channel
3. **Report a bug** โ Open a [new GitHub Issue](https://github.com/Provenance-Emu/Provenance/issues/new) with your device model, OS version, Provenance version, steps to reproduce, and crash logs if available
{% endhint %}
# Contributing
How to contribute code, documentation, or bug reports to Provenance
Provenance is an open-source project and welcomes contributions from the community. Here's how you can help:
## Ways to Contribute
| Contribution | Where | Skill Level |
| -------------------------- | ---------------------------------------------------------------------------------- | ------------ |
| **Report bugs** | [GitHub Issues](https://github.com/Provenance-Emu/Provenance/issues) | Any |
| **Improve documentation** | [Wiki repo](https://github.com/Provenance-Emu/wiki) | Any |
| **Submit code fixes** | [Main repo](https://github.com/Provenance-Emu/Provenance) (fork & PR) | Developer |
| **Add features** | [Main repo](https://github.com/Provenance-Emu/Provenance) (fork & PR) | Developer |
| **Test beta builds** | [TestFlight](/faqs#what-is-provenance-plus) or build from source | Intermediate |
| **Share controller skins** | [DeltaStyles](https://deltastyles.com) or [Discord](https://discord.gg/provenance) | Designer |
***
## Code Contributions (Fork & PR Workflow)
Provenance uses a **fork-and-pull-request workflow** โ you work on your own fork and submit PRs back to the main repo. This means you don't need write access to contribute.
### 1. Create a Fork
1. Go to the [Provenance GitHub page](https://github.com/Provenance-Emu/Provenance) and click **Fork**
2. Clone your fork locally:
```bash
# Clone your fork (with submodules)
git clone --recurse-submodules -j4 git@github.com:YOUR-USERNAME/Provenance.git ProvFork
cd ProvFork
```
3. Add the upstream remote so you can pull future updates:
```bash
# Add the original repo as "upstream"
git remote add upstream git@github.com:Provenance-Emu/Provenance.git
# Verify remotes
git remote -v
```
### 2. Create a Feature Branch
Always work on a dedicated branch โ never commit directly to `develop`:
```bash
git checkout -b feature/your-feature-name
```
### 3. Keep Your Fork Up to Date
Before starting work (and periodically while working), sync with upstream:
```bash
# Fetch latest from upstream
git fetch upstream
# Update your local develop branch
git checkout develop
git pull upstream develop
git push origin develop
# Rebase your feature branch on the latest develop
git checkout feature/your-feature-name
git merge upstream/develop
```
You can also use the **Fetch upstream** button on your fork's GitHub page.
### 4. Submit a Pull Request
PRs should contain all changes **squashed into a single commit** to keep the git history clean:
```bash
# Make sure you're on your feature branch
git checkout feature/your-feature-name
# Squash all commits into one
git reset --soft develop
git add -A
git commit -m "Add your feature description here"
# Push (force push needed since history was rewritten)
git push --force origin feature/your-feature-name
```
Then open a Pull Request on GitHub from your branch to `Provenance-Emu/Provenance:develop`.
***
## Wiki / Documentation Contributions
The wiki lives in a [separate repo](https://github.com/Provenance-Emu/wiki). It's all Markdown files rendered by GitBook.
**Quick fixes:** Edit directly on GitHub (click the pencil icon on any file) and submit a PR.
**Larger changes:** Fork the wiki repo, make edits locally, and submit a PR to `master`.
**Style notes:**
* Use relative links between pages (e.g., `[FAQ](../faqs.md)`)
* Preserve existing YAML frontmatter
* Update `SUMMARY.md` if adding or renaming pages
***
## Reporting Bugs
Good bug reports help us fix issues faster:
1. **Search first** โ Check [existing issues](https://github.com/Provenance-Emu/Provenance/issues) to avoid duplicates
2. **Use the latest version** โ Update from the App Store or build from the latest source
3. **Include details:**
* Device model and OS version
* Provenance version (Settings โ About)
* Steps to reproduce the issue
* What you expected vs what happened
* Screenshots or screen recordings if applicable
4. **One bug per issue** โ Don't bundle multiple problems together
{% hint style="warning" %}
**Before reporting:** Make sure you installed from an [official source](/getting-started/installing-provenance). We cannot support 3rd-party builds or signing services.
{% endhint %}
***
## Community
* [**Discord**](https://discord.gg/provenance) โ Chat, help, and discussion
* [**GitHub Discussions**](https://github.com/Provenance-Emu/Provenance/discussions) โ Feature requests and Q\&A
* [**Twitter/X**](https://twitter.com/provenanceapp) โ Updates and announcements
{% hint style="success" %}
Every contribution matters โ whether it's a one-line typo fix, a detailed bug report, or a major feature. Thank you for helping make Provenance better!
{% endhint %}
# UDID Registration
How to find your device's UDID for development or beta testing
A **UDID** (Unique Device Identifier) is a 40-character string that uniquely identifies your Apple device. You may need it for:
* Joining OTA (over-the-air) beta distributions
* Registering your device on an Apple Developer account for sideloading
* Troubleshooting device-specific issues
***
## How to Find Your UDID
{% tabs %}
{% tab title="iPhone / iPad (On-Device)" %}
#### Using a web tool
1. Open Safari on your device and visit [udid.tech](https://udid.tech) or [ipsw.me/device-finder](https://ipsw.me/device-finder)
2. Follow the prompts to install a temporary configuration profile
3. Your UDID will be displayed โ tap to copy it
4. The profile can be removed afterward in Settings โ General โ VPN & Device Management
{% hint style="info" %}
These tools install a temporary profile to read your UDID. The profile can be safely removed after you've copied the identifier.
{% endhint %}
{% endtab %}
{% tab title="macOS (Finder)" %}
#### Using Finder (macOS Catalina and later)
1. Connect your iPhone/iPad to your Mac via USB
2. Open **Finder** and select your device under **Locations** in the sidebar
3. Click the **device name** or **model** at the top of the pane
4. A summary appears showing Capacity, Phone Number, and **Serial Number**
5. **Click on Serial Number** โ it cycles through: Serial Number โ UDID โ ECID โ Model Number
6. When UDID is displayed, **right-click** โ **Copy UDID**
#### Using System Information
1. Connect your device via USB
2. Click โ **About This Mac** โ **More Info** โ **System Report**
3. Select **USB** in the sidebar
4. Find your device under the USB bus
5. The **Serial Number** shown here is your UDID (you may need to add a dash after the 8th character)
{% endtab %}
{% tab title="Windows" %}
#### Using Apple Devices app
1. Install the [Apple Devices app](https://apps.microsoft.com/detail/9NP83LWLPZ9K) from the Microsoft Store
2. Connect your iOS device via USB
3. Select your device by clicking its image
4. A summary shows Capacity, Phone Number, and **Serial Number**
5. **Click on Serial Number** โ it changes to display your UDID
6. Right-click to copy
{% endtab %}
{% tab title="Linux" %}
#### Using lsusb
1. Connect your device via USB
2. Run:
```sh
lsusb -v 2> /dev/null | grep -e "Apple Inc" -A 2
```
3. The serial number shown is your UDID
#### Using libimobiledevice
For more reliable detection, install `libimobiledevice`:
```sh
# Debian/Ubuntu
sudo apt install libimobiledevice-utils
# Fedora
sudo dnf install libimobiledevice-utils
# Then run:
idevice_id -l
```
{% endtab %}
{% endtabs %}
***
## Registering Your UDID
Once you have your UDID, it needs to be registered on an Apple Developer account:
**If you're a developer:**
1. Log in to [developer.apple.com](https://developer.apple.com)
2. Go to **Certificates, Identifiers & Profiles** โ **Devices**
3. Click **+** to register a new device
4. Enter a name and paste your UDID
5. Click **Continue** โ **Register**
**If you're joining a beta:**
* Send your UDID to the developer who invited you (they'll register it on their account)
{% hint style="warning" %}
Free Apple Developer accounts can register up to **10 devices per year** (across all device types). Paid accounts support up to 100 devices per device type.
{% endhint %}
***
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}
# Open Source Licenses
Open-source projects and libraries that power Provenance.
Provenance is free and open-source, and it is built on the shoulders of countless other open-source projects. This page acknowledges the emulator cores, libraries, and tools that make it possible.
For the complete, always up-to-date license list โ including all 114 RetroArch cores โ see the [**Open Source Licenses**](https://provenance-emu.com/licenses/) page on the Provenance website. That page is automatically synced from the source code and includes live search and filtering.
## Native Emulator Cores
The following cores are built directly into Provenance (not via RetroArch). Each entry links to the upstream project and its license.
| Name | Systems | License |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Atari 800](https://atari800.github.io) | Atari 5200, Atari 8-bit | [GPL-2.0-or-later](https://github.com/atari800/atari800/blob/master/COPYING) |
| [Azahar (Experimental)](https://azahar-emu.org) | Nintendo 3DS | [GPL-2.0-or-later](https://github.com/azahar-emu/azahar/blob/master/LICENSE) |
| [BeetlePSX](https://github.com/libretro/beetle-psx-libretro) | PS1 | [GPL-2.0-only](https://github.com/libretro/beetle-psx-libretro/blob/master/COPYING) |
| [Desmume2015](https://github.com/flyinghead/desmume2015) | Nintendo DS | [GPL-2.0-or-later](https://github.com/TASEmulators/desmume/blob/master/desmume/COPYING) |
| [Dolphin](https://github.com/Provenance-Emu/dolphin-ios-jitless) | GameCube, Wii | [GPL-2.0-or-later](https://github.com/dolphin-emu/dolphin/blob/master/COPYING) |
| [DosBox Pure](https://github.com/schellingb/dosbox-pure) | DOS | [GPL-2.0-or-later](https://github.com/schellingb/dosbox-pure/blob/main/LICENSE) |
| [DuckStation](https://github.com/stenzek/duckstation/) | PS1 | [GPL-3.0-only](https://github.com/stenzek/duckstation/blob/master/LICENSE) |
| [EP128Emu](http://ep128emu.sourceforge.net) | Enterprise 128, ZX Spectrum | [GPL-2.0-or-later](http://ep128emu.sourceforge.net/about.html) |
| [EmuThreeDS](https://github.com/emuPlace/emuThreeDS) | Nintendo 3DS | [GPL-2.0-or-later](https://github.com/emuPlace/emuThreeDS/blob/main/LICENSE) |
| [FBNeo](https://github.com/finalburnneo/FBNeo) | Neo Geo, MSX, CPS, ColecoVision | [LicenseRef-FBNeo](https://github.com/finalburnneo/FBNeo/blob/master/src/license.txt) |
| [FCEUX](http://sourceforge.net/projects/fceultra/) | NES, FDS | [GPL-2.0-or-later](https://github.com/TASEmulators/fceux/blob/master/COPYING) |
| [Final Burn Neo](https://neo-source.com) | Neo Geo, MSX, MSX2, Arcade, NES, ColecoVision | [LicenseRef-FBNeo](https://github.com/finalburnneo/FBNeo/blob/master/src/license.txt) |
| [Flycast](https://github.com/flyinghead/flycast) | Dreamcast | [GPL-2.0-only](https://github.com/flyinghead/flycast/blob/master/LICENSE) |
| [FreeIntv](https://github.com/libretro/FreeIntv) | Intellivision | [GPL-3.0-or-later](https://github.com/libretro/FreeIntv/blob/master/LICENSE) |
| [Fuse](http://fuse-emulator.sourceforge.net) | ZX Spectrum | [GPL-2.0-or-later](http://fuse-emulator.sourceforge.net) |
| [Gambatte](https://github.com/sinamas/gambatte) | Game Boy, GBC | [GPL-2.0-or-later](https://github.com/sinamas/gambatte/blob/master/COPYING) |
| [Gearcoleco](https://github.com/drhelius/Gearcoleco) | ColecoVision | [MIT](https://github.com/drhelius/Gearcoleco/blob/master/LICENSE) |
| [Genesis Plus GX](https://github.com/ekeeke/Genesis-Plus-GX) | Genesis, Game Gear, Master System, SG-1000, Sega CD | [LicenseRef-Genesis-Plus-GX](https://github.com/ekeeke/Genesis-Plus-GX/blob/master/LICENSE.txt) |
| [GME](https://github.com/libretro/libretro-gme) | Music files | [LGPL-2.1-or-later](https://github.com/libretro/libretro-gme/blob/master/LICENSE) |
| [Hatari](http://hatari.tuxfamily.org) | Atari ST | [GPL-2.0-or-later](https://git.tuxfamily.org/hatari/hatari.git/tree/gpl.txt) |
| [Mednafen](https://mednafen.github.io) | Saturn, PS1, Lynx, Neo Geo Pocket, PC Engine, PC-FX, Virtual Boy, WonderSwan, NES, SNES, GB, GBC, GBA | [GPL-2.0-or-later](https://mednafen.github.io/documentation/) |
| [melonDS](https://melonds.kuribo64.net) | Nintendo DS | [GPL-3.0-or-later](https://github.com/melonDS-emu/melonDS/blob/master/LICENSE) |
| [Mini vMac](https://www.gryphel.com/c/minivmac/) | Macintosh | [MIT](https://www.gryphel.com/c/minivmac/license.html) |
| [Mu](https://meepingsnesroms.github.io) | Palm OS | [MIT](https://github.com/meepingsnesroms/Mu/blob/master/LICENSE) |
| [mGBA](https://mgba.io/) | GBA | [MPL-2.0](https://github.com/mgba-emu/mgba/blob/master/LICENSE) |
| [Mupen64Plus](https://github.com/mupen64plus) | N64 | [GPL-2.0-or-later](https://github.com/mupen64plus/mupen64plus-core/blob/master/COPYING) |
| [Mupen64Plus-Next](https://github.com/libretro/mupen64plus-libretro-nx) | N64 | [GPL-2.0-or-later](https://github.com/libretro/mupen64plus-libretro-nx/blob/develop/LICENSE) |
| [Opera](https://github.com/libretro/opera-libretro) | 3DO | [LGPL-2.1-or-later](https://github.com/libretro/opera-libretro/blob/master/LICENSES) |
| [PCSX Rearmed](https://github.com/notaz/pcsx_rearmed) | PS1 | [LGPL-2.1-or-later](https://github.com/notaz/pcsx_rearmed/blob/master/COPYING) |
| [PicoDrive](https://github.com/notaz/picodrive) | 32X | [LicenseRef-PicoDrive](https://github.com/notaz/picodrive/blob/master/COPYING) |
| [Play!](https://github.com/jpd002/Play-) | PS2 | [MIT](https://github.com/jpd002/Play-/blob/master/LICENSE.md) |
| [PokeMini](http://sourceforge.net/projects/pokemini/) | Pokemon Mini | [GPL-2.0-or-later](https://sourceforge.net/projects/pokemini/) |
| [Potator](https://github.com/alekmaul/potator) | Supervision | [GPL-2.0-or-later](https://github.com/alekmaul/potator/blob/master/LICENSE) |
| [PPSSPP](https://github.com/hrydgard/ppsspp) | PSP | [GPL-2.0-or-later](https://github.com/hrydgard/ppsspp/blob/master/LICENSE.TXT) |
| [ProSystem](https://gstanton.github.io/ProSystem1_3/) | Atari 7800 | [GPL-2.0-or-later](https://gstanton.github.io/ProSystem1_3/) |
| [Reicast](https://github.com/reicast/reicast-emulator) | Dreamcast | [BSD-2-Clause](https://github.com/reicast/reicast-emulator/blob/master/LICENSE) |
| [SameDuck](https://github.com/libretro/libretro-SameDuck) | Mega Duck | [MIT](https://github.com/libretro/libretro-SameDuck/blob/master/LICENSE) |
| [Snes9x](http://www.snes9x.com) | SNES | [LicenseRef-Snes9x](https://github.com/snes9xgit/snes9x/blob/master/LICENSE) |
| [SNESticle](https://github.com/iaddis/SNESticle) | SNES | [LicenseRef-SNESticle](https://github.com/iaddis/SNESticle) |
| [Stella](https://stella-emu.github.io) | Atari 2600 | [GPL-2.0-or-later](https://github.com/stella-emu/stella/blob/master/License.txt) |
| [TGBDual](https://github.com/libretro/tgbdual-libretro) | Game Boy, GBC | [GPL-2.0-or-later](https://github.com/libretro/tgbdual-libretro/blob/master/COPYING) |
| [TIC-80](https://tic80.com) | TIC-80 | [MIT](https://github.com/nesbox/TIC-80/blob/dev/LICENSE) |
| [VecX](https://github.com/libretro/libretro-vecx) | Vectrex | [GPL-2.0-or-later](https://github.com/libretro/libretro-vecx/blob/master/LICENSE) |
| [VisualBoyAdvance](https://sourceforge.net/projects/vba/) | GBA | [GPL-2.0-or-later](https://github.com/visualboyadvance-m/visualboyadvance-m/blob/master/COPYING) |
| [Yabause](https://yabause.org) | Saturn | [GPL-2.0-or-later](https://github.com/Yabause/yabause/blob/master/yabause/COPYING) |
| [blueMSX](http://fms.komkon.org/blueMSX/) | MSX, MSX2 | [GPL-2.0-or-later](http://fms.komkon.org/blueMSX/) |
| [fMSX](http://fms.komkon.org/fMSX/) | MSX, MSX2 | [LicenseRef-fMSX](http://fms.komkon.org/fMSX/) |
## RetroArch Cores
Provenance also includes 114 [RetroArch](https://www.retroarch.com/) / [libretro](https://www.libretro.com/) cores. RetroArch is a unified front-end for emulator cores built using the libretro API. These cores cover a wide range of additional systems and are licensed individually by their respective upstream projects โ the majority under GPL-2.0-or-later.
For the complete list of all RetroArch cores included in Provenance, with individual license links, see the [**Open Source Licenses**](https://provenance-emu.com/licenses/) page on the website.
## License Types
Provenance and its included cores use a variety of open-source licenses. Here is a plain-language summary:
GPL (GNU General Public License) โ v2.0 and v3.0
The most common license in Provenance. GPL requires that any distributed software โ including apps incorporating GPL code โ make their source code available under the same license. Provenance's source code is publicly available on [GitHub](https://github.com/Provenance-Emu/Provenance).
* **GPL-2.0-only** โ Version 2 only; cannot be relicensed under later versions.
* **GPL-2.0-or-later** โ Version 2 or any later version at your option.
* **GPL-3.0-only / GPL-3.0-or-later** โ Version 3, which adds patent protection clauses.
LGPL (GNU Lesser General Public License)
A more permissive variant of the GPL. LGPL allows the library to be linked into non-GPL software without requiring the whole application to be open-sourced, provided the library itself remains under LGPL. Used by a small number of cores (Opera, PCSX Rearmed, GME).
MIT License
A permissive, short license that allows nearly unrestricted use, copying, modification, and distribution โ including in closed-source software โ as long as the original copyright notice is preserved. Very business-friendly. Used by Gearcoleco, Mini vMac, Mu, Play!, SameDuck, and TIC-80.
BSD Licenses (2-Clause and 3-Clause)
Similar in spirit to MIT: permissive, allowing redistribution with minimal conditions. The 3-Clause variant adds a non-endorsement clause (you cannot use the project's name to promote your product without permission). Used by Reicast and several RetroArch cores.
MPL-2.0 (Mozilla Public License)
A "weak copyleft" license โ modified files must remain under MPL, but they can be combined with code under other licenses. Used by mGBA.
LicenseRef-* (Custom Licenses)
Some projects use custom licenses that are not standard SPDX identifiers. These are denoted with the `LicenseRef-` prefix:
* **LicenseRef-FBNeo** โ Final Burn Neo's custom non-commercial license.
* **LicenseRef-Genesis-Plus-GX** โ Genesis Plus GX's custom license (non-commercial use).
* **LicenseRef-PicoDrive** โ PicoDrive's custom license terms.
* **LicenseRef-Snes9x** โ Snes9x's custom non-commercial license.
* **LicenseRef-SNESticle** โ SNESticle's custom license.
* **LicenseRef-fMSX** โ fMSX's custom non-commercial license.
## Provenance Source Code
Provenance itself is licensed under the **BSD 3-Clause License**. The full source code is available at:
[**github.com/Provenance-Emu/Provenance**](https://github.com/Provenance-Emu/Provenance)
## See Also
* [Supported Systems](/platforms-and-performance/supported-systems)
* [System-Specific Guides](/platforms-and-performance/system-guides)
* [Contributing](/help-and-community/contribute)
{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}