picopilot 0.2.1 → 0.3.0

package/src/commands/music.ts

@@ -3,9 +3,19 @@ import {isAbsolute, resolve} from 'node:path';
 import {Cli, z} from 'incur';
 
 import {
+	AudioMmlError,
+	clearSfxSlot,
+	formatSlots,
+	mergeSfxRow,
 	MusicError,
+	musicSfxRefs,
+	parseSlotList,
 	patternsToMusic,
 	type Pattern,
+	planScore,
+	readScore,
+	readSfxRows,
+	ScoreError,
 	SFX_INDEX_MAX,
 	setMusicSection,
 } from '../engine/audio/index.js';
@@ -270,11 +280,251 @@ function buildMusicGroup(): Cli.Cli {
 		},
 	});
 
+	music.command('from-score', {
+		description:
+			"Write whole SONGS from a score: up to 4 channels per song, each a picopilot-MML string of ANY length (ADR-0020). picopilot cuts every channel into 32-row SFX aligned across channels, makes a channel that is silent for a whole pattern OFF (null), de-duplicates identical SFX, allocates slots, and writes __sfx__ + __music__ (only the slots it writes or clears and __music__ change). Several songs (e.g. title + in-game) are laid out back to back; the report gives each song's start pattern for `music(n)`. Slots: by default only FREE (note-less) slots, filled from 63 down, never touching other content; --slots <from-to> gives the score a range it OWNS (it overwrites and clears that range; recommended when iterating, so re-runs are idempotent).",
+		args: z.object({
+			score: z
+				.string()
+				.optional()
+				.describe(
+					'The score as JSON: {"songs":[{"name":"title","speed":16,"loop":true,"channels":["<mml ch0>", {"mml":"<mml ch1>","filters":"!dampen"}, null, null]}]}. Per song: speed (ticks/row, default the channels\' shared s<N> or 16), patternRows (1-32, default 32), loop (default true; false = stop at the end), loopFrom (pattern within the song the loop returns to, default 0). One song may be given directly as {"channels":[...]}. Omit and pass --file instead.',
+				),
+		}),
+		options: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to write. Defaults to main.p8 in the current folder.',
+				),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Read the JSON score from this file instead of the `score` argument.',
+				),
+			slots: z
+				.string()
+				.optional()
+				.describe(
+					'A slot range the score OWNS, e.g. "16-63": any slot in it may be overwritten, and the ones the score does not use are cleared. Without it, only free (note-less) slots are used.',
+				),
+		}),
+		output: z.object({
+			cart: z
+				.string()
+				.describe('The absolute path of the cart that was written.'),
+			songs: z
+				.array(
+					z.object({
+						name: z.string(),
+						startPattern: z
+							.number()
+							.describe('Play this song with music(startPattern).'),
+						endPattern: z.number(),
+						patterns: z.number(),
+						speed: z.number(),
+						patternRows: z.number(),
+						loop: z.boolean(),
+						loopStartPattern: z.number().optional(),
+						seconds: z.number().describe('Length of one pass, in seconds.'),
+					}),
+				)
+				.describe('Each song as laid out in __music__.'),
+			patterns: z.number().describe('Total patterns written to __music__.'),
+			slots: z
+				.array(
+					z.object({
+						slot: z.number(),
+						uses: z.array(z.string()),
+						overwrote: z
+							.boolean()
+							.describe('The slot held different, non-empty content before.'),
+					}),
+				)
+				.describe('Every SFX slot the score wrote, and where it plays.'),
+			slotRange: z
+				.string()
+				.describe('The slots used, compactly (e.g. "40-63").'),
+			cleared: z
+				.array(z.number())
+				.describe(
+					'Owned slots (--slots) the score does not use, cleared to empty.',
+				),
+			warnings: z.array(z.string()).describe('Advisory warnings.'),
+		}),
+		examples: [
+			{
+				description:
+					'Two songs (title + in-game) from a file, owning slots 16-63',
+				args: {},
+				options: {file: 'score.json', slots: '16-63'},
+			},
+			{
+				description: 'One short looping song inline',
+				args: {
+					score:
+						'{"speed":16,"channels":["!dampen @0 v[3 2 2 1/0] o2 l8 a d+ f e","!dampen @0 v[2 2 1] o1 l16 d a-"]}',
+				},
+			},
+		],
+		run({args, options, error, ok}) {
+			let text: string;
+			if (options.file !== undefined) {
+				if (args.score !== undefined) {
+					return error({
+						code: 'ambiguous-input',
+						message:
+							'pass EITHER the score argument OR --file, not both (they are two ways to give the same source).',
+						exitCode: 1,
+					});
+				}
+				const filePath = resolvePath(options.file);
+				if (!existsSync(filePath)) {
+					return error({
+						code: 'score-file-not-found',
+						message: `no score file at ${filePath}`,
+						exitCode: 1,
+					});
+				}
+				text = readFileSync(filePath, 'utf8');
+			} else if (args.score !== undefined) {
+				text = args.score;
+			} else {
+				return error({
+					code: 'no-score',
+					message:
+						'no score: pass it as the `score` argument (JSON) or via --file.',
+					exitCode: 1,
+				});
+			}
+
+			let range: {from: number; to: number} | undefined;
+			if (options.slots !== undefined) {
+				const list = parseSlotList(options.slots);
+				const ok =
+					list !== undefined &&
+					list.length > 0 &&
+					list[list.length - 1]! - list[0]! + 1 === list.length;
+				if (!ok) {
+					return error({
+						code: 'audio-score-bad-slot-range',
+						message: `--slots "${options.slots}" is not one contiguous range within 0-${SFX_INDEX_MAX}, e.g. "16-63".`,
+						exitCode: 1,
+					});
+				}
+				range = {from: list![0]!, to: list![list!.length - 1]!};
+			}
+
+			const cartPath = resolvePath(options.cart);
+			const loaded = loadCart(cartPath);
+			if (!loaded.ok) {
+				return error({code: loaded.code, message: loaded.message, exitCode: 1});
+			}
+
+			// Plan FIRST (pure): a bad score never touches the cart.
+			let plan: ReturnType<typeof planScore>;
+			try {
+				let raw: unknown;
+				try {
+					raw = JSON.parse(text);
+				} catch (e) {
+					throw new ScoreError(
+						'audio-score-parse-error',
+						`score is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+					);
+				}
+				plan = planScore(
+					readScore(raw),
+					{
+						sfxRows: readSfxRows(loaded.cart),
+						musicRefs: musicSfxRefs(loaded.cart.getSection('music')),
+					},
+					range !== undefined ? {slots: range} : {},
+				);
+			} catch (e) {
+				if (e instanceof ScoreError || e instanceof AudioMmlError) {
+					return error({
+						code: e.code,
+						message: e.message,
+						exitCode: 1,
+						...(e.code === 'audio-score-no-free-slots'
+							? {
+									cta: {
+										description: 'Give the music a slot range it owns:',
+										commands: [
+											{
+												command:
+													'music from-score --file <score.json> --slots 16-63',
+												description:
+													'The score overwrites and clears that range (and nothing else).',
+											},
+										],
+									},
+								}
+							: {}),
+					});
+				}
+				throw e;
+			}
+
+			for (const s of plan.slots) mergeSfxRow(loaded.cart, s.slot, s.row);
+			for (const slot of plan.cleared) clearSfxSlot(loaded.cart, slot);
+			setMusicSection(loaded.cart, plan.musicSection);
+			writeFileSync(cartPath, loaded.cart.serialize());
+
+			const lua = plan.songs
+				.map((s) => `${s.name}: music(${s.startPattern})`)
+				.join(', ');
+			return ok(
+				{
+					cart: cartPath,
+					songs: plan.songs.map((s) => ({
+						name: s.name,
+						startPattern: s.startPattern,
+						endPattern: s.endPattern,
+						patterns: s.patterns,
+						speed: s.speed,
+						patternRows: s.patternRows,
+						loop: s.loop,
+						...(s.loopStartPattern !== undefined
+							? {loopStartPattern: s.loopStartPattern}
+							: {}),
+						seconds: s.seconds,
+					})),
+					patterns: plan.patterns,
+					slots: plan.slots.map((s) => ({
+						slot: s.slot,
+						uses: s.uses,
+						overwrote: s.overwrote,
+					})),
+					slotRange: formatSlots(plan.slots.map((s) => s.slot)),
+					cleared: plan.cleared,
+					warnings: plan.warnings,
+				},
+				{
+					cta: {
+						description: `Written. Play from Lua with ${lua} (add a channel mask, e.g. music(n,0,7), to leave channel 3 for SFX). Then hear and measure it:`,
+						commands: [
+							{
+								command: `audio render --pattern ${plan.songs[0]!.startPattern} --seconds ${Math.ceil(2 * plan.songs[0]!.seconds + 2)} --analyze`,
+								description:
+									'Record the first song twice over (the loop length needs two passes) and get loudness/brightness/repetition numbers.',
+							},
+						],
+					},
+				},
+			);
+		},
+	});
+
 	return music;
 }
 
 /**
- * Registers the `music` command group (`music from-patterns`) on the root CLI.
+ * Registers the `music` command group (`music from-patterns`, `music
+ * from-score`) on the root CLI.
  *
  * `music` is a shrinko-FREE and PICO-8-FREE command group: it assembles a
  * structural pattern list into `__music__` and merges it through the cart model

package/src/commands/sfx.test.ts

@@ -7,6 +7,9 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import {mmlToSfxRow, SFX_ROW_LENGTH} from '../engine/audio/index.js';
 import {createCli} from '../cli.js';
 
+/** The .p8 header lines. */
+const HEADER = 'pico-8 cartridge // http://www.pico-8.com\nversion 42\n';
+
 /** A minimal valid cart with a lua + gfx section (to prove they stay untouched). */
 function cartText(sfxBody?: string): string {
 	let text =
@@ -347,3 +350,55 @@ describe('picopilot sfx from-mml: dotted-length rounding is reported', () => {
 		expect(out.warnings[0]).toContain('rounded');
 	});
 });
+
+describe('picopilot sfx clear', () => {
+	it('clears the named slots and nothing else', async () => {
+		const a = mmlToSfxRow('s4 c').row;
+		const b = mmlToSfxRow('s5 d').row;
+		const c = mmlToSfxRow('s6 e0 c').row;
+		writeFileSync(
+			cartPath,
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n${b}\n${c}\n`,
+		);
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'clear',
+			'1,5',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.cleared).toEqual([1]);
+		expect(out.alreadyEmpty).toEqual([5]);
+		const text = readFileSync(cartPath, 'utf8');
+		expect(text).toContain(`${a}\n${'0'.repeat(168)}\n${c}\n`);
+	});
+
+	it('clearing the last slots trims them (what PICO-8 writes)', async () => {
+		const a = mmlToSfxRow('s4 c').row;
+		writeFileSync(
+			cartPath,
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n${a}\n`,
+		);
+		await runSfx(['sfx', 'clear', '1-63', '--cart', cartPath, '--json']);
+		expect(readFileSync(cartPath, 'utf8')).toBe(
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n`,
+		);
+	});
+
+	it('refuses a bad slot list', async () => {
+		writeFileSync(cartPath, `${HEADER}__lua__\nprint(1)\n`);
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'clear',
+			'70',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('bad-slot-list');
+	});
+});

