batari Basic kickstart

batari Basic kickstart

your first atari 2600 program in 45 minutes or double your money back!

Kirk Israel -- Version 0.95 -- Last Updated January March 2021

This is meant to be a rough document about getting you to make your first Atari 2600 program using a language called "batari Basic". It is not a full language guide, but rather a kickstart focused on getting your system setup to write and then play Atari 2600 games and have some general idea of what's going on.

It is targeted at people with some computer experience, but who may not know much about the Atari 2600. Technically you might not need any programming experience, but if you have some -- enough to get the idea that programming is all about breaking up a complicated task into steps a dumb, dumb computer can understand -- then you should be in good shape for batari Basic.

(On the other hand, it does get complicated and arbitrary-feeling! If you are looking for even simpler ways to make things with computers, you might consider Scratch (a very friendly, block-based language) or P5 (a kit based on real Javascript) - both allow you to make and share things you can run in a web browser and share with people.)

This tutorial is meant to be a stepping stone to let you make sense of more complete documents, like the batari Basic Commands (a potentially overwhleming repository maintained by Duane Alan "Random Terrain" Hahn), and then to ask educated questions at the AtariAge batariBasic discussion forums. By the end of this tutorial, you will have made a program featuring 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

The Atari 2600 was the premier video game console of the early 1980s. 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 to manufacture, and so its hardware is rather primitive. It only has 128 bytes of working memory ("RAM") - enough to store 128 number between 0-255, which isn't very much! Luckily the game is loaded from the "read only memory" - the ROM - and so the code itself can be larger than that. (2K and 4K were very common in the day, but later games tended to have more space.)

It was a very flexible system. Engineers got very smart about using the limited resources and later cartridges were able to include extra hardware to punch things up a bit. 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 - a programmer can't just say "light up this pixel" and expect it to stay lit. Instead, each television scanline, the programmer has 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 (homebrew, the art of DIY game making, usually for hold hardware) 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, as well as make one-off cartridges on my batari Basic efforts Loaded4Bear and Sisyphus. Besides the forums there is also an AtariAge community on Facebook.

Also of note: Zeropage Homebrew streams reviews of new and upcoming Atari homebrews.

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. (These days there are other ways of getting games in progress onto a real, such as the harmony cartridge that pulls things off of SD cards inserted into the cartridge)

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 mere mortals), translates it into Assembly language, and then using a program called "DASM" to turn the Assembly language into a "binary" that an emulator or real 2600 can run.

(Actually, one original purpose of batari Basic was to let people look at the Assembly it generates to learn more about ASM.)

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 emulate "screen mapped memory" - remember which pixels you have set - so you can draw big fat pixels directly on the screen. And there are variable kernels 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 to a wider range of people.

(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 in many ways he succeeded.

Underway

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

The Emulator

With Atari Dev Studio including an emulator, you technically don't need this step! But if you might like to play some Atari games on your own computer and get a feel for using the keyboard to play Atari ROMs, read on!)

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 right version for your computer. The install is straight forward from there.

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 a fun game or two to get used to running games on your system.

batari BASIC via the Atari Dev Studio

Since I first wrote this guide, the Atari Dev Studio has appeared, bundling batari Basic, DASM, the Stella emulator, as well as a sprite editor in one super-convenient package that works on Windows, Mac, and Linux. However, here are my previous getting running on Windows instructions (I've switched to mostly Mac myself...)

Atari Dev Studio is a module for Visual Studio Code (aka "VS Code"), which is one of the most popular editors for web developers these days. I'd say follow the directions for installing VS Code + Atari Dev Studio - no need for me to invent the wheel.

Once you have ADS set up, you should see a bar like the following at the bottom of VS Code:

The main button you need is that rocketship!

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 way back when! I like it better than some other options because it generates ready-to-run sample code.)

So to the left you see a big canvas, and then the possible multiple frames of animation to the right. (Animation on the atari is simply flipping between multiple images representing frames of animation for the same character) You can change which 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 just one frame. I'm not the boss of you!) Try to make it so it's clear which way the player is facing. 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 (cmd-A,cmd-C on Mac))

(If doing it the old Windows way, skip to OLD WINDOWS INSTRUCTIONS below)

Return to VS Code, go to File|New File to create a new file, and save it with a file name ending in ".bas" or ".bb"

Hit the rocketship button at the bottom... if all goes well you will see batari Basic + DASM chew for a bit, and then Stella will automatically fire up to see your creation!

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 with the arrow keys, and he (or she) even faces the other way when you go left.

OLD WINDOWS INSTRUCTIONS: 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.

Code Student

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 goofy little two step animation. Read through the basic code, then I'll explain it part by part. 
  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
