@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/look/anim.js

@@ -0,0 +1,206 @@
+import { ACTORS_DOC } from "../walk/judge.js";
+import { PLAYER_WORDS, playerHint, playerSaid } from "./player.js";
+const DEFAULT_PLAYER = { pattern: PLAYER_WORDS, from: 'default', name: null };
+export const grouped = (list, cap = 8) => {
+    const by = new Map();
+    for (const n of list)
+        by.set(n, (by.get(n) ?? 0) + 1);
+    const all = [...by].sort((a, b) => b[1] - a[1]).map(([n, k]) => (k > 1 ? `${n} ×${k}` : n));
+    return all.length > cap ? `${all.slice(0, cap).join(', ')} and ${all.length - cap} more type(s)` : all.join(', ');
+};
+const names = (list) => grouped(list.map((a) => a.name));
+export const LIVING_WORLD = 'skill funpixel-world-and-story, references/living-world.md';
+export function travelVerdicts(living, windowMs = null, walk = null) {
+    if (walk && walk.people) {
+        const text = `people: ${walk.moved} of ${walk.people} moved through space over ${Math.round(walk.seconds)} s of the ${walk.route} walk (walk.json)`;
+        return walk.moved ? [{ status: 'pass', text }] : [{ status: 'warn', text: `A CROWD THAT NEVER TRAVELS: ${text.replace(/^people: /, '')}`, hint: `give each a task loop (haul, patrol, errand, chat, work) that walks them between points (${LIVING_WORLD})` }];
+    }
+    const people = living.filter((a) => a.role === 'person' && a.travels !== undefined);
+    if (!people.length)
+        return [];
+    const span = windowMs ? ` in a ${Math.round(windowMs / 1000)} s window` : '';
+    const longer = windowMs ? ' — a short look: people waiting at a stop read as in place; funtools walk watches the whole run' : '';
+    const moving = people.filter((a) => a.travels);
+    const inPlace = people.filter((a) => !a.travels && a.verdict === 'animated');
+    if (!moving.length && people.length >= 2) {
+        return [{ status: 'warn', text: `A CROWD THAT NEVER TRAVELS: ${people.length} people, ${inPlace.length} animated in place, none moved through space${span}`, hint: `give each a task loop (haul, patrol, errand, chat, work) that walks them between points, the walk clip's rate following their ground speed (${LIVING_WORLD})${longer}`, items: [names(people)] }];
+    }
+    if (inPlace.length)
+        return [{ status: 'note', text: `people: ${moving.length} of ${people.length} move through space${span}; ${inPlace.length} animate in place${longer}`, items: [names(inPlace)] }];
+    return [{ status: 'pass', text: `people: ${moving.length} of ${people.length} move through space${span}` }];
+}
+export function crowdVerdicts(r) {
+    const c = r.crowd;
+    if (!c || !c.people)
+        return [];
+    const out = [];
+    const clones = r.actors.filter((a) => a.role === 'person' && a.hero);
+    if (clones.length) {
+        const what = clones.some((a) => a.hero === 'both') ? "the hero's body and texture (the player's mesh and picture)"
+            : clones.some((a) => a.hero === 'texture') ? "the hero's face (the player's texture)" : "the hero's body (the player's geometry)";
+        const parts = [...new Set(clones.flatMap((a) => a.hero_parts ?? []))].slice(0, 6);
+        out.push({ status: 'warn', text: `HERO CLONES: ${clones.length} of ${c.people} people wear ${what}${parts.length ? `, sharing ${parts.join(', ')}` : ''}`, hint: `a crowd shares a rig, never the hero's face or what is baked into the hero's mesh and picture (a backpack, a badge, the hero's jacket): a body, face, hair and clothes pool of its own, tinted per person, heights 1.55–1.90 m (${LIVING_WORLD})`, items: [names(clones)] });
+    }
+    if (c.people >= 4 && c.looks <= 1)
+        out.push({ status: 'warn', text: `ONE LOOK FOR ${c.people} PEOPLE: every person is made of the same geometry and textures`, hint: `vary faces, hair, colours and heights per person (${LIVING_WORLD})` });
+    else if (c.people >= 2 && !clones.length)
+        out.push({ status: 'pass', text: `crowd: ${c.looks} look(s) across ${c.people} people, none wearing the hero's face` });
+    return out;
+}
+export function flyerVerdicts(living) {
+    const flyers = living.filter((a) => a.flies);
+    if (!flyers.length)
+        return [];
+    const flap = flyers.filter((a) => a.verdict === 'animated');
+    const glide = flyers.filter((a) => a.verdict === 'slides' || a.verdict === 'rigid');
+    if (glide.length)
+        return [{ status: 'warn', text: `FLYERS WITHOUT A FLAP: ${glide.length} of ${flyers.length} move through the air with nothing inside them changing`, hint: `a wing cycle (a 4–8 frame flap, bones, or a vertex flap by distance from the body) and a bank into each turn; mark them flying: true in the actors contract so they are not judged as floating (${LIVING_WORLD})`, items: [names(glide)] }];
+    return [{ status: 'pass', text: `flyers: ${flap.length} of ${flyers.length} flap` }];
+}
+export const GAIT_DESIGN_SPEED = { walk: 0.8, run: 2.3, sneak: 0.4, carry: 0.6, limp: 0.5, old: 0.5, child: 1.0, quadruped: 1.2, flyer: 3 };
+const GAIT_KIND = { quadruped: 'quadruped', flyer: 'flyer' };
+const MOTION_DOC = 'skill funpixel-game-feel, references/motion.md';
+export function gaitVerdicts(r) {
+    const out = [];
+    const secs = r.ms / 1000;
+    for (const a of r.actors) {
+        if (!a.gait)
+            continue;
+        const design = GAIT_DESIGN_SPEED[a.gait];
+        if (design === undefined) {
+            out.push({ status: 'note', text: `${a.name}: gait "${a.gait}" is not a preset (${Object.keys(GAIT_DESIGN_SPEED).join(', ')})`, hint: MOTION_DOC });
+            continue;
+        }
+        if (a.verdict === 'slides')
+            out.push({ status: 'note', text: `${a.name}: declared gait ${a.gait}, but it slides: drive its stride by distance (motion-sample.ts advance + sampleGait)`, hint: MOTION_DOC });
+        const height = a.height ?? (r.engine === 'three' ? (a.role === 'person' || a.role === 'player' ? 1.75 : null) : null);
+        if (!height || !a.travels || !(secs > 0.5))
+            continue;
+        const speed = a.travelled / secs / height;
+        const ratio = speed / design;
+        if (ratio >= 0.6 && ratio <= 1.6)
+            continue;
+        const kind = GAIT_KIND[a.gait] ?? 'biped';
+        const near = Object.keys(GAIT_DESIGN_SPEED).filter((n) => (GAIT_KIND[n] ?? 'biped') === kind).reduce((x, y) => (Math.abs(GAIT_DESIGN_SPEED[y] - speed) < Math.abs(GAIT_DESIGN_SPEED[x] - speed) ? y : x));
+        out.push({ status: 'note', text: `${a.name}: travels ${speed.toFixed(2)} body heights/s against its ${a.gait} preset's ${design} (${ratio.toFixed(1)}×): the feet ${ratio < 0.6 ? 'moonwalk' : 'scramble'}${near !== a.gait ? `; nearer the ${near} preset` : ''} (averaged over ${Math.round(secs)} s, stops included)`, hint: `clipTimeScale(g, speed) or switch preset (${MOTION_DOC})` });
+    }
+    return out;
+}
+export const CUTOUT_HINT = 'a cut-out animates by a frame set whose stride follows ground speed (frames advance by distance, not time), by bending its plane (top sways, feet pinned; squash on landing), by hinged parts (legs, wings, a tail) or a 4–8 frame flap; a mirror flip, a bob, a tilt or an opacity pulse is the picture moving';
+const coef = (v) => {
+    if (v.length < 2)
+        return 0;
+    const m = v.reduce((a, b) => a + b, 0) / v.length;
+    if (!(m > 0))
+        return 0;
+    return Math.sqrt(v.reduce((a, b) => a + (b - m) ** 2, 0) / v.length) / m;
+};
+export function strideSync(chunks) {
+    const ok = chunks.filter(([m, n, s]) => m > 0.05 && s > 0.05 && n >= 0);
+    const metres = ok.reduce((a, c) => a + c[0], 0), swaps = ok.reduce((a, c) => a + c[1], 0);
+    const perMetre = metres > 0 ? Math.round((swaps / metres) * 100) / 100 : null;
+    if (ok.length < 3 || !swaps)
+        return { verdict: 'not_observed', perMetre, speedVaries: false };
+    const speedVaries = coef(ok.map(([m, , s]) => m / s)) >= 0.2;
+    if (!speedVaries)
+        return { verdict: 'not_observed', perMetre, speedVaries };
+    const byM = coef(ok.map(([m, n]) => n / m)), byS = coef(ok.map(([, n, s]) => n / s));
+    return { verdict: byM <= byS ? 'distance' : 'timer', perMetre, speedVaries };
+}
+const RIDES = /\b(kart|car|racer|truck|van|bus|taxi|bike|motorbike|scooter|skateboard|train|tram|cart|wagon|sled|tank|mech|rover|vehicle)s?\b/i;
+const FLIES = /\b(ship|spaceship|rocket|plane|jet|glider|drone|helicopter|balloon|ufo|kite)s?\b/i;
+const ROLLS = /\b(ball|marble|orb|puck|disc|wheel|boulder)s?\b/i;
+const SWIMS = /\b(boat|raft|canoe|kayak|submarine|sub|fish|shark|whale|dolphin)s?\b/i;
+export function heroMoves(p, declared = null) {
+    const said = declared?.trim().toLowerCase();
+    if (said)
+        return /^(walk|run|leg|biped|quadruped|on foot)/.test(said) ? 'walks' : said;
+    if (p.flies || p.gait === 'flyer')
+        return 'flies';
+    const name = p.name.replace(/[_\-.]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2');
+    return RIDES.test(name) ? 'rides' : FLIES.test(name) ? 'flies' : ROLLS.test(name) ? 'rolls' : SWIMS.test(name) ? 'swims' : 'walks';
+}
+export const HERO_WALK_FRAMES = 6;
+export function heroWalkVerdicts(r, declared = null) {
+    const p = r.actors.find((a) => a.role === 'player');
+    if (!p || p.moving_s === undefined)
+        return [];
+    const how = heroMoves(p, declared);
+    if (how !== 'walks')
+        return [{ status: 'pass', text: `hero walk: not judged, ${p.name} ${how} (${declared ? 'funpixel.json life.hero' : p.flies || p.gait === 'flyer' ? 'a flyer' : 'by its name'})` }];
+    const unit = r.engine === 'pixi' ? 'px' : 'm';
+    const far = (p.moved_m ?? 0) > (r.engine === 'pixi' ? 60 : 1);
+    if (!far || !p.deform)
+        return [];
+    const swaps = p.swaps_moving ?? 0;
+    if (!swaps)
+        return [];
+    const out = [];
+    const frames = p.cycle_frames ?? 0;
+    const hint = `a hero that does not walk on legs (it rides, flies, rolls, swims) says so in funpixel.json "life": { "hero": "rides" } and the walk is not judged; a walker: 8–12 pictures a cycle with contact, passing and up poses, frames advanced by distance (one cycle ≈ 0.8 × body height travelled), a bob of 2–4% of the height at twice the step rate; contact and bob are not measured here: watch the walk film (${MOTION_DOC}; ${LIVING_WORLD})`;
+    if (frames < HERO_WALK_FRAMES)
+        out.push({ status: 'warn', text: `HERO WALK POPS: ${p.name} walks on ${frames} picture(s) a cycle (under ${HERO_WALK_FRAMES} reads as poses popping)${p.cutout ? ', a cut-out' : ''}`, hint });
+    const still = p.swaps_still_walk ?? 0;
+    if (still >= 3 && still >= 0.25 * swaps)
+        out.push({ status: 'warn', text: `HERO WALK ON A TREADMILL: ${p.name}'s walk frames swapped ${still} time(s) while it stood still`, hint: 'frames advance by distance travelled, so a standing hero holds its pose (or plays its idle)' });
+    const sync = strideSync(p.chunks ?? []);
+    if (sync.verdict === 'timer')
+        out.push({ status: 'warn', text: `HERO WALK ON A TIMER: ${p.name}'s frames advance with the clock, not the ground (the feet slide as speed changes)`, hint });
+    if (!out.length)
+        out.push({ status: 'pass', text: `hero walk: ${p.name} ${frames} pictures a cycle, ${sync.perMetre ?? '?'} swaps per ${unit}${sync.verdict === 'distance' ? ', stride follows ground speed' : sync.speedVaries ? '' : ' (speed steady: stride sync not observed)'}` });
+    return out;
+}
+const playerMoved = (r) => {
+    const p = r.actors.find((a) => a.role === 'player');
+    return !!p && (p.travels === true || p.travelled > (r.engine === 'pixi' ? 20 : 0.5));
+};
+export const UNSEEN_HINT = 'the sampler reads pictures, bones, morphs, vertices, hinged parts and code-drawn shapes, not a filter or a shader; if they animate that way, mark them "deform": true in the actors contract (__FPX_ACTORS__)';
+export function lifeVerdicts(r, ctx = {}) {
+    if (!r || r.engine === 'none')
+        return [{ status: 'not_observed', text: 'motion vs animation: no scene graph to read (window.__THREEJS_SCENE__ or window.__PIXI_APP__)' }];
+    const all = r.actors.filter((a) => a.role !== 'player');
+    const unseen = all.filter((a) => a.unseen);
+    const living = all.filter((a) => !a.unseen);
+    const out = [];
+    if (unseen.length)
+        out.push({ status: 'not_observed', text: `motion inside not observed for ${unseen.length}: drawn with a filter or shader the sampler cannot read inside`, hint: UNSEEN_HINT, items: [names(unseen)] });
+    if (!living.length && unseen.length) { }
+    else if (!living.length) {
+        out.push({ status: 'not_observed', text: 'motion vs animation: no person or creature found by name', hint: `name them (person, folk, villager, crab, bird…), give each actor its scene node in the actors contract (node), or set funpixel.json "life": { "people": "…", "creatures": "…" } — ${ACTORS_DOC}` });
+    }
+    else {
+        const slides = living.filter((a) => a.verdict === 'slides' && !a.flies);
+        const rigid = living.filter((a) => a.verdict === 'rigid');
+        const still = living.filter((a) => a.verdict === 'still');
+        const animated = living.filter((a) => a.verdict === 'animated');
+        const noIdle = living.filter((a) => a.idle === false);
+        out.push({ status: animated.length === living.length ? 'pass' : 'note', text: `life: ${animated.length} of ${living.length} people and creatures animated (frames, bones, morphs, parts or drawn shapes changing)` });
+        out.push(...travelVerdicts(living, ctx.windowMs ?? null, ctx.walk ?? null), ...crowdVerdicts(r), ...flyerVerdicts(living), ...gaitVerdicts(r));
+        const cutSlides = slides.filter((a) => a.cutout), cutRigid = rigid.filter((a) => a.cutout);
+        if (slides.length) {
+            const all = cutSlides.length === slides.length;
+            out.push({ status: 'warn', text: all ? `CUT-OUTS THAT GLIDE: ${slides.length} painted cut-out(s) travel as one picture (no frame, bend or hinge changing)` : `SLIDES LIKE A STONE: ${slides.length} travel with nothing inside them changing${cutSlides.length ? ` (${cutSlides.length} of them painted cut-outs)` : ''}`, hint: cutSlides.length ? CUTOUT_HINT : 'a walk, scuttle or wing cycle while moving (sheet frames, a rig, parts): never a still picture slid across the ground', items: [names(slides)] });
+        }
+        if (rigid.length) {
+            const all = cutRigid.length === rigid.length;
+            out.push({ status: 'warn', text: all ? `CUT-OUTS ON A STICK: ${rigid.length} painted cut-out(s) only bob, tilt, flip or scale as one picture` : `RIGID: ${rigid.length} only bob, tilt or turn as one picture${cutRigid.length ? ` (${cutRigid.length} of them painted cut-outs)` : ''}`, hint: cutRigid.length ? CUTOUT_HINT : 'a bob of a cut-out reads as a card on a stick; breathing, looking round, shifting weight need parts or frames', items: [names(rigid)] });
+        }
+        if (still.length)
+            out.push({ status: 'warn', text: `STILL: ${still.length} people or creatures never moved or changed`, items: [names(still)] });
+        if (noIdle.length)
+            out.push({ status: 'warn', text: `NO IDLE: ${noIdle.length} stood in place with no idle (breathing, looking around, shifting weight)`, items: [names(noIdle)] });
+        if (r.reactions.near)
+            out.push({ status: 'pass', text: `reactions: ${r.reactions.near} actor(s) react when the player comes near${r.reactions.actors.length ? ` (${grouped(r.reactions.actors.slice(0, r.reactions.near), Infinity)}${r.reactions.actors.length < r.reactions.near ? ` and ${r.reactions.near - r.reactions.actors.length} more` : ''})` : ''}; ${r.reactions.far} change at their own rate wherever the player is` });
+        else if (r.player_found && ctx.acted === false && !playerMoved(r))
+            out.push({ status: 'not_observed', text: `reactions: not judged — judged without the player acting: the player stood still and no input was sent while ${living.length} people and creatures were watched, so nothing they might answer (the player coming near, a lantern lit, a door opened) happened`, hint: 'a reaction to the player\'s action is judged after a view with moment: true in __FPX_VIEWS__ (entered through the rules, it does the action and marks the moment; life watches what answers it); one to the player coming near is judged by `funtools walk`, which moves the player' });
+        else
+            out.push({ status: r.player_found ? 'warn' : 'not_observed', text: r.player_found ? `NO REACTION: no person or creature changed more with the player near than far away (${r.reactions.far} change at their own rate wherever the player is)` : `reactions: no player node found to measure distance from (looked for ${playerSaid(ctx.player ?? DEFAULT_PLAYER)})`, hint: r.player_found ? 'turn heads, step aside, wave, flee: people and creatures must answer the player' : playerHint(ctx.player ?? DEFAULT_PLAYER) });
+    }
+    const p = r.actors.find((a) => a.role === 'player');
+    if (p && !p.deform && p.travelled > 0.5)
+        out.push(p.unseen
+            ? { status: 'not_observed', text: `the player (${p.name}) travelled with nothing seen to change inside it, but it is drawn with a filter or shader the sampler cannot read`, hint: UNSEEN_HINT }
+            : { status: 'warn', text: `the player slides like a stone: it travelled with no frame, bone, part or drawn shape changing${p.cutout ? ' (a painted cut-out moved as one picture)' : ''}`, ...(p.cutout ? { hint: CUTOUT_HINT } : {}) });
+    out.push(...heroWalkVerdicts(r, ctx.hero ?? null));
+    return out;
+}

package/dist/look/boxes.js

@@ -0,0 +1,209 @@
+export const BOXES = {
+    step: 2,
+    flatDetail: 0.15,
+    bigTri: 0.004,
+    meshShare: 0.03,
+    frameShare: 0.2,
+    detailMin: 0.005,
+    facetMax: 0.12,
+    figureBoxes: 2, figureShare: 0.75, figureVerts: 900,
+};
+export const FACETED = /flat[- ]shad(?:ed|ing)|faceted|low[- ]poly|polygonal|flat two-tone|flat-colou?r(?:ed)? facets/i;
+export const FACETED_MESH = /ground|terrain|rock|cliff|hill|mountain|crater|dune|valley|ridge|slope|boulder|stone|land|ice|snow|salt|mesa|canyon|scree/i;
+export function styleLockOf(texts) {
+    for (const [source, text] of texts) {
+        const m = FACETED.exec(text ?? '');
+        if (m)
+            return { faceted: true, phrase: m[0], source };
+    }
+    return { faceted: false, phrase: null, source: null };
+}
+export const isBoxFigure = (f) => f.boxes >= BOXES.figureBoxes && f.boxes >= BOXES.figureShare * f.meshes && f.verts <= BOXES.figureVerts;
+const NOT_STRUCTURE = /ground|terrain|floor|sky|backdrop|panorama|plate|valley|water|sea\b|ocean|horizon|cloud|road|path|street|land/i;
+const lum = (d, i) => 0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2];
+export function cellPixels(img, read, cssWidth) {
+    const { cols, rows } = read.grid;
+    const v = read.view;
+    const k = img.width / (cssWidth || img.width);
+    const n = cols * rows;
+    const detail = new Float32Array(n), rgb = new Uint8Array(n * 3);
+    const cw = (v.width * k) / cols, ch = (v.height * k) / rows;
+    const W = img.width, d = img.data;
+    const L = (x, y) => lum(d, (y * W + x) * 4);
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            const x0 = Math.max(0, Math.floor(v.left * k + c * cw) + 1), x1 = Math.min(W - 2, Math.floor(v.left * k + (c + 1) * cw) - 2);
+            const y0 = Math.max(0, Math.floor(v.top * k + r * ch) + 1), y1 = Math.min(img.height - 2, Math.floor(v.top * k + (r + 1) * ch) - 2);
+            let m = 0, t = 0, R = 0, G = 0, B = 0;
+            for (let y = y0; y <= y1; y++) {
+                for (let x = x0; x <= x1; x++) {
+                    const i = (y * W + x) * 4, l = lum(d, i);
+                    if (Math.abs(L(x + 1, y) - l) + Math.abs(L(x, y + 1) - l) >= BOXES.step)
+                        t++;
+                    m++;
+                    R += d[i];
+                    G += d[i + 1];
+                    B += d[i + 2];
+                }
+            }
+            const at = r * cols + c;
+            if (!m)
+                continue;
+            detail[at] = t / m;
+            rgb[at * 3] = R / m;
+            rgb[at * 3 + 1] = G / m;
+            rgb[at * 3 + 2] = B / m;
+        }
+    }
+    return { detail, rgb };
+}
+const matWords = (m) => {
+    const has = m.map ? 'a texture map' : m.custom ? 'a custom shader' : m.textures ? `${m.textures} texture(s)` : 'no texture';
+    return `${m.type || 'material'}${m.name ? ` "${m.name}"` : ''}, ${has}${m.flat ? ', flat shading' : ''}${m.vertex_colors ? ', vertex colours' : ''}`;
+};
+const hex = (rgb, i) => `#${[rgb[i * 3], rgb[i * 3 + 1], rgb[i * 3 + 2]].map((x) => x.toString(16).padStart(2, '0')).join('')}`;
+export function judgeBoxes(read, img, cssWidth, style = null) {
+    if (!read || read.engine !== 'three' || !read.grid || !read.view || !read.cells?.length)
+        return { observed: false, flat: 0, plain: [], detailed: null, why: read?.error || 'no Three scene to read' };
+    if (!img)
+        return { observed: false, flat: 0, plain: [], detailed: null, why: 'no screenshot' };
+    const { detail: fine, rgb } = cellPixels(img, read, cssWidth);
+    const n = read.cells.length;
+    const per = read.meshes.map(() => ({ cells: 0, flat: 0, fine: 0, detailed: 0, near: Infinity, first: -1 }));
+    let flatAll = 0;
+    for (let k = 0; k < n; k++) {
+        const mi = read.cells[k];
+        if (mi < 0 || !read.meshes[mi] || read.meshes[mi].backdrop)
+            continue;
+        const p = per[mi];
+        p.cells++;
+        p.fine += fine[k];
+        if (fine[k] >= BOXES.flatDetail)
+            p.detailed++;
+        if (fine[k] < BOXES.flatDetail && read.tri[k] >= BOXES.bigTri) {
+            p.flat++;
+            flatAll++;
+            if (read.depth[k] < p.near) {
+                p.near = read.depth[k];
+                p.first = k;
+            }
+        }
+    }
+    const plain = [];
+    const styled = [];
+    let detailed = null;
+    for (const [mi, m] of read.meshes.entries()) {
+        const p = per[mi];
+        if (!p.cells)
+            continue;
+        const detail = Math.round((p.fine / p.cells) * 100) / 100;
+        const painted = m.material.map && detail >= BOXES.flatDetail * 1.5;
+        const faceted = !!style?.faceted && FACETED_MESH.test(`${m.name} ${m.path}`) && m.max_tri <= BOXES.facetMax;
+        if (faceted) {
+            flatAll -= p.flat;
+            if (p.flat / n > BOXES.meshShare)
+                styled.push({ name: m.name, flat: Math.round((p.flat / n) * 1000) / 1000, biggest: m.max_tri });
+        }
+        if (p.flat / n > BOXES.meshShare && !painted && !faceted) {
+            plain.push({
+                name: m.name, kind: m.kind, instances: m.instances, verts: m.verts, flat: Math.round((p.flat / n) * 1000) / 1000, share: Math.round((p.cells / n) * 1000) / 1000,
+                biggest: m.max_tri, near: Number.isFinite(p.near) ? p.near : null, detail, textured: Math.round((p.detailed / p.cells) * 100) / 100, material: matWords(m.material), colour: p.first >= 0 ? hex(rgb, p.first) : m.material.color,
+            });
+        }
+        if (p.cells / n >= BOXES.detailMin && !NOT_STRUCTURE.test(`${m.name} ${m.path}`) && p.flat / p.cells < 0.5 && (!detailed || detail > detailed.detail)) {
+            detailed = { name: m.name, share: Math.round((p.cells / n) * 1000) / 1000, detail, material: matWords(m.material) };
+        }
+    }
+    const weight = (x) => x.flat / (1 + (x.near ?? 50) / 20);
+    plain.sort((a, b) => weight(b) - weight(a));
+    if (detailed && plain.some((x) => x.name === detailed.name))
+        detailed = null;
+    const figures = (read.figures ?? []).filter((f) => f.on && isBoxFigure(f));
+    return { observed: true, flat: Math.round((flatAll / n) * 1000) / 1000, plain, detailed, ...(styled.length ? { styled, style: style } : {}), ...(figures.length ? { figures } : {}) };
+}
+const pc = (v) => `${Math.round(v * 100)}%`;
+export function plainLine(x) {
+    const body = x.kind === 'instanced' ? `instanced ×${x.instances}, ${x.verts} vertices each` : `${x.verts} vertices`;
+    const rest = x.textured >= 0.3 ? `; the rest of it is textured (${pc(x.textured)} of its cells)` : '';
+    return `${x.name} (${body}): ${pc(x.flat)} of the frame in flat colour${x.colour ? ` ${x.colour}` : ''}, triangles up to ${pc(Math.min(1, x.biggest))} of the frame each${x.near !== null ? `, ${Math.round(x.near)} m from the camera` : ''}; ${x.material}${rest}`;
+}
+export const ART_PASS_DOC = 'skill funpixel-world-and-story, references/living-world.md ("Made, not boxes")';
+export function styledLine(names, style) {
+    return `style: faceted (not judged as boxes): ${names.slice(0, 4).join(', ')}${style?.phrase ? ` (the style lock: "${style.phrase}"${style.source ? `, ${style.source}` : ''}; a facet over ${pc(BOXES.facetMax)} of the frame is still judged)` : ''}`;
+}
+export function boxFiguresCheck(figs) {
+    if (!figs.length)
+        return null;
+    return {
+        status: 'warn',
+        text: `BOX FIGURES: ${figs.length} ${figs.length === 1 ? 'person or creature is' : 'people or creatures are'} a handful of boxes (${figs.slice(0, 4).map((f) => f.id).join(', ')}${figs.length > 4 ? ` +${figs.length - 4}` : ''})`,
+        hint: `a person or creature is drawn or modelled (a cut-out from the part sheets, a rigged model), never stacked cuboids, however small on screen (${ART_PASS_DOC})`,
+        items: figs.slice(0, 6).map((f) => `${f.id} (${f.kind}, node ${f.node}): ${f.boxes} cuboid(s) of ${f.meshes} piece(s), ${f.verts} vertices`),
+    };
+}
+export function boxesCheck(f, where = 'the frame') {
+    if (!f.observed)
+        return { status: 'not_observed', text: `boxes: not observed (${f.why ?? 'nothing read'})` };
+    const styled = f.styled?.length ? `; ${styledLine(f.styled.map((x) => x.name), f.style)}` : '';
+    if (!f.plain.length && f.flat <= BOXES.frameShare)
+        return { status: 'pass', text: `boxes: nothing large reads unfinished in ${where} (${pc(f.flat)} flat colour on big triangles)${styled}` };
+    const beside = f.detailed ? ` beside ${f.detailed.name} (detail ${f.detailed.detail}, ${f.detailed.material})` : '';
+    const names = f.plain.slice(0, 3).map((x) => x.name).join(', ');
+    return {
+        status: 'warn',
+        text: f.plain.length
+            ? `BOXES: ${names} read${f.plain.length === 1 ? 's' : ''} as unfinished in ${where}: ${pc(f.plain.reduce((s, x) => s + x.flat, 0))} of it is flat colour on big, plain triangles${beside}`
+            : `BOXES: ${pc(f.flat)} of ${where} is flat colour on big triangles${styled}`,
+        hint: `camera-near geometry is the most detailed, never the plainest: every structure the player passes reads as made (shape detail + textures or decals in the palette), matched to the best-painted asset in the scene (${ART_PASS_DOC})`,
+        items: f.plain.slice(0, 6).map(plainLine),
+    };
+}
+export const boxTally = () => ({ frames: 0, observed: 0, worst: null, meshes: new Map(), styled: new Set(), style: null, figures: new Map() });
+export function tallyBoxes(tally, f, t) {
+    tally.frames++;
+    if (!f.observed)
+        return false;
+    tally.observed++;
+    for (const x of f.styled ?? [])
+        tally.styled.add(x.name);
+    if (f.style)
+        tally.style = f.style;
+    for (const x of f.figures ?? [])
+        if (!tally.figures.has(x.id))
+            tally.figures.set(x.id, x);
+    for (const x of f.plain) {
+        const was = tally.meshes.get(x.name);
+        if (!was)
+            tally.meshes.set(x.name, { worst: x, frames: 1, first_s: Math.round(t * 10) / 10 });
+        else {
+            was.frames++;
+            if (x.flat > was.worst.flat)
+                was.worst = x;
+        }
+    }
+    const score = (b) => b.plain.reduce((s, x) => s + x.flat, 0) + b.flat / 10;
+    if (!tally.worst || score(f) > score(tally.worst.frame)) {
+        tally.worst = { t: Math.round(t * 10) / 10, frame: f };
+        return true;
+    }
+    return false;
+}
+export function walkBoxesCheck(tally, frameFile) {
+    if (!tally.observed)
+        return { status: 'not_observed', text: `boxes: not observed (${tally.frames ? 'no Three scene in the sampled frames' : 'no frame sampled'})` };
+    const list = [...tally.meshes.values()].filter((x) => x.frames >= 2 || tally.observed < 2).sort((a, b) => b.worst.flat * b.frames - a.worst.flat * a.frames);
+    const w = tally.worst;
+    const named = new Set(list.map((x) => x.worst.name));
+    const quiet = [...tally.styled].filter((n) => !named.has(n)), loud = [...tally.styled].filter((n) => named.has(n));
+    const styled = (quiet.length ? `; ${styledLine(quiet, tally.style ?? undefined)}` : '')
+        + (loud.length ? `; ${loud.join(', ')} ${loud.length === 1 ? 'is' : 'are'} faceted by the style lock${tally.style?.phrase ? ` ("${tally.style.phrase}")` : ''} and counted only where one facet covers over ${pc(BOXES.facetMax)} of the frame` : '');
+    if (!list.length)
+        return { status: 'pass', text: `boxes: nothing large read unfinished in ${tally.observed} sampled frame(s) (at most ${pc(w.frame.flat)} flat colour on big triangles)${styled}` };
+    const beside = w.frame.detailed ? `; the most detailed thing in that frame: ${w.frame.detailed.name} (detail ${w.frame.detailed.detail}, ${w.frame.detailed.material})` : '';
+    return {
+        status: 'warn',
+        text: `BOXES: ${list.slice(0, 3).map((x) => x.worst.name).join(', ')} read as unfinished in ${Math.max(...list.map((x) => x.frames))} of ${tally.observed} sampled frames; worst at ${w.t} s with ${pc(w.frame.plain.reduce((s, x) => s + x.flat, 0))} of the frame flat colour on big triangles${frameFile ? ` (${frameFile})` : ''}${beside}${styled}`,
+        hint: boxesCheck({ observed: true, flat: 1, plain: [list[0].worst], detailed: null }).hint,
+        items: list.slice(0, 6).map((x) => `${plainLine(x.worst)} — in ${x.frames} frame(s) from ${x.first_s} s`),
+    };
+}

