BBC Elite source, now fully documented and explained

[MarkMoxon]

Hi all.

I'm pretty excited to be able to tell you about my latest project, which has just reached the point where it may be of interest to others. Consider this a bank-holiday present of sorts...

In the following repository you can find fully documented, fully buildable and (for the most part) fully explained source code to Elite on the BBC Micro:

https://github.com/markmoxon/elite-beebasm

I don't think Elite has been analysed to this extent before, and it's been fascinating to explore the source code in this level of detail. Not only is every single bit (literally!) documented in full, but there are various deep dives peppered throughout, explaining everything from the game's procedural generation to ship tactics.

Have you ever wondered how the iconic scanner in Elite works? Or how the game manages to draw such complex 3D shapes so quickly? Or how the split-screen mode does its stuff? Or how the game knows the difference between a successful docking and a fatal faceplant? Or exactly how much free memory is left in a standard BBC Micro when Elite is running? If so, then you might find this interesting.

The idea is that anyone with a vague knowledge of 6502 assembly language and rudimentary trigonometry should be able to follow the commentary - I've tried to keep it as simple as possible while still explaining everything that I can. I'm hoping that it will help others appreciate the beauty and brilliance of this landmark 8-bit game.

The README on the above URL explains everything. It's been an absolute joy to wander through the Elite source code, trying to understand what makes it work, and I hope you like the results. What a great lockdown project it's been.

Note that this is not a finished project - far from it! For a start, the commentary needs tidying up and clarifying in places; as it stands, this whole thing is basically a first draft that needs a fair amount of editing. There are one or two areas where the code is documented in terms of explaining what the code does, but I'm still trying to get my head around exactly how it works, so those areas still need addressing.

I'm also planning to turn this repository into a more navigable website, as well as extending it to cover the disc and second processor versions (it only covers the tape version at the moment, for reasons explained in the README). But for now this is a first stab with a lot of rough edges, and there is still much for me to do, so please be gentle... but hopefully you'll like it.

(The README contains full acknowledgements of those whose shoulders I have stood on for this project, but I must give a particular shout out to kieranhj, whose original port of the source code to BeebAsm gave me the starting point for this project. You really inspired me, Kieran - thank you.)

Right On Commanders!

Mark

[BigEd]

Splendid and marvellous!

[Diminished]

Sounds wonderful. I'll be sure to have a good peruse when I'm not tediously vectorising disc controller die shots. :/

[julie_m]

Mmm, I'm sure there's some good stuff in there! I think I even have a use for the CRTC stunts they pulled .....

[SteveF]

I'm really enjoying looking over this. The notation for multi-byte numbers is quite cool too, I might steal that for some of my own code - is it your own invention?

[MarkMoxon]

I'm really enjoying looking over this. The notation for multi-byte numbers is quite cool too, I might steal that for some of my own code - is it your own invention?

Yes, it’s my own invention. I tried to find an existing convention for talking about multi-byte numbers but I couldn’t find anything out there, which was a real surprise - I’m still convinced I must have missed something. But the notation I came up with works pretty well for all sorts of numbers, however they are stored, so that’s good. Please feel free to pinch it!

Mark

[Snuggsy187]

Mega top work Mark...... where's the 'doff-hat' Emoticon ?!

[jms2]

This is fascinating. Brilliant work!

[0xC0DE]

Brilliant!!

[colinhoad]

Wow! Amazing! Thank you for this wonderful gift, Mark

[jms2]

Having read a bit more of this, I realise that my initial comment doesn't do it justice. You really have written an absolutely superb explanation here.

I love this kind of thing; very complicated subjects explained in a clear way. It's a joy to read, especially when so much of the technology we are surrounded by these days is explained really badly (or not at all).

[Kroc]

Hello! I'm Kroc Camen, author of the Commodore 64 disassembly of Elite, Elite Harmless. This project just shot across my bow like a giant flaming meteor! You've managed to explain all the 3D stuff that I've been struggling with for years, so I wanted to know if I could have permission to use your disassembly & comments to finish off the C64 disassembly.

