Writing a Game in FastBasic, Step by Step
FastBasic looks like BASIC but behaves like a compiled language: no line numbers, real procedures, structured loops and fast 16-bit integer arithmetic. That makes it a good second step for anyone who has written a game in Atari BASIC and found it too slow. This guide builds Rock Rain, a small but complete game, one piece at a time. You steer a ship along the bottom of the screen while rocks fall at increasing speed. Every rock that falls past you scores a point, and a hit costs one of three lives.
Unlike a typical Atari BASIC game, Rock Rain uses player/missile graphics (the Atari's hardware sprites) for everything that moves, and the hardware collision registers to detect hits. Both are much easier to use from FastBasic than from Atari BASIC.
What you'll learn: structuring a program with PROCs, a loop locked to the TV frame, sprite shapes in DATA arrays, moving sprites with PMHPOS, MOVE and MSET, reading collisions, simple sound effects, game over and a high score.
What you need: FastBasic, either the PC cross-compiler or the on-Atari editor, and a joystick (or an emulator's keyboard joystick). The program in this guide was compiled with the FastBasic 4.7 cross-compiler (fastbasic rockrain.bas produces rockrain.xex) and played in the atari800 emulator, as shown in the screenshot. For an introduction to the language itself, see Getting Started with FastBasic.
1. Plan the game
Before writing code, list what the game needs:
- A screen: GRAPHICS 0 with a black background. The top text line shows score, lives and high score; the rest is empty space for the sprites.
- Objects: the ship (player 0) and three rocks (players 1–3). Each rock has a horizontal position
RX(), a vertical positionRY()and a speedSP(). - A loop that runs once per TV frame: check for a hit, move the ship, move each rock, update the sound.
- States: title screen, playing, game over, then back to the title.
In FastBasic each of those jobs becomes a named procedure. The main program is then short enough to read at a glance.
2. The main loop
DO
@Title
@NewGame
REPEAT
PAUSE
@CheckHit
@MoveShip
FOR I = 0 TO 2 : @MoveRock I : NEXT I
IF SND > 0
SND = SND - 1 : SOUND 0, 60, 10, SND
ENDIF
UNTIL LIVES = 0
@GameOver
LOOP
@Name is FastBasic shorthand for EXEC Name, a call to a PROC. Procedures can be defined before or after the code that calls them, so the main loop can sit at the top of the program where it is easy to find.
PAUSE with no number waits for the next vertical blank, the moment the TV beam returns to the top of the screen. Placing it at the top of the loop locks the game to the frame rate: 60 frames a second on NTSC, 50 on PAL. This is what makes the movement smooth and the speed predictable. FastBasic is fast enough that the whole loop body finishes well within one frame.
The IF ... ENDIF block is a tiny sound engine. When something happens, a procedure sets SND to 15. Each frame the volume drops by one, so a hit produces a short noise that fades over a quarter of a second without the program ever stopping to wait for it.
3. Declare variables before you use them
FastBasic compiles the whole program in order, from top to bottom. It needs to have seen a variable assigned before the first place it is read. In Rock Rain, SND and LIVES are first given values inside NewGame, which comes later in the file than the main loop that tests them. The compiler rejects that with parse error, expected: variable name. The fix is to set everything up at the top:
DATA ship() BYTE = $18,$18,$3C,$7E,$FF,$DB,$81,$00
DATA rock() BYTE = $3C,$7E,$FF,$FF,$FF,$7E,$3C,$00
DIM RX(2), RY(2), SP(2)
HI = 0 : SCORE = 0 : LIVES = 0 : SND = 0 : X = 0
All plain variables are 16-bit integers (−32768 to 32767), which is ideal for game logic. DIM RX(2) creates an array with elements 0 to 2.
The two DATA ... BYTE lines are the sprite shapes, eight bytes each, one byte per row. Each set bit is a lit pixel: $18 is 00011000, the ship's nose. The last byte of each shape is zero. That blank row matters later, because it means a shape that moves down by a row erases its own top edge.
4. The title screen
PROC Title
GRAPHICS 18 : SETCOLOR 4, 9, 2
POSITION 5, 2 : ? #6, "ROCK RAIN"
POSITION 2, 5 : ? #6, "dodge the rocks"
POSITION 1, 7 : ? #6, "HIGH SCORE "; HI
POSITION 5, 10 : ? #6, "press fire"
REPEAT : UNTIL STRIG(0) = 0
REPEAT : UNTIL STRIG(0) = 1
ENDPROC
GRAPHICS 18 is mode 2 (large text, 20 columns) with no text window. In modes 1 and 2, lower-case letters print in a second colour, which is an easy way to add some variety. The two REPEAT loops wait for the fire button to be pressed and then released, so the press that starts the game doesn't also count as anything inside it.
5. Setting up players and missiles
PROC NewGame
GRAPHICS 0 : POKE 752, 1
SETCOLOR 2, 0, 0 : SETCOLOR 4, 0, 0
PMGRAPHICS 2
FOR I = 0 TO 3 : MSET PMADR(I), 128, 0 : NEXT I
POKE 704, $1C : POKE 705, $F6 : POKE 706, $F6 : POKE 707, $F6
X = 120 : PMHPOS 0, X
MOVE ADR(ship), PMADR(0) + 100, 8
FOR I = 0 TO 2 : @NewRock I : RY(I) = RY(I) - I * 30 : NEXT I
SCORE = 0 : LIVES = 3 : SND = 0
@Status
POKE $D01E, 0
ENDPROC
This is where FastBasic saves the most work compared with Atari BASIC:
PMGRAPHICS 2reserves player/missile memory, sets the hardware registers and turns on sprite display in double-line resolution. Each player is then a 128-byte strip as tall as the screen, and each byte is two scan lines high.PMADR(n)returns the address of player n's strip.MSET PMADR(I), 128, 0fills a whole strip with zeros, wiping any old shapes.- Locations 704–707 are the OS shadows of the four player colours.
$1Cis a light yellow-orange;$F6is an orange-brown. PMHPOS n, xsets a player's horizontal position, which is the same as POKEing$D000+n. Values from about 48 to 200 are on a normal-width screen.MOVE ADR(ship), PMADR(0) + 100, 8copies the eight-byte ship shape into the strip at byte 100, near the bottom of the screen. The ship never moves vertically, so this is done only once.
POKE 752, 1 hides the text cursor, and POKE $D01E, 0 writes to HITCLR, which clears all the collision registers so the game doesn't start with a leftover hit.
6. Rocks: random starts and a rising speed
PROC NewRock N
RX(N) = 48 + RAND(145)
RY(N) = 0 - RAND(20)
SP(N) = 1 + RAND(2) + SCORE / 25
IF SP(N) > 5 THEN SP(N) = 5
PMHPOS N + 1, RX(N)
ENDPROC
A PROC can take parameters: N is the rock number, 0 to 2, and rock N is drawn with player N+1. RAND(145) returns 0 to 144, so each rock gets a random column across the screen.
The vertical position starts at zero or below. A negative RY means "waiting above the screen", so the rocks arrive one by one rather than together. NewGame staggers them further by subtracting I * 30. The speed is 1 or 2 bytes per frame at first, plus one for every 25 points, up to a limit of 5. Because the arithmetic is integer, SCORE / 25 simply drops the fraction.
7. Moving the rocks
PROC MoveRock N
P = PMADR(N + 1)
IF RY(N) >= 0 THEN MSET P + RY(N), 8, 0
RY(N) = RY(N) + SP(N)
IF RY(N) > 112
SCORE = SCORE + 1 : @Status
@NewRock N
ENDIF
IF RY(N) >= 0 THEN MOVE ADR(rock), P + RY(N), 8
ENDPROC
Players have no vertical position register. To move a shape down, you move its bytes within the strip. Each frame the procedure:
- Erases the rock at its old position with
MSET(only if it is on the strip). - Adds the speed to
RY. - If the rock has gone past byte 112, below the visible area, scores a point and starts a new rock.
- Draws the rock at the new position with
MOVE.
MOVE and MSET are machine-code block operations, so each one takes a tiny fraction of a frame. In Atari BASIC the same job needs a FOR loop of POKEs or a string-copy trick; here it is one statement.
8. Moving the ship
PROC MoveShip
S = STICK(0)
IF S & 4 = 0 AND X > 48 THEN X = X - 2
IF S & 8 = 0 AND X < 196 THEN X = X + 2
PMHPOS 0, X
ENDPROC
STICK(0) returns the same values as in Atari BASIC: 15 at rest, with one bit cleared for each direction pushed. Bit value 4 is left and 8 is right. Testing the bits with & (binary AND), instead of comparing with 11 and 7, means the ship also moves when the stick is pushed diagonally. The limits keep the ship on screen.
9. Collisions from the hardware
PROC CheckHit
IF PEEK($D00C) & 14
LIVES = LIVES - 1 : SND = 15 : @Status
FOR I = 0 TO 2
MSET PMADR(I + 1), 128, 0
@NewRock I : RY(I) = RY(I) - I * 30
NEXT I
ENDIF
POKE $D01E, 0
ENDPROC
The GTIA chip records every overlap between sprites as the screen is drawn. Location $D00C (P0PL) holds the collisions of player 0 with the other players: bit value 2 for player 1, 4 for player 2 and 8 for player 3. & 14 therefore asks "did the ship touch any rock?" The check is pixel-accurate, so a rock that passes through the gap beside the ship's nose doesn't count.
The order in the main loop matters. CheckHit runs straight after PAUSE, so it reads the collisions from the frame that has just been displayed, then clears them with HITCLR for the next one. After a hit, all three rocks are wiped and restarted above the screen, which gives the player a moment to recover.
10. Score and game over
PROC Status
POSITION 2, 0
? "SCORE "; SCORE; " LIVES "; LIVES; " HIGH "; HI; " ";
ENDPROC
PROC GameOver
SOUND
IF SCORE > HI THEN HI = SCORE
POSITION 15, 11 : ? "GAME OVER";
PAUSE 120
PMGRAPHICS 0
ENDPROC
The status line is printed only when something changes, not every frame. The trailing spaces wipe out leftover digits, and the final semicolon stops the cursor from moving to the next line. SOUND on its own silences all four voices. PAUSE 120 holds the GAME OVER message for two seconds (NTSC). PMGRAPHICS 0 then turns the sprites off before the title screen appears. HI is never reset, so the title screen shows the best score of the session.
11. The complete program
' ROCK RAIN - A small game in FastBasic
DATA ship() BYTE = $18,$18,$3C,$7E,$FF,$DB,$81,$00
DATA rock() BYTE = $3C,$7E,$FF,$FF,$FF,$7E,$3C,$00
DIM RX(2), RY(2), SP(2)
HI = 0 : SCORE = 0 : LIVES = 0 : SND = 0 : X = 0
DO
@Title
@NewGame
REPEAT
PAUSE
@CheckHit
@MoveShip
FOR I = 0 TO 2 : @MoveRock I : NEXT I
IF SND > 0
SND = SND - 1 : SOUND 0, 60, 10, SND
ENDIF
UNTIL LIVES = 0
@GameOver
LOOP
PROC Title
GRAPHICS 18 : SETCOLOR 4, 9, 2
POSITION 5, 2 : ? #6, "ROCK RAIN"
POSITION 2, 5 : ? #6, "dodge the rocks"
POSITION 1, 7 : ? #6, "HIGH SCORE "; HI
POSITION 5, 10 : ? #6, "press fire"
REPEAT : UNTIL STRIG(0) = 0
REPEAT : UNTIL STRIG(0) = 1
ENDPROC
PROC NewGame
GRAPHICS 0 : POKE 752, 1
SETCOLOR 2, 0, 0 : SETCOLOR 4, 0, 0
PMGRAPHICS 2
FOR I = 0 TO 3 : MSET PMADR(I), 128, 0 : NEXT I
POKE 704, $1C : POKE 705, $F6 : POKE 706, $F6 : POKE 707, $F6
X = 120 : PMHPOS 0, X
MOVE ADR(ship), PMADR(0) + 100, 8
FOR I = 0 TO 2 : @NewRock I : RY(I) = RY(I) - I * 30 : NEXT I
SCORE = 0 : LIVES = 3 : SND = 0
@Status
POKE $D01E, 0
ENDPROC
PROC NewRock N
RX(N) = 48 + RAND(145)
RY(N) = 0 - RAND(20)
SP(N) = 1 + RAND(2) + SCORE / 25
IF SP(N) > 5 THEN SP(N) = 5
PMHPOS N + 1, RX(N)
ENDPROC
PROC MoveShip
S = STICK(0)
IF S & 4 = 0 AND X > 48 THEN X = X - 2
IF S & 8 = 0 AND X < 196 THEN X = X + 2
PMHPOS 0, X
ENDPROC
PROC MoveRock N
P = PMADR(N + 1)
IF RY(N) >= 0 THEN MSET P + RY(N), 8, 0
RY(N) = RY(N) + SP(N)
IF RY(N) > 112
SCORE = SCORE + 1 : @Status
@NewRock N
ENDIF
IF RY(N) >= 0 THEN MOVE ADR(rock), P + RY(N), 8
ENDPROC
PROC CheckHit
IF PEEK($D00C) & 14
LIVES = LIVES - 1 : SND = 15 : @Status
FOR I = 0 TO 2
MSET PMADR(I + 1), 128, 0
@NewRock I : RY(I) = RY(I) - I * 30
NEXT I
ENDIF
POKE $D01E, 0
ENDPROC
PROC Status
POSITION 2, 0
? "SCORE "; SCORE; " LIVES "; LIVES; " HIGH "; HI; " ";
ENDPROC
PROC GameOver
SOUND
IF SCORE > HI THEN HI = SCORE
POSITION 15, 11 : ? "GAME OVER";
PAUSE 120
PMGRAPHICS 0
ENDPROC
The compiled executable is about 2.5 KB. On a PC, save the listing as rockrain.bas and run fastbasic rockrain.bas. The result, rockrain.xex, loads in any emulator or from a real Atari's DOS, SD-card device or FujiNet. It ran in the emulator with the BASIC ROM switched on or off, because FastBasic executables don't depend on BASIC.
12. Where to take it next
- Fire back: use missile 0 (
PMHPOS 4, ..., data atPMADR(-1)) as a laser and the register at$D008(M0PL) to find which rock it hit. - Smoother sprites: switch to
PMGRAPHICS 1, single-line resolution. Each strip is then 256 bytes, so double every vertical number and make the shapes taller. - More rocks: players are limited to four, but the missiles can be extra small rocks, or rocks can be drawn as characters in the playfield (see Player Multiplexing for the hardware-sprite route).
- Better sound: use a second voice for a constant engine hum, or a falling pitch for the explosion (see Sound Effects Recipes for Atari BASIC; the ideas carry over directly).
- A colour background: FastBasic 4.3 and later can define display list interrupts in the language with
DLI SET, for a sky that changes colour down the screen.
Troubleshooting
parse error, expected: variable name: a variable is read before the compiler has seen it assigned. Give it a value near the top of the program.- Nothing appears, or the program locks up: call
PMGRAPHICSafterGRAPHICS, as the manual's own examples do, and set the sprites up again after every mode change. A GRAPHICS command rebuilds the screen and its memory. - Rocks leave trails: a shape must be erased before it moves, or end in enough zero bytes to cover the distance it moves each frame.
- Lives vanish all at once: the collision registers were not cleared. Write to
$D01E(HITCLR) once per frame and after restarting the rocks. - The game starts immediately after the title: wait for the fire button to be released as well as pressed.
Further reading
- FastBasic Manual (MANUAL.md in the FastBasic distribution), for every statement used here, including
PMGRAPHICS,PMADR,MOVE,MSET,PAUSEandDLI. - Ian Chadwick, Mapping the Atari, for the GTIA collision registers and colour shadows.
- On this site: Getting Started with FastBasic, Player/Missile Graphics in Atari BASIC, Collision Detection in Depth, Writing a Complete Game in Atari BASIC, Step by Step.
Credits
- Picture: Rock Rain running: steer the ship left and right and dodge the falling rocks. — Program authors; screenshot by the site
- FastBasic Manual (MANUAL.md, FastBasic 4.7 distribution) — GitHub project authors
- FastBasic cross-compiler usage (USAGE.md) — GitHub project authors
- AtariAge — FastBasic 4.7 is here! — AtariAge forum members
- AtariAge — explanatory demo for the new pm commands in fastbasic — AtariAge forum members
- Mapping the Atari — 704-707 PCOLR0-3, 752 CRSINH, $D00C P0PL, $D01E HITCLR — AtariArchives.org
