Jetpac annotated disassembly released

[mrcook]

Hi All,

I've decided to make my annotated disassembly of Ultimate's Jetpac public over on github: https://github.com/mrcook/jetpac-disassembly

I'd always fancied my hand at disassembling an old game from my childhood, and in 2018 I decided to jump in and give it a go. After a couple of false starts with other games - and realising just how much work is involved in such an endeavour - I decided to take on Jetapac (the 16K cartridge version).

Over 230 hours later I had a fully annotated disassembly of the Jetpac game!

I don't know much about writing games in assembly, but the source code is certainly neat, tidy, and very well organised. I guess the Stamper brothers knew how to code!

I had grand ideas of porting this to other systems - I even made a start refactoring to pull out the IO code so that I could create a cross-platform version. But, well, life kinda got in the way. So instead, I'm releasing the original disassembly.

Cheers,
Michael

[Cosmium]

Fascinating! Thanks for doing this

I remember back in the day I tried a few (failed) attempts to disassemble this on the Spectrum itself, and gave up after a while because it seemed quite impenetrable, so hats off to you for sticking with it!

[mrcook]

I'm not sure I would've made it through this myself if it was not for the skoolkit project!

Also, once I'd figured out the basic structure of the code using skoolkit I went and spent €10 on getting it printed. I could then chip away at this during my lunch breaks to get to a first draft disassembly, before going back to skoolkit. It was a really relaxed approach.

[Morkin]

Nice stuff..! I think [mention]pobtastic[/mention] has been doing Jetpac as well?

Maybe worth getting a link up on the Skoolkit links page?

[mrcook]

Spectrum 128K fix

I had an email from a chap called Allan with a fix for running the game in 128K mode. I've not tested it myself, be he assures me it works:

Code: Select all

// jetpac.skool
- $7326 out ($fd),a   ; Set port for reading keyboard
+ $7326 nop
+ $7327 nop

Also while I'm here posting. Back in 2018 after the main disassembly was complete, I had a play around with replacing the original menu screen with the splash screen:



I envisaged this being useful for a Sega Master System port.

[ZXOxo67]

Very nice, is there a patchfile?

[mrcook]

I made this using the code from my half-done Amstrad port, so I'm afraid it's not possible to patch the disassembly. It was only experimental code so would need re-doing anway.

[pobtastic]

Nice stuff..! I think @pobtastic has been doing Jetpac as well?

Maybe worth getting a link up on the Skoolkit links page?

Mine is nowhere near as complete as this! I've mainly been doing mine as I'm recreating it for FUZE and I wanted to utilise similar techniques (hence, I probably won't ever finish it).

I've also got a bit of Wheelie and Harrier Attack done for the same reasons.

[mention]mrcook[/mention] this looks like very nice work! Well done!

[mrcook]

Many thanks [mention]pobtastic[/mention], it was an enjoyable adventure and I learned a lot from it.

[Quazar]

Impressive work, I had a look through the .skool file to see what comments you had for a few parts of Jetpac as I had to disassemble this last year to fix a few issues, so curious on your take of a few things.

I'm stumped by your description of this OUT in various places:

out ($fd),a ; Set port for reading keyboard

as port $fd isn't used for keyboard reading. It's not a valid port on the 16k/48k ZX Spectrums and used for memory control on the 128K onwards (I see for your 128k fix you patch one with NOPs, but not them all). The IN instruction after that OUT handle setting A0-A15 to read the keyboard correctly - with the current value of A setting A8-A15 and $fe being A0-A7.

The reason I came across this, is that when making an interface to use the ZX ROM cartridges on the SAM Coupe last year I had to add code to patch the Ultimate cartridges to remove all the out($fd),a instructions (in JetPac, Tranz Am, Cookie and Pssst). On the SAM, port $fd is used for MIDI-OUT so these instructions trigger unwanted interrupts messing the games up with various crashes/timing issues.

... why did Ultimate do this unneeded instruction all the time, just causes problems

[cmal]

Great job MrCook. I'm looking forward to delving into the disassembly. I once tried to disassemble Starquake with the Spectacular debugger and pen & paper and got absolutely lost!

[Seven.FFF]

... why did Ultimate do this unneeded instruction all the time, just causes problems

They had some cross-development system which allowed them to assemble the code on another computer, and send it up to the wire to the Spectrum, and then remotely debug from the other computer. Port $7d, being unused on the 16K and 48K Spectrums before the 128K models were invented, was how they interfaced and controlled the Spectrum side of the debug hardware. It only started causing problems when the 128K model was invented.

They really shouldn't have left the debug instructions in the release versions of the games though, if they were practicing defensive coding (they weren't). A while back I did a similar thing with the Parasys remote debug hardware. The code I left in checks the serial port to see if there is a byte ready to be received. Without a debugger attached there should never be any bytes to be received, but I found if I left my game running overnight, sometimes there was random electrical noise picked up that caused the code to wait for a byte that never arrived, so my game would very occasionally hang.

[Ast A. Moore]

I found if I left my game running overnight . . .

Holy smokes, Robin. That’s some rigorous software testing right there.

[Quazar]

