Advanced Mac Substitute is an API-level reimplementation of 1980s-era Mac OS
ELI5 / TLDR
Most emulators recreate the entire hardware of an old computer, then boot the original operating system on top of it. Advanced Mac Substitute skips all that — it reimplements the Mac OS APIs themselves, so classic 68K Mac applications think they’re talking to a real 1984 Macintosh, but they’re actually running on modern Linux or macOS. No Apple ROM dump needed, no system software license. You just launch an app and it works.
The Full Story
The Problem with Normal Emulation
If you want to run a 1984 Mac app today, the standard path goes something like this: find or build a 68K hardware emulator, obtain a copy of the original Macintosh ROM (legally murky), install System software on a virtual disk, then boot the whole thing up and launch your program. It works, but it’s a full simulation of hardware that hasn’t existed for decades — startup sequence, memory map, I/O chips, the works.
The Shortcut Nobody Takes
Joshua Juran’s Advanced Mac Substitute does something different. Instead of emulating the hardware and running the real OS, it replaces the OS entirely. The project reimplements the Macintosh Toolbox — the set of API calls that applications used to draw windows, handle menus, respond to mouse clicks, and everything else. When MacPaint calls DrawMenuBar, it’s not hitting a ROM chip emulated in software running on emulated hardware. It’s hitting a modern reimplementation that translates that call into something your actual screen can render.
The result: applications launch directly. No boot sequence, no “Welcome to Macintosh” screen, no waiting. You point it at a 68K binary and it runs.
Architecture
The system splits into two pieces. The backend contains a 68K CPU emulator and the reimplemented Toolbox APIs, built to run on any POSIX system. The frontend handles the actual display — there are implementations for SDL2 (the generic option), native macOS, X11, Linux framebuffer, and VNC. That last one means you could theoretically serve a 1984 Mac app to a browser.
What Actually Works
The current feature set covers the fundamentals of the original Mac graphics model: 1-bit black-and-white graphics, QuickDraw regions, circles, rounded rectangles, lines, cursors, GrafPorts (the Mac’s drawing abstraction), text rendering, windows, controls, menus, and dialogs. That’s enough to run real software. The demonstrated applications include MacPaint, Lode Runner, The Fool’s Errand, and a handful of 1984-era games — Amazing, Solitaire, Missile, and IAGO.
No color support yet. This is strictly the 512x342, black-and-white, Susan Kare icon era of the Mac.
What It Isn’t
This is not a general-purpose “run any old Mac app” solution. The Toolbox reimplementation covers early Mac OS — think 1984 to roughly 1987. Later Mac applications that depend on Color QuickDraw, the Sound Manager, or post-System 6 features won’t work. The scope is intentionally narrow: the original Macintosh experience, faithfully reconstructed at the API level.
Claude’s Take
This is a genuinely elegant approach to preservation. Most emulation projects are brute-force affairs — simulate every transistor and hope the software doesn’t notice. API-level reimplementation is architecturally cleaner but dramatically harder, because you need to get the behavior of hundreds of undocumented system calls exactly right. The fact that MacPaint runs is not a trivial achievement.
The project has obvious limitations. The 1-bit-only scope means it covers maybe five years of the Mac’s life. And the number of people who urgently need to run The Fool’s Errand on a Linux framebuffer is probably small. But as a piece of systems engineering and as a preservation tool, it’s solid work — the kind of deep, patient project that only exists because someone cared enough to spend years on it.
Score: 7/10. Technically impressive, historically meaningful, narrow audience. The architecture write-up alone is worth reading if you’re interested in how operating systems actually talk to applications.