Emulsion

Better gaming through chemistry

Display your games collection(s) into responsive galleries, manage game metadata, cover art and emulator configuration. Launch your games in style. Ideal for powering a cabinet, pinball included.

Emulsion lets you browse and launch a mixed game collection from one interface. It is designed to be practical: fullscreen-friendly, comfortable with a controller, and flexible about how your collection is organized.

Your games can stay where they already are: local disk, external drive, mixed folders, or a NAS share. Emulsion does not require a proprietary library layout.

It also works well for arcade and pinball cabinets, including VPX setups.

Features

Multi-platform launcher — one frontend for many systems
Your games can stay where they are — local folders, external drives, mixed storage, even a NAS
Gamepad-first UI — also works with keyboard and mouse
Recents and Favorites — quick access to what matters
Metadata and cover management — fetch, edit, save, batch-download
Per-platform emulator config — executable, args, extensions, enable / disable
Responsive layouts — grid or list, configurable columns, fullscreen friendly
Kiosk mode — ideal for kids, cabinets, or public-facing setups
GameModeRun support on Linux — enabled by default when available
Pinball ready — pinball control scheme, OPDB integration, cabinet-friendly launching

Why it is practical

Emulsion tries to stay out of your way:

point each platform at the folder you already use
keep your existing emulator binaries and command lines
add metadata and cover art without reorganizing your collection
mix tiny curated setups with huge multi-system libraries
use it on a desktop today, then drop the same config into a cabinet later

Why it works well in a cabinet

For cabinet builders, Emulsion gives you the stuff that matters:

boot straight into a platform with --auto-select
hide the UI chrome entirely with --no-ui
lock things down with --kiosk
use recents and favorites like a real front-end, not an afterthought
run VPX from the same launcher as the rest of your collection
fetch OPDB metadata and images for pinball setups
use the built-in pinball control scheme with --control-scheme=pinball

It works well as a couch-friendly launcher, a dedicated cabinet frontend, or a setup where the collection already lives on a server or NAS.

Emulsion keeps your library structure simple:

images are stored in images/ inside your games folder
metadata is stored in metadata/ inside your games folder
recents and favorites are stored in your user config directory
favorites / recents enrich their records from metadata/<gameName>.json when available, using publisher and releaseDate
for VPX-style names like Game Name (Publisher YYYY), the gallery badge prefers the filename values over metadata

Installation

Packages

All releases

Wayland note: if your Linux setup needs it, try:

emulsion --enable-features=UseOzonePlatform --ozone-platform=x11

From source

npm install
npm start

Quick start

Launch Emulsion
Open a platform from the home carousel
In the platform menu, set:
- Games Directory
- Emulator
- optional Emulator Arguments
Save
Browse, launch, add favorites, fetch covers, enjoy

When your setup is done, you can switch Disabled platforms to hide in Settings for a cleaner home screen.

Tip: your main config lives in ~/.config/emulsion/preferences.json on Linux.

Configuration

Per-platform settings

Setting	What it does
Games Directory	Folder scanned for games / ROMs
Emulator	Executable used to launch the selected platform
Emulator Arguments	Optional CLI flags
Extensions	File extensions to scan
View Mode	Grid or list
Enabled	Show or hide the platform from normal browsing

Global settings

Current global settings include:

theme
footer size
number of columns
disabled platform policy
recents / favorites visibility
recents / favorites view mode
favorites sorting
startup help dialog policy
launch dialog policy
Optimize (GameModeRun)
API keys for image / metadata sources

On Linux, Optimize (GameModeRun) is enabled by default when gamemoderun is available. You can disable it in Settings.

Emulator management

Emulsion helps you manage emulator setup per platform.

On Linux, it can help install / select supported emulators automatically
On Windows / macOS / BSD, you can point Emulsion at your already-installed emulator manually

Either way, the result is the same: once configured, it becomes a set-it-and-forget-it frontend.

MAME note

MAME is handled slightly differently from most platforms.

Set the games directory to your MAME ROM folder
Set the emulator to your MAME binary or command
Use Emulator Arguments only for optional extra flags

Emulsion automatically launches MAME with the ROM folder as -rompath and uses the ROM filename without extension as the game name.

Example:

ROM file: ~/roms/mame/roms/gridlee.zip
Launch shape: mame [extra args] -rompath ~/roms/mame/roms gridlee

Metadata & cover art

Emulsion supports both manual curation and batch automation.

Built-in behavior

By default, Emulsion can fetch useful game information and images even without extra setup.

Optional APIs

Add keys in Settings to improve coverage:

SteamGridDB — strong image coverage
GiantBomb — optional extra source
OPDB — especially relevant for VPX / pinball metadata and images

Sources currently used

Text / metadata

Wikipedia
OPDB for VPX

Images

Wikimedia / Wikipedia
SteamGridDB
GiantBomb
OPDB for VPX

All fetched assets are stored alongside your games:

images/
metadata/

Controls

Home carousel

Action	Keyboard	Controller
Navigate platforms	`←` `→`	D-Pad left / right
Select platform	`Enter`	A / Cross
Jump to Settings	`Home` / `End`	—
Exit	`Ctrl+Q`	B / Circle

Gallery

Action	Keyboard	Controller
Move selection	Arrows	D-Pad
Switch platforms	`Shift+←` `Shift+→`	`L1` `R1`
Jump 10 rows	`PgUp` `PgDn`	—
Launch game	`Enter`	A / Cross
Open cover / image menu	`I`	X / Square
Back to home	`Esc`	B / Circle

Global shortcuts

Action	Keyboard	Controller
Open Emulsion menu	`/`	Start
Exit emulator / game back to Emulsion	`Ctrl+Shift+K`	Select + D-Pad Down
Reload Emulsion	`F5`	—
Restart Emulsion	`Shift+F5`	Select + D-Pad Up
Toggle fullscreen	`F11`	—

Mouse

Left click: open / launch
Right click: game image / cover menu
Wheel: navigate

Command line

emulsion [options]

Options:
  --help
  --full-screen
  --kiosk
  --auto-select=[gallery_name]
  --no-ui
  --verbose

Notes

--auto-select supports platform names, plus recents and favorites
--no-ui is meant for use with --kiosk and --auto-select
Emulsion also supports --control-scheme=pinball for cabinet-oriented controls

Example

emulsion --kiosk --full-screen --auto-select=snes

Cabinet / pinball example

emulsion --kiosk --full-screen --auto-select=vpx --no-ui --control-scheme=pinball

Platforms

Current platform keys include:

atari
amstrad
spectrum
c64
nes
sms
pcengine
amiga
megadrive
gameboy
lynx
gamegear
snes
jaguar
saturn
ps1
n64
dreamcast
ps2
gamecube
xbox
psp
ps3
3ds
xbox360
ps4
vpx
mame
plus recents and favorites

Not every platform has to be enabled. Emulsion is happy with a tiny curated setup or a giant all-in-one cabinet build.

Data locations

Typical Linux paths:

Main config: ~/.config/emulsion/preferences.json
Recents: ~/.config/emulsion/recently_played.json
Favorites: ~/.config/emulsion/favorites.json

Per-platform content lives next to your games:

your-games-folder/images/
your-games-folder/metadata/

Contributing

Found a bug?

Report it on GitLab

Have an idea?

Open an issue

Want to contribute code?

Contributions are welcome.

Support the project

License

Emulsion is open source under the GPL v3.

Links

This repository is a mirror of the official GitLab repo.

Back to top

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
build		build
img		img
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
main.js		main.js
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation