Skip to content

Official Codebase of 3DCodeVerse

Python
10.7 KB
Raw Blame

runtime_js — harness-owned node runtime

Everything Three.js / headless-Chrome the harness does lives here. Agent code never imports from this directory; it only imports three (and three/addons/...), which the harness resolves for it — through the --import lib/resolve_three.mjs hook in node, and through the import map serve.cjs::importMapHtml() in the browser (runtime_js is mounted at /__runtime/; nothing is fetched from a CDN).

Install

This directory is an ordinary npm package owned by the harness: package.json and package-lock.json are committed, node_modules/ is not (gitignored, ~97 MB, 99 packages). Node itself is a system prerequisite — installing it is separate from what npm ci does here.

Node floor: 20.6.0 (package.json engines.node; developed on v24.14.0). 20.6.0 is where node --import lands, which lib/resolve_three.mjs needs; the npm dependencies themselves bottom out at node 18, and node:util.parseArgs (the CLI helpers) at 18.3. Between 20.6 and 22.15 the resolver registers the older async loader hooks (lib/resolve_three_async.mjs, a separate loader thread) instead of the in-thread module.registerHooks; the resolutions are identical. The python side refuses to spawn an older node with an actionable message (codeverse3d.spatial.node.NODE_MIN, mirrored by 3dcodeverse doctor's node row), and tests/core/test_portability.py pins the two declarations together. The floor is exercised, not assumed: the 139 node-marked tests all pass on node 20.19.5 (C3D_BINARIES__NODE=/path/to/node20 pytest tests -m "node and not live and not blender").

cd harness/runtime_js
npm ci                                  # exact-lockfile install (~2 s); NOT `npm install`
npx puppeteer browsers install chrome   # only if ~/.cache/puppeteer is empty

bash harness/setup.sh does both of these (plus the python install, the agy / claude / codex CLIs at their latest, and 3dcodeverse doctor) and skips npm ci when the lockfile has not moved.

Re-run npm ci after a fresh clone or after pulling a package.json / package-lock.json change — it deletes node_modules/ first, so never while a render or bench is running. Deps: three 0.182 (export + render + scene host), puppeteer 24 (headless Chrome, downloads its own build into ~/.cache/puppeteer). Full guide: ../docs/INSTALL.md.

gpu_launch.cjs        launchBrowser({gpu:'auto'|'on'|'off'}) → {browser, gpu, renderer, shared, release()};
                      rendererInfo(browser).  Callers must release(), never browser.close(): connect-first
                      reuse shares one browser per backend via browser_daemon.cjs (endpoint file under
                      C3D_CACHE_DIR, connect ~5 ms vs ~0.55 s launch; C3D_BROWSER_REUSE=off disables).
                      WSL2 hardware WebGL (ANGLE gl-egl + Mesa d3d12 env), UNMASKED_RENDERER probe,
                      negative verdict cached 20 min in ~/.cache/codeverse3d/gpu_probe.json, SwiftShader fallback
browser_daemon.cjs    detached keeper of the shared browser (one per gpu|cpu backend): advertises its
                      ws endpoint, reaps after ~90 s idle (endpoint-file mtime heartbeat + open-page count)
serve.cjs             serveDirs({root, mounts, routes}) loopback static server (MIME table, CORS);
                      runtime_js is always mounted at /__runtime/; importMapHtml() maps 'three' +
                      'three/addons/' onto it — nothing is ever fetched from the internet
export_glb.mjs        node --import lib/resolve_three.mjs export_glb.mjs --ws <ws> [--entry src/object.js]
                      [--out artifacts/object.glb] [--census artifacts/census.json]
                      imports the agent module, build(THREE) (awaits promises), validates
                      (NaN/empty-bbox errors name the mesh + part), runs an exported selfcheck(THREE, root)
                      if any (throw → SelfCheckError), bakes InstancedMesh copies into named meshes
                      (lib/instances.mjs — trimesh ignores EXT_mesh_gpu_instancing), keeps the source
                      placement (off-ground/off-centre → warning + census.placement_offset), strips textures (warning),
                      writes GLB + census.json (only what the export knows: placement offset, baked
                      instances, selfcheck, tick, unnamed meshes, warnings — spatial/measure.py measures
                      the GLB); on failure export_error.json +
                      {ok:false,error:{type,message,file,line,frames,part?}}
render_glb.mjs        --glb --out --views '[{name,azimuth,elevation}]' [--mode shaded|wire|normals|silhouette|clay]
                      [--width --height] [--isolate A,B] [--explode 0.3] [--background studio|white|transparent]
                      [--anim-time t] [--gpu auto|on|off] [--shadow 0|1]
                      writes view_<name>.png + views.json; last stdout line = JSON record.  Thin entry:
                      args/JSON protocol from lib/cli.mjs, browser + server from lib/host_env.mjs,
                      browser release from lib/host_page.mjs, everything visual from lib/browser/
lib/resolve_three.mjs node --import hook: bare 'three' / 'three/addons/*' resolve
                      from runtime_js/node_modules for modules anywhere on disk (NODE_PATH is CJS-only);
                      module.registerHooks on node >= 22.15, module.register + lib/resolve_three_async.mjs
                      on the 20.6 floor.  Redirect rule stated once in lib/three_redirect.mjs
lib/node_polyfills.mjs FileReader shim so GLTFExporter writes binary GLB without a DOM
lib/census.mjs        NaN/Infinity check naming mesh + part, world boxes, geometry triangles (node + browser)
lib/instances.mjs     bakeInstancedMeshes(THREE, root): InstancedMesh → sibling plain meshes Name_0.. in its place
lib/stack.mjs         Error → {type,message,file,line,frames} with workspace-relative src/ paths
lib/syntax_check.mjs  THE JS syntax check: every file parsed as an ES module in ONE node
                      (vm.SourceTextModule, never linked or run; `node --check` only for a failing
                      file's line).  CLI for the python lints, findSyntaxError() for export_glb
lib/asset_check.mjs   the scene-asset checker: import one asset module, call build<Pascal>(THREE, {}),
                      measure the group (size, tris, meshes, materials, NaN positions); one JSON line
                      for tracks/scene_assets.check_threejs_asset
lib/browser/*.js      page-side ESM (served through /__runtime/): renderer.js (THE WebGLRenderer factory —
                      sRGB + ACES + PCF shadows + pixel ratio 1, used by the object rig AND the scene host),
                      camera_fit.js (azimuth/elevation → tight bbox fit; the distance math itself is
                      lib/orbit.mjs::fitDistance, shared with the scene orbit rig), studio.js
                      (softbox PMREM + key/fill/rim, shadow catcher, render modes), render_rig.js
                      (load GLB, isolate/explode/anim, views)
lib/browser/studio_env.js procedural softbox environment, backdrop and contact-shadow textures of the
                      object rig (v2): generated from constants, so a render is byte-reproducible
lib/browser/post.js   THE scene post chain (object renders stay raw): RenderPass → finite clamp → GTAO →
                      glow bloom → grade (scene.userData.grade) → OutputPass; `--no-post` / C3D_POST=0 skips it

probe_scene.mjs       scene build gate: boot src/scene.js, census, update(t,dt), first-camera checks;
                      --compile folds the full shader preflight into the SAME boot (shader_report);
                      --sun-azimuth returns harness-fitted overview + per-group camera specs (lib/orbit.mjs)
check_shaders.mjs     the effect-library tests' compile driver: the same preflight as probe_scene --compile,
                      plus --module to scope the static audit to one fixture file
render_scene.mjs      authored cameras + orbit rig renders at times, metrics.json/views.json
fit_orbit.mjs         the same framingBox + fitOrbitCameras on a census.json WITHOUT a browser (scene_blender)
lib/host_env.mjs      ESM adapters over gpu_launch.cjs + serve.cjs (launchBrowser, serveWorkspace)
lib/host_page.mjs     node-side page driver: serve ws, launch, boot scene, collect errors, release the browser
lib/scene_host.mjs    page-side host (window.__c3v): boot/renderAt/census/compileAll/fps/cameraChecks
lib/glb_scene.mjs     the createScene the host boots for an OFFLINE scene (`--glb`, scene_blender): hoists the
                      census GLB's root nodes + extras.c3d_cameras — the same census and placement code
lib/host_compile.mjs  page-side compile machinery: capture every custom material's final GLSL, attribute
                      compiler errors to materials by source line, audit runtime materials (fog/uTime)
lib/host_shader_errors.mjs renderer.debug.onShaderError hook: every `ERROR: n:m` with its assembled source line
lib/host_placement.mjs placementTable(scene): does every placed asset sit on something (feet columns, gaps,
                      sunk, water, interpenetration; time-budgeted) + the boot-time settle
lib/placement_words.json the seated-vocabulary both the settle and spatial/scene_placement.py read
lib/update_hooks.mjs  observeUpdateHooks: which userData.update hooks the sampled update interval never called
lib/orbit.mjs         THE camera-fit owner: fitDistance (exact per-corner frustum fit — also used by the
                      object rig through lib/browser/camera_fit.js), fitOverviewCamera, fitZoneCamera
                      (eye level), fitOrbitCameras, framingBox
lib/backdrop.mjs      THE sky/ground/content classifier (name + world-box rules), shared by the census
                      (host_census.mjs) and the frame-coverage instrument (host_coverage.mjs)
lib/host_metrics.mjs  page-side frame instruments: sampleFrame (the shared 96x54 readback grid),
                      frameStats (luminance), nearGeometry (camera-in-geometry rays)
lib/shader_report.mjs shared shader-preflight report builder (static + compile stages)
lib/glsl_audit.mjs    static GLSL audits + compiler-line → file:line mapping

Conventions (from codeverse3d/conventions.py): Y up, +Z front, meters; azimuth 0 = front, counter-clockwise seen from above (90 = camera on +X); elevation above the horizon. Views are fitted per camera so the projected bbox fills ~85 % of the frame.

Python entry points: codeverse3d.spatial.node.run_node, codeverse3d.spatial.render.render_glb, codeverse3d.languages.threejs.ThreeJsRuntime.

Quick checks:

node --import lib/resolve_three.mjs export_glb.mjs --ws /path/to/ws
node render_glb.mjs --glb ws/artifacts/object.glb --out /tmp/r --views '[{"name":"front","azimuth":0,"elevation":10}]'