El emulador

El emulador es ZX-V hecho software. Ejecuta la misma ROM (el BASIC) que la máquina real, así que un programa que funciona en el emulador funciona en el hardware, y al revés. Viene en varias formas:

Los paquetes de Windows y Linux traen zxv, zxv-sdl, zxv-cli, sdimg, zxv-check, zxv-gfx y zxv-tracker, además de los ejemplos (la carpeta ejemplos) y la unidad ROM: (romdisk.bin). Cómo descargarlos se explica en Primeros pasos.

La aplicación de escritorio (zxv)#

zxv abre una ventana con la pantalla de la máquina, menús y una barra de estado. La imagen se escala sin deformarse al cambiar el tamaño de la ventana. Lo que eliges (tamaño, tarjeta SD, ficheros recientes, opciones) se recuerda para la próxima vez.

Los menús#

Archivo

Máquina

Ver: el tamaño de la ventana (x1 es 640 × 480, hasta x4), el borde, el escalado, la pantalla completa (Alt+Intro, sin menús) y la barra de estado. El borde es lo que rodea el área de 512 × 384 en la que se dibuja: Completo enseña lo que la máquina de verdad manda a la pantalla (640 × 480), Pequeño (576 × 432) lo recorta y Sin borde deja solo el área de dibujo. Se recuerda para la próxima vez. Escalado dice cómo llena la imagen la ventana cuando la agrandas: Mantener la proporción (lo normal: tan grande como quepa sin deformarse), Escala entera (solo a x1, x2, x3..., con todos los píxeles iguales) o Llenar la ventana, aunque la imagen se deforme. Cuando no es una escala entera, la imagen se amplía con los bordes de los píxeles suavizados, sin filas más gruesas que otras.

Opciones

Depurar: la ventana del depurador (Alt+D), cargar los símbolos de un programa, una instrucción (Alt+N), hasta el final del frame (Alt+F), el servidor GDB y los avisos del modo estricto. Ver Depuración.

Ayuda: el teclado y los atajos, esta documentación (la que trae el paquete, que se lee sin conexión, o si no la de la web) y la versión.

El teclado#

Se teclea como en cualquier PC, con tu propia distribución de teclado: lo que pone en la tecla es lo que sale. El BASIC y su editor usan directamente las teclas del PC:

Windows se queda Ctrl+Alt+Supr para sí, y algunos escritorios de Linux también: si te pasa, usa Máquina > Ctrl+Alt+Supr (vuelve al BASIC).

El editor se explica en El editor.

Como Ctrl es de la máquina, todos los atajos del emulador van con Alt. La tecla Alt sola no abre la barra de menús.

Las teclas del Spectrum. Algunos programas, sobre todo los que vienen del ZX Spectrum, leen el teclado como la rejilla de teclas del Spectrum (con IN o INKEY$). Para ellos, el teclado del PC también pulsa las teclas del Spectrum: las letras y las cifras son ellas mismas, Mayús es CAPS SHIFT, Ctrl es SYMBOL SHIFT, Retroceso es DELETE (CAPS SHIFT + 0), Esc es BREAK (CAPS SHIFT + SPACE) y las flechas son CAPS SHIFT + 5, 6, 7 y 8. Los signos siguen al carácter que da tu tecla: la que escribe " pulsa SYMBOL SHIFT + P, sea cual sea tu distribución. Normalmente no tienes que pensar en esto.

El ratón y los mandos#

El ratón no hay que capturarlo: mientras el puntero del PC está sobre la imagen, el de la máquina va al mismo sitio, y los botones y la rueda son de la máquina. Al salir de la imagen vuelve a ser el puntero de tu PC. Si un programa dibuja su propio puntero, Opciones > Ocultar el puntero del PC sobre la imagen quita el que sobra.

Los mandos funcionan en cuanto los conectas; el primero es el jugador 1 y el segundo, el jugador 2. La cruceta o el stick izquierdo son las direcciones, y los botones son:

En un mando de PlayStation son ✕, ○ y □. El teclado del PC no se convierte en un mando; la mayoría de los juegos, como Estela, admiten las dos cosas.

La tarjeta SD#

La máquina guarda tus ficheros en su tarjeta SD. En zxv se elige en Archivo > Tarjeta SD:

