@datamoc/mw_games 0.38.0 → 0.40.0

package/tools/compile-resources.d.mts

@@ -7,9 +7,15 @@ export interface CompileResourcesOptions {
 	to: string;
 	mime?: Record<string, string>;
 	groupBy?: (key: string) => string;
+	/** Exact paths relative to the asset folder to embed. Omit to include all; [] includes none. Unknown entries fail by name. */
+	assetFiles?: readonly string[];
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** 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. */
+	soundFontUsage?: readonly SoundFontUsage[];
 }
 
 export interface CompileResourcesGroup {
@@ -26,9 +32,27 @@ export interface CompileResourcesResult {
 	skipped: number;
 	/** the `CREDITS.txt` text when the asset folder holds a `credits.json`, else null */
 	credits: string | null;
+	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
+	soundFonts: SoundFontEmbed[];
 }
 
 /** the plain-text credits for a manifest (an array, or `{ credits: [...] }`, of `{ name, license, author?, url? }`) */
 export function creditsText(manifest: unknown): string;
 
+export interface SoundFontUsage {
+	bank: number;
+	program: number;
+}
+
+export interface SoundFontEmbed {
+	key: string;
+	/** programs kept, or null when the font was embedded whole for lack of a usage list */
+	programs: number | null;
+	rawBytes: number;
+	embeddedBytes: number;
+}
+
+/** parses a `--soundfont-usage=bank:program,...` CLI value; undefined when the flag is absent */
+export function soundFontUsageFromFlag(value: string | undefined): SoundFontUsage[] | undefined;
+
 export function compileResources(options: CompileResourcesOptions): Promise<CompileResourcesResult>;

package/tools/compile-resources.mjs

@@ -38,8 +38,56 @@ export const DEFAULT_MIME = {
 	'.woff2': 'font/woff2',
 	'.json': 'application/json',
 	'.txt': 'text/plain',
+	'.mid': 'audio/midi',
+	'.midi': 'audio/midi',
+	'.sf2': 'application/octet-stream',
 };
 
+const isSoundFontKey = (key) => key.toLowerCase().endsWith('.sf2');
+const isMidiKey = (key) => /\.(mid|midi)$/i.test(key);
+
+/**
+ * The SoundFont/MIDI implementation lives in the library, not in this tool: in this
+ * repository it is the TypeScript source, in an installed package it is the built
+ * `dist/` the source compiles to. Only called when a build actually embeds a
+ * SoundFont it can subset, so a game without one never pays for the import.
+ */
+async function loadSoundFontTools() {
+	try {
+		const [soundFont, midi] = await Promise.all([
+			import('../src/audio/SoundFont.ts'),
+			import('../src/audio/Midi.ts'),
+		]);
+		return { ...soundFont, ...midi };
+	} catch {
+		return import('../dist/audio/index.js');
+	}
+}
+
+function checkedSoundFontUsage(soundFontUsage) {
+	if (soundFontUsage === undefined) return undefined;
+	if (!Array.isArray(soundFontUsage)) throw new Error('soundFontUsage must be an array of { bank, program }');
+	return soundFontUsage.map((entry, index) => {
+		const { bank, program } = entry ?? {};
+		if (!Number.isInteger(bank) || bank < 0 || !Number.isInteger(program) || program < 0 || program > 127) {
+			throw new Error(`soundFontUsage[${index}] needs an integer bank >= 0 and a program between 0 and 127`);
+		}
+		return { bank, program };
+	});
+}
+
+/** parses a `--soundfont-usage=bank:program,...` CLI value; undefined when the flag is absent */
+export function soundFontUsageFromFlag(value) {
+	if (value === undefined) return undefined;
+	return value
+		.split(',')
+		.filter(Boolean)
+		.map((pair) => {
+			const [bank, program] = pair.split(':').map(Number);
+			return { bank, program };
+		});
+}
+
 export async function* walk(dir) {
 	let entries;
 	try {
@@ -58,6 +106,9 @@ export async function* walk(dir) {
  * @param options.from folder holding the assets
  * @param options.to folder to write the generated scripts into
  * @param options.mime extension to MIME type, merged over the defaults
+ * @param options.assetFiles exact paths relative to `from` to embed; omit for all, [] for none.
+ *   Unknown paths and explicitly selected unsupported formats fail before replacing output.
+ *   credits.json is converted to CREDITS.txt only when selected (or when no list is given).
  * @param options.groupBy how to name the script an asset lands in; defaults to its top folder
  * @param options.toWebp convert `.png`/`.jpg`/`.jpeg` assets to WebP before embedding
  *   (default false - see `tools/webp-convert.mjs`). The asset's *key* never changes (a game
@@ -69,6 +120,10 @@ 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
+ *   `.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
  * @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? }`)
@@ -81,15 +136,66 @@ export async function compileResources({
 	to,
 	mime = {},
 	groupBy,
+	assetFiles,
 	toWebp: convertToWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	soundFont = true,
+	soundFontUsage,
 } = {}) {
 	if (!from || !to) throw new Error('compileResources needs both `from` and `to`');
 
 	const types = { ...DEFAULT_MIME, ...mime };
 	const group = groupBy ?? ((key) => (key.includes('/') ? key.slice(0, key.indexOf('/')) : 'assets'));
 
+	const files = [];
+	for await (const file of walk(from)) files.push(file);
+	const keyOf = (file) => relative(from, file).split(sep).join('/');
+	const selected =
+		assetFiles === undefined
+			? undefined
+			: new Set(assetFiles.map((key) => key.replaceAll('\\', '/').replace(/^\.\//, '')));
+	if (selected) {
+		const known = new Set(files.map(keyOf));
+		for (const key of selected) {
+			if (!known.has(key)) throw new Error(`unknown asset file ${key}`);
+			if (key !== 'credits.json' && !types[extname(key).toLowerCase()])
+				throw new Error(`unsupported asset file ${key}`);
+		}
+	}
+
+	// A shipped SoundFont carries only the programs the game's shipped MIDI files
+	// request: the full bank - even a small one - is mostly
+	// instruments no track plays. Usage is resolved before any output is replaced,
+	// so an unreadable MIDI or SoundFont fails the build with the old output intact.
+	// With no shipped MIDI and no explicit `soundFontUsage` the usage is unknowable
+	// (a game may voice notes it generates), so the font embeds whole.
+	const isSelected = (file) => !selected || selected.has(keyOf(file));
+	const explicitUsage = checkedSoundFontUsage(soundFontUsage);
+	const embedsSoundFont =
+		soundFont !== false && files.some((file) => isSelected(file) && isSoundFontKey(keyOf(file)));
+	let soundFontTools = null;
+	let usage = explicitUsage;
+	if (embedsSoundFont && usage === undefined) {
+		const midiFiles = files.filter((file) => isSelected(file) && isMidiKey(keyOf(file)));
+		if (midiFiles.length > 0) {
+			soundFontTools = await loadSoundFontTools();
+			const parsed = [];
+			for (const file of midiFiles) {
+				try {
+					parsed.push(soundFontTools.parseMidi(await readFile(file)));
+				} catch (error) {
+					throw new Error(
+						`cannot read MIDI asset ${keyOf(file)} to subset a SoundFont: ${error.message ?? error}`,
+					);
+				}
+			}
+			usage = soundFontTools.collectSoundFontUsage(parsed);
+		}
+	}
+	if (embedsSoundFont && usage !== undefined && !soundFontTools) soundFontTools = await loadSoundFontTools();
+	const soundFonts = [];
+
 	await rm(to, { recursive: true, force: true });
 	await mkdir(to, { recursive: true });
 
@@ -106,7 +212,8 @@ export async function compileResources({
 	const creditsFile = join(from, 'credits.json');
 	let credits = null;
 
-	for await (const file of walk(from)) {
+	for (const file of files) {
+		if (selected && !selected.has(keyOf(file))) continue;
 		if (file === creditsFile) {
 			credits = creditsText(JSON.parse(await readFile(file, 'utf8')));
 			continue;
@@ -118,7 +225,7 @@ export async function compileResources({
 			continue;
 		}
 
-		const key = relative(from, file).split(sep).join('/');
+		const key = keyOf(file);
 		const data = await readFile(file);
 
 		let mimeType = type;
@@ -132,6 +239,19 @@ export async function compileResources({
 			}
 		}
 
+		if (isSoundFontKey(key)) {
+			if (usage !== undefined && soundFontTools) {
+				try {
+					bytes = Buffer.from(soundFontTools.subsetSoundFont(data, usage));
+				} 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 });
+			} else {
+				soundFonts.push({ key, programs: null, rawBytes: data.length, embeddedBytes: data.length });
+			}
+		}
+
 		const name = group(key);
 		if (!groups.has(name)) groups.set(name, {});
 		groups.get(name)[key] = `data:${mimeType};base64,${bytes.toString('base64')}`;
@@ -152,7 +272,7 @@ export async function compileResources({
 
 	if (credits) await writeFile(join(to, 'CREDITS.txt'), credits, 'utf8');
 
-	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits };
+	return { groups: written, rawBytes, embeddedBytes, webpConverted, skipped, credits, soundFonts };
 }
 
 /** the plain-text credits for a manifest, one block per entry; throws on an entry that cannot be attributed */
@@ -181,7 +301,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]]',
+			'usage: node compile-resources.mjs <asset folder> <output folder> [--to-webp] [--webp-lossy[=quality]] [--no-soundfont-subset] [--soundfont-usage=bank:program,...]',
 		);
 		process.exit(1);
 	}
@@ -190,7 +310,11 @@ async function runCli() {
 	const webpLossless = !lossyFlag;
 	const webpQuality = lossyFlag && lossyFlag.includes('=') ? Number(lossyFlag.split('=')[1]) : 90;
 
-	const { groups, rawBytes, embeddedBytes, webpConverted, skipped } = await compileResources({
+	const soundFontUsage = soundFontUsageFromFlag(
+		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
@@ -198,6 +322,8 @@ async function runCli() {
 		toWebp,
 		webpLossless,
 		webpQuality,
+		soundFont: !args.includes('--no-soundfont-subset'),
+		soundFontUsage,
 	});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
@@ -205,6 +331,13 @@ async function runCli() {
 		console.log(`  ${join(relative(process.cwd(), to), name + '.js').padEnd(40)}${kb(size)}  (${count} files)`);
 	}
 	console.log(`  ${groups.length} script(s), ${kb(rawBytes)} of assets` + (skipped ? `, ${skipped} skipped` : ''));
+	for (const font of 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 (toWebp) {
 		console.log(
 			`  ${webpConverted} image(s) converted to WebP (${webpLossless ? 'lossless' : `lossy, quality ${webpQuality}`}), ` +

package/tools/emit-page.d.mts

@@ -1,4 +1,4 @@
-import type { CompileResourcesGroup } from './compile-resources.mjs';
+import type { CompileResourcesGroup, SoundFontEmbed, SoundFontUsage } from './compile-resources.mjs';
 import type { CompressRow } from './compress-dist.mjs';
 import type { SingleFileOptions, SingleFileResult } from './single-file.mjs';
 
@@ -9,6 +9,8 @@ export interface EmitPageOptions {
 	assets?: string;
 	/** maps an asset path to its script's name; defaults to one script per top-level folder */
 	groupBy?: (key: string) => string;
+	/** Exact paths relative to the asset folder to embed. Omit to include all; [] includes none. Unknown entries fail by name. */
+	assetFiles?: readonly string[];
 	/** write `.gz`/`.br` siblings for a server to negotiate; default true */
 	compress?: boolean;
 	/** also write `.xz`, where the system `xz` binary exists */
@@ -18,6 +20,10 @@ export interface EmitPageOptions {
 	toWebp?: boolean;
 	webpLossless?: boolean;
 	webpQuality?: number;
+	/** 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. */
+	soundFontUsage?: readonly SoundFontUsage[];
 	/** the page's Content-Security-Policy: on by default, `false` to leave it out */
 	csp?: boolean | CspOptions;
 }
@@ -36,6 +42,8 @@ export interface EmitPageResult {
 	rawBytes: number;
 	embeddedBytes: number;
 	webpConverted: number;
+	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
+	soundFonts: SoundFontEmbed[];
 	compressed: CompressRow[] | null;
 	single: SingleFileResult | null;
 }

package/tools/emit-page.mjs

@@ -3,7 +3,7 @@ import { readFile, writeFile, rm, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { compileResources } from './compile-resources.mjs';
+import { compileResources, soundFontUsageFromFlag } from './compile-resources.mjs';
 import { compressDist } from './compress-dist.mjs';
 import { toClassicScript } from './classic-html.mjs';
 import { buildSingleFile } from './single-file.mjs';
@@ -30,6 +30,7 @@ import { withContentSecurityPolicy } from './csp.mjs';
  *                 [--no-compress] [--xz]
  *                 [--single-file] [--single-file-compress[=level]]
  *                 [--single-file-brotli[=quality]] [--to-webp] [--webp-lossy[=quality]]
+ *                 [--no-soundfont-subset] [--soundfont-usage=bank:program,...]
  *
  * `--dist` defaults to `<project folder>/dist` and `--assets` to `<project folder>/assets`; with
  * no assets folder at all, the page is rewritten and nothing is compiled.
@@ -66,18 +67,32 @@ export async function emitPage({
 	dist,
 	assets,
 	groupBy,
+	assetFiles,
 	compress = true,
 	xz = false,
 	singleFile = false,
 	toWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	soundFont = true,
+	soundFontUsage,
 	csp = true,
 }) {
 	if (!dist) throw new Error('emitPage needs the dist folder of a vite build');
+	if (!assets && assetFiles?.length) throw new Error(`unknown asset file ${assetFiles[0]}: no assets folder`);
 	const compiled = assets
-		? await compileResources({ from: assets, to: join(dist, 'assets'), groupBy, toWebp, webpLossless, webpQuality })
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0 };
+		? await compileResources({
+				from: assets,
+				to: join(dist, 'assets'),
+				groupBy,
+				assetFiles,
+				toWebp,
+				webpLossless,
+				webpQuality,
+				soundFont,
+				soundFontUsage,
+			})
+		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, soundFonts: [] };
 
 	const html = await readFile(join(dist, 'index.html'), 'utf8');
 	const classic = toClassicScript(html);
@@ -132,6 +147,10 @@ async function main(argv) {
 		level: levelFlag?.includes('=') ? Number(levelFlag.split('=')[1]) : undefined,
 	};
 
+	const soundFontUsage = soundFontUsageFromFlag(
+		argv.find((a) => a.startsWith('--soundfont-usage='))?.slice('--soundfont-usage='.length),
+	);
+
 	const result = await emitPage({
 		dist,
 		assets: hasAssets ? assetsDir : undefined,
@@ -143,6 +162,8 @@ async function main(argv) {
 		toWebp: argv.includes('--to-webp'),
 		webpLossless: !webpLossyFlag,
 		webpQuality: webpLossyFlag?.includes('=') ? Number(webpLossyFlag.split('=')[1]) : 90,
+		soundFont: !argv.includes('--no-soundfont-subset'),
+		soundFontUsage,
 		csp: argv.includes('--no-csp')
 			? false
 			: { connect: argv.filter((a) => a.startsWith('--connect=')).map((a) => a.slice('--connect='.length)) },
@@ -158,6 +179,13 @@ async function main(argv) {
 				`${kb(result.rawBytes)} -> ${kb(result.embeddedBytes)} embedded`,
 		);
 	}
+	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)}`,
+		);
+	}
 	console.log('  open index.html directly - no server needed');
 	if (result.compressed) {
 		for (const row of result.compressed) {

package/tools/vite.mjs

@@ -11,7 +11,12 @@ import { buildArtifactSbom, serialize, shippedFiles } from './sbom.mjs';
  * It sets the configuration that target needs (a classic IIFE bundle named `game.js`, relative
  * urls through `base: './'`, no inlined or copied assets since they are compiled instead) and
  * serves `assets` (default `'assets'`, `false` for none) as the public folder, so an asset path reads the same in `vite` dev as in the
- * build. At the end of the build it runs `emitPage` over the output folder with the same
+ * build. `assetFiles: ['characters/hero.svg', 'music/theme.ogg']` embeds only those paths;
+ * omit it for all assets, or pass [] for none. An unknown entry fails by name. Filtering
+ * affects the build only, so the dev server still serves the asset folder normally.
+ * An embedded `.sf2` is subset at build time to the programs the embedded `.mid` files
+ * use (`soundFont: false` embeds it whole, `soundFontUsage` names the programs instead).
+ * At the end of the build it runs `emitPage` over the output folder with the same
  * options. A setting the game's own config gives explicitly still wins, since vite merges a
  * plugin's `config` result under the user's.
  *