Studying the Star Raiders Source Code: A Guided Tour
Star Raiders, Doug Neubauer's 1979 space combat game for Atari, fits a first-person 3D star field, a strategic galactic map, enemy AI, damage control and full sound into an 8 KB cartridge. A complete documented source listing now lets you read it line by line. This guide is a map for that reading: where things are, which routines to read first, and which tricks are worth reusing.
What you'll learn: what the available source is and how it relates to Neubauer's original, how the program is laid out in RAM and ROM, how the game loop and interrupt handlers divide the work, how the display list changes between views, how the rotating star field and perspective projection are calculated, and how the Galactic Chart and damage system work. At the end, you'll rebuild the cartridge yourself.
What you need: the source file StarRaiders.source.asm.txt (or the MADS-ready copy described below), a text editor, and ideally Altirra for setting breakpoints as you read. Comfort with 6502 assembly and display lists helps (see Getting Started with 6502 Assembly on the Atari 8-bit and Display Lists Explained).
1. Which source is this?
The listing everyone studies is a reverse-engineered reconstruction by Lorenz Wiest, made from the ROM binary without access to the original source (first release 22 September 2015, last update 10 December 2016). He wrote his own MAC/65-syntax cross-assembler to check that the source rebuilds the cartridge byte for byte, and a symbol checker to keep the address references in the comments correct.
A month later, in October 2015, scans of Neubauer's original source listing turned up and were put on the Internet Archive. Comparing them with the reconstruction confirmed its findings and led to only a few trivial corrections. The original is sparsely commented, as you'd expect from code never meant for publication. Wiest's version adds the theory of operation and so is the better one to learn from.
Keep in mind that the label names in the reconstruction are Wiest's. When this guide quotes GAMELOOP or VBIHNDLR, those are the documented source's names, which need not match Neubauer's.
After a notation section and an overview of position and velocity vectors come a memory map, the symbols, data, and the code. Comments mark suspected bugs with (!) and code that isn't fully understood with (?). Searching for those is a quick way into the interesting corners.
2. The memory map: almost everything below $2000
Star Raiders doesn't use the OS screen editor or the BASIC-era memory layout. It takes over the machine and lays out RAM itself:
| Address | Contents |
|---|---|
| $0062–$00FB | Zero-page game variables |
| $0280–$02E9 | DSPLST, the display list |
| $0300–$07FF | Player/missile data (PMBASE = 0, single-line) |
| $0800–$08C7 | Row address tables for the playfield |
| $08C9–$0948 | GCMEMMAP, the Galactic Chart's 16 × 8 sectors |
| $09AD–$0BF8 | Position and velocity tables for 49 space objects |
| $0DE9–$0FE8 | MAPTO80 and MAPTOBCD99 lookup tables |
| $1000–$1F77 | PFMEM, the GRAPHICS 7 playfield |
| $A000–$BFFF | The 8 KB cartridge: code, data, shapes, character set |
Setting PMBASE to 0 puts the player stripes at $0400–$07FF and the missile stripe at $0300, which the game uses as a fifth player. All of the game's RAM, including the display list, the P/M graphics and the playfield, sits in the first 8 KB, below $2000.
Each space object has a 17-bit signed coordinate per axis, split across three parallel tables (for example ZPOSSIGN, ZPOSHI, ZPOSLO), so one index register reaches any object with LDA ZPOSHI,X. This is the standard 6502 alternative to arrays of structures. Objects 0–4 are drawn with players (Zylons, meteors, torpedoes, the starbase). Objects 5–48 are playfield pixels: stars, explosion fragments and star trails.
3. Start-up: INITCOLD
The cartridge enters at INITCOLD ($A14A). There are four entry points that run into each other: INITCOLD, INITSELECT, INITDEMO and INITSTART. Each loads one more parameter before continuing into the next one. Pressing START or SELECT, or entering demo mode, jumps in at the matching point.
The clearing loop shows an example of the craftsmanship. One loop with X running from 0 to 255 clears GTIA, ANTIC, POKEY, PIA and the zero-page variables together. To stop the zero-page store wrapping around to $0000, the source forces an absolute-indexed opcode by hand:
.BYTE $9D ; HACK: Force ISVBISYNC,X with 16-bit address
.WORD ISVBISYNC ; (loop jamming)
Most assemblers would pick the zero-page form of STA ISVBISYNC,X, which would wrap and wipe $0000–$0066. The absolute form harmlessly clears into the unused part of the stack page instead. After that, INITCOLD points the OS vectors VIMIRQ, VVBLKI and VDSLST at the game's own IRQ, VBI and DLI handlers. It enables PRIOR = $11 (a fifth player, players in front of the playfield) and calls INITIALIZE to build the display list and lookup tables and to scatter Zylons and starbases across the Galactic Chart.
4. The game loop and the three interrupt handlers
Read the header of GAMELOOP ($A1F3) first: it lists all 33 steps of one iteration, each matched by a numbered banner in the code. The loop starts by waiting for the vertical blank handler:
GAMELOOP LDA ISVBISYNC ; Wait for execution of VBI
BEQ GAMELOOP ;
Then it redraws the stars and players, rotates and moves every object, projects them to the screen, and handles input, torpedoes, docking, AI, damage, the control panel and hyperwarp. The interrupt handlers are short and worth reading in full:
VBIHNDLRsets the sync flag, switches to the ROM character set, picks the background colour (flashing it when the ship is hit), copies the colour variables to the hardware registers, clears collisions, callsSOUNDand counts the idle timer that starts demo mode. It ends by jumping into the DLI handler's register-restore code instead of having its own.DLSTHNDLRchooses the ROM or custom character set depending onVCOUNT, copies the DLI colours to the playfield registers after aWSYNC, and copies the torpedo collision registers into variables.IRQHNDLRhandles only the keyboard. It re-arms the keyboard interrupt, readsKBCODEand stores the code for the game loop.
Sound runs from the VBI, so it keeps time whatever the main loop does. Channels 1–3 share the engines and "noise patterns" (explosions, torpedoes), and channel 4 plays prioritised "beeper patterns" such as RED ALERT.
5. Display lists: one list, edited live
INITIALIZE builds a display list at DSPLST with blank lines and 90 GRAPHICS 7 rows for the cockpit view, and leaves a gap. The subroutine MODDLST fills that gap at run time from a table of display-list fragments (DLSTFRAG) to show or hide the title line, the per-view header and the Control Panel Display at the bottom. To avoid glitches, it first waits until VCOUNT reaches 124, the bottom of the playfield, before changing anything.
The Galactic Chart has its own list, DLSTGC, of GRAPHICS 1 and 2 text rows (ANTIC modes 6 and 7), with DLIs on two blank-line instructions that switch between the custom-font map and the ROM-font text below it.
6. The 3D star field: projection and Minsky rotation
Two routines do the 3D work.
PROJECTION ($AA21) computes x/z × 128 with an 8-step shift-and-subtract division. The quotient (0–255) indexes MAPTO80, a table built at start-up that turns it into a pixel offset of 0–80 from the screen centre. Division by zero or overflow returns 255 as an "off-screen" marker.
ROTATE is the most famous piece of the program. Turning the ship rotates every object around the ship. There are no sine or cosine tables. For a left turn, each object's coordinates are updated as
x := x + z / 64
z := -x / 64 + z
with the new x used in the second line. Division by 64 is just shifts, and using 1/64 for the sine and 1 for the cosine gives a fixed step of about 0.89° per game loop. Feeding the new x into the z calculation isn't a bug: it makes the transform's determinant exactly 1. This is the "Minsky rotation" from MIT's HAKMEM (item 149, 1972), which keeps rotating points on stable orbits instead of spiralling outwards.
Colour and size give the depth cues. Player shapes are picked from a table of "shape cells" by a range index (0–15) derived from the z coordinate, and both players and star pixels take their brightness from the same range index through FOURCOLORPIXEL.
7. The Galactic Chart, Zylon strategy and damage
The galaxy is GCMEMMAP, 16 columns × 8 rows of sector bytes. At game start, INITIALIZE blocks out the ship's starting sector and then places the sector types (starbase, 4-, 3- and 2-or-1-Zylon groups), mission level + 2 of each. Starbases never go on the border or next to an occupied sector.
The strategic AI lives at the end of each iteration in FLUSHGAMELOOP. Every 8 iterations the Zylon units choose a starbase to hunt. Each unit is given a chance to move based on its size (the source's table gives 100% for one- and two-ship groups, 75% for three and 13% for four). A unit that moves calculates the "block distance" to the target from each of its 8 neighbouring sectors and moves to the first one that is closer, empty, inside the chart and not occupied by your ship. A starbase with Zylons in the sectors to its north, east, south and west is destroyed, replaced by a 2-Zylon sector, and costs you 18 points.
DAMAGE runs when a Zylon torpedo hits. The chance of damage depends on the mission level: 0 out of 256 for NOVICE, 80 for PILOT, 180 for WARRIOR and 254 for COMMANDER. It then picks one of six subsystems, the PESCLR of the status line (Photons, Engines, Shields, Computer, Long-range scan, Radio). A torpedo with 30 or more game-loop iterations of lifetime left destroys the subsystem rather than just damaging it, and the letter turns yellow (damaged) or pink (destroyed).
8. Bugs and oddities to look for
The flagged bugs make good exercises: a loop bound of 144 that should be 147 in the velocity update, a CMP #3 in the VBI that would read more clearly as #2, and the VBI entering demo mode with a JMP that never pops the registers it pushed. Each comes with a suggested fix. Keep an unmodified build for comparison.
9. Rebuilding the cartridge
Wiest's file is written for MAC/65. He assembled it on an emulated Atari running MAC/65 and got a binary identical to the cartridge. If you prefer a cross-assembler, the Mad-Assembler (MADS) distribution includes a converted copy, examples/games/star_raiders/StarRaiders.asm. Its changes are mechanical: opt h- (no executable header), ORG $A000 instead of *= $A000, | for OR instead of !, LSR @ instead of LSR A, and labels moved onto their own lines in front of data blocks. To build it:
mads StarRaiders.asm -o:sr.rom
atari800 -cart sr.rom -cart-type 1
The MADS build is an 8,192-byte image identical to the original ROM. It runs as a standard 8 KB cartridge (the Galactic Chart above is from it). In Altirra, use File > Attach Cartridge. Because it's an exact rebuild, you can experiment safely: change a value, rebuild, and compare the binaries. With a label file (-t:sr.lab) loaded into Altirra's debugger, bp ROTATE or bp DAMAGE lets you watch these routines run.
Troubleshooting
- The emulator asks for a cartridge type. Raw
.romfiles carry no header. Choose the standard 8 KB cartridge (atari800 type 1). - MADS reports errors on the GitHub file. That file is MAC/65 syntax. Use the MADS-converted copy, or make the conversions listed above.
- Your modified build crashes at start-up. Check that your edit didn't push code past the cartridge's end at $BFFF or move data the code assumes is fixed. Compare the label files.
Further reading
- Lorenz Wiest, "Reverse Engineering Star Raiders", PoC||GTFO 0x13 (October 2016), pages 5–20.
- The Atari BASIC Source Book (COMPUTE! Books, 1983), the commented-ROM book that inspired Wiest's project.
- De Re Atari (Atari, Inc., 1982): display lists, DLIs and player/missile graphics.
- The scanned original Star Raiders source listing on the Internet Archive ("Atari Star Raiders Source Code").
- Mapping the Atari by Ian Chadwick (COMPUTE! Books).
Credits
- Picture: The Galactic Chart from a ROM rebuilt with MADS from the documented source. The PESCLR letters are the damage-control readout. — Program authors; screenshot by the site
- Lorenz Wiest — StarRaiders (GitHub): README — Lorenz Wiest; GitHub project authors
- Lorenz Wiest — StarRaiders.source.asm.txt (reverse-engineered, documented source; MAC/65 syntax) — Lorenz Wiest; GitHub project authors
- Lorenz Wiest — StarRaiders.source.txt (assembler listing output) — Lorenz Wiest; GitHub project authors
- Mad-Assembler examples — games/star_raiders/StarRaiders.asm (MADS conversion) and StarRaiders.rom — GitHub project authors
- Internet Archive — Atari Star Raiders Source Code (scans of the original listing) — Internet Archive
