A Mega Drive you can read.

The answer was yes, for reasons that shaped everything that followed. The Mega Drive is one of the best-documented machines of its era: mature open emulators such as Genesis Plus GX, BlastEm, Exodus and clownmdemu exist, and between them almost every behaviour of the hardware has been measured and written down. Nothing had to be guessed; it had to be understood and written clearly.

The goals were ranked, and the ranking mattered. Pedagogy first: someone should be able to open the source and learn how the console works. Then performance, compatibility, quality of life, and finally best practices with few dependencies. When two goals pulled in different directions, the higher one won.

Rust suited those goals. Hardware arithmetic is explicit (wrapping_add, u16::from_be_bytes), so the code shows what the chip does to every bit. Generics with static dispatch let a CPU core talk to the memory map at no cost while staying a standalone crate. And #![forbid(unsafe_code)] turned out to be realistic: nothing here needs it.

Performance was not the risk

A 7.67 MHz 68000 executes one to two million instructions a second. A plain interpreter in Rust handles that in a few percent of one modern core. The study concluded that speed could be spent on accuracy and on comforts such as rewind. The real risks were elsewhere: the exactness of the 68000, the VDP’s timing tricks, the YM2612’s sound, odd cartridge hardware, and keeping audio and video in sync without crackles. Each one later got its own chapter.

The 68000 runs the game. It sees the cartridge, 64 KiB of work RAM, the controller ports and the video chip’s two ports in one 24-bit address space. The Z80, a separate 8-bit computer with 8 KiB of its own RAM, drives the sound chips; the 68000 can stop it, load a program into its RAM and restart it, and the Z80 can look into the 68000’s memory through a 32 KiB window.

The VDP is never addressed like memory. Its 64 KiB of VRAM, its palette (CRAM) and its vertical scroll table (VSRAM) are only reachable through a control port and a data port, which is why so much of a game’s code is about feeding those two ports at the right moment.

Each chip lives in its own crate, with module documentation written as a short course on that chip: the 68000’s registers and addressing modes, the Z80’s undocumented flags, the VDP’s tile formats, FM synthesis as the YM2612 actually computes it. The crates were built in parallel, on separate branches, before anything connected them.

What lets them stay apart is a small trait. Each CPU says what it needs from the outside world and nothing more:

A test vector is one instruction, frozen. It records every register and the relevant bytes of memory before the instruction, the same after it, and the bus activity in between. Run the instruction from the “before” state; if a single bit or cycle differs from “after”, the test fails.

Here is a real one, the first of the 1,000 cases for Z80 opcode 80, ADD A,B, shortened:

The scheduler in gase-core runs the console one scanline at a time. At the start of each line the VDP draws it. Then the 68000 executes instructions up to the next event on that line (the vertical interrupt, horizontal blanking, the end of the line), and after every 68000 instruction the Z80 catches up to the same master-clock time. The two CPUs never drift more than one instruction apart.

The sound chips are not stepped in that loop at all. They are brought up to date lazily: only when a CPU writes to them, so that the write lands at exactly the right sample, and at the end of the frame. When nobody is listening, catching up costs nothing.

The first real programs were five freely licensed test ROMs, chosen to cover different parts of the machine. Each became a regression test: run for a fixed number of frames, with scripted button presses, then hash the picture. A hash was only recorded after the frame had been checked by eye.

Everything on screen is made of tiles: 8 × 8 pixels, four bits per pixel, 32 bytes each. A pixel’s four bits pick one of 16 colours in one of four palettes; colour 0 is transparent. Two planes, A and B, are scrollable maps of tiles in which each entry chooses a tile, a palette, horizontal and vertical flips and a priority bit. A window can replace plane A in a fixed rectangle, for status bars that must not scroll. On top come up to 80 sprites, kept in a linked list.

Below is one real frame of Right 2 Repair taken apart. Each layer was drawn by gase’s own renderer with the other layers hidden, so this is exactly what the VDP combines.

