7800basic is a ton of fun to develop with compared to batariBasic because so many limitations are lifted. You can have over 1500 variables, a bitmapped display, 24 on screen sprites with no flicker or slowdown, CPU usage is much less of a concern, and you can plot text directly on-screen. I really enjoy it, and there’s a much smaller gap between what’s possible with assembly vs. 7800basic compared to batariBasic.
With that said, there haven’t really been any good tutorials posted as of yet on how to get started. I’d like to address that with a series of tutorials that start from the very beginning. Once I cover the basics, I’d like to actually go through the process of making a simple game, step by step, with as much detail as I can realistically provide. Please understand that I don't profess to be an expert at anything and there's nothing that uniquely qualifies me to make this tutorial. I just wanted to do it. Anything I type here is subject to edit at any time (after RevEng corrects me!) and I may add things to this initial post from time to time to try and improve it.
The first thing that needs to be done of course is to set up your development environment, which includes downloading, installing, and configuring all of the software that you’re going to need. I’ll be writing this guide based on my own development environment, yours may be slightly different, but the basics will be the same regardless. I use a Windows 10 PC, but you can also use a Mac or Linux PC. There are also many options when it comes to the text editors and graphics programs you use, but I personally use Visual Studio Code and Gimp, and I’ll likely be referring to those specific applications as I go through this tutorial.
Topics I'll cover in Part 1: Software | Hardware | Compiling Code | Some Common Compile Errors | Using an Emulator
Topics I'll cover in Part 2 (next time): Setting up the color palette in Gimp | Basic Image creation & editing with Gimp | Creating a playfield map file
You’re going to need some software installed to get started. Below is a summary of what you’re going to need for development:
1. A code editor [I use Visual Studio Code]
2. A graphics editor [I use Gimp]
3. The tiled map editor [optional but highly recommended]
4. An Atari 7800 Emulator [I use Mame]
5. The 7800basic distribution files
Which editor you use is really a personal preference and there are a ton of options out there. For many years I’ve simply used the notepad app that’s built in to windows. There is no IDE enviornment for 7800basic that’s similar to Visual batariBasic, and I’m not aware of anyone working on one. I personally use Microsoft’s Visual Studio Code. It’s free, it runs on Windows, OS X and Linux, it offers lots of flexibility with add on modules for other programming languages, and it does a really good job of text highlighting for basic code. I highly recommend checking it out. Here’s the links to Visual Studio Code and some other good alternatives that I’ve used either personally or at work at some point:
Visual Studio Code [Free] - It includes support for debugging, embedded Git control, syntax highlighting, intelligent code completion, snippets, and code refactoring.
UltraEdit [$99] - It contains tools for programmers, including macros, configurable syntax highlighting, code folding, file type conversions, project management, regular expressions for search-and-replace, a column-edit mode, remote editing of files via FTP, interfaces for APIs or command lines of choice, and more. Files can be browsed and edited in tabs, and it also supports Unicode and hex editing mode. Not cheap, but a great tool!
SublimeText [$70] - A proprietary cross-platform source code editor with a Python application programming interface (API). It natively supports many programming languages and markup languages, and functions can be added by users with plugins, typically community-built and maintained under free-software licenses.
Notepad++ [Free] - A lightweight, free editor that supports tabbed editing, which allows working with multiple open files in a single window. It also supports code highlighting, a vast improvement over windows notepad.
Visual Studio Code:
Unlike batariBasic, you will need a good graphics editing program and commercial editors generally do not come cheap. I posted a quick tutorial on setting up palettes with Gimp a few years ago, and I received lots of private mail on how to do the same thing in Photoshop. I unfortunately don’t use Photoshop and don’t plan on using it, as gimp serves me very well for editing and it’s free to use. Once you get the hang of it it’s really not difficult to use it for 7800 graphics creation and editing. I’ll dive a bit deeper into actually using it later and go beyond simply setting up palettes.
Tiled Map Editor
Using a tiled map editor is optional but I highly recommend it. It will make playfield creation a whole lot easier for you, especially as you start developing larger or more complex games. I will dive into how to use the open source “Tiled” app specifically. The tiled map editor generates an output file that can be called directly inside your 7800basic code. It doesn’t actually contain any graphics, it’s simply a map file that lays out the on-screen location of all the image files you’ve already created for your playfield.
There are three emulators available - Mame, ProSystem and A7800, with different strengths and weaknesses with regard to ease of use and emulation accuracy. For 7800basic development, ProSystem is not recommended. Despite its age, it remains popular because of it’s easy of use and nice GUI front-end, but it is not being actively developed and does not accurately emulate real hardware. When you want to test how your program will actually look on a real 7800 you really need to use mame or A7800. ProSystem is overly generous with the amount of time it gives to MARIA, it’s colors aren’t accurate, and it doesn’t support all of the bankswitched ROM formats, among other things.
Note that 7800basic will generate three files when you compile your code: a78, bin, and asm. The a78 file is what you use for running in an emulator, the bin is used for running on real hardware, and the asm file is the assembly language output of your 7800basic code. If you want to test on real hardware with a bin file, your choices are somewhat limited at the moment as the hardware is either no longer produced or still in development. The Cuttle Cart 2 [No longer produced], MCPDev Cart [From CPUWIZ], Harmony Concerto [In development], and the Mateos Cart.
A7800 Enhancements over mame:
· Support for emulation of Proline Joysticks, VCS Joysticks, Lightguns, Paddles, Driving Controllers, Keypads, Trak-Balls, Amiga Mice, and ST Mice.
· Maria DMA timing has been improved further, with the addition of accurate DMA hole penalties.
· Improved saturated/normalized 'factory set' default palette colors.
· A bug in the existing RIOT emulation has been fixed.
ProSystem Config: Simply download and extract to the directory of your choice and run the exe. It doesn’t require any configuration.
A7800 Config: Trebor posted detailed info about the setup, click here to review it.
Mame Config: · Extract and run the setup file to your desired location.
· Download the 7800 BIOS files to the mame ROMs subdirectory: Atari 7800 BIOS Files
· Run this command to launch a game ROM, substituting your install path and game ROM name: C:\>mame64\mame64 a7800 -cart "C:\mame64\roms\mygame.a78"
Tip: I’ve been using mame for years for 7800basic development and testing. To make it easier on myself, I typically install mame and 7800basic into the same root folder. That way, when I’m working from the command prompt, I can compile and then type in the cli command to launch the game all from the same window and the same directory.
You can completely skip the hardware section if you like, as it’s not absolutely necessary for development. You can develop under emulation and hardware is not absolutely necessary, but you will probably want to get your hands on the real deal at some point. 7800 consoles are not terribly hard to find and are generally available on eBay. While you don’t really need it, here’s the hardware you’re probably going to want:
1. A real Atari 7800
2. A Video and Audio mod for your 7800 [for a much clearer picture over RF]
3. An AtariVox [not required, but a really fun accessory!]
4. A multicart or flash cart [If you can get your hands on one]
5. An Edladdin controller or adapter [Many call the Proline joysticks the ‘Painline’ joysticks!]
6. Lots of free time!
Atari 7800 Hardware Revisions
There were three main revisions of the Atari 7800 hardware. All should be 99.9% compatible with the 2600 and 7800 library. The most notable difference is in the final revision, as the expansion port was removed.
- Atari CX7800, two joystick ports on lower front panel. Side expansion port for upgrades and add-ons. Bundled accessories included two CX24 Pro-Line joysticks, AC adapter, switchbox, RCA connecting cable, and Pole Position II cartridge.
- Atari CX7800, second revision. Slightly revised motherboard, added an additional timing circuit. Expansion port connector removed from motherboard but is still etched. Shell has indentation of where expansion port was to be.
- Atari CX7800, third revision. Same as above but with only a small blemish on the shell where the expansion port was.
All of the different mods available and how to do them is beyond the scope of this tutorial, but you’ll see many options available with a quick search of the 7800 forums. Below are a few you can take a look at. I had my 7800 modded by Joe (ElectronicSentimentalities) and he did a nice job. The difference between RF and S-Video or Composite output is dramatic, and worth it if you want to spend the money.
The AtariVox is an incredibly fun addition to the 2600 and the 7800, providing in-game voice as well as high score saving. 7800basic makes it relatively easy to add AtariVox speech to your code, but testing it is a whole different story. Unfortunately there is no way to emulate 7800 AtariVox speech on your PC with an emulator, you need the real thing to hear it. There is a workaround to hear speech from your PC outside of an Atari 7800 emulator for development purposes, but the process is admittedly a little painful. I realize I’m getting way ahead of myself by putting this information here, but below is a quick overview on how I did it.
How to test AtariVox speech code without a flash/multicart on real hardware:
If you hook up your AtariVox to your PC via a USB/Serial connection there is a way to hear speech using the Phrase-a-lator software tool, but I didn't use it for creating speech for Dungeon Stalker. You will need to connect your AtariVox to your PC with a USB to serial adapter. I have an official AtariVox USB to serial adapter I got from goldenaxe last year, I don't think AtariAge sells them, but I assume a generic USB to serial port adapter would work. If you examine the asm output file of your 7800 code once you've compiled the program, you can enter the specific numbers from the output in the .byte commands to listen to speech on your PC without a 7800. If you want to take the time to figure it out, it's the only way to listen to speech on a PC with an AtariVox. (The example below is from my AtariVox Speech Test Utility).
Here's a sample of what you'd be looking for in the asm output file for use with the Phrase-a-lator software (It's the 'watch out' speech from the sample program):
.L0270 ; speechdata speech31
.byte 31, 31 ; reset
.byte 21, 100 ; speed
.byte 22, 80 ; pitch
.byte 147,14,135,182 ; WATCH (dictionary)
.byte 21, 100 ; speed
.byte 22, 78 ; pitch
.byte 14,161,191 ; OUT (dictionary)
.byte 255 ; end of avox data
When you lauch Phrase-a-lator, go to the "SpeakJet Phrase Editor", and add in the .byte commands from the asm output file like this: "\31 \31 \21 \100 \22 \80", those are the phoneme codes.
Setting Up 7800Basic for the first time
You can download the latest version of the 7800basic distribution from 8bitdev.org here. It is distributed as a zip file, download extract the contents of the folder to the location of your preference. Once you’ve extracted it, we’ll take a look at what’s in it. There should be five subdirectories created, 7800devkit, contrib, docs, includes, and samples. Note that 7800basic is run entirely from the command line, and for the most part in this guide I’m assuming you have a basic familiarity with how to use the command line. For those that don’t, I’ll start with a very basic rundown on how to get started with the command line in Windows 10.
1. In Windows 10, right click the start button and choose “Run” (Windows 7 users would left click the start button to get to “Run”).
2. Type in CMD and click ok.
3. A Command prompt window will appear, and by default it will place you in your home directory (“C:\Users\Steve”).
4. Navigate to the folder location that unzipped your 7800basic files. In my case it’s C:\78b.
a. Type “cd \78b”. The “cd” stands for “change directory”, the single space and backslash tells it to look in the root of your C drive.
5. Once you’ve typed that, you’ll see the prompt change to your current location. Instead of seeing “C:\Users\Steve”, you’ll see “C:\78b”.
6. To change to a subdirectory inside the 78b directory, type “cd <name>”, for example to go into the samples directory we’d type “cd samples” (note the space in between). The prompt will change to “C:\78b\samples”.
7. To see a listing of the files and folders inside the directory, type “dir” (short for “directory”), and it will list the contents of the folder.
8. If you want to go back one directory (to C:\78b), you can type “cd ..”. The two dots will take you backwards one level each type you type it.
9. If you want to list all of the files of a single type, you can qualify the dir statement. For example, to see all of your basic files that end with the bas extension, type “dir *.bas”, and it will list only bas files.
10. For the next step, change directories back to the root folder, e.g. “C:\78b”.
7800 initial Installation
Once extracted, you’ll need to run the install script. Windows users should double-click and the provided install_win.bat file, or of course run it from the command line. OS X and Linux users should run the install_ux.sh script. What does the install script do? It permanently sets your bas7800dir variable and updates your environment path. If you ever change the directory you’ve extracted the files to, you will need to run the install script again. Here is the output you should see after running the batch file in windows:
The 7800basic installation batch file v1.1
Permanently setting the bas7800dir variable to:
SUCCESS: Specified value was saved.
Updating the user PATH variable so this bas7800dir directory is your primary
SUCCESS: Specified value was saved.
You should re-open any programs or command-line windows that rely on this
variable so they take on the new value.
You should re-run this batch file if you ever change the location of the
Now that it's installed, let's take a look at the subdirectories that are included in the distribution.
Documentation folder (\docs)
There is a pdf-format guide in the \docs folder, and Random Terrain has an online version of the manual as well. I’d recommend reading the manual before you get started to familiarize yourself with the commands and syntax. Do your homework.
\7800devkit & \Contrib folders
These subfolders contain 7800basic source code and a collection of assembly language tools required for auto-creating your binary files, including the dasm assembler, the crypto singing tool for 7800 images, and the 7800 header tool. You won’t need to use or access anything in these directories for creating 7800basic code.
The includes folder contains extra assembly code that is used at compile time. You can think of them as “modules”, and many of them are optional. I can dive into what some of them are used for later on, when you’re first getting started you won’t really need to worry too much about what’s in this folder.
This is a collection of code samples that are almost entirely written by RevEng, I have one demo (Smasteroids) that he includes. This is a great place to start if you like to learn from example code. In addition to the sample code, in the root of the folder is the palette files that can be used when configuring your graphics editor, more on that later. Here’s an overview of the sample files that are included with 7800basic:
· Adventurer – demonstrates sprite movement around a mapped playfield display, and sprite animation. It’s a good example of how to create a mapped playfield without using the tiled map editor, if you choose to do it that way.
· Atarivoxspeech – As you would expect, this file shows the basics on how to create speech with the atarivox, and gives you four different options of speech phrases to test. It’s an example of plotting text on the screen as well.
· Banner – This sample is based on the adventurer sample, but with the addition of a logo in the middle of the screen that would be useful for a title screen. It demonstrates using the plotbanner command.
· Boxcollision – A very basic demonstration of how collisions work in 7800 basic. Use the joystick and the fire button to move two sprites together to trigger a collision.
· Doublebuffer – This sample demonstrates 36 sprites on screen at the same time in double-buffered display. This routine and 7800basic can handle more, but Maria runs out of DMA time when too many of the sprites drift into the same zone. As it stands, this demo intentionally spreads the sprites out vertically, to help Maria. In practice, you can have 24 sprites on screen at once.
· Drivingcontrol simple program to move a happy face around with the joystick, demonstrating the use of the driving controller with 7800basic.
· Helloworld – What you’d expect, it displays “Hello, World!” on the screen. It is a good example of using 320A mode and plotting text on the screen.
· Multisprite – Demonstrates 24 moving sprites on the screen at once, which is about the limit on real hardware.
· Plotmapfile – Based on the adventurer sample, it demonstrates how to use a mapped playfield using the tiled map editor, rather than plot commands within the code.
· Pokey – Demonstrates the use of pokey sound routines in 7800basic.
· Ramcharmap – This demonstrates the use of plotting charaters into RAM for use as a playfield, The game is a platformer demo, with a “hero” that you can move around the platforms.
· Samplegfx – Contains code for standard alphabet and score digits. They are extremely useful and you’ll probably use a few of these files in any game you start working on.
· Simple – A very simple demo that lets you move a happy face around the screen.
· Smasteroids – A demo that I created. It’s a simple space shooter that resembles astrosmash. You move your spaceship back and forth across the bottom of the screen and shoot asteroids out of the sky.
· Soundtest – A demonstration of using TIA based sound effects.
· Spacephysics – A more advanced demo that demonstrates the use of gravity and thrusting, similar to the spaceship in asteroids.
· Splitmodedemo - This is a quick demo on how to split the screen with 2 modes in 7800basic. The same technique can be used to just change color on the fly. Ideally, the split should happen near the top of the screen, as this technique wastes precious on-screen CPU cycles waiting until the split happens. If you waste cycles for a split near the bottom of the screen, you may not have enough cycles for game logic.
· Trackertest – A great sound tracker demo that demonstrates how to add full songs to your 7800basic programs.
You should now have your environment set up and ready to go, so it’s time to try and compile our first program. Let’s compile RevEng’s “Hello World” sample program to get started.
To successfully compile, we need the files to be in the correct location. To keep things simple, I’m going to say “root folder” whenever I refer to the folder you’ve installed the 7800basic files and subfolders, be it “c:\7800bas\” or “/usr/dev/7800bas”, etc. By default, RevEng’s hello world sample program does not specify the location of the atascii.png graphics file that’s used to generate the “hello world” text on the screen, so it will look in the root folder for the file (in my case, “C:\78b”). To keep things organized and as a best practice, I’d recommend making a separate graphics subfolder for each project you work on in your root 7800basic folder. To compile the helloworld sample, copy the helloworld.bas file into your root folder, and create a new subfolder for the graphics file. Let’s call it “gfx_helloworld”. In my case, my root folder is “C:\78b”, and I created a new directory named “C:\78b\gfx_helloworld”. We’ll have to make a small change to the code for this to work. Open up the code in a text editor, and I’ll note in red text the one change we’ll need to make:
set basepath gfx_helloworld
rem **background color...
rem **set the height of characters and sprites...
set zoneheight 8
rem **import the characterset png...
incgraphic atascii.png 320A
rem **set color of 320A text palette 0...
rem **set the current character set...
rem **set the letters represent each graphic character...
plotchars 'Hello World!' 0 0 0
plotchars 'It`s great to be alive.' 0 0 1
plotchars '12345678901234567890123456789012' 0 0 4
After you’ve copied the files from the \samples directory and made that edit to the file, we’re ready to compile it. Open up a command prompt window, navigate to your root directory, and type in “7800bas helloworld.bas”. If all goes well, you should see the output below. If not, 7800basic has many built in error handling functions, and in many cases it will either describe the error or tell you which line number of code is causing the problem. In windows, you can also type in the exension of the file, typing "7800bas.bat helloworld.bas" will also work. Either way, You must specify a filename after 7800bas, it won't run without that. Also, don't type 7800basic (or 7800basic.exe, the same file), as that's a separate executable file that is not used for this purpose.
7800basic 0.6 Jul 12 2017 22:46:35
*** (): INFO, GFX Block #0 starts @ $E000
*** (): INFO, GFX block #0 has 1064 bytes left (133 x 8 bytes)
*** (): INFO, User-defined 'default.inc' found in the current directory
7800basic compilation complete.
User-defined macro.h found in current directory
User-defined 7800macro.h found in current directory
User-defined speakjet.inc found in current directory
User-defined 7800basicheader.asm found in current directory
User-defined 7800.asm found in current directory
User-defined last4k.asm found in current directory
User-defined std_routines.asm found in current directory
User-defined startup.asm found in current directory
User-defined zonememory.asm found in current directory
User-defined encryptionguard.asm found in current directory
User-defined 7800basicfooter.asm found in current directory
24389 bytes of ROM space left in the main area.
$1880 to $1fff used as zone memory, allowing 15 display objects per zone.
2501 bytes left in the 7800basic reserved area.
Read $8000 bytes of cartridge data.
Cartridge hash area is from $F000 to $FFFF.
Cartridge signature for 'C:\78b\78b\helloworld.bas.bin' appears to be empty.
Encrypting... 00 01 02 success!
A valid cartridge signature is:
09 57 6a 92 da 83 71 ba ca 44 11 cb bd b0 73 1c
18 0d f7 e8 3e 3d a5 4a 1a ef ca fa 01 8f b8 b5
92 e0 0b 23 81 4e 73 66 37 97 f6 3c 8d b5 25 c4
78 ed e0 5f 4d e4 ad 24 95 6b 9e 45 e0 fc b3 e1
0f 13 8f 87 fc eb 2f f3 6d de 80 5e 37 ec 30 a0
1c 6e 2e 1d 62 ff b9 55 8d fc ae ce 71 83 9a ef
d9 b7 7d 54 ba c6 7d 13 94 0c c8 78 c7 5d c8 a1
34 b7 56 4c ff 98 85 13
Wrote back 120 bytes to 'C:\78b\78b\helloworld.bas.bin'.
7800header 0.7 Jul 12 2017 22:46:45
opened parameter file a78info.cfg
Notes about the compile time output
There are a few important things to note about your compile time output as you’re working on developing your game, shown below. Note that as you add additional options and features such as bankswitching, multiple graphics blocks, DMA holes, etc., the compile time output will present additional information relating to those specific options. For starters, you’ll want to keep track of how much space you’re using in your graphics block and how much ROM space you have left. It will also inform you of the specific version of 7800basic you’re running.
Version of 7800basic you’re running: 7800basic 0.6 Jul 12 2017 22:46:35
The amount of space left in your graphics block: INFO, GFX block #0 has 1064 bytes left (133 x 8 bytes)
The amount of ROM space remaining: 24389 bytes of ROM space left in the main area.
Your compiled output files
Now that it’s compiled, you should see three new output files. As I noted earlier, the a78 file is what you’ll be using to test from within an emulator and the bin file is for use on real hardware.
Common Compile Errors
This is not an exhaustive list, but here are a few errors you might see when compiling your code, and what you can do to resolve them. In many cases the error itself will tell you specifically what the problem is. I figured I'd be revising this list and adding to it as time goes on.
The system cannot find the path specified.
It’s likely you are running the 7800bas.bat file by itself with no code specified after it. Run “7800bas mycode.bas” instead.
7800basic 0.6 Jul 12 2017 22:46:35, then it hangs
If you only see a message similar to the above that shows the version of 7800basic you’re using, you’re probably running 7800basic.exe instead of 7800bas.bat. 7800basic.exe is not intended to be run for compiling, you need to use the batch file.
*** (101): ERROR, graphics overrun in bank 1
The error message means you have too many graphics with "incraphic" in bank1. You'll need to shift some of those to another bank. Keep in mind that when you issue "drawscreen" you can only use graphics in the last bank or the same bank with the "drawscreen" command.
*** (1667): error: Label mismatch...
Unrecoverable error(s) in pass, aborting assembly!
There can be a few causes for "label mismatch". General syntax errors or duplicate labels are the common causes. An bank that’s over filled might trigger the error as well.
I generated the error above by creating an "if...then" statement and leaving off the "then", an easy syntax error to make.
If you can't figure out where the error is, the (1667) refers to the line number in the asm output file. You can open the asm file and look at line 1667 to see what exactly is causing the error.
*** (144): ERROR, alphadata character ' ' is missing from alphachars."
You defined an alphachars image file that doesn’t contain the character specified in the command. The "144" means the syntax error occurred on line 144.
*** (1698): error: Value in 'cmp #257' must be <$100
Somewhere in your code you've called an invalid number.
Unresolved symbol List Errors
--- Unresolved Symbol List ---
USED_ADJUSTVISIBLE 0000 ???? (R )
ROMAT4K 0000 ???? (R )
0.dsdfff 0000 ???? (R )
The "Unresolved Sybol List" error will give you some clues as to where to look. In this case, I created an invalid goto statment to a non existent label, "dsdfff". Look for items in the list that you recognize that you’ve created yourself – variable names, label names, etc. That’s where to look first.
Running your game in an emulator
Now that you’ve compiled your game, it’s time to run it in an emulator and take a look at it. As I mentioned in a tip earlier, I always install mame into the same directory as 7800basic on my development PC. In addition, to make things easier for myself I created a simple windows batch file so I can simply type ‘game rom.a78’ to launch the game immediately after it’s compiled, otherwise I’d have to type ‘c:\78b\mame a7800 –cart rom.a78’ each time. Here’s the windows batch file code (which I have saved as game.cmd):
if "%1"=="" goto error
c:\78b\mame64 a7800 -cart "c:\78b\%1.bas.a78"
echo Atari 7800 mame game launcher
echo You must type in a ROM name to launch
Once you’ve launched the ROM, the hello world output should look like this:
Congratulations! You’ve made your first Atari 7800 game, and you’re all set to start compiling code. J Before we dive into creating a new game, we’re going to need to get Gimp and Tiled configured and learn a bit about how to create graphics and use them. That’s where we’ll start in Part 2, stay tuned!