Decoded: The Bisqwit NES Emulator

Back in 2011, Bisqwit (Joel Yliluoma), posted source code and a demonstration video for his NES emulator. We witnessed him push out 1000 lines of code in less than an hour to faithfully reproduce everyone's favorite Nintendo games. An impressive feat in both capability and generosity, especially for those learning to program. Some folks have asked me to comment on it over the years and so I thought I would make a formal article out of it.

Quick Links

Bisqwit's YouTube Presentation
The Code: (Original) (With line numbers) (Code Walkthrough)

Bottom line: It works -- that means it's a job well done! Programming for YouTube forces you to cut corners and Bisqwit handled it very well. I consider this an intermediate programming project with much knowledge buried in it for the novice programmer to dig out.

But there is a problem...the project may be inaccessible for beginners. We're going to solve that right now.

I see two serious hurdles for understanding Bisqwit's work:

1) You need to understand the underlying architecture of the Nintendo.

Nearly every line of code regurgitates the inner-workings of the console and if you don't grok it, you cannot truly follow along. It's more than just understanding the statement on the line; it means knowing why it's there, and how it represents the logic behind the console. The actual C/C++ operations are very simple, but the code is full of seemingly unrelated memory addresses and literals meant to reflect hardware. Fortunately, the NES is one of the most well-documented architectures to come out of the 1980s. Reverse engineers have been pounding on this box for decades. Look no further than NesDev for more than enough information to get started. For those not willing to do the research, continue reading here and I'll try to fill in sufficient detail. If you have a background in DSP or computational photography, then you'll be ahead of the game.

2) The source code is not conventional (...if there is such a thing).

Bisqwit presented his emulator as a single flat file on YouTube. He had to. It's too tedious to flip between many source files while presenting. But now we're left with a code format that doesn't match what most programmers expect (especially beginners). There isn't a stereotypical group of novice programmers ready to tackle this code-style.

Beginner's claiming C++ as their language of choice are disappointed to see the preprocessor getting this much exercise. We have entire functions constructed using nothing but macros and tokens. Possibly worse, is that much of the code is large swaths of procedural work with very little abstraction. No common patterns (or arguably objects) exist. In fact, the C++11 claim is limited to minor features (like auto-typing, lambdas and array consts). The C++ usage overall is thin. It's confined to code organization (through namespaces), generics (templates), and overloading. If you're a C++'er, then you'll have the most to learn...frankly, this is a C project that cherry-picks C++ features to keep it terse and organized inside a single file.

If you're a novice C programmer, then your blood pressure went up after seeing four namespace changes. You probably completely checked out when the first template appeared. Fortunately, the feel of the code should be familiar to the C crowd. Lots of bit-banging, masking, shifting, etc.

If you program in ANY high-level language, then this flat file organization is evil for learning.

So no matter what kind of beginner you are, there is something not quite right about this program. But that's the learning opportunity: To develop that code reading ability. A career in programming means you'll rarely have the luxury of code in your preferred style. Being able to read and understand programs like this means you're on your way to fortune and glory! For people with many years of experience in programming, I think there's something here for you too. Especially if you enjoy the code golfing or other "minimum solution" problems.

Let's decode Bisqwit's NES emulator!