Atarius Maximus

Part 2:

Part 3:

Collision Detection between gunfire and Non-Player Sprites

Adding a Status bar with the Score and Lives Remaining

Collision Detection between all Sprites, Speed Change on clearing screen

Animation, Sound Effects, and Performance Troubleshooting

In this section I'll be covering setting up the color palette in Gimp, basic image creation & editing with Gimp, and creating a playfield map file.

Creating Graphics

Graphics are a little tricker with the 7800basic than with 2600 batariBasic because there are multiple modes to choose from, and you’re creating actual bitmapped graphics rather than just entering 1’s and 0’s into your code. The most common graphics mode is 160A, it allows for 3 colors per sprite and is the native mode (there are no strange restrictions). It uses the lower 160x192 resolution. I chose the high resolution 320A mode for Dungeon Stalker to get the higher 320x192 resolution, but it limits you to single color sprites.

As we get started working with image files, my tip would be to open graphic images from RevEng's samples and modify them, they are already formatted correctly and is what I did when I got started. Modifying the graphics in a regular graphic editor won't work, because they will be saved with the wrong color palette and 7800basic will complain and crash when you go to compile. I did a quick tutorial how to set up the 7800 color palette in Gimp here, however I’m going to start over in this tutorial as I may add a few more details here and there.

Before we start, you should be aware that the 7800’s graphics chip, MARIA, is capable of 3 graphic display modes: 160A, 320A, and 320B. Each of these graphic modes is capable of displaing sprites or characters in the display mode’s regular format or in it’s alternate format. In addition, MARIA is equipped with 8 adjustable 3-color palettes. A sprite or character can be drawn using any one of these palettes. You can set the mode with ‘displaymode <value>’ near the beginning of your code. It can only be set once.

160A/B modes have no restrictions, and are generally the most commonly used:

160A: 160x192, 3 colors

160B: 160x192, 12 colors

320A and 320B allow for higher resolution images. In 320C mode, even pixel pairs use the first two colors in the palette, and odd pixel pairs use the last two colors in the palette. 320B mode requires pairs of pixels to use the same palette. 320D requires pixels in odd columns to use the first two palette colors, and pixels in even columns to use the last two palette colors.

320A: 320x192, 1 color (320C has 3 colors)

320B: 320x192, 3 colors (320D has 3 colors)

Setting up the 7800 color palette in Gimp

You should already have Gimp installed from the previous section, but if you don’t go ahead and download it here. You should also have already downloaded the 7800 pallete file, but if not grab it here. After you launch Gimp, our first step is to open the palette file image. Note that I’m using Gimp for Windows, version 2.8.22.

Open the palette file “atari256.png” by going to File | Open Image:

Next, click on Windows | Dockable Dialogs | Palettes. We need the Palettes dialog box to be open for the next step.

Next, right click anywhere inside the palettes dialog box to pull up the popup menu. Click on the “Import Palette” menu option.

Once the window is open, click on Image, Palette name (rename to Atari7800), and click on Import.

Nex we’ll want to change the Index mode. Click on Image | Mode | Indexed.

Next we need to change the number of colors in the palete. Click on Generate Optimum Palette and change the number to 13, then click on convert.

Change setting back to RGB, just so we can go back and change it to Indexed again to make one more modification...

Click on Image | Mode | Indexed again to make one more change.

Click on Use custom palette, then the button next to it, then click on the 7800palette that was just added and click convert.

Click on File | Open, image, and open the tileset_rocks image from RevEng's plotmapfile sample that’s included in the distribution. In my case, the file is located at C:\78b\samples\plotmapfile\gfx\tileset_rocks.png. Once you have it open, zoom in so you can actually see what you’re doing. The image is only 48x26 pixels in size, so viewing it at 100% makes it too tiny to actually use. I generally increase the zoom level to 800%, that works well with the native resolution of my laptop. You will likely need to resize the window so you can see the entire image on the screen at once.

Here is the file resized to 800%. Note that the visible area of the image that will be used in our 7800basic program is only the top portion, the bottom 10 vertical pixels are simply for reference in sizing and picking colors when editing the image. In addition, the actual colors that you use in the image are actually inconsequential, you just need to pick four different colors from the palette. The actual colors that are displayed on screen are configurable within your 7800basic code.

