@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/test.js

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { nodeTest } from "../suite/node-run.js";
+import { ui } from "../ui.js";
+import { designDoc } from "../gdd/doc.js";
+import { namedTests, readBack, testsInCode } from "../gdd/design.js";
+import { goalCounts, readGoalsRecord, runGoals } from "../goals/run.js";
+import { GOALS_RECORD } from "../goals/goals.js";
+export const TESTS_RECORD = join('.funtools', 'tests.json');
+export const COULD_NOT_START = new Set([126, 127]);
+export function npmTest(dir, json = false, silent = false) {
+    return new Promise((done) => {
+        const env = { ...process.env };
+        delete env.NODE_TEST_CONTEXT;
+        const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['test'], { cwd: dir, env, stdio: silent ? 'ignore' : ['ignore', json ? 'pipe' : 'inherit', 'inherit'] });
+        child.stdout?.pipe(process.stderr);
+        child.on('error', () => done(127));
+        child.on('close', (code) => done(code ?? 1));
+    });
+}
+const RUNNERS = { npm: npmTest, node: nodeTest };
+export async function test(opts, io = console, run = {}) {
+    const runners = { ...RUNNERS, ...run };
+    const dir = resolve(opts.target ?? '.');
+    const u = ui(io, 'test');
+    let script = '';
+    try {
+        script = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')).scripts?.test ?? '';
+    }
+    catch { }
+    if (!opts.node && (!script || /no test specified/.test(script))) {
+        u.error('no test script in package.json', 'add "test": "node --test test/*.test.ts" and a test per rule (skill funpixel-game-logic), or run the files with --node');
+        return EXIT.error;
+    }
+    const fp = (await fingerprint(dir)).fingerprint;
+    let command = 'npm test';
+    let exit = opts.node ? 127 : await runners.npm(dir, opts.json);
+    if (opts.node || COULD_NOT_START.has(exit)) {
+        if (!opts.node && !opts.json)
+            u.item('note', `npm test could not start (exit ${exit}: a tool it calls is missing from PATH, or the host refused it)`, 'running the test files with this Node instead (funtools test --node)');
+        const r = await runners.node(dir, opts.json);
+        if (r.why) {
+            u.error(`the test files could not run with Node: ${r.why}`, opts.node ? 'add test/*.test.ts (skill funpixel-game-logic)' : 'fix the test script so npm test starts');
+            return EXIT.error;
+        }
+        command = `node --test ${r.files.join(' ')}`;
+        exit = r.exit;
+    }
+    const named = namedTests(designDoc(dir)?.text ?? '');
+    const back = named.length ? readBack(named, testsInCode(dir)) : null;
+    let goals = null;
+    if (opts.goals)
+        goals = await runGoals(dir, { bot: run.goalBot });
+    else {
+        const last = readGoalsRecord(dir);
+        if (last && last.fingerprint === fp)
+            goals = last;
+    }
+    const record = {
+        tool: 'funtools', command, exit, fingerprint: fp, at: new Date().toISOString(),
+        ...(back ? { gdd_tests: { named: named.length, in_code: back.inCode.length, not_yet: back.notYet } } : {}),
+        ...(goals && goals.goals.length ? { goals: { ...goalCounts(goals), record: GOALS_RECORD } } : {}),
+    };
+    await mkdir(dirname(join(dir, TESTS_RECORD)), { recursive: true });
+    await writeFile(join(dir, TESTS_RECORD), JSON.stringify(record, null, 2) + '\n');
+    if (opts.json)
+        io.log(JSON.stringify(record, null, 2));
+    else {
+        if (back && back.notYet.length)
+            u.item('note', `${back.notYet.length} of ${named.length} behaviour tests the GDD names are not in the test files yet`, back.notYet.slice(0, 5).join(' · ') + (back.notYet.length > 5 ? ' …' : ''));
+        else if (back)
+            u.item('pass', `all ${named.length} behaviour tests the GDD names are in the test files`);
+        if (goals)
+            goalLines(u, goals, !!opts.goals);
+        else if (named.length)
+            u.item('note', 'goal playtests not run on these files', '`funtools test --goals`: a bounded player per goal the GDD states (met / not met / blocked / not observed)');
+    }
+    if (!opts.json)
+        u.summary(exit === 0 ? 'pass' : 'fail', exit === 0 ? 'the rules suite passed on these files' : `${command.split(' ')[0] === 'node' ? 'node --test' : 'npm test'} exited ${exit}`);
+    return exit === 0 ? EXIT.pass : EXIT.fail;
+}
+const GOAL_STATE = { met: 'pass', 'not met': 'fail', blocked: 'fail', 'not observed': 'note' };
+function goalLines(u, rec, ran) {
+    if (rec.written.length)
+        u.item('note', `${rec.written.length} goal file(s) written for the GDD's goal sentences`, `${rec.written.join(', ')}: write observe (how met is seen in __FPX_STATE__) and a route`);
+    if (!rec.goals.length) {
+        if (ran)
+            u.item('note', 'no behaviour test states a player goal', 'a goal names what a player does or gets to: "a new player reaches the dock within 3 minutes"');
+        return;
+    }
+    const c = goalCounts(rec);
+    u.item(c.blocked || c['not met'] ? 'warn' : c.met ? 'pass' : 'note', `goal playtests: ${c.met} met · ${c['not met']} not met · ${c.blocked} blocked · ${c['not observed']} not observed${ran ? '' : ' (last run, these files)'}`, GOALS_RECORD);
+    for (const g of rec.goals) {
+        if (g.problems?.length) {
+            u.item('warn', `${g.file}: ${g.problems[0]}`);
+            continue;
+        }
+        const by = [g.bot ? `scripted: ${g.bot.verdict} (${g.bot.why})` : 'scripted: no route', g.agent ? `seat: ${g.agent.verdict} (${g.agent.why})` : `seat: not filed (.funtools/goals/${g.id}/seat.md)`];
+        u.item(GOAL_STATE[g.verdict], `"${g.sentence}": ${g.verdict}`, by.join(' · '));
+    }
+}