package/dist/look/dressing.js

@@ -0,0 +1,24 @@
+export const DRESSING = { bare: 0.6, calls: 120, triangles: 300_000, silt: 'Silt\'s first chapter: ~42k instanced flowers, 782 landmark details' };
+const HINT = 'skill funpixel-3d, references/light-and-places.md ("Dressing"): a kit per place, scattered by rule, instanced';
+export function dressingCheck(r, view, viewport) {
+    if (!r || r.engine !== 'three')
+        return { status: 'not_observed', text: `dressing: no Three scene to count in ${view}` };
+    if (!r.at)
+        return { status: 'not_observed', text: `dressing: no player or camera to centre on in ${view}` };
+    const roles = Object.entries(r.by_role).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join(', ') || 'none';
+    const cost = r.calls !== null ? `${r.calls} draw calls, ${Math.round((r.triangles ?? 0) / 1000)}k triangles a frame` : `${Math.round(r.instanced_triangles / 1000)}k instanced triangles`;
+    const facts = `${r.per100} things per 100 m² within ${r.radius} m of the ${r.at.from} (${roles}); ${r.instanced} instanced in the scene; ${cost}`;
+    const items = r.kinds.slice(0, 6).map((k) => `${k.name} (${k.role}): ${k.count} near, ${k.instances} in all, ${k.triangles} triangles each`);
+    const problems = [];
+    if (r.target !== null && r.per100 < r.target * DRESSING.bare)
+        problems.push(`BARE: ${r.per100} things per 100 m² against the place's target ${r.target}`);
+    if (r.on_road)
+        problems.push(`ROAD CLUTTERED: ${r.on_road} thing(s) stand on a declared road (the road stays clear; dress its sides)`);
+    if (viewport === 'phone' && r.calls !== null && (r.calls > DRESSING.calls || (r.triangles ?? 0) > DRESSING.triangles))
+        problems.push(`OVER THE PHONE BUDGET: ${r.calls} calls / ${r.triangles} triangles (budget ${DRESSING.calls} / ${DRESSING.triangles}; instance a kind, merge, or lower the tier's share)`);
+    if (problems.length)
+        return { status: 'warn', text: `${problems.join('; ')} — in ${view}: ${facts}`, hint: HINT, items };
+    if (r.target === null)
+        return { status: 'note', text: `dressing in ${view}: ${facts}; no target stated (state.world.dressing.target, from the place's plan), so no verdict (${DRESSING.silt})`, hint: HINT, items };
+    return { status: 'pass', text: `dressing in ${view}: ${facts}, at or over ${Math.round(DRESSING.bare * 100)}% of its target ${r.target}${r.roads ? ', the road clear' : ''}`, items };
+}