My disassembly is somewhat different than others (4 that I know of, now) in that it's been split, so that you can heavily modify the game and rebuild it, even rearrange the memory-map freely. I've already enhanced the C64 port with some extra lookup tables, faster line-drawing and many other small optimisations. Like yours, the code is heavily commented, with a focus on explaining the ideas at work. If I can make use of your disassembly as an extra source, I can save literally years of work unpicking many aspects of the 3D math I've been banging my head against.

[MarkMoxon]

Having read a bit more of this, I realise that my initial comment doesn't do it justice. You really have written an absolutely superb explanation here.

I love this kind of thing; very complicated subjects explained in a clear way. It's a joy to read, especially when so much of the technology we are surrounded by these days is explained really badly (or not at all).

Thank you so much. I did wonder how understandable the explanations would be, as there are some really challenging topics in there, but this is music to my ears.

To pick one example, I wrestled with the whole rotation matrix thing for ages, before realising I could split it up into three vectors, one pointing out of the ship's nose, another out of the side and the other out of the roof. Then, all of a sudden, I found I could picture the ships orientating themselves in space in relation to everything else, something I just couldn't do with a matrix. Maths is powerful stuff, but sometimes you just have to be able to visualise what those equations actually mean...

Anyway, thanks for the kind words. It makes all the effort worthwhile to know it's being appreciated.

Mark

[MarkMoxon]

Hello! I'm Kroc Camen, author of the Commodore 64 disassembly of Elite, Elite Harmless. This project just shot across my bow like a giant flaming meteor! You've managed to explain all the 3D stuff that I've been struggling with for years, so I wanted to know if I could have permission to use your disassembly & comments to finish off the C64 disassembly.

My disassembly is somewhat different than others (4 that I know of, now) in that it's been split, so that you can heavily modify the game and rebuild it, even rearrange the memory-map freely. I've already enhanced the C64 port with some extra lookup tables, faster line-drawing and many other small optimisations. Like yours, the code is heavily commented, with a focus on explaining the ideas at work. If I can make use of your disassembly as an extra source, I can save literally years of work unpicking many aspects of the 3D math I've been banging my head against.

Hi Kroc.

Of course you can use what I've written to help with Elite Harmless - the whole point of this is to share the knowledge and help people appreciate the brilliance of the original. Besides, you're a fellow Elite disassembler, and there aren't too many of us about!

That said, coming from a publishing background, I'm retaining copyright on the commentary that I've written, mainly out of habit than for any particular reason. Attribution is always a kindness in this sort of thing, so it'd be good to know a bit more about your plans, all of which I'm sure will be absolutely fine by me.

I don't think you'll have PMs enabled with your new account, so feel free to drop me a private message via http://www.markmoxon.com and I'll be happy to email you back.

Mark

[Kroc]

I've sent you an e-mail via your site; to answer your concerns, acknowledgement is absolutely honoured. The README lists acknowledgements, as a whole, and many more are made in the code -- one thing to note is that, to appease the interests of David Braben who has taken projects down in the past, I've used a Creative Commons Non-Commercial Share-Alike licence for Elite Harmless. This means that the code is free to re-use, but to not sell, as long as attribution remains, which would include the suitable attribution for other sources such as your own disassembly. In practice, I'm not likely to use your work "as-is", I've used the acknowledged sources as additional learning resources and tend to write my own comments and documentation as I understand it myself; Elite Harmless doesn't use the original source's label or variable names et al.

[MarkMoxon]

In practice, I'm not likely to use your work "as-is", I've used the acknowledged sources as additional learning resources and tend to write my own comments and documentation as I understand it myself; Elite Harmless doesn't use the original source's label or variable names et al.

Great. Then this won't be a problem at all! Will ping you an email.

Mark

[Rich Talbot-Watkins]

Wow, just had a chance to look at this! More detail there than I could possibly have imagined - great work! And nice to confirm that it really uses the Minsky hack for rotating things in place by small angles. Will look forward to browsing through this properly when I can!

