Skip to content

Atari - Jaguar (Virtual Jaguar)

Background

Virtual Jaguar is the actively maintained Atari Jaguar and Jaguar CD emulator for libretro, continuing the Virtual Jaguar project (originally by David Raingeard of Potato Emulation).

No BIOS files are required: the Jaguar boot ROM and CD BIOS images are embedded in the core. The core supports Jaguar CD (CUE/BIN, CDI) with Memory Track saves and audio-CD / Virtual Light Machine playback, the Jaguar GameDrive (JagGD) flash cartridge, JagLink/CatBox network play over TCP or RetroArch netplay, a high-level BIOS that lets most commercial titles boot without a real BIOS image, save states, SRAM, cheat codes and RetroAchievements. Enhancement options include M68K/RISC clock scaling (overclock) for framerate-limited games, full-precision 'True Color' gouraud shading, and 2x internal resolution. The accurate blitter is SIMD-accelerated (SSE2 on x86, NEON on ARM); the Blitter core option can be set to 'Fast' to trade some accuracy for additional speed on lower-end hardware.

Author/License

The Virtual Jaguar core has been authored by

  • Joseph Mattiello
  • David Raingeard
  • Shamus

The Virtual Jaguar core is licensed under

A summary of the licenses behind RetroArch and its cores can be found here.

Extensions

Content that can be loaded by the Virtual Jaguar core have the following file extensions:

  • .j64
  • .jag
  • .rom
  • .abs
  • .cof
  • .bin
  • .prg
  • .cue (Jaguar CD)
  • .cdi (Jaguar CD)

Attention

Bare .iso images are refused at load time. A 2048-byte-sector ISO cannot represent a Jaguar CD's multi-session layout (session 1 audio warning track, session 2 data recorded as byte-swapped 2352-byte audio-type sectors, track lead-in offsets), so no retail disc can boot from one. Use CUE/BIN or CDI instead.

Databases

RetroArch database(s) that are associated with the Virtual Jaguar core:

BIOS

No BIOS files are required. The Jaguar console boot ROM and both Jaguar CD BIOS images are compiled into the core.

The files below are optional overrides for the Jaguar CD real-BIOS boot path only. If present in the frontend's system directory they are preferred over the embedded copies, and the 'CD BIOS Type' core option picks which one wins when both are present.

Filename Description md5sum
[BIOS] Atari Jaguar CD (World).j64 Jaguar CD BIOS, retail - optional override 77cd95c7ad06a39f4c59995094aa10f9
[BIOS] Atari Jaguar Developer CD (World).j64 Jaguar CD BIOS, developer - optional override 578de34498cb9a40c5368b6f5ca80484

The CD BIOS is also searched for under several other common filenames, and inside Atari - Jaguar, Atari - Jaguar CD, jaguar and jaguarcd sub-folders of the system directory.

Attention

The Jaguar console boot ROM is never loaded from the system directory — the 'BIOS (Cartridges)' core option selects between the core's HLE BIOS and the embedded boot ROM. There is no cartridge BIOS file to supply.

Features

Frontend-level settings or features that the Virtual Jaguar core respects.

Feature Supported
Restart ✔
Screenshots ✔
Saves ✔
States ✔
Rewind ✔
Netplay ✔
Core Options ✔
Memory Monitoring (achievements) ✔
RetroArch Cheats ✔
Native Cheats ✔
Controls ✔
Remapping ✔
Multi-Mouse ✕
Rumble ✕
Sensors ✕
Camera ✕
Location ✕
Subsystem ✕
Softpatching ✔
Disk Control ✕
Username ✕
Language ✕
Crop Overscan ✕
LEDs ✕

Attention

The core reports its save states with no serialization quirks, which is what enables rewind and netplay.

Directories

The Virtual Jaguar core's internal core name is 'Virtual Jaguar'

The Virtual Jaguar core saves/loads to/from these directories.

Frontend's Save directory

File Description
*.srm Cartridge EEPROM, CD EEPROM and Memory Track NVRAM save data

Note: All non-volatile save data goes into a single frontend-managed .srm. Cartridge content stores the cartridge and CD EEPROM banks (128 bytes each); CD content additionally stores the 128 KB Memory Track NVRAM after them.

Frontend's System directory

File Description
Jaguar CD BIOS images Optional - see BIOS
vj_netlink.txt Optional - network link host address on the first line, used when the 'Network Link Host' core option is set to 'From file'

Geometry and timing

  • The Virtual Jaguar core's core provided FPS is 50 for PAL games and 60 for NTSC games.
  • The Virtual Jaguar core's core provided sample rate is 48000 Hz
  • The Virtual Jaguar core's core provided aspect ratio is 4/3

Core options

The Virtual Jaguar core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded.

Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch.

