Virtual Jaguar libretro

An Atari Jaguar and Jaguar CD emulator packaged as a libretro core, so it runs in RetroArch and other libretro frontends. It emulates the 68000, GPU, DSP and Object Processor, plus the CD drive controller, link port, Memory Track and GameDrive. It continues the original Virtual Jaguar project (see Credits).

Website, downloads, compatibility and enhancement write-ups: jaguar.provenance-emu.com.

Two ways to play: the RetroArch core (everything below), or the standalone desktop app for macOS, Windows and Linux, which runs the same core without RetroArch. New in v3.9.0.

Install

• RetroArch: Online Updater > Core Downloader > Atari - Jaguar (Virtual Jaguar).

• Releases: tagged builds are on GitHub Releases. Put the file in RetroArch's cores folder.

• Nightly: the rolling nightly prerelease is rebuilt on every push to develop. It is gated on compiling, not on the test suite.

• The desktop app: packages for macOS, Windows and Linux are on the same releases and nightlies; see The desktop app.

• Installer: one command installs or updates the core, the app, or both, and checks each download against SHA256SUMS.txt (read tools/install.sh and tools/install.ps1 first; both take --dry-run / -DryRun and --channel nightly / -Channel nightly):

  curl -fsSL https://raw.githubusercontent.com/libretro/virtualjaguar-libretro/master/tools/install.sh | sh -s -- --what both   # or: --what core | --what app
  

  Windows (PowerShell): $env:VJ_WHAT = 'both'; irm https://raw.githubusercontent.com/libretro/virtualjaguar-libretro/master/tools/install.ps1 | iex

Core release builds cover Linux (x86_64, aarch64, i686, and Raspberry Pi 1, 2, 3, 4 and 5, each with its own CPU-tuned build, plus 64-bit builds for the Pi 3, 4 and 5), macOS (Apple Silicon, Intel), Windows (x64, x86), Android (arm64-v8a, armeabi-v7a, x86_64, x86), iOS (arm64), tvOS (arm64), WebAssembly (Emscripten), PS Vita and Nintendo Switch. The matrix is in release.yml. Other platforms get the core through the libretro buildbot.

BIOS

None required. The Jaguar boot ROMs and CD BIOSes are embedded, and cartridges boot through a high-level BIOS by default. Optional external boot ROM and CD BIOS overrides, and exactly how they are found and checked, are in docs/bios.md.

Content

Type	Extensions	Notes
Cartridge	j64, jag, rom, abs, cof, bin, prg	Headerless raw homebrew is detected conservatively. Soft patching is covered in docs/rom-patches.md.
Jaguar CD	cue (with bin), cdi, chd	.iso is not supported. CHD needs session metadata from a recent chdman; see docs/jagcd-chd.md. Each release attaches a suitable chdman as jagcd-tools-*.zip.

