@datamoc/mw_games 0.39.1 → 0.41.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,10 @@ export interface CompileResourcesOptions {
 	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 {
@@ -28,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,57 @@ export const DEFAULT_MIME = {
 	'.woff2': 'font/woff2',
 	'.json': 'application/json',
 	'.txt': 'text/plain',
+	'.mid': 'audio/midi',
+	'.midi': 'audio/midi',
+	'.sf2': 'application/octet-stream',
+	'.sf3': 'application/octet-stream',
 };
 
+const isSoundFontKey = (key) => /\.sf[23]$/i.test(key);
+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 {
@@ -72,6 +121,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` 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
  * @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? }`)
@@ -88,6 +141,8 @@ export async function compileResources({
 	toWebp: convertToWebp = false,
 	webpLossless = true,
 	webpQuality = 90,
+	soundFont = true,
+	soundFontUsage,
 } = {}) {
 	if (!from || !to) throw new Error('compileResources needs both `from` and `to`');
 
@@ -110,6 +165,38 @@ export async function compileResources({
 		}
 	}
 
+	// 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 });
 
@@ -153,6 +240,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')}`;
@@ -173,7 +273,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 */
@@ -202,7 +302,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);
 	}
@@ -211,7 +311,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
@@ -219,6 +323,8 @@ async function runCli() {
 		toWebp,
 		webpLossless,
 		webpQuality,
+		soundFont: !args.includes('--no-soundfont-subset'),
+		soundFontUsage,
 	});
 
 	const kb = (n) => (n / 1024).toFixed(1).padStart(8) + ' KB';
@@ -226,6 +332,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';
 
@@ -20,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;
 }
@@ -38,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.
@@ -73,6 +74,8 @@ export async function emitPage({
 	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');
@@ -86,8 +89,10 @@ export async function emitPage({
 				toWebp,
 				webpLossless,
 				webpQuality,
+				soundFont,
+				soundFontUsage,
 			})
-		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0 };
+		: { groups: [], rawBytes: 0, embeddedBytes: 0, webpConverted: 0, soundFonts: [] };
 
 	const html = await readFile(join(dist, 'index.html'), 'utf8');
 	const classic = toClassicScript(html);
@@ -142,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,
@@ -153,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)) },
@@ -168,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/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;