Cupid is an NES and Famicom emulator for Windows and Linux. It supports NTSC, PAL, and Dendy timing, cartridge games, Disk System images, NSF/NSFe music, StudyBox media, and supported VS System arcade images.
The GTK4 desktop has native menus, a compact toolbar, and separate windows for settings and tools. Keep the debugger, memory editor, or TAS timeline beside the game. Windows follows the system light or dark appearance. Controls have no surrounding borders; keyboard focus stays visible in both themes. The desktop paces emulation independently of expensive display updates. When presentation falls behind, it shows the latest frame while preserving audio, movie input, and captured frames. See performance troubleshooting. Frame waits use the high-resolution clock and service pending desktop paints between frames. Windows uses an accelerated SDL game viewport even when GTK uses Cairo for desktop widgets. Game Information shows the game renderer and refreshes when a game is replaced or unloaded. Frame Timing Statistics reports emulation and display draw rates separately, with interval jitter to help diagnose uneven motion.
Get the Windows ZIP from Releases.
Extract it into a new folder and run cupid-nes.cmd. The package includes GTK and
its runtime libraries. Preview releases are available while the desktop changes
are under review.
Linux x64 previews are available as cupid-linux-x64.tar.gz for Ubuntu 24.04.
See Linux download instructions for runtime dependencies.
Use File > Open Game, press Ctrl+O, or drop an image onto the game window. Recent games remember archive members and patches. Opening another image switches games in the same window; a failed load keeps the current session available. Disk System and StudyBox images need their respective BIOS files.
Open Settings from the toolbar or press Ctrl+Comma. Choose a category on the left. Video, audio, input, media, and hardware pages divide longer lists into tabs. Apply saves validated changes; Cancel discards pending changes. File fields have native pickers. Audio settings list detected output devices.
Memory Search keeps results beside range and comparison controls. The debugger places registers and breakpoints beside disassembly. The header editor separates ROM, RAM, and console fields; format, mirroring, and region use named choices.
| Task | Tools and guide |
|---|---|
| Inspect code and memory | Debugger, assembler, memory search, watches, hex editor, and PPU viewers |
| Analyze execution | Coverage, profiles, events, symbols, source, traces, and text extraction |
| Edit input movies | TAS timeline, branches, markers, bookmarks, checkpoints, Lua, and splicing |
| Manage cheats | Cheat editor and Game Genie conversion, checksum-matched database |
| Change presentation | Shader presets, HD drafts, frame timing, history, and audio output |
| Record output | Screenshots, WAV, raw or ZMBV AVI, animated GIF, and overlays |
| Manage sessions | Automatic resume, state recording, game settings, and update checks |
| Edit cartridge metadata | iNES and NES 2.0 header editor |
| Use expansion input | Controllers and peripherals, Family BASIC keyboard |
The TAS editor opens FM2 movies and FM3 projects. Its input grid sits beside a resizable game preview and editing tabs. Save the full editing session as CTAS or export a movie. The converter handles supported power-on FCM movies after checking game identity.
These screenshots come from the native GTK regression application using a generated diagnostic cartridge and input movie. The desktop guide explains the menus, individual windows, and settings.
| Key | Action |
|---|---|
| Z / X | A / B |
| Right Shift / Enter | Select / Start |
| Arrow keys | D-pad |
| Ctrl+O | Open a game |
| Ctrl+P / Ctrl+. | Pause or resume / advance one frame |
| Ctrl+R / Ctrl+Shift+R | Soft reset / power cycle |
| F5 / F6 | Save / load the selected state slot |
| F12 | Screenshot |
| Ctrl+F12 / Shift+F12 | Audio / video recording |
| Ctrl+Shift+F12 | Stop and finalize recording |
Settings can change keyboard and gamepad assignments and select another input profile. The first SDL controller drives player 1 by default. See controls for device-specific input and shortcut precedence.
The core uses C11, with C++17 cartridge modules and the EPSM sound engine. GTK4 provides desktop widgets; SDL2 handles the emulation video pipeline, audio, and controllers. Both a C and a C++ compiler are required.
On Ubuntu:
sudo apt install build-essential libgtk-4-dev libsdl2-dev libcurl4-openssl-dev
git clone https://github.com/cupidthecat/cupid-nes.git
cd cupid-nes
make -j4
./cupid-nes path/to/game.nesOn Windows, from the repository root:
.\scripts\setup-gtk-windows.ps1
.\scripts\build-gtk-windows.ps1 -Jobs 8 -Package
Expand-Archive .\build\release\cupid-windows-x64.zip .\build\cupid-preview
.\build\cupid-preview\cupid-nes.cmdAdd -Test to run hardware regressions. make GTK=0 test builds the headless
regression suite. See getting started for toolchains,
output paths, Clang, and sanitizer builds.
Cupid supports iNES, NES 2.0, and named UNIF boards. The optional NesDB.txt
database supplies legacy corrections and recognized headerless images. Explicit
command-line settings take precedence. The hardware reference
lists mapper families, expansion sound, controller devices, supported layouts,
and remaining limits. Mapper support is not a per-game compatibility guarantee.
Cartridge saves normally live beside the ROM. Disk System writes default to a separate IPS overlay. Quitting or replacing an image finalizes recordings and persistent data first; failed writes leave the session available for retry. See saves and media, states and replay, netplay, and HD packs.
The recorded accuracy checkpoint passed all 144 AccuracyCoin tests with none skipped or unfinished, the 91-ROM diagnostic collection, and the 8,991-state canonical CPU trace in normal and sanitizer builds. Separate regressions cover mappers, storage, input, and expansion audio. Results apply to the tested revision and configuration; see accuracy notes for coverage and limits.
The GTK workflow checks settings transactions, input handling, debugger and assembler edits, TAS interactions, window resizing, and rendered screenshots. It also builds and checks the Windows package. Development and testing describes how to reproduce checks.
Start with the documentation index, configuration reference, or troubleshooting guide. See support for bug reports and contributing for changes.
Cupid is GPL-3.0-or-later; see LICENSE. Imported components retain their licenses, including emu2413 and ymfm. Credits lists component attribution, diagnostic sources, and hardware references.