{"id":13835976,"url":"https://github.com/markmoxon/elite-source-code-nes","last_synced_at":"2025-07-10T13:31:09.610Z","repository":{"id":170686865,"uuid":"631944679","full_name":"markmoxon/elite-source-code-nes","owner":"markmoxon","description":"Fully documented and annotated source code for Elite on the Nintendo Entertainment System (NES)","archived":false,"fork":false,"pushed_at":"2024-10-16T16:12:56.000Z","size":10644,"stargazers_count":370,"open_issues_count":0,"forks_count":16,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-18T09:30:03.233Z","etag":null,"topics":["6502","6502-assembly","acornsoft","bbc","bbc-micro","bbcmicro","elite","nes","nintendo-nes","retrocomputing","retrogaming"],"latest_commit_sha":null,"homepage":"https://elite.bbcelite.com/nes/","language":"Assembly","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markmoxon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-24T11:47:27.000Z","updated_at":"2024-10-16T16:13:00.000Z","dependencies_parsed_at":"2023-09-23T11:43:09.427Z","dependency_job_id":"ce18bbce-143e-4227-b131-bc00ae65c66a","html_url":"https://github.com/markmoxon/elite-source-code-nes","commit_stats":null,"previous_names":["markmoxon/nes-elite-beebasm","markmoxon/elite-source-code-nes"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-nes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-nes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-nes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-nes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmoxon","download_url":"https://codeload.github.com/markmoxon/elite-source-code-nes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225638925,"owners_count":17500652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","6502-assembly","acornsoft","bbc","bbc-micro","bbcmicro","elite","nes","nintendo-nes","retrocomputing","retrogaming"],"created_at":"2024-08-04T15:00:31.395Z","updated_at":"2024-11-20T22:31:31.563Z","avatar_url":"https://github.com/markmoxon.png","language":"Assembly","readme":"# Fully documented source code for Elite on the NES\n\n[BBC Micro cassette Elite](https://github.com/markmoxon/elite-source-code-bbc-micro-cassette) | [BBC Micro disc Elite](https://github.com/markmoxon/elite-source-code-bbc-micro-disc) | [6502 Second Processor Elite](https://github.com/markmoxon/elite-source-code-6502-second-processor) | [BBC Master Elite](https://github.com/markmoxon/elite-source-code-bbc-master) | [Acorn Electron Elite](https://github.com/markmoxon/elite-source-code-acorn-electron) | [Commodore 64 Elite](https://github.com/markmoxon/elite-source-code-commodore-64) | [Apple II Elite](https://github.com/markmoxon/elite-source-code-apple-ii) | **NES Elite** | [Elite-A](https://github.com/markmoxon/elite-a-source-code-bbc-micro) | [Teletext Elite](https://github.com/markmoxon/teletext-elite) | [Elite Universe Editor](https://github.com/markmoxon/elite-universe-editor) | [Elite Compendium (BBC Master)](https://github.com/markmoxon/elite-compendium-bbc-master) | [Elite Compendium (BBC Micro)](https://github.com/markmoxon/elite-compendium-bbc-micro) | [Elite over Econet](https://github.com/markmoxon/elite-over-econet) | [Flicker-free Commodore 64 Elite](https://github.com/markmoxon/c64-elite-flicker-free) | [BBC Micro Aviator](https://github.com/markmoxon/aviator-source-code-bbc-micro) | [BBC Micro Revs](https://github.com/markmoxon/revs-source-code-bbc-micro) | [Archimedes Lander](https://github.com/markmoxon/lander-source-code-acorn-archimedes)\n\n![Screenshot of Elite on the NES](https://elite.bbcelite.com/images/github/nes-station.png)\n\nThis repository contains source code for Elite on the Nintendo Entertainment System (NES), with every single line documented and (for the most part) explained. It has been reconstructed by hand from a disassembly of the original game binaries.\n\nIt is a companion to the [elite.bbcelite.com website](https://elite.bbcelite.com).\n\nSee the [introduction](#introduction) for more information, or jump straight into the [documented source code](1-source-files/main-sources).\n\n## Contents\n\n* [Introduction](#introduction)\n\n* [Acknowledgements](#acknowledgements)\n\n  * [A note on licences, copyright etc.](#user-content-a-note-on-licences-copyright-etc)\n\n* [Browsing the source in an IDE](#browsing-the-source-in-an-ide)\n\n* [Folder structure](#folder-structure)\n\n* [Building NES Elite from the source](#building-neselite-from-the-source)\n\n  * [Requirements](#requirements)\n  * [Windows](#windows)\n  * [Mac and Linux](#mac-and-linux)\n  * [Build options](#build-options)\n  * [Verifying the output](#verifying-the-output)\n  * [Log files](#log-files)\n\n* [Building different variants of NES Elite](#building-different-variants-of-nes-elite)\n\n  * [Building the PAL variant](#building-the-pal-variant)\n  * [Building the NTSC variant](#building-the-ntsc-variant)\n  * [Differences between the variants](#differences-between-the-variants)\n\n## Introduction\n\nThis repository contains source code for Elite on the NES, with every single line documented and (for the most part) explained.\n\nYou can build the fully functioning game from this source. [Two variants](#building-different-variants-of-nes-elite) are currently supported: the Imagineer PAL variant and the NTSC variant from Ian Bell's personal website.\n\nIt is a companion to the [elite.bbcelite.com website](https://elite.bbcelite.com), which contains all the code from this repository, but laid out in a much more human-friendly fashion. The links at the top of this page will take you to repositories for the other versions of Elite that are covered by this project.\n\n* If you want to browse the source and read about how Elite works under the hood, you will probably find [the website](https://elite.bbcelite.com) is a better place to start than this repository.\n\n* If you would rather explore the source code in your favourite IDE, then the [annotated source](1-source-files/main-sources) is what you're looking for. It contains the exact same content as the website, so you won't be missing out (the website is generated from the source files, so they are guaranteed to be identical). You might also like to read the section on [browsing the source in an IDE](#browsing-the-source-in-an-ide) for some tips.\n\n* If you want to build NES 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 NES Elite from the source](#building-nes-elite-from-the-source).\n\nMy hope is that this repository and the [accompanying website](https://elite.bbcelite.com) 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.\n\n## Acknowledgements\n\nNES Elite was written by Ian Bell and David Braben and is copyright \u0026copy; D. Braben and I. Bell 1991/1992.\n\nThe code on this site has been reconstructed from a disassembly of the version released on [Ian Bell's personal website](http://www.elitehomepage.org/).\n\nThe commentary is copyright \u0026copy; Mark Moxon. Any misunderstandings or mistakes in the documentation are entirely my fault.\n\nHuge 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](https://github.com/kieranhj/elite-beebasm), 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](https://elite.bbcelite.com/about_site/about_this_project.html).\n\nThe following archive from Ian Bell's personal website forms the basis for this project:\n\n* [NES Elite, NTSC version](http://www.elitehomepage.org/archive/a/b7120500.zip)\n\n### A note on licences, copyright etc.\n\nThis repository is _not_ provided with a licence, and there is intentionally no `LICENSE` file provided.\n\nAccording to [GitHub's licensing documentation](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/licensing-a-repository), 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\".\n\nThe 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.\n\nUnder 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.\n\nMy 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.\n\n## Browsing the source in an IDE\n\nIf you want to browse the source in an IDE, you might find the following useful.\n\n* The main game's source code is split across eight different ROM banks, which you can find in the [main-sources](1-source-files/main-sources) folder. This is the motherlode and probably contains all the stuff you're interested in.\n\n* It's probably worth skimming through the [notes on terminology and notations](https://elite.bbcelite.com/terminology/) 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).\n\n* The accompanying website contains [a number of \"deep dive\" articles](https://elite.bbcelite.com/deep_dives/), 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.\n\n* 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`.\n\n* If you know the name of a routine, you can find it by searching for `Name: \u003cname\u003e`, as in `Name: SCAN` (for the 3D scanner routine) or `Name: LL9` (for the ship-drawing routine).\n\n* The entry point for the main game code is the `BEGIN` routine in [bank 7](1-source-files/main-sources/elite-source-bank-7.asm), 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](https://elite.bbcelite.com/deep_dives/) on the accompanying website.\n\n* 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.\n\nI hope you enjoy exploring the inner workings of NES Elite as much as I have.\n\n## Folder structure\n\nThere are five main folders in this repository, which reflect the order of the build process.\n\n* [1-source-files](1-source-files) contains all the different source files, such as the main assembler source files, image binaries, fonts and so on.\n\n* [2-build-files](2-build-files) contains build-related scripts, such as the crc32 verification scripts.\n\n* [3-assembled-output](3-assembled-output) contains the output from the assembly process, when the source files are assembled and the results processed by the build files.\n\n* [4-reference-binaries](4-reference-binaries) contains the correct binaries for each variant, so we can verify that our assembled output matches the reference.\n\n* [5-compiled-rom-images](5-compiled-rom-images) 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.\n\n## Building NES Elite from the source\n\nBuilds are supported for both Windows and Mac/Linux systems. In all cases the build process is defined in the `Makefile` provided.\n\n### Requirements\n\nYou will need the following to build NES Elite from the source:\n\n* BeebAsm, which can be downloaded from the [BeebAsm repository](https://github.com/stardot/beebasm). Mac and Linux users will have to build their own executable with `make code`, while Windows users can just download the `beebasm.exe` file.\n\n* Python. The build process has only been tested on 3.x, but 2.7 might work.\n\n* 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).\n\nYou may be wondering why we're using BeebAsm - a BBC Micro assembler - to build the NES version of Elite. This is because NES Elite is a conversion of BBC Master Elite, which itself is a direct descendant of the original 1984 release for the BBC Micro and Acorn Electron (and the same is true of the Commodore 64 and Apple II versions of Elite - they are all cut from the same cloth). All of the older 6502 versions of Elite were built and assembled on a BBC Micro, including the Commodore and Apple versions, so BeebAsm is a good modern assembler to use for the NES version as well. The 1991 NES version was actually developed on the PC-based PDS development system, so the use of BeebAsm here isn't historically accurate, it's just a good fit for the source material.\n\nFor details of how the build process works, see the [build documentation on bbcelite.com](https://elite.bbcelite.com/about_site/building_elite.html).\n\nLet's look at how to build NES Elite from the source.\n\n### Windows\n\nFor Windows users, there is a batch file called `make.bat` which you can use to build the game. 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`).\n\nAll being well, entering the following into a command window:\n\n```\nmake.bat\n```\n\nwill produce a file called `elite-pal.NES` in the `5-compiled-rom-images` folder that contains the PAL variant, which you can then load into an emulator, or into a real NES using a flash cart.\n\n### Mac and Linux\n\nThe 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`).\n\nAll being well, entering the following into a terminal window:\n\n```\nmake\n```\n\nwill produce a file called `elite-pal.NES` in the `5-compiled-rom-images` folder that contains the PAL variant, which you can then load into an emulator, or into a real NES using a flash cart.\n\n### Build options\n\nBy default the build process will create a typical Elite game ROM with a standard commander and verified binaries. There are various arguments you can pass to the build to change how it works. They are:\n\n* `variant=\u003cname\u003e` - Build the specified variant:\n\n  * `variant=pal` (default)\n  * `variant=ntsc`\n\n* `commander=max` - Start with a maxed-out commander (specifically, this is the test commander file from the original source, which is almost but not quite maxed-out)\n\n* `match=no` - Do not attempt to match the original game binaries (i.e. omit workspace noise)\n\n* `verify=no` - Disable crc32 verification of the game binaries\n\nSo, for example:\n\n`make variant=ntsc commander=max match=no verify=no`\n\nwill build an NTSC variant with a maxed-out commander, no workspace noise and no crc32 verification.\n\nSee below for more on the verification process.\n\n### Verifying the output\n\nThe default build process prints out checksums of all the generated files, along with the checksums of the files from the original sources. You can disable verification by passing `verify=no` to the build.\n\nThe 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).\n\nThe 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`, then this is the output of the verification process:\n\n```\nResults for variant: pal\n[--originals--]  [---output----]\nChecksum    Size  Checksum    Size  Match  Filename\n-----------------------------------------------------\n6a32bd20   16384  6a32bd20   16384   Yes   bank0.bin\n1840f774   16384  1840f774   16384   Yes   bank1.bin\ne08fa78a   16384  e08fa78a   16384   Yes   bank2.bin\ne07c0f21   16384  e07c0f21   16384   Yes   bank3.bin\n731cd900   16384  731cd900   16384   Yes   bank4.bin\nfee7480c   16384  fee7480c   16384   Yes   bank5.bin\n500f28cd   16384  500f28cd   16384   Yes   bank6.bin\n8e1162f8   16384  8e1162f8   16384   Yes   bank7.bin\n4cf12d39  131088  4cf12d39  131088   Yes   elite.bin\neb5e8763      16  eb5e8763      16   Yes   header.bin\n```\n\nAll the compiled binaries match the originals, so we know we are producing the same final game as the PAL variant.\n\n### Log files\n\nDuring compilation, details of every step are output in a file called `compile.txt` in the `3-assembled-output` folder. If you have problems, it might come in handy, and it's a great reference if you need to know the addresses of labels and variables for debugging (or just snooping around).\n\n## Building different variants of NES Elite\n\nThis repository contains the source code for two different variants of NES Elite:\n\n* The Imagineer PAL variant, which is the only official release of NES Elite\n\n* The NTSC variant from Ian Bell's personal website\n\nBy default the build process builds the PAL variant, but you can build a specified variant using the `variant=` build parameter.\n\n### Building the PAL variant\n\nYou can add `variant=pal` to produce the `elite-pal.NES` file that contains the PAL variant, though that's the default value so it isn't necessary. In other words, you can build it like this:\n\n```\nmake.bat variant=pal\n```\n\nor this on a Mac or Linux:\n\n```\nmake variant=pal\n```\n\nThis will produce a file called `elite-pal.NES` in the `5-compiled-rom-images` folder that contains the PAL variant.\n\nThe verification checksums for this version are as follows:\n\n```\nResults for variant: pal\n[--originals--]  [---output----]\nChecksum    Size  Checksum    Size  Match  Filename\n-----------------------------------------------------\n6a32bd20   16384  6a32bd20   16384   Yes   bank0.bin\n1840f774   16384  1840f774   16384   Yes   bank1.bin\ne08fa78a   16384  e08fa78a   16384   Yes   bank2.bin\ne07c0f21   16384  e07c0f21   16384   Yes   bank3.bin\n731cd900   16384  731cd900   16384   Yes   bank4.bin\nfee7480c   16384  fee7480c   16384   Yes   bank5.bin\n500f28cd   16384  500f28cd   16384   Yes   bank6.bin\n8e1162f8   16384  8e1162f8   16384   Yes   bank7.bin\n4cf12d39  131088  4cf12d39  131088   Yes   elite.bin\neb5e8763      16  eb5e8763      16   Yes   header.bin\n```\n\n### Building the NTSC variant\n\nYou can build the NTSC variant by appending `variant=ntsc` to the `make` command, like this on Windows:\n\n```\nmake.bat variant=ntsc\n```\n\nor this on a Mac or Linux:\n\n```\nmake variant=ntsc\n```\n\nThis will produce a file called `elite-ntsc.NES` in the `5-compiled-rom-images` folder that contains the NTSC variant.\n\nThe verification checksums for this version are as follows:\n\n```\nResults for variant: ntsc\n[--originals--]  [---output----]\nChecksum    Size  Checksum    Size  Match  Filename\n-----------------------------------------------------\n0560a52b   16384  0560a52b   16384   Yes   bank0.bin\nc1239b33   16384  c1239b33   16384   Yes   bank1.bin\n5e6c3bfb   16384  5e6c3bfb   16384   Yes   bank2.bin\n54df916d   16384  54df916d   16384   Yes   bank3.bin\n5953c5d4   16384  5953c5d4   16384   Yes   bank4.bin\n0dd49e0c   16384  0dd49e0c   16384   Yes   bank5.bin\n39255d4f   16384  39255d4f   16384   Yes   bank6.bin\n26f0c7de   16384  26f0c7de   16384   Yes   bank7.bin\n54386491  131088  54386491  131088   Yes   elite.bin\neb5e8763      16  eb5e8763      16   Yes   header.bin\n```\n\n### Differences between the variants\n\nYou can see the differences between the variants by searching the source code for `_PAL` (for features in the PAL variant) or `_NTSC` (for features in the NTSC variant). The main differences in the NTSC variant compared to the PAL variant are:\n\n* The two versions count a different number of cycles in the NMI handler (7433 in the PAL version, 6797 in the NTSC version).\n\n* The NTSC version is missing the Imagineer and Nintendo headings from the Start screen.\n\n* The PAL version waits for longer before starting auto-play on the combat demo.\n\n* Each version has its own unique checksum algorithm for the save slots.\n\n* The internal version number is different (the PAL version is \"\u003c2.8\u003e\" while the NTSC version is \"5.0\")\n\n* 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\"\n\n* The first title in the combat demo scroll text is different (the PAL title is \"IMAGINEER PRESENTS --- E L I T E --- (C)BRABEN \u0026 BELL 1991\" while the NTSC title is \"NTSC EMULATION --- E L I T E ---  (C)BELL \u0026 BRABEN 1991\")\n\n* 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.\n\n* The interrupt vectors in banks 0 to 6 that are used during initialisation are subtly different.\n\n* 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.\n\nIt'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).\n\nSee the [accompanying website](https://elite.bbcelite.com/nes/releases.html) for a comprehensive list of differences between the variants.\n\n---\n\nRight on, Commanders!\n\n_Mark Moxon_","funding_links":[],"categories":["Assembly"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmoxon%2Felite-source-code-nes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmoxon%2Felite-source-code-nes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmoxon%2Felite-source-code-nes/lists"}