@datamoc/mw_games 0.36.1 → 0.38.0

package/tools/compile-resources.mjs

@@ -1,5 +1,7 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { readdir, readFile, mkdir, writeFile, rm } from 'node:fs/promises';
-import { join, extname, relative, sep, dirname, basename } from 'node:path';
+import { join, extname, relative, sep, dirname } from 'node:path';
 import { WEBP_CONVERTIBLE_EXTENSIONS } from './webp-convert.mjs';
 
 /**
@@ -68,6 +70,11 @@ export async function* walk(dir) {
  *   lossy re-encoding for photographic source art)
  * @param options.webpQuality 0-100, used only when `webpLossless` is false (default 90)
  * @returns the group names, in the order the page should load them
+ *
+ * An `assets/credits.json` (an array, or `{ "credits": [...] }`, of `{ name, license, author?, url? }`)
+ * is not embedded as an asset: it is turned into `CREDITS.txt` beside the compiled scripts, for
+ * the attribution that free art packs require. An entry without a `name` and a `license` is an
+ * error, since a credits file that silently omits a pack defeats its purpose.
  */
 export async function compileResources({
 	from,
@@ -96,7 +103,14 @@ export async function compileResources({
 	// (or requires installing) sharp
 	const toWebp = convertToWebp ? (await import('./webp-convert.mjs')).toWebp : null;
 
+	const creditsFile = join(from, 'credits.json');
+	let credits = null;
+
 	for await (const file of walk(from)) {
+		if (file === creditsFile) {
+			credits = creditsText(JSON.parse(await readFile(file, 'utf8')));
+			continue;
+		}
 		const ext = extname(file).toLowerCase();
 		const type = types[ext];
 		if (!type) {
@@ -136,14 +150,33 @@ export async function compileResources({
 		written.push({ name, count: Object.keys(assets).length, size: js.length });
 	}
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped };
+	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
+
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits };
+}
+
+/** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
+export function creditsText(manifest) {
+	const entries = Array.isArray(manifest) ? manifest : manifest?.credits;
+	if (!Array.isArray(entries)) throw new Error('credits.json must be an array or { "credits": [...] }');
+	const blocks = entries.map((entry, index) => {
+		if (typeof entry?.name !== 'string' || typeof entry?.license !== 'string') {
+			throw new Error(`credits.json entry ${index} needs a "name" and a "license"`);
+		}
+		const lines = [entry.name + (entry.author ? ` by ${entry.author}` : ''), `License: ${entry.license}`];
+		if (entry.url) lines.push(entry.url);
+		return lines.join('\n');
+	});
+	return blocks.join('\n\n') + '\n';
 }
 
 // ---------------------------------------------------------------- CLI
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const args = process.argv.slice(2);
 	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
@@ -180,4 +213,12 @@ if (isMain) {
 	}
 }
 
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}
+
 export { dirname };

package/tools/compress-dist.mjs

@@ -1,5 +1,7 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { readFile, writeFile } from 'node:fs/promises';
-import { relative, extname, basename } from 'node:path';
+import { relative, extname } from 'node:path';
 import { gzip, brotliCompress, constants } from 'node:zlib';
 import { promisify } from 'node:util';
 import { availableParallelism } from 'node:os';
@@ -153,9 +155,11 @@ async function compressOne(dir, file, { gzip, brotli, wantXz }) {
 	return row;
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const [dir, ...flags] = process.argv.slice(2);
 	if (!dir) {
 		console.error('usage: node tools/compress-dist.mjs <dist folder> [--xz] [--no-gzip] [--no-brotli]');
@@ -179,3 +183,11 @@ if (isMain) {
 	}
 	console.log(`  ${rows.length} file(s) considered in ${relative(process.cwd(), dir)}`);
 }
+
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}

package/tools/emit-page.mjs

@@ -184,5 +184,9 @@ async function main(argv) {
 }
 
 //realpath, since an npm `bin` shim reaches this file through a symlink
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
-	await main(process.argv.slice(2));
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});

package/tools/init.d.mts

@@ -0,0 +1,5 @@
+/** the starter project's files as `{ path: content }`, for a package called `name` */
+export function initFiles(name: string): Record<string, string>;
+
+/** writes the starter project into an empty or missing `folder`; throws if it already holds files */
+export function initProject(folder: string): { folder: string; files: string[] };

package/tools/init.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `mwg-init <folder>`: the smallest game that builds into one double-clickable page.
+ *
+ * It writes a vite project that uses `mwgPage()`: one scene, a moving square, a vite config
+ * that loads without `"type": "module"` in the way `.mts` files do, and the scripts to run
+ * and build it. The point is that the nearest example to copy is already on disk, in the
+ * shape the published package supports, rather than a folder of this repository's own
+ * examples that import their sources by relative path.
+ */
+const PACKAGE_VERSION = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+).version;
+
+/** the project's files as `{ path: content }`, named after `name` */
+export function initFiles(name) {
+	return {
+		'package.json':
+			JSON.stringify(
+				{
+					name,
+					private: true,
+					version: '0.0.0',
+					type: 'module',
+					scripts: { dev: 'vite', build: 'vite build', check: 'tsc --noEmit' },
+					dependencies: { '@datamoc/mw_games': `^${PACKAGE_VERSION}`, 'pixi.js': '^8.20.1' },
+					devDependencies: { typescript: '^7.0.2', vite: '^8.2.2' },
+				},
+				null,
+				2,
+			) + '\n',
+		'vite.config.mts': [
+			"import { defineConfig } from 'vite';",
+			"import { mwgPage } from '@datamoc/mw_games/tools/vite';",
+			'',
+			'//`singleFile: true` also writes dist/standalone.html, the whole game in one file',
+			'export default defineConfig({ plugins: [mwgPage({ singleFile: true })] });',
+			'',
+		].join('\n'),
+		'tsconfig.json':
+			JSON.stringify(
+				{
+					compilerOptions: {
+						target: 'ES2022',
+						module: 'ESNext',
+						moduleResolution: 'bundler',
+						lib: ['ES2022', 'DOM'],
+						strict: true,
+						noEmit: true,
+						skipLibCheck: true,
+					},
+					include: ['src'],
+				},
+				null,
+				2,
+			) + '\n',
+		'index.html': [
+			'<!DOCTYPE html>',
+			'<html lang="en">',
+			'<head>',
+			'\t<meta charset="utf-8">',
+			'\t<meta name="viewport" content="width=device-width, initial-scale=1">',
+			`\t<title>${name}</title>`,
+			'\t<style>html, body { margin: 0; height: 100%; background: #101018; overflow: hidden; } #game { display: block; width: 100vw; height: 100vh; }</style>',
+			'</head>',
+			'<body>',
+			'\t<canvas id="game"></canvas>',
+			'\t<script type="module" src="./src/main.ts"></script>',
+			'</body>',
+			'</html>',
+			'',
+		].join('\n'),
+		'src/main.ts': [
+			"import { Game, Scene2D } from '@datamoc/mw_games/two-d';",
+			"import { Shape2D, Text2D } from '@datamoc/mw_games/two-d/render';",
+			'',
+			'class MainScene extends Scene2D {',
+			'\tprivate square!: Shape2D;',
+			'\tprivate elapsed = 0;',
+			'',
+			'\toverride create(): void {',
+			"\t\tconst label = new Text2D({ text: 'Hello, mwg!', style: { fill: 0xd8dae6, fontFamily: 'monospace', fontSize: 16 } });",
+			'\t\tlabel.position.set(24, 24);',
+			'\t\tthis.stage.addChild(label);',
+			'\t\tthis.square = new Shape2D().rect(-20, -20, 40, 40).fill(0x6fb1ff);',
+			'\t\tthis.stage.addChild(this.square);',
+			'\t}',
+			'',
+			'\toverride update(dt: number): void {',
+			'\t\tthis.elapsed += dt;',
+			'\t\tthis.square.position.set(Game.current.width / 2 + Math.sin(this.elapsed) * 120, Game.current.height / 2);',
+			'\t}',
+			'}',
+			'',
+			"const game = new Game({ canvas: document.getElementById('game') as HTMLCanvasElement, background: 0x101018 });",
+			'game.start(MainScene).catch((error) => console.error(error));',
+			'',
+		].join('\n'),
+		'assets/.gitkeep': '',
+		'README.md': `# ${name}\n\n\`npm install\`, then \`npm run dev\` to play it while you edit, \`npm run build\` to write \`dist/\`.\nOpen \`dist/index.html\` (or \`dist/standalone.html\`) by double-clicking it: no server needed.\n\nPut images and sounds under \`assets/\`; the build compiles them into the page. An \`assets/credits.json\`\n(\`[{ "name": "...", "license": "...", "author": "...", "url": "..." }]\`) becomes \`dist/CREDITS.txt\`.\n`,
+	};
+}
+
+/** writes the project into `folder`; refuses a folder that already holds files, so nothing is overwritten */
+export function initProject(folder) {
+	const target = resolve(folder);
+	if (existsSync(target) && readdirSync(target).length > 0) {
+		throw new Error(`${target} is not empty; run mwg-init in a new or empty folder`);
+	}
+	const written = [];
+	for (const [path, content] of Object.entries(
+		initFiles(
+			basename(target)
+				.toLowerCase()
+				.replace(/[^a-z0-9-]/g, '-'),
+		),
+	)) {
+		const file = join(target, path);
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, content, 'utf8');
+		written.push(path);
+	}
+	return { folder: target, files: written };
+}
+
+//no top-level await: this module is also imported, and the real path covers an npm bin symlink
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const folder = process.argv[2];
+	if (!folder) {
+		console.error('usage: mwg-init <new folder>');
+		process.exitCode = 2;
+	} else {
+		try {
+			const { folder: target, files } = initProject(folder);
+			console.log(`wrote ${files.length} files to ${target}\nnext: cd ${folder} && npm install && npm run dev`);
+		} catch (error) {
+			console.error(error.message);
+			process.exitCode = 1;
+		}
+	}
+}

package/tools/play-uci.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { readFileSync, readdirSync } from 'node:fs';
-import { join, basename, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join, extname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { applyMove, cloneChess, legalMoves, parseFen, squareName, startingChess } from '../src/board/chess.ts';
 import { parseUciMove, probeBook } from '../src/board/openings.ts';
@@ -164,7 +165,9 @@ export function createUciSession(options = {}) {
 	};
 }
 
-const isMain = process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]));
+//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
+//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
 if (isMain) {
 	const args = process.argv.slice(2);

package/tools/sbom.mjs

@@ -328,5 +328,9 @@ async function main(argv) {
 }
 
 //realpath, since an npm `bin` shim reaches this file through a symlink
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
-	await main(process.argv.slice(2));
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});

