Chapter 6

JSSpeccy Manual

See also the Github Page

This is a fork of the wonderful JSSpeccy3 by Matt Westcott, incorporating a few improvements:

I’m planning to maintain this fork for as long as I need it (until/unless I’m finished adding new features, and all of these features get merged back into the original project).

Features

Implementation notes

JSSpeccy 3 is a complete rewrite of JSSpeccy to make full use of the web technologies and APIs available as of 2021 for high-performance web apps. The emulation runs in a Web Worker, freeing up the UI thread to handle screen and audio updates, with the emulator core (consisting of the Z80 processor emulation and any auxiliary processes that are likely to interrupt its execution multiple times per frame, such as constructing the video output, reading the keyboard and generating audio) running in WebAssembly, compiled from AssemblyScript (with a custom preprocessor).

Contributions

These days, releasing open source code tends to come with an unspoken social contract, so I'd like to set some expectations...

This is a personal project, created for my own enjoyment, and my act of publishing the code does not come with any commitment to provide technical support or assistance. I'm always happy to hear of other people getting similar enjoyment from hacking on the code, and pull requests are welcome, but I can't promise to review them or shepherd them into an "official" release on any sort of timescale. Managing external contributions is often the point at which a "fun" project stops being fun. If there's a feature you need in the project - feel free to fork.

[These are Matt Westcott’s words… but the same applies to me, and to this fork!]

Embedding

JSSpeccy is designed with embedding in mind. To include it in your own site, download a release archive and copy the contents of the jsspeccy folder somewhere web-accessible. Be sure to keep the .js and .wasm files and the subdirectories in the same place relative to jsspeccy.js.

In the <head> of your HTML page, include the tag

<script src="/path/to/jsspeccy.js"></script>

replacing /path/to/jsspeccy.js with (yes!) the path to jsspeccy.js. At the point in the page where you want the emulator to show, place the code:

<div id="jsspeccy"></div>
<script>JSSpeccy(document.getElementById('jsspeccy'))</script>

If you're suitably confident with JavaScript, you can put the call to JSSpeccy anywhere else that runs on page load, or in response to any user action.

You can also pass configuration options as a second argument to JSSpeccy:

<script>JSSpeccy(document.getElementById('jsspeccy'), {zoom: 2, machine: 48})</script>

The available configuration options are:

For additional JavaScript hackery, the return value of the JSSpeccy function call is an object exposing a number of functions for controlling the running emulator:

<script>
    let emu = JSSpeccy(document.getElementById('jsspeccy'));
    emu.openFileDialog();
</script>

Licence

JSSpeccy-ALT is licensed under the GPL version 3