Official Codebase of 3DCodeVerse
Python
/**
* Deterministic scene census (page-side, pure over a THREE.Scene).
* Counts meshes / instances / draws / lights / triangles / custom-shader materials,
* measures per top-level group (zone) world bboxes, classifies sky/ground
* groups (shared rules: `backdrop.mjs`), computes a content bbox (sky + ground excluded) and pairwise zone
* overlap statistics. Returns plain JSON.
*/
import { classifyBackdrop, drawableBox, splitInstance } from './backdrop.mjs';
import { geometryTriangles as triCount, geometryInstances } from './census.mjs';
import { boxJson, placementTable } from './host_placement.mjs';
export function isCustomShader(mat, THREE) {
if (!mat) return false;
if (mat.isShaderMaterial || mat.isRawShaderMaterial) return true;
if (Object.prototype.hasOwnProperty.call(mat, 'onBeforeCompile')) return true;
return mat.onBeforeCompile !== THREE.Material.prototype.onBeforeCompile;
}
const boxToJson = (box) => (!box || box.isEmpty() ? null : boxJson(box.min.toArray(), box.max.toArray()));
const STAMP_MIN = 8; // copies before a family's ring / size statistics are worth reporting
const STAMPS_PER_GROUP = 6;
/**
* How a family of placed copies sits: evenly on a circle round their centroid, and all one
* size? `points` are world [x, y, z] per copy, `sizes` their largest extents. Null below
* STAMP_MIN. The day's tally (2026-09-09, five of six exteriors): "a ring of identical cones
* stamped round the perimeter", "rocks in a perfect circle" — a backdrop the judge calls a toy,
* and one the census can see: radius spread, angular spread, size spread.
*/
export function stampStats(points, sizes) {
const n = points.length;
if (n < STAMP_MIN) return null;
let cx = 0, cz = 0;
for (const [x, , z] of points) { cx += x; cz += z; }
cx /= n; cz /= n;
const cv = (v) => {
const m = v.reduce((s, x) => s + x, 0) / v.length;
if (m <= 1e-9) return 0;
return Math.sqrt(v.reduce((s, x) => s + (x - m) ** 2, 0) / v.length) / m;
};
const radii = points.map(([x, , z]) => Math.hypot(x - cx, z - cz));
const angles = points.map(([x, , z]) => Math.atan2(z - cz, x - cx)).sort((a, b) => a - b);
const gaps = angles.map((a, i) => (i ? a - angles[i - 1] : a + 2 * Math.PI - angles[n - 1]));
const r = radii.reduce((s, x) => s + x, 0) / n;
return { n, radius_m: +r.toFixed(2), radius_cv: +cv(radii).toFixed(3), gap_cv: +cv(gaps).toFixed(3), size_cv: +cv(sizes).toFixed(3) };
}
/**
* Draw calls one visible object submits per pass: one per material group when its material is
* an array (three.js draws each group separately), else one. An InstancedMesh is ONE draw at
* any instance count. Load-, camera- and GPU-independent — the `scene_probe` draw gate's count
* (spatial/probes.py), where `fps.draw_calls` is one frame from one camera after culling.
*/
export function objectDraws(o) {
if (!Array.isArray(o.material)) return 1;
return Math.max(1, o.geometry?.groups?.length || 0);
}
function walkGroup(root, THREE) {
let meshes = 0, instances = 0, draws = 0, tris = 0, lights = 0, custom = 0;
const kinds = { sky: 0, ground: 0, content: 0 };
const box = new THREE.Box3(); // content only
const boxAll = new THREE.Box3(); // everything drawable
const groundBox = new THREE.Box3();
const tmp = new THREE.Box3();
const families = new Map(); // family name -> { points, sizes } of its placed copies
const copy = (family, b) => {
if (!families.has(family)) families.set(family, { points: [], sizes: [] });
const f = families.get(family);
const size = b.getSize(new THREE.Vector3());
f.points.push([(b.min.x + b.max.x) / 2, (b.min.y + b.max.y) / 2, (b.min.z + b.max.z) / 2]);
f.sizes.push(Math.max(size.x, size.y, size.z));
};
root.updateMatrixWorld(true);
root.traverseVisible((o) => {
if (o.isLight) lights += 1;
if (!(o.isMesh || o.isPoints || o.isLine || o.isSprite)) return;
const count = geometryInstances(o);
draws += objectDraws(o);
if (o.isMesh) { meshes += 1; instances += count; }
if (o.isMesh) tris += triCount(o.geometry) * count;
const mats = Array.isArray(o.material) ? o.material : [o.material];
if (mats.some((m) => isCustomShader(m, THREE))) custom += 1;
const mb = drawableBox(o, THREE); // an InstancedMesh's box spans its instances
if (!mb) return;
if (o.isInstancedMesh) { // each instance is a placed copy of its family
const m = new THREE.Matrix4();
for (let i = 0, n = Math.min(o.count, 4096); i < n; i++) {
o.getMatrixAt(i, m);
copy(o.name || 'instances', tmp.copy(o.geometry.boundingBox).applyMatrix4(m).applyMatrix4(o.matrixWorld));
}
} else {
copy(splitInstance(o.name)[0] || 'meshes', mb);
}
const kind = classifyBackdrop(o, mb); // shared rules (lib/backdrop.mjs); no content bbox yet here
kinds[kind] += 1;
boxAll.union(mb);
if (kind === 'content') box.union(mb);
if (kind === 'ground') groundBox.union(mb);
});
const kind = kinds.content ? 'content' : kinds.ground ? 'ground' : kinds.sky ? 'sky' : (lights && !meshes ? 'light' : 'empty');
const stamps = [];
for (const [name, f] of families) {
const st = stampStats(f.points, f.sizes);
if (st) stamps.push({ name, ...st });
}
stamps.sort((a, b) => b.n - a.n);
return { meshes, instances, draws, tris, lights, custom, box, boxAll, groundBox, kind, kinds, stamps: stamps.slice(0, STAMPS_PER_GROUP) };
}
function overlapStats(groups) {
const out = [];
const content = groups.filter((g) => g.kind === 'content' && g.bbox);
for (let i = 0; i < content.length; i++) {
for (let j = i + 1; j < content.length; j++) {
const a = content[i].bbox, b = content[j].bbox;
const ix = Math.min(a.max[0], b.max[0]) - Math.max(a.min[0], b.min[0]);
const iz = Math.min(a.max[2], b.max[2]) - Math.max(a.min[2], b.min[2]);
if (ix <= 0 || iz <= 0) continue;
const areaA = Math.max(1e-6, a.size[0] * a.size[2]);
const areaB = Math.max(1e-6, b.size[0] * b.size[2]);
const frac = (ix * iz) / Math.min(areaA, areaB);
if (frac > 0.05) out.push({ a: content[i].name, b: content[j].name, footprint_overlap: +frac.toFixed(3) });
}
}
return out.sort((x, y) => y.footprint_overlap - x.footprint_overlap).slice(0, 20);
}
/** Walk `scene` and return the census JSON. `opts.placement` (default off — the
* render driver calls this per frame set) adds the per-asset placement table of
* `host_placement.mjs` under `placement`: the probe's `placement()` asks for it. */
export function sceneCensus(scene, THREE, opts = {}) {
scene.updateMatrixWorld(true);
const groups = [];
const totals = { meshes: 0, instances: 0, draws: 0, triangles: 0, lights: 0, custom_shader_meshes: 0 };
const lightTypes = {};
const materials = new Set();
const customMaterials = [];
scene.traverse((o) => {
if (o.isLight) lightTypes[o.type] = (lightTypes[o.type] || 0) + 1;
if (o.material) {
for (const m of Array.isArray(o.material) ? o.material : [o.material]) {
if (!m || materials.has(m.uuid)) continue;
materials.add(m.uuid);
if (isCustomShader(m, THREE)) {
customMaterials.push({
name: m.name || '', type: m.type, on: o.name || o.type,
kind: m.isShaderMaterial || m.isRawShaderMaterial ? 'ShaderMaterial' : 'onBeforeCompile',
has_time_uniform: !!(m.uniforms && (m.uniforms.uTime || m.uniforms.time)),
});
}
}
}
});
const unionAll = new THREE.Box3();
const content = new THREE.Box3();
const groundAll = new THREE.Box3();
for (const child of scene.children) {
const g = walkGroup(child, THREE);
const name = child.name || `${child.type}_${groups.length}`;
groups.push({
name, named: !!child.name, type: child.type, kind: g.kind, meshes: g.meshes, instances: g.instances, draws: g.draws,
triangles: g.tris, lights: g.lights, custom_shader_meshes: g.custom, mesh_kinds: g.kinds,
bbox: boxToJson(g.kind === 'content' ? g.box : g.boxAll), stamps: g.stamps,
});
totals.meshes += g.meshes; totals.instances += g.instances; totals.draws += g.draws; totals.triangles += g.tris; totals.lights += g.lights; totals.custom_shader_meshes += g.custom;
if (!g.boxAll.isEmpty()) unionAll.union(g.boxAll);
if (!g.box.isEmpty()) content.union(g.box);
if (!g.groundBox.isEmpty()) groundAll.union(g.groundBox);
}
const groundY = groundAll.isEmpty() ? null : groundAll.max.y;
const contentBox = boxToJson(content.isEmpty() ? unionAll : content);
const out = {
totals,
light_types: lightTypes,
materials: materials.size,
custom_materials: customMaterials,
fog: scene.fog ? { type: scene.fog.type, near: scene.fog.near, far: scene.fog.far, density: scene.fog.density } : null,
background: scene.background ? (scene.background.isColor ? '#' + scene.background.getHexString() : scene.background.type || 'texture') : null,
environment: !!scene.environment,
groups,
bbox: boxToJson(unionAll),
content_bbox: contentBox,
ground_y: groundY !== null ? +groundY.toFixed(3) : (contentBox ? contentBox.min[1] : 0),
has_ground: groundY !== null,
overlaps: overlapStats(groups),
};
if (opts.placement) out.placement = placementTable(scene, THREE, { groundY: out.ground_y, contentBox });
return out;
}