Better gaming throught chemistry
Display your games collection into responsive galleries, manage game metadata, cover art and emulator configuration. Launch your games in style.
Website • Download • Documentation • GitHub mirror (releases) • Blog • Cracktro
- Flexible Storage - Your games / ROMs can be anywhere, across multiple drives / NAS, etc.
- Universal Input - Keyboard, mouse, or any game controller
- Responsive UX - Adapts perfectly to any screen size / orientation
- Smart emulator management - Emulsion uses your installed emulator, or installs it ; Standard and up to date.
- Flexible Metadata Management - Manual curation, and / or batch automation. Downloads from multiple sources, Wikipedia API default ; All manageable from the platform page.
Emulsion is reproducible - one single config file - and arcade ready ; Perfect for driving an arcade cabinet.
- Linux Debian / Ubuntu
- Linux RPM
- Linux AppImage
- Linux Arch
- FreeBSD (testers needed)
- Windows
- Mac OS (testers needed)
⚠️ Note: If your Linux distro uses Wayland you 1-are a very brave person and 2-may have to run Emulsion like this:emulsion --enable-features=UseOzonePlatform --ozone-platform=x11until it (Wayland) is finally ready for production.
npm install && npm start- Get some games - Let's say NES ROMs
- Open Emulsion → NES
- Games Directory: Click Browse, navigate to your NES games folder
- Emulator:
- Click Install, choose... Let's try
nestopia. - Click Select
- Click Enable, click Save
- Click Install, choose... Let's try
- Done - That's it, your NES Platform is set up forever.
When you're done, optionally set "disabled platforms: hide" in the global setting menu, so you only see the enabled platforms. Also enable "Recents" and "Favorites" ; I guess we're all set now. You are welcome 🙂
💡 Pro Tip: Your config lives in
~/.config/emulsion/preferences.json- back it up!
| Setting | Description |
|---|---|
| Games Directory | Where your ROMs are for this platform |
| Emulator | The emulator executable (use the install button to install / select emulator) |
| Emulator Arguments | Optional flags (most emulators don't need any) |
| Extensions | File types to scan for (already set if you use the Install / Select dialog) |
Emulsion finds your emulators, helps you install the ones you don’t have, and sets them up with sensible defaults (file extensions and CLI arguments) — all configurable. Emulsion is flexible: You can put all your Vic20 games in the C64 page if you want.
Emulsion keeps up-to-date on platforms emulators and their extensions and arguments.
⚠️ Note: Automatic emulator installation / selection is currently only available on Linux. On BSD, macOS and Windows, emulators must be installed manually. No biggie, the result is the same anyway: setup and forget.
For Windows, we're thinking of implementing something like Scoop or WinGet, when we find the time and motivation. Again, it's not a big deal: Install youe emulator, select it with the "Browse" button, save (optionally tweak the arguments) and you are done.
Press □ or I to select the cover art for the selected platform / game.
By default, Emulsion uses Wikipedia to fetch cover images and game metadata — so even without any setup, you get images, release info, and other useful text details automatically.
Want more options and higher-quality covers? Add free API keys to expand Emulsion’s reach:
- Login at steamgriddb.com
- Get your API key from Preferences
- Paste it into Emulsion Settings
- Register at giantbomb.com/api
- Paste your free key into Emulsion Settings
- Wikipedia – API (default) text metadata (title, release date, description, etc.)
- WikiMedia – API (default) good coverage
- SteamGridDB – API, best coverage & high-quality images
- GiantBomb – API, actually quite poor, thinking of removing it.
All images and metadata are saved alongside your platform games / ROMs, keeping your collection organized.
The console carousel
| Action | Keyboard | Controller |
|---|---|---|
| Navigate consoles | ← → | ◄ ► D-Pad |
| Select console | Enter | ⤫ A/Cross |
| Go to 1st (settings) platform | Home / End | |
| Exit | Ctrl+Q | ○ B/Circle |
The games gallery
| Action | Keyboard | Controller |
|---|---|---|
| Browse games | ↑ ↓ ← → | D-Pad |
| Switch consoles | Shift+← Shift+→ | L1 R1 |
| Jump 10 rows | PgUp PgDn | - |
| LAUNCH GAME | Enter | ⤫ A/Cross |
| Cover art menu | I | □ X/Square |
| Back to home | Esc | ○ B/Circle |
They work everywhere
| Action | Keyboard | Controller |
|---|---|---|
| Display Emulation menu | / | Start |
| Exit emulator / Game (return to Emulsion) | Ctrl+Shift+K | Select + ▼ D-Pad Down |
| Reload Emulsion | F5 | - |
| Restart Emulsion | Shift+F5 | Select + ▲ D-Pad Up |
- Left Click: Launch game / Select cover art
- Right Click: Open game cover menu
- Scroll Wheel: Navigate
emulsion [options]
Options:
--kiosk Read-only mode (perfect for kids/arcade)
--full-screen Start fullscreen
--auto-select=PLATFORM Jump directly to a platform
--help Show this help
Available consoles:
atari spectrum c64 nes sms pcengine amiga megadrive
gameboy lynx gamegear snes jaguar saturn psx n64
dreamcast ps2 gamecube xbox psp ps3 3ds xbox360 ps4
recents settingsExample:
emulsion --kiosk --full-screen --auto-select=snesUse Emulsion? Consider supporting development:
Report it on GitLab - We track everything there!
Open an issue and let's discuss it!
Check out our issues - contributions welcome!
Emulsion is open source under the GPL V3 and brought to you for free by yPhil. You are welcome.
