zero_page

The MOS 6502 was an incredibly adopted chip for its time. It showed up in many famous computers and entertainment systems of that era. It did, however, have some drawbacks. Namely, there were a lot of known bugs that exist on the chip. While these were mostly straightforward to work around, the chipset was later extended with the superior 65C02 chip.

Not only did the 65C02 fix the quirks of the original chip it was based on, it also added some handy extra opcodes for programmers to utilize. This chip was further extended by Western Design Center to include a little-known instruction: WAI.

The purpose of the instruction was to effectively shut down the chip's power consumption and wait for an interrupt to come from the hardware in order to wake it back up. This would allow programmers to suspend execution of a program while also drastically reducing its power draw.

Electrical power isn't necessarily very interesting in this case, but I do have cases where terminals are running software that want to wait around for the game engine to poke them awake again. Pretty much exactly like how the WAI command was meant to be used. But instead of taking less electrical power they can now take less processor power.

It's worth noting that the emulator works by running a fixed amount of processor cycles per frame to run at the proper 1MHz that the Apple II ran at. Even if the machine is just sitting in a loop waiting, that waiting requires as much processing power as when the emulator is crunching a lot of numbers. Cycles are cycles, whether they're doing real work or just idling. So the WAI command allows me to specify when the game should just ignore the terminal and cut its cost.

The core problem I had is that the game engine needed to be able to talk to the "terminals" in the game world and vice versa. Given that I'm running an emulation of a 40+ year old piece of hardware, I couldn't just plumb a callback into it. I also needed to do this in a way that would protect certain pieces of data from users stomping over them intentionally or not. I'd like users to be able to hack interesting solutions with the terminals, but not by breaking the fourth wall (i.e. manipulating the game at some meta level outside the game's fiction).

As an example, if I have a sensor in a room that reports temperatures I need the game engine to be able to provide that information to a terminal looking for it, but not allow that same terminal to change the value in the sensor. This makes sense in the fiction of the game: you can't tell the sensor what the temperature is, it can only tell you.

Likewise, I needed the terminal to be able to send data through to the game engine and have it evaluate it for "truth" before doing something. For instance, if a program wants to set a fan spinning it needs to somehow tell the game engine to turn that fan on in the same way a real computer might make the request of a real piece of hardware connected to it. Ultimately, the game engine must decide if the fan can in fact turn on (e.g. does it have power?)

But how does an 80s computer without a network card do that? I don't want to try and emulate or fake a networking layer since that's overkill and complicated. So instead I took a page from how the Apple II used its expansion slots to allow all sorts of interesting hardware to be added into the main system.

Briefly, Steve Wozniak (the creator of the Apple II) implemented an elegant system for hobbyists or manufacturers to create little expansion cards that could be plugged directly into the main motherboard of the computer. Apple computers all had an easy-to-open top on their cases that allowed their owners to get right into the guts without needing even a screwdriver.

These cards were mapped into the memory space of the computer the moment they were plugged in. So accessing cards in the memory range of $C080-$C100 would let the user directly read or set up to 16 bytes per slot (there were seven possible slots in total). You can see a more detailed breakdown here.

Given how I wanted to lay things out, I could easily just use the same paradigm the actual Apple II would have used and make an "I/O card" that could let the user read values and write values exactly how you would have done it in the 80s.

The first approach was splitting the 16 bytes available in a slot into two equal 8-byte sections for reading and writing. So the first eight bytes could be written to by the terminal, and the second set of eight bytes could be read by the terminal. This second set of eight bytes was effectively write-protected so that the terminal could not make any alterations to it, only read it. The game engine would however be allowed to write there, giving it some authority where the data is concerned.

This worked great and I could easily have the game engine write status information into the "read" portion, while the terminal could use the "write" portion to output commands for the game engine to read. The only problem was that outside of isolated testing where it was one terminal doing work, it didn't scale well.

