@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/unity-player.js

@@ -0,0 +1,672 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { loadavg, cpus } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { execFile } from 'node:child_process';
+import { listProcs, machineDir, ownerPid, sessionOf, unityRuns } from "../machine/procs.js";
+import { readPlist } from "../simulator/screen.js";
+import { realSimctl } from "../simulator/simctl.js";
+import { isUnityProject } from "../unity/run.js";
+import { BUDGETS, judge, mergeBudget, tierFor, TIERS } from "../unity/probe/budgets.js";
+import { connect as realConnect, freePort } from "../unity/probe/client.js";
+import { addTo, installed, kitPackage, reference, removeFrom, PACKAGE } from "../unity/probe/install.js";
+import { buildPlayer, execText, freshness, launchArgs, launchMac, launchSim, stopMac, stopSim } from "../unity/probe/player.js";
+import { parseReport, withoutRows } from "../unity/probe/report.js";
+import { parseScript, parseWords, runSteps } from "../unity/probe/script.js";
+import { ui } from "../ui.js";
+import { realRunDeps } from "./unity.js";
+export const EXIT = { pass: 0, fail: 1, not_observed: 2, error: 3 };
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function realPlayerDeps(io, run, env = process.env) {
+    const log = (l) => io.error(`funtools unity: ${l}`);
+    return {
+        connect: realConnect,
+        launch: { procs: listProcs, plist: readPlist, exec: execText, sleep: realSleep, kill: (pid, sig) => process.kill(pid, sig), now: Date.now, log },
+        lease: async () => {
+            const pid = ownerPid(await listProcs(), env);
+            return { root: join(machineDir(env), 'sim-leases'), simctl: realSimctl, procs: listProcs, now: Date.now, ownerPid: pid, session: sessionOf(env, pid), cwd: process.cwd(), log };
+        },
+        run, freePort, now: Date.now, sleep: realSleep, load: () => loadavg()[0], cpuCount: cpus().length, env, cwd: process.cwd(),
+        ffmpeg: (args) => new Promise((ok) => execFile('ffmpeg', args, { timeout: 600_000 }, (err) => ok(!err))),
+    };
+}
+const stamp = (ms) => new Date(ms).toISOString().replace(/[-:]/g, '').replace(/\..*$/, '').replace('T', '-');
+const r1 = (v) => Math.round(v * 10) / 10;
+function targetOf(o) {
+    const t = o.target ?? 'mac';
+    return t === 'mac' || t === 'sim' ? t : { error: `--target ${t}: mac or sim (a device comes later)` };
+}
+const sessionFile = (project) => join(project, '.funtools', 'unity-play.json');
+async function readSession(project) {
+    try {
+        return JSON.parse(await readFile(sessionFile(project), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function trackedChanges(project, exec) {
+    try {
+        const out = await exec('git', ['-C', project, 'status', '--porcelain', '--untracked-files=no'], undefined, 30_000);
+        return out.split('\n').filter((l) => l.length > 3).map((l) => l.slice(3).trim());
+    }
+    catch {
+        return [];
+    }
+}
+export function dirtiedNote(files) {
+    if (!files.length)
+        return null;
+    return `the build changed ${files.length} tracked file(s) that were clean before it: ${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''} (left as they are; a pre-build step that regenerates a checked-in file does this every build: make it deterministic, or ignore the file)`;
+}
+export async function unityOutDir(project) {
+    const dir = join(project, '.funtools', 'unity');
+    await mkdir(dir, { recursive: true });
+    const ignore = join(dir, '.gitignore');
+    if (!existsSync(ignore))
+        await writeFile(ignore, '# Written by funtools: reports, frames, shots and captures, never committed.\n*\n');
+    return dir;
+}
+async function openPlayer(project, target, o, d, log, variant = 'development') {
+    await unityOutDir(project);
+    if (o.port) {
+        const bridge = await d.connect(o.port, { waitMs: 10_000 });
+        return { running: null, bridge, stop: async () => { bridge.close(); return 'left running (attached with --port)'; } };
+    }
+    let manifest = '';
+    try {
+        manifest = await readFile(join(project, 'Packages', 'manifest.json'), 'utf8');
+    }
+    catch { }
+    if (!o.player && !installed(manifest))
+        return { error: `${PACKAGE} is not in ${project}/Packages/manifest.json — add it with: funtools unity probe install --project ${project}`, code: EXIT.error };
+    let app = o.player ? resolve(d.cwd, o.player) : null;
+    let built;
+    let dirtied = [];
+    if (app && !existsSync(app))
+        return { error: `no app at ${app}`, code: EXIT.error };
+    if (!app) {
+        const f = await freshness(project, target, variant);
+        if (f.fresh && !o.rebuild && f.app) {
+            app = f.app;
+            log(`reusing ${app} (${f.why})`);
+        }
+        else if (o.noBuild)
+            return { error: `no current probe build (${f.why}); drop --no-build to build one through the queue`, code: EXIT.error };
+        else {
+            log(`building: ${o.rebuild ? '--rebuild' : f.why}`);
+            const clean = await trackedChanges(project, d.launch.exec);
+            const b = await buildPlayer(project, target, { queue: o.queue, run: d.run, variant, keepTarget: o.keepTarget, log });
+            dirtied = (await trackedChanges(project, d.launch.exec)).filter((f) => !clean.includes(f));
+            const note = dirtiedNote(dirtied);
+            if (note)
+                log(`note: ${note}`);
+            if (!b.ok || !b.app)
+                return { error: b.message, code: EXIT.error };
+            app = b.app;
+            built = b.message;
+        }
+    }
+    const port = await d.freePort();
+    const tier = o.tier ?? tierFor(target, o.device);
+    const upright = tier === 'tablet' ? { w: 820, h: 1180 } : { w: 390, h: 844 };
+    const landscape = target === 'mac' && tier !== 'mac' && (await projectOrientation(project)) === 'landscape';
+    const size = target === 'mac' ? (tier === 'mac' ? { w: 1280, h: 800 } : landscape ? { w: upright.h, h: upright.w } : upright) : undefined;
+    const logFile = join(project, 'Builds', 'FunpixelProbe', `player-${stamp(d.now())}.log`);
+    const own = await gameArgs(o, d.cwd);
+    if ('error' in own)
+        return { error: own.error, code: EXIT.error };
+    if (own.args.length)
+        log(`the game's own arguments: ${own.args.join(' ')}`);
+    const args = [...launchArgs({ port, probe: false, mute: !o.sound, size, log: target === 'mac' ? logFile : undefined }), ...own.args];
+    let running;
+    if (target === 'mac') {
+        running = await launchMac(app, args, { visible: !!o.visible, port }, d.launch);
+        log(`launched ${app} (pid ${running.pid}, ${o.visible ? 'visible' : 'hidden'}, port ${port}, log ${logFile})`);
+    }
+    else {
+        running = await launchSim(app, args, { port, udid: o.udid, device: o.device, keep: o.keepSim, gameArgs: own.args }, d.launch, await d.lease());
+        log(`launched ${running.bundle} on ${running.udid} (port ${port})`);
+    }
+    let gone = false;
+    const watch = target === 'mac' ? setInterval(() => { void d.launch.procs().then((ps) => { gone = !ps.some((p) => p.pid === running.pid); }).catch(() => { }); }, 2000) : null;
+    let bridge;
+    try {
+        bridge = await d.connect(port, { waitMs: 90_000, alive: () => !gone });
+    }
+    catch (e) {
+        if (watch)
+            clearInterval(watch);
+        const how = target === 'mac' ? await stopMac(running, null, d.launch) : await stopSim(running, null, d.launch, await d.lease());
+        return { error: `${e.message} (player ${how}${running.log ? `; log ${running.log}` : ''})`, code: EXIT.error };
+    }
+    if (watch)
+        clearInterval(watch);
+    const stop = async () => {
+        const quit = () => bridge.send({ cmd: 'quit' }, 5_000);
+        const how = target === 'mac' ? await stopMac(running, quit, d.launch) : await stopSim(running, quit, d.launch, await d.lease());
+        bridge.close();
+        return how;
+    };
+    return { running, bridge, stop, built, dirtied };
+}
+export async function projectOrientation(project) {
+    let text;
+    try {
+        text = await readFile(join(project, 'ProjectSettings', 'ProjectSettings.asset'), 'utf8');
+    }
+    catch {
+        return 'any';
+    }
+    const num = (k) => { const m = new RegExp(`^\\s*${k}:\\s*(\\d+)`, 'm').exec(text); return m ? Number(m[1]) : null; };
+    const def = num('defaultScreenOrientation');
+    if (def === 0 || def === 1)
+        return 'portrait';
+    if (def === 2 || def === 3)
+        return 'landscape';
+    if (def === 4) {
+        const portrait = num('allowedAutorotateToPortrait') === 1 || num('allowedAutorotateToPortraitUpsideDown') === 1;
+        const land = num('allowedAutorotateToLandscapeRight') === 1 || num('allowedAutorotateToLandscapeLeft') === 1;
+        if (land && !portrait)
+            return 'landscape';
+        if (portrait && !land)
+            return 'portrait';
+    }
+    return 'any';
+}
+export async function gameArgs(o, cwd) {
+    const args = [...(o.playerArgs ?? [])];
+    if (o.playerArgsFile) {
+        let text;
+        try {
+            text = await readFile(resolve(cwd, o.playerArgsFile), 'utf8');
+        }
+        catch (e) {
+            return { error: `--player-args: ${e.message}` };
+        }
+        for (const line of text.split(/\r?\n/)) {
+            const t = line.trim();
+            if (t && !t.startsWith('#'))
+                args.push(t);
+        }
+    }
+    return { args };
+}
+async function loadBudget(spec, tier, cwd) {
+    if (!spec)
+        return { budget: BUDGETS[tier], chosen: new Set() };
+    let raw;
+    try {
+        raw = JSON.parse(spec.trim().startsWith('{') ? spec : await readFile(resolve(cwd, spec), 'utf8'));
+    }
+    catch (e) {
+        return { error: `--budget: ${e.message}` };
+    }
+    const all = raw;
+    const own = TIERS.some((t) => t in all) ? all[tier] : all;
+    const merged = mergeBudget(BUDGETS[tier], own);
+    if ('error' in merged)
+        return merged;
+    return { budget: merged, chosen: new Set(own && typeof own === 'object' ? Object.keys(own) : []) };
+}
+export async function probeRun(o, io, d) {
+    const u = ui(io, 'unity probe');
+    const project = resolve(d.cwd, o.project ?? '.');
+    if (!o.port && !isUnityProject(project)) {
+        u.error(`${project} is not a Unity project (no ProjectSettings/ProjectVersion.txt)`, 'run it in the project, or pass --project <dir>');
+        return EXIT.error;
+    }
+    const target = targetOf(o);
+    if (typeof target !== 'string') {
+        u.error(target.error);
+        return EXIT.error;
+    }
+    if (o.tier && !TIERS.includes(o.tier)) {
+        u.error(`--tier ${o.tier}`, 'phone, tablet or mac');
+        return EXIT.error;
+    }
+    const tier = o.tier ?? tierFor(target, o.device);
+    const budget = await loadBudget(o.budget, tier, d.cwd);
+    if ('error' in budget) {
+        u.error(budget.error);
+        return EXIT.error;
+    }
+    let script = { steps: [] };
+    if (o.path) {
+        let text;
+        try {
+            text = await readFile(resolve(d.cwd, o.path), 'utf8');
+        }
+        catch (e) {
+            u.error(`--path ${o.path}: ${e.message}`);
+            return EXIT.error;
+        }
+        const p = parseScript(text);
+        if (!p.ok) {
+            u.error(`--path ${o.path}: ${p.error}`);
+            return EXIT.error;
+        }
+        script = p.script;
+    }
+    const seconds = o.seconds ?? script.seconds ?? (script.steps.length ? 0 : 10);
+    const log = (l) => io.error(`funtools unity probe: ${l}`);
+    const procs0 = await d.launch.procs().catch(() => []);
+    const host = { load_start: r1(d.load()), load_peak: r1(d.load()), cpus: d.cpuCount, unity_runs: unityRuns(procs0).length };
+    let opened;
+    try {
+        opened = await openPlayer(project, target, o, d, log);
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+    if ('error' in opened) {
+        u.error(opened.error);
+        return opened.code;
+    }
+    const { bridge } = opened;
+    const shots = join(project, '.funtools', 'unity', 'shots');
+    let steps = [];
+    let report = null;
+    let failure = null;
+    const sampler = setInterval(() => { host.load_peak = Math.max(host.load_peak, r1(d.load())); }, 2000);
+    try {
+        const start = await bridge.send({ cmd: 'probe.start', warmup: 30 });
+        if (!start.ok)
+            throw new Error(`probe.start: ${start.error}`);
+        const t0 = d.now();
+        steps = await runSteps(script.steps, bridge, { space: o.points ? 'pt' : script.space, device: o.mouse ? 'mouse' : script.device }, {
+            log: (l) => log(l), now: d.now,
+            shot: async (name, png) => { await mkdir(shots, { recursive: true }); const f = join(shots, `${name.replace(/[^\w.-]+/g, '-')}.png`); await writeFile(f, png); return f; },
+        });
+        const left = seconds * 1000 - (d.now() - t0);
+        if (left > 0)
+            await bridge.send({ cmd: 'wait', ms: left }, left + 30_000);
+        const rep = await bridge.send({ cmd: 'probe.report', rows: true }, 120_000);
+        const parsed = parseReport(rep);
+        if (!parsed.ok)
+            throw new Error(rep.ok ? `the report: ${parsed.error}` : `probe.report: ${rep.error}`);
+        report = parsed.report;
+    }
+    catch (e) {
+        failure = e.message;
+    }
+    finally {
+        clearInterval(sampler);
+        const how = await opened.stop().catch((e) => `not stopped: ${e.message}`);
+        log(`player ${how}`);
+    }
+    if (!report) {
+        u.error(failure ?? 'no report');
+        return EXIT.error;
+    }
+    host.unity_runs = Math.max(host.unity_runs, unityRuns(await d.launch.procs().catch(() => [])).length);
+    const j = judge(report, tier, budget.budget, o.strict ? 'all' : budget.chosen);
+    const dirtied = dirtiedNote(opened.dirtied ?? []);
+    if (dirtied)
+        j.notes.push(dirtied);
+    if (host.load_peak > host.cpus)
+        j.notes.push(`the Mac was loaded (load ${host.load_peak} on ${host.cpus} cores${host.unity_runs ? `, ${host.unity_runs} Unity run(s) beside it` : ''}): frame times carry host noise`);
+    const stepFailed = steps.find((s) => !s.ok);
+    const verdict = stepFailed ? 'fail' : j.verdict;
+    const dir = join(project, '.funtools', 'unity');
+    await mkdir(dir, { recursive: true });
+    const at = stamp(d.now());
+    const frames = join(dir, `probe-${at}.frames.json`);
+    await writeFile(frames, JSON.stringify(report) + '\n');
+    const outcome = {
+        schema: 'funtools.unity-probe/1', verdict, target, tier, at: new Date(d.now()).toISOString(), budget: j.budget, checks: j.checks, notes: j.notes,
+        host: { ...host, flagged: j.host.flagged.map((f) => ({ frame: f.frame, ms: f.ms, own_ms: f.own_ms, own_from: f.own_from })), rule: j.host.rule, max_game_ms: j.host.max_game_ms },
+        steps: steps.map((s) => ({ step: s.step, ok: s.ok, ms: s.ms, ...(s.error ? { error: s.error } : {}), ...(s.shot ? { shot: s.shot } : {}) })),
+        report: withoutRows(report), frames,
+    };
+    const file = o.out ? resolve(d.cwd, o.out) : join(dir, 'probe.json');
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(outcome, null, 2) + '\n');
+    if (o.json) {
+        io.log(JSON.stringify(outcome, null, 2));
+        return EXIT[verdict];
+    }
+    const m = report.meta;
+    u.heading(`unity probe · ${target} · ${tier} budgets · ${report.frames.included} frames measured · ${m.device ?? '?'} ${m.screen?.w ?? '?'}×${m.screen?.h ?? '?'}`);
+    const f = report.frame_ms;
+    if (f)
+        u.line(`frame ms  p50 ${r1(f.p50)}  p95 ${r1(f.p95)}  p99 ${r1(f.p99)}  max ${r1(f.max)}   (main p95 ${report.main_ms ? r1(report.main_ms.p95) : '–'}, render p95 ${report.render_ms ? r1(report.render_ms.p95) : '–'}, work p95 ${report.work_ms ? r1(report.work_ms.p95) : '–'}${report.gpu_ms ? `, gpu p95 ${r1(report.gpu_ms.p95)}` : ''})`, 1);
+    for (const c of j.checks)
+        u.item(c.verdict, `${c.label}: ${c.value === null ? '—' : `${c.value}${c.unit ? ` ${c.unit}` : ''}`} (${c.source === 'kit' ? 'kit starting point' : 'budget'} ${c.budget}${c.unit ? ` ${c.unit}` : ''})`, c.note);
+    u.item(report.hitch_count ? 'warn' : 'pass', `${report.hitch_count} hitch(es) over ${report.hitch_ms} ms`, report.hitches.slice(0, 5).map((h) => `frame ${h.frame} ${r1(h.ms)} ms${h.work !== null ? ` (work ${r1(h.work)})` : ''}${h.segment && h.segment !== 'run' ? ` in ${h.segment}` : ''}${h.note ? ` · ${h.note}` : ''}`).join('; ') || undefined);
+    for (const s of steps.filter((x) => !x.ok))
+        u.item('fail', `step ${JSON.stringify(s.step)}`, s.error);
+    for (const n of j.notes)
+        u.line(n, 1);
+    u.line(`written: ${file} (frames: ${frames})`, 1);
+    u.summary(verdict === 'not_observed' ? 'not_observed' : verdict, `unity probe: ${verdict === 'pass' ? 'within budget' : verdict === 'fail' ? (stepFailed ? 'a step failed' : 'over budget') : 'not observed'}`);
+    return EXIT[verdict];
+}
+export async function probeInstall(o, io, d, remove = false) {
+    const u = ui(io, `unity probe ${remove ? 'uninstall' : 'install'}`);
+    const project = resolve(d.cwd, o.project ?? '.');
+    const file = join(project, 'Packages', 'manifest.json');
+    if (!isUnityProject(project) || !existsSync(file)) {
+        u.error(`${project} is not a Unity project with Packages/manifest.json`, 'pass --project <dir>');
+        return EXIT.error;
+    }
+    const text = await readFile(file, 'utf8');
+    let edit;
+    if (remove)
+        edit = removeFrom(text);
+    else {
+        const ref = reference(project, { path: o.git ? undefined : (o.from ? resolve(d.cwd, o.from) : kitPackage(d.env) ?? undefined), git: o.git, ref: o.ref, absolute: o.absolute });
+        if (typeof ref !== 'string') {
+            u.error(ref.error);
+            return EXIT.error;
+        }
+        edit = addTo(text, ref, { force: o.force, tests: o.tests });
+    }
+    if ('error' in edit) {
+        u.error(edit.error);
+        return EXIT.error;
+    }
+    if (o.json) {
+        io.log(JSON.stringify({ file, changed: edit.changed, dry_run: !!o.dryRun, diff: edit.diff, note: edit.note ?? null }, null, 2));
+        if (edit.changed && !o.dryRun)
+            await writeFile(file, edit.text);
+        return 0;
+    }
+    u.heading(`${file}${o.dryRun ? ' · dry run' : ''}`);
+    for (const l of edit.diff)
+        u.line(l, 1);
+    if (!edit.changed) {
+        u.summary('note', edit.note ?? 'nothing to change');
+        return 0;
+    }
+    if (!o.dryRun)
+        await writeFile(file, edit.text);
+    u.summary('pass', o.dryRun ? 'not written (--dry-run)' : remove ? `${PACKAGE} removed; Unity resolves packages when the project next opens` : `${PACKAGE} added (development builds only); Unity resolves it when the project next opens. Undo: funtools unity probe uninstall`);
+    return 0;
+}
+const PLAY_STEPS = new Set(['tap', 'hold', 'drag', 'stick', 'key', 'pad', 'wait', 'frames', 'scene', 'view', 'segment', 'shot', 'state', 'release', 'cmd', 'speed']);
+async function sessionBridge(project, o, d) {
+    const port = o.port ?? (await readSession(project))?.port;
+    if (!port)
+        return { error: `no play session in ${project} — start one: funtools unity play start --project ${project}` };
+    try {
+        return { bridge: await d.connect(port, { waitMs: 5_000 }), session: await readSession(project) };
+    }
+    catch (e) {
+        return { error: `${e.message} — the session's player is gone? funtools unity play end, then play start` };
+    }
+}
+function printReply(io, r, json) {
+    const { ok: _ok, id: _id, png: _png, ...rest } = r;
+    io.log(json ? JSON.stringify(r) : JSON.stringify(rest, null, 2));
+}
+export async function playRun(o, io, d) {
+    const verb = o.args[0];
+    const u = ui(io, `unity play${verb ? ` ${verb}` : ''}`);
+    const project = resolve(d.cwd, o.project ?? '.');
+    const log = (l) => io.error(`funtools unity play: ${l}`);
+    if (!verb) {
+        u.error('which one?', 'funtools unity play start | tap x y | drag … | key … | state | ui | shot | record | act "<step>" … | end');
+        return EXIT.error;
+    }
+    if (verb === 'start') {
+        const target = targetOf(o);
+        if (typeof target !== 'string') {
+            u.error(target.error);
+            return EXIT.error;
+        }
+        const had = await readSession(project);
+        if (had) {
+            try {
+                const b = await d.connect(had.port, { waitMs: 2_000 });
+                b.close();
+                u.error(`a play session already runs here (port ${had.port}, started ${had.started})`, 'funtools unity play end first');
+                return EXIT.error;
+            }
+            catch {
+                await rm(sessionFile(project), { force: true });
+            }
+        }
+        let opened;
+        try {
+            opened = await openPlayer(project, target, { ...o, port: undefined }, d, log);
+        }
+        catch (e) {
+            u.error(e.message);
+            return EXIT.error;
+        }
+        if ('error' in opened) {
+            u.error(opened.error);
+            return opened.code;
+        }
+        const screen = await opened.bridge.send({ cmd: 'screen' });
+        opened.bridge.close();
+        await mkdir(dirname(sessionFile(project)), { recursive: true });
+        await writeFile(sessionFile(project), JSON.stringify(opened.running, null, 2) + '\n');
+        if (o.json) {
+            io.log(JSON.stringify({ session: opened.running, screen }, null, 2));
+            return 0;
+        }
+        u.summary('pass', `play session on port ${opened.running.port}: ${target === 'mac' ? `pid ${opened.running.pid}` : `${opened.running.bundle} on ${opened.running.udid}`} · screen ${JSON.stringify(screen.px)} px, ${target === 'mac' && Array.isArray(screen.px) ? (screen.px[0] > screen.px[1] ? 'landscape' : 'portrait') : screen.orientation} · end it with: funtools unity play end`);
+        return 0;
+    }
+    if (verb === 'end') {
+        const s = await readSession(project);
+        if (!s) {
+            u.summary('note', 'no play session here');
+            return 0;
+        }
+        let quit = null;
+        let bridge = null;
+        try {
+            bridge = await d.connect(s.port, { waitMs: 3_000 });
+            quit = () => bridge.send({ cmd: 'quit' }, 5_000);
+        }
+        catch { }
+        const how = s.target === 'mac' ? await stopMac(s, quit, d.launch) : await stopSim(s, quit, d.launch, await d.lease());
+        bridge?.close();
+        await rm(sessionFile(project), { force: true });
+        u.summary('pass', `play session ended: player ${how}`);
+        return 0;
+    }
+    if (verb === 'status') {
+        const s = await readSession(project);
+        if (!s) {
+            u.summary('note', 'no play session here');
+            return 0;
+        }
+        try {
+            const b = await d.connect(s.port, { waitMs: 3_000 });
+            const st = await b.send({ cmd: 'state' });
+            b.close();
+            io.log(JSON.stringify({ session: s, state: st }, null, 2));
+            return 0;
+        }
+        catch (e) {
+            u.error(`session recorded (port ${s.port}) but its player does not answer: ${e.message}`, 'funtools unity play end');
+            return EXIT.not_observed;
+        }
+    }
+    const got = await sessionBridge(project, o, d);
+    if ('error' in got) {
+        u.error(got.error);
+        return EXIT.error;
+    }
+    const { bridge } = got;
+    try {
+        if (verb === 'ui' || verb === 'views' || verb === 'screen') {
+            const r = await bridge.send({ cmd: verb });
+            printReply(io, r, o.json);
+            return r.ok ? 0 : EXIT.fail;
+        }
+        if (verb === 'send') {
+            let cmd;
+            try {
+                cmd = JSON.parse(o.args.slice(1).join(' '));
+            }
+            catch (e) {
+                u.error(`send: ${e.message}`, `funtools unity play send '{"cmd":"state"}'`);
+                return EXIT.error;
+            }
+            const r = await bridge.send(cmd, 120_000);
+            printReply(io, r, o.json);
+            return r.ok ? 0 : EXIT.fail;
+        }
+        if (verb === 'record') {
+            const seconds = o.seconds ?? 5;
+            const out = o.out ? resolve(d.cwd, o.out) : join(project, '.funtools', 'unity', `record-${stamp(d.now())}`);
+            const sess = got.session;
+            const dirForPlayer = sess?.target === 'sim' ? `funpixel-record-${stamp(d.now())}` : out;
+            const r = await bridge.send({ cmd: 'record', dir: dirForPlayer, seconds, fps: 30, audio: true }, seconds * 1000 * 20 + 60_000);
+            if (!r.ok) {
+                u.error(`record: ${r.error}`);
+                return EXIT.fail;
+            }
+            let dir = String(r.dir);
+            if (sess?.target === 'sim' && sess.udid && sess.bundle) {
+                const data = (await d.launch.exec('xcrun', ['simctl', 'get_app_container', sess.udid, sess.bundle, 'data'])).trim();
+                const inSim = join(data, 'Documents', dirForPlayer);
+                await mkdir(out, { recursive: true });
+                await d.launch.exec('cp', ['-R', `${inSim}/.`, out]);
+                dir = out;
+            }
+            const mp4 = `${dir}.mp4`;
+            const audio = r.audio ? join(dir, 'audio.wav') : null;
+            const ok = await d.ffmpeg(['-y', '-loglevel', 'error', '-framerate', String(r.fps), '-i', join(dir, 'f%05d.jpg'), ...(audio ? ['-i', audio] : []),
+                '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', ...(audio ? ['-c:a', 'aac', '-b:a', '192k', '-shortest'] : []), mp4]);
+            if (o.json) {
+                io.log(JSON.stringify({ ...r, dir, mp4: ok ? mp4 : null }, null, 2));
+                return 0;
+            }
+            u.summary('pass', `${r.frames} frames at ${r.fps} fps (${r.w}×${r.h})${audio ? `, audio ${r.sample_rate} Hz ×${r.channels}` : ` — no audio${r.audio_error ? ` (${r.audio_error})` : ''}`} → ${dir}${ok ? ` · ${mp4}` : ' · ffmpeg not run (missing or failed): join them yourself'}`);
+            return 0;
+        }
+        const words = verb === 'act' ? o.args.slice(1) : [o.args.join(' ')];
+        const steps = [];
+        for (const w of words) {
+            const s = parseWords(w);
+            if ('error' in s) {
+                u.error(`"${w}": ${s.error}`);
+                return EXIT.error;
+            }
+            steps.push(s);
+        }
+        if (verb !== 'act' && !PLAY_STEPS.has(verb)) {
+            u.error(`unknown: unity play ${verb}`);
+            return EXIT.error;
+        }
+        const shotOut = (name) => o.out && steps.length === 1 ? resolve(d.cwd, o.out) : join(project, '.funtools', 'unity', 'shots', `${stamp(d.now())}-${name.replace(/[^\w.-]+/g, '-')}.png`);
+        const results = await runSteps(steps, bridge, { space: o.points ? 'pt' : 'px', device: o.mouse ? 'mouse' : undefined }, {
+            shot: async (name, png) => { const f = shotOut(name); await mkdir(dirname(f), { recursive: true }); await writeFile(f, png); return f; },
+        });
+        for (const r of results) {
+            if (o.json)
+                io.log(JSON.stringify({ step: r.step, ok: r.ok, ...(r.error ? { error: r.error } : {}), ...(r.shot ? { shot: r.shot } : {}), reply: r.reply }));
+            else if ('state' in r.step && r.reply)
+                printReply(io, r.reply, false);
+            else
+                u.item(r.ok ? 'pass' : 'fail', `${Object.keys(r.step)[0]} ${JSON.stringify(Object.values(r.step)[0])}`, r.error ?? r.shot ?? r.reply?.note ?? undefined);
+        }
+        return results.every((r) => r.ok) && results.length === steps.length ? 0 : EXIT.fail;
+    }
+    finally {
+        bridge.close();
+    }
+}
+export async function captureAll(o, io, d) {
+    const u = ui(io, 'unity capture');
+    if (!o.all) {
+        u.error('unity capture takes --all (one still of each view); a single still is `funtools unity play shot`');
+        return EXIT.error;
+    }
+    const project = resolve(d.cwd, o.project ?? '.');
+    const log = (l) => io.error(`funtools unity capture: ${l}`);
+    const target = targetOf(o);
+    if (typeof target !== 'string') {
+        u.error(target.error);
+        return EXIT.error;
+    }
+    const sess = o.port ? null : await readSession(project);
+    let opened;
+    try {
+        opened = sess ? { running: null, bridge: await d.connect(sess.port, { waitMs: 5_000 }), stop: async () => 'left running (the play session)' } : await openPlayer(project, target, o, d, log, o.dev ? 'development' : 'capture');
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+    if ('error' in opened) {
+        u.error(opened.error);
+        return opened.code;
+    }
+    const { bridge } = opened;
+    const out = o.out ? resolve(d.cwd, o.out) : join(project, '.funtools', 'unity', `capture-${stamp(d.now())}`);
+    const shots = [];
+    try {
+        const v = await bridge.send({ cmd: 'views' });
+        if (!v.ok)
+            throw new Error(`views: ${v.error}`);
+        const views = v.views ?? [];
+        const scenes = (v.scenes ?? []).map((s) => s.name);
+        const list = views.length ? views.map((n) => ({ name: n, kind: 'view' })) : scenes.map((n) => ({ name: n, kind: 'scene' }));
+        if (!list.length)
+            throw new Error('the game registers no views (FunpixelProbe.View) and the build has no scenes');
+        log(views.length ? `${views.length} registered view(s)` : `no registered views: the build's ${scenes.length} scene(s)`);
+        await mkdir(out, { recursive: true });
+        for (const [i, item] of list.entries()) {
+            const enter = await bridge.send(item.kind === 'view' ? { cmd: 'view', name: item.name } : { cmd: 'scene', name: item.name }, 120_000);
+            if (!enter.ok) {
+                shots.push({ view: item.name, kind: item.kind, error: enter.error });
+                continue;
+            }
+            await bridge.send({ cmd: 'wait', ms: o.settleMs ?? 1000 }, 60_000);
+            const s = await bridge.send({ cmd: 'shot', inline: true }, 60_000);
+            if (!s.ok || typeof s.png !== 'string') {
+                shots.push({ view: item.name, kind: item.kind, error: s.error ?? 'no picture' });
+                continue;
+            }
+            const file = join(out, `${String(i + 1).padStart(2, '0')}-${item.name.replace(/[^\w.-]+/g, '-')}.png`);
+            await writeFile(file, Buffer.from(s.png, 'base64'));
+            shots.push({ view: item.name, kind: item.kind, file, w: s.w, h: s.h });
+        }
+    }
+    catch (e) {
+        u.error(e.message);
+        await opened.stop().catch(() => '');
+        return EXIT.error;
+    }
+    const how = await opened.stop().catch((e) => `not stopped: ${e.message}`);
+    log(`player ${how}`);
+    await writeFile(join(out, 'index.json'), JSON.stringify({ project, target, shots }, null, 2) + '\n');
+    const missed = shots.filter((s) => !s.file);
+    if (o.json) {
+        io.log(JSON.stringify({ out, shots }, null, 2));
+        return missed.length ? EXIT.not_observed : 0;
+    }
+    u.heading(`unity capture --all · ${shots.length} view(s) · ${out}`);
+    for (const s of shots)
+        u.item(s.file ? 'pass' : 'not_observed', `${s.kind} ${s.view}`, s.file ? `${s.file} (${s.w}×${s.h})` : s.error);
+    u.summary(missed.length ? 'not_observed' : 'pass', `unity capture: ${shots.length - missed.length} of ${shots.length} shot`);
+    return missed.length ? EXIT.not_observed : 0;
+}
+export async function unityPlayer(o, io, deps) {
+    const env = deps?.env ?? process.env;
+    if (process.platform !== 'darwin' && !deps && o.sub !== 'probe') {
+        ui(io, `unity ${o.sub}`).error('the Unity player tools run on macOS (a Mac player or the iOS Simulator)');
+        return EXIT.not_observed;
+    }
+    const d = { ...realPlayerDeps(io, realRunDeps(io, env), env), ...deps };
+    if (o.sub === 'probe' && (o.args[0] === 'install' || o.args[0] === 'uninstall'))
+        return probeInstall(o, io, d, o.args[0] === 'uninstall');
+    if (o.sub === 'probe') {
+        if (o.args.length) {
+            ui(io, 'unity probe').error(`unknown: unity probe ${o.args[0]}`, 'funtools unity probe [--path script.json] | probe install | probe uninstall');
+            return EXIT.error;
+        }
+        return probeRun(o, io, d);
+    }
+    if (o.sub === 'play')
+        return playRun(o, io, d);
+    return captureAll(o, io, d);
+}