v3.0.0

307 commits since v2.3.2 (248 non-merge), 181 files, +40,392 / -841.

v3.0.0 delivers:

• Jaguar CD support — all 10 locally-available titles boot to game code, in both HLE and real-BIOS mode
• Jaguar Link networking — real link-cable multiplayer over TCP and RetroArch netplay, up to multi-console hubs
• Memory Track saves — CD games save settings, progress, and high scores like real hardware
• 100+ compatibility fixes — Wolfenstein 3D music, Pitfall, Tempest 2000, Alien vs Predator, Brutal Sports Football, and a full CD-title cluster
• Reorganized options menu — 9 categories, content-aware, translation pipeline wired
• A hardware-referenced test suite — acid conformance tests, screenshot regression baselines, and blocking CI gates

What shipped

Jaguar CD	Boots all 10 locally-available titles (11 images) to GAME_CODE in HLE and real-BIOS mode. Memory Track NVM is HLE'd, so Vid Grid saves again (#258). virtualjaguar_cd_read_speed gives 1x/2x/4x/8x/instant on the HLE path. cue2cdi ships for building CDI interchange images.
Jaguar Link networking	JagLink/CatBox emulated at the JERRY UART level. Three transports: direct TCP (works in frontends with no netplay support), the libretro netpacket interface for real RetroArch netplay, and a CatNet-style hub for more than two consoles. Doom deathmatch is playable over TCP.
Core options	9 categories with content-aware hiding, so CD-only options vanish when a cart is loaded (#251). CD BIOS Type wired up, BIOS vs. CD-BIOS wording clarified, i18n scaffolding in place.
Compatibility wave	Wolfenstein 3D music, Pitfall's black screen (#138), Tempest 2000's playfield collapse (#187), Alien vs Predator's cyan and brown bars (#178), Brutal Sports Football's copier headers, plus a CD-specific cluster. 108 of the 248 non-merge commits are typed fix.
Acid suite + blocking CI gate	Three live regressions reconciled against the JTRM, the 68000 bus-wait model corrected, and the pipefail bug that let the acid job silently pass on regressions fixed. Real regression gate now, not an aspirational one.

Breaking changes

.iso CD images are refused. A bare 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). No retail disc boots from one, and BigPEmu does not accept bare .iso either. The loader now fails at load time with an explanatory error instead of presenting a BIOS screen that goes nowhere. Use CUE/BIN or CDI (test/tools/cue2cdi converts).

Savestate format v7. States written by v3.0.0 will not load in older cores. Going the other way, everything from the v2.x releases (STATE_VERSION >= 2) still loads with newer fields defaulted; only pre-v2 states from far older cores are rejected. v7 is frozen as the stable format going forward.

Known issues

• Netlink internet play is best-effort. Only localhost and LAN play are validated. No relay, no matchmaking, and that is an explicit non-goal for now.
• BattleSphere Gold networked play is validated only to networked-lobby entry. A sustained multi-round dogfight has not been verified.
• AirCars under netpacket (RetroArch netplay) is untested; its interrupt-driven receive path doesn't exercise the same code path TCP mode does. TCP mode is fully validated for AirCars.
• iOS/Provenance TCP netlink mode has not been device-tested. Validation so far is macOS/localhost only.
• CDI images with a damaged or truncated boot header are refused (#269). Affects a small number of V2-format third-party rips where the boot landmark itself is missing, not recoverable by offset correction. V3.5 images and self-generated (cue2cdi) images are unaffected; 10/14 of the local CDI corpus passes.
• Savestates from cores older than STATE_MIN_VERSION are rejected (#268). Pre-v2 states cannot be migrated. States from the v2.x line load normally.
• Alien vs Predator: a green-dot / green title-bar-area artifact is still unreproduced (#266), and a red-background-behind-the-shotgun report (#267) is open. Both are narrower follow-ups split from the #178 umbrella, which is otherwise resolved.
• FMV scene-jump drift: Dragon's Lair, Space Ace and BrainDead 13 occasionally jump cutscenes early or late in HLE mode, because their own delivery-clock counters drift relative to our transfer pacing. Reproducible and understood, not yet fixed. Real-BIOS mode is unaffected.
• Doom runs combat pacing ~1.5x fast (2x in heavy scenes). This release measured the gap against real-hardware footage and identified GPU/DSP instruction timing as the fix path — docs/doom-pace-calibration.md has the full analysis. In-level music silence is authentic to original hardware, not a bug.
• Iron Soldier (cart): the wireframe tank is still missing under the fast blitter (#186 class). The accurate blitter is unaffected.
• Battle Sphere Gold: menu text renders too dark to read. The glyphs arrive already dark from the game's own pre-shading path, so the blitter is exonerated; the writer routine is still under investigation. Networked lobby entry is unaffected.
• Tempest 2000 (#187) and the AvP items above are not independently device-verified this cycle. Treat as believed-fixed pending confirmation.
• The accurate blitter remains considerably slower than the fast blitter. Some games may still need the fast blitter on lower-end hardware.
• No bus contention modeling beyond the experimental dram_timing option above. VC register behavior is not fully accurate.

Jaguar CD: full detail

• Full local corpus (10 titles across 11 images: 10 CUE/BIN plus 1 CDI) reaches GAME_CODE in both HLE and real-BIOS mode. The CD boot-matrix regression gate (docs/cd-boot-matrix.md) is green across all active rows, with no genuine regressions across this cycle's re-run sweeps. One apparent backward move was traced to a substituted bad disc image and is documented in the matrix.
• Corpus: Baldies, Battle Morph, BrainDead 13, Dragon's Lair, Highlander, Hover Strike, Iron Soldier 2, Primal Rage, Space Ace, Myst.
• Memory Track NVM BIOS module HLE'd (_NVM at $2400) alongside the $900000 flash window, so Vid Grid and other Memory-Track-dependent titles save correctly (#258).
• The real-BIOS path falls back to an embedded CD boot ROM when no external BIOS file is configured, so no BIOS file is strictly required.
• virtualjaguar_cd_read_speed (1x/2x/4x/8x/instant) is HLE-path only by design: scaling the real-BIOS path's FIFO/DSA cadence would reopen the DSA-steal and FIFO-storm race classes those constants encode.
• test/tools/cue2cdi: CUE/BIN → CDI converter with a batch mode, for building interchange images from disc rips.
• Known bad / copier-header dumps are warned about and named instead of silently mis-parsed.
• CD trace ring (core option virtualjaguar_cd_trace, env VJ_CD_TRACE=1) plus test/tools/cd_wedge_probe and cd_visual_verify for diagnosing intermittent CD lockups without a device.

Networking (Jaguar Link): full detail

• JERRY asynchronous serial UART emulated at the register level (ASIDATA/ASICTRL/ASISTAT/ASICLK, $F10030-$F10035), verified against the JTRM rather than source comments.
• Pluggable link transport: loopback (default/disabled), direct TCP (tcp_server/tcp_client core-option modes, per-frame link poll), and the libretro netpacket interface for real RetroArch netplay integration.
• CatNet-style multi-peer hub in the TCP link server for more-than-two-console play.
• Sub-frame link latency: immediate TX flush plus mid-frame RX pump, a self-tuning bounded wall-clock reply wait, and a fix for Wi-Fi netplay lag caused by netpacket TX batching (#248).
• Netlink host configurable as a core option; vj_netlink.txt is now a fallback rather than the only path. Hostnames resolve, not just dotted-quad addresses (#263).
• UART and link state serialize in savestates.
• Validated over TCP on localhost/LAN: Doom deathmatch (host + client join, playable), BattleSphere Gold (to networked-lobby entry), AirCars (2-player direct + 3-console hub). The direct TCP link is designed to work in any frontend without netplay support and is validated on macOS; the iOS/Provenance device test is pending (see Known Issues).

Bug fixes: full list

• Wolfenstein 3D: missing game music fixed (DSP D_FLAGS pipeline-stage correction).
• Pitfall: black screen shortly into gameplay fixed. The 68000 now builds the full 14-byte group-0 bus-error exception frame (it previously pushed only a standard frame), GPU STOREP gained byte-lane masking, plus a GPU-RAM sync correction (#138, 2 of 3 tracked sub-issues; the remaining item is a GPU ISR r31 leak, non-blocking, noted in docs/cart-issue-triage.md).
• Tempest 2000: one-frame playfield collapse fixed by holding TOM's level-2 interrupt request across the CPU interrupt mask instead of dropping it (#187).
• Alien vs Predator: first-frame cyan bar fixed (the framebuffer now seeds opaque black, not cyan — a core-wide artifact, not AvP-specific); in-game brown bottom bar fixed (rows the TOM never writes are blanked instead of showing stale data) (#178, 2 of 4 tracked sub-symptoms; green-dot artifact and a savestate-rejection edge remain open, see Known Issues).
• Brutal Sports Football: 512-byte copier header skipped instead of causing the image to be rejected.
• Iron Soldier 2: match-load hang fixed (single-step + driver-ownership handling); cold-boot black screen fixed (unaligned CD_read tail now carries the next disc bytes instead of padding).
• Battle Morph: HLE ISR stomp fixed. Stream status base is latched per CD_read instead of leaking across calls; boots in both HLE and BIOS mode.
• Myst, Primal Rage: boot-stub redirect and audio-path fixes. Both play in HLE and BIOS mode with headless audio RMS in envelope.
• Hover Strike: instant CD_read code-stomp lockup fixed. CD reads stream at drive rate instead of completing instantly and overwriting in-flight polling code.
• Baldies: HLE boot progress reporting and CDI third-party-rip loading fixed (landmark-scan CDI global-data-offset detection, #233, which also resolved #230, see Known Issues).
• Blitter: pixel-mode data reads now use channel 0's data registers (they wrongly read channel 2's).
• GPU: indexed-load alignment now tests the effective address rather than the raw register mode.
• OP: GPU objects correctly halt the Object Processor until the GPU releases OBF, then resume at the next phrase (fixed Primal Rage's black bottom-third during fights).

Options menu, performance internals, and testing

Options menu

• Core options grouped into 9 categories (#251).
• Options that don't apply to the loaded content type (CD-only options with a cart loaded, and so on) are hidden dynamically (#251).
• CD BIOS Type wired up; BIOS vs. CD-BIOS wording clarified (#251).
• i18n scaffolding: Crowdin workflow plus libretro_core_options_intl.h. 0 languages translated yet, infrastructure only in this release.

Performance / experimental

• virtualjaguar_dram_timing (Experimental, default disabled) as described above: 68000 wait-states charged only for accesses that leave the local bus (DRAM/IO are free to the 68K, matching its own 8-sysclk bus cycle; only slow cartridge ROM stalls it), GPU DRAM-access timing extracted from the bus arbiter, and OP-fetch plus DRAM refresh (MEMCON2 REFRATE) occupancy charged against the 68K.
• GPU DRAM-access timing extracted into its own accounting path in the bus arbiter (#169), separate from the 68K's self-cost.
• Savestate layout updated (v7) to persist the new bus-occupancy accumulators.

Testing

• Acid test suite reconciled: all three previously-regressed cases (unaligned_word, op_gpu_int_object, pit_countdown_rate) fixed, and the CI gate's pipefail bug fixed so the job actually blocks on regressions going forward instead of only reporting them.
• New harnesses: Doom gametic-rate and audio-gap probes for bus-occupancy calibration (doom_renderrate, per docs/doom-pace-calibration.md).
• CD boot-matrix regression tooling (cd_boot_matrix.sh) hardened: rows are build-stamped so a resume never resurrects a stale row as a fresh result. This caught a phantom intermittent Battle Morph flake that was actually an old build's row.
• cd_visual_verify (per-second motion timeline, non-black coverage, audio RMS, periodic screenshots) and cd_wedge_probe (frozen-framebuffer catch plus register/trace-ring/RAM dump) added for CD lockup triage without a device.
• Netlink test stack: test_jlink, test_uart_loopback, test_uart_core, netlink_pair, test_jlink_netpacket, and netlink_ra_matrix.sh against real RetroArch 1.22.2.

Downloads

Platform	Targets
Linux	x86_64, aarch64, i686
macOS	arm64, x86_64
Windows	x86_64, i686 (MSYS2/MinGW)
iOS / tvOS	arm64 / arm64
Android	arm64-v8a, armeabi-v7a, x86_64, x86
Web	Emscripten (bitcode for WASM builds)
Consoles	PS Vita, Nintendo Switch

Every binary has a matching debug artifact (*-debug.tar.gz): split debug symbols where the toolchain supports it (.debug / .dSYM), and the Emscripten target ships its bitcode directly. SHA256 checksums in SHA256SUMS.txt.

One stopwatch closes the biggest open number

Neither real-hardware Doom capture used in the pace calibration contains the attract demo, so its wall-clock duration on silicon is the one number the footage could not give us. Our core measures the first demo at 27.6 s and the second at 35.0 s, timed from the first rendered demo frame to the cut back to the title.

If you own a Jaguar and a copy of Doom: let it sit at the title until the attract demo starts, then time from the first frame of demo gameplay to the moment it cuts back. Both demos if you can. That number decides which timing model is right and reprioritizes the next round of work. Donated hardware works too.

Credits

Thanks to the community members who filed and helped diagnose issues fixed this cycle, including the reports that led to the Pitfall (#138), Tempest 2000 (#187), Alien vs Predator (#178) and CD compatibility (#230, #233) fixes, and to everyone who reported and re-tested the Wi-Fi netplay lag.

This release builds on the original Virtual Jaguar emulator and its contributors, and on hardware documentation cross-referenced against the Jaguar Technical Reference Manual. CD boot-sequence and TOC-format details were additionally cross-checked against the MiSTer Jaguar core and BigPEmu's documented behavior where cited in docs/.

Maintainer, libretro/Provenance fork: Joseph Mattiello (@JoeMatt, Provenance-Emu).

Archival release notes, with the full narrative version of everything above: docs/RELEASE_NOTES_v3.0.0.md.