package/tools/single-file.mjs

@@ -200,7 +200,7 @@ function renderBootstrap(payloads, algorithm) {
 
 const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const args = process.argv.slice(2);
 	const dist = args[0];
 	if (!dist || dist.startsWith('--')) {
@@ -229,3 +229,11 @@ if (isMain) {
 	);
 	console.log('  one file, no server, no sibling script - open it directly');
 }
+
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}

package/tools/verify-scenarios.d.mts

@@ -0,0 +1,15 @@
+export interface ScenarioPlanEntry {
+	id: string;
+	enter: string;
+	/** Steps that play all sides and advance dialogue for one game-owned turn. */
+	turn: string[];
+	/** A step that throws when game-owned map, units, outcome or campaign checks fail. */
+	verify: string;
+	leave?: string;
+}
+export function validateScenarioPlan(plan: unknown): ScenarioPlanEntry[];
+export function verifyScenarios(options: { file: string; turns?: number; timeoutMs?: number; only?: string }): Promise<{
+	ok: boolean;
+	scenarios: { id: string; turns: number; ok: boolean }[];
+	failures: string[];
+}>;

package/tools/verify-scenarios.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { launchChrome } from './find-chrome.mjs';
+
+/** Validate the serialisable, game-owned plan before running any scene steps. */
+export function validateScenarioPlan(plan) {
+	if (!Array.isArray(plan) || plan.length === 0) throw new Error('scenario plan must be a nonempty array');
+	const ids = new Set();
+	for (const scenario of plan) {
+		if (!scenario || typeof scenario.id !== 'string' || !scenario.id || ids.has(scenario.id))
+			throw new Error('scenario IDs must be nonempty and unique');
+		ids.add(scenario.id);
+		for (const field of ['enter', 'verify'])
+			if (typeof scenario[field] !== 'string' || !scenario[field])
+				throw new Error(`${scenario.id}: ${field} needs a scene control name`);
+		if (
+			!Array.isArray(scenario.turn) ||
+			scenario.turn.length === 0 ||
+			scenario.turn.some((step) => typeof step !== 'string' || !step)
+		)
+			throw new Error(`${scenario.id}: turn needs a nonempty list of scene control names`);
+		if (scenario.leave !== undefined && (typeof scenario.leave !== 'string' || !scenario.leave))
+			throw new Error(`${scenario.id}: leave needs a scene control name`);
+	}
+	return plan;
+}
+
+/** Opens one local page and drives every scenario through its registered SceneControls. */
+export async function verifyScenarios({ file, turns = 3, timeoutMs = 120000, only = '' }) {
+	if (!Number.isSafeInteger(turns) || turns < 1) throw new Error('turns must be a positive integer');
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('timeoutMs must be a positive integer');
+	const browser = await launchChrome({ argsEnv: 'MWG_VISUAL_CHROME_ARGS' });
+	const failures = [];
+	const scenarios = [];
+	let expired = false;
+	const bounded = async (operation) => {
+		let timer;
+		try {
+			return await Promise.race([
+				operation,
+				new Promise((_, reject) => {
+					timer = setTimeout(() => {
+						expired = true;
+						reject(new Error(`scene step exceeded ${timeoutMs} ms`));
+					}, timeoutMs);
+				}),
+			]);
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	try {
+		const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+		let current = 'startup';
+		page.on('pageerror', (error) => failures.push(`${current}: ${error.message}`));
+		page.on('console', (message) => {
+			if (message.type() === 'error') failures.push(`${current}: ${message.text()}`);
+		});
+		await page.goto(pathToFileURL(resolve(file)).href, { waitUntil: 'load', timeout: timeoutMs });
+		await page.waitForFunction(() => Boolean(window.__MWG_SCENARIOS__), undefined, { timeout: timeoutMs });
+		const plan = validateScenarioPlan(await page.evaluate(() => window.__MWG_SCENARIOS__.scenarios));
+		const selected = plan.filter((scenario) => scenario.id.startsWith(only));
+		if (!selected.length) throw new Error(`no scenarios match ${JSON.stringify(only)}`);
+		// Refuse a missing step before entering the first scenario.
+		await page.evaluate((plan) => {
+			const controls = window.__MWG_SCENARIOS__.controls;
+			for (const scenario of plan)
+				for (const step of [scenario.enter, ...scenario.turn, scenario.verify, scenario.leave].filter(Boolean))
+					if (!controls.has(step)) throw new Error(`scene control step is not registered: ${step}`);
+		}, selected);
+		for (const scenario of selected) {
+			current = scenario.id;
+			const before = failures.length;
+			let played = 0;
+			const run = (step) => bounded(page.evaluate((name) => window.__MWG_SCENARIOS__.controls.run(name), step));
+			try {
+				await run(scenario.enter);
+				for (; played < turns; played++) {
+					for (const step of scenario.turn) await run(step);
+					await run(scenario.verify);
+				}
+			} catch (error) {
+				failures.push(`${current}: ${error.message}`);
+			} finally {
+				if (scenario.leave && !expired) {
+					try {
+						await run(scenario.leave);
+					} catch (error) {
+						failures.push(`${current}: cleanup: ${error.message}`);
+					}
+				}
+			}
+			scenarios.push({ id: scenario.id, turns: played, ok: failures.length === before });
+			// A timed-out promise is still live in the page. Do not overlap another scenario with it.
+			if (expired) break;
+		}
+		return { ok: failures.length === 0, scenarios, failures };
+	} finally {
+		await browser.close();
+	}
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const [file, ...args] = process.argv.slice(2);
+	const options = { file };
+	try {
+		if (!file)
+			throw new Error('usage: mwg-scenarios <built index.html> [--turns N] [--timeout-ms N] [--only prefix]');
+		for (let i = 0; i < args.length; i += 2) {
+			const name = { '--turns': 'turns', '--timeout-ms': 'timeoutMs', '--only': 'only' }[args[i]];
+			if (!name || args[i + 1] === undefined) throw new Error(`invalid option: ${args[i]}`);
+			options[name] = name === 'only' ? args[i + 1] : Number(args[i + 1]);
+		}
+		verifyScenarios(options)
+			.then((report) => {
+				console.log(JSON.stringify(report, null, 2));
+				process.exitCode = report.ok ? 0 : 1;
+			})
+			.catch((error) => {
+				console.error(error.message);
+				process.exitCode = 1;
+			});
+	} catch (error) {
+		console.error(error.message);
+		process.exitCode = 1;
+	}
+}

package/tools/vite.mjs

@@ -50,6 +50,11 @@ export function mwgPage(options = {}) {
 					reportCompressedSize: false,
 					rollupOptions: {
 						output: { format: 'iife', entryFileNames: 'game.js', assetFileNames: '[name][extname]' },
+						//an iife has no import.meta, and the bundler already swaps it for {} (vite's own
+						//preload helper reads it); the warning on every build is noise, not information
+						onLog(level, log, defaultHandler) {
+							if (log.code !== 'EMPTY_IMPORT_META') defaultHandler(level, log);
+						},
 					},
 				},
 			};

package/tools/webp-convert.mjs

@@ -58,7 +58,7 @@ export const WEBP_CONVERTIBLE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
 
 const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (isMain) {
+async function runCli() {
 	const args = process.argv.slice(2);
 	const input = args.find((a) => !a.startsWith('--'));
 	if (!input) {
@@ -88,3 +88,11 @@ if (isMain) {
 			(lossless ? ' [lossless]' : ` [lossy, quality ${quality}]`),
 	);
 }
+
+//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
+if (isMain) {
+	runCli().catch((error) => {
+		console.error(error);
+		process.exitCode = 1;
+	});
+}