Make real 3D with raw code: Blender bpy, CadQuery, Three.js, URDF, GLSL and OpenGL objects, mechanisms, scenes and shader effects, with the 3dcode instruments and a judge subagent.

GitHub stars
405

Install

/plugin install 3dcodeverse@3dcodeverse

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gaoypeng/3dcodeverse.

Contents

Discovered from source

Skills 29

Blender bpy — static objects

You own the mesh: every part is authored geometry with the exact name the plan gives it. The build owns the scene setup, the export and the cameras: never save, render or add lights.

Files (the lint and the wrapper read exactly these)

  • src/model.py — the entry: imports each part's builder and calls it ONCE (a builder called twice builds Name.001).
  • src/parts/<snake>.py — one per plan part (SeatCushion → seat_cushion.py) defining build_seat_cushion() -> bpy.types.Object: builds the part at its WORLD pose with its exact name, links it to bpy.context.scene.collection, returns it; instances Leg_0 … Leg_N-1 are built in that one file and returned as a list. A part file only DEFINES (a module-level call builds twice: lint WARN); a part file model.py never imports is never built (WARN); a builder not named build_<snake> is a lint ERROR. src/ is on sys.path (from parts.seat import build_seat); src/parts/_<name>.py is a shared helper. A single src/model.py with no src/parts/ is accepted (the lint then expects the part names there).
  • The build runs blender -b --factory-startup on an EMPTY scene, takes a census, exports artifacts/object.glb (Y-up) + object.stl with modifiers applied; errors come back as src/parts/<file>.py:<line>. random, numpy and mathutils.noise are seeded before your module runs, so draws repeat from build to build.
  • references/interface.md is the interface, executable.

Frame, units, placement (the contract gate of 3dcode check)

  • Z up, −Y front, +X right, metres (a 450 mm seat is 0.45; a measured bbox of 450 × 500 × 900 means the plan was typed in mm). The exporter maps to Y-up itself: do not pre-rotate.
  • Lowest vertex at z = 0: off by > 1 cm is a WARN, > 3 cm an ERROR. Footprint centre within max(1 cm, 10 % of the larger horizontal extent) of the Z axis (WARN). Findings print the translation that fixes them. The export is AS AUTHORED — translating the whole assembly is fine; bpy.ops.object.origin_set changes what is measured.

Naming and structure (the contract gate, the census)

  • One top-level mesh object per plan part, obj.name exactly the plan's PascalCase; a merged mesh reports every other part missing, a misspelt name is an ERROR. Instances <Name>_0 … <Name>_N-1; Leg.001 means two objects claimed one name.
  • A parent Empty merges its subtree into ONE part; a scaled parent bakes its scale into the children. Collections are organisation only. bpy.ops.object.join inherits the ACTIVE object's transform (lint WARN without one).
  • Every object made through the data API must be linked to bpy.context.scene.collection; every visible object exports — delete cutters and guides or hide_render / hide_viewport / hide_set(True) (an unapplied boolean still evaluates with a hidden cutter). A curve exports only with bevel_depth > 0.

Sizes and contact (the contract and connectivity gates of 3dcode check)

  • Each part's built AABB (after modifiers) vs its plan row: per axis tol = max(1 cm, 10 % of the planned extent); past tol WARN, past 3 × tol ERROR, with the per-axis delta. Instances are measured on extents (each copy or their union); a wrong copy count is a WARN.
  • Contact: surface gap ≤ 2 mm counts as touching (a flush face IS contact; the 2 mm is a welding allowance, not a budget — a leg sunk 8 mm into a seat is a modelling error); overlap

    2 mm is interpenetration (WARN), 10 mm with ≥ 2 % of one part's surface inside the other an ERROR (score cap 0.70). Every part must reach the ground-touching component through contacts: a floating part is an ERROR (cap 0.60) whose finding prints the fix. Fix a gap by moving or extending the part, never with connector sticks.

  • Islands: no shell inside a part smaller than 5 % of its largest extent (WARN "tiny disconnected island": boolean debris, a stray vertex, an un-merged mirror half). Zero-thickness faces have no volume and break booleans; coincident faces z-fight.
  • Budgets (detail_budget, sized from parts × instances): < 350 triangles per built object WARN (floor clamped to 1 500–40 000 total), > 20 000 per built object ERROR (ceiling clamped to 60 000–600 000); a build over 3 s per built object (≥ 20 s) WARN; killed at 300 s. Per-vertex Python loops over large meshes hit the limit — foreach_set, modifiers, fewer segments.

