@moonbase-machines/player 0.12.0 → 0.13.0

package/engines/original.js

@@ -9,6 +9,8 @@
 // { choice ('commodore' or 'moonbase-petscii', @moonbase-machines/c64/start.js), load: async name => a ROM's bytes };
 // and `studies`, files of its own for a Commodore 64 game's disk, a name to its bytes in base64, in the drive, not kept.
 import { Speaker } from '../audio.js';
+import { typing as typingOf } from '../keys.js';
+import { pace } from '@moonbase-machines/mos6502/pace.js';
 
 // the setting the Apple's engine acts on (play.js `setting`): its pictures drawn as vectors over the screen
 const VECTORS = { name: 'vectors', type: 'boolean', default: false, owner: 'person', words: 'Draw the pictures as vectors' };
@@ -68,8 +70,10 @@ const rgba = new Uint8ClampedArray(560 * 384 * 4);
 const image = new ImageData(rgba, 560, 384);
 const cols = new Uint8Array(140 * 192);
 let mode = '';
-function frame() {
-  if (!m.halted) m.runCycles(17030);   // a frame's worth of the Apple's clock, at 60 a second
+// the Apple's frames, 60 a second against the clock (@moonbase-machines/mos6502/pace.js), the screen painted each
+// animation frame
+const frame = () => { if (!m.halted) m.runCycles(17030); };   // a frame's worth of the Apple's clock
+function after() {
   const now = `text ${m.sw.text} page2 ${m.sw.page2} hires ${m.sw.hires} dhires ${m.sw.dhires}`;
   if (now !== mode) { console.log('screen:', now, 'at pc $' + m.cpu.pc.toString(16), 'cycles', m.cpu.cycles); mode = now; }
   speaker.feed(sound ? m.clicks : [], m.cpu.cycles); m.clicks.length = 0;
@@ -79,13 +83,12 @@ function frame() {
   ctx.putImageData(image, 0, 0);
   layer.style.visibility = vectors.value && !text ? 'visible' : 'hidden';
   status.textContent = m.halted ? 'The game has stopped: ' + m.halted + '.' : (m.idle > 2000 ? 'Waiting for a key.' : 'Running.');
-  requestAnimationFrame(frame);
 }
 canvas.addEventListener('pointerdown', () => canvas.focus());
 // (the keys, the Apple's codes, given by the player: play.js, keys.js)
 let sound = true;
 return {
-  run() { canvas.focus(); frame(); },
+  run() { canvas.focus(); pace(frame, 60, { after }); },
   press(k) { console.log('key', k, 'at pc $' + m.cpu.pc.toString(16)); m.press(k); },
   start() { speaker.start(); },
   sound(on) { sound = on; },
@@ -96,7 +99,9 @@ return {
 // A C64 game: on moonbase's own ROMs (@moonbase-machines/c64/rom.js), as the site has it everywhere, or on
 // Commodore's where the page gives them (`roms`) and asks for them; the machine autostarted
 // with LOAD"name",8,1, and RUN for a BASIC program, typed into the KERNAL's buffer, the frame on a canvas of
-// 384 by 272 doubled, the keys as the matrix, the arrows its cursor keys, and a gamepad the joystick.
+// 384 by 272 doubled, the keys as the matrix, the arrows its cursor keys, and a gamepad the joystick. A demonstration
+// (play.js `demonstrate`, the game's data's steps) is typed into the same buffer the same way, after the start, the game
+// taking each key when it asks for one; the person's first key or push of the stick drops what is left of it.
 async function c64(g, { canvas, layer, speaker }) {
   const { game, saves, roms: makers, studies, status, printer } = g;
   const [{ C64 }, { keyboard, painter }, { SID }, { c64Roms, typed: startTyped }, { add }] = await Promise.all([
@@ -115,36 +120,42 @@ async function c64(g, { canvas, layer, speaker }) {
   for (const [file, data] of Object.entries(studies ?? {})) m.drive.saved.set(file, raw(data));
   layer.style.display = 'none';
   const draw = painter(canvas);
-  let typing = null, typed = 0, sound = true;
+  let typing = null, typed = 0, sound = true, demo = null;
+  // (the person at the keys or the stick: what is left of a demonstration is theirs to stop)
+  const theirs = () => { demo = null; };
   // the keys as the 64's matrix (@moonbase-machines/c64/browser.js), given them by the player (play.js)
   const listeners = { keydown: [], keyup: [] };
   const keys = keyboard(m, { log: true, listen: (type, f) => listeners[type].push(f) });
   // once BASIC is ready, the start typed in; the KERNAL's buffer takes ten characters at a time.
-  // The C64 runs 50 frames a second, so frames are run to keep up with the clock, two at most.
-  let frames = 0, sid = null, started = performance.now();
-  function frame() {
-    const due = Math.min(2, Math.floor((performance.now() - started) / 20) - frames);
-    for (let i = 0; i < due; i++) {
-      m.runFrame(); frames++; keys.frame();
-      if (speaker.node && sound) {
-        if (!sid) sid = new SID(speaker.rate);
-        const n = Math.round(19656 / 985248 * speaker.rate), first = m.cpu.cycles - 19656;
-        const wave = sid.render(n, m.sidWrites.map(([c, r, v]) => [Math.floor((c - first) / 19656 * n), r, v]));
-        speaker.node.port.postMessage(wave, [wave.buffer]);
-      }
-      m.sidWrites.length = 0;
+  // The C64 runs 50 frames a second against the clock (@moonbase-machines/mos6502/pace.js: a hitch caught up, a pause
+  // dropped), the SID's frame rendered with each, and the screen painted each animation frame
+  let frames = 0, sid = null;
+  const frame = n => {
+    frames = n; m.runFrame(); keys.frame();
+    if (speaker.node && sound) {
+      if (!sid) sid = new SID(speaker.rate);
+      const n = Math.round(19656 / 985248 * speaker.rate), first = m.cpu.cycles - 19656;
+      const wave = sid.render(n, m.sidWrites.map(([c, r, v]) => [Math.floor((c - first) / 19656 * n), r, v]));
+      speaker.node.port.postMessage(wave, [wave.buffer]);
     }
-    // (LOAD, and RUN for a BASIC program: @moonbase-machines/c64/start.js)
+    m.sidWrites.length = 0;
+  };
+  function after() {
+    // (LOAD, and RUN for a BASIC program: @moonbase-machines/c64/start.js; then a demonstration, if one is asked for)
     if (frames >= 120 && typing === null && !typed) { typing = startTyped(m, game); typed = 1; }
-    if (typing !== null && !m.ram[0xc6]) { typing = m.type(typing); if (!typing.length) typing = null; }
+    if (demo !== null && m.joystick) theirs();
+    if (!m.ram[0xc6]) {
+      if (typing !== null) { typing = m.type(typing); if (!typing.length) typing = null; }
+      else if (demo !== null && typed) { demo = m.type(demo); if (!demo.length) demo = null; }
+    }
     draw(m.vic.frame);
     status.textContent = m.halted ? 'The game has stopped: ' + m.halted + '.' : 'Running.';
-    requestAnimationFrame(frame);
   }
   return {
-    run() { canvas.focus(); frame(); },
+    run() { canvas.focus(); pace(frame, 50, { after }); },
     press(k) { m.type(String.fromCharCode(k)); },   // (into the KERNAL's buffer, as typed)
-    key(e) { for (const f of listeners[e.type]) f(e); },
+    key(e) { if (e.type === 'keydown' && !e.repeat) theirs(); for (const f of listeners[e.type]) f(e); },
+    demonstrate(steps) { demo = typingOf(steps, 'c64'); },
     start() { speaker.start(); },
     sound(on) { sound = on; },
     engine: m,

package/engines/scenes.js

@@ -157,7 +157,11 @@ export async function play(g) {
       }
       if (speaker?.node && sounding) {
         sid ??= new SID(speaker.rate); from ??= performance.now();
-        const n = Math.floor((performance.now() - from) / 1000 * speaker.rate) - sent;
+        // (a quarter of a second at most: after a pause, a tab in the background, the sound goes on from now, not from
+        // where it stopped, and no wave the length of the pause is made)
+        let n = Math.floor((performance.now() - from) / 1000 * speaker.rate) - sent;
+        const most = Math.floor(speaker.rate / 4);
+        if (n > most) { sent += n - most; n = most; }
         if (n > 0) { const wave = sid.render(n, engine.sid.map(([, r, v]) => [0, r, v])); sent += n; speaker.node.port.postMessage(wave, [wave.buffer]); }
       }
       engine.sid.length = 0;

package/keys.js

@@ -5,6 +5,9 @@
 //   code(event, kind)     the key's code for the machine of that kind ('prodos', 'dos33' or 'c64'; none for a title
 //                         of its own engine), or undefined for a key it has none for
 //   named(name, kind)     a key by its name in a route or ?keys= (space, return, left...), as the machine's code
+//   typing(steps, kind)   a demonstration's steps (data.js `demonstrations`) as the one string the machine is to be
+//                         given, as typed: each step a key by its name, { key: 'f4' }, or text, { type: '1 PISTONS' };
+//                         a step of any other shape, or a key the machine has no name for, refused
 
 // the Apple II's keyboard: the arrows as its control keys, DELETE, ESC, TAB
 const APPLE = { ArrowLeft: 8, ArrowRight: 21, ArrowDown: 10, ArrowUp: 11, Enter: 13, Backspace: 127, Delete: 127, Escape: 27, Tab: 9, ' ': 32 };
@@ -13,6 +16,9 @@ const C64 = { ArrowLeft: 157, ArrowRight: 29, ArrowDown: 17, ArrowUp: 145, Enter
 // the names a route's keys and ?keys= use, as the Apple's codes, and those a Commodore 64 has in their place
 const NAMES = { space: 32, return: 13, escape: 27, delete: 127, left: 8, right: 21, down: 10, up: 11, 'control-e': 5, 'control-t': 20, none: -1 };
 const PETSCII = { 8: 157, 21: 29, 10: 17, 11: 145, 127: 20, 27: 3 };
+// and the keys a Commodore 64 alone has, by name: its function keys, CLR and HOME, INST and DEL, RUN/STOP, £ and ←, in
+// PETSCII as the KERNAL's GETIN gives them
+const C64_NAMES = { f1: 133, f2: 137, f3: 134, f4: 138, f5: 135, f6: 139, f7: 136, f8: 140, home: 19, clr: 147, inst: 148, del: 20, stop: 3, pound: 92, arrow: 95 };
 
 export function code(e, kind) {
   if (!kind || e.metaKey || e.altKey) return undefined;
@@ -23,6 +29,18 @@ export function code(e, kind) {
 }
 
 export function named(name, kind) {
+  if (kind === 'c64' && name in C64_NAMES) return C64_NAMES[name];
   const k = NAMES[name] ?? name.charCodeAt(0);
   return kind === 'c64' ? PETSCII[k] ?? k : k;
 }
+
+export function typing(steps, kind) {
+  if (!Array.isArray(steps) || !steps.length) throw new Error('a demonstration is a list of steps, each { key } or { type }');
+  return steps.map(s => {
+    const [what, ...more] = Object.keys(s ?? {});
+    if (more.length || !['key', 'type'].includes(what) || typeof s[what] !== 'string' || !s[what]) throw new Error('a step is { key: name } or { type: text }: ' + JSON.stringify(s));
+    if (what === 'type') return kind === 'c64' ? s.type.toUpperCase() : s.type;   // (the 64's letters its capitals, as the keyboard gives them)
+    if (s.key === 'none' || !(s.key in NAMES || (kind === 'c64' && s.key in C64_NAMES))) throw new Error(`no key named ${s.key} for a ${kind} game`);
+    return String.fromCharCode(named(s.key, kind));
+  }).join('');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonbase-machines/player",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The player for Mark Wharton's titles of 1985 to 1995: the Original, a game's own disk on Moonbase's machines, and the Remake, its scenes on an engine; the player's own disk of saves in the browser.",
   "type": "module",
   "license": "MIT",
@@ -14,11 +14,11 @@
     "moonbase-play": "./bin/moonbase-play.mjs"
   },
   "dependencies": {
-    "@moonbase-machines/apple2e": "0.12.0",
-    "@moonbase-machines/c64": "0.12.0",
-    "@moonbase-machines/charset": "0.12.0",
-    "@moonbase-machines/mos6502": "0.12.0",
-    "@moonbase-machines/vector": "0.12.0"
+    "@moonbase-machines/apple2e": "0.13.0",
+    "@moonbase-machines/c64": "0.13.0",
+    "@moonbase-machines/charset": "0.13.0",
+    "@moonbase-machines/mos6502": "0.13.0",
+    "@moonbase-machines/vector": "0.13.0"
   },
   "scripts": {
     "test": "node --test test/*.test.js",

package/play.js

@@ -33,19 +33,22 @@
 //     roms         the makers' ROMs this machine has (engines/original.js; a Commodore 64 remake's { chargen })
 //     studies      files of its own for a Commodore 64 game's disk, in the drive, not kept
 //     downloadDisk a Commodore 64 game's disk offered to download, with what is saved on it
+//   and, from the game's data (data.js `demonstrations`), where the engine can type them: a button for each
+//   demonstration, its name, typing its steps into the game as the keys would be; the person's first key ends it.
 //
 // An engine (engines/original.js, engines/scenes.js, or the title's own, its title.js `engine` a module in its folder)
 // exports `play(game)`: given `game`, the player's own for it (below), it declares the settings it acts on
 // (`game.setting(declaration)`, settings.js, each shown only so), makes what it draws on the stage and returns
 // its handle, or nothing where it cannot start (and has said why in the status):
 //   { run(), press(k)?, key(e, k)?, keys(list)?, route(route)?, start()?, sound(on)?, quick(on)?,
-//     engine?, diskImage()? }
+//     demonstrate(steps)?, engine?, diskImage()? }
 // run() starts it; press(k) a key, the machine's code (none for a title of its own engine with no machine's keys,
 // which reads the keyboard itself); key(e, k), for an engine that reads the keyboard itself, each
 // keydown and keyup with its code (undefined where the machine has none); keys(list), the page's `keys` at the start;
 // route, the page's route; start(), at the player's first gesture (sound may start only then); sound(on), the
 // player's speaker on or off (the Sound setting; a game's own sound setting stays the game's); quick(on) the game at
-// full speed; engine, what `watch` gives a page; diskImage(), the disk to download.
+// full speed; demonstrate(steps), a demonstration's steps typed into the game; engine, what `watch` gives a page;
+// diskImage(), the disk to download.
 import { titleOf, loadTitle, read } from './remake/load.js';
 import { savesFor } from './saves.js';
 import { code, named } from './keys.js';
@@ -162,6 +165,12 @@ export async function play(options) {
         a.click(); URL.revokeObjectURL(a.href);
       });
     }
+    // the game's demonstrations (data.js), where the engine types them: a button each, named as the data names it
+    if (handle.demonstrate) for (const d of game?.demonstrations ?? []) {
+      const button = Object.assign(document.createElement('button'), { type: 'button', textContent: d.name });
+      button.addEventListener('click', () => { handle.start?.(); handle.demonstrate(d.steps); });
+      $('disk').before(button);
+    }
     // a page that follows the game: its engine, a key pressed as the player presses one, the game at full speed
     options.watch?.({ engine: handle.engine, press: k => { handle.start?.(); handle.press?.(k); }, quick: on => handle.quick?.(on) });
     // a route the page gives, played first; then the game; then the page's keys, to go straight to a scene

package/test/play.test.js

@@ -9,7 +9,8 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { code, named } from '@moonbase-machines/player/keys.js';
+import { code, named, typing } from '@moonbase-machines/player/keys.js';
+import { gameData } from '@moonbase-machines/player/data.js';
 import { savesFor } from '@moonbase-machines/player/saves.js';
 import { openDisk } from '@moonbase-machines/player/disk/disk.js';
 import { memory } from '@moonbase-machines/player/disk/memory.js';
@@ -34,6 +35,24 @@ test('a key is the Apple\'s code or the Commodore 64\'s, by the machine\'s kind'
   assert.deepEqual(['left', 'delete'].map(n => named(n, 'c64')), [157, 20]);
 });
 
+test('a demonstration\'s steps as typed: the 64\'s own keys by name, its text in capitals; a step of another shape refused', () => {
+  assert.deepEqual(['f1', 'f4', 'f8', 'return', 'stop', 'clr', 'pound'].map(n => named(n, 'c64')), [133, 138, 140, 13, 3, 147, 92]);
+  assert.equal(typing([{ key: 'return' }, { key: 'f4' }, { type: '1 Pistons' }, { key: 'return' }, { key: 'f8' }], 'c64'), '\r\x8a1 PISTONS\r\x8c');
+  assert.equal(typing([{ type: 'run' }, { key: 'return' }], 'prodos'), 'run\r', 'an Apple\'s text as typed');
+  for (const [bad, kind] of [[[], 'c64'], [[{}], 'c64'], [[{ key: 'f4', type: 'x' }], 'c64'], [[{ key: 'none' }], 'c64'], [[{ type: '' }], 'c64'], [[{ press: 'a' }], 'c64'], [[{ key: 'f4' }], 'prodos'], ['f4', 'c64']])
+    assert.throws(() => typing(bad, kind), JSON.stringify(bad));
+});
+
+test('a game\'s data carries its demonstrations, each step checked; a game of another kind refused one', () => {
+  const disk = make({ name: 'DISK', id: 'MB', files: [] }), steps = [{ key: 'return' }, { key: 'f8' }];
+  const c64 = more => ({ title: 'GAME', kind: 'c64', disks: [disk], start: 'GAME', ...more });
+  assert.deepEqual(gameData('game', c64({ demonstrations: [{ name: 'Frames', steps }] })).data.demonstrations, [{ name: 'Frames', steps }]);
+  assert.equal(gameData('game', c64({})).data.demonstrations, undefined);
+  assert.throws(() => gameData('game', c64({ demonstrations: [{ name: 'Frames', steps: [{ key: 'f9' }] }] })), /no key named f9/);
+  assert.throws(() => gameData('game', c64({ demonstrations: [{ steps }] })), /has a name/);
+  assert.throws(() => gameData('game', { title: 'GAME', kind: 'dos33', disks: [], demonstrations: [{ name: 'Frames', steps }] }), /C64 game only/);
+});
+
 test('the saves: a game\'s volume given what is kept, and a change to its files kept', async () => {
   const disk = await openDisk('title/one', { backend: memory() });
   disk.write('KEPT', [1, 2], { type: 'BIN', aux: 0x2000 });