Compiling BASIC with ZX Basic
ZX Basic is a BASIC compiler for the ZX
Spectrum, by José Rodríguez (Boriel), widely used to make games. There is a
version with a ZX-V target that turns a BASIC program into a native program
(.zxv), like the C ones of the SDK: you load it with
LOAD "name" and it runs about 90 times faster than the same program in the
machine's BASIC.
It is not an official version of ZX Basic: it lives in a fork, cronomantic/zxbasic, based on version 1.19.0.
Which BASIC it is
ZX Basic is not ZX-V's BASIC. It is the Spectrum's BASIC with additions
from modern BASICs: types (UByte, Integer, Long, Float, String...),
SUB and FUNCTION with local variables, DO ... LOOP, #include, and no
line numbers needed. A Spectrum program usually compiles as it is: PRINT AT,
INK, PLOT, DRAW, CIRCLE, BEEP, INKEY$, PEEK and POKE work as
there, also with the addresses of the screen (16384) and of the system
variables.
What is only in ZX-V (the modes, the two pages, sprites, shapes, the joystick
and the AY chips) is in the zxv.bas library, with the same names as in ZX-V's
BASIC:
#include <zxv.bas>
GRABSTR 0, 4, "1111122112211111"
FOR x = 0 TO 240 STEP 16
SPRITE 0, x, 80
NEXT x
BOX 4, 100, 20, 20, 20
| Commands | |
|---|---|
MODE, PAGE, SCREEN, SCROLL, REMAP, WAIT |
The modes, the page shown and the one drawn on (double buffering), scrolling, colour changes and a steady 60 frames per second |
PALETTE, PALETTERESET |
The palette: any colour (red, green and blue from 0 to 255) for each of the 16, and the standard ones again |
GRAB, GRABSTR, SPRITE, HIT |
Sprites, mirrored, recoloured or scaled, and pixel-exact collisions |
BOX, DISC, POLY, CLIP, PIXEL |
Filled shapes, clipping and the colour of a pixel |
KEY, JOY, SOUND, TIME |
Keys held down, joysticks, the AY registers and the frame counter |
MUSICLOAD, MUSICPLAY, MUSICSTOP, MUSICPAUSE, MUSICCONTINUE, MUSIC |
Music from a tracker (a .zxm or a .pt3 from zxv-tracker...), in the background while the program goes on |
SFXLOAD, SFX, SFXSTOP, SFXPLAYING |
Sound effects from an AYFX bank |
SAMPLELOAD, SAMPLE, SAMPLESTOP, SAMPLEPLAYING |
Recorded sounds (WAV) on the sample channels |
Where it differs from ZX-V's BASIC: the sprite of a string is GRABSTR
(GRAB n, width, a$ in ZX-V's); KEY, JOY, HIT and PIXEL take
parentheses (KEY(9)); REMAP and SOUND take one pair at a time and
PALETTE one colour, only in table 0 (no #t); REMAP and PALETTE alone
are REMAPRESET and PALETTERESET; POLY takes up to 8 points; and music and effects are loaded with MUSICLOAD f$ and
SFXLOAD f$ (LOAD f$ MUSIC and SFX in ZX-V's), played with MUSICPLAY,
MUSICSTOP... and the function that says whether an effect plays is
SFXPLAYING; recorded sounds, with SAMPLELOAD f$, n (LOAD f$ SAMPLE n),
SAMPLE n, tone, vol, pan, c (; c in ZX-V's) and SAMPLEPLAYING (the
function SAMPLE). MUSICLOAD plays .zxm, PT3, TurboSound, PT2, STC, ASC,
PSG and AY VGM (also .vgz), but not MOD, S3M or XM, which ZX-V's BASIC
converts while loading: so as not to carry the converter in every program,
they are turned into a .zxm first with zxv-music.
SAVE, LOAD and VERIFY use the SD card as ZX-V's BASIC does: without an
extension, the screen goes in a .gfx (the ZX-V one, with its colours if they
are not the standard ones) and CODE and DATA in a .bin, just the bytes; with the extension .tap, in a Spectrum tape. Compiled with
--enable-break, Esc stops the program and errors say the line. The rest, and
the libraries there are, is in its
target documentation.
Installing it
On Windows: download zxbasic-1.19.0-zxv.6-win64.zip from the
release page
and unzip it anywhere. It has zxbc.exe, which does not need Python.
On Linux and macOS: download the source code from that same page (or
clone the fork's zxv branch). You need Python 3.14; the compiler is
zxbc.py.
Also, on all of them: the RISC-V C compiler, the same one the SDK uses. How to install it is in the SDK guide.
Your first program
Save this as hello.bas:
DIM x AS FLOAT
PAPER 1: INK 7: CLS
PRINT AT 10, 6; "Hello from ZX Basic"
FOR x = 0 TO 255
PLOT x, 40 + 30 * SIN(x / 20)
NEXT x
Compile it:
zxbc --arch=zxv hello.bas
(zxbc.exe on Windows, python3 zxbc.py with the source code.) That gives
hello.zxv: copy it to the SD card (in the emulator, to the folder that acts
as the card) and load it with LOAD "hello". When it ends, its report (0 OK
or the error) stays at the bottom until you press a key, as on the Spectrum.
With --loading-screen title.png (or a .gfx with a screen), the .zxv
carries a loading screen, as elf2zxv.py --screen does. The machine shows it
while it loads the program.
With --embed song.pt3 (as many as needed: music, effects, .gfx, data), the
.zxv carries those files inside, as the C games do. LOAD, MUSICLOAD and
SFXLOAD use the file in the current folder if there is one and, if not, the
one inside: the program works alone, also from ROM:, and a file on the card
with the same name takes the place of the one inside.
Mind the types. Without DIM, a variable takes the smallest type that fits
it: here, without the first line, x would be a UByte (0 to 255). And
between integers, / divides as integers: x / 20 would give 0, 0, 0... 1, 1,
1, and the curve would come out in steps. And the FOR would never end,
because a UByte never gets past 255. Declare as FLOAT whatever needs
decimals, and with a bigger type the counters that reach the limit.
Two examples
Stardust is a small game made
with zxv.bas: double buffering, sprites from strings, collisions, keyboard
or joystick and sound, at 60 frames per second.
Petit Soccer is a big one:
seven-a-side football against the machine or between two players, with a
pitch bigger than the screen and scroll, sprites from a PNG sheet, and music
and effects from a tracker. It carries its music and effects inside
(zxbc --embed), so it also runs from the ROM: drive, where it comes built in:
LOAD "ROM:petitsoccer".
The licence of your programs
The compiler is AGPL 3, but what goes inside your programs (ZX Basic's runtime and libraries, and the parts of the ZX-V SDK) is MIT: your programs can have any licence you like, closed ones too.