Sandbox (the lint)

  • Allowed imports: bpy, bmesh, mathutils, bpy_extras, math, random, numpy, itertools, functools, collections, typing, dataclasses, colorsys, statistics, operator, enum, copy, sys, os, __future__, your parts.*. Else WARN; pathlib, subprocess, urllib, requests, socket, http, shutil, ctypes, pickle ERROR.
  • ERROR calls: bpy.ops.render.*, bpy.ops.export_* / import_*, bpy.ops.wm.*, bpy.ops.image.save, bpy.data.libraries.*, open(, os.system / file-IO os.*, subprocess.*, shutil.*, network, exec / eval / __import__ / input(). WARN: cameras, lights, worlds, render settings, scene.camera, scene.world, bpy.ops.view3d.* / bpy.ops.screen.*, sys.exit.

Materials (what the exporter keeps)

  • Flat PBR only — base colour, metallic, roughness, emission, alpha — plus IMAGE textures; procedural node trees are NOT exported (the judge sees the flat base colour). Principled inputs on 5.2: Base Color, Roughness, Metallic, Alpha, Emission Color + Emission Strength, Specular IOR Level, Transmission Weight, Coat Weight, Sheen Weight, Subsurface Weight; the pre-4.0 keys (Specular, Transmission, Emission, Clearcoat, Sheen, Subsurface) raise KeyError (lint ERROR). mat.use_nodes is deprecated (every material has a tree). Transparency: mat.surface_render_method = 'BLENDED' (mat.blend_method still exists on 5.2.2 but is legacy).
  • Several colours on one part = several slots (obj.data.materials.append) + polygon.material_index (every polygon starts on slot 0); the census warns on unused slots or an index past the last slot — that warning means the assignment did nothing and the part exports in one colour.

API traps (Blender 5.2.2; build errors or silent wrong sizes)

  • bpy.ops.* needs bpy.context.temp_override(object=obj, active_object=obj, selected_objects=[obj]); the dict-override form was removed in 4.0 (ERROR). bpy.context.object / selected_objects are unreliable headless — keep your own references.
  • bmesh.ops.create_* centres on the origin and needs no context; bpy.ops.mesh.primitive_*_add defaults to size=2 — pass size=1 with scale= (else the extents double, WARN), then transform_apply(location=False, rotation=False, scale=True) with all three keywords (an omitted keyword defaults to True and bakes the location, WARN). Keep obj.scale at 1 by export time: nothing resets it, and a scaled object is exported and measured scaled.
  • bm.verts[i] / bm.faces[i] need ensure_lookup_table() after from_mesh or any topology op (IndexError). create_cube / create_cone return only verts.
  • Modifiers may stay unapplied (the exporter applies them); modifier_apply needs temp_override and a single-user mesh (obj.data = obj.data.copy() first). Boolean solvers MANIFOLD / EXACT / FLOAT ('FAST' raises); a cutter coplanar with the face it cuts fails silently.
  • bmesh faces smooth with face.smooth = True (a BMFace has no use_smooth; that is the mesh polygon's).
  • Removed (lint ERROR): use_auto_smooth / auto_smooth_angle (use polygon.use_smooth or shade_smooth_by_angle), Mesh.calc_normals(), mod["Socket_2"] = v (getattr(mod.properties.inputs, "Socket_2").value = v). Removed and NOT linted: calc_normals_split(), edge.crease / edge.bevel_weight (crease_edge / bevel_weight_edge attributes), scene.node_tree, bgl, gpu.types.GPUShader(...). BLENDER_EEVEE_NEXT is not an engine id on 5.x (lint WARN; render settings are the build's).

Built as a scene hero (blender_glb)

When this workspace builds a hero for a scene plan: nothing outside the asset — no ground plane, no environment. A moving part (only when the asset's description names one): keyframe that part's OWN rotation/location with its origin at the pivot (an Empty is not a part); the build runs at the factory 24 fps, so a key on frame f lands at t = f / 24 s — key frame 0 and frame 36 (t = 1.5 s, the scene's second sampled time) with the pose differing ≥ 0.15 rad or ≥ 0.05 m; the GLB carries the action as a clip the scene loops, so end where you start.

The loop

write every part file → 3dcode check (build, contract, connectivity, budget) → fix each ERROR at the file:line or part it names → 3dcode check again until no ERROR → 3dcode judge. No render-sheet before the first judge: isolate --part X and cross-section answer "is this part where I think it is" from numbers, faster than a look. A clean simpler object beats a richer one with a visible defect: clear the ERRORs, then spend on the brief's detail. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

CadQuery — static objects

You drive a real B-rep kernel: shapes are solids with topology, and the kernel refuses an operation it cannot make valid. The build owns the export and the cameras: never save, render or show_object.

Files and result

  • src/model.py is the entry. The build runs it in a subprocess (src/ first on sys.path, so a helper module beside it imports) and reads the module-level variable result; it must exist at import time (not under if __name__ == "__main__"). random and numpy are seeded before the module runs; nothing may depend on time — the build runs twice (measure, render) and both must match.
  • result = cq.Assembly(name="<ObjectName>") with one .add(solid, name="<PartName>", color=cq.Color(r, g, b), loc=cq.Location(...)) per plan part. Part names PascalCase, unique, exactly the plan's (they become the GLB node names); instances Name_0..Name_N-1. cq.Color takes 0–1 floats. Assemblies nest; a child's loc composes with its parent's.
  • A bare result = <cq.Workplane> builds one solid exported as the node Object (lint WARN; the plan's part names are then not in the GLB). A chain ending on a selector exports the parent solid with a warning; no recoverable solid errors naming the stack types; a bare cq.Face is "contains no solid".
  • references/interface.md is the interface, executable.

Frame, units, placement (the contract gate of 3dcode check)

  • Z up, −Y front, +X right, metres at real scale (the wrapper converts to Y-up GLB). Author in world coordinates (identity loc) or at the origin and place with loc=cq.Location(cq.Vector(x, y, z)). Export is AS AUTHORED: seat the assembly on the ground yourself.
  • Lowest point within 10 mm of z = 0 (WARN; 30 mm ERROR). Footprint centre within max(10 mm, 10 % of the footprint extent) of the up axis (WARN). Each part's bbox and the overall bbox within max(10 mm, 10 % of the plan extent) per axis (WARN; 3 × ERROR). A part the plan does not name is an INFO — the judge still sees the stray solid.
  • Angles: .rotate(p0, p1, deg), cq.Location(v, axis, deg), .revolve(deg), .twistExtrude(h, deg) take DEGREES; math takes radians. The lint checks three-argument .rotate(...) (a math.pi expression there is an ERROR).

Contact (the connectivity gate of 3dcode check)

  • Surface gap ≤ 2 mm is contact; overlap > 2 mm WARN "interpenetrate", > 10 mm with ≥ 2 % of one part's surface inside ERROR (judge cap 0.70). Parts under 10 mm are skipped.
  • Every part must be in the ground-touching component; an unreachable part is a floating ERROR (cap 0.60) — two parts touching only each other are both floating. The finding prints the translation that closes the gap.
  • A second solid inside a part (a cut that split it, a union that did not meet) smaller than 5 % of its largest extent is a stray-island WARN. Two plan parts unioned into one read as a missing part.
  • Budgets (detail_budget, sized from parts × instances): < 350 triangles per built object after tessellation WARN (floor clamped to 1 500–40 000), > 20 000 per built object ERROR (ceiling clamped to 60 000–600 000); a build over 3 s per built object (≥ 20 s) WARN; killed at 300 s.

Imports and calls (the lint)

  • Allowed: cadquery (as cq), math, random, numpy, itertools, functools, collections, typing, dataclasses, enum, copy, statistics, operator; anything else WARN "may not exist in the build sandbox".
  • ERROR imports: os, sys, pathlib, subprocess, shutil, socket, urllib, requests, http, ftplib, smtplib, webbrowser, ctypes, pickle, multiprocessing, threading, importlib, OCP, OCC, ocp_vscode, cq_editor, cq_warehouse, build123d.
  • ERROR calls: show_object, show, open(, cq.exporters.*, cq.importers.*, .save() / .export*() on the assembly, exit / quit.

Kernel facts (what the build reports as an error)

  • cq.Workplane("XY") normal +Z (up), "XZ" normal −Y (the front elevation), "YZ" normal +X. .extrude(h) goes along the normal; .hole(d) cuts in −normal.
  • .box(x, y, z) is centred unless centered=(…) — centered=False puts the MIN corner at the origin on all axes. .cylinder(height, radius) takes height first.
  • .rotate(), .translate(), .mirror() return NEW objects — assign the result.
  • A fillet or chamfer whose radius reaches the adjacent wall, or whose edges conflict, raises StdFail_NotDone: BRep_API: command not done and fails the WHOLE build (no GLB); the hint is radius < 0.45 × the thinnest adjacent wall. A cosmetic fillet in try/except falling back to the unrounded solid is the one allowed exception. A selector matching nothing raises ValueError.
  • A revolve profile stays at r ≥ 0; in Workplane("XZ") the axis (0, 1, 0) is plane-local (world Z). .center() before a revolve moves the profile onto the axis and the kernel refuses; .moveTo() does not.
  • cq.Solid.makeSphere(r) without angles is a hemisphere (lint WARN); cq.Workplane("XY").sphere(r) is full. Features under ~0.5 mm come out invalid. .text() may raise headless (no fonts).

The loop

write → 3dcode check (the build surfaces the OCC exceptions with the line; then contract and connectivity) → fix each ERROR → 3dcode check again until no ERROR → 3dcode judge. Detail the brief asks for is scored; a feature the kernel refused fails the build unless wrapped, and then it is not there. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

GLSL fragment shader — graphics

You write ONE Shadertoy-style image pass; the build wraps it, compiles it (OpenGL 3.3 core, headless), renders the judged frames up to duration_s, measures them and shows them to the judge. Every frame is a pure function of the pixel and absolute u_time (plus the samplers); there is no state between pixels.

Files

src/shader.frag     REQUIRED  the image pass: mainImage() composites the layers — a few dozen lines (no #version, no uniform/out declarations)
src/*.glsl          include files, ONE LAYER EACH, a few KB: 10_noise.glsl, 20_sky.glsl, 30_aurora.glsl, 40_terrain.glsl … — pasted ABOVE shader.frag (and buffer_a.frag) at build time, common.glsl first if present, then file-name order (number the prefixes so helpers precede their callers); functions and constants only
src/buffer_a.frag   optional  ONE feedback buffer pass, rendered every frame before the image pass

Nothing else is read (a file under src/ of another kind, or a .glsl in a subfolder, is a lint WARN stray_file). Every error the build prints names the include file and ITS line. references/interface.md is the interface, executable.

What the build prepends (writing these yourself is a lint ERROR)

#version 330 core
uniform float u_time;         // seconds; judged frames at t = 0, 1, 2.5, 4, 6 s
uniform vec2  u_resolution;   // pixels
uniform vec2  u_mouse;        // always (0,0) headless
uniform int   u_frame;        // frame counter — NOT a clock: the sampled times are not evenly spaced
uniform sampler2D u_prev;     // previous frame of THIS pass; black at frame 0
uniform sampler2D u_noise;    // 256x256 RGBA white noise, repeat, linear: one fetch is a bilinear hash
uniform sampler2D u_buffer_a; // output of src/buffer_a.frag (only when that file exists)
#define iTime u_time          // Shadertoy aliases: iTime iResolution iFrame iMouse iChannel0(=u_prev) iChannel1(=u_noise)
out vec4 fragColor;           // the ONLY output

NOT available: iChannel2/3, iDate, iSampleRate, iChannelResolution, textures, images, sound.

Entry point (one of the two)

void mainImage(out vec4 fragColor, in vec2 fragCoord) (preferred) or void main() using gl_FragCoord.xy. Pixel coordinates, origin BOTTOM-LEFT, y up (the build flips rows when it writes PNGs). u_prev / u_buffer_a are sampled at fragCoord / u_resolution. Circles must stay round at the plan's resolution (judge defect stretched_aspect, −0.06): normalise both axes by u_resolution.y.

What is measured (3dcode gl-frames; the cap is the highest score the round can get)

measuredthresholdfindingcap
any NaN / Inf pixel≥ 1nan ERROR0
every frame black> 97 % of pixels under luminance 0.03 in each frameblack ERROR0.5
every frame blown> 97 % over 0.98 in each frameblown ERROR0.5
largest mean |Δ| between consecutive frames< 0.002 (plan motion non-empty)static WARN0.5
largest mean |Δ| between consecutive frames> 0.35flicker WARN0.7
mean edge density< 0.002low_detail WARNnone (the judge is told)
any lint ERROR0.6
build failure (compile error, render timeout)0
NaN sources: division by zero, sqrt / pow / log of a negative, normalize of a zero vector,
acos / asin outside [−1, 1]. An unmet must acceptance item caps at 0.7.

The lint (ERROR unless noted)

  • GLSL 330 core: texture() not texture2D; fragColor not gl_FragColor; no varying / attribute; % is integer-only — mod(x, y) on floats.
  • No uniform declarations (yours would never be set — use const), no out, no #version, no #include; precision is ignored (INFO). Only u_prev, u_noise, u_buffer_a may be sampled. An include file must not define main() / mainImage(); inside buffer_a.frag the previous buffer is u_prev (sampling u_buffer_a there is a WARN). > 60 000 characters in one file WARN — split the layers.

Build errors

src/<file>:LINE: error: … — the include file or pass and YOUR line number in it. "no matching function": an int literal where a float is expected (pow(2, 3), mod(x, 2)) — write 2.0; "too few components": vec4(col) of a vec3 needs vec4(col, 1.0); "redeclaration": a harness uniform declared again; "undeclared": a typo, or a helper defined in an include file that sorts AFTER its caller. Loop bounds are compile-time constants (break early inside); smoothstep(a, b, x) is undefined for a ≥ b; a frame that does not finish inside the render timeout fails the build.

Feedback and determinism

u_prev is THIS pass's previous frame (black at frame 0); buffer_a.frag reads its own previous output as u_prev (neighbours at uv ± 1.0 / u_resolution) and shader.frag reads it as u_buffer_a. An accumulation with gain ≥ 1 saturates by t = 6 s (blown). No per-frame random seeds, nothing that depends on u_frame alone (flicker).

What the judge (shader) names

Weights: likeness 0.26, depth_and_detail 0.16, light_and_tone 0.16, motion_quality 0.14, composition 0.10, technical_cleanliness 0.10, craft 0.08. Likeness: the wrong physics scores 0.4 however complete the inventory — evenly spaced bars standing in for curtains, rays, flames or waves (comb_artefact, −0.10, cap 0.65); hard-edged opaque shapes standing in for light — bokeh, glow, aurora, neon (opaque_shapes_for_light, −0.08); a few sparkles for a star field (a star field is thousands of points); a flat wash for a nebula. Depth and detail: one texture or noise field filling the frame is flat_fill (−0.08); staircase edges banding_or_aliasing (−0.05, and a technical_cleanliness deduction). Light and tone: a night subject with nothing near-black no_dark_range (−0.06); haze lifting a region toward white white_wash (−0.08); uniformly candy-saturated colour candy_saturation (−0.06). Motion: a texture scrolling under a fixed shape is 0.5; a hard cut between two sampled times is flicker (−0.08, cap 0.70). A textbook demo with the brief's colours swapped in is placeholder_look (−0.10); an effect present in source but invisible in the frame is wrong_subject (cap 0.40) — check the final fragColor write, the raymarch hit test, the ray direction, a term multiplied to zero.

The loop

write one include file per layer, then shader.frag → 3dcode gl-probe (compiles? one frame at t = 1 s) → fix each compile error at the file:line it names → 3dcode gl-probe again until it compiles → 3dcode check (renders the judged frames, runs the gl_frames gate) → fix each ERROR (NaN, black, blown) → 3dcode judge. Do not finish while gl-probe reports anything: measured on a ten-rung ladder, sessions that ran this loop compiled 10 of 10, sessions without it 5 of 10. When a frame or a judge item says a layer looks wrong, edit THAT layer's function in its include file (the host's edit tool, scoped to the lines); never rewrite a file. Deleting a layer is a legitimate fix. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

moderngl program — graphics

You write ONE module, src/program.py, with a lifetime: setup(ctx, width, height) runs ONCE and returns your state; render(ctx, state, t, frame, fbo) may be called for any t, any number of times, in any order, and draws the frame for that t into the framebuffer it is handed. No window, no context creation, no clock of your own.

Files

src/program.py      REQUIRED  defines setup() and render()
src/*.glsl          optional  shader sources, one file per shader so program.py keeps only the GL plumbing; read with Path(__file__).with_name("x.glsl").read_text()

Only these two globs are delivered; another src/*.py is a lint WARN (stray_file). references/interface.md is the interface, executable.

The two entry points (exact signatures)

def setup(ctx: moderngl.Context, width: int, height: int):      # called ONCE; returns your state
def render(ctx: moderngl.Context, state, t: float, frame: int, fbo: moderngl.Framebuffer) -> None:
    ...                                                          # multi-pass into your own FBOs allowed
    fbo.use()   # the build's framebuffer (RGBA f4 + depth) — draw the FINAL image into it LAST
  • The build makes ONE sorted schedule of the judged times (t = 0, 1, 2.5, 4, 6 s, clipped to the plan's duration, never fewer than 3) and about 12 preview times; for each it binds fbo, clears it to (0, 0, 0, 1) with depth 1.0, sets ctx.viewport to the full size and calls render. frame is the index into that merged schedule — not a 60 fps counter.
  • The sampled-time trap: a simulation that advances one step per call has taken five steps by the last judged frame. Pose from t; if a state must integrate, integrate to t inside the call. Same t → same image, whatever was rendered before.
  • After render the build reads fbo back as float and flips the rows: draw with y up, do not flip in the shader. If you draw into your own FBOs, call fbo.use() and reset ctx.viewport = (0, 0, width, height) before the final pass. Never call ctx.screen.
  • Width / height come from the plan's resolution (1280 × 720 when unusable; at most 1920 × 1080). The whole schedule renders inside 300 s or the build fails.

The lint (an ERROR caps the score at 0.6)

  • Imports allowed: moderngl, numpy, math, random, struct, array, pathlib, typing, dataclasses, itertools, functools, collections, colorsys, enum, __future__; anything else is an ERROR.
  • ERROR: window / input libraries (glfw, pygame, pyglet, PyQt, PySide, tkinter, moderngl_window, sdl2, wx, PyOpenGL); os, sys, io, time, datetime, signal, tempfile, subprocess and network modules; open / exec / eval / compile / __import__ / input / exit / quit / breakpoint; file-system writes (.write_text / .write_bytes / .unlink / .mkdir / .rmdir / .rename); moderngl.create_context() / create_standalone_context(); time.time() / perf_counter() / monotonic(); gl_FragColor, attribute / varying in a shader string.
  • WARN: a #version other than 330 core (glsl_version); random.* without random.seed(...) or a default_rng(...) (unseeded_random) — seed in setup; a file over 120 000 characters; an extra src/*.py.
  • No cleanup() callback: when you replace resources, release each VAO, buffer, texture, framebuffer and program you own; never release the supplied ctx or fbo.

moderngl facts that decide whether the build runs

  • Every shader string starts with #version 330 core on its first line (nothing before it), uses in / out and declares out vec4 fragColor;.
  • ctx.vertex_array(prog, [(buffer, "3f 3f 2f", "in_pos", "in_normal", "in_uv")], index_buffer=ibo): names match the vertex shader's ins; x pads bytes ("3f 3f 2x4"); /i is per-instance ("3f 1f/i", vao.render(instances=n)). A wrong float count silently shuffles the data. buffer.write(...) keeps the byte size.
  • An in or uniform the compiler optimised away is absent from prog: setting it raises KeyError: 'u_name' — remove it, pad it, or guard with if "u_name" in prog:.
  • prog["u"].value = 1.0 / (r, g, b); matrices: numpy is row-major and GLSL column-major, so prog["u_m"].write(M.T.astype("f4").tobytes()), never .value = m.tolist().
  • A sampler is a texture unit: prog["u_tex"].value = k once, tex.use(location=k) on every render before the draw that samples it.
  • ctx.clear(...) clears whatever framebuffer is bound (my_fbo.clear(...) for your own). An offscreen framebuffer tests depth only with a depth_attachment= (ctx.depth_renderbuffer); reading and writing the same texture in one pass is undefined.
  • With CULL_FACE a front face is counter-clockwise from outside (ctx.front_face defaults to "ccw"; wound the other way the mesh is inside out). GL 3.3 core: no line_width above 1, no GL_QUADS; ctx.wireframe = True is a debugging aid.
  • Errors come back as src/program.py:LINE: <Exception>; GLSL compile errors show the driver log with line numbers inside the shader STRING.

What is measured (3dcode gl-frames; the cap is the highest score the round can get)

measuredthresholdfindingcap
any NaN / Inf pixel≥ 1nan ERROR0
every frame black> 97 % of pixels under luminance 0.03 in each frameblack ERROR0.5
every frame blown> 97 % over 0.98 in each frameblown ERROR0.5
largest mean |Δ| between consecutive frames< 0.002 (motion planned)static WARN0.5
largest mean |Δ| between consecutive frames> 0.35flicker WARN0.7
mean edge density< 0.002low_detail WARN ("a near-flat gradient")none
a lint ERRORany0.6
the build fails (import, setup, render, timeout)0
An unmet must acceptance item caps at 0.7. A periodic wrap that jumps between two sampled
times is the flicker finding. Get the frame into a readable band before spending on hue and
palette, which are invisible on dark, low-chroma pixels. The judge's named defects are the
3d-lang-glsl-shader skill's (flat_fill, comb_artefact, opaque_shapes_for_light,
no_dark_range, white_wash, candy_saturation, stretched_aspect, placeholder_look).

The loop

write → 3dcode gl-probe (imports? one frame at t = 1 s) → fix each error at the file:line it names → 3dcode gl-probe again until it runs → 3dcode check (renders the judged frames, runs the gl_frames gate) → fix each ERROR (NaN, black, blown) → 3dcode judge. Do not finish while gl-probe reports anything. A pass that looks wrong is edited in its own shader file or its draw code with the host's edit tool; never rewrite a file. Deleting a pass is a legitimate fix. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

Blender bpy scenes

Every mesh, material, light, world and motion is bpy / bmesh / mathutils you write. The build owns the process, the render settings, the cameras, the frame clock and the export; you build into the Collection you are handed.

Files (Z up, −Y front, metres)

src/scene.py            written by `3dcode validate-plan` from plan.json — data only (ZONES / ASSETS / HEROES / CAMERAS); never edit it, re-run validate-plan after a plan change
src/env.py              def height_at(x, y) -> z    def build_env(ctx) -> dict     (world, light, ground, atmosphere; an interior's shell)
src/zones/<snake>.py    def build(ctx) -> bpy.types.Collection      (everything linked into ctx.collection, the zone's own)
src/assets/<snake>.py   def build_<snake>(ctx, variant=0) -> bpy.types.Collection   (ONCE at the origin, base on z = 0, front −Y)
public/assets/<snake>.glb   heroes built as objects (a static_object/blender workspace's object.glb) — imported into ctx.assets['<snake>']

Code zones share lives in src/env.py (from env import …); an asset module is self-contained (built and checked on its own). The build runs ONE Blender process in this order, each builder in its own try/except: env.build_env(ctx); every hero imported; every assets.<snake>.build_<snake>(ctx); every zones.<snake>.build(ctx). A builder that raises is DROPPED with its file:line and everything it created removed — the rest still builds, so one bad zone costs that zone; a dropped asset is NOT AVAILABLE, so ctx.assets['x'] raises in every zone that instances it and drops those zones too. build_<zone>(ctx), create(), main(), register() are never called. Link every object into ctx.collection (an object in ctx.scene.collection belongs to no zone). Then the build adds the plan's cameras, hides the asset sources, writes the census and the .blend, and renders every camera at t = 0 and t = 1.5 s (frames 1 and 46). references/interface.md has an env and a zone module as-is.

The ctx every builder receives (data, never verbs)

fieldwhat it is
ctx.scenethe bpy Scene (read it; its render settings are the build's)
ctx.collectionthe Collection THIS builder links into — a zone's own (active, so bpy.ops primitives land in it), an asset's own, the scene root for build_env
ctx.height_at(x, y)the ground: env.height_at once the env built, else flat 0
ctx.envthe dict build_env returned (shared materials, the water level, the sun direction…); {} before
ctx.assets{snake: Collection} — every procedural asset built and every hero imported, at the origin, base on z = 0
ctx.rng(seed)random.Random(seed) — THE randomness (random.* and unseeded numpy are lint ERRORS)
ctx.fps, ctx.times30 and (0.0, 1.5)
ctx.frame(t)1 + round(t * fps): keyframe on ctx.frame(0.0) and ctx.frame(1.5)

Frame

Z up, −Y front, +X right, metres, the ground height_at(x, y) around z = 0. The PLAN is written in the Y-up GLB frame: a plan point (x, y, z) is Blender (x, −z, y) and plan extents (w, h, d) are Blender (w, d, h). Only the CAMERAS in src/scene.py are pre-converted; the bounds and zone bboxes you convert yourself, and check-placement reports boxes and the out_of_bounds bounds in the plan's Y-up frame. The plan's prose is not converted either — "y = 1.2 m up" is z = 1.2, "+z towards the camera" is −y.

Allowed imports

bpy, bmesh, mathutils (Vector, Matrix, Euler, noise), math, numpy (randomness only through numpy.random.default_rng(seed)), itertools, functools, collections, dataclasses, colorsys, and from env import … (module-level names of env.py).

Forbidden (lint ERRORs that fail the build gate)

bpy.ops.render.*, bpy.ops.wm.*, bpy.ops.export_*, bpy.ops.import_*, bpy.ops.image.save, bpy.data.libraries, bpy.data.cameras.new / bpy.ops.object.camera_add, any scene.render.* / scene.cycles.* / scene.eevee.* / scene.view_settings.* / scene.display_settings.* / scene.camera / scene.frame_* assignment, frame_set, bpy.app.handlers, bpy.app.timers, a driver whose expression needs Python (use_self, attribute access, **, %, noise.*), the world outside src/env.py, random.* and unseeded numpy, open(), os / sys / pathlib / time / datetime / subprocess / shutil / tempfile / glob / io. WARN: bpy.ops.mesh.primitive_* inside a loop (each call rebuilds the scene state), bpy.ops.view3d.* / bpy.ops.screen.*.

Blender 5.2 API facts (a build error or a silent zero)

Removed: use_nodes (materials, worlds and lights always have a tree; a new material carries Principled BSDF and Material Output), sky_type = 'NISHITA' ('MULTIPLE_SCATTERING', with aerosol_density), boolean 'FAST' (FLOAT / EXACT / MANIFOLD), mod["Socket_2"] = v (getattr(mod.properties.inputs, "Socket_2").value = v), Action.fcurves (slotted: action.layers[0].strips[0].channelbag(action.slots[0]).fcurves), Mesh.calc_normals() and use_auto_smooth (me.shade_smooth() or f.smooth = True), the Principled inputs Specular / Subsurface / Transmission / Emission (now Specular IOR Level, Subsurface Weight, Transmission Weight, Coat Weight, Sheen Weight, Emission Color + Emission Strength), ShaderNodeMixRGB (ShaderNodeMix with data_type = 'RGBA': inputs 6 / 7 the colours, output 2 the result; the mix input is Factor). Background mode: bpy.context.object / selected_objects are empty after bpy.data.objects.new — keep your own references. bm.verts[i] raises before ensure_lookup_table(). A fresh object's matrix_world is identity until the view layer updates (compose parent.matrix_world @ child.matrix_basis or bpy.context.view_layer.update()). Geometry nodes: a new tree has no sockets or nodes — ng.interface.new_socket(name, in_out='INPUT' | 'OUTPUT', socket_type='NodeSocketGeometry'), add the NodeGroupInput / NodeGroupOutput nodes yourself, obj.modifiers.new(name, 'NODES').node_group = ng.

What the renderer does with what you build

Cycles at 32 samples + OIDN, AgX, exposure 0, 1024 × 576; no post chain, no bloom: an emissive at strength 3–8 reads as a lamp, 20+ whites the frame (blown_frac), and a lamp beside it is what lights the wall. Light is physical: a Sun in W/m², lamps in Watts; starting pairs that landed in the exposure band on a mid-albedo ground — day: Sun 2–5 W/m² under a sky world at strength 0.2–0.5, Sun angle 1–3° so shadows read and shade keeps colour; dusk: 1–1.5 W/m² at 0.2; night: a moon 0.05–0.3 W/m² at 0.1, lit by practicals (an emissive skin plus a Point light with a radius); fog density 0.003–0.008. Hue, material and geometry work are invisible on near-black pixels. A SURFACE shader always has a silhouette: a soft particle (steam, smoke, dust, spray) renders edgeless only as a VOLUME — a material whose only linked output is the Material Output's Volume, fed by a ShaderNodeVolumePrincipled; a translucent puff, metaball, torus or disc is hard_edged_particles. The census is the evaluated depsgraph (modifiers, geometry nodes and instances count as rendered; a volume-only mesh is fog, never a placed thing). Triangle budgets: 15 000 per asset, 40 000 per hero, 3 000 000 unique for the scene (an instance cloud counts its instances as rendered, its source once).

Motion

Animation is DATA: obj.keyframe_insert(data_path, frame=ctx.frame(t)) at the two times (a location, rotation, shape key, node input), or a SIMPLE driver of frame (fc = obj.driver_add("rotation_euler", 2), fc.driver.expression = "frame * 0.1" — sin / cos / min / max / clamp / lerp, + - * /, comparisons; anything needing Python evaluates to 0 in a --factory-startup build). Set each keyframe_points[].interpolation = 'LINEAR' for a travel. The build differences the two frames per camera: a camera moves when ≥ 0.4 % of its pixels change by more than 8/255; none moving is no_motion (ERROR), the judge's nothing_moves. Amplitudes that registered: ≥ 0.10 rad, ≥ 0.05 m per 1.5 s, a particle / leaf / boat ≥ 0.6 m (an asset's own moving part: ≥ 0.15 rad). A hero GLB's own clip plays in every instance by itself.

Naming

PascalCase, globally unique (a second Lantern_0 becomes Lantern_0.001 and reports a prop nobody planned): number every copy f"{base}_{i}", never reuse a base across zones. The census classifies by name: Ground… / Terrain…, Water…, distant backdrop Sky… (a sky-named mesh wider than 50 m is backdrop, not content), an interior's shell RoomShell… / Ceiling… (the overview rig lifts the lid).

Placement (3dcode check-placement, on every build)

Every root object linked into a zone (a mesh, a parent Empty with children, a collection- instance Empty) is ONE row. From its lowest evaluated vertices the gate looks down for the nearest surface and up for one through it: a gap > 0.05 m outdoors / 0.02 m indoors is floating (ERROR at 0.08 m, or more than 2 floaters); buried > 0.10 m is sunken (ERROR at 0.20 m and a fifth of the height; rocks, posts and bushes may sit partly in; a foot at or under water is fine); touching nothing unsupported; two boxes sharing > 10 % of the smaller interpenetration (ERROR at 35 %). The feet are the foot band — the evaluated vertices within max(0.02 m, 5 % of its height) of the lowest, sampled as up to 5 columns. Seat a root by moving it by the smallest ctx.height_at(x, y) - z over that band's world-space vertices (children and the instanced collection through the Empty's matrix included), or onto its support's top; keep any two roots' world boxes from sharing > 10 %. Four or more foot columns with at most one touching and a gap > 0.05 m is cantilevered (WARN). obj["placement"] = "free" only for things MEANT to hang (WARN past 25 % tagged, ERROR past 50 %). Geometry-nodes instance clouds are exempt per asset. A planned content entirely outside the bounds + max(5 m, 10 % of the span) is out_of_bounds (WARN); an asset placed beyond 2.5 × the plan's size is a WARN, 4 × an ERROR — never re-scale an instance to fit; a chimney or pipe that must reach further is a separate object. Place an asset as a collection-instance Empty (bpy.data.objects.new(name, None), instance_type = 'COLLECTION', instance_collection = ctx.assets['<snake>']).

What else the gates measure

scene_frames (3dcode scene-views), every authored camera at both times: dark_frame (mean luminance < 0.12 or > 35 % near-black, cap 0.55), blown_frame (> 20 % near-white), flat_frame (> 85 % of pixels in one band; ERROR above 92 %), content_small (establishing camera ≥ 20 % content, others ≥ 10 %), camera_in_geometry (inside or within 0.5 m of a surface), camera_blocked (6 of 9 sight rays within 1.5 m), camera_underground — the camera findings cap at 0.50; eye < 0.3 m above the ground camera_low, > 80 m camera_high (WARN). hero_unseen: a hero covering < 0.5 % of the frame in every camera is an ERROR (< 2 % in its named camera a WARN). scene_probe (3dcode scene-probe): unique triangles over 3 000 000, a Python driver or app handler, no world, no atmosphere (no_fog: neither a world Volume nor a bounded fog volume — mist is not read), render settings touched; a hero that would not import is a WARN on its file. Outdoors fog_short warns when 1 / density < span / 1.5 and world_edge when no standing geometry reaches 1.25 × the bounds half-extent. A dropped zone / asset / env is an ERROR on its line.

Interiors

interior: true: the enclosure (floor, walls, lid named RoomShell… / Ceiling…) is src/env.py's; it must read enclosed from every camera and be lit inside; the floating threshold indoors is 0.02 m. Env cuts windows and doors as OPENINGS; zones put glazing and door leaves in the opening and wall fixtures flush against the inner face, and never build walls or a roof. Zones dress the inside; a partition or counter a zone needs is the zone's, seated and clear of the shell.

Realism (judged)

Every large surface varies at more than one scale — broad tone and wear over metres AND fine grain or bump over centimetres — in a node tree you wire (Noise / Voronoi / Wave through Mix and Bump); one constant colour per surface is placeholder_material / flat_ground. A tree is a trunk branching into limbs carrying leaf or needle cards, a rock an irregular asymmetric mass — never a cone, a ball on a stick or a cube (asset_quality_detail); one shape stamped many times is monotonous_vegetation. The world continues past the content in every frame (world_edge_visible). A pond, bed or terrace must not read as a plate laid on the terrain from the overview rig: carve it into height_at or give it a built edge or a dressed seam; inside a shoreline the terrain lies below the water level or the shore z-fights. Distant forms keep their natural colour, darkened — pre-tinted toward the fog they render brighter than the land and read as cardboard (placeholder_material). The brief's time of day is a hard constraint, decided once in src/env.py and shared through the dict build_env returns.

Asset modules

build_<snake>(ctx, variant=0) links every part into ctx.collection (pre-made, active) and returns it: at the origin, lowest point z = 0, footprint centred, front −Y, sized as the plan states (ERROR beyond 2.5 × or under 0.4 × on any axis); zones instance it at scale 1 and never call it. Imports bpy, bmesh, mathutils, math; no lights, cameras, world, file IO, ground plane. Every part has a Principled material with a real colour and roughness, varied at more than one scale; unique PascalCase names, one root mesh or children parented at RELATIVE locations; ≤ 15 000 triangles. variant changes the SILHOUETTE when several copies are placed; ctx.rng(seed) varies details and colour, so many copies are not one colour. A moving part (when the description names one) is keyframed on its OWN rotation/location with its origin at the pivot (≥ 0.15 rad or ≥ 0.05 m registers). Every sub-shape overlaps a neighbour by ≥ 2 mm; the lowest point is exactly z = 0.

The loop

write every module → 3dcode check (build, placement rows with the metres to move each thing, asset modules, census: triangles, drivers, the world) → fix each ERROR → 3dcode check again until no ERROR → 3dcode judge. Exposure and motion are measured at the judge and come back in score's list with the numbers (camera_checks.mean_lum, MEASURED MOTION); 3dcode scene-views is the refine round's one look. Get the floor and the light right; spend everything after that on the brief. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

three.js scenes

You write RAW ESM modules: import * as THREE from 'three', three/addons/*, your own relative files and the harness-owned src/lib/*.js — nothing else. The build owns the renderer, the render loop and the export; you build the scene graph and the cameras.

Files (Y up, +Z front, metres)

src/scene.js        export async function createScene({ THREE, renderer, loaders }) → { scene, cameras, update(t, dt) }
src/env.js          export function heightAt(x, z); export function buildEnv(ctx) → { update(t, dt) }; export const SUN_AZIMUTH_DEG
src/zones/<snake>.js   export function build(ctx) → THREE.Group   (ctx = { THREE, scene, renderer, loaders, heightAt, env, assets })
src/assets/<snake>.js  export function build<Asset>(THREE, opts = {}) → THREE.Group   (procedural; lowest point on y = 0)
src/shaders/<snake>.js export function make<Name>Material(THREE, opts = {}) → ShaderMaterial | patched material
src/lib/*.js        HARNESS-OWNED effect library: import and call, NEVER read — the project's creation (`validate-plan`'s first call or `init`) printed every export with its parameters and references/effects-catalog.md says what each is for; edits are reverted
public/assets/<snake>.glb   optional Blender-built heroes; scene.js preloads each into ctx.assets['<snake>']

The build serves the workspace over http (public/assets/ at /assets/), imports src/scene.js in headless Chrome with the real THREE, a configured WebGLRenderer and loaders = { gltf, texture, cube, manager }, awaits createScene, validates the return value, renders every camera at t = 0 and t = 1.5 s (calling update) and probes (tris, draw calls, console/shader errors, camera checks, exposure, content, the frame difference). The library's surface is the index printed when the project was created plus the catalog: open a src/lib file only for ONE signature the index lacks, and read only that function's lines — never a lib file whole. The plan's bounds are what the census and placement gate measure against; the world a camera sees extends past them as far as the brief needs. references/interface.md has the wiring of scene.js and the env module's shape.

createScene

  • scene: a THREE.Scene; scene.fog and scene.background set (unset = no_fog / no_background, ERROR); scene.environment an environment texture (metals and glass render near black without one). Whatever a camera sees ends in something the brief justifies.
  • Every zone root carries group.userData.c3d_zone = group.name before scene.add — the placement gate and the judge find zones by it.
  • cameras: every camera the plan lists (its list decides how many), as PLAIN objects { name, position: [x, y, z], lookAt: [x, y, z], fov } (the build makes the PerspectiveCameras: aspect 16/9, near 0.1, far from the bounds). PascalCase names from the plan; cameras[0] is the establishing view (≥ 20 % content; others ≥ 10 %, content_small) and need not contain the whole bounds. The overview rig (scene-views without authored cameras) is a fallback, not your picture: a scene judged only on the rig is a scene you did not frame. Eye ≥ 0.3 m above the ground under it (camera_low WARN; camera_high above 80 m), ≥ 0.5 m from every surface and not inside geometry (camera_in_geometry, ERROR, cap 0.50), at most 5 of its 9 sight rays ending within 1.5 m (camera_blocked, cap 0.50), the line of sight to lookAt not cut in its first half; below the terrain is camera_underground (cap 0.50) — compute y from heightAt(x, z), never guess.
  • update(t, dt): cheap (no allocations, traversals or material creation — cache lists at build time and hoist scratch objects such as new Vector3 / getSize to module scope) and deterministic (same t → same frame). It fans out to env.update and every zone's group.userData.update; tickEnv, userData.tick and build<Zone>(ctx) are never called — a hook nobody calls stands still, and calling a missing hook throws.
  • src/env.js: heightAt(x, z) is the surface every zone seats on — deterministic, cheap, 0 for a flat floor; every walkable surface (a path, a deck) is part of it, and it must agree with the ground mesh. SUN_AZIMUTH_DEG is a plain numeric export const (read by regex to put the overview rig on the sun side; omitted, the rig guesses 45°). Anything else it exports is a convention between it and the zones.

Imports and sandbox

Only three, three/addons/*, relative files and src/lib/*.js resolve; no CDN, no other package, no three/webgpu / three/tsl. Shader text: .vert / .frag / .glsl files under src/shaders/, loaded in async createScene with new THREE.FileLoader(loaders.manager).loadAsync(new URL('./shaders/x.frag', import.meta.url).href) — no bundler ?raw, no #include of your own files (Three's #include <chunk> is its built-ins only); never load or compile during update. Forbidden: document.* / window.* except window.innerWidth and document.createElement('canvas') for a procedural texture; network, arbitrary fetch / XHR; Math.random() (mulberry32(seed) from lib/noise.js); Date.now() / performance.now() (use t); requestAnimationFrame; creating a renderer or changing its settings; environment sniffing; EffectComposer (nothing reads one). Textures: procedural (incl. DataTextures) or loaders.texture for files present in the workspace.

What is measured

  • Placement (3dcode check-placement; runs on every build): each direct child of a zone group is ONE placed object; from its lowest vertices the probe looks down for the nearest surface and up for one passing through it. Gap under the foot > 0.05 m outdoors / 0.02 m indoors = floating (ERROR at 0.08 m, or more than two floaters); buried > 0.10 m = sunken (ERROR at 0.20 m and > 20 % of the height; buried, slope-following and water-level feet are exempt); a bbox touching nothing = unsupported; two boxes sharing > 10 % of the smaller = interpenetration (ERROR at 35 %). A Group of several props is ONE box, their union, and every prop inside reads as interpenetrating it: one placed thing = one direct child; many of one thing = one InstancedMesh (a scattered instance inside a placed thing is that thing's interpenetration). obj.userData.placement = 'free' for things meant to hang (WARN when

    25 % are tagged, ERROR past 50 %). Four or more foot columns with at most one touching and a gap > 0.05 m is cantilevered (WARN). A placed asset is measured against the plan's approx_size_m: WARN beyond 2.5 × (or under 1 / 2.5), ERROR beyond 4 × — never re-scale to fit or stretch a clone; a chimney or cable that must reach further is a separate object. The judge's wrong_scale (cap 0.75) is perceptual, on top of that gate.

  • Bounds and contents: a planned content entirely outside the bounds + max(5 m, 10 % of the span) is out_of_bounds (WARN; scenery past them is never reported); a zone group missing or empty zone_empty; a planned asset not placed missing_content.
  • The world's extent (exteriors): standing geometry ≥ 2 m tall reaches ≥ 1.25 × the bounds half-extent (world_edge, WARN); fog far ≥ 2 × the plan span, or for FogExp2 1 / density ≥ span / 1.5 (fog_short); ≥ 8 same-size copies evenly on a ring is stamped_ring.
  • Frames (3dcode scene-views, per authored camera): mean luminance < 0.12 or > 35 % near-black pixels = dark_frame (unless luminance std ≥ 0.12 with ≤ 35 % near-black: low-key but lit); > 20 % blown = blown_frame; > 85 % of the pixels in one band = flat_frame (ERROR above 92 %); plus the camera checks and content_small above. Exposure is gated before anything is judged: a frame that fails scores nothing for what is in it. Non-solid cards near a camera read as geometry to the raycast — mesh.raycast = () => {};.
  • Motion: the t = 0 and t = 1.5 s frames differenced per camera; a camera MOVES when ≥ 0.4 % of its pixels change by more than 8/255 (or ≥ 0.08 % by more than 60/255). No authored camera moving is no_motion (ERROR) and the judge's nothing_moves. Sub-centimetre sway is invisible at 1024 × 576: foliage ±0.10–0.20 rad, particles ≥ 0.6 m per 1.5 s, water a bob ≥ 0.04 m with a scrolling uv/normal have passed.
  • Hero (hero_unseen): a public/assets/*.glb covering < 0.5 % of the frame in EVERY camera is an ERROR; < 2 % in the camera the plan names for it a WARN. A hero is visible only if a zone clones ctx.assets['<snake>'] (its pivot is at its base; clips play by themselves; clone.userData.clipOffset = <s> de-phases a copy).
  • Budget (3dcode scene-probe): WARN above 5 000 draw calls, ERROR above 15 000; 3 000 000 unique triangles. InstancedMesh and merged static geometry are the cheap repeats; practicals are allowed, but a shadow-casting light per practical is the usual blow-out.
  • Shaders: a console or shader error in any module is a build finding; 3dcode shader-probe compiles a material before it renders black.
  • Assets: a procedural asset module is built in node when written, so it is synchronous and loads nothing (no FileLoader / loaders.* / await: shader text is loaded in createScene and passed in through opts); one instance ≤ 15 000 triangles, lowest point y = 0, footprint centred, size the plan's (ERROR beyond 2.5 × or under 0.4 × on any axis, and on a single-box blockout); every sub-shape overlaps a neighbour by ≥ 2 mm. Zones place the Group by its ORIGIN, so an off-origin footprint misplaces every copy. Set group.userData.size = [w, h, d]; optional group.userData.update = (t, dt) => {} which the placing zone caches and calls. opts.seed / opts.variant vary details deterministically; variant changes the SILHOUETTE, and opts.hue / opts.seed vary the colour so many copies are not one colour.

Naming

Zones are Groups named PascalCase (plan names); assets PascalCase; every animated object has a stable .name; mat.name = 'Water' on ShaderMaterials; the ground mesh Ground; backdrop geometry beyond the content Sky… (classified as sky, so it does not inflate the content box); an interior's lid meshes Ceiling… / RoomShell… (the overview rig lifts them).

Requirements that hold for every brief

  • The brief's time of day and weather are hard constraints the judge compares every frame against; a night brief under a noon sky is the wrong scene whatever stands in it. Flat fill (AmbientLight, a hemisphere with no key) turns a lit night into a grey wash: add light where the brief's sources are, give dark materials a low but non-zero albedo (albedos in 0.02–0.8 linear; ACES at exposure 1.0). Shade may stay dark but must carry colour.
  • The environment is judged as heavily as the props (brief_fidelity, lighting_atmosphere, flat_ground, diorama_look): a default sky over default green ground is unfinished. Distant forms pre-tinted toward the fog render BRIGHTER than the terrain and read as cardboard (placeholder_material); natural colour, darkened, left to the fog, reads as haze. Fog gives the aerial perspective thin_atmosphere looks for — kept subtle, or the frame reads milky (blown_frac).
  • An interior (interior: true) must read enclosed from every camera — walls and a ceiling exist in every frame, lit from the sources the brief names (a closed room with no openings and no practicals renders black). roomShell in lib/environment.js is one option. Env cuts windows and doors as openings; zones put glazing and door leaves IN the opening and wall fixtures flush against the inner face, and never build walls or a roof.
  • Shadows: castShadow on the light AND the meshes, receiveShadow on what they fall on; a shadow texel larger than ~0.05 m over the content reads as jagged (judged) — sunRig({ bounds }) with the CONTENT radius fits frustum, map size and bias; a hand-set sun.shadow.* must meet the same texel size.
  • Emissives bloom through the post chain (GTAO + selective bloom + an identity grade unless scene.userData.grade is set): author practicals at peak 1.5–4, not 20; material.userData.bloom = false | true | <colour> opts a material in or out.
  • A sky-dome material needs fog: false, side: THREE.BackSide, depthWrite: false (and the tonemap / colorspace chunks makeShaderMaterial adds) or it renders black or fogged. mergeGeometries returns null on mismatched attributes. Inside a shoreline the terrain lies below the water level or the shore z-fights.
  • Soft particles: a bounded density volume or a radial-alpha sprite; bare PointsMaterial squares, spheres or polygon sparks are hard_edged_particles.
  • A blender_glb hero is built in its own workspace (track static_object, language blender) and its artifacts/object.glb copied to public/assets/<snake>.glb.

The loop

write every module → 3dcode check (build, shader preflight, placement rows with the metres to move each floater / sunken / overlapping thing, asset modules, census) → fix each ERROR → 3dcode check again until no ERROR → 3dcode judge. Exposure, camera and motion are measured at the judge (scene_frames) and come back in score's list with the numbers; 3dcode scene-views is the refine round's one look. A module that throws takes the whole frame black; a zone that throws is dropped and scores nothing — never wrap it in try/catch to hide it. A simple scene that is seated, lit and legible beats an elaborate one that floats in the dark. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

three.js — static objects

build(THREE) returns a THREE.Group with at least one mesh; the build owns the renderer, the export and the cameras (a renderer or render loop in object code is a lint ERROR, a light or camera a WARN the export ignores).

Files (ES modules, three r182)

src/object.js            export function build(THREE) → THREE.Group   (the whole object)
src/parts/<snake>.js     export function build<Pascal>(THREE) → THREE.Group  (one per plan part)

build() imports the part builders with relative paths, adds each Group to a root Group named after the object, returns the root. The build loads src/object.js in node, calls build(THREE), validates the Group (no meshes, a NaN / Infinity vertex or an empty bounding box fails the build naming the part), runs the optional selfcheck, exports artifacts/object.glb AS AUTHORED. The lint derives the export name from the file stem (seat_cushion.js → buildSeatCushion): misspelt WARN, no build* export ERROR, a part file nothing imports WARN (its geometry is absent). Other relative helper files under src/ are fine. references/interface.md is the interface, executable.

Frame, units, placement

  • Y up, +Z front, +X right, metres. BoxGeometry(w, h, d) is x-width, y-height, z-depth; CylinderGeometry / ConeGeometry / LatheGeometry axis is Y (a lathe profile is Vector2(radius, y), normals outward when the radius runs 0 → R → 0 bottom-up); TorusGeometry, PlaneGeometry, ShapeGeometry, ExtrudeGeometry lie in XY (extrusion along +Z); every primitive is centred on its origin, so a part's position is its CENTRE, not its base — the one term behind most floating and sunken parts here.
  • Each part Group is returned at its world pose, geometry in metres, root scale (1, 1, 1) (root.scale.set(...) makes the bounds and the contract gate disagree). The build warns when the object needs > 10 mm of translation to stand on y = 0 centred on the Y axis.

Naming

  • g.name = "<PartName>" — the plan's PascalCase; the GLB's top-level node name is how every gate finds the part, new THREE.Box3().setFromObject(root) is the box the contract gate measures. Unique names (a reused name makes the loader re-parent a node); instances get their own (Leg_0…Leg_3). A mesh with no .name is a build warning.
  • root.userData.tick is never called on this track; the judged pose is what build returns.

Imports and sandbox (the lint)

  • Resolve: three, three/addons/... (e.g. three/addons/utils/BufferGeometryUtils.js for mergeGeometries, three/addons/geometries/RoundedBoxGeometry.js), relative ./ files under src/. A URL, another package, three/webgpu, three/tsl, a path escaping src/, a missing file or a name the module does not export is a lint ERROR (bad_import); never copy three's sources into src/ (two copies of the library, instanceof failures). Undefined before r182: mergeBufferGeometries (now mergeGeometries), three/examples/js/*, Geometry, Face3, sRGBEncoding, outputEncoding. mergeGeometries returns null when one input is indexed or lacks an attribute another has (uv, color).
  • Lint ERRORs: document, window, navigator, localStorage, fetch, XMLHttpRequest, WebSocket, require(), process., eval, TextureLoader / ImageLoader / FileLoader, WebGLRenderer, requestAnimationFrame. WARN: a camera, a light, a Scene as root.
  • Math.random is replaced by a seeded generator at build; the clock (Date.now(), performance.now()) is not — geometry depending on it differs between the measured and the rendered build.

Materials

  • MeshStandardMaterial / MeshPhysicalMaterial colour, roughness, metalness, emissive and vertex colours (setAttribute('color', …) + vertexColors: true, exported as COLOR_0) survive the export. ShaderMaterial, MeshToonMaterial and every texture do not (textures stripped with a build warning; a shader material exports plain). A hex colour is sRGB; material.color.r is linear.
  • An InstancedMesh named Posts exports as sibling meshes Posts_0 … Posts_{n-1} with the matrices baked, so the gates see every copy as an instance of Posts — and a copy that touches nothing is a floating island.

What is measured

  • the contract gate of 3dcode check (the GLB vs the plan): each part's bbox centre and extents within max(10 mm, 10 % of the plan extent) per axis — WARN beyond, ERROR beyond 3 ×; lowest point within 10 mm of y = 0 (WARN; ERROR past 30 mm); footprint centre within max(10 mm, 10 % of the footprint) of the Y axis (WARN); height along the wrong axis is "lying on its side"; a top-level node the plan does not name is "not in the plan" — no helper meshes, bounding boxes or axes in the GLB.
  • the connectivity gate of 3dcode check (per top-level part): contact when the surface gap ≤ 2 mm; a part with no contact path to the supported assembly is a floating ERROR (cap 0.60) with the translation that closes the gap (parts under 10 mm are INFO); penetration > 2 mm WARN,

    10 mm ERROR (cap 0.70); islands under 5 % of the part are stray_islands WARN — what a merge leaves: a degenerate triangle, a duplicated ring at a lathe seam, a vertex at the origin.

  • Triangle budget (sized from parts × instances): WARN below 350 per built object (floor clamped to 1 500–40 000), ERROR above 20 000 per built object (ceiling 60 000–600 000); target about 2 000 per built object; a build over 3 s per built object (≥ 20 s) WARN; killed at 300 s; the build also has a memory limit, but the triangle ceiling is the only count enforced. Detail inside a part is invisible to the part-level gates; a new top-level node is a part.
  • Build: a zero extent or radius, or scale.set(0, 0, 0) to hide, produces NaN and fails the export (visible = false, or do not add it).

Self-check (optional)

export function selfcheck(THREE, root) is called on the built group before export; a throw fails the build as SelfCheckError with your message — assert only what you are sure of.

The loop

write every part file → 3dcode check (build, connectivity, contract) → fix each ERROR → 3dcode check again until no ERROR → 3dcode judge. isolate --part X settles "where did that fragment come from". Every WARN left at the end goes to the judge with the renders; a WARN never caps. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

URDF + bpy — articulated objects

You model a MECHANISM, judged while it moves. Links are bpy objects named exactly as the URDF links; joints are native URDF: the origin in the PARENT link frame, the axis in the joint frame that origin sets up. The build owns the export and the pose sweep.

Files

src/model.py    pure bpy (3d-lang-blender's sandbox and lint apply): per link, the object named exactly as the
                link plus anything parented under it, built in WORLD coordinates at the REST pose (= q = 0).
src/robot.urdf  links + joints; every link has ONE <visual> and ONE identical <collision>,
                geometry <mesh filename="meshes/<link>.glb"/>, origin = −(link frame).

The build runs model.py headless; takes the object named <link> plus everything parented under it as that link's mesh (the wrapper joins them); exports artifacts/meshes/<link>.glb with WORLD coordinates baked in; lints the URDF; checks that FK at q = 0 puts every mesh back where you authored it within 1 mm (else the build FAILS as FkInconsistent and prints the corrected <origin>); fails on a rest-pose penetration deeper than 5 mm (RestPenetration); sweeps every joint (3dcode joint-sweep); renders q = 0 plus every joint at both limits for the judge; builds object.glb with one node per link. A link no object matches fails the build (with a did-you-mean for a case / snake_case mismatch); a visible mesh no link claims fails it too (parent it under a link's object or add a <link>). <collision> missing or different from <visual> is a WARN: the VISUAL mesh is collided. references/interface.md is one hinge, end to end.

Frame rule (measured by the FK check)

  • Z up, −Y front, +X right, metres, radians. Object on z = 0 at q = 0 (the contract gate of 3dcode check compares every link's bbox with the plan's: max(10 mm, 10 % of the planned extent) per axis).
  • q = 0 = what you build = the plan's rest pose (doors closed, drawers in, lids down unless the plan's rest says otherwise). The judge sees q = 0 and both limits of every joint.
  • Write every joint with rpy="0 0 0": link frames are then world-aligned and the arithmetic below is subtraction. A rotated origin is accepted (lint INFO) but the visual/collision origin must then be the full inverse of the link's FK transform — the FK check prints it.
  • Root link frame = world origin. Every other link frame = its joint's PIVOT: a world point ON the joint axis (hinge line, slide axis, axle); fixed joints: the attachment point.
  • <joint><origin xyz> = pivot_child − frame_parent (a child of the root: just its pivot; a handle on a door: pivot_handle − pivot_door).
  • <visual> AND <collision> <origin xyz> = −pivot_link (root: 0 0 0), because the mesh holds world coordinates and the link frame sits at the pivot. The build verifies this numerically and prints the numbers when it is wrong.
  • <axis xyz> is a unit vector in the JOINT frame (world-aligned with rpy="0 0 0"): the world direction of the hinge line or slide (non-unit: normalised, WARN; missing: 1 0 0, WARN). Sign: positive q must move the child the way the plan's motion word says — the motion_direction gate moves the joint positively and checks the child's centroid displacement within 60° of that word. Wrong way: negate the axis; never swap lower/upper (q = 0 must stay the authored rest pose).
  • Limits describe the mechanism's real travel (a lid 0…1.5 rad, a drawer 0…0.4 m), never -3.14 / 3.14 placeholders: the sweep poses both ends, and a hinge that can swing through its own housing is a modelling error it will find. revolute / prismatic need <limit lower upper effort velocity/> with lower ≤ 0 ≤ upper (lower = plan.lower − rest, upper = plan.upper − rest); a missing <limit> is a load ERROR. continuous: <limit effort velocity/> only. fixed: no <limit>, no <axis>. Lint WARNs: lower == upper, a revolute range > 2π (use continuous), a <limit> without effort/velocity.
  • Single-root tree: exactly one link that is no joint's child (the base); every other link the child of exactly one joint (ERROR otherwise); no cycles. Anything riding on a moving link is part of that link's mesh or a fixed child of it — attached to the base it stays behind and the sweep reports the overlap.
  • Names: link name == Blender object name == meshes/<link>.glb stem, case-sensitive, a plain identifier (Door.001 means two objects shared a name); world is reserved (ERROR); name the part, not its state (door, not door_open: WARN). snake_case of the plan parts (PascalCase accepted). Copies of a plan part are separate links <part>_1..n with their own joints <joint>_1..n. Joint names: the plan's, unique.

Clearance and attachment (3dcode joint-sweep)

  • Pose set: rest; every movable joint alone at lower, mid and upper (the others at 0; continuous: 0, ±π/2, π); 8 seeded random full-body combinations when more than one joint moves. <mimic> followers follow their driver.
  • In every sampled pose no two links overlap by more than 2 mm. In a moved pose that is an ERROR at any depth — the normal failure of this track is an assembly clean at rest that jams at 40° of travel: give each moving link the clearance its WHOLE range needs, and make travel limits honest rather than letting links intersect. At rest 2–5 mm is a WARN, > 5 mm fails the build. Links joined only by fixed joints are one rigid group. A non-watertight link gets an estimated depth ([approx: non-watertight mesh]).
  • Attachment at rest: a fixed child within 2 mm of its parent (ERROR beyond); a hinged / sliding child's mesh within 10 mm (WARN beyond, ERROR beyond 30 mm; a prismatic child already inside its parent's bbox is exempt).
  • the connectivity gate of 3dcode check reports a fragment inside a link smaller than 5 % of its largest extent as a stray island.

Allowed / forbidden

model.py: the blender skill's lint, plus exit() / quit() ERROR, input() ERROR, time.sleep / while True WARN; every link name must appear as a string literal in model.py (WARN otherwise). URDF: no <gazebo>, <transmission>, <sensor>, xacro, package://, mesh scale (WARN), inline primitives (ERROR: visual geometry must be a <mesh>). Inertials optional. <mimic joint="..." multiplier="..." offset="..."/> IS honoured — one per follower of a one-input mechanism (a coupling naming no joint, itself, a fixed joint, or closing a loop is a lint ERROR). No triangle-budget gate; the build is killed at 300 s.

The loop

write → 3dcode check (lint, FK at q = 0, rest penetration, the joint sweep, connectivity, contract) → fix each ERROR → 3dcode check again until no ERROR → 3dcode judge. A sweep ERROR blocks the round whatever the geometry looks like; 3dcode joint-sweep --joints J alone re-tests one joint after its fix. The round's hand-over, the one look at renders per refine round and the stop rules are the 3dcodeverse skill's ## The loop.

3D coding with 3dcodeverse

This is 3D CODING. You write raw, executable 3D code — bpy / CadQuery / three.js / URDF / GLSL / moderngl — in a workspace; the 3dcode instruments build, export, measure, render and gate it; a judge who never sees your code scores the renders; 3dcode score turns the verdict into a number and an improvement list. Nothing is drawn by hand and nothing comes from an asset store: the object, mechanism, place or effect has to come out of the code at real scale, and it is measured. Your job is the loop below, honestly.

Already in context? A 3DCODEVERSE PRELOADED block at the start of the session (the plugin's session hook) holds this file, every plan reference and every language skill: then nothing is left to read — write the plan. Otherwise read three files together, in ONE step, before anything else — all under the plugin root, beside this file: this skill's ## The loop (the rest of this file is reference), the language skill skills/3d-lang-<language>/SKILL.md (hyphens: scene_threejs → 3d-lang-scene-threejs; the table below names each) and skills/3dcodeverse/references/plan-<track>.md. Open no other reference (c3d-* skills, a language skill's references/) unless a finding needs it.

Tracks and languages

trackwhat it islanguages (default first)read before writing codeplan reference
static_objectone thing that does not move — furniture, tools, props, a vehicle at restblender, cadquery, threejs3d-lang-blender / 3d-lang-cadquery / 3d-lang-threejsreferences/plan-static.md
articulated_objecta mechanism judged while it moves — doors, drawers, lids, wheels, linkages, robotsurdf_blender3d-lang-urdf-blenderreferences/plan-articulated.md
scenea place — terrain or room, sky and light, many placed things, authored cameras, something movingscene_threejs, scene_blender3d-lang-scene-threejs / 3d-lang-scene-blenderreferences/plan-scene.md
graphicsan animated image — a fragment shader or a moderngl program, judged on framesglsl_shader, opengl_python3d-lang-glsl-shader / 3d-lang-opengl-pythonreferences/plan-graphics.md

Pick the track from what the user wants and the language from their words, else the row's first. The language skill states the files, the frame, the sandbox and every threshold the gates measure; the c3d-* skills hold optional craft for one defect class each (parts that touch, the bbox contract, repeats, scene lighting / placement / water, shader traps …) — read one when its description matches your plan or a finding.

The instruments

Every call is 3dcode <subcommand> --workspace <abs dir> [--flag value …]. Always pass --workspace (the absolute path). The first line of the output is the verdict — PASS, FAIL or ERROR — then the numbers and fix hints, then the absolute paths of any PNGs it wrote (open one when the loop below says to look). Exit 0 means the tool ran (a FAIL is exit 0); non-zero means it could not run. --json gives the same result as JSON. A list flag is repeated (--views front --views top); 3dcode <subcommand> --help lists a tool's flags. If 3dcode is not on PATH, run <plugin root>/bin/3dcode.

subcommandwhat it answerswhen
initwrites spec.json (track, language, prompt, must-haves, dims, references, style) and the workspace layout; prints the entry filesonly to create a project before its plan exists — the first validate-plan does it otherwise
validate-planis plan.json a valid plan for the track — schema, plan checks, the acceptance items derived from spec.json; writes the normalised plan back (scene_blender: also src/scene.py)after every plan edit, until PASS
builddoes src/ lint, build and export, without the gatesscene / graphics quick iterations; object tracks run check
checkbuild + EVERY gate of the track → artifacts/gates.json; PASS/FAIL with each ERROR and its fix — the round's verdict (it subsumes build and prints the measurement table)before judging; every ERROR caps the score
judge --round Nthe round's hand-over in one call: commits src/ + plan.json tagged rNN (re-running check when the gates are stale), runs judge-pack, prints the folder and the JUDGE INSTRUCTION: line for the judge subagentafter a clean check, once per round
judge-pack --round Nrenders the judged views, composes the montages and crops, writes judge/rNN/brief.md + images for a fresh-context judgeinside judge; alone only to re-pack
score --round Nthe rubric arithmetic on judgment.json: overall, passed, caps, the improvement list → score.json; repairs a trivial deviation in the judgment and says what it repairedafter the judge replied
cross-sectiona labelled slice (`--axis xy
render-viewsnamed views (--views, `--mode shadedwire
render-sheetthe labelled 14-view contact sheet (--mode)the refine round's one look, to confirm a listed item
isolate --part Xone part alone + its measurement rowwhere did that fragment come from; where is this part
compare-referencea reference image beside a render with the outline diff and IoU (--reference-index, --view)after the first clean build and after every shape change when spec.json has references
joint-sweepthe joint_sweep gate plus pose renders (--joints renders fewer)articulated, when a sweep finding needs the poses seen — check already runs the gate
scene-probethe scene census: objects, materials, lights, draw calls, triangles, console errors, world and atmospherescene, for the budget and the world
check-placementper placed thing: gap under its feet, burial, support, interpenetration with the metres to move it; bounds, scale, zone contents (--rebuild probes again)scene, after every build — read its rows (gap + tolerance), never artifacts/scene_probe.json (the raw dump)
scene-viewsthe authored cameras and/or the orbit rig (`--cameras authoredorbit
shader-probecompiles every ShaderMaterial headlessly; errors with line numbersscene_threejs, before a material renders black
gl-probecompile / import and ONE frame (--t, default 1 s): errors with source lines, or the frame + its statsgraphics, after every edit
gl-framesthe judged frames (--times, --width, --height) as a sheet + per-frame metrics + the gl_frames gategraphics; check runs it — alone only as the refine round's one look
list · doctorevery tool with its arguments · the machine's deps (Blender, node, GPU)when a tool or a build is missing

spec.json is re-read on every call; plan.json is what the gates measure against.

The workspace

spec.json     the request (track, language, prompt, must_have, must_not, dims, references)
plan.json     your plan — exact numbers; validated before any code
src/          your raw code (scene track: also public/ for compiled assets)
artifacts/    instrument output: object.glb, renders/, gates.json, measurement.json — READ-ONLY
judge/rNN/    brief.md + montages (judge-pack), judgment.json (the judge), score.json (score)
  • Only code goes in src/ — no notes, READMEs or reports; install nothing, fetch nothing.
  • Never write under artifacts/ or judge/ except the judge's judgment.json; never edit spec.json after init; never edit plan.json after it validated (a re-plan starts the rounds over). The one exception is a camera finding: prefer moving the subject (a zone's placement, the ground under the eye); when the camera itself must move, edit cameras[] only and re-run 3dcode validate-plan — that is not a re-plan.

The loop

Editing rule. After a file's first write, change it only with the host's edit tool, scoped to the lines the change needs; a large change is several edits, never a whole-file rewrite. Keep files small and modular so edits stay local — one part / zone / asset / layer per file, as the language skill's ## Files allows. Do not re-read a file you just wrote or edited.

Commands run in the foreground; wait for them. Every 3dcode call finishes on its own (a scene check or judge can take a minute or two): give each 3dcode command a wait of up to five minutes (300 000 ms) so it finishes in the same step instead of moving to the background. Never poll a running command or subagent; its result comes back to you.

How many rounds is the user's call. By default there is ONE round: plan, write the code, 3dcode check until it lists no ERROR, report — no judge, no render-look-edit cycles. Judge (steps 4–5) only when the user asks for a score or for refine rounds, and run exactly the number of refine rounds the user asked for. No self-polishing: the judge decides what to polish and score lists it; you do not iterate on looks between judges. A refine round fixes exactly what the last score listed (gate ERRORs first, then the judge's items), runs 3dcode check until no ERROR, then 3dcode judge — at most ONE look at renders (render-sheet / scene-views / gl-frames) per refine round, to confirm the listed items. A WARN never caps the score: fix it once if cheap, otherwise leave it.

  1. Plan. The workspace is empty until step 2 creates it — nothing to read or list: write W/plan.json by references/plan-<track>.md — exact numbers, an acceptance checklist, and SHORT: one sentence per part, one line of summary, the reference's example is the length (an object plan under 5 KB).
  2. Validate (and create the project). 3dcode validate-plan --workspace W --track T --language L --prompt "..." with --must-have "..." / --must-not "..." per hard requirement, --dims height=0.45 per stated dimension, --references img.png per reference image: the first call also creates the project (spec.json, layout, the language's own files) and prints its entry files. Then 3dcode validate-plan --workspace W until PASS; FAIL lists each error with its JSON path — fix the plan, never argue with the validator. It says what it normalised; there is nothing to re-read.
  3. Baseline round (r00). Write every file the language skill describes from the plan in at most THREE write steps — several files per step (all the part / zone / layer files together), the entry file last — then 3dcode check --workspace W and fix each ERROR it lists (a compile or runtime error at the file:line it names, see Repairs; a gate ERROR by its fix hint) until none is left — every ERROR caps the score. When the user asked for a score, run 3dcode judge --workspace W --round 0 instead of each check after the code is written: it runs the check first and stops on any ERROR with the same output, so a clean round goes straight to step 4 without a separate check. Object tracks: the whole object first — every plan part at its box and attached to its parent before any part gets detail (a part still a ≤ 12-triangle box within 1 mm of its plan box is a placeholder_part ERROR); then detail. Model each part AT its planned size from the plan's numbers; never scale finished geometry to fit the plan box (a non-uniform scale bends bevels, radii and tube walls: sessions that did scored 0.06 lower on craftsmanship and no better on proportions). Keep comments sparse: a short note only where the code alone does not say why — no step-by-step narration, no restating the plan's numbers or part list. No ERROR → the round is done: without a judge request, go to step 6.
  4. Judge (only when the user asked for a score or for refine rounds). 3dcode judge --workspace W --round 0: it commits and tags r00, writes judge/r00/ and prints a line starting JUDGE INSTRUCTION:. The judge is a context that has not seen your work: start a FRESH subagent with the 3d-judge agent definition and hand it that instruction VERBATIM — nothing else: not what you built, not what you think of it. It reads brief.md and the images, writes judgment.json and replies wrote <path>; wait for that reply. Only when the host cannot start any fresh context, judge it yourself as a DEGRADED verdict — a clearly separated step after writing nothing else into context: open brief.md, look at every image, answer exactly its JSON — and mark the round "self-judged" in your report. Then 3dcode score --workspace W --round 0: it prints overall, passed, the caps applied, what it repaired in the judgment and the improvement list — each item names its target, its tile and the evidence, which is all a fix needs. Do NOT open the judge's montages after score; the refine round's one look is the render-sheet (or the track's scene-views / gl-frames) after your edits. Never list or guess names in judge/, never re-read brief.md.
  5. Refine rounds (r01, r02 …; exactly as many as the user asked for). Each round makes exactly the score's improvement list, gate ERRORs first ([gate/...] items), as edits under the editing rule, keeping every other part, name and dimension. A placement task changes that part's placement numbers to the plan's centre; a material task changes that part's colour / roughness / metalness only; a shape task rebuilds that part alone; on graphics a colour/light task touches palette, exposure and grade only, a motion task the time terms only — never rewrite unrelated layers or passes. A measured finding that repeats needs a different change of the thing it measures, not the same edit again; a judge note that repeats needs a visible change in the named view. Then judge --round N (it checks first and stops on any ERROR) until it packs, or check first when an item needs the round's one look at the renders → the judge → score --round N.
  6. Stop when the rounds the user asked for are done, when score says passed with an empty improvement list, or when the overall fell two rounds running. Without a judge the deliverable is r00; with one it is the BEST-scoring round: if the last round is not it, git -C W checkout rNN -- src (and public) and run 3dcode check once more so artifacts/ matches. Report in AT MOST ten lines: each round's overall and caps (if judged), the entry files, the deliverable round and the paths of its montages — nothing more, no file-by-file list.

Quality rules on every track

  • The plan's numbers are what the gates measure. Build them; if one looks wrong for the object, keep the plan's value in the code and say why in a comment — never drift silently.
  • Parts meet at their surfaces. Where one part goes INTO another (an axle in a hub, a fork in a head tube, a switch in its base, a leg in a seat) end it at the receiving surface or make the receiver hollow: more than 2 mm of overlap is measured, more than 10 mm is an ERROR.
  • Detail goes INSIDE the parts the plan names — edges, profiles, seams, counted repeats — never into new parts: detail inside a part is neutral-to-positive for the score, an unplanned part is strongly negative (the contract gate reports it, the judge counts it as clutter).
  • Model only what a viewer sees from outside. Internals — springs in a housing, wiring, the underside of a lid that never opens — are never parts.
  • A material per part with the plan's colour; a grey default anywhere is a judged defect.
  • Hollow things are hollow when the real object is (a mug, bowl, box, drawer): cut the cavity in the code; open 3dcode cross-section only when check or a score item says it is missing.
  • Never trim part names, counts, the overall size or the planned motion to "simplify"; no placeholders, no unit-cube stand-ins, no static image where the plan says motion.
  • A render is evidence; "it should be fine" is not. The judge's montages are that evidence; on your one look per refine round check only the listed items — and that the silhouette still reads as the requested thing, nothing missing, exploded, lying on its side or left over from a primitive (a stray Cube), the materials the plan's.

References

When the user gives reference images, open them before planning. On the object tracks the plan's proportions, part set and visible details match the FIRST image, with dimensions in metres consistent with what it shows; the pictures outrank the text where they disagree; that first reference is the silhouette target — its outline IoU against the best-matching render is measured (check WARNs below 0.6) and the judge scores silhouette_match from it (rubric reference). Run 3dcode compare-reference after the first clean build and after every shape change. On the scene and graphics tracks the photos are not a composition to copy: they show what the real thing looks like — its dominant and secondary colours, how its structure folds, layers and thins, where brightness concentrates and how much stays dark, its texture at fine scale — and they outrank the brief's adjectives; the judge sees your frames beside the same photos. Keep the brief's foreground, framing and landscape, and open the photos again on the refine round's one look.

Repairs

A build failure is fixed with the smallest correct change at the file:line the output names: a runtime error → the call or import (the language skill's allow-list is the only set of modules); a lint error → the construct the fix hint names; a syntax error → that line; a timeout or memory blow-up → fewer segments or loop counts. Keep every part, name and dimension. The same error twice means the edit missed the cause: change a different call, not different arguments — check the name and signature against the language skill's API facts first. Never finish a round on a broken build. A gate ERROR (the build is fine) still listed after THREE fixes: take its fix hint literally once more (a joint_sweep hint may name the exact limit that clears), and if it is still there, judge anyway — run 3dcode judge again with src/ unchanged; the ERROR caps the score and the judge's list carries it into the next round.

Honesty

  • One code path: no detection of headless mode, user agent or the instruments.
  • Never special-case a check to make it pass — no hidden parts, zero-scaled parts, invisible filler geometry, connector sticks bridging a gap; fix the geometry the finding names.
  • No fake success, no swallowed exceptions around geometry (the one exception is a cosmetic fillet/chamfer falling back to the unrounded solid when the kernel refuses it).
  • Never import a helper SDK, the plugin's own package or runtime_js/; harness-owned modules a language skill names inside src/ (scene_threejs src/lib/*.js) are the one exception.
  • judgment.json is the judge's: never edit it, never give the judge anything but the printed JUDGE INSTRUCTION, and report a self-judged round as such.

The plan's numbers are the contract

Read this before you type a dimension. Every number in plan.json is a promise the contract gate measures against the exported GLB, in the plan's own authoring frame — which is why every fix hint it writes is already labelled with that frame and is safe to paste straight into your code.

What the gate actually allows

Per axis, tol = max(1 cm, 0.10 x the planned extent on that axis) (codeverse3d/spatial/contract.py, codeverse3d/conventions.py). A deviation past tol is a WARN; past 3x tol it is an ERROR.

planned extenttolerance on that axisin relative terms
3 cm1 cm33 %
10 cm1 cm10 %
50 cm5 cm10 %
2 m20 cm10 %

The absolute floor rules small parts and the relative term rules large ones. So a 4 cm bracket may wander a full centimetre, and a 2 m beam that comes out 25 cm short is an ERROR, not a rounding difference.

What actually goes wrong (recomputed from bench/out 2026-08-25, 142 graded records with gate artefacts)

  • part bbox deviates — 75 runs (52.8 %); overall bbox — 44 (31.0 %); per-instance — 29 (20.4 %); footprint off the up axis — 21 (14.8 %).
  • Of 978 bbox findings, 673 name only the size, 133 only the centre, 172 both. This is overwhelmingly a size defect, not a placement defect.
  • Out-of-tolerance axes run 713 undersized to 394 oversized. The usual story is a part built as its core shape while the plan's extent included the trim, flange or overhang.
  • Median worst deviation is 1.47x tolerance, p90 2.86x. Most failures are one axis missing by a hair — arithmetic you could have checked before building, not a redesign.

Rules

  1. Derive, do not retype (a strong option, not a layout rule). A dimension computed from the plan numbers it depends on — a neighbour's bounds included — lives in one place; a number typed twice will disagree with itself, which is how the 1.47x median miss is made.
  2. Budget for what the modifiers do to the bounding box. The gate measures the built AABB, after everything. A bevel, chamfer or fillet shrinks the silhouette; a solidify, skin or subdivision surface pulls a cage inward; an outline offset grows it. If the plan says 88 mm and your bevel eats 9 mm, you shipped 79 mm and the gate says so.
  3. Instanced parts are measured on extents only. For a part with instances > 1 the gate reads the plan box two ways — as the size of ONE copy, and as the union of all copies — and keeps whichever fits better, so building either reading is accepted. It does not check the centre of an instanced part (it cannot know which copy is which). A wrong count is a separate WARN: name the copies Name_0 .. Name_N-1.
  4. Sit on the ground and centre the footprint. Lowest point at zero: a gap beyond 1 cm is a WARN and beyond 3 cm an ERROR, with the exact translation in the hint. The footprint centre must be within max(1 cm, 10 % of the larger horizontal extent) of the up axis — that one is always a WARN and always fixable by one translate.
  5. Names are the join key. Parts match by their snake-cased name; the exact name is claimed first and Name_0..Name_N afterwards. A plan part with no matching node is an ERROR ("missing from the GLB"); an extra node the plan never mentioned is only INFO. So a spare helper node is cheap and a misspelt part name is expensive.

Prove it, do not eyeball it

3dcode check prints both: its measurement table gives per-part size in cm and the ground gap; its contract gate gives, per failing part, the built size against the planned size, the per-axis delta, the planned centre and the frame those numbers are written in. Fix the largest ratio first — the message states it ("worst 3.4x tolerance"), so you always know which finding is the ERROR.

isolate <PartName> renders one part alone with its measurement row when a delta does not make sense.

Measure like the gate when you check a size in your own script (bpy): the gate reads the world-space AABB, so take obj.matrix_world @ Vector(c) over obj.bound_box after bpy.context.view_layer.update(); obj.dimensions ignores rotation and bound_box is object-space, so either one disagrees with the gate on a rotated part.

Worked example of turning a real fix hint into an edit: references/reading-a-fix-hint.md.

Shapes to bpy, and the traps the lint counts

Read this if you are about to write bpy code. It is two things: a form-to-technique table so you do not build everything out of boxes, and the five traps that a static lint already caught in this corpus, with how often. Every row and practice is an option under its real API name — the brief and the plan say what the object is; nothing here says how it must be built.

blender is the biggest language here (102 of 142 graded runs with gate artefacts) and its two weakest judge criteria are assembly_fit (0.60) and geometry_detail (0.67), means over 246 judged rounds, mined 2026-08-25. geometry_detail is what the table below moves; assembly_fit belongs to c3d-part-contact, whose contact and weld numbers this skill defers to rather than restating.

Form to technique

Say the form in words, then pick the technique; the table is a menu, not an order.

formtechniquenotes
revolved profile (bottle, knob, vase, wheel hub)bmesh.ops.spin on a profile, or a SCREW modifierone (radius, z) list is the whole shape; spin needs EDGES in geom, and remove_doubles welds the seam and the axis points
thread, coil, springSCREW modifier with screw_offset and iterationsnot a stack of tori
swept tube (rail, cable, handle, hose)curve with a non-zero bevel_depth; evaluate it to a mesh when a later step needs real geometrybevel_depth = 0 is a path with no surface: it exports no node and the part is reported missing (contract.md)
moulding, rim, handrail, cornicea 2-D profile curve as the bevel_object of a 3-D path curve (bevel_mode = 'OBJECT'), evaluated to a mesha curved path needs sampled points, not four corners
extruded outline with softened edgesbmesh.ops.extrude_face_region then BEVEL modifierwidth must be under half the thinnest wall or the bevel eats the part
shell / sheet metal / panel with wall thicknessbuild the surface, add SOLIDIFY, then any beveloffset=-1 grows inward, so the outer surface stays on the plan bbox; zero-thickness faces have no volume for the gate's inside test and break booleans
cavity, slot, groove, holeBOOLEAN DIFFERENCE, solver EXACT or MANIFOLDcutter must overshoot the pierced face and never be coplanar with it
small detail welded onto a bodyBOOLEAN UNION, or build it into the same bmeshoverlapping is not merging: see c3d-part-contact
N identical features on one partARRAY or MIRROR modifier, or one python loop into one bmesharray/mirror/screw results are ONE object, which is what you want for in-part detail
N identical partsa loop that creates N top-level objects named Name_0 .. Name_N-1never a parent Empty; see c3d-repeats-and-mirrors
taper, bend, twistbmesh vertex maths, or SIMPLE_DEFORMpivots on the object origin; needs rings along the length
smooth organic body with sharp seamsSUBSURF plus edge creases (crease_edge attribute)subsurf shrinks the part: measured on Blender 5.2.2 a level-2 subsurfed cube loses 16% of every extent. The exporter applies it, so the contract gate sees the shrunk size
beam between two pointsbuild along one axis, then place from the endpointsa quaternion from the endpoint direction (Vector.rotation_difference) avoids Euler-order mistakes; see references/form-recipes.md

Short practices for each row are in references/form-recipes.md.

The five traps, with counts

Counted over the 102 graded blender runs (mined 2026-08-25); each is a real lint:blender finding, emitted before the build even runs.

  1. bpy.ops.object.join — 17 runs (17%). The join result inherits the active object's transform, and in background mode the selection is not what you think. Either set bpy.context.view_layer.objects.active to an object with an identity transform first, or do not join at all: build the whole part in one bmesh and skip the operator.
  2. A part file src/model.py never imports — 7 runs (7%). src/parts/backrest.py that nobody imports ships nothing, silently: no build error, just a missing part and a contract/missing_part finding two gates later. model.py must from parts.backrest import build_backrest and call it exactly once. The mirror trap: a part file that calls its own builder at module level builds the part twice and you get Backrest.001.
  3. No PascalCase object names — 14 runs (14%). Every visible mesh takes its plan part's name exactly; instances are Leg_0 .. Leg_3. An auto-suffixed Leg.001 is a different part as far as the contract gate is concerned. (urdf_blender instead names each object after its URDF link, and lint:urdf checks the link name appears verbatim in model.py.)
  4. bpy.ops.object.modifier_apply out of context — 7 runs (7%). It needs the object active and selected in OBJECT mode. Usually you should not apply at all: the exporter runs with export_apply=True, so bevels, solidifies, arrays and mirrors are evaluated for you. Apply only when a later step needs the real mesh — a boolean, a join, a vertex loop — and then wrap it: with bpy.context.temp_override(object=obj, active_object=obj, selected_objects=[obj]):.
  5. primitive_cube_add(scale=...) without size=1 — the extents come out doubled. Re-measured on Blender 5.2.2: primitive_cube_add(scale=(0.3, 0.2, 0.1)) gives dimensions 0.6 x 0.4 x 0.2; adding size=1 gives exactly 0.3 x 0.2 x 0.1. Pass size=1 and the scale vector is the plan's extents, so you can paste the plan numbers in. Then bake it: transform_apply(location=False, rotation=False, scale=True) — all three keywords, always, because the ones you omit default to True and will bake the location too.

Two more from the same lint that cost a whole run when they fire: indexing bm.verts[i] without ensure_lookup_table() is an ERROR (IndexError at build time), and bsdf.inputs["Specular"] is an ERROR (renamed to "Specular IOR Level" in 4.x/5.x).

Strong options (not in the lint)

  • Struts. Build along +Z and place with a quaternion from the two world endpoints (references/form-recipes.md §1); Euler order betrays you on the second axis.
  • Spans computed from the neighbours' plan bboxes follow the neighbours when they move; a typed literal does not.
  • Keep obj.scale at 1 by export time. A scaled object bevels unevenly and exports its scale baked; apply the transform before any bevel or boolean.
  • bpy.context.selected_objects and bpy.context.object are unreliable headless. Keep your own references to everything you create. (1 run lost time to this.)
  • The exporter takes every visible mesh. A leftover cutter, a construction guide or a duplicate ships as a part. Delete it or set hide_render/hide_viewport.
  • Fewer booleans. Cutters of one kind can share one mesh and one cut: every boolean is another evaluation and another chance of a non-manifold sliver, which the island gate reports. A cutter coplanar with the face it cuts, or not closed (cap_ends=True), fails silently.
  • Flipped normals after bmesh.ops.scale with a negative factor or after mirroring read as dark, inside-out faces in every render (no gate measures them): bmesh.ops.recalc_face_normals(bm, faces=bm.faces) before to_mesh.
  • Bend / taper. SIMPLE_DEFORM pivots on the object origin and needs rings along the length (bmesh.ops.subdivide_edges on the side edges): an origin at one end gives an arc, a centred one a C.
  • Two-tone parts. A second colour on one part is a second material slot and face.material_index on the faces you choose; bmesh.ops.create_* return only verts, so diff set(bm.faces) before and after the op to find the new faces, or set polygon.material_index on obj.data.polygons afterwards. The census warns when a slot is never used (contract.md, Materials).
  • Where detail is seen. The judge's montage shows the silhouette and the largest faces from the rig's views; the underside and interiors the camera cannot enter are never rendered. Bevels and chamfers add shading breaks for few triangles; the triangle budget gate states a number only when you exceed it.

Before you finish

3dcode check (its connectivity and contract gates) -> 3dcode render-sheet, and read the lint:blender findings in the build report first: they are free, static, and every one of the five above was reported before the model was wrong.

Short options — the beam, the lathe, the swept tube, the solidify shell, the boolean with its cutter cleaned up, and the multi-file wiring — are in references/form-recipes.md.

Lighting a Cycles scene the frame gate will accept

What is fixed, and what is measured

The harness renders the authored cameras and the first overview rig views with Cycles at 32 samples plus denoising, AgX view transform, look None, exposure 0 — and it owns every one of those settings: an assignment to scene.render, scene.cycles or scene.view_settings is a lint ERROR (harness-owned). There is no exposure knob. Lamp energies, the world strength and the albedos are the whole of your control.

The gate (scene_frames) reads the Blender PNGs with the statistics it reads three.js frames with — per camera mean_lum, lum_std, dark_frac, blown_frac and modal_frac in the camera_checks of metrics.json:

findingfires whenauthored cameraharness rig view
dark_framemean luminance below 0.12, or more than 35 % of the pixels near blackERRORWARN
dark_frame, "dim but lit"dark by the mean, but with contrast (lum_std) of at least 0.12 and not mostly blackWARNWARN
blown_framemore than 20 % of the pixels pure whiteERRORWARN
flat_frameone luminance band holds more than 85 % of the frameWARN; ERROR above 92 %WARN

An ERROR of each kind is a score ceiling in the scene rubric, and every finding's hint carries the scene_blender wording (lamps, world nodes, ctx.height_at), not the three.js one. The rig views (overview_*) are WARN-only; the judge reads those pictures too.

The bands, measured on this renderer

Measured 2026-10-14 on Blender 5.2.2 LTS with the harness's exact render setup, on a synthetic scene (a flat ground plane of linear albedo a and six boxes; an eye-level camera with sky in the top third, and a camera at the overview rig's angle). Numbers are mean_lum; the full tables and the other four statistics are in references/exposure-bands.md.

setupmean_lumwhat it says
the multiple-scattering sky alone, sun disc ON (a hand-built world), strength 0.05 / 0.2 / 1.0 (eye camera)0.63 / 0.82 / 0.96with its disc the physical sky IS daylight at strength 0.05-0.1; at 1.0 the sky starts to clip
sky 0.2 with the disc off + ONE sun lamp at 1 / 3 / 10 W per square metre, a = 0.3 (overview)0.57 / 0.63 / 0.73the lamp is a weak dial under AgX
the same sun at 3, ground albedo 0.03 / 0.15 / 0.6 (overview)0.32 / 0.52 / 0.72albedo is the strong dial
sun lamp 3 with the sky's disc ALSO on (two suns)0.83the doubled sun: washed, shadows fight
dark-blue night world alone / with a moon sun of 0.2 / 0.50.02 / 0.06 / 0.10too dark, and evenly so: no low-key escape, because lum_std stays under 0.05
that night + two practical area lamps 2.5 m up at 45 / 150 / 500 W0.05 / 0.08 / 0.1445 W is a look, not a light; 500 W per lamp passes, with contrast
that night + two fixture-sized emissive spheres at strength 5 / 80 / 320, no lamps0.03 / 0.05 / 0.09emission does not carry a frame; it needs a lamp beside it
a closed 6 m room, one 1 m ceiling area lamp at 50 / 200 / 800 W0.34 / 0.61 / 0.82interiors are easy: tens to hundreds of watts

Two things fall out of the table. Under any daylight world nothing is dark and the risk is the other two kinds: a uniformly coloured ground seen from the overview rig sat in the flat band (modal_frac 0.84-0.95) in every daylight row, so value variance on the ground and shadow-casting content are what break it, not more light. And at night the lamps that make the picture pass are an order of magnitude stronger than the ones that make the fixtures glow.

Interface, requirements, and ways that measured inside the band

  • Interface: the world is build_env's. A world created or assigned anywhere else is a harness-owned lint ERROR. Zones add lamps.
  • Requirement: one consistent sun direction, shadows that do not fight (judged) and every frame in the band (measured). A physical sky with its disc on plus a sun lamp measured 0.83, washed, with doubled shadows; so did a second sun lamp in a zone. A matched pair is a world whose ShaderNodeTexSky (sky_type = 'MULTIPLE_SCATTERING') has its sun disc off and a Sun lamp (bpy.data.lights.new(name, "SUN"), energy in W per square metre, angle for the softness) casting the shadows, both at the same compass angles; a Sun shines down its local -Z, so its rotation is the elevation's complement about X, then the azimuth plus 90 degrees about Z. A dark day moves with the albedos and the sun's energy more than with the world strength (the second and third rows).
  • The brief's hour decides the palette; the band still applies. A world Background fed by a ColorRamp over the view direction's Z (horizon to zenith), or a flat deep night colour at a low strength, with a low or cool Sun lamp, are measured ways to sit in it for dusk, overcast and night; a warm key under a cool sky (a sky texture gives that for free) is what keeps shade from reading black or the frame from reading one orange tone (judged). Soft shadows come from a light's size (angle on a sun, size on an area lamp), which is one lamp, not two.
  • Interface: atmosphere is counted from the census. The no_fog plan check fires when the census finds no volume at all; a volume-only mesh (only the Material Output's Volume socket linked, fed by a ShaderNodeVolumePrincipled) counts, and the placement gate ignores it. A box mesh with that material is the simplest one; a local mist over a pond or a hollow, or a light shaft (a higher Anisotropy where the sun crosses an opening) is the same material on any volume-only mesh. A world volume over a large scene measured as swallowing the sun and flattening the frame. How thick the air is, and its colour, is the brief's; fog_short warns when the density would dissolve the plan's own span.
  • Lamps in zones are yours — bpy.data.lights.new(name, "AREA" | "POINT" | "SPOT") on an object linked into ctx.collection; a "practical" is a small soft area lamp beside a lantern, window, fire or sign, aimed at what it lights. A glow-sized energy (tens of watts) lights the surfaces beside it, not a frame: two such lamps measured mean_lum 0.05 (an ERROR); hundreds of watts each is where a night frame passed. Create lamps through bpy.data.lights.new; operators in a loop are a hang-risk lint finding, and bpy.ops.object.light_add wants a view-layer context the build does not give.
  • An emissive mesh is the look, not the light. Cycles does scatter light from an emissive surface, but a fixture-sized emitter throws almost nothing a frame can measure: two 0.15 m emissive spheres at the strengths that make a lantern read as lit left the night frame at mean_lum 0.03, and at forty times that strength — white blobs — it was still an ERROR; the same scene passed once each sphere had a 500 W practical area lamp beside it (reference, section 4). Emission on the fixture (Emission Color with a modest Emission Strength), illumination in a lamp, and the emission modest: AgX pulls a saturated emitter toward white, so a strong neon tube renders as a white bar.
  • Interiors. The band applies on every authored camera inside, and the overview rig lifts a lid it can identify: a mesh named Ceiling… whose parent is named RoomShell… and whose evaluated bbox top is below the camera is hidden for that rig frame (lift_lids in render_bpy_scene, the three.js host's rule): name your shell that way. A ceiling area lamp sized to the room measured 0.34-0.82 at 50-800 W, and an emissive window pane with an area lamp just inside it is one way to light a room by day. The indoor placement tolerance is tighter, so a lamp on a table is seated on the table's top too.
  • Albedo before light. A ground whose Base Color is near black stays dark under any sun, and a plaster wall clips under the sun that lights a lawn correctly. The large surfaces' albedo is the strong dial (the third row), the sun the weak one, the practicals the local one.

Night: the band, not the floor

Target: the "dim but lit" band on every authored camera — mean low, lum_std at least 0.12, not mostly black. Both ends fail: a sky-lit average on a lantern scene is a grey wash (a flat frame, and the judge's unlit-or-blown defect), and glowing fixtures with no lamps behind them are a black frame with stickers. Measured on this renderer: a low night world, each fixture paired with a practical area lamp at hundreds of watts so the pools overlap into a readable picture, dark materials with a low but non-zero Base Color and shadows left dark reached the band; a fill lamp that lifts the mean pushed it to a flat wash.

The hero must be visible

The frames gate also reports hero_unseen and hero_small_in_its_camera; a hero in shadow at night is a hero the judge cannot find. Its own key — a practical area lamp or a spot aimed at it (a Track To constraint, or a rotation computed from the direction) — and a look at its camera's frame.

Prove it

3dcode scene-views --cameras all --times 0, then read camera_checks per camera against the first table: the same five numbers the gate uses. A Blender view costs seconds, so render once per change, all cameras, and fix whatever the finding names on EVERY camera, rig views included.

Full measured tables, the night and interior setups as code: references/exposure-bands.md.

Surfaces that read as a place — Principled recipes the census cannot see

Who sees what

The judge sees Cycles pixels: every noise texture, bump and vertex colour you wire is in the picture, and the rubric names the failures directly — placeholder_material (default-grey or untextured flat surfaces, with a score ceiling of its own), flat_ground (one flat colour with a hard undressed seam where objects meet it), monotonous_vegetation (one shape stamped many times with no variation in hue or size) and hard_edged_particles (steam, smoke or sparks with a silhouette) — under its materials_shaders_effects criterion. The deterministic side sees almost nothing: the census GLB the gates read carries each material's Principled Base Color, Metallic and Roughness default values only, and a LINKED socket exports as its default. So no gate measures material work; this sheet is about the judge's picture, plus the one census fact that does bite — a mesh with no material at all is warned as exporting grey.

Blender 5.2 facts the lint checks

  • bpy.data.materials.new(name) already carries a node tree with a Principled BSDF: reach into mat.node_tree.nodes["Principled BSDF"]. A use_nodes line is not needed, and the lint reports it as deprecated.
  • Socket names are the 4.x ones — Base Color, Roughness, Metallic, IOR, Alpha, Normal, Emission Color plus Emission Strength, Transmission Weight, Coat Weight, Sheen Weight, Subsurface Weight, Specular IOR Level. The old Specular, Transmission, Emission, Subsurface and Clearcoat keys raise, and the lint names the renamed ones for you. Specular Tint is a colour, so assign a 4-tuple.
  • Mixing colours is ShaderNodeMix with its data type set to RGBA (Factor, A, B in, Result out); ShaderNodeMixRGB is gone.
  • Per-face materials: set material_index on the bmesh faces BEFORE bm.to_mesh. Every new polygon starts on slot 0, and the census warns about slots no polygon uses — the part was authored in four colours and exports in one.

Surfaces in nodes — what reads as photoreal

Every material is a node tree you wire on mat.node_tree. What the judge reads as real is variation at MORE THAN ONE SCALE, in object or generated coordinates so it is metres whatever the object's size:

scalewhat carries itnodes
metres — tone, wear, damp, sun-bleacha low-frequency mask mixing two close coloursNoise texture (Scale ~0.2-1 per metre) into ShaderNodeMix (RGBA)
decimetres — courses, planks, patchesa pattern the material hasBrick / Wave / Voronoi texture, or a ColorRamp over noise
centimetres — grain, pores, gritfine bump and roughness breakupNoise / Voronoi (Scale 20-200) into ShaderNodeBump and through a Map Range into Roughness

Keep non-emissive albedos inside 0.02-0.8 linear: pure black reads as a hole, pure white as a blown surface. A copy is not a twin when its variant picks other colours or an Object Info Random drives a small hue shift (below). A glowing fixture is Emission Color with a modest Emission Strength — the look only; the light is a lamp (c3d-bpy-scene-lighting). Steam, smoke, dust and mist are a volume-only material (below). Node snippets in references/principled-recipes.md.

Variation without twins

Collection instances share the source collection's materials, so per-instance tinting is not "edit the material". Variation across copies comes from (a) several SOURCE variants — build_<snake>(ctx, variant=k) building with other colours and another silhouette — placed in rotation, (b) per-instance scale and yaw on each instance Empty, and (c) for one material over many copies, an Object Info node's Random output driving a hue shift, which Cycles evaluates per instance. The stamped_ring plan check measures rings of identical copies at one radius, and the judge calls the result monotonous vegetation.

Ground: what flat_ground means

Requirement (judged): the ground does not read as one flat untextured colour where the brief's surface would vary, and the seam where structures meet it does not read as a hard undressed line. A ground mesh usually carries ONE material, so the variation lives inside it or in the mesh's own attributes. Options, by what the brief's place has: a slope mix (the Geometry node's Normal, its Z through a ColorRamp into the mix factor) and a height mix (object Z from Texture Coordinate) for natural ground; a worn band as a noise-masked colour along the routes people take; a darker or rougher apron, or ground cover (a geometry-nodes Instance on Points cloud), at the feet of big structures; a colour attribute on the ground mesh read by a Color Attribute node when the bands are easier to paint per vertex than to compute per pixel; paving (a Brick texture, or modelled setts) where the ground is built, not grown. A polished floor or a plaza that IS one material is not a defect when its material reads as that material.

Water, glass, fog — dielectrics and volumes

  • Water is a dielectric: Transmission Weight 1, a low roughness and Metallic at zero; a metallic mirror plane reads as chrome, not water. Moving water scrolls its Mapping node's Location input with keyframes on ctx.frame(t).
  • Glass: full Transmission Weight, roughness near zero, IOR about 1.45-1.5. The bounce budget is the harness's, so a stack of transmissive layers along one sight line goes dark — one or two read.
  • Fog is a VOLUME-ONLY material on any mesh (a box is enough): only the Material Output's Volume socket linked. A mesh with a surface shader as well is matter to the census — a huge placed asset enclosing everything — and the no_fog check does not count it as atmosphere.
  • Soft particles are volumes too. A surface shader always has a silhouette; 8 of the 30 argon Blender scenes of 2026-10-15 built steam from translucent ico-spheres, metaballs, stacked tori, discs or polygon sparks and were graded hard_edged_particles. A volume-only material on a cloud of spheres (one mesh, one object, tagged placement = "free", keyframed so the two judged frames differ) rendered with no edge, and 40 such puffs added 0.7 s to a 32-sample GPU frame; motes and sparks read as tiny emissive spheres. Under a dim world a volume with zero emission comes out grey.

Emissive and metal under AgX

AgX desaturates bright emitters toward white: a saturated sign needs a modest Emission Strength and a coloured area lamp beside it for the glow on the ground. Metals need something to reflect — the sky world and the haze are what a worn metal mirrors; a metal under a black world is a black shape.

Verify before you finish

3dcode scene-views --cameras authored --times 0 and zoom one frame: a wall or a ground that is one flat value where the brief's would not be needs variation; two copies you cannot tell apart need variants; a grey default is a mesh that never got a material (the build output warns about it by name). Then 3dcode scene-probe for triangle counts — materials are free, geometry is not.

Node snippets — noise to bump, the slope mix, the Object Info tint, per-face slots, the volume-only material, the socket rename table — in references/principled-recipes.md.

Everything sits on something — placement the gate can measure

Read this if you are writing a zone, the env, or fixing a 3dcode check-placement finding. The placement gate is deterministic (a hand's breadth of hover is an ERROR), every ERROR is a score ceiling in the scene rubric, and the judge is handed a close-up crop of each measured finding.

What is measured, and on what

The build writes a census GLB from the evaluated depsgraph (modifiers, geometry nodes and instances included) and the gate reads that, never the .blend. A placed thing is every direct child of a zone collection that has mesh descendants, and each one is ONE row:

what you buildrowsmeasured
a mesh object, with or without children1 — the whole subtreeyes
a collection-instance Empty (instance_type = 'COLLECTION')1 per placed copyyes — its clones are sampled like a mesh
a multi-part prop under one root (a parent Empty, parts parented under one mesh, or joined meshes)1yes
twelve loose meshes that together are a hut12yes, each at its own feet
a geometry-nodes or particle cloud (an Instance on Points tree)1, exempt as instancedno — and never a support either
a volume-only mesh (a fog box, a steam puff)exempt as volumetricno, and never a support or an overlap partner
ground, water and sky by name and shape; a shell that swallows the content boxexempt as backdrop or enclosureno
anything tagged obj["placement"] = "free", or its whole zone collectionexempt as freeno — but counted, see below

Per row, from up to 5 foot columns taken from its lowest vertices — a table is measured at its leg tips, not under its top:

  • ground_gap_m — the vertical distance from the foot to the nearest surface of any OTHER mesh below it (terrain, floor, table top), else to the census ground level.
  • sunk_m — how far a foot sits below a surface that passes through the asset's own extent.
  • on_water — a water-named surface at or above the foot: supported, never sunk.
  • attached — another asset's box within contact distance: mounted, so a small gap is left alone.
  • gap_max_m, columns_resting, tilt_m — how many columns rest, how far the worst hangs.

The kinds the report names, worst first: floating (a gap above the indoor or outdoor tolerance; ERROR past floating_error_m or when more than floating_error_count assets float), unsupported (a smaller gap, touching nothing: WARN), sunken (burial past sunk_m; ERROR past sunk_error_m when it also swallows sunk_error_frac of the height), interpenetration (two boxes overlapping more than overlap_warn of the smaller one, confirmed by inside_frac of its vertices inside the other; ERROR past overlap_error), cantilevered (at most one of four or more columns rests while the worst hangs: WARN) and free_exempt (the share of free-tagged assets past free_exempt_warn, then free_exempt_error). Every threshold is a Settings.placement field and the summary line of 3dcode check-placement prints the values it used. Interiors get the tighter tolerance; the plan's setting words decide that (is_interior).

Three exemptions are by NAME (placement_words.json, one file read by the gate and by the boot-time settle): buried_ok words (pit, pool, well, trench) are never sunken; slope_ok words (path, platform, stairs, terrace) follow the terrain; partial_ok words (rock, tree, post, fence, pebble) may sink up to partial_ok_frac of their height. A thing named what it is gets the tolerance its kind has; the judge grades the crop whatever the name.

The requirements, and ways to meet them

  1. Interface: one ground authority. height_at(x, y) in src/env.py is the ground every zone reads as ctx.height_at, and the ground mesh samples the same function. Any function of (x, y) the brief's landform needs is fine: rolling hills from summed sines or mathutils.noise.fractal, a slope to a river, a ridge, a terrace, a quay stepping down to a basin, a plaza flat everywhere; the ground mesh is a grid whose vertices you set to it. A zone that flattens its own patch to a different number is a bench buried on one side, floating on the other.
  2. Requirement: feet within the gate's gap tolerance of what is under them (measured on the census GLB at the foot columns). Read the point set the gate reads — the root's world-space vertices, its children's, and for an instance Empty the source collection's through the Empty's matrix — keep the lowest ones, and move the root by the smallest ctx.height_at(x, y) - z over them. A thing ON a thing — a cup on a table, a lantern on a post — goes onto the support's top under its footprint, because the gate measures the gap to the SUPPORT. Any placement that passes 3dcode check-placement is acceptable.
  3. Sinking is tolerated for names that sink — a rock, a post, a tree with modelled roots; the words file carries the list. A crate sunk "so it cannot float" is a sunken finding and a crop of a crate in the ground.
  4. Slopes. Seating by the smallest gap rests the foot over the lowest ground and buries the rest, so a wide thing on a slope comes back sunken uphill; placed at the ground height of its CENTRE, its downhill feet hang: cantilevered. Options: a pad in height_at under it (the ground mesh follows), seated segments, or a turn along the contour (a yaw about Z).
  5. Requirement: a multi-part thing whose parts support each other is ONE row — one direct child of the zone collection with the parts under it — or each part is seated on its own support. A root Empty with the parts parented under it at relative locations, or one mesh built from all of them, does it; twelve loose meshes are twelve rows and twelve overlap partners for each other.
  6. Requirement: anything the brief or plan counts is a measured row (a direct child of the zone collection with mesh descendants). Geometry-nodes and particle clouds are exempt from placement and are never supports, so nothing can rest on them; the plan-contents check counts instances either way. Collection-instance Empties make rows; a geometry-nodes Instance on Points tree makes a cloud — the way for the hundreds (blades, pebbles, litter, a far treeline). In 5.2 a new GeometryNodeTree has no sockets and no nodes: add them with ng.interface.new_socket(name, in_out='INPUT' | 'OUTPUT', socket_type='NodeSocketGeometry') and your own NodeGroupInput / NodeGroupOutput nodes (NodeTree.inputs / .outputs are gone).
  7. free is for hanging and airborne things — a bird, a kite, a lantern on a chain, a steam plume. The gate reports the share of free-tagged assets (free_exempt), and the judge's floating defect still sees a free-tagged crate in the air.
  8. Requirement: a PLANNED content placed entirely outside the plan bounds is the out_of_bounds kind (a WARN, past the bounds + max(5 m, 10 % of the span)). Everything else — terrain, water, far buildings, forest, the rest of the street — continues past the bounds as the brief's place does and is never reported. Clamping its x / y into the zone's plan box slides one back. A row far from its planned approx_size_m is the scale kind, and the fix is the SOURCE asset's build, not the Empties.
  9. Requirement (outdoor plans): the world continues past the bounds. world_edge is a WARN when the farthest content or ground group at least 2 m tall reaches less than 1.25 × the bounds' half-extent from the centre. Whatever the brief's horizon holds satisfies it — a landform that keeps rising, a forest edge, far roofs, cliffs, a sea wall — built in the env (not a placement row) and named Sky… when wide, so the census classifies it as backdrop. The census also measures stamped_ring — near-identical copies evenly on a circle round the world's edge — which the judge calls a toy backdrop.
  10. Names are global in Blender. Number copies f"{base}_{i}"; a second Lantern_0 becomes Lantern_0.001 and the plan-contents check loses it.

The self-check, then the gate

Compare the world bounding boxes of the zone's roots AND its scattered Empties pair by pair: the overlap volume over the smaller box's volume past the interpenetration band is a finding. Drop every scatter point that falls inside the footprint (plus a margin) of what you placed by hand: 9 of the 13 Blender zones with an interpenetration ERROR in the argon loop's iteration 0 (2026-10-15) had scattered a small prop into a cart, a rack, a shrub or a mound. Then 3dcode build, then 3dcode check-placement, which prints the findings with their fix hints and the table:

asset | gap to support (m) | support | sunk (m) | into | water | attached
Market/Bench_0 | +0.236 | Terrain | 0.000 | - | - | -
interpenetration Market/Cart_1 × Market/Stall_0: 41% box, 23% inside

The hint's number is the measured gap: move the root by it. A round whose last 3dcode check-placement lists an ERROR is capped by the rubric on each one; a PASSED gate vetoes the judge's own floating claim.

Motion, and the feet

The census is taken at the build's current frame, so a moving thing is measured seated at every time the harness samples (t = 0 and t = 1.5 s; the judge diffs the two frames and names nothing_moves when it sees no change). Motion is data: keyframes on ctx.frame(t) or a simple driver of frame (a driver that needs Python evaluates to 0 and the lint rejects it). A tree with its origin at its base sways about its feet (a keyed rotation turns about the origin: put it at the hinge or hub). A boat drifting ON a water-named plane is on_water; a bird, a steam plume or a spark cloud built as one object is a free row.

Worked zone, row provenance and the finding-to-fix table: references/finding-to-fix.md.

CadQuery: forms, and the kernel rules that gate them

Evidence warning, read it once: we have no graded CadQuery runs. The API rules below are verified against the installed kernel; nothing here is ranked by measured defect frequency.

Form to technique — an optional toolbox

The plan names language-neutral forms; the kernel has a native maker for most of them. These are options under their real API names, not a mapping to follow.

forma native option
slab / block / panel.box(x, y, z), centered=(True, True, False) to stand on zero
shaft / disc / cylinder.circle(r).extrude(h); .cylinder(h, r) takes height FIRST
revolved profile — vase, finial, baluster, dome, barrelclosed half-profile on "XZ" (.polyline/.spline + .close()) then .revolve(360, (0,0,0), (0,1,0)); keep the profile at radius >= 0
ring / band / torus.moveTo(R, 0).circle(r).revolve(angle, ...) — see kernel rule 1
extruded outline with softened edgesoutline .polyline().close().extrude(t), then `.edges("
tube swept along a path.circle(r).sweep(path); the profile plane must be perpendicular to the path start
tapered solid — horn, spout, mast.circle(r1).workplane(offset=h).circle(r2).loft(), or .extrude(h, taper=deg)
lofted transition between sections.loft() between profiles with matching vertex counts (circle to circle, rect to rect)
shell with wall thickness.faces(">Z").shell(-t) from ONE open face; the kernel refuses it on a lofted round body — subtract a shrunken inner loft instead
carved cavity / slot / bore.cut(cutter), .hole(d), .cutBlind(-depth), .slot2D(length, width)
faceted solid — die, gem.polygon(n, d).extrude(h), facets via taper= or a loft between polygons
repeated feature — grid, ring of N, point list.rarray(dx, dy, nx, ny), .polarArray(radius, start, angle, count) or .pushPoints([...]) before the feature
mirror pair.mirror("XZ") on the piece, then place both in the Assembly
where a feature goesstring selectors `"
embossed label.text(txt, size, depth) — may raise headless (no fonts), so try/except it

Kernel rules — probed against CadQuery 2.8.0 in this repo

  1. .center() before a revolve is fatal; use .moveTo(). Workplane("XZ").center(R, 0) .circle(r).revolve(360, ...) raises StdFail_NotDone: BRep_API: command not done. The identical chain with .moveTo(R, 0) builds a valid torus. .center() moves the workplane origin, so the profile ends up sitting on the axis. Passing an explicit axis does not rescue it — both forms fail.
  2. A union that does not overlap fails silently. Two spheres placed exactly tangent union into 2 solids and still report isValid() == True; the same pair with 0.5 mm of overlap gives 1 solid. .isValid() will not catch this and neither will a render — the connectivity gate of 3dcode check reports the second solid as a stray island. len(wp.solids().vals()) after a union or a cut catches it before a build; a through cut that splits a part also leaves 2 valid solids.
  3. Each plan part is its own Assembly child. A pair unioned across a plan boundary reads as a missing part in the contract gate of 3dcode check. Touching parts: a gap ≤ 2 mm is contact, overlap

    2 mm is WARN, > 10 mm is ERROR (the connectivity gate of 3dcode check; the table is in c3d-part-contact).

  4. Keep solids closed. Export runs through STL as well as GLB; .shell() keeps a solid watertight, hand-assembled faces do not.
  5. Features under ~0.5 mm come out invalid at OCC tolerance.

Strong options — optional practices

Fillets the kernel accepts. Refusal is not monotone in the radius: on a 3 mm shelled wall a rim fillet passed at 1.4 mm, failed at 1.5 mm, passed again at 2.0 mm and failed at 3.0 mm, so "try a slightly bigger radius" is not a strategy. A conservative budget (the hint the runtime prints after a refusal says 0.45 x the thinnest adjacent wall), few edges per .fillet() call, and try/except around fillets that are only cosmetic is the strong option. Whether a fillet goes before or after a boolean that touches its edge is not a rule either way — only the build result counts. Where .fillet() is refused on a thin wall, a .cut() with a rounded tool softens the same edge. (The claim that the limit is half the shortest adjacent edge is false here: a 10 mm radius on a 10 mm vertical edge builds.)

Mating faces. A mating coordinate computed from the plan numbers of the face it meets lands inside the gate's contact band (flush counts) without nudging. A cutter that overshoots the face it exits avoids coplanar-face boolean failures; the coplanar case passed in this probe, so the overshoot is a habit, not a measured need.

Selectors after booleans. Edge indices reshuffle after a boolean; re-select by geometry (">Z", BoxSelector) rather than by a cached index, and print len(wp.edges(sel).vals()) when a selector might match nothing — an empty selection raises ValueError.

Measure before you render. Print per part what the gates read — BoundingBox() extents and zmin, len(solids().vals()), Volume(), isValid() — then the track loop: 3dcode check (its contract and connectivity gates) -> 3dcode render-views. Volume() catches hollow-when-it-should-be-solid, the solid count catches a split, zmin catches a floater, all before a render is spent.

The four traps our own tooling is written to catch

  • No module-level result — ERROR from lint:cadquery. It must not live under if __name__ == "__main__":, and sys.exit() before it is set is its own error.
  • result that is not a cq.Assembly — the whole model exports as ONE node called Object, so the contract gate reports every plan part missing. Use result.add(solid, name="PascalName", color=cq.Color(r, g, b)) per plan part; an .add() without name= gets a uuid node name and has the same effect.
  • A trailing selector — a chain ending .faces(">Z") leaves Face objects on the stack. The wrapper recovers the parent solid and warns; end the chain on the solid.
  • Radians into a degrees argument — .rotate(p0, p1, angle), cq.Location(v, axis, deg), .revolve(deg) and twistExtrude(h, deg) all take degrees. A math.pi expression in that slot is a lint ERROR. Also cq.Solid.makeSphere(r) without angle arguments builds a hemisphere (measured: z extent half of x and y); use cq.Workplane("XY").sphere(r).

More probe results and the failing/passing chains: references/kernel-probes.md.

What separates a graded shader from a demo

Read this if you are writing src/shader.frag. The contract states the interface and what the harness measures; this sheet is the layer above it: what the measurement can and cannot see, and a few strong options that answer the judge's recorded complaints. None of them is a recipe — the brief decides what is on screen and how it is built.

The gate is a floor, not the bar

spatial/frame_stats.py renders five frames — t = 0, 1, 2.5, 4, 6 s — and measures them:

  • static — the largest mean |Δ| between consecutive frames is under 0.002 (WARN, score cap 0.5 when motion is planned)
  • flicker — a consecutive pair differs by more than 0.35 of the image (WARN, cap 0.7)
  • black / blown — in every frame over 97 % of the pixels sit under luminance 0.03, or over 0.98 (ERROR, cap 0.5)
  • low_detail — almost no pixel sits on a visible luminance edge (WARN)
  • nan — any NaN / Inf pixel (ERROR, cap 0)

Over the 9 graded glsl runs mined 2026-08-25 the gate fired nothing while the judge sat at 0.55-0.65: clearing it proves nothing. The judge is shader: likeness 0.26, depth_and_detail 0.16, light_and_tone 0.16, motion_quality 0.14, composition 0.10, technical_cleanliness 0.10, craft 0.08, plus the defect list the system prompt carries. One hint, and only a hint at n = 9: the harness's colourfulness metric (3dcode gl-frames prints it) ranked with the final score at +0.75, edge density at +0.40 and frame-to-frame motion at +0.20 — the palette is worth more attention than another octave.

Strong options (none required; each answers a recorded complaint)

Scales. One octave at one frequency is both flat (flat_fill) and shimmery (banding_or_aliasing): a recorded major issue reads "uniform high-frequency noise rather than multi-scale fractal relief, causing severe aliasing". Fine octaves smaller than a pixel alias — fade them with the distance or the footprint the pixel represents.

Edges. A step aliases; a transition about one pixel wide (from fwidth or the resolution) does not. A staircase edge is the banding_or_aliasing defect.

Banding. A long two-stop gradient bands on 8-bit output (3 of 6 fancy-battery runs, 2026-08-31). A sub-LSB dither on the final colour — one hash per pixel, added after the tone-map and gamma — removes it.

Tone. Additive light sums (glow, bokeh, scattering) pass 1.0 quickly: one tone-map at the very end keeps them under the blown threshold; gamma applied twice washes the frame (white_wash).

Exposure first. Hue and palette work is invisible on dark, low-chroma pixels. Read the mean luminance 3dcode gl-frames prints and compare it with what the brief's place would show before grading colour.

Night subjects. The judge's no_dark_range and white_wash defects: a night, space or dusk frame needs near-black pixels somewhere, and haze and bloom belong on the light, not on the frame. 3dcode gl-frames prints the mean luminance and the black-pixel fraction — read them.

Across the flow. Water, wood, marble, cloth and stone read as a sliding texture when the pattern is stretched along the direction of movement (the judge's "texture scrolling under a fixed shape" is 0.5 on motion). Put the fine axis of the pattern across the flow and advect only the phase.

Motion from the mechanism. The frames compared are 1-2 s apart; a single scroll of the uv by u_time gives the same delta everywhere and reads as a conveyor belt. Drive each element from its own quantity — a drop falls with the square of its time, a flame's tips lag its base, a spark has a hash-seeded lifetime — and give every instance a phase from its id so t = 0 is not a symmetric frame.

Continuity. fract and mod of u_time are cuts; wrap through a smooth function, cross-fade the wrap, or hide it under a fade that reaches zero at the wrap. A visible cut between two sampled times is the flicker warning.

Domain warp. Feeding fbm with fbm (IQ's domain warping) gives billowing edges to clouds, smoke and marble; it costs octaves, so budget them.

Volumes. A shaft or a lit cloud is scattering integrated along the view ray: march front to back, attenuate by Beer-Lambert transmittance, weight each step by a phase function normalised over the sphere (Henyey-Greenstein, +1 forward, in light-travel directions — PBRT's convention differs) and by a short march toward the light for self-shadow. A radial falloff around a point has neither direction nor occluder: the sharpest recorded complaint, "a diffuse, uniform spherical glow rather than directional rays", is that term. A cloud is brighter where its shell is thin toward the light — sample the density a short step toward the sun and light the difference.

Surfaces. A dielectric (glass, water) is a Fresnel-weighted reflection plus a tinted transmission; a metallic tint reads as metal, not glass. GGX with Smith visibility and Schlick Fresnel on linear inputs gives a microfacet response; roughness changes the highlight's shape, a shiny colour cannot.

Raymarchers. A hit tolerance that grows with distance, the same epsilon for the normal, and a relaxed step. The critical bug of the lowest-scoring run (0.30) — "bright cyan/white pixels along the edges of all geometry at grazing angles" — was a tangential overshoot feeding a central-difference normal.

The three uniforms worth designing around

  • u_noise — one texture fetch is a bilinear-interpolated hash, several times cheaper than a hash plus interpolation, so an fbm built on it affords more octaves. Scale the uv, not the result.
  • u_prev — this pass's previous frame: trails, motion blur, accumulation. The contract states when it saturates.
  • u_buffer_a — a whole extra pass. When the effect is a simulation (advection, reaction-diffusion, a height field), simulate in buffer_a.frag and shade in shader.frag. No graded glsl run in this corpus used it (0 of 9), while all five critical effect failures recorded in the sibling opengl_python runs are simulations with nowhere to keep their state.

Before you finish

3dcode gl-probe compiles and shows frame 0; 3dcode gl-frames renders all five judged times and prints mean luminance, colourfulness, edge density and the per-pair deltas. Look at the contact sheet, then read the numbers: a largest delta just above the static threshold with a brief that promised motion means the motion is there but invisible.

The moderngl pipeline, and the two things that actually sink these runs

Interface, sandbox, the moderngl build facts and the gate thresholds are in the language contract (setup / render, the harness fbo, the lint lists, the caps); this skill is the craft on top of it, and nothing below is a required shape.

Trap 1: render() is sampled, not ticked

The judged times are t = 0, 1, 2.5, 4 and 6 s — five calls, with unequal gaps (frame counts calls, not seconds; gl-frames --times renders other times). There is no dt and there is no 60 Hz loop.

A simulation that advances one step per render() call therefore gets five steps in total. This is not hypothetical: two of our 5 graded opengl_python runs were ping-pong feedback effects, and they scored 0.19 and 0.48 (graphics_v2_flash, mined 2026-08-25) - the lowest and third-lowest of the five. The judge wrote "the interior of the seeds dies out", "only expanding rings rather than labyrinthine patterns", "ink is only injected at t=0s" and "the ink dissipates far too quickly". Those are all the same defect: five iterations of a solver that needed hundreds.

The requirement: the frame at t must not depend on which ts were rendered before (the instruments re-render single times, and the build renders a sorted schedule). One strong way to meet it with a simulation: keep the state and the simulated time it represents in state; each call integrates from that time to t with a fixed step and a bounded step count, and resets to the seed whenever t is earlier than the state; inject sources as a function of the simulated time, not in a frame == 0 branch. A worked description: references/sampled-time.md.

Trap 2: motion has to be continuous and visible

3dcode gl-frames takes the mean |Δ| of each consecutive pair of sampled frames: if the largest is below 0.002 the program is static (cap 0.5); if it exceeds 0.35 it is flicker (cap 0.7). Only one of our five opengl_python runs ever tripped this gate, but it tripped it in three separate rounds (max deltas 0.373, 0.392, 0.416, ogl_hard_voxel_city, final score 0.342), and the judge read the same frames as "the camera motion is discontinuous or clips into a building, resulting in a hard cut". Since the samples are 1 to 2 s apart, a camera or a phase that is fine at 60 fps can still jump between samples. Check the change between the sampled times, not per frame: periodic wraps and per-call randomness are what has tripped the threshold.

What the gate and the judge measure on the image

Over 5 runs and 10 judged rounds (graphics_v1_flash + graphics_v2_flash, recomputed 2026-08-25) this language's three weakest criteria were originality 0.330, visual_richness 0.375 and brief_fidelity 0.420 — the lowest three numbers anywhere in our corpus. What is measured behind them:

  • mean edge density over the judged frames — below 0.002 the gate reports "a near-flat gradient" (low_detail, no cap; the judge sees the same frames) — and the frame-to-frame delta above. Structure at more than one scale supplies both: silhouettes, instanced or particle detail, texture inside surfaces. Parallax between elements at different depths is one way to get the delta, not a required composition.
  • the acceptance items and key visuals of the plan — the judge checks each one against the frames, and an unmet must item caps the score at 0.7. Build the named things so each is findable in the judged frames; an abstraction that gestures at the brief scores as generic.

Practices (strong options, none required)

A full-screen pass. Four clip-space vertices in a ctx.buffer, a ctx.vertex_array bound with "2f" to the vertex shader's in vec2, drawn as a triangle strip; the vertex shader derives uv from the clip position. A purely 2D brief can be one such pass driven by uniforms you set from render — a legitimate option, not the expected shape. Full-screen passes with DEPTH_TEST on draw nothing behind the previous depth: disable it for them.

Instancing. A second buffer bound with /i formats and vao.render(instances=n) draws many copies in one call. A per-instance phase attribute lets the vertex shader animate each copy from u_time with no per-frame upload, which keeps the cost of a call flat under the build timeout; CPU-side updates go through buffer.write(...) at the same byte size (buffer.orphan() before a full rewrite).

Textures. Procedural data from a seeded np.random.default_rng(seed) goes into ctx.texture((w, h), components, data, dtype="f4") or ctx.texture3d(...); set .filter and .repeat_x / .repeat_y explicitly, and bind with .use(location=k) on every call before the draw that samples it.

Your own framebuffers. ctx.framebuffer(color_attachments=[tex], depth_attachment=...) with a ctx.depth_renderbuffer when the pass needs occlusion. Ping-pong needs two textures — never sample the one you are writing. Give a simulation state texture NEAREST filtering and clamped wrap (LINEAR diffuses the state a little every step and repeat wraps the domain) and store it as f4, not f2 (half float clips near 65504 and quantises visibly in a feedback loop). Several outputs from one pass are fragment-shader out variables with a layout location each, one colour attachment per location.

Light in linear, tonemap once. Keep lighting and accumulation in linear HDR targets (f2 / f4) and apply one tonemap plus gamma in the final pass into fbo; that is also what keeps the blown gate quiet when glow sums grow. With non-uniform scale, transform normals by the inverse-transpose of the model matrix. For a physically based surface a GGX / Schlick direct term in linear light is the usual choice — c3d-glsl-craft describes it; nothing is seeded into this language's workspace.

GL state. The enables and blend modes you are likely to reach for:

ctx.enable(moderngl.DEPTH_TEST); ctx.disable(moderngl.DEPTH_TEST)
ctx.enable(moderngl.BLEND); ctx.blend_func = moderngl.SRC_ALPHA, moderngl.ONE_MINUS_SRC_ALPHA
ctx.blend_func = moderngl.ONE, moderngl.ONE            # additive glow
ctx.enable(moderngl.CULL_FACE); ctx.front_face = "ccw"
ctx.enable(moderngl.PROGRAM_POINT_SIZE)                # gl_PointSize in the vertex shader, mode=moderngl.POINTS

Prove it

3dcode gl-probe after every edit (one frame, compile errors with source line numbers), then 3dcode gl-frames before finishing — it renders the judged times, returns the per-frame luminance / colour / detail / motion table and runs the gate. Look at the contact sheet.

How the schedule is built and what the gate measures: references/sampled-time.md.

Parts that touch

Read this if your plan has two or more parts and you are about to write, move or resize any of them. It is the one defect class that costs the most score here and the one that repair rounds are worst at removing.

Why this is the first thing to get right

Measured on the 102 graded blender runs that have a connectivity report (mined 2026-08-25):

first gated roundlast gated round
runs with interpenetrating parts88 (86%)67 (66%)
runs with a floating part10 (10%)3 (3%)
runs with tiny stray islands56 (55%)52 (51%)

Floating parts get fixed, because they are ERRORs. Interpenetration and crumbs mostly do not: three quarters of the runs that started buried shipped buried. And it is expensive — eval/docs/COMPLEXITY.md section 6, over 160 recorded rounds with both a score and a connectivity report, mean assembly_fit falls 0.709 (nothing buried) to 0.505 (a part more than half buried), and the plain count of penetrating pairs is the strongest single predictor of that criterion (r = -0.258). assembly_fit is already the lowest-scoring criterion in blender (mean 0.60 over 246 judged rounds, 102 runs).

So: fewer pairs in contact, and each contact within the band below.

The band — every number is a live constant

codeverse3d/spatial/connectivity.py + codeverse3d/conventions.py:

whatconstantvalueconsequence
two parts count as touchingCONTACT_GAP_Msurface distance ≤ 2 mmfurther apart = no edge in the contact graph
overlap that is still a weldPENETRATION_WARN_Mdepth ≤ 2 mmabove it: WARN "interpenetrate by ~N mm"
overlap that is a defectPENETRATION_ERROR_Mdepth > 10 mmERROR, and the judge rubric caps the run at 0.70
how much has to be insidePENETRATION_MIN_FRACTION2% of surface samplesbelow it nothing is reported at any depth
samples per partN_SAMPLES600the depth you see is the deepest sampled point
a part too small to checkMIN_PART_SIZE_Mlargest extent < 10 mmskipped for contact, penetration and islands (INFO only)
a crumb inside one partTINY_ISLAND_FRACTIONisland extent < 5% of the part's largest extentWARN "stray geometry"

The whole legal window for a joint is 2 mm of gap to 2 mm of overlap, flush (a gap of 0) included — no overlap is required. Two traps follow directly:

  • Do not "fix" an interpenetration WARN by pulling the parts apart. Past 2 mm of gap the contact edge disappears and the part can drop out of the support component — a WARN becomes an ERROR that caps the run at 0.60.

  • An overlap of exactly 2 mm already reads WARN. Measured with the gate's own penetration probe on a rod driven into a disc:

    overlapreported depthfraction insidegate
    4.0 mm4.00 mm2.8%WARN
    2.0 mm2.00 mm2.7%WARN (right on the line)
    1.0 mm1.00 mm2.5%clean

Floating parts: never guess the fix

A part outside the support component (the ground-touching component with the most faces) is always an ERROR, and the finding already contains the answer:

ERROR part 'door_leaf' is floating: nearest supported part is 'frame' at 4.0 mm
      fix: translate 'door_leaf' by (0.0000, -0.0040, 0.0000) m -- or extend it by
           4.0 mm towards 'frame' -- so the surfaces touch

The vector is converted into your authoring frame before it is printed, and the alternative ("extend it by N mm") is usually the better one: translating a leg leaves a gap at its other end. Apply one of the two literally. Do not eyeball a new position.

Know the contacts before you write code

A strong option: before coding, note for each part with attach_to set which face meets which neighbour, and at what coordinate, and compute that coordinate from the neighbour's plan bbox rather than retyping it — a computed end follows the neighbour when it moves in a later round. (c3d-bbox-contract owns the tolerance arithmetic.)

Detail belongs INSIDE a part, not as more parts

N top-level parts create N(N-1)/2 candidate contact pairs, and the count of penetrating pairs is what predicts the score. Sub-shapes inside one part create none. Measured over 183 judged rounds on this harness: ρ(triangles per part, geometry_detail) ≈ +0.08 while ρ(number of plan parts, assembly_fit) = −0.48 — triangles inside a part are free, extra top-level parts are not.

PartPlan.children is exactly this device — the docstring says sub-parts of an assembly part are "still ONE named object in the export" — and spatial/measure.py::part_meshes backs it up: a part is an effective top-level node and its whole subtree is merged into one mesh before any pairwise test runs. Measured on Blender 5.2.2 through the wrapper: three disjoint sub-shapes built into one mesh named Housing export as a single node.

But fusing is not optional. Islands are split by face connectivity, not by overlap — verified against the gate: a rivet placed so it geometrically overlaps a panel, without shared topology, is still a separate island. So a sub-shape must be either

  • welded into the body — one boolean UNION, or an array / mirror / screw result (those are one object by construction), or built into the same bmesh; or
  • at least 5% of the part's largest extent, which is what TINY_ISLAND_FRACTION asks. On a 1.0 m panel that is 50 mm: a 15 mm rivet dropped in loose is a stray-island WARN.

Where crumbs actually come from

  • A cutter object left in the scene. Measured on Blender 5.2.2: the exporter selects every visible mesh, so an un-hidden boolean cutter exports as its own part — with its own interpenetration and its own floating ERROR. Apply the boolean and delete the cutter, or set hide_render / hide_viewport / hide_set(True) on it; all three keep it out of the export and the boolean still evaluates.
  • Boolean leftovers and slivers — check the result with the connectivity gate of 3dcode check. The solvers on 5.2.2 are EXACT, MANIFOLD (closed inputs) and FLOAT; 'FAST' is a lint ERROR.
  • A mirrored half that was never merged, and zero-thickness or coincident faces.

Verify with the gate, do not re-implement it

Run 3dcode check; its connectivity gate reads your workspace and answers in your authoring frame. It runs an fcl exact-distance contact graph, a per-island parity containment test and the island split. A hand-written centroid or bounding-box check in your own build script is strictly weaker and will disagree with the gate that scores you. Do not finish on a run whose last 3dcode check still lists an ERROR.

Worked recipes (bpy, CadQuery, URDF) and the full finding-to-fix table are in references/contact-recipes.md.

Repeats, mirrors and arrays

When: a plan row says instances > 1, or symmetry is mirror_x / mirror_y / radial, or the brief asks for a ring / row / pair of the same thing. Skip if every part is unique.

A strong option: build the shape once and place the copies from a loop whose numbers come out of the plan row — a hand-typed second copy is how a pair stops matching.

What the gate actually measures

the contract gate of 3dcode check (spatial/contract.py) treats an instanced part differently from a single part.

  • Naming. The gate first claims the node named exactly like the plan part, then claims Name_0, Name_1, ... (Leg1, with no separator, is NOT an instance of Leg). A node whose name is exactly another plan part's name is never stolen. Use Name_0 .. Name_{N-1} — that is the string the gate's own fix hint asks for.
  • Count. instances = N but a different number of nodes found is a WARN: 'ApexFinial': found 1 instance(s), plan asks for 2.
  • Box. For instances > 1 the centre is not checked at all. The gate computes two readings and reports whichever fits better:
    • (each instance) — the worst single copy's extents against the plan extents;
    • (all instances) — the union bbox of all copies against the plan extents. Satisfying either one clears the finding. The plan's bbox for an instanced row describes one copy at a representative location (see tracks/planner.py::plan_example: Upright, instances: 4, the extents of one bar), so build each copy at those extents and the (each instance) reading goes to zero.
  • Tolerance. Per axis tol = max(0.01 m, 0.10 x plan extent); beyond 3.0 x tol the WARN becomes an ERROR. Same constants as c3d-bbox-contract (BBOX_TOLERANCE_M, REL_TOL, ERROR_FACTOR).

Because the centre is ignored here, a mis-placed copy never shows up as instance_bbox. It surfaces later as interpenetration, a floating part, or an overall-bbox deviation — one loop bug, N findings in a different gate.

Measured (bench/out, 2026-08-25)

  • contract/instance_bbox fired in 38 of 217 runs; 12 of those reached ERROR.
  • Of its 191 findings, 144 were (each instance) and 47 (all instances) — the copies were the wrong size, far more often than the group was the wrong span.
  • Median worst deviation 2.0 x tolerance, max 27.7 x.
  • The judge's phrasing of the same bug is plural and total: "All four stool legs float above the ground plane", "All four feet interpenetrate the BasePlinth by 3.0 mm", "All four wheels interpenetrate the chassis". When a loop is wrong it is wrong N times.

Placement: derive from the plan, not from the keyboard

# plan row: Name - extents EX, instances N; CENTRES = the N copy centres the row's symmetry gives
first = build_mesh("Name_0", EX, CENTRES[0])          # ONE build of the mesh data ...
for i, c in enumerate(CENTRES[1:], start=1):
    copy = bpy.data.objects.new(f"Name_{i}", first.data)  # ... N objects sharing it
    copy.location = c
    bpy.context.scene.collection.objects.link(copy)

Shared mesh data means every copy has the same extents by construction, so (each instance) cannot drift. If a copy must differ, that is a different plan part, not an instance.

Radial arrays: the angle comes from the count

n = 6                                              # the count drives the angles
for i in range(n):
    a = 2.0 * math.pi * i / n
    place(f"Spoke_{i}", (R * math.cos(a), R * math.sin(a), Z), yaw=a)

A typed list silently drops or duplicates a step when the count changes, and the gate then reports a count mismatch it took you a round to see. For repeated detail inside one part (flutes, dentils, cage wires) an ARRAY modifier with use_object_offset and an Empty rotated 2π/n is the option (apply it and delete the Empty — only meshes reach the export): one export node, which is what the plan asked for.

Mirrors

Two different things share the word:

  • Symmetry inside one part (a bracket that is symmetric about x=0): MIRROR modifier over the object origin — put the origin ON the symmetry plane, then apply. One node, one plan part.
  • A mirrored pair the plan names (instances: 2, symmetry: mirror_x): two nodes, Name_0 and Name_1, at +X and -X. Both must exist; a missing twin is a count WARN and usually a lopsided silhouette in every render.

On mirroring by negative object scale, the usual warning is wrong here. It is widely repeated that a negative scale reaches the export and inverts normals. Checked on 2026-08-25: spatial/measure.py loads the GLB with trimesh and calls apply_transform per node, and trimesh repairs the face winding of a negatively-scaled mesh on load; the measurement table of 3dcode check then records abs(volume). The gates read identical numbers either way. That cuts the other way too — no geometry gate here can tell a correctly mirrored twin from a botched one. Mirror the mesh data (MIRROR modifier, or a bmesh transform), apply it, and look at the render: the judge is the only check you have.

Same, or deliberately different

The judge penalises both ends, so read the brief before looping:

  • Too different: "The two handle loops are identical in size and shape, failing to provide a distinct smaller thumb loop and larger multi-finger loop" — 3 findings, major, urdf. When the brief distinguishes the members, they are separate plan parts, not instances.
  • Too same: "Cliff walls are composed of identical, rigidly stacked blocks arranged in perfectly straight lines, lacking any organic shape" — critical. For natural repeats, give copies a seeded per-copy variation in scale and rotation small enough to stay inside the contract tolerance (max(0.01 m, 0.10 x extent) per axis) so it cannot cost you a contract finding — see references §6.

Finish

Run 3dcode check: its contract gate (count + both box readings) and connectivity gate (the loop's placement). Read the numbers; do not eyeball the montage.

Depth, the full failing-message catalogue and the per-language array/mirror idioms: references/instances.md.

Sky, environment and air — the frame's light source

Requirement: if any material reflects (metal, glass, water, wet ground), scene.environment is set before the first frame renders and agrees with the sky the camera sees. The order you write things in is yours; a reflective surface born before its environment exists simply mirrors black until it is set.

The sky

Interface: a drawable is classified sky when its name matches sky / skydome / skybox / stars / clouds / sun / moon / atmosphere and spans more than 50 m (or by size alone past 2000 m) — then it inflates neither content_frac nor the overview fit. Whether the brief's place has a visible sky at all is the brief's (an interior, a cave, deep space).

Strong options: makeSky(scene, { rig }) from lib/sky.js is the shipped dome, lit from the same sunRig as the scene (it keeps a scene.background already set, else sets its horizon colour). One of your own is a BackSide sphere (fog: false, depthWrite: false, built with makeShaderMaterial from lib/shader.js so the tonemap chunks stay) whose fragment colour is a function of the view direction: a horizon-to-zenith gradient, a sun term around sunDir (a halo and, if the brief's weather shows it, a disk), and a haze band that pulls the lowest degrees toward the horizon colour. The curve shapes and the colours are the brief's sky: a low sun widens the halo and warms the horizon, an overcast sky is one flat gradient, a night sky hashes the direction for stars and shades a moon.

Bake the SAME sky into scene.environment

sunRig returns envTex baked from its own sky — assign it and the requirement is met. If you bake your own equirect DataTexture, these are bugs when broken:

  • 256x128 or larger. three derives its PMREM cube size as width / 4; a 64x32 bake gives 16-pixel cube faces — technically valid, visually useless.
  • Bake WITHOUT the sun disk — the disk doubles every specular highlight.
  • tex.mapping = THREE.EquirectangularReflectionMapping; tex.colorSpace = THREE.SRGBColorSpace;
  • The orientation bug that blackens water: three samples v = 1 at the ZENITH, and a DataTexture defaults to flipY = false, so ROW 0 IS STRAIGHT DOWN. Fill with const v = 1 - y / h; (theta = v * PI from the zenith). Inverted, the ground half sits where the sky belongs and every reflective surface mirrors the dark half — the reference harness found this in 4 of 9 delivered scenes; its canal went from near-black to green-with-sun by flipping that single line.
  • Keep dome and bake the same function, and paint the cloud shapes faintly into the bake too, so reflections agree with the sky the camera sees.

Clouds

Requirement: if the brief's sky has clouds, they read as soft volumes at the authored cameras, not as hard-edged cards (judged: hard_edged_particles, materials_shaders_effects). Strong options: a ray-marched deck lit from sunDir for a sky-filling layer, a volume with internal light when a cumulus is close enough to need it, or sprite puffs from one shared radial-gradient canvas in a flattened cluster, bottoms tinted darker, depthWrite: false. Volumetrics cost frame time; the brief decides whether a cloud earns it.

Haze

If the brief's weather has haze or fog: keep it in the sky's hue family and thin enough that the midground stays readable — the frame gate reads a washed frame as flat_frame (one luminance band holding > 92 % of an authored frame is an ERROR) and the judge reads no falloff at all as thin_atmosphere. scene.fog does the simplest version; ground fog is a height-faded layer of your own, distance haze a view-distance blend toward the horizon colour. A clear dry day may have almost none. The shader-trap skill covers the fog uniforms custom shaders must honour.

Verify before you finish

Render one frame and look at a reflective surface: water or glass mirroring a BRIGHT sky half means the bake is upright; mirroring darkness at midday means row 0 went to the zenith. references/exotic-space.md holds the validated black-hole / nebula / planet notes for space briefs.

Composing a scene the instruments can read

Read this if you are writing env.js, placing a zone, or returning the cameras array. The harness measures a composition in a handful of numbers; this sheet says which numbers, where they come from, and leaves the picture to the brief. Nothing here is a layout: the 60 argon iteration-0 scenes (2026-10-15) all came out as one block on a flat plate ringed by hills because every session built the same recipe, and that is what the judge marks as a toy.

What has to be true, in whatever order you build it

  • The plan's bounds are the content box: the harness clamps its own overview rig to them and the placement gate measures planned assets against them (out_of_bounds, a WARN past max(5 m, 10 % of the span)). Nothing in env.js restates them for the harness — it reads only heightAt, buildEnv and the sun-azimuth export (the contract) from that file. They are where the content lives, not where the world stops: the world the authored cameras see continues past them.
  • One height function. heightAt(x, z) in env.js is the only ground authority: the ground mesh samples it, every zone seats on it, every camera's eye is set from it. A zone that invents its own ground level is how props end up buried and cameras underground.
  • The world does not end in shot. From every authored camera nothing shows the ground ending or an empty horizon line (judged: world_edge_visible); the placement report measures outdoor standing geometry reaching past the bounds (world_edge, a WARN) and fog reaching past the content (fog_short, no_fog). See the horizon menu below.
  • Cameras are derived from measured content, not guessed (the table below).

The classifier nobody tells you about

runtime_js/lib/backdrop.mjs sorts every drawable into sky / ground / content from its name and its world box shape, and that classification decides content_frac (the coverage gate) and ground_y (the camera-height gate). The rules, in order:

ruleclass
name matches sky, skydome, skybox, stars, clouds, sun, moon, atmosphere and span > 50 msky
span > 2000 m, or height > 300 m with span > 300 msky
any InstancedMeshcontent (always)
name matches ground, terrain, floor, water, ocean, sea, lake, river, plane, sand, grass, land and span > 20 m and height < 6% of spanground
span > 40 m and height < 2% of span (any name)ground
everything elsecontent

Three consequences to design around:

  • A wide flat slab is ground whatever you call it. A 50 m plaza deck or a big pond is classified ground, so it stops counting as content, and its top raises ground_y.
  • ground_y is the top of every ground mesh unioned, so a raised terrace or a hill sets the floor that camera heights are checked against. In this corpus a garden reported ground_y = 6.21 m and three authored cameras placed at absolute eye height came back as camera is 1.0 / 4.6 / 4.8 m below the ground level — three ERRORs in one run.
  • content_frac counts drawables classified content. A bigger ground plane does not raise it; what raises it in a thin shot is whatever the brief's place has in that view (buildings, trees, people, boats, instanced cover — the brief decides which).

Cameras are measured, and the numbers are hard

codeverse3d/spatial/frame_metrics.py runs on the authored cameras, where every finding is an ERROR (the harness's own orbit rig only gets WARNs). judges/rubrics/scene.yaml turns those ERRORs into score ceilings:

conditionconstantfindingcap on the run
nearest surface < 0.5 m, or the camera is inside a mesh boxNEAR_HIT_Mcamera inside / touching geometry0.50
eye below ground and the frame corroborates it (dark, empty or one-colour)—camera_underground0.50
the first camera (measured as the establishing shot) shows < 20 % content—establishing shot shows too little content0.60
any authored shot that is almost all sky/ground—shot shows little contentWARN
eye less than 0.3 m above groundEYE_MIN_ABOVE_GROUND_Mant's-eye viewWARN
eye more than 80 m above groundEYE_MAX_ABOVE_GROUND_Msatellite view, not a shotWARN
one luminance band dominates the frame—flat frameWARN; ERROR and 0.65 when it holds nearly all of it

So compute the eye from the terrain and aim each camera at the subject the brief gives it:

const y = heightAt(x, z) + EYE;   // terrain FIRST, then the eye height the brief's shot has

Where a camera stands, how many there are and what each frames is the brief's. The first camera in the array is the one measured as establishing.

Two notes that save a wasted repair round:

  • camera is N m below the scene's highest ground surface is downgraded to a WARN when the frame itself renders fine — that usually means a hill or a raised bed reaches above a camera standing in the open, not a buried camera. Check the frame before you move it.
  • Do not set near or far. runtime_js/lib/scene_host.mjs computes far = max(1000, farthest scene-bbox corner * 1.25 + 10) from the whole scene, so a distant backdrop or sky dome is never clipped.

The world must not end in shot — a menu, not a recipe

The requirement: from every authored camera, nothing shows the ground ending or an empty horizon line (world_edge_visible, judged; all 4 composition issues across the 3 graded runs mined 2026-08-25 were that sentence). Any ground mesh extends past the fog's far distance along every authored view, or something stands between the camera and its edge. How the world continues is the brief's place. Strong options, each on its own enough:

  • Terrain that keeps going — makeOutskirts from lib/environment.js carries the land from the content out to the fog with seam-matched relief, fields and wooded clusters; ground from lib/terrain.js with its relief option is the simpler version.
  • A ridge or mesa on ONE side, with the opposite side falling away to fog or water.
  • A treeline (imposter cards at distance) or an orchard edge.
  • A far skyline — a city block mass, a harbour wall, a viaduct.
  • A shoreline: water to the horizon on one or more sides.
  • Fog only, when the brief's weather is thick enough that the ground fades before it ends.
  • Walls, cliffs, or an interior with no horizon at all (roomShell, cliff).

A ring of near-identical copies stamped evenly round the world is measured (stamped_ring, the placement report) and judged monotonous_vegetation; whatever closes the horizon has to read as that place's far distance at the authored cameras' range, not as a placeholder or a flat card (placeholder_material, judged). If you use fog, a fog colour that matches the horizon it fades into keeps the ground edge from reading as a line; scene.fog already blends distant materials toward it, so pre-tinting a backdrop toward the fog colour doubles the haze and renders as pale cardboard.

Depth that reads

empty_midground (judged) is an authored frame with empty regions the brief's place would fill; what fills them — and at which distances — is the brief's. Two measured limits on the near field: the gate needs nearest_hit_m >= 0.5 m, and no more than 5 of the 9 sight rays may end within 1.5 m (camera_blocked). Scatter is blind, so keep each authored camera's first metres clear of it — a conifer planted on the lens turns the money shot into bark.

Verify before you finish

3dcode scene-views renders the authored cameras and prints camera_checks per camera — mean_lum, modal_frac, content_frac, nearest_hit_m, eye_height_m, ground_y. Read those six numbers against the table above rather than judging the thumbnails by eye, and 3dcode scene-probe for triangles, draw calls and fps. A camera that fails the table fails it deterministically; there is nothing to argue with.

references/measured-cameras.md holds the finding-to-fix table and the naming rules the classifier reads.

Lighting a scene the frame gate will accept

What is measured, and how hard it bites

The harness renders every camera and scores the pixels (spatial/frame_metrics.py):

findingfires whenseverity
too darkmean luminance under 0.12 or more than 35 % of pixels near-blackERROR on an authored camera (cap 0.55), WARN on a harness rig view
blown outmore than 20 % of pixels pure whitesame (cap 0.60)
flat frameone luminance band dominates the frame (an ERROR, cap 0.65, when it holds more than 92 %)WARN / ERROR

Two consequences people get wrong:

  • The two dark conditions are independent. A real finding from scenes_v1_flash: frame too dark: mean luminance 0.07, 0% of pixels near black — a frame with not one near-black pixel still failed, because the whole image was dim. Another in the same battery: mean luminance 0.17, 43% of pixels near black — bright enough on average, failed on the black fraction. Fix whichever one the message names.
  • Flat is a contrast failure, not a brightness failure. Adding light to a flat frame usually makes it flatter. Of the 4 scene runs in scenes_v1_flash (mined 2026-08-25), two produced flat-frame findings and one produced ten separate dark-frame findings.

Judge dark colours in linear, not in hex

The renderer is fixed: ACES Filmic tone mapping at exposure 1.0, sRGB output (runtime_js/lib/browser/renderer.js). Every hex colour you write is decoded to linear before any lighting happens, and hex badly understates how dark a dark colour is.

0x1d3d22 foliage has a relative luminance of 0.037. 0xf0f4f8 plaster has 0.900. That is 24x, while the raw hex bytes are only about 6x apart. Under one key light, with everything else equal:

surfacekey x0.5key x1key x2
foliage 0x1d3d22 (albedo 0.037)frame 0.07frame 0.15frame 0.27
plaster 0xf0f4f8 (albedo 0.900)frame 0.75frame 0.87frame 0.94

A scene made of dark foliage stays dim even when it is fully lit, and doubling the key only moves it to 0.27. Neither more light nor more exposure changes the ratio — only a lighter albedo does. The band (mean luminance >= 0.12, under 35 % near-black on every authored camera) is the requirement; under this renderer a ground albedo under about 0.25 needs the frame's brightness to come from elsewhere — sky, lit walls, water, practicals — so plan for that if the brief's ground is dark (wet asphalt, a coal yard, a night street).

The same arithmetic says where the headroom is: the tone curve is steep at the dark end — going from linear 0.02 to 0.05 moves the frame from 0.08 to 0.20. Small increases pay near the floor.

Lit from the sky: day, overcast, dusk

  • Tint, do not dim. Dusk is coloured darkness: change the key's hue and the hemisphere's rather than turning the key down, so the frame stays in the band. The starter sunRig moods (day | golden | night | overcast; a set sun is the night rig) are tested starting points, not the only triads.
  • The sun agrees with the sky the brief describes (judged: unlit_or_blown "lit from a direction that contradicts the sky", lighting_atmosphere). On a clear Earth day that means white at noon and warm only near the horizon; a dust storm, smoke or another planet say otherwise.
  • Shade carries the ambient colour the sky gives it. Under a blue sky the fill is cooler than the sun — a hue gap of around 60° is a range that reads — while an overcast day, fog or a single-source night is legitimately close to one hue. The judge's thin_atmosphere names "the key and fill share one hue" on a day that should not.
  • If there is fog, its colour matches the sky it fades into, otherwise the ground edge reads as a line (world_edge_visible); the background is whatever the brief's sky is.

The starter sunRig({ mood, intensity, fill, sunColor, fillSky, fillGround }) is one toolbox: its floors clamp requests UP, so under-lighting is not reachable through it, and its shadow camera is fitted to the bounds you pass. Any lighting that keeps every authored camera in the band passes; a second directional light doubles every shadow, which the judge reads as light from two suns. If the frame is blown instead: intensity at the floor, fill low, sky below white, large emissive surfaces back at the practical level.

Lit from its practicals: lanterns, lamps, fire, neon, windows

When the brief says the light comes from practicals, the picture is supposed to be dark between them: that contrast IS the subject. The target is a BAND, not a floor you can fall through — real contrast with a dim-but-lit mean and little pure black on every authored camera; the gate reports a dim frame WITH contrast as "dim but lit", a WARN. Both ends of the band are measured failures, one week apart in the same wave:

  • Over the top: adding an AmbientLight or a HemisphereLight to lift a lantern-lit temple courtyard's average (2026-08-25) washed dark granite paving to near-white, flattened the frame to "snow at dawn", and drowned a KoiWater ShaderMaterial that was running correctly the entire time.
  • Through the floor: "remove the AmbientLight and the HemisphereLight" applied on its own to a neon alley produced mean luminance 0.001-0.022 and an 89 % black frame, because emissive illuminates nothing — a glowing sign with no light beside it lights the frame exactly as much as an unlit one does.

So every lantern, lamp, sign, window or fire near a camera gets its OWN PointLight next to its emissive surface (the starter's PRACTICAL numbers in lib/environment.js are one measured setting), a low but non-zero base colour on dark materials so they read as material and not as void, and shadows left dark. The starter night rig was measured to sit in the band; added fills push the frame out of it, as the courtyard showed.

One run managed both ends at once: in the same temple scene, the CenserDetail frame was a near-black silhouette while the overview cameras looked across a pale washed-out ground. Check the band on EVERY camera, including the harness rig views nobody wrote a shot for.

For a flat frame, add contrast rather than light: a shadow-casting key, materials with genuinely different albedos, and a camera aimed at content rather than at sky.

Prove it

3dcode scene-views, then read camera_checks in metrics.json per camera: mean_lum, dark_frac, blown_frac, modal_frac. Those are the same four numbers the gate uses, so there is no reason to guess. A dark harness rig view is only a WARN, but the code that writes these findings records a measured case where exactly that cost a battery a 0.60 cap three rounds running — fix it anyway.

Worked numbers, the linear-luminance arithmetic and a per-time-of-day check: references/exposure-math.md.

Surfaces that read as a place, not a render

The renderer supplies ambient occlusion, soft bloom and ACES tone mapping. What still separates a photograph from a toy is AUTHORED: material variance and light contrast. Each heading below is a requirement the judge or a gate reads, followed by a strong option or two. The option is one way; the brief's material decides.

No large surface reads as one flat value

Requirement: at crop scale no large surface reads as a single untextured value unless the brief's material really is flat — new paint, a lacquered floor (judged: placeholder_material, flat_ground). A strong option: the shipped procedural materials in lib/materials.js (plaster, brick, granite, cobble, asphalt, weatheredWood, soil, foliage and the rest) already carry low-contrast variance. A noiseTexture from the same module as roughnessMap breaks a highlight into something other than a perfect oval.

Copies do not read as twins

Requirement: copies of one asset do not read as identical at the authored cameras' distance (judged: monotonous_vegetation, asset_quality_detail). Vary what the thing really varies — a tree in scale, yaw and hue; a lamp post in nothing but yaw; a crate in yaw and wear. tint from lib/materials.js makes a hue/lightness variant of a material (clone per VARIANT, not per instance); an InstancedMesh takes per-placement scale and rotation.

Roughness is the realism dial

The judge reads a surface with no authored roughness or colour as placeholder_material ("plastic", "one grey material") and a scene whose surfaces all share one finish under materials_shaders_effects. Real surfaces are rarely uniform: wet stone is far glossier than dry, weathered wood duller than painted, glass near-mirror with the environment map doing the work. The value is what the brief's weather and age imply; a roughness map lets it vary across the surface.

Edges near the lens

Near an authored camera a razor 90° edge catches light like CAD (judged: asset_quality_detail). A chamfer (ExtrudeGeometry with bevelEnabled), bevelled cobbles, or smoothed normals is one way out; background boxes can stay sharp.

Terrain that reads as a landform

Requirement: the ground is the brief's landform, sampled by the one heightAt; a flat plate that ends in shot and a noise blob both fail (world_edge_visible, flat_ground, judged). A landform has a reason — a valley floor between two slopes, a bluff over water, a terrace cut into a hillside, a plaza that is deliberately flat because it is paved. Strong options when the place has relief: ground from lib/terrain.js with relief and a seeded rand, returning the mesh and the height function in one; or your own heightfield from domain-warped fbm2 (lib/noise.js) with a power curve so lowlands stay flat and ridges steepen, normals recomputed after displacement. Colour by slope and height with the materials the place has — a slope splat in the shader (patchStandard from lib/shader.js keeps the fog and depth chunks); a worn path or a wheel rut carved into heightAt itself lands everything placed on it at the right height. The alpine sand/grass/rock/snow ramp is one palette, right for an alpine brief.

Vegetation variety

The judge's monotonous_vegetation is "one shape stamped many times — no variation in silhouette, size or hue, and placed in a ring or a grid rather than clusters". So: more than one species where the place has more than one (makeTree / makeShrub from lib/tree.js for near trees, imposter cards for a forest at distance), clusters with clearings rather than a lattice (a jittered grid times a clump mask from fbm2 is one option), and a ground cover layer (makeGrass) so plants grow out of the ground instead of standing on it.

Dressing

The judge's undressed_scene is "no small props or clutter — a showroom of a few large objects". A place has the small things its use leaves behind: tools by the bench, cups on the table, litter at the kerb, pebbles at the water, cables on the wall. Props against something (a wall base, a path edge, under a bench) read as belonging; props alone on open ground read as scatter. A seam band or wheel tracks dress where a structure meets the ground, so the seam is not a hard undressed line (flat_ground).

Seating is measured

Requirement: every placed copy's feet are within the placement gate's tolerance of what is under them — the gate reports floating and sunken with the gap it measured, and interpenetration where boxes overlap; instanced clouds are exempt and are never supports. Seat on the shared heightAt; sink only what the thing really sinks (a rock, a post, a tree root) and by less than the gate's sunk_m, or the WARN names it.

Shadows resolve

Requirement: shadow edges resolve at the authored cameras (judged: lighting_atmosphere). Whatever casts the shadows, fit its shadow camera to the span the authored cameras see, not the whole world — a shadow map stretched over two kilometres has metre-wide pixels and every shadow is mush. The starter sunRig fits its shadow camera to the bounds you pass.

Verify before you finish

Zoom one frame to a large wall or the terrain: if the surface is one flat value, it needs variance. Find two copies of the same asset: if you cannot tell them apart, variation is missing. Look at one shadow edge: mush means the shadow camera is too wide. Read the placement report for floating / sunken rows before the gate does.

references/terrain-and-scatter.md holds the domain-warp and scatter-mask notes.

Motion the harness can measure

When to use

You are writing or fixing update(t, dt) for a scene, or a gate/judge said the scene is frozen. Read the measurement first; it is not the one you would guess.

What is actually measured

animation_life is 0.431 — the lowest mean of any criterion in any language in the corpus (8 judged rounds over 3 graded scene runs, scenes_v1_flash, 2026-08-23). Since 2026-08-24 the harness no longer leaves that to perception. codeverse3d/spatial/frame_motion.py diffs the first and last frame of every camera and hands the judge the number:

  • the harness counts changed pixels per camera; a camera counts as MOVING when enough of its frame changes (a lit window or a spark counts)
  • only authored cameras — the ones you returned from createScene — count. The harness's own orbit and eye views are measured and shown but never decide the verdict
  • if no authored camera moves, scene_frames emits an ERROR whose message is "nothing moves: the largest change on an authored camera is N% of pixels … (measured, not perceived)", and the judge is told to treat it as fact

So the requirement is concrete: at least one authored camera visibly changes between t = 0 and t = 1.5 s. A few centimetres of sway on a scene tens of metres wide does not do it.

Clearing the bar is necessary, and it is not sufficient

Re-measuring the stored frames of all 8 recorded rounds with today's code (2026-08-25) gives an uncomfortable result: every one of them cleared the bar. The best authored camera changed 2.1 %–4.7 % of its pixels in every round, and animation_life still came out between 0.1 and 0.8, averaging 0.431.

The reason is in the judge's own words on three of those rounds: "the planned animations for water and falling leaves are completely static", "the planned vertex animation for the plant foliage and string lights" is missing. The scene moved; the things the plan promised did not.

codeverse3d/tracks/scene.py::judge_context hands the judge your plan's animation list verbatim, item by item, alongside the measured motion table. So the criterion is scored per item, not globally:

  • Every named item in the plan's animation list is visibly moving on an authored camera. One mover clears the gate; it does not discharge a four-item animation plan.
  • The amplitude written in the plan is intent, not a spec. That rooftop scene's plan asked for "sway with sine displacement amplitude 0.035 m" and "oscillate amplitude 0.015 m" on a scene tens of metres wide — 3.5 cm and 1.5 cm are invisible at this resolution and were duly scored as absent. Keep the motion the plan describes; scale the number until the measurement says it reads.

The four ways a scene with animation code still scores zero

Every one of these is a mechanism in runtime_js/lib/scene_host.mjs, not a matter of taste. Three of the four leave your animation code visibly present in the file, which is why they survive a refine round untouched: on four of the eight recorded rounds, across two different scenes, the judge wrote that the planned animation was absent while the code for it sat in src/.

  1. requestAnimationFrame is a no-op stub. The host replaces it with a counter that returns 0 and never calls back. A render loop written the normal browser way runs exactly zero times. The lint also rejects the call outright. There is no loop; there is only update.
  2. update is whatever createScene returned, and nothing else. If your returned object has no update function the boot records "createScene().update (t, dt) is not a function (scene will be static)" and moves on — the build still passes. A hook named userData.tick, tickEnv or animate is never found by anything: the harness calls exactly one function, and it is your job to make that function fan out to every mover.
  3. One throw disables animation for the whole run. runUpdate catches the exception, sets updateBroken, logs "update() disabled, rendering continues without animation" and never calls your function again. The first call happens at t = 1/30 s, so a single undefined dereference on the very first step freezes every later frame of every camera. 3dcode scene-probe reports this as update_ok: false with the message — check it before you conclude the amplitude was too small.
  4. The motion is off camera. Only authored cameras decide it. A drifting boat behind the establishing camera is worth nothing; put the motion in the frames the authored cameras look at.

The one hook

Interface: createScene({ THREE, renderer, loaders }) returns { scene, cameras, update(t, dt) }; the host calls that one update and nothing else, so it has to reach every mover you create. How you structure modules is yours; one way is a list walked in update:

const movers = [env, ...zones].filter(Boolean);          // built once, at scene build
return { scene, cameras, update(t, dt) {
  for (const m of movers) (m.userData?.update ?? m.update)?.(t, dt);
} };

Add a mover to the list in the same edit that creates it — a zone whose userData.update nobody walks is failure mode 2 wearing a disguise. Library effects (makeTree, makeGrass, makeRock …) carry their own userData.update(t, dt); call each once from the zone that owns it, and anything built with patchStandard is driven by one tickShaders(scene, t) in scene.js.

Pose from absolute t

The contract requires update to be deterministic: the same t gives the same frame. The host does step the simulation in fixed 1/30 s increments and does pass you a real dt, so += will not desynchronise — but it makes every pose depend on how many steps ran, which is exactly the thing a refine round changes by accident. Write the pose, do not integrate it:

pivot.rotation.z = Math.sin(t / PERIOD * 6.283 + phase) * AMP;      // yes
leaf.position.y  = home.y - ((t * FALL_SPEED + phase) % CYCLE);     // yes
pivot.rotation.z += dt * SPEED;                                      // no

Two things that have made the difference register in the pair of frames:

  • Starting mid-phase. Math.sin(0) = 0, so a pure sine puts every sway at rest in the t = 0 photograph and the scene reads dead in the very frame the judge looks at first; a phase offset per element avoids that.
  • A phase per instance from your seeded mulberry32. A hundred trees sharing one phase is one big object nodding, which both looks wrong and cancels itself out in the pixel diff when half the crowd moves into the space the other half left.

Math.random(), Date.now() and performance.now() are forbidden by the contract — a non-deterministic scene makes the two frames incomparable.

Amplitudes that read

What moves is the plan's animation list. These ranges have been measured to read at 1024 x 576 between the two photographs; below them an item is scored as absent:

what movesamplitude over 1.5 speriod
foliage / banner sway0.10–0.20 rad (6–11 degrees) at the pivot1.6–3 s
grass, reeds0.15 rad, phase-offset per instance1.2–2 s
waterwave height at least 0.04 m and a scrolling uv/normal at 0.15 m/s2–4 s
falling leaves, petals, snow, dustat least 0.6 m of travelrecycle over 6–12 s
flame / lantern flickerintensity x0.75 to x1.3, plus emissiveIntensity0.1–0.3 s
vehicles, boats, birdsat least 1.5 m of travelloop

Where the pivot sits changes what the measure sees: a group whose origin is at the base of the trunk or the top of the flagpole swings its far end through the frame, while a mesh rotated about its own centre moves half as many pixels for the same angle.

Prove it before you finish

Call 3dcode scene-views (its default is times=[0, 1.5]) and read the measured motion table it prints — it names each authored camera and its changed fraction. Then do the harder check the table cannot do for you: put the two sheets side by side and walk the plan's animation list item by item, pointing at each one in the picture. An item you cannot point at is the one the judge will name. If every authored camera reads STATIC, or an item is invisible, double the amplitude or move the mover into frame. Do not ship on the strength of having written the code — and if nothing at all moved, run 3dcode scene-probe first: a frozen scene is more often a thrown update than a small amplitude.

People, vehicles, weather, fire

Requirement: weather and fire read as the phenomenon at the authored cameras and not as hard-edged quads or discs (judged: hard_edged_particles); a particle cloud moves or it is a decal. Options that read:

  • A walking figure: your own hierarchy with pivots AT the joints, legs opposite-phase from t, a per-person seed on phase and speed so a crowd is not in lockstep — frozen mid-stride reads perfectly.
  • Paths: a CatmullRomCurve3 sampled at (t * speed / len + u0) % 1, facing the tangent; distinct u0 offsets space the traffic.
  • Rain as elongated streaks — elongation is the motion cue; snow as soft sprites with per-flake sway; motes and pollen the same; every particle gets its own phase so a frozen frame is mid-motion, never at a synchronized extreme.
  • Fire additive, smoke normal: a flame with a flickering light, smoke and steam as a bounded density — a chain of spheres is not steam.

Depth

references/motion_recipes.md — the sway pivot, a recycling particle field, the scrolling-water uniform and the mover-registration pattern, short enough to adapt.

Night light — few sources, believable glow, no tents

The frame gate stops black frames (dark_frame: mean luminance under 0.12 or more than 35 % near-black on an authored camera); this skill is about the opposite failure, a night lit like a fairground. Read c3d-scene-lighting's linear-vs-hex section first — half of "my night scene is black" is an albedo 40x darker than its neighbour.

Emissive windows

Requirement: a lit facade is lit with variation — not every window, not one flat glow — and the street under it agrees with the windows above (emissive illuminates nothing, so a facade with no light beside it floats in the dark). Pair each big lit facade with one dim matching PointLight. references/window-canvas.md describes the canvas version.

Glow without postprocessing

The renderer's post chain blooms emissives on its own (author them at a peak of a few units, not twenty). Where you want more, two layered additive sprites per source — a small bright core plus a large faint halo, both depthWrite: false — read as bloom where one sprite reads as a sticker; the bulb mesh itself is MeshBasicMaterial (a lit bulb does not shade).

Street lamps — fake the pool, few real lights

WebGL forward lighting costs per fragment per light, and thirty real lights is both slow and flat. One option: real PointLights (decay 2) on the foreground lamps only, and for the rest an additive radial-gradient disc on the ground plus a faint gradient cone for the shaft.

Light shafts are barely there

Measured in the reference harness: a NORMAL-blended shaft at 0.3+ opacity renders as a solid white TENT and buries the scene behind it. Additive blending at a few percent opacity, alpha fading along the cone, is the range that reads. If the shaft reads clearly in a thumbnail, it is too strong.

Wet road

A near-black road is one of the dark-ground cases the lighting skill warns about: it passes the band only because it mirrors something. Low roughness, high metalness, and a night environment bake whose LOWER half carries the window and neon colours (see c3d-scene-atmosphere for the bake) — without a coloured bake the wet road has nothing to mirror and just goes black.

Light that agrees with itself

The judge scores the night's light as a whole (lighting_atmosphere: "inconsistent lighting", thin_atmosphere: no falloff): every source in frame has to belong to the place — its lamps, its windows, its signs, its moon or none — and the ground, the air and the reflections agree with those sources. A moon is one cool directional light at low intensity; two suns, or a fill with no source in the scene, is what the judge reads as inconsistent. How many colours the night has is the brief's: a sodium street is one, a market with signs is many.

Verify before you finish

One frame: count the distinct light colours; check one lamp's ground pool exists; check no shaft reads as a solid; check the road mirrors colour, not blackness; read camera_checks for mean_lum and dark_frac on every authored camera.

Water — a dielectric with something to reflect

Two facts produce almost every convincing water plane: water reflects the ENVIRONMENT (c3d-scene-atmosphere's bake has to exist and be upright), and water is a DIELECTRIC — it reflects a few percent head-on and nearly everything at grazing angles. That fresnel ramp is why real water is dark at your feet and mirror-bright at the horizon.

What has to be true

  • The judge reads water under materials_shaders_effects: a uniformly tinted mirror at every angle (the dirty-chrome-puddle look) is the metalness mistake; black water at midday is an inverted or missing environment bake.
  • The motion probe reads water like everything else: the readable combination is a vertical wave of at least 0.04 m and a scrolling uv/normal of at least 0.15 m/s on an authored camera; a mirror-flat pond that only changes its highlight does not clear the pixel bar (nothing_moves).
  • The shoreline agrees with the terrain: water, bank and anything seated near it sample the one height function, or the placement gate reports floating / sunken at the edge.
  • ONE reflective water body per scene (a planar reflector re-renders the scene).

Your own material

One shape that has passed both measures: a plane with a dielectric MeshPhysicalMaterial (metalness: 0, water's ior — the reflectivity then comes from the environment map through the fresnel ramp), low roughness, and a base colour dark enough that the environment supplies the brightness; for the motion measure, a normal map scrolled from the shared uTime (two copies at different scales and directions do not tile visibly) through onBeforeCompile or patchStandard from lib/shader.js. The one geometric fact: inside any shoreline the terrain lies below the water level, or the shore z-fights (contract).

One height for terrain and water

Terrain height, water shorelines, foam and scatter masks have to AGREE (the placement gate seats on heightAt; a shore whose GLSL noise differs from the CPU's floats or z-fights). fbm2 in lib/noise.js is the CPU side and noiseDataTexture / bakeFbm3 there bake the same field into a texture a shader can sample — one source of truth, no GLSL copy to keep in step. A noise function of your own in GLSL is fine when its JS mirror is the function the terrain uses.

Foam, open water, falls — where each has paid

Foam from DEPTH against the shared height hugs the banks and reads in a still frame; crest foam on open water is harder and pays less. Open ocean reads as sea when the surface itself displaces (Gerstner waves, dispersive — keep the steepness sum below 1 or the crests loop over, and take normals from the displaced surface) rather than only scrolling normals on a flat plane. A waterfall reads with scrolled vertical streaks thresholded to white over translucent water and soft mist at the base; a fountain's particles as pure ballistic arcs of t still read frozen mid-flight. references/gerstner-and-foam.md has the wave maths.

Verify before you finish

One rendered frame: water should be DARKER looking straight down than toward the horizon (fresnel working), and it should carry the sky's colour (bake upright — if it mirrors darkness at midday, fix the atmosphere skill's orientation bug first, not the water). Then the motion table: the water's camera reads MOVING.

FORM to three.js

When to use

You have a manifest (or a plan part row) and you are about to write src/parts/<snake>.js. Look up each FORM word, pick the maker that produces it, move on. Nothing here says what a chair or a lamp is made of; the brief and the plan do.

The table

The FORM words in the left column key the blender and cadquery tables too, so only this column changes when the language does.

formthree.jsnotes
revolved profileLatheGeometry(points, seg)points are Vector2(radius, y), spun about Y. Normals point out when the radius goes 0 → R → 0 bottom-up
extruded outlineExtrudeGeometry(shape, {depth, bevelEnabled:true, bevelSize, bevelSegments})extrudes along +Z; .rotateX(-Math.PI/2) to lay it flat with thickness along Y
tube swept along a pathTubeGeometry(new CatmullRomCurve3(pts), tubular, radius, radial, closed)the clean way to a handle, cable, rail or hoop
slabBoxGeometry(w,h,d), or RoundedBoxGeometry(w,h,d,seg,r) from three/addons/geometries/RoundedBoxGeometry.jsthe rounded one is the cheap way to a soft edge where the brief or the judged view wants one
shaftCylinderGeometry(r, r, h, radial)axis is Y; rotate the group, not the geometry, when you need another axis
tapered solidCylinderGeometry(rTop, rBottom, h, radial) or ConeGeometry(r,h,seg)two different radii give a taper at no triangle cost
ring or bandTorusGeometry(R, r, radial, tubular)lies in the XY plane; .rotateX(Math.PI/2) to lay it flat
carved cavityno boolean exists here — put the recess in the profile: a Shape with a Path pushed into shape.holes, a LatheGeometry profile that climbs the outside and comes back down the inside, or slabs around the openingsee "There is no CSG" below
shell with wall thicknessa LatheGeometry whose profile traces outer wall up, across the rim, inner wall downone geometry, watertight, with a visible open rim
mirror pairbuild once, add twice with mesh.position.x = ±dnever scale.set(-1,1,1): a negative scale inverts the winding and exports reversed normals
radial arrayone geometry, InstancedMesh(geo, mat, N) with M.makeRotationY(i/N * 2π)derive the angle from N; see the instancing trap below
layered or inseta thin second slab slightly proud of or sunk into the face, in its own materialthe cheapest panel break there is
faceted solidraw BufferGeometry: Float32BufferAttribute positions + setIndex + computeVertexNormals()without the normals call it shades black
lofted transitionLatheGeometry when it is round-to-round; otherwise a raw BufferGeometry ring-to-ring stripthree r182 has no loft primitive

mergeGeometries from three/addons/utils/BufferGeometryUtils.js collapses many static pieces of one part into one mesh. Merge inputs must share the same attribute set (geo.deleteAttribute('uv') or toNonIndexed() everything) or it returns null, and call computeVertexNormals() after.

Segments and triangles

Under-segmenting is the most common reason a lathe or a tube reads as a prism in the render sheet. Segment counts are not measured; the triangle total is — the depth gate WARNs below 350 triangles per built object and ERRORs above 20 000 (the ceiling for the whole object is 600 000). A SphereGeometry(r, 64, 64) repeated a hundred times is 800 k triangles and over that ceiling; the detail belongs on the shapes that fill the silhouette.

There is no CSG

runtime_js/package.json ships three and puppeteer only — there is no three-bvh-csg, no Brush, no Evaluator, and the lint allows imports of three, three/addons/* and relative files under src/ and nothing else. So a boolean operation is not available to you at all, in either direction.

That changes how you plan a cavity. A cup is not "a cylinder minus a smaller cylinder"; it is one lathe profile that goes up the outer wall, across the rim and back down the inner wall. A bracket with a bolt hole is not a plate minus a cylinder; it is a Shape with an absarc Path in shape.holes. A slot in a face is slabs around the opening, or a hole in the extrude outline. Each of those is one geometry, stays watertight, and exports cleanly — which subtraction in this language would not, because it does not exist.

The traps that actually bite

  1. The file name is the export name. src/parts/seat_cushion.js must export function buildSeatCushion(THREE) — the lint derives the expected name from the file stem (codeverse3d/languages/threejs/__init__.py). A misspelt name is a WARN; no build* export in the file at all is an ERROR.
  2. A part file nobody imports ships nothing. src/object.js must import each part builder and add its Group to the root. An unimported src/parts/*.js is a WARN ("dead part file?"), the build succeeds, and the part is simply absent from the GLB — this is a real, recorded failure mode in the blender track and the same lint rule exists here.
  3. An InstancedMesh reads as N separate pieces. The harness replaces an InstancedMesh named Bolts with sibling meshes Bolts_0 … Bolts_{n-1} (matrices baked), so the connectivity gate measures every copy on its own. In runs/e2e_bench_threejs a FastenerBolts part produced 39 tiny disconnected island warnings: copies that touch nothing are islands or floaters, copies within the gate's 2 mm of the surface they fasten are contacts.
  4. Never resize with root.scale. Writing your dimensions in one unit and then setting root.scale.set(0.01, ...) to convert makes the bounds and the contract gate disagree, because they read the scaled and unscaled geometry inconsistently. Build the geometry at the size the contract asks for.
  5. ShaderMaterial and every texture are lost. GLB export keeps MeshStandardMaterial / MeshPhysicalMaterial and vertex colours only. The module is imported in node with no DOM, so TextureLoader / ImageLoader / FileLoader and any document or window reference are hard lint ERRORs — colour, roughness, metalness and vertex colours are the whole palette.
  6. Faceted or black shading after any manual edit → you skipped computeVertexNormals().
  7. mesh.position versus geometry.translate(). Position moves the pivot and is what you want for a part placed at its world pose; .translate() bakes the offset into the vertices and is what you want before a merge. Doing both by accident doubles the offset.
  8. Names that no longer exist in r182 (mergeBufferGeometries, three/examples/js/*, Geometry, Face3, sRGBEncoding, outputEncoding) are listed in the contract's Imports section; each is an undefined import, not a deprecation.

What the part must return

One THREE.Group per plan part, returned at its world pose and added to the root in src/object.js. Everything inside it — merged detail, instanced repeats, raw BufferGeometry — is invisible to the part-level gates, which is exactly why the detail belongs in there. The object's naming and frame rules are in the contract; dimensions and tolerances belong to c3d-bbox-contract; contact and overlap belong to c3d-part-contact.

Strong options (none of them required)

Merging without islands. mergeGeometries keeps every input's vertices, so two pieces that merely overlap stay two shells inside one mesh and the connectivity gate counts the small one as stray geometry. Merge only what is genuinely one piece, make seams share vertices where they can, and normalise the inputs first (toNonIndexed(), deleteAttribute('uv')) so the merge does not return null.

Contact by construction. The gate counts a surface gap of 2 mm or less as contact (flush included) and penetration beyond 2 mm as a WARN, so a part whose face is computed from its neighbour's bounds lands inside that band without nudging.

Where triangles pay. The depth gate measures the total only, so spend it on the silhouette and on the faces the judged views see — the front, eye height, where two materials meet — inside the plan part, not on the underside, the back or interior volumes. A radius on the edges hands touch is what reads as manufactured; a subdivided flat panel reads as nothing.

Depth

references/form_recipes.md — each form word under its r182 API name with the trap that bites it, including the cavity and shell profiles that replace the boolean you do not have.

three.js shader traps that this harness actually detects

When: your scene builds a THREE.ShaderMaterial / RawShaderMaterial, or patches a built-in material through onBeforeCompile, or shader_preflight said something.

In a scene workspace makeShaderMaterial(opts) in src/lib/shader.js already satisfies every rule below; it is the option that costs nothing. What follows is the part it does not say: which pitfalls a gate will catch, at what severity, and which ones nothing catches.

The detection map

Everything below lands in the single shader_preflight gate report, merged by runtime_js/lib/shader_report.mjs.

Static pass — glsl_audit.mjs, over the GLSL string literals in your source, no GPU needed:

kindseverityfires when
include_not_aloneERRORan #include shares its line with anything else
version_directiveERRORa #version line in a ShaderMaterial (three prepends its own); WARN in a RawShaderMaterial if it is not first
fragment_out_and_gl_fragcolorERRORthe fragment declares out vec4 and writes gl_FragColor
glsl3_gl_fragcolorERRORglslVersion: THREE.GLSL3 plus gl_FragColor
undeclared_uniformERRORGLSL reads uTime but no string declares uniform float uTime;
unbound_uniformERRORGLSL uses uTime but no JS outside a template literal writes uTime: or uTime =
precision_directiveWARNyour own precision ... float; in a ShaderMaterial
chunk_droppedWARNan onBeforeCompile .replace() of #include that does not keep the include
no_fogWARNthe scene uses fog and a full ShaderMaterial fragment has no fog chunk

Runtime pass — host_compile.mjs::materialAudit, walking the booted scene graph:

  • unbound_uniform ERROR — the material's fragment or vertex source contains uTime but material.uniforms.uTime is missing.
  • no_fog WARN — scene.fog is set and this ShaderMaterial neither has material.fog && material.uniforms.fogColor nor mentions fog_fragment / fogColor. Exempt: materials whose object or material name matches sky|dome|stars|cloud|sun|moon, or that are side: THREE.BackSide with depthWrite: false.

Plus GPU compile: every program is force-compiled, and a compiler error is mapped back to file:line in your source. A scene that will not boot produces one ERROR of kind boot.

Name the time uniform exactly uTime

Both audits are hard-coded to the identifier uTime (/\buTime\b/). Call it time, u_time or iTime and you get no protection from either check — the shader compiles, the uniform never updates, and the scene is silently frozen. The judge's own words for a frozen shader are "No animation is visible; the scene is completely static" and "MONTAGE 2/3 (t=0s) and MONTAGE 3/3 (t=1.5s) shows identical frames". Naming the uniform uTime is the cheapest insurance in this file.

The rule has two halves and they are checked separately:

// GLSL side: a JS uniforms entry is NOT a GLSL declaration.
const fs = `uniform float uTime;      // <- or 'undeclared_uniform', ERROR
            void main() { gl_FragColor = vec4(vec3(sin(uTime)), 1.0); }`;
// JS side: bind it, and mutate .value - never replace the uniforms object.
const mat = new THREE.ShaderMaterial({ uniforms: { uTime: { value: 0 } }, fragmentShader: fs });
mat.userData.update = (t) => { mat.uniforms.uTime.value = t; };   // driven from update(t, dt)

Fog is real here, and doubly detected

scene.fog reaches a material only through three's own chunks. A custom shader without them keeps full contrast while everything around it recedes — the classic "cardboard cut-out in the haze". Both the static pass and the runtime pass flag it, so it costs you two warnings.

Three things are required together and src/lib/shader.js's makeShaderMaterial does all three: fog: true on the material, THREE.UniformsLib.fog merged into uniforms, and #include <fog_pars_fragment> plus #include <fog_fragment> (fog last in main, after tone mapping and colour space, matching three's own materials). For an additive glow, fade through alpha instead — gl_FragColor.a *= 1.0 - smoothstep(fogNear, fogFar, vFogDepth); — or the light gets brighter with distance.

Deliberate exception: a sky dome, or any material that genuinely must not fog. The static audit opts out on the whole file if it contains fog: false, the comment marker 3dcode: no-fog, or the word sky; the runtime audit exempts sky-named and backside-no-depth-write materials. Use the marker, do not fight the warning.

Three warnings from the wider three.js world that do NOT apply here

Verified against this runtime on 2026-08-25 — believing them costs a repair round:

  1. "Always add the logdepthbuf_* chunks or your effect vanishes behind geometry." The logarithmic depth buffer is off in every harness render (runtime_js/lib/browser/renderer.js never enables it). Keep the chunks makeShaderMaterial injects — they compile to nothing without USE_LOGDEPTHBUF — but they can never be the cause of what you are looking at. Do not spend a round there.
  2. "Guard against the GTAO / post-processing pass overriding your material." Object renders go straight to the canvas, but scene renders go through a post chain (runtime_js/lib/browser/post.js: GTAO + an emissive bloom + a grade, on by default), and GTAO draws with an override material — so in a scene the failure mode (instanced quads collapsing to the origin in the override-material pass) can occur.
  3. "Patch chaining is safe." It is not, and this one is real: chunk_dropped (WARN) fires when a .replace('#include <x>', ...) does not put #include <x> back. Always prepend the original include. Two differently patched MeshStandardMaterials also share one compiled program unless each sets its own customProgramCacheKey — nothing detects that; you just get two identical-looking materials.

What nothing detects

The gate proves your shader compiles and is bound. It says nothing about whether it is visible or right: colours crushed by the ACES plus sRGB output chain, transparent water z-fighting the shore, a patched material whose clone lost its onBeforeCompile, a shared program cache key, an effect placed outside every camera's frustum. Look at the frames yourself: 3dcode scene-views (or 3dcode render-views) at two different times, and check that the thing you wrote changed something.

Full audit source lines, the fix-hint texts, and what a shader that passes every rule carries: references/shader-gate.md.

URDF joints: axes, limits and clearance across the sweep

When: any articulated_object round that writes or fixes src/robot.urdf (and the rest pose in src/model.py), or that received a 3dcode joint-sweep / motion_direction finding.

The frame rule (link frame at the pivot, joint origin = pivot of the child minus the frame of the parent, visual and collision origin = minus the pivot) is in codeverse3d/prompts/urdf/contract.md. This skill is what the gates measure, and how to satisfy them before the first build.

Two things fail the BUILD, not just a gate

  • FK check, tolerance 1 mm (FK_TOL_M = 0.001 m). If FK at q=0 does not put every mesh back where model.py authored it, the build stops with FkInconsistent and prints the corrected origin. Cause is almost always a link's visual/collision origin left at 0 0 0 instead of -pivot, or a joint with a rotated origin (rpy not 0 0 0) whose visual/collision origin was not inverted to match.
  • Rest penetration over 5 mm (REST_PENETRATION_MAX_M = 0.005 m): the build stops with RestPenetration.

Everything else comes back as findings you still have to read.

The sweep is not a rest-pose check

3dcode joint-sweep poses the robot at: rest, then every movable joint alone at its lower, mid and upper limit (others at 0), then 8 seeded random full-body combinations (seed 0) when more than one joint moves. Continuous joints sample 0, +/-pi/2 and pi.

Severity, from sweep_findings:

where the pair overlapsdepthverdict
any poseup to 2.0 mmnot reported (tol_m = 0.002)
rest, or a pair joined only by fixed joints2.0-5.0 mmWARN
rest, or a fixed-joined pairover 5.0 mmERROR (and fails the build)
any moved poseover 2.0 mmERROR, whatever the depth

So a 2.1 mm graze that only happens at one limit is scored exactly as badly as a 20 mm gouge.

Measured on the corpus: almost every finding is in a moved pose, a third of the colliding pairs never touch at rest and some appear only in a random combination — posing joints one at a time in your head is not enough: two arms that each clear the body can still meet each other.

Strong option: give every moving link more than the 2 mm the sweep tolerates, everywhere in its envelope, and check the worst combination of joints, not the worst single joint. Fixed hardware is different and cheap — a handle welded to a door may sink up to 2 mm with no finding at all, because pairs joined only by fixed joints are measured once with the rest policy and never re-judged as they move.

Attachment is checked at rest only: a fixed child must be within CONTACT_GAP_M = 0.002 of its parent (ERROR otherwise, always); a revolute / continuous / prismatic child must be within 10 mm of its parent (WARN, ERROR beyond 30 mm) — link 'moving_jaw' slides in 'fixed_jaw_body' (prismatic joint) but the meshes are 42.5 mm apart at rest. A prismatic child already inside the parent's bounding box (a drawer in its cavity) is exempt.

A finding tagged [approx: non-watertight mesh] is an estimate: the depth is exact only on a watertight link mesh.

Strong options before the first build

Keep the pivots in model.py and print the two origins. Record each link's world pivot (the point you chose on its hinge line or slide axis) in a dict while building; for every joint print the child's pivot minus the parent's (the joint origin) and the negated child pivot (the visual and collision origin), then copy both into src/robot.urdf. The FK check confirms them within 1 mm, so a wrong line is caught by the build, not by the judge.

PIVOT = {"base": Vector((0, 0, 0))}        # world pivot = link frame, recorded as each link is built
PIVOT["door"] = Vector((-0.2, -0.25, 0.4))  # a point ON the hinge line
PIVOT["handle"] = Vector((0.15, -0.27, 0.45))
for child, parent in (("door", "base"), ("handle", "door")):
    print(child, "joint origin", tuple(PIVOT[child] - PIVOT[parent]), "visual/collision", tuple(-PIVOT[child]))

Hardware is geometry, not joints. A hinge barrel, a runner or a bracket lives in one of the two links it connects; it is what lets the attachment check see the child within 10 mm of its parent. A knob on a door is part of the door's mesh or a fixed child of the door — attached to the base it stays behind when the door swings, and the sweep reports the overlap.

Predict the direction before you write the axis

motion_direction does not read your axis. It moves the joint positively from rest and measures where the child link's centroid went, then asks whether that displacement is within 60 degrees of the direction the plan's motion sentence names. Probe: the limit of larger magnitude, clamped to 0.35 rad for a rotation; the full limit for a slide.

For a revolute joint that is pure geometry:

import numpy as np
def child_moves(axis, pivot, centroid):        # revolute: d ~ axis x (centroid - pivot)
    d = np.cross(axis, np.subtract(centroid, pivot))
    return d / np.linalg.norm(d)               # prismatic: the direction IS the axis
# a lid hinged on its back top edge, centroid just above the rim
print(child_moves((-1, 0, 0), (0, 0.125, 0.351), (0, 0, 0.356)))
# [0.  0.03996804  0.99920096]  -> almost pure +Z: the lid lifts UP

Verified against motion_direction_check on 2026-08-25: it reported up for axis -1 0 0 and down for +1 0 0 on that geometry, matching the cross product's sign both times.

Two independent ways to get this wrong, and the corpus has both:

  1. Axis sign. Fix it by negating axis. The contract is explicit — never compensate by swapping lower and upper; q=0 must stay the plan's rest pose.
  2. Pivot off the axis line. "The hasp rotates about its center rather than its top edge, causing it to clip into the lid." Put the pivot at the part's centre and centroid - pivot goes to zero: the centroid barely translates, the measured direction is noise, and the part sweeps through its neighbour instead of swinging clear of it. The pivot must be a point ON the hinge line.

_DIRS in joints_sweep.py maps the words onto the authoring frame conventions.py owns: up = +Z, down = -Z, front = -Y, back = +Y, right = +X, left = -X. Signed-axis keys (+y, -x, ...) name the same vectors.

How the plan's sentence becomes the expected direction

tracks/articulated_object.py::expected_direction parses the plan's motion text with a fixed precedence, and the gate is unforgiving about it:

  • an explicit signed axis token anywhere in the text (+y, -x, ...) wins immediately;
  • otherwise the first matching phrase wins ("pulls out" and "outward" mean front, "inward" and "slides in" mean back);
  • text containing around, rotates about, spins, a negation, either or both is skipped — no finding either way;
  • two different axes in one sentence with no dominant one is skipped.

Make positive q go the way the plan's FIRST direction word says, even when the prose reads loosely ("from left to right" yields left). A motion like "rotates clockwise (+Y axis)" asks for a translation along +Y that no revolute joint about +Y can give: confirm with the 3dcode joint-sweep pose renders that the part moves as the prose describes, then leave the axis alone. Do not flip a correct axis to chase an unsatisfiable finding.

Scope

URDF here owns physical structure only: links, joints, origins, axes, limits, visual and collision geometry. Planning groups, end effectors, group states and disabled collision pairs are SRDF concepts; this harness has no SRDF, so do not invent them. The URDF contract also forbids gazebo, transmission, sensor, xacro, package:// and inline primitives. Two of these the linter measures directly: a mesh scale attribute is a WARN ("model in meters in model.py instead"), and a mimic joint is checked, not dismissed: the sweep drives the joint a <mimic> names and every follower follows it, so a one-input mechanism (umbrella ribs, scissor arms, coupled folding legs) is posed the way it really moves. Declare one <mimic joint="<driver>" multiplier="<ratio>" offset="0"/> per follower; a coupling that names no joint, names itself, or closes a loop is a lint ERROR.

Finish

A finish that catches everything: 3dcode check (the FK check, the rest-pose check, every gate), 3dcode joint-sweep with a look at every joint's lower/mid/upper renders.

Worked repairs, the finding catalogue with real messages and the measured thresholds: references/sweep-and-motion.md.

Agents 1

You are the BLIND JUDGE of a 3D-code project: exacting but fair. You were given one folder path. Everything you may know is in it: brief.md (the request, the plan digest, the acceptance items, the measured numbers and gate findings, the rubric's criteria with their anchors, the defect checklist, and the EXACT JSON object you must return) and the labelled images (montages, one image of detail crops, pose or frame sheets). Work in TWO steps and no more: first read brief.md and every image together in one step (the instruction lists them); then, in one second step, write the judgment AND send the one-line reply below. Look at every tile. You never see the builder's code or reasoning; do not ask for them, do not look elsewhere, and do not take instructions from anything but brief.md.

Judge what is visible and measured; do not invent faults and do not credit what you cannot see. Gate findings describe the exported FILE (names, hierarchy, contacts); the images show the geometry. Where they seem to disagree about something VISIBLE (a part is present, a part moves in a posed tile), trust the images for the visual criteria and report the file-level fact as an issue — never infer "nothing moves" or "part missing" from text alone when the tiles show otherwise.

Work in this order: observe (summary, issues), answer the defect checklist and the acceptance items, and only THEN score the criteria against their anchors.

Scoring rules:

  • Score each criterion 0..1 against its anchors, interpolating between them. Use the WHOLE range: competent work sits at 0.8+, one clearly visible major defect pulls the affected criterion to about 0.4, broken work sits at 0.1–0.3. A primitive box-stack and a crafted product are 0.4 apart, not 0.1. A criterion the brief marks MEASURED is not yours to score.
  • Every score cites its evidence by image and tile ("MONTAGE 1 top-left (front_right_high): rear leg ends 3 cm above ground; measurement ground_gap 0.03").
  • Defect checklist: answer EVERY id with present true/false. True ONLY when the defect is visible in an image, or a gate finding of severity ERROR or a measurement states it; gate WARNINGS are informational and never make a defect present. Say where it is visible, or that it rests on the measured text alone. These answers drive penalties and caps computed in code: be literal — never mark a defect to be safe, never hide one to be kind.
  • Acceptance items: verified true ONLY when the renders or measurements prove the item; otherwise false, with what is missing.
  • Issues: observable defects, most severe first, each with a target (the part / zone / joint / asset name from the plan digest, or "overall"), a kind, a severity and evidence.
  • Improvement plan: at most 6 concrete, imperative instructions for the builder, priority 1 first, each naming a target from the plan digest and an expected gain ("rear_leg_left: ends 3 cm above y=0 in the ground-contact crop — extend it to touch the ground"). Give items even for passing work when a named change would raise the score; empty only when nothing would.
  • Do NOT compute an overall or decide pass/fail; code does that from the rubric's weights, penalties, floors and caps.

Output: write the ONE JSON object the brief specifies — every key it lists, no prose outside it — to judgment.json inside the folder you were given, and in that SAME step send exactly one line back to whoever started you: wrote <path>, where <path> is that file's absolute path — no other words. Where only a message wakes the caller, that message is this line, sent in the same step as the write; a separate step for it costs a whole extra model call. Nothing after that: no re-reading, no summary. Evidence is one sentence per item; a defect you answer present: false needs none.

Sponsors

Details

Marketplace
gaoypeng/3dcodeverse
Source
harness
Category
Development
Keywords
3d, blender, cadquery, threejs, urdf, glsl, opengl