bB Tutorial, Session 3

[SeaGtGruff]

batari BASIC for Beginners -- Session 3: Getting Set Up

-------------------------------------------------------

 

It's a good idea to keep things organized on your computer, to help you find things more easily. For this tutorial, we'll create a directory where we'll put most of the programs we'll be installing. You don't have to use the same organization and directory names that I do, but I advise you to use some kind of organization that makes sense to you.

 

The following instructions assume that you want to organize things the same way that I'm going to, and that you're using Windows. If you want to organize things differently, or if you aren't using Windows, then you'll need to adjust the following instructions as appropriate.

 

On your computer, go to the root directory of your C: drive and create an "Atari2600" directory (i.e., "C:\Atari2600"). Inside it, create the following subdirectories:

 

Docs (i.e., "C:\Atari2600\Docs")

ROMs (i.e., "C:\Atari2600\ROMs")

Screenshots (i.e., "C:\Atari2600\Screenshots")

 

Installing DASM

---------------

 

The batari BASIC package already contains an MS-DOS executable of the DASM assembler, but you might want to download and install the full DASM package, since it includes some documentation that isn't in the batari BASIC package. And if you're using a non-Windows system, you'll need to download DASM to get the version that works on your system.

 

If you don't need or don't want to download the full DASM package, you can skip to the section about "Installing an Emulator."

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "DASM" subdirectory (i.e., "C:\Atari2600\DASM").

 