An operator is a sine oscillator with a volume envelope. On its own it makes a pure, dull tone. The trick, found by John Chowning in 1973 and licensed to Yamaha, is to add one operator’s output to another’s phase. The modulator bends the carrier back and forth and creates sidebands: when the two frequencies are in a simple ratio the sidebands are harmonics and the result is a rich, pitched timbre; odd ratios give bells and metal. The modulator’s volume, the modulation index, sets the brightness.

Try it. This is the formula, drawn live: out = sin(ωc·t + I · sin(ωm·t)).

Airstriker booted to its SEGA logo and then, a few seconds later, stopped on a black screen with a message from its own runtime: 68K Address Error. It is a small freeware game written in BasiEgaXorz, a BASIC compiler for the Mega Drive, and it is known to work in popular emulators. So the first suspect was gase.

An address error is the 68000 refusing a word or long access at an odd address. The chip has no address line A0. A 16-bit access always covers two bytes at an even address, chosen with upper- and lower-byte strobes, so there is no way to ask for a word that starts on an odd byte. The CPU aborts the instruction mid-flight and takes exception 3, pushing a 14-byte frame that describes the faulting access. gase implements this exactly, because the MAME-derived test vectors check those frames bit for bit.

While it draws a line, the VDP reads VRAM almost continuously: name table entries, tile patterns, scroll values, sprite data. VRAM has a single port, so each line is divided into a fixed sequence of memory slots, and most go to the renderer. Only a few external access slots are left for the 68000 and the DMA engine.

SGDK, the C toolkit most homebrew is built with, clears all 64 KiB of VRAM at start-up with a DMA fill, twice, with the display on. At real slot speed each fill takes about five and a half frames, so with this model SGDK software finishes booting about twelve frames later, as it does on a console. Two regression hashes had to be revisited. The Spiral showed the same particle scene at a slightly later point of its animation, and its new hash was recorded after comparing screenshots. The 240p Test Suite’s pattern menu now finished loading after the scripted button press, so the press moved from frames 330–335 to 345–350; the resulting frame was bit-identical to the old one.

A regression test that changes is not a failure if you can explain the change. These two could be explained to the frame.

A save state is the whole console written down: every component implements one trait, writing its fields in a fixed order and reading them back. The format is plain little-endian binary with a magic number, a version and a fingerprint of the game, with no field names and no schema. Loading is transactional: a damaged state leaves the running console untouched.

Rewind then costs almost nothing to build: a ring buffer of save states, one taken every few frames, popped and loaded while you hold the key. A state is roughly 150 KiB, so ten seconds of history fit in a few tens of megabytes. During the performance work, saving byte slices in one copy instead of byte by byte made those snapshots about six times cheaper.

The chip with two wires

Most cartridges save to battery-backed SRAM, ordinary memory at $200000. A few dozen use a serial EEPROM instead: a tiny I²C chip with only a clock and a data pin, which the game drives bit by bit by writing to a latch at an address that depends on who made the board. gase emulates the chip edge by edge (start and stop conditions, the acknowledge bit on every ninth clock, both addressing modes, page writes that wrap within the page) and keeps a table of which games use which chip and wiring, because nothing in the ROM says so.

Press F1 in gase and a second window opens with the console as its chips see it: both CPUs’ registers and disassembly, the VDP’s registers decoded by name, the palettes, every tile in VRAM or the plane maps, and the sprite list in link order. You can pause, step one 68000 instruction, run to the end of the frame or to the next vertical blank, set breakpoints, and mute each FM and PSG channel to hear how the music is arranged.

The work started with measurement, not hunches. Two numbers were taken for each of the five test ROMs: frames per second from the headless benchmark, which is what you feel, and the count of host instructions executed over 300 frames under callgrind, which does not depend on what else the machine is doing and shows changes of a fraction of a percent.

The profile was unambiguous. The scanline renderer took 50–57% of all instructions: it recomputed the scroll, the cell and the pixel for every one of the 320 pixels of each plane, and composited them with branchy loops. Next came the 68000’s operand helpers, called out of line, then the YM2612 computing silent channels, the PSG ticking one step at a time, and the resampler.

