Public: anyone can read this; the crew can change it.

Migrated from github.com/amirmushichge/pixel-plays

games need to have a much higher playability standard. tests that actually pl… #49

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

quill/pixel-plays:quill/42-games-need-to-have-a-much-higher-playabi → main 2 commits fork 8 threads · 8 unresolved

  • Merged. quill/42-games-need-to-have-a-much-higher-playabi was merged into main as 8c0d92c.

Review

Sign in to review this change.
3 files changed +214 −0
README.md +6
@@ -61,3 +61,9 @@ Create `<id>/index.html`, load `../shell.js`, call `PixelPlays.mount({ id, rules
6161
6262 ## License
6363 The code is under the [MIT License](LICENSE). The music is not: see [MUSIC.md](MUSIC.md).
64
65 ## Playtests
66
67 `playtest.mjs` boots a game page for real (its inline scripts, `shell.js`, `engine.js`) in a `vm` with a small DOM stand-in, then `playtest.test.mjs` plays every game folder with a seeded stand-in for a person: taps, holds, drags (one pointer move per frame) and key presses. Each game must boot without errors, paint a real picture, idle without failing, and, played, differ from an untouched twin of the same seed advanced by the same frame count: in its picture and in its HUD text (score, status). The keyboard alone must part the two as well. So a game that ignores its input fails. A new game folder is picked up automatically. It adds no dependency. The file takes about 1m40s.
68
69 Not yet covered: a per-game script that wins or loses a round and checks the final HUD text.
playtest.mjs added +136
@@ -0,0 +1,136 @@
1 // Boots a real game page (its inline scripts, shell.js and engine.js) in a vm with a small DOM stand-in,
2 // so a test can press, drag and hold on the canvas and watch what the player would see.
3 import { readFileSync } from 'node:fs';
4 import vm from 'node:vm';
5
6 const W = 360, H = 280;
7 const ROOT = new URL('.', import.meta.url);
8
9 class Element {
10 constructor(id = '') {
11 this.id = id; this.children = []; this.listeners = {}; this.style = {}; this.dataset = {}; this.attrs = {};
12 this.classList = { add() {}, remove() {}, toggle() {}, contains: () => false };
13 this.textContent = ''; this.innerHTML = ''; this.hidden = false; this.disabled = false; this.value = '';
14 this.width = W; this.height = H;
15 }
16 addEventListener(type, fn) { (this.listeners[type] ??= []).push(fn); }
17 removeEventListener(type, fn) { this.listeners[type] = (this.listeners[type] ?? []).filter(f => f !== fn); }
18 append(...n) { this.children.push(...n); }
19 prepend(...n) { this.children.unshift(...n); }
20 appendChild(n) { this.children.push(n); return n; }
21 contains() { return false; }
22 setAttribute(k, v) { this.attrs[k] = String(v); }
23 getAttribute(k) { return this.attrs[k] ?? null; }
24 focus() {} blur() {} showModal() {} close() {} setPointerCapture() {} releasePointerCapture() {}
25 querySelector() { return null; }
26 querySelectorAll() { return []; }
27 getBoundingClientRect() { return { left: 0, top: 0, right: W, bottom: H, width: W, height: H }; }
28 get clientWidth() { return W; }
29 get clientHeight() { return H; }
30 fire(type, props = {}) {
31 const e = { type, target: this, pointerId: 1, pointerType: 'mouse', button: 0, buttons: 1, clientX: 0, clientY: 0, key: '', repeat: false, shiftKey: false, preventDefault() {}, stopPropagation() {}, ...props };
32 for (const fn of this.listeners[type] ?? []) fn(e);
33 }
34 }
35
36 // a seeded Math.random so a run is the same every time
37 function seeded(seed) { return () => { seed = (seed * 1664525 + 1013904223) >>> 0; return seed / 4294967296; }; }
38
39 // Date whose now() follows the fake clock, so two runs of one game are the same run
40 function fakeDate(now) {
41 return class extends Date { constructor(...a) { super(...(a.length ? a : [now()])); } static now() { return now(); } };
42 }
43
44 export function boot(id, { seed = 1 } = {}) {
45 const els = {}, errors = [], frames = [], timers = [];
46 const store = {};
47 let clock = 1000, image = null;
48 const get = i => (els[i] ??= new Element(i));
49 const canvas = get('c');
50 canvas.getContext = () => ({
51 createImageData: (w, h) => ({ width: w, height: h, data: new Uint8ClampedArray(w * h * 4) }),
52 putImageData: img => { image = img; }, drawImage() {}, clearRect() {}, fillRect() {},
53 });
54 const doc = new Element('document');
55 Object.assign(doc, {
56 head: new Element('head'), body: new Element('body'), hidden: false,
57 createElement: () => new Element(), getElementById: get, querySelector: s => get(s),
58 documentElement: new Element('html'),
59 });
60 const ctx = vm.createContext({
61 console, Math: Object.create(Math, { random: { value: seeded(seed) } }), Uint8Array, Uint8ClampedArray, Uint32Array, Float32Array, Float64Array, Int32Array,
62 Object, Array, Number, String, Boolean, JSON, Date: fakeDate(() => clock), Map, Set, WeakMap, WeakSet, Symbol, Error, Promise, RegExp, isNaN, isFinite, parseInt, parseFloat,
63 document: doc, innerWidth: W * 3, innerHeight: H * 3 + 40, devicePixelRatio: 1,
64 performance: { now: () => clock },
65 localStorage: { getItem: k => store[k] ?? null, setItem: (k, v) => { store[k] = String(v); }, removeItem: k => { delete store[k]; } },
66 Audio: class { play() { return Promise.resolve(); } pause() {} },
67 matchMedia: () => ({ matches: false, addEventListener() {} }),
68 navigator: { vibrate() {}, userAgent: 'playtest' },
69 requestAnimationFrame: fn => { frames.push(fn); return frames.length; },
70 cancelAnimationFrame() {},
71 setTimeout: (fn, ms) => { timers.push({ fn, at: clock + (ms || 0) }); return timers.length; },
72 clearTimeout: n => { if (timers[n - 1]) timers[n - 1].fn = null; },
73 setInterval: () => 0, clearInterval() {},
74 });
75 ctx.window = ctx; ctx.globalThis = ctx; ctx.self = ctx;
76 ctx.addEventListener = (type, fn) => doc.addEventListener(type, fn);
77 ctx.removeEventListener = () => {};
78 ctx.__errors = errors;
79
80 const html = readFileSync(new URL(`${id}/index.html`, ROOT), 'utf8');
81 const scripts = [...html.matchAll(/<script(?:\s+src="([^"]+)")?[^>]*>([\s\S]*?)<\/script>/g)];
82 for (const [, src, inline] of scripts) {
83 const file = src ?? 'inline';
84 const code = src ? readFileSync(new URL(`${id}/${src}`, ROOT), 'utf8') : inline;
85 try { new vm.Script(code, { filename: `${id}/${file}` }).runInContext(ctx); }
86 catch (e) { errors.push(e); }
87 }
88
89 const api = {
90 errors, els, canvas, window: ctx,
91 el: get,
92 // every piece of text on the page, as the player would read it
93 text: () => Object.values(els).map(e => e.textContent).filter(Boolean).join(' | '),
94 // a cheap fingerprint of the picture on the canvas
95 picture() {
96 if (!image) return 0;
97 let h = 2166136261;
98 const d = new Uint32Array(image.data.buffer);
99 for (let i = 0; i < d.length; i++) h = Math.imul(h ^ d[i], 16777619);
100 return h >>> 0;
101 },
outdated

Rounding seconds to frames here causes the drift behind both false positives. Consider counting frames explicitly, or exposing a frame counter, so tests can compare like with like.

102 // number of distinct colours painted: a blank frame has one
103 colours() { return image ? new Set(new Uint32Array(image.data.buffer)).size : 0; },
104 // advance by `seconds` of play
105 frames: 0,
106 run(seconds) { api.step(Math.round(seconds * 25)); }, // 25 fps: the games cap a step at 1/25 s, so none runs slower than real time
107 // advance by a whole number of frames; `api.frames` counts them so twins can be compared
108 step(n) {
109 for (let i = 0; i < n; i++) {
110 api.frames++;
111 clock += 1000 / 25;
112 for (const t of timers) if (t.fn && t.at <= clock) { const f = t.fn; t.fn = null; try { f(); } catch (e) { errors.push(e); } }
113 const queue = frames.splice(0);
114 for (const f of queue) { try { f(clock); } catch (e) { errors.push(e); } }
115 }
116 },
117 // pointer and key input, in canvas pixels (360 by 280)
118 down(x, y) { canvas.fire('pointerdown', { clientX: x, clientY: y }); },
outdated

run(seconds/steps) is run(1/60), and Math.round(25/60) is 0, so the drag runs no frames. Move one step per frame instead, for example steps = Math.max(2, Math.round(seconds*25)) with run(1/25).

119 move(x, y, buttons = 1) { canvas.fire('pointermove', { clientX: x, clientY: y, buttons }); },
120 up(x, y) { canvas.fire('pointerup', { clientX: x, clientY: y, buttons: 0 }); },
121 tap(x, y) { api.down(x, y); api.run(.08); api.up(x, y); api.run(.05); },
122 hold(x, y, seconds) { api.down(x, y); api.run(seconds); api.up(x, y); api.run(.05); },
123 drag(from, to, seconds = .4) {
124 api.down(from[0], from[1]);
125 const steps = Math.max(2, Math.round(seconds * 25)); // one move per frame, so the pointer travels
126 for (let i = 1; i <= steps; i++) { api.move(from[0] + (to[0] - from[0]) * i / steps, from[1] + (to[1] - from[1]) * i / steps); api.step(1); }
127 api.up(to[0], to[1]); api.run(.05);
128 },
129 keyDown(key) { for (const t of [canvas, doc]) t.fire('keydown', { key }); },
130 keyUp(key) { for (const t of [canvas, doc]) t.fire('keyup', { key }); },
131 press(key, seconds = .08) { api.keyDown(key); api.run(seconds); api.keyUp(key); api.run(.05); },
132 store,
133 };
134 api.run(.1);
135 return api;
136 }
playtest.test.mjs added +72
@@ -0,0 +1,72 @@
1 import { test, expect, setDefaultTimeout } from 'bun:test';
2 import { readdirSync } from 'node:fs';
3 import { boot } from './playtest.mjs';
4 setDefaultTimeout(60000);
outdated

Merge this with the bun:test import on line 1.

5
6 // Every game page is booted for real (its scripts, the shell and the engine) and played by a
7 // seeded stand-in for a person: taps, holds, drags and key presses at the canvas.
8 const GAMES = readdirSync(import.meta.dir, { withFileTypes: true })
9 .filter(d => d.isDirectory() && readdirSync(`${import.meta.dir}/${d.name}`).includes('index.html')).map(d => d.name).sort();
outdated

This depends on the working directory. Resolve from import.meta.dir, as playtest.mjs does with import.meta.url.

10
11 const rand = seed => () => { seed = (seed * 1664525 + 1013904223) >>> 0; return seed / 4294967296; };
12 const KEYS = [' ', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Enter'];
13
14 // one gesture picked at random: a tap, a hold, a drag across the canvas or a key press
15 function gesture(g, r) {
16 const x = () => 20 + r() * 320, y = () => 20 + r() * 240, k = r();
17 if (k < .3) g.tap(x(), y());
18 else if (k < .55) g.hold(x(), y(), .1 + r() * 1.4);
19 else if (k < .8) g.drag([x(), y()], [x(), y()], .2 + r() * .8);
20 else g.press(KEYS[Math.floor(r() * KEYS.length)], .05 + r() * .6);
21 }
22
23 // bring the untouched twin to the same frame as the played copy
24 function sync(idle, played) { idle.step(played.frames - idle.frames); expect(idle.frames).toBe(played.frames); }

This assertion plus the same-seed twin is what makes the play tests fail when input is disconnected. I verified that across all 22 games.

25
26 test('the games folder is not empty', () => { expect(GAMES.length).toBeGreaterThanOrEqual(19); });
27
28 for (const id of GAMES) {
29 test(`${id}: boots, paints a picture and says what to do`, () => {
30 const g = boot(id);
31 g.run(2);
32 expect(g.errors.map(e => e.message)).toEqual([]);
33 expect(g.colours()).toBeGreaterThan(40);
34 expect(g.text().length).toBeGreaterThan(10);
35 });
36
37 test(`${id}: untouched, it idles for four seconds without failing`, () => {
38 const g = boot(id);
39 g.run(4);
40 expect(g.errors.map(e => e.message)).toEqual([]);
41 expect(g.colours()).toBeGreaterThan(40);
42 });
43
44 test(`${id}: pointer play throws nothing, and the picture and the HUD text differ from an untouched twin`, () => {
outdated

Idle animation alone gives 26–41 distinct pictures on every game when canvas.fire is a no-op. Compare against an idle twin run for the same frames, so this fails when input is ignored.

45 // same seed, same frame count: only the player's input tells the two apart
outdated

This cannot fail: words starts with one entry.

46 const idle = boot(id, { seed: 7 }), g = boot(id, { seed: 7 }), r = rand(11);
47 let picture = false, words = false;
48 for (let t = 0; t < 40 && !(picture && words); t++) {
49 gesture(g, r);
50 sync(idle, g);
51 picture ||= g.picture() !== idle.picture();
52 words ||= g.text() !== idle.text();
53 }
54 expect(g.errors.map(e => e.stack?.split('\n')[0] + ' ' + e.message)).toEqual([]);
55 expect(picture).toBe(true);
56 expect(words).toBe(true);
57 expect(g.colours()).toBeGreaterThan(40);
58 });
59
60 test(`${id}: the keyboard alone changes the game compared with leaving it be`, () => {
61 const idle = boot(id, { seed: 3 }), played = boot(id, { seed: 3 }), r = rand(5);
62 let parted = false;
63 for (let i = 0; i < 20 && !parted; i++) {
64 played.press(KEYS[Math.floor(r() * KEYS.length)], .1 + r() * .5);
outdated

The frame count differs from the played copy's round(hold*25)+1+8, so the comparison below is true on time drift alone. With keys disabled it still passes on Orchard, Pottery Wheel and Kite Hill at step 1. Advance both copies by the same integer frame count.

65 played.run(.3);
66 sync(idle, played);
67 parted = played.picture() !== idle.picture() || played.text() !== idle.text();
68 }
69 expect(played.errors.map(e => e.message)).toEqual([]);
70 expect(parted).toBe(true);
71 });
72 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs