@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/vendor/verify/src/page/grounding.js

@@ -0,0 +1,448 @@
+// Is everything big standing on the ground (owner, 2 Oct, one game's round 4: "the spacecraft must
+// not stay in the air if it's landed" — the walk said "floating: none" because it only read actors).
+// For the large props and the vehicles of a Three scene: where each one touches down (the lowest
+// vertices of its mesh, cell by cell under it, or the bottom corners of its box), read by a vertical ray
+// against the SURFACES under it, and how far it is above (hovering) or below (sunk) the nearest one. A
+// thing resting on another (a stacked container) is held, not hovering.
+//
+// The surfaces (lane J4, one game's round 5: a deck, a ramp, its railing and the gantry's trestles read
+// "sunk" against the crater floor under them, and the landed ship "41 m over a drop" beside its pad):
+//   terrain   meshes named ground, terrain, floor, road… (the `ground` regex)
+//   supports  built things people stand on: a mesh named deck, pad, platform, ramp, bridge, pier, dock,
+//             floor, street, walkway, stairs… (a word of its name; a leg, post or trestle is not one); one
+//             the actors contract marks (`supports: [names]` at the top of the answer, or `ground: true` /
+//             `support: true` on an entry); and one the player or a person was found standing on (a ray
+//             down from their feet, remembered across calls in window.__FPX_STOOD_ON__)
+// A thing is judged against the NEAREST surface below where it touches down (a ship on a pad over a
+// crater stands on the pad, not on the crater floor). Sunk = it goes through terrain, or through a deck
+// it rises above. Not sunk: a leg, trestle, piling or post going down into a pit whose top meets a
+// support (braced: held by that support). A railing, kerb or skirt built onto a support within 1.5 m of
+// it is attached (held).
+//
+// What is judged: a node named like a vehicle (ship, craft, crawler, truck…) as one body (its whole
+// subtree), and every other mesh or instance that is big (footprint ≥ min_size, height ≥ 1 m, under
+// 80 m) and is a volume or a painted cut-out (a thin plane counts only with a texture map). Not
+// judged: the terrain and the supports, backdrops, sprites, see-through glows, flyers by name, and
+// anything the actors contract or a name marks flying. The contract can mark a node `landed: true`
+// (judged whatever its size) or `flying: true`; a name or contract type with landed|parked|docked reads
+// as landed. A contract entry is linked to its mesh by `node` or `mesh`, else by its id (`ship-lateShow`
+// is the mesh `lateShow`: a word of the id, or for a machine or a landed entry, the id containing the
+// name or the name the id); a linked landed entry's `ground` (a number: the height under its feet) is a
+// surface under its footprint and its x/z the centre of its footprint.
+// A cut-out's picture may start above its plane's bottom edge (transparent rows): the lowest opaque
+// row of its map is read (when the image can be drawn) and the bottom raised to it.
+//
+// Part of @funpixel/verify: one function expression of one argument. See mechanic_check.js for the
+// calling convention.
+//
+// a = { min_size (m, 2.5), vehicles, flyers, ground: regex sources; max (things, 300);
+//       ignore: node names already judged elsewhere (the actors contract's); supports: more support
+//       mesh names (the caller's) }
+//
+// Answers JSON:
+//   engine — three | none;  error
+//   ground — the terrain meshes' names ([] with no supports either = none found: not observed)
+//   supports — [{ name, why: name|contract|stood }] the built surfaces read as ground
+//   things — [{ name, kind: vehicle|prop, hint: landed|null, instance, contract (the linked entry's id), size: { w, h, d },
+//               at: { x, y, z } (bottom centre), ground (under the centre, or null), support (the surface's mesh), gap
+//               (bottom − ground, m), corners (gaps where it touches down, null where nothing is under), held (by),
+//               verdict: grounded|hovering|sunk|overhang|held|no_ground, alpha_floor, on (in front of the camera),
+//               nearest / farthest ({ x, z, gap }: the touch-down points with the least and the most gap, null when
+//               nothing is under it), deepest ({ x, z, depth }: the point most sunk, null when none is),
+//               tolerance ({ touch, drop, sink }, m: a point within `touch` of a surface touches it; over a drop =
+//               most points more than `drop` above; sunk = most points more than `sink` through) }]
+(a) => {
+  const out = { engine: 'none', error: '', ground: [], supports: [], things: [] };
+  const scene = window.__THREEJS_SCENE__ || (window.scene && window.scene.isScene ? window.scene : null);
+  if (!scene || !scene.isObject3D) { out.error = 'no Three scene (window.__THREEJS_SCENE__)'; return JSON.stringify(out); }
+  out.engine = 'three';
+  const MIN = a.min_size || 2.5, MAX = a.max || 300;
+  const VEH = new RegExp(a.vehicles || 'ship|vehicle|craft|crawler|truck|\\bcar\\b|cart|wagon|boat|train|rover|shuttle|lander|lorry|\\bbus\\b|\\btank\\b|plane|jeep|\\bvan\\b|tractor|buggy|mech', 'i');
+  const FLY = new RegExp(a.flyers || 'flying|fly|hover|airborne|drone|kite|bird|gull|moth|bat\\b|crow|owl|whale|cloud|sky|sun\\b|moon\\b|stars?\\b|balloon|blimp|zeppelin|glow|light|halo|smoke|steam|dust|spark|particle', 'i');
+  const LANDED = /landed|parked|docked|grounded|wreck/i;
+  const GROUND = new RegExp(a.ground || 'ground|terrain|floor|land(?!ed|ing)|heightmap|dune|island|seabed|road|street|plaza|apron|pier|dock(?!ed)', 'i');
+  const BACKDROP = /sky|backdrop|panorama|background|horizon|skybox|dome/i;
+  // Words of a name: camelCase and separators split ("landingPad" → landing, pad; "padLeg" → pad, leg).
+  const words = (s) => String(s || '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  const set = (s) => new Set(s.split(' '));
+  const SUPPORT_W = set('deck decks pad pads platform platforms ramp ramps bridge pier piers dock docks wharf quay jetty boardwalk walkway gangway catwalk floor floors street streets stair stairs step steps');
+  const LEG_W = set('trestle trestles leg legs piling pilings pile piles post posts pylon pylons pillar pillars column columns strut struts stilt stilts footing footings brace braces truss trusses');
+  const ATTACHED_W = set('rail rails railing railings handrail handrails guardrail fence fences balustrade banister barrier kerb kerbs curb curbs toe skirt edge trim girder girders beam beams cable cables pipe pipes gutter');
+  const hasWord = (nm, W) => words(nm).some((w) => W.has(w));
+  // A support by its name: the head word (the last, "rampDeck", "landingPad") is a support word, or a support
+  // word with only a qualifier after it ("street_main", "deck01"); "padCrates" and "padLeg" are not supports.
+  const QUAL = set('main top base surface mesh geo geometry upper lower left right north south east west near far big small inner outer a b c');
+  const supportByName = (nm) => {
+    const w = words(nm).filter((x) => !/^\d+$/.test(x));
+    if (!w.length || w.some((x) => LEG_W.has(x))) return false;
+    let i = w.length - 1;
+    while (i > 0 && QUAL.has(w[i])) i--;
+    return SUPPORT_W.has(w[i]);
+  };
+  const ignore = new Set(Array.isArray(a.ignore) ? a.ignore.map(String) : []);
+  const V = scene.position.constructor;
+  scene.updateMatrixWorld && scene.updateMatrixWorld();
+
+  const seeThrough = (m) => !m || m.visible === false || m.colorWrite === false || (m.transparent && (m.depthWrite === false || (typeof m.opacity === 'number' && m.opacity < 0.5)));
+  const visibleChain = (o) => { for (let n = o; n; n = n.parent) if (n.visible === false) return false; return true; };
+  const nameOf = (o) => o.name || (o.parent && o.parent.name) || '';
+  const pathNames = (o) => { const p = []; for (let n = o; n && !n.isScene; n = n.parent) if (n.name) p.push(n.name); return p; };
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+  // ---- the actors contract: hints, supports, and each entry linked to its mesh ----------------------
+  const names = new Set();
+  scene.traverse((o) => { if (o.name) names.add(o.name); });
+  const hints = new Map(), contractNodes = new Set(), contractSupports = new Set(), linked = new Map();
+  let actorFeet = [];
+  try {
+    const f = window.__FPX_ACTORS__;
+    const got = typeof f === 'function' ? f() : f;
+    const list = got && Array.isArray(got.actors) ? got.actors : Array.isArray(got) ? got : [];
+    if (got && Array.isArray(got.supports)) for (const s of got.supports) if (typeof s === 'string' && s) contractSupports.add(s);
+    for (const x of list) {
+      if (!x || typeof x !== 'object') continue;
+      const id = typeof x.id === 'string' ? x.id : '';
+      const explicit = typeof x.node === 'string' && x.node ? x.node : typeof x.mesh === 'string' && x.mesh ? x.mesh : '';
+      const kindWord = String(x.kind || '');
+      const landedHint = x.landed === true || x.grounded === true || LANDED.test(String(x.type || '')) || LANDED.test(id);
+      const machine = /machine|vehicle/i.test(kindWord) || VEH.test(id) || VEH.test(String(x.type || ''));
+      // The mesh it names: node/mesh, else the id or a word of it, else (a machine or a landed thing) containment.
+      let node = explicit;
+      if (!node && id) {
+        const lid = id.toLowerCase(), toks = new Set(id.split(/[-_:#./ ]+/).map((t) => t.toLowerCase()).filter(Boolean));
+        let best = '', score = 0;
+        for (const n of names) {
+          const ln = n.toLowerCase();
+          const sc = ln === lid ? 3 : toks.has(ln) ? 2 : (machine || landedHint) && ln.length >= 4 && (lid.includes(ln) || ln.includes(lid)) ? 1 : 0;
+          if (sc > score || (sc === score && sc > 0 && n.length > best.length)) { best = n; score = sc; }
+        }
+        node = best;
+      }
+      if (x.ground === true || x.support === true) { if (node) contractSupports.add(node); continue; }
+      const feet = { x: num(x.x), y: num(x.y), z: num(x.z) };
+      const p = x.pos || x.position || x.feet;
+      if (Array.isArray(p)) { feet.x = num(p[0]); feet.y = num(p[1]); feet.z = num(p[2]); } else if (p && typeof p === 'object') { feet.x = num(p.x); feet.y = num(p.y); feet.z = num(p.z); }
+      const flies = x.flying === true || x.flies === true;
+      if (/player|person|people|folk|npc|creature|animal|hero|human|child|kid/i.test(kindWord) && !flies && feet.x !== null && feet.y !== null && feet.z !== null) actorFeet.push({ ...feet, node });
+      if (!node) continue;
+      // Only a named node hands its judging to walk (the contract's positions); a linked id lends its hints.
+      if (explicit) contractNodes.add(node);
+      if (flies) hints.set(node, 'flying');
+      else if (landedHint) hints.set(node, 'landed');
+      const l = linked.get(node) || [];
+      l.push({ id, ground: num(x.ground), x: feet.x, z: feet.z, machine });
+      linked.set(node, l);
+    }
+  } catch (e) { /* no contract */ }
+  actorFeet = actorFeet.slice(0, 40);
+
+  // ---- the surfaces: terrain by name, supports by name, contract or a body standing on them ----------
+  let stood = window.__FPX_STOOD_ON__;
+  if (!(stood instanceof Set)) { stood = new Set(Array.isArray(stood) ? stood : []); try { window.__FPX_STOOD_ON__ = stood; } catch (e) { /* frozen window */ } }
+  for (const s of Array.isArray(a.supports) ? a.supports : []) if (typeof s === 'string') stood.add(s);
+  const supportWhy = (nm) => (contractSupports.has(nm) ? 'contract' : supportByName(nm) ? 'name' : stood.has(nm) ? 'stood' : null);
+  const landedName = (nm) => hints.get(nm) === 'landed' || LANDED.test(nm) || VEH.test(nm);
+  const surfaceOk = (o) => (o.isMesh || o.isInstancedMesh) && !o.isSkinnedMesh && !o.isSprite && o.geometry && visibleChain(o) && !BACKDROP.test(nameOf(o));
+  const isTerrain = (o) => GROUND.test(nameOf(o));
+  const isSupport = (o) => { const nm = nameOf(o); return !isTerrain(o) && !landedName(nm) && supportWhy(nm) !== null; };
+  const surfaces = [];
+  scene.traverse((o) => { if (surfaceOk(o) && (isTerrain(o) || isSupport(o))) { const m = Array.isArray(o.material) ? o.material[0] : o.material; if (!seeThrough(m) || isTerrain(o)) surfaces.push(o); } });
+
+  // Triangles of a mesh in world space (instances unrolled), handed to `fn(A, B, C)`.
+  const eachTri = (g, fn, cap) => {
+    const pos = g.geometry.attributes && g.geometry.attributes.position; if (!pos) return;
+    const idx = g.geometry.index ? g.geometry.index.array : null;
+    const n = Math.floor((idx ? idx.length : pos.count) / 3);
+    const inst = g.isInstancedMesh ? g.count : 1;
+    let k = 0;
+    for (let i = 0; i < inst && k < cap; i++) {
+      const M = g.matrixWorld.clone ? g.matrixWorld.clone() : g.matrixWorld;
+      if (g.isInstancedMesh && M.multiply) { const im = M.clone(); im.fromArray(g.instanceMatrix.array, i * 16); M.multiply(im); }
+      const w = (q) => new V(pos.getX(q), pos.getY(q), pos.getZ(q)).applyMatrix4(M);
+      for (let t = 0; t < n && k < cap; t++, k++) fn(w(idx ? idx[t * 3] : t * 3), w(idx ? idx[t * 3 + 1] : t * 3 + 1), w(idx ? idx[t * 3 + 2] : t * 3 + 2));
+    }
+  };
+  // The height of triangle T at (x, z), or null when (x, z) is outside it.
+  const yIn = (T, x, z) => {
+    const [ax, ay, az, bx, by, bz, cx, cy, cz] = T;
+    const d = (bz - cz) * (ax - cx) + (cx - bx) * (az - cz);
+    if (Math.abs(d) < 1e-12) return null;
+    const u = ((bz - cz) * (x - cx) + (cx - bx) * (z - cz)) / d, v = ((cz - az) * (x - cx) + (ax - cx) * (z - cz)) / d, w = 1 - u - v;
+    if (u < -1e-6 || v < -1e-6 || w < -1e-6) return null;
+    return u * ay + v * by + w * cy;
+  };
+
+  // Bodies standing on a mesh make it a support: a ray down from each actor's feet finds a surface within 0.4 m under
+  // them (not terrain, not a support yet, never a vehicle or a landed thing: those stay judged).
+  if (actorFeet.length) {
+    const cands = [];
+    scene.traverse((o) => {
+      if (!surfaceOk(o) || isTerrain(o) || isSupport(o) || landedName(nameOf(o)) || hints.get(nameOf(o)) === 'flying') return;
+      const m = Array.isArray(o.material) ? o.material[0] : o.material; if (seeThrough(m)) return;
+      const g = o.geometry; if (!g.boundingBox && g.computeBoundingBox) g.computeBoundingBox(); if (!g.boundingBox) return;
+      const bb = g.boundingBox, b = { x0: Infinity, y0: Infinity, z0: Infinity, x1: -Infinity, y1: -Infinity, z1: -Infinity };
+      if (o.isInstancedMesh) return; // instances (posts, crates) are not walked on here
+      for (let i = 0; i < 8; i++) { const p = new V(i & 1 ? bb.max.x : bb.min.x, i & 2 ? bb.max.y : bb.min.y, i & 4 ? bb.max.z : bb.min.z).applyMatrix4(o.matrixWorld); b.x0 = Math.min(b.x0, p.x); b.y0 = Math.min(b.y0, p.y); b.z0 = Math.min(b.z0, p.z); b.x1 = Math.max(b.x1, p.x); b.y1 = Math.max(b.y1, p.y); b.z1 = Math.max(b.z1, p.z); }
+      cands.push({ o, b });
+    });
+    for (const f of actorFeet) {
+      let best = null, by = -Infinity;
+      for (const { o, b } of cands) {
+        if (f.x < b.x0 || f.x > b.x1 || f.z < b.z0 || f.z > b.z1 || b.y1 < f.y - 0.4 || b.y0 > f.y + 0.3) continue;
+        if (f.node && pathNames(o).includes(f.node)) continue; // its own body
+        eachTri(o, (A, B, C) => { const y = yIn([A.x, A.y, A.z, B.x, B.y, B.z, C.x, C.y, C.z], f.x, f.z); if (y !== null && y <= f.y + 0.3 && y >= f.y - 0.4 && y > by) { by = y; best = o; } }, 200000);
+      }
+      if (best && nameOf(best)) { stood.add(nameOf(best)); if (!surfaces.includes(best)) surfaces.push(best); }
+    }
+  }
+  out.ground = [...new Set(surfaces.filter(isTerrain).map(nameOf))];
+  const supNames = [...new Set(surfaces.filter((o) => !isTerrain(o)).map(nameOf))];
+  out.supports = supNames.map((name) => ({ name, why: supportWhy(name) || 'stood' }));
+
+  // Triangles bucketed on x/z, cached across calls while the surfaces stay the same.
+  const KEY = '__FPX_GROUND_TRIS__';
+  const stamp = surfaces.map((g) => `${g.uuid}:${g.geometry.uuid}:${g.geometry.attributes.position ? g.geometry.attributes.position.count : 0}:${isTerrain(g) ? 't' : 's'}`).join('|');
+  let G = window[KEY];
+  if (!G || G.stamp !== stamp) {
+    const CELL = 4, buckets = new Map(), tris = [], wide = [], meta = [];
+    for (const g of surfaces) {
+      const terr = isTerrain(g), nm = nameOf(g);
+      eachTri(g, (A, B, C) => {
+        const ti = tris.length; tris.push([A.x, A.y, A.z, B.x, B.y, B.z, C.x, C.y, C.z]); meta.push({ terr, nm });
+        const x0 = Math.floor(Math.min(A.x, B.x, C.x) / CELL), x1 = Math.floor(Math.max(A.x, B.x, C.x) / CELL);
+        const z0 = Math.floor(Math.min(A.z, B.z, C.z) / CELL), z1 = Math.floor(Math.max(A.z, B.z, C.z) / CELL);
+        if ((x1 - x0 + 1) * (z1 - z0 + 1) > 400) { wide.push(ti); return; } // a big low-poly face: asked every time
+        for (let x = x0; x <= x1; x++) for (let z = z0; z <= z1; z++) { const k = `${x},${z}`; const l = buckets.get(k); if (l) l.push(ti); else buckets.set(k, [ti]); }
+      }, 2000000 - tris.length);
+    }
+    G = { stamp, CELL, buckets, tris, wide, meta };
+    try { window[KEY] = G; } catch (e) { /* frozen window */ }
+  }
+  // Every surface under (x, z): [{ y, terr, nm }], highest first.
+  const surfAt = (x, z) => {
+    const l = G.buckets.get(`${Math.floor(x / G.CELL)},${Math.floor(z / G.CELL)}`) || [];
+    const res = [];
+    for (const ti of l.length ? l.concat(G.wide) : G.wide) { const y = yIn(G.tris[ti], x, z); if (y !== null) res.push({ y, terr: G.meta[ti].terr, nm: G.meta[ti].nm }); }
+    return res.sort((p, q) => q.y - p.y);
+  };
+
+  // ---- the lowest opaque row of a cut-out's picture --------------------------------------------------
+  const floors = window.__FPX_ALPHA_FLOORS__ || new Map();
+  try { window.__FPX_ALPHA_FLOORS__ = floors; } catch (e) { /* ignore */ }
+  // { floor: share of the height below the lowest opaque row, u0/u1: the opaque span of the bottom rows }.
+  const NONE = { floor: 0, u0: 0, u1: 1 };
+  const alphaFloor = (mat) => {
+    const map = mat && mat.map, img = map && map.image;
+    if (!img || typeof document === 'undefined' || !document.createElement) return NONE;
+    // A sheet frame (repeat/offset) or an unflipped texture: the whole image is not the picture.
+    if (map.flipY === false || (map.repeat && (map.repeat.x !== 1 || map.repeat.y !== 1))) return NONE;
+    const key = img.currentSrc || img.src || map.uuid;
+    if (floors.has(key)) return floors.get(key);
+    let r = NONE;
+    try {
+      const c = document.createElement('canvas'), H = 64, W = 64;
+      c.width = W; c.height = H;
+      const ctx = c.getContext('2d'); ctx.drawImage(img, 0, 0, W, H);
+      const d = ctx.getImageData(0, 0, W, H).data;
+      const opaque = (x, y) => d[(y * W + x) * 4 + 3] > 128;
+      let low = -1;
+      for (let y = H - 1; y >= 0 && low < 0; y--) for (let x = 0; x < W; x++) if (opaque(x, y)) { low = y; break; }
+      if (low >= 0) {
+        // The span the picture stands on: opaque columns within its lowest 6% (legs, wheels, a hull's keel).
+        let u0 = W, u1 = -1;
+        for (let y = low; y >= Math.max(0, low - 3); y--) for (let x = 0; x < W; x++) if (opaque(x, y)) { u0 = Math.min(u0, x); u1 = Math.max(u1, x); }
+        r = { floor: (H - 1 - low) / H, u0: u0 / W, u1: (u1 + 1) / W };
+      }
+    } catch (e) { r = NONE; }
+    floors.set(key, r);
+    return r;
+  };
+
+  // ---- the things to judge ----------------------------------------------------------------------------
+  // A box: its world bounds and the four lowest of its eight corners (the footprint as turned, not the bounds).
+  const boxOf = (o, M) => {
+    const g = o.geometry;
+    if (!g.boundingBox && g.computeBoundingBox) g.computeBoundingBox();
+    const bb = g.boundingBox; if (!bb) return null;
+    const b = { x0: Infinity, y0: Infinity, z0: Infinity, x1: -Infinity, y1: -Infinity, z1: -Infinity, foot: [] };
+    const pts = [];
+    for (let i = 0; i < 8; i++) {
+      const p = new V(i & 1 ? bb.max.x : bb.min.x, i & 2 ? bb.max.y : bb.min.y, i & 4 ? bb.max.z : bb.min.z).applyMatrix4(M);
+      pts.push(p);
+      b.x0 = Math.min(b.x0, p.x); b.y0 = Math.min(b.y0, p.y); b.z0 = Math.min(b.z0, p.z); b.x1 = Math.max(b.x1, p.x); b.y1 = Math.max(b.y1, p.y); b.z1 = Math.max(b.z1, p.z);
+    }
+    b.foot = pts.sort((p, q) => p.y - q.y).slice(0, 4).map((p) => [p.x, p.z]);
+    return b;
+  };
+  const grow = (b, c) => {
+    if (!c) return b;
+    if (!b) return { ...c };
+    b.x0 = Math.min(b.x0, c.x0); b.y0 = Math.min(b.y0, c.y0); b.z0 = Math.min(b.z0, c.z0); b.x1 = Math.max(b.x1, c.x1); b.y1 = Math.max(b.y1, c.y1); b.z1 = Math.max(b.z1, c.z1);
+    b.foot = [[b.x0, b.z0], [b.x1, b.z0], [b.x0, b.z1], [b.x1, b.z1]];
+    return b;
+  };
+  // Where a single mesh touches down: the lowest vertex in each cell of a grid over its footprint (a long
+  // ramp railing touches down all along the ramp, not at its box's lowest corner). null for a big mesh.
+  const contactsOf = (o, b) => {
+    const pos = o.geometry.attributes && o.geometry.attributes.position;
+    if (!pos || pos.count > 120000) return null;
+    const cell = Math.max(0.5, Math.max(b.x1 - b.x0, b.z1 - b.z0) / 10), step = Math.max(1, Math.floor(pos.count / 6000));
+    const low = new Map(), M = o.matrixWorld;
+    for (let i = 0; i < pos.count; i += step) {
+      const p = new V(pos.getX(i), pos.getY(i), pos.getZ(i)).applyMatrix4(M);
+      const k = `${Math.floor(p.x / cell)},${Math.floor(p.z / cell)}`;
+      const was = low.get(k); if (!was || p.y < was[1]) low.set(k, [p.x, p.y, p.z]);
+    }
+    return [...low.values()];
+  };
+  const flatOf = (o) => { const g = o.geometry; if (!g.boundingBox && g.computeBoundingBox) g.computeBoundingBox(); const bb = g.boundingBox; return bb ? Math.min(bb.max.x - bb.min.x, bb.max.y - bb.min.y, bb.max.z - bb.min.z) < 1e-3 : false; };
+  // Hung or carried by design: a crane's load, a lamp, a sign, a flag (judged only when marked landed).
+  const HUNG = new RegExp(a.hung || 'load|cargo|hook|cable|chain|rope|lamp|lantern|sign|flag|banner|bunting|awning|wire', 'i');
+  // An outline shell (an inverted hull drawn back-faced) is the body it outlines, not another body.
+  const outline = (m) => !!m && m.side === 1;
+  const surfaceSet = new Set(surfaces);
+  const notThing = (o) => surfaceSet.has(o) || (!isTerrain(o) && supportWhy(nameOf(o)) !== null && !landedName(nameOf(o)));
+  const linkOf = (nm, up) => { for (const n of [nm, ...up]) { const l = linked.get(n); if (l) return l; } return null; };
+  const things = [];
+  const taken = new Set();
+  // Vehicles by name (or a landed hint): the whole subtree is one body.
+  scene.traverse((o) => {
+    if (things.length >= MAX || o === scene || o.isCamera || o.isLight || taken.has(o)) return;
+    const nm = o.name || '';
+    if (!nm || ignore.has(nm) || GROUND.test(nm) || BACKDROP.test(nm) || notThing(o) || !visibleChain(o)) return;
+    const up = pathNames(o.parent || o).filter((p) => p !== nm);
+    const hint = hints.get(nm) || up.map((p) => hints.get(p)).find(Boolean) || (LANDED.test(nm) ? 'landed' : null);
+    // An actor of the contract (or a part of one) is judged by walk from the contract, unless marked landed.
+    if (hint === 'flying' || ((contractNodes.has(nm) || up.some((p) => contractNodes.has(p))) && hint !== 'landed')) return;
+    if (!VEH.test(nm) && hint !== 'landed') return;
+    if (FLY.test(nm) && hint !== 'landed') return;
+    let b = null, picture = null;
+    o.traverse((c) => {
+      if (!(c.isMesh || c.isInstancedMesh) || c.isSprite || !c.geometry) return;
+      const m = Array.isArray(c.material) ? c.material[0] : c.material;
+      if (seeThrough(m) || outline(m)) return;
+      b = grow(b, boxOf(c, c.matrixWorld)); if (!picture && m && m.map) picture = c; taken.add(c);
+    });
+    if (!b) return;
+    if (picture && o === picture) b = boxOf(o, o.matrixWorld);
+    taken.add(o);
+    const link = linkOf(nm, up);
+    things.push({ name: nm, kind: 'vehicle', hint, instance: null, b, picture, mesh: null, link });
+  });
+  // Big props: single meshes first, then instances (a town of instanced crates must not crowd the rest out).
+  const singles = [], instanced = [];
+  scene.traverse((o) => {
+    if (taken.has(o) || !(o.isMesh || o.isInstancedMesh) || o.isSprite || o.isSkinnedMesh || !o.geometry || !visibleChain(o) || notThing(o)) return;
+    (o.isInstancedMesh ? instanced : singles).push(o);
+  });
+  for (const o of [...singles, ...instanced]) {
+    if (things.length >= MAX) break;
+    const nm = nameOf(o), path = pathNames(o);
+    if (ignore.has(nm) || path.some((p) => GROUND.test(p) || BACKDROP.test(p))) continue;
+    const hint = hints.get(o.name) || path.map((p) => hints.get(p)).find(Boolean) || (LANDED.test(nm) ? 'landed' : null);
+    if (hint !== 'landed' && (hint === 'flying' || FLY.test(nm) || HUNG.test(nm) || path.some((p) => contractNodes.has(p)))) continue;
+    const mats = Array.isArray(o.material) ? o.material : [o.material];
+    if (mats.every(seeThrough) || outline(mats[0])) continue;
+    const flat = flatOf(o);
+    if (flat && !(mats[0] && mats[0].map)) continue; // a bare plane (an awning, a decal) is not a body
+    const n = o.isInstancedMesh ? Math.min(o.count, 400) : 1;
+    const link = linkOf(o.name || nm, path);
+    for (let i = 0; i < n && things.length < MAX; i++) {
+      let M = o.matrixWorld;
+      if (o.isInstancedMesh) { M = o.matrixWorld.clone(); const im = o.matrixWorld.clone(); im.fromArray(o.instanceMatrix.array, i * 16); M.multiply(im); }
+      const b = boxOf(o, M); if (!b) continue;
+      const w = b.x1 - b.x0, h = b.y1 - b.y0, d = b.z1 - b.z0;
+      if (hint !== 'landed' && (Math.max(w, d) < MIN || h < 1 || Math.max(w, h, d) > 80)) continue;
+      const kind = VEH.test(nm) || (link && link.some((l) => l.machine)) ? 'vehicle' : 'prop';
+      things.push({ name: nm, kind, hint, instance: o.isInstancedMesh ? i : null, b, picture: flat ? o : null, mesh: o.isInstancedMesh || flat ? null : o, link });
+    }
+  }
+
+  // ---- judge ---------------------------------------------------------------------------------------------
+  const cam = window.camera || window.__THREEJS_CAMERA__ || null;
+  const r2 = (v) => (v === null ? null : Math.round(v * 100) / 100);
+  // Many touch-down points: eight of them, lowest to highest (the least and the most kept).
+  const spread = (l) => { if (l.length <= 8) return l; const k = l.filter((c) => c !== null).sort((p, q) => p - q); return k.length <= 8 ? k : Array.from({ length: 8 }, (_, i) => k[Math.round((i * (k.length - 1)) / 7)]); };
+  for (const t of things) {
+    const { b } = t;
+    const w = b.x1 - b.x0, h = b.y1 - b.y0, d = b.z1 - b.z0;
+    // A painted cut-out stands where its picture does: the lowest opaque row, and the opaque span along it.
+    const pic = t.picture ? alphaFloor(Array.isArray(t.picture.material) ? t.picture.material[0] : t.picture.material) : NONE;
+    const floor = pic.floor;
+    let bottom = b.y0 + floor * h, foot = b.foot;
+    const pg = t.picture && t.picture.geometry && t.picture.geometry.boundingBox;
+    if (pg && pg.max.z - pg.min.z < 1e-3 && t.instance === null) {
+      const M = t.picture.matrixWorld, ly = pg.min.y + floor * (pg.max.y - pg.min.y);
+      const at = (u) => new V(pg.min.x + u * (pg.max.x - pg.min.x), ly, 0).applyMatrix4(M);
+      const p0 = at(pic.u0), p1 = at(pic.u1);
+      foot = [[p0.x, p0.z], [p1.x, p1.z]];
+      bottom = Math.min(p0.y, p1.y);
+    }
+    let cx = foot.reduce((s, p) => s + p[0], 0) / foot.length, cz = foot.reduce((s, p) => s + p[1], 0) / foot.length;
+    // The linked contract entry: its feet are the footprint's centre, its `ground` a surface under the footprint.
+    const entry = t.link && t.hint === 'landed' ? t.link.slice().sort((p, q) => (p.x === null ? 1e9 : Math.hypot(p.x - cx, p.z - cz)) - (q.x === null ? 1e9 : Math.hypot(q.x - cx, q.z - cz)))[0] : null;
+    if (entry && entry.x !== null && entry.z !== null && entry.x >= b.x0 - 1 && entry.x <= b.x1 + 1 && entry.z >= b.z0 - 1 && entry.z <= b.z1 + 1) { cx = entry.x; cz = entry.z; }
+    const deck = entry && entry.ground !== null ? entry.ground : null;
+    const tol = Math.max(0.25, 0.03 * h), sinkTol = Math.max(0.5, 0.35 * h);
+    const under = (x, z) => { const l = surfAt(x, z); if (deck !== null && x >= b.x0 - 1 && x <= b.x1 + 1 && z >= b.z0 - 1 && z <= b.z1 + 1) { l.push({ y: deck, terr: false, nm: entry.id || 'contract ground' }); l.sort((p, q) => q.y - p.y); } return l; };
+    // The nearest surface at or below y (+tol): what this point stands on.
+    const below = (l, y) => l.find((s) => s.y <= y + tol) || null;
+    // Gone through: terrain above it, or a deck it rises above (a crate under a deck is not sunk).
+    const through = (l, y) => l.filter((s) => s.y > y + sinkTol && (s.terr || b.y1 > s.y + tol)).reduce((m, s) => (m === 0 ? s.y - y : Math.min(m, s.y - y)), 0);
+    // Where it touches down.
+    const touch = (t.mesh && !t.picture && contactsOf(t.mesh, b)) || [...foot, [cx, cz]].map(([x, z]) => [x, bottom, z]);
+    const lc = under(cx, cz), gc = below(lc, bottom);
+    const g = gc ? gc.y : lc.length ? lc[lc.length - 1].y : null;
+    const gaps = touch.map(([x, y, z]) => { const l = under(x, z), s = below(l, y); return { gap: s ? y - s.y : null, sunk: through(l, y), any: l.length > 0 }; });
+    const corners = gaps.map((q) => (q.gap === null ? null : r2(q.gap)));
+    const gap = gc ? bottom - gc.y : g === null ? null : bottom - g;
+    let verdict = 'grounded', held = null;
+    const known = gaps.filter((q) => q.gap !== null).map((q) => q.gap);
+    const sunkN = gaps.filter((q) => q.sunk > 0).length;
+    const nameW = t.name;
+    // A leg, trestle or post down into a pit, its top meeting a support: braced, not sunk.
+    const braced = () => {
+      const pts = [[cx, cz], ...touch.map(([x, , z]) => [x, z])];
+      const reach = hasWord(nameW, LEG_W) ? Math.max(3, 0.15 * h) : Math.max(1.2, 0.05 * h);
+      for (const [x, z] of pts) { const s = surfAt(x, z).find((q) => !q.terr && q.y >= b.y1 - tol && q.y <= b.y1 + reach); if (s) return s.nm; }
+      return null;
+    };
+    if (!gaps.some((q) => q.any) && g === null) verdict = 'no_ground';
+    else if (sunkN * 2 >= gaps.length && sunkN > 0) {
+      const by = braced();
+      if (by) { verdict = 'held'; held = `braced under ${by}`; } else verdict = 'sunk';
+    } else {
+      const touching = known.filter((v) => v <= tol).length;
+      const up = known.filter((v) => v > tol);
+      if (!touching && known.length && up.length * 2 >= known.length) {
+        // Resting on another body (a stacked container, a crate on a crate)?
+        const on = things.find((o) => o !== t && Math.abs(o.b.y1 - bottom) <= Math.max(tol, 0.35) && cx >= o.b.x0 - 0.2 && cx <= o.b.x1 + 0.2 && cz >= o.b.z0 - 0.2 && cz <= o.b.z1 + 0.2);
+        const by = braced();
+        if (on) { verdict = 'held'; held = on.instance === null ? on.name : `${on.name}#${on.instance}`; }
+        else if (hasWord(nameW, ATTACHED_W) && Math.min(...up) <= 1.5) { verdict = 'held'; held = 'attached to a support'; }
+        else if (by) { verdict = 'held'; held = `hung from ${by}`; }
+        else verdict = 'hovering';
+      } else if (known.length >= 2 && known.filter((v) => v > Math.max(1.5, 0.4 * h)).length * 2 >= known.length) verdict = 'overhang';
+    }
+    let on = null;
+    if (cam && cam.isCamera) { const p = new V(cx, bottom + h / 2, cz).project(cam); on = p.z > -1 && p.z < 1 && Math.abs(p.x) <= 1.1 && Math.abs(p.y) <= 1.1; }
+    const sunkGap = verdict === 'sunk' ? -Math.max(...gaps.map((q) => q.sunk)) : null;
+    const hoverGap = verdict === 'hovering' && known.length ? Math.min(...known) : null;
+    // Touching down cell by cell: the gap where it is nearest a surface (a sloped railing is not "−3.6 m" at its centre).
+    const nearGap = t.mesh && known.length ? known.reduce((m, v) => (Math.abs(v) < Math.abs(m) ? v : m), known[0]) : null;
+    // Where it is off and by how much (one game: "a distance and not which corner or what tolerance").
+    let lo = -1, hi = -1, deep = -1;
+    gaps.forEach((q, i) => {
+      if (q.gap !== null) { if (lo < 0 || q.gap < gaps[lo].gap) lo = i; if (hi < 0 || q.gap > gaps[hi].gap) hi = i; }
+      if (q.sunk > 0 && (deep < 0 || q.sunk > gaps[deep].sunk)) deep = i;
+    });
+    const pt = (i) => (i < 0 ? null : { x: r2(touch[i][0]), z: r2(touch[i][2]), gap: r2(gaps[i].gap) });
+    out.things.push({
+      name: t.name, kind: t.kind, hint: t.hint, instance: t.instance, ...(entry && entry.id ? { contract: entry.id } : {}), size: { w: r2(w), h: r2(h), d: r2(d) }, at: { x: r2(cx), y: r2(bottom), z: r2(cz) },
+      ground: r2(g), support: gc ? gc.nm : null, gap: r2(sunkGap !== null ? sunkGap : hoverGap !== null ? hoverGap : nearGap !== null ? nearGap : gap), corners: spread(corners), held, verdict, alpha_floor: Math.round(floor * 100) / 100, on,
+      nearest: pt(lo), farthest: pt(hi), deepest: deep < 0 ? null : { x: r2(touch[deep][0]), z: r2(touch[deep][2]), depth: r2(gaps[deep].sunk) },
+      tolerance: { touch: r2(tol), drop: r2(Math.max(1.5, 0.4 * h)), sink: r2(sinkTol) },
+    });
+  }
+  return JSON.stringify(out);
+}

package/dist/vendor/verify/src/page/hooks.js

@@ -0,0 +1,74 @@
+// Adapt a game's own hooks to the __FPX_* names (funpixel.json "hooks"), so a
+// scaffold that exposes, say, window.__ROBIN__ is observable without a rewrite.
+// a = { map: { state: "__ROBIN__.state" | { score: "__ROBIN__.points", … },
+//              verbs, views, keys, audio, selftest, levels: "<dotted path>" } }
+//
+// Each mapped name becomes a getter on window that reads the path on EVERY
+// access, so hooks the game sets late are still read. A name the game already
+// declares itself is left alone; one it sets later replaces the getter. A
+// `state` path may name a function (called bound to its owner) or an object
+// (snapshotted); a `keys` path may name an array of codes. Returns JSON
+// { mapped, unresolved, skipped }: unresolved = read undefined at install.
+//
+// Part of @funpixel/verify: one function expression of one argument, loaded by
+// funpixel-browser (include_str!) and by local `funtools verify`. See
+// mechanic_check.js for the calling convention.
+(a) => {
+  const NAMES = {
+    state: '__FPX_STATE__', verbs: '__FPX_VERBS__', views: '__FPX_VIEWS__', keys: '__FPX_KEYS__',
+    audio: '__FPX_AUDIO__', selftest: '__FPX_SELFTEST__', levels: '__FPX_LEVELS__',
+  };
+  const PATH = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+  const owner = (path) => {
+    let o = window;
+    const parts = path.split('.');
+    for (const k of parts.slice(0, -1)) { if (o == null) return [undefined, undefined]; o = o[k]; }
+    return [o, o == null ? undefined : o[parts[parts.length - 1]]];
+  };
+  const get = (path) => owner(path)[1];
+  const map = (a && a.map && typeof a.map === 'object') ? a.map : {};
+  const mapped = [], unresolved = [], skipped = [];
+  for (const hook of Object.keys(map)) {
+    const name = NAMES[hook], spec = map[hook];
+    if (!name) continue;
+    if (Object.prototype.hasOwnProperty.call(window, name)) { skipped.push(hook); continue; }
+    let read = null;
+    if (hook === 'state' && spec && typeof spec === 'object') {
+      const fields = Object.keys(spec).filter((f) => typeof spec[f] === 'string' && PATH.test(spec[f]));
+      read = () => (fields.every((f) => get(spec[f]) === undefined) ? undefined : () => {
+        const out = {};
+        for (const f of fields) out[f] = get(spec[f]);
+        return out;
+      });
+    } else if (typeof spec === 'string' && PATH.test(spec)) {
+      read = () => {
+        const [o, v] = owner(spec);
+        if (hook === 'state') {
+          if (typeof v === 'function') return v.bind(o);
+          if (!v || typeof v !== 'object') return undefined;
+          return () => { try { return JSON.parse(JSON.stringify(v)); } catch (e) { return Object.assign({}, v); } };
+        }
+        if (hook === 'keys' && Array.isArray(v)) {
+          const keys = {};
+          for (const k of v) keys[String(k)] = 1;
+          return keys;
+        }
+        return v;
+      };
+    }
+    if (!read) continue;
+    try {
+      Object.defineProperty(window, name, {
+        configurable: true,
+        get: read,
+        // The game declaring the name itself later wins over the map.
+        set(v) { Object.defineProperty(window, name, { value: v, writable: true, configurable: true, enumerable: true }); },
+      });
+    } catch (e) { continue; }
+    mapped.push(hook);
+    let now;
+    try { now = read(); } catch (e) { now = undefined; }
+    if (now === undefined) unresolved.push(hook);
+  }
+  return JSON.stringify({ mapped, unresolved, skipped });
+}