Contribute

Sources are required

Everything on Emulator World is checked against a source, so every value you add or change needs one. List them in your pull request description, one link per fact or group of facts:

• Best: the project itself. Its website, README, documentation, changelog, release notes, app store listing or source code. For hardware, the maker's product page.
• Acceptable when the project says nothing: a well-known reference such as a system's Wikipedia article or a long-running community wiki. Say why you used it.
• Not enough on their own: forum posts, videos, social media, other emulator lists, or "I've used it". Use them to point to a primary source, not as the source.
• A "doesn't have it" needs a source too. Only put a feature in lacks when the docs, a complete settings list or the code show it is missing. If you can't show either way, leave it out and the site shows "not known yet".
• Images: give where the image came from and its license (see Images below).

Pull requests without sources can't be merged. If you're not sure about a value, leave it out; someone who knows can add it later.

Add an emulator

1. Create data/emulators/<slug>.json. The slug becomes the URL (/emulators/<slug>/), so use lowercase letters, digits and hyphens, e.g. steem-sse.json.
2. Fill in the fields below. Your editor will autocomplete and check them if you keep the $schema line. Existing entries make good examples to copy from: VICE is a desktop emulator with full C64 feature data, C64 READY. a browser-based one with mobile support, and Clock Signal shows partial support for several systems. Every emulator page also has an "Edit this entry" link to its file.
3. Run npm run validate, then open a pull request and list your sources in its description. CI runs the same checks.

{
  "$schema": "../../schema/emulator.schema.json",
  "name": "My Emulator",
  "systems": ["c64"],
  "description": "One or two neutral sentences on what makes it distinct.",
  "website": "https://example.org/",
  "repository": "https://github.com/me/my-emulator",
  "licenseType": "open-source",
  "license": "GPL-3.0-or-later",
  "platforms": ["windows", "macos", "linux"],
  "languages": ["C++"],
  "status": "active",
  "firstRelease": 2024,
  "accuracy": "high",
  "features": ["save-states"],
  "input": ["gamepad"],
  "devTools": ["debugger"],
  "requiresSystemRoms": false,
  "authors": ["Your Name"]
}

Fields

The fields are the same for every system, so emulators can be compared across machines. Only the first block is required; leave out anything you can't verify.

Field	Required	Values
name	yes	Display name
systems	yes	System ids, e.g. ["c64"]. Use an object for per-system detail: {"id": "amiga", "support": "partial", "accuracy": "high", "features": [...]}. support: complete, partial, experimental. features come from the system's own feature list
description	yes	20–300 characters, factual, no marketing copy
website	yes	Project home page
licenseType	yes	open-source, source-available, freeware, shareware, commercial
license	if open source or source available	SPDX id, e.g. GPL-2.0-or-later
repository	if open source or source available	Source code URL. GitHub repos show stars and the latest release automatically
platforms	yes	windows, macos, linux, bsd, android, ios, browser, raspberry-pi, amiga, dos, other
status	yes	active (activity in the last 12 months), inactive, discontinued
architectures	no	x86-64, x86, arm64, arm32, wasm
stores	no	List of {"store": ..., "url": ...}. Stores: steam, app-store, mac-app-store, google-play, f-droid, microsoft-store, flathub, snap, homebrew, winget, itch
frontends	no	Slugs from data/frontends/. RetroArch and Lakka are added automatically when libretroCore is set
languages	no	Main implementation languages
firstRelease	no	Year
accuracy	no	Overall rating: cycle-exact, high, moderate, basic
hardwareDemand	no	light, moderate, heavy
models	no	From the system's variants
mediaFormats	no	File extensions from the system's mediaFormats
features	no	Player features: save-states, rewind, fast-forward, run-ahead, netplay, crt-shaders, recording, cheats, achievements, themes
video	no	integer-scaling, vrr, high-refresh, internal-resolution, hdr, black-frame-insertion, widescreen-hacks
input	no	gamepad, touch-controls, light-gun, mouse, positional-keyboard, symbolic-keyboard, keyboard-overlay, native-keyboard
onlinePlay	no	delay, rollback, link-cable, ghost-racing
devTools	no	debugger, memory-viewer, disassembler, profiler, trace-logger, scripting, command-line
peripherals	no	Emulated add-on hardware: hard-disk, midi, printer, networking, modem, ram-expansion, accelerator-cards
requiresSystemRoms	no	true if users must supply their own BIOS/Kernal/TOS/Kickstart
firmware	no	More detail on system ROMs: not-needed, original-required, original-bundled, open-replacement-bundled, licensed-bundled
hleBios	no	true if it runs software without the real BIOS
retroAchievements	no	true if RetroAchievements is built in
libretroCore	no	Core name in RetroArch, e.g. vice_x64sc
basedOn	no	Slug of the emulator this is a fork, port or distribution of
authors	no	People, team or company
uiLanguages	no	Interface languages as codes, e.g. ["en", "de"]
price	no	{"amount": 9.95, "currency": "EUR", "freeTier": true} for commercial entries
mobile	no	{"support": "full", "features": [...], "lacks": [...]}. support: full (made for phones and tablets), partial (runs, but limited), none. Features: official-app, mobile-browser, touch-controls, on-screen-keyboard, native-keyboard, gamepad, portrait-layout, landscape-layout, installable, offline. Use lacks only for features verified to be missing
latestRelease	no	{"version", "date"}. Filled in automatically for GitHub projects
lastVerified	no	Date you checked the entry, YYYY-MM-DD
links	no	download, documentation, forum, discord, mastodon, funding
screenshot	should	{"file", "credit", "license", "source"}, see Images below

