batari Basic kickstart
your first atari 2600 program in 30 minutes or double your money back!
Kirk Israel -- Version 0.9 -- Last Updated January 2008

This is meant to be a quick and dirty document about getting you to make your first Atari 2600 program using a language called "batari Basic". It is not a language guide, rather, this is a kickstart focused on getting your system setup to write and then play Atari 2600 games. There have been other guides, but few that really focus on the essential points without assuming too much or too little about what you know. It is targeted at people with a reasonable amount of Windows experience, but who may not know anything about the Atari 2600. Technically you might not need any programming experience, but if you have any -- enough to get the idea that programming is just about breaking up a complicated task into steps a dumb computer can understand -- then you should be in good shape for batari Basic.

Because of my own biases, I will keep this tutorial to the simplest downloads and primitive environment, and on Windows. There is an all-in-one IDE (Integrated Development Environment) that I may get into here, but doing it "from scratch" isn't much harder, and in some ways less complex than using more advanced tools.

In short, this tutorial is meant to be a stepping stone to let you make sense of more complete documents, like the Official Manual (ably maintained by Duane Alan "Random Terrain" Hahn), and to ask sensible questions at AtariAge batariBasic discussion forums. By the end of this tutorial, you will have made an animated sprite that you can move with the joystick, compiled it into an Atari program, and run that program on an Atari emulator.

Background
As you probably know, the Atari 2600 was the premier video game console of its generation in the early 1980s. (Only the NES, PlayStation and GameBoy have achieved similar dominance in their domains.) Its primary controller was a single joystick for each of the two players, each controller with a single button. (It also could connect up to four of these nifty rotating "paddle" controllers, allowing for Breakout/Arkanoid type games)

