Writing a Small Complete Game in Assembly: Catch!

A black screen with a white SCORE 0000 MISSES 0 status line at the top, a yellow falling drop, a green bucket near the bottom and a row of asterisks as the ground

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 dlist address in catch.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 dy changes.
  • 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 without SED.
  • 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

  1. Add a title line and wait for START (CONSOL, $D01F) instead of the trigger.
  2. Use missile 0 as a second, faster object worth double points.
  3. Keep a high score, and print it with the same bcd2scr.
  4. Move the drawing into a deferred VBI and let the main loop handle only game rules.
  5. 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