@datamoc/mw_games 0.43.0 → 0.44.2

package/tools/audio.mjs

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/**
+ * `mwg-audio`: the developer-side tool for a game's audio files. It tells what a file is
+ * (`inspect`), renders a MIDI file to a WAV through any registered engine (`render`), converts
+ * between the formats the library reads and writes (`convert`), measures what the audio costs a
+ * page and the memory a bus holds once tracks are rendered (`budget`), and says how far apart
+ * two renders sound (`compare`). Nothing here runs in a browser or reaches a player.
+ *
+ * The chip formats (MWA, YM, VGM, NSF, SID) belong to a separate package: `inspect` names them
+ * by their signature, and `convert` hands them to `--converter <module>`, a module whose default
+ * export is `(bytes, name) => Uint8Array`. Engines for `render --synth` come from `--module
+ * <file>`, a module that calls `registerMidiSynth` when imported.
+ */
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** the library: the TypeScript source in this repository, the built `dist/` in an installed package */
+async function loadLibrary() {
+	try {
+		const [midi, render, soundFont, wav, resample, distance, synth] = await Promise.all([
+			import('../src/audio/Midi.ts'),
+			import('../src/audio/MidiRender.ts'),
+			import('../src/audio/SoundFont.ts'),
+			import('../src/audio/Wav.ts'),
+			import('../src/audio/Resample.ts'),
+			import('../src/audio/SpectralDistance.ts'),
+			import('../src/audio/MidiSynth.ts'),
+		]);
+		return { ...midi, ...render, ...soundFont, ...wav, ...resample, ...distance, ...synth };
+	} catch {
+		return import(pathToFileURL(join(HERE, '..', 'dist', 'audio', 'index.js')).href);
+	}
+}
+
+const ascii = (bytes, from, to) => String.fromCharCode(...bytes.subarray(from, to));
+
+const SYSEX_MAKERS = new Map([
+	[0x41, 'Roland'],
+	[0x42, 'Korg'],
+	[0x43, 'Yamaha'],
+	[0x44, 'Casio'],
+	[0x47, 'Akai'],
+	[0x7e, 'universal non-real-time'],
+	[0x7f, 'universal real-time'],
+]);
+
+/**
+ * Names a file by its content, falling back on the extension for formats with no signature.
+ * Returns `{ format, kind }` where kind is `midi`, `wav`, `soundfont`, `compressed`, `chip`,
+ * `tracker`, `sysex` or `unknown`.
+ */
+export function detectAudioFormat(bytes, name = '') {
+	const head4 = ascii(bytes, 0, 4);
+	const extension = extname(name).toLowerCase();
+	if (head4 === 'MThd') return { format: 'MIDI', kind: 'midi' };
+	if (head4 === 'RIFF') {
+		const form = ascii(bytes, 8, 12);
+		if (form === 'WAVE') return { format: 'WAV', kind: 'wav' };
+		if (form === 'sfbk') return { format: 'SoundFont 2', kind: 'soundfont' };
+		if (form === 'RMID') return { format: 'RIFF MIDI', kind: 'midi' };
+	}
+	if (head4 === 'OggS')
+		return { format: ascii(bytes, 28, 35) === '\x01vorbis' ? 'Ogg Vorbis' : 'Ogg', kind: 'compressed' };
+	if (head4 === 'fLaC') return { format: 'FLAC', kind: 'compressed' };
+	if (head4 === 'MWA1') return { format: 'MWA', kind: 'chip' };
+	if (head4 === 'NESM') return { format: 'NSF', kind: 'chip' };
+	if (head4 === 'PSID' || head4 === 'RSID') return { format: 'SID', kind: 'chip' };
+	if (head4 === 'Vgm ') return { format: 'VGM', kind: 'chip' };
+	if (head4 === 'IMPM') return { format: 'Impulse Tracker', kind: 'tracker' };
+	if (ascii(bytes, 0, 17) === 'Extended Module: ') return { format: 'XM', kind: 'tracker' };
+	if (head4.startsWith('YM') && /^YM[3456]/.test(head4)) return { format: 'YM', kind: 'chip' };
+	if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
+		return {
+			format: extension === '.vgz' ? 'VGZ (gzip VGM)' : 'gzip',
+			kind: extension === '.vgz' ? 'chip' : 'unknown',
+		};
+	}
+	if (bytes[0] === 0xf0 && bytes.includes(0xf7)) return { format: 'MIDI SysEx', kind: 'sysex' };
+	if (head4.startsWith('ID3') || (bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0))
+		return { format: 'MP3', kind: 'compressed' };
+	if (ascii(bytes, 4, 8) === 'ftyp') return { format: 'MP4 audio', kind: 'compressed' };
+	if (extension === '.mod' && bytes.length > 1084) return { format: 'MOD', kind: 'tracker' };
+	return { format: 'unknown', kind: 'unknown' };
+}
+
+/** the SysEx messages of a file: how many, who made the instrument, how large */
+function sysexSummary(bytes) {
+	const messages = [];
+	let start = -1;
+	for (let i = 0; i < bytes.length; i++) {
+		if (bytes[i] === 0xf0) start = i;
+		else if (bytes[i] === 0xf7 && start !== -1) {
+			messages.push({ maker: bytes[start + 1], size: i - start + 1 });
+			start = -1;
+		}
+	}
+	return {
+		messages: messages.length,
+		makers: [...new Set(messages.map((m) => SYSEX_MAKERS.get(m.maker) ?? `0x${m.maker.toString(16)}`))],
+		largestMessage: Math.max(0, ...messages.map((m) => m.size)),
+	};
+}
+
+/** the facts about a MIDI file a developer wants before rendering it */
+function midiSummary(lib, bytes) {
+	const file = lib.parseMidi(bytes);
+	const notes = lib.scheduleMidi(file);
+	const channels = {};
+	for (const note of notes) {
+		const entry = (channels[note.channel] ??= { notes: 0, programs: new Set() });
+		entry.notes++;
+		entry.programs.add(note.channel === 9 ? 'drums' : note.program);
+	}
+	const end = notes.reduce((latest, note) => Math.max(latest, note.time + note.duration), 0);
+	return {
+		ticksPerQuarter: file.ticksPerQuarter,
+		events: file.events.length,
+		notes: notes.length,
+		seconds: Number(end.toFixed(3)),
+		loopStartSeconds: lib.midiLoopStart(file),
+		channels: Object.fromEntries(
+			Object.entries(channels).map(([channel, entry]) => [
+				channel,
+				{ notes: entry.notes, programs: [...entry.programs] },
+			]),
+		),
+	};
+}
+
+/** describes one file: its format and the numbers that matter for that format */
+export async function inspectAudio(bytes, name = '') {
+	const lib = await loadLibrary();
+	const detected = detectAudioFormat(bytes, name);
+	const report = { name, bytes: bytes.length, ...detected };
+	if (detected.kind === 'wav') Object.assign(report, lib.wavInfo(bytes));
+	else if (detected.kind === 'midi' && detected.format === 'MIDI') Object.assign(report, midiSummary(lib, bytes));
+	else if (detected.kind === 'sysex') Object.assign(report, sysexSummary(bytes));
+	else if (detected.kind === 'soundfont') {
+		const font = lib.parseSoundFont(bytes);
+		report.presets = font.presets ? font.presets.length : undefined;
+	}
+	return report;
+}
+
+/** `"0,9"` as `[0, 9]`, each a MIDI channel */
+export function parseChannelList(text) {
+	return text.split(',').map((item) => {
+		const channel = Number(item.trim());
+		if (!Number.isInteger(channel) || channel < 0 || channel > 15)
+			throw new Error(`invalid channel "${item}": expected 0 to 15`);
+		return channel;
+	});
+}
+
+async function importModule(path) {
+	return import(pathToFileURL(resolve(path)).href);
+}
+
+/**
+ * Renders MIDI bytes to WAV bytes. `synth` is an engine name or a comma list tried in order
+ * (the engines come from `modules`, imported first), `soundfont` the bytes of a SoundFont.
+ */
+export async function renderToWav(midiBytes, options = {}) {
+	const lib = await loadLibrary();
+	for (const module of options.modules ?? []) await importModule(module);
+	const rendered = lib.renderMidiToBuffer(lib.parseMidi(midiBytes), {
+		synth: options.synth ? options.synth.split(',').map((name) => name.trim()) : undefined,
+		soundfont: options.soundfont ? lib.parseSoundFont(options.soundfont) : null,
+		sampleRate: options.rate,
+		gain: options.gain,
+		channels: options.channels,
+	});
+	return lib.encodeWav(rendered, options.float ? 'float32' : 'pcm16');
+}
+
+/** resamples WAV bytes to another rate */
+export async function resampleWav(wavBytes, rate, float = false) {
+	const lib = await loadLibrary();
+	return lib.encodeWav(lib.resampleStereo(lib.decodeWav(wavBytes), rate), float ? 'float32' : 'pcm16');
+}
+
+/** how far apart two WAV files sound, in dB of log-spectrum difference */
+export async function compareWavs(a, b, options = {}) {
+	const lib = await loadLibrary();
+	return lib.spectralDistance(lib.decodeWav(a), lib.decodeWav(b), options);
+}
+
+const AUDIO_EXTENSIONS = new Set([
+	'.mid',
+	'.midi',
+	'.wav',
+	'.ogg',
+	'.mp3',
+	'.flac',
+	'.m4a',
+	'.mwa',
+	'.sf2',
+	'.sf3',
+	'.syx',
+	'.nsf',
+	'.sid',
+	'.vgm',
+	'.ym',
+]);
+
+/** every audio file under the given files and folders */
+function collectFiles(paths) {
+	const found = [];
+	const visit = (path) => {
+		const stats = statSync(path);
+		if (stats.isDirectory()) {
+			for (const entry of readdirSync(path).sort()) visit(join(path, entry));
+		} else if (AUDIO_EXTENSIONS.has(extname(path).toLowerCase())) {
+			found.push(path);
+		}
+	};
+	for (const path of paths) visit(path);
+	return found;
+}
+
+const MEGABYTE = 1024 * 1024;
+
+/**
+ * What the audio of a game costs: for each file the bytes on disk, the bytes it adds to a page
+ * (base64 makes it a third larger) and the memory it holds once decoded into a bus. A MIDI file
+ * is rendered to PCM before it plays, so its memory is its length times the render rate; a
+ * compressed file's decoded size cannot be known without decoding it, and is left out of the
+ * total rather than guessed.
+ */
+export async function audioBudget(paths, options = {}) {
+	const lib = await loadLibrary();
+	const rate = options.rate ?? 22050;
+	const maxSeconds = options.maxSeconds ?? 480;
+	const files = [];
+	for (const path of collectFiles(paths)) {
+		const bytes = readFileSync(path);
+		const detected = detectAudioFormat(bytes, path);
+		let seconds = null;
+		let decodedBytes = null;
+		let renderRate = rate;
+		let sizingSeconds = null;
+		if (detected.kind === 'midi' && detected.format === 'MIDI') {
+			const summary = midiSummary(lib, bytes);
+			seconds = summary.seconds;
+			//the memory a render holds includes its decay tail; the track's own length does not
+			sizingSeconds = Math.min(maxSeconds, seconds + 1.5);
+		} else if (detected.kind === 'wav') {
+			const info = lib.wavInfo(bytes);
+			seconds = info.seconds;
+			sizingSeconds = seconds;
+			renderRate = info.sampleRate;
+		}
+		if (sizingSeconds !== null) decodedBytes = Math.ceil(sizingSeconds * renderRate) * 2 * 4;
+		files.push({
+			path,
+			format: detected.format,
+			diskBytes: bytes.length,
+			pageBytes: Math.ceil((bytes.length * 4) / 3),
+			seconds,
+			decodedBytes,
+		});
+	}
+	const total = (key) => files.reduce((sum, file) => sum + (file[key] ?? 0), 0);
+	const problems = [];
+	if (options.maxMegabytes !== undefined && total('decodedBytes') > options.maxMegabytes * MEGABYTE) {
+		problems.push(
+			`decoded audio is ${(total('decodedBytes') / MEGABYTE).toFixed(1)} MB, over the ${options.maxMegabytes} MB budget`,
+		);
+	}
+	for (const file of files) {
+		if (file.seconds !== null && file.seconds > (options.maxTrackSeconds ?? Infinity)) {
+			problems.push(`${file.path} is ${file.seconds.toFixed(0)} s, over ${options.maxTrackSeconds} s`);
+		}
+	}
+	return {
+		files,
+		totals: { diskBytes: total('diskBytes'), pageBytes: total('pageBytes'), decodedBytes: total('decodedBytes') },
+		problems,
+	};
+}
+
+const USAGE = `usage: mwg-audio <command>
+  inspect <file>...                              the format and its numbers: MIDI notes and channels, WAV layout, SysEx messages
+  render <in.mid> -o <out.wav> [--synth <names>] [--module <file>...] [--soundfont <file>] [--rate <hz>]
+                                                 [--channels 0,9] [--gain <0-1>] [--float]
+                                                 a MIDI file to WAV through a registered engine (--module imports the code that registers it)
+  convert <in> <out> [--rate <hz>] [--converter <module>]
+                                                 .mid to .wav, .wav to .wav at another rate, or any file through a converter module
+                                                 (MWA and the other chip formats come from the retro-audio package's converter)
+  budget <file|folder>... [--rate <hz>] [--max-mb <n>] [--max-track-seconds <n>] [--json]
+                                                 disk, page and decoded memory cost of the audio; exits 1 over a budget
+  compare <a.wav> <b.wav> [--max <db>]           spectral distance between two renders; exits 1 over --max`;
+
+async function main(argv) {
+	const [command, ...rest] = argv;
+	if (!command || command === '--help' || command === '-h') {
+		console.log(USAGE);
+		return;
+	}
+	const flag = (name) => {
+		const at = rest.indexOf(name);
+		return at === -1 ? undefined : rest[at + 1];
+	};
+	const valuesAfter = (name) => {
+		const out = [];
+		for (let at = rest.indexOf(name); at !== -1 && at < rest.length; at = rest.indexOf(name, at + 1)) {
+			for (let i = at + 1; i < rest.length && !rest[i].startsWith('--') && rest[i] !== '-o'; i++)
+				out.push(rest[i]);
+		}
+		return out;
+	};
+	const number = (name) => (flag(name) === undefined ? undefined : Number(flag(name)));
+	const positional = () => {
+		const out = [];
+		const valued = new Set([
+			'-o',
+			'--synth',
+			'--module',
+			'--soundfont',
+			'--rate',
+			'--channels',
+			'--gain',
+			'--converter',
+			'--max',
+			'--max-mb',
+			'--max-track-seconds',
+		]);
+		for (let i = 0; i < rest.length; i++) {
+			if (valued.has(rest[i])) i++;
+			else if (!rest[i].startsWith('-')) out.push(rest[i]);
+		}
+		return out;
+	};
+
+	if (command === 'inspect') {
+		const files = positional();
+		if (files.length === 0) throw new Error('usage: mwg-audio inspect <file>...');
+		for (const file of files) console.log(JSON.stringify(await inspectAudio(readFileSync(file), file), null, 2));
+	} else if (command === 'render') {
+		const [input] = positional();
+		const out = flag('-o');
+		if (!input || !out) throw new Error('usage: mwg-audio render <in.mid> -o <out.wav>');
+		const wav = await renderToWav(readFileSync(input), {
+			synth: flag('--synth'),
+			modules: valuesAfter('--module'),
+			soundfont: flag('--soundfont') ? readFileSync(flag('--soundfont')) : undefined,
+			rate: number('--rate'),
+			gain: number('--gain'),
+			channels: flag('--channels') ? parseChannelList(flag('--channels')) : undefined,
+			float: rest.includes('--float'),
+		});
+		mkdirSync(dirname(resolve(out)), { recursive: true });
+		writeFileSync(out, wav);
+		console.log(`wrote ${out}: ${(wav.length / 1024).toFixed(0)} KB`);
+	} else if (command === 'convert') {
+		const [input, output] = positional();
+		if (!input || !output) throw new Error('usage: mwg-audio convert <in> <out>');
+		const bytes = readFileSync(input);
+		const target = extname(output).toLowerCase();
+		let result;
+		if (flag('--converter')) {
+			const converter = (await importModule(flag('--converter'))).default;
+			if (typeof converter !== 'function')
+				throw new Error('a converter module must export a default function (bytes, name) => Uint8Array');
+			result = await converter(bytes, input);
+		} else if (target === '.mwa') {
+			throw new Error(
+				"converting to MWA is the retro-audio package's job: pass its converter with --converter <module>",
+			);
+		} else if (target === '.wav') {
+			const detected = detectAudioFormat(bytes, input);
+			if (detected.kind === 'midi') result = await renderToWav(bytes, { rate: number('--rate') });
+			else if (detected.kind === 'wav')
+				result = number('--rate') ? await resampleWav(bytes, number('--rate')) : bytes;
+			else throw new Error(`cannot convert ${detected.format} to .wav without a converter`);
+		} else {
+			throw new Error(`no conversion to "${target}" is built in: pass --converter <module>`);
+		}
+		mkdirSync(dirname(resolve(output)), { recursive: true });
+		writeFileSync(output, result);
+		console.log(`wrote ${output}: ${(result.length / 1024).toFixed(0)} KB`);
+	} else if (command === 'budget') {
+		const paths = positional();
+		if (paths.length === 0) throw new Error('usage: mwg-audio budget <file|folder>...');
+		const report = await audioBudget(paths, {
+			rate: number('--rate'),
+			maxMegabytes: number('--max-mb'),
+			maxTrackSeconds: number('--max-track-seconds'),
+		});
+		if (rest.includes('--json')) {
+			console.log(JSON.stringify(report, null, 2));
+		} else {
+			for (const file of report.files) {
+				const memory =
+					file.decodedBytes === null
+						? 'decoded size unknown'
+						: `${(file.decodedBytes / MEGABYTE).toFixed(1)} MB decoded`;
+				console.log(
+					`${file.path}  ${file.format}  ${(file.pageBytes / 1024).toFixed(0)} KB in the page  ${memory}`,
+				);
+			}
+			const { totals } = report;
+			console.log(
+				`total: ${(totals.pageBytes / 1024).toFixed(0)} KB in the page, ${(totals.decodedBytes / MEGABYTE).toFixed(1)} MB decoded (files of unknown decoded size not counted)`,
+			);
+		}
+		for (const problem of report.problems) console.error(problem);
+		if (report.problems.length > 0) process.exitCode = 1;
+	} else if (command === 'compare') {
+		const [a, b] = positional();
+		if (!a || !b) throw new Error('usage: mwg-audio compare <a.wav> <b.wav>');
+		const result = await compareWavs(readFileSync(a), readFileSync(b));
+		console.log(`${result.decibels.toFixed(2)} dB over ${result.windows} windows`);
+		if (number('--max') !== undefined && result.decibels > number('--max')) {
+			console.error(`over the ${number('--max')} dB limit`);
+			process.exitCode = 1;
+		}
+	} else {
+		throw new Error(`unknown command "${command}"\n${USAGE}`);
+	}
+}
+
+//realpath, since an npm `bin` shim reaches this file through a symlink
+if (
+	process.argv[1] &&
+	existsSync(process.argv[1]) &&
+	realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	});
+}

