VJAG_TEST

THE EMULATOR WITH THE WINDOW RIPPED OFF

C:\JAGUAR> vjag_test
vjag_test: the emulator without a window. it runs an image for a number of frames and reports.
it links without SDL, so it should build wherever V does.
C:\JAGUAR> _

THE COMMANDS

COMMANDDOES
inspect <image>describes how the image would be loaded: format, load address, entry point
run <image>runs for --frames frames, then produces what the options ask for: screenshots, sound, video, memory dumps
compat <dir>boots every image in a directory and writes a triage report: animated, static_picture, blank, crashed, load_error
bench <image>measures emulation speed with nothing holding it back
trace <image>single-steps, keeps the last instructions of one processor, and prints them when a stop condition hits

vjag accepts the same commands, so vjag run ... works too.

TRACE: HOW MOST BUGS GOT FOUND

It single-steps the machine, keeps the last instructions of one processor in a ring, and stops when something interesting happens: the DSP wanders out of its RAM, the 68000 jumps into the vector table, a memory location changes. Then it prints the ring as a disassembly. Most of the bugs fixed so far were found this way.

vjag_test trace game.j64 --cpu m68k --stop-range 0x0:0x400   # who jumped into the vectors?
vjag_test trace game.j64 --cpu m68k --watch 0x4912           # who overwrote this?
vjag_test trace game.j64 --cpu dsp --tail 80                  # what was the DSP doing?
OPTIONMEANING
--cpu m68k|gpu|dspprocessor to follow; default dsp
--tail <n>instructions to print; default 64
--stop-pc <addr>stop when the processor reaches an address
--stop-range <lo:hi>stop when its program counter enters a range
--watch <addr[:mask]>stop when the long at an address changes
--skip <n>instructions to run before the stop conditions apply

RUN: SCREENSHOTS, SOUND, FILMS

# start a game at frame 30, hold right for a second, look at the result
vjag_test run demos/wirewing.jag --frames 200 --press b@30 --press right@60+60 --screenshot shot.png

# a film with sound: frames and audio from frame 120 on, joined with ffmpeg
vjag_test run demos/maw.jag --frames 720 --video out/maw.ppm --video-from 120 --wav out/maw.wav
ffmpeg -framerate 60 -f image2pipe -c:v ppm -i out/maw.ppm -i out/maw.wav -pix_fmt yuv420p out/maw.mp4

# what is in the program's variables?
vjag_test run demos/hello.jag --frames 60 --peek 0x4000:64 --list 0x4000:20

# every write to the DSP control registers
vjag_test run game.j64 --watch-io 0xf1a100:0xf1a120
FUN FACT!! Every GIF on this site and every frame of game footage in the music video came out of vjag_test run --video. The jukebox tracks came out of --wav.
RUN OPTIONMEANING
--screenshot <png>save the last frame
--wav <file>save the sound
--video <ppm>save every frame as one stream of binary PPM images
--video-from <n>first frame saved; the --wav starts there too, so the two stay in step
--press <button@frame[+n]>hold a pad button from a frame, for n frames (6 if left out); repeatable
--press-file <file>presses from a file, one or more a line; # starts a comment
--eeprom-in / --eeprom-outload or write the 128-byte EEPROM image
--dumpprocessors, video registers and the display list at the end
--peek <addr[:len]>print memory at the end
--list <addr[:count]>disassemble 68000 code at the end
--watch-io <lo:hi>log every write to hardware registers in the range
--region ntsc|paltelevision standard; default ntsc

Buttons: up down left right a b c option pause 0-9 star hash

PRESS FILES & ROBOPLAY

A press file is the pad written down frame by frame. Here is the start of the GHOSTGRID robot's run:

# demos/ghostgrid/roboplay.press
a@3+1
a@22+1
a@41+1
right@87+10
right@99+11
down@111+9
... 233 lines, four missions, each finished unseen with an S rank

vjag <image> --press-file <file> replays it in the window, frame for frame as run would. While it plays, the pad keys are ignored (a stray key would put the game out of step), the buttons it holds stay held when the window loses focus, and the save is neither loaded nor written. Reset starts the replay over.

just roboplay ghostgrid    # four missions, unseen
just roboplay hero         # the 180 BPM finale, every note perfect

COMPAT & BENCH

vjag_test compat roms/ --frames 900 --report-json out/compat.json --screenshots out/shots
vjag_test bench game.j64 --frames 1200

Comparing two compat reports is how a change to the emulator is checked against a whole collection. --jobs sets parallel workers; the default is all cores.

A SECOND OPINION

scripts/crosscheck/run.sh runs images in another emulator, the Virtual Jaguar libretro core, and leaves a picture from each side by side. compare.v diffs them pixel by pixel at an offset of (16, 3); the colours agree to within 2 or so. It has found one bug in each direction so far.

compared 77025 pixels, 0 differ by more than 2, max channel difference 1

FULL MANUAL: docs/headless.md