Options are grouped into categories, and options that do not apply to the loaded content type are hidden — the CD-ROM options do not appear when a cartridge is loaded, and vice versa.

Video

  • Blitter [virtualjaguar_usefastblitter] (Accurate|Fast)

    Choose which blitter implementation to use. 'Accurate' is SIMD-accelerated (SSE2 on x86, NEON on ARM) and is the most compatible. 'Fast' is the older blitter; it trades accuracy for extra speed on low-end hardware and breaks some games.

  • PAL (Restart) [virtualjaguar_pal] (disabled|enabled)

    Emulate a PAL Jaguar instead of NTSC.

  • True Color (Gouraud Precision) [virtualjaguar_true_color] (disabled|enabled)

    Render gouraud-shaded pixels at full precision (chroma x 24-bit intensity) to reduce banding in 3D games. The game-visible 16-bit framebuffer is unchanged, so savestates, achievements and emulation behaviour are unaffected. Applies to CRY 16bpp video modes only.

  • Internal Resolution (Restart Required) [virtualjaguar_internal_resolution] (1x (native)|2x)

    Render internally at a multiple of the Jaguar's native resolution. At 2x, qualifying content is supersampled with real sub-pixel detail rather than merely upscaled: fractional-walk blits, scaled Object Processor sprites (including 8bpp CLUT objects), and both CRY and RGB16 direct video modes all resolve genuine extra detail. Applied when content is loaded; changing it mid-game takes effect on restart. The game-visible framebuffer and all emulation timing are unchanged — savestates and achievements are unaffected. Combines with True Color.

  • Per-Title Enhancement Defaults [virtualjaguar_pertitle_defaults] (enabled|disabled)

    Apply known-safe enhancement presets automatically for recognized games (e.g. internal resolution or true color for titles verified to benefit). A preset only applies to options you have left at their default value — any option you change yourself always wins. Disable for stock behaviour on every title.

  • Blit Memoization (Per-Title) [virtualjaguar_blit_memo] (Disabled|Enabled|Verify (debug, no speedup))

    Skip blits whose inputs are provably unchanged since an identical earlier blit (some titles re-render an identical scene every engine cycle while the player is idle). Output is bit-identical by construction; enabled per title via the enhancement database. Verify mode never skips — it executes every would-be skip and logs any divergence. Not available for CD content.

BIOS & Boot

  • BIOS (Cartridges) [virtualjaguar_bios] (HLE|Real)

    Which BIOS a CARTRIDGE boots with. 'HLE' has the core emulate the BIOS setup and services itself, which lets most commercial titles boot faster and skips the boot animation. 'Real' runs the actual Jaguar boot ROM, which some titles require. The boot ROM is built into the core, so neither setting needs a file — unlike the CD BIOS, the console boot ROM is never loaded from the system directory. Ignored for CD content: there, 'CD Boot Mode' decides and turns the boot ROM on or off to match.

BIOS (Cartridges) - Real

  • Jaguar GameDrive (Restart) [virtualjaguar_jgd] (Auto (images over 6 MB)|disabled|Enabled (force, for GD-locked images))

    Emulate the Jaguar GameDrive (JagGD) flash cartridge: its detection/install interface and 1 MB bank switching of up to 16 MB of cart SDRAM. 'Auto' turns it on only for ROM images larger than the 6 MB cartridge window. 'Enabled' forces it on for smaller images too, for GD-locked homebrew that refuses to boot without the cart. Without it, GD-locked titles hang at boot exactly as on a stock console.

CD-ROM