The core can also start with no content and take a disc through RetroArch's disk control. Cartridge EEPROM/SRAM and the CD Memory Track are saved as <game>.srm in RetroArch's saves folder; save states go in states. Exception: a no-content session exposes the Memory Track as save RAM from the start (#810), but with no content the frontend has nothing to name the .srm after, so it is not per-game and is not named after the disc you insert. Load the disc as content for per-game saves.

The desktop app

A standalone front end for the same core, in app/: SDL3 for window, audio and input, Dear ImGui for the UI, OpenGL 3.3 for presentation. It drives the core through the same retro_* API RetroArch uses, so core options and save states behave the same. It carries the core's version number and is released with it (new in v3.9.0). Screenshot gallery and downloads: jaguar.provenance-emu.com/app.html.

<p> <img src="site/assets/app_library.png" width="49%" alt="The app's game library: Favorites and Recently played strips above a grid of Atari Jaguar box art tiles, under Cartridges, Jaguar CD, Save states and BIOS and system tabs"> <img src="site/assets/app_game_crt.png" width="49%" alt="The Alien vs Predator menu drawn through the crt-gdv-mini-ultra-trinitron aperture-grille shader preset"> </p> <p> <img src="site/assets/app_theme_jaguar_red.png" width="49%" alt="The library in a custom dark theme named Jaguar Red, with a red accent"> <img src="site/assets/app_ra_achievements.png" width="49%" alt="The Achievements window for Ultra Vortek: grey locked and coloured unlocked badges, points, rarity and unlock dates (a mock RetroAchievements account)"> </p>

• Library: your games in Cartridges, Jaguar CD, Favorites, Recently played, Save states and BIOS & system tabs; identified by CRC32 (No-Intro, Redump), box art from libretro-thumbnails on demand, title cards or your own cover for discs.
• Playing: save states with thumbnails and "Resume where I left off", per-device and per-game remapping (all 12 keypad keys, rotary, mice, light gun, Team Tap), cheats from the libretro database, several windows at once, and link-cable netplay on a local network (not rollback, not for the Internet).
• Look & feel: dark, light and custom themes with an editor, a choice of interface font, RetroArch .slangp shaders through librashader with the slang-shaders CRT, scanline and interpolation families bundled, aspect fit and integer scaling, and native menus on each OS. The macOS and Windows packages bundle librashader; on Linux install a librashader package, and the macOS universal package currently ships an arm64-only copy, so shaders may be unavailable on Intel Macs (packaging notes).
• RetroAchievements and Discord: softcore by default, optional hardcore (no loading states, no cheats), login token kept in the system keychain; optional Discord Rich Presence for the game you are playing. See the privacy policy and terms.
• AI players: the Neuro game API: Neuro-sama, or any AI that speaks it, plays as Player 1 through controller actions and per-game profiles (Tempest 2000 built in). See docs/neuro.md.
• Developer tools: memory and palette editors, cheat scanner, Object Processor list, blitter log, texture browser, audio scope and a CPU debugger (68000, GPU, DSP).

System	Package (X.Y.Z is the version; nightlies use nightly)
macOS 11+, Apple Silicon and Intel	VirtualJaguar-X.Y.Z-macos-universal.zip
Windows x64	VirtualJaguar-X.Y.Z-windows-x64.zip (portable) or ...-windows-x64-setup.exe (installer)
Windows ARM64	VirtualJaguar-X.Y.Z-windows-arm64.zip (portable) or ...-windows-arm64-setup.exe (installer)
Linux x86_64, aarch64	VirtualJaguar-X.Y.Z-linux-<arch>.AppImage or virtualjaguar_X.Y.Z_<amd64|arm64>.deb
Linux x86_64 (Flatpak)	VirtualJaguar-X.Y.Z-linux-x86_64.flatpak

The macOS app, core and command-line tools are signed with a Developer ID and notarized by Apple. The Windows installer is not code-signed yet, so SmartScreen may warn. Builds you make yourself are unsigned until you sign them. To build it, see app/README.md; packaging is in app/packaging/README.md.

Features

• Jaguar CD: boots through a high-level CD BIOS (default) or the real CD BIOS on emulated BUTCH hardware; audio CDs and the Virtual Light Machine work. Memory Track saves are emulated. Load-time tuning: docs/cd-read-speed.md.
• Enhancements, all core options: true-color Gouraud shading, 2x internal resolution, widescreen, per-title defaults, and texture dump/replacement for HD packs. Overview and A/B images on the website; texture packs in docs/texture-dump.md.
• Speed: an accurate SIMD blitter (SSE2/NEON), idle-loop fast-forward for the GPU and DSP (on by default), and M68K and RISC clock-scale options. Which options help and which cancel each other: docs/settings-and-performance-guide.md.
• Save states, run-ahead, rewind, cheats, RetroAchievements: supported. The state format reads every version back to the first release, though a CD state is refused on a different disc (docs/savestate-compat.md).
• Controllers: joypad, Pro Controller, Team Tap, ST/Amiga mouse, Tempest rotary, analog and driving controllers, 6D stick and light gun, with per-axis tuning. See docs/input-devices-user-guide.md.
• Link play: JagLink/CatBox serial over TCP or RetroArch netplay, and the Voice Modem (docs/netlink-user-guide.md, docs/voice-modem.md).
• Jaguar GameDrive: detection and bank switching for GD-locked homebrew (docs/jgd-interface-notes.md).
• Debugging: a crash watchdog that writes the failure signature to the frontend log, and an optional GDB/LLDB stub (docs/gdb-stub-guide.md).

Every option is documented in the core options menu and in the libretro docs, which can lag the newest release.

Compatibility

Nearly every cartridge and disc image in the maintainer's test corpus reaches game code, but some games are still broken, freeze, or run at the wrong speed. The website's compatibility page is the player-facing summary.

The committed boot matrices are headless regression gates, not completion certificates: docs/cart-boot-matrix.md and docs/cd-boot-matrix.md. The cartridge matrix runs only the Fast blitter, so it misses freezes that appear at default settings (#800). A reaching-game-code row does not mean a game is playable. Known problems are tracked in the v3.7.1 milestone, docs/cd-known-issues.md and docs/cart-issue-triage.md. libretro also keeps a community compatibility list.

If a game works or fails for you, tell us in Discussions and attach the frontend log.

Building

make -j$(getconf _NPROCESSORS_ONLN)          # build for the host platform
make -j$(getconf _NPROCESSORS_ONLN) DEBUG=1  # -O0 -g
make platform=ios-arm64                      # cross-compile
make test                                    # test suite (builds with TEST_EXPORTS=1)

The result is virtualjaguar_libretro.{so,dylib,dll} in the repository root. The desktop app is a separate CMake build (cmake -S app -B app/build); see app/README.md. The source is strict C89/GNU89 because the libretro buildbot uses MSVC; run bash scripts/c89-lint.sh before pushing. Platforms, cross-compiles and test details are in docs/agent/build.md and docs/agent/testing.md. Other docs: source layout, profiling, release process.

Contributing and support

• Pull requests target develop, not master. Branching, lint gates and commit style are in CONTRIBUTING.md.
• Bugs: Issues; questions and compatibility reports: Discussions.
• Security reports: SECURITY.md. Do not file these as public issues.
• Release history: docs/RELEASE_NOTES_v3.7.0.md and the earlier docs/RELEASE_NOTES_*.md.

Credits and license

• Original Virtual Jaguar by David Raingeard (Potato Emulation).
• SDL/Linux/Win32 port by Niels Wagenaar and Carwin Jones (SDLEMU).
• Cleanups, the Qt GUI and upstream maintenance by James Hammons (Shamus). The upstream repository was shamusworld.gotdns.org/git/virtualjaguar; a GitHub mirror exists.
• libretro port by libretro/RetroArch contributors; current maintainer Joseph Mattiello (@JoeMatt). Many Jaguar CD fixes in v3.7.0 are by Adrien Beudin (@beudbeud). Full list: contributors.

Licensed under the GNU General Public License v3.0.