The emulator

The emulator is ZX-V in software. It runs the same ROM (the BASIC) as the real machine, so a program that works in the emulator works on the hardware, and the other way round. It comes in several forms:

The Windows and Linux packages contain zxv, zxv-sdl, zxv-cli, sdimg, zxv-check, zxv-gfx and zxv-tracker, plus the examples (the ejemplos folder) and the ROM: drive (romdisk.bin). How to download them is explained in Getting started.

The desktop application (zxv)#

zxv opens a window with the machine's screen, menus and a status bar. The picture is scaled without distortion when you resize the window. What you choose (window size, SD card, recent files, options) is remembered for the next time.

The menus#

File

Machine

View: the window size (x1 is 640 × 480, up to x4), the border, the scaling, full screen (Alt+Enter, without menus) and the status bar. The border is what surrounds the 512 × 384 drawing area: Full shows what the real machine sends to the screen (640 × 480), Small (576 × 432) crops it, and No border leaves just the drawing area. It is remembered for next time. Scaling says how the picture fills the window when you make it bigger: Keep the aspect ratio (the usual: as big as fits without distortion), Integer scale (only x1, x2, x3..., with every pixel the same size) or Fill the window, even if the picture gets stretched. When the scale is not a whole number, the picture is enlarged with the pixel edges smoothed, without some rows thicker than others.

Options

Debug: the debugger window (Alt+D), loading a program's symbols, one instruction (Alt+N), to the end of the frame (Alt+F), the GDB server and the strict mode warnings. See Debugging.

Help: the keyboard and shortcuts, this documentation (the copy in the package, which works offline, or else the one on the web), and the version.

The keyboard#

You type as on any PC, with your own keyboard layout: what is printed on the key is what you get. BASIC and its editor use the PC keys directly:

Windows keeps Ctrl+Alt+Del for itself, and some Linux desktops do too: if that happens, use Machine > Ctrl+Alt+Del (back to BASIC).

The editor is explained in The editor.

Because Ctrl belongs to the machine, all the emulator's shortcuts use Alt. Alt on its own does not open the menu bar.

The Spectrum keys. Some programs, especially those that come from the ZX Spectrum, read the keyboard as the Spectrum's grid of keys (with IN or INKEY$). For them, your PC keyboard also presses the Spectrum keys: letters and digits are themselves, Shift is CAPS SHIFT, Ctrl is SYMBOL SHIFT, Backspace is DELETE (CAPS SHIFT + 0), Esc is BREAK (CAPS SHIFT + SPACE) and the arrow keys are CAPS SHIFT + 5, 6, 7 and 8. Punctuation follows the symbol your key produces: the key that types " presses SYMBOL SHIFT + P, whatever your layout. You do not need to think about this in normal use.

Mouse and gamepads#

The mouse does not need to be captured: while the PC pointer is over the picture, the machine's pointer goes to the same place, and the buttons and the wheel are the machine's. When it leaves the picture, it is your PC's pointer again. If a program draws its own pointer, Options > Hide the PC pointer over the picture removes the duplicate.

Gamepads work as soon as you connect them; the first is player 1 and the second, player 2. The d-pad or the left stick are the directions, and the buttons are:

On a PlayStation pad that is ✕, ○ and □. The PC keyboard is not turned into a gamepad; most games, like Estela, accept both the keyboard and a gamepad.

The SD card#

The machine keeps your files on its SD card. In zxv you can choose, in File > SD card:

• The usual one (Documents/ZX-V): the default. The first time, zxv creates this folder and copies the examples into it.
• A folder...: any folder of your PC acts as the card. Everything the machine saves goes into it, and anything you copy there with your file manager is on the card. Open the folder shows it in your file manager.
• A card image...: a .img file containing a whole card, formatted as FAT, FAT32 or exFAT. It can be a copy of a real ZX-V card, which you can make with dd on Linux or a tool such as Win32 Disk Imager on Windows, and you can write an image back to a card.
• No card: as if the card had been taken out. BASIC then reports U No SD card.

A folder card behaves like a real card: names are not case sensitive (GAME.ZVB and game.zvb are the same file) and programs cannot see anything outside the folder. File names can use only unaccented letters, digits and some symbols, up to 63 characters; files with other names do not show up.

sdimg creates and fills card images from the command line:

sdimg new card.img 64 fat32          # a new 64 MB image (fat, fat32 or exfat)
sdimg put card.img game.zvb /game.zvb   # copy a file into the image
sdimg get card.img /game.zvb game.zvb   # copy a file out of it
sdimg mkdir card.img /games          # create a folder
sdimg ls card.img /                  # list a folder, with dates