That was the rule for every optimisation. The straightforward version stays in the code as the documented definition, the fast path names it in its own documentation, and a unit test proves the two agree, usually on thousands of random inputs. On top of that, every change had to leave the test-ROM frame hashes, the recorded audio and the CPU test vectors bit-identical. No unsafe, and no hand-written SIMD: the compiler does the vectorising.

Work happens on feature/… and fix/… branches cut from develop and merged back through pull requests; main follows releases. Chips were developed in parallel on their own branches, which the one-crate-per-chip layout made painless, and each pull request description lists what was tested, what is approximate, and which other open pull requests it will conflict with and in what order to merge them.

Continuous integration runs on every pull request, with warnings treated as errors:

1. cargo fmt --all --check
2. cargo clippy --workspace --all-targets, with the workspace lints, forbid(unsafe_code) among them
3. cargo test --workspace: unit tests, hand-assembled whole-system programs, debugger equivalence
4. cargo build -p gase --no-default-features, proving the headless build has no external dependencies
5. cargo doc --workspace --no-deps with warnings as errors: the documentation is part of the product
6. cargo clippy -p gase-web --target wasm32-unknown-unknown, and clippy for the five phone targets
7. scripts/smoke-sdl.sh: the optimised program must still be running after five seconds (chapter 18)

Separate workflows build the browser version and the phone apps: an Android APK, and the iOS app for device and simulator.

One interface, then three platforms at once

