Overview

In my increasingly-distant youth, my family had a Dragon 32 home computer, which I spent many hours with. For a lot of this time, I was writing programs of various kinds, with the built-in Basic and then also assembly language. But, unsurprisingly, I also played games, including one called Invader’s Revenge, written by Kenneth Kalish. You control a yellow ship, and have to shoot enemy “defender” ships while not crashing into anything or being shot by the enemy base. Good fun.

In my current job, I am developing and researching Pytch, a free online educational coding platform which helps people learn Python by writing “Scratch-like” programs. I thought a port of Invader’s Revenge could be a good example of what can be made in Pytch.

I could probably have achieved this by taking screenshots and working out the game logic just by observations, but thought it would be a more interesting exercise to reverse engineer the original machine code. This would also allow a dose of nostalgia for the Dragon and working in assembly language, albeit someone else’s.

Pytch version

This is the result. You can play it below, or “see inside” by opening the project within the Pytch IDE.

Annotated disassembly

The starting point was a 7525-byte raw binary dump of the game from its cassette audio. (I do own this cassette, but got the image from the web to save time.) Using a combination of existing tools and various bits of ad-hoc Python code, I produced what I hope is a reasonably readable disassembly of the game’s code and data.

; Turn next mask byte into red/blue
; detect mask
  LDB  ,U+
  ASLB

; If the player overlaps with something
; red or blue...
  ANDB ,X
; ...they have hit a defender or defender
; shot; chain to handler
  LBNE  Sub_HandlePlayerCrash

; Mask out yellow from destination byte
  LDB  ,X
  ANDB #$AA
  STB  ,X+

Result

Code and data are shown with different background colours. Subroutines are cross-linked, to make them clickable at call sites. Chunks of data which represent graphics are rendered.

• Disassembly — about 3.5k lines of 6809 assembly language.

Observations

Various features of the code struck me as interesting:

• No pseudo-random numbers. Although the behaviour of the defenders seems random, there are not even any pseudo-random numbers involved. The random-looking behaviour emerges from the deterministic logic for starting new defender patrols.
• Interleaved code and data. The lump of machine code is not neatly divided into data and code. Code is interspersed with data; sometimes a variable appears in the middle of the code for the subroutine it is used in.
• Fine-grained movement for the player ship. The defenders move horizontally by four pixels at a time, allowing simpler code because four pixels are stored in one byte of video memory. The fact that the defenders move in four-pixel steps is part of the style of the game. But the player ship can move at a two-pixel resolution, and has two different bitmaps (“right position” and “left position”) to support this.
• Inventive use of the system stack. I saw a few nice examples of manipulating values stored on the system stack, for example overwriting a saved value, multiplying by three, and saving a RTS opcode by pulling the program counter in the same instruction as restoring a saved register.
• Seemingly unused variables. There are a few locations which are written to but, as far as I could tell, never read from, so their purpose is unclear to me. There are other locations which are, as far as I can tell, completely unused.
• Seemingly unused graphics. There are some bytes near the start which can be interpreted as a small defender-like graphic. Maybe there were plans to use this as another “special” defender?
• Fall-through code. In a few places, one subroutine “falls through” into another. Another way of thinking of this is that some routines have multiple entry points.
• Collision detection via colours. In some situations, the code determines the game state by reading the video display memory, rather than with reference to stored program data. The code looks for the presence of, say, a defender, by looking for pixels which are either blue or red. I suspect the choice of this colour scheme was influenced by the fact that the two-bit codes for blue and red are 10 and 11 respectively, allowing a simple bitwise-and test for defender-coloured pixels.
• Split responsibility for destroying defenders. As far as I can tell, the job of destroying a defender when a player’s shot hits it is split between the subroutine which moves the shots, and the subroutine which moves the defenders. This all seems quite intricate but I expect is the best fit for the data structures used and the time constraints the code works under.
• Timekeeping with delays or sounds. Each update usually ends with a do-nothing delay loop, which gets shorter as the player gets more points, speeding the game up. But when a sound effect is playing, bit-banging the audio output serves the dual purpose of creating the delay, so the do-nothing loop is skipped. The sound effects have to match the dynamic delay, so the sound effects get more frantic as the game speeds up — this counts as a feature I think.
• Score stored in Binary Coded Decimal. The player’s score is stored in units of 100 points, as a four-digit BCD (16-bit) value. The code uses the special 6809 instruction DAA (for Decimal Adjust after Addition) for arithmetic with BCD values. The logic for awarding an extra life each 10,000 points falls out in a pleasingly simple way from this representation.
• Differing basic block layout. Code which in a high-level language would be an if/else is laid out differently in different places. Sometimes one of the blocks is “inline”, and other times both the if and the else arms are separate and jumped to and from.
• Iteration over arrays. Sometimes this is done by counting how many entries remain to be processed, and other times by comparing the record pointer with the “one past the end” value.
• Looping and sequencing split over updates. The fundamental logic implemented by the code which animates the result of a defender shot hitting something is reasonably straightforward. However, the code has to carefully track progress through the logic with an explicit state value, because it has to do a small piece of work each time it is called. This makes the code more complex.
• Partially-written single joystick mode? There is some duplicated state for recording whether the game is in one- or two-player mode. Different variables are used in the logic for player state vs the logic for selecting which joystick to read. Perhaps there were plans to allow two players to play a two-player game where only one joystick was used?
• Use of illegal opcode. At one point, in code which seems to be resetting the “number of shots” game parameter, the opcode 8F is used, which is not a valid 6809 opcode. It is reported as having a deterministic effect (store X immediate), but I did not get to the bottom of the effect on the game logic.
• Stack leak. The code which implements the timeout when prompting the user for the speed and number of shots leaks two bytes of stack, because it does a JMP to the reset routine even though conceptually it is a subroutine. This was suspected by code inspection and verified under GDB. Compare the care taken in a similar situation in the end-of-game code.
• Unused slot for defender explosion data? There is space reserved for up to ten defender explosions. However, the code which processes this array seems to only handle the first nine entries — it initialises a counter to 10 then, in each iteration, decrements this counter and then tests it for being non-zero. I wasn’t able to verify this behaviour in play though.
• Large unused section of memory image. The cassette memory image has a 602-byte section (out of a 7,525-byte image) of meaningless values, as far as I can tell. Perhaps this came about from a development process which made it difficult to mode large blocks of code or data, and so space had to be reserved?