For example, one use of the I/O card was to send a message to the game engine to open a door. The program would write the appropriate value to a specific byte, the game would then see this and open the door. Another use was for the game to relay some information to the terminal about the atmospheric conditions in a sealed room. The terminal could then send commands to open or close valves to adjust the various gases in the room's atmosphere, or to turn on a fan to help vent out unwanted mixtures. Again, this worked in isolation.

However, when both of these things were placed into the same level they created an issue. Which bytes controlled which system in the game? If the door and the atmospheric controller knew about each other they could try to reserve bytes that didn't overlap, but this quickly becomes untenable with any number of systems needing to read or write data to a small memory range.

An easy way to overcome this is to just add more "slots", so instead of going from $C080-$C100 we could go from say $C080-$CFFF. That would give us plenty of space and each system would just carve out a 16-byte "slot" for itself. I could even go for a system that pages memory in and out to pack those slots into one slot, but there are a lot of weird edge cases around concurrency since the machines can't read and write to a page in one atomic operation.

Now, you have to suspend your disbelief a little bit because I'm hand-waving over a crucial detail. The way this "expansion card" is written, it's basically as if it were installed into the same memory slot on each terminal that accesses it. In other words, it's like all the terminal's share the same card magically. That's not impossible, just slightly impractical.

So with that in place I have a section of memory that both parties can use to exchange a very limited set of data through.

To extend this, as an interface between the emulator machine instance and the game engine I wrote a quick "memory accessor" component. This can read and write bytes directly to a machine instance, but is more useful for watching for data conditions. For instance, you could watch for one of these I/O bytes to become equal to 255 and call an event when that happens. You can see this scenario below where there are watch conditions on each of the eight possible I/O bytes that can be read. When they occur they're identified by a string name (for end-user clarity) and can be routed accordingly. 

The image below shows a set of lights and buttons on the right side, and the computer terminal running a program on the left. The program is writing out a cycling value on one byte of its output I/O range. These show up in the "READ" column LEDs as they're detected.

The lighted buttons under the "WRITE" column write I/O values to their respective locations, which is then displayed by the terminal when read.

This allows you to watch the terminal change the READ column while you press buttons under the WRITE column and see them show up on the screen.

What followed was a lot of learning about the early days of computers and how machines of old linked their hard and software unlike anything we're capable of doing these days. There's a real simplicity and cleverness to how it all hangs together, and I think it's worth anyone's time to jump head first down the rabbit hole of building an emulator.

A Quick Caveat

Before you fire up your favorite compiler and start typing up your own NES emulator, it's worth noting that you're starting down a path many have gone down before. Spending five minutes on an emulator enthusiast bulletin board will give you handfuls of links to people's half-finished work. There are some really bulletproof emulators around these days, mostly because there's a wealth of experience and knowledge (and documentation) around the whole thing. There are a few novel examples of people doing new things in the space, but for the most part it's a solved problem.

So if you're going to go down this road, just know that few people are going to congratulate you or be very interested in the end result. Don't spend too much time coming up with a catchy name for your emulator, because at the end of the day no one is going to choose it over what's already out there.

Why Bother?

So if it's been done before, why bother? Well, for one it's a wholly unique experience in the field of programming. Usually when you build something that has a high tech investment you're dealing with a lot of variables. You don't know exactly what specifications you want to use for it. How much memory would it need? What's the video resolution? How does the controller work? Typically you would iron these details out over months or years before you could even think of building the first product to actually run on it.

Emulators don't have any of these problems. Your task is to recreate the behavior of a known piece of hardware as exactly as you can. Everything about the machine is generally available for your inspection so you're working from a complete and "shipped" technical spec. What's more, you have a massive (and generally very familiar) set of products that have already shipped on the machine. So you have all the known test cases in the world at your disposal at any given time. This means that you don't have to build complex systems and hope an artist or designer can figure them out and use them, you just have to make Mario jump on the screen and have it scroll to the next (which is actually easier said than done).

