THE EMULATOR WITH THE WINDOW RIPPED OFF
| COMMAND | DOES |
|---|---|
| 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.
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?
| OPTION | MEANING |
|---|---|
| --cpu m68k|gpu|dsp | processor 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 |
# 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
vjag_test run --video. The jukebox tracks came out of --wav.
| RUN OPTION | MEANING |
|---|---|
| --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-out | load or write the 128-byte EEPROM image |
| --dump | processors, 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|pal | television standard; default ntsc |
Buttons: up down left right a b c option pause 0-9 star hash
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
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.
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