Now we can modify the file to use in a 7800basic program. Let’s make an edit! First, we’re going to need our brush to be much smaller, the default brush is 20 pixels wide, we need it set to 1. Go to Windows | Dockable Dialogs | Brushes, as we need the brushes dialog box open. Go to the Windows Menu | Toolbox or press CTRL+B to open the Toolbox Tool Options if you don't see it on screen.

We now need to pick a color. You may remember that 160A sprites are only 3 colors, so why can we choose from 4? One of them is transparent and will take on the color of the background. Which is which depends on how your palettes are defined in the code. Since we pulled this graphic file from the plotmapfile sample, we can take a look at the palette that is used when it’s called in the code:

rem ** setup Palette 1

P1C1=$12

P1C2=$F6

P1C3=$Fc

If we look at the Color Chart (available on Random Terrain’s website), we can see that it’s set to use shades of dark yellow and brown. We can also see in the code that the background is set to $00, or black, so we know that the “transparent” background color is black in this case.

Let’s click on color picker tool and choose one of the four colors to modify the image. he colors in this image don't matter, but if you want to see what your image will ultimately look like pick from the palette., as they are changeable with the PxCx command in the code. One of the colors is transparent and will take the background color.

I”ll explain it in more detail later, but in the plotmapfile sample file RevEng has “set doublewide on” enabled, so our sprites will be 16x16 pixels in size. This particular file includes the images for three diferent sprites, but you can make the file much larger. If you wanted to have six sprites in the same image file, you could double this file in horizontal size. I’ll get to how to do that a bit later, for now let’s modify this file as it is now. After you use the color picker tool, click on the pencil tool to actually draw a pixel. Modify the brush size in the toolbox to however many pixels you want to draw at once.

I decided to change the blank area to a smiley face.

When you’re satisfied with your results, we can save the file. That sounds easy, but Gimp tries to trick you. J You’d think you could just click on “File” and “Save As”, right? Well, if you do that you’ll be saving it in a Gimp proprietary format. We need to save it in PNG format, so we need to export it, not save it. Click on File | Export As to save it for use in your code. When you click on the “export” button in the Export Image window, it will present you with 8 checkbox options. It’s ok to simply accept the defaults, no changes are required.

That’s it! We’re now ready to use the modified image file in a 7800basic program. To test out our changes, let’s try compiling the sample program with our newly modified image.

Just like when we worked on the Hello World sample, I’m going to create a new graphics directory in my root folder called “gfx_plotmapfile”. I’ll copy the plotmapfile.bas file to my root directory and all of the image files in the “gfx” folder into my newly created graphics subfolder. Remember that we’ll have to add or modify the set basepath line in the code for it to work. In this case, each graphic was hardcoded to gfx/, I removed that from each line of code. It may seem like extra work, but being consistent will pay off later!

So just like in our hello world sample earlier, I ran “7800bas plotmapfile.bas” from the command line in my root folder, then ran “C:\78b\mame a7800 –cart plotmapfile.bas.a78” in order to bring it up in the emulator. Resut? Success! We now have our adventurer navigating a desert with both rocks and smiley faces. J

So, we’ve had our first taste of success in modifying a file, but the plotmap file is also a sample of how to use a character map with the Tiled application. If we had saved the file with a different name, updated the 7800basic code to reflect that new name, and compiled it, we would have gotten an error. Why? Because the image file is tied to a character map that was generated with the Tiled map editor, which uses the original file name. Let's dive into creating our own playfield map next using the same sample program.

A few Gimp tips

Before I get to creating a map file with Tiled, I’d like to go over some other tips and tricks I’ve learned working with Gimp. I really like RevEng’s sample graphics files and how they include the extra info at the bottom, it’s a great help in lining up your individual sprite graphics. In most cases you’re going to want the file to be larger, however, and it’s easy to do. You can make the files much wider if you want, I’ve made them up to 256 pixels wide. It's important to note that these sample files with the extra info are appropriate and helpful for creating tilesets for maps, not sprites. Once we get into making standalone sprites, the entire image will be used by the sprite. With that said, let’s try making a wider image with the same tileset_rocks file.

First, to make it easy on ourselves, open up a second copy. We’ll be modifying one, and copying from the other.

Once you have two copies opened up, choose Select | All from one of them, and then hit CTRL+C to copy it to the windows clipboard. On the 2^nd image, choose Image | Scale Image from the menu, and change the Width to 96, then click the link between them (to break it), then change the Height to 26 (to keep the height the same). It will double the width, but it will also stretch out the image itself. Now we can copy in the image we have stored in the clipboard (twice) to fill in the image on the left and right sides. Hit CTRL+V to paste the image from the windows clipboard.