What you're in for, generally, is a lot of debugging. And if done right this is a fantastic way to get better at that crucial skill set. You'll most likely sit down and read a piece of the documentation for the hardware, write your first take at it, fire up a ROM to check it against, then invariably scratch  your head at the weird result you see. Then you'll check the docs again, cross reference with some other sites, look at the code again, step through it all, rinse, repeat. It can be really tedious and confusing sometimes, but it's incredibly fulfilling when you fix an issue and suddenly a big chunk of a game comes to life before your eyes. That fulfillment generally diminishes a bit when you find the next issue, but over time you see your work get more and more robust, playing a greater number of titles.

Which is the other great thing about making an emulator: It's a lot of fun to test it! You're playing games you may have grown up with, but now you're seeing them through fresh eyes because you know how the sprites are being drawn on the screen and how the color palette works. You appreciate the logic being strung together in 6502 assembly code, and just how little resources were available to make these great titles.

For all those reasons I think it's a really fantastic project if you like to code. Just know when you're into the point of diminishing returns on making your emulator "perfect". It's driven many a coder insane, and as mentioned before, other people have already climbed that mountain before you.

Where to Start?

There are plenty of good resources for learning about making an emulator. It's going to be tempting to want to dive in and figure out how to draw things or make sounds (spoiler: the latter task sucks) but I would stress that you'll want to start out with a solid 6502 emulation. The 6502 is the processor at the heart of the NES. It was cheap and relatively powerful for its price point, so it found its way into many well-known products of that era. The nice thing is that it's also a fairly simple thing to wrap your head around once you get started. I won't go into the details of the registers and status flags, there are plenty of resources for that as well. What I would say though is to get a CPU unit test program like nestest to verify that your work is behaving properly. Writing an emulation for the processor is tedious, but gloriously so. You implement an opcode, test it, and watch it do what you expect. Then you move to the next and repeat. You slowly build up not only a working processor but also your understanding of exactly what it's doing.

One tip I would give you is to pay attention to cycle counts as you write this. It seems pointless when you're just starting out, but being wrong by even a few cycles here or there can cause lots of headaches down the road. The documents will tell you exactly how to count cycles, so just get in the habit of doing it as you go along.

Next Steps

Once the nestest ROM is working, you're ready to start seeing something on the screen. When I started I wanted to jump into the background images first, but I would suggest a different tack: once you have the barest background working, move on to sprites. Why? They're simple and they will show you real working code faster. The first time I could see characters moving around on screen with real code controlling their movement it was like magic.

Now at this point you're going to go out and download Super Mario Bros and try to get it running right away. Don't do that. I did that starting out as well thinking that since SMB came with the system it must be fairly rudimentary. But sadly SMB is not rudimentary and it's not straightforward. It will bite you in a bunch of different ways I can't even begin to explain yet, so just put that ROM on the shelf and come back to it much later.

Instead, try something simple like Balloon Fight. Never heard of it? Neither had I, but it's basically a Joust-alike. What makes it a good choice is that it is actually straightforward and has no scrolling. This means you can pretty rapidly go from nothing on the screen to seeing things moving, to actually controlling those things and playing the game. I ironed out a lot of issues on that ROM before ever setting foot into another.

Off Into the Wilderness

Once you've got those basics working it becomes more of an open exploration of the software space. Do you want to handle scrolling and memory mirroring? Maybe you want to run a certain title so you'll need to wrap your head around memory mappers to actually get at the data. Or you've got those working and you're wondering why your backgrounds don't scroll like they should. Have fun with "sprite zero" collisions! Once you've got a foothold and you can see things happening on the screen, you're either going to be hooked or exhausted.

In short, I want to make Riven in space with an Apple II as your survival tool.