package/src/commands/sfx.ts

@@ -4,9 +4,14 @@ import {Cli, z} from 'incur';
 
 import {
 	AudioMmlError,
+	clearSfxSlot,
+	formatSlots,
+	isFreeSfxRow,
 	mergeSfxRow,
 	mmlToSfxRow,
+	parseSlotList,
 	PITCH_MAX,
+	readSfxRows,
 	SFX_MAX_ROWS,
 	SFX_SLOT_COUNT,
 } from '../engine/audio/index.js';
@@ -58,7 +63,7 @@ function buildSfxGroup(): Cli.Cli {
 
 	sfx.command('from-mml', {
 		description:
-			'Transpile picopilot-MML text into one __sfx__ slot (0-63) and merge it into the cart (only that slot changes). picopilot-MML is TRACKER-ROW based: a length is a ROW COUNT (l4 = 4 rows), NOT a musical note value, and there is NO tempo/BPM (PICO-8 measures in ticks/row via `s<N>` speed). Notes carry per-note waveform (@0-7, @8-f = custom SFX-instrument), volume (v0-7), and effect (e0-7) that a score notation cannot express. SFX-level FILTER directives reach DESIGNED sounds (explosion/engine/pad): !dampen[2] (low-pass body), !reverb (echo tail), !noiz (@6 white noise), !buzz, !detune1/!detune2. Out-of-range pitch (below C0 / above D#5), >32 rows, and a bad filter level are refused loudly, never silently clamped.',
+			'Transpile picopilot-MML text into one __sfx__ slot (0-63) and merge it into the cart (only that slot changes). picopilot-MML is TRACKER-ROW based: a length is a ROW COUNT (l4 = 4 rows), NOT a musical note value, and there is NO tempo/BPM (PICO-8 measures in ticks/row via `s<N>` speed). Notes carry per-note waveform (@0-7, @8-f = custom SFX-instrument), volume (v0-7), and effect (e0-7) that a score notation cannot express. A held note (c8) is ONE note: fade in/out and drop land once per held note, not on every row (ADR-0019); shape its volume with an envelope v[3 2 2 1/0] (one digit per row, last value held, after / = release) and delay vibrato with ~N (vibrato from row N). For melodies over 32 rows use `music from-score`. SFX-level FILTER directives reach DESIGNED sounds (explosion/engine/pad): !dampen[2] (low-pass body), !reverb (echo tail), !noiz (@6 white noise), !buzz, !detune1/!detune2. Out-of-range pitch (below C0 / above D#5), >32 rows, and a bad filter level are refused loudly, never silently clamped.',
 		args: z.object({
 			slot: z.coerce
 				.number()
@@ -70,7 +75,7 @@ function buildSfxGroup(): Cli.Cli {
 				.string()
 				.optional()
 				.describe(
-					'The picopilot-MML source (e.g. "s16 @1 v6 c d e f"). Omit and pass --file to read from a file instead. Modal state: @ waveform, v volume, e effect, o octave, l default length (all sticky). Durations are ROWS: c4 = 4 rows (held via tie rows). Loop with {..}; a lone { marks the pattern LEN. SFX filters (per-SFX, place anywhere): !dampen/!dampen2, !reverb, !noiz, !buzz, !detune1/!detune2 (e.g. "!dampen !reverb @6 v7 o3 e c o1 g" = an explosion).',
+					'The picopilot-MML source (e.g. "s16 @1 v6 c d e f"). Omit and pass --file to read from a file instead. Modal state: @ waveform, v volume or v[...] envelope, e effect, ~N delayed vibrato, o octave, l default length (all sticky). Durations are ROWS: c4 = one note held 4 rows. Loop with {..}; a lone { marks the pattern LEN. SFX filters (per-SFX, place anywhere): !dampen/!dampen2, !reverb, !noiz, !buzz, !detune1/!detune2 (e.g. "!dampen !reverb @6 v7 o3 e c o1 g" = an explosion).',
 				),
 		}),
 		options: z.object({
@@ -135,6 +140,11 @@ function buildSfxGroup(): Cli.Cli {
 					'A DESIGNED explosion: DAMPEN body + REVERB tail on @6 noise',
 				args: {slot: 3, mml: 's7 !dampen2 !reverb @6 v7 o3 e c o1 g c'},
 			},
+			{
+				description:
+					'A soft lead note: held 8 rows with a decaying envelope and vibrato from row 4',
+				args: {slot: 6, mml: 's16 !dampen @0 ~4 v[3 3 2 2 2 1/1 0] o2 a8'},
+			},
 			{
 				description: 'Read a longer source from a file',
 				args: {slot: 1},
@@ -199,28 +209,40 @@ function buildSfxGroup(): Cli.Cli {
 								}
 							: e.code === 'audio-mml-sfx-overflow'
 								? {
-										description: `One SFX holds at most ${SFX_MAX_ROWS} rows; split longer melodies:`,
+										description: `One SFX holds at most ${SFX_MAX_ROWS} rows; for longer melodies:`,
 										commands: [
 											{
-												command: 'sfx from-mml <other-slot> "<rest>"',
+												command: 'music from-score --file score.json',
 												description:
-													'Author the remainder as another SFX, then arrange both with `music from-patterns`.',
+													'Write each voice at any length; picopilot splits it into SFX + patterns.',
 											},
 										],
 									}
-								: e.code === 'audio-mml-filter-level-out-of-range'
+								: e.code === 'audio-mml-tie-state-change'
 									? {
-											description: 'The SFX filters + their valid levels:',
+											description:
+												'A tie continues one held note; shape it instead:',
 											commands: [
 												{
-													command:
-														'sfx from-mml <slot> "!dampen[2] !reverb !noiz !buzz !detune1/!detune2 ..."',
+													command: 'sfx from-mml <slot> "v[3 2 2 1] c8"',
 													description:
-														'!dampen has 2 levels (!dampen/!dampen2); !reverb/!noiz/!buzz are on/off; !detune needs 1 or 2.',
+														'A volume envelope: one digit per row, last value held.',
 												},
 											],
 										}
-									: undefined;
+									: e.code === 'audio-mml-filter-level-out-of-range'
+										? {
+												description: 'The SFX filters + their valid levels:',
+												commands: [
+													{
+														command:
+															'sfx from-mml <slot> "!dampen[2] !reverb !noiz !buzz !detune1/!detune2 ..."',
+														description:
+															'!dampen has 2 levels (!dampen/!dampen2); !reverb/!noiz/!buzz are on/off; !detune needs 1 or 2.',
+													},
+												],
+											}
+										: undefined;
 					return error({
 						code: e.code,
 						message: e.message,
@@ -282,6 +304,91 @@ function buildSfxGroup(): Cli.Cli {
 		},
 	});
 
+	sfx.command('clear', {
+		description:
+			'Clear SFX slots back to EMPTY (no notes). Only the named slots change; every other slot and section stays byte-identical. Use it to free slots for `music from-score` or to remove a leftover song.',
+		args: z.object({
+			slots: z
+				.string()
+				.describe(
+					'The slots to clear: one slot ("5"), a range ("16-63"), or a list ("3,5,16-20").',
+				),
+		}),
+		options: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to edit. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		output: z.object({
+			cart: z
+				.string()
+				.describe('The absolute path of the cart that was written.'),
+			cleared: z
+				.array(z.number())
+				.describe('The slots that held notes and are now empty.'),
+			alreadyEmpty: z
+				.array(z.number())
+				.describe(
+					'The named slots that had no notes already (left byte-identical).',
+				),
+		}),
+		examples: [
+			{description: 'Clear slot 11', args: {slots: '11'}},
+			{
+				description: 'Clear a whole music range of a cart',
+				args: {slots: '16-63'},
+				options: {cart: 'game.p8'},
+			},
+		],
+		run({args, options, error, ok}) {
+			const slots = parseSlotList(args.slots);
+			if (slots === undefined) {
+				return error({
+					code: 'bad-slot-list',
+					message: `"${args.slots}" is not a slot list within 0-${SFX_SLOT_COUNT - 1}: use "5", "16-63" or "3,5,16-20".`,
+					exitCode: 1,
+				});
+			}
+			const cartPath = resolvePath(options.cart);
+			const loaded = loadCart(cartPath);
+			if (!loaded.ok) {
+				return error({code: loaded.code, message: loaded.message, exitCode: 1});
+			}
+			const before = readSfxRows(loaded.cart);
+			const cleared: number[] = [];
+			const alreadyEmpty: number[] = [];
+			for (const slot of slots) {
+				// A note-less slot is already empty: leave its bytes (header) alone.
+				if (isFreeSfxRow(before[slot])) {
+					alreadyEmpty.push(slot);
+					continue;
+				}
+				cleared.push(slot);
+				clearSfxSlot(loaded.cart, slot);
+			}
+			writeFileSync(cartPath, loaded.cart.serialize());
+			return ok(
+				{cart: cartPath, cleared, alreadyEmpty},
+				cleared.length > 0
+					? {
+							cta: {
+								description: `Cleared SFX ${formatSlots(cleared)}. If __music__ still references them, those channels are now silent:`,
+								commands: [
+									{
+										command: 'verify',
+										description: 'Static gate: the cart still parses.',
+									},
+								],
+							},
+						}
+					: undefined,
+			);
+		},
+	});
+
 	return sfx;
 }