Go to the DASM homepage (http://www.atari2600.org/DASM/). In the "DASM Assembler Download" section, click on the link for the newest version of DASM (as I write this, the newest version is 2.20.10b; the date to the left should say "2005," not "2004"). When the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\DASM" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\DASM" directory and decompress it with whatever decompression utility you use-- WinZip, PKUNZIP, Windows' compressed folder feature, etc. You should extract the files to the "C:\Atari2600\DASM" directory, and use the option to keep the directory information, so the files will be extracted into their appropriate subdirectories.

 

Installing an Emulator

----------------------

 

You need only one Atari 2600 emulator, but you might want to install more than one, especially if you want to try out several to see which one you like best. For this tutorial, I'll be using the Stella emulator most of the time, but I'll give instructions for installing three of the more popular emulators for Windows-- Stella, z26, and PCAE.

 

If you want to install just one emulator, decide which one you want to use, and skip to that section. Or you can follow the instructions to install all three emulators. If you aren't using Windows, you'll need to use an emulator that works with your operating system.

 

Installing Stella

-----------------

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "Stella" subdirectory (i.e., "C:\Atari2600\Stella").

 

Go to the Stella homepage (http://stella.sourceforge.net/). In the left sidebar, in the "Downloads" section, click on the link for the "Stable Releases." On the next page, click on the link for the newest version of Stella (as I write this, the newest version is 2.1). For Windows, you'll want the "Binary installer (exe) for Windows 98/ME/2000/XP." You'll be taken to another page and asked to select a mirror; just click on the link for the first site, or look for the site closest to your location. When the computer asks whether you want to run or save the file, click on "Save," then browse to the "C:\Atari2600\Stella" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\Stella" directory and double-click it to start the installation. You should install the program in the "C:\Atari2600\Stella" directory.

 

Installing z26

--------------

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "z26" subdirectory (i.e., "C:\Atari2600\z26").

 

Go to the z26 homepage (http://www.whimsey.com/z26/z26.html). Click on the link to download the newest version of z26 (as I write this, the newest version is 2.13). When the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\z26" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\z26" directory and decompress it. You should extract the files to the "C:\Atari2600\z26" directory.

 

Installing PCAE

---------------

 

For our purposes, we would prefer to use an emulator that can start up playing a particular game. The most recent version of PCAE that can do this is version 2.5, so that's the version we'll use in this tutorial.

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "PCAE" subdirectory (i.e., "C:\Atari2600\PCAE").

 

The PCAE emulator has no homepage, but you can download version 2.5 from the "Zophar's Domain" website (http://www.zophar.net/a2600.html). In the "PC Atari" section, click on the link for "v2.5." When the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\PCAE" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\PCAE" directory and decompress it. You should extract the files to the "C:\Atari2600\PCAE" directory.

 

Installing batari BASIC

-----------------------

 

The batari BASIC package doesn't divide its files into subdirectories, but if we install them all in the same directory, the directory will become cluttered as we write and compile our game programs. We'll create subdirectories to help us organize things.

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "bB" subdirectory (i.e., "C:\Atari2600\bB"). Inside it, create the following subdirectories:

 

Docs (i.e., "C:\Atari2600\bB\Docs")

Includes (i.e., "C:\Atari2600\bB\Includes")

Projects (i.e., "C:\Atari2600\bB\Projects")

Source (i.e., "C:\Atari2600\bB\Source")

 

The version of batari BASIC that we'll be using (0.99b) hasn't been posted on batari BASIC's "semi-official" homepage yet, so we'll have to download it from batari's (Fred Quimby's) blog on the AtariAge website (http://www.atariage.com/forums/index.php?automodule=blog&blogid=134&). Scroll down to the "bB latest build" entry, and click on the link for the "batari_Basic_Bleeding_edge_99b.zip" file. When the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\bB" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\bB" directory and decompress it. You should extract the files to the "C:\Atari2600\bB" directory.

 

Now comes the fun part! First, move (drag and drop) the following file into the "C:\Atari2600\bB\Docs" directory:

 

license.txt

 

Next, move the following files into the "C:\Atari2600\bB\Includes" directory:

 

2600basic.asm

2600basic.h

2600basicfooter.asm

2600basicheader.asm

banksw.asm

bankswitch.inc

default.inc

div_mul16.asm

div_mul.asm

fixed_point_math.asm

macro.h

multisprite.h

multisprite.inc

multisprite_kernel.asm

pf_drawing.asm

pf_scrolling.asm

score_graphics.asm

startup.asm

std_kernel.asm

std_overscan.asm

std_routines.asm

vcs.h

 

Next, move the following files into the "C:\Atari2600\bB\Projects" directory:

 

2600baside.bat

avox.bas

mazecraze2.bas

ms.bas

RallyB.bas

 

Finally, move the following files into the "C:\Atari2600\bB\Source" directory:

 

2600bas.c

2600basic.sh

keywords.c

keywords.h

makefile

postprocess.c

preprocess.lex

statements.c

statements.h

 

This should leave you with the following files still in the main "C:\Atari2600\bB" directory:

 

2600bas.bat

2600basic.exe

batari_Basic_Bleeding_edge_99b.zip

dasm.exe

postprocess.exe

preprocess.exe

 

Before we can successfully compile a batari BASIC program using this organization, we'll need to modify the two compile batches. Right-click on the "2600bas.bat" file. In the pop-up menu, click on the "Edit" option. You should see the following lines of text:

 

preprocess <%1 | 2600basic.exe>bB.asm

postprocess>%1.asm

dasm %1.asm -f3 -o%1.bin

 

The first thing the batch file should do is change to the "Includes" subdirectory so it can find the "include" files. Then we'll have to modify the other commands so the batch file can find them, too. Edit the batch file so it looks like the following:

 

cd Includes

..\preprocess.exe < %1 | ..\2600basic.exe > bB.asm

..\postprocess.exe > %1.asm

..\dasm %1.asm -f3 -o%1.bin

 

Save the changes and close the batch file.

 

Now we need to make similar changes to the "2600baside.bat" file. Go to the "C:\Atari2600\bB\Projects" directory and right-click on the "2600baside.bat" file. In the pop-up menu, click on the "Edit" option. You should see the following lines of text:

 

@echo off

preprocess <%1 | 2600basic.exe>bB.asm

postprocess>%1.asm

dasm %1.asm -f3 -o%1.bin

 

Edit the batch file so it looks like the following:

 

@echo off

cd ..\Includes

..\preprocess.exe < %1 | ..\2600basic.exe > bB.asm

..\postprocess.exe > %1.asm

..\dasm %1.asm -f3 -o%1.bin

 

Save the changes and close the batch file.

 

Installing 2600IDE

------------------

 

We'll need to use a text editor to write batari BASIC programs, but as mentioned in Session 2, it's better to use an IDE ("integrated development environment"), which is a fancy kind of text editor that programmers use for writing, compiling, and running programs. Jacco Mintjes ("Attendo") created the 2600IDE editor just for batari BASIC, so let's install the newest version of it (0.4.1).

 

Go to the "Atari 2600 BASIC IDE" thread in the AtariAge Forums (http://www.atariage.com/forums/index.php?showtopic=72573&hl=2600ide). Scroll down to the bottom of the first entry, and click on the link for the "2600IDEV04_1.zip" file. When the computer asks whether you want to open or save the file, click on "Save," then browse to the "C:\Atari2600\bB" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\bB" directory and decompress it. You should extract the file to the "C:\Atari2600\bB" directory.

 

Once the "2600IDE.exe" file is extracted, double-click on it. This will pop up a "Locate emulator executable" window. Browse to the directory that contains the emulator you want to use (Stella, z26, or PCAE). For this tutorial, we'll primarily use the Stella emulator, so browse to the "C:\Atari2600\Stella" directory. Once there, double-click on the "stella.exe" file to select it as the emulator which 2600IDE will use. (Note that we can switch to a different emulator later if we want.) You should now see a tiny window that says "Emulator located." Click on the "OK" button to finish.

 

Now that we've installed and set up the 2600IDE editor, we can test it by compiling one of the programs that came in the batari BASIC package. Click on the "File" menu and select the "Open" option. In the "Open" window, browse to the "C:\Atari2600\bB\Projects" directory. Let's compile the "RallyB.bas" program. Double-click on the "RallyB.bas" file, and it will load into the 2600IDE editor. We won't worry about trying to understand any of the program code right now. Instead, let's just compile it.

 

Click on the "Actions" menu and select the "Compile" option. The screen will flash, and then return to the program listing.

 

To run the compiled program, click on the "Actions" menu and select the "Run a Compile" option. Browse to the "C:\Atari2600\bB\Projects" directory (if you aren't already in that directory), and double-click on the "RallyB.bas.bin" file to run it. The Stella emulator will start up and display the "RallyB" game. Use your cursor control keys to move your car around the maze of streets. After you've tested the game for a little while, click on the "close" icon in the upper right corner of the Stella window to exit the emulator.

 

Next, click on the "File" menu and select the "Exit" option to close the 2600IDE editor.

 

Installing Crimson Editor

-------------------------

 

Although the 2600IDE editor is easy to use, and has a built-in sprite editor and playfield editor, the primary editor that I'll be using in this tutorial is the free Crimson Editor. Crimson Editor is much more powerful than the 2600IDE editor, because it's been under development for a much longer period of time.

 

Go to the "C:\Atari2600" directory that you created earlier, and create a "CrimsonEditor" subdirectory (i.e., "C:\Atari2600\CrimsonEditor").

 

Go to the Crimson Editor homepage (http://www.crimsoneditor.com/). Click on the link for the newest version (as I write this, the newest version of Crimson Editor is 3.70). On the next page, click on the link for the "Crimson Editor 3.70 Release" file. When the computer asks whether you want to run or save the file, click on "Save," then browse to the "C:\Atari2600\CrimsonEditor" directory, and save it there.

 

Once the file is downloaded, go to the "C:\Atari2600\CrimsonEditor" directory and double-click it to start the installation. You should select all of the components, and install the program in the "C:\Atari2600\CrimsonEditor" directory.

 

Once the installation is finished, it will put a "Crimson Editor" shortcut on your desktop. Double-click on the shortcut to start it. You may see a scary-looking message that says the "Crimson Editor configuration file has been corrupted!" But then it says "Ignore this message if it is the first installation." (Whew!) Click on the "OK" button to continue.

 

On the left side of the Crimson Editor window is a sidebar that shows your drives and directories. If you don't see this box, then look at the menu task bar and find the binoculars. Immediately to the right of the fourth binoculars icon (which says "Find Prev" when you point to it), there is an icon of a split window with a folder on it (which says "Directory Window" when you point to it). Clicking on that icon makes the directory sidebar appear or disappear. If the directory sidebar is not visible, then click that icon to open it. Then double-click on the "Atari2600" folder to expand it, double-click on the "bB" folder to expand it, and double-click on the "Projects" folder to expand it.

 

You should now see all of the files in the "C:\Atari2600\bB\Projects" directory. Double-click on the "mazecraze2.bas" file to open it. (Of course, you could also click on the "File" menu, select the "Open..." option, and then browse to the file you want to open.)

 

You'll note that the "Text1" tab is still there. You can right-click on it and select the "Close" option to close it, since it's just a blank text file. This will leave the "mazecraze2.bas" file open. As you can see, Crimson Editor lets you open multiple files at the same time, and click on their tabs to go from one to the other.

 

In order to compile a batari BASIC program with Crimson Editor, we need to set up a menu function for us to use. Click on the "Tools" menu and select the "Conf. User Tools..." option.

 

In the new window, click on the first line in the "User Tools" box, which says "- Empty - Ctrl+1." Then click in the "Menu Text" field and type "Compile bB Program."

 

Next, click on the "..." button to the right of the "Command" field. Browse to the "C:\Atari2600\bB" directory, and double-click on the "2600bas.bat" file. This will put "C:\Atari2600\bB\2600bas.bat" in the "Command" field.

 

Next, click on the ">" button to the right of the "Argument" field. In the pop-up menu, click on the "File Path" option. This will put "$(FilePath)" in the "Argument" field.

 

Next, click on the ">" button to the right of the "Initial Dir" field. In the pop-up menu, click on the "Browse..." option. Browse to the "bB" folder and select it, then click on the "OK" button. This will put "C:\Atari2600\bB" in the "Initial Dir" field.

 

Next, check the "Capture output" option, and uncheck the "Use short filename (8.3)" option. The "Save before execute" option should also be checked. Finally, click on the "OK" button to save the setup.

 

Now let's compile the "mazecraze2.bas" program. Click on the "Tools" menu, and select the new "Compile bB Program" option. An "Output" window will appear at the bottom of the screen showing the results of the compile, which should end as follows:

 

> Terminated with exit code 0.

 

(That means "Everything was A-OK!")

 

Now that we've successfully compiled the "mazecraze2.bas" program, let's set up another menu function so we can run it. Click on the "Tools" menu and select the "Conf. User Tools..." option again.

 

In the new window, click on the "- Empty - Ctrl+2" line, just below the line that says "Compile bB Program." Then click in the "Menu Text" field and type "Run bB Program."

 

Next, click on the "..." button to the right of the "Command" field. Browse to the "C:\Atari2600\Stella" directory, and double-click on the "stella.exe" file. This will put "C:\Atari2600\Stella\stella.exe" in the "Command" field.

 

Next, click on the ">" button to the right of the "Argument" field. In the pop-up menu, click on the "File Path" option. This will put "$(FilePath)" in the "Argument" field. Click at the end of the "Argument" field so the cursor is at the end of the "$(FilePath)" entry, and add ".bin" to the end of it, so it says "$(FilePath).bin."

 

Next, click on the ">" button to the right of the "Initial Dir" field. In the pop-up menu, click on the "Browse..." option. Browse to the "Stella" folder and select it, then click on the "OK" button. This will put "C:\Atari2600\Stella" in the "Initial Dir" field.

 

Finally, click on the "OK" button to save the setup.

 

Now let's run the compiled "mazecraze2" program. Click on the "Tools" menu and select the new "Run bB Program" option. This will start up the Stella emulator with the "mazecraze2" game. Use your cursor control keys to wander around the maze. After you get totally lost, click on the "close" icon in the upper right corner of the Stella window to exit the emulator.

 

There's more we could do to set up the Crimson Editor program, such as creating language files so that Crimson Editor will color code the batari BASIC and 6502 assembly keywords, but we won't worry about that right now. We also won't worry about installing any other programs yet, such as the Distella disassembler; we'll install them as we need to use them in the tutorial. For the time being, we're all set up and ready to rock and roll!

 

Michael Rideout

[atwwong]

Hi Michael,

 

Thanks for the very clear instructions. I was able to follow everything and I'm all caught up! Well done!

 

Cheers,

Tony

[SeaGtGruff]

Hi Michael,

 

Thanks for the very clear instructions. I was able to follow everything and I'm all caught up! Well done!

 

Cheers,

Tony

 

I'm glad to hear that the instructions were easy to understand and follow. I'd gotten kind of hung up on that session for some reason, but now that it's out of the way, I ought to be able to get back on track during the next week. I might even be posting Session 4 later tonight.

 

One thing I'm curious about, has anyone been able to get PCAE 2.7 to run? I swear, it ran just fine on my old PC; but I can't get it to run at all on my new PC, and I don't know why not.

 

Michael Rideout

[atwwong]

One thing I'm curious about, has anyone been able to get PCAE 2.7 to run? I swear, it ran just fine on my old PC; but I can't get it to run at all on my new PC, and I don't know why not.

Do you mean running on a user tool script in Crimson Editor or just plain running on Windows XP? My initial attempts to run PCAE 2.7 in your script weren't successful, but I do have that version running stand-alone on XP. My emulator of choice is still z26. I modified your Crimson Editor User Tools script by using

 

E:\Atari2600\z26\Z26.EXE

as the Command and

 

$(FilePath).bin -p8 -M1 -n

as the Argument and

 

E:\Atari2600\z26

as the Initial Dir. (my C drive is cluttered with other stuff).

Edited April 1, 2006 by atwwong

[SeaGtGruff]

One thing I'm curious about, has anyone been able to get PCAE 2.7 to run? I swear, it ran just fine on my old PC; but I can't get it to run at all on my new PC, and I don't know why not.

Do you mean running on a user tool script in Crimson Editor or just plain running on Windows XP? My initial attempts to run PCAE 2.7 in your script weren't successful, but I do have that version running stand-alone on XP. My emulator of choice is still z26. I modified your Crimson Editor User Tools script by using

 

E:\Atari2600\z26\Z26.EXE

as the Command and

 

$(FilePath).bin -p8 -M1 -n

as the Argument and

 

E:\Atari2600\z26

as the Initial Dir. (my C drive is cluttered with other stuff).

 

I meant as a standalone program. PCAE 2.7 ran fine on my other computer, but I can't even get it to start up at all on my new computer. I don't know if it's something to do with the CPU (dual-core), or my version of DirectX (9), or what. But since PCAE 2.5 seems to be the last version which supported passing a game to run as part of the command line, and is also the most recent version that I'm able to get to run on my new PC, I opted for using PCAE 2.5 in the tutorial.

 

Just for the record, this is what I get whenever I try to start up PCAE 2.6 or PCAE 2.7 on my new computer:

 

 

With 2.7, if I click "click here," it gives me this message, which seems to indicate that kernel32.dll is the problem:

 

 

But with 2.6, I get this message instead, which doesn't say kernel32.dll:

 

 

Michael Rideout

[atwwong]

One thing I'm curious about, has anyone been able to get PCAE 2.7 to run? I swear, it ran just fine on my old PC; but I can't get it to run at all on my new PC, and I don't know why not.

...

 

I meant as a standalone program. PCAE 2.7 ran fine on my other computer, but I can't even get it to start up at all on my new computer. I don't know if it's something to do with the CPU (dual-core), or my version of DirectX (9), or what. But since PCAE 2.5 seems to be the last version which supported passing a game to run as part of the command line, and is also the most recent version that I'm able to get to run on my new PC, I opted for using PCAE 2.5 in the tutorial.

 

Just for the record, this is what I get whenever I try to start up PCAE 2.6 or PCAE 2.7 on my new computer:

 

 

With 2.7, if I click "click here," it gives me this message, which seems to indicate that kernel32.dll is the problem:

 

 

But with 2.6, I get this message instead, which doesn't say kernel32.dll:

 

 

Michael Rideout

I'm using DirectX 9c, so that shouldn't be the problem. If you have all the Windows XP Service Packs and updates, then maybe it is the processor, since both PCAE 2.6 and PCAE 2.7 don't work.

 

I've read previous posts that users haven't been able to run PCAE 2.6+ on their systems. I just checked my wife's newer P4 system - her computer has hyperthreading and mine doesn't, and PCAE 2.6+ does NOT work on her system. My system is an older P4 1.7 GHz machine. My conclusion is that PCAE 2.6+ does not work on newer P4 processors.

[Thomas Jentzsch]

Switch to z26 oder Stella instead. They are the far better emulators now anyway.

[SeaGtGruff]

My conclusion is that PCAE 2.6+ does not work on newer P4 processors.

That's what I was thinking, too. I work for a software company, and most of our programs are written in AcuCobol. We used to compile them with a "native code" switch for Intel processors, which helps them run faster. But one of our clients got a new computer with a dual-core processor, and our programs wouldn't run on his workstation anymore, so we had to recompile every single program in our system without using the "native code" option. But then again, we bought a new workstation with a dual-core processor for our office, and it runs our system just fine using the "native code" option!

 

Michael Rideout

[Piggles]

Thank you Mike! I'm so excited! I dabbled a bit in .35 and managed to the some of the basics down. I'm ready to get my hands dirty!

[MausBoy]

These tutorials are great and I can't wait for session 4.

[gambler172]

Hi Michael

hope to see session 4 soon.

Great work.

greetings Gambler172

[gambler172]

Hi Michael

i would like to see session 4,because i want to try programming with Batari Basic.

greetings Walter

[SeaGtGruff]

i would like to see session 4

You'll have to wait a while for Session 4, because I've decided to skip sessions 4 through 9 for the time being, since (when I eventually write/post them) they're going to contain more or less preliminary information, as follows:

 

Session 4 -- The TV Picture

Session 5 -- The Atari 2600

Session 6 -- The batari BASIC Language

Session 7 -- The 6502 Assembly Language

Session 8 -- A Crash Course in Programming

Session 9 -- Designing a Game

 

Instead, I'm jumping straight to Session 10, "The Background, Colors, Kernels, and Blanking," which talks about the background and what it's good for, the three color palettes (NTSC, PAL, and SECAM), using hexadecimal notation to express color values, what kernels are and how to write one, and what blanking is and how to use it. I started writing it a couple of nights ago, and am maybe one-fourth finished, so I expect to post it this weekend. This will be the first session to include illustrations, as well as the first one to include homework! We'll also start working on a couple of simple games.

 

MR

[gambler172]

i would like to see session 4

You'll have to wait a while for Session 4, because I've decided to skip sessions 4 through 9 for the time being, since (when I eventually write/post them) they're going to contain more or less preliminary information, as follows:

 

Session 4 -- The TV Picture

Session 5 -- The Atari 2600

Session 6 -- The batari BASIC Language

Session 7 -- The 6502 Assembly Language

Session 8 -- A Crash Course in Programming

Session 9 -- Designing a Game

 

Instead, I'm jumping straight to Session 10, "The Background, Colors, Kernels, and Blanking," which talks about the background and what it's good for, the three color palettes (NTSC, PAL, and SECAM), using hexadecimal notation to express color values, what kernels are and how to write one, and what blanking is and how to use it. I started writing it a couple of nights ago, and am maybe one-fourth finished, so I expect to post it this weekend. This will be the first session to include illustrations, as well as the first one to include homework! We'll also start working on a couple of simple games.

 

MR

Hi Michael

cannot wait to see the next sessions.I am a totally newbie and i only want to try to make a small game.I would be happy,if i could do a simple shooter.

greetings Walter

[CPFace]

Writing a kernel, eh? Wahoo! That's the exact piece of the puzzle that I'm interested in. I would really appreciate some advice for that.

[atwwong]

I'm glad to see that the tutorials will continue!

[diogoandrei]

These tutorials are awesome. Thanks a lot for this, Michael! Looking forward for more...

 

Cheers