blockyard 0.0.1 → 0.1.0

package/public/js/doom.js

@@ -0,0 +1,31 @@
+// DOOM, the tab (operator, 2026-09-15: "I've added doom_dos to the project directory. Get DOOM
+// working as a diversion inside blockyard with zero dependancies").
+//
+// The shareware DOOM.EXE v1.9 from games/doom_dos/, unmodified, on the emulated PC (dosgame.js has
+// the tab, dosworker.js the machine). What is DOOM's own is here: its keys, and the WASD switch,
+// which rebinds the running game in place ("have to refresh for settings to take effect").
+import { createDosGame } from './dosgame.js';
+import { DEFAULT_CONTROLS } from './dosio.js';
+
+const CONTROLS_KEY = 'blockyard.doom.controls';
+
+export const renderDoom = createDosGame({
+  game: 'doom',
+  page: 'doom',
+  prefix: 'doom',
+  title: 'DOOM',
+  idleText: 'The shareware episode, Knee-Deep in the Dead: the real DOOM.EXE v1.9 running on a 486 this monitor emulates. Click the screen to use the mouse.',
+  loadingText: 'loading the shareware episode…',
+  saveName: /\.DSG$/i,
+  keysText: (p) => (p[CONTROLS_KEY] === 'wasd'
+    ? 'W S walk · A D strafe · ← → turn · E open · Ctrl or left click fire · Shift run · 1–7 weapons · Tab map · Esc menu · F2 save · F3 load'
+    : '↑ ↓ walk · ← → turn · Alt+arrows strafe · Space open · Ctrl or left click fire · Shift run · 1–7 weapons · Tab map · Esc menu · F2 save · F3 load'),
+  switches: [{
+    id: 'Wasd', pref: CONTROLS_KEY, fallback: DEFAULT_CONTROLS,
+    on: (v) => v === 'wasd',
+    flip: (v) => (v === 'wasd' ? 'classic' : 'wasd'),
+    // straight into the running game: no restart, no refresh
+    apply: (v, G) => G.worker?.postMessage({ type: 'controls', scheme: v }),
+  }],
+  bootMessage: (p) => ({ controls: p[CONTROLS_KEY] }),
+});

package/public/js/dosaudio.js

@@ -0,0 +1,48 @@
+// THE SPEAKERS of the DOS Diversions: an AudioWorklet that plays what the emulated Sound Blaster
+// produced (public/js/soundcard.js, running in dosworker.js). The worker sends interleaved stereo chunks
+// straight to this processor over a MessagePort; the page's thread never touches a sample.
+//
+// A queue with a ceiling: the machine's clock and the audio clock are both wall time, so they agree
+// on average, but a stall on either side leaves one ahead. Too little queued plays silence until the
+// next chunk; too much (over a quarter of a second) drops the oldest, so a hitch costs a click, not
+// a delay that grows for the rest of the game.
+class DosSpeakers extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.chunks = [];
+    this.pos = 0;
+    this.queued = 0;
+    this.port.onmessage = (e) => {
+      if (e.data?.port) { e.data.port.onmessage = (m) => this.take(m.data); return; }
+      if (e.data?.flush) { this.chunks = []; this.pos = 0; this.queued = 0; }
+    };
+  }
+
+  take(chunk) {
+    if (!(chunk instanceof Float32Array) || chunk.length < 2) return;
+    this.chunks.push(chunk);
+    this.queued += chunk.length / 2;
+    const ceiling = sampleRate / 4;
+    while (this.queued > ceiling && this.chunks.length > 1) {
+      const old = this.chunks.shift();
+      this.queued -= (old.length - this.pos) / 2;
+      this.pos = 0;
+    }
+  }
+
+  process(_inputs, outputs) {
+    const out = outputs[0];
+    const l = out[0], r = out[1] ?? out[0];
+    for (let i = 0; i < l.length; i++) {
+      const c = this.chunks[0];
+      if (!c) { l[i] = 0; r[i] = 0; continue; }
+      l[i] = c[this.pos]; r[i] = c[this.pos + 1];
+      this.pos += 2;
+      this.queued--;
+      if (this.pos >= c.length) { this.chunks.shift(); this.pos = 0; }
+    }
+    return true;
+  }
+}
+
+registerProcessor('dos-speakers', DosSpeakers);

package/public/js/dosgame.js