Ok, the explanation.

Batari BASIC might seem very odd if you are used to the more common computer languages. One easy-to-messup gotcha is, any line that doesn't start with a space or a tab is a "label" So all your actual code needs to be indented, or bB will be confused. We will learn more about labels below. 

  rem CODE INSPIRED BY Atarius Maximus at http://www.atariage.com/forums/index.php?showtopic=109288
"rem" is short for "remark" - it means what follows is a comment. Comments are notes to other programmers or your future self to explain just what you were up to, beause trust me, you'll forget soon enough! 
   set kernel_options player1colors playercolors pfcolors
So, we're jumping right in with a fairly deep cut! As you can see on the batari Basic reference, kernel options enable a few bells and whistles, but usually at the cost of some other features. In this case, we are saying we want both players to have multiple colors, and multiple colors for the background... I guess its overkill for this case. 
  player0x = 50
  player0y = 50
So, batari Basic uses up some of the precious RAM so it can track various things that games commonly want... in this case player0x and player0y are two special variables that give the x and y position of the first player. (Player 0 is the first player... computer geeks love to start counting so that 0 = first, 1 = second, 2 = third, etc...) So these lines are setting the player's position on screen. 
  
main
We start with a "label", "main". This means "identify this location in the code"... for example, we may use the "goto" statement to jump back to run that part of the code again. (And again and again.) 
  f=f+1
  rem POSSIBLY INEFFICIENT CODE, SEPARATE COLOR INFO FOR EACH FRAME...
batari Basic gives you all the letter (a-z) as separate variables for your own use. (You can also give them another nickname with the "dim" statement.) In this case we're just keeping "f" for "frame". Every time we go through our main program loop, we are setting f to be whatever f used to be plus 1. (Ataris run fast... 60 frames per second!) 
  
  if f = 10 then player0:
        %01000110
        %01100100
        %00101000
        %10010110
        %01111000
        %00010000
        %00011000
        %00011000
end
So here we start with an f statement, the next lines make up the graphic of the runner. (you can see what bits are set (the 1s) and also that the whole figure is upsidedown! That's an old trick to make it easier for batari Basic.) So the whole thing is we're saying "if the current frame is 10, then set the player graphic to this" 
   if f = 10 then player0color:
    $84;
    $84;
    $84;
    $B4;
    $B4;
    $B4;
    $FE;
    $FE;
end
Similarly, if the frame is 10, then we set colors. (Atari uses certain hex numbers for certain colors.) 
  
  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 the frame has gotten all the way to 20, we change the graphic and the colors used. 
  if f=20 then f=0
So if the frame IS all the way up to 20, we reset it to 0. 
    
  if joy0right then REFP0 = 0
  if joy0left then REFP0 = 8
The Atari has its own special variables... "REFP0" is "reflect player zero", in other words do we draw the player flipped or no. (Note that this logic doesn't work because REFP0 is actually reset each frame, but we only change it to what it should be if the joystick is actually pressed. Unfortunately atari programming has many little gotchas like that) 
  
  drawscreen
You always need to call "drawscreen" in your main loop. This activates the "kernel" which does the tricky work of putting all the stuff on the screen where you asked it to be. 
  
  if joy0right then player0x = player0x + 1
  if joy0left then player0x = player0x - 1
  if joy0up then player0y = player0y - 1
  if joy0down then player0y = player0y + 1
Some basic logic to read the joystick and move the player accordingly. 
  
  goto main
Finally, we just loop over and over.

Conclusion

Man that probably seems like a lot but we're barely scratching the surface! The batari Basic commands page has many details, but some people find its method of organization a bit hard to follow! Feel free to ask questions on the AtariAge forums.

Parting Thoughts

One thing I've noticed in Atari Dev Studio... if you don't properly close the Stella Emulator (with esc key) you might have trouble re-compiling and seeing your new changes. If it feels like your changes are kicking in when you hit the rocket button, switch back to Stella, press esc to quit... you may then have to switch back to VS Code and re-save in order for the ADS to notice you've made changes.

One thing you'll hear a lot about is "DPC+". This means the game is built to use a special chip (based on one built into Pitfall 2 back in the day) to let the cartridge do more - offload some processing into the cartridge itself. Some people think it's cooler to just to make old fashioned "4K Roms", to push the boundaries of what the original Atari hardware could do, but DPC+ frees up all kinds of gameplay options.

I've actually made a few other tools that let you make up graphics or music in the browser and then see it run on a real Atari- a great toy or starting point for more complicated programs. You can then copy and paste the code into a .bb or .bas file in Atari Dev Studio: