Star Raiders Source Code by Lorenz Wiest
Total Page:16
File Type:pdf, Size:1020Kb
Star Raiders source code by Lorenz Wiest# Lorenz Wiest did a tremendous must see job with a complete commented Star Raiders source code at the highest level possible! Highly recommended!!! Every assembly source code should look like this. The reader can take his work as a template on how to do it the right way! Source Code in TXT-Format# • StarRaiders.source.txt ; size: 840 KB ; incredible source code listing with assembled hex bytes!!! A must see!!! • StarRaiders.source.asm.txt ; size: 644 KB ; incredible source code listing without assembled hex bytes, ready to use in an assembler!!! A must see!!! Read Me from Lorenz Wiest# Reverse engineered and fully documented STAR RAIDERS source code STAR RAIDERS is a seminal computer game, published by Atari Inc. in 1979 as one of the first titles for the original Atari 8-bit Home Computer System (Atari 400 and 800). During the last years, as a hobby afterhours project, I reverse engineered a complete, extensively documented assembly language source code of STAR RAIDERS. I reverse engineered the source code directly from the binary file of the ROM cartridge, finishing it in September 2015. This repo contains both the reverse enginered assembly source code input StarRaiders.source.asm.txt and output StarRaiders.source.txt. You may find this useful if you are curious about the internals of STAR RAIDERS or if you are planning to make your own, modified version. After very positive reader feedback on the initial release of my reverse engineered source code I reviewed it again, resulting in a minor update. Enjoy -- Lorenz P.S. I was absolutely thrilled to learn that in October 2015 scans of the original STAR RAIDERS source code re-surfaced. To my delight, inspection of the original source code confirmed the findings of my reverse engineered version and caused only a few trivial corrections. Even more, the documentation of my reverse engineered version adds a substantial amount of information - from overall theory of operation down to some tricky details - to the understanding of the often sparsely commented original (quite expected for source code never meant for publication). So, if you are interested in learning how STAR RAIDERS works, my reverse engineered source code could be of help to you. Extras# Genome Sequence# The picture below shows the 'genome sequence' of the reverse engineered STAR RAIDERS 8 KB ROM (which I prepared for a publication. I stacked the 8192 bytes vertically, with each byte represented by a tiny, solid horizontal line of 8 pixels. Then, I split the stack into strips of 192 bytes, arranged side-by-side. The segments of the stack are color-coded: • Code (main game loop and subroutines) is in alternating shades of blue. • Data (lookup tables, texts, etc.) is in alternating shades of green. • Bitmap data (Player-Missile shapes and character set) is in alternating shades of purple and the solid line of a byte is replaced by its actual bit pattern. STAR RAIDERS 8KB ROM Genome Sequence ; thank you so much Lorenz, that is totally incredible! :-) ColorSheets# • STAR RAIDERS Color Sheets ; size: 250 KB DisplayListSheets# • STAR RAIDERS Display List Sheets ; size: 250 KB References# • Original post of the source code • AtariAge Forum - Fully documented, reverse-engineered STAR RAIDERS source code available • Link at github of the source code • Wikipedia 'Star Raiders' • ANTIC The Atari 8-bit Podcast • Star Raiders Tribute Page • Brainwagon - Deconstructing the Classic Atari Game: Star Raiders • Article 'Reverse Engineering Star Raiders', PoC GTFO 0x13, p. 5-20, October 2016 Source Code Listing# 00001 ;******************************************************************************* 00002 ;* * 00003 ;* S T A R R A I D E R S * 00004 ;* * 00005 ;* for the Atari 8-bit Home Computer System * 00006 ;* * 00007 ;* Reverse engineered and documented assembly language source code * 00008 ;* * 00009 ;* by * 00010 ;* * 00011 ;* Lorenz Wiest * 00012 ;* * 00013 ;* (lo.wiest(at)web.de) * 00014 ;* * 00015 ;* First Release * 00016 ;* 22-SEP-2015 * 00017 ;* * 00018 ;* Last Update * 00019 ;* 10-DEC-2016 * 00020 ;* * 00021 ;* STAR RAIDERS was created by Douglas Neubauer * 00022 ;* STAR RAIDERS was published by Atari Inc. * 00023 ;* * 00024 ;******************************************************************************* 00025 00026 ; I wrote this document out of my own curiosity. When STAR RAIDERS was released 00027 ; in 1979 it became the killer app for the Atari 8-bit Home Computer System. 00028 ; Since then I have always been wondering what made it tick and how its (at that 00029 ; time) spectacular 3D graphics worked, especially the rotating star field. 00030 ; Impressed by "The Atari BASIC Source Book" I decided to reverse engineer the 00031 ; STAR RAIDERS 8KB ROM cartridge to recreate a fully documented assembly 00032 ; language source code file. I had no access to the original source code, so the 00033 ; only way to succeed was a combination of educated guesses, trial-and-error, 00034 ; and patience. Eventually, I made it. 00035 ; 00036 ; Essential in preparing this document were three programs I wrote: 00037 ; 00038 ; (1) A 6502-cross-assembler based on the syntax of the MAC/65 assembler for the 00039 ; Atari 8-bit Home Computer System to create the binary file that I verified 00040 ; against the binary of the original ROM cartridge. 00041 ; 00042 ; (2) A text formatter to layout the source code file with its copious comment 00043 ; sections. This was a big time saver, because as the documentation grew the 00044 ; source code had to be reformatted over and over again. 00045 ; 00046 ; (3) A symbol checker to verify that the ubiquitous symbol-value pairs in the 00047 ; documentation match the corresponding symbol values produced by the 00048 ; assembler. 00049 ; 00050 ; This assembly language source code file is compatible with the MAC/65 00051 ; assembler for the Atari 8-bit Home Computer System. I was able to assemble it 00052 ; on an emulated Atari running MAC/65, producing the identical binary of the ROM 00053 ; cartridge. 00054 ; 00055 ; Your feedback is welcome! Send feedback to lo.wiest(at)web.de. 00056 ; 00057 ; Enjoy! -- Lorenz 00058 00059 ;******************************************************************************* 00060 ;* * 00061 ;* N O T A T I O N * 00062 ;* * 00063 ;******************************************************************************* 00064 00065 ; BITS AND BYTES 00066 ; 00067 ; o A "byte" consists of 8 bits. They are numbered B7..0. Bit B0 is the least 00068 ; significant bit. 00069 ; 00070 ; o A "word" consists of 16 bits. They are numbered B15..B0. Bit B0 is the 00071 ; least significant bit. A word is stored in low-order then high-order byte 00072 ; order. 00073 ; 00074 ; o The high-order byte ("high byte") of a word consists of bits B15..8 of the 00075 ; word. 00076 ; 00077 ; o The low-order byte ("low byte") of a word consists of bits B7..0 of the 00078 ; word. 00079 ; 00080 ; NUMBERS 00081 ; 00082 ; o The dollar sign ($) prefixes hexadecimal numbers. 00083 ; Example: $101 is the decimal number 257. 00084 ; 00085 ; o The percent sign (%) prefixes binary numbers. 00086 ; Example: %101 is the decimal number 5. 00087 ; 00088 ; o The asterisk (*) is a wildcard character for a single hexadecimal or 00089 ; binary digit. 00090 ; Example: $0*00 is a placeholder for the numbers $0000, $0100, ..., $0F00. 00091 ; 00092 ; o The lowercase R (r) is a wildcard character for a single random 00093 ; hexadecimal or binary digit. The random digit r is chosen by a random 00094 ; number generator. 00095 ; Example: %00r0 is a placeholder for the numbers %0000 or %0010. 00096 ; 00097 ; OPERATORS 00098 ; 00099 ; o The exclamation mark (!) is the binary OR operator. 00100 ; Example: $01!$02 is $03. 00101 ; 00102 ; o The less-than sign (<) indicates bits B7..0 of a word. 00103 ; Example: <$1234 is $34. 00104 ; 00105 ; o The greater-than sign (>) indicates bits B15..8 of a word. 00106 ; Example: >$1234 is $12. 00107 ; 00108 ; o A pair of brackets ([]) groups mathematical expressions. 00109 ; Example: [3-1]*4 is 8. 00110 ; 00111 ; ASSEMBLY LANGUAGE 00112 ; 00113 ; o The uppercase A (A) indicates the accumulator register of the 6502 CPU. 00114 ; 00115 ; o The uppercase X (X) indicates the X register of the 6502 CPU. 00116 ; 00117 ; o The uppercase Y (Y) indicates the Y register of the 6502 CPU. 00118 ; 00119 ; o The prefix uppercase L and dot (L.) indicates a local variable, a memory 00120 ; location used temporarily in a subroutine. 00121 ; 00122 ; PSEUDO-FUNCTIONS 00123 ; 00124 ; o The function ABS(<num>) returns the absolute value of <num>. 00125 ; Example: ABS(3) returns 3. 00126 ; Example: ABS(-3) returns 3. 00127 ; 00128 ; o The function RND(<num1>..<num2>) returns a random integer in 00129 ; <num1>..<num2>. 00130 ; Example: RND(3..5) returns a random number out of 3, 4, or 5. 00131 ; 00132 ; o The function MAX(<num1>,<num2>) returns the larger number of <num1> and 00133 ; <num2>. 00134 ; Example: MAX(2,4) returns 4. 00135 ; 00136 ; VECTORS 00137 ; 00138 ; o The lowercase X (x) indicates the x-axis of the 3D coordinate system. 00139 ; 00140 ; o The lowercase Y (y) indicates the y-axis of the 3D coordinate system. 00141 ; 00142 ; o The lowercase Z (z) indicates the z-axis of the 3D coordinate system. 00143 ; 00144 ; o Components of a position vector (called "coordinates") have the arbitrary 00145 ; unit <KM> ("kilometers"). 00146 ; 00147 ; o Components of a velocity vector have the arbitrary unit <KM/H> 00148 ; ("kilometers per hour"). 00149 ; 00150 ; o A positive component of a position vector (coordinate) in hexadecimal 00151 ; notation is written in the form +$<hexNum> <KM>. <hexNum> is an unsigned 00152 ; integer value. 00153 ; Example: The starbase is +$1000 (or 4096) <KM> ahead of our starship. 00154 ; 00155 ; o A negative component of a position vector (coordinate) in hexadecimal 00156 ; notation is written in the form -($<hexNum>) <KM>. <hexNum> is an unsigned 00157 ; integer value. To calculate the actual bit pattern of this coordinate 00158 ; value compute the two's-complement of <hexNum>.