CVBasic: A BASIC compiler for Colecovision

CVBasic is a cross-compiler of BASIC language running on a PC computer, and generates Z80 assembler code that should be processed by an assembler (Gasm80) to generate the game that can be run on an emulator or a real Colecovision console.
The latest version now allows to generate games for Sega SG-1000, MSX, Spectravideo SVI-318/328, Sord M5, Memotech MTX, Vtech Creativision, Dick Smith's Wizzard, Casio PV-2000, Hanimex/Soundic Pencil II, Tatung Einstein, and Texas Instruments TI-99/4A.
If you already know everything about the Colecovision and you don't need to know the CVBasic development history then you can scroll down to the CVBasic usage and the Downloads sections.

The Colecovision console

The Colecovision console was released in 1982 in the USA by Coleco Industries, Inc. It had a great success because of the pack-in game Donkey Kong, the first time an arcade game looked like an arcade game in your home!
It went to sell more than 6 million of consoles until the 1984 crash of videogames.
The Colecovision is based on off-the-shelf components, this is common components that could be bought directly from manufacturers or even large electronic stores. We see the common Z80 processor being used, along two 2114 static RAM, and the TMS9928 video processor accompanied by eight 4116 dynamic RAM chips.
The components availability make easier doing repairs, and because of it I could make a Colecovision on a breadboard that once helped me for testing a game when my two Colecovision consoles died.
Colecovision with a Zombie Near cartridge inserted
Colecovision with a Zombie Near cartridge inserted

CVBasic development

In 2014, I coded IntyBASIC, a BASIC compiler for Intellivision. It had a great success and a soft learning curve. Since then I was thinking about a similar one but for Colecovision. However, I couldn't find the right approach for the Video Display Processor, until in 2024 I found my old games Viboritas and Cubos.
On Feb/27/2024 morning I took the source code of IntyBASIC, and extracted the lexer and the barebones for GOTO and GOSUB, made a tiny compiler for Z80 and announced it in X (Twitter). By the way, this is how many years ago I learned to make translations of BASIC to assembler, GOTO is a JP, and GOSUB is a CALL.
Very happy with this result I went ahead to adapt my expression parser and made a tree generator dedicated to Z80. It generated tons of PUSH/POP instructions instead of optimizing, but this way I managed to get by night a bouncing face program that could be compiled, assembled, and ran in my CoolCV emulator.
To handle the VDP, I decided to separate it in three parts: DEFINE SPRITE (for sprites), DEFINE CHAR (for characters), DEFINE COLOR (the color for characters). Besides the statement SPRITE helps to handle hardware sprites, and the screen grid 32x24 is accessed by using VPOKE/VPEEK or PRINT AT.
The only control handling instruction implemented was IF, and it was supported by GOTO and GOSUB (this is basically how microprocessors work: comparison, jump, and call instructions).
The next day, I only could work 3 hours in the night, so I adapted the control statements from IntyBASIC (FOR/NEXT, WHILE/WEND, DO/LOOP, and EXIT). With all this functional, it was clear where the compiler's conditional jumps generation could be optimized.
The last day of February (2024 is leap), I started converting Viboritas to CVBasic language in order to see what constructs I was missing, and also to detect bugs (there were plenty of these). I implemented the controller support. I had to code 16-bit multiply, divide, and modulo subroutines, along with a pseudorandom number generator. I decided also on the syntax for the SOUND statement, and went ahead to implement RESTORE/READ/DATA and added array support because it simplifies game development.
In the afternoon I went on full steam mode to write the manual, and in one hour I optimized the code generator to remove most of the PUSH/POP instructions and make CVBasic reasonably efficent. Also one single game example wasn't enough, so I added another example: Space Attack.
In the late night I published CVBasic v0.1.0.
In just 3 days, I created 2956 source code lines for the compiler (part of this derived from IntyBASIC), 600 assembler lines for the library, and 1100 lines of CVBasic code for examples. A total of 4656 lines of code.
Viboritas ported to CVBasic
Viboritas ported to CVBasic.

CVBasic usage