[cjpinder]

Nicely done Mark, it's very comprehensive.

Thanks,
Christian.

[kieranhj]

(The README contains full acknowledgements of those whose shoulders I have stood on for this project, but I must give a particular shout out to kieranhj, whose original port of the source code to BeebAsm gave me the starting point for this project. You really inspired me, Kieran - thank you.)

This is truly fantastic work Mark, more detail than I thought possible and I haven't even had chance to dig into a fraction of it yet!

I'm so happy that my port to BeebAsm was a helpful starting point for such an epic project. My original goal of doing the port was so that I could make some fun extensions to Elite once it was buildable, but I never did get around to that bit. Now that you have created such thorough documentation, it should be much easier for me to figure out how to insert alterations across the code base. You've definitely inspired me in return to pick those ideas back up.

PS. Not that I have many followers, but my tweet about your project seems to be travelling quite far - apologies I didn't know your Twitter handle, otherwise I would have tagged you in it!

[cjpinder]

Hello! I'm Kroc Camen, author of the Commodore 64 disassembly of Elite, Elite Harmless.

Sorry to got off-topic a bit but if you are fixing stuff with the C64 Elite I seem to remember there being a bug in the code which calculates the score addition when destroying ships with a missile. It was fixed in the NES code. I can probably hunt the fix out if you want.

Thanks,
Christian.

[Kroc]

I seem to remember there being a bug in the code which calculates the score addition when destroying ships with a missile. It was fixed in the NES code. I can probably hunt the fix out if you want.

I think you're referring to the cash-overflow bug; I know where it is, but haven't fixed it yet as I've been busy with commenting and sussing out the code. If you can point me to the specific fix, that would save me some effort so that would be appreciated.

[cjpinder]

I think you're referring to the cash-overflow bug; I know where it is, but haven't fixed it yet as I've been busy with commenting and sussing out the code. If you can point me to the specific fix, that would save me some effort so that would be appreciated.

No, not the cash overflow bug, this is a score bug specific to the C64 Elite. To keep this slightly Acorn related, the C64 version of Elite (and the Apple II port) was done on a BBC Micro using the in-built assembler.

On the BBC and Elk versions of Elite, each object destroyed adds one point to the player's score. So destroying an asteroid scores the same as shooting down a Thargoid mothership. When the C64 port was done the scoring was changed so that each object has a different score depending on how tough it is.

So, when an object is destroyed in C64 Elite the player's score is increased by an amount based on the object's type. When the player destroys an object with a missile the code needs to take the ID of the object destroyed and lookup what type it is. The C64 code misses out the bit which looks up the object type based on its ID. The bug is fixed in NES Elite and looks like this:

Code: Select all

TA87
    LDA	INWK+32		; A = The ID of the Missile Target * 2
    AND	#127		; Clear the top bit which indicates the missile belongs to the player
    LSR	A		; A = ID of Missile Target
    TAX			; X = ID of Missile Target
    LDA	FRIN,X		; NES Lookup the object's type from its ID 
    TAX			; NES X = A

As the last two lines of the above code are missing from C64 Elite the score addition ends up being based on the object's ID instead of its type. So effectively the player is given a random score increase when destroying something with a missile.

Thanks,
Christian.

[MarkMoxon]

(The README contains full acknowledgements of those whose shoulders I have stood on for this project, but I must give a particular shout out to kieranhj, whose original port of the source code to BeebAsm gave me the starting point for this project. You really inspired me, Kieran - thank you.)

This is truly fantastic work Mark, more detail than I thought possible and I haven't even had chance to dig into a fraction of it yet!

I'm so happy that my port to BeebAsm was a helpful starting point for such an epic project.

Thanks Kieran, that means a lot. There’s no way I would have been able to follow all that crazy copy protection code in the loader, so thank goodness you got there first!

My original goal of doing the port was so that I could make some fun extensions to Elite once it was buildable, but I never did get around to that bit. Now that you have created such thorough documentation, it should be much easier for me to figure out how to insert alterations across the code base. You've definitely inspired me in return to pick those ideas back up.

