@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/review/video.js

@@ -0,0 +1,248 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { measure, PEAK_CEILING, TOLERANCE } from "../sound/loudness.js";
+import { decodeErrors, found, named, probe, round1, round2, stem, together, unseen } from "./media.js";
+export const EDGE_S = 0.5;
+export const FREEZE_S = 2;
+export const STILL_SHARE = 0.9;
+export const VIDEO_LUFS = { web: -14, broadcast: -23 };
+const spanWord = (s) => `${round2(s.start)}–${round2(s.end)} s`;
+export function parseDetect(stderr, duration) {
+    const black = [];
+    for (const m of stderr.matchAll(/black_start:\s*([\d.]+)\s+black_end:\s*([\d.]+)/g))
+        black.push({ start: Number(m[1]), end: Number(m[2]) });
+    const frozen = [];
+    let open = null;
+    for (const m of stderr.matchAll(/freezedetect\.freeze_(start|end):\s*([\d.]+)/g)) {
+        if (m[1] === 'start')
+            open = Number(m[2]);
+        else if (open !== null) {
+            frozen.push({ start: open, end: Number(m[2]) });
+            open = null;
+        }
+    }
+    if (open !== null)
+        frozen.push({ start: open, end: duration });
+    return { black, frozen };
+}
+export function blackErrors(black, duration) {
+    return black.filter((s) => Math.min(s.end, duration - EDGE_S) - Math.max(s.start, EDGE_S) > 0.02).map((s) => `black ${spanWord(s)}`);
+}
+const overlap = (a, b) => Math.max(0, Math.min(a.end, b.end) - Math.max(a.start, b.start));
+export function frozenErrors(frozen, black, duration, limit, still) {
+    const frozenTotal = frozen.reduce((s, f) => s + (f.end - f.start), 0);
+    if (still || (duration > 0 && frozenTotal / duration >= STILL_SHARE))
+        return { errors: [], still: true };
+    const errors = frozen
+        .filter((f) => f.end - f.start > limit)
+        .filter((f) => black.reduce((s, b) => s + overlap(f, b), 0) < 0.5 * (f.end - f.start))
+        .map((f) => `frozen ${spanWord(f)} (${round1(f.end - f.start)} s, over ${limit} s)`);
+    return { errors, still: false };
+}
+export const SAFE = {
+    '9:16': { top: 0.14, bottom: 0.2, left: 0.06, right: 0.12 },
+    '16:9': { top: 0.05, bottom: 0.05, left: 0.05, right: 0.05 },
+    '1:1': { top: 0.06, bottom: 0.06, left: 0.06, right: 0.06 },
+};
+export function shapeOf(w, h) {
+    const r = Math.log(w / h);
+    const shapes = [['9:16', 9 / 16], ['16:9', 16 / 9], ['1:1', 1]];
+    let best = shapes[2];
+    for (const s of shapes)
+        if (Math.abs(Math.log(s[1]) - r) < Math.abs(Math.log(best[1]) - r))
+            best = s;
+    return best[0];
+}
+export const CAPTION_LINE = 0.05;
+const pct = (s) => (s !== undefined && /^-?[\d.]+%$/.test(s) ? Number(s.slice(0, -1)) / 100 : null);
+export function vttBoxes(text) {
+    const boxes = [];
+    let unplaced = 0;
+    const blocks = text.replace(/\r/g, '').split(/\n\n+/);
+    for (const b of blocks) {
+        const lines = b.split('\n');
+        const i = lines.findIndex((l) => l.includes('-->'));
+        if (i < 0)
+            continue;
+        const [, rest = ''] = lines[i].split('-->');
+        const tokens = rest.trim().split(/\s+/).slice(1);
+        const set = Object.fromEntries(tokens.map((t) => t.split(':')).filter((kv) => kv.length === 2));
+        const textLines = lines.slice(i + 1).filter((l) => l.trim());
+        const at = lines[i].split('-->')[0].trim();
+        const [lineV, lineAlign = 'start'] = (set.line ?? '').split(',');
+        const top0 = pct(lineV);
+        const [posV, posAlign] = (set.position ?? '').split(',');
+        const pos = pct(posV);
+        const size = pct(set.size);
+        if (top0 === null && (pos === null || size === null)) {
+            unplaced++;
+            continue;
+        }
+        const h = Math.max(1, textLines.length) * CAPTION_LINE;
+        const top = top0 === null ? null : lineAlign === 'end' ? top0 - h : lineAlign === 'center' ? top0 - h / 2 : top0;
+        let left = null, right = null;
+        if (pos !== null && size !== null) {
+            const align = posAlign ?? (set.align === 'start' || set.align === 'left' ? 'line-left' : set.align === 'end' || set.align === 'right' ? 'line-right' : 'center');
+            left = align === 'line-left' ? pos : align === 'line-right' ? pos - size : pos - size / 2;
+            right = left + size;
+        }
+        boxes.push({ at, text: textLines.join(' ').slice(0, 40), top, bottom: top === null ? null : top + h, left, right });
+    }
+    return { boxes, unplaced };
+}
+export function srtBoxes(text, w, h) {
+    const boxes = [];
+    let unplaced = 0;
+    for (const b of text.replace(/\r/g, '').split(/\n\n+/)) {
+        const lines = b.split('\n');
+        const i = lines.findIndex((l) => l.includes('-->'));
+        if (i < 0)
+            continue;
+        const c = Object.fromEntries([...lines[i].matchAll(/([XY][12]):\s*(-?\d+)/g)].map((m) => [m[1], Number(m[2])]));
+        const textLines = lines.slice(i + 1).filter((l) => l.trim());
+        if (c.Y1 === undefined || c.Y2 === undefined) {
+            unplaced++;
+            continue;
+        }
+        boxes.push({ at: lines[i].split('-->')[0].trim(), text: textLines.join(' ').slice(0, 40), top: c.Y1 / h, bottom: c.Y2 / h, left: c.X1 !== undefined ? c.X1 / w : null, right: c.X2 !== undefined ? c.X2 / w : null });
+    }
+    return { boxes, unplaced };
+}
+export function jsonBoxes(raw, w, h) {
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw?.captions) ? raw.captions : [];
+    const boxes = [];
+    let unplaced = 0;
+    for (const c of list) {
+        const b = Array.isArray(c?.box) ? c.box : c?.box && typeof c.box === 'object' ? [c.box.x, c.box.y, c.box.w, c.box.h] : [c?.x, c?.y, c?.w, c?.h];
+        if (!b.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+            unplaced++;
+            continue;
+        }
+        const shares = b.every((v) => Math.abs(v) <= 1);
+        const [x, y, bw, bh] = shares ? b : [b[0] / w, b[1] / h, b[2] / w, b[3] / h];
+        boxes.push({ at: String(c?.start ?? c?.at ?? '?'), text: String(c?.text ?? '').slice(0, 40), top: y, bottom: y + bh, left: x, right: x + bw });
+    }
+    return { boxes, unplaced };
+}
+export function sidecarOf(file) {
+    for (const ext of ['.vtt', '.srt', '.captions.json']) {
+        const p = join(dirname(file), stem(file) + ext);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function captionCount(file, w, h) {
+    const side = sidecarOf(file);
+    if (!side)
+        return unseen('no captions sidecar (.vtt, .srt or .captions.json beside it) says where captions sit');
+    let got;
+    try {
+        const text = readFileSync(side, 'utf8');
+        got = side.endsWith('.json') ? jsonBoxes(JSON.parse(text), w, h) : side.endsWith('.vtt') ? vttBoxes(text) : srtBoxes(text, w, h);
+    }
+    catch (e) {
+        return unseen(`${side.split('/').pop()} does not read: ${e.message}`);
+    }
+    if (!got.boxes.length)
+        return unseen(`${side.split('/').pop()} gives no cue a position${got.unplaced ? ` (${got.unplaced} unplaced)` : ''}`);
+    const shape = shapeOf(w, h);
+    const z = SAFE[shape];
+    const out = [];
+    for (const b of got.boxes) {
+        const sides = [];
+        if (b.top !== null && b.top < z.top - 1e-6)
+            sides.push('top');
+        if (b.bottom !== null && b.bottom > 1 - z.bottom + 1e-6)
+            sides.push('bottom');
+        if (b.left !== null && b.left < z.left - 1e-6)
+            sides.push('left');
+        if (b.right !== null && b.right > 1 - z.right + 1e-6)
+            sides.push('right');
+        if (sides.length)
+            out.push(`caption at ${b.at} "${b.text}" outside the ${shape} safe zone (${sides.join(', ')})`);
+    }
+    const c = found(out);
+    if (got.unplaced)
+        c.detail.push(`${got.unplaced} cue(s) give no position: not judged`);
+    return c;
+}
+const SIDE = 48;
+const FRAME = SIDE * SIDE * 3;
+export const WRAP_RATIO = 2;
+export const WRAP_MIN = 3;
+function smallFrames(file, seconds, from) {
+    const args = ['-hide_banner', '-v', 'error', ...(from === 'end' ? ['-sseof', `-${seconds}`] : []), '-i', file, ...(from === 'start' ? ['-t', String(seconds)] : []), '-an', '-vf', `scale=${SIDE}:${SIDE},format=rgb24`, '-f', 'rawvideo', 'pipe:1'];
+    const r = spawnSync('ffmpeg', args, { timeout: 60_000, maxBuffer: 64 * 1024 * 1024 });
+    const b = r.stdout;
+    if (r.status !== 0 || !b?.length)
+        return [];
+    const out = [];
+    for (let o = 0; o + FRAME <= b.length; o += FRAME)
+        out.push(new Uint8Array(b.subarray(o, o + FRAME)));
+    return out;
+}
+export const frameDiff = (a, b) => { let s = 0; for (let i = 0; i < a.length; i++)
+    s += Math.abs(a[i] - b[i]); return s / a.length; };
+export function judgeLoop(first, last) {
+    if (first.length < 2 || last.length < 2)
+        return null;
+    const steps = [];
+    for (const run of [first, last])
+        for (let i = 1; i < run.length; i++)
+            steps.push(frameDiff(run[i - 1], run[i]));
+    steps.sort((a, b) => a - b);
+    const step = steps[Math.floor(steps.length / 2)];
+    const jump = frameDiff(last[last.length - 1], first[0]);
+    return { seam: jump > WRAP_MIN && jump > WRAP_RATIO * Math.max(step, 0.25), jump: round1(jump), step: round1(step) };
+}
+export function reviewVideo(file, rel, o = {}) {
+    const r = { file: rel, trade: 'video', errors: unseen('not measured'), overlaps: unseen('not measured'), seams: unseen('not measured'), notes: [] };
+    const p = probe(file);
+    if ('error' in p) {
+        r.errors = found([`does not open: ${p.error}`]);
+        return r;
+    }
+    const v = p.streams.find((s) => s.codec_type === 'video');
+    const a = p.streams.find((s) => s.codec_type === 'audio');
+    if (!v || !v.width || !v.height) {
+        r.errors = found(['no picture: the file has no video stream']);
+        return r;
+    }
+    const rot = Math.abs(v.side_data_list?.find((d) => typeof d.rotation === 'number')?.rotation ?? 0) % 180 === 90;
+    const [w, h] = rot ? [v.height, v.width] : [v.width, v.height];
+    const duration = p.duration ?? (Number(v.duration) || 0);
+    r.notes.push(`${w}×${h} (${shapeOf(w, h)}), ${round2(duration)} s${a ? '' : ', no sound'}`);
+    const decode = decodeErrors(file);
+    const broken = decode.length ? [`does not decode cleanly: ${decode[0]}${decode.length > 1 ? ` (+${decode.length - 1} more)` : ''}`] : [];
+    const limit = o.freezeS ?? FREEZE_S;
+    const det = spawnSync('ffmpeg', ['-hide_banner', '-nostats', '-i', file, '-an', '-vf', `scale=320:-2,blackdetect=d=0.04:pix_th=0.10,freezedetect=n=-60dB:d=${Math.min(limit, 0.5)}`, '-f', 'null', '-'], { encoding: 'utf8', timeout: 300_000 });
+    const spans = parseDetect(det.stderr ?? '', duration);
+    const black = blackErrors(spans.black, duration);
+    const still = o.still || named(rel, 'still|static|poster');
+    const frozen = frozenErrors(spans.frozen, spans.black, duration, limit, still);
+    if (frozen.still)
+        r.notes.push('a still cut: frozen frames are not judged');
+    r.errors = together(found(broken), det.status === 0 ? found([...black, ...frozen.errors]) : unseen('the black and frozen-frame pass did not run'));
+    r.overlaps = captionCount(file, w, h);
+    if (o.loop || named(rel, 'loop|loops|looping|seamless')) {
+        const span = Math.min(0.4, Math.max(0.1, duration / 4));
+        const j = judgeLoop(smallFrames(file, span, 'start'), smallFrames(file, span, 'end'));
+        r.seams = j ? found(j.seam ? [`as a loop it jumps: the last frame into the first moves ${j.jump} levels, ${round1(j.jump / Math.max(j.step, 0.25))}× the ordinary step (${j.step})`] : []) : unseen('too short to judge its loop');
+    }
+    else
+        r.seams = unseen('not a loop (name it loop, or --loop)');
+    if (a) {
+        const m = measure(file);
+        const kind = named(rel, 'broadcast|tv') ? 'broadcast' : 'web';
+        const target = VIDEO_LUFS[kind];
+        if (m.lufs === null || m.lufs <= -69)
+            r.notes.push(`loudness: too short or too quiet for integrated loudness (sample peak ${m.max ?? '–'} dB)`);
+        else {
+            const off = Math.abs(m.lufs - target) > TOLERANCE;
+            r.notes.push(`loudness ${m.lufs} LUFS, true peak ${m.peak ?? '–'} dBTP (target ${target} ±${TOLERANCE} for ${kind}${off ? `: ${m.lufs < target ? 'quiet' : 'loud'} for it` : ''}${m.peak !== null && m.peak > PEAK_CEILING ? `; peak over ${PEAK_CEILING}` : ''})`);
+        }
+    }
+    return r;
+}

package/dist/schema/game.js

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { closest, validate as validateLook, LOOK_FILE } from "../look/theme.js";
+import { MANIFEST as ASSET_MANIFEST, readAssetManifest } from "../assets/manifest.js";
+import { checkWorld } from "../world/check.js";
+import { sidecarReader } from "../commands/world.js";
+export const MANIFEST_KEYS = {
+    name: 'the game\'s name (string)',
+    title: 'a display title (string)',
+    description: 'one line about the game (string)',
+    game_id: 'the draft id: 32 lowercase hex',
+    guidance_hash: 'which kit guidance wrote it (funtools init)',
+    splash: 'own | funpixel: who draws the first screen',
+    metadata: 'genre, tagline, artStyle, dimension, mode, orientation, framework, palette, fonts',
+    checks: 'the mechanics verify presses: [{ mechanic, verb|key, field, expect, times }]',
+    hooks: 'names the probe maps onto the game\'s own functions',
+    production: '{ tier: small|mid|deep, because }',
+    flow: 'the owner\'s settings: { autonomy: ask|plan-then-go|go, rounds_per_session }',
+    studio: 'the locked studio pitch (funtools pitch lock)',
+    framing: 'camera framing rules (funtools framing)',
+    walk: 'routes the walk film follows (funtools walk)',
+    reach: '{ levels, movement, sealed, seen } (funtools reach)',
+    scale: 'world scale facts (funtools walk)',
+    life: 'the living-world contract (funtools life)',
+    actors: 'actor names matched in the scene (funtools scene)',
+    art: 'art direction facts',
+    moments: 'the timed moments a playtest shoots',
+    criteria: 'the game\'s own pass criteria',
+    firstMinute: 'what the first minute must show',
+    optimize: 'asset optimizer settings (funtools optimize)',
+    play_min_minutes: 'the length floor in minutes (default 15)',
+    accuracy_min: 'the owner\'s bar for a moment against its target (0–100)',
+    owner_gates: 'gates the Stop hook may hold on: { accuracy_min, panel_min, evidence }',
+    gdk: '{ gate: block|warn|off } for the local hooks',
+    pixelArt: 'the pixel grid a pixel-art game keeps (funtools assets pixels)',
+    world: 'the forged world\'s file and seed (funtools world forge)',
+    review: 'what funtools review holds media to: { triangles: a model\'s budget, palette: a palette file }',
+};
+const METADATA_KEYS = ['genre', 'tagline', 'artStyle', 'dimension', 'mode', 'orientation', 'framework', 'palette', 'fonts', 'engine', 'players', 'platform'];
+const CHECK_KEYS = ['mechanic', 'verb', 'key', 'field', 'expect', 'subject', 'times', 'hold', 'pointer', 'note', 'within_ms', 'skip'];
+const EXPECTS = ['increases', 'decreases', 'changes', 'changed'];
+const OWNER_GATE_KEYS = ['accuracy_min', 'panel_min', 'evidence', 'round_needs_evidence'];
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const GAME_ID = /^[0-9a-f]{32}$/;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function oneOf(out, file, path, v, allowed) {
+    if (v === undefined)
+        return;
+    if (typeof v !== 'string' || !allowed.includes(v))
+        out.push({ file, path, level: 'error', what: `${JSON.stringify(v)} is not one of ${allowed.join(', ')}`, suggest: typeof v === 'string' ? closest(v, allowed) : [] });
+}
+function unknownKeys(out, file, path, obj, known, level) {
+    for (const k of Object.keys(obj)) {
+        if (k.startsWith('$') || known.includes(k))
+            continue;
+        out.push({ file, path: path ? `${path}.${k}` : k, level, what: 'not a key any kit command reads', suggest: closest(k, known) });
+    }
+}
+function num(out, file, path, v, lo, hi, int = false) {
+    if (v === undefined)
+        return;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < lo || v > hi || (int && !Number.isInteger(v)))
+        out.push({ file, path, level: 'error', what: `${JSON.stringify(v)} is not ${int ? 'a whole number' : 'a number'} from ${lo} to ${hi}` });
+}
+export function validateManifest(m, opts = {}) {
+    const F = 'funpixel.json';
+    const out = [];
+    if (!isObj(m))
+        return [{ file: F, path: '', level: 'error', what: 'not a JSON object' }];
+    unknownKeys(out, F, '', m, Object.keys(MANIFEST_KEYS), opts.strict ? 'error' : 'warn');
+    if (typeof m.name !== 'string' || !m.name.trim())
+        out.push({ file: F, path: 'name', level: 'error', what: 'every game has a name (a non-empty string)' });
+    if (m.game_id !== undefined && (typeof m.game_id !== 'string' || !GAME_ID.test(m.game_id)))
+        out.push({ file: F, path: 'game_id', level: 'error', what: 'a game id is 32 lowercase hex (no "game-" prefix)' });
+    oneOf(out, F, 'splash', m.splash, ['own', 'funpixel']);
+    if (m.metadata !== undefined) {
+        if (!isObj(m.metadata))
+            out.push({ file: F, path: 'metadata', level: 'error', what: 'not an object' });
+        else {
+            const md = m.metadata;
+            unknownKeys(out, F, 'metadata', md, METADATA_KEYS, 'warn');
+            oneOf(out, F, 'metadata.dimension', md.dimension, ['2d', '3d']);
+            oneOf(out, F, 'metadata.mode', md.mode, ['single', 'multiplayer']);
+            oneOf(out, F, 'metadata.orientation', md.orientation, ['landscape', 'portrait', 'both', 'any']);
+            if (md.palette !== undefined) {
+                if (!isObj(md.palette))
+                    out.push({ file: F, path: 'metadata.palette', level: 'error', what: 'a palette is { name: "#rrggbb" }' });
+                else
+                    for (const [k, v] of Object.entries(md.palette))
+                        if (typeof v !== 'string' || !HEX.test(v))
+                            out.push({ file: F, path: `metadata.palette.${k}`, level: 'error', what: `${JSON.stringify(v)} is not a #rrggbb colour` });
+            }
+            if (md.fonts !== undefined && (!Array.isArray(md.fonts) || md.fonts.some((f) => typeof f !== 'string')))
+                out.push({ file: F, path: 'metadata.fonts', level: 'error', what: 'fonts is a list of family names' });
+        }
+    }
+    if (m.checks !== undefined) {
+        if (!Array.isArray(m.checks))
+            out.push({ file: F, path: 'checks', level: 'error', what: 'checks is a list' });
+        else
+            m.checks.forEach((c, i) => {
+                const at = `checks[${i}]`;
+                if (!isObj(c)) {
+                    out.push({ file: F, path: at, level: 'error', what: 'not an object' });
+                    return;
+                }
+                unknownKeys(out, F, at, c, CHECK_KEYS, 'warn');
+                if (typeof c.mechanic !== 'string' || !c.mechanic.trim())
+                    out.push({ file: F, path: `${at}.mechanic`, level: 'error', what: 'each check names its mechanic in words' });
+                if (c.verb === undefined && c.key === undefined && c.pointer === undefined)
+                    out.push({ file: F, path: at, level: 'error', what: 'a check presses something: a verb, a key or a pointer' });
+                if (c.field !== undefined && typeof c.field !== 'string')
+                    out.push({ file: F, path: `${at}.field`, level: 'error', what: 'the field read is a name' });
+                oneOf(out, F, `${at}.expect`, c.expect, EXPECTS);
+                num(out, F, `${at}.times`, c.times, 1, 100, true);
+            });
+    }
+    if (m.production !== undefined) {
+        if (!isObj(m.production))
+            out.push({ file: F, path: 'production', level: 'error', what: 'not an object' });
+        else
+            oneOf(out, F, 'production.tier', m.production.tier, ['small', 'mid', 'deep']);
+    }
+    if (m.flow !== undefined) {
+        if (!isObj(m.flow))
+            out.push({ file: F, path: 'flow', level: 'error', what: 'not an object' });
+        else {
+            oneOf(out, F, 'flow.autonomy', m.flow.autonomy, ['ask', 'plan-then-go', 'go']);
+            num(out, F, 'flow.rounds_per_session', m.flow.rounds_per_session, 1, 50, true);
+        }
+    }
+    num(out, F, 'play_min_minutes', m.play_min_minutes, 1, 600);
+    num(out, F, 'accuracy_min', m.accuracy_min, 0, 100);
+    if (m.owner_gates !== undefined) {
+        if (!isObj(m.owner_gates))
+            out.push({ file: F, path: 'owner_gates', level: 'error', what: 'not an object' });
+        else {
+            unknownKeys(out, F, 'owner_gates', m.owner_gates, OWNER_GATE_KEYS, 'warn');
+            num(out, F, 'owner_gates.accuracy_min', m.owner_gates.accuracy_min, 0, 100);
+            num(out, F, 'owner_gates.panel_min', m.owner_gates.panel_min, 0, 10);
+        }
+    }
+    if (m.gdk !== undefined) {
+        if (!isObj(m.gdk))
+            out.push({ file: F, path: 'gdk', level: 'error', what: 'not an object' });
+        else
+            oneOf(out, F, 'gdk.gate', m.gdk.gate, ['block', 'warn', 'off']);
+    }
+    return out;
+}
+export function validateTunables(t, file = 'design/spec/tunables.json') {
+    const out = [];
+    const rows = Array.isArray(t) ? t : isObj(t) && Array.isArray(t.tunables) ? t.tunables : isObj(t) ? Object.entries(t).map(([id, v]) => (isObj(v) ? { id, ...v } : { id, default: v })) : [];
+    if (!rows.length)
+        return [{ file, path: '', level: 'error', what: 'no tunables: a list of { id, default, range, unit, why }' }];
+    const seen = new Set();
+    rows.forEach((r, i) => {
+        const at = isObj(r) && typeof r.id === 'string' ? r.id : `[${i}]`;
+        if (!isObj(r)) {
+            out.push({ file, path: at, level: 'error', what: 'not an object' });
+            return;
+        }
+        if (typeof r.id !== 'string' || !r.id.trim())
+            out.push({ file, path: at, level: 'error', what: 'each tunable has an id' });
+        else if (seen.has(r.id))
+            out.push({ file, path: at, level: 'error', what: 'the id is used twice' });
+        else
+            seen.add(r.id);
+        const range = r.range;
+        if (typeof r.default === 'number') {
+            if (!Array.isArray(range) || range.length !== 2 || range.some((x) => typeof x !== 'number'))
+                out.push({ file, path: at, level: 'warn', what: 'a number with no [low, high] range: the next lane cannot tell a tune from a break' });
+            else if (r.default < range[0] || r.default > range[1])
+                out.push({ file, path: at, level: 'error', what: `default ${r.default} sits outside its range [${range[0]}, ${range[1]}]` });
+            if (typeof r.unit !== 'string' || !r.unit)
+                out.push({ file, path: at, level: 'warn', what: 'no unit' });
+        }
+        if (typeof r.why !== 'string' || r.why.trim().length < 8)
+            out.push({ file, path: at, level: 'warn', what: 'no reason: say why this number (what breaks above and below it)' });
+    });
+    return out;
+}
+export function validateWorldShape(w, file = 'design/world/world.json') {
+    const out = [];
+    if (!isObj(w))
+        return [{ file, path: '', level: 'error', what: 'not a JSON object' }];
+    const rooms = Array.isArray(w.rooms) ? w.rooms : null;
+    if (!rooms || !rooms.length)
+        return [{ file, path: 'rooms', level: 'error', what: 'a world has at least one room' }];
+    const ids = new Set();
+    rooms.forEach((r, i) => {
+        if (!isObj(r) || typeof r.id !== 'string') {
+            out.push({ file, path: `rooms[${i}]`, level: 'error', what: 'each room has an id' });
+            return;
+        }
+        if (ids.has(r.id))
+            out.push({ file, path: `rooms[${i}]`, level: 'error', what: `room id ${r.id} is used twice` });
+        ids.add(r.id);
+    });
+    const edges = Array.isArray(w.doors) ? w.doors : Array.isArray(w.edges) ? w.edges : [];
+    edges.forEach((e, i) => {
+        if (!isObj(e))
+            return;
+        for (const end of ['from', 'to'])
+            if (typeof e[end] === 'string' && !ids.has(e[end]))
+                out.push({ file, path: `doors[${i}].${end}`, level: 'error', what: `names room ${e[end]}, which the world does not have`, suggest: closest(e[end], [...ids]) });
+    });
+    return out;
+}
+const readJson = (p) => {
+    try {
+        return { ok: true, v: JSON.parse(readFileSync(p, 'utf8')) };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+};
+export const SPEC_FILES = { tunables: join('design', 'spec', 'tunables.json'), world: join('design', 'world', 'world.json'), pipeline: join('design', 'pipeline.json') };
+const PLANS = [join('design', 'GDD.md'), 'GAME-DESIGN.md', join('design', 'GAME-DESIGN.md'), join('design', 'plan.md')];
+export function validateGame(root, opts = {}) {
+    const files = [];
+    const out = [];
+    const mp = join(root, 'funpixel.json');
+    let manifest = null;
+    if (!existsSync(mp))
+        out.push({ file: 'funpixel.json', path: '', level: 'error', what: 'missing: every game has one (funtools init writes it)' });
+    else {
+        files.push('funpixel.json');
+        const r = readJson(mp);
+        if (!r.ok)
+            out.push({ file: 'funpixel.json', path: '', level: 'error', what: `not JSON: ${r.error}` });
+        else {
+            out.push(...validateManifest(r.v, opts));
+            manifest = isObj(r.v) ? r.v : null;
+        }
+    }
+    const plan = PLANS.find((p) => existsSync(join(root, p)));
+    if (plan)
+        files.push(plan);
+    else
+        out.push({ file: 'design/GDD.md', path: '', level: 'warn', what: 'no design document: the plan the rest of the game is checked against' });
+    const look = join(root, LOOK_FILE);
+    if (existsSync(look)) {
+        files.push(LOOK_FILE);
+        const r = readJson(look);
+        if (!r.ok)
+            out.push({ file: LOOK_FILE, path: '', level: 'error', what: `not JSON: ${r.error}` });
+        else
+            for (const p of validateLook(r.v))
+                out.push({ file: LOOK_FILE, path: p.token, level: 'error', what: p.what, suggest: p.suggest });
+    }
+    if (existsSync(join(root, ASSET_MANIFEST))) {
+        files.push(ASSET_MANIFEST);
+        try {
+            readAssetManifest(root);
+        }
+        catch (e) {
+            out.push({ file: ASSET_MANIFEST, path: '', level: 'error', what: e.message });
+        }
+    }
+    const tun = join(root, SPEC_FILES.tunables);
+    if (existsSync(tun)) {
+        files.push(SPEC_FILES.tunables);
+        const r = readJson(tun);
+        if (!r.ok)
+            out.push({ file: SPEC_FILES.tunables, path: '', level: 'error', what: `not JSON: ${r.error}` });
+        else
+            out.push(...validateTunables(r.v));
+    }
+    const worldPath = typeof manifest?.world?.file === 'string' ? String(manifest.world.file) : SPEC_FILES.world;
+    if (existsSync(join(root, worldPath))) {
+        files.push(worldPath);
+        const r = readJson(join(root, worldPath));
+        if (!r.ok)
+            out.push({ file: worldPath, path: '', level: 'error', what: `not JSON: ${r.error}` });
+        else {
+            const shape = validateWorldShape(r.v, worldPath);
+            out.push(...shape);
+            if (!shape.length && isObj(r.v) && r.v.format === 'funpixel-world') {
+                try {
+                    for (const f of checkWorld(r.v, sidecarReader(root)).findings)
+                        if (f.status === 'fail' || f.status === 'warn')
+                            out.push({ file: worldPath, path: f.room ?? '', level: f.status === 'fail' ? 'error' : 'warn', what: f.what });
+                }
+                catch (e) {
+                    out.push({ file: worldPath, path: '', level: 'error', what: `the world check broke: ${e.message}` });
+                }
+            }
+        }
+    }
+    else if (manifest?.world !== undefined)
+        out.push({ file: 'funpixel.json', path: 'world', level: 'error', what: `names ${worldPath}, which is not there (funtools world forge writes it)` });
+    const pipe = join(root, SPEC_FILES.pipeline);
+    if (existsSync(pipe)) {
+        files.push(SPEC_FILES.pipeline);
+        const r = readJson(pipe);
+        if (!r.ok)
+            out.push({ file: SPEC_FILES.pipeline, path: '', level: 'error', what: `not JSON: ${r.error}` });
+        else if (!isObj(r.v) || !Array.isArray(r.v.stages))
+            out.push({ file: SPEC_FILES.pipeline, path: 'stages', level: 'error', what: 'a pipeline is { stages: [...] }' });
+    }
+    const md = isObj(manifest?.metadata) ? manifest.metadata : {};
+    if (md.framework === 'pixi' && md.dimension === '3d')
+        out.push({ file: 'funpixel.json', path: 'metadata.dimension', level: 'warn', what: 'a 3d game on the pixi starter: the 3D starters are three and three-world' });
+    if (md.mode === 'multiplayer' && plan && !/multiplayer|\brooms?\b|relay/i.test(readFileSync(join(root, plan), 'utf8')))
+        out.push({ file: plan, path: '', level: 'warn', what: 'funpixel.json says multiplayer and the design document never plans the rooms' });
+    return { files, findings: out, errors: out.filter((f) => f.level === 'error').length, warnings: out.filter((f) => f.level === 'warn').length };
+}

package/dist/score/comfort.js

@@ -0,0 +1,79 @@
+export const COMFORT_SHORT = 360;
+export const CLIP_LOW = 2;
+export const CLIP_HIGH = 253;
+export const BUSY_CEILING = 14;
+export const BUSY_OVER_TARGET = 1.25;
+export const CLIPPED_WARN = 6;
+const round1 = (v) => Math.round(v * 10) / 10;
+const luma = (r, g, b) => 0.299 * r + 0.587 * g + 0.114 * b;
+export function greyAt(p, short = COMFORT_SHORT) {
+    const s = Math.min(1, short / Math.min(p.width, p.height));
+    const W = Math.max(1, Math.round(p.width * s)), H = Math.max(1, Math.round(p.height * s));
+    const sum = new Float64Array(W * H), n = new Uint32Array(W * H);
+    let black = 0, white = 0;
+    const xs = new Uint32Array(p.width);
+    for (let x = 0; x < p.width; x++)
+        xs[x] = Math.min(W - 1, Math.floor((x * W) / p.width));
+    for (let y = 0; y < p.height; y++) {
+        const row = Math.min(H - 1, Math.floor((y * H) / p.height)) * W;
+        for (let x = 0; x < p.width; x++) {
+            const i = (y * p.width + x) * 4;
+            const l = luma(p.data[i], p.data[i + 1], p.data[i + 2]);
+            if (l <= CLIP_LOW)
+                black++;
+            else if (l >= CLIP_HIGH)
+                white++;
+            sum[row + xs[x]] += l;
+            n[row + xs[x]]++;
+        }
+    }
+    for (let i = 0; i < sum.length; i++)
+        sum[i] = n[i] ? sum[i] / n[i] : 0;
+    return { grey: sum, width: W, height: H, black, white };
+}
+export function comfortRead(p, short = COMFORT_SHORT) {
+    const g = greyAt(p, short);
+    let steps = 0, pairs = 0;
+    for (let y = 0; y < g.height; y++)
+        for (let x = 0; x < g.width; x++) {
+            const v = g.grey[y * g.width + x];
+            if (x + 1 < g.width) {
+                steps += Math.abs(v - g.grey[y * g.width + x + 1]);
+                pairs++;
+            }
+            if (y + 1 < g.height) {
+                steps += Math.abs(v - g.grey[(y + 1) * g.width + x]);
+                pairs++;
+            }
+        }
+    const all = p.width * p.height || 1;
+    return {
+        busyness: round1(pairs ? steps / pairs : 0),
+        clipped: round1((100 * (g.black + g.white)) / all), black: round1((100 * g.black) / all), white: round1((100 * g.white) / all),
+        at: { width: g.width, height: g.height }, scaled: Math.min(p.width, p.height) >= short,
+    };
+}
+const band = (xs) => (xs.length ? { min: Math.min(...xs), max: Math.max(...xs) } : null);
+export function comfortVerdict(frames, targets = []) {
+    const t = band(targets.map((r) => r.busyness));
+    const busyLine = round1(t ? Math.min(BUSY_CEILING, t.max * BUSY_OVER_TARGET) : BUSY_CEILING);
+    if (!frames.length)
+        return { verdict: 'not_observed', frames: null, targets: t, busyLine, warnings: [], warned: [], why: 'no game frame was measured' };
+    const warnings = [], warned = new Set();
+    for (const f of frames) {
+        const r = f.read;
+        if (r.busyness > busyLine) {
+            warnings.push(`${f.name}: busy ${r.busyness} (over ${busyLine}: ${t && busyLine < BUSY_CEILING ? `${BUSY_OVER_TARGET}× its targets' busiest ${t.max}` : `the ceiling ${BUSY_CEILING}`}) — calm the texture, not the quality`);
+            warned.add(f.name);
+        }
+        if (r.clipped > CLIPPED_WARN) {
+            warnings.push(`${f.name}: ${r.clipped}% clipped (over ${CLIPPED_WARN}%: ${r.white >= r.black ? `${r.white}% blown white` : `${r.black}% crushed black`}) — lower the bloom or exposure, lift the shadows`);
+            warned.add(f.name);
+        }
+    }
+    const fb = band(frames.map((f) => f.read.busyness));
+    return {
+        verdict: warned.size ? 'warn' : 'calm', frames: fb, targets: t, busyLine, warnings, warned: [...warned],
+        why: `busyness ${fb.min === fb.max ? fb.min : `${fb.min}–${fb.max}`}${t ? ` against the targets' ${t.min === t.max ? t.min : `${t.min}–${t.max}`}` : ' (no target read)'}, line ${busyLine}; clipped warns over ${CLIPPED_WARN}%`,
+    };
+}