Official Codebase of 3DCodeVerse
Python
#!/usr/bin/env node
/**
* Fast import-only probe of a scene_threejs workspace (the scene 'build' gate):
* does src/scene.js load, does createScene() return {scene, cameras, update},
* are cameras valid, does update(t, dt) run — plus the census and all
* console/page/shader errors. No screenshots.
*
* node probe_scene.mjs --ws <ws> [--scene src/scene.js] [--gpu auto] [--timeout-ms 60000] [--out probe.json]
* [--compile] [--shaders-out report.json] [--sun-azimuth 60] [--bounds '{"min":[..],"max":[..]}'|none]
* [--glb artifacts/census.glb]
*
* `--glb` probes an OFFLINE scene (scene_blender): the host boots lib/glb_scene.mjs on that
* harness-written census GLB instead of `--scene` — the same census and placement code.
*
* `--compile` additionally runs the full shader preflight (static GLSL audits +
* force-compile of every material, lib/shader_report.mjs) on the SAME booted
* page — one browser boot instead of two for a scene build. The report
* (identical schema to check_shaders.mjs) lands in the summary as
* `shader_report` and, when `--shaders-out` is given, in that file.
* `--sun-azimuth <deg>` returns harness-fitted camera specs (lib/orbit.mjs —
* the single owner of camera-fit math) from the measured census: an overview
* of the content bounds plus one eye-level camera per top-level group, all
* standing on the sun side — `fitted_cameras: {azimuth, overview, zones}`.
* The azimuth is `sunRig`'s (x-first: 0 = +X, 90 = +Z), converted here to orbit.mjs's
* z-first angle; `--bounds` (the plan's) guards the overview framing exactly as
* render_scene.mjs does, so a 400 m instanced meadow cannot shrink the content to a speck.
* The scene assembler (assemble.py) converts these into its CameraPlans.
* Last stdout line = JSON {ok, boot, census, console_errors, shader_errors, ...}.
*/
import path from 'node:path';
import { armWatchdog, fail, finish, parseCli, readJsonArg, writeJson } from './lib/cli.mjs';
import { createTimeoutMs, errorSummary, openHost } from './lib/host_page.mjs';
import { fitOverviewCamera, fitZoneCamera, framingBox } from './lib/orbit.mjs';
import { compileIntoReport, staticShaderReport } from './lib/shader_report.mjs';
const args = parseCli({
'no-settle': { type: 'boolean', default: false },
'camera-repair': { type: 'boolean', default: false },
ws: {}, out: {}, gpu: { default: process.env.C3D_RENDER_GPU || 'auto' }, 'timeout-ms': { default: '60000' },
scene: { default: 'src/scene.js' }, glb: { default: '' },
compile: { type: 'boolean', default: false }, 'shaders-out': { default: '' }, 'sun-azimuth': { default: '' },
bounds: { default: 'none' },
});
/** Harness-fitted camera specs from the census: overview + one per group, on the side
* `sunRig({azimuth})` lights. sunRig's sun is x-first — (cos A, ·, sin A) — and
* orbitDirection z-first — (sin B, ·, cos B) — so the same side is B = 90 − A (they agree
* only at 45°; at 135° the "sun-side" camera stood exactly opposite the sun). */
function fitCameras(census, azimuth, bounds) {
const groundY = census.ground_y;
const orbitAz = 90 - azimuth;
const box = framingBox(census, bounds);
const overview = box ? fitOverviewCamera(box, { azimuth: orbitAz, elevation: 30, groundY }) : null;
const zones = [];
for (const g of census.groups || []) {
if (!g.bbox || g.kind === 'sky' || g.kind === 'empty' || g.kind === 'light') continue;
zones.push({ group: g.name, ...fitZoneCamera(g.bbox, { azimuth: orbitAz, floor: groundY }) });
}
return { azimuth, overview, zones };
}
async function main() {
if (!args.ws) throw new Error('--ws is required');
const timeoutMs = parseInt(args['timeout-ms'], 10);
// The phase the watchdog reports when the budget runs out (D111; python: render_scene.SCENE_PHASES).
// `scene` (import, createScene, the boot settle), `census` (census + placement table) and `update`
// are the scene's own construction work, a verdict on the code; `host` (browser launch, page ready),
// `report`, `compile` (the shader preflight) and `close` are the box's.
let phase = 'host';
const watchdog = armWatchdog(timeoutMs, () => ({ phase }));
const t0 = Date.now();
let host;
try {
host = await openHost(args.ws, {
width: 320, height: 180, gpu: args.gpu, sceneRel: args.scene.replace(/^\.?\//, ''),
glb: args.glb ? path.resolve(args.glb) : null,
createSceneTimeoutMs: createTimeoutMs(timeoutMs),
settle: !args['no-settle'],
cameraRepair: !!args['camera-repair'],
post: false,
onBoot: () => { phase = 'scene'; },
});
} catch (e) {
return fail(`host failed: ${e.message}`);
}
const { page, boot } = host;
const result = { ok: false, renderer: boot.renderer || host.renderer, gpu: host.gpu, boot, census: null, update_ok: null, update_error: '', shader_errors: [] };
try {
if (boot.ok) {
phase = 'census';
result.census = await page.evaluate(() => window.__c3v.census());
// placement table (floating / sunken / unsupported / interpenetration per asset);
// a failure here must never fail the probe — the python gate reports it as a WARN
try {
result.census.placement = await page.evaluate(() => window.__c3v.placement());
} catch (e) {
result.census.placement = { error: String((e && e.message) || e).slice(0, 400) };
}
// exercise update() for a few fixed steps and one tiny render (lazy programs compile)
phase = 'update';
const upd = await page.evaluate((n) => {
try {
const animation_hooks = window.__c3v.probeUpdateHooks(n / 30);
window.__c3v.renderAt(window.__c3v.cameras()[0], n / 30);
return { ok: true, animation_hooks };
} catch (e) {
return { ok: false, error: String((e && e.stack) || e).slice(0, 800) };
}
}, 10);
result.update_ok = upd.ok;
result.update_error = upd.error || '';
if (upd.animation_hooks) result.census.animation_hooks = upd.animation_hooks;
// update() exceptions are caught page-side (rendering continues); still a probe failure
const updateErrors = await page.evaluate(() => window.__c3v.updateErrors());
if (upd.ok && updateErrors.length) {
result.update_ok = false;
result.update_error = updateErrors[0].slice(0, 800);
}
const frame = await page.evaluate(() => { const c = window.__c3v.cameras()[0]; return window.__c3v.cameraChecks(c); });
result.first_camera = frame;
// the render/check exercises above may have repaired a camera AFTER the census
// was captured: stitch it back so census.camera_repair is observable (review-3 S5)
const reps = await page.evaluate(() => window.__c3v.cameraRepairs());
if (reps.length) result.census.camera_repair = reps;
const sunAz = parseFloat(args['sun-azimuth']);
const bounds = args.bounds !== 'none' ? readJsonArg(args.bounds, 'bounds') : null;
if (Number.isFinite(sunAz)) result.fitted_cameras = fitCameras(result.census, sunAz, bounds);
}
phase = 'report';
// Probe truth is snapshotted BEFORE any forced compile: the probe gate sees
// exactly what a standalone probe would; the preflight below sees everything.
result.shader_errors = await page.evaluate(() => window.__c3v.shaderErrors());
Object.assign(result, errorSummary(host.errors, boot));
result.ok = boot.ok && result.update_ok === true && result.console_errors.length === 0 && result.shader_errors.length === 0;
if (args.compile) {
phase = 'compile';
const ts = Date.now();
if (boot.ok) {
const { report, files } = staticShaderReport(path.resolve(args.ws), null);
await compileIntoReport(report, files, host);
report.ok = report.errors.length === 0;
report.duration_ms = Date.now() - ts;
result.shader_report = report;
} else {
result.shader_report = { ok: false, skipped: 'scene did not boot', errors: [], warnings: [], compile: null, duration_ms: Date.now() - ts };
}
if (args['shaders-out']) writeJson(path.resolve(args['shaders-out']), result.shader_report);
}
result.duration_ms = Date.now() - t0;
phase = 'close';
clearTimeout(watchdog);
await host.close();
if (args.out) writeJson(path.resolve(args.out), result);
return finish(result, result.ok ? 0 : 1);
} catch (e) {
await host.close();
return fail(`probe failed: ${e.message}`);
}
}
main().catch((e) => fail(e.stack || String(e)));