package/dist/commands/trailer.js

@@ -0,0 +1,255 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { basename, extname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { filmWithRetry, openGame } from "./reel.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { launch } from "../verify/browser.js";
+import { ffmpegBin, frameName } from "../reel/encode.js";
+import { beatGrid, decode, DEFAULT_GRID } from "../trailer/beats.js";
+import { planCut } from "../trailer/cut.js";
+import { FORMATS, LABEL, renderCards } from "../trailer/cards.js";
+import { assembleArgs, FPS, probe, run, takeArgs } from "../trailer/assemble.js";
+import { findMaterial } from "../trailer/find.js";
+import { loopedBed, placeCues, skipReason } from "../trailer/cues.js";
+import { MIX, mixdown } from "../trailer/mix.js";
+import { measure } from "../sound/loudness.js";
+import { ui } from "../ui.js";
+export const TRAILER_LIMITS = { seconds: [10, 60], fps: [8, 30] };
+const takeSeconds = (seconds) => Math.min(75, Math.round(seconds * 1.25) + 4);
+const MAX_SOUND_FILES = 64;
+const MAX_SOUND_BYTES = 20 * 1024 * 1024;
+async function fetchSounds(cues, dir) {
+    const urls = [...new Set(cues.filter((c) => c.src && (skipReason(c) === null || c.loop)).map((c) => c.src))].slice(0, MAX_SOUND_FILES);
+    const got = new Map();
+    if (!urls.length)
+        return got;
+    await mkdir(dir, { recursive: true });
+    for (const url of urls) {
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+            if (!r.ok || /text\/html/.test(r.headers.get('content-type') ?? ''))
+                continue;
+            const bytes = Buffer.from(await r.arrayBuffer());
+            if (!bytes.length || bytes.length > MAX_SOUND_BYTES)
+                continue;
+            const name = basename(new URL(url).pathname) || 'sound';
+            const file = join(dir, `${createHash('sha1').update(url).digest('hex').slice(0, 8)}-${name.replace(/[^\w.-]/g, '_')}${extname(name) ? '' : '.bin'}`);
+            await writeFile(file, bytes);
+            got.set(url, file);
+        }
+        catch { }
+    }
+    return got;
+}
+const fileOf = (url) => { try {
+    return decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+}
+catch {
+    return url;
+} };
+async function clip(file, role) {
+    if (!file)
+        return undefined;
+    const p = resolve(file);
+    if (!existsSync(p))
+        return `no ${role} clip at ${p}`;
+    const info = probe(p);
+    if (!info || !info.width || info.seconds <= 0)
+        return `${role} clip ${p} is not a video ffprobe can read`;
+    return { file: p, seconds: info.seconds };
+}
+export async function trailer(opts, io = console) {
+    const u = ui(io, 'trailer');
+    const bin = ffmpegBin();
+    if (!bin) {
+        u.error('trailer needs ffmpeg on PATH', 'install ffmpeg (brew install ffmpeg · apt install ffmpeg · winget install ffmpeg)');
+        return EXIT.error;
+    }
+    const intro = await clip(opts.intro, 'intro');
+    const outro = await clip(opts.outro, 'outro');
+    for (const c of [intro, outro])
+        if (typeof c === 'string') {
+            u.error(c);
+            return EXIT.error;
+        }
+    const target = opts.target ?? '.';
+    const game = await openGame(target, opts.viewport);
+    if (!game) {
+        u.error(`no dist/index.html in ${resolve(target)}`, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const work = game.dir ? join(game.dir, '.funtools', 'trailer') : resolve('.funtools', 'trailer');
+    const outDir = resolve(opts.out ?? work);
+    const framesDir = join(work, 'frames');
+    await rm(framesDir, { recursive: true, force: true });
+    await mkdir(framesDir, { recursive: true });
+    await mkdir(outDir, { recursive: true });
+    let filmed;
+    let sounds = new Map();
+    try {
+        filmed = await filmWithRetry(game.url, hookMapOf(game.manifest), game.checkVerbs, { seconds: takeSeconds(opts.seconds), fps: opts.fps, cues: true }, game.viewport, game.orientation, framesDir);
+        sounds = await fetchSounds(filmed.cues, join(work, 'sounds'));
+    }
+    finally {
+        await game.served?.close();
+    }
+    const take = join(work, 'take.mp4');
+    const encoded = run(bin, takeArgs(framesDir, opts.fps, take));
+    if (!encoded.ok) {
+        u.error(`ffmpeg could not encode the take: ${encoded.error}`, `the frames are in ${framesDir}`);
+        return EXIT.error;
+    }
+    const found = game.dir ? findMaterial(game.dir, game.manifest) : { title: new URL(game.url).hostname };
+    const played = loopedBed(filmed.cues);
+    const playedBed = played ? sounds.get(played) : undefined;
+    const music = opts.noMusic ? undefined : opts.music ? resolve(opts.music) : (playedBed ?? found.music);
+    const musicFrom = !music ? null : opts.music ? 'flag' : playedBed ? `played by the game (${fileOf(played)})` : 'found in its assets';
+    if (music && !existsSync(music)) {
+        u.error(`no music at ${music}`);
+        return EXIT.error;
+    }
+    let grid = DEFAULT_GRID;
+    if (music) {
+        const samples = decode(bin, music);
+        if (!samples) {
+            u.error(`ffmpeg could not read the music ${music}`);
+            return EXIT.error;
+        }
+        grid = beatGrid(samples);
+    }
+    const cut = planCut({
+        grid,
+        footage: filmed.frames / opts.fps,
+        moments: filmed.marks.map((m) => ({ t: m.frame / opts.fps, name: m.name, weight: m.weight })),
+        seconds: opts.seconds,
+        ...(intro ? { intro: intro } : {}),
+        ...(outro ? { outro: outro } : {}),
+    });
+    const placement = opts.noSfx ? { used: [], skipped: [], outside: 0, offFilm: 0 } : placeCues(filmed.cues, filmed.frameTimes, opts.fps, cut);
+    for (const c of placement.used.filter((c) => !sounds.has(c.src))) {
+        const k = placement.skipped.find((s) => s.name === c.name && s.reason === 'no file');
+        if (k)
+            k.count++;
+        else
+            placement.skipped.push({ name: c.name, kind: 'buffer', reason: 'no file', count: 1 });
+    }
+    const used = placement.used.filter((c) => sounds.has(c.src));
+    const top = Math.max(0, ...used.map((c) => c.gain));
+    const rel = (g) => Math.round((top > 0 ? g / top : 1) * 1000) / 1000;
+    const cues = used.map((c) => ({ file: sounds.get(c.src), at: c.at, gain: rel(c.gain), rate: c.rate, offset: c.offset, length: c.length }));
+    let audio;
+    let level = { lufs: null, true_peak: null };
+    if (music || cues.length) {
+        const mixed = join(work, 'sound.wav');
+        const r = mixdown(bin, { ...(music ? { music: { file: music, offset: grid.offset } } : {}), cues, total: Math.round(cut.total * FPS) / FPS }, join(work, 'sound-pre.wav'), mixed);
+        if (r.ok)
+            audio = mixed;
+        else if (r.error !== 'the mix is silent') {
+            u.error(`ffmpeg could not mix the sound: ${r.error}`);
+            return EXIT.error;
+        }
+    }
+    const art = {
+        title: opts.title ?? found.title,
+        keyArt: opts.keyArt ? resolve(opts.keyArt) : found.keyArt,
+        logo: opts.logo ? resolve(opts.logo) : found.logo,
+        backdrop: join(framesDir, frameName(Math.floor(filmed.frames / 2))),
+        cta: opts.cta ?? 'Play free',
+    };
+    const exports = [];
+    let browser;
+    try {
+        browser = (await launch(false)).browser;
+        for (const name of opts.formats) {
+            const fmt = FORMATS[name];
+            const cards = await renderCards(browser, art, fmt, work);
+            const file = join(outDir, `trailer-${fmt.name}.mp4`);
+            const r = run(bin, assembleArgs(cut, fmt, { take, cards, ...(audio ? { audio } : {}) }, file, process.env.FUNTOOLS_TRAILER_PRESET || 'medium'));
+            if (!r.ok) {
+                u.error(`ffmpeg could not cut the ${name} trailer: ${r.error}`);
+                return EXIT.error;
+            }
+            const info = probe(file);
+            exports.push({ format: name, file, width: info?.width ?? fmt.width, height: info?.height ?? fmt.height, seconds: info?.seconds ?? cut.total, audio: info?.audio ?? !!audio, bytes: (await stat(file)).size });
+        }
+    }
+    finally {
+        await browser?.close().catch(() => { });
+    }
+    if (audio && exports[0]) {
+        const m = measure(exports[0].file);
+        level = { lufs: m.lufs, true_peak: m.peak };
+    }
+    await rm(framesDir, { recursive: true, force: true });
+    await rm(take, { force: true });
+    for (const f of ['sound.wav', 'sound-pre.wav', 'sounds'])
+        await rm(join(work, f), { recursive: true, force: true });
+    for (const f of await readdir(work).catch(() => []))
+        if (/^(title|end|label)-/.test(f))
+            await rm(join(work, f), { force: true });
+    const generated = cut.segments.filter((s) => s.source === 'generated').length;
+    const shots = cut.segments.filter((s) => s.source === 'gameplay');
+    const result = {
+        title: art.title,
+        exports,
+        seconds: cut.total,
+        music: music ? (playedBed ? basename(fileOf(played)) : basename(music)) : null,
+        music_from: musicFrom,
+        bpm: grid.bpm, beat_detected: grid.detected,
+        key_art: art.keyArt ? basename(art.keyArt) : null,
+        driven: filmed.tour.driven,
+        moments: filmed.marks.length,
+        segments: cut.segments.map((s) => ({ ...s, ...(s.file ? { file: basename(s.file) } : {}), ...(s.source === 'generated' ? { label: LABEL } : {}) })),
+        gameplay: { real: true, shots: shots.length, seconds: Math.round(shots.reduce((a, s) => a + s.duration, 0) * 1000) / 1000 },
+        generated_clips: generated,
+        sound: {
+            mix: { music_db: MIX.musicDb, sfx_db: MIX.sfxDb, duck_db: MIX.duckDb, fade_out_s: MIX.fadeOut, target_lufs: MIX.lufs, ceiling_dbtp: MIX.truePeak },
+            lufs: level.lufs, true_peak: level.true_peak,
+            sfx: opts.noSfx ? 'off (--no-sfx)' : "the game's own",
+            logged: filmed.cues.length,
+            cues: used.map((c) => ({ at: c.at, name: c.name, source: fileOf(c.src), take_at: c.take, gain: rel(c.gain), rate: c.rate, seconds: c.length, shot: c.segment })),
+            skipped: placement.skipped,
+            outside_cut: placement.outside,
+            off_film: placement.offFilm,
+        },
+    };
+    await writeFile(join(outDir, 'trailer.json'), JSON.stringify(result, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`trailer · ${game.dir ?? target}`);
+    u.item(filmed.tour.driven === 'passive' ? 'warn' : 'pass', filmed.tour.driven === 'passive'
+        ? 'passive: the game declares no __FPX_VERBS__ or __FPX_KEYS__, so the shots show it idle (funtools doctor --add-hooks)'
+        : `real play, driven by its ${filmed.tour.driven}: ${shots.length} shots, ${result.gameplay.seconds}s`);
+    u.item(filmed.marks.length ? 'pass' : 'note', filmed.marks.length
+        ? `${filmed.marks.length} marked payoff(s); shots placed on the heaviest`
+        : 'no __FPX_MOMENT__ marks: shots are spread evenly (mark payoffs with markMoment from @funpixel/sdk)');
+    if (!music)
+        u.item('note', opts.noMusic ? 'no music (--no-music)' : 'no music found: silent, cut at 120 BPM', 'pass --music <file>, or keep the bed in public/assets/music/');
+    else
+        u.item(grid.detected ? 'pass' : 'warn', grid.detected ? `cut on the beat of ${result.music} (${grid.bpm} BPM, ${musicFrom})` : `no clear beat in ${result.music}: cut at 120 BPM`);
+    if (opts.noSfx)
+        u.item('note', 'no sound effects (--no-sfx)');
+    else if (used.length)
+        u.item('pass', `${used.length} of the game's own sounds, on the shots they played in (${[...new Set(used.map((c) => c.name))].slice(0, 5).join(', ')})`);
+    else
+        u.item('note', filmed.cues.length ? 'no sound the game played landed in a kept shot' : 'the game played no sound while it was filmed', 'is its audio unlocked by the first input?');
+    const synth = placement.skipped.filter((s) => s.reason === 'synth' || s.reason === 'made in the page').reduce((a, s) => a + s.count, 0);
+    if (synth)
+        u.item('note', `${synth} synthesised sound(s) left out: no file to play back (listed in trailer.json)`);
+    if (level.lufs !== null)
+        u.item(level.true_peak !== null && level.true_peak > MIX.truePeak + 0.5 ? 'warn' : 'pass', `sound ${level.lufs} LUFS, true peak ${level.true_peak} dBTP (target ${MIX.lufs} / ${MIX.truePeak})`);
+    if (!art.keyArt)
+        u.item('note', 'no key art found: the cards sit on a blurred frame of play', 'pass --key-art <file>, or save design/key-art.png');
+    if (generated)
+        u.item('note', `${generated} generated clip(s), intro/outro only, each labelled "${LABEL}"`);
+    if (filmed.distinct <= 1)
+        u.item('warn', 'every frame of the take is the same picture', 'is the game stuck on a loading or title screen?');
+    for (const e of exports)
+        u.line(`${e.file}  ${e.width}x${e.height} · ${e.seconds.toFixed(1)}s · ${(e.bytes / 1_048_576).toFixed(2)} MB`);
+    u.summary(filmed.distinct <= 1 ? 'warn' : 'pass', `${exports.length} trailer(s), ${cut.total.toFixed(1)}s each`);
+    return EXIT.pass;
+}