package/tools/mwl.mjs

@@ -8,15 +8,24 @@ import {
 	collectHookReferences,
 	compile,
 	compileAndEmitSources,
+	compilePackages,
 	compileSources,
 	contentReport,
+	decodePackage,
+	emitArtifacts,
 	emitHooksDeclaration,
 	emitModule,
+	encodePackage,
 	extractCatalog,
+	generateCredits,
+	loadPackage,
+	mergePackage,
+	packageContent,
 	parse,
 	preprocess,
 	validate,
 	validateHookReferences,
+	verifyPackage,
 } from '../dist/mwl/index.js';
 
 /**
@@ -54,6 +63,9 @@ const commands = [
 	'ci',
 	'hooks',
 	'build',
+	'pack',
+	'unpack',
+	'verify',
 ];
 const [command, input] = args;
 const outputFlag = args.indexOf('-o');
@@ -67,16 +79,18 @@ 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]',
+		'usage: mwg-mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build|pack|unpack|verify> input.mwl|input.mwp|directory [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory] [--audio-converter module] [--allow capabilities] [--json]',
 	);
 	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]',
+		'Usage: mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build|pack|unpack|verify> input.mwl|input.mwp|directory [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory] [--audio-converter module] [--allow capabilities] [--json]',
 	);
 	process.exitCode = 2;
+} else if (command === 'pack' || command === 'unpack' || command === 'verify' || /.mwp$/i.test(input)) {
+	process.exitCode = await packageCommand();
 } else {
 	const files = fs.statSync(input).isDirectory()
 		? collectSources(input)
@@ -322,3 +336,131 @@ async function hooks(files) {
 		fs.rmSync(entryFile, { force: true });
 	}
 }
+
+/**
+ * `pack <dir> -o x.mwp` writes a folder (`content.mwl` plus its media) as one package, refusing to
+ * write one that `verify` would reject. `unpack x.mwp -o dir` writes the files back. `verify x.mwp`
+ * checks digests, limits, schema, references, licences, ROM images and the capabilities requested
+ * (`--allow audio,script` applies a game policy, `--json` prints the report). Any other command
+ * given a `.mwp` runs on the content the package's characters expand to.
+ *
+ * Audio conversion to MWA belongs to the retro-audio package, not to mwg: `--audio-converter module`
+ * names an ES module whose default export is `(path, bytes) => { path, data } | undefined`, called
+ * for chip-music files (.ym .vgm .nsf .sid .dro .imf .cmf). Without it those files are packed as
+ * they are, with a warning.
+ */
+async function packageCommand() {
+	const flag = (name) => {
+		const at = args.indexOf(name);
+		return at === -1 ? undefined : args[at + 1];
+	};
+	if (command === 'pack') {
+		const root = path.resolve(input);
+		const converter = flag('--audio-converter');
+		const convert = converter ? (await import(pathToFileURL(path.resolve(converter)).href)).default : undefined;
+		if (converter && typeof convert !== 'function') throw new Error(`${converter} must default-export a function`);
+		const files = [];
+		const visit = (directory) => {
+			for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+				if (entry.name.startsWith('.')) continue;
+				const full = path.join(directory, entry.name);
+				if (entry.isDirectory()) visit(full);
+				else
+					files.push({
+						path: path.relative(root, full).split(path.sep).join('/'),
+						data: new Uint8Array(fs.readFileSync(full)),
+					});
+			}
+		};
+		visit(root);
+		const chip = /.(?:ym|vgm|nsf|sid|dro|imf|cmf)$/i;
+		const packed = [];
+		for (const file of files) {
+			if (!chip.test(file.path)) {
+				packed.push(file);
+				continue;
+			}
+			if (!convert)
+				console.error(`warning: ${file.path} is packed as it is; pass --audio-converter to store it as MWA`);
+			packed.push((convert && (await convert(file.path, file.data))) || file);
+		}
+		const bytes = await encodePackage(packed, { main: flag('--main') });
+		const report = await verifyPackage(bytes);
+		for (const warning of report.warnings) console.error(`warning: ${warning}`);
+		if (!report.ok) {
+			for (const error of report.errors) console.error(`error: ${error}`);
+			console.error('nothing was written');
+			return 1;
+		}
+		const target = path.resolve(output ?? `${root}.mwp`);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, bytes);
+		console.log(`packed ${packed.length} file(s) into ${target} (${report.ref})`);
+		return 0;
+	}
+	const bytes = new Uint8Array(fs.readFileSync(input));
+	if (command === 'verify') {
+		const allow = flag('--allow');
+		const report = await verifyPackage(
+			bytes,
+			allow === undefined ? {} : { policy: { allow: allow.split(',').filter(Boolean) } },
+		);
+		if (args.includes('--json')) console.log(JSON.stringify(report, null, '	'));
+		else {
+			for (const warning of report.warnings) console.error(`warning: ${warning}`);
+			for (const error of report.errors) console.error(`error: ${error}`);
+			if (report.ok)
+				console.log(
+					`${input}: valid package ${report.ref} (capabilities: ${report.capabilities.join(', ') || 'none'})`,
+				);
+		}
+		return report.ok ? 0 : 1;
+	}
+	if (command === 'unpack') {
+		const decoded = await decodePackage(bytes);
+		const target = path.resolve(output ?? input.replace(/.mwp$/i, ''));
+		for (const file of decoded.files) {
+			const destination = path.resolve(target, file.path);
+			if (!destination.startsWith(target + path.sep))
+				throw new Error(`${file.path} escapes the output directory`);
+			fs.mkdirSync(path.dirname(destination), { recursive: true });
+			fs.writeFileSync(destination, file.data);
+		}
+		console.log(`unpacked ${decoded.files.length} file(s) into ${target}`);
+		return 0;
+	}
+	if (!['validate', 'compile', 'extract-i18n', 'assets', 'report', 'build'].includes(command)) {
+		console.error(`mwl ${command} does not take a package; unpack it first`);
+		return 2;
+	}
+	const loaded = await loadPackage(bytes);
+	const set = mergePackage(loaded);
+	const game = compilePackages(set);
+	if (command === 'validate') {
+		console.log(`${input}: valid package`);
+		return 0;
+	}
+	if (command === 'build') {
+		const directory = path.resolve(output ?? 'generated');
+		fs.mkdirSync(directory, { recursive: true });
+		const content = JSON.stringify(packageContent(set), null, '	');
+		for (const artifact of emitArtifacts(game, {
+			artifacts: {
+				'package-content.json': `${content}
+`,
+			},
+		}))
+			fs.writeFileSync(path.join(directory, artifact.name), artifact.content);
+		const credits = generateCredits([loaded.document]);
+		if (credits) fs.writeFileSync(path.join(directory, 'CREDITS.txt'), credits);
+		console.log(`built package ${loaded.document.meta.id} into ${directory}`);
+		return 0;
+	}
+	const values =
+		command === 'extract-i18n' ? extractCatalog(game) : command === 'assets' ? game.assets : contentReport(game);
+	const text = `${JSON.stringify(values, null, '	')}
+`;
+	if (output) fs.writeFileSync(output, text);
+	else process.stdout.write(text);
+	return 0;
+}