(sdimg speaks only Spanish for now.)

The ROM: drive, with the built-in examples, is the romdisk.bin file that sits next to the emulator. If it is missing, ROM: is empty.

Opening files#

File > Open... (Alt+O), dragging a file onto the window, or naming it on the command line (zxv game.zvb) all do the same:

Programs from outside the card. A program has to be on the card to be loaded, so if it is somewhere else the emulator asks you to choose:

• Copy it to the card, to its main folder, together with the files next to it that have the same name (such as a game's .gfx graphics).
• Use its folder as the card until you choose another one. Anything the program saves goes into that folder.

Options > Programs outside the card can make the choice for you every time.

A .bas listing is the easiest way to write programs in your favourite text editor: a text file with numbered lines, keywords spelt out (PRINT, GO TO), in capitals or not. It loads on the real machine too, from the card (Listings in text). Type RUN once it is loaded.

Snapshots#

A snapshot (.zxvs) stores the complete state of the machine: memory, the screen, the sound chips, the clock, the language and the current folder. Loading it continues exactly from that moment, as if the machine had never stopped. It is a quick way to save a game in the middle, or to go back to a known point while you experiment:

• Alt+I saves a snapshot: it asks for a file name, suggesting the last one. Alt+U goes back to the last snapshot saved or loaded.
• File > Load a snapshot..., Open, or dragging the file onto the window load any snapshot.

A snapshot does not contain the SD card: when you load one, the card is the one in use now, and files the program had open are closed (as with Ctrl+Alt+Del). The emulator's settings are not saved in it either.

Screenshots and sound#

• Alt+S (File > Save screenshot) saves the screen as you see it, with the border from View > Border, as zxv-DATE-TIME.png in Pictures/ZX-V.
• File > Record sound... records everything the machine plays to a WAV file (48 kHz, stereo, 16 bits) until you stop it.

There is no video recording; to capture video, use a screen recorder on your PC.

Speed#

The emulator runs the machine at its real speed: 60 frames per second, with a 144 MHz processor. Options > Unlimited CPU speed lets the processor run as fast as your PC can (up to twenty times more work per frame), while the screen and the sound stay at their normal 60 frames per second. Programs that synchronise with the screen (most games) look the same; long BASIC calculations finish much sooner.

The emulator counts one instruction per clock cycle, so a native program that just fits in a frame in the emulator may be a little slower on the real hardware. See the SDK guide for measuring.

Language#

Options > Language chooses English or Spanish (or Automatic, your system's language, or English if it is neither). It changes:

• the emulator's menus and windows, the next time you open zxv;
• the machine's language (BASIC's messages and editor), when you reset it (Alt+R).

A program can also change the machine's language with LANGUAGE "en" or LANGUAGE "es"; zxv remembers that choice, just as the real machine does.

New translations of the menus can be added without recompiling: a zxv_XX.qm file in a folder called idiomas next to the program.

The simple window (zxv-sdl)#

zxv-sdl shows the machine in a window without menus. You type and use the mouse as in zxv, and you control the emulator with these keys:

zxv-sdl has no SD card unless you give it one with --sd FOLDER or --sd-image FILE. If you open a program from outside, its folder becomes the card. You can drop files on the window, as in zxv. By default its machine and messages use your system's language.

Command-line options#

zxv, zxv-sdl and zxv-cli accept the same options (and zxv-cli --help lists them all). These are the ones you are most likely to use:

The rest (--rom, --elf, --load, --gdb, --basic-debug, --debug, --profile, --panel, --test, --fail-on-warning) are for programmers: zxv-cli --help explains them, and the SDK guide tells how to debug.

zxv-cli: the machine without a window#

zxv-cli has no window, no sound output and no keyboard: it runs as fast as it can, typing what you tell it to, and saves what you ask for. It is useful for scripts, automatic tests and making screenshots for documentation. Like zxv-sdl, it has no SD card unless you give it one, and its machine is in English unless you use --lang.

Run a BASIC listing and take a screenshot after six seconds. --paste types the file after anything given with --type, so make RUN the last line of program.bas:

zxv-cli --paste program.bas --frames 360 --screenshot result.bmp

Load a game from the card, wait, and record ten seconds of its music:

zxv-cli --sd mycard --type 'LOAD "game"\n' --frames 600 --wav music.wav

zxv-check: checking listings#

zxv-check checks a BASIC listing (.bas) without the machine: it reads each line as LOAD does (the same tokenizer and the same syntax check as the editor when you press Enter) and tells which ones have errors, without stopping at the first one. It also warns about repeated line numbers. It comes with the emulator; the ZX-V extension for VS Code uses the same to mark errors as you type.

zxv-check game.bas

game.bas:12:7: error: C Nonsense in BASIC
game.bas:30:1: warning: repeated line number: LOAD keeps the last one

Each problem gives the file line and the column (in characters), like compilers do, so editors understand it. --lang en or --lang es picks the language of the reports (otherwise, the system's), and --json gives it as JSON. It exits with 0 if there are no errors and with 1 if there are.

It only looks at the syntax of each line: the errors that come up when the program runs (a variable that does not exist, a NEXT without FOR...) come from RUN.

zxv-check --keywords gives the BASIC's keywords as JSON, taken from the tokenizer itself: their codes, which ones are functions and where they are recognised (at the start of a statement, anywhere, or only in SAVE, LOAD, VERIFY and MERGE). It is for editors, such as the VS Code extension; zxv-check.js gives it with check_keywords().

The web version#

The web version is the same machine running in your browser, with the same ROM, BASIC and ROM: drive. Unzip zxv-web.zip and open index.html: it works straight from the disk, or from any web server. It takes about 2 MB, with the examples and the ROM disk. The play/ folder is another page, the one for publishing a game on its own.

Click on the picture so that it receives the keyboard. Browsers do not allow any sound until you press a key or click, so the machine starts silent.

The menus are like those of zxv, and so are the Alt shortcuts (with the left Alt key):

Ctrl+Alt+Del is in the Machine menu because your operating system keeps those keys for itself.

The SD card is stored in the browser, so it is still there the next time you open the page. The first time, it contains the examples. File > The SD card... shows it: you can browse folders, upload files from your PC, download files to your PC, create folders, delete files and open them. Files you drag onto the page are copied to the card (to the folder shown in the card window) and the first one is opened. What programs save is written to the browser's storage every three seconds and when you leave the page.

The card lives in that browser only: another browser, or another computer, has its own card. If you clear the site's data in your browser, the card is erased. Download the files you want to keep.

Snapshots: Alt+I keeps a snapshot inside the page and Alt+U goes back to it; File > Download the snapshot saves it as a .zxvs file, which you can open later in the web version or in zxv.

Options (View > Options...): the language (of the page and of the machine; by default, your browser's), the border and the scaling (the same as in zxv: the picture takes all the room of the page, keeping the aspect ratio, in whole multiples or filling it), strict mode, unlimited CPU speed and hiding the pointer over the picture. The machine's language changes when you reset it. The border and the scaling are remembered, and Save the image (Alt+S) saves what you see, with that border.

What it does not have: card images (.img), the GDB server and the debugger windows. The debug panel (Alt+D) is there.

Putting it on your website#

The contents of zxv-web.zip can be uploaded as they are to any web server, or to sites like itch.io: create a project of type HTML, upload the zip and mark it as This file will be played in the browser. The page adapts to the size it is given (960 × 720, for example), and View > Full screen works if you enable itch.io's full-screen button. To publish a game of yours, a page of its own is better, one that starts it without going through the BASIC: Publishing your game on the web.

On sites like itch.io the page runs inside a frame from another domain, and some browsers (Safari, and possibly Firefox) do not let such frames store anything. Then the card only lasts while the page is open, and the page tells you so. View > Open in a separate tab opens the emulator on its own, where the card is stored normally. Downloads from inside a frame depend on what the site allows.

Debugging#

The emulator is also a complete development environment for native programs:

• in zxv, the debugger window (Alt+D): disassembly, breakpoints, watches, registers, memory, stack, the video and sound chips, and the symbols of your program;
• in zxv-sdl and the web version, a debug panel drawn over the picture;
• in zxv-cli, a console debugger (--debug);
• a GDB server (--gdb PORT, or Debug > GDB server... in zxv) to debug C programs with GDB, line by line;
• the BASIC debugger of the ROM (--basic-debug PORT in zxv-sdl and zxv-cli): the VS Code extension uses it to debug a ROM BASIC listing, with breakpoints, steps by statement, variables and the call stack;
• strict mode, which warns about anything that would fail on the real machine.

All of this is explained in the SDK guide, except the BASIC debugger, which you use from the VS Code extension.