These options only apply to Jaguar CD content.

  • CD Boot Mode (Restart) [virtualjaguar_cd_boot_mode] (HLE (Recommended)|Auto (Real BIOS)|Real BIOS (Included, Experimental))

    How Jaguar CD discs boot. This OVERRIDES the 'BIOS (Cartridges)' setting for CD content. 'HLE' emulates the CD BIOS services directly and runs with the console boot ROM off — fastest and the most broadly compatible. 'Real BIOS' runs an actual CD BIOS and forces the boot ROM on: more faithful, still experimental. It prefers a CD BIOS ROM file from the system directory and otherwise uses the embedded image chosen by 'CD BIOS Type', so no files are required. 'Auto' is currently identical to 'Real BIOS'. If a real-BIOS mode is chosen but no CD BIOS can be staged at all, the core falls back to HLE rather than failing.

  • CD BIOS Type (Restart) [virtualjaguar_cd_bios_type] (Retail|Developer)

    Which CD BIOS the real-BIOS boot path uses. 'Retail' is the standard consumer BIOS; 'Developer' is the dev-kit BIOS, which applies less strict disc checks and can boot images the retail BIOS refuses. Both are built into the core, so no files are required. CD BIOS ROM files in the system directory are preferred over the embedded images, and this selection picks which file wins when both types are present. Only has an effect when 'CD Boot Mode' is 'Real BIOS' or 'Auto' — the HLE boot path never runs a CD BIOS.

  • CD Read Speed (HLE Boot Mode Only) [virtualjaguar_cd_read_speed] (1x (150 KB/s)|2x (Accurate)|4x|8x|Instant)

    Data-transfer rate for Jaguar CD reads in HLE boot mode. '2x' matches the real drive (300 KB/s) and is hardware-accurate. Higher speeds shorten load times but may break timing-sensitive titles (some games rely on the drive rate for code overlays, music cues, and load handshakes); 'Instant' completes each read in one tick and is the most likely to cause hangs. BIOS boot mode always uses the accurate rate. Applied per-read: a transfer already in flight keeps the speed it started with.

  • Memory Track (Restart) [virtualjaguar_memory_track] (enabled|disabled)

    Emulate the Memory Track save cartridge alongside the CD unit, as on real hardware. CD games detect it and save settings, progress and high scores to its 128 KB NVRAM (stored in the save file). Disable to emulate a console without the cartridge — games will warn that game information cannot be saved.

  • Network Link (JagLink / CatBox) [virtualjaguar_netlink] (disabled|Loopback (echo to self)|TCP Host (listen)|TCP Client (connect))

    Emulates JERRY's serial link port used by networked games (BattleSphere, AirCars, Doom deathmatch). 'Loopback' echoes transmitted bytes back to this console, for testing link-detect menus without a partner. TCP Host listens for a second emulator instance; TCP Client connects to the address in 'Network Link Host'. Localhost/LAN latency recommended.

    The core also implements the libretro netpacket interface, so RetroArch's own netplay carries the link with this option left disabled — which needs no address configuration at all.

  • Network Link Host (TCP Client) [virtualjaguar_netlink_host] (127.0.0.1 (localhost)|jaghub.local (host machine named 'jaghub' on the LAN)|From file (vj_netlink.txt in system dir))

    Address the TCP client connects to — an IP, a DNS name, or a Bonjour/mDNS name. Easiest LAN setup with no typing at all: name the host machine 'jaghub' (its local hostname), then pick the 'jaghub.local' preset here on each client. Frontends with free-text option entry accept any address directly; in stock RetroArch the alternative is 'From file' with the address on the first line of vj_netlink.txt in the system directory. The VJ_NETLINK_HOST environment variable overrides this option.

  • Network Link Port [virtualjaguar_netlink_port] (42171|42172|42173|42174)

    TCP port for the network link (both sides must match). Overridable with the VJ_NETLINK_PORT environment variable.

  • Network Link Latency Hiding [virtualjaguar_netlink_wait] (enabled|disabled)

    Briefly holds each frame until the link partner's reply arrives, so network latency doesn't round every link exchange up to whole video frames. The wait adapts automatically to the measured connection (a few ms on localhost, more on Wi-Fi) and is capped so audio/video pacing survives. Disable only for troubleshooting or benchmarking.

Input

  • Enable Core Options Remapping [virtualjaguar_alt_inputs] (disabled|enabled)

    Enabling this option will let you rebind controllers from the core options, removing the 'Controls' menu limitation that makes Numpad 7, 8, 9, * and # impossible to remap. NOTE: the 'Controls' menu can still conflict with the core options remapping, if you're using a remap file it is recommended to delete/reset it.

Input Port 1

  • Port 1 > Numpad Buttons to Keyboard Keys [virtualjaguar_p1_numpad_to_kb] (disabled|Number Row Keys|Keypad Keys)

    Map Jaguar numpad 0-9, * and # to keyboard keys. 'Number Row Keys' will use 1234567890-= keys, 'Keypad Keys' will use 0123456789/* keypad keys.

  • Port 1 > RetroPad (button) [virtualjaguar_p1_retropad_*]

    One option per RetroPad input (Up, Down, Left, Right, A, B, X, Y, Select, Start, L1, R1, L2, R2, L3, R3, and the eight analog stick directions) — for example virtualjaguar_p1_retropad_a and virtualjaguar_p1_retropad_l1. Each can be assigned to any Jaguar control: Up, Down, Left, Right, A, B, C, Pause, Option, Numpad 0-9, Numpad *, Numpad #, or --- (unbound). Requires 'Enable Core Options Remapping' to take effect. Defaults match the controller table below.

Input Port 2

  • Port 2 > Numpad Buttons to Keyboard Keys [virtualjaguar_p2_numpad_to_kb] (disabled|Number Row Keys|Keypad Keys)

    As Port 1, for the second controller.

  • Port 2 > RetroPad (button) [virtualjaguar_p2_retropad_*]

    As Port 1, for the second controller — for example virtualjaguar_p2_retropad_a.