package/tools.md

@@ -13,7 +13,7 @@ by double-clicking. Run from the repo root.
 | `soundfonts` | Picks a SoundFont other than the bundled `microgm-opt` (WTFPL, 2.6 MB, the default). `list` prints the catalogue (`data/soundfont-catalog.json`, a licence-classified snapshot of the marmooo free-soundfonts collection: public domain, MIT and CC-BY fonts fetch freely, share-alike, copyleft and unclear ones need `--accept-licence`); `fetch <font>` downloads only the instruments the game's MIDI files use (`--midi`) or a list (`--programs 0,24,128:0`), and merges them into one SoundFont 3 (the compressed samples untouched, no decoding, no `ffmpeg`) beside a `.credits.txt` that keeps the licence with the file; the game decodes it where it runs with `loadSoundFont`. `fetch --sf2` and `convert <in.sf3> <out.sf2>` decode to a plain SoundFont 2 instead, about eight times larger, which needs `ffmpeg` on PATH (developer machines only). The result goes in the asset folder, where the build subsets it to the programs the game plays | `npx mwg-soundfonts list`, `npx mwg-soundfonts fetch GeneralUser_GS_v2.0.3 --midi assets/*.mid --accept-licence`, or `fetchSoundFont` from `@datamoc/mw_games/tools/soundfonts` |
 | `extract-rgssad` | Decrypts an RPG Maker XP/VX archive to plain files (vendored MIT decoder, developer-side only); an entry whose name would land outside `outDir` is refused (item 389) | `npm run extract:rgssad -- <archive.rgssad> <outDir>` here; `npx mwg-extract-rgssad <archive> <outDir>` or `extractRgssad` from `@datamoc/mw_games/tools/extract-rgssad` in a game |
 | `multiplayer-server` | The reference lockstep server for `core.LockstepClient`: rooms, one shared tick, `null` for a missed input, messages capped at `maxMessageBytes` (64 KB) and read through `parseInbound`, room names bounded, `maxClientsPerRoom` (64). Speaks `ws:`, so a deployment puts it behind a TLS proxy (items 129, 385) | `npx mwg-lockstep-server [port] [--host=]` (127.0.0.1 unless `--host`), or `createLockstepServer(options)` from `@datamoc/mw_games/tools/multiplayer-server`; needs the optional peer `ws` |
