@datamoc/mw_games 0.40.0 → 0.42.0

package/tools/benchmark-browser.mjs

@@ -136,6 +136,12 @@ export async function measurePage({
  * `benchmark-results/<page>.json`, named by the page so two pages keep separate histories.
  */
 async function main(argv) {
+	if (argv.includes('--help') || argv.includes('-h')) {
+		console.log(
+			'usage: mwg-bench <page.html | dist folder> [--frames=180] [--min-fps=45] [--max-p95=40] [--history=<file>]',
+		);
+		return;
+	}
 	const value = (name, env, fallback) =>
 		argv.find((a) => a.startsWith(`--${name}=`))?.split('=')[1] ?? process.env[env] ?? fallback;
 	const target = argv.find((arg) => !arg.startsWith('--')) ?? 'examples/dungeon/dist/index.html';

package/tools/bundle-size.mjs

@@ -99,6 +99,10 @@ function measureFramework(root) {
 }
 
 function main(argv) {
+	if (argv.includes('--help') || argv.includes('-h')) {
+		console.log('usage: mwg-size <dist folder> [--baseline=<file>] [--tolerance=0.02] [--update]');
+		return;
+	}
 	const tolerance = Number(
 		argv.find((a) => a.startsWith('--tolerance='))?.slice(12) ?? process.env.MWG_SIZE_TOLERANCE ?? 0.02,
 	);

package/tools/compile-resources.d.mts

@@ -12,6 +12,8 @@ export interface CompileResourcesOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** minify embedded `.svg` assets through the optional `svgo` package (version 4 or newer); false by default */
+	svgo?: boolean;
 	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
 	soundFont?: boolean;
 	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
@@ -29,6 +31,8 @@ export interface CompileResourcesResult {
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	/** SVG assets embedded smaller than their source because of `svgo` */
+	svgOptimised: number;
 	skipped: number;
 	/** the `CREDITS.txt` text when the asset folder holds a `credits.json`, else null */
 	credits: string | null;
@@ -50,6 +54,8 @@ export interface SoundFontEmbed {
 	programs: number | null;
 	rawBytes: number;
 	embeddedBytes: number;
+	/** the programs the game's MIDI files ask for that this font does not carry; empty when none */
+	missing: SoundFontUsage[];
 }
 
 /** parses a `--soundfont-usage=bank:program,...` CLI value; undefined when the flag is absent */

package/tools/compile-resources.mjs

@@ -41,9 +41,10 @@ export const DEFAULT_MIME = {
 	'.mid': 'audio/midi',
 	'.midi': 'audio/midi',
 	'.sf2': 'application/octet-stream',
+	'.sf3': 'application/octet-stream',
 };
 
-const isSoundFontKey = (key) => key.toLowerCase().endsWith('.sf2');
+const isSoundFontKey = (key) => /\.sf[23]$/i.test(key);
 const isMidiKey = (key) => /\.(mid|midi)$/i.test(key);
 
 /**
@@ -120,7 +121,11 @@ export async function* walk(dir) {
  *   pixel-art tileset's exact colours survive; set false only with `webpQuality` to opt into
  *   lossy re-encoding for photographic source art)
  * @param options.webpQuality 0-100, used only when `webpLossless` is false (default 90)
- * @param options.soundFont subset an embedded `.sf2` to the programs the embedded
+ * @param options.svgo minify embedded `.svg` assets through the optional `svgo` package (default
+ *   false - see `tools/svg-optimise.mjs`). The key never changes, only the embedded bytes, and
+ *   only when the optimised file is actually smaller. A file svgo cannot parse fails the build by
+ *   name rather than shipping unoptimised in silence.
+ * @param options.soundFont subset an embedded `.sf2` or `.sf3` to the programs the embedded
  *   `.mid`/`.midi` files use (default true); `false` embeds every SoundFont whole
  * @param options.soundFontUsage explicit `{ bank, program }` list to subset to, for a
  *   game that voices notes no shipped MIDI file requests; overrides the MIDI-derived list
@@ -140,6 +145,7 @@ export async function compileResources({
 	toWebp: convertToWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo: optimiseSvgFiles = false,
 	soundFont = true,
 	soundFontUsage,
 } = {}) {
@@ -204,10 +210,12 @@ export async function compileResources({
 	let rawBytes = 0;
 	let embeddedBytes = 0;
 	let webpConverted = 0;
+	let svgOptimised = 0;
 
 	// only paid when toWebp is actually used, so a build that never asks for it never imports
 	// (or requires installing) sharp
 	const toWebp = convertToWebp ? (await import('./webp-convert.mjs')).toWebp : null;
+	const optimiseSvg = optimiseSvgFiles ? (await import('./svg-optimise.mjs')).optimiseSvg : null;
 
 	const creditsFile = join(from, 'credits.json');
 	let credits = null;
@@ -239,6 +247,19 @@ export async function compileResources({
 			}
 		}
 
+		if (optimiseSvg && ext === '.svg') {
+			let optimised;
+			try {
+				optimised = await optimiseSvg(data);
+			} catch (error) {
+				throw new Error(`cannot optimise SVG asset ${key}: ${error.message ?? error}`);
+			}
+			if (optimised.length < data.length) {
+				bytes = optimised;
+				svgOptimised++;
+			}
+		}
+
 		if (isSoundFontKey(key)) {
 			if (usage !== undefined && soundFontTools) {
 				try {
@@ -246,7 +267,14 @@ export async function compileResources({
 				} catch (error) {
 					throw new Error(`cannot subset SoundFont asset ${key}: ${error.message ?? error}`);
 				}
-				soundFonts.push({ key, programs: usage.length, rawBytes: data.length, embeddedBytes: bytes.length });
+				soundFonts.push({
+					key,
+					programs: usage.length,
+					rawBytes: data.length,
+					embeddedBytes: bytes.length,
+					//the programs the MIDI files ask for that this font does not carry
+					missing: soundFontTools.missingSoundFontPrograms(data, usage),
+				});
 			} else {
 				soundFonts.push({ key, programs: null, rawBytes: data.length, embeddedBytes: data.length });
 			}
@@ -272,7 +300,7 @@ export async function compileResources({
 
 	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits, soundFonts };
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, svgOptimised, skipped, credits, soundFonts };
 }
 
 /** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
@@ -301,7 +329,7 @@ async function runCli() {
 	const [from, to] = args.filter((a) => !a.startsWith('--'));
 	if (!from || !to) {
 		console.error(
-			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
+			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--svgo] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
 		);
 		process.exit(1);
 	}
@@ -314,17 +342,19 @@ async function runCli() {
 		args.find((a) => a.startsWith('--soundfont-usage='))?.slice('--soundfont-usage='.length),
 	);
 
-	const { groups, rawBytes, embeddedBytes, webpConverted, skipped, soundFonts } = await compileResources({
-		from,
-		to,
-		//a flat folder has no subdirectories to group by, so everything lands in one file
-		groupBy: (key) => (key.includes('/') ? key.slice(0, key.indexOf('/')) : 'assets'),
-		toWebp,
-		webpLossless,
-		webpQuality,
-		soundFont: !args.includes('--no-soundfont-subset'),
-		soundFontUsage,
-	});
+	const { groups, rawBytes, embeddedBytes, webpConverted, svgOptimised, skipped, soundFonts } =
+		await compileResources({
+			from,
+			to,
+			//a flat folder has no subdirectories to group by, so everything lands in one file
+			groupBy: (key) => (key.includes('/') ? key.slice(0, key.indexOf('/')) : 'assets'),
+			toWebp,
+			webpLossless,
+			webpQuality,
+			svgo: args.includes('--svgo'),
+			soundFont: !args.includes('--no-soundfont-subset'),
+			soundFontUsage,
+		});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
 	for (const { name, count, size } of groups) {
@@ -337,7 +367,14 @@ async function runCli() {
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
+	if (args.includes('--svgo')) console.log(`  ${svgOptimised} SVG(s) optimised`);
 	if (toWebp) {
 		console.log(
 			`  ${webpConverted} image(s) converted to WebP (${webpLossless ? 'lossless' : `lossy, quality ${webpQuality}`}), ` +

package/tools/emit-page.d.mts

@@ -20,6 +20,8 @@ export interface EmitPageOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** minify embedded `.svg` assets through the optional `svgo` package; false by default */
+	svgo?: boolean;
 	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
 	soundFont?: boolean;
 	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
@@ -42,6 +44,7 @@ export interface EmitPageResult {
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	svgOptimised: number;
 	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
 	soundFonts: SoundFontEmbed[];
 	compressed: CompressRow[] | null;

package/tools/emit-page.mjs

@@ -29,7 +29,7 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * usage: mwg-emit <project folder> [--dist=<dir>] [--assets=<dir>] [--no-csp] [--connect=<origin>]...
  *                 [--no-compress] [--xz]
  *                 [--single-file] [--single-file-compress[=level]]
- *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]]
+ *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]] [--svgo]
  *                 [--no-soundfont-subset] [--soundfont-usage=bank:program,...]
  *
  * `--dist` defaults to `<project folder>/dist` and `--assets` to `<project folder>/assets`; with
@@ -53,6 +53,9 @@ import { withContentSecurityPolicy } from './csp.mjs';
  * `--to-webp` converts `.png`/`.jpg`/`.jpeg` example assets to WebP before embedding (see
  * `tools/webp-convert.mjs`), lossless by default; `--webp-lossy[=quality]` opts into lossy
  * re-encoding instead. Needs the optional `sharp` devDependency installed.
+ *
+ * `--svgo` minifies embedded `.svg` assets (see `tools/svg-optimise.mjs`), keeping the `viewBox` and
+ * every id. Needs the optional `svgo` package installed.
  */
 
 /**
@@ -74,6 +77,7 @@ export async function emitPage({
 	toWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	svgo = false,
 	soundFont = true,
 	soundFontUsage,
 	csp = true,
@@ -89,10 +93,11 @@ export async function emitPage({
 				toWebp,
 				webpLossless,
 				webpQuality,
+				svgo,
 				soundFont,
 				soundFontUsage,
 			})
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, soundFonts: [] };
+		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, svgOptimised: 0, soundFonts: [] };
 
 	const html = await readFile(join(dist, 'index.html'), 'utf8');
 	const classic = toClassicScript(html);
@@ -162,6 +167,7 @@ async function main(argv) {
 		toWebp: argv.includes('--to-webp'),
 		webpLossless: !webpLossyFlag,
 		webpQuality: webpLossyFlag?.includes('=') ? Number(webpLossyFlag.split('=')[1]) : 90,
+		svgo: argv.includes('--svgo'),
 		soundFont: !argv.includes('--no-soundfont-subset'),
 		soundFontUsage,
 		csp: argv.includes('--no-csp')
@@ -179,12 +185,19 @@ async function main(argv) {
 				`${kb(result.rawBytes)} -> ${kb(result.embeddedBytes)} embedded`,
 		);
 	}
+	if (argv.includes('--svgo')) console.log(`  ${result.svgOptimised} SVG(s) optimised`);
 	for (const font of result.soundFonts ?? []) {
 		console.log(
 			font.programs === null
 				? `  ${font.key}: SoundFont embedded whole (${kb(font.rawBytes)}), no shipped MIDI to subset against`
 				: `  ${font.key}: SoundFont subset to ${font.programs} program(s), ${kb(font.rawBytes)} -> ${kb(font.embeddedBytes)}`,
 		);
+		if (font.missing?.length > 0) {
+			console.log(
+				`  warning: ${font.key} does not carry ${font.missing.map(({ bank, program }) => `${bank}:${program}`).join(', ')}: ` +
+					"they play the font's piano, or the built-in synthesizer with `missingProgram: 'synth'`",
+			);
+		}
 	}
 	console.log('  open index.html directly - no server needed');
 	if (result.compressed) {

package/tools/init.mjs

@@ -130,7 +130,9 @@ export function initProject(folder) {
 //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) {
+	if (folder === '--help' || folder === '-h') {
+		console.log('usage: mwg-init <new folder>');
+	} else if (!folder) {
 		console.error('usage: mwg-init <new folder>');
 		process.exitCode = 2;
 	} else {

package/tools/make-example-assets.mjs

@@ -717,6 +717,10 @@ if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.me
 	const args = process.argv.slice(2);
 	const folder = args.find((arg) => !arg.startsWith('--'));
 	const inRepository = existsSync(join(here, '..', 'examples'));
+	if (args.includes('--help') || args.includes('-h')) {
+		console.log('usage: mwg-placeholder-assets <folder> [--force]');
+		process.exit(0);
+	}
 	if (!folder && !inRepository) {
 		console.error('usage: mwg-placeholder-assets <folder> [--force]');
 		process.exit(1);

package/tools/multiplayer-server.mjs

@@ -187,6 +187,10 @@ export function createLockstepServer(options = {}) {
 //realpath, since an npm `bin` shim reaches this file through a symlink
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
 	const args = process.argv.slice(2);
+	if (args.includes('--help') || args.includes('-h')) {
+		console.log('usage: mwg-lockstep-server [port] [--host=<address>]');
+		process.exit(0);
+	}
 	const port = Number(args.find((arg) => !arg.startsWith('--')) ?? 8787);
 	const host = args.find((arg) => arg.startsWith('--host='))?.slice(7) ?? '127.0.0.1';
 	const server = createLockstepServer({ port, host });

package/tools/mwl.mjs

@@ -65,6 +65,13 @@ const assetRoot = assetRootFlag === -1 ? undefined : args[assetRootFlag + 1];
 const targetFlag = args.indexOf('--to');
 const target = targetFlag === -1 ? undefined : args[targetFlag + 1];
 
+if (args.includes('--help') || args.includes('-h')) {
+	console.log(
+		'usage: mwg-mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build> input.mwl [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory]',
+	);
+	process.exit(0);
+}
+
 if (!command || !input || !commands.includes(command)) {
 	console.error(
 		'Usage: mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build> input.mwl [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory]',

package/tools/play-uci.mjs

@@ -171,6 +171,10 @@ const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPat
 
 if (isMain) {
 	const args = process.argv.slice(2);
+	if (args.includes('--help') || args.includes('-h')) {
+		console.log('usage: mwg-uci [--book <book.json>] [--tables <dir>] [--depth N]');
+		process.exit(0);
+	}
 	const flag = (name) => {
 		const at = args.indexOf(name);
 		return at === -1 ? undefined : args[at + 1];

package/tools/sbom.mjs

@@ -301,6 +301,10 @@ async function readJson(path) {
  * `application`, anything else as a `library`. `--check` compares instead of writing, for CI.
  */
 async function main(argv) {
+	if (argv.includes('--help') || argv.includes('-h')) {
+		console.log('usage: mwg-sbom [project folder] [--out=<file>] [--check]');
+		return;
+	}
 	const root = resolve(argv.find((arg) => !arg.startsWith('--')) ?? '.');
 	const out = resolve(root, argv.find((arg) => arg.startsWith('--out='))?.slice(6) ?? OUTPUT);
 	const packageJson = await readJson(join(root, 'package.json'));

package/tools/soundfonts.d.mts

@@ -0,0 +1,79 @@
+/** how freely a catalogue font may be shipped inside a game */
+export type SoundFontLicenceClass =
+	'public-domain' | 'permissive' | 'attribution' | 'share-alike' | 'copyleft' | 'check';
+
+export interface SoundFontCatalogEntry {
+	name: string;
+	licence: string;
+	licenceClass: SoundFontLicenceClass;
+	web?: string;
+	/** instrument files the collection carries for this font (programs for a bundled bank) */
+	programs: number;
+	/** megabytes of a full General MIDI bank, SoundFont 3 compressed; absent for the bundled bank */
+	gmMB?: number;
+	/** megabytes of every instrument file, SoundFont 3 compressed (the bundled bank's own size) */
+	fullMB: number;
+	/** the file of a bundled bank, relative to the package root */
+	file?: string;
+	note?: string;
+}
+
+export interface SoundFontCatalog {
+	description: string;
+	/** where the per-instrument files are fetched from by default */
+	source: string;
+	/** the name of the bank the package ships and games use unless they choose another */
+	default: string;
+	bundled: SoundFontCatalogEntry[];
+	fonts: SoundFontCatalogEntry[];
+}
+
+export interface SoundFontProgramRef {
+	bank: number;
+	program: number;
+}
+
+export interface FetchSoundFontOptions {
+	/** a catalogue font name, from `mwg-soundfonts list` */
+	name: string;
+	programs: SoundFontProgramRef[];
+	catalog?: SoundFontCatalog;
+	/** a folder or `http(s)` URL laid out as `<font>/<bank>/<program>.sf3`; the catalogue's source by default */
+	source?: string;
+	/** required for a licence class that is not public-domain, permissive or attribution */
+	acceptLicence?: boolean;
+	/** the decoded font is a SoundFont 2 (`ffmpeg` needed) instead of a SoundFont 3; `sf3` by default */
+	format?: 'sf2' | 'sf3';
+	/** Ogg Vorbis bytes to mono 16-bit frames, for `format: 'sf2'`; `ffmpeg` by default */
+	decode?: (ogg: Uint8Array, rate: number) => Int16Array | Promise<Int16Array>;
+	/** replaces the file reader, mainly for tests */
+	read?: (path: string) => Promise<Uint8Array | null>;
+}
+
+export interface FetchedSoundFont {
+	/** one font holding the found programs, in `format` */
+	bytes: Uint8Array;
+	format: 'sf2' | 'sf3';
+	found: SoundFontProgramRef[];
+	/** requested programs the collection does not carry */
+	missing: SoundFontProgramRef[];
+	font: SoundFontCatalogEntry;
+}
+
+/** the licence-classified catalogue of fetchable fonts */
+export declare const CATALOG_PATH: string;
+export declare function readCatalog(path?: string): SoundFontCatalog;
+export declare function findFont(catalog: SoundFontCatalog, name: string): SoundFontCatalogEntry | undefined;
+/** `"0,24,128:0"`: a bare number is a program of bank 0, `bank:program` names both */
+export declare function parseProgramList(text: string): SoundFontProgramRef[];
+/** mono 16-bit frames from Ogg Vorbis bytes, through `ffmpeg` */
+export declare function ffmpegDecode(ogg: Uint8Array): Int16Array;
+/** a SoundFont 3 decoded into SoundFont 2 bytes (`ffmpeg` unless `decode` is given) */
+export declare function sf3ToSf2(
+	bytes: Uint8Array,
+	decode?: (ogg: Uint8Array, rate: number) => Int16Array | Promise<Int16Array>,
+): Promise<Uint8Array>;
+export declare function readCollectionFile(source: string, path: string): Promise<Uint8Array | null>;
+export declare function fetchSoundFont(options: FetchSoundFontOptions): Promise<FetchedSoundFont>;
+/** the credits note that travels beside a fetched font */
+export declare function creditsFor(font: SoundFontCatalogEntry, programs: SoundFontProgramRef[]): string;