Following the conventions of command-line, CVBasic is a cross compiler that takes BASIC source code and translates it to Z80 assembler code. The assembler code needs to be processed by Gasm80 to generate the final binary.
This is the compilation process:
cvbasic game.bas game.asm
gasm80 game.asm -o game.rom
The final ROM file can be run using any Colecovision emulator like my own emulator CoolCV, Adamem, GearColeco, BlueMSX, or OpenMSX.
Alternatively, you can get a cartridge PCB (like this one) and program your video game to run on a real Colecovision console.
CVBasic includes support for Colecovision video and sound features in form of commands like SPRITE and SOUND, trying to be close to the hardware but so easy as possible to user.
I intend to keep updated this early version and add new features to the compiler.

Downloads

I suggest you to download the most recent version (v0.7.0) from the AtariAge forums.
CVBasic needs Windows XP as minimum, but if your version doesn't have service packs it could need the Visual C++ 2008 runtime, or 2010 runtime (for v0.2.0 onwards).
Mac and Linux binaries are included.
The user's manual is included inside the ZIP file, along gasm80, and TMSColor for converting BMP images to the video format used in the Colecovision.
I suggest strongly to register in AtariAge where you can get help on using CVBasic just by reading the Colecovision Programming forum or posting your questions.

Space Attack

The book

The success of CVBasic inspired me to write the book "Programming Games for Colecovision". It follows the learning technique that was so useful for me when I started with the BASIC language: Games published in parts, source code for typing, and detailed explanation of every game part.
The foreword is written by David R. Megarry, programmer of Zaxxon™ for Colecovision, and also creator of the Dungeon!™ board game.
One of the best parts is that the book applies to all seven platforms currently supported by CVBasic!
The book has 250 pages, and is available in paperback, hardcover, and as ebook:
Programming Games for Colecovision book

Supported targets

Colecovision console (since v0.1.0). Emulate with CoolCV, BlueMSX, or OpenMSX.
    cvbasic game.bas game.asm
    gasm80 game.asm -o game.rom
Sega SG-1000 console (since v0.2.0). Emulate with CoolCV, BlueMSX, or Meka.
    cvbasic --sg1000 game.bas game.asm
    gasm80 game.asm -o game.rom
MSX computers (since v0.4.0). Emulate with BlueMSX, Meisei, or OpenMSX.
    cvbasic --msx game.bas game.asm
    gasm80 game.asm -o game.rom

    cvbasic --msx -ram16 game.bas game.asm
    gasm80 game.asm -o game.rom
Spectravideo SVI-318/328 computers (since v0.5.1). Emulate with BlueMSX.
    cvbasic --svi game.bas game.asm
    gasm80 game.asm -o game.rom
Sord M5 computers (since v0.6.0). Emulate with Common Source Code Project, M5 emulator. You need to download the BIOS separately.
    cvbasic --sord game.bas game.asm
    gasm80 game.asm -o game.rom
Memotech MTX computers (since v0.6.0). Emulate with Memu.
    cvbasic --memotech game.bas game.asm
    gasm80 game.asm -o game.run

    cvbasic --memotech -cpm game.bas game.asm
    gasm80 game.asm -o game.com
Vtech Creativision / Dick Smith's Wizzard (since v0.6.0). Emulate with Creativision emulator.
    cvbasic --creativision game.bas game.asm
    gasm80 game.asm -o game.rom
Casio PV-2000 (since v0.7.0). Emulate with MAME.
    cvbasic --pv2000 game.bas game.asm
    gasm80 game.asm -o game.rom
Hanimex/Soundic Pencil II (since v0.7.0). Emulate replacing BIOS in BlueMSX (Colecovision emulation).
    cvbasic --pencil game.bas game.asm
    gasm80 game.asm -o game.rom
Tatung Einstein (since v0.7.0). Emulate using MAME.
    cvbasic --einstein game.bas game.asm
    gasm80 game.asm -o game.com
Texas Instruments TI-99/4A (since v0.7.0). Assemble using xdt99. Emulate using classic99 or js99er.net
    cvbasic --ti994a game.bas game.a99
    xas99.py -R game.a99
    xdm99.py -X sssd game.dsk -a game.obj -f df80

Links

Last modified: Sep/07/2024