When I first played Myst I was thrilled to be wrapped up in a strange world that felt more like a dream than an adventure. Puzzles were random and didn't relate to one another, the set pieces could have been 3D clip-art from the time, and the pace was ponderous and slow. Despite those things however it had an interesting story with unreliable narrators and player choices that relied on your gut intuitions and what you had revealed in your travels. It also required that you have a notebook next to you in the real world to scrawl down notes and work through the various head-scratchers littered around the imaginary one. You could also roam around the island with (what felt like) reckless abandon, finding clues along the way as you tried to figure out where the first puzzle even really began.

For as much as it sold, and for unique as it felt at the time, Myst doesn't stand the test of time to me like Riven does. It's always hard to separate nostalgia from your critical judgement, but the image above still evokes a place and tone quite strongly. Riven was a world with a language, history, and logic all to itself. As you played the game, things you had seen all around you started to take focus and become something you could comprehend. You felt a mastery over the world not just in terms of skill, but also in your understanding of how it all fit together and where it all came from.

Granted, it still had maddening "puzzles" that were little more than exercises in frustration and tedium, but its simplest puzzles (and often the most mechanical ones) were where the game shined. One puzzle in particular stood out to me: Crater Island.

Now if you go and play this puzzle today, you may not have the same experience that is rattling around in my head still, but my interpretation of the puzzle (or at least what I took away from it) was what counts.

I have no clue what the in-world fiction for this device was. I think it had something to do with steam and boiling, I'm not really sure. What Riven did really well was present fantastical and impossible machines with rudimentary and familiar input controls. You can easily see that the lever on the left will turn the wheel, which is in turn attached to the flexible pipe. There's a lever to the right which seems to divert flow. There are little push buttons here and there. Every input is recognizable and easily interacted with. What it does once you interact with it and how it works together with the other pieces is the hard part.

When making a puzzle, it's not fun to solve if you don't know what pieces are in play. If you're trying to solve a puzzle with a hidden or missing piece, you're going to spend a lot of time on frustrating false solutions until you uncover what you didn't know existed. In this case, however, everything is up front and center for your attention. What's difficult is trying to tease out what you're even trying to do and what you can do at all. Luckily, you can experiment easily with all the components at your disposal to slowly build up a map in your mind of what everything is doing and how they relate.

When you finally put all the pieces into play properly, the solution becomes obvious and you can progress. But more than that, you feel like you're learned about the set piece and perhaps even worked out what it is and what its purpose in the world was. This tied the gameplay directly into the storytelling in a very subtle way, without the need for heavy-handed audio journals or floating-head narrators trying to walk you through the designer's very complex ideas that they desperately want you to appreciate.

This type of hands-on storytelling, wrapped in a puzzle, was really appealing to me. Working out the story and setting can help solve the puzzle, or vice versa. So when I talk about being Riven in space, this is the aspect that intrigues me. This is the vibe I'd like to capture and push forward.

The first step was taking the stand-alone Apple II emulator and getting it into a package that could be accessed by Unreal. Since the emulator was written in C++ it was a pretty straightforward decision: make it a DLL. This isn't too much work once you get past all the boilerplate importing and exporting of functions.

I knew I wanted to allow for multiple instances of the emulator to be running concurrently so I decomposed the emulator into "machines" that had their own sets of memory, CPUs, video processors, etc. Effectively it was as if each instance were its only little Apple II sitting on a shelf somewhere. This would also allow me to multithread the machines so that I could run around eight different instances of the emulator at the same time without extra cost. I'll touch on this more in a later post.

Once this was working I needed a way to display the results of the machine's work on screen. The emulator had already been using SDL's texture library to render the images produced by the video component of the machine, so it was a simple matter of making a procedural texture in Unreal and piping the output of the machine to it.

The last major step to making it work was to take input from the user and feed that to the machine. This was simple in Unity because I could easily poll for keys and pass them through to the current machine, but in Unreal it wasn't as straight forward. I ended up having to do some back and forth work to get the key presses and route them successfully to the machine. However, once that was squared away it was all up and running inside the engine.