Skip to the text
The Colophon Project

The player and its debugger

A colophon is written to be read, and a machine is meant to be watched. The player is where the emulator is put on a page, so that the account of a game and the game itself can be held against each other.

Today that page is a debugger. It builds a machine, runs it at the speed the hardware ran, and lets a reader stop it between instructions and ask what it holds: the registers, the bytes, the counters of the chip drawing the picture, and the picture itself. The debugger sets out each of its panels and what each one reads.

There are two machines: a CPC and a Spectrum. Each has an element named for it, because a machine is a board with particular chips soldered to it and whatever builds one has to know which. The panels know only their own chip, so they watch either machine without being told which they are in.

Carrying it into a page

The debugger travels as two files, each pinned to a version that cannot change under the link: a stylesheet that dresses the page, and a module that carries the machine. A whole page is those two lines and the elements arranged beneath them.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>A machine under study</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/colophon-player@0.4.2/dist/colophon-player.css"
    />
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/colophon-player@0.4.2/dist/colophon-player.js"
    ></script>
  </head>
  <body>
    <colophon-cpc model="cpc6128" snapshot="game.sna">
      <colophon-controls></colophon-controls>
      <colophon-monitor zoom="1.5"></colophon-monitor>
      <div class="panels">
        <colophon-z80></colophon-z80>
        <colophon-disassembly></colophon-disassembly>
      </div>
    </colophon-cpc>
  </body>
</html>

The stylesheet dresses the page and not only the elements: it resets the document and sets the body’s colour and type, which is why the page above holds nothing else. panels is the one class it offers the page, and it stacks what it holds into a column beside the monitor. The controls take a line to themselves when they are placed directly inside the machine element, rather than standing in one of those columns.

That page builds a CPC; a Spectrum is the same shape with <colophon-spectrum> in its place and its own firmware in /roms.

The rest is files standing where the page looks for them.

index.html          the page above
game.sna            fetched beside the page
roms/cpc6128.rom    fetched from the root of the site
roms/amsdos.rom     and this one, on any machine with a disc interface

The snapshot is named by the snapshot attribute and fetched relative to the page, and a disc image named by disc is fetched the same way. The firmware is looked for in /roms at the root of the site, whatever the page’s own address; a roms attribute on the machine element sends it elsewhere, and a relative one there is resolved against the page like any other link. Which machine’s firmware is read follows from model. amsdos.rom is read alongside it wherever the disc interface is fitted, which the 664 and the 6128 have built in and a 464 gets only when it is given a disc.

Nothing is asked of the server but to hand files over, and any static server will do — one is needed all the same, because a browser will fetch neither a module nor a snapshot nor a disc image from a page opened straight off the filesystem.

While the version begins with a zero, any release may break what the last one promised. Pin the exact version.