The Complete NostalgiApp Guide

Getting Started

NostalgiApp is a native macOS launcher for retro games. It runs on macOS 13 Ventura or later and is a Universal Binary (Apple Silicon + Intel).

Installation

1. Download NostalgiApp.dmg from the website.
2. Open the DMG and drag NostalgiApp.app into your /Applications folder.
3. Eject the DMG and launch NostalgiApp from Applications or Spotlight.

The app is signed and notarized by Apple, so Gatekeeper will allow it to open without any workarounds.

First Launch & the Setup Wizard

The first time you open NostalgiApp, a setup wizard walks you through five steps:

1. Welcome — introduction and what to expect.
2. Dependencies — NostalgiApp bundles everything it needs (including the aria2 download manager used for eXoDOS torrents). This step shows a few optional niceties like wget and a modern Bash — you can skip it entirely. No Homebrew installation required.
3. Emulators — NostalgiApp already ships with DOSBox Staging, DOSBox-X, DREAMM, ScummVM, 86Box, and MAME bundled inside the app, so nothing to install here unless you want a specific external emulator like RetroArch.
4. MT-32 Audio — optional ROMs for authentic Roland MT-32 synthesis in supported DOS games. Skip if you don't care about MT-32.
5. Complete — you're in.

Trial & License

Every new install begins a 14-day free trial automatically. No sign-up, no email. After the trial you'll need a license:

• Personal — €19.99, one-time, 1 Mac.
• Family — €69.99, one-time, 5 Macs.

Purchases are handled by LemonSqueezy. You'll receive a license key by email; enter it in Settings → License and click Activate. Activations are tied to a hardware machine ID; if you migrate to a new Mac, deactivate on the old one first (or contact support).

Importing eXoDOS

eXoDOS is the largest and best-curated DOS game collection in the world — 7,000+ games pre-configured with the correct emulator settings. NostalgiApp can download and set it up for you, or import an existing copy.

Option A: Download eXoDOS inside the app

NostalgiApp ships with the aria2c BitTorrent client bundled, so it can download the eXoDOS archive directly.

1. Open Library → Add Collection… (or use the first-run prompt).
2. Choose eXoDOS and pick Lite or Full.
   • Lite — a few GB. Only metadata and scripts; games download on demand when you click "Play" for the first time.
   • Full — 500+ GB. All games pre-extracted, no per-game download.
3. Pick where to store the collection (an external drive is recommended for Full).
4. Wait for the torrent to finish, then let the setup run. It extracts metadata archives, parses LaunchBox XML, and populates your library.

Option B: Import an existing copy

