Skip to content

Official Codebase of 3DCodeVerse

Python

docs: D63–D66 record the hero-path measurements; INTERFACES/RUNBOOK/ARCHITECTURE match the code; a verified cookbook recipe for a hero's keyframed motion

gaoypeng0241d28924c4
diff --git a/harness/codeverse/prompts/blender/cookbook.md b/harness/codeverse/prompts/blender/cookbook.md
index ee686776..21f1389a 100644
--- a/harness/codeverse/prompts/blender/cookbook.md
+++ b/harness/codeverse/prompts/blender/cookbook.md
@@ -864,6 +864,48 @@ Decomposition recipe (any object): 1 main mass → 2–6 secondary masses that T
attachments (handles, feet, trim) that overlap ≥ 2 mm → detail pass (bevels, seams,
fasteners). Name every mass as the plan does; instances by `linked_copy`.
+## Keyframed motion for a scene hero (the harness exports it as a glTF clip)
+
+A scene hero may carry ONE 2 s loop (24 fps, frames 1–49, ends where it starts); the
+scene plays it by itself. Keyframe the moving object's OWN transform, and build that
+object's mesh AROUND ITS PIVOT so the rotation happens where the hinge is — an object whose
+origin sits at its centre swings about its centre, and the sails fly off the hub.
+
+```python
+import bpy, bmesh, math
+from mathutils import Matrix
+
+def build_sail_rotor() -> bpy.types.Object:
+ """Four lattice sails on a hub; the mesh is centred on the hub axis so rotation is about it."""
+ bm = bmesh.new()
+ for i in range(4): # sails built AROUND (0, 0, 0)
+ a = i * math.pi / 2
+ sail = bmesh.new()
+ bmesh.ops.create_cube(sail, size=1.0)
+ sail.transform(Matrix.Diagonal((11.0, 0.15, 1.6, 1.0))) # a lattice sail, 11 m long
+ sail.transform(Matrix.Translation((5.5, 0.0, 0.0))) # out from the hub
+ sail.transform(Matrix.Rotation(a, 4, "Y")) # around the hub axis
+ me_s = bpy.data.meshes.new("_sail"); sail.to_mesh(me_s); sail.free()
+ bm.from_mesh(me_s); bpy.data.meshes.remove(me_s)
+ me = bpy.data.meshes.new("SailRotor"); bm.to_mesh(me); bm.free()
+ rotor = bpy.data.objects.new("SailRotor", me)
+ rotor.location = (0.0, -3.2, 18.0) # the HUB's world position = the pivot
+ bpy.context.scene.collection.objects.link(rotor)
+ sc = bpy.context.scene; sc.frame_start, sc.frame_end = 1, 49
+ for frame, ang in ((1, 0.0), (25, math.pi / 4), (49, math.pi / 2)): # a quarter turn: 4 sails loop seamlessly
+ rotor.rotation_euler = (0.0, ang, 0.0) # about the hub axis (-Y is the front: the axis is Y here)
+ rotor.keyframe_insert("rotation_euler", index=1, frame=frame)
+ return rotor
+```
+
+* Keep the moving part a normal named MESH object (no Empty pivots — an Empty is not a
+ part and the census counts it as junk); parent nothing to it.
+* A loop of a quarter turn for 4-fold sails, a half turn for 2-fold, a full turn for a
+ wheel; a swing goes −a → +a → −a. Amplitude must read at scene distance (≥ 0.15 rad or
+ ≥ 0.05 m); the scene samples t = 0 and t = 1.5 s.
+* Linear interpolation for a wheel (`kp.interpolation = 'LINEAR'` on the fcurve's
+ keyframe points) so it does not ease at the loop seam.
+
## Pitfalls (symptom → cause → fix)
1. **`bm.verts[i]` raises "outdated internal index table"** → call
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index fd4d3126..a31b5f20 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -421,7 +421,7 @@ in-loop option with `n_samples ≥ 2` for decisions.
```
plan (structured output, one re-ask) → skeleton (buildable placeholder) → materialise workspace
-[scene only] assets (parallel; blender_glb assets get a sub-workspace + asset_v1 judge + one fix pass; a degraded asset verdict leaves
+[scene only] assets (parallel; both kinds climb one ladder — single-shot → check → one repair → agent; blender_glb heroes get a sub-workspace with the static planner's parts + asset_v1 judge + one re-judged fix pass, undone when worse; a degraded asset verdict leaves
score None / judged False, emits asset.judge_degraded and skips the fix pass)
→ env → zones (parallel) → assemble (deterministic scene.js)
round 0 "baseline": generate → build_with_repair → measure → gates → render → post-render gates → judge
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index b5a575fc..a8a94ffb 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -982,6 +982,62 @@ written) that were accepted because the code works that way and the tests pin it
CONTAINING mesh's own surface, not from anything at all); the rule does not ship on this
evidence.
+* **D63 A scene hero climbs the same ladder as a module, and its GLB is checked like one
+ (2026-09-07).** Measured over the 18 `blender_glb` heroes in the recorded batteries
+ (2026-08-25 → 09-05): 15 of 19 first agent sessions were killed at the 420 s asset clip
+ and booked at $0 (a killed gemini-cli reports no usage); 12 of 18 GLBs were ONE joined
+ mesh with vertex-painted colour, because `asset_plan()` gave the sub-run a one-part plan
+ and the Blender contract demands one object per plan part; every fix prompt read "Style
+ of the whole scene: (none)" because the sub-spec's prompt IS the asset sheet; nothing
+ measured the GLB (a module gets sink / tri-budget / size findings and one repair); repair
+ sessions took the 1 800 s agent default (a 25-minute scene could spend 70 minutes on one
+ hero); the fix pass was never re-judged. Live on 6768aae the same day, 3 of 4 heroes in
+ an asset A/B and 3 of 4 in a scene A/B produced nothing before the clip. Decision: ONE
+ ladder for both asset kinds (`scene_assets._ladder`: single-shot → deterministic check →
+ one feedback repair → agent session), the static-object planner's part list for the hero
+ (one call; the sheet is the fallback), `_soft_findings` from one measurement of the GLB,
+ `build_with_repair(timeout_s=)` clipping every repair to the asset window, a re-judged
+ fix that is UNDONE when it judges worse (loop 1's BronzeCenser went 0.526 → 0.43 and
+ shipped that way), the scene brief and Blender's tool cards in the hero prompt, a 20 mm
+ ground self-check for a hero (the module's own sink rule; the scene seats every clone).
+ Measured after: 15 of 15 heroes built across eight scenes against 1 of 4 the same
+ morning; like-for-like re-judge (n=3) of four recorded hero descriptions 0.501 vs 0.358
+ for the same props as modules; `asset_v1` passes on 9 of 13 judged (0.70–0.88) against
+ 2 of 18 recorded. Whole-scene verdicts still swing 0.0–0.75 on one prompt for zone,
+ camera and judge reasons and do not measure this.
+
+* **D64 A keyframed Blender part reaches the scene as a clip, and the assembled scene
+ plays it (2026-09-07).** The wrapper exports animations (an object nobody keyframed
+ exports exactly as before), the preload keeps `gltf.animations` on the root — which
+ `.clone()` copies — and the assembled `scene.js` drives one mixer per clone by ABSOLUTE
+ time from `update(t)`, so t = 0 / 1.5 s are deterministic frames. The first attempt gave
+ the zone a `clipPlayer` helper and a sentence; the windmill zone placed the clone and
+ played nothing, so the harness took the job and the helper was deleted. Measured: the
+ windmill's `MillCapDetail` frames a quarter turn apart (19.3 % of the frame changed; the
+ judge: "the windmill sails animate correctly"), the lighthouse lens sweeping its beam
+ (61 %). A zone de-phases a copy with `clone.userData.clipOffset`.
+
+* **D65 The starter `env.js` lights through `sunRig` and assigns its environment map; a
+ small thing kilometres away is backdrop (2026-09-07).** 0 of 127 recorded `env.js` and
+ 0 of 4 written that morning set `scene.environment`, although the effects catalog asks
+ for it; every recorded hero carried Blender metalness 0.7–0.9 into such a scene. On the
+ example scene a metalness-0.9 sphere's region reads 0.24 (black with one highlight)
+ without the map and 0.55 (metal, reflecting the sky) with `sunRig`'s. The starter now
+ uses the rig (13 lines of its own sun + hemisphere deleted) and the env prompt says to
+ keep it. `sunRig`'s 'SunDisc' at 3.6 km (no word boundary for `SKY_NAME_RE`) blew the
+ content bbox to 2.5 km and put the overview rig kilometres up (`overview_top` ground
+ 0.0008); `backdrop.mjs` now calls anything small and > 1.5 km from the origin sky.
+
+* **D66 A procedural module is judged on the hero's rig, and the plan's largest one keeps
+ its verdict (2026-09-07).** `scene_assets` had judged threejs assets through
+ `runtime.render_asset` since the stage was written and nothing defined it: 0 of 860
+ recorded modules were judged while every hero was, so no paired verdict existed.
+ `SceneThreeJsRuntime.render_asset` exports the module with the object track's
+ `export_glb.mjs` and renders the same quick sheet. With it live the 5 % share rule alone
+ still judged nothing (measured over two scenes: 1e-5 .. 2e-3 of the scene volume), so
+ the plan's largest module of at least 1 m³ is judged whatever its share — one extra
+ verdict per scene at most; a bollard is not a hero, a boat is.
+
## Rejected / deferred
* A versioned `Spec`/`RunRecord`/`RunState` load-normaliser (rejected 2026-08-30: of the seven
@@ -992,7 +1048,7 @@ written) that were accepted because the code works that way and the tests pin it
* Registering `single-shot` as a CodingAgent kind (rejected: it has no tools/session).
* A free-form `dict` judge schema (rejected: flash skips criteria).
* Storing URDF meshes Y-up and converting on load (rejected: breaks foreign loaders).
-* Per-asset judging for threejs scene assets (deferred: needs a `render_asset` hook).
+* Per-asset judging for threejs scene assets — done 2026-09-07 (D66: `render_asset` on the scene runtime).
* Proposed and not yet done (owner-level files): `ToolCallPart.extra` for provider
state; `n_samples` in Settings. (Done since first written: `Workspace._git`
lock + index.lock retry; the `languages/**` package-data globs.)
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 593c72b4..9c56f01d 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -292,7 +292,7 @@ from codeverse.spatial.scene_placement import check_placement, placement_finding
check_placement(ws, *, indoor=None, force_probe=False) -> GateReport # gate "scene_placement"; data.kind ∈ floating | sunken |
# unsupported | interpenetration | summary | probe_failed; target "Zone/Asset" (routes to src/zones/<zone>.js);
# messages carry the scene_v1 floating_part cap words; reads artifacts/census.json["placement"] (host_placement.mjs)
-placement_gate_safe(census, *, plan=None) -> GateReport | None # round gate: None without a table, WARN on failure, never raises
+placement_gate_safe(census, *, plan=None, layouts=None, unavailable=()) -> GateReport | None # round gate: None without a table, WARN on failure, never raises; `unavailable` = assets the stage could not build (not "missing planned contents")
from codeverse.spatial.scene_placement import setting_text # (plan: dict | model) -> the indoor/outdoor setting line
from codeverse.spatial.silhouette import compare_silhouette
from codeverse.spatial.sections import judge_slices, SliceManifest, JUDGE_SLICE_PLANES # (D48)
@@ -471,7 +471,9 @@ generate(ws, *, agent_id, task, ..., budget=BudgetGuard, max_turns=0, wrapup_tur
# default was measured and rejected, docs/COST.md §17). A session that hits a cap that IS set is
# asked for a final build + summary (WRAPUP_PROMPT) instead of being killed.
# EVERY session (attempt 1, <label>.a2 retry, <label>.wrapup) is charged as it ends.
-from codeverse.tracks.repair import build_with_repair # RepairOutcome(.ok/.repaired/.max_attempts, attempts, usage)
+from codeverse.tracks.repair import build_with_repair # RepairOutcome(.ok/.repaired/.max_attempts, attempts, usage); build_with_repair(ctx, *, round_index, label, files_hint=None, max_attempts=None, timeout_s=None) — timeout_s clips every repair session (a scene asset's window)
+# scene assets (tracks/scene_assets.py): build_threejs_asset / build_blender_asset climb ONE ladder (_ladder: single-shot → check → one feedback repair → agent session); a hero's parts come from the static planner (hero_plan); SceneThreeJsRuntime.render_asset(ws, name, out_dir) renders a module on the hero's quick rig; the assembled scene.js plays every GLB clone's clips (clone.userData.clipOffset de-phases a copy)
+# languages/blender.write_blender_skeleton(ws, plan, *, multi_file=True, ground_tol_m=0.002) — the self-check's stands-on-z=0 tolerance (a scene hero passes 0.02)
from codeverse.tracks.steps import run_round, skip_judge_reason, emit_round_cost, record_aborted_round
skip_judge_reason(ctx, *, gates, renders) -> str # "" = judge it. ONLY states where the verdict is
# never bought at all: no judge / no renders / budget already exceeded / gate errors with
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index cd7c1b95..8471d8c8 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -242,8 +242,8 @@ asserts that the specific fixes the arm exists to measure are present.
**A new worktree needs `runtime_js/node_modules` before it can run a battery.** Without it
`render_glb` dies on every round, the judge is skipped for want of renders, and the cells
come back `status=plateau` with `score=None` — an arm that reads as healthy and measures
-nothing (2026-09-04, the mimic-off arm). `npm ci` in `runtime_js/`, or symlink the
-directory from a worktree that has it (the `package.json` is the same file). The row now
+nothing (2026-09-04, the mimic-off arm). `npm ci` in `runtime_js/`, or COPY the
+directory from a worktree that has it (the `package.json` is the same file). The row now (a symlink gave two 404s on every render of one worktree on 2026-09-07 — `serve.cjs` refuses a real path outside its root — while another probe served through one; copy and be sure)
says `no verdict in any of N round(s)` when this happens.
A run that crashed outside its own handling leaves `record.json` with `status=failed`;