Writing a Small Complete Game in Assembly: Catch!
Most assembly tutorials stop at a moving sprite. A game needs more than that: a screen you designed yourself, a loop that runs at a steady speed, a way to win and a way to lose, a score and some noise. This guide puts all of those together in one short program, Catch!. Drops fall from random places at the top of the screen. You steer a bucket left and right with the joystick to catch them. Every catch scores a point, every tenth catch makes the drops fall faster, and three misses end the game. The program assembles to 647 bytes.
What you'll learn: how to structure a whole game, from one-time setup through a new-game routine to a main loop locked to the TV frame; how to combine a custom display list with player/missile graphics; how to detect hits with GTIA's collision registers; how to keep a decimal score with the 6502's BCD mode and print it straight into screen memory; and how to add sound effects without slowing anything down.
What you need: the MADS assembler, Altirra or atari800, and a joystick (or the emulator's keyboard joystick). This guide builds on Getting Started with 6502 Assembly on the Atari 8-bit (the build-and-run workflow) and Player/Missile Graphics in Assembly (P/M memory layout and registers). Read those first if PMBASE or run start mean nothing to you yet.
1. Plan the game before you write code
A small game is easiest to write if you decide up front what lives where:
| Thing | How it's done |
|---|---|
| Status line | One ANTIC mode 2 text line at the top, in our own memory |
| Playing field | 168 blank scan lines (no screen memory needed at all) |
| Ground | One more mode 2 line of * characters |
| Bucket | Player 0, double width, fixed height near the bottom |
| Drop | Player 1, redrawn lower each frame |
| Timing | Main loop waits for the OS frame counter to change |
| Sound | POKEY voice 1, switched off by a frame countdown |
Using blank display-list lines for the field is a useful trick. Players are drawn by GTIA regardless of what the playfield shows, so a game whose action is all sprites doesn't need a bitmap. The whole screen costs 80 bytes of text plus a 30-byte display list.
2. The listing
Save this as catch.asm and build it with the command in the second line.
; catch.asm - a small complete game for the Atari 8-bit
; build: mads catch.asm -o:catch.xex -l:catch.lst -t:catch.lab
; ---- OS shadow registers and variables ----
RTCLOK = $14 ; jiffy counter, +1 every vertical blank
ATRACT = $4D ; attract-mode timer
SDMCTL = $022F ; shadow of DMACTL
SDLSTL = $0230 ; shadow of DLISTL/DLISTH
GPRIOR = $026F ; shadow of PRIOR
STICK0 = $0278 ; joystick 0 directions
STRIG0 = $0284 ; joystick 0 trigger, 0 = pressed
PCOLR0 = $02C0 ; player 0 colour
PCOLR1 = $02C1 ; player 1 colour
COLOR1 = $02C5 ; text luminance in mode 2
COLOR2 = $02C6 ; mode 2 background
COLOR4 = $02C8 ; border / background
; ---- hardware ----
HPOSP0 = $D000
HPOSP1 = $D001
SIZEP0 = $D008 ; write
P1PL = $D00D ; read: player 1 to player collisions
GRACTL = $D01D
HITCLR = $D01E
AUDF1 = $D200
AUDC1 = $D201
AUDCTL = $D208
RANDOM = $D20A
SKCTL = $D20F
PMBASE = $D407
PMG = $3000 ; 2K-aligned P/M area
PLAYER0 = PMG+$400
PLAYER1 = PMG+$500
CATCHY = 200 ; scan line of the catcher (single-line units)
BOTTOM = 212 ; drop gets past the catcher here
org $2000
; ================= one-time setup =================
start lda #0
sta SDMCTL ; screen off while we build it
sta AUDCTL ; plain 64 kHz POKEY clock
lda #3
sta SKCTL ; POKEY out of init mode
lda #<dlist
sta SDLSTL
lda #>dlist
sta SDLSTL+1
lda #$00
sta COLOR4 ; black border
sta COLOR2 ; black text background
lda #$0E
sta COLOR1 ; white text
lda #>PMG
sta PMBASE
lda #0 ; clear both players
tax
clrpm sta PLAYER0,x
sta PLAYER1,x
inx
bne clrpm
ldx #5 ; draw the catcher (never moves vertically)
drawc lda cshape,x
sta PLAYER0+CATCHY,x
dex
bpl drawc
lda #1
sta SIZEP0 ; double width: 16 pixels
lda #$C8
sta PCOLR0 ; green catcher
lda #$1A
sta PCOLR1 ; yellow drop
lda #1
sta GPRIOR ; players in front of playfield
lda #3
sta GRACTL ; GTIA: show players and missiles
lda #$3E ; ANTIC: DL + P/M DMA, single line, normal width
sta SDMCTL
; ================= new game =================
newgame lda #0
sta score
sta score+1
sta misses
sta sndtime
lda #1
sta speed
lda #120
sta cx
jsr showstat
jsr newdrop
; ================= main loop: once per frame =================
loop lda RTCLOK ; wait for the next vertical blank
wait cmp RTCLOK
beq wait
lda #0
sta ATRACT ; we have no key presses: stop attract mode
lda P1PL ; did the drop touch the catcher last frame?
sta HITCLR ; reset collisions for the coming frame
and #1 ; bit 0 = player 0
beq nocatch
jsr caught
jmp move
nocatch lda dy
cmp #BOTTOM
bcc move
jsr missed
lda misses
cmp #3
bcc move
jmp gameover
move jsr joystick
jsr falldrop
jsr sound
jmp loop
; ---- joystick: left/right moves the catcher 2 pixels ----
joystick lda STICK0
and #4 ; bit 2 = left, 0 when pushed
bne notleft
lda cx
cmp #50
bcc notleft
dec cx
dec cx
notleft lda STICK0
and #8 ; bit 3 = right
bne notright
lda cx
cmp #190
bcs notright
inc cx
inc cx
notright lda cx
sta HPOSP0
rts
; ---- move the drop down by "speed" lines ----
falldrop ldx dy ; erase it at the old position
ldy #7
lda #0
erase sta PLAYER1,x
inx
dey
bpl erase
lda dy
clc
adc speed
sta dy
tax ; draw it at the new position
ldy #0
draw lda dshape,y
sta PLAYER1,x
inx
iny
cpy #8
bne draw
lda dx
sta HPOSP1
rts
; ---- a new drop at a random column ----
newdrop ldx dy ; erase the old one first
ldy #7
lda #0
ndclr sta PLAYER1,x
inx
dey
bpl ndclr
lda RANDOM
and #$7F ; 0..127
clc
adc #56 ; 56..183
sta dx
lda #40 ; just below the status line
sta dy
rts
; ---- caught: score, beep, maybe speed up ----
caught sed ; score is BCD: 0000..9999
lda score
clc
adc #1
sta score
lda score+1
adc #0
sta score+1
cld
lda score
and #$0F ; every 10 catches...
bne nofast
lda speed
cmp #6
bcs nofast
inc speed ; ...fall one line per frame faster
nofast lda #40 ; high-pitched pure tone
sta AUDF1
lda #$AA ; distortion 10 (pure), volume 10
sta AUDC1
lda #6
sta sndtime
jsr showstat
jmp newdrop
; ---- missed: count it, buzz ----
missed inc misses
lda #200 ; low noisy buzz
sta AUDF1
lda #$8C ; distortion 8 (noise), volume 12
sta AUDC1
lda #20
sta sndtime
jsr showstat
jmp newdrop
; ---- silence the sound when its time is up ----
sound lda sndtime
beq quiet
dec sndtime
bne snddone
quiet lda #0
sta AUDC1
snddone rts
; ---- write score and misses into screen memory ----
showstat lda score+1
ldx #6 ; column of the first score digit
jsr bcd2scr
lda score
jsr bcd2scr
lda misses
ora #$10 ; screen code of '0' is $10
sta status+19
rts
bcd2scr pha ; two BCD digits -> two screen codes
lsr
lsr
lsr
lsr
ora #$10
sta status,x
inx
pla
and #$0F
ora #$10
sta status,x
inx
rts
; ---- game over: wait for the trigger ----
gameover lda #0
sta AUDC1
ldx #9
goshow lda gotext,x
sta status+30,x
dex
bpl goshow
gowait lda STRIG0 ; wait until the trigger is released...
beq gowait
gopress lda STRIG0 ; ...then pressed
bne gopress
ldx #9
lda #0 ; screen code 0 = space
goclr sta status+30,x
dex
bpl goclr
jmp newgame
; ================= data =================
score dta 0,0 ; BCD, low byte first
misses dta 0
speed dta 1
cx dta 120 ; catcher x
dx dta 120 ; drop x
dy dta 40 ; drop y (top line of shape)
sndtime dta 0
cshape dta $C3,$C3,$C3,$C3,$FF,$FF ; a small bucket
dshape dta $18,$3C,$7E,$FF,$FF,$7E,$3C,$18
gotext dta d'GAME OVER!'
; ---- display list: status line, empty field, ground line ----
.align $100 ; keep the display list inside one 1K block
dlist dta $70,$70,$70 ; 24 blank lines (top border)
dta $42,a(status) ; mode 2 + LMS: the status line
:21 dta $70 ; 168 blank scan lines: the playing field
dta $42,a(ground) ; mode 2 + LMS: the ground
dta $41,a(dlist) ; jump and wait for vertical blank
status dta d'SCORE 0000 MISSES 0 '
ground :40 dta $0A ; screen code $0A = '*'
run start
Boot catch.xex in Altirra (File > Boot Image) or with atari800 -run catch.xex. Neither needs a DOS disk.
3. Setup: build the screen, then switch it on
The first instruction stores 0 in SDMCTL ($22F), the OS shadow of ANTIC's DMA control register. With DMA off the screen goes black. That way you never see a half-built display while the display list pointer and colours change. The OS copies SDMCTL, SDLSTL and the colour shadows into the hardware during every vertical blank, so the program writes only shadows and the change happens cleanly at the start of a frame.
POKEY gets the standard reset: 0 into AUDCTL ($D208) for plain 64 kHz clocking, and 3 into SKCTL ($D20F) to take it out of its initialisation state. The display list pointer goes into SDLSTL ($230/$231).
The P/M setup is the one from Player/Missile Graphics in Assembly. PMBASE gets the high byte of a 2K-aligned block at $3000, both player stripes are cleared, and SDMCTL = $3E turns on display-list DMA, player and missile DMA and single-line resolution with a normal-width playfield. GRACTL = 3 lets GTIA show the data. The bucket is drawn once, because it only ever moves sideways. Storing 1 in SIZEP0 ($D008) makes it double width, which is easier to play.
The display list at the bottom of the listing does the screen layout. Three $70 bytes are the usual 24 blank lines that push the picture below the top of the TV. $42 is mode 2 (40-column text) plus the LMS bit, followed by the address of the status line. Then 21 more $70s make 168 empty scan lines, a second $42 points at the ground, and $41 jumps back and waits for vertical blank. Display Lists Explained and Custom Display Lists cover the instruction bytes in detail. The .align $100 keeps the list well inside a 1K block, which ANTIC requires.
4. Separate "new game" from setup
newgame resets only what a fresh game needs: score, misses, speed, bucket position and the first drop. Hardware setup isn't repeated. The game-over code jumps back here, so restarting is one JMP. Keeping these two stages apart is a habit worth adopting even in tiny programs.
5. A main loop locked to the frame
The loop starts by reading the low byte of RTCLOK ($14), which the OS increments once per vertical blank, and spinning until it changes. Everything after that runs once per frame, 60 times a second on NTSC or 50 on PAL. That means:
- Movement speed is in pixels per frame, so the game runs at the same pace no matter how much work a frame takes (as long as it fits).
- The loop body runs just after vertical blank, while the beam is still near the top. The drop is redrawn before the beam reaches it, so there is no tearing.
Waiting on RTCLOK is the simplest frame sync. For finer control you can poll VCOUNT ($D40B), which gives the current scan line divided by two. LDA VCOUNT / CMP #100 / BNE *-5 waits for a particular line, which is how you'd start drawing just after the beam has passed an object. For bigger games, moving the per-frame work into a vertical blank interrupt, as the P/M guide does, frees the main loop for slower logic.
The loop also clears ATRACT ($4D) every frame. The OS counts up attract mode from the last key press, and after several minutes it starts cycling colours. A joystick game never presses keys, so without this line the screen would start changing colour mid-game.
6. Collisions: check first, then move
GTIA sets collision bits while it draws, so at the top of the loop they describe the frame just shown. The program reads P1PL ($D00D, player 1 to player collisions, read-only), writes anything to HITCLR ($D01E) to reset all collision registers for the next frame, and then tests bit 0 (player 0, the bucket). Only after that does it move anything. Doing it in the other order would test a frame the player hasn't seen yet.
At the top speed the drop moves six lines a frame. Because the drop is 8 lines tall and the bucket 6, their rows always overlap in at least one frame as the drop passes, so a fast drop can't jump straight through the bucket. If you make objects faster or thinner, check this arithmetic or test the positions yourself as well.
7. Score in screen memory, in BCD
The score is two bytes in binary-coded decimal: each nibble holds one decimal digit, so $0123 means 123. With the decimal flag set (SED), ADC does decimal arithmetic, so adding 1 to $09 gives $10. Clear the flag with CLD straight away, so that no later binary arithmetic runs in decimal mode by mistake.
BCD makes printing trivial. bcd2scr shifts the high nibble down, ORs in $10 (the internal screen code for the digit 0) and stores it into the status line, then does the same for the low nibble. No division is needed. Remember that screen memory holds internal codes, not ATASCII, which is why the text is written with MADS's dta d'...'. The ground's * is screen code $0A.
The difficulty curve uses the BCD score too. When the low digit is 0 after a catch, that's another ten catches, and speed goes up by one line per frame, to a maximum of six.
8. Sound without stopping the game
A sound effect that waits in a delay loop would freeze the game. Instead, caught and missed set a voice going and load sndtime with a duration in frames. Each pass through the loop, sound counts it down and writes 0 to AUDC1 when it reaches zero. The catch is a short pure tone (AUDC1 = $AA: distortion 10, volume 10) and a miss is a longer noisy buzz ($8C: distortion 8, volume 12). See POKEY Sound Basics for what the distortion values do. A table of frequencies stepped by the same counter turns these beeps into sweeps and jingles.
9. Randomness and game over
RANDOM ($D20A) returns a fresh value from POKEY's noise generator on every read. AND #$7F and adding 56 give horizontal positions 56–183, inside the visible area.
When misses reaches 3, gameover silences the voice, copies GAME OVER! into the status line and waits for the trigger. It waits for STRIG0 ($284) to read 1 (released) first and then 0 (pressed). Without the release check, a player still holding the button from the last game would restart instantly.
Troubleshooting
- Black screen. SDMCTL is still 0, or the display list address is wrong. Check the
dlistaddress incatch.lab. - Players visible but no text. The LMS addresses in the display list are wrong, or you wrote ATASCII (
c'...') instead of screen codes (d'...'). - The drop leaves a trail. The erase loop must clear the old position before
dychanges. - Catches never register. Check that you read P1PL ($D00D) and not the P/M graphics register at the same address, which is write-only. Also check that HITCLR is written after the read, not before.
- Score shows strange characters. You forgot
CLD, or added withoutSED. - The game runs at different speeds on PAL and NTSC. That's expected with frame-based movement: PAL gives 50 frames a second. Adjust speeds after checking PAL (see Keeping Time: RTCLOK, System Timers and POKEY Hardware Timers).
Ideas to extend it
- Add a title line and wait for START (CONSOL, $D01F) instead of the trigger.
- Use missile 0 as a second, faster object worth double points.
- Keep a high score, and print it with the same
bcd2scr. - Move the drawing into a deferred VBI and let the main loop handle only game rules.
- Replace the blank lines with a mode 4 character playfield and give the game scenery.
Further reading
- Atari Graphics and Arcade Game Design by Jeffrey Stanton and Dan Pinal (Arrays, 1984): complete arcade-game design in assembly.
- De Re Atari (Atari, Inc., 1982), chapters on ANTIC, P/M graphics and sound.
- Mapping the Atari by Ian Chadwick (COMPUTE! Books): every address used here.
- Atari Roots by Mark Andrews (Datamost, 1984) and Machine Language for Beginners by Richard Mansfield (COMPUTE! Books, 1983).
- ANALOG Computing's "Boot Camp" assembly column, and the many complete assembly games ANALOG published with full source.
Credits
- Picture: Catch! running in the atari800 emulator: steer the green bucket under the falling drop. — Program authors; screenshot by the site
- Mapping the Atari (revised edition) — RTCLOK 18-20, ATRACT 77, SDMCTL 559, SDLSTL 560, GPRIOR 623, STICK0 632, STRIG0 644, PCOLR0-1 704-705, COLOR1/2/4, HPOSP0-1, SIZEP0, P1PL 53261, GRACTL, HITCLR, AUDF1/AUDC1, AUDCTL, RANDOM, SKCTL, PMBASE, VCOUNT — AtariArchives.org
- De Re Atari, Chapter 2: ANTIC and the Display List (1K display-list and 4K screen-memory boundaries) — AtariArchives.org
- De Re Atari, Chapter 4: Player-Missile Graphics — Chris Crawford (Section 4 of De Re Atari)
- De Re Atari, Chapter 7: Sound (POKEY reset: AUDCTL 0, SKCTL 3) — Bob Fraser (Section 7 of De Re Atari)
- MADS (Mad-Assembler) manual — dta d'' screen codes, :n repeat, .align, run — mads.atari8.info
