Porting the Basilisk II classic Macintosh emulator to the browser

Screenshot of Basilisk II in the browser

Basilisk II Classic Macintosh emulator in the browser. Try it out.

I recently ported the Basilisk II Classic Macintosh emulator to run in a web browser. I've been hoping to get it running for some time, and previously made an attempt back in 2013, before switching to focus on the PCE emulator. Since then browser technologies have advanced, and I've learned a lot more about emulation (in part by making a simulated computer of my own). The Basilisk II port is the culmination of both of these things. Anyway, let's get into the gory technical details of how it works.

How it works

The emulator code is compiled with Emscripten and run in a Web Worker. Communication with the main thread happens by reading and writing data in SharedArrayBuffers which are shared between the main browser thread and the worker, allowing the emulator's main loop to run continuously without ever yielding to the event loop. This allows the simulation to be more smooth, as the emulator thread can just focus on simulating the Macintosh computer, and leave the tasks of displaying the contents of the video framebuffer and playing audio up to the main (browser) thread.


The original emulator codebase makes use of SDL (a cross-platform set of video/audio/input APIs). Emscripten provides an implementation of SDL for the browser, but this implementation isn't designed to run in a web worker, so I've hacked the emulator's video output code to write to the SharedArrayBuffer instead of calling SDL APIs. In video_sdl.cpp where the EM_ASM_ macro is used to call this JS function to copy the contents of the video framebuffer to a SharedArrayBuffer. This shared memory is read from the main thread here and output onto a Canvas. I experimented with locking the video surface when reading and writing, but this hurt performance due to lock contention. However, we don't really need it. Even if the UI thread reads a frame from the video framebuffer while it is currently in the middle of being written to from the emulator worker, it's not really noticable, because in the shared memory the new frame contents is just being written directly over the old one at the same position, so visually it just presents as a bit of 'tearing' (showing part of the old frame, part of the new frame). We could improve on this by using a circular queue of framebuffers for alternating frames (multiple buffering), which would allow locking (with less contention), but in practice this is okay.


Mouse and keyboard input are communicated via another SharedArrayBuffer here in the UI thread JS, then read in the worker thread JS here, when requested from the C code here. I also had to add a mapping to convert JS keycodes to ADB (Apple) keycodes.


The implementation of audio uses a queue of buffers in shared memory, which each have a flag signifying whether they are full and ready to be consumed by the UI thread, or empty and ready to be written by the emulator thread. The emulator thread will ensure that there are several buffers of audio queued up, to avoid gaps in playback in the case of a slowdown. When the emulator is built natively, audio has a dedicated thread to avoid slowness on the emulator thread affecting playback, but to make things simpler I've just hacked in a call to output audio directly into the emulator's main loop here. This could be improved by using Emscripten's pthreads support to spawn a separate audio thread. The audio buffer is passed to JS here and copied into a SharedArrayBuffer here. The audio read in the UI thread here and output using the Web Audio API.


By using a worker thread with shared memory, this port manages to achieve a great framerate, with the mouse movement feeling relatively fluid. For comparison, see this alternate port I put together without the use of shared memory, which has to regularly yield to the browser event loop. The mouse movement is noticably choppier.

Potential Improvements

In future this implementation could be improved by moving all of the shared memory communication to C code by leveraging Emscripten's pthreads support. In this scenario the emulator code would start up, spawn a thread to run the emulator main loop, and then yield back to the browser. Instead of creating SharedArrayBuffers to communicate video, audio, and input, Emscripten's pthreads mode makes the entire C heap memory space a SharedArrayBuffer, with each spawned thread running in a web worker. The JS would simply read and write values on the C heap. This would also unblock using threads in the emulator code (currently not easy due to Chrome's lack of support for web workers spawning other web workers).