Official Codebase of 3DCodeVerse
Python
/**
* Placement table — deterministic "does every placed asset sit on something?"
* for a THREE.Scene (page-side or node; pure three.js math, no renderer).
* Added 2026-08-26: the scene track had NO deterministic placement check — the
* census only reported 2-D zone-footprint overlap (INFO) and floating / sunken
* assets were left to the VLM (defect −0.06), while the scene_v1 `floating_part`
* cap could never fire because no gate emitted those words.
*
* A "placed asset" is each direct child of a ZONE ROOT that has Mesh descendants.
* The zone roots are the objects the harness's own assembler marks with
* `userData[ZONE_ROOT_KEY]` (conventions.ZONE_ROOT_KEY; scene_blender: the census GLB's zone
* node extras) — D111, 2026-10-16. Every other root (env scenery, a zone's stray
* `scene.add`) is SCENERY: no rows, never paired, never in the free share — but its meshes
* still support and bury the zone assets. A scene the harness did not assemble carries no
* mark: there every top-level child is a zone root and a top-level Mesh an asset of its
* own, as before. Assets are named by Object3D name.
*
* Per asset (all in world space, metres):
* bbox exact AABB of its (non-instanced) mesh vertices
* ground_gap_m min over its FOOT COLUMNS of the vertical distance from the
* foot to the nearest surface of any OTHER mesh below it (terrain,
* floor, table…); falls back to the census ground_y when nothing
* is beneath. Foot columns are up to 5 XZ points taken from the
* asset's lowest vertices (lowest, ±x, ±z extremes of the band
* ≤ 5 % of its height above its minimum) — so a table is measured
* at its leg tips, not under its top.
* gap_max_m the LARGEST column gap (2026-10-14): a crate seated by its lowest
* corner on a slope has ground_gap_m 0 and gap_max_m the hang of the
* far corner; the python gate's `cantilevered` reads it
* columns_resting columns within CONTACT_TOL_M of what is under them, or buried
* tilt_m gap_max_m − ground_gap_m: how unevenly the feet meet the ground
* sunk_m max over columns of how far the foot sits below a surface that
* passes through the asset's own vertical extent at that column,
* or below a ground-like surface (terrain/floor) above it.
* support / sunk_into the mesh (its owning asset when it is one) that was hit
* on_water a water-named surface lies at/above the foot at some column: the
* foot is in the water (boat, jetty post) → supported, never sunk
* attached other assets whose AABB intersects this one's AABB + 2 cm
* supported gap ≤ 0.02 m or sunk
* floating gap > 0.05 m and not sunk (python re-derives with the indoor
* threshold; these booleans are for tools/humans)
* touches_nothing gap > 0.02 m, not sunk, attached to nothing
* Interpenetration: pairs of checked assets whose AABBs overlap by > 10 % of the
* smaller box (OVERLAP_MIN_FRAC), refined by sampling the smaller asset's vertices for containment
* in the larger one's meshes (parity of surfaces above the point per column) —
* a bench under a tree canopy is NOT an interpenetration, a crate half inside a
* wall is. `aabb_overlap` is the box fraction (the reported number), `inside_frac`
* the vertex containment that confirmed it.
*
* Exempt (listed with a reason, never scored): lights, cameras, ground / sky
* meshes (`backdrop.mjs` rules), enclosures whose AABB swallows the content box,
* instanced-only assets (scatter cannot be sampled per instance at this budget;
* instanced meshes are also never used as support), VOLUMETRIC assets — every mesh
* of which writes no depth, i.e. haze, god rays, glow (`nonSolid`) — and anything
* the author tags `userData.placement = 'free'` on the asset or its zone (a bird, a
* hanging lantern, a drone). A volumetric mesh is not indexed at all, so it is
* never a support, never something to sink into and never an overlap partner.
* First 400 assets, 4 s budget; the table says when it cut.
*
* Vertical rays only, so every mesh gets a "column index": world vertices once
* and, above 1 500 triangles, a uniform XZ grid of triangle buckets. A column
* query is point-in-triangle in XZ + barycentric height — double-sided by
* construction (a raycaster with FrontSide materials never sees the terrain from
* below, which is exactly the sunk case).
*/
import { classifyBackdrop, GROUND_NAME_RE, nonSolid, nameText, nameWords, splitInstance } from './backdrop.mjs';
import { geometryTriangles } from './census.mjs';
//: the harness's zone-root mark (python twin: conventions.ZONE_ROOT_KEY; tests/scene_runtime/test_zone_roots.py pins them)
export const ZONE_ROOT_KEY = 'c3d_zone';
//: scenery root names recorded in the table (the count is exact)
export const MAX_SCENERY_NAMES = 24;
export const MAX_ASSETS = 400;
export const TIME_BUDGET_MS = 4000;
export const CONTACT_TOL_M = 0.02;
export const FLOATING_M = 0.05;
export const SUNK_M = 0.10;
// Pairs under this box fraction are neither confirmed nor reported; the python gate grades the
// rest from Settings.placement (WARN past overlap_warn, ERROR past overlap_error) and this floor IS
// the default overlap_warn — tests/scene_gates/test_placement.py pins the two together. 0.20 →
// 0.10 on 2026-10-14 (D105, the owner's stricter contact standards): the 10–35 % band was never
// measured, so the strict WARN level would have had nothing to read.
export const OVERLAP_MIN_FRAC = 0.10;
//: named descendants recorded per row, so the plan-contents check can see through one
//: wrapper group without the table growing without bound
export const MAX_INNER_NAMES = 24;
export const WATER_RE = /\b(water|ocean|sea|lake|river|pond|pool|stream|canal)\b/i;
const FOOT_BAND_MIN_M = 0.02;
const FOOT_BAND_FRAC = 0.05;
const MAX_COLUMNS = 5;
const GRID_MIN_TRIS = 1500;
const MAX_INDEXED_TRIS = 1500000;
const OVERLAP_SAMPLES = 64;
const EPS = 1e-3;
const BARY_TOL = 1e-4;
const r3 = (v) => +v.toFixed(3);
/** World-space vertices + XZ triangle buckets for vertical column queries on one mesh. */
class ColumnIndex {
constructor(mesh) {
const geo = mesh.geometry;
const pos = geo.attributes.position;
this.mesh = mesh;
this.tris = geometryTriangles(geo);
this.index = geo.index ? geo.index.array : null;
const n = pos.count;
const xyz = new Float32Array(n * 3);
const e = mesh.matrixWorld.elements;
let minx = Infinity, miny = Infinity, minz = Infinity, maxx = -Infinity, maxy = -Infinity, maxz = -Infinity;
for (let i = 0; i < n; i++) {
const x = pos.getX(i), y = pos.getY(i), z = pos.getZ(i);
const wx = e[0] * x + e[4] * y + e[8] * z + e[12];
const wy = e[1] * x + e[5] * y + e[9] * z + e[13];
const wz = e[2] * x + e[6] * y + e[10] * z + e[14];
xyz[3 * i] = wx; xyz[3 * i + 1] = wy; xyz[3 * i + 2] = wz;
if (wx < minx) minx = wx; if (wx > maxx) maxx = wx;
if (wy < miny) miny = wy; if (wy > maxy) maxy = wy;
if (wz < minz) minz = wz; if (wz > maxz) maxz = wz;
}
this.xyz = xyz;
this.count = n;
this.min = [minx, miny, minz];
this.max = [maxx, maxy, maxz];
this.grid = null;
this.kind = this.empty ? 'content' : classifyBackdrop(mesh, { min: { x: minx, y: miny, z: minz }, max: { x: maxx, y: maxy, z: maxz } });
this.water = isWaterLike(mesh);
this.groundLike = this.kind === 'ground' || GROUND_NAME_RE.test(nameText(mesh.name)) || GROUND_NAME_RE.test(nameText(nearestName(mesh)));
}
get empty() { return this.count === 0 || this.tris === 0 || !Number.isFinite(this.min[0]); }
containsXZ(x, z, pad = EPS) {
return x >= this.min[0] - pad && x <= this.max[0] + pad && z >= this.min[2] - pad && z <= this.max[2] + pad;
}
vertexOf(t, k) { return this.index ? this.index[3 * t + k] : 3 * t + k; }
_buildGrid() {
const cells = Math.min(128, Math.max(8, Math.ceil(Math.sqrt(this.tris) / 2)));
const sx = Math.max(1e-6, this.max[0] - this.min[0]), sz = Math.max(1e-6, this.max[2] - this.min[2]);
const buckets = new Array(cells * cells);
const xyz = this.xyz;
for (let t = 0; t < this.tris; t++) {
let cx0 = Infinity, cx1 = -Infinity, cz0 = Infinity, cz1 = -Infinity;
for (let k = 0; k < 3; k++) {
const v = this.vertexOf(t, k);
const x = xyz[3 * v], z = xyz[3 * v + 2];
if (x < cx0) cx0 = x; if (x > cx1) cx1 = x;
if (z < cz0) cz0 = z; if (z > cz1) cz1 = z;
}
const ix0 = Math.max(0, Math.floor((cx0 - this.min[0]) / sx * cells)), ix1 = Math.min(cells - 1, Math.floor((cx1 - this.min[0]) / sx * cells));
const iz0 = Math.max(0, Math.floor((cz0 - this.min[2]) / sz * cells)), iz1 = Math.min(cells - 1, Math.floor((cz1 - this.min[2]) / sz * cells));
for (let ix = ix0; ix <= ix1; ix++) for (let iz = iz0; iz <= iz1; iz++) {
const b = ix * cells + iz;
(buckets[b] || (buckets[b] = [])).push(t);
}
}
this.grid = { cells, sx, sz, buckets };
}
_candidates(x, z) {
if (this.tris <= GRID_MIN_TRIS) return null; // null = all triangles
if (!this.grid) this._buildGrid();
const g = this.grid;
const ix = Math.floor((x - this.min[0]) / g.sx * g.cells), iz = Math.floor((z - this.min[2]) / g.sz * g.cells);
if (ix < 0 || iz < 0 || ix >= g.cells || iz >= g.cells) return [];
return g.buckets[ix * g.cells + iz] || [];
}
/** Heights (world y) of every surface of this mesh crossing the vertical line at (x, z). */
heightsAt(x, z, out = []) {
if (!this.containsXZ(x, z)) return out;
const list = this._candidates(x, z);
const n = list ? list.length : this.tris;
const xyz = this.xyz;
for (let i = 0; i < n; i++) {
const t = list ? list[i] : i;
const a = this.vertexOf(t, 0), b = this.vertexOf(t, 1), c = this.vertexOf(t, 2);
const ax = xyz[3 * a], az = xyz[3 * a + 2], bx = xyz[3 * b], bz = xyz[3 * b + 2], cx = xyz[3 * c], cz = xyz[3 * c + 2];
const d = (bz - cz) * (ax - cx) + (cx - bx) * (az - cz);
if (Math.abs(d) < 1e-12) continue; // vertical / degenerate: never blocks a vertical line
const l1 = ((bz - cz) * (x - cx) + (cx - bx) * (z - cz)) / d;
const l2 = ((cz - az) * (x - cx) + (ax - cx) * (z - cz)) / d;
const l3 = 1 - l1 - l2;
if (l1 < -BARY_TOL || l2 < -BARY_TOL || l3 < -BARY_TOL) continue;
out.push(l1 * xyz[3 * a + 1] + l2 * xyz[3 * b + 1] + l3 * xyz[3 * c + 1]);
}
return out;
}
/** Parity test: is world point (x, y, z) inside this (closed) mesh? */
contains(x, y, z) {
const hs = this.heightsAt(x, z);
let above = 0;
for (const h of hs) if (h > y) above += 1;
return above % 2 === 1;
}
}
export function boxJson(min, max) {
return { min: min.map(r3), max: max.map(r3), size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]].map(r3) };
}
function materialNames(mesh) {
const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
return mats.map((m) => (m && (m.name || (m.map && m.map.name))) || '').join(' ');
}
function nearestName(obj) {
for (let o = obj; o; o = o.parent) if (o.name) return o.name;
return obj.type || 'mesh';
}
function isWaterLike(mesh) { return !!mesh && (WATER_RE.test(nameText(mesh.name)) || WATER_RE.test(nameText(materialNames(mesh))) || WATER_RE.test(nameText(nearestName(mesh)))); }
/**
* Every visible, non-instanced Mesh with a position attribute → ColumnIndex (skipping
* giants and volumetrics). A `nonSolid` mesh is collected into `volumetric` instead:
* it is neither a support, nor something to sink into, nor an overlap partner, but an
* asset made only of them still has to appear in the table with a reason.
*/
function indexMeshes(scene, notes) {
const map = new Map();
const volumetric = new Set();
scene.traverse((o) => {
if (!o.visible || !o.isMesh || o.isInstancedMesh || !o.geometry || !o.geometry.attributes || !o.geometry.attributes.position) return;
if (geometryTriangles(o.geometry) > MAX_INDEXED_TRIS) { notes.push(`skipped ${nearestName(o)}: > ${MAX_INDEXED_TRIS} triangles`); return; }
if (nonSolid(o)) { volumetric.add(o); return; }
const ci = new ColumnIndex(o);
if (!ci.empty) map.set(o, ci);
});
return { map, volumetric };
}
function isFree(obj) { return !!(obj && obj.userData && obj.userData.placement === 'free'); }
function isZoneRoot(obj) { return !!(obj && obj.userData && obj.userData[ZONE_ROOT_KEY]); }
/**
* The roots whose direct children are the placed assets, and the scenery roots beside them.
* Marked zone roots are found anywhere in the tree (the assembler's own probe nests each in a
* wrapper), a marked root's subtree is not searched further. Why (D111, argon loop iteration 4,
* 2026-10-15): every top-level child used to be a "zone", so an env-built wall merged per material
* became a body row, a flashing row and a pier row that overlap by construction; a two-mesh bollard
* was a cap "interpenetrating" its post; a zone's envelope added straight to the scene filled 337 of
* the 400 rows. A replay of four of its runs put 3-15 placement ERRORs each on roots outside the
* zones; in two of them every final ERROR was of that kind (scenery-vs-scenery is never paired now;
* zone-vs-scenery still is, collectAssets).
*/
function zoneRoots(scene) {
const marked = [];
const walk = (o) => { for (const c of o.children) { if (isZoneRoot(c)) marked.push(c); else walk(c); } };
walk(scene);
if (!marked.length) return { roots: scene.children, scenery: [] };
const holdsZone = (o) => { let found = false; o.traverse((d) => { if (!found && isZoneRoot(d)) found = true; }); return found; };
const scenery = scene.children.filter((c) => c.visible && !c.isLight && !c.isCamera && !holdsZone(c));
return { roots: marked, scenery };
}
/** One root's measurable pieces: its direct children (or the root itself when it is a mesh). */
function piecesOf(root) {
if (!root.visible || root.isLight || root.isCamera) return [];
return (root.isMesh || root.isInstancedMesh ? [root] : root.children).filter((c) => c.visible && !c.isLight && !c.isCamera);
}
/** The placed assets: direct children of each zone root (or a zone root that is a mesh itself) —
* and, measured the same way but never rows, the SCENERY PIECES (the children of every root outside
* the zones). A zone asset still touches and clips them: a sconce flush on an env facade is mounted
* on it (`attached`, and the settle leaves it), a storefront pushed through an env wall is an
* interpenetration; only scenery-vs-scenery is never paired (D111). */
function collectAssets(scene, indices, volumetrics, contentBox) {
const assets = [];
const sceneryPieces = [];
let total = 0;
const seen = new Set();
const { roots, scenery } = zoneRoots(scene);
for (const zone of roots) {
for (const child of piecesOf(zone)) {
if (seen.has(child)) continue;
seen.add(child);
const a = measurePiece(zone, child, indices, volumetrics, contentBox, total);
if (!a) continue;
total += 1;
if (assets.length < MAX_ASSETS) assets.push(a);
}
}
for (const root of scenery) {
for (const child of piecesOf(root)) {
const a = measurePiece(root, child, indices, volumetrics, contentBox, sceneryPieces.length);
// only a solid, non-exempt piece can hold or clip a zone asset — the rule the zone assets
// themselves follow (a ground / water / enclosing shell is a backdrop: things stand ON it)
if (a && !a.exempt) { a.scenery = true; sceneryPieces.push(a); }
}
}
return { assets, total, scenery, sceneryPieces };
}
/** Measure one piece (`child` of `zone`): its meshes, named inner families, AABB and exemption;
* null when it holds nothing measurable at all. */
function measurePiece(zone, child, indices, volumetrics, contentBox, ordinal) {
const meshes = [];
let instanced = 0;
let volumetric = 0;
// Named descendants, not just this row's own name: a zone often wraps its content in
// one group ("IslandAssembly"), and the plan-contents check reads names off these
// rows. Measured 2026-09-05 (scene_fixed/floating_islands): Windmill, FloatingRock
// and SkyPine were built and named correctly, added to `IslandAssembly`, and three
// zones were reported as "missing planned contents".
const inner = [];
// Per named FAMILY below this row, the world AABB of each member (a member = one named
// descendant, its meshes pooled). A zone wraps a scatter in one group ('PicketFences' =
// twelve 'PicketFence' builder outputs along a path, 'GorseBushClusters' = eight bushes
// over 12 m), and the plan sized the INSTANCE: measured 2026-09-07 (loop 9 lighthouse),
// the scale check read the wrapper's 14.7 m against the plan's 2.4 m fence, the judge
// repeated "6.1x too large", and the repair shrank the whole run to microscopic dots.
const members = new Map(); // family -> Map(member object -> [min, max])
child.traverse((o) => {
if (!o.visible) return;
// one slot per FAMILY (Planter_3 / Planter.003 → Planter): the by-name check matches on
// the plan's word, and 30 numbered props must not push the hero behind them past the cap
const family = o.name ? splitInstance(o.name)[0] : '';
if (o !== child && family && inner.length < MAX_INNER_NAMES && !inner.includes(family)) inner.push(family);
if (o.isInstancedMesh) instanced += 1;
else if (indices.has(o)) {
const ci = indices.get(o);
meshes.push(ci);
for (let m = o; m && m !== child; m = m.parent) {
if (!m.name) continue;
const fam = splitInstance(m.name)[0];
if (!members.has(fam)) members.set(fam, new Map());
const box = members.get(fam).get(m) || [[Infinity, Infinity, Infinity], [-Infinity, -Infinity, -Infinity]];
for (let k = 0; k < 3; k++) { box[0][k] = Math.min(box[0][k], ci.min[k]); box[1][k] = Math.max(box[1][k], ci.max[k]); }
members.get(fam).set(m, box);
}
}
else if (volumetrics.has(o)) volumetric += 1;
});
if (!meshes.length && !instanced && !volumetric) return null;
const families = {};
for (const [fam, byMember] of members) {
if (byMember.size < 2) continue;
const sizes = [...byMember.values()].map(([lo, hi]) => Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2])).sort((x, y) => x - y);
families[fam] = { n: sizes.length, size_m: r3(sizes[Math.floor(sizes.length / 2)]) };
}
const a = { obj: child, name: child.name || `${child.type}_${ordinal}`, zone: zone === child ? '' : (zone.name || zone.type), meshes, instanced, inner, families, exempt: '' };
if (isFree(zone) || isFree(child)) a.exempt = 'free';
// (the `RoomShell…` name exemption of 2026-10-15 is gone, D111: the env's room shell is a
// scenery root of a marked scene, so its walls, lid and lintels are never rows at all)
// instanced first: an asset that is scatter PLUS a haze shell is exempt because its
// instances cannot be sampled at this budget, which is the more informative reason
else if (!meshes.length && instanced) a.exempt = 'instanced';
else if (!meshes.length && volumetric) a.exempt = 'volumetric';
else {
a.min = [Infinity, Infinity, Infinity]; a.max = [-Infinity, -Infinity, -Infinity];
let backdrop = 0;
for (const ci of meshes) {
for (let k = 0; k < 3; k++) { a.min[k] = Math.min(a.min[k], ci.min[k]); a.max[k] = Math.max(a.max[k], ci.max[k]); }
// a ground / floor / water surface is what things sit ON, whatever its size
if (ci.kind !== 'content' || ci.groundLike || ci.water) backdrop += 1;
}
if (backdrop === meshes.length || GROUND_NAME_RE.test(nameText(a.name)) || WATER_RE.test(nameText(a.name))) a.exempt = 'backdrop';
else if (contentBox && enclosesContent(a, contentBox)) a.exempt = 'enclosure';
}
return a;
}
function enclosesContent(a, cb) {
const span = Math.max(a.max[0] - a.min[0], a.max[2] - a.min[2]);
const cspan = Math.max(cb.max[0] - cb.min[0], cb.max[2] - cb.min[2]);
const inside = [0, 1, 2].every((k) => a.min[k] <= cb.min[k] + EPS && a.max[k] >= cb.max[k] - EPS);
return inside && span > 2 * Math.max(cspan, 1);
}
/** Up to MAX_COLUMNS foot columns [x, y, z] from the asset's lowest vertices. */
function footColumns(a) {
const band = a.min[1] + Math.max(FOOT_BAND_MIN_M, FOOT_BAND_FRAC * (a.max[1] - a.min[1]));
let lowest = null, minx = null, maxx = null, minz = null, maxz = null;
for (const ci of a.meshes) {
const xyz = ci.xyz;
for (let i = 0; i < ci.count; i++) {
const y = xyz[3 * i + 1];
if (y > band) continue;
const p = [xyz[3 * i], y, xyz[3 * i + 2]];
if (!lowest || y < lowest[1]) lowest = p;
if (!minx || p[0] < minx[0]) minx = p;
if (!maxx || p[0] > maxx[0]) maxx = p;
if (!minz || p[2] < minz[2]) minz = p;
if (!maxz || p[2] > maxz[2]) maxz = p;
}
}
const out = [];
for (const p of [lowest, minx, maxx, minz, maxz]) {
if (!p) continue;
if (out.some((q) => Math.hypot(q[0] - p[0], q[2] - p[2]) < 0.01)) continue;
out.push(p);
if (out.length >= MAX_COLUMNS) break;
}
return out;
}
/** One column: nearest other surface below the foot, nearest above, own top. */
function probeColumn(a, col, indices, owner, groundY) {
const [x, y0, z] = col;
let y1 = y0;
for (const ci of a.meshes) for (const h of ci.heightsAt(x, z)) if (h > y1) y1 = h;
let below = null, above = null, onWater = false;
for (const ci of indices.values()) {
if (a.meshSet.has(ci) || ci.kind === 'sky' || !ci.containsXZ(x, z)) continue;
if (ci.min[1] > a.max[1] + EPS) continue; // entirely above the asset: cannot support or bury it
// only something that STARTS below the foot can bury it (terrain, a floor slab, a table
// under a badly stacked crate); a neighbour standing at the same level is a lateral
// overlap and belongs to the interpenetration pass
const startsBelow = ci.min[1] < y0 - EPS || ci.groundLike;
for (const h of ci.heightsAt(x, z)) {
// a foot at or under a water surface is IN the water: boats, jetty posts, reeds —
// whatever is below the surface is invisible, so neither floating nor sunk applies
if (ci.water && h >= y0 - EPS) onWater = true;
if (h <= y0 + EPS) { if (!below || h > below.y) below = { y: h, ci }; } else if (startsBelow && (!above || h < above.y)) above = { y: h, ci };
}
}
const res = { gap: below ? y0 - below.y : (groundY === null ? null : y0 - groundY),
support: below ? owner(below.ci.mesh) : (groundY === null ? '' : 'ground_y'), water: onWater, sunk: 0, into: '' };
if (above && (above.y <= y1 + EPS || above.ci.groundLike)) {
res.sunk = above.y - y0; res.into = owner(above.ci.mesh);
if (!below) { res.gap = -res.sunk; res.support = res.into; } // under a surface with nothing beneath: gap is "that far under"
}
return res;
}
function boxOverlapFrac(a, b) {
const size = (o) => [0, 1, 2].map((k) => Math.max(0.01, o.max[k] - o.min[k]));
const sa = size(a), sb = size(b);
let vol = 1;
for (let k = 0; k < 3; k++) {
const ov = Math.min(a.min[k] + sa[k], b.min[k] + sb[k]) - Math.max(a.min[k], b.min[k]);
if (ov <= 0) return 0;
vol *= ov;
}
return vol / Math.min(sa[0] * sa[1] * sa[2], sb[0] * sb[1] * sb[2]);
}
function touches(a, b, tol) {
return [0, 1, 2].every((k) => a.min[k] - tol <= b.max[k] && b.min[k] - tol <= a.max[k]);
}
/** Fraction of the smaller asset's sampled vertices inside the larger one's meshes. */
function containment(small, large) {
const total = small.meshes.reduce((n, ci) => n + ci.count, 0);
const stride = Math.max(1, Math.floor(total / OVERLAP_SAMPLES));
let sampled = 0, inside = 0;
for (const ci of small.meshes) {
for (let i = 0; i < ci.count; i += stride) {
const x = ci.xyz[3 * i], y = ci.xyz[3 * i + 1], z = ci.xyz[3 * i + 2];
sampled += 1;
if (x < large.min[0] || x > large.max[0] || y < large.min[1] || y > large.max[1] || z < large.min[2] || z > large.max[2]) continue;
if (large.meshes.some((lc) => lc.contains(x, y, z))) inside += 1;
}
}
return { frac: sampled ? inside / sampled : 0, sampled };
}
/** Every touching pair of checked zone assets, and of a checked zone asset with a scenery piece
* (never two scenery pieces, D111): both sides of a touch are `attached`, an overlap past the floor
* whose vertices confirm it is an interpenetration. A zone-vs-scenery pair names the zone asset
* `a` whichever is smaller: the finding targets `a`, and the zone author is the one who can move it. */
function pairs(checked, sceneryPieces = []) {
const out = [];
const vol = (o) => [0, 1, 2].reduce((v, k) => v * Math.max(0.01, o.max[k] - o.min[k]), 1);
const test = (a, b) => {
if (!touches(a, b, CONTACT_TOL_M)) return;
a.attached.push(b.name);
if (!b.scenery) b.attached.push(a.name);
const aabb = boxOverlapFrac(a, b);
if (aabb <= OVERLAP_MIN_FRAC) return;
const [small, large] = vol(a) <= vol(b) ? [a, b] : [b, a];
const c = containment(small, large);
if (c.frac <= OVERLAP_MIN_FRAC) return;
const [x, y] = b.scenery ? [a, b] : [small, large];
out.push({ a: x.name, b: y.name, zone_a: x.zone, zone_b: y.zone, aabb_overlap: r3(aabb), inside_frac: r3(c.frac), samples: c.sampled });
};
for (let i = 0; i < checked.length; i++) {
for (let j = i + 1; j < checked.length; j++) test(checked[i], checked[j]);
for (const s of sceneryPieces) test(checked[i], s);
}
return out.sort((x, y) => y.aabb_overlap - x.aabb_overlap).slice(0, 40);
}
/** Index `scene` once and collect its assets; `owner(mesh)` names the asset a mesh belongs to. */
function survey(scene, opts) {
const notes = [];
scene.updateMatrixWorld(true);
const { map: indices, volumetric } = indexMeshes(scene, notes);
const { assets, total, scenery, sceneryPieces } = collectAssets(scene, indices, volumetric, opts.contentBox || null);
const meshOwner = new Map();
for (const a of assets) { a.meshSet = new Set(a.meshes); for (const ci of a.meshes) meshOwner.set(ci.mesh, a.name); }
const groundY = Number.isFinite(opts.groundY) ? opts.groundY : null;
return { groundY, notes, indices, assets, total, scenery, sceneryPieces, owner: (mesh) => meshOwner.get(mesh) || nearestName(mesh) };
}
/** Probe every foot column of `a`: smallest gap (`best`) and largest (`gapMax`), how many columns
* rest (within contact, or buried), deepest and shallowest burial (`sunk`, `minSunk` — 0 once a
* column is not sunk), whether an unsunk column rests, any foot in water. */
function probeFeet(a, indices, owner, groundY) {
const cols = footColumns(a);
const f = { columns: cols.length, best: null, gapMax: null, resting: 0, sunk: null, water: false, minSunk: Infinity, anyRest: false };
for (const col of cols) {
const r = probeColumn(a, col, indices, owner, groundY);
if (r.gap !== null && (!f.best || r.gap < f.best.gap)) f.best = r;
if (r.gap !== null && (f.gapMax === null || r.gap > f.gapMax)) f.gapMax = r.gap;
if (r.sunk > 0 || (r.gap !== null && r.gap <= CONTACT_TOL_M)) f.resting += 1;
if (r.sunk > 0) {
if (!f.sunk || r.sunk > f.sunk.sunk) f.sunk = r;
f.minSunk = Math.min(f.minSunk, r.sunk);
} else {
f.minSunk = 0;
if (r.gap !== null && r.gap <= CONTACT_TOL_M) f.anyRest = true;
}
if (r.water) f.water = true; // one foot in the water is enough: a jetty is half on the shore
}
return f;
}
/**
* The placement table for `scene`.
* @param {THREE.Scene} scene
* @param {object} THREE unused today (kept for symmetry with sceneCensus)
* @param {{groundY?: number|null, contentBox?: {min:number[], max:number[]}|null}} opts
*/
export function placementTable(scene, THREE, opts = {}) {
const t0 = Date.now();
const { groundY, notes, indices, assets, total, scenery, sceneryPieces, owner } = survey(scene, opts);
const checked = [];
let timeCut = false;
const rows = [];
for (const a of assets) {
const row = { name: a.name, zone: a.zone, meshes: a.meshes.length, instanced: a.instanced, inner: a.inner || [], families: a.families || {},
exempt: a.exempt, bbox: a.min ? boxJson(a.min, a.max) : null };
if (a.exempt) { rows.push(row); continue; }
if (Date.now() - t0 > TIME_BUDGET_MS) { row.exempt = 'time_budget'; timeCut = true; rows.push(row); continue; }
const { columns, best, gapMax, resting, sunk, water } = probeFeet(a, indices, owner, groundY);
a.attached = [];
a.row = row;
Object.assign(row, {
columns,
ground_gap_m: best ? r3(best.gap) : null,
gap_max_m: gapMax === null ? null : r3(gapMax),
columns_resting: resting,
tilt_m: best && gapMax !== null ? r3(gapMax - best.gap) : null,
support: best ? best.support : '',
sunk_m: sunk ? r3(sunk.sunk) : 0,
sunk_into: sunk ? sunk.into : '',
on_water: water,
});
checked.push(a);
rows.push(row);
}
const inter = pairs(checked, sceneryPieces);
for (const a of checked) {
const row = a.row;
row.attached = a.attached.slice(0, 8);
const gap = row.ground_gap_m === null ? 0 : row.ground_gap_m;
row.supported = gap <= CONTACT_TOL_M || row.sunk_m > 0 || row.on_water;
row.floating = gap > FLOATING_M && row.sunk_m === 0 && !row.on_water;
row.touches_nothing = gap > CONTACT_TOL_M && row.sunk_m === 0 && !row.on_water && a.attached.length === 0;
}
const exempt = {};
for (const r of rows) if (r.exempt) exempt[r.exempt] = (exempt[r.exempt] || 0) + 1;
return {
assets: rows, interpenetrations: inter, total, checked: checked.length,
truncated: total > assets.length || timeCut, exempt,
// the roots outside every marked zone (D111): measured as nothing, listed so nothing is silent
scenery: { n: scenery.length, names: scenery.slice(0, MAX_SCENERY_NAMES).map((o) => o.name || o.type) },
thresholds: { contact_m: CONTACT_TOL_M, floating_m: FLOATING_M, sunk_m: SUNK_M, overlap_min: OVERLAP_MIN_FRAC },
ground_y: groundY, notes, duration_ms: Date.now() - t0,
};
}
// ============================================================================ settle
// Deterministic auto-seat, added 2026-08-30. Measured on the 48-run scene batteries:
// 38 sunken + 22 floating gate ERRORS were still present in FINAL rounds — the refine
// agent is handed the exact "lower X by 0.23 m" hint and demonstrably does not apply
// it reliably. The measurement is deterministic, so the FIX can be too: after boot
// (before any census or render) every clearly mis-seated asset is translated onto its
// support. The zone code keeps its wrong constant; every frame anyone sees or judges
// is seated. The moves are returned and carried in the census, so nothing is silent.
//
// Deliberately conservative. What it accepts as seated, the python gate exempts too
// (codeverse3d/spatial/scene_placement.py; the words and the partial fraction are ONE
// file both read, placement_words.json):
// · exempt assets (free / backdrop / enclosure / instanced) are never touched
// · a foot in the water is a boat / jetty: never touched
// · BURIED-ok names (basin, trench, pool…) are below ground by definition
// · SLOPE-ok names (stairs, ramps, paths, terraces…) follow the terrain
// · PARTIAL-ok names (rocks, posts, trees…) may bury up to partial_ok_frac of their
// height; a deeper burial is pulled up only to the 40 % embed that reads as
// "grown in", never to the surface
// · a floating asset that TOUCHES another asset may be mounted on it: skipped
// (Not accepted, only not auto-fixed — the gate still reports them: the slope guard
// below, a move beyond SETTLE_MAX_MOVE_M, a burial under SUNK_M at its shallowest column.)
// · normal sunken assets keep a 4 cm embed (the zone recipes ask for 3-5 cm)
const SETTLE_EMBED_M = 0.04;
const SETTLE_PARTIAL_FRAC = 0.40;
const SETTLE_MAX_MOVE_M = 6;
const SETTLE_SEAT_EPS_M = 0.005;
/** Measure every placed asset once, then translate the clearly mis-seated ones onto
* their support. Returns `{count, moves}`; mutates object positions (world-space dy
* applied through each parent's frame) and leaves matrices updated. `opts.words` is
* `placement_words.json` (the gate's own list: the host fetches it, a test reads it). */
export function settleScene(scene, THREE, opts = {}) {
if (!opts.words) throw new Error('settleScene needs opts.words (runtime_js/lib/placement_words.json)');
const buriedOk = new Set(opts.words.buried_ok), slopeOk = new Set(opts.words.slope_ok);
const partialOk = new Set(opts.words.partial_ok), partialFrac = opts.words.partial_ok_frac;
const { groundY, indices, assets, sceneryPieces, owner } = survey(scene, opts);
const checked = assets.filter((a) => !a.exempt);
// what a floating asset may be mounted on: another zone asset or a scenery piece (an env facade
// holding a sign or a sconce, D111) — the gate's `attached` rule, pairs() above
const neighbours = [...checked, ...sceneryPieces];
const moves = [];
const t0 = Date.now();
for (const a of checked) {
if (Date.now() - t0 > TIME_BUDGET_MS) break;
const { columns, best, sunk, water, minSunk, anyRest } = probeFeet(a, indices, owner, groundY);
if (!columns || water) continue;
const words = nameWords(a.name);
const height = Math.max(a.max[1] - a.min[1], 1e-6);
let dy = 0, why = '';
if (sunk && sunk.sunk > 0) {
if (words.some((w) => buriedOk.has(w) || slopeOk.has(w))) continue;
// Slope guard (2026-08-30): a structure following a hillside is "deeply sunk" at
// its uphill columns while its downhill columns rest — lifting by the DEEPEST
// burial strands the low end in the air. Measured on t36_santorini: six
// StoneStairways lifted +1.3..+3.3 m turned a 0.258 scene into a 0.000 one.
// Settle only what is sunk at EVERY column, and lift by the SHALLOWEST burial.
if (anyRest || minSunk < Math.max(SUNK_M, 0.5 * sunk.sunk)) continue;
const frac = minSunk / height;
if (words.some((w) => partialOk.has(w))) {
if (frac <= partialFrac) continue; // grown / driven in: fine
dy = minSunk - SETTLE_PARTIAL_FRAC * height; // pull up to a 40 % embed
why = 'sunken_partial';
} else if (minSunk > SUNK_M) {
dy = minSunk - SETTLE_EMBED_M; // reseat with a 4 cm embed
why = 'sunken';
} else { continue; }
} else if (best && best.gap !== null && best.gap > FLOATING_M) {
// mounted on a neighbour? touching anything → leave it alone
if (neighbours.some((b) => b !== a && touches(a, b, CONTACT_TOL_M))) continue;
dy = -(best.gap - SETTLE_SEAT_EPS_M); // drop onto the support
why = 'floating';
} else { continue; }
if (!Number.isFinite(dy) || Math.abs(dy) < 1e-4 || Math.abs(dy) > Math.max(SETTLE_MAX_MOVE_M, height)) continue;
const obj = a.obj, parent = obj.parent || scene;
const w = new THREE.Vector3();
obj.getWorldPosition(w);
const delta = parent.worldToLocal(new THREE.Vector3(w.x, w.y + dy, w.z))
.sub(parent.worldToLocal(w.clone()));
obj.position.add(delta);
moves.push({ name: a.name, zone: a.zone, dy_m: Math.round(dy * 1000) / 1000, why });
}
if (moves.length) scene.updateMatrixWorld(true);
return { count: moves.length, moves };
}