-| `mwl` | Compiles MWL content (`[game]`/`[scenario]`/`[side]`/`[unit]`/`[event]`/`[campaign]`) into a game-data module, an i18n catalog and an asset manifest | `npm run mwl -- build <contentDir> -o <outDir>`, or `node node_modules/@datamoc/mw_games/tools/mwl.mjs build <contentDir> -o <outDir>` from an install. It is a command line, not an importable module (it dispatches when loaded), so it has no package subpath; script against the typed library instead: `@datamoc/mw_games/mwl` |
+| `mwl` | Compiles MWL content (`[game]`/`[scenario]`/`[side]`/`[unit]`/`[event]`/`[campaign]`) into a game-data module, an i18n catalog and an asset manifest. Also packs a folder (`content.mwl` plus media) into one `.mwp` content package (`pack`), unpacks it, and verifies it (`verify`: digests, limits, schema, licences, instrument ROM refusal, requested capabilities); `build`, `validate`, `extract-i18n` and `assets` accept a `.mwp` in place of a folder. `pack --audio-converter <module>` is the hook for converting chip music to MWA, which lives in the retro-audio package | `npm run mwl -- build <contentDir> -o <outDir>`, or `node node_modules/@datamoc/mw_games/tools/mwl.mjs build <contentDir> -o <outDir>` from an install. It is a command line, not an importable module (it dispatches when loaded), so it has no package subpath; script against the typed library instead: `@datamoc/mw_games/mwl` |
 | `extract-html` | Splits the resources embedded in an HTML file (scripts, CSS, images) back out into files | `npm run extract:html -- <page.html> -o <outDir>`, or `extractHtml` from `@datamoc/mw_games/tools/extract-html` |
 | `compile-openings` | Compiles opening tables (`eco`, `name`, `pgn` TSV rows) into a position-keyed book JSON a game checks in beside its own code: SAN resolved against the real move generator, every position keeping its continuations, the longest line ending there naming it. Rows are vendored CC0 data (`data/openings/`), never fetched | `node tools/compile-openings.mjs <tsv folder> <book.json>`, or `npx mwg-openings <tsv folder> <book.json>` in a game |
 | `build-tablebases` | Solves pawnless white-extras-against-lone-king endings by retrograde analysis and ships them compiled as Huffman-coded JSON under `data/tablebases` (3-piece: `KQK KRK KBK KNK`; 4-piece like `KBNK KBBK` generate the same way but stay a tool run away, full 4-piece tables are tens of megabytes each). One `threads.spawn` task per ending over capped lanes (4-piece lanes stay narrow: hundreds of megabytes of arrays each); captures convert into the already-solved smaller tables, so 3-piece endings solve first. Golden counts: KQK 0/200896/99448/223944, KRK 0/201700/98644/223944, KBK/KNK all draws, KBBK 0/5628080/21071792/6854560, KBNK 0/11188168/8816020/13550244 (unknown/loss/draw/win) | `node tools/build-tablebases.mjs <outDir> [ending ...] [--jobs=N]`, or `npx mwg-tablebases <outDir> [ending ...]` in a game |