Diagnostics

  • Crash Detect [virtualjaguar_crash_detect] (Enabled|Disabled|Enabled (verbose / heartbeat))

    Lightweight runtime watchdog that logs GPU/DSP PC escape, GPU/DSP wedge, and video stall events to the RetroArch log. Helpful when filing bug reports about games that hang or go to a black screen mid-play. Verbose mode also dumps a state heartbeat every 10 seconds.

  • CD Trace (Diagnostic) [virtualjaguar_cd_trace] (disabled|enabled)

    Records DSA command/response traffic and seek/FIFO transitions to a bounded ring buffer, dumped to the RetroArch log when the cd_seek_wedge watchdog fires. Diagnostic only — intended for troubleshooting Jaguar CD boot/data-transfer bugs, not for normal play.

Timing

Clock speed multipliers first, then the experimental hardware-timing models they interact with.

  • M68K Clock Scale (Overclock) [virtualjaguar_m68k_clock_scale] (0.5x|1x (stock)|1.5x|2x|3x)

    Run the 68000 at a multiple of its stock ~13.3 MHz. An enhancement, not an accuracy fix: it can smooth framerate-limited games (Doom, AvP, Checkered Flag) but may break titles that depend on stock CPU timing. Timers and bus costs stay at stock speed. If an overclocked game misbehaves, try enabling the timing models below. Report bugs only at 1x.

  • RISC (GPU/DSP) Clock Scale (Overclock) [virtualjaguar_risc_clock_scale] (0.5x|1x (stock)|1.5x|2x)

    Run the GPU and DSP at a multiple of their stock ~26.6 MHz. An enhancement, not an accuracy fix: extra cycles can lift GPU-bound framerates. Audio pacing and timers stay at stock speed, so nothing pitch-shifts. May break titles that depend on stock RISC timing. If an overclocked game misbehaves, try enabling the timing models below. Report bugs only at 1x.

  • DRAM Timing (Experimental) [virtualjaguar_dram_timing] (disabled|enabled)

    Charge the GPU and 68000 realistic DRAM access time once they leave their local buses, pacing hardware-timed games (Doom-class) closer to real hardware. Each processor pays only its own costs, so relative CPU/GPU timing is preserved. Still being calibrated.

  • GPU Pipeline Timing (Experimental) [virtualjaguar_gpu_pipeline_timing] (disabled|enabled)

    Model the GPU's real instruction costs: the single external-memory gateway, the register score-board, and ALU interlocks. The emulated GPU otherwise finishes renders 2-4x faster than silicon, which makes loops paced on render completion (Doom's menus and demo, Hover Strike) run too fast. Still being calibrated.

  • Blitter Bus Timing (Experimental) [virtualjaguar_blitter_timing] (disabled|enabled)

    Charge the 68000 the bus time each blit really takes — on hardware the blitter is the top-priority bus master and freezes the cacheless 68000 while it runs. Zero-time blits let games paced on blit completion (Doom's menus, Hover Strike) run too fast. Still being calibrated.

Controllers

The Virtual Jaguar core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s):

User 1 - 2 device types

  • None - Doesn't disable input. There's no reason to switch to this.
  • RetroPad - Joypad - Stay on this.
  • RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this.

Controller tables

Joypad

User 1 - 2 Remap descriptors RetroPad Inputs
B
C
Pause
Option
D-Pad Up
D-Pad Down
D-Pad Left
D-Pad Right
A
Numpad 0
Numpad 1
Numpad 2
Numpad 3
Numpad 4
Numpad 5
Numpad 6

Note: Numpad 7, 8, 9, * and # cannot be reached from the 'Controls' menu. Enable the 'Enable Core Options Remapping' core option to bind them.

Keyboard

User 1 Joypad Descriptors Keyboard Inputs
Numpad 0 0
Numpad 1 1
Numpad 2 2
Numpad 3 3
Numpad 4 4
Numpad 5 5
Numpad 6 6
Numpad 7 7
Numpad 8 8
Numpad 9 9
Numpad * -
Numpad # =

Compatibility

The full commercial cartridge library and every Jaguar CD title boot and run. Per-game issues are tracked on the core's issue tracker rather than duplicated here, so that a single list stays current — please file a report there if a game misbehaves.

Jaguar CD discs boot in both HLE and real-BIOS mode; the per-title boot matrix lives in the core repository as docs/cd-boot-matrix.md.

Audio CDs (as CUE/BIN images) play through the Jaguar CD's Virtual Light Machine. Set 'CD Boot Mode' to 'Auto' or 'Real BIOS' for audio-only discs — they have no boot stub for the HLE path.