Methods used while reverse-engineering

I had heard of, and wanted to try, the special-purpose reverse-engineering disassembler IDA, but the free version does not support the 6809 processor. Only too late did I discover the free-software Cutter, based on Rizin, which does support the 6809. This might be worth exploring if I do something like this again.

The tool I ended up using was f9dasm. As well as the binary machine-code dump, you supply a separate file of annotations and other directives. The f9dasm tool then disassembles the machine code according to your directives and annotations. I added a post-processing step, implemented as a collection of ad-hoc Python scripts, to break the disassembly into “chunks” for more readable rendering in HTML. A “chunk” is a subroutine or a piece of data.

The whole process was highly iterative. The starting point was to trace execution from the entry-point address, and then go round and round with a mixture of the following activities.

• Identify a subroutine or block of data.
• Decode a block of data representing a graphics sprite.
• Conjecture the fields of a data structure.
• Conjecture the semantics of a variable.
• Conjecture what a particular subroutine did with variables or overall machine state (e.g., display or sound).
• Make or refine notes and comments on a subroutine, variable, or data structure.
• Refer to Dragon 32 ROM information (either Inside The Dragon or this disassembly)
• Give a name to a subroutine or piece of data.
• Write some more ad-hoc Python code.

Understanding a variable or data structure was the most important and helpful task. It was not always immediately obvious (to me) what role a particular variable had, so making a conjecture and then refining it was quite common.

Looking for sections of code which write to video memory was a helpful technique, because by noting where the data was read from, I could tell whether that section drew the player ship, a defender ship, etc.

Almost all of the work was done just by looking at the code, although for a handful of tricky parts I used the XRoar emulator, and its ability to act as a debug target for a custom build of the GNU Debugger. In particular, I decided that working out the exact waveform of a sound effect from the code was too much work; see below.

Port to Pytch

Graphics layout

The Dragon and Pytch screen dimensions differ. The Dragon, in the graphics mode used, has a 128×192 pixel grid, with each pixel twice as wide as it is high. The Pytch “stage” is 480×360.

In broad terms, the game layout has an upper score/display area, and a lower play area, separated by a pair of thin red bars. The Dragon also has a fairly broad border round the active display area. I drew a static background image which I hope is a reasonable replication of the overall effect.

The defenders patrol in horizontal “lanes”. I tried to get a close match to the spacing of these lanes, including a gap such that the player cannot be hit at a particular vertical position. This is coupled with the graphics design in terms of the dimensions of the sprites; see below.

Movement

The horizontal “stepping” motion of the defenders and their base is part of the aesthetics of the design, so I kept that. In the Dragon original, the player ship has finer-grained movement; in the port I allow it to move with single-pixel resolution.

Graphics

To keep things on an integer grid, the sprites had to be different sizes to the originals. I redrew them by hand with reference to the originals, trying to keep the look and feel of images, but I did have to make some changes. In some cases I used the higher resolution available. For some explosion graphics, the original was not symmetrical; here I drew symmetrical versions, although I’m not sure whether this was the right thing to do.

Example of a higher-resolution sprite:

Sounds

From inspection of the code, it was possible to tell that each sound effect consists of a sequence of “chirps” — short fragments of rising or falling pitch. However, replicating the sound effects based on the code would have required an exact understanding of the timing of the instructions used, so I took a different approach.

Running the game under the XRoar emulator, I captured the sound effects. Analysing the sounds in Jupyter Lab, and using regression to estimate the starting pitch and rate of change of pitch for each chirp, allowed them to be re-synthesised. On the Dragon, the output waveform is essentially a square wave. In the re-synthesis, I used something slightly more rounded. This gives a softer sound, which I think I’m happy with.

Example of captured vs re-synthesised sound effect:

Code

With the understanding of the game logic gained from the reverse engineering, I was able to write event-driven Python code in Pytch to give (something very close to) the same behaviour. In some cases, such as stepping through the phases of a defender explosion, the concurrency provided by Pytch made the code much simpler.

Differences

The Pytch port is not a perfect re-creation. The main differences in the Pytch version are:

• The player has to use the keyboard; there is no joystick support — although see below.
• Only one player can play.
• The initial speed is fixed, and the player always has five shots.
• No high-score is maintained.
• The game plays once and then stops. You have to click Pytch’s “play” button to have another game.
• There is a sound effect when you gain an extra ship at multiples of 10,000 points.

Hardware controller

We have an experimental version of Pytch which can interface with hardware via the GPIO pins on a Raspberry Pi. In this version, you can play Invader’s Revenge with an arcade-style joystick and fire button.

Conclusions

I ended up getting drawn into this project rather more than I originally planned, but the result was a full understanding of almost all of the code of the game. Porting the code to Pytch was an interesting exercise, and the resulting game is fun to play.

Links

• GitHub source, including ad-hoc Python code
• Interview with the game’s author, Ken Kalish
• Cobra: A game my Dad and I wrote on the Dragon 32.
• Dragon 32 ROM disassembly
• Inside the Dragon book