If you already have eXoDOS on disk (e.g. from the eXo team's downloads), point NostalgiApp at the collection root — the folder that contains eXoDOS/, Images/, Data/, and !dos/ inside it.

1. Open Library → Add Collection…
2. Choose Import existing folder.
3. Select the collection root in Finder.
4. NostalgiApp detects the collection type from the XML and runs any missing metadata extractions automatically.

Download on demand (Lite)

Lite collections store only a small index and download individual game archives as you launch them. Downloads are handled by bundled aria2c and pulled from the eXo project's mirrors. You'll see a progress dialog on first launch of each game; subsequent launches use the cached extraction.

Other eXo Collections

Beyond eXoDOS, NostalgiApp supports every major eXo pack:

Where to get the archives

The eXo project distributes every collection from www.retro-exo.com — each collection has its own page with the latest torrent links and mirrors. NostalgiApp cannot distribute these archives itself.

Adding a manual collection

1. Download and extract the collection archive to any location (external drive recommended).
2. In NostalgiApp, choose Library → Add Collection… → Import existing folder.
3. Select the collection root (the folder containing Data/Platforms/ and the eXoXXX/ games folder).
4. NostalgiApp detects the collection type and extracts any metadata archives.

Collection-specific notes

eXoWin9x

Windows 9x games use a per-year folder structure (e.g. eXoWin9x/1996/GameName.zip). NostalgiApp detects and extracts year archives automatically. Fullscreen and resolution settings are injected at launch; multi-disc mounts are preserved from the original scripts. Enabled in v1.0.8 Build 81 with permission from the eXo team.

eXoDREAMM

LucasArts classics (Monkey Island, Day of the Tentacle, etc.) run natively through DREAMM, which is bundled inside the app. Permission to bundle DREAMM granted by Aaron Giles.

eXoAppleIIGS

Uses MAME under the hood. NostalgiApp auto-extracts ROMs from the nested archive structure (utilAppleIIGS.zip → EXTIIGS.zip → apple2gs.zip) and patches a missing 344s0047.bin for MAME 0.286 compatibility. Press Esc to quit (the -ui_active flag is set so the emulated keyboard doesn't swallow it).

ROM Libraries

Besides eXo collections, NostalgiApp imports any folder of ROMs for 60+ platforms — NES, SNES, N64, Game Boy, GBA, DS, 3DS, Genesis, Saturn, Dreamcast, PS1, PS2, PSP, Neo Geo, Atari, Commodore, ZX Spectrum, and more.

Importing ROMs

1. Choose File → Import ROMs… (or the Import button in the sidebar).
2. Select the folder containing your ROM files. Subfolders are scanned recursively.
3. NostalgiApp detects the platform from the file extension and filename. An MD5 hash is calculated for RetroAchievements matching.
4. Review the detected platform per ROM; override any mistakes with the dropdown.
5. (Optional) Fetch metadata from ScreenScraper — box art, descriptions, ratings, release dates.
6. Click Import. ROMs are copied into the collection directory structure.

BIOS Manager

Some consoles need BIOS files to run: PS1, Saturn, Dreamcast, Neo Geo, etc. Open Settings → Emulators → BIOS Manager to see a per-platform checklist of required BIOS files, their expected filenames, and where to place them. The manager auto-scans RetroArch's system/ directory.

ScreenScraper Metadata

NostalgiApp integrates with ScreenScraper.fr, a massive community database of game artwork and metadata.

1. Create a free account at screenscraper.fr (optional but gives higher rate limits).
2. Enter your credentials in Settings → Services → ScreenScraper.
3. During ROM import, tick Fetch metadata. Or bulk-scrape an entire library via the Scrape button.

Scraping is rate-limited to be respectful (5 req/sec max). Expect a large library to take an hour or two. Failed lookups are cached to avoid retrying.

Emulators

NostalgiApp ships several emulators bundled inside the app, so everything works out of the box for eXo collections:

External emulators

For console and handheld platforms, NostalgiApp auto-detects these when installed:

Install any of these via Homebrew or download from their websites. Paths are detected from standard locations; override manually in Settings → Emulators if needed.

RetroArch cores — updates and overrides

Open Settings → Emulators → Cores for two useful features:

• Core updates — a list of your installed cores with a Check button and an Update All button when updates are available. Two toggles control automatic behavior: Check for core updates automatically (on by default) and Install updates automatically (off by default — updates are discovered but not installed without your click).
• Platform Core Override — each platform has a default core (e.g. SNES → snes9x_libretro), but you can override it per-platform from a disclosure list of all your installed cores. Useful if you prefer, say, bsnes_libretro for SNES or mesen_libretro for NES.

DOSBox variant routing

Some eXoDOS games specify a preferred DOSBox flavour in dosbox.txt:

• vanilla / staging → DOSBox Staging (bundled, fast)
• x → DOSBox-X (bundled, more compatibility)
• ece / custom → you'll be prompted to pick Staging or Wine+ECE

CRT effects

DOSBox Staging's default CRT shader can look fuzzy on modern displays. NostalgiApp disables it by default via glshader=none. Toggle in Settings → Emulators.

Playing Games

Version picker

Many classic games shipped in multiple flavours: CD vs Floppy, VGA vs EGA, MT-32 vs SoundBlaster, English vs German. When a game has variants, NostalgiApp shows a picker before launch. Variants are auto-detected from the title (e.g. "King's Quest VI (CD Version w/ MT-32)") and grouped by category — Media, Audio, Graphics, Language, Version.

Self-healing game fixes

Sometimes the auto-detected executable is wrong (common with heavily-modded games). NostalgiApp handles this with a crowdsourced fix system:

1. A game launches but does the wrong thing (wrong executable, no sound, etc.).
2. Report "It didn't work" in the game detail view.
3. NostalgiApp parses run.bat or dosbox.conf's autoexec to propose the correct launch command.
4. It relaunches with the proposed fix; if you confirm it works, the fix is uploaded to the community server.
5. All other users pull the fix on next app launch. Everyone benefits.

Fixes are stored per-variant so the "CD Version" fix doesn't interfere with the "Floppy Version".

Save states & cloud sync

Save states work per-emulator:

• RetroArch — F2/F4 for save/load state by default.
• DOSBox — in-game save files (extension varies per game).
• ScummVM — F5 opens the in-game save menu.

Enable Cloud Save Sync in Settings → Services → Cloud Sync to back up saves to iCloud or a local folder. NostalgiApp watches a curated extension whitelist (.sav, .state, .gam, .sg0–.sg9, .mcd, …) so runtime junk doesn't pollute your backup. Syncs are manual-triggered — click Sync Now — to avoid surprises.

RetroAchievements

Earn achievements in retro games just like modern consoles, via the RetroAchievements.org community.

Connecting your account

1. Create a free account at retroachievements.org.
2. In your RA profile, go to Account → Preferences and copy your Web API Key.
3. In NostalgiApp, open Settings → Services → Achievements.
4. Enter your RA username and API key and click Connect.

Your profile card (points, rank, recent achievements) appears in Settings, and each game's detail view shows its achievement list once matched.

Hash matching

NostalgiApp calculates a platform-specific hash for each ROM to match it against RA's database. Supported directly: NES, SNES, Game Boy / GB Color, GBA, Genesis, Master System, Atari 2600 / 7800, Neo Geo Pocket, PCE, and more. Platforms with complex hashes (N64, DS, PS1, Saturn, Dreamcast, arcade) fall back to title matching, which is slightly less accurate.

Tracking progress

While a game is running, earned achievements are pulled from RA and displayed in real time. Progress is stored against your RA account — you'll see the same progress in the RetroAchievements website and in NostalgiApp.

Music Player

The eXo project publishes an eXo Media Pack with thousands of original game soundtracks. NostalgiApp plays them automatically as you browse.

Getting the Media Pack ready

NostalgiApp handles Media Pack setup the same way the eXo Windows Setup.bat does: during setup it scans your collection's Content/ folder for *Soundtracks.zip, *Videos.zip, and *Catalogs.zip and extracts each one into the right place. Three common situations, three different steps:

Scenario 1 — You already have an inflated collection

If you're migrating a Windows library (or have an external drive where the Media Pack was already extracted), your collection's Music/ folder is already populated with game soundtracks. Nothing to do. Point NostalgiApp at the collection, enable background music in settings, and it plays.

Scenario 2 — Fresh install, Media Pack alongside the collection

1. Download both the collection and the Media Pack from retro-exo.com.
2. Drop the Media Pack archives (DOSSoundtracks.zip, optionally DOSVideos.zip / DOSCatalogs.zip) into the collection's Content/ folder alongside the metadata zips.
3. Add the collection in NostalgiApp. First-time setup detects every archive in Content/ and extracts each one to the correct location.
4. Enable Settings → Appearance → Music → Enable background music.

Scenario 3 — You already set up the collection, Media Pack came later

This case is easy to miss: NostalgiApp marks a collection "set up" once the core metadata is extracted and won't automatically re-scan for new archives. You need to kick it off manually.

1. Download the Media Pack from retro-exo.com.
2. Drop the archives into your collection's Content/ folder.
3. In NostalgiApp, choose File → Run Setup… and confirm. Setup re-scans Content/ and extracts the newly-added Media Pack archives. Existing game files are untouched.
4. The Music folder is now populated. Music auto-plays on next game selection.

Supported audio formats: MP3, M4A, OGG, FLAC, WAV, AAC.

How autoplay works

• When you click a game — if that game has a matching soundtrack folder in the Media Pack, NostalgiApp starts playing it automatically. Switching games swaps the music.
• When no game is selected (e.g. idle on the library) — the player builds a random 20-track shuffle playlist from your whole Media Pack and plays it as ambient background music.

Matching is done by game title with a few sensible fallbacks (with/without year, "The" at the start, etc.), so most Media Pack layouts just work.

Using the player

A "Now Playing" card shows the current track with play/pause, next/previous, volume slider, and mute controls. Soundtrack ZIPs dropped into a game's Extras folder are auto-detected and extracted on demand — a separate feature from the Media Pack itself.

Screensaver

Leave NostalgiApp idle and it morphs into a showcase of your library — perfect for a dedicated retro-gaming setup or a Mac mini under the TV.

Two modes

Configuration

Open Settings → Appearance → Screensaver:

• Enable screensaver — master toggle.
• Mode — Bouncing Images or Game Showcase.
• Idle timeout — 1 to 60 minutes before it triggers.
• Rotation speed — 1 to 10 seconds per image.
• Show game titles — overlay the game name on each slide.
• Preview — trigger the screensaver right now.

Only games with box art are shown. Move the mouse or press any key to dismiss.

Search & Discovery

In-app search

The search field above the game list filters by title, platform, developer, and genre (150 ms debounce keeps it responsive on huge libraries). Filters are composable with the platform sidebar, playlists, and smart collections.

Playlists

Two kinds:

• Static — hand-curated; add/remove games manually.
• Dynamic — rule-based; any game matching your criteria is included automatically. Rules support equals/contains/greater-than/less-than on title, developer, publisher, release year, rating, genre, play count, etc.

Playlists can nest and can be exported to CSV or LaunchBox XML.

Smart Collections

Built-in dynamic playlists: Unplayed, Most Played, Highly Rated, Recently Added, MT-32 Games, ScummVM Games, by-decade groupings, by progress state (Playing / Beaten / Completed), and more.

Variant grouping

Games that exist in multiple versions (e.g. the same adventure as DOS and ScummVM, or CD + Floppy editions) are grouped under a single entry in the library with a version picker on launch. Toggle grouping in Settings → General.

macOS Spotlight

NostalgiApp indexes every game in your library into Spotlight. Press ⌘+Space, type a game name, and click the result to launch it straight from the keyboard — no need to open NostalgiApp's window first.

Menu bar quick launch

Enable Settings → General → Show menu bar icon to get a small controller icon in the menu bar with your recently-played and favorite games. One click to launch without switching windows.

Shortcuts & Siri

NostalgiApp registers three Apple Shortcuts actions via AppIntents:

• Launch Game — pick by name.
• Launch Random Game — optional platform filter.
• Get Library Stats — returns totals (games, installed, favorites, total play time).

Build automations in the Shortcuts app or speak them to Siri: "Hey Siri, launch a random game."

Power Features

Batch operations

Open Game → Batch Operations… (⌘+⇧+B) to act on many games at once. A sheet opens with a searchable list and selection helpers — Select All Visible, Select Installed, and so on — then you pick an operation and run it.

• Install Games — bulk-extract archives for selected on-demand games.
• Uninstall Games — remove extracted game folders (keeps archives).
• Add to Favorites / Remove from Favorites.
• Add to Playlist.
• Export Metadata — dump selected games to a CSV.
• Verify Game Files — integrity check.

Progress is shown per-game with a cancel button; operations can be interrupted safely.

Statistics

Open View → Statistics for charts and tables:

• Total games, installed, favorites.
• Total play time and per-game breakdown.
• Top 10 by play time.
• Per-game progress state (Not Started, Playing, Beaten, Completed, Mastered) — set manually from the detail view.

Play time is only tracked for sessions launched through NostalgiApp.

Parental controls

NostalgiApp can hide adult-rated games behind a password. Set it up in Settings → General → Parental Lock. The password is stored as a salted SHA-256 hash — never plaintext.

Auto-update (Sparkle)

NostalgiApp ships with Sparkle and checks for updates automatically. Toggle or change the frequency in Settings → Updates. Updates are signed with our EdDSA key and verified before install.

The Quiz

Take a break with the retro gaming quiz — a fun trivia game we host at quiz.multimodalsolutions.gr. Open it straight from Game → Play the Quiz.

Settings Reference

A whirlwind tour of every tab in Settings.

General

• Show menu bar icon — enables the menu bar quick launcher.
• Sidebar platform counts — show the number of games next to each platform.
• Hide adult games — content filter, protected by the parental password.
• Collection path — where your games live.
• Library refresh interval — how often to rescan for changes on disk.
• Variant grouping — group multi-version games into one library entry.

Appearance

Three sub-tabs: Theme, Music, and Screensaver.

The Theme tab goes well beyond light/dark. Pick an overall color scheme — System, Retro Purple, Ocean Blue, Forest Green, or Midnight Glass — each with its own accent gradient, background, and text colors. Also here: sidebar width, thumbnail size, and the Group duplicate games toggle (consolidates identical titles across platforms — e.g. Gabriel Knight on DOS and ScummVM — into a single library entry with a platform selector).

Emulators

Sub-tabs: Emulators (status and paths), Dependencies (bundled tools and optional niceties like MT-32 ROMs), Cores (RetroArch core versions and auto-update), and BIOS Manager.

Services

Sub-tabs: Cloud Sync, ScreenScraper, Achievements (RetroAchievements), and Community (fix submission and feedback).

License

Trial status, license activation, subscription status, grace-period indicator, restore/validate button.

Updates

Current version, last-check date, auto-update toggle, frequency (hourly/daily/weekly/monthly), manual "Check Now" button.

About

Version, build, credits to the eXo project and the DREAMM / DOSBox / ScummVM / MAME teams, acknowledgements and license text for all bundled open-source emulators.

Troubleshooting

"Game doesn't launch"

1. Confirm the game is installed (not a Lite download stub) — install it first if needed.
2. Check if a community fix already exists — NostalgiApp pulls fixes automatically at launch.
3. Use the "It didn't work" button to trigger self-healing; the app will re-parse the game's config and try again.
4. If self-healing still fails, click Submit Logs in the error dialog. Logs are anonymized (user paths and hostnames redacted) and uploaded so we can debug.

"Game starts but behaves wrong under DOSBox Staging"

A handful of DOS games were originally built against specific quirks of DOSBox ECE and don't behave correctly on DOSBox Staging — bad timing, broken input, or a black screen. Classic examples: Wolfenstein 3D, Eye of the Beholder, Dune II, some of the SSI Gold Box RPGs.

NostalgiApp already flags many of these in GameLaunchOverrides and will offer you a choice dialog: DOSBox Staging (recommended, native) or Wine + DOSBox ECE (authentic timing). If the Staging launch looks wrong:

1. Close the game.
2. Relaunch — when prompted, pick Wine + DOSBox ECE.
3. For games NostalgiApp doesn't already flag, open the game detail view and switch the emulator override manually.

"Collection path not found"

Usually happens when a collection lives on an external drive that isn't mounted. Reconnect the drive or update the path in Settings → General → Collection path.

"License not activated on this Mac"

If you've replaced hardware, deactivate the old Mac first (via the LemonSqueezy customer portal in your purchase email), then re-activate on the new Mac. If you're locked out, email [email protected] — we'll reset it.

DOSBox game runs but no sound

Most eXoDOS games default to SoundBlaster 16. If a game expects MT-32 and you haven't installed the ROMs, sound will be silent. Run Settings → Emulators → Dependencies → MT-32 Audio to set them up.

ScummVM game shows wrong graphics

Open the game detail view and check the detected ScummVM game ID. Override it from the detail view if needed.

RetroAchievements not tracking

• Confirm username + API key are correct in Settings.
• Check that the game's MD5 hash matches RA's database (some platforms fall back to title match which is less reliable).
• Required internet connection during gameplay.

Where are my logs?

~/Library/Logs/NostalgiApp/nostalgi.log

Still stuck?

Email [email protected] with a description and, ideally, a recent log. We read every message.

Thank You

NostalgiApp wouldn't exist without the work of an enormous community of preservationists, developers, and testers. A few names deserve explicit mention.

Aaron Giles — DREAMM

Aaron built DREAMM, the brilliant native macOS emulator that makes the classic LucasArts adventures playable again on modern hardware, and generously granted us permission to bundle it inside NostalgiApp. Thank you, Aaron.

The eXo team

Every DOS, Windows, ScummVM, DREAMM, and Apple IIGS collection NostalgiApp launches is the product of years of careful curation by the eXo project. Thank you to:

• Retro eXo
• Dutchmagic
• gschmidl
• parricc
• TaraLonger — special thanks for the Win9x work
• …and the rest of the team at retro-exo.com.

Beta testers

A heartfelt thanks to the testers who shaped the app into what it is today by reporting bugs, trying weird edge cases, and putting up with broken builds:

• soegaard
• TruthSeeker
• ChainsawJaguar
• miguelito1979
• Rezza
• Kitaria

Open source

And of course, huge thanks to the teams behind the bundled emulators: DOSBox Staging, DOSBox-X, ScummVM, MAME, 86Box, and Sparkle — plus every RetroArch core author whose work NostalgiApp wraps on the ROM side.