This is what you should see after you scale the image:

And this is what you should see after you paste the original image from the clipboard on the left and right sides.

Easy, right? Now you can save the image after you’ve modified it, and when you pull it up in the tiled map editor you’ll have twice as many tiles to choose from in the same image file (I’ll get to using the map editor next).

Having trouble starting fresh with a clean sprite image? You can also grab any image you want from the internet, scale it to the correct size, pasted it into an existing image file that already has the correct palette colors, and you’re ready to go for editing it. I’ll give you an example of that as well, as it’s what I did when I created the Zelda adventure demo a few years ago to save time.

I did a quick google image search for “zelda sprites”, and found an image of a sprite that looks like Link here.

I copied it, and here it is:

As-is the image is unusable as it won’t match the color palette of the 7800. It’s 218x267 pixels and uses an incorrect RGB palette. Let’s open it up in Gimp.

Now what?

First, let’s resize it to a usable size by the 7800, 16x16 pixels. Use the same method you used before, making sure to break the scaling link and keeping it at 16x16. After we resize it, you can really see all of the extra palette colors in the image. It looks like crap, yes, but we’re not done yet. Again using the same method as before, select the entire image, then copy and paste it into the tileset_rocks image that is already configured with the correct 7800 palette. No, it doesn’t paste in perfectly, but it gives you the basic shape that you can easily modify and make your own. In many cases it’s much easier than starting from scratch.

With a little touching up, we’ve got a nice looking 16x16 Link type sprite, and it only took about 2 minutes of work. J

Creating a plotted playfield map with the Tiled map editor

Now that we’ve got a basic primer on using Gimp out of the way, I’m going to go through the initial setup steps for Tiled, specifically for a map that will work with the 160A display mode along with 'set doublewide on' in your code. The Tiled app has been updated since I first posted my original tutorial so I’m going to update the screenshots and the text as some things have changed.

This tutorial was created with Tiled version 1.0.2.

Before you start you'll of course need all of your graphics images completed. If you make any changes to your tileset graphics in the future, the changes will automatically be reflected in the map as long as you do not change the name of the file. As I mentioned earlier, you cannot change the names of your files once you’ve included them in your map without re-doing all of the tiles in the map that were contained in the image with the old file name.

If you do change the name of one of your existing tileset files, when you load your map the tiles with the old file name the tiles that were used that file will now appear to be blank on the map. Tiled does not create an image file, it creates an XML file that maps out and links to the different graphics images that you have. If you change your image files you will have to update your map file (or files).

The tutorial here assumes 160A mode (as stated) as well as the "set doublewide on" setting. Normally the width of one character in 160A mode is 4 pixels wide, but adding "doublewide" changes that to 8 pixels wide. This is why I used "8" for the "tile width" in Tiled. As you would expect, if you do not use doublewide, you should choose a tile width of 4 pixels. If you wanted to adjust this tutorial for another mode, you can just lookup the width of one character in that mode in the table I linked to, and adjust for "set doublewide on" if you use it. That will be your value for "tile width". The "tile height" will be your zone height, and you can adjust the map size as you prefer.

Once you've installed it, select File | New Map.

Make sure you select the correct options for your new map. Select an orthogonal orientation, CSV format, 20x12 map size, and 8x16 tile size. Note that the Tile Layer format option has changed from the previous tutorial I made. For some reason XML is no longer an option in the drop down list, but it can be changed later once the new map is loaded. XML format is a requirement.

When you’re done selecting option, click on Save As. I’d recommend saving your map file in the same directory as your image files for the project. After it’s saved, you’ll be taken to the main editing screen. At this point we will be able to change our Tile Layer Format to XML. In the properties window pane on the left side, click on the Value box and change the option from CSV to XML.

Now your ready to load up your tileset graphics. You can load multiple sets if you’d like. Go to the Map Menu and click on New Tileset. Let’s load up the tile set that we just modified earlier.

Click on browse to select your tileset. For this map, using 160A and doublewide, we should choose Tiles at 8x16, Margin 0, Spacing 0. Make sure you click on "embed in map"! I forgot to add that in to the initial posting. After clicking on “Save As” and saving the tile set, it will load up and be available to use.