The interface and the ports were the biggest piece of work after the emulator itself, and the order mattered. The platform-free interface came first, on its own branch with the desktop shell (#22), because everything else would stand on its Platform contract. As soon as that contract settled, the browser version (#23) and the phone apps (#24) were built in parallel, each in its own working copy, on branches stacked on top of #22. They worked in different directories (crates/web and web/, crates/mobile and mobile/), so they could not step on each other’s code; where they did meet, in the README and ARCHITECTURE.md, the second merge produced conflicts that were resolved by hand.

Each port also fed fixes back. The crash of chapter 18 was found on the interface branch and its fix merged into the other two before they were reviewed; the landscape bug of chapter 14 was found while taking pictures for this site. Twice a follow-up commit arrived a minute after its pull request had been merged, so it went into a new, small pull request instead of being lost: working fast means checking the last word after the merge, not only before.

gase was written with an AI assistant working on its own branches and pull requests; a person reviewed and merged every one of them. Each commit says so in its last line: Co-authored with AI.

The big suites are too large for every push (the Z80 vectors alone are about 1.3 GB), so a second workflow runs them weekly and on demand, together with the test-ROM regression: each ROM run for a fixed number of frames with scripted presses, and an FNV-1a hash of the picture compared with a value that was only recorded after looking at the frame.

Until version 0.1, gase was a command line and a window. Making it pleasant to use meant menus, a way to pick a game, settings that survive a restart, remappable controls, and on phones, buttons under your thumbs. Writing that four times, once per platform toolkit, would have quadrupled the code a learner has to read. So it lives in one crate, gase-app, with no dependencies and no I/O, just like the core.

The app draws itself. Every frame it paints its menus into a plain buffer of pixels with its own bitmap font, the same way the debugger does. A platform only has to show that buffer, play sound, and report keys, pad buttons and fingers. The interface is immediate-mode: there are no widget objects to keep in sync. Each frame the current screen is drawn from the settings and the console’s state, and input is handled as it is drawn.

The platform contract

Everything a platform must provide fits in one trait, Platform: read and write a named file, list a folder, ask for a ROM, report the time. Everything it gives the app is an Event: a key, a pad button or axis, a pointer, a dropped file, the app going to the background. Everything the app asks back comes through Requests: go fullscreen, quit, open the system’s document picker. A shell is the code that keeps that promise on one platform, and there are three: SDL2 for desktops and phones, and a WebAssembly one for browsers.

Every controller at once

The keyboard, any number of gamepads and the touch screen are mapped to the two console pads at the same time. Each device keeps its own set of pressed buttons, and the console sees their union. Nothing has to be switched over, and letting go of a key can’t release a button a gamepad is still holding. Every key and pad button can be remapped for both players.

Pulling in a library would have been the easy way. But the rule of few dependencies had held so far, and DEFLATE, the compression inside ZIP files (and gzip, and PNG), turns out to be a good thing to learn from: about 900 lines, tests aside, that combine two old ideas. gase-zip reads ZIP archives, inflates DEFLATE streams and checks CRC-32 sums. When Cartridge::from_bytes sees the bytes PK\3\4 at the start of a file, it opens the archive and takes the ROM inside. Every platform gets ZIP support from that one check.

The first idea is LZ77. Instead of storing text it has already seen, the compressor writes “go back distance bytes and copy length bytes from there”. The decompressor’s own output is the dictionary. A copy may overlap what it is writing: distance 1, length 100 repeats one byte a hundred times. Try it:

The usual way to put Rust in a web page is wasm-bindgen, which generates the glue between the two languages. It works well, but it hides exactly what a learner would want to see. So gase-web does without it. The module is built for wasm32-unknown-unknown and exports about twenty plain functions that take and return numbers. The page imports nine functions back: read and write a file, push sound, make a request. Six JavaScript modules, loaded as they are written, do the rest.

Play gase in your browser

One shared memory

A WebAssembly module’s memory is a single ArrayBuffer that JavaScript can see, and a Rust pointer is just an offset into it. So no picture or sound is ever copied across the boundary. Rust returns vec.as_ptr() as a number, and the page wraps those bytes in a typed array and hands them to the canvas. After every frame the module fills a seventeen-word frame description, telling the page where the picture is, how big it is, where to draw it and how to pace. The page reads it through one Uint32Array, like a C struct.

Neither phone system starts a program by calling main. On Android, the Java virtual machine starts an activity. SDL’s SDLActivity loads two native libraries, libSDL2.so and libmain.so, and calls the C function SDL_main on a thread of its own. On iOS, a tiny Objective-C main hands control to UIKit, and once the app has launched, SDL calls the same SDL_main. The gase-mobile crate exports exactly that function: built as a shared library for Android, and as a static library linked into the iOS app.

From there it is the desktop program with a different Shell. Files live in the app’s private storage, ROMs come from the system’s document picker or “Open with”, the screen rotates, and there is no Quit. Copying a picked file into the app is a few dozen lines of Java and Objective-C. That glue then hands the copy’s path back as an ordinary SDL “file dropped” event, which the shell already understood from the desktop.

A phone can kill you at any moment

A desktop program runs until it is closed. A phone app sent to the background may never be woken again. So when gase goes to the background it saves the game’s battery RAM and the settings at once, opens the pause menu, stops drawing and sleeps without using the CPU. Coming back, it drops the stale sound and resumes. If the system takes the graphics device away, SDL says so and the textures are recreated.

The debug build of the new interface ran fine. The release build died with SIGSEGV within a second of opening its window. Every unit test passed, because none of them opens a window. gdb placed the crash inside SDL, copying pixels into a texture. valgrind was more precise: an uninitialised value created by a stack allocation, followed by writes to memory that belonged to nobody.

Uploading a picture to the GPU went through sdl2’s safe wrapper, Texture::with_lock(rect, …). Inside that crate it looks like this:

When a release is published on GitHub, the Release workflow checks out the tagged commit and builds it everywhere at once: on Linux, Windows and macOS machines for the desktop programs, a WebAssembly build for the browser, and the phone workflow of chapter 17 for Android and iOS. A last job gathers the files, adds their checksums, takes the version’s section of CHANGELOG.md as the release notes and attaches everything. GitHub adds the source code by itself.

The workflow can also be started by hand with a tag name, and then it creates the tag and the release too. That is how 0.2.0 and the older 0.1.0 got their files after the fact; 0.1.0 predates the browser and phone code, so the workflow looks at what the commit contains and builds only those platforms.