Bitshifters meets Elite? Wow, that really would be something! Though there’s not a lot of free memory to play with, that’s for sure...

PS. Not that I have many followers, but my tweet about your project seems to be travelling quite far - apologies I didn't know your Twitter handle, otherwise I would have tagged you in it!

No problem - my Twitter account is a study in tumbleweed, but I’m glad it got some traction. It’s only a first draft so I figured stardot was the place to post, but if people are OK with massive assembler files in old-school 80-column monospaced text, that’s good. It will be interesting to see how different it feels as a website with linked label names and the like. I’ve just got to build some Python scripts to automate the process...

Mark

[MarkMoxon]

I think you're referring to the cash-overflow bug; I know where it is, but haven't fixed it yet as I've been busy with commenting and sussing out the code. If you can point me to the specific fix, that would save me some effort so that would be appreciated.

No, not the cash overflow bug, this is a score bug specific to the C64 Elite. To keep this slightly Acorn related, the C64 version of Elite (and the Apple II port) was done on a BBC Micro using the in-built assembler.

That’s fascinating - do you know if it was using a second processor? The thought of creating the C64 version in a standard BBC Micro’s memory footprint is pretty daunting. Then again, creating the original in the built-in assembler is nothing short of miraculous (let alone the parts written on an Atom, which counts for quite a chunk of code if the variable names are anything to go by). It’s hard enough working out what’s going on in a modern IDE with oodles of memory!

Mark

[Kroc]

What I can say from picking apart the internals of the C64 version is that it was a swift port from the BBC (Bell & Braben both disliked the Commodore 64, and were doing the port purely for the larger market it represented). Since the C64 screen is 320px wide, compared to the 256px screen mode used on the BBC, the game does some last-minute adjustments to correct for the 0-256px values used throughout the math. The code is very, very similar to the BBC throughout. They added a few extra look up tables and adapted the drawing routines to the C64's non-linear screen layout, but it's safe to say that the port was more about getting the existing BBC code up and running rather than being true to the C64's capabilities.

[Kweepa]

Don't have much to contribute except woo! great job!

[cjpinder]

That’s fascinating - do you know if it was using a second processor?

The code is assembled in sections (ELITEA-K) which are individually assembled and saved to disk, similar to BBC Elite. It think it could be done on a standard BBC Model B with disk drive. They were using machines with second processors and HIBASIC though so would have had more memory to play with.

Thanks,
Christian.

[cjpinder]

What I can say from picking apart the internals of the C64 version is that it was a swift port from the BBC (Bell & Braben both disliked the Commodore 64, and were doing the port purely for the larger market it represented).

Deadlines are imposed by publishers and Firebird would have wanted to get it to market as soon as possible. There wouldn't have been time for a major re-write.

Thanks,
Christian.

[Snuggsy187]

Sorry to be repetitive, but Wow (again) Mark !

Amazing detail (just looking at the IRQ1 section and T1 timers extensive explanation - which is of particular interest to me and just what I was looking for !).

How you did all this in the space of one lifetime is beyond me !

[MarkMoxon]

Sorry to be repetitive, but Wow (again) Mark !

Amazing detail (just looking at the IRQ1 section and T1 timers extensive explanation - which is of particular interest to me and just what I was looking for !).

I know, that screen mode routine is amazing! It was one of the first things I wanted to get my head round, particularly as it’s so specific to the BBC Micro. I really felt like I was getting to know the machine’s insides as I worked through the routine - finally, a good use for my dusty old Advanced User Guide...

How you did all this in the space of one lifetime is beyond me !

To be honest, I just got hooked on unpacking all the little secrets buried in the code. It helps that I was hopelessly in love with the game when I was 14, and once I’d started getting the hang of 6502 code after so many years, I just couldn’t put it down. It’s taken about 3 months to get to this point, mainly in the evenings (on the sofa, using an iPad, next to a very understanding wife).

As a way of escaping from the current state of the world, disassembling iconic code from 1984 comes highly recommended!

Mark