In the next screenshot, note that you can increase the zoom levels of the tile sets and map to make them easier to see and work with. At this point you can click on the image files (more than one can be chosen at a time), and then click on the map to place them where you want them. If you hold the left button mouse down you can drag the tile to fill the map screen. Note that this tileset does not include any “blank” tiles, and the entire map must have something added. If you want areas with a blank background, you’d have to load up a tile set with an image file that includes blank spaces.

If you load multiple tilesets, each one will get their own tab. An additional tile set is loaded the same way as the first one – click on the New Tileset icon and add another. The sample code includes another file named “tileset_blanks”. I loaded that one up and modified the map to make the entire middle portion blank.

Once you're happy with your map design you can save it as a tmx file and use it in your 7800basic program.

So, we now have an updated map file. Let’s see if it works! If you look in the sample code, you can see that the tmx map file is called directly from within the 7800basic code:

incmapfile myplotmapfile.tmx

I simply saved over the existing file with the file that we just modified. After that, it’s just recompile and check the results in an emulator. Results? Success!

That's it for this part. I'm haven't started on part 3 yet, so it'll be a little while. I'd like to review a few more Gimp demos before I dive in to starting on a game.

Tutorial Contents:

Part 1:

Part 2:

Part 3:

Collision Detection between gunfire and Non-Player Sprites

Adding a Status bar with the Score and Lives Remaining

Collision Detection between all Sprites, Speed Change on clearing screen

Animation, Sound Effects, and Performance Troubleshooting

September 19, 2017

Tutorial Contents:

Part 1:

Part 2:

Part 3:

Collision Detection between gunfire and Non-Player Sprites

Adding a Status bar with the Score and Lives Remaining

Collision Detection between all Sprites, Speed Change on clearing screen

Animation, Sound Effects, and Performance Troubleshooting

http://atariage.com/forums/topic/249468-composite-mods-are-they-really-needed/?hl=%2B7800+%2Bhardware+%2Bdifferences&do=findComment&comment=3454792

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

Software

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

Code Editors

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:

Notepad++:

Graphics Editors

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.

Gimp Download

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.

Tiled Map Editor

7800 Emulators

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.

Emulator Downloads

ProSystem Emulator

Mame

A7800 Emulator

Emulator Configuration

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.

Hardware

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.

Video/Audio Mods

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.

http://atariage.com/forums/topic/127926-easier-7800-composite-video-mod/page-6?hl=%2B7800+%2Bhardware+%2Bdifferences&do=findComment&comment=2065687

http://atariage.com/forums/topic/269768-the-uav-rev-d-video-upgrade-installation-in-an-atari-7800-pal/?hl=%2B7800+%2Bdifferences

http://atariage.com/forums/topic/267363-different-av-mods-for-2600-4-switcher-jr-and-7800/?hl=%2B7800+%2Bdifferences&do=findComment&comment=3799740

AtariVox

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

JMP .skipL0270

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

.skipL0270

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.

Command Line

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:

C:\Users\e071237\Downloads\78b

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

7800basic directory.

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.

\includes folder

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.

\samples 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.

Compiling Code

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:

displaymode 320A

set basepath gfx_helloworld

rem **background color...

BACKGRND=$0

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...

P0C2=$0F

rem **set the current character set...

characterset atascii

rem **set the letters represent each graphic character...

alphachars ASCII

clearscreen

plotchars 'Hello World!' 0 0 0

plotchars 'It`s great to be alive.' 0 0 1

plotchars '12345678901234567890123456789012' 0 0 4

main

drawscreen

goto main

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.

C:\78b\>7800bas helloworld.bas

7800basic 0.6 Jul 12 2017 22:46:35

*** (): INFO, GFX Block #0 starts @ $E000

atascii

*** (): 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.

Complete.

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):

@echo off

if "%1"=="" goto error

c:\78b\mame64 a7800 -cart "c:\78b\%1.bas.a78"

goto end

:error

echo Atari 7800 mame game launcher

echo .

echo You must type in a ROM name to launch

:end

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!

Tutorial Contents:

Part 1:

Part 2:

Part 3:

Collision Detection between gunfire and Non-Player Sprites

Adding a Status bar with the Score and Lives Remaining

Collision Detection between all Sprites, Speed Change on clearing screen

Animation, Sound Effects, and Performance Troubleshooting