• La de siempre (Documentos/ZX-V): la de partida. La primera vez, zxv crea esta carpeta y copia en ella los ejemplos.
• Una carpeta...: cualquier carpeta de tu PC hace de tarjeta. Todo lo que grabe la máquina va ahí, y lo que copies ahí con el explorador de archivos está en la tarjeta. Abrir la carpeta la abre en el explorador.
• Una imagen de tarjeta...: un fichero .img con una tarjeta entera, formateada en FAT, FAT32 o exFAT. Puede ser una copia de una tarjeta de ZX-V de verdad, hecha con dd en Linux o con un programa como Win32 Disk Imager en Windows, y una imagen también se puede grabar en una tarjeta.
• Sin tarjeta: como si se hubiera sacado la tarjeta. El BASIC dice entonces U No hay tarjeta SD.

Una carpeta se comporta como una tarjeta de verdad: no se distinguen las mayúsculas de las minúsculas (JUEGO.ZVB y juego.zvb son el mismo fichero) y los programas no ven nada fuera de la carpeta. Los nombres solo pueden llevar letras sin tildes, cifras y algunos signos, hasta 63 caracteres; los ficheros con otros nombres no aparecen.

sdimg crea y llena imágenes de tarjeta desde la línea de órdenes:

sdimg new tarjeta.img 64 fat32            # una imagen nueva de 64 MB (fat, fat32 o exfat)
sdimg put tarjeta.img juego.zvb /juego.zvb   # copia un fichero a la imagen
sdimg get tarjeta.img /juego.zvb juego.zvb   # copia un fichero de la imagen
sdimg mkdir tarjeta.img /juegos           # crea una carpeta
sdimg ls tarjeta.img /                    # lista una carpeta, con las fechas

(Por ahora sdimg solo habla español.)

La unidad ROM:, con los ejemplos de serie, es el fichero romdisk.bin que está junto al emulador. Si falta, ROM: está vacía.

Abrir ficheros#

Archivo > Abrir... (Alt+O), arrastrar un fichero a la ventana o darlo en la línea de órdenes (zxv juego.zvb) hacen lo mismo:

Programas de fuera de la tarjeta. Para cargar un programa, tiene que estar en la tarjeta; si está en otro sitio, el emulador te pide que elijas:

• Copiarlo a la tarjeta, a su carpeta principal, junto con los ficheros de al lado que se llaman igual (como los gráficos .gfx de un juego).
• Usar su carpeta como tarjeta hasta que elijas otra. Lo que grabe el programa irá a esa carpeta.

Opciones > Programas de fuera de la tarjeta puede dejar hecha la elección para siempre.

Un listado .bas es la forma más cómoda de escribir programas en tu editor de textos favorito: un fichero de texto con líneas numeradas y las palabras clave escritas con letras (PRINT, GO TO), en mayúsculas o no. También se carga en la máquina de verdad, desde la tarjeta (Listados en texto). Cuando esté cargado, escribe RUN.

Instantáneas#

Una instantánea (.zxvs) guarda el estado completo de la máquina: la memoria, la pantalla, los chips de sonido, el reloj, el idioma y la carpeta actual. Al cargarla, la máquina sigue exactamente desde ese momento, como si nunca se hubiera parado. Sirve para guardar una partida a medias, o para volver a un punto conocido mientras experimentas:

• Alt+I guarda una instantánea: pide el nombre del fichero y propone el último. Alt+U vuelve a la última instantánea guardada o cargada.
• Archivo > Cargar una instantánea..., Abrir o arrastrar el fichero a la ventana cargan cualquier instantánea.

Una instantánea no guarda la tarjeta SD: al cargarla, la tarjeta es la que esté puesta, y los ficheros que tenía abiertos el programa se cierran (como con Ctrl+Alt+Supr). Tampoco guarda los ajustes del emulador.

Capturas y sonido#

• Alt+S (Archivo > Guardar la imagen) guarda la pantalla tal como se ve, con el borde de Ver > Borde, en zxv-FECHA-HORA.png dentro de Imágenes/ZX-V.
• Archivo > Grabar el sonido... graba todo lo que suena en un fichero WAV (48 kHz, estéreo, 16 bits) hasta que lo paras.

No se graba vídeo; para eso, usa un programa de grabación de pantalla en tu PC.

La velocidad#

