Welcome to the fully documented source code for Revs on the BBC Micro. Here's a quick summary of what you'll find on this site, whether you're looking to read about Revs and how it works, or you're just keen to get stuck into the source code.
Finding out how Revs works
--------------------------
- Read the about this project page for an introduction to this site.
- Read some of the deep dive articles to discover how Revs works under the hood. The following selection is a good place to start:
- Hidden secrets of the custom screen mode - Revs has a custom screen mode that conceals working code in a lush blue sky
- Program flow of the main game loop - The sequence of events in the main game loop
- Drawing a 3D car from 2D parts - Using a paper-cut shadow-box effect to conjure 3D cars from 2D objects
- The track data file format - Every byte in the Revs track data file, explained
- Secrets of the extra tracks - How the extra track files modify the main game code using code hooks
- An overview of the driving model - Secrets of the sophisticated driving simulation that powers Revs
- Check out the index of all deep dive articles to continue exploring.
Exploring the source code
-------------------------
- See the map of the source code for an overview of the program structure. You can dive straight into the source code from here - just click on the routine names and away you go.
- Read the notes on terminology used in this commentary, as without this it might be a bit tricky to follow the comments (in particular, you should understand the terminology I use for multi-byte numbers).
- You can explore the source code in two different ways. The easiest way is with each routine shown individually, which is what you'll see if you click the links from the map of the source code. These pages are small and easy to navigate in a browser. For example, the main game code starts with the Entry routine, while the driving model code is in ApplyDrivingModel.
- The other way is to explore the original source code in larger chunks, as shown in the map of the source code. These larger source files are pretty big and can be a bit unwieldy, but they do show the routines in context.
- You can see more information on a routine by using the "Show more" link. Amongst other things, this is where you can switch between the two ways of looking at the code. For example, here is DrawTrack shown on its own page, and here's the same routine in context as part of the Revs B source file.
- When viewing the source code, you can click on variable and routine names to see more information in a popup. The source code also has syntax highlighting.
- Important routines are flagged with a "*" in the site menu.
- The entry point for the main game code is routine Entry.
Finding your way around
-----------------------
- There is a whole section of the site dedicated to indexes and analyses, to help you find what you are looking for. Look in the site menu for the "Indexes to the source code" section for details.
- There are loads of subroutines in Revs. You can find them all listed and linked in the indexes of subroutines, variables, workspaces and macros.
- There is also an A-Z index of the whole source, which lists every single label across all the source files, as well as source code statistics, and an index of cross-references to help you find what you're looking for.
Other helpful hints
-------------------
- If you want to build the source on a modern computer, then check out the page on building Revs from the source.
- 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. If you're viewing this on a phone, you may find it easier to view the source code pages in landscape.
- You can change the site's colour scheme by clicking the theme icons in the top-right corner.
I hope you enjoy exploring the inner workings of Revs as much as I have.