package/dist/look/feedback.js

@@ -0,0 +1,50 @@
+export const FEEDBACK_BARS = {
+    inset: 0.2,
+    over: 0.3,
+    readMs: 800,
+    perWordMs: 300,
+};
+export const wordsIn = (text) => text.replace(/[×x]\s?\d+|[+-]?\d[\d,.  ]*/g, ' ').split(/\s+/).filter((w) => /\p{L}{2,}/u.test(w)).length;
+export const readMs = (words) => Math.max(FEEDBACK_BARS.readMs, words * FEEDBACK_BARS.perWordMs);
+const overlap = (a, b) => Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+export function feedbackFindings(s, i) {
+    const out = [];
+    const area = s.play ?? { x: 0, y: 0, w: s.viewport.w, h: s.viewport.h };
+    const k = FEEDBACK_BARS.inset;
+    const middle = { x: area.x + area.w * k, y: area.y + area.h * k, w: area.w * (1 - 2 * k), h: area.h * (1 - 2 * k) };
+    for (const p of s.pieces) {
+        if (p.control || !p.text)
+            continue;
+        const words = wordsIn(p.text);
+        if (p.transient && words > 0 && p.w * p.h > 0 && overlap(p, middle) > FEEDBACK_BARS.over * p.w * p.h)
+            out.push({
+                kind: 'feedback_over_play', severity: 'warn', where: p.name, number: Math.round((overlap(p, middle) / (p.w * p.h)) * 100) / 100, sample: i,
+                what: `"${p.text.slice(0, 40)}" lands over the middle of the play, where the player is looking at the action: a message lane in the HUD band (one message at a time, away from the player) keeps it readable without hiding the moment`,
+            });
+        const fade = p.fade_ms;
+        if (words > 0 && typeof fade === 'number' && fade > 0 && fade < readMs(words))
+            out.push({
+                kind: 'fast_fade', severity: 'warn', where: p.name, number: fade, sample: i,
+                what: `"${p.text.slice(0, 40)}" is gone after ${(fade / 1000).toFixed(1)} s; ${words} word${words === 1 ? '' : 's'} need about ${(readMs(words) / 1000).toFixed(1)} s to read`,
+            });
+    }
+    return out;
+}
+const STAND_IN = /\b(?:will be (?:here|shown|added)|goes here|placeholder|lorem|ipsum|coming soon|sample text|insert \w+ here)\b/i;
+const MARKS = /\b(?:TODO|TBD|FIXME|WIP|XXX)\b|(?:^|[\s:(])(?:undefined|NaN|null)(?=$|[\s)/.,])|\[object Object\]/;
+export const isPlaceholder = (text) => STAND_IN.test(text) || MARKS.test(text);
+export function placeholderPieces(pieces) {
+    const seen = new Set();
+    return pieces.filter((p) => {
+        if (!p.text || !isPlaceholder(p.text) || seen.has(p.text))
+            return false;
+        seen.add(p.text);
+        return true;
+    });
+}
+export function placeholderFindings(pieces, i) {
+    return placeholderPieces(pieces).map((p) => ({
+        kind: 'placeholder_text', severity: 'warn', where: p.name, number: 0, sample: i,
+        what: `"${p.text.slice(0, 48)}" reads as developer copy on screen: write the player's words, or name the stand-in in the hand-back`,
+    }));
+}