If an emulator covers a machine that isn't listed yet, add the system first.

Add a system

Create data/systems/<id>.json. The id is what emulators use in systems, so keep it short, like master-system, pc-engine, apple-ii or atari-800, none of which are covered yet. For a complete example with features, file formats and models, see the Commodore 64.

{
  "$schema": "../../schema/system.schema.json",
  "name": "Sega Master System",
  "shortName": "Master System",
  "manufacturer": "Sega",
  "type": "console",
  "released": 1985,
  "cpu": "Zilog Z80 @ 3.58 MHz",
  "variants": ["Mark III", "Master System", "Master System II"],
  "description": "One or two sentences on the machine and why it matters.",
  "wikipedia": "https://en.wikipedia.org/wiki/Master_System",
  "accentColor": "#1d4ed8"
}

System features

Some things only make sense for one machine: true drive emulation on the C64, Kickstart versions on the Amiga. Instead of adding fields for each machine, a system file lists its own features (and mediaFormats and variants), and emulators tick them per system:

"systems": [{ "id": "c64", "features": ["true-drive", "pal", "reu"], "lacks": ["ntsc"] }]

features are what the emulator has; partial maps a feature to a short note when it only partly works (for example, opening 1581 disks without emulating the drive); lacks are what it is verified not to have. Anything in neither list is shown as "not known yet", so only use lacks when the docs or the software show the feature is missing.

The system page turns these into a comparison table. Keep the list to features people actually choose emulators by.

Add an FPGA core

FPGA cores go in data/fpga/<slug>.json (schema: schema/fpga.schema.json): name, systems, description, boards (mister, analogue-pocket, mars, mist, sidi), licenseType, status, and optionally requires (sdram, dual-sdram, io-board, usb-hub), repository, accuracy, models and mediaFormats.

Add hardware

Mini consoles and FPGA hardware go in data/hardware/<slug>.json (schema: schema/hardware.schema.json): name, systems, description, manufacturer, released, technology (software-emulation, fpga), formFactor (mini, full-size, handheld) and status (upcoming, available, discontinued). Optional: includedGames, originalMedia, ownFiles, outputs, price (launch price), website and a product photo in image. Examples: THEA1200 (a pre-order mini console) and Analogue Pocket (FPGA hardware).

Add a frontend

Frontends, launchers, installers and distributions go in data/frontends/<slug>.json (schema: schema/frontend.schema.json), with a kind of frontend, launcher, installer, distribution. Emulators link to them by slug in frontends.

Images

Only freely licensed images are accepted, because the site and its data are published openly. An entry without an image shows a missing-photo icon, which is better than an image we may not use.

• Allowed: your own photos or captures, released under CC0, CC BY or CC BY-SA; images from Wikimedia Commons with their Commons license; and screenshots from a project's own repository when the repository has an open license (GPL, MIT and so on). A capture of an open-source emulator's interface is covered by that emulator's license.
• Not allowed: images from official websites, shops or press kits, unless the page gives an open license; anything from a repository with no license or a non-commercial one; and screenshots showing a commercial game, box art, a commercial operating system's desktop or other third-party artwork. Show the emulator's own interface, a boot screen, a free homebrew game or a test program instead.
• Put the file in data/images/<kind>/<slug>.png (or .jpg/.webp) and add an entry with file, credit, license and source. license must start with the license name, for example CC BY-SA 4.0, Public domain or GPL-2.0 (project repository). The validator rejects anything else.

Ground rules

• Every fact needs a source. Link it in your pull request; see Sources are required.
• Each kind has its own place. Software emulators go in data/emulators/, FPGA cores in data/fpga/, and frontends and distributions in data/frontends/. Mini consoles and FPGA hardware go in data/hardware/.
• Link to official sources. No ROM or game download sites.
• Keep descriptions neutral. Say what's distinct, not what's "best".
• Not sure about a value? Leave it out. Optional fields can be filled in later by someone who knows.