@@ -0,0 +1,389 @@
+// A DOS GAME, THE TAB: what the DOOM and Quake Diversions share (operator, 2026-09-15: "Get DOOM
+// working as a diversion inside blockyard with zero dependancies", then "get Quake working as a
+// diversion").
+//
+// THE REAL GAMES. Not ports and not remakes: the shareware executables from games/, unmodified,
+// running on a PC this repository emulates -- an i386 (x86.js), the DOS extender and the PC around
+// it (dospc.js), a Sound Blaster Pro 2 with its OPL3 (soundcard.js) -- inside a worker
+// (dosworker.js). A game's tab is this module with its own names: the monitor, the keyboard, the
+// mouse and the speakers. It draws the frames the worker sends, and sends the worker scancodes,
+// mouse motion and the audio port.
+//
+// Same manners as the other Diversions: it pauses when you change tabs or look away, holds the
+// machine exactly where it was (the emulated clock stops with it, so nothing moves), and resumes on
+// the button. Savegames and the config a game writes on quit are kept in this browser.
+import { scancodes, textRuns, paletteLut } from './dosio.js';
+
+/**
+ * One game's tab. `spec`:
+ *   game       the worker's name for it ('doom', 'quake')
+ *   page       the app's page id
+ *   prefix     the element id prefix in index.html ('doom' -> doomScreen, doomPlay, ...)
+ *   title      shown on the overlay
+ *   idleText, loadingText
+ *   saveName   a RegExp for the files worth a "saved" toast
+ *   keysText(prefs)  the HUD's key list
+ *   switches   [{ id, pref, fallback, on(value), flip(value) -> value, apply(value, G) }]
+ *   bootMessage(prefs) -> extra fields for the worker's boot message
+ * Returns the page's render hook for app.js.
+ */
+export function createDosGame(spec) {
+  const pfx = spec.prefix;
+  const SMOOTH_KEY = `blockyard.${spec.game}.smooth`;
+  const MUTE_KEY = `blockyard.${spec.game}.mute`;
+
+  const G = {
+    worker: null, state: null, h: null, bound: false,
+    phase: 'idle',            // idle | loading | running | paused | exited | failed
+    why: '',
+    audio: null, gain: null, speakers: null, connect: null,
+    lut: new Uint32Array(256), image: null, ctx: null,
+    held: new Set(), mouse: { dx: 0, dy: 0, buttons: 0, dirty: false },
+    frames: 0, fps: 0, mips: 0, fpsAt: 0, raf: null,
+    mode: 'graphics',
+  };
+
+  const el = (name) => document.getElementById(`${pfx}${name}`);
+  const pref = (key, fallback) => { try { return globalThis.localStorage?.getItem(key) ?? fallback; } catch { return fallback; } };
+  const setPref = (key, v) => { try { globalThis.localStorage?.setItem(key, v); } catch { /* private mode */ } };
+
+  // ---------------------------------------------------------------- the screen
+  function screen() {
+    const c = el('Screen');
+    if (!c) return null;
+    if (!G.ctx || G.ctx.canvas !== c) { G.ctx = c.getContext('2d', { alpha: false }); G.image = null; }
+    return c;
+  }
+
+  function drawFrame(pixels, palette) {
+    const c = screen();
+    if (!c) return;
+    if (palette) paletteLut(palette, G.lut);
+    if (G.mode !== 'graphics' || c.width !== 320) { c.width = 320; c.height = 200; G.mode = 'graphics'; G.image = null; }
+    if (!G.image) G.image = G.ctx.createImageData(320, 200);
+    const px = new Uint32Array(G.image.data.buffer);
+    const lut = G.lut;
+    for (let i = 0; i < 64000; i++) px[i] = lut[pixels[i]];
+    G.ctx.putImageData(G.image, 0, 0);
+    G.frames++;
+  }
+
+  // text mode: a game's start-up log, and DOOM's ENDOOM when it quits -- 80x25 cells at 8x16 pixels
+  function drawText(cells) {
+    const c = screen();
+    if (!c) return;
+    if (G.mode !== 'text') { c.width = 640; c.height = 400; G.mode = 'text'; }
+    const ctx = G.ctx;
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.fillStyle = '#000';
+    ctx.fillRect(0, 0, 640, 400);
+    ctx.font = '15px ui-monospace, "DejaVu Sans Mono", Menlo, Consolas, monospace';
+    ctx.textBaseline = 'top';
+    const w = ctx.measureText('M').width || 8;
+    for (const run of textRuns(cells)) {
+      if (run.bg !== '#000000') { ctx.fillStyle = run.bg; ctx.fillRect(run.x * 8, run.y * 16, run.text.length * 8, 16); }
+      if (!run.text.trim()) continue;
+      ctx.fillStyle = run.fg;
+      for (let i = 0; i < run.text.length; i++) {
+        const ch = run.text[i];
+        if (ch === ' ' || ch === '\u0000') continue;
+        // block elements fill their cell exactly; glyphs are squeezed to the cell's eight pixels
+        const x = (run.x + i) * 8, y = run.y * 16;
+        if (ch === '█') { ctx.fillRect(x, y, 8, 16); continue; }
+        if (ch === '▀') { ctx.fillRect(x, y, 8, 8); continue; }
+        if (ch === '▄') { ctx.fillRect(x, y + 8, 8, 8); continue; }
+        if (ch === '▌') { ctx.fillRect(x, y, 4, 16); continue; }
+        if (ch === '▐') { ctx.fillRect(x + 4, y, 4, 16); continue; }
+        ctx.setTransform(8 / w, 0, 0, 1, x, y + 1);
+        ctx.fillText(ch, 0, 0);
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------- the overlay and HUD
+  function overlay(msg, sub, button, dim = true) {
+    const ov = el('Over');
+    if (!ov) return;
+    ov.classList.toggle('hidden', !msg);
+    ov.classList.toggle('dim', dim);
+    el('Msg').textContent = msg ?? '';
+    el('Sub').textContent = sub ?? '';
+    const b = el('Play');
+    if (b) { b.textContent = button ?? 'play'; b.classList.toggle('hidden', !button); }
+  }
+
+  const switchValue = (sw) => pref(sw.pref, sw.fallback);
+  const prefsNow = () => Object.fromEntries((spec.switches ?? []).map((sw) => [sw.pref, switchValue(sw)]));
+  function drawHud() {
+    const keys = el('Keys');
+    if (keys) keys.textContent = spec.keysText(prefsNow());
+    const lights = [...(spec.switches ?? []).map((sw) => [sw.id, sw.on(switchValue(sw))]),
+      ['Smooth', pref(SMOOTH_KEY, '0') === '1'], ['Sound', pref(MUTE_KEY, '0') !== '1']];
+    for (const [id, on] of lights) {
+      const b = el(id);
+      if (!b) continue;
+      b.classList.toggle('on', on);
+      b.setAttribute('aria-pressed', on ? 'true' : 'false');
+    }
+    el('Screen')?.classList.toggle('smooth', pref(SMOOTH_KEY, '0') === '1');
+    const st = el('Status');
+    if (st) {
+      const rows = [
+        ['machine', { idle: 'off', loading: 'booting', running: 'running', paused: 'paused', exited: 'powered off', failed: 'halted' }[G.phase]],
+        ['cpu', G.mips ? `${G.mips.toFixed(0)} MIPS` : '–'],
+        ['frames', G.phase === 'running' && G.fps ? `${G.fps.toFixed(0)} a second` : '–'],
+        ['sound', G.audio ? (pref(MUTE_KEY, '0') === '1' ? 'muted' : `Sound Blaster Pro 2 · ${G.audio.sampleRate} Hz`) : '–'],
+      ];
+      const html = rows.map(([k, v]) => `<i>${k}</i><b>${v}</b>`).join('');
+      if (st.innerHTML !== html) st.innerHTML = html;
+    }
+  }
+
+  // ---------------------------------------------------------------- audio
+  async function startAudio() {
+    // one context for the life of the page; each power-on gets a fresh port into it
+    if (G.audio) return G.connect?.() ?? null;
+    const Ctx = globalThis.AudioContext ?? globalThis.webkitAudioContext;
+    if (!Ctx) return null;
+    const ctx = new Ctx({ latencyHint: 'interactive' });
+    const gain = ctx.createGain();
+    gain.gain.value = pref(MUTE_KEY, '0') === '1' ? 0 : 1;
+    gain.connect(ctx.destination);
+    G.audio = ctx; G.gain = gain;
+    // An AudioWorklet needs a secure context; this monitor is often plain HTTP on a LAN address,
+    // where `audioWorklet` does not exist. The fallback is a ScriptProcessor fed on this thread.
+    if (ctx.audioWorklet && globalThis.AudioWorkletNode) {
+      try {
+        await ctx.audioWorklet.addModule('/js/dosaudio.js');
+        const node = new AudioWorkletNode(ctx, 'dos-speakers', { numberOfInputs: 0, outputChannelCount: [2] });
+        node.connect(gain);
+        G.speakers = node;
+        G.connect = () => {
+          const channel = new MessageChannel();
+          node.port.postMessage({ flush: true });
+          node.port.postMessage({ port: channel.port1 }, [channel.port1]);
+          return channel.port2;
+        };
+        return G.connect();
+      } catch { /* fall through to the processor */ }
+    }
+    const node = ctx.createScriptProcessor(1024, 0, 2);
+    const q = { chunks: [], pos: 0, queued: 0 };
+    node.onaudioprocess = (e) => {
+      const l = e.outputBuffer.getChannelData(0), r = e.outputBuffer.getChannelData(1);
+      for (let i = 0; i < l.length; i++) {
+        const c = q.chunks[0];
+        if (!c) { l[i] = 0; r[i] = 0; continue; }
+        l[i] = c[q.pos]; r[i] = c[q.pos + 1]; q.pos += 2; q.queued--;
+        if (q.pos >= c.length) { q.chunks.shift(); q.pos = 0; }
+      }
+    };
+    node.connect(gain);
+    G.speakers = node;
+    G.connect = () => {
+      const channel = new MessageChannel();
+      q.chunks = []; q.pos = 0; q.queued = 0;
+      channel.port1.onmessage = (m) => {
+        const c = m.data;
+        q.chunks.push(c); q.queued += c.length / 2;
+        while (q.queued > ctx.sampleRate / 4 && q.chunks.length > 1) { const o = q.chunks.shift(); q.queued -= (o.length - q.pos) / 2; q.pos = 0; }
+      };
+      return channel.port2;
+    };
+    return G.connect();
+  }
+
+  // ---------------------------------------------------------------- the machine
+  async function powerOn() {
+    if (G.worker) { G.worker.terminate(); G.worker = null; }
+    G.phase = 'loading'; G.mips = 0; G.fps = 0;
+    overlay(spec.title, spec.loadingText, null, true);
+    let port = null;
+    try { port = await startAudio(); } catch { port = null; }
+    if (G.audio?.state === 'suspended') G.audio.resume().catch(() => {});
+    const w = new Worker('/js/dosworker.js', { type: 'module' });
+    G.worker = w;
+    w.onmessage = (e) => onWorker(e.data);
+    w.onerror = (e) => fail(e.message || 'the machine failed to start');
+    if (port) w.postMessage({ type: 'audio', port }, [port]);
+    w.postMessage({ type: 'boot', game: spec.game, rate: G.audio ? G.audio.sampleRate : 0, ...(spec.bootMessage?.(prefsNow()) ?? {}) });
+    drawHud();
+  }
+
+  function onWorker(m) {
+    switch (m.type) {
+      case 'status':
+        if (m.text === 'booted') { G.phase = 'running'; overlay(null); loopUi(); }
+        else overlay(spec.title, m.text, null, true);
+        break;
+      case 'frame':
+        drawFrame(m.pixels, m.palette);
+        G.worker?.postMessage({ type: 'pixels', buffer: m.pixels.buffer }, [m.pixels.buffer]);
+        break;
+      case 'text': drawText(m.cells); break;
+      case 'stats': G.mips = m.mips; drawHud(); break;
+      case 'saved': if (!m.deleted && spec.saveName?.test(m.name)) G.h?.toast?.(`saved ${m.name} in this browser`); break;
+      case 'exit':
+        G.phase = 'exited';
+        releaseKeys();
+        drawText(m.cells);
+        document.exitPointerLock?.();
+        overlay(null);
+        el('Play2')?.classList.remove('hidden');
+        drawHud();
+        break;
+      case 'error': fail(m.message); break;
+    }
+  }
+
+  function fail(message) {
+    G.phase = 'failed';
+    G.worker?.terminate(); G.worker = null;
+    overlay(`${spec.title} stopped`, message, 'start again', true);
+    drawHud();
+  }
+
+  function pause(why) {
+    if (G.phase !== 'running') return;
+    G.phase = 'paused'; G.why = why;
+    releaseKeys();
+    G.worker?.postMessage({ type: 'run', on: false });
+    G.audio?.suspend().catch(() => {});
+    document.exitPointerLock?.();
+    overlay(why, 'the machine is holding exactly where it was', 'resume', true);
+    drawHud();
+  }
+
+  function resume() {
+    if (G.phase === 'paused') {
+      G.phase = 'running';
+      overlay(null);
+      G.audio?.resume().catch(() => {});
+      G.worker?.postMessage({ type: 'run', on: true });
+      loopUi();
+      drawHud();
+      return;
+    }
+    if (G.phase === 'idle' || G.phase === 'exited' || G.phase === 'failed') {
+      el('Play2')?.classList.add('hidden');
+      powerOn();
+    }
+  }
+
+  // the page's own loop: pause on leaving, batch the mouse, count frames
+  function loopUi() {
+    if (G.raf) return;
+    const tick = (t) => {
+      G.raf = null;
+      if (G.phase !== 'running') return;
+      if (document.hidden || G.state?.page !== spec.page) { pause(document.hidden ? 'paused — you looked away' : 'paused — you changed tabs'); return; }
+      if (G.mouse.dirty) {
+        G.worker?.postMessage({ type: 'mouse', dx: G.mouse.dx, dy: G.mouse.dy, buttons: G.mouse.buttons });
+        G.mouse.dx = 0; G.mouse.dy = 0; G.mouse.dirty = false;
+      }
+      if (t - G.fpsAt >= 1000) { G.fps = G.frames * 1000 / (t - G.fpsAt || 1000); G.frames = 0; G.fpsAt = t; drawHud(); }
+      G.raf = requestAnimationFrame(tick);
+    };
+    G.fpsAt = performance.now(); G.frames = 0;
+    G.raf = requestAnimationFrame(tick);
+  }
+
+  // ---------------------------------------------------------------- input
+  function releaseKeys() {
+    const codes = [];
+    for (const code of G.held) codes.push(...(scancodes(code, false) ?? []));
+    G.held.clear();
+    if (codes.length) G.worker?.postMessage({ type: 'key', codes });
+    if (G.mouse.buttons) { G.mouse.buttons = 0; G.mouse.dirty = true; }
+  }
+
+  function onKey(e, down) {
+    if (G.state?.page !== spec.page || G.phase !== 'running') return;
+    const tag = e.target?.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+    if (e.metaKey || e.code === 'F12') return;             // the browser's own shortcuts and tools
+    const codes = scancodes(e.code, down);
+    if (!codes) return;
+    e.preventDefault();
+    if (down) G.held.add(e.code); else G.held.delete(e.code);
+    if (codes.length) G.worker?.postMessage({ type: 'key', codes });
+  }
+
+  function bind() {
+    if (G.bound) return;
+    G.bound = true;
+    document.addEventListener('keydown', (e) => onKey(e, true));
+    document.addEventListener('keyup', (e) => onKey(e, false));
+    window.addEventListener('blur', () => releaseKeys());
+    document.addEventListener('visibilitychange', () => { if (document.hidden) pause('paused — you looked away'); });
+    const c = el('Screen');
+    c?.addEventListener('click', () => { if (G.phase === 'running' && document.pointerLockElement !== c) c.requestPointerLock?.(); });
+    c?.addEventListener('contextmenu', (e) => e.preventDefault());
+    document.addEventListener('mousemove', (e) => {
+      if (document.pointerLockElement !== c || G.phase !== 'running') return;
+      G.mouse.dx += e.movementX; G.mouse.dy += e.movementY; G.mouse.dirty = true;
+    });
+    const buttons = (e) => {
+      if (document.pointerLockElement !== c || G.phase !== 'running') return;
+      // DOS mouse bits and the DOM's agree: 1 left, 2 right, 4 middle
+      G.mouse.buttons = e.buttons & 7; G.mouse.dirty = true;
+    };
+    document.addEventListener('mousedown', buttons);
+    document.addEventListener('mouseup', buttons);
+    el('Play')?.addEventListener('click', () => resume());
+    el('Play2')?.addEventListener('click', () => resume());
+    for (const sw of spec.switches ?? []) {
+      el(sw.id)?.addEventListener('click', () => {
+        const next = sw.flip(switchValue(sw));
+        setPref(sw.pref, next);
+        drawHud();
+        sw.apply?.(next, G);
+      });
+    }
+    el('Smooth')?.addEventListener('click', () => { setPref(SMOOTH_KEY, pref(SMOOTH_KEY, '0') === '1' ? '0' : '1'); drawHud(); });
+    el('Sound')?.addEventListener('click', () => {
+      const mute = pref(MUTE_KEY, '0') !== '1';
+      setPref(MUTE_KEY, mute ? '1' : '0');
+      if (G.gain) G.gain.gain.value = mute ? 0 : 1;
+      drawHud();
+    });
+    // FULL SCREEN, AND A WAY BACK (operator, 2026-09-15: "I can't exit fullscreen in the dos emulated
+    // games"). The keyboard lock on Escape is what lets a tap of Esc reach the game's own menu in
+    // full screen -- and it is also what takes away the browser's Esc-to-leave. So two ways out:
+    // an "exit full screen" button in the corner (drawn only while full screen), and HOLDING Esc
+    // for a second, which the page times itself rather than trusting the browser's own hold
+    // gesture (Chrome has one under keyboard lock; Firefox has no keyboard lock at all). Leaving
+    // unlocks the keyboard and lets the mouse go.
+    const leave = () => { if (document.fullscreenElement) document.exitFullscreen?.().catch(() => {}); };
+    el('Full')?.addEventListener('click', () => {
+      const wrap = el('Wrap');
+      if (!wrap?.requestFullscreen) return;
+      if (!wrap.querySelector('.dosexit')) {
+        const b = document.createElement('button');
+        b.type = 'button'; b.className = 'btn dosexit'; b.textContent = 'exit full screen'; b.title = 'or hold Esc for a second';
+        b.addEventListener('click', leave);
+        wrap.appendChild(b);
+      }
+      wrap.requestFullscreen().then(() => navigator.keyboard?.lock?.(['Escape'])).catch(() => {});
+    });
+    document.addEventListener('fullscreenchange', () => {
+      if (!document.fullscreenElement) { navigator.keyboard?.unlock?.(); document.exitPointerLock?.(); }
+    });
+    let escHold = null;
+    document.addEventListener('keydown', (e) => {
+      if (e.key !== 'Escape' || !document.fullscreenElement || e.repeat) return;
+      escHold = setTimeout(() => { escHold = null; leave(); }, 1000);
+    });
+    document.addEventListener('keyup', (e) => { if (e.key === 'Escape' && escHold) { clearTimeout(escHold); escHold = null; } });
+  }
+
+  /** The page's render hook, called by app.js whenever the app draws. */
+  return function render(s, state, h) {
+    G.state = state; G.h = h;
+    bind();
+    drawHud();
+    if (G.phase === 'idle') { overlay(spec.title, spec.idleText, 'play', false); return; }
+    if (G.phase === 'paused') overlay(G.why, 'the machine is holding exactly where it was', 'resume', true);
+  };
+}

package/public/js/dosio.js

@@ -0,0 +1,186 @@
+// DOS I/O: the pure pieces between a browser and the emulated PC, for the DOOM and Quake Diversions
+// (operator, 2026-09-15: "Get DOOM working as a diversion inside blockyard with zero dependancies",
+// then "get Quake working as a diversion"). No DOM, no worker, no clock, so every mapping here runs
+// under node:test.
+//
+//   GAMES            each game's files, arguments and where its saves are kept (Wolfenstein 3D, DOOM, Quake)
+//   scancodes()      a KeyboardEvent.code as the bytes a PC/AT keyboard puts on port 60h
+//   withControls()   DOOM's config with the page's control scheme laid over it
+//   rebindKeys()     the same, into a running DOOM
+//   quakeAutoexec()  Quake's first-run WASD and mouse look
+//   CP437 / CGA      how text mode's bytes and attributes become characters and colours
+//   paletteLut()     the VGA DAC's 6-bit palette as 32-bit pixels for an ImageData
+
+// ------------------------------------------------------------------ the games
+/**
+ * What the worker fetches for each game, from /games/<name>/: the executable, the files it cannot
+ * start without, the ones it can, the command line, and the IndexedDB database its saves live in.
+ * Paths are DOS paths under the game's directory, upper case.
+ */
+export const GAMES = Object.freeze({
+  // a real-mode program: the data files are the .WL1s, CONFIG.WL1 its settings and high scores
+  wolf3d: Object.freeze({ exe: 'WOLF3D.EXE', required: ['AUDIOHED.WL1', 'AUDIOT.WL1', 'GAMEMAPS.WL1', 'MAPHEAD.WL1', 'VGADICT.WL1', 'VGAGRAPH.WL1', 'VGAHEAD.WL1', 'VSWAP.WL1'], optional: ['CONFIG.WL1'], config: 'CONFIG.WL1', args: '', db: 'blockyard-wolf3d', label: 'WOLF3D.EXE and its data files', dir: 'games/wolf3d_dos' }),
+  doom: Object.freeze({ exe: 'DOOM.EXE', required: ['DOOM1.WAD'], optional: ['DEFAULT.CFG'], config: 'DEFAULT.CFG', args: '', db: 'blockyard-doom', label: 'DOOM.EXE and DOOM1.WAD', dir: 'games/doom_dos' }),
+  // -nocdaudio: there is no CD in the drive, and without it Quake stops at a "press a key" warning
+  quake: Object.freeze({ exe: 'QUAKE.EXE', required: ['ID1/PAK0.PAK'], optional: ['ID1/CONFIG.CFG'], config: 'ID1/CONFIG.CFG', args: '-nocdaudio', db: 'blockyard-quake', label: 'QUAKE.EXE and ID1/PAK0.PAK', dir: 'games/quake_dos' }),
+});
+
+/**
+ * QUAKE'S AUTOEXEC.CFG, which it runs after its config on every start. Mouse look always -- Quake 1
+ * did not save it, and a browser game without it is a fight with the mouse -- and, the first time
+ * only (no config the game wrote itself yet), W A S D to move and Space to jump. After that the
+ * game's own saved bindings are the player's, and this does not overwrite them.
+ */
+export function quakeAutoexec({ firstRun }) {
+  const lines = ['+mlook'];
+  if (firstRun) lines.push('bind "w" "+forward"', 'bind "s" "+back"', 'bind "a" "+moveleft"', 'bind "d" "+moveright"', 'bind "SPACE" "+jump"', 'bind "MOUSE2" "+jump"');
+  // A SMALLER VIEW, the first time (operator, 2026-09-15: "we need to render it in a smaller window,
+  // so it runs faster"): Quake draws 3D only inside its view, and measured on this PC's emulator
+  // timedemo demo1 went 29.7 fps at viewsize 100, 32.5 at 80, 40.5 at 60. 80 keeps the status bar
+  // and a border; - and = change it in the game, and Quake saves the choice with its config.
+  if (firstRun) lines.push('viewsize 80');
+  const text = `${lines.join('\n')}\n`;
+  return Uint8Array.from(text, (c) => c.charCodeAt(0));
+}
+
+// ------------------------------------------------------------------ the keyboard
+// Scancode set 1: the make code; the break code is the same with bit 7 set. Keys that arrived with
+// the AT's extra cluster are sent after an 0xE0 prefix, the way the hardware does -- DOOM's own
+// keyboard handler skips the prefix and reads the arrows as the keypad's 8, 4, 6 and 2.
+const SET1 = {
+  Escape: 0x01, Digit1: 0x02, Digit2: 0x03, Digit3: 0x04, Digit4: 0x05, Digit5: 0x06, Digit6: 0x07, Digit7: 0x08,
+  Digit8: 0x09, Digit9: 0x0a, Digit0: 0x0b, Minus: 0x0c, Equal: 0x0d, Backspace: 0x0e, Tab: 0x0f,
+  KeyQ: 0x10, KeyW: 0x11, KeyE: 0x12, KeyR: 0x13, KeyT: 0x14, KeyY: 0x15, KeyU: 0x16, KeyI: 0x17, KeyO: 0x18, KeyP: 0x19,
+  BracketLeft: 0x1a, BracketRight: 0x1b, Enter: 0x1c, ControlLeft: 0x1d,
+  KeyA: 0x1e, KeyS: 0x1f, KeyD: 0x20, KeyF: 0x21, KeyG: 0x22, KeyH: 0x23, KeyJ: 0x24, KeyK: 0x25, KeyL: 0x26,
+  Semicolon: 0x27, Quote: 0x28, Backquote: 0x29, ShiftLeft: 0x2a, Backslash: 0x2b,
+  KeyZ: 0x2c, KeyX: 0x2d, KeyC: 0x2e, KeyV: 0x2f, KeyB: 0x30, KeyN: 0x31, KeyM: 0x32,
+  Comma: 0x33, Period: 0x34, Slash: 0x35, ShiftRight: 0x36, NumpadMultiply: 0x37, AltLeft: 0x38, Space: 0x39,
+  CapsLock: 0x3a, F1: 0x3b, F2: 0x3c, F3: 0x3d, F4: 0x3e, F5: 0x3f, F6: 0x40, F7: 0x41, F8: 0x42, F9: 0x43, F10: 0x44,
+  NumLock: 0x45, ScrollLock: 0x46, Numpad7: 0x47, Numpad8: 0x48, Numpad9: 0x49, NumpadSubtract: 0x4a,
+  Numpad4: 0x4b, Numpad5: 0x4c, Numpad6: 0x4d, NumpadAdd: 0x4e, Numpad1: 0x4f, Numpad2: 0x50, Numpad3: 0x51,
+  Numpad0: 0x52, NumpadDecimal: 0x53, IntlBackslash: 0x56, F11: 0x57, F12: 0x58,
+};
+const EXTENDED = {
+  NumpadEnter: 0x1c, ControlRight: 0x1d, NumpadDivide: 0x35, AltRight: 0x38, Home: 0x47, ArrowUp: 0x48, PageUp: 0x49,
+  ArrowLeft: 0x4b, ArrowRight: 0x4d, End: 0x4f, ArrowDown: 0x50, PageDown: 0x51, Insert: 0x52, Delete: 0x53,
+  MetaLeft: 0x5b, MetaRight: 0x5c, ContextMenu: 0x5d,
+};
+
+/** The bytes for a key going down (`down`) or up, or null for a key the PC keyboard does not have. */
+export function scancodes(code, down) {
+  if (code === 'Pause') return down ? [0xe1, 0x1d, 0x45, 0xe1, 0x9d, 0xc5] : [];
+  if (code in SET1) return [down ? SET1[code] : SET1[code] | 0x80];
+  if (code in EXTENDED) return [0xe0, down ? EXTENDED[code] : EXTENDED[code] | 0x80];
+  return null;
+}
+
+// ------------------------------------------------------------------ the config
+/** Scancodes the two control schemes bind, by DOOM's config key. WASD is the default. */
+export const CONTROLS = {
+  classic: { key_up: 72, key_down: 80, key_left: 75, key_right: 77, key_strafeleft: 51, key_straferight: 52, key_use: 57 },
+  wasd: { key_up: 17, key_down: 31, key_left: 75, key_right: 77, key_strafeleft: 30, key_straferight: 32, key_use: 18 },
+};
+export const DEFAULT_CONTROLS = 'wasd';
+
+// DOOM's own key codes for those scancodes (its scantokey table): letters and punctuation are their
+// lowercase ASCII, the arrows are 0xac-0xaf
+const DOOM_KEY = { 17: 119, 31: 115, 30: 97, 32: 100, 18: 101, 72: 0xad, 80: 0xaf, 75: 0xac, 77: 0xae, 51: 44, 52: 46, 57: 32 };
+
+/**
+ * REBIND A RUNNING DOOM (operator, 2026-09-15: "have to refresh for settings to take effect").
+ * DOOM reads its keys from default.cfg once, at start-up, into its defaults table: one 20-byte
+ * entry a setting -- the name's address, the address of the live int, the default, whether the
+ * value is a scancode, and the scancode as read (which is what the game writes back on quit). This
+ * finds each key's entry by its name in the program's memory and writes both the live key code and
+ * the scancode, so the change applies to the next key press and survives the config DOOM saves.
+ * Returns how many settings it rewrote (0 before the program is loaded, or for an unknown build).
+ */
+export function rebindKeys(mem, controls, cache = {}) {
+  const scheme = CONTROLS[controls];
+  if (!scheme) return 0;
+  const dv = new DataView(mem.buffer, mem.byteOffset, mem.length);
+  const lo = 0x100000, hi = Math.min(mem.length - 32, 0x400000);   // where the loader puts the program
+  let n = 0;
+  for (const [key, scan] of Object.entries(scheme)) {
+    let entry = cache[key];
+    if (entry === undefined) {
+      entry = null;
+      const name = [...key].map((c) => c.charCodeAt(0)).concat(0);
+      for (let i = lo; i < hi && entry === null; i++) {
+        if (mem[i] !== name[0]) continue;
+        let j = 1;
+        while (j < name.length && mem[i + j] === name[j]) j++;
+        if (j < name.length) continue;
+        // a name alone is not proof (the linker packs strings, so no terminator need precede one):
+        // the entry is the 4-aligned pointer to it whose scantranslate field says it is a key
+        for (let p = lo & ~3; p < hi; p += 4) {
+          if (dv.getUint32(p, true) === i && dv.getUint32(p + 12, true) === 1) { entry = p; break; }
+        }
+      }
+      cache[key] = entry;
+    }
+    if (entry === null) continue;
+    const live = dv.getUint32(entry + 4, true);
+    if (live < lo || live >= hi) continue;
+    dv.setInt32(live, DOOM_KEY[scan], true);
+    dv.setInt32(entry + 16, scan, true);
+    n++;
+  }
+  return n;
+}
+
+/**
+ * DOOM's config (its `default.cfg`, bytes) with a control scheme laid over it. Every scheme turns
+ * the mouse on: the shipped file has `use_mouse 0`, and a browser always has one. A key missing
+ * from the file is appended rather than dropped, so a config the game wrote itself survives.
+ */
+export function withControls(bytes, controls = DEFAULT_CONTROLS) {
+  let text = '';
+  for (const b of bytes) text += String.fromCharCode(b);
+  const set = (key, value) => {
+    const re = new RegExp(`^(${key}[ \\t]+)\\S+`, 'm');
+    text = re.test(text) ? text.replace(re, `$1${value}`) : `${text.replace(/\s*$/, '')}\n${key}\t\t${value}\n`;
+  };
+  set('use_mouse', 1);
+  for (const [k, v] of Object.entries(CONTROLS[controls] ?? {})) set(k, v);
+  const out = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i) & 0xff;
+  return out;
+}
+
+// ------------------------------------------------------------------ text mode
+/** Code page 437 as Unicode, so text mode's box drawing and ENDOOM's blocks draw as they did. */
+export const CP437 = '\u0000☺☻♥♦♣♠•◘○◙♂♀♪♫☼►◄↕‼¶§▬↨↑↓→←∟↔▲▼ !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~⌂'
+  + 'ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀'
+  + 'αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■ ';
+
+/** The sixteen text-mode colours, as CSS. */
+export const CGA = ['#000000', '#0000aa', '#00aa00', '#00aaaa', '#aa0000', '#aa00aa', '#aa5500', '#aaaaaa',
+  '#555555', '#5555ff', '#55ff55', '#55ffff', '#ff5555', '#ff55ff', '#ffff55', '#ffffff'];
+
+/** An 80x25 text screen's cells as rows of runs: [{ x, y, text, fg, bg }], same colours merged. */
+export function textRuns(cells) {
+  const runs = [];
+  for (let y = 0; y < 25; y++) {
+    let cur = null;
+    for (let x = 0; x < 80; x++) {
+      const i = (y * 80 + x) * 2;
+      const ch = CP437[cells[i]] ?? ' ', attr = cells[i + 1];
+      const fg = CGA[attr & 15], bg = CGA[(attr >> 4) & 7];
+      if (cur && cur.fg === fg && cur.bg === bg) cur.text += ch;
+      else { cur = { x, y, text: ch, fg, bg }; runs.push(cur); }
+    }
+  }
+  return runs;
+}
+
+// ------------------------------------------------------------------ the palette
+/** The DAC's 768 six-bit components as little-endian ABGR pixels (what an ImageData's Uint32 view holds). */
+export function paletteLut(pal, out = new Uint32Array(256)) {
+  for (let i = 0; i < 256; i++) {
+    const r = Math.round((pal[i * 3] & 63) * 255 / 63), g = Math.round((pal[i * 3 + 1] & 63) * 255 / 63), b = Math.round((pal[i * 3 + 2] & 63) * 255 / 63);
+    out[i] = (0xff << 24 | (b << 16) | (g << 8) | r) >>> 0;
+  }
+  return out;
+}