package/dist/look/fit.js

@@ -0,0 +1,123 @@
+export const FIT_VIEWPORTS = [
+    { name: 'wide-short', width: 1700, height: 800, kind: 'desktop' },
+    { name: 'short', width: 1280, height: 600, kind: 'desktop' },
+    { name: 'square', width: 1024, height: 1024, kind: 'desktop' },
+    { name: 'phone-landscape', width: 844, height: 390, kind: 'phone', orientation: 'landscape' },
+    { name: 'phone-portrait', width: 390, height: 844, kind: 'phone', orientation: 'portrait' },
+];
+export const FIT = {
+    tolerance: 28,
+    lineShare: 0.004,
+    blankShare: 0.001,
+    barShare: 0.08,
+    minContentShare: 0.45,
+    bunchedSpan: 0.6,
+    blankMs: 3000,
+    watchMs: 8000,
+    everyMs: 250,
+};
+export function groundOf(img) {
+    const counts = new Map();
+    const { width: w, height: h, data } = img;
+    const add = (x, y) => {
+        const i = (y * w + x) * 4;
+        const k = ((data[i] >> 3) << 10) | ((data[i + 1] >> 3) << 5) | (data[i + 2] >> 3);
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+    };
+    for (let x = 0; x < w; x++) {
+        add(x, 0);
+        add(x, h - 1);
+    }
+    for (let y = 0; y < h; y++) {
+        add(0, y);
+        add(w - 1, y);
+    }
+    let best = 0, key = 0;
+    for (const [k, n] of counts)
+        if (n > best) {
+            best = n;
+            key = k;
+        }
+    return [((key >> 10) & 31) * 8 + 4, ((key >> 5) & 31) * 8 + 4, (key & 31) * 8 + 4];
+}
+export function fitOf(img) {
+    const { width: w, height: h, data } = img;
+    const g = groundOf(img);
+    const rows = new Uint32Array(h), cols = new Uint32Array(w);
+    let painted = 0;
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            if (Math.abs(data[i] - g[0]) > FIT.tolerance || Math.abs(data[i + 1] - g[1]) > FIT.tolerance || Math.abs(data[i + 2] - g[2]) > FIT.tolerance) {
+                rows[y]++;
+                cols[x]++;
+                painted++;
+            }
+        }
+    }
+    const share = painted / (w * h);
+    const rowOn = (y) => rows[y] > Math.max(1, w * FIT.lineShare);
+    const colOn = (x) => cols[x] > Math.max(1, h * FIT.lineShare);
+    let top = 0;
+    while (top < h && !rowOn(top))
+        top++;
+    let bottom = h - 1;
+    while (bottom > top && !rowOn(bottom))
+        bottom--;
+    let left = 0;
+    while (left < w && !colOn(left))
+        left++;
+    let right = w - 1;
+    while (right > left && !colOn(right))
+        right--;
+    const blank = share < FIT.blankShare || top >= h || left >= w;
+    if (blank)
+        return { painted: share, box: null, content_share: 0, bars: { left: 0, right: 0, top: 0, bottom: 0 }, boxed: null, bunched: null, blank: true };
+    const box = { x: left / w, y: top / h, w: (right - left + 1) / w, h: (bottom - top + 1) / h };
+    const bars = { left: left / w, right: (w - 1 - right) / w, top: top / h, bottom: (h - 1 - bottom) / h };
+    const lr = bars.left >= FIT.barShare && bars.right >= FIT.barShare, tb = bars.top >= FIT.barShare && bars.bottom >= FIT.barShare;
+    const near = 0.02;
+    const corner = box.w < FIT.bunchedSpan && box.h < FIT.bunchedSpan
+        ? (bars.left <= near && bars.top <= near ? 'top-left' : bars.right <= near && bars.top <= near ? 'top-right' : bars.left <= near && bars.bottom <= near ? 'bottom-left' : bars.right <= near && bars.bottom <= near ? 'bottom-right' : null)
+        : null;
+    return { painted: share, box, content_share: box.w * box.h, bars, boxed: lr && tb ? 'both' : lr ? 'pillarbox' : tb ? 'letterbox' : null, bunched: corner, blank: false };
+}
+const pct = (x) => `${Math.round(x * 100)}%`;
+export function judgeFit(row) {
+    const f = row.fit;
+    const findings = [];
+    const { width, height } = row.viewport;
+    if (row.first_content_ms === null)
+        findings.push(`nothing but one flat colour for ${FIT.watchMs / 1000} s after opening at ${width}x${height}`);
+    else if (row.first_content_ms > FIT.blankMs)
+        findings.push(`blank for ${(row.first_content_ms / 1000).toFixed(1)} s after opening (over ${FIT.blankMs / 1000} s)`);
+    if (!f)
+        return { ...row, verdict: 'not_observed', findings, why: row.why ?? 'the frame could not be read' };
+    findings.push(...frameFindings(f, row.view ?? 'page'));
+    if (row.loaded && row.entered)
+        findings.push(...frameFindings(row.loaded, 'first screen').map((x) => `first screen: ${x}`));
+    const judged = findings.length ? 'fail' : 'pass';
+    return { ...row, verdict: judged, findings };
+}
+function frameFindings(f, what) {
+    if (f.blank)
+        return [`the ${what} frame is one flat colour`];
+    const out = [];
+    if (f.content_share < FIT.minContentShare)
+        out.push(`content spans ${pct(f.content_share)} of the window (${pct(f.box.w)} wide, ${pct(f.box.h)} tall)`);
+    if (f.bunched)
+        out.push(`content bunched in the ${f.bunched} corner (${pct(f.box.w)} × ${pct(f.box.h)} of the window)`);
+    if (f.boxed)
+        out.push(`${f.boxed === 'both' ? 'bars on all four sides' : f.boxed === 'letterbox' ? 'letterbox bars' : 'pillarbox bars'}: left ${pct(f.bars.left)}, right ${pct(f.bars.right)}, top ${pct(f.bars.top)}, bottom ${pct(f.bars.bottom)} of flat colour`);
+    return out;
+}
+export const WINDOW_MS = 60_000;
+export function fitLine(r) {
+    const size = `${r.viewport.name} ${r.viewport.width}x${r.viewport.height}`;
+    if (r.verdict === 'not_observed')
+        return `${size}: not observed (${r.why ?? 'no frame'})${r.findings.length ? `; ${r.findings.join('; ')}` : ''}`;
+    const f = r.fit;
+    const base = f.blank ? 'one flat colour' : `content ${pct(f.content_share)} of the window${r.canvas_share !== null ? `, canvas ${pct(r.canvas_share)}` : ''}`;
+    const first = r.first_content_ms === null ? 'never painted in the watch' : `first paint ${(r.first_content_ms / 1000).toFixed(1)} s (headless on this machine)`;
+    return `${size} (${r.entered ? `\`${r.view}\`` : 'as loaded'}): ${base}, ${first}${r.findings.length ? ` — ${r.findings.join('; ')}` : ''}`;
+}