The system was one of the first to have different games on different cartridges. Originally it was designed to play straight arcade conversions like Outlaw and Tanks (Combat). It was also meant to be cheap, and there are some severe hardware restrictions with it. Fortunately, the engineers made a very flexible system, and as programmers got more clever and cartridges got more ROM (although the Atari only has 128 bytes of RAM (meaning it can work with 128 small integer numbers (by small, I mean no larger than 255) ) it can use almost all of that for variables, it doesn't also have to hold the program code, which can be read off the ROM - up to 4K, without using special tricks) some of the games were pretty damn impressive... those same restrictions also tended to encourage games that were fast (60 hz, same as the TV) and colorful.

More specs: without using special tricks a programmer get 2 player sprites (think the two tanks in "Combat") 2 missiles (think each player firing a bullet in "Combat"), 1 ball (like a missile), and a low resolution playfield. Because RAM was so expensive, the Atari doesn't map memory to the screen. Instead, each television scanline, the programmer had to get all the sprite and background information loaded into memory, so that everything was where it needed to be as the TV's electron beam swept past... essentially, making a 2D screen involved carefully programming a pile of 1D lines!

For many years, the only remotely serious option to program an Atari was to learn Assembly language -- just a few steps removed from hacking 1s and 0s directly. (If you wish to begin to learn this worthy craft of Assembly language on the Atari, one of the purer forms of programming available, I'd suggest starting with my previous tutorial, 2600 101.) There was (and is) a small homebrewing scene, originally focused on the "Stella" mailing list, now largely moved to the excellent AtariAge game programming forums. (Incidentally, AtariAge is a great site. They helped me get my own original Atari effort, "JoustPong"/"FlapPing", onto physical cartridges and sold to interested collectors.)

Enter Batari
In the mid-2000s, Fred "batari" Quimby decided there should be a better way for the masses to live their 2600 dreams, and he decided to make it. The result is batari Basic. Prior to this, homebrewers would code an assembly language program, compile it into a binary using the program DASM, and then run that binary in an emulator. (There are also ways to run programs on real 2600s, even without "burning" them onto a cartridge, but that's beyond the scope of this tutorial.) Batari Basic is a precompiler, meaning it takes the programmer's Basic code (Basic being a much easier language to program in than Assembly, at least for most mortals), translates it into Assembly language (actually, inspecting the assembly language it produces is a good way of learning how to program in assembly), and then goes through the same DASM->binary process.

Batari Basic also does all of the dirty work of the "kernel" -- the kernel is that bit of code that juggles all those 1D strips into a 2D screen. It actually provides several different kernels - some that emulate "screen mapped memory" so you can draw big fat pixels directly on the screen, others that let you reuse the Atari's sprites so you can have more than just the 2 characters on screen (with some restrictions), etc. It also provides cool (err, for extremely geeky values of "cool") stuff like fixed point fractional math, so you're not stuck with integers, and other things that make Atari programming possible for mere mortals.

(Because it uses one-size-fits-most kernels, few batari Basic games will be visual tour-de-forces... even by Atari standards. Still, there's a lot of gameplay to be had, and it can also act as a stepping stone or "glue language" for more ambitious programming feats.)

In short, batari wanted to make programming the Atari 2600 like programming on home computers back in the day, and he in many ways succeeded.

Underway
To start Atari 2600 development, you need a few things: That's it, really!

The Emulator
(If you already know how to run an Atari .bin file (aka "an Atari ROM") on your computer you can skip this part.)

There are a number of good emulators out there -- I think I'd suggest Stella, which seems to be the current de facto standard (Z26 has been known for its accuracy of emulation, and PCAEWin had features for recording videos.) On the left side of the Stella page, click "Stable Releases", then the link for "Binary installer (exe) for Windows 95/98/ME/2000/XP/Vista". The install is straight forward from there.

I like testing things to make sure they work, and I like video games. So at this point, you might wish to browse through AtariAge's great collection of Atari 2600 Games. Not every game has a ROM there (there are other, less active-copyright-holder respecting sites for those) but you should be able to download (and unzip... like I said, this tutorial isn't for complete computer virgins) a fun game or two.

Unzip the file so you are looking at the ".bin". (For better or worse, that is the standard file extension for games ready to run Atari 2600 games.) You could start Stella, navigate to where you saved the .bin, and play it, but I would strongly recommend associating .bin files with Stella so you can double click on them and start playing immediately. To do this, right click on the file, hit "Open With", "Choose Program", hit "Browse" to indicate where you installed Stella (C:\Program Files\Stella ?), double click Stella, make sure "Always use the selected program to open this kind of file" is selected, and hit OK. (This was on XP... different versions of Windows may differ slightly.) By default, the arrow keys are mapped to the first player, and ctrl is fire. F1 is "Game Select" and F2 is "Game Reset" -- some games use those physical switches on the console to control the actual starting of a game.

batari BASIC
The best place to download batari Basic is bataribasic.com. On the left side should be a link to the download page, and the link is probably the first one listed: "version 1.0 for Windows/DOS" in this case.

This is a zip file you should unzip in a directory. For better or probably worse, things will be much easier if you unzip it to a path that has no spaces in the name. Yes, it's corny, but that's the way it is with some of these tools.

For now I'll unzip it to C:\Atari2600\bB\ (which is the default suggested by the README) but you're free to put it somewhere else ... just make the appropriate changes below (and if you don't think you'll be able to tell what the appropriate changes are, well, keep it in C:\Atari2600\bB\ )

You should get used to using the bad old "DOS command line". To get to it, from the "Run" menu type "cmd". Some people are frightened of this thing, but I swear to you it's pretty simple. (For the people who don't find it comfortable, you can start using the Visual batariBasic IDE, but I'm going to pretend you want to try it using the command line at least once.)

So the "README.txt" in your batari Basic directory lists a few steps to do:

Your First Program
OK, time to make your first completely (well, not completely) original bB program!

We're going to use an Atari sprite graphics editor PlayerPal (Atari sprites are often called "players", and together with the "missile" are "P/M Graphics".)

(I admit I wrote this editor, and am not above pimping it a bit.)

So to the left you see a big canvas, and then the possible multiple frames of animation to the right. (FWIW, there's nothing especially easy about doing multiple frames of animation on the Atari, nothing built-in, but it's not particularly hard, and I figured it was something people would want to see. You can change what frame you're editing by hitting the radio button underneath, or just clicking on the mini-canvas. You can also open up the "image edit controls" to copy from one frame to another and some other tricks.

So you might notice a few odd things... for one things, Atari pixels aren't quite square, and the editor tries to show that. The other strangeness is if you start to make multicolored sprites... one thing that gives Atari sprites their distinct look is that-- barring some serious trickery-- they have at most one color per 'scanline", i.e. horizontal row. To change the color in the editor, click on the pluses to the side of the main canvas. (By default, you change the colors used in all the frames - you can elect not to by unchecking the checkbox at the bottom of the color picker ).

So, make a few frames of a walking animation. (Or don't, be boring and have a static image) Use a few colors (or, you know, don't). Open the "generate code" panel and click "generate batariBasic code". Select and copy all the text (just click in the textarea and hit ctrl-A, ctrl-C.

Open notepad (or the editor of your choice) and paste in the text. Then save it... I made a new directory c:\atari2600\work\ and saved it as first.bas. Then I went to the commandline, typed
cd \atari2600\work
2600bas first.bas
Now I navigate to that folder and double click first.bas.bin, or just type first.bas.bin in the command line.

BAM -- AN ORIGINAL ATARI PROGRAM THAT HAS PROBABLY NEVER EXISTED IN THE WHOLE HISTORY OF THE UNIVERSE! You are great! You can move your walking guy around, and he (or she) even faces the other way when you go left.

code monkey
This guide isn't meant to be a serious language tutorial, but lets take a look at the code that was produced. Here is the one I made, a goof little two step animation. I'll show you the code, then we'll dissect it a bit.
  rem CODE INSPIRED BY Atarius Maximus at http://www.atariage.com/forums/index.php?showtopic=109288
   set kernel_options player1colors playercolors pfcolors
  player0x = 50
  player0y = 50
main
  f=f+1
  rem POSSIBLY INEFFICIENT CODE, SEPARATE COLOR INFO FOR EACH FRAME...
  if f = 10 then player0:
        %01000110
        %01100100
        %00101000
        %10010110
        %01111000
        %00010000
        %00011000
        %00011000
end
   if f = 10 then player0color:
    $84;
    $84;
    $84;
    $B4;
    $B4;
    $B4;
    $FE;
    $FE;
end
  if f = 20 then player0:
        %00101100
        %00111000
        %01011000
        %01011000
        %00110100
        %00010000
        %00011000
        %00011000
end
   if f = 20 then player0color:
    $84;
    $84;
    $84;
    $B4;
    $B4;
    $B4;
    $FE;
    $FE;
end

  if f=20 then f=0

  if joy0right then REFP0 = 0
  if joy0left then REFP0 = 8

  drawscreen

  if joy0right then player0x = player0x + 1
  if joy0left then player0x = player0x - 1
  if joy0up then player0y = player0y - 1
  if joy0down then player0y = player0y + 1

  goto main