The Virtual Jaguar app

The packages are attached to each GitHub release next to the core builds, and listed in that release’s SHA256SUMS.txt.

Or use the installer, which can install the core, the app, or both:

macOS, Linux

curl -fsSL {{RAW_URL}}/tools/install.sh | sh -s -- --what app

Windows (PowerShell)

$env:VJ_WHAT = 'app'; irm {{RAW_URL}}/tools/install.ps1 | iex

--what takes core, app or both; the installer verifies each download against SHA256SUMS.txt. More options, and the PowerShell alternatives, are on the home page.

Nightlies carry the app too. The rolling nightly prerelease holds VirtualJaguar-nightly-* packages built from the same develop commit as the nightly core. Add --channel nightly to the installer to get them. They are gated on compiling, not on the test suite.

Unsigned builds. Until signing is configured for the release, macOS may refuse the app at first launch (right-click the app and choose Open, once) and Windows SmartScreen may warn about the installer. Packaging, signing and the package-manager templates are in app/packaging/README.md.

Home screen Cartridges

• Three tabs: Cartridges, Jaguar CD, and BIOS & system. BIOS files are recognised by checksum and name, shown with what the core uses them for, and never launched as games. None is required.
• Favorites, recently played and save states: star a game, and the games you boot are remembered; each list shows as its own tab, as a strip on the Cartridges and Jaguar CD tabs, both, or not at all. A Save states tab lists every state with the screenshot saved with it, and a game's right-click menu can load one.
• Identification is by CRC32 against the libretro database: No-Intro for cartridges, Redump for CDs. A name-only match is badged ?, an unidentified file ??. Discs in .cue, .chd and .cdi form are checksummed from their first track; a rip that is not a Redump dump is matched by its file or folder name when that is unambiguous.
• Box art comes from libretro-thumbnails, downloaded on demand for the tiles you can see and cached on your machine. Upstream does not have art for every title, so some tiles show a snapshot or a placeholder. Download box art turns downloading off. libretro-thumbnails has no Jaguar CD art yet, so discs fall back to artwork hosted on this site until it does; right-click any tile (or drop a PNG on it) to set your own cover, or put PNGs named after the game in the covers folder of the app's data directory.
• Click a tile to launch. File > Open, drag and drop, and the command line still work, and so does File > Open recent.

The app runs RetroArch .slangp presets, unmodified, through librashader. Presets from libretro/slang-shaders are bundled: the CRT family (CRT-Royale, CRT-Geom, CRT-EasyMode and others), scanlines and interpolation, plus two small first-party presets (vj-scanlines, vj-sharp-bilinear). Point Preset folder at a full slang-shaders checkout for the rest, and preset parameters get sliders. Integer scaling and the aspect modes are separate from shaders and apply to both.

Shaders are optional: if a preset does not compile or librashader is missing, the app draws the plain picture and says why. Platform notes: the macOS and Windows packages bundle the librashader runtime; upstream publishes no Linux build, so on Linux install a librashader package and the app finds it. The macOS universal package currently ships an arm64-only librashader, so shaders may be unavailable on Intel Macs (see the packaging notes).

Settings > Video Shader

Skyhammer running

• Remapping. Settings > Input edits bindings per device (the keyboard, every gamepad, or one controller model), either everywhere or for one game. Unknown controllers can be added with a gamecontrollerdb.txt in the data folder.
• All 12 keypad keys. The default gamepad layout reaches 0–9, * and # without the overlay (face button, shoulders, triggers and the right stick). F2 opens an on-screen keypad as well.
• Keyboard play uses the Jaguar Pro Controller 6-button layout: arrows, Z X C, Enter and Right Shift, A S D for X Y Z, Q and E for the shoulders, the number row for the keypad.
• Controls overlay (F3) is a cheat sheet of the bindings in effect. It appears by itself for a few seconds when a game starts with a keyboard on Player 1, and once per gamepad model, and can be turned off in Settings > Input.
• Unusual devices. Settings > Input > Devices & players picks what is plugged into each Jaguar port: the ST and Amiga mouse, the Tempest 2000 rotary, analog, driving and paddle controllers, the 6D stick, the light gun, or a Team Tap, and which controller plays which player.

Settings > Input Devices & players

Controls overlay F3

The mouse is captured only while a mouse or rotary is plugged in and a game has focus; Esc or F10 releases it. Controller details: input devices guide and the app README.

Cheats

Emulation > Cheats lists the cheats the libretro cheat database has for the running game, with a toggle each, plus manual ADDRESS:VALUE codes. What is on is remembered per game. The database files are bundled with the app, with their licence (CC BY-SA 4.0); you can add your own .cht files.

Emulation > Cheats Tempest 2000

RetroAchievements

• Sign in from the Achievements menu. The app keeps only the login token, not your password, and keeps it in your system keychain. Unlocks, leaderboard events and progress show as toasts, and the menu has the achievement list and rich presence. The achievements window shows your avatar, the game icon and every badge, filters the list, and lists the Jaguar and Jaguar CD games that have achievements with your progress and a Play button for the ones in your library.
• Softcore is the default. Hardcore is a toggle: while it is on, loading save states is refused (saving still works) and no cheat reaches the core. Turning it on mid-game restarts the game for a clean run.
• Cartridges and .cue discs are identified. .chd and .cdi discs are not identified yet: the game runs without achievements and the app says why.

Save states

F5 saves, F7 loads, F6 cycles the slot; Emulation > State manager shows every slot with a thumbnail. States use the core’s own format, so they behave as they do in RetroArch.

State manager thumbnails

The Netplay window sets up Jaguar link-cable play over a local network: it joins the two emulated link ports. It is not rollback netplay and not general online play, and play over the Internet or a VPN is not supported. The link swaps many small messages every frame, so it is limited by network delay: a wired connection is best.

• Host shows your LAN addresses and starts listening; Join finds hosts on the LAN by discovery, or takes a typed address.
• Choose the device plugged into the link port: the JagLink / CatBox cable or the Voice Modem. Both players choose the same, run the same game and the same version of the app.
• Games: Doom (Game Mode > Deathmatch), BattleSphere Gold, AirCars, and Ultra Vortek over the Voice Modem (type 911 at the title screen).
• Two windows on one machine work too: File > New window (or open -n on macOS) starts another copy with its own save folder, so you can host in one and join 127.0.0.1 in the other, or give each window its own controller for local multiplayer.
• The same setup is on the command line: --netplay host|join|join-discovered|browse|loopback.

Netplay window Host a game

Background and the details of the link itself: netlink user guide and voice-modem.md.

• It behaves like a program of your OS: a native menu bar and Dock menu on macOS, a dark title bar and taskbar recent games on Windows, MIME types and desktop actions on Linux, double-click or Open With for .j64 .jag .cue .chd and the other game formats (an installer checkbox on Windows), and an optional tray or menu-bar icon.
• The app keeps its settings, saves and states in the per-user data folder (or beside the program in portable mode). Everything is listed in the app README.
• To build it yourself, see app/README.md: SDL3, Dear ImGui and OpenGL 3.3, CMake 3.20 or later.
• Questions and reports go in Discussions and Issues; mention that it is the app and the version shown in Help > About.