They had some cross-development system which allowed them to assemble the code on another computer, and send it up to the wire to the Spectrum, and then remotely debug from the other computer. Port $7d, being unused on the 16K and 48K Spectrums before the 128K models were invented, was how they interfaced and controlled the Spectrum side of the debug hardware. It only started causing problems when the 128K model was invented.

Ah ha! Thanks for explaining!

[XoRRoX]

[mention]mrcook[/mention] Wow - very nice Thanks so much for doing and sharing this

Seeing recent comments regarding the out ($fd),a, could you update the listing to reflect this so others aren't thrown off by it?

[Nienn Heskil]

Port $7d, being unused on the 16K and 48K Spectrums before the 128K models were invented, was how they interfaced and controlled the Spectrum side of the debug hardware.

Doubt it. They use OUT (#FD),A in very specific spots - reading the keyboard, just before an IN A,(#FE), with 'A' holding the keyrow byte. You can see this picture in all of their early games (Tranz Am, Jetpac, Cookie, Pssst, Jetman, even Knight Lore). It seems more likely that they simply had incorrect info in regards to how keyboard reading is done on the Spectrum, thinking you were first supposed to OUTput the keyrow byte to #FD.

[mrcook]

Thanks for all the feedback!

I should clarify that before I started this disassembly I had no prior experience with assembly on any system. This project was a way for me to learn a little more about it so there's likely plenty of mistakes and misunderstanding on my part

I'm stumped by your description of this OUT in various places

I just thought it was another way to read the keyboard, and figured the brothers knew what they were doing

They had some cross-development system which allowed them to assemble the code on another computer, and send it up to the wire to the Spectrum, and then remotely debug from the other computer.

Considering this was 1982/83 I'd be surprised if they had any kind of remote debugging. I'm sure it'd be just a case of squirt the code to the speccy, manual test, rinse and repeat.

They use OUT (#FD),A in very specific spots - reading the keyboard, just before an IN A,(#FE), with 'A' holding the keyrow byte. You can see this picture in all of their early games (Tranz Am, Jetpac, Cookie, Pssst, Jetman, even Knight Lore). It seems more likely that they simply had incorrect info in regards to how keyboard reading is done on the Spectrum, thinking you were first supposed to OUTput the keyrow byte to #FD.

Sounds plausible considering there would have been very little developer docs around at the time. It also seems there are differing ideas on what this OUT is doing so I'll leave the annotations as-is for now, until there is a definitive answer.

Seeing recent comments regarding the out ($fd),a, could you update the listing to reflect this so others aren't thrown off by it?

I don't see any option for editing posts on this forum, but I will try to clarify the README on github.

Cheers,
Michael

[XoRRoX]

[mention]mrcook[/mention]
I meant the source listing on github;)

[uglifruit]

[mention]mrcook[/mention] This is very interesting.
How hard would it be to reassemble Jetpac into uncontended memory, I wonder - and would there be an appreciable speed boost.

[D-Type]

Is the HTML disassembly hosted online anywhere or do I have to install SkoolKit? (Which I don't really want to do, but if needs must I will. I'm currently using dasmfw for 8-bit reverse engineering, but it's Motorola/6502 family.)

Thanks!

[mrcook]

Is the HTML disassembly hosted online anywhere

I never generated the HTML stuff. Except for a few formatting niceties I think opening the .skool file in an editor is more useful, and easy to navigate.

You don't need to install Skoolkit, unless you really want those HTML docs, or need to build a tape file.

[Joefish]

@mrcook This is very interesting.
How hard would it be to reassemble Jetpac into uncontended memory, I wonder - and would there be an appreciable speed boost.

The cartridge version is effectively running from uncontended memory (the ROM space). I don't know if that appears to run any faster, or has been deliberately slowed down. May be worth comparing the code from the cartridge with that from the cassette version.

[mrcook]

The cartridge version is effectively running from uncontended memory (the ROM space).

The whole game is copied to RAM first. Here's the loader from the start of the ROM:

Code: Select all

$0000 di
$0001 ld a,$3f
$0003 ld i,a
$0005 ld sp,$5cf0
$0008 im 1
$000a ld hl,$2000
$000d ld de,$4000
$0010 ld bc,$1b00
$0013 ldir
$0015 xor a
$0016 out ($fe),a
$0018 out ($fd),a
$001a in a,($fe)
$001c cpl
$001d and $1f
$001f jr z,$c01a
$0021 ld hl,$004d
$0024 ld de,$6000
$0027 ld bc,$2000
$002a ldir
$002c jp $6000

First the splash screen, then the game code.

The game also utilises self-modifiying code (the NewActor routine at address $6971), so needs to live in RAM.

[Alessandro]

I like these Skoolkit disassemblies when they come as formatted HTML and are available with decimal numerals. Much easier to read and to understand for Assembly semi-literates like yours truly

[Lethargeek]

I like these Skoolkit disassemblies when they come as formatted HTML and are available with decimal numerals. Much easier to read and to understand for Assembly semi-literates like yours truly

blasphemer! loathsome decimal heresy (except counters) in z80 disassembly must be eradicated with fire!