https://github.com/markmoxon/nes-elite-beebasm Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} markmoxon / nes-elite-beebasm Public * Notifications * Fork 6 * Star 235 Fully documented and annotated source code for Elite on the Nintendo Entertainment System (NES) www.bbcelite.com 235 stars 6 forks Activity Star Notifications * Code * Pull requests 0 * Actions * Security * Insights More * Code * Pull requests * Actions * Security * Insights markmoxon/nes-elite-beebasm This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 0 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/m] Use Git or checkout with SVN using the web URL. [gh repo clone markmo] Work fast with our official CLI. Learn more about the CLI. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @markmoxon markmoxon Merge Inventory category into Market, recategorise various routines ... 41f1c1c Oct 7, 2023 Merge Inventory category into Market, recategorise various routines 41f1c1c Git stats * 249 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time 1-source-files Merge Inventory category into Market, recategorise various routines October 7, 2023 16:26 2-build-files Extracted font and line images into single images August 27, 2023 14:46 3-assembled-output Fixed path in compile output October 6, 2023 15:51 4-reference-binaries Added more information on source files and reference binaries to the ... August 29, 2023 10:28 5-compiled-game-discs Add PAL variant June 4, 2023 14:23 .gitignore Add compile.txt debug output to repository October 6, 2023 15:49 Makefile Add compile.txt debug output to repository October 6, 2023 15:49 README.md Clarified the build commands for building the default variant October 7, 2023 14:30 make.bat Add build files April 24, 2023 13:05 View code [ ] Fully documented source code for Elite on the NES Contents Introduction Acknowledgements A note on licences, copyright etc. Browsing the source in an IDE Folder structure Building Elite from the source Requirements Build targets Windows Mac and Linux Verifying the output Log files Building different variants of NES Elite Building the NTSC variant Building the PAL variant Differences between the variants README.md Fully documented source code for Elite on the NES BBC Micro (cassette) | BBC Micro (disc) | 6502 Second Processor | BBC Master | Acorn Electron | Elite-A | NES Screenshot of Elite on the NES This repository contains source code for Elite on the Nintendo Entertainment System (NES), with every single line documented and (for the most part) explained. It is a companion to the bbcelite.com website. See the introduction for more information, or jump straight into the documented source code. Contents * Introduction * Acknowledgements + A note on licences, copyright etc. * Browsing the source in an IDE * Folder structure * Building Elite from the source + Requirements + Build targets + Windows + Mac and Linux + Verifying the output + Log files * Building different variants of NES Elite + Building the NTSC variant + Building the PAL variant + Differences between the variants Introduction This repository contains source code for Elite on the NES, with every single line documented and (for the most part) explained. You can build the fully functioning game from this source. Two variants are currently supported: the NTSC version from Ian Bell's personal website, and the Imagineer PAL release. * If you want to explore the source code, then the annotated source is what you're looking for. You might also like to read the section on Browsing the source in an IDE for some tips. * If you want to build Elite from the source on a modern computer, to produce a working ROM image that can be loaded into a real NES or an emulator, then you want the section on Building Elite from the source. My hope is that this repository and the accompanying website will be useful for those who want to learn more about Elite and what makes it tick. It is provided on an educational and non-profit basis, with the aim of helping people appreciate one of the most iconic games of the 8-bit era. Acknowledgements NES Elite was written by Ian Bell and David Braben and is copyright (c) D. Braben and I. Bell 1991/1992. The code on this site has been reconstructed from a disassembly of the version released on Ian Bell's personal website. The commentary is copyright (c) Mark Moxon. Any misunderstandings or mistakes in the documentation are entirely my fault. Huge thanks are due to the original authors for not only creating such an important piece of my childhood, but also for releasing the source code for us to play with; to Paul Brink for his annotated disassembly; and to Kieran Connell for his BeebAsm version, which I forked as the original basis for this project. You can find more information about this project in the accompanying website's project page. The following archive from Ian Bell's personal website forms the basis for this project: * NES Elite, NTSC version A note on licences, copyright etc. This repository is not provided with a licence, and there is intentionally no LICENSE file provided. According to GitHub's licensing documentation, this means that "the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work". The reason for this is that my commentary is intertwined with the original Elite source code, and the original source code is copyright. The whole site is therefore covered by default copyright law, to ensure that this copyright is respected. Under GitHub's rules, you have the right to read and fork this repository... but that's it. No other use is permitted, I'm afraid. My hope is that the educational and non-profit intentions of this repository will enable it to stay hosted and available, but the original copyright holders do have the right to ask for it to be taken down, in which case I will comply without hesitation. I do hope, though, that along with the various other disassemblies and commentaries of this source, it will remain viable. Browsing the source in an IDE If you want to browse the source in an IDE, you might find the following useful. * The main game's source code is split across eight different ROM banks, which you can find in the main-sources folder. This is the motherlode and probably contains all the stuff you're interested in. * It's probably worth skimming through the notes on terminology and notations on the accompanying website, as this explains a number of terms used in the commentary, without which it might be a bit tricky to follow at times (in particular, you should understand the terminology I use for multi-byte numbers). * The accompanying website contains a number of "deep dive" articles, each of which goes into an aspect of the game in detail. Routines that are explained further in these articles are tagged with the label Deep dive: and the relevant article name. * There are loads of routines and variables in Elite - literally hundreds. You can find them in the source files by searching for the following: Type: Subroutine, Type: Variable, Type: Workspace and Type: Macro. * If you know the name of a routine, you can find it by searching for Name: , as in Name: SCAN (for the 3D scanner routine) or Name: LL9 (for the ship-drawing routine). * The entry point for the main game code is the BEGIN routine in bank 7, which you can find by searching for Name: BEGIN. If you want to follow the program flow all the way from the title screen around the main game loop, then you can find a number of deep dives on program flow on the accompanying website. * The source code is designed to be read at an 80-column width and with a monospaced font, just like in the good old days. I hope you enjoy exploring the inner workings of NES Elite as much as I have. Folder structure There are five main folders in this repository, which reflect the order of the build process. * 1-source-files contains all the different source files, such as the main assembler source files, image binaries, fonts and so on. * 2-build-files contains build-related scripts, such as the crc32 verification scripts. * 3-assembled-output contains the output from the assembly process, when the source files are assembled and the results processed by the build files. * 4-reference-binaries contains the correct binaries for each variant, so we can verify that our assembled output matches the reference. * 5-compiled-game-discs contains the final output of the build process: an iNES ROM image that contains the compiled game and which can be run on real hardware or in an emulator. Building Elite from the source Requirements You will need the following to build Elite from the source: * BeebAsm, which can be downloaded from the BeebAsm repository. Mac and Linux users will have to build their own executable with make code, while Windows users can just download the beebasm.exe file. * Python. Both versions 2.7 and 3.x should work. * Mac and Linux users may need to install make if it isn't already present (for Windows users, make.exe is included in this repository). For details of how the build process works, see the build documentation on bbcelite.com. Let's look at how to build Elite from the source. Build targets There are two main build targets available. They are: * build - A version with a maxed-out commander * encrypt - A version that exactly matches the released version of the game Unlike the Acornsoft versions of Elite on which it is based, the NES version is not encrypted, so there is no difference in encryption between the two targets. I have used the same target names for consistency, but the only difference is in the commander file. Builds are supported for both Windows and Mac/Linux systems. In all cases the build process is defined in the Makefile provided. Windows For Windows users, there is a batch file called make.bat to which you can pass one of the build targets above. Before this will work, you should edit the batch file and change the values of the BEEBASM and PYTHON variables to point to the locations of your beebasm.exe and python.exe executables. You also need to change directory to the repository folder (i.e. the same folder as make.bat). All being well, doing one of the following: make.bat build make.bat encrypt will produce a file called elite-ntsc.NES in the 5-compiled-game-discs folder that contains the NTSC release, which you can then load into an emulator, or into a real NES using a flash cart. Mac and Linux The build process uses a standard GNU Makefile, so you just need to install make if your system doesn't already have it. If BeebAsm or Python are not on your path, then you can either fix this, or you can edit the Makefile and change the BEEBASM and PYTHON variables in the first two lines to point to their locations. You also need to change directory to the repository folder (i.e. the same folder as Makefile). All being well, doing one of the following: make build make encrypt will produce a file called elite-ntsc.NES in the 5-compiled-game-discs folder that contains the NTSC release, which you can then load into an emulator, or into a real NES using a flash cart. Verifying the output The build process also supports a verification target that prints out checksums of all the generated files, along with the checksums of the files from the original sources. You can run this verification step on its own, or you can run it once a build has finished. To run it on its own, use the following command on Windows: make.bat verify or on Mac/Linux: make verify To run a build and then verify the results, you can add two targets, like this on Windows: make.bat encrypt verify or this on Mac/Linux: make encrypt verify The Python script crc32.py in the 2-build-files folder does the actual verification, and shows the checksums and file sizes of both sets of files, alongside each other, and with a Match column that flags any discrepancies. If you are building an unencrypted set of files then there will be lots of differences, while the encrypted files should mostly match (see the Differences section below for more on this). The binaries in the 4-reference-binaries folder are those extracted from the released version of the game, while those in the 3-assembled-output folder are produced by the build process. For example, if you don't make any changes to the code and build the project with make encrypt verify, then this is the output of the verification process: Results for variant: pal [--originals--] [---output----] Checksum Size Checksum Size Match Filename ----------------------------------------------------- 6a32bd20 16384 6a32bd20 16384 Yes bank0.bin 1840f774 16384 1840f774 16384 Yes bank1.bin e08fa78a 16384 e08fa78a 16384 Yes bank2.bin e07c0f21 16384 e07c0f21 16384 Yes bank3.bin 731cd900 16384 731cd900 16384 Yes bank4.bin fee7480c 16384 fee7480c 16384 Yes bank5.bin 500f28cd 16384 500f28cd 16384 Yes bank6.bin 8e1162f8 16384 8e1162f8 16384 Yes bank7.bin 4cf12d39 131088 4cf12d39 131088 Yes elite.bin eb5e8763 16 eb5e8763 16 Yes header.bin All the compiled binaries match the originals, so we know we are producing the same final game as the release version. Log files During compilation, details of every step are output in nine files called compile.txt (for the header) or compile0.txt through compile7.txt (for banks 0 to 7) in the 3-assembled-output folder. If you have problems, these might come in handy, and they're a great reference if you need to know the addresses of labels and variables for debugging (or just snooping around). Building different variants of NES Elite This repository contains the source code for two different variants of NES Elite: * The NTSC version from Ian Bell's personal website * The Imagineer PAL release, which is the only official release of NES Elite By default the build process builds the NTSC release, but you can build a specified variant using the variant= build parameter. Building the NTSC variant You can add variant=ntsc to produce the elite-ntsc.NES file that contains the NTSC variant, though that's the default value so it isn't necessary. In other words, you can build it like this: make.bat encrypt verify variant=ntsc or this on a Mac or Linux: make encrypt verify variant=ntsc This will produce a file called elite-ntsc.NES in the 5-compiled-game-discs folder that contains the NTSC variant. The verification checksums for this version are as follows: Results for variant: ntsc [--originals--] [---output----] Checksum Size Checksum Size Match Filename ----------------------------------------------------- 0560a52b 16384 0560a52b 16384 Yes bank0.bin c1239b33 16384 c1239b33 16384 Yes bank1.bin 5e6c3bfb 16384 5e6c3bfb 16384 Yes bank2.bin 54df916d 16384 54df916d 16384 Yes bank3.bin 5953c5d4 16384 5953c5d4 16384 Yes bank4.bin 0dd49e0c 16384 0dd49e0c 16384 Yes bank5.bin 39255d4f 16384 39255d4f 16384 Yes bank6.bin 26f0c7de 16384 26f0c7de 16384 Yes bank7.bin 54386491 131088 54386491 131088 Yes elite.bin eb5e8763 16 eb5e8763 16 Yes header.bin Building the PAL variant You can build the PAL variant by appending variant=ntsc to the make command, like this on Windows: make.bat encrypt verify variant=pal or this on a Mac or Linux: make encrypt verify variant=pal This will produce a file called elite-pal.NES in the 5-compiled-game-discs folder that contains the PAL variant. The verification checksums for this version are as follows: Results for variant: pal [--originals--] [---output----] Checksum Size Checksum Size Match Filename ----------------------------------------------------- 6a32bd20 16384 6a32bd20 16384 Yes bank0.bin 1840f774 16384 1840f774 16384 Yes bank1.bin e08fa78a 16384 e08fa78a 16384 Yes bank2.bin e07c0f21 16384 e07c0f21 16384 Yes bank3.bin 731cd900 16384 731cd900 16384 Yes bank4.bin fee7480c 16384 fee7480c 16384 Yes bank5.bin 500f28cd 16384 500f28cd 16384 Yes bank6.bin 8e1162f8 16384 8e1162f8 16384 Yes bank7.bin 4cf12d39 131088 4cf12d39 131088 Yes elite.bin eb5e8763 16 eb5e8763 16 Yes header.bin Differences between the variants You can see the differences between the variants by searching the source code for _PAL (for features in the PAL release) or _NTSC (for features in the NTSC release). The main differences in the NTSC release compared to the PAL release are: * The two versions count a different number of cycles in the NMI handler (7433 in the PAL version, 6797 in the NTSC version). * The NTSC version is missing the Imagineer and Nintendo headings from the Start screen. * The PAL version waits for longer before starting auto-play on the combat demo. * Each version has its own unique checksum algorithm for the save slots. * The internal version number is different (the PAL version is " <2.8>" while the NTSC version is "5.0") * The copyright message hidden in bank 3 is different (the PAL message is "NES ELITE IMAGE 2.8 - 04 MAR 1992" while the NTSC message is "NES ELITE IMAGE 5.2 - 24 APR 1992" * The first title in the combat demo scroll text is different (the PAL title is "IMAGINEER PRESENTS --- E L I T E --- (C)BRABEN & BELL 1991" while the NTSC title is "NTSC EMULATION --- E L I T E --- (C)BELL & BRABEN 1991") * A number of pixel y-coordinate constants in the PAL version are six pixels bigger than in the NTSC version, to cater for the taller screen height. * The interrupt vectors in banks 0 to 6 that are used during initialisation are subtly different. * The code for detecting double-taps of the B button when choosing buttons from the icon bar is a bit simpler in the NTSC version. It's worth noting that the NTSC variant doesn't actually work on an NTSC machine. The NMI timings have been changed to work with some (but not all) emulators in NTSC mode, but it isn't a full NTSC conversion, it's an NTSC emulation (as per the scroll text). --------------------------------------------------------------------- Right on, Commanders! Mark Moxon About Fully documented and annotated source code for Elite on the Nintendo Entertainment System (NES) www.bbcelite.com Topics bbcmicro bbc nes elite retrocomputing retrogaming 6502 nintendo-nes bbc-micro 6502-assembly acornsoft Resources Readme Activity Stars 235 stars Watchers 6 watching Forks 6 forks Report repository Languages * Assembly 98.6% * Python 1.2% * Other 0.2% Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time.