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
Check · Review · Land · Live done — Landed and live in production.
quill/pixel-plays:quill/42-games-need-to-have-a-much-higher-playabi → main 2 commits fork 8 threads · 8 unresolved
README.md +6
| @@ -61,3 +61,9 @@ Create `<id>/index.html`, load `../shell.js`, call `PixelPlays.mount({ id, rules | ||
| 61 | 61 | |
| 62 | 62 | ## License |
| 63 | 63 | The code is under the [](LICENSE). The music is not: see [](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 | }, | |
| 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
|
||
| 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 |
||
| 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 |
||
| 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 |
||
| 45 | // same seed, same frame count: only the player's input tells the two apart | |
outdated
This cannot fail: |
||
| 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 |
||
| 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 | } |
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.