El emulador lleva la máquina a su velocidad real: 60 imágenes por segundo, con un procesador de 144 MHz. Opciones > CPU sin límite de velocidad deja que el procesador vaya todo lo rápido que pueda tu PC (hasta veinte veces más trabajo en cada imagen), mientras la pantalla y el sonido siguen a sus 60 imágenes por segundo. Los programas que se sincronizan con la pantalla (casi todos los juegos) se ven igual; los cálculos largos en BASIC terminan mucho antes.

El emulador cuenta una instrucción por ciclo de reloj, así que un programa nativo que cabe justo en una imagen en el emulador puede ir algo más lento en el hardware. Cómo medirlo, en la guía del SDK.

El idioma#

Opciones > Idioma elige español o inglés (o Automático, el de tu sistema, o el inglés si no es ninguno de los dos). Cambia:

• los menús y las ventanas del emulador, la próxima vez que abras zxv;
• el idioma de la máquina (los mensajes y el editor del BASIC), al reiniciarla (Alt+R).

Un programa también puede cambiar el idioma de la máquina con LANGUAGE "es" o LANGUAGE "en"; zxv recuerda esa elección, como hace la máquina real.

Se pueden añadir traducciones de los menús sin recompilar: un fichero zxv_XX.qm en una carpeta llamada idiomas, junto al programa.

La ventana sencilla (zxv-sdl)#

zxv-sdl enseña la máquina en una ventana sin menús. Se teclea y se usa el ratón como en zxv, y el emulador se maneja con estas teclas:

zxv-sdl no tiene tarjeta SD salvo que le des una con --sd CARPETA o --sd-image FICHERO. Si abres un programa de fuera, su carpeta pasa a ser la tarjeta. Se pueden soltar ficheros en la ventana, como en zxv. Si no se le dice otra cosa, la máquina y los mensajes van en el idioma del sistema.

Opciones de la línea de órdenes#

zxv, zxv-sdl y zxv-cli admiten las mismas opciones (zxv-cli --help las lista todas). Estas son las que más vas a usar:

Las demás (--rom, --elf, --load, --gdb, --basic-debug, --debug, --profile, --panel, --test, --fail-on-warning) son para programadores: zxv-cli --help las explica, y la guía del SDK cuenta cómo depurar.

zxv-cli: la máquina sin ventana#

zxv-cli no tiene ventana, ni salida de sonido, ni teclado: va tan rápido como puede, teclea lo que le digas y guarda lo que le pidas. Sirve para guiones, pruebas automáticas y hacer capturas para la documentación. Como zxv-sdl, no tiene tarjeta salvo que le des una, y su máquina va en inglés salvo que uses --lang.

Ejecutar un listado BASIC y hacer una captura a los seis segundos. --paste teclea el fichero después de lo que se dé con --type, así que la última línea de programa.bas debe ser RUN:

zxv-cli --lang es --paste programa.bas --frames 360 --screenshot resultado.bmp

Cargar un juego de la tarjeta, esperar y grabar diez segundos de su música:

zxv-cli --sd mitarjeta --type 'LOAD "juego"\n' --frames 600 --wav musica.wav

zxv-check: comprobar listados#

zxv-check comprueba un listado BASIC (.bas) sin la máquina: lee cada línea como LOAD (el mismo tokenizador y la misma comprobación de la sintaxis que el editor al pulsar Intro) y dice cuáles tienen errores, sin pararse en el primero. Avisa también de los números de línea repetidos. Viene con el emulador; la extensión de ZX-V para VS Code usa lo mismo para marcar los errores mientras escribes.

zxv-check juego.bas

juego.bas:12:7: error: C Sintaxis incorrecta
juego.bas:30:1: warning: número de línea repetido: LOAD se queda con la última

Cada problema dice la línea del fichero y la columna (en caracteres), como los compiladores, para que los editores lo entiendan. --lang es o --lang en elige el idioma de los informes (si no, el del sistema), y --json lo da como JSON. Termina con 0 si no hay errores y con 1 si los hay.

Solo mira la sintaxis de cada línea: los errores que salen al ejecutar (una variable que no existe, un NEXT sin FOR...) los da RUN.

zxv-check --keywords da las palabras clave del BASIC como JSON, sacadas del propio tokenizador: sus códigos, cuáles son funciones y dónde se reconocen (al principio de una sentencia, en cualquier sitio, o solo en SAVE, LOAD, VERIFY y MERGE). Es para los editores, como la extensión de VS Code; zxv-check.js lo da con check_keywords().

La versión web#

La versión web es la misma máquina funcionando en el navegador, con la misma ROM, el mismo BASIC y la misma unidad ROM:. Descomprime zxv-web.zip y abre index.html: funciona directamente desde el disco o desde cualquier servidor web. Ocupa unos 2 MB, con los ejemplos y el disco ROM. La carpeta play/ es otra página, la de publicar un juego solo.

Haz clic en la imagen para que reciba el teclado. Los navegadores no dejan sonar nada hasta que se pulsa una tecla o se hace clic, así que la máquina arranca en silencio.

Los menús son como los de zxv, y los atajos con Alt también (con la tecla Alt de la izquierda):

Ctrl+Alt+Supr está en el menú Máquina porque el sistema operativo se queda esas teclas.

La tarjeta SD se guarda en el navegador, así que sigue ahí la próxima vez que abras la página. La primera vez trae los ejemplos. Archivo > La tarjeta SD... la enseña: puedes recorrer las carpetas, subir ficheros desde tu PC, descargar ficheros a tu PC, crear carpetas, borrar ficheros y abrirlos. Los ficheros que arrastras a la página se copian a la tarjeta (a la carpeta que se ve en la ventana de la tarjeta) y se abre el primero. Lo que graban los programas se guarda en el almacenamiento del navegador cada tres segundos y al salir de la página.

La tarjeta vive solo en ese navegador: otro navegador, u otro ordenador, tiene la suya. Si borras los datos del sitio en el navegador, la tarjeta se borra. Descarga los ficheros que quieras conservar.

Instantáneas: Alt+I guarda una instantánea dentro de la página y Alt+U vuelve a ella; Archivo > Descargar la instantánea la guarda en un fichero .zxvs, que luego puedes abrir en la versión web o en zxv.

Opciones (Ver > Opciones...): el idioma (de la página y de la máquina; si no se elige, el del navegador), el borde y el escalado (los mismos que en zxv: la imagen ocupa todo el sitio de la página, manteniendo la proporción, en múltiplos enteros o llenándolo), el modo estricto, la CPU sin límite de velocidad y ocultar el puntero sobre la imagen. El idioma de la máquina cambia al reiniciarla. El borde y el escalado se recuerdan, y Guardar la imagen (Alt+S) guarda lo que se ve, con ese borde.

Lo que no tiene: las imágenes de tarjeta (.img), el servidor GDB y las ventanas del depurador. El panel de depuración (Alt+D) sí está.

Ponerla en tu web#

El contenido de zxv-web.zip se puede subir tal cual a cualquier servidor web o a sitios como itch.io: crea un proyecto de tipo HTML, sube el zip y márcalo como This file will be played in the browser. La página se adapta al tamaño que se le dé (960 × 720, por ejemplo), y Ver > Pantalla completa funciona si activas el botón de pantalla completa de itch.io. Para publicar un juego tuyo, mejor una página solo para él, que lo empieza sin pasar por el BASIC: Publicar tu juego en la web.

En sitios como itch.io la página va dentro de un marco de otro dominio, y algunos navegadores (Safari, y puede que Firefox) no dejan guardar nada a esos marcos. Entonces la tarjeta dura lo que la página abierta, y la página lo avisa. Ver > Abrir en una pestaña aparte abre el emulador solo, donde la tarjeta se guarda normalmente. Las descargas desde dentro de un marco dependen de lo que permita el sitio.

Depuración#

El emulador es también un entorno de desarrollo completo para programas nativos:

• en zxv, la ventana del depurador (Alt+D): desensamblado, puntos de ruptura, vigilancias, registros, memoria, pila, los chips de vídeo y de sonido, y los símbolos de tu programa;
• en zxv-sdl y en la versión web, un panel de depuración dibujado sobre la imagen;
• en zxv-cli, un depurador de consola (--debug);
• un servidor GDB (--gdb PUERTO, o Depurar > Servidor GDB... en zxv) para depurar programas en C con GDB, línea a línea;
• el depurador del BASIC de la ROM (--basic-debug PUERTO en zxv-sdl y zxv-cli): la extensión de VS Code lo usa para depurar un listado del BASIC de la ROM, con puntos de ruptura, pasos por sentencia, variables y la pila;
• el modo estricto, que avisa de lo que fallaría en la máquina real.

Todo esto se explica en la guía del SDK, salvo el depurador del BASIC, que se usa desde la extensión de VS Code.