@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/mobile-qa.js

@@ -0,0 +1,119 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { framesFor, keepHudFrames, measure } from "../playtest/measure.js";
+import { factsOf, factsText } from "../playtest/facts.js";
+import { premiseOf } from "../playtest/prepare.js";
+import { playerRound } from "../playtest/assemble.js";
+import { counts, mergedText, phoneTarget, prepareMobileQa, readMobileQa, runPhone, SEVERITIES, swipesFor } from "../playtest/mobile-qa.js";
+import { ui } from "../ui.js";
+export const MOBILE_QA_DIR = join('.funtools', 'mobile-qa');
+const runsIn = (root) => {
+    const d = join(root, MOBILE_QA_DIR);
+    return existsSync(d) ? readdirSync(d).filter((x) => /^\d+$/.test(x)).map(Number).sort((a, b) => a - b) : [];
+};
+export async function mobileQa(opts, io = console) {
+    const u = ui(io, 'mobile-qa');
+    const root = resolve(opts.dir);
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+    }
+    catch {
+        u.error(`no funpixel.json in ${root}`, 'run it in the game folder');
+        return EXIT.error;
+    }
+    const latest = runsIn(root).at(-1);
+    if (opts.sub === 'report') {
+        if (!latest) {
+            u.error('no Mobile QA here yet', 'run `funtools mobile-qa` first');
+            return EXIT.error;
+        }
+        const dir = join(root, MOBILE_QA_DIR, String(latest));
+        const r = readMobileQa(join(dir, 'mobile-qa.json'));
+        let prep = null;
+        try {
+            prep = JSON.parse(readFileSync(join(dir, 'evidence.json'), 'utf8'));
+        }
+        catch { }
+        if (!r.verdict) {
+            u.error(`the seat's answer: ${r.problem}`, `run the \`mobile-qa\` agent with ${join(dir, 'mobile-qa.md')}`);
+            return EXIT.error;
+        }
+        const observed = (prep?.platforms ?? []).filter((p) => p.observed).map((p) => p.id);
+        const order = (s) => SEVERITIES.indexOf(s);
+        const findings = [...r.verdict.findings].sort((a, b) => order(a.severity) - order(b.severity));
+        const c = counts(r.verdict);
+        const md = [
+            `# Mobile QA ${latest}: ${manifest.name ?? 'this game'}`, '',
+            `Phone-native **${r.verdict.phoneNative}/10** · ${c.high} high, ${c.medium} medium, ${c.low} low. ${r.verdict.verdict ?? ''}`, '',
+            `Looked at on: ${observed.join(', ') || 'no phone'}.`, '',
+            ...findings.map((f) => `- **${f.severity}** · ${f.area}: ${mergedText(f, observed)}${f.evidence?.number ? ` (${f.evidence.number})` : ''}${f.evidence?.frame ? ` [${f.evidence.frame}]` : ''}${f.fix ? ` — fix: ${f.fix}` : ''}`),
+            '', ...(r.verdict.fixFirst?.length ? ['Fix first:', ...r.verdict.fixFirst.map((x, i) => `${i + 1}. ${x}`), ''] : []),
+        ].join('\n');
+        await writeFile(join(dir, 'report.md'), md + '\n');
+        if (opts.json) {
+            io.log(JSON.stringify({ n: latest, phone_native: r.verdict.phoneNative, ...c, observed, findings: findings.map((f) => ({ ...f, text: mergedText(f, observed) })), fixFirst: r.verdict.fixFirst ?? [] }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`mobile-qa ${latest} · phone-native ${r.verdict.phoneNative}/10`);
+        for (const f of findings)
+            u.item(f.severity === 'high' ? 'fail' : f.severity === 'medium' ? 'warn' : 'note', `${f.severity} · ${f.area}`, `${mergedText(f, observed)}${f.evidence?.number ? ` (${f.evidence.number})` : ''}`);
+        u.line(join(dir, 'report.md'));
+        u.summary('pass', c.high ? `${c.high} high: a phone player meets these first; pick, edit or ignore` : 'no high finding');
+        return EXIT.pass;
+    }
+    const target = phoneTarget(manifest);
+    if (!target.target) {
+        if (opts.json)
+            io.log(JSON.stringify({ target }, null, 2));
+        else
+            u.summary('not_observed', `not a phone game: ${target.why}`);
+        return EXIT.not_observed;
+    }
+    const n = (latest ?? 0) + 1;
+    const dir = join(root, MOBILE_QA_DIR, String(n));
+    await mkdir(dir, { recursive: true });
+    const note = (line) => { if (!opts.json)
+        u.item('note', line); };
+    if (!opts.json) {
+        u.heading(`mobile-qa ${n} · ${manifest.name ?? root}`);
+        u.item('note', `measuring here, free: a few minutes, more for a game with many views (build, every view captured at both sizes, audit-screens and look --hud at phone size, a WebKit phone shot, key parity at phone size, five windows swept with look --fit)${opts.phone ? ', then `funtools phone` portrait and landscape, about a minute each' : ''}; then your agent runs one Mobile QA seat`);
+    }
+    try {
+        const measures = await measure(root, { quick: true, build: opts.build, note });
+        if (!measures.build.ok) {
+            u.item('fail', 'the build failed: nothing to judge', measures.build.tail);
+            u.summary('fail', 'fix the build, then run it again');
+            return EXIT.fail;
+        }
+        const frames = await framesFor(root, join(dir, 'frames'), measures.capture);
+        await keepHudFrames(measures, dir);
+        await writeFile(join(dir, 'measures.json'), JSON.stringify(measures, null, 2) + '\n');
+        if (opts.phone)
+            await runPhone(root, { sim: opts.sim, note, swipes: swipesFor(measures) });
+        const previous = latest ? readMobileQa(join(root, MOBILE_QA_DIR, String(latest), 'mobile-qa.json')).verdict ?? null : null;
+        const round = playerRound(root, '');
+        const prep = await prepareMobileQa(root, dir, {
+            manifest, premise: premiseOf(root, manifest).text, measures, frames: { dir: join(dir, 'frames'), names: frames },
+            facts: factsText(factsOf(measures)), round, prior: previous, note,
+        });
+        if (opts.json) {
+            io.log(JSON.stringify({ n, dir, seat: prep.seat, target: prep.target, platforms: prep.platforms, facts: prep.facts }, null, 2));
+            return EXIT.pass;
+        }
+        for (const p of prep.platforms)
+            u.item(p.observed ? 'pass' : 'not_observed', p.id, p.why);
+        for (const f of prep.facts)
+            u.item(/^not (observed|measured|filed)/.test(f.text) ? 'not_observed' : 'note', f.id, `${f.instrument}: ${f.text.slice(0, 240)}`);
+        u.line('the seat (a fresh `mobile-qa` agent, handed only this file):');
+        u.line(prep.seat ?? '', 4);
+        u.summary('pass', 'run the seat, then `funtools mobile-qa report`');
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(`mobile-qa failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+}

package/dist/commands/model.js

@@ -0,0 +1,256 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { findBench, benchArgs, LOCAL_VERBS, readModel, refusal, ENTRYPOINT } from "../model/bench.js";
+import { findBlender, runVerb } from "../model/blender.js";
+import { finalizeLocal } from "../model/finalize.js";
+import { judgeClips, modelClips } from "../model/clips.js";
+import { ui } from "../ui.js";
+import { gen } from "./gen.js";
+import { assetOf } from "../gen/record.js";
+const USAGE_LOCAL = 'funtools model --local <inspect|normalize|decimate|render|finalize> <model> | level <spec.json>';
+const USAGE_HOSTED = 'funtools model <inspect|render|finalize|skin> <asset-id|file> | retexture <asset-id|file> "new look" | level <spec.json>';
+function specName(path) {
+    try {
+        const name = JSON.parse(readFileSync(path, 'utf8'))?.name;
+        return typeof name === 'string' && /^[a-z][a-z0-9_]{0,31}$/.test(name) ? name : { why: 'its "name" is not a-z, 0-9 and _ (a letter first)' };
+    }
+    catch (e) {
+        return { why: `it is not readable JSON (${e instanceof Error ? e.message : e})` };
+    }
+}
+const rendersOf = (path) => join(process.cwd(), '.funtools', 'renders', basename(path, extname(path)));
+export async function model(opts, io = console) {
+    const u = ui(io, 'model');
+    if (opts.positionals[0] === 'clips')
+        return clips(opts, io);
+    if (!opts.local)
+        return hosted(opts, io);
+    const [verb, file] = opts.positionals;
+    if (!verb || !Object.hasOwn(LOCAL_VERBS, verb) || !file) {
+        u.error(`usage: ${USAGE_LOCAL}`, 'e.g. funtools model --local inspect public/assets/models/hero.glb');
+        return 3;
+    }
+    const path = resolve(file);
+    const v = verb;
+    if (!existsSync(path)) {
+        u.error(`no such file: ${file}`, v === 'level' ? 'give the path of a level spec (.json)' : 'give the path of a .glb, .gltf or .fbx');
+        return 3;
+    }
+    let levelName = '';
+    if (v === 'level') {
+        const name = specName(path);
+        if (typeof name !== 'string') {
+            u.error(`${file} is not a level spec`, name.why);
+            return 3;
+        }
+        levelName = name;
+    }
+    else {
+        const refused = refusal(path, readModel(path));
+        if (refused) {
+            u.error(`Blender cannot open ${file}`, refused);
+            return 1;
+        }
+    }
+    const spec = LOCAL_VERBS[v];
+    const out = opts.out ?? (v === 'render' ? rendersOf(path)
+        : v === 'level' ? join(process.cwd(), 'public', 'assets', 'models', `${levelName}.glb`)
+            : join(dirname(path), `${basename(path, extname(path))}.${verb}.glb`));
+    const proofs = v === 'level' ? join(process.cwd(), '.funtools', 'renders', levelName) : undefined;
+    const args = benchArgs(v, path, out, opts, proofs);
+    if (typeof args === 'string') {
+        u.error(args, 'run `funtools --help` for the usage');
+        return 3;
+    }
+    let keep = [];
+    if (v === 'finalize' && opts.keepClips !== undefined) {
+        keep = opts.keepClips.split(',').map((s) => s.trim()).filter(Boolean);
+        if (!keep.length) {
+            u.error('--keep-clips is a comma list of clip names', 'e.g. --keep-clips Idle,Walk');
+            return 3;
+        }
+    }
+    const bench = findBench();
+    if ('missing' in bench) {
+        u.error('no bench scripts', bench.missing);
+        return 3;
+    }
+    const blender = findBlender();
+    if ('missing' in blender) {
+        u.error('no Blender', blender.missing);
+        return 3;
+    }
+    const run = (benchVerb, a) => runVerb(blender.bin, join(bench.dir, ENTRYPOINT), benchVerb, a);
+    let answer;
+    if (v === 'finalize') {
+        answer = await finalizeLocal(run, { model: path, format: String(args.format), out: resolve(out), proofDir: rendersOf(path) }, keep);
+    }
+    else {
+        if (v === 'render')
+            mkdirSync(resolve(out), { recursive: true });
+        if (proofs) {
+            mkdirSync(proofs, { recursive: true });
+            mkdirSync(dirname(resolve(out)), { recursive: true });
+        }
+        answer = await run('bench' in spec ? spec.bench : verb, args);
+    }
+    if (opts.json) {
+        io.log(JSON.stringify({ verb, blender: blender.version.join('.'), ...answer }, null, 2));
+        return answer.ok ? 0 : 1;
+    }
+    u.heading(`model ${verb} · ${file} · Blender ${blender.version.join('.')} (local, free)`);
+    if (!answer.ok) {
+        u.item('fail', answer.error);
+        u.summary('fail', 'Blender refused the model');
+        return 1;
+    }
+    for (const line of describe(v, answer.result))
+        u.item('note', line);
+    if (v === 'render')
+        u.summary('pass', `wrote ${answer.result?.contact_sheet ?? out}`);
+    else if (v === 'level')
+        u.summary('pass', `wrote ${answer.result?.out_path ?? out}; look at ${answer.result?.plan ?? proofs}`);
+    else if (spec.writes)
+        u.summary('pass', `wrote ${answer.result?.out_path ?? out}`);
+    else
+        u.summary('pass', 'inspected');
+    return 0;
+}
+function clips(opts, io) {
+    const u = ui(io, 'model');
+    const file = opts.positionals[1];
+    if (!file || opts.positionals.length > 2) {
+        u.error('usage: funtools model clips <model.glb|gltf>', 'e.g. funtools model clips public/assets/models/hero.glb');
+        return 3;
+    }
+    let r;
+    try {
+        r = modelClips(resolve(file));
+    }
+    catch (e) {
+        u.error(`cannot read the clips of ${file}: ${e instanceof Error ? e.message : e}`, 'give a .glb or .gltf');
+        return 3;
+    }
+    const code = r.verdict === 'pass' ? 0 : r.verdict === 'fail' ? 1 : 2;
+    if (opts.json) {
+        io.log(JSON.stringify({ file, ...r }, null, 2));
+        return code;
+    }
+    u.heading(`model clips · ${file} · ${r.clips.length} named clip(s)`);
+    if (r.clips.length)
+        u.line(r.clips.join(', '), 2);
+    for (const [a, b] of r.collisions)
+        u.item('fail', `"${a}" sits inside "${b}"`, `a lookup for ${a} can play ${b}: rename one so neither contains the other (e.g. ${b} → a word of its own), and look clips up by exact name`);
+    for (const d of r.duplicates)
+        u.item('fail', `"${d}" names more than one clip`, 'only the first is reachable by name: rename or drop the others (finalize --keep-clips)');
+    if (r.unnamed)
+        u.item('fail', `${r.unnamed} clip(s) have no name`, 'name them in the exporter; code cannot ask for them');
+    u.summary(r.verdict, r.verdict === 'pass' ? 'every clip name is exact and apart'
+        : r.verdict === 'not_observed' ? 'no animation clips in this model: nothing to route (not a pass)' : 'a clip lookup by name can land on the wrong clip');
+    return code;
+}
+const HOSTED = {
+    inspect: { kind: 'inspect', takes: [] },
+    render: { kind: 'render', takes: ['frames', 'size', 'out'] },
+    finalize: { kind: 'finalize', takes: ['keepClips', 'out'] },
+    level: { kind: 'level', takes: ['size', 'out'] },
+    skin: { kind: 'skin', takes: ['tone', 'out'] },
+    retexture: { kind: 'retexture', takes: ['palette', 'gameId', 'quality', 'roughness', 'normal', 'out'] },
+};
+const FLAG = {
+    out: '--out', frames: '--frames', size: '--size', keepClips: '--keep-clips', tone: '--tone', palette: '--palette',
+    gameId: '--game-id', quality: '--quality', roughness: '--roughness', normal: '--normal',
+};
+async function hosted(opts, io) {
+    const u = ui(io, 'model');
+    const [verb, target, ...extra] = opts.positionals;
+    const spec = HOSTED[verb ?? ''];
+    const words = extra.join(' ').trim();
+    if (!spec || !target || (verb === 'retexture' ? !words : extra.length)) {
+        u.error(`usage: ${USAGE_HOSTED} (hosted) or ${USAGE_LOCAL}`, verb === 'retexture' ? 'describe the new look: funtools model retexture hero.glb "a snowy winter coat"'
+            : 'normalize and decimate run on your own Blender (--local); the hosted optimize-model, fracture and lod are `funtools gen`');
+        return 3;
+    }
+    if (opts.targetTriangles || opts.heightM) {
+        u.error('--target-triangles and --height-m are for --local normalize and decimate', 'the hosted optimize-model is `funtools gen optimize-model`');
+        return 3;
+    }
+    const stray = Object.keys(FLAG).find((k) => opts[k] !== undefined && opts[k] !== false && !spec.takes.includes(k));
+    if (stray) {
+        u.error(`hosted ${verb} takes no ${FLAG[stray]}`, spec.takes.length ? `${verb} takes ${spec.takes.map((k) => FLAG[k]).join(', ')}` : `${verb} writes nothing`);
+        return 3;
+    }
+    const flags = {};
+    for (const k of spec.takes) {
+        const v = opts[k];
+        if (k !== 'out' && v !== undefined && v !== false)
+            flags[FLAG[k]] = v === true ? true : String(v);
+    }
+    if (verb === 'level') {
+        const path = resolve(target);
+        if (!existsSync(path)) {
+            u.error(`no such file: ${target}`, 'give the path of a level spec (.json)');
+            return 3;
+        }
+        const name = specName(path);
+        if (typeof name !== 'string') {
+            u.error(`${target} is not a level spec`, name.why);
+            return 3;
+        }
+        return gen({ positionals: ['level'], flags: { ...flags, '--spec': path }, json: opts.json, wait: true, yes: false, out: opts.out, name }, io);
+    }
+    let asset = target;
+    let name;
+    const path = resolve(target);
+    if (existsSync(path)) {
+        const found = await assetOf(path);
+        if ('why' in found) {
+            u.error(`cannot ${verb} ${target} on the hosted bench: ${found.why}`, `${verb} it on your own Blender: funtools model --local ${verb} ${target}`);
+            return 3;
+        }
+        asset = found.asset_id;
+        name = basename(path, extname(path));
+    }
+    else if (/[\\/]|\.(glb|gltf|fbx)$/i.test(target)) {
+        u.error(`no such file: ${target}`, 'give a model file gen saved in this game, or the asset id of one a job made (funtools jobs --tool model3d)');
+        return 3;
+    }
+    flags['--asset'] = asset;
+    const positionals = words ? [spec.kind, words] : [spec.kind];
+    return gen({ positionals, flags, json: opts.json, wait: true, yes: false, out: opts.out, name }, io);
+}
+function describe(verb, r) {
+    if (!r || typeof r !== 'object')
+        return [];
+    if (verb === 'inspect') {
+        const meshes = Array.isArray(r.meshes) ? r.meshes : [];
+        const tris = meshes.reduce((n, m) => n + (Number(m.triangles) || 0), 0);
+        const lines = [`${meshes.length} mesh(es), ${tris} triangles, ${r.total_vertices ?? 0} vertices`];
+        if (r.armature)
+            lines.push(`armature: ${r.armature.bones ?? r.armature.bone_count ?? '?'} bones`);
+        if (Array.isArray(r.clips)) {
+            lines.push(`${r.clips.length} animation clip(s)`);
+            const c = judgeClips(r.clips.map((x) => x?.name));
+            for (const [a, b] of c.collisions)
+                lines.push(`clip "${a}" sits inside "${b}": a lookup by name can play the wrong one (funtools model clips)`);
+        }
+        if (r.up_axis)
+            lines.push(`up axis ${r.up_axis}`);
+        return lines;
+    }
+    if (verb === 'render') {
+        const frames = Array.isArray(r.frames) ? r.frames : [];
+        return [`${frames.length} view(s) round the model, a front view and a contact sheet (${r.engine ?? 'Blender'})`];
+    }
+    if (verb === 'finalize') {
+        const fixed = Array.isArray(r.materials_fixed) ? r.materials_fixed : [];
+        const lines = [fixed.length ? `repaired ${fixed.map((m) => m.name).join(', ')}` : 'materials were already correct'];
+        if (r.clips)
+            lines.push(`kept ${(r.clips.kept ?? []).length} clip(s), dropped ${(r.clips.dropped ?? []).length}`);
+        lines.push(r.proof?.rendered ? `proof: ${r.proof.contact_sheet ?? r.proof.front}` : `NO PROOF: ${r.proof?.error ?? 'the render failed'} — do not assume it looks right`);
+        return lines;
+    }
+    return Object.entries(r)
+        .filter(([k, v]) => k !== 'out_path' && (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'string'))
+        .map(([k, v]) => `${k}: ${v}`);
+}

package/dist/commands/models.js

@@ -0,0 +1,93 @@
+import { MODELS } from "../gen/models.js";
+import { GEN_MODELS } from "../gen/models.generated.js";
+import { providerFor } from "../gen/local/index.js";
+import { LocalFailure, LocalRefusal, modelsDir, realMachine } from "../gen/local/provider.js";
+import { ui } from "../ui.js";
+export const MODELS_SUBCOMMANDS = ['list', 'install'];
+export function localState(id, m) {
+    const p = providerFor(id);
+    if (!p)
+        return { installed: false, fix: `${id} has no runner in this funtools yet`, check: null };
+    const c = p.check(m);
+    return c.state === 'installed' ? { installed: true, check: c } : { installed: false, fix: c.state === 'missing' ? c.fix : c.says, check: c };
+}
+export async function models(opts, io = console) {
+    const u = ui(io, `models ${opts.sub}`);
+    const m = opts.machine ?? realMachine();
+    if (opts.sub === 'list') {
+        const rows = MODELS.map((x) => ({ ...x, ...(x.where === 'local' ? (({ check: _c, ...rest }) => rest)(localState(x.id, m)) : {}) }));
+        if (opts.json) {
+            io.log(JSON.stringify({ models: rows }, null, 2));
+            return 0;
+        }
+        for (const kind of GEN_MODELS.kinds) {
+            const of = rows.filter((x) => x.kind === kind);
+            if (!of.length)
+                continue;
+            u.heading(kind);
+            for (const x of of) {
+                if (x.where === 'hosted')
+                    u.item(x.recommended ? 'pass' : 'note', `${x.id}${x.recommended ? ' (recommended)' : ''} — ${x.label}`, x.one_line);
+                else
+                    u.item(x.installed ? 'pass' : 'skip', `${x.id} (on this Mac, free, not checked by us) — ${x.installed ? 'set up here' : `not set up: ${x.fix}`}`, x.one_line);
+            }
+        }
+        u.summary('pass', 'leave out --model for our pick; a local one runs only when named (funtools gen <kind> --model <id>)');
+        return 0;
+    }
+    const id = opts.id;
+    if (!id) {
+        u.error('install needs a model', `funtools models install ${MODELS.filter((x) => x.where === 'local').map((x) => x.id).join('|') || '<id>'}`);
+        return 3;
+    }
+    const entry = MODELS.find((x) => x.id === id);
+    if (!entry) {
+        u.error(`no model ${id}`, 'funtools models list names them');
+        return 2;
+    }
+    if (entry.where !== 'local') {
+        u.error(`${id} runs on our servers: there is nothing to install`, `use it with funtools gen ${entry.kind} --model ${id} (or leave --model out for our pick)`);
+        return 2;
+    }
+    const p = providerFor(id);
+    if (!p) {
+        u.error(`${id} has no runner in this funtools yet`, 'upgrade funtools: npx @funpixel/tools@latest');
+        return 2;
+    }
+    if (!opts.json)
+        u.heading(`models install ${id} · into ${modelsDir(m)}`);
+    const live = opts.json ? null : u.progress();
+    try {
+        await p.install(m, {
+            force: opts.force,
+            progress: (line, isLive) => {
+                if (opts.json)
+                    return;
+                if (isLive)
+                    live?.update(line);
+                else
+                    u.line(line);
+            },
+        });
+    }
+    catch (e) {
+        live?.done('fail', 'not set up');
+        const code = e instanceof LocalRefusal ? 2 : e instanceof LocalFailure ? 1 : 3;
+        if (opts.json)
+            io.log(JSON.stringify({ ok: false, model: id, error: { message: e.message } }, null, 2));
+        u.error(e.message);
+        return code;
+    }
+    live?.done('pass', 'weights in place');
+    const after = p.check(m);
+    if (opts.json) {
+        io.log(JSON.stringify({ ok: after.state === 'installed', model: id, check: after }, null, 2));
+        return after.state === 'installed' ? 0 : 1;
+    }
+    if (after.state !== 'installed') {
+        u.error(`installed, but the check still says: ${after.says}`, 'run funtools doctor');
+        return 1;
+    }
+    u.summary('pass', `${id} is set up: funtools gen ${entry.kind === 'voice' ? 'line "Hello there." --preset Kore' : entry.kind} --model ${id} (free, on this Mac, not checked by us; leave --model out for our pick)`);
+    return 0;
+}