Official Codebase of 3DCodeVerse
Python
D106: the scene track states requirements, never templates — both scene cookbooks gone, skeletons are stubs, gates and judge stop rewarding the plate-and-ring look
gaoypeng2aec1f4c8d3f
diff --git a/eval/bench/_loop_prompts.py b/eval/bench/_loop_prompts.pyindex d98f5e2e..09b59f77 100644--- a/eval/bench/_loop_prompts.py+++ b/eval/bench/_loop_prompts.py@@ -1,8 +1,9 @@"""The rung ladder and the planner-model request behind ``bench.loop generate`` (private).-A loop iteration runs ~30 scene prompts per language, and the prompts have to be two things-at once: HARD enough to move (an iteration that scores 0.8 on every prompt has nothing to-learn), and PAIRABLE across iterations (``bench.loop compare`` pairs by prompt id). So the+A loop iteration runs ~15 scene prompts per language (owner, 2026-10-15; was 30 — enough to+pair across iterations, small enough to turn an iteration in hours), and the prompts have to be+two things at once: HARD enough to move (an iteration that scores 0.8 on every prompt has nothing+to learn), and PAIRABLE across iterations (``bench.loop compare`` pairs by prompt id). So thedifficulty lives in a ladder of five rungs, each a set of OBJECTIVE knobs the owner fixed(zones / asset types / instance cap / lighting / effects), a rung's prompts are generatedONCE and cached, and an iteration's battery is a mix of the cached rungs up to ``--rung``.@@ -12,6 +13,11 @@ types with counts, a luminance band, one effect, one animation, a camera brief,loop renders the scenes_v2 composition contract from them (:func:`contract_lines`) — so thecounts always parse, the band is always a band, and the rung rules are checked on typedfields (:func:`check_prompt`), never by reading numbers back out of prose.++The brief describes a PLACE, never a layout (owner's rule, 2026-10-15): how its zones sit relative+to each other, how high its viewpoint stands and what continues past the detailed area+(``beyond``) are the brief's own choices, and the contract states them as requirements the judge+verifies — not as a shape the builder copies."""from __future__ import annotations@@ -92,7 +98,12 @@ class GeneratedPrompt(BaseModel):title: str = Field(description="3-6 words")category: Categoryprompt: str = Field(description="the brief: 2-4 sentences naming the place, its zones, the time of day and one activity")- zones: list[str] = Field(description="named zones in walking order, short lowercase phrases")+ zones: list[str] = Field(description="named zones, short lowercase phrases; how they relate in space (side by side, "+ "nested, stacked, across water, along a road that leaves the frame) is the "+ "prompt text's choice")+ beyond: str = Field(description="what continues past the detailed area, one clause — the rest of the street, open "+ "water to the horizon, more forest, a skyline, farmland, a wall; the place does not "+ "stop where its zones stop")asset_types: list[AssetCount]lighting: Lightingfeatures: list[Extra] = Field(default_factory=list)@@ -101,9 +112,10 @@ class GeneratedPrompt(BaseModel):luminance_high: float = Field(ge=0.0, le=1.0, description="mean frame luminance band, high edge")effect: str = Field(description="ONE water / weather / particle / shader effect, concrete and visible")animation: str = Field(description="ONE thing that visibly moves between the sampled times")- camera: str = Field(description="ONE eye-level viewpoint — where it stands, what it looks along and its height, "- "e.g. 'at the quay's landward end looking along it at 1.6 m'; a still camera, "- "never a path")+ camera: str = Field(description="ONE fixed viewpoint — where it stands, what it looks along and its height above "+ "the surface it stands on (eye level, 1.6 m, is the usual choice; a balcony, tower, "+ "ridge or quay crane is fine when the place has one), e.g. 'at the quay's landward "+ "end looking along it at 1.6 m'; a still camera, never a path")hero: str = Field(default="", description="rungs 4-5: the one hero asset")hero_motion: str = Field(default="", description="rungs 4-5: how the hero moves")scale_constraints: list[str] = Field(default_factory=list, description="rung 5: 'the lighthouse is 18 m tall'")@@ -157,7 +169,7 @@ def check_prompt(gp: GeneratedPrompt, rung: Rung) -> list[str]:problems.append(f"{gp.title!r}: rung {rung.level} needs a hero and its motion")if rung.scale and len(gp.scale_constraints) < 2:problems.append(f"{gp.title!r}: rung {rung.level} needs at least 2 scale constraints")- for field in ("effect", "animation", "camera", "mood", "prompt"):+ for field in ("effect", "animation", "camera", "mood", "prompt", "beyond"):if not getattr(gp, field).strip():problems.append(f"{gp.title!r}: empty {field}")return problems@@ -168,11 +180,18 @@ def check_prompt(gp: GeneratedPrompt, rung: Rung) -> list[str]:#: brief that asked for a tracking camera was a must-have no run could satisfy: the harness planner turns#: every must_have line into a ``must`` acceptance item, and the judge marked it unverified in 5 of#: iteration 0's 60 runs ("remains stationary between t=0s and t=1.5s"), which caps the whole score-#: (``missing_must_acceptance``). Every camera line starts with the prefix — :func:`migrate_camera_lines`-#: recognises the form by it — and ends with the suffix.-CAMERA_PREFIX = "camera: a FIXED eye-level camera"+#: (``missing_must_acceptance``). Every camera line starts with a fixed-form prefix — :func:`migrate_camera_lines`+#: recognises the form by it — and ends with the suffix. ``CAMERA_PREFIX`` is the form written since+#: 2026-10-15: FIXED is interface (stills only), the height is the brief's own (a tower, a balcony, eye level —+#: the harness measures the eye >= 0.3 m above what it stands on and >= 0.5 m from every surface), so the+#: "eye-level" of the first fixed form is no longer baked into an acceptance item the judge verifies.+#: ``LEGACY_CAMERA_PREFIX`` is that first form: the migrated lines of the cached rungs keep it verbatim (they+#: pair iterations), and the migration recognises both forms as already fixed.+CAMERA_PREFIX = "camera: a FIXED camera"+LEGACY_CAMERA_PREFIX = "camera: a FIXED eye-level camera"CAMERA_SUFFIX = ("; the harness renders still cameras only (nothing dollies or tracks); it never intersects any ""geometry (no clipping, nothing cut by the near plane)")+FIXED_CAMERA_PREFIXES: tuple[str, ...] = (CAMERA_PREFIX, LEGACY_CAMERA_PREFIX)def camera_line(camera: str) -> str:@@ -189,10 +208,10 @@ def migrate_camera_lines(prompts: Sequence[BenchPrompt]) -> int:n = 0for p in prompts:for i, line in enumerate(p.must_have):- if not line.startswith("camera: ") or line.startswith(CAMERA_PREFIX):+ if not line.startswith("camera: ") or line.startswith(FIXED_CAMERA_PREFIXES):continueroute = line.removeprefix("camera: ").split(";", 1)[0].strip()- p.must_have[i] = (f'{CAMERA_PREFIX} standing where this route begins and looking along it — "{route}"'+ p.must_have[i] = (f'{LEGACY_CAMERA_PREFIX} standing where this route begins and looking along it — "{route}"'f"{CAMERA_SUFFIX}")n += 1return n@@ -200,7 +219,8 @@ def migrate_camera_lines(prompts: Sequence[BenchPrompt]) -> int:def contract_lines(gp: GeneratedPrompt) -> list[str]:"""The scenes_v2 composition contract rendered from the typed fields (the ``must_have`` list)."""- lines = [f"{len(gp.zones)} zones: {', '.join(z.strip() for z in gp.zones)}"]+ lines = [f"{len(gp.zones)} zones: {', '.join(z.strip() for z in gp.zones)}",+ f"beyond: {gp.beyond.strip()} — the place continues past the detailed zones, visibly, from the authored camera"]for a in gp.asset_types:line = f"at least {a.count} {a.name.strip()}"if a.designs > 1:@@ -225,17 +245,23 @@ def instance_total(gp: GeneratedPrompt) -> int:# --------------------------------------------------------------------------- the requestSYSTEM = ("You write evaluation prompts for a procedural 3D scene generator: each prompt describes ONE place "- "that a coding agent must build as a multi-file scene (zones, instanced assets, lighting, one effect, "- "one animation, authored cameras). Prompts must be concrete, varied across categories and settings, "- "and buildable from primitives and a small effects library — no licensed characters, no text-heavy "- "signage, no real people. Answer ONLY with the JSON the schema describes."+ "that a coding agent builds as a procedural 3D scene (named zones, repeated assets with counts, lighting, "+ "one effect, one animation, authored cameras). Prompts are concrete, varied across categories and "+ "settings, and buildable procedurally in code (no external models or textures) — no licensed characters, "+ "no text-heavy signage, no real people. Describe the place, not a layout: where its zones sit relative to "+ "each other, how high its viewpoint stands and what continues past the detailed area are each prompt's own "+ "choices, and they should differ from prompt to prompt. Answer ONLY with the JSON the schema describes.")def rung_text(rung: Rung) -> str:lines = [f"Rung {rung.level} ({rung.tier}): {rung.brief}.",- f"- at least {rung.zones} named zones, laid out so a walk-through camera passes them in order",+ f"- at least {rung.zones} named zones, each a distinct part of the place the prompt describes; the prompt text "+ "says how they sit relative to each other (side by side, nested, stacked, across water, along a road that "+ "leaves the frame — the place's own arrangement)",+ "- beyond: what continues past the detailed zones (the rest of the street, open water, hills, a skyline, "+ "farmland, a wall) — the place does not end where its zones end",f"- at least {rung.asset_types} distinct asset types, each with an explicit instance count; the counts "f"must sum to at most {rung.instances} instances in the whole scene","- lighting is one of day / dusk / night; extra features are any of interior / water / particles",@@ -243,9 +269,9 @@ def rung_text(rung: Rung) -> str:f"(day ≈ 0.35-0.65, dusk ≈ 0.20-0.45, night ≈ {LUMINANCE_FLOOR:.2f}-0.35)","- exactly one effect (water surface, rain, snow, steam, dust, sparks, fog volume, a custom shader material)","- exactly one animation (a thing that visibly moves between two sampled times)",- "- a camera brief: ONE fixed eye-level viewpoint — where it stands, what it looks along and its height; "- "the scenes are rendered from still cameras only (nothing dollies or tracks), and the camera must never "- "intersect geometry",+ "- a camera brief: ONE fixed viewpoint — where it stands, what it looks along and how high it is (eye level "+ "is one option; a tower, balcony, ridge or deck is another when the place has it); the scenes are rendered "+ "from still cameras only (nothing dollies or tracks), and the camera never intersects geometry",]if rung.require_all:lines.append(f"- REQUIRED features: {', '.join(rung.require_all)}")@@ -319,6 +345,6 @@ def mix_counts(top: int, n: int) -> dict[int, int]:return {r: base + (1 if r > top - rem else 0) for r in range(1, top + 1)}-__all__ = ["FEATURE_POOL", "RUNGS", "AssetCount", "GeneratedBattery", "GeneratedPrompt", "Rung",- "build_request", "camera_line", "check_battery", "check_prompt", "contract_lines", "instance_total",- "migrate_camera_lines", "mix_counts", "parse_battery", "rung_text"]+__all__ = ["CAMERA_PREFIX", "FEATURE_POOL", "LEGACY_CAMERA_PREFIX", "RUNGS", "AssetCount", "GeneratedBattery",+ "GeneratedPrompt", "Rung", "build_request", "camera_line", "check_battery", "check_prompt", "contract_lines",+ "instance_total", "migrate_camera_lines", "mix_counts", "parse_battery", "rung_text"]diff --git a/eval/bench/loop.py b/eval/bench/loop.pyindex fd30e1c5..bb38fdee 100644--- a/eval/bench/loop.py+++ b/eval/bench/loop.py@@ -4,7 +4,7 @@python -m bench.loop init --name argon_scene --out bench/out/loop_argon --variant argon \\--languages scene_threejs,scene_blender --generator agy:gemini-4-argon \\--judge gemini:gemini-4-argon --judge-thinking medium --parallel 15 --rounds 2 --max-minutes 90- python -m bench.loop generate --out bench/out/loop_argon --iter 0 [--n 30] [--rung 1]+ python -m bench.loop generate --out bench/out/loop_argon --iter 0 [--n 15] [--rung 1]python -m bench.loop run --out bench/out/loop_argon --iter 0 [--languages scene_threejs] [--resume]python -m bench.loop diagnose --out bench/out/loop_argon --iter 0python -m bench.loop compare --out bench/out/loop_argon --iter 1 --against 0@@ -14,7 +14,7 @@python -m bench.loop status --out bench/out/loop_argonOne iteration = one edit of a per-model prompt/skill VARIANT (``codeverse3d/prompts/variants/<v>/`` +-``codeverse3d/skills/variants/<v>/``, D105) measured on ~30 scene prompts per language, run in+``codeverse3d/skills/variants/<v>/``, D105) measured on ~15 scene prompts per language, run inparallel on the generator under test, judged by ONE fixed judge at ONE thinking level. ``init``freezes every knob in ``<out>/loop.json``; everything else reads it, so two iterations never differin anything but the variant and (when ``--rung`` moves) the prompt mix.@@ -99,8 +99,9 @@ LOOP_JSON = "loop.json"VARIANT_TOML = "variant.toml"#: the machine-wide Cycles slots the children share: 30 parallel runs render on ONE GPU, and#: `Render.blender_gpu_slots` defaults to 2 for an interactive box (D104 measured 0.21-0.64 s/frame-#: on the GPU vs 2.3 s on the CPU, so a third slot is worth more than a third CPU render)-BLENDER_GPU_SLOTS = "3"+#: on the GPU vs 2.3 s on the CPU, so a third slot is worth more than a third CPU render; five slots fit the+#: memory the renders measured)+BLENDER_GPU_SLOTS = "5" # 3 → 5 on 2026-10-15: 24 GB of GPU memory sat at 2.7 GB with 30 runs; the owner asked for more parallelism#: how long a stopped driver waits for a child to record its stop before SIGKILL: the child's own#: stop handler (`run_bench.main` installs it) unwinds within `proc.STOP_GRACE_S` = 30 sCHILD_STOP_GRACE_S = 45.0@@ -131,7 +132,7 @@ class LoopConfig(BaseModel):"(run_bench --stagger); the children themselves launch stagger_s/2 apart")rounds: int = Field(default=2, ge=0)max_minutes: float = Field(default=90.0, gt=0)- n: int = Field(default=30, ge=1, description="prompts per battery")+ n: int = Field(default=15, ge=1, description="prompts per battery") # 30 → 15 (owner, 2026-10-15)track: Track = Track.SCENEcreated_at: str = ""@@ -887,7 +888,7 @@ def build_parser() -> argparse.ArgumentParser:"half that apart (0 = everything at once)")s.add_argument("--rounds", type=int, default=2)s.add_argument("--max-minutes", type=float, default=90.0)- s.add_argument("--n", type=int, default=30, help="prompts per battery")+ s.add_argument("--n", type=int, default=15, help="prompts per battery")s = sub.add_parser("generate", help="write the iteration's batteries (a mix of cached rungs)")_add_out(s)diff --git a/eval/tests/test_loop.py b/eval/tests/test_loop.pyindex 37c8ad95..f575f720 100644--- a/eval/tests/test_loop.py+++ b/eval/tests/test_loop.py@@ -23,6 +23,8 @@ from bench._loop_diag import (py_lib_modules,)from bench._loop_prompts import (+ CAMERA_PREFIX,+ LEGACY_CAMERA_PREFIX,LUMINANCE_CEILING,LUMINANCE_FLOOR,RUNGS,@@ -91,6 +93,7 @@ def good_prompt(rung: int, k: int) -> GeneratedPrompt:title=f"place {rung}-{k}", category=CATEGORIES[k % len(CATEGORIES)],prompt=f"a place number {k} at rung {rung} with zone 0 and zone 1 and a walk-through",zones=[f"zone {i}" for i in range(r.zones)],+ beyond="the lane runs on downhill past the last zone into orchards that fade into the haze",asset_types=[AssetCount(name=f"things {i}", count=count, designs=2 if i == 0 else 1) for i in range(r.asset_types)],lighting=lighting, features=features, mood="warm low sun" if lighting != "night" else "lantern glow",luminance_low=NIGHT_LOW if lighting == "night" else 0.3, luminance_high=0.35 if lighting == "night" else 0.6,@@ -199,8 +202,17 @@ def test_the_rung_ladder_is_the_owners_table_and_the_mix_splits_evenly():assert any("scale" in p for p in check_prompt(good_prompt(4, 0), RUNGS[5]))few = good_prompt(2, 0).model_copy(update={"zones": ["a", "b"]})assert any("needs at least 4" in p for p in check_prompt(few, RUNGS[2]))+ # `beyond` (2026-10-15): what continues past the detailed area is a required field and a contract line,+ # so "nothing past the bounds" fails an acceptance item instead of being the default shape+ nowhere = good_prompt(1, 0).model_copy(update={"beyond": " "})+ assert any("empty beyond" in p for p in check_prompt(nowhere, RUNGS[1]))lines = contract_lines(good_prompt(4, 1))assert lines[0].startswith("6 zones: ") and "at least 20 things 0 using at least 2 distinct designs" in lines+ assert lines[1].startswith("beyond: the lane runs on downhill") and "continues past the detailed zones" in lines[1]+ # the rung text asks for the field and never dictates a layout (no walk-through order, no eye-level default)+ for level in RUNGS:+ text = rung_text(RUNGS[level])+ assert "beyond:" in text and "walk-through" not in text and "in order" not in text and "eye-level" not in text, levelassert any(ln.startswith("night mood:") and f"mean luminance roughly {NIGHT_LOW:.2f}-0.35" in ln for ln in lines)assert any(ln.startswith("water:") for ln in lines) and any(ln.startswith("hero: the hero wheel") for ln in lines)assert any("never intersects any geometry" in ln for ln in lines)@@ -209,12 +221,15 @@ def test_the_rung_ladder_is_the_owners_table_and_the_mix_splits_evenly():def test_the_camera_line_is_a_still_viewpoint_and_old_lines_migrate_once():"""Both scene languages render the authored cameras as STILLS at t = 0 and t = 1.5 s, so a brief thatasked for a dolly was a must-have no run could satisfy (iteration 0: unverified in 5 of 60 runs, a- `missing_must_acceptance` cap on the whole score). The line now states a fixed eye-level viewpoint;- a cached line of the old form is rewritten around the route the model wrote, once."""+ `missing_must_acceptance` cap on the whole score). The line now states a fixed viewpoint whose height is+ the brief's own (2026-10-15: "eye-level" left the prefix — a tower or balcony viewpoint is not an unverified+ must item); a cached line of the old moving form is rewritten around the route the model wrote, once, in+ the first fixed form, which stays verbatim because the cached rungs pair iterations."""assert camera_line(" at the quay's landward end looking along it at 1.6 m ") == (- "camera: a FIXED eye-level camera, at the quay's landward end looking along it at 1.6 m; the harness renders "+ "camera: a FIXED camera, at the quay's landward end looking along it at 1.6 m; the harness renders ""still cameras only (nothing dollies or tracks); it never intersects any geometry (no clipping, nothing cut by ""the near plane)")+ assert CAMERA_PREFIX == "camera: a FIXED camera" and LEGACY_CAMERA_PREFIX == "camera: a FIXED eye-level camera"lines = contract_lines(good_prompt(1, 0))assert [ln for ln in lines if ln.startswith("camera: ")] == [camera_line("at the lane's near end looking along it at 1.6 m")]assert "still cameras only (nothing dollies or tracks)" in rung_text(RUNGS[1]) and "path" not in rung_text(RUNGS[1])@@ -233,6 +248,11 @@ def test_the_camera_line_is_a_still_viewpoint_and_old_lines_migrate_once():"effect: steam rising from a grate"]assert fresh.must_have == [camera_line("at the gate looking in at 1.6 m"), "animation: the awning extends"]assert migrate_camera_lines([old, fresh]) == 0, "idempotent: the fixed form is recognised, nothing moves twice"+ # a cache in the FIRST fixed form (iteration 1's) is recognised too — never wrapped a second time+ legacy = BenchPrompt(id="it01_scene_threejs_r1_02", prompt="p", tier="medium",+ must_have=[f"{LEGACY_CAMERA_PREFIX}, at the gate looking in at 1.6 m; the harness renders still cameras only"])+ before = list(legacy.must_have)+ assert migrate_camera_lines([legacy]) == 0 and legacy.must_have == beforedef test_the_luminance_floor_is_the_frame_gates_dark_threshold():@@ -366,7 +386,7 @@ def test_run_builds_the_child_argv_and_env_and_records_exit_codes(cfg: loop.Loopassert "--no-report" in argv and "--redo-status" not in argv and "--planner" not in argvenv = call["env"]assert (env["C3D_JUDGE__THINKING"], env["C3D_VARIANT"], env["C3D_RENDER__BLENDER_GPU_SLOTS"], env["PYTHONUNBUFFERED"]) == \- ("medium", "argon", "3", "1")+ ("medium", "argon", "5", "1")assert call["cwd"] == str(loop.REPO) and call["start_new_session"] is Truerun = json.loads((cfg.iter_dir(0) / "run.json").read_text())assert run["children"]["scene_threejs"]["pid"] == 4242 and run["children"]["scene_blender"]["returncode"] == 0diff --git a/eval/tests/test_scene_regate.py b/eval/tests/test_scene_regate.pyindex ac6ed187..48dc92f1 100644--- a/eval/tests/test_scene_regate.py+++ b/eval/tests/test_scene_regate.py@@ -21,6 +21,8 @@ from bench.scene_regate import ()from codeverse3d.contracts.artifacts import GateFinding, GateReportfrom codeverse3d.contracts.common import Language+from codeverse3d.spatial.scene_placement import placement_gate+from codeverse3d.workspace import Workspacedef _run(root: Path, name: str, *, track: str = "scene", with_src: bool = True, language: str | None = "scene_threejs",@@ -56,8 +58,13 @@ def test_regate_reads_the_stage_records_the_round_gate_reads(tmp_path: Path, mon"support": "Ground"}], "pairs": []}}monkeypatch.setattr(sr, "probe", lambda ws, timeout_s, language: census)after = regate(run, timeout_s=1.0)["after"]- assert any("holds ~179 instances but its layout budgeted 443" in m for m in after), afterassert not any("BronzeCenser" in m for m in after), after+ # the density finding is an INFO note since D106 (a count is not a requirement), so it is not+ # among the ERRORs regate lists; the round's own gate, which regate calls, still reads it+ report = placement_gate(Workspace(run), census, plan)+ notes = [f.message for f in report.findings if f.data.get("kind") == "density_note"]+ assert any("holds ~179 instances" in m and "443" in m for m in notes), [f.message for f in report.findings]+ assert not any("179" in m for m in after), afterdef test_only_scene_runs_with_their_entry_file_are_re_gated(tmp_path: Path) -> None:diff --git a/harness/CLAUDE.md b/harness/CLAUDE.mdindex 2acc50e8..bfee559e 100644--- a/harness/CLAUDE.md+++ b/harness/CLAUDE.md@@ -90,6 +90,8 @@ cd harness3dcodeverse make "..." --track articulated_object --language urdf_blender3dcodeverse make "..." --track scene --language scene_threejs --rounds 2 --max-minutes 603dcodeverse make "..." --track scene --language scene_blender --rounds 2 --max-minutes 90 # bpy scene on Blender 5.2.2 (D105): harness-owned src/lib, Cycles judged frames+# The scene track states REQUIREMENTS, never templates (D106, 2026-10-15): no scene cookbook, no inlined recipes, placeholder+# skeletons; a scene prompt / skill keeps only interface, sandbox rules and measured thresholds (+ the lib as an optional toolbox).3dcodeverse make "..." --variant argon # per-model prompt/skill overlay: prompts/variants/<name>/ + skills/variants/<name>/ (D105; C3D_VARIANT, C3D_VARIANTS='{"agy:gemini-4-argon": "argon"}')3dcodeverse make "neon rain on a window" --track graphics --language glsl_shader3dcodeverse make "..." --image ref.png --candidates 3 --rounds 2 --dim height=0.45 --must "three legs" --texture --no-rundiff --git a/harness/codeverse3d/agents/materialize.py b/harness/codeverse3d/agents/materialize.pyindex 2d5ec01f..8fed68a5 100644--- a/harness/codeverse3d/agents/materialize.py+++ b/harness/codeverse3d/agents/materialize.py@@ -90,7 +90,7 @@ def _tool_section(agent_kind: str, spatial_tools: bool, mcp_command: list[str],)-def _body(agent_kind: str, contract_md: str, cookbook_note: str, spatial_tools: bool, mcp_command: list[str],+def _body(agent_kind: str, contract_md: str, cookbook_section: str, spatial_tools: bool, mcp_command: list[str],ws: Workspace | None = None) -> str:return ("# 3dcode workspace — rules for the coding agent\n\n"@@ -108,7 +108,7 @@ def _body(agent_kind: str, contract_md: str, cookbook_note: str, spatial_tools:"5. When you are done, reply with a SHORT summary of what you changed and what you verified. ""Do not ask questions — there is no human in the loop; make a reasonable decision and proceed.\n\n"f"{_tool_section(agent_kind, spatial_tools, mcp_command, ws)}\n"- f"## Cookbook\n\n{cookbook_note}\n\n"+ f"{cookbook_section}"f"## Language contract\n\n{contract_md.strip()}\n")@@ -156,33 +156,34 @@ def materialize_workspace(Returns nothing: the ``Materialized`` DTO this used to build (body/ignore paths, thecookbook path, the argv, a warnings list) was discarded by every production caller —- ``tracks/common.Services.materialize`` is typed ``-> None`` — so its one real signal,- a cookbook that did not resolve, was written and read by nobody. That is the exact- failure the cookbook path lookup (``cookbook_rel_for``, gone since 2026-09-22) was fixed- for on 2026-08-29 (an articulated run told the agent "No cookbook is available" while its- 24 kB cookbook sat on disk);- it is a log line now, where someone reading the run can see it (2026-08-30).+ ``tracks/common.Services.materialize`` is typed ``-> None``.``cookbook_text`` is what the catalog loaded (``RunContext.cookbook_text``): until2026-09-22 this took a path and resolved it itself, workspace first — so a- ``<ws>/blender/cookbook.md`` the agent wrote shadowed the harness cookbook."""+ ``<ws>/blender/cookbook.md`` the agent wrote shadowed the harness cookbook. A language+ that ships no cookbook (the two scene languages, owner 2026-10-15) passes ``""`` and the+ body carries no "## Cookbook" section at all: the contract and the skills are what there+ is, and a note saying a file is missing would only send the agent looking for one. (A+ stale ``.3dcode/cookbook.md`` from an earlier materialisation is removed for the same+ reason.)"""mcp_command = list(mcp_command) if mcp_command else default_mcp_command(ws)# cookbook: copy into the harness-owned .3dcode/ dir so every CLI can read it in-workspace+ dest = ws.root / C3D_DIR / "cookbook.md"if cookbook_text:- dest = ws.root / C3D_DIR / "cookbook.md"dest.parent.mkdir(parents=True, exist_ok=True)dest.write_text(cookbook_text, encoding="utf-8")- cookbook_note = (+ cookbook_section = (+ "## Cookbook\n\n"f"The cookbook for this language — copyable, verified snippets and skeletons — is at "f"`{C3D_DIR}/cookbook.md` (relative to the workspace root). Read the relevant sections "- "before writing code and copy its patterns exactly."+ "before writing code and copy its patterns exactly.\n\n")else:- log.warning("cookbook not found — the %s session gets the contract only", agent_kind)- cookbook_note = "No cookbook is available in this session; rely on the contract below."+ dest.unlink(missing_ok=True)+ cookbook_section = ""- body = _body(agent_kind, contract_md, cookbook_note, spatial_tools, mcp_command, ws)+ body = _body(agent_kind, contract_md, cookbook_section, spatial_tools, mcp_command, ws)for name in BODY_FILES:(ws.root / name).write_text(body)# No MCP server is written into the workspace: every CLI gets 3dcode from a harness-owneddiff --git a/harness/codeverse3d/config.py b/harness/codeverse3d/config.pyindex 8e6e45c6..cd4ddbe0 100644--- a/harness/codeverse3d/config.py+++ b/harness/codeverse3d/config.py@@ -181,7 +181,7 @@ class Rate(BaseModel):"""max_in_flight: int = Field(- default=64,+ default=96,ge=0, # NEGATIVE is not "unlimited" here: 0 is. Without this bound -5 survived config,# was reported as FITTING the pool budget by `3dcode doctor`, poisoned the shared# in-flight accounting, and finally died as a bare ValueError from@@ -190,7 +190,10 @@ class Rate(BaseModel):description="machine-wide cap on concurrent model calls (0 = off): every process draws ""from the same N slot files, so the machine never exceeds the largest N any process runs ""with. Measured knee: a 128-call burst of 12k-token prompts ran 29.6 calls/min at 16 "- "in-flight, 43.9 at 32, 72.9 at 64 and fell back to 47.2 at 128 (docs/COST.md Part III).")+ "in-flight, 43.9 at 32, 72.9 at 64 and fell back to 47.2 at 128 (docs/COST.md Part III) — with 22 "+ "keys; raised 64 → 96 on 2026-10-15 for the 30-key pool after iteration 0 of the argon loop hit the "+ "64 cap 172 times at launch while the keys themselves showed no 429 pressure (12 concurrent calls on "+ "one key: 0 × 429; re-measure the knee when the loops run two tracks at once).")hedge: int = Field(default=2, ge=1,description="keys a retry is raced on once a call has met its first 503 (1 = off). Measured "diff --git a/harness/codeverse3d/contracts/plan.py b/harness/codeverse3d/contracts/plan.pyindex 018975c0..d467e97b 100644--- a/harness/codeverse3d/contracts/plan.py+++ b/harness/codeverse3d/contracts/plan.py@@ -548,8 +548,10 @@ class ArticulatedPlan(StaticPlan):class ZonePlan(BaseModel):name: str = Field(description="PascalCase zone name, e.g. Harbour")- description: str- bbox: BBox+ description: str = Field(description="what the place is, what happens there, its layout as numbers and "+ "how much dressing it carries — one builder realises it")+ bbox: BBox = Field(description="where this zone's builder may place; any size or shape, laid out as the "+ "place is (its layout is validated against this box)")contents: list[str] = Field(default_factory=list, description="asset names placed in this zone")@@ -579,9 +581,9 @@ class AssetPlan(BaseModel):# planner swaps in its own enum (``scene_plan_schema``)json_schema_extra={"enum": list(SCENE_ASSET_KINDS["scene_threejs"])},)- description: str- approx_size_m: Vec3- instances_hint: int = 1+ description: str = Field(description="construction in numbers and colours; the builder realises it")+ approx_size_m: Vec3 = Field(description="width x height x depth in meters; the built asset is measured against it")+ instances_hint: int = Field(default=1, description="how many appear in the whole scene")class EffectPlan(BaseModel):@@ -604,7 +606,7 @@ class CameraPlan(BaseModel):position: Vec3look_at: Vec3fov: float = Field(default=50.0, ge=5.0, le=150.0)- purpose: str = ""+ purpose: str = Field(default="", description="what the shot is of and what the judge should see in it")@field_validator("name")@classmethod@@ -628,13 +630,16 @@ class ScenePlan(BaseModel):summary: strsetting: str = Field(description="place, era, weather, time of day")mood: str = ""- bounds: BBox- environment: str = Field(description="sky, sun/moon, fog, ground, water — one paragraph")+ bounds: BBox = Field(description="the DETAILED area the harness measures against (layouts, placements, camera "+ "clearance); the world continues past it as the place does")+ environment: str = Field(description="lighting, atmosphere, landform and ground surface, water, and how the world "+ "continues beyond the bounds — one paragraph of numbers")interior: bool = Field(default=False,description="the view is from INSIDE a built space (workshop, room, cabin, hall, shop): the "- "environment module owns the enclosure — floor, walls and ceiling on the bounds' faces with "- "openings where the windows and doors are — and the zones dress the inside; false outdoors",+ "environment module owns the enclosure — floor, walls, ceiling and the openings `environment` "+ "describes (the skeleton starts it on the bounds' faces; the builder may reshape it) — and the "+ "zones dress the inside; false outdoors",)glazed: bool = Field(default=False,@@ -708,9 +713,9 @@ class ZoneLayout(BaseModel):placements: list[ZonePlacement] = Field(default_factory=list)path_points: list[tuple[float, float]] = Field(default_factory=list, description="(x, z) polyline of the walkway through this zone, if any")- mid_props: int = Field(default=0, ge=0, description="loose mid props (0.3-1.5 m) beyond the placements")- small_props: int = Field(default=0, ge=0, description="small props (< 0.3 m)")- ground_cover: int = Field(default=0, ge=0, description="instanced tufts / pebbles")+ mid_props: int = Field(default=0, ge=0, description="loose mid props (0.3-1.5 m) beyond the placements; 0 for a bare place")+ small_props: int = Field(default=0, ge=0, description="small props (< 0.3 m); 0 for a bare place")+ ground_cover: int = Field(default=0, ge=0, description="instanced tufts / pebbles; 0 where the ground is bare")notes: str = Field(default="", description="one line of layout intent, e.g. 'stalls face the lane'")diff --git a/harness/codeverse3d/judges/prompt_builder.py b/harness/codeverse3d/judges/prompt_builder.pyindex 3b0668a9..dad80caf 100644--- a/harness/codeverse3d/judges/prompt_builder.py+++ b/harness/codeverse3d/judges/prompt_builder.py@@ -1121,7 +1121,10 @@ RIG_RULES: dict[str, str] = {"geometry": "The GEOMETRY-ONLY montage shows the same object without materials/lighting: use it for holes, inverted (black) faces, intersections and floating parts; use the SHADED montage for materials and detail.","poses": "POSE tiles show the SAME object with joints moved by the harness (tile label = joint@value or rest). Judge articulation only from them and the joint table.","scene_cams": "Views named overview_* and eye_* are harness cameras fitted to the scene bounds (layout X-ray); every other view is one of the scene's own authored cameras (grade composition/lighting on those); 't=' is the animation time.",- "scene_craft": "On the authored cameras also read the CRAFT of the picture, not only its contents: depth layering (is there anything within a few metres framing the shot, and anything on the horizon), ground variation (blended materials, paths, dressed edges vs one flat colour), variety among repeated natural elements, small-prop dressing, and aerial perspective (distant things hazier than near ones). The same camera at two times appears as separate tiles — compare them pixel-for-pixel before answering nothing_moves.",+ # 2026-10-15 (owner's rule: requirements, not templates): the craft list names what to read against the+ # BRIEF's place, not one recipe (foreground prop + blended ground + fog), and nothing_moves is the+ # MEASURED MOTION line's — the rubric forbids judging motion by comparing tiles+ "scene_craft": "On the authored cameras also read the CRAFT of the picture, not only its contents: depth readable for what each shot frames, surfaces that read as the brief's materials rather than one flat colour, variety among repeated elements, the secondary detail the brief's place implies, and distance softened where the brief's weather would soften it — each judged against what THIS place would have, not a fixed recipe. The same camera at two times appears as separate tiles; nothing_moves is answered from the MEASURED MOTION line only, never by comparing tiles.",# scene_v2 (2026-10-14): the high overview tiles lift room ceilings (scene_host.skyLayersBelow) and# drop the fog; the low one is the contact camera; CONTACT CROPs are diagnostic close-ups"scene_contact": "The high overview_* tiles (overview_front_right / overview_back_left / overview_top) are rendered with the fog removed and room ceilings lifted: a missing roof, lid or haze in them is never a defect. overview_low_front stands at ground level just outside the content, where daylight under a base shows. CONTACT CROP images are diagnostic close-ups cut from an overview tile around a placement finding the gate measured (the label names the asset, the kind and the number): judge the contact they show — base meets ground, part through neighbour — never their composition, lighting or dressing. Every floating / sunken / clipping / scale claim must name its view and its asset.",diff --git a/harness/codeverse3d/judges/rubrics/scene_v2.yaml b/harness/codeverse3d/judges/rubrics/scene_v2.yamlindex 906652bf..3d35b5f1 100644--- a/harness/codeverse3d/judges/rubrics/scene_v2.yaml+++ b/harness/codeverse3d/judges/rubrics/scene_v2.yaml@@ -12,6 +12,11 @@ description: >particles / missing planned elements / hero placement join the checklist, the caps followthe scene_placement gate's typed kinds, and every criterion is anchored at six levels so thejudge uses the whole scale. scene_v1 stays frozen for replays of the rounds it scored.+ 2026-10-15 (owner's rule — the harness states requirements, never templates): the craft+ criteria and defects judge each place against what ITS brief implies instead of one recipe+ (blended ground + paths, clustered scatter, foreground-frame / midground / horizon, fog and+ a two-hue key/fill everywhere), and `diorama_look` names the template itself — a block on a+ plate ringed by a uniform backdrop with nothing beyond — as a defect.extra_instructions: >Views named overview_* are HARNESS cameras fitted to the scene bounds — nobody framed@@ -49,28 +54,42 @@ extra_instructions: >CALIBRATION — fixed points on the overall scale (the harness computes the overall fromyour criterion scores; these say where the criteria must land): a bare skeleton — groundplane, a few primitives, the starter sky — scores at most 0.35 overall; a correct but plain- diorama (every planned zone present, boxes-and-cones assets, flat ground, no dressing, no- haze) sits around 0.55; a photographable place — layered detail, varied assets, dressed- ground, aerial perspective, no visible defect — scores 0.80 or more. A diorama and a- photographable place must land at least 0.3 apart: if you cannot tell which of two scenes a- person would screenshot, you have compressed the scale. Each criterion carries six anchors- (1.0 / 0.85 / 0.7 / 0.55 / 0.4 / 0.1); interpolate between them and use the whole range.+ diorama (every planned zone present, primitive assets, surfaces without variation or wear,+ nothing of the brief's place beyond its named elements) sits around 0.55; a photographable+ place — detail layered at every scale the authored cameras see, varied assets, surfaces that+ read as the brief's materials, depth readable in the shots that have distance, no visible+ defect — scores 0.80 or more. A diorama and a photographable place must land at least 0.3+ apart: if you cannot tell which of two scenes a person would screenshot, you have compressed+ the scale. Each criterion carries six anchors (1.0 / 0.85 / 0.7 / 0.55 / 0.4 / 0.1);+ interpolate between them and use the whole range.Craft on this track is mostly about five things, so look for each of them explicitly- before scoring: (1) the GROUND — is it several blended materials with paths, wear and- dressed edges, or one flat colour with a hard bbox line; (2) VEGETATION / repeated- natural elements — several silhouettes with size and hue variation in clusters, or one- shape stamped in a ring; (3) DEPTH — is there something in the near foreground framing- the shot, a subject in the midground and a horizon above, or is it a small diorama alone- on a big empty plane; (4) DRESSING — the small props (pebbles, leaves, tools, cups,- cables, litter) that make a place look used; (5) ATMOSPHERE — fog/haze giving aerial- perspective, coloured (sky-lit) shade, and a key light whose hue differs from the fill.- A scene can be entirely correct against the brief and still sit at 0.55 because it fails- all five; say so in the issues rather than inventing a fidelity complaint. And a scene- that passes all five can still lose on DETAIL: look at every asset at crop scale for a- floating base, a part through another part, a mismatched scale and hard-edged particles- before you score.+ before scoring — and judge each against what the BRIEF's place would have, never against a+ fixed recipe (a quay, a gym and a snowfield are flat by nature; an overcast noon has no warm+ key; a lab is clean): (1) the GROUND — does it read as the surface the brief's place would+ have (variation, wear, how things meet it), or as one flat untextured colour ending in a+ hard bbox line; (2) REPEATED ELEMENTS (trees, rocks, figures, fixtures) — several+ silhouettes with per-copy size and hue variation, arranged as the place would arrange them+ (an orchard is a grid, a stone circle is a ring), or one shape stamped identically; (3) DEPTH+ — does each authored shot have readable depth for what it frames (near / far relationships,+ overlap, scale cues, a horizon where the place has one), or is it a small diorama alone on a+ big empty plane; (4) DRESSING — the secondary detail the brief's place implies (what people+ left there, wear, fixtures, growth) that makes it look used, or a showroom of a few large+ objects; (5) ATMOSPHERE — do the light and the air match the brief's hour and weather+ (distance readable where the scene has distance, shade carrying the sky's colour rather than+ black), or is the frame airless for no reason the brief gives. A scene can be entirely+ correct against the brief and still sit at 0.55 because it fails all five; say so in the+ issues rather than inventing a fidelity complaint. And a scene that passes all five can+ still lose on DETAIL: look at every asset at crop scale for a floating base, a part through+ another part, a mismatched scale and hard-edged particles before you score.+++ One shape of scene is a defect whatever its polish: a compact block of content in the middle+ of a flat plate, ringed all round by one uniform backdrop (identical hills, trees or+ silhouettes at one radius) with nothing continuing beyond it — a model on a table, not a+ place that goes on. That is `diorama_look`: cite the view that shows the plate's edge or+ the ring.criteria:- id: brief_fidelity@@ -94,14 +113,16 @@ criteria:floor: 0.25title: Composition and cameradescription: >- Do the authored cameras make readable, well-framed pictures — a focal subject,- foreground/midground/background, horizon placed deliberately, nothing clipped by- the near plane, no camera inside geometry, no shot that shows only sky or ground?+ Do the authored cameras make readable, well-framed pictures — a focal subject the+ camera is aimed at, depth readable for what the shot frames, nothing clipped by the+ near plane, no camera inside geometry, no shot that shows only sky or ground? The+ brief decides what each viewpoint looks at and from how high; a corridor, a lake+ crossing, a tower seen from below or a top-down map shot can each be a composed shot.anchors:- "1.0": Every authored camera is a composed shot — a foreground element within a few metres frames the edge, the subject fills the middle distance, a horizon band sits above, and the subject is what the camera is aimed at.- "0.85": Every shot is composed and aimed; one lacks a foreground frame or sits a little too high / too central.- "0.7": Shots are readable and aimed at the subject, but one layer is missing (no foreground, or a bare horizon) or one shot is flat / off-centre.- "0.55": The scene reads as a diorama photographed from outside — subject centred on a large empty plane, no foreground, nothing on the horizon.+ "1.0": Every authored camera is a composed shot of what the brief says that viewpoint looks at — the subject is clearly what the camera is aimed at, the frame has depth where the place offers it (something near, something far, overlap, a horizon where the place has one), and nothing is clipped or empty.+ "0.85": Every shot is composed and aimed; one has less depth than its place offers, or sits a little too high / too central.+ "0.7": Shots are readable and aimed at the subject, but one is flat where the place had depth to give, or off-centre, or oddly cropped.+ "0.55": The scene reads as a diorama photographed from outside — subject centred on a large empty plane with nothing between it and the camera and nothing beyond it."0.4": One authored camera shows nothing useful (sky, ground, the inside of a wall), or the establishing shot is aimed at the bounds centre rather than the subject, or a shot is badly clipped."0.1": Most shots are unusable or the camera is inside geometry.@@ -110,15 +131,17 @@ criteria:floor: 0.25title: Lighting and atmospheredescription: >- Is the lighting readable and atmospheric — a consistent sun/moon direction,- present soft shadows, sky that matches the mood, aerial perspective / fog giving- depth, exposure neither blown nor crushed, coloured (sky-lit) shade rather than- black?+ Is the lighting readable and right for the brief — a consistent light direction,+ shadows where the light would cast them, a sky that matches the brief's hour and+ weather, depth readable where the place has distance, exposure neither blown nor+ crushed, shade that carries ambient colour rather than black? An overcast, a+ sodium-lit night, a clear dry noon or an interior is legitimately near-monochrome+ or haze-free when the brief says so.anchors:- "1.0": Clear mood executed consistently; warm key against a cooler fill (or the reverse); soft accurate shadows with smooth edges; fog/haze gives visible aerial perspective with distance; shade carries sky colour.- "0.85": The mood is clear and the key / fill / haze are all present; one of them is a notch off (shadows a little hard, haze a little thin, the sky a little flat).- "0.7": Good lighting with one weakness (slightly flat shadows, slightly heavy fog, or a horizon with no atmospheric falloff).- "0.55": Lit but airless — no haze or depth cue, key and fill share one hue so the frame is monochrome, or shadow edges are visibly stair-stepped.+ "1.0": Clear mood executed consistently — light colour, direction and contrast agree with the brief's hour and weather; shadows soft and accurate; distance reads where the shot has it; shade is coloured, never black.+ "0.85": The mood is clear and consistent; one element is a notch off (shadows a little hard, distance a little too crisp or too milky for the weather, the sky a little flat).+ "0.7": Good lighting with one weakness (slightly flat shadows, air heavier or thinner than the brief's weather, or a far distance with no falloff where the weather would give some).+ "0.55": Lit but airless — no depth cue in shots that have distance, or a monochrome frame the brief's weather does not explain, or shadow edges visibly stair-stepped."0.4": Flat shadowless light, or noticeably under/over-exposed, or sky contradicting the light, or black (unfilled) shadows."0.1": Near-black, blown white, or unlit.@@ -131,10 +154,10 @@ criteria:furniture where the place calls for them — without copy-paste monotony? Judgethem at crop scale, not only from the overviews.anchors:- "1.0": Assets are crafted and varied — several silhouettes per family, per-instance size and hue variation, wear and small props everywhere; the crops hold up.+ "1.0": Assets are crafted and varied — several silhouettes per family, per-copy size and hue variation, and the wear and small props the brief's place would carry; the crops hold up."0.85": Assets are crafted and varied; one family is plainer than the rest or repeats a silhouette, and the crops show a seam or two."0.7": Assets are decent with some repetition, a few plain ones, or thin set dressing.- "0.55": Hero assets are fine but everything around them is one repeated primitive and the place is undressed — no small props, no litter, no ground cover.+ "0.55": Hero assets are fine but everything around them is one repeated primitive and the place lacks the secondary detail its brief implies."0.4": Mostly plain boxes / cones, or one shape stamped everywhere, or a solid object faked as a flat coloured plane."0.1": Primitive blobs or an empty world.@@ -287,19 +310,26 @@ defects:text: A hard world edge / terrain cliff / missing horizon is visible from an authored camera.penalty: 0.04- id: flat_ground- text: The ground is one flat untextured colour — no material blending, no paths or worn areas, and where objects meet it the seam is a hard undressed line.+ text: The ground reads as one flat untextured colour where the brief's surface would show variation or wear, and where objects meet it the seam is a hard undressed line.penalty: 0.04- id: monotonous_vegetation- text: A repeated natural element (trees, rocks, plants, crowd) is one shape stamped many times — no variation in silhouette, size or hue, and placed in a ring or a grid rather than clusters.+ text: A repeated natural element (trees, rocks, plants, crowd) is one shape stamped many times — no variation in silhouette, size or hue — in a mechanical pattern (a ring, a grid, an even row) the place itself would not have.penalty: 0.04- id: empty_midground- text: An authored camera has no depth layering — nothing in the near foreground and/or nothing on the horizon, so the subject sits alone on a large empty plane.+ text: An authored shot that frames the place at distance has the subject alone on a large undressed plane — the space between the camera and the subject, and beyond it, is empty of anything the place would have there.penalty: 0.04+ - id: diorama_look+ text: >+ The scene is a compact block of content in the middle of a flat plate, ringed all round by+ one uniform backdrop (identical hills / trees / silhouettes at one radius) with nothing+ continuing beyond — a model on a table rather than a place that goes on. Cite the view+ that shows the plate's edge or the ring.+ penalty: 0.05- id: undressed_scene- text: The place has no small props or clutter (pebbles, leaves, tools, cups, cables, litter, ground cover) — it looks like a showroom of a few large objects.+ text: The place lacks the secondary detail its brief implies and reads as a showroom of a few large objects.penalty: 0.03- id: thin_atmosphere- text: No visible aerial perspective — distant things are as saturated and contrasty as near things, there is no haze/fog falloff, and the key and fill light share one hue.+ text: In a shot with real distance, far things are as saturated and contrasty as near things although the brief's weather would soften them.penalty: 0.03# The scene_placement gate (spatial/scene_placement.py) measures every placed asset's footdiff --git a/harness/codeverse3d/languages/scene_blender/__init__.py b/harness/codeverse3d/languages/scene_blender/__init__.pyindex 1cafadad..db23734f 100644--- a/harness/codeverse3d/languages/scene_blender/__init__.py+++ b/harness/codeverse3d/languages/scene_blender/__init__.py@@ -17,6 +17,8 @@ from __future__ import annotationsimport astimport json+import math+import reimport timefrom collections.abc import Sequencefrom pathlib import Path@@ -361,7 +363,8 @@ def _exports(tree: ast.Module, *, target: str, role: str) -> list[GateFinding]:stem = Path(target).stemneed = {"zone": ("build", "build(ctx) -> bpy.types.Collection: link everything into ctx.collection and return it"),"asset": (f"build_{stem}", f"build_{stem}(ctx, variant=0) -> bpy.types.Collection, built at the origin, base on z = 0"),- "env": ("build_env", "build_env(ctx) -> dict: world, sun, ground, atmosphere")}.get(role)+ "env": ("build_env", "build_env(ctx) -> dict: the environment the plan describes (world / lighting / ground or "+ "floor / atmosphere as the brief needs); zones read the returned dict as ctx.env")}.get(role)out = []if need and need[0] not in defs:out.append(_f(LintKind.LAYOUT, Severity.ERROR, f"{target} defines no `{need[0]}`", None, f"define {need[1]}", target))@@ -458,62 +461,84 @@ def _v(v: Sequence[float], *, extents: bool = False) -> tuple[float, float, floareturn tuple(round(c, 3) for c in to_authoring_frame(v, LANGUAGE.value, extents=extents)) # type: ignore[return-value]+#: the placeholder plate's side as a multiple of the plan span (the three.js skeleton's+#: ``PLACEHOLDER_GROUND_SPANS``): past the 2 × span the ``fog_short`` gate measures once the author's+#: atmosphere is in, so no authored camera reads a plate edge before the land is built. No+#: minimum world size.+PLACEHOLDER_GROUND_SPANS = 3.0++def _env_source(plan: ScenePlan) -> str:- """``src/env.py`` built FROM the library: the ground function, the sky, the sun, the ground- mesh, the fog box and — for an interior — the room shell and its ceiling light."""+ """``src/env.py`` as an interface stub: the plan's data (bounds, interior, glazed, the sun the+ plan states), the two exports the wrapper calls, and a PLACEHOLDER body that builds ONE thing —+ a level plate named Ground past the plan span — and no world, no lamp, no atmosphere: as+ written the stub FAILS the probe (no world / no atmosphere) and the frame gate (black frames)+ until the author writes the brief's. It used to be a finished landscape (a level pad of the+ bounds' half-span + 15 m, fbm hills beyond, a mossy ground, a fog box, a room shell with one+ ceiling light): 30 of 30 iteration-0 scenes kept its shape; then a passing placeholder (a+ neutral sun at 45° / 35°, a haze) that any brief could keep for the same reason (the+ de-templating of 2026-10-15)."""+ from codeverse3d.languages.scene_threejs import sun_from_plan+c, e = _v(plan.bounds.center), _v(plan.bounds.extents, extents=True)- span = max(e[0], e[1], 40.0)- ground = round(max(120.0, span * 2.5), 1)- # level ground wherever the plan put its cameras (z ≈ 0 inside the bounds), gentle hills beyond- flat = round(max(45.0, span / 2 + 15.0), 1)- fog_h = round(max(e[2] * 2.0, 20.0), 1)+ span = max(e[0], e[1], 1.0)+ ground = round(span * PLACEHOLDER_GROUND_SPANS, 1)interior = "True" if plan.interior else "False"glazed = bool(getattr(plan, "glazed", False))- room_energy = round(40.0 * e[0] * e[1], 1)- return f'''"""src/env.py — the environment: world (sky), sun, ground, atmosphere{", enclosure" if plan.interior else ""}.+ az, el = sun_from_plan(plan)+ az_line = (f"SUN_AZIMUTH_DEG = {az:g} # the plan's light: compass 0 = +X, 90 = +Y (the sky and the lamp share it; zones may import it)"+ if az is not None else+ "SUN_AZIMUTH_DEG = None # the plan states no azimuth: set the brief's (compass 0 = +X, 90 = +Y; zones may import it)")+ el_line = (f"SUN_ELEVATION_DEG = {el:g}" if el is not None else "SUN_ELEVATION_DEG = None # the plan states none: set the brief's")+ return f'''"""src/env.py — the environment: the ground every zone seats on, the light, the sky / backdrop, the+atmosphere{" and the enclosure" if plan.interior else ""}.ENV PLAN: {plan.environment.strip()}setting: {plan.setting.strip()} mood: {plan.mood.strip()}-Frame: Z up, -Y front, metres. BOUNDS below are the plan's, in this frame.-CONTRACT: height_at(x, y) -> z is THE ground: the terrain mesh and every zone's seat use it.- build_env(ctx) -> dict builds the world, lamps, ground and atmosphere into ctx.collection and returns- what zones may share (materials, water level, sun direction ...) — they read it as ctx.env.- Everything below is built from src/lib (lib.terrain / lib.sky / lib.lighting / lib.materials /- lib.architecture — see the effects catalog): rewrite the sky / sun / ground / fog to match the- plan; keep build_env and height_at.+Frame: Z up, -Y front, metres. BOUNDS below are the plan's, in this frame: the extent of the PLANNED+content and the cameras' subject, not the edge of the world — land, backdrop and scenery continue beyond+it as the brief implies.+CONTRACT (the wrapper calls exactly these two):+ height_at(x, y) -> z: the ONE ground function — the ground mesh samples it and every zone seats on it+ (measured: scene_placement floating > 0.05 m outdoors / 0.02 m indoors, sunken > 0.10 m); the plan's+ cameras expect the ground near their look_at at the height the plan states, and each eye above it+ (camera_underground, cap 0.50).+ build_env(ctx) -> dict: builds the world, the lamps, the ground and the atmosphere the plan describes into+ ctx.collection and returns what zones may share (materials, water level, sun direction ...) — ctx.env to them.+MEASURED: a world exists and an atmosphere exists — a world Volume or a bounded fog volume (no_fog, ERROR) —+ with 1 / density >= the plan span / 1.5 (fog_short); the judged frames sit in the exposure band+ (scene_frames: dark_frame / blown_frame / flat_frame); whatever the zones seat on is named Ground... /+ Terrain... (the census finds the ground by name and shape); backdrop geometry is named Sky...; no world+ edge in any authored frame (judged; the census: standing geometry past 1.25 x the bounds' half-extent).+PLACEHOLDER below: ONE level plate named Ground past the plan span, so the census has a surface — and NO+ world, NO lamp, NO atmosphere: as written this module fails the probe and renders black until build_env+ builds the brief's. The landform, the sky, the light and the atmosphere are yours. Raw bpy / bmesh is the+ baseline; src/lib (terrain / sky / lighting / materials / architecture / water ... — the effects catalog) is+ an OPTIONAL toolbox. Keep build_env and height_at."""-from lib import architecture, lighting, materials, sky, terrain+from lib import materials, terrain # the optional toolbox (the placeholder uses two of its calls)BOUNDS = {{"center": ({fmt3(c)}), "extents": ({fmt3(e)})}}-INTERIOR = {interior}-GLAZED = {glazed} # a glass house: the shell's walls and lid are panes on an iron frame-GROUND_SIZE = {ground}-FLAT_RADIUS = {flat} # level ground for the plan's cameras (z = 0); the hills start beyond it-SUN_AZIMUTH_DEG = 45.0 # compass angle of the sun: 0 = +X, 90 = +Y (the sky and the lamp share it)-SUN_ELEVATION_DEG = 35.0+INTERIOR = {interior} # the plan's: an interior needs the enclosure the brief describes (openings, materials as+ # named; it reads black without openings or practical lights); lib.architecture.room_shell is one way+GLAZED = {glazed} # the plan says the enclosure is glazed; its construction is the brief's+GROUND_SIZE = {ground} # the placeholder plate's side (m): 3 x the plan span, past the reach the fog gate measures+{az_line}+{el_line}SEED = 0-_RELIEF = terrain.make_height_at(seed=SEED, relief=0.0 if INTERIOR else 2.5, scale=60.0, flat_radius=FLAT_RADIUS)def height_at(x, y):- """z of the ground at (x, y) — level inside FLAT_RADIUS, rolling beyond (the ground mesh follows)."""- return _RELIEF(x, y)+ """z of the ground at (x, y): the one function every zone seats on and the ground mesh follows. PLACEHOLDER: level."""+ return 0.0def build_env(ctx):- sky.sun_world(ctx.scene, elevation_deg=SUN_ELEVATION_DEG, azimuth_deg=SUN_AZIMUTH_DEG, strength=0.4, dust=1.5)- _, towards_sun = lighting.sun(ctx.collection, azimuth_deg=SUN_AZIMUTH_DEG, elevation_deg=SUN_ELEVATION_DEG, energy=3.0)- ground_mat = materials.material("GroundMat", "4A5A3A", roughness=0.9, noise_scale=6.0)- terrain.ground("Ground", ctx.collection, size=GROUND_SIZE, segments=96, height_at=height_at, material=ground_mat)- (cx, cy, cz), (ex, ey, ez) = BOUNDS["center"], BOUNDS["extents"]- if INTERIOR:- # the shell sits 1 cm above the ground so its floor never z-fights the terrain- architecture.room_shell(ctx.collection, materials.material("WallMat", "B8AE9A", roughness=0.85),- center=(cx, cy, cz + 0.01), extents=(ex, ey, ez), glazed=GLAZED)- lighting.area_light(ctx.collection, "CeilingLight", (cx, cy, cz + ez / 2 - 0.05), "FFF1DC", {room_energy},- size=max(0.5, min(ex, ey) * 0.5), target=(cx, cy, cz - ez / 2))- sky.haze(ctx.collection, (cx, cy, {fog_h / 2}), (GROUND_SIZE, GROUND_SIZE, {fog_h}), density={0.001 if plan.interior else 0.002})- return {{"ground_material": ground_mat, "sun_direction": tuple(towards_sun)}}+ # PLACEHOLDER ground: a level plate following height_at — REPLACE with the brief's land (named Ground... / Terrain...)+ ground_mat = materials.material("GroundMat", "6F6A60", roughness=0.95)+ terrain.ground("Ground", ctx.collection, size=GROUND_SIZE, segments=32, height_at=height_at, material=ground_mat)+ # NO world, lamp or atmosphere here: the brief's go in this function (the docstring says what is measured)+ return {{"ground_material": ground_mat}}'''@@ -526,16 +551,18 @@ def _asset_source(a: AssetPlan) -> str:approx size {w:g} x {d:g} x {h:g} m (x = width, y = depth, z = height); expected instances: ~{a.instances_hint}CONTRACT: build_{snake}(ctx, variant=0) -> bpy.types.Collection — link every part into ctx.collection(named '{pascal}'), built ONCE at the origin with its base on z = 0, front facing -Y. Zones place- collection instances of it (ctx.assets['{snake}']); never link it anywhere else.+ collection instances of it (ctx.assets['{snake}']); link it nowhere else. It must read as the plan+ describes it at the judge's camera distance (judged) and measure about the size above (the asset check);+ parts, materials and construction are yours."""-from lib.materials import material-from lib.mesh import Batch+from lib.materials import material # optional toolbox: the placeholder uses it+from lib.mesh import Batch # optional: one way to build multi-material parts (raw bmesh is equally fine)def build_{snake}(ctx, variant=0):mat = material("{pascal}Mat", ({fmt3(rgb)}), roughness={rough}, metal={metal})- # PLACEHOLDER blockout at the planned size — REPLACE with the real construction: several parts- # in a Batch (one mesh per material, lib.mesh), base on z = 0, front facing -Y.+ # PLACEHOLDER blockout at the planned size — REPLACE with the real thing (a single box fails the asset check);+ # base on z = 0, front facing -Y.b = Batch("{pascal}")b.box(mat, (0.0, 0.0, {h / 2:g}), ({w:g}, {d:g}, {h:g}))b.finish(ctx.collection, parent=False)@@ -543,44 +570,41 @@ def build_{snake}(ctx, variant=0):'''-def _zone_source(z: ZonePlan, assets: dict[str, AssetPlan], counters: dict[str, int]) -> str:- """A zone stub placing each planned asset once; ``counters`` numbers the placed copies across- zones, because a Blender object name is global (a second ``Lantern_0`` would be ``Lantern_0.001``)."""+def _zone_source(z: ZonePlan, assets: dict[str, AssetPlan]) -> str:+ """The zone's interface and a TODO naming the plan's contents — no positions. The stub used to+ tile the contents on a quarter-extent grid inside the bbox and say "keep them inside the bbox":+ the seed of the blocks-in-a-rectangle look (the de-templating of 2026-10-15)."""snake, pascal = to_snake(z.name), to_pascal(z.name)c, e = _v(z.bbox.center), _v(z.bbox.extents, extents=True)- places = []- for i, name in enumerate(z.contents):+ todo = []+ for name in z.contents:a = assets.get(to_snake(name))if a is None:- continue- ox = (-e[0] / 4 + (i % 3) * e[0] / 4) if len(z.contents) > 1 else 0.0- oy = (-e[1] / 4 + (i // 3) * e[1] / 4) if len(z.contents) > 3 else 0.0- n = counters.get(to_snake(a.name), 0)- counters[to_snake(a.name)] = n + 1- places.append(f' place(ctx, "{to_snake(a.name)}", "{to_pascal(a.name)}_{n}", {round(c[0] + ox, 2)}, {round(c[1] + oy, 2)})')- body = "\n".join(places) or " pass # TODO: build this zone's content (seat everything with ctx.height_at(x, y))"+ todo.append(f" - {name}: not an asset of the plan — built here")+ elif a.kind == "blender_glb":+ todo.append(f" - {a.name}: ctx.assets['{to_snake(a.name)}'] — the hero GLB public/assets/{to_snake(a.name)}.glb imported by the harness")+ else:+ todo.append(f" - {a.name}: ctx.assets['{to_snake(a.name)}'] — built by src/assets/{to_snake(a.name)}.py; ~{a.instances_hint} planned")+ todo_block = "\n".join(todo) if todo else " (the plan lists no contents)"return f'''"""src/zones/{snake}.py — zone "{pascal}": {z.description.strip()}-PLAN bbox (Z up, -Y front, metres): centre ({fmt3(c)}) extents ({fmt3(e)}). Contents: {", ".join(z.contents) or "-"}-CONTRACT: build(ctx) -> bpy.types.Collection — ctx.collection is this zone's (named '{pascal}', active);- every PLACED thing is ONE root object in it, named <Name>_<i> (object names are global in- Blender: never reuse one another zone uses). Seat things on ctx.height_at(x, y) — lib.scatter- instances and lib.place.seat do — and keep them inside the bbox. Assets: a collection-instance- Empty of ctx.assets['<snake>'] (lib.scatter.instance). Animation is data: lib.motion.+PLAN bbox (Z up, -Y front, metres): centre ({fmt3(c)}) extents ({fmt3(e)}).+CONTRACT: build(ctx) -> bpy.types.Collection — ctx.collection is this zone's (named '{pascal}', active): link+ everything into it and return it. Every PLACED thing is ONE root object in it, named <Name>_<i> (object+ names are global in Blender: never reuse one another zone uses). Seat things on ctx.height_at(x, y)+ (measured: scene_placement floating > 0.05 m outdoors / 0.02 m indoors, sunken > 0.10 m). The planned+ contents are measured against the plan bounds and this bbox (scene_placement: present, at the plan's size,+ not outside the bounds); scenery may continue past the bbox as the brief implies.+ Assets: ctx.assets['<snake>'] is a Collection — place collection-instance Empties of it (lib.scatter.instance+ seats one on ctx.height_at; one way among others). Animation: keyframes or simple drivers (the build samples+ frames 1 and 46 = t 0 / 1.5 s; motion between them is measured); lib.motion is an optional helper.+TODO — this zone's planned contents, none placed yet:+{todo_block}"""-from lib.scatter import instance---def place(ctx, key, name, x, y, rot_z=0.0):- """One placed copy of asset `key`: a collection-instance Empty seated on ctx.height_at."""- source = ctx.assets.get(key)- if source is None:- return None- return instance(ctx.collection, source, name, x, y, height_at=ctx.height_at, rot_z=rot_z)def build(ctx):-{body}+ # TODO: build the contents listed above (seat everything with ctx.height_at)return ctx.collection'''@@ -630,9 +654,8 @@ def write_skeleton(ws: Workspace, plan: Plan | None = None) -> list[Path]:for a in plan.assets:if a.kind != "blender_glb":_put(ws.root / asset_file(a), _asset_source(a), written)- counters: dict[str, int] = {}for z in plan.zones:- _put(ws.root / zone_file(z.name), _zone_source(z, assets, counters), written)+ _put(ws.root / zone_file(z.name), _zone_source(z, assets), written)_put(ws.root / ENTRY_REL, render_scene_py([to_snake(z.name) for z in plan.zones],[to_snake(a.name) for a in plan.assets if a.kind != "blender_glb"], [],list(plan.cameras[:6]), title=plan.title, summary=plan.summary), written)@@ -656,13 +679,30 @@ class WrapperRun(BaseModel):facts: dict[str, Any] = Field(default_factory=dict)-def _fallback_camera(plan: ScenePlan | None) -> CameraPlan:+_SUN_RE = re.compile(r"^SUN_AZIMUTH_DEG\s*=\s*(-?\d+(?:\.\d+)?)", re.M)+++def _fallback_camera(plan: ScenePlan | None, ws: Workspace | None = None) -> CameraPlan:+ """An overview when the plan names no camera (the schema requires one, so this is the plan-less+ path): in the PLAN frame (Y up), on the lit side — the env's ``SUN_AZIMUTH_DEG`` (compass 0 = +X,+ 90 = +Y in this language's Z-up frame, i.e. -Z in the plan's), the rig's 45° guess without one —+ at the bounds' span from their centre; derived, never a fixed corner."""+ from codeverse3d.languages.scene_threejs import SUN_AZIMUTH_GUESS_DEG++ azimuth = SUN_AZIMUTH_GUESS_DEG+ env = (ws.src / "env.py") if ws is not None else None+ if env is not None and env.is_file():+ m = _SUN_RE.search(env.read_text(errors="replace"))+ if m:+ azimuth = float(m.group(1))if plan is None:- return CameraPlan(name="overview", position=(30.0, 18.0, 30.0), look_at=(0.0, 1.0, 0.0), fov=50.0)- c, e = plan.bounds.center, plan.bounds.extents- r = max(e[0], e[2], 10.0)- return CameraPlan(name="overview", position=(c[0] + 0.8 * r, c[1] + 0.5 * r, c[2] + 0.8 * r), look_at=c, fov=50.0,- purpose="fallback: the plan names no camera")+ c, r = (0.0, 0.0, 0.0), 30.0+ else:+ c = tuple(float(v) for v in plan.bounds.center)+ r = max(float(plan.bounds.extents[0]), float(plan.bounds.extents[2]), 10.0)+ a = math.radians(azimuth)+ return CameraPlan(name="overview", position=(c[0] + 0.9 * r * math.cos(a), c[1] + 0.45 * r, c[2] - 0.9 * r * math.sin(a)),+ look_at=(c[0], c[1] + 1.0, c[2]), fov=50.0, purpose="fallback: the plan names no camera")class AssembleResult(BaseModel):@@ -867,7 +907,7 @@ def assemble(runtime: SceneBlenderRuntime, ws: Workspace, plan: ScenePlan | Noneraise FileNotFoundError(f"no zone modules under {ws.src / 'zones'}")assets = [p.stem for p in module_files(ws, "assets")]heroes = [p.stem for p in hero_files(ws)]- cams = list(plan.cameras[:6]) if plan is not None and plan.cameras else [_fallback_camera(plan)]+ cams = list(plan.cameras[:6]) if plan is not None and plan.cameras else [_fallback_camera(plan, ws)]warnings: list[str] = []env_ok = (ws.src / "env.py").is_file()if not env_ok:diff --git a/harness/codeverse3d/languages/scene_blender/starter/src/env.py b/harness/codeverse3d/languages/scene_blender/starter/src/env.pyindex 28134f45..bcdc0497 100644--- a/harness/codeverse3d/languages/scene_blender/starter/src/env.py+++ b/harness/codeverse3d/languages/scene_blender/starter/src/env.py@@ -1,5 +1,5 @@-"""src/env.py — the environment of the example scene: a low warm sun, rolling meadow beyond a-level play area, a lake basin, haze.+"""src/env.py — the environment of the EXAMPLE scene (a lakeside hamlet): a low warm sun, rolling+meadow beyond a level pad, a lake basin, haze. The landform is this example's, not a rule.Frame: Z up, -Y front, metres.CONTRACT: height_at(x, y) -> z is THE ground: the terrain mesh and every zone's seat use it.@@ -13,7 +13,7 @@ import mathfrom lib import lighting, materials, sky, terrainGROUND_SIZE = 160.0-FLAT_RADIUS = 48.0 # level ground under the cameras (z = 0); gentle hills beyond+FLAT_RADIUS = 48.0 # THIS example's landform: level under its hamlet, hills beyond — one landform among many; yours is the brief'sSUN_AZIMUTH_DEG = 215.0 # compass angle of the sun: 0 = +X, 90 = +Y (the sky and the lamp share it)SUN_ELEVATION_DEG = 22.0BASIN = (-24.0, 2.0, 15.0, 1.2) # the lake's (x, y, radius, depth): zones/lakeside.py fills it to WATER_LEVELdiff --git a/harness/codeverse3d/languages/scene_blender/starter/src/lib/architecture.py b/harness/codeverse3d/languages/scene_blender/starter/src/lib/architecture.pyindex 03cae71d..d0e45a76 100644--- a/harness/codeverse3d/languages/scene_blender/starter/src/lib/architecture.py+++ b/harness/codeverse3d/languages/scene_blender/starter/src/lib/architecture.py@@ -1,12 +1,10 @@"""lib/architecture.py — buildings, bridges, roofs, paving, room shells and signs.-Batch recipes stand on the ground z you pass (``center`` = (x, y, ground z), pass-``height_at(x, y)``); the ridge / long axis runs along +X unless a ``direction`` says-otherwise (compass degrees: 0 = +X, 90 = +Y, for a window's outward normal). Paving is 2 cm-thick so a prop seated on ``height_at`` still reads as resting on it (the gate's contact-tolerance). ``room_shell`` is for ``src/env.py``: it names the lid ``Ceiling`` under a-``RoomShell`` root so the overview rig can lift it; ``glazed=True`` makes it a glass house (glass-panes on an iron-frame grid, the sun coming through).+Batch recipes stand on the ground z you pass (``center`` = (x, y, ground z), pass ``height_at(x, y)``);+the ridge / long axis runs along +X unless a ``direction`` says otherwise (compass degrees: 0 = +X,+90 = +Y, for a window's outward normal). Paving is 2 cm thick so a prop seated on ``height_at`` still+reads as resting on it (the gate's contact tolerance). ``room_shell`` (one enclosure, for ``src/env.py``)+names the lid ``Ceiling`` under a ``RoomShell`` root so the overview rig can lift it."""from __future__ import annotations@@ -24,7 +22,7 @@ from lib.noise import hash01Vec3 = tuple[float, float, float]_WALLS = ("front", "back", "left", "right")-_BAY, _BAR, _PANE = (1.6, 1.6, 2.4), 0.08, 0.02 # a glazed shell's frame spacing per world axis, bar section, glass (m)+_BAY, _BAR, _PANE = (1.6, 1.6, 2.4), 0.08, 0.02 # a glazed room_shell's default frame rhythm per world axis, bar section, glass (m)def _yaw(direction_deg: float) -> Matrix:@@ -278,7 +276,7 @@ def arched_footbridge(batch: Any, wood: Any, stone: Any, *, start: Sequence[floaheight_at: Any = None) -> None:"""A wooden footbridge arching ``rise`` m from ``start`` to ``end`` (x, y, ground z): planks,rails on posts, stone abutments standing on the two ground points (their corners follow- ``height_at`` when given — a bank is never level). ~1.5 k triangles."""+ ``height_at`` when given — banks are rarely level). ~1.5 k triangles."""a, b = Vector(tuple(float(v) for v in start)), Vector(tuple(float(v) for v in end))d = b - aL = max(0.5, d.length)@@ -368,16 +366,18 @@ def _slab(name: str, collection: Any, mat: Any, loc: Sequence[float], size: Sequdef room_shell(collection: Any, mat: Any, *, center: Sequence[float], extents: Sequence[float], thickness: float = 0.2,openings: Sequence[Sequence[Any]] = (), glazed: bool = False) -> list[Any]:- """An interior's floor, four walls and ceiling OUTSIDE the box ``center`` / ``extents``- (inner faces = the box faces), under a root Empty ``RoomShell`` with the lid named- ``Ceiling`` (the overview rig lifts it). ``openings`` = ``(wall, offset, width, sill, head)``- rows — ``wall`` front/back/left/right (front = -Y), ``offset`` along the wall from its- centre, ``sill``/``head`` heights above the floor — cut as panels, no booleans. ``glazed``- makes a glass house (a conservatory, a greenhouse, a glass atrium): every wall panel and the- lid become a ``materials.glass`` pane that casts no shadow on an iron-frame grid of ``mat``- bars (the sun comes through, the frame's grid shadows the floor); the floor stays an opaque- slab of ``mat`` and the names stay, a pane being its panel's name + ``Glass``. Returns- ``[root, floor, ceiling, walls…]`` (glazed: each panel's frame then its pane); for ``src/env.py``."""+ """One enclosure: a rectangular room whose inner faces are the box ``center`` / ``extents`` (floor,+ four walls and lid built OUTSIDE it) under a root Empty ``RoomShell``, the lid named ``Ceiling`` (the+ overview rig lifts it) — for ``src/env.py``. Measured for ANY interior: it reads enclosed in the judged+ frames (the finding is "not enclosed, a diorama on a flat plane"), nothing seats inside a wall+ (placement gate), the lid is ``Ceiling`` under ``RoomShell``; a nave, a vault or an L-shaped loft is+ built by hand to the same names. ``openings`` = ``(wall, offset, width, sill, head)`` rows — ``wall``+ front/back/left/right (front = -Y), ``offset`` along the wall from its centre, ``sill``/``head`` above+ the floor — cut as panels, no booleans. ``glazed`` makes a glass house: every wall panel and the lid+ become a ``materials.glass`` pane casting no shadow on an iron-frame grid of ``mat`` bars (``_BAY`` /+ ``_BAR`` rhythm; the sun comes through, the grid shadows the floor); the floor stays opaque ``mat``, a+ pane is its panel's name + ``Glass``. Returns ``[root, floor, ceiling, walls…]`` (glazed: each panel's+ frame then its pane)."""cx, cy, cz = (float(v) for v in center)ex, ey, ez = (float(v) for v in extents)t = float(thickness)diff --git a/harness/codeverse3d/languages/scene_blender/starter/src/lib/sky.py b/harness/codeverse3d/languages/scene_blender/starter/src/lib/sky.pyindex 70a6524d..b7a1d7e7 100644--- a/harness/codeverse3d/languages/scene_blender/starter/src/lib/sky.py+++ b/harness/codeverse3d/languages/scene_blender/starter/src/lib/sky.py@@ -42,9 +42,11 @@ def _fresh_world(scene: Any, name: str) -> tuple[Any, Any, Any, Any]:def sun_world(scene: Any, *, elevation_deg: float = 12.0, azimuth_deg: float = 125.0, strength: float = 0.2,dust: float = 2.0) -> Any:"""A physical sky (MULTIPLE_SCATTERING) lit from compass ``azimuth_deg`` (0 = +X, 90 = +Y —- pass the same numbers to ``lighting.sun``) at ``elevation_deg``; ``strength`` is the world's- Background strength (0.2-0.5 by day: the sky is bright), ``dust`` the aerosol density- (1 = clear, 2-4 hazy, warm low sun). The sun disc is off: the Sun lamp casts the shadows."""+ the same numbers as ``lighting.sun``, so the sky's bright side and the shadows agree) at+ ``elevation_deg``; ``strength`` is the world's Background strength, ``dust`` the aerosol+ density (1 clear, 2-4 hazy). The defaults are a hazy low afternoon — pass the brief's time+ of day and weather; strength and dust together decide where a day frame lands in the judged+ luminance band. The sun disc is off: the Sun lamp casts the shadows."""world, nodes, links, bg = _fresh_world(scene, "Sky")sky = nodes.new("ShaderNodeTexSky")sky.sky_type = "MULTIPLE_SCATTERING"@@ -58,7 +60,9 @@ def sun_world(scene: Any, *, elevation_deg: float = 12.0, azimuth_deg: float = 1def night_world(scene: Any, color: str | Sequence[float] = "17273F", strength: float = 0.3) -> Any:- """A flat night sky in ``color`` (a deep blue, never black: AgX needs something to lift)."""+ """A flat night world in ``color``. A black world fails the judged luminance floor (AgX has+ nothing to lift); give it the brief's colour with some value — deep blue, sodium amber,+ moonlit grey."""world, _, _, bg = _fresh_world(scene, "NightSky")bg.inputs["Color"].default_value = _rgb(color)bg.inputs["Strength"].default_value = float(strength)@@ -111,10 +115,12 @@ def gradient_world(scene: Any, stops: Sequence[tuple[float, str | Sequence[floatdef haze(collection: Any, loc: Sequence[float], size: float | Sequence[float], density: float = 0.003,color: str | Sequence[float] = "ADC9E1", name: str = "Atmosphere") -> Any:- """A bounded fog volume: a box centred at ``loc`` of ``size`` m whose only material is a- Principled Volume (``density`` per metre: 0.002 clear valley air, 0.01 morning mist, 0.03- a dense fog bank). Volume-only, so the census reports it as fog, not matter; a world- volume over a large scene swallows the sun — this stays over the play area."""+ """A bounded fog volume: a box centred at ``loc`` of ``size`` m (a number, or (x, y, z))+ whose only material is a Principled Volume (``density`` per metre: 0.002 clear valley air,+ 0.01 morning mist, 0.03 a dense fog bank). Volume-only, so the census reports it as fog,+ not matter. A box rather than a world volume because a world volume over a large scene+ swallows the sun (whether the sun still reaches the frame shows in the luminance band);+ size and place it for the brief — a valley floor, a riverbank, the whole site."""sx, sy, sz = (size, size, size) if isinstance(size, (int, float)) else sizehx, hy, hz = sx / 2, sy / 2, sz / 2cx, cy, cz = (float(v) for v in loc)diff --git a/harness/codeverse3d/languages/scene_blender/starter/src/lib/terrain.py b/harness/codeverse3d/languages/scene_blender/starter/src/lib/terrain.pyindex ef5c22fb..cbebcc2c 100644--- a/harness/codeverse3d/languages/scene_blender/starter/src/lib/terrain.py+++ b/harness/codeverse3d/languages/scene_blender/starter/src/lib/terrain.py@@ -1,10 +1,11 @@"""lib/terrain.py — the ground and the rock that sits on it.-``make_height_at`` is THE ground function: the env's ``height_at`` returns it, the ground mesh-samples it, every zone seats on it (``place.seat`` / ``scatter.instance``). Level inside-``flat_radius`` (the plan's cameras were written for z ≈ 0 there), rolling beyond, so nothing-in the play area tilts. Batch recipes (``boulder``, ``talus``, ``basalt_column`` …) stand-their lowest vertex ON the ``center`` z you pass — pass ``height_at(x, y)``.+INTERFACE: ``src/env.py`` exports ``height_at(x, y) -> z``, the one ground truth the zones,+``place.seat`` / ``scatter.instance`` and the placement gate sample. Any function with that+signature qualifies — a slope, a terrace, a valley floor, a riverbed, whatever land the brief+describes; ``make_height_at`` below is one optional landform, not the ground. Batch recipes+(``boulder``, ``talus``, ``basalt_column`` …) stand their lowest vertex ON the ``center`` z you+pass — pass ``height_at(x, y)``."""from __future__ import annotations@@ -24,29 +25,39 @@ def _smoothstep(e0: float, e1: float, x: float) -> float:return t * t * (3.0 - 2.0 * t)-def make_height_at(*, seed: int = 0, relief: float = 3.0, scale: float = 60.0, flat_radius: float = 45.0,+def make_height_at(*, seed: int = 0, relief: float = 3.0, scale: float = 60.0, flat_radius: float = 0.0,base: float = 0.0) -> HeightFn:- """A ground function: ``base`` within ``flat_radius`` m of the origin, hills of up to- ``relief`` m with features ``scale`` m wide beyond it (blended in over ``scale`` m, so the- rim slopes under 5 % at the defaults)."""+ """One landform among many: rolling fbm hills of up to ``relief`` m above ``base`` with+ features ``scale`` m wide, and — only when asked — a level pad within ``flat_radius`` m of+ the origin (0 = no pad; the hills blend in over ``scale`` m beyond it). Whether a pad+ exists, where it sits and what the land does beyond it is the brief's: for a slope, a+ terrace, a ridge, a riverbed, write your own ``height_at`` — only the signature is the+ contract. What is measured: every seated object rests on ``height_at`` within the placement+ gate's contact tolerance, and a camera's eye stays above the ground under it (the frame+ gate's ``camera_underground``) — lift the camera, not the land."""blend = max(1.0, scale)+ pad = max(0.0, float(flat_radius))def height_at(x: float, y: float) -> float:+ n = 0.5 + 0.5 * fbm2(x / scale, y / scale, octaves=4, seed=seed)+ if pad <= 0.0:+ return base + relief * nr = math.hypot(x, y)- if r <= flat_radius:+ if r <= pad:return base- t = _smoothstep(flat_radius, flat_radius + blend, r)- n = 0.5 + 0.5 * fbm2(x / scale, y / scale, octaves=4, seed=seed)- return base + t * relief * n+ return base + _smoothstep(pad, pad + blend, r) * relief * nreturn height_atdef ground(name: str, collection: Any, *, size: float | Sequence[float], segments: int, height_at: HeightFn,material: Any, center: Sequence[float] = (0.0, 0.0), smooth: bool = True) -> Any:- """The terrain mesh: a ``size`` m grid of ``segments`` cells (96 for a 120-200 m ground)- following ``height_at``. Name it ``Ground…`` / ``Terrain…``: the census classifies the- ground by name and shape, and the placement gate seats on it."""+ """The terrain mesh: a ``size`` m grid (a number, or (x, y)) of ``segments`` cells around+ ``center`` following ``height_at``. Extent, shape and resolution are the brief's, within+ the triangle budget (2 x ``segments`` ** 2); what is measured is that no authored camera sees+ a hard world edge, a terrain cliff or a missing horizon (rubric ``world_edge_visible``), so+ the ground reaches whatever closes the view. Name it ``Ground…`` / ``Terrain…``: the census+ classifies the ground by name and shape, and the placement gate seats on it."""sx, sy = (float(size), float(size)) if isinstance(size, (int, float)) else (float(size[0]), float(size[1]))n = max(1, int(segments))cx, cy = float(center[0]), float(center[1])diff --git a/harness/codeverse3d/languages/scene_threejs/__init__.py b/harness/codeverse3d/languages/scene_threejs/__init__.pyindex 5d6c9ddc..8b3ae429 100644--- a/harness/codeverse3d/languages/scene_threejs/__init__.py+++ b/harness/codeverse3d/languages/scene_threejs/__init__.py@@ -2,6 +2,7 @@from __future__ import annotations+import mathimport reimport timefrom collections.abc import Sequence@@ -157,18 +158,18 @@ def lint(ws: Workspace) -> GateReport:hint="export function buildLamp(THREE) { ... return group; }"))for b in big:findings.append(_f(LintKind.LAYOUT, Severity.WARN, f"large file {b} > {MAX_LINES} lines", target=b.split(" ")[0],- hint="split into zones/assets/shaders modules"))+ hint="a file over 800 lines is reported; how (or whether) to split it is yours"))return GateReport.of(GATE, findings, duration_ms=int((time.time() - t0) * 1000))# ===================================================================== skeletonSTARTER_DIR = Path(__file__).resolve().parent / "starter" / "src"-#: pattern files copied verbatim in plan mode (shown as reusable examples)-PATTERN_FILES = ("shaders/water.js", "assets/pine_tree.js", "assets/windmill.js")-#: the harness-owned effect library (``src/lib/*.js``), shipped into EVERY workspace.-#: Plan mode copied only PATTERN_FILES, so a planned run got the effects catalog in its-#: prompt and no ``src/lib/`` to import from — every ``from './lib/grass.js'`` a 2026-09-01-#: agent wrote would have been a build error. Both skeleton paths write it now.+#: the harness-owned effect library (``src/lib/*.js``), shipped into EVERY workspace by both+#: skeleton paths (a planned run once got the effects catalog in its prompt and no ``src/lib/``+#: to import from — every ``from './lib/grass.js'`` a 2026-09-01 agent wrote was a build error).+#: The example scene's own files (``zones/``, ``assets/``, ``shaders/``) ship ONLY without a plan:+#: a planned workspace used to carry a pine tree, a windmill and a pond shader whatever the brief,+#: and its stubs cited them as the pattern (the de-templating of 2026-10-15).LIB_DIR = STARTER_DIR / "lib"@@ -209,27 +210,113 @@ def write_example(ws: Workspace) -> list[Path]:return written+#: the stub plate's side as a multiple of the plan span: its edge then sits 1.5 spans from the+#: centre — past the 2 × span the ``fog_short`` gate measures once the author's fog is in — so no+#: authored camera reads a plate edge before the land is built. Derived from the plan alone: no+#: minimum world size.+PLACEHOLDER_GROUND_SPANS = 3.0++_AZIMUTH_RE = re.compile(r"azimuth[^0-9\-]{0,12}(-?\d+(?:\.\d+)?)", re.I)+_ELEVATION_RE = re.compile(r"elevation[^0-9\-]{0,12}(-?\d+(?:\.\d+)?)", re.I)+#: the overview rig's own guess when a scene states no sun azimuth (``sun_azimuth`` below)+SUN_AZIMUTH_GUESS_DEG = 45.0+++def sun_from_plan(plan: ScenePlan) -> tuple[float | None, float | None]:+ """The sun azimuth and elevation (degrees) the plan's ``environment`` paragraph states+ ("sun azimuth 250° elevation 8°"), ``None`` for each it does not: the skeleton carries the+ PLAN's light into the env stub rather than a light of its own (the de-templating of+ 2026-10-15: a hardcoded azimuth 60 / elevation 38 / mood 'day' shipped in every env)."""+ text = plan.environment+ az = _AZIMUTH_RE.search(text)+ el = _ELEVATION_RE.search(text)+ return (float(az.group(1)) if az else None, float(el.group(1)) if el else None)+++_ENV_STUB = """// src/env.js — the environment: the ground every zone seats on, the light, the sky / backdrop, the atmosphere.+// export function heightAt(x, z) → ground height (m): the ONE function every zone seats on.+// export function buildEnv(ctx) → {{ update?(t, dt), ...whatever zones may share as ctx.env (sunDir, materials, a water level …) }}+// export const SUN_AZIMUTH_DEG → where the light comes from (0 = +X, 90 = +Z); the assembler reads it (regex) to fit cameras on the lit side.+//+// PLACEHOLDER: nothing below decides the brief's world. It ships ONE thing — a level plate named Ground reaching past+// the plan span, so the census has a surface to seat on and to measure the fog against — and NO light, NO sky and NO+// atmosphere: as written this module FAILS the gates (no_fog / no_background on the census, dark_frame on every frame)+// until buildEnv builds the brief's. What is measured:+// • every zone seats on heightAt, so the ground mesh and heightAt must agree (scene_placement: floating > 0.05 m+// outdoors / 0.02 m indoors, sunken > 0.10 m); the plan's cameras expect the ground near their look_at at the+// height the plan states, and each eye above heightAt at its own (x, z) (camera_underground, cap 0.50).+// • scene.fog and scene.background set (no_fog / no_background, ERROR); fog far ≥ 2 × the plan span or+// 1/density ≥ span / 1.5 (fog_short); the land reaches past the fog from every authored camera; no world edge+// in any authored frame (judged world_edge_visible; the census: standing geometry past 1.25 × the half-extent).+// • scene.environment is an environment texture (PBR metals and glass render near black without one).+// • the judged frames sit in the exposure band (scene_frames: dark_frame / blown_frame / flat_frame).+// • the ground mesh is named 'Ground…' / 'Terrain…' (the census classifies the ground by name; the placement gate+// seats on it); backdrop geometry is named 'Sky…' (it then never inflates the content bounds).+// Raw three.js is the baseline. src/lib is an OPTIONAL toolbox the effects catalog lists: lib/terrain.js ground()+// displaces and textures a ground from a height field, lib/sky.js makeSky, lib/environment.js sunRig / roomShell,+// lib/atmosphere.js makeHeightFog — use a call when it fits the brief, write your own when it does not.+import * as THREE from 'three';++export const SUN_AZIMUTH_DEG = {azimuth}; // 0 = +X, 90 = +Z — {azimuth_note}+export const SUN_ELEVATION_DEG = {elevation}; // {elevation_note}+export const GROUND_SIZE = {ground}; // the placeholder plate's side (m): 3 × the plan span, past the 2 × the fog gate measures+// An INTERIOR plan (filled from the plan): the room box the plan gives, {{ center, extents, openings, glazed? }}. The+// enclosure the brief describes — walls, openings, ceiling, materials as named — is yours; lib/environment.js+// roomShell(INTERIOR) is one way to build it. An interior reads black without openings or practical lights (dark_frame).+export const INTERIOR = {interior};++/** Ground height at (x, z) — every placement seats on this. PLACEHOLDER: level; the brief's landform is yours. */+export function heightAt(x, z) {{+ return 0;+}}++export function buildEnv(ctx) {{+ const {{ scene }} = ctx;+ // PLACEHOLDER ground: a level plate following heightAt — REPLACE with the brief's land (named Ground… / Terrain…)+ const ground = new THREE.Mesh(new THREE.PlaneGeometry(GROUND_SIZE, GROUND_SIZE, 1, 1),+ new THREE.MeshStandardMaterial({{ color: 0x6f6a60, roughness: 0.95 }}));+ ground.rotation.x = -Math.PI / 2;+ ground.receiveShadow = true;+ ground.name = 'Ground';+ scene.add(ground);+ // NO light, sky, fog or scene.environment here: the brief's go in this function (see the header for what is measured)+ return {{ ground, update(t, dt) {{}} }};+}}+"""++def _env_for_plan(plan: ScenePlan) -> str:- text = (STARTER_DIR / "env.js").read_text()+ """``src/env.js`` as an interface stub under the plan's data: the plate side from the span, the+ sun azimuth / elevation the plan states, the room box for an interior — and no light, sky or+ atmosphere. The starter's finished landscape (a level disc inside the bounds' radius with+ hills and a ridge beyond) was kept byte for byte by 29 of 30 iteration-0 scenes, and the+ passing placeholder that replaced it (a day sun rig at azimuth 60, a grey fog) built and+ passed for any brief, so it was kept too: a placeholder that passes is a template by another+ name (the de-templating of 2026-10-15)."""ex = plan.bounds.extents- span = max(ex[0], ex[2], 40.0)- ground = int(max(120, span * 2.5))- text = re.sub(r"export const GROUND_SIZE = \d+;", f"export const GROUND_SIZE = {ground};", text)- # level ground inside the plan's radius (its cameras were written for y ≈ 0), rolling beyond- text = re.sub(r"export const CONTENT_RADIUS = \d+;", f"export const CONTENT_RADIUS = {int(max(20, span / 2))};", text)+ span = max(ex[0], ex[2], 1.0)+ az, el = sun_from_plan(plan)+ interior = "null"if plan.interior:c = [round(float(v), 2) for v in plan.bounds.center]e = [round(float(v), 2) for v in ex]glazed = ", glazed: true" if plan.glazed else ""- text = re.sub(r"export const INTERIOR = null;",- f"export const INTERIOR = {{ center: {c}, extents: {e}, openings: []{glazed} }};", text)+ interior = f"{{ center: {c}, extents: {e}, openings: []{glazed} }}"header = (f"// ENV PLAN: {plan.environment.strip()}\n"f"// setting: {plan.setting.strip()} mood: {plan.mood.strip()}\n"- f"// bounds: centre {tuple(round(c, 1) for c in plan.bounds.center)} extents {tuple(round(e, 1) for e in ex)} m\n"- "// Rewrite the ground/sky/fog/sun below to match the plan; keep buildEnv/heightAt exports.\n"+ f"// bounds: centre {tuple(round(c, 1) for c in plan.bounds.center)} extents {tuple(round(e, 1) for e in ex)} m — the extent\n"+ "// of the PLANNED content and the cameras' subject, not the edge of the world: land, backdrop and scenery\n"+ "// continue beyond it as the brief implies.\n"+ "// Keep the buildEnv(ctx), heightAt(x, z) and SUN_AZIMUTH_DEG exports; everything else is yours to write for the plan above.\n")- return header + text+ body = _ENV_STUB.format(+ azimuth=f"{az:g}" if az is not None else f"{SUN_AZIMUTH_GUESS_DEG:g}",+ azimuth_note="the plan's light" if az is not None else "the plan states none: this is only the rig's guess — set the brief's",+ elevation=f"{el:g}" if el is not None else "null",+ elevation_note="the plan's" if el is not None else "the plan states none: set the brief's (a number)",+ ground=int(span * PLACEHOLDER_GROUND_SPANS), interior=interior)+ return header + body# ===================================================================== layout@@ -282,14 +369,16 @@ def _asset_stub(a: AssetPlan) -> str:return f'''// src/assets/{snake}.js — asset "{pascal}": {a.description.strip()}// approx size {w:g} x {h:g} x {d:g} m (w x h x d); expected instances: ~{a.instances_hint}// CONTRACT: export function build{pascal}(THREE) → THREE.Group, origin at the base (y = 0), +Y up, +Z front, meters.-// Build it from several parts with distinct materials (see assets/pine_tree.js, assets/windmill.js);-// for many instances also export {snake}Parts(THREE) → [{{ geometry, material, castShadow }}].+// It must read as the plan describes it at the judge's camera distance (judged) and measure about the size+// above (scene_placement: scale). Parts, materials and construction are yours.+// OPTIONAL: export {snake}Parts(THREE) → [{{ geometry, material, castShadow }}] if a zone wants to instance+// repeats of it (the triangle budget is measured on the census; THREE.InstancedMesh is one way to afford them).import * as THREE from 'three';export function build{pascal}(T = THREE) {{const g = new T.Group();g.name = '{pascal}';- // PLACEHOLDER blockout at the planned size — REPLACE with real construction.+ // PLACEHOLDER blockout at the planned size — REPLACE with the real thing (a single box fails the asset check).const box = new T.Mesh(new T.BoxGeometry({w:g}, {h:g}, {d:g}), new T.MeshStandardMaterial({{ color: 0x9a9a9a, roughness: 0.8 }}));box.position.y = {h / 2:g};box.castShadow = box.receiveShadow = true;@@ -300,43 +389,42 @@ export function build{pascal}(T = THREE) {{def _zone_stub(z: ZonePlan, assets: dict[str, AssetPlan]) -> str:+ """The zone's interface and a TODO naming the plan's contents — no positions. The stub used+ to tile the contents on a quarter-extent grid inside the bbox and say "keep everything inside+ the plan bbox": the seed of the blocks-in-a-rectangle look (the de-templating of 2026-10-15)."""snake, pascal = to_snake(z.name), to_pascal(z.name)c, e = z.bbox.center, z.bbox.extents- imports, places = [], []- for i, name in enumerate(z.contents):+ imports, todo = [], []+ for name in z.contents:a = assets.get(to_snake(name))if a is None:- continue- asn, asp = to_snake(a.name), to_pascal(a.name)- ox = (-e[0] / 4 + (i % 3) * e[0] / 4) if len(z.contents) > 1 else 0.0- oz = (-e[2] / 4 + (i // 3) * e[2] / 4) if len(z.contents) > 3 else 0.0- x, zz = round(c[0] + ox, 2), round(c[2] + oz, 2)- if a.kind == "threejs":+ todo.append(f"// - {name}: not an asset of the plan — built here")+ elif a.kind == "threejs":+ asn, asp = to_snake(a.name), to_pascal(a.name)imports.append(f"import {{ build{asp} }} from '../assets/{asn}.js';")- places.append(f" place(build{asp}(THREE), {x}, {zz});")+ todo.append(f"// - {a.name}: build{asp}(THREE) → a Group with its origin at the base; ~{a.instances_hint} planned")else:- places.append(- f" if (ctx.assets && ctx.assets.{asn}) place(ctx.assets.{asn}.clone(), {x}, {zz});"- f" // GLB built in Blender → public/assets/{asn}.glb (preloaded by scene.js)"- )- imp = "\n".join(imports)- body = "\n".join(places) if places else " // TODO: build this zone's content here (use ctx.heightAt to seat objects)."+ asn = to_snake(a.name)+ todo.append(f"// - {a.name}: ctx.assets.{asn} — the hero GLB public/assets/{asn}.glb preloaded by scene.js; place .clone()s")+ imp = ("\n".join(imports) + "\n") if imports else ""+ todo_block = "\n".join(todo) if todo else "// (the plan lists no contents)"return f'''// src/zones/{snake}.js — zone "{pascal}": {z.description.strip()}-// PLAN bbox: centre ({c[0]:g}, {c[1]:g}, {c[2]:g}) extents ({e[0]:g} x {e[1]:g} x {e[2]:g}) m. Contents: {", ".join(z.contents) or "-"}+// PLAN bbox: centre ({c[0]:g}, {c[1]:g}, {c[2]:g}) extents ({e[0]:g} x {e[1]:g} x {e[2]:g}) m.// CONTRACT: export function build(ctx) → THREE.Group named '{pascal}'. ctx = {{ THREE, scene, renderer, loaders, env, heightAt, assets }}-// • seat objects on the ground with ctx.heightAt(x, z); keep everything inside the plan bbox-// • repeats → THREE.InstancedMesh (see the pattern in assets/pine_tree.js: <asset>Parts(THREE))-// • animation → zone.userData.update = (t, dt) => {{ ... }} (scene.js fans update() out to every zone)+// • seat things on ctx.heightAt(x, z) (measured: scene_placement floating > 0.05 m outdoors / 0.02 m indoors, sunken > 0.10 m)+// • the planned contents are measured against the plan bounds and this bbox (scene_placement: present, at the plan's+// size, not outside the bounds); scenery may continue past the bbox as the brief implies+// • animation → zone.userData.update = (t, dt) => {{ ... }} (scene.js fans update() out; motion between t = 0 and 1.5 s is measured)+// • the triangle budget is measured on the census; THREE.InstancedMesh is one way to afford repeats+// TODO — this zone's planned contents, none placed yet:+{todo_block}import * as THREE from 'three';{imp}-export function build(ctx) {{- const {{ heightAt }} = ctx;const zone = new THREE.Group();zone.name = '{pascal}';- const place = (obj, x, z, ry = 0) => {{ obj.position.set(x, heightAt(x, z), z); obj.rotation.y = ry; zone.add(obj); return obj; }};-{body}- zone.userData.update = (t, dt) => {{ /* animate zone elements here */ }};+ // TODO: build the contents listed above (seat everything with ctx.heightAt)+ zone.userData.update = (t, dt) => {{}}; // the animation hook; delete it if the zone is stillreturn zone;}}'''@@ -359,8 +447,6 @@ def write_skeleton(ws: Workspace, plan: Plan | None = None) -> list[Path]:if plan is None or not isinstance(plan, ScenePlan):return write_example(ws)written: list[Path] = []- for rel in PATTERN_FILES:- _write(ws.src / rel, (STARTER_DIR / rel).read_text(), written)_write_lib(ws, written)_write(ws.src / "env.js", _env_for_plan(plan), written)assets = {to_snake(a.name): a for a in plan.assets}@@ -575,8 +661,18 @@ def probe_zone_modules(ws: Workspace, *, timeout_s: float = 90.0, sun_azimuth_de# --------------------------------------------------------------------------- cameras-_FALLBACK_CAMERA = CameraPlan(name="overview", position=(30.0, 18.0, 30.0), look_at=(0.0, 1.0, 0.0), fov=50.0,- purpose="fallback: no measurable zones")+def fallback_camera(plan: ScenePlan | None, azimuth_deg: float = SUN_AZIMUTH_GUESS_DEG) -> CameraPlan:+ """An overview when nothing was measurable: on the lit side (``azimuth_deg`` is the scene's+ ``SUN_AZIMUTH_DEG``, 0 = +X, 90 = +Z), at the bounds' span from their centre, looking at it —+ derived, not the fixed +X+Z corner shot every example once showed."""+ if plan is None:+ c, r = (0.0, 0.0, 0.0), 30.0+ else:+ c = tuple(float(v) for v in plan.bounds.center)+ r = max(float(plan.bounds.extents[0]), float(plan.bounds.extents[2]), 10.0)+ a = math.radians(azimuth_deg)+ return CameraPlan(name="overview", position=(c[0] + 0.9 * r * math.cos(a), c[1] + 0.45 * r, c[2] + 0.9 * r * math.sin(a)),+ look_at=(c[0], c[1] + 1.0, c[2]), fov=50.0, purpose="fallback: no measurable zones")def _plan_from_spec(spec: dict[str, Any], *, name: str, purpose: str) -> CameraPlan:@@ -584,7 +680,8 @@ def _plan_from_spec(spec: dict[str, Any], *, name: str, purpose: str) -> CameraPfov=float(spec.get("fov", 50.0)), purpose=purpose)-def cameras_from_specs(specs: dict[str, Any], probes: dict[str, ZoneProbe], *, max_cameras: int = 6) -> list[CameraPlan]:+def cameras_from_specs(specs: dict[str, Any], probes: dict[str, ZoneProbe], *, max_cameras: int = 6,+ plan: ScenePlan | None = None, azimuth_deg: float = SUN_AZIMUTH_GUESS_DEG) -> list[CameraPlan]:"""Convert driver-fitted camera specs (``probe_scene.mjs --sun-azimuth``;math owned by ``runtime_js/lib/orbit.mjs``) into CameraPlans: overviewfirst, then per-zone cameras, largest footprints first. Falls back to a@@ -592,14 +689,15 @@ def cameras_from_specs(specs: dict[str, Any], probes: dict[str, ZoneProbe], *, mhealthy = [p for p in probes.values() if p.ok and p.bbox]overview = (specs or {}).get("overview")if not healthy or not overview:- return [_FALLBACK_CAMERA.model_copy()]- cams = [_plan_from_spec(overview, name="overview", purpose="overview fitted to measured content bounds, sun side")]+ return [fallback_camera(plan, azimuth_deg)]+ cams = [_plan_from_spec(overview, name="overview", purpose="fallback: fitted to the measured content (the plan named no camera)")]by_zone = {str(z.get("group", "")).removeprefix("__zone__"): z for z in (specs or {}).get("zones", [])}by_area = sorted(healthy, key=lambda p: -(p.bbox["size"][0] * p.bbox["size"][2]))for p in by_area[: max_cameras - 1]:spec = by_zone.get(p.name)if spec:- cams.append(_plan_from_spec(spec, name=f"{to_snake(p.name)}_view", purpose=f"zone {to_pascal(p.name)} from the sun side"))+ cams.append(_plan_from_spec(spec, name=f"{to_snake(p.name)}_view",+ purpose=f"fallback: zone {to_pascal(p.name)} fitted to its measured bbox (the plan named no camera)"))return cams@@ -701,7 +799,7 @@ def assemble(ws: Workspace, plan: ScenePlan | None = None, *, cameras: str = "deif cameras == "plan" and plan is not None and plan.cameras:cams = list(plan.cameras[:6])else:- cams = cameras_from_specs(camera_specs, probes)+ cams = cameras_from_specs(camera_specs, probes, plan=plan, azimuth_deg=sun_azimuth(ws))text = render_scene_js(healthy, cams, glb_assets(ws), env_ok=env_ok)out = ws.src / "scene.js"out.parent.mkdir(parents=True, exist_ok=True)diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/env.js b/harness/codeverse3d/languages/scene_threejs/starter/src/env.jsindex 7c93f02c..ff8e6407 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/env.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/env.js@@ -1,45 +1,32 @@-// src/env.js — environment owned by the scene: ground, sky, sun, fog, heightAt.-// export function buildEnv(ctx) → { ground, sky, sun, hemi, update(t, dt) }-// export function heightAt(x, z) → ground height (m) so zones can seat objects.-//-// The outdoor world ships from the harness-owned library (D71, 2026-09-08): a textured,-// displaced ground that is LEVEL inside the content radius and rolls beyond it, the sky-// gradient + horizon ridge + matched fog of `worldShell`, the relief / fields / copses of-// `makeOutskirts` between the content and that ridge, and the sun rig with its baked-// environment. Measured over the day's exteriors: with a flat one-colour plane and a bare-// dome as the default, every env session that under-delivered (or died) shipped "flat-// untextured ground", "no aerial perspective", "hard world edge" — the three most frequent-// defects of the tally. TUNE these (palette, mood, relief, flat areas, the path); do not-// replace them with a plane.+// src/env.js — the environment of the EXAMPLE scene (the plan-less skeleton the tests build): the ground every zone+// seats on, the light, the sky / backdrop, the atmosphere. A plan skeleton gets an interface STUB here instead+// (languages/scene_threejs/_env_for_plan): the plan's data, a plate, and no light or atmosphere until the author writes them.+// export function heightAt(x, z) → ground height (m): the ONE function every zone seats on.+// export function buildEnv(ctx) → { update?(t, dt), ...whatever zones may share as ctx.env (sunDir, materials, a water level …) }+// export const SUN_AZIMUTH_DEG → where the light comes from (0 = +X, 90 = +Z); the assembler reads it to fit cameras on the lit side.+// What is measured on any env:+// • every zone seats on heightAt, so the ground mesh and heightAt must agree (scene_placement: floating > 0.05 m+// outdoors / 0.02 m indoors, sunken > 0.10 m); each camera's eye stays above heightAt at its (x, z).+// • scene.fog and scene.background set (no_fog / no_background); fog far ≥ 2 × the plan span or 1/density ≥ span / 1.5+// (fog_short); the land reaches past the fog from every authored camera; no world edge in any authored frame (judged).+// • the judged frames sit in the exposure band (scene_frames: dark_frame / blown_frame / flat_frame).+// • the ground mesh is named 'Ground…' / 'Terrain…' (the census classifies the ground by name); backdrop geometry 'Sky…'.+// Raw three.js is the baseline; src/lib is an OPTIONAL toolbox (the effects catalog lists it).import * as THREE from 'three';-import { makeOutskirts, roomShell, sunRig, worldShell } from './lib/environment.js';-import { mulberry32 } from './lib/noise.js';-import { ground } from './lib/terrain.js';+import { sunRig } from './lib/environment.js';-export const SUN_AZIMUTH_DEG = 60; // where the sun is, as sunRig reads it (0 = +X, 90 = +Z front); cameras on the sun side are front-lit+export const SUN_AZIMUTH_DEG = 60; // 0 = +X, 90 = +Z — this example's lightexport const SUN_ELEVATION_DEG = 38;-export const MOOD = 'day'; // day | golden | night | overcast — the rig, the shell and the fog agree on it-export const GROUND_SIZE = 160; // ground plane extent (m); the outskirts start at its edge-export const CONTENT_RADIUS = 45; // the plan bounds' radius (m): level ground inside, rolling beyond; the shadow frustum-// An INTERIOR plan (the skeleton fills this from plan.bounds): the room shell — floor is the-// ground, walls and ceiling on the bounds' faces. Cut the plan's windows and doors as-// `openings` (see lib/environment.js roomShell) and light the inside; never delete it. A glass-// house (`glazed: true`, from the plan) is glass walls and roof on an iron frame grid: the sun-// and the land outside come through it.-export const INTERIOR = null; // e.g. { center: [0, 3, 0], extents: [14, 6, 16], openings: [{ face: 'west', center: [8, 2.5], size: [6, 3] }] }+export const MOOD = 'day'; // this example's time of day (sunRig's rigs: day | golden | night | overcast)+export const GROUND_SIZE = 160; // the example meadow's plate (m): past 2 × its span, so the fog has land to read+export const SHADOW_RADIUS = 45; // half-size (m) of the sun's shadow frustum: shadows are crisp inside it+// An interior's room box, { center, extents, openings, glazed? } (null: this example is outdoors).+export const INTERIOR = null;const SEED = 7;-// The ground and its height function are ONE thing (terrain.js): built at module load with a-// seeded PRNG, so `heightAt` is exactly the field the mesh was displaced with. Level inside-// CONTENT_RADIUS (the plan's cameras were written for y ≈ 0), rolling out to the outskirts.-const GROUND = ground({- size: GROUND_SIZE, segments: 128, rand: mulberry32(SEED), relief: 3, scale: 60,- flat: (x, z) => 1 - Math.min(1, Math.max(0, (Math.hypot(x, z) - CONTENT_RADIUS) / CONTENT_RADIUS)),-});--/** Ground height at (x, z) — every placement seats on this. */+/** Ground height at (x, z) — every placement seats on this. This example: level. */export function heightAt(x, z) {- return GROUND.height(x, z);+ return 0;}export function buildEnv(ctx) {@@ -47,34 +34,28 @@ export function buildEnv(ctx) {const group = new THREE.Group();group.name = 'Environment';- // --- ground (textured, receives shadows) and, for an interior, the enclosure on the bounds- const ground = GROUND.mesh;+ // the example's ground: a level plate following heightAt, named Ground+ const ground = new THREE.Mesh(new THREE.PlaneGeometry(GROUND_SIZE, GROUND_SIZE, 1, 1),+ new THREE.MeshStandardMaterial({ color: 0x6f6a60, roughness: 0.95 }));+ ground.rotation.x = -Math.PI / 2;+ ground.receiveShadow = true;+ ground.name = 'Ground';group.add(ground);- if (INTERIOR) group.add(roomShell(INTERIOR)); // the enclosure exists before anyone dresses the room-- // --- the world beyond: sky gradient + horizon ridge + fog the colour of the horizon, and the- // land between the content and that ridge (relief, field patchwork, distant copses)- const shell = worldShell({ rand: mulberry32(SEED + 1), mood: MOOD, bounds: CONTENT_RADIUS });- group.add(shell.group);- if (!INTERIOR || INTERIOR.glazed) group.add(makeOutskirts({ inner: GROUND_SIZE / 2, shellRadius: shell.radius, heightAt, seed: SEED }));- // --- lights + the baked environment: the library's rig — sun, hemisphere fill, the env map- // metals read from, the visible disc. Measured 2026-09-07 on this renderer: a metalness-0.9- // sphere renders near black under hand-rolled sun + hemi (no scene.environment) and reads as- // metal with this rig; every recorded Blender hero carried metalness 0.7-0.9 into a scene- // whose env.js set no environment map (0 of 127).- const rig = sunRig({ mood: MOOD, azimuth: SUN_AZIMUTH_DEG, elevation: SUN_ELEVATION_DEG, bounds: CONTENT_RADIUS });+ // the example's light: the library's rig (sun + hemisphere fill + the baked environment map PBR materials read+ // from — a metal with no scene.environment renders near black)+ const rig = sunRig({ mood: MOOD, azimuth: SUN_AZIMUTH_DEG, elevation: SUN_ELEVATION_DEG, bounds: SHADOW_RADIUS });const sun = rig.sun, hemi = rig.fill;group.add(sun, sun.target, hemi);if (rig.sunDisc) group.add(rig.sunDisc);scene.environment = rig.envTex;- // --- fog + background: the shell's, matched to its horizon colour- scene.fog = shell.fog;- scene.background = new THREE.Color(shell.fog.color);+ // the example's atmosphere: a fog reaching past the plate, the background its colour+ scene.fog = new THREE.Fog(0xbfc6cc, GROUND_SIZE * 0.25, GROUND_SIZE * 0.9);+ scene.background = new THREE.Color(scene.fog.color);scene.add(group);const update = () => {};const sunDir = sun.position.clone().normalize();- return { ground, sky: shell.group, sun, sunDir, hemi, group, update };+ return { ground, sun, sunDir, hemi, group, seed: SEED, update };}diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.jsindex 2ccb57dd..9921ae8d 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js@@ -1,9 +1,13 @@/**- * The world beyond the scene, in one call — kills the void-background- * defect family. Three cheap layers far outside the playable area:- * a vertex-coloured gradient sky dome, a seeded ridge SILHOUETTE ring- * so the ground plane never meets bare sky, and fog whose colour- * equals the horizon tint so the far field dissolves instead of ending.+ * The world beyond the scene — optional closures for one measured+ * requirement: from every authored camera the far field does not end+ * in bare sky at the ground line and the sky is not a void (rubric+ * `world_edge_visible`: a hard world edge, a terrain cliff or a missing+ * horizon). `worldShell` is one way to meet it — a graded sky dome,+ * fog the colour of the horizon and, only when asked, a generic+ * silhouette line. A sea horizon, a city skyline, a forest wall, a+ * canyon side or one distant peak close a scene just as well: build+ * what the brief describes.*/import * as THREE from 'three';@@ -13,6 +17,11 @@ import { patchStandard, sunVector } from './shader.js';import { skyRadiance } from './sky.js';import { snapshotResources, attachDisposal } from './lifecycle.js';+/**+ * Four example palettes. Any sky is just `zenith` / `horizon` /+ * `ridgeColor` / `fogDensity` numbers — pass the brief's (a dusk, a+ * storm, a blizzard, an alien sky); `mood` only picks the defaults.+ */export const MOODS = {day: { zenith: 0x5d8fd6, horizon: 0xdbe3ea, ridge: 0x9fb2c4,fogDensity: 0.0018 },@@ -25,19 +34,21 @@ export const MOODS = {};/**- * The enclosure of an INTERIOR scene, in one call: four walls and a- * ceiling on the faces of the plan bounds, with rectangular openings- * (windows, doors) cut where the plan puts them — so nothing the zones- * place inside the bounds can be in a wall, and the roof exists before- * anyone dresses the room. Measured 2026-09-07 over six interior runs:- * with no owner for walls and roof, every one was judged "not enclosed,- * a diorama on a flat plane, tool racks floating at a missing wall"- * (0.0–0.3) until a refine round built them; a bare one-file scene of- * the same brief built the room first and scored 0.82.+ * One enclosure for an interior: a rectangular room on a given box,+ * with rectangular openings (windows, doors) cut where you put them.+ * What is measured for ANY interior: it reads enclosed from the+ * authored cameras (walls and a lid where the brief implies them —+ * six interior runs without them were judged "not enclosed, a diorama+ * on a flat plane, tool racks floating at a missing wall", 0.0–0.3,+ * 2026-09-07), no placed object intersects a wall (placement gate),+ * and the lid is named `Ceiling` under a `RoomShell` group so the+ * overview rig can lift it. A nave, a vault, an L-shape or an+ * open-sided shed is hand-built to the same names.** @param {object} opts- * `center` [x, y, z] and `extents` [w, h, d] of the plan bounds (the- * room's inner box: floor at center.y - h/2, ceiling at center.y + h/2);+ * `center` [x, y, z] and `extents` [w, h, d] of the room's inner box+ * (often, not necessarily, the plan bounds; floor at center.y - h/2,+ * ceiling at center.y + h/2);* `thickness` wall thickness in metres (default 0.3, built OUTWARD so* the inner face is exactly the bounds face); `openings` list of* `{ face: 'west'|'east'|'north'|'south', center: [along, up],@@ -180,17 +191,24 @@ export function roomShell(opts = {}) {}/**- * Build the sky dome + horizon ridge + matched fog.+ * A graded sky dome + fog the colour of its horizon, and an opt-in+ * silhouette line.** @param {object} [opts]- * `rand` seeded PRNG (REQUIRED for the ridge silhouette);- * `mood` one of `day | golden | night | overcast` (default `day`);- * `radius` metres to the sky (default 4000 — far outside any scene);- * `bounds` content radius in metres (the same number `sunRig` takes)- * — clamps fog so the far edge of the content stays visible on- * km-scale worlds; `ridge` false to skip the silhouette ring (open- * ocean, deep space); `zenith`/`horizon`/`ridgeColor` hex overrides;- * `fogDensity` override (wins over the clamp).+ * `rand` seeded PRNG (REQUIRED when `ridge` is on — no Math.random);+ * `mood` one of `day | golden | night | overcast` (default `day`;+ * see MOODS); `radius` metres to the sky (default 4000 — far outside+ * any scene); `bounds` content radius in metres (the same number+ * `sunRig` takes) — clamps fog so the far edge of the content stays+ * visible on km-scale worlds; `ridge` true adds a generic seeded+ * silhouette line at 82 % of the radius (default off: a brief whose+ * horizon is something — a sea, a plain, a skyline, a forest edge,+ * one named mountain — builds that horizon instead); `ridgeHeight`+ * its crest as a fraction of the radius (default 0.055);+ * `ridgeProfile(azimuthDeg) => 0..1` shapes the crest by compass+ * sector (0 = no crest there; default a seeded random walk), so it+ * can be directional or partial; `zenith`/`horizon`/`ridgeColor` hex+ * overrides; `fogDensity` override (wins over the clamp).* @returns {{group: THREE.Group, fog: THREE.FogExp2, radius: number}}* Add `group` to the scene and assign `fog` to `scene.fog`.*/@@ -227,19 +245,24 @@ export function worldShell(opts = {}) {skyMesh.renderOrder = -2;group.add(skyMesh);- // HORIZON RIDGE: seeded silhouette ring at 82% of the sky radius so- // the ground line meets hills, never void. Featureless on purpose —- // a backdrop, not terrain.- if (opts.ridge !== false) {+ // HORIZON RIDGE (opt-in): a generic silhouette line at 82% of the sky+ // radius — one way to keep the ground line off bare sky. A brief that+ // gives its horizon a character builds that instead, or shapes this+ // one through `ridgeHeight` / `ridgeProfile`.+ if (opts.ridge === true) {const rr = radius * 0.82;const seg = 160;- const ridgeH = radius * 0.055;+ const ridgeH = radius+ * (opts.ridgeHeight === undefined ? 0.055 : opts.ridgeHeight);+ const profile = typeof opts.ridgeProfile === 'function'+ ? opts.ridgeProfile : null;const shape = [];let h = 0.5;for (let i = 0; i <= seg; i++) {h = Math.max(0.12, Math.min(1,h + (rand() - 0.5) * 0.35));- shape.push(h);+ shape.push(profile+ ? Math.max(0, Math.min(1, profile((i / seg) * 360))) : h);}shape[seg] = shape[0]; // close the loop seamlesslyconst geo = new THREE.BufferGeometry();@@ -284,37 +307,44 @@ export function worldShell(opts = {}) {}/**- * The middle distance: land between the content and the horizon.+ * The middle distance, one optional filler: an annulus of rolling land+ * that blends into `heightAt` at its inner seam and rises into fbm+ * hills outward, painted as a field patchwork, with an instanced layer+ * of distant copses when asked. Two draw calls, fogged like any land,+ * deterministic in `seed`.*- * `worldShell` closes the SKYLINE, but between the content's edge and- * its ridge the judge still sees "a diorama on a vast, empty flat- * plane" — measured on a scene that had a 6 km textured ground. This- * is that plane given relief, a field patchwork and tree clumps: an- * annulus that MATCHES the scene's ground at its inner seam and rises- * into fbm hills outward, plus one instanced layer of distant copses.- * Two draw calls, fogged like any land, deterministic in `seed`.+ * What is measured: the middle distance reads as the world continuing+ * in the brief's terms (the judge's finding is "a diorama on a vast,+ * empty flat plane" — seen even over a 6 km textured ground), and+ * whatever you build reaches the backdrop (a land edge short of it is+ * a visible cliff: rubric `world_edge_visible`). A desert, a sea, a+ * city, a marsh or a forest needs its own continuation; the defaults+ * here sketch temperate farmland.** @param {object} [opts]- * `inner` metres where the annulus starts — the content's radius- * (default 160); `shellRadius` the sky radius `worldShell` used- * (default 4000 — pass `shell.radius` when you overrode it);- * `outer` metres where it ends (default the shell's RIDGE line,- * `0.82 * shellRadius`, and clamped there: land must reach the- * backdrop or its edge is a visible cliff — measured, a 2 km- * annulus under a 3.28 km ridge left a 1.2 km pale void and the- * census flagged every camera with "terrain ends Nm ahead"; past- * the ridge it would instead paint over that silhouette);- * `baseY` ground level at the seam (default 0); `heightAt` (x, z) =>- * y, the scene's ground truth — the seam band blends from it into- * the relief so the joint cannot step; `relief` hill amplitude in- * metres at full distance (default 26); `rise` metres of gentle- * climb per metre of distance (default 0.004 — receding land reads- * flat without it); `colors` [a, b, c] hex field tones (default a- * muted scrub/field/dust trio); `clumps` distant-copse count- * (default 140, 0 disables); `clumpColor` hex (default dark- * grey-green); `seed` (default 7); `name` group name.- * @returns {THREE.Group} Named `Outskirts`; add it at the world origin- * the content is centred on.+ * `inner` metres from the origin where this filler begins — where+ * your own ground stops (default 160; the content need not be+ * centred or circular, pass what fits your ground); `shellRadius`+ * the sky radius `worldShell` used (default 4000 — pass+ * `shell.radius` when you overrode it); `outer` metres where it ends+ * (default `0.82 * shellRadius`, the shell's ridge line, and clamped+ * there: a 2 km annulus under a 3.28 km ridge left a 1.2 km pale+ * void flagged from every camera; past the ridge it would paint over+ * that silhouette); `baseY` ground level at the seam (default 0);+ * `heightAt` (x, z) => y, the scene's ground truth — the seam band+ * blends from it into the relief so the joint cannot step; `relief`+ * hill amplitude in metres at full distance (default 26; 0 for a+ * plain or a sea); `rise` metres of gentle climb per metre of+ * distance (default 0.004 — receding land reads flat without it);+ * `colors` [a, b, c] hex land tones (default a muted+ * scrub/field/dust trio — pass the brief's soil or vegetation);+ * `fields` false paints one tone instead of the patchwork (sand,+ * snow, scrub); `clumps` distant-copse count (default 0 — a+ * temperate cue: pass a count only where the brief has woodland);+ * `clumpColor` hex (default dark grey-green); `seed` (default 7);+ * `name` group name.+ * @returns {THREE.Group} Named `Outskirts`, in world space about the+ * origin.*/export function makeOutskirts(opts = {}) {const inner = opts.inner === undefined ? 160 : opts.inner;@@ -392,14 +422,16 @@ export function makeOutskirts(opts = {}) {new THREE.BufferAttribute(new Float32Array(verts), 3));geo.computeVertexNormals();- // FIELDS in the fragment, not the lattice: a patchwork of worked- // land at km scale is what says "the world continues" — one fbm- // picks the field, a second lightens or tires it.+ // LAND COVER in the fragment, not the lattice: by default a patchwork+ // of worked land at km scale (one fbm picks the field, a second+ // lightens or tires it) — one "the world continues" cue among many;+ // `fields: false` keeps the mottle and drops the patchwork.+ const patchwork = opts.fields !== false;const mat = new THREE.MeshStandardMaterial({color: 0xffffff, roughness: 0.96, metalness: 0, name: 'OutskirtsLand',});patchStandard(mat, {- name: 'outskirts:fields',+ name: patchwork ? 'outskirts:fields' : 'outskirts:plain', // the program cache keyuniforms: {uOutA: { value: tones[0] },uOutB: { value: tones[1] || tones[0] },@@ -416,9 +448,11 @@ export function makeOutskirts(opts = {}) {].join('\n'),fragmentBody: [' float ofPick = astraFbm2(vOutW * 0.0016, 3);',- ' vec3 ofCol = mix(uOutA, uOutB,',- ' smoothstep(0.35, 0.5, ofPick));',- ' ofCol = mix(ofCol, uOutC, smoothstep(0.58, 0.72, ofPick));',+ ...(patchwork ? [+ ' vec3 ofCol = mix(uOutA, uOutB,',+ ' smoothstep(0.35, 0.5, ofPick));',+ ' ofCol = mix(ofCol, uOutC, smoothstep(0.58, 0.72, ofPick));',+ ] : [' vec3 ofCol = uOutA;']),' ofCol *= 0.9 + 0.2 * astraFbm2(vOutW * 0.012 + 37.0, 2);',' diffuseColor.rgb = ofCol;',].join('\n'),@@ -428,12 +462,13 @@ export function makeOutskirts(opts = {}) {land.receiveShadow = false;group.add(land);- // WOODS: one instanced layer of squashed dark blobs, CLUSTERED —- // 2-6 blobs strung along a heading make a copse or a hedgerow, and a- // lone pancake reads as debris. Placement is biased toward the seam- // (rand^1.8): that is the band a camera actually resolves, and 140- // singles spread over 28 km2 measured out to an empty plain.- const clumps = opts.clumps === undefined ? 220 : opts.clumps;+ // WOODS (opt-in, `clumps` > 0): one instanced layer of squashed dark+ // blobs, CLUSTERED — 2-6 blobs strung along a heading make a copse or+ // a hedgerow, and a lone pancake reads as debris. Placement is biased+ // toward the seam (rand^1.8): that is the band a camera actually+ // resolves, and 140 singles spread over 28 km2 measured out to an+ // empty plain.+ const clumps = opts.clumps === undefined ? 0 : opts.clumps;if (clumps > 0) {const blob = new THREE.SphereGeometry(1, 6, 4);blob.scale(1, 0.55, 1);@@ -541,8 +576,8 @@ const RIGS = {* A PRACTICAL — a lantern, lamp, sign, window or fire: an emissive surface* (it glows, and the post chain blooms it, but it lights nothing) plus its* own small PointLight beside it, which is what lights the ground around- * it. These are the numbers the cookbook's dusk/night recipe builds one- * with; flicker scales `intensity`.+ * it. Starting numbers for one, measured on this renderer; flicker+ * scales `intensity`.*/export const PRACTICAL = Object.freeze({ emissiveIntensity: 3.0, intensity: 1.5, distance: 9, decay: 2 });@@ -559,12 +594,16 @@ export const PRACTICAL = Object.freeze({ emissiveIntensity: 3.0, intensity: 1.5,* `glowCore`) so it reads as a highlight — bloom-friendly, never a* clipped white band. Overcast keeps the flat gradient bake.*- * A SET SUN IS NIGHT: `elevation` below 0 (any mood) switches to the- * night rig — the key light becomes a moon opposite the sun's azimuth- * (elevation 30-55), the fill and env take the night mood, the disc is- * the moon. `sunDir` still reports the authored (below-horizon) sun so- * `makeSky()` paints twilight/night on it; `lightDir` is the vector the- * shadow light actually uses (equal to `sunDir` by day).+ * A below-horizon `elevation` (any mood) lights nothing, so the rig+ * supplies another key to meet the luminance floor: it switches to the+ * night rig — by default a moon opposite the sun's azimuth, 30-55 deg+ * up (`moonAzimuth` / `moonElevation` put it where the brief's dusk+ * wants its glow; keep an above-horizon `elevation` with+ * `mood: 'golden'` for a sun still up) — the fill and env take the+ * night mood, the disc is the moon. `sunDir` still reports the+ * authored (below-horizon) sun so `makeSky()` paints twilight/night on+ * it; `lightDir` is the vector the shadow light actually uses (equal+ * to `sunDir` by day).* An explicit night mood with an above-horizon direction uses that* direction for the moon; `skySunDir` supplies the set sun to both* the environment bake and `makeSky()`.@@ -572,8 +611,10 @@ export const PRACTICAL = Object.freeze({ emissiveIntensity: 3.0, intensity: 1.5,* @param {object} [opts]* `mood` one of `day | golden | night | overcast` (default `day`;* `night` is a moon rig); `bounds` radius in metres of the content- * the shadow frustum must cover (default 150); `azimuth`/`elevation`+ * the shadow frustum covers (default 150); `azimuth`/`elevation`* sun direction in degrees (per-mood defaults; golden sits low);+ * `moonAzimuth`/`moonElevation` where the moon stands when the sun+ * is set (default opposite the sun, 30-55 deg up);* `sunColor`/`intensity` sun overrides; `fill` hemisphere intensity,* clamped UP to the mood's readability floor (its `fillFloor` in RIGS);* `fillSky`/`fillGround` hex overrides of the hemisphere's colours (the@@ -616,7 +657,10 @@ export function sunRig(opts = {}) {// A set sun lights nothing from under the ground: the moon rises// opposite it, 30-55 deg up (deeper sun, higher moon).const moonDir = belowHorizon- ? sunVector(azDeg + 180, Math.max(30, Math.min(55, 25 - elDeg)))+ ? sunVector(+ opts.moonAzimuth === undefined ? azDeg + 180 : opts.moonAzimuth,+ opts.moonElevation === undefined+ ? Math.max(30, Math.min(55, 25 - elDeg)) : opts.moonElevation): (night ? dir.clone() : null);const lightDir = belowHorizon ? moonDir.clone() : dir.clone();@@ -664,9 +708,9 @@ export function sunRig(opts = {}) {// The darkest tenth of a frame is not shade the fill reaches — it is// albedo the libraries have already multiplied toward zero at contact// points, and no light colour rescues a black albedo.- // Colours are the mood's unless the scene tints them: the cookbook's- // time-of-day rows carry a cool sky over a warm ground for every hour,- // and the env bake's ground half below follows the same override.+ // Colours are the mood's unless the scene tints them (a cool sky over+ // a warm ground is the usual daylight pair), and the env bake's ground+ // half below follows the same override.const fillSky = opts.fillSky === undefined ? rig.fillSky : opts.fillSky;const fillGround = opts.fillGround === undefined ? rig.fillGround : opts.fillGround;const fill = new THREE.HemisphereLight(@@ -736,8 +780,8 @@ export function sunRig(opts = {}) {envTex.needsUpdate = true;// SUN DISC (moon at night): on the SAME normalized light vector, at- // 90% of the sky radius so worldShell's horizon ridge (82%) occludes- // it at the skyline the way hills occlude a low sun.+ // 90% of the sky radius so a worldShell ridge (82%), when there is+ // one, occludes it at the skyline the way hills occlude a low sun.let sunDisc = null;if (opts.disc === undefined ? rig.disc : opts.disc) {// The moon subtends about half a degree, independent of sky radius.diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/place.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/place.jsindex 705e8e34..4275aa54 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/place.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/place.js@@ -89,8 +89,10 @@ function restingY(ys, y) {* @param {THREE.Object3D} obj Already positioned in x/z.* @param {THREE.Object3D|THREE.Object3D[]} surfaces Ground, terrain,* decks, roofs — anything that can be stood on.- * @param {object} [opts] `bite` metres to sink (default 0.03),- * `maxDrop` how far down to look (default 500).+ * @param {object} [opts] `bite` metres to sink so no seam shows+ * (default 0.03, inside the placement gate's contact tolerance — the+ * gate measures contact, not this number), `maxDrop` how far down to+ * look (default 500).* @returns {THREE.Object3D} obj, or obj unchanged when nothing is below.*/export function seat(obj, surfaces, opts = {}) {@@ -185,10 +187,14 @@ function clearNeeded(dist) {/*** Build a CAMERAS entry whose geometry is verified, not guessed.- * Two checks: (1) a down-ray over `surfaces` lifts the eye to at- * least 1.6 m above the first hit — never lowers it; (2) a ray toward- * `lookAt` must not hit anything closer than max(2 m, 5% of target- * distance), else the camera slides back and up until the frame clears.+ * What is measured (the frame gate's `camera_underground` and "camera+ * blocked" findings): the eye is above the surface under it and+ * nothing fills the frame from closer than max(2 m, 5% of target+ * distance). Two checks: (1) a down-ray over `surfaces` lifts the eye+ * to at least 1.6 m (a standing eye) above the floor it finds — only+ * ever lifts, so a deliberately low or aerial eye stays where it is+ * put; (2) a ray toward `lookAt` that hits something closer than the+ * clearance slides the camera back and up until the frame clears.** @param {string} name Camera name for the CAMERAS array.* @param {THREE.Vector3|number[]} position Requested eye point.@@ -235,18 +241,17 @@ export function shot(name, position, lookAt, fov, surfaces) {};}-// Widest a view direction may sit from the sun before the low-sun mie-// lobe washes the frame. 55 deg still bleached a third of it, 25 deg-// blew the whole image, 120 deg rendered clean (theme-park run).+// Measured: a low-sun mie lobe within ~90 deg of the view direction+// washed the frame — 55 deg still bleached a third of it, 25 deg blew+// the whole image, 120 deg rendered clean (theme-park run). The+// requirement is only that the judged frame stays in the luminance band.const SUN_CLEAR_DEG = 90;/**- * Push a camera azimuth out of the sun's glare lobe.- *- * The rule has been in the composer prompt since the theme-park run and- * was violated by three of the next three low-sun establishing shots,- * so it is arithmetic now rather than advice. A camera at azimuth A- * LOOKS toward A, so the sun at S is in frame when |A - S| is small.+ * Push a camera azimuth out of the sun's glare lobe — opt-in: it acts+ * only when `sunAzDeg` is given. Omit it for a deliberate contre-jour+ * composition and handle the exposure another way. A camera at azimuth+ * A LOOKS toward A, so the sun at S is in frame when |A - S| is small.** @param {number} azDeg Requested camera azimuth in degrees.* @param {number} [sunAzDeg] Sun azimuth, same convention; when absent@@ -265,21 +270,27 @@ export function awayFromSun(azDeg, sunAzDeg) {}/**- * Frame a hero object whole — the bbox-fitted establishing CAMERAS- * entry, derived instead of eyeballed: project the 8 world-bbox- * corners, dolly until the widest NDC extent hits `coverage`, seat the- * eye with the same down-ray as `shot()`, and — when something stands- * between the eye and the hero — slide along the fit sphere (up first,- * then around) until the hero is actually visible, rather than shipping- * a frame full of ridge.+ * One establishing composition (optional): a hero object whole,+ * centred, filling `coverage` of the frame — derived instead of+ * eyeballed: project the 8 world-bbox corners, dolly until the widest+ * NDC extent hits `coverage`, seat the eye with the same down-ray as+ * `shot()`, and — when something stands between the eye and the hero —+ * slide along the fit sphere (up first, then around) until the hero is+ * actually visible. What is measured for ANY establishing camera: the+ * brief's subject is visible and unblocked in the judged frame (frame+ * gate "camera blocked") and the eye is above the surface under it+ * (`camera_underground`). A street receding, a view through a doorway+ * or a low wide are establishing shots too — compose those with+ * `shot()` or by hand.** @param {string} name Camera name for the CAMERAS array.* @param {THREE.Object3D} heroObj The subject to fit whole.- * @param {object} [opts] `azDeg` view azimuth (default 35), `elDeg`- * elevation (default 22), `fov` (default 45), `coverage` how much of- * the frame the hero spans, 0.5-0.9 (default 0.7), `surfaces` to- * keep the eye at least 1.6 m above the ground, `sunAzDeg` to have- * the azimuth pushed clear of the sun's glare lobe automatically.+ * @param {object} [opts] the defaults of this composition: `azDeg`+ * view azimuth (default 35), `elDeg` elevation (default 22), `fov`+ * (default 45), `coverage` how much of the frame the hero spans,+ * 0.5-0.9 (default 0.7), `surfaces` to keep the eye at least `eyeMin`+ * m above the ground (default 1.6, a standing eye), `sunAzDeg` to+ * have the azimuth pushed clear of the sun's glare lobe.* @returns {{name: string, position: number[], lookAt: number[],* fov: number}} A ready CAMERAS entry.*/@@ -293,6 +304,7 @@ export function establishingShot(name, heroObj, opts = {}) {const elDeg = opts.elDeg === undefined ? 22 : opts.elDeg;const fov = opts.fov === undefined ? 45 : opts.fov;const coverage = opts.coverage === undefined ? 0.7 : opts.coverage;+ const eyeMin = opts.eyeMin === undefined ? 1.6 : opts.eyeMin;const targets = surfaceList(opts.surfaces);heroObj.updateWorldMatrix(true, true);_box.setFromObject(heroObj);@@ -343,7 +355,7 @@ export function establishingShot(name, heroObj, opts = {}) {: awayFromSun(azDeg + dAz + 180, opts.sunAzDeg) - 180;const dir = sunVector(a, Math.min(70, elDeg + dEl));const p = center.clone().addScaledVector(dir, fit(dir));- liftAbove(p, targets, 1.6);+ liftAbove(p, targets, eyeMin);const v = probeView(p, center, targets);if (v.hit >= clearNeeded(v.dist)) { pos = p; break; }// Nothing clears: keep whichever candidate sees furthest into thediff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/sky.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/sky.jsindex 6d2f3859..ac9f53b1 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/sky.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/sky.js@@ -142,7 +142,8 @@ export function skyRadiance(dir, sunDir, opts = {}) {* @param {object} [opts]* `rig` a `sunRig()` result to slave to; `sunDir` explicit sun* vector; `elevationDeg` (default 15) / `azimuthDeg` (default 135)- * sun angles; `turbidity` (default 4.5), `rayleigh` (default 1.6),+ * sun angles — defaults are a low afternoon sun, pass the brief's+ * hour; `turbidity` (default 4.5), `rayleigh` (default 1.6),* `mieCoefficient` (default 0.0035), `mieDirectionalG` (default* 0.8) — the battery-graded atmosphere; `exposure` dome gain* (default 0.36, graded for exposure 1.0 — the old ungraded dome isdiff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/terrain.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/terrain.jsindex c9e828a5..36730030 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/terrain.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/terrain.js@@ -1,8 +1,9 @@/**- * The ground, textured and seatable, in one call (the model takes CODE- * and ignores prose, so the ground ships as a function). `ground()`- * samples the actual mesh triangles — place- * every asset at `h(x, z)`; floating assets are the most-flagged defect.+ * A textured, seatable ground and its height function — one optional+ * recipe. INTERFACE: whatever builds the ground exposes a height+ * function (x, z) => y that samples the actual mesh, and every seated+ * asset rests on it (the placement gate measures contact; floating+ * assets are the most-flagged defect).*/import * as THREE from 'three';@@ -48,17 +49,24 @@ function latticeSampler(rand) {/*** Build a displaced, textured ground plane and its height function.+ * The defaults make a 400 m square of gentle fbm hills — one landform;+ * extent, relief and feature size are the brief's. What is measured:+ * no authored camera sees a hard world edge, a terrain cliff or a+ * missing horizon (rubric `world_edge_visible`), and the grid stays in+ * the triangle budget (`segments` is capped at 128).** @param {object} opts* `size` metres across (default 400), `segments` grid resolution* (default 128), `rand` a seeded PRNG* (REQUIRED — no Math.random), `material` a THREE material (defaults* to `MAT.soil()`), `relief` peak-to-trough metres (default 6),- * `scale` feature size in metres (default 90), `flat` a function- * (x, z) => 0..1 that damps relief to 0 where the scene needs level- * ground (a plaza, a quay, a street grid), `name` (default 'Ground').+ * `scale` feature size in metres (default 90), `flat` an optional+ * (x, z) => 0..1 mask that damps relief where the brief needs level+ * ground — a plaza, a quay, a road, a terrace — of whatever+ * footprint the brief implies (a radial pad around the origin is+ * only one mask), `name` (default 'Ground').* @returns {{mesh: THREE.Mesh, height: (x: number, z: number) => number}}- * The mesh to add, and the height function EVERY placement must use.+ * The mesh to add, and the height function placements seat on.*/export function ground(opts = {}) {const size = opts.size || 400;@@ -128,9 +136,11 @@ export function ground(opts = {}) {}/*- * A cliff face is ONE connected ribbon, never a pile of slabs (slab- * piles read as buildings). Strata are VERTEX-COLOUR bands sampled on- * the displaced surface so a band cannot detach; the same field backs+ * What is measured: a cliff reads as rock in the judged frames and+ * seats props on its measured face (`faceAt`). One connected displaced+ * ribbon is a construction that does; stacked slabs have been judged+ * as buildings. Strata are VERTEX-COLOUR bands sampled on the+ * displaced surface so a band cannot detach; the same field backs* `faceAt(s, y)` so props seat ON the measured rock.*/diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/scene.js b/harness/codeverse3d/languages/scene_threejs/starter/src/scene.jsindex b2b8e6a1..ce7c6638 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/scene.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/scene.js@@ -4,14 +4,15 @@// export function createScene({ THREE, renderer, loaders })// → { scene, cameras: [{ name, position: [x,y,z], lookAt: [x,y,z], fov }], update(t, dt) }// • Y is up, +Z is front, units are meters. The scene owns its lights, sky/env and fog.-// • cameras: 3–4 authored shots (eye above the ground, clear of every surface).+// • cameras: the plan's authored shots, 1–6; each is measured (eye above the ground, nothing within 0.5 m of the lens,+// the first one as the establishing shot: ≥ 20 % of its frame is content).// • update(t, dt): t = seconds since start, dt = step; animate here (no requestAnimationFrame).// • loaders.gltf is a GLTFLoader: loaders.gltf.loadAsync('/assets/<name>.glb') for Blender-built assets.// • Imports allowed: 'three', 'three/addons/*', relative files. No CDN, no network, no DOM access.// • Raw three.js + GLSL only: never import a helper SDK or any npm package.// ./lib/ is the ONE exception and is not an SDK: harness-owned effect modules// shipped INTO this workspace, already compiled and rendered on this renderer.-// Import and call them (`import { makeGrass } from './lib/grass.js'`); do not+// Import and call them (`import { makeGrass } from './lib/grass.js'`) when they help; do not// rewrite them — writes to src/lib/ are reverted. Table: prompts effects_catalog.import * as THREE from 'three';import { buildEnv, heightAt, SUN_AZIMUTH_DEG } from './env.js';@@ -22,7 +23,7 @@ export function createScene({ THREE: T = THREE, renderer, loaders }) {const scene = new THREE.Scene();const ctx = { THREE, scene, renderer, loaders, heightAt, sunAzimuthDeg: SUN_AZIMUTH_DEG };- const env = buildEnv(ctx); // ground, sky, sun, hemi light, fog+ const env = buildEnv(ctx); // whatever env.js shares with the zonesctx.env = env;// Each zone returns ONE named THREE.Group (PascalCase = zone name in the census/judge).diff --git a/harness/codeverse3d/prompts/_claims.toml b/harness/codeverse3d/prompts/_claims.tomlindex c90695de..faa7dc4b 100644--- a/harness/codeverse3d/prompts/_claims.toml+++ b/harness/codeverse3d/prompts/_claims.toml@@ -45,7 +45,7 @@ context = "sampled-time trap"[[claim]]key = "scene_times"-file = "scene_threejs/cookbook.md"+file = "scene_threejs/contract.md"text = "0 and t = 1.5"python = "codeverse3d.tracks.scene:SCENE_TIMES"sep = " and t = "@@ -53,7 +53,7 @@ context = "renders every camera at t ="[[claim]]key = "scene_times"-file = "scene_threejs/cookbook.md"+file = "scene_threejs/contract.md"text = "0, 1.5"python = "codeverse3d.tracks.scene:SCENE_TIMES"sep = ", "@@ -66,7 +66,7 @@ context = "scene_views(times=["[[claim]]key = "scene_times"-file = "scene_blender/cookbook.md"+file = "scene_blender/contract.md"text = "0 and t = 1.5"python = "codeverse3d.tracks.scene:SCENE_TIMES"sep = " and t = "@@ -81,17 +81,19 @@ context = "fps="[[claim]]key = "asset_max_tris"-file = "scene_blender/cookbook.md"-text = "15000"+file = "scene_blender/contract.md"+text = "15,000"python = "codeverse3d.tracks.scene_assets:ASSET_MAX_TRIS"+format = "{:,}"context = "per asset"[[claim]]key = "hero_max_tris"-file = "scene_blender/cookbook.md"-text = "40000"+file = "scene_blender/contract.md"+text = "40,000"python = "codeverse3d.tracks.scene_assets:HERO_MAX_TRIS"-context = "for a hero"+format = "{:,}"+context = "per hero"[[claim]]key = "scene_max_tris"@@ -215,7 +217,7 @@ context = "ERRORS at"[[claim]]key = "placement_floating_error_m"-file = "scene_blender/cookbook.md"+file = "scene_blender/contract.md"text = "0.08"python = "codeverse3d.config:Placement"format = "{0.model_fields[floating_error_m].default:.2f}"@@ -223,7 +225,7 @@ context = "ERROR at"[[claim]]key = "placement_sunk_error_m"-file = "scene_blender/cookbook.md"+file = "scene_blender/contract.md"text = "0.20"python = "codeverse3d.config:Placement"format = "{0.model_fields[sunk_error_m].default:.2f}"@@ -231,7 +233,7 @@ context = "ERROR at"[[claim]]key = "placement_overlap_error"-file = "scene_blender/cookbook.md"+file = "scene_blender/contract.md"text = "35%"python = "codeverse3d.config:Placement"format = "{0.model_fields[overlap_error].default:.0%}"diff --git a/harness/codeverse3d/prompts/catalog.py b/harness/codeverse3d/prompts/catalog.pyindex 780e4107..28a53e5b 100644--- a/harness/codeverse3d/prompts/catalog.py+++ b/harness/codeverse3d/prompts/catalog.py@@ -23,6 +23,8 @@ A file that tries to be both is the thing this split exists to prevent.from __future__ import annotations+from collections.abc import Sequence+from codeverse3d.contracts.common import Languagefrom codeverse3d.prompts import load_text@@ -37,9 +39,30 @@ def language_prompt(language: Language, name: str) -> str:def language_text(language: Language, name: str) -> str:- """The text of :func:`language_prompt`, or ``""`` for a file the language does not ship- (only scene_threejs ships an effects catalog)."""+ """The text of :func:`language_prompt`, or ``""`` for a file the language does not ship:+ only the two scene languages ship an effects catalog, and they ship NO ``cookbook.md``+ (owner, 2026-10-15: its interface facts went into contract.md / system.md, its craft into+ the skills) — ``RunContext.cookbook_text`` is ``""`` for them, so no prompt, workspace+ note or error report carries a cookbook on the scene track."""try:return load_text(language_prompt(language, name))except FileNotFoundError:return ""+++def contract_sections(text: str, headings: Sequence[str]) -> str:+ """The ``## `` sections of a contract whose heading starts with one of ``headings``, in the+ contract's own order, under its preamble (the ``# `` title and anything before the first+ ``## ``). A session that writes one asset module, or a planner that writes JSON, is handed+ the sections it acts on — the files, the gates, the lint — not the whole contract (the+ copyability review of 2026-10-15: the asset brief had grown 52 % by carrying the wiring+ example of modules it must not write)."""+ out: list[str] = []+ keep = True+ for line in text.splitlines():+ if line.startswith("## "):+ title = line[3:].strip()+ keep = any(title.startswith(h) for h in headings)+ if keep:+ out.append(line)+ return "\n".join(out).rstrip() + "\n"diff --git a/harness/codeverse3d/prompts/scene_blender/asset.md b/harness/codeverse3d/prompts/scene_blender/asset.mdindex e619a064..be0349a6 100644--- a/harness/codeverse3d/prompts/scene_blender/asset.md+++ b/harness/codeverse3d/prompts/scene_blender/asset.md@@ -2,20 +2,20 @@ You write ONE self-contained Blender bpy asset module for a larger scene — a f`build_<snake>(ctx, variant=0)` that builds every part of the prop into `ctx.collection` (aCollection the harness created for it, active, and the value it returns) at the origin, baseon z = 0, front facing −Y, metres. Raw bpy / bmesh / mathutils only: no file IO, no image-loading, no `bpy.ops` in loops, no lights, no cameras, no world. Imports: `bpy`, `bmesh`,-`mathutils`, `math`, and the scene's shipped bpy library `from lib.<module> import …` when the-task sheet names one of its calls — it is harness code that ships with every scene, not an-outside package.+loading, no lights, no cameras, no world; the lint warns on `bpy.ops.mesh.primitive_*` in a+loop. Imports: `bpy`, `bmesh`, `mathutils`, `math`, and the scene's shipped bpy library+`from lib.<module> import …` when the task sheet names one of its calls — it is harness code+that ships with every scene, not an outside package.The module is built once by the harness in an isolated Blender process (a raise is reportedwith its line and the asset is NOT AVAILABLE to the zones), then placed by the zones ascollection instances of `ctx.assets['<snake>']` — so the task sheet's exact function name, sizeand `variant` contract outrank everything else: zone code places your Collection sight unseenby its origin, and a wrong name or an off-origin footprint fails every placement, not just-this file. It is judged as a prop at scene distance: silhouette first, then the 2-3-recognisable features a person would name, then wear that makes it look used; several parts-with distinct materials (Principled BSDF: `Base Color`, `Roughness`, `Metallic`), never one-grey box. Keep it under the triangle budget the sheet states and give every part a unique-PascalCase name.+this file. It is judged as a prop at scene distance: it must be recognisable as what the+sheet names (its silhouette and the features a person would name), and a single flat grey+material is graded `placeholder_material` — every surface carries a Principled material+(`Base Color`, `Roughness`, `Metallic`) that matches what it is. Keep it under the triangle+budget the sheet states and give every part a unique PascalCase name.Write the one file completely and stop. No commentary, no extra files.diff --git a/harness/codeverse3d/prompts/scene_blender/contract.md b/harness/codeverse3d/prompts/scene_blender/contract.mdindex 87b3abea..bdc1d6e7 100644--- a/harness/codeverse3d/prompts/scene_blender/contract.md+++ b/harness/codeverse3d/prompts/scene_blender/contract.md@@ -3,10 +3,10 @@## Files (Blender 5.2 LTS python; Z up, −Y front, metres)```src/scene.py ASSEMBLED BY THE HARNESS — data only (ZONES / ASSETS / HEROES / CAMERAS); never edit it-src/env.py def height_at(x, y) -> z def build_env(ctx) -> dict (world, sun, ground, atmosphere; the enclosure of an interior)+src/env.py def height_at(x, y) -> z def build_env(ctx) -> dict (world, light, ground, atmosphere; the enclosure of an interior)src/zones/<snake>.py def build(ctx) -> bpy.types.Collection (everything linked into ctx.collection, the zone's own Collection)src/assets/<snake>.py def build_<snake>(ctx, variant=0) -> bpy.types.Collection (built ONCE at the origin, base on z = 0, front facing −Y)-src/lib/*.py HARNESS-OWNED bpy library — import and call, never edit (a write to it is reverted; the catalog ships with every brief)+src/lib/*.py HARNESS-OWNED bpy library — an optional toolbox: import and call, never edit (a write to it is reverted; the catalog ships with every brief)public/assets/<snake>.glb heroes the harness built as objects — imported for you into ctx.assets['<snake>']```@@ -15,12 +15,15 @@ metric units, fps=30, the frame range 1..46, every random source seeded) in thisbuilder in its own try/except: `env.build_env(ctx)`; every hero GLB imported; every`assets.<snake>.build_<snake>(ctx)`; every `zones.<snake>.build(ctx)`. A builder that raisesis DROPPED with its `file:line` and everything it created is removed — the rest of the scene-still builds and is measured, so one bad zone costs that zone, not the round. Then the-harness adds the plan's cameras, hides the asset sources (they render only through their-collection instances), writes the census and the `.blend`, and renders every camera at-t = 0 and t = 1.5 s (frames 1 and 46) with Cycles (32 samples + OpenImageDenoise, AgX view-transform, exposure 0). Render settings, colour management, cameras, the frame clock and-file IO are the harness's: the lint rejects code that touches them.+still builds and is measured, so one bad zone costs that zone, not the round. A module that+raises on import (a bad top-level statement) is gone the same way; `build_<zone>(ctx)`,+`create()`, `main()` and `register()` are never called. Link every object into+`ctx.collection`: an object linked into `ctx.scene.collection` belongs to no zone and is+graded as the harness's. Then the harness adds the plan's cameras, hides the asset sources+(they render only through their collection instances), writes the census and the `.blend`, and+renders every camera at t = 0 and t = 1.5 s (frames 1 and 46) with Cycles (32 samples ++OpenImageDenoise, AgX view transform, exposure 0). Render settings, colour management,+cameras, the frame clock and file IO are the harness's: the lint rejects code that touches them.## The `ctx` every builder receives (data, never verbs)| field | what it is |@@ -46,7 +49,8 @@ width × depth × height here (the plan's width × height × depth, reordered).`bpy`, `bmesh`, `mathutils` (Vector, Matrix, Euler, noise), `math`, `numpy` (only through`numpy.random.default_rng(seed)` for randomness), `itertools`, `functools`, `collections`,`dataclasses`, `colorsys`, and the workspace's own packages: `from lib.<module> import …`,-`from env import …` (zones may read env constants). Nothing else resolves in the build.+`from env import …` (zones may read whatever `env` defines at module level). Nothing else+resolves in the build.## FORBIDDEN (the lint's policy table; each is an ERROR that fails the build gate)`bpy.ops.render.*`, `bpy.ops.wm.*` (open/save/append/link), `bpy.ops.export_*`,@@ -58,15 +62,38 @@ width × depth × height here (the plan's width × height × depth, reordered).(`driver.use_self`, attribute access, `**`, `%`, `noise.*` in an expression), the worldoutside `src/env.py` (`bpy.data.worlds.new`, `scene.world =`), `random.*` and unseeded numpy,`open()`, `os` / `sys` / `pathlib` / `time` / `datetime` / `subprocess` / `shutil` / `tempfile`-/ `glob` / `io`. Blender 5.2 removed: `use_nodes` (deprecated — materials, worlds and lights-always have a node tree), `sky_type = 'NISHITA'` (it is `'MULTIPLE_SCATTERING'`), the boolean-solver `'FAST'` (`FLOAT` / `EXACT` / `MANIFOLD`), `mod["Socket_2"] = v` for geometry-nodes-inputs (`getattr(mod.properties.inputs, "Socket_2").value = v`), `Action.fcurves`-(`action.layers[0].strips[0].channelbag(action.slots[0]).fcurves`), `Mesh.calc_normals()`,-`use_auto_smooth`, the Principled inputs `Specular` / `Subsurface` / `Transmission` /-`Emission` (now `Specular IOR Level`, `Subsurface Weight`, `Transmission Weight`,-`Emission Color` + `Emission Strength`), `ShaderNodeMixRGB` (it is `ShaderNodeMix` with-`data_type = 'RGBA'`: inputs 6 / 7 are the colours, output 2 the result).+/ `glob` / `io`. The lint WARNS on `bpy.ops.mesh.primitive_*` inside a loop (every operator+call rebuilds the scene state) and on `bpy.ops.view3d.*` / `bpy.ops.screen.*` (no viewport in+background mode).++## Blender 5.2 API facts (each is a build error or a silent zero)+Removed: `use_nodes` (deprecated — materials, worlds and lights always have a node tree; a new+material already carries `Principled BSDF` and `Material Output`), `sky_type = 'NISHITA'` (it is+`'MULTIPLE_SCATTERING'`, with `aerosol_density`), the boolean solver `'FAST'` (`FLOAT` / `EXACT` /+`MANIFOLD`), `mod["Socket_2"] = v` for geometry-nodes inputs (`getattr(mod.properties.inputs,+"Socket_2").value = v`), `Action.fcurves` (actions are slotted:+`action.layers[0].strips[0].channelbag(action.slots[0]).fcurves`, or `lib.motion.fcurves`),+`Mesh.calc_normals()` and `use_auto_smooth` (`me.shade_smooth()` or `f.smooth = True` per face),+the Principled inputs `Specular` / `Subsurface` / `Transmission` / `Emission` (now `Specular IOR+Level`, `Subsurface Weight`, `Transmission Weight`, `Coat Weight`, `Sheen Weight`, `Emission Color`++ `Emission Strength`), `ShaderNodeMixRGB` (it is `ShaderNodeMix` with `data_type = 'RGBA'`:+inputs 6 / 7 are the colours, output 2 the result; the mix input is `Factor`, not `Fac`).+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()` after any+topology change. A fresh object's `matrix_world` is identity until the view layer updates+(`lib.place.world_matrix`, or `bpy.context.view_layer.update()` before reading it; parent with a+RELATIVE `location`).++## What the renderer does with what you build+Cycles at 32 samples + OpenImageDenoise, AgX, exposure 0, 1024 × 576; no post chain and no+bloom: an emissive surface at strength 3–8 reads as a lamp, 20+ whites the frame out+(`blown_frac`), and a lamp beside it is what lights the wall. A SURFACE shader always has a+silhouette: in Cycles a soft particle (steam, smoke, dust, spray) renders without an edge only+as a Principled VOLUME (`lib.materials.volume`); a translucent puff, metaball, torus or disc is+graded `hard_edged_particles`. The census is the evaluated depsgraph: modifiers, geometry+nodes and instances count as they render; 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 rendered, its source once).## MotionAnimation is DATA in the `.blend`: keyframes on `ctx.frame(t)` for the two times in@@ -74,18 +101,21 @@ Animation is DATA in the `.blend`: keyframes on `ctx.frame(t)` for the two timesdriver of `frame` (`lib.motion.spin`: `frame * 0.1` — sin / cos / min / max / clamp / lerp,`+ - * /`, comparisons; nothing that needs Python, which a `--factory-startup` build silentlyevaluates to 0). Set `keyframe_points[].interpolation = 'LINEAR'` for motion that should-read at t = 1.5 as a travel, not an ease. Amplitudes that read in a 1024 × 576 frame: ≥ 0.10-rad of rotation, ≥ 0.05 m of travel per 1.5 s, a particle / leaf / boat ≥ 0.6 m. A hero-GLB's own keyframed clip plays in every instance by itself.+read at t = 1.5 as a travel, not an ease. The harness differences the two frames per camera+and reports the number (a camera moves at ≥ 0.4 % of its pixels changed by > 8/255; none moving+is the `no_motion` ERROR, the judge's `nothing_moves`). Amplitudes that have registered+at 1024 × 576: ≥ 0.10 rad of rotation, ≥ 0.05 m of travel per 1.5 s, a particle / leaf / boat+≥ 0.6 m. A hero GLB's own keyframed clip plays in every instance by itself.## NamingPascalCase object names, globally unique — a Blender object name is global, so a second`Lantern_0` becomes `Lantern_0.001` and the placement table then reports a prop nobodyplanned: number every placed copy with `lib.place.unique_name(base, i)` (`Lantern_0`,-`Lantern_1`…) and never reuse a base another zone uses. Name the terrain and the backdrop-`Ground…` / `Terrain…` / `Water…` / `Sky…` (`SkyRidge`: the census classifies by name — a sky-named-mesh wider than 50 m is backdrop, not content);-an interior's shell `RoomShell…` / `Ceiling…` (the overview rig lifts the lid by name).+`Lantern_1`…) and never reuse a base another zone uses. The census classifies by name: a+ground / terrain mesh is `Ground…` / `Terrain…`, water `Water…`, and anything meant as distant+backdrop (if the brief's place has one) `Sky…` — a sky-named mesh wider than 50 m is filed as+backdrop, not content, so the overview cameras frame the content; an interior's shell is+`RoomShell…` / `Ceiling…` (the overview rig lifts the lid by name).## Placement (the scene_placement gate, run on every build)Every root object you link into a zone (a mesh, a parent Empty with children, a@@ -96,92 +126,98 @@ than 2 things float); a foot buried deeper than 0.10 m is `sunken` (an ERROR atfifth of the thing's height — rocks, posts and bushes may sit partly in; stairs and ramps mayfollow the slope; a foot at or under water is fine); a bbox touching nothing is `unsupported`;two boxes sharing more than 10% of the smaller one's volume is `interpenetration` (an ERROR at 35%).-Seat with `lib.place.seat(obj, ctx.height_at)` (the same foot columns the gate samples: gap ≤ 0.02 m-after) or `lib.scatter.instance(..., height_at=ctx.height_at)`, and check your pairs with-`lib.place.clear_of(objs)` before you finish. `obj["placement"] = "free"` exempts-a thing MEANT to hang in the air (a bird, a lantern on a chain, a kite) — nothing else: the-gate reports the share of placed things tagged free and warns past 25%, errors past 50%.-Geometry-nodes instance clouds (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`) are-counted as instances and exempt per asset, like scatter is.+`lib.place.seat(obj, ctx.height_at)` samples the same foot columns the gate does (gap ≤ 0.02 m+after); `lib.scatter.instance(..., height_at=ctx.height_at)` seats as it places;+`lib.place.clear_of(objs)` is the pair check. A thing resting on one corner with the others in+the air (four or more foot columns, at most one touching, the worst gap > 0.05 m) is+`cantilevered` (a WARN). `obj["placement"] = "free"` exempts a thing MEANT+to hang in the air (a bird, a lantern on a chain, a kite) — nothing else: the gate reports the+share of placed things tagged free and warns past 25%, errors past 50%. Geometry-nodes instance+clouds (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`) are counted as instances and+exempt per asset, like scatter is. A PLANNED content is also measured against the plan bounds+(`out_of_bounds`, a WARN: entirely outside them by more than max(5 m, 10 % of the span); scenery that+continues the place past the bounds is never reported) and an asset placed+at a size other than the plan's (beyond 2.5 × is a WARN, 4 × an ERROR).## What else the gates measure-`scene_frames`: every authored camera's frame at both times — too dark, blown out, mostly-sky / ground, the camera inside geometry or below the ground. `scene_probe` (from the census-GLB and the bpy facts): unique triangles over the scene ceiling (3,000,000), a Python driver-or an app handler, no world / no atmosphere, render settings touched. A hero that would not-import is a WARN on its file; a zone / asset / env that raised is an ERROR on its line.--## COMPLETE minimal examples (the harness builds exactly these; copy their shape)+`scene_frames`: every authored camera's frame 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 the pixels in one luminance band; ERROR above 92 %), mostly sky / ground (an establishing+camera needs ≥ 20 % of its frame to be content, every other authored camera ≥ 10 %:+`content_small`), the camera inside geometry or within 0.5 m of a surface+(`camera_in_geometry`), 6 or more of its 9 sight rays ending within 1.5 m (`camera_blocked`), or+below the ground under it (`camera_underground`) — the camera findings cap the score at 0.50; an+eye less than 0.3 m above the ground is a `camera_low` WARN, more than 80 m above it+`camera_high`. `frame_motion`: the two frames are 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` follows it. A hero GLB+covering < 0.5 % of the frame in every authored camera is `hero_unseen` (ERROR; < 2 % in the+camera named for it, a WARN). `scene_probe` (from the census GLB and the bpy facts): unique+triangles over the scene ceiling (3,000,000), a Python driver or an app handler, no world / no+atmosphere (`no_fog`: neither a world Volume nor a bounded fog volume — mist is not read),+render settings touched. Outdoors, `fog_short` warns when 1 / density < span / 1.5 (the census+reads the volume's density: a density above 1.5 / span dissolves the world inside two thirds of+the plan span) and `world_edge` warns when no standing geometry reaches past 1.25 × the bounds'+half-extent — the world continues past the content in whatever form the brief's place has. A+hero that would not import is a WARN on its file; a zone / asset / env that raised is an ERROR on+its line.++## Interiors+A plan with `interior: true`: the enclosure (floor, walls, lid) is `src/env.py`'s, with the lid+meshes named `RoomShell…` / `Ceiling…`; it must read enclosed from every authored camera and be+lit inside (the frame gate); the floating threshold indoors is 0.02 m. `lib.architecture.room_shell`+builds a box with openings; the room's shape and extent are the brief's. Zones dress the inside;+a partition, counter or alcove a zone needs is the zone's, seated and clear of the shell.++## Two modules the harness builds as-is (the interface shown once; the content is a harbour, yours is the brief's)`src/env.py````python"""src/env.py — the environment of `Harbour at dusk`: world, sun, ground, atmosphere."""-import bpy-from lib.lighting import sunfrom lib.materials import materialfrom lib.sky import haze, sun_world-from lib.terrain import ground, make_height_at+from lib.terrain import ground-BOUNDS = {"center": (0.0, 0.0, 5.0), "extents": (120.0, 120.0, 30.0)} # the plan's, in this frame-SUN_AZIMUTH_DEG = 250.0 # compass angle of the sun: 0 = +X, 90 = +Y-SUN_ELEVATION_DEG = 8.0-_terrain = make_height_at(seed=3, relief=1.2, scale=40.0, flat_radius=60.0)+SUN_AZIMUTH_DEG, SUN_ELEVATION_DEG = 250.0, 8.0 # the plan's light (compass 0 = +X, 90 = +Y); zones may `from env import` these+WORLD_M = 320.0 # how far this place's land and air reach (plan span 100 m): the brief's number-def height_at(x, y):- """THE ground (z at x, y): level inside the content radius, rolling beyond; every seat reads it."""- return _terrain(x, y)+def height_at(x, y): # THE ground: any function of (x, y) the brief's landform needs — here level quay land, a basin east, ground rising inland+ return -2.0 * min(1.0, x / 25.0) if x >= 0.0 else 0.04 * max(0.0, -45.0 - x)def build_env(ctx):sun_world(ctx.scene, elevation_deg=SUN_ELEVATION_DEG, azimuth_deg=SUN_AZIMUTH_DEG, strength=0.25, dust=3.0)- _, towards_sun = sun(ctx.collection, azimuth_deg=SUN_AZIMUTH_DEG, elevation_deg=SUN_ELEVATION_DEG,- color="FFB070", energy=2.5)+ _, towards_sun = sun(ctx.collection, azimuth_deg=SUN_AZIMUTH_DEG, elevation_deg=SUN_ELEVATION_DEG, color="FFB070", energy=2.5)ground_mat = material("GroundMat", "4A5A33", roughness=1.0, noise_scale=0.35)- ground("Ground", ctx.collection, size=320.0, segments=160, height_at=height_at, material=ground_mat)- haze(ctx.collection, (0.0, 0.0, 15.0), (320.0, 320.0, 30.0), density=0.004, color="D9703A")+ ground("Ground", ctx.collection, size=WORLD_M, segments=160, height_at=height_at, material=ground_mat) # past every camera's fog+ haze(ctx.collection, (0.0, 0.0, 15.0), (WORLD_M, WORLD_M, 30.0), density=1.0 / WORLD_M, color="D9703A") # 1/density ≥ span/1.5return {"ground_material": ground_mat, "sun_direction": tuple(towards_sun), "water_level": 0.0}````src/zones/quay.py````python-"""src/zones/quay.py — zone "Quay": L-shaped granite quay with bollards and crates."""-import bmesh-import bpy-+"""src/zones/quay.py — zone "Quay": the granite quay deck with its bollards."""from lib.materials import material+from lib.mesh import Batchfrom lib.place import clear_of, seat, unique_namefrom lib.scatter import instance-CENTRE = (-20.0, 0.0) # the plan's zone centre, in this frame-DECK_TOP = 1.2 # the quay stands 1.2 m above the water---def _slab(name, mat, size, loc, collection):- me = bpy.data.meshes.new(name)- bm = bmesh.new()- bmesh.ops.create_cube(bm, size=1.0)- bmesh.ops.scale(bm, vec=size, verts=bm.verts)- bmesh.ops.translate(bm, vec=loc, verts=bm.verts)- bm.to_mesh(me)- bm.free()- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- collection.objects.link(ob)- return ob+CENTRE, DECK_TOP, N_BOLLARDS = (-20.0, 0.0), 1.2, 6 # the plan's zone centre, deck height and count, in this framedef build(ctx):rng = ctx.rng(11)granite = material("QuayGranite", "6E6A63", roughness=0.9, noise_scale=0.6)- deck = _slab("QuayDeck", granite, (40.0, 60.0, DECK_TOP), (CENTRE[0], CENTRE[1], DECK_TOP / 2), ctx.collection)- seat(deck, ctx.height_at) # its lowest vertices meet the ground+ b = Batch("QuayDeck") # one mesh per material, one placement row+ b.box(granite, (CENTRE[0], CENTRE[1], DECK_TOP / 2), (40.0, 60.0, DECK_TOP))+ deck = b.finish(ctx.collection, parent=False)[0]+ seat(deck, ctx.height_at) # its lowest vertices meet the groundplaced = [deck]- for i in range(6): # bollards along the water edge, ON the deck- x = CENTRE[0] + 18.0 + rng.uniform(-0.2, 0.2)- y = CENTRE[1] - 25.0 + i * 10.0+ for i in range(N_BOLLARDS): # where the plan puts them: along the water edge, ON the deck+ x, y = CENTRE[0] + 18.0 + rng.uniform(-0.2, 0.2), CENTRE[1] - 25.0 + i * 10.0placed.append(instance(ctx.collection, ctx.assets["bollard"], unique_name("Bollard", i), x, y,height_at=lambda px, py: DECK_TOP, rot_z=rng.uniform(0.0, 6.283)))- for a, b, frac in clear_of(placed): # [] here — nothing shares more than 10 % of the smaller box- print("quay: fix the overlap", a, "x", b, f"{frac:.0%}")+ for a, b_, frac in clear_of(placed): # [] here — nothing shares more than 10 % of the smaller box+ print("quay: fix the overlap", a, "x", b_, f"{frac:.0%}")return ctx.collection```diff --git a/harness/codeverse3d/prompts/scene_blender/cookbook.md b/harness/codeverse3d/prompts/scene_blender/cookbook.mddeleted file mode 100644index bbec2b86..00000000--- a/harness/codeverse3d/prompts/scene_blender/cookbook.md+++ /dev/null@@ -1,1365 +0,0 @@-# Scene cookbook — multi-file Blender bpy scenes (5.2 LTS), built and rendered headless by the harness--Every `python` snippet runs as-is INSIDE a zone's `build(ctx)`: the harness test suite writes-each one into `src/zones/<n>.py` under `import math · import bmesh · import bpy ·-from mathutils import Euler, Matrix, Vector, noise` with `rng = ctx.rng(7)` in scope, builds-the workspace in Blender 5.2.2 and lints it as a zone. A block whose first line is `# role: env` is-module-level code of `src/env.py` instead (the world is only ever built there). Z up, −Y-front, metres. Materials, lights and worlds always have a node tree (no `use_nodes`). The-shipped `src/lib/` does most of what is below in one call — its catalog is in your brief;-these snippets show the raw construction so you can read, extend or replace a call. The-harness inlines the relevant chapters into your prompts; the full file is at-`.3dcode/cookbook.md` in your workspace.--**The chapters that decide the score.** Scenes on this track lose most of their points to-a few repeatable defects, one chapter each:--| the judge / gate writes | read this chapter |-|---|---|-| "flat ground plane", "one colour", "no paths" | Ground that reads real |-| "a hard world edge is visible against the sky" | Horizon: the world must not end |-| `floating` / `sunken` / `interpenetration` (the placement gate) | Placement self-check |-| "monotonous / identical cones", "primitive stacked shapes" | Vegetation that reads real · Rocks, cliffs and boulders |-| "sparse", "a diorama on an empty plane", "no midground" | Scene layering · Set dressing |-| "flat light", "too dark", "monochrome", `dark_frame` | Atmosphere: time-of-day triads · Dusk / night lighting recipe · Lighting for Cycles + AgX |-| "frames at t=0 and t=1.5 are identical", `nothing_moves` | Motion you can SEE between t = 0 and t = 1.5 s |-| "plastic", "one grey material", "untextured" | Materials: Principled recipes and the lib palette |--## Environment (`src/env.py`): world + sun + ground + atmosphere — the scene's floor comes first--```python-# role: env-import math--import bmesh-import bpy-from mathutils import Vector, noise--BOUNDS = {"center": (0.0, 0.0, 5.0), "extents": (120.0, 120.0, 30.0)} # the plan's, in this frame-MOOD = "dusk" # the brief's time of day, decided ONCE (the time-of-day table below)-SUN_AZIMUTH_DEG = 250.0 # compass angle of the sun: 0 = +X, 90 = +Y-SUN_ELEVATION_DEG = 8.0-GROUND_SIZE = 320.0 # >= 2.5 x the plan span: the ground must reach past the haze-GROUND_SEGMENTS = 160 # ~1 vertex per 2 m over 320 m; fine enough for a carved path-PATH = [(-26.0, 20.0), (-9.0, 7.0), (4.0, -2.0), (17.0, -15.0), (26.0, -26.0)] # (x, y) polyline-PATH_HALF_W = 0.9 # a 1.8 m path, carved INTO the height so props on it sit on it---def _clamp(v, lo=0.0, hi=1.0):- return lo if v < lo else hi if v > hi else v---def _smooth(x, a, b):- t = _clamp((x - a) / (b - a))- return t * t * (3.0 - 2.0 * t)---def _mix(c1, c2, t):- return tuple(a + (b - a) * t for a, b in zip(c1, c2))---def _dist_to_path(x, y):- best = 1e9- for (ax, ay), (bx, by) in zip(PATH, PATH[1:]):- vx, vy, wx, wy = bx - ax, by - ay, x - ax, y - ay- t = _clamp((wx * vx + wy * vy) / (vx * vx + vy * vy))- best = min(best, math.hypot(wx - t * vx, wy - t * vy))- return best---def height_at(x, y):- """THE ground: rolling relief within +/-1.5 m (the plan's cameras are absolute heights), flat on- the path. Every zone seats on this; the ground mesh IS this function sampled."""- base = 1.1 * noise.fractal(Vector((x * 0.035, y * 0.035, 0.0)), 1.0, 2.0, 3) + 0.25 * math.sin(x * 0.08) * math.cos(y * 0.06)- flat = 1.0 - _clamp((_dist_to_path(x, y) - PATH_HALF_W) / 2.2) # 1 on the path -> 0 at 3.1 m- return base * (1.0 - 0.85 * flat) - 0.05 * flat # the path is flat and slightly sunken---def _ground_material():- """Base colour from the mesh's 'Blend' colour attribute (one material, four blended colours), plus a- noise bump so a flat area still catches the light."""- mat = bpy.data.materials.new("GroundMat")- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- bsdf.inputs["Roughness"].default_value = 1.0- attr = nodes.new("ShaderNodeAttribute")- attr.attribute_name = "Blend"- links.new(attr.outputs["Color"], bsdf.inputs["Base Color"])- tex = nodes.new("ShaderNodeTexNoise")- tex.inputs["Scale"].default_value = 6.0- tex.inputs["Detail"].default_value = 6.0- bump = nodes.new("ShaderNodeBump")- bump.inputs["Strength"].default_value = 0.25- links.new(tex.outputs["Factor"], bump.inputs["Height"])- links.new(bump.outputs["Normal"], bsdf.inputs["Normal"])- return mat---def _ground(ctx, mat):- """The terrain mesh displaced by height_at, colour-blended by height, slope, noise and the path."""- me = bpy.data.meshes.new("Ground")- bm = bmesh.new()- bmesh.ops.create_grid(bm, x_segments=GROUND_SEGMENTS, y_segments=GROUND_SEGMENTS, size=GROUND_SIZE / 2)- for v in bm.verts:- v.co.z = height_at(v.co.x, v.co.y)- for f in bm.faces:- f.smooth = True- bm.to_mesh(me)- bm.free()- grass, dry, dirt, rock, path = (0.33, 0.44, 0.18), (0.54, 0.51, 0.28), (0.42, 0.33, 0.20), (0.43, 0.42, 0.39), (0.66, 0.60, 0.49)- blend = me.color_attributes.new("Blend", "FLOAT_COLOR", "POINT")- e = GROUND_SIZE / GROUND_SEGMENTS- for v, c in zip(me.vertices, blend.data):- x, y, z = v.co- slope = min(1.0, (abs(height_at(x + e, y) - z) + abs(height_at(x, y + e) - z)) / (e * 1.2))- n = 0.5 + 0.5 * noise.noise(Vector((x * 0.35, y * 0.35, 0.0))) # breaks every band into patches- col = _mix(grass, dry, _clamp(0.35 + z * 0.5 + (n - 0.5) * 0.9))- col = _mix(col, dirt, _smooth(slope, 0.12, 0.45))- col = _mix(col, rock, _smooth(slope, 0.45, 0.9))- col = _mix(col, path, (1.0 - _smooth(_dist_to_path(x, y), PATH_HALF_W, PATH_HALF_W + 1.4)) * (0.75 + 0.25 * n))- c.color = (col[0], col[1], col[2], 1.0)- me.materials.append(mat)- ob = bpy.data.objects.new("Ground", me)- ctx.collection.objects.link(ob)- return ob---def _sun(ctx, color, energy):- """ONE Sun lamp from the compass angle + elevation; returns the unit vector TOWARDS the sun."""- az, el = math.radians(SUN_AZIMUTH_DEG), math.radians(SUN_ELEVATION_DEG)- towards_sun = Vector((math.cos(el) * math.cos(az), math.cos(el) * math.sin(az), math.sin(el)))- lamp = bpy.data.lights.new("Sun", "SUN")- lamp.energy = energy # W/m^2: 2-5 for day, 0.05-0.3 for a moon (AgX, exposure 0)- lamp.color = color- lamp.angle = math.radians(2.0) # soft-edged shadows; 0.5 deg is the real sun, too crisp for a diorama- ob = bpy.data.objects.new("Sun", lamp)- ob.rotation_euler = (-towards_sun).to_track_quat("-Z", "Y").to_euler()- ctx.collection.objects.link(ob)- return towards_sun---def _atmosphere(ctx, density, color):- """A BOUNDED fog volume over the scene (a world volume over a large scene swallows the sun). The- census reads a volume-only mesh as fog, never as matter, so it is no placement row."""- me = bpy.data.meshes.new("Atmosphere")- bm = bmesh.new()- bmesh.ops.create_cube(bm, size=1.0)- bmesh.ops.scale(bm, vec=(GROUND_SIZE, GROUND_SIZE, 40.0), verts=bm.verts)- bmesh.ops.translate(bm, vec=(BOUNDS["center"][0], BOUNDS["center"][1], 18.0), verts=bm.verts)- bm.to_mesh(me)- bm.free()- mat = bpy.data.materials.new("AtmosphereFog")- nodes, links = mat.node_tree.nodes, mat.node_tree.links- nodes.remove(nodes["Principled BSDF"])- fog = nodes.new("ShaderNodeVolumePrincipled")- fog.inputs["Density"].default_value = density- fog.inputs["Color"].default_value = (color[0], color[1], color[2], 1.0)- links.new(fog.outputs["Volume"], nodes["Material Output"].inputs["Volume"])- me.materials.append(mat)- ctx.collection.objects.link(bpy.data.objects.new("Atmosphere", me))---def build_env(ctx):- tod = apply_time_of_day(ctx, MOOD) # the world (sky texture + strength) from the table below- towards_sun = _sun(ctx, tod["sun_color"], tod["sun_energy"])- mat = _ground_material()- _ground(ctx, mat)- _atmosphere(ctx, tod["fog_density"], tod["fog_color"])- return {"ground_material": mat, "sun_direction": tuple(towards_sun), "mood": MOOD, "palette": tod}-```--Numbers: ground ≥ 2.5 × the plan span at ~1 vertex per 2 m (the path needs the resolution,-the far field does not); `height_at` within ±1.5 m of 0 inside the bounds; the fog box 40 m-tall over the whole ground; sun angle 2° (soft, readable shadows). `build_env` returns what-zones share — the ground material, the sun direction, the palette — and zones read it as-`ctx.env`.--## The exact contract the harness wrapper enforces--`src/scene.py` is **written by the harness**: a data file naming the zones, assets, heroes-and the plan's cameras, regenerated by the assembler and overwritten after your stages. The-wrapper then runs, in one Blender process, each in its own try/except:--```text-ctx.collection = scene root; out = env.build_env(ctx); ctx.env = out (a dict) ; ctx.height_at = env.height_at-for each hero: import public/assets/<snake>.glb into a Collection -> ctx.assets[snake]-for each asset: ctx.collection = its own Collection; assets.<snake>.build_<snake>(ctx) -> ctx.assets[snake]-for each zone: ctx.collection = its own Collection (active); zones.<snake>.build(ctx)- a raise = that zone DROPPED with file:line, everything it made removed; the rest builds-then: the plan's cameras, the asset sources excluded from the view layer, frame 1 set, the census written,- scene.blend saved, every camera rendered at frames 1 and 46 (t = 0 and t = 1.5 s)-```--So `build_env(ctx)`, `build(ctx)` and `build_<snake>(ctx, variant=0)` are the whole interface:-`build_<zone>(ctx)`, `create()`, `main()` and `register()` are NEVER called, and a module that-raises on import (a bad top-level statement) is gone from the scene. Link every object into-`ctx.collection`; an object linked into `ctx.scene.collection` instead belongs to no zone and is-graded as the harness's.--## Ground that reads real (blend, paths, edges — never one flat colour)--A single-colour plane is the #1 reason a scene reads as a toy. Real ground is **three or four-colours blended by height, slope and noise** (the `_ground` recipe above: a `FLOAT_COLOR`-attribute read by an Attribute node), with the path carved into `height_at` itself and dressed-edges where anything meets it. `lib.terrain.ground(...)` builds exactly that; `lib.terrain.-make_height_at(...)` the relief. Where a built thing meets the ground, sink it 3–5 cm AND-scatter 6–15 small pieces along the seam:--```python-def seam_dressing(ctx, name, points, count, rng, radius=0.18, color=(0.31, 0.42, 0.17)):- """Tufts / pebbles hugging a seam polyline [(x, y), ...] as ONE mesh (one placement row, exempt-free)."""- mat = bpy.data.materials.new(name + "Mat")- bsdf = mat.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Roughness"].default_value = 1.0- bm = bmesh.new()- for i in range(count):- u = (i + 0.5) / count * (len(points) - 1)- k = min(len(points) - 2, int(u))- f = u - k- x = points[k][0] + (points[k + 1][0] - points[k][0]) * f + rng.uniform(-0.5, 0.5)- y = points[k][1] + (points[k + 1][1] - points[k][1]) * f + rng.uniform(-0.5, 0.5)- r = radius * rng.uniform(0.5, 1.4)- new = bmesh.ops.create_icosphere(bm, subdivisions=1, radius=r)- bmesh.ops.scale(bm, vec=(1.0, 1.0, 0.6), verts=new["verts"])- bmesh.ops.translate(bm, vec=(x, y, ctx.height_at(x, y) - r * 0.35), verts=new["verts"]) # sunk a third- me = bpy.data.meshes.new(name)- bm.to_mesh(me)- bm.free()- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- ctx.collection.objects.link(ob)- return ob--seam = seam_dressing(ctx, "SeamTufts", [(-6.0, -6.0), (6.0, -6.0), (6.0, 6.0)], 24, rng)-print("seam tufts", len(seam.data.polygons))-```--Numbers: ≥ 3 blended colours, each with ≥ 8 % of the visible area; path 1.2–2.0 m wide; a-ground plane that is one flat colour, or a raised bed that is a sharp box on top of grass, are-both graded as defects (`flat_ground`, `undressed_scene`). A raised platform gets a chamfered-kerb (`bmesh.ops.bevel` on its top edges, offset 0.03), never a naked box edge.--## Horizon: the world must not end (closing the frame in Cycles)--The single most repeated judge complaint on this track is *"a hard world edge is visible-against the sky"*. Five rules kill it for good:--1. **Ground reaches past the haze.** Ground size ≥ 2.5 × the plan span, the fog box over all- of it; detail only needs to exist inside the bounds.-2. **The fog's colour is the sky's horizon colour.** Then the ground fades into the sky- instead of ending at it (the time-of-day table pairs them).-3. **A silhouette ring** at `radius ≈ 0.6 × (1 / fog density)` and ≥ 2 × the bounds- half-diagonal: 24–40 low-poly hills / treeline / rooftops / mesas, height 0.06–0.12 ×- radius. Measured on a 45 m garden: a ring at 46 m reads as distant hills, the same ring- at 95 m as a crater wall, at 20 m as a stone circle.-4. **Never tint the backdrop toward the fog colour.** The volume already hazes it by- distance; a pre-tinted ridge reads as pale cardboard (`placeholder_material`). Give it- its natural colour DARKENED (× 0.6–0.8) and let the fog do the haze.-5. **Solid geometry, never flat cut-outs.** A ring of planes reads as cardboard from every- oblique and overview camera, and its base floats.--```python-def horizon_ring(ctx, radius, rng, count=30, shape="hill", color=(0.17, 0.24, 0.16), darken=0.72):- """Build this from build_env (an env object is not a placement row): ONE mesh of low hills / blocks /- mesas around the content, each base at the ground. Named Sky... (SkyRidge, SkyHills): a sky-named- mesh wider than 50 m is BACKDROP to the census, so the overview cameras frame the content, not the ring."""- mat = bpy.data.materials.new("SkyRidgeMat")- bsdf = mat.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0] * darken, color[1] * darken, color[2] * darken, 1.0)- bsdf.inputs["Roughness"].default_value = 1.0- bm = bmesh.new()- for i in range(count):- a = (i + 0.35 * rng.random()) / count * math.tau- rr = radius * rng.uniform(0.82, 1.12)- hgt = radius * rng.uniform(0.06, 0.12)- wid = hgt * rng.uniform(1.1, 2.7)- x, y = math.cos(a) * rr, math.sin(a) * rr- if shape == "hill":- new = bmesh.ops.create_cone(bm, cap_ends=True, segments=7, radius1=wid, radius2=0.0, depth=hgt)- elif shape == "mesa":- new = bmesh.ops.create_cone(bm, cap_ends=True, segments=6, radius1=wid, radius2=wid * 0.75, depth=hgt)- else:- new = bmesh.ops.create_cube(bm, size=1.0)- bmesh.ops.scale(bm, vec=(wid, wid * 0.8, hgt), verts=new["verts"])- bmesh.ops.rotate(bm, cent=(0.0, 0.0, 0.0), matrix=Matrix.Rotation(rng.uniform(0.0, math.tau), 3, "Z"), verts=new["verts"])- bmesh.ops.translate(bm, vec=(x, y, ctx.height_at(x, y) + hgt / 2 - 1.5), verts=new["verts"]) # base 1.5 m under the ground- me = bpy.data.meshes.new("SkyRidge")- bm.to_mesh(me)- bm.free()- me.materials.append(mat)- ob = bpy.data.objects.new("SkyRidge", me)- ctx.collection.objects.link(ob)- return ob--ring = horizon_ring(ctx, 60.0, rng, shape="block", color=(0.17, 0.19, 0.25))-print("sky ridge pieces", len(ring.data.polygons))-```--Interiors (a greenhouse, a cabin) need no ring — but the *outside* seen through the glass must-still be something: the sky world plus 5–10 silhouette shapes beyond the windows.--## Dusk / night lighting recipe (dark scenes are the #1 gate failure)--"Dusk", "night", "moonlit", "lantern-lit" means COLOURED darkness, never black. The harness-measures every camera's frame; a frame that is too dark is a gate ERROR (`scene_frames:-dark_frame`) capping the score at 0.55. Exposure is fixed at 0 and you cannot touch it: take-the `dusk` / `night` row of the time-of-day table for the world, the sun (or moon) and the-fog, then add **practicals** — every lantern, window and fire near a camera is an emissive-surface (the lamp you SEE, Emission Strength 5–10, it blooms) plus its own Point light with a-radius (the light that reaches the ground: 30–60 W within ~3 m). `lib.lighting.practical(...)`-is this in one call; the raw version, as ONE placed thing (post → bulb → light, parented, one-placement row seated on the ground):--```python-def practical(ctx, name, x, y, height=2.3, color=(1.0, 0.70, 0.44), energy=45.0, radius=0.42, rng=None):- wood = bpy.data.materials.new(name + "Post")- wood.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.16, 0.12, 0.08, 1.0)- me = bpy.data.meshes.new(name)- bm = bmesh.new()- bmesh.ops.create_cone(bm, cap_ends=True, segments=10, radius1=0.045, radius2=0.035, depth=height)- bmesh.ops.translate(bm, vec=(0.0, 0.0, height / 2), verts=bm.verts)- bm.to_mesh(me)- bm.free()- me.materials.append(wood)- post = bpy.data.objects.new(name, me)- post.location = (x, y, ctx.height_at(x, y) - 0.03) # 3 cm into the ground: the seam reads planted- ctx.collection.objects.link(post)- glow = bpy.data.materials.new(name + "Glow")- bsdf = glow.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Emission Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Emission Strength"].default_value = 8.0- bme = bpy.data.meshes.new(name + "Bulb")- bm = bmesh.new()- bmesh.ops.create_icosphere(bm, subdivisions=2, radius=0.09)- bm.to_mesh(bme)- bm.free()- bme.materials.append(glow)- bulb = bpy.data.objects.new(name + "Bulb", bme)- bulb.parent = post # a child: the post is the ONE placement row- bulb.location = (0.0, 0.0, height + 0.05) # relative to the post- ctx.collection.objects.link(bulb)- lamp = bpy.data.lights.new(name + "Light", "POINT")- lamp.energy = energy- lamp.color = color- lamp.shadow_soft_size = radius # a radius: soft, physical falloff- light = bpy.data.objects.new(name + "Light", lamp)- light.parent = bulb- ctx.collection.objects.link(light)- return post--for i, (x, y) in enumerate([(4.0, 2.0), (-3.0, 5.0)]):- practical(ctx, f"Lantern_{i}", x, y)-print("practicals", 2)-```--Rules of thumb: the moon is a Sun lamp at 0.05–0.3 W/m², cool (0.66, 0.75, 1.0), elevation-30–50°; the night world is a deep blue Background (never black) at strength 0.05–0.15; ground-albedo ≥ 0.25; every practical near a camera path gets its own light, the far ones share ONE-emissive material and light nothing. **Exposure self-check (after each build):** `scene_views`-→ the frame table (`camera_checks`) for every authored camera: read `mean_lum` / `dark_frac` /-`blown_frac` / `content_frac`. If a frame is dark, raise the world strength by +0.05 and the-practicals by +15 W and re-render — never add a second Sun.--## Atmosphere: time-of-day triads with numbers--Pick the row, hand its numbers to the world and the sun, then only tune the practicals. Cycles-reads physical units and AgX compresses the top: a day scene is a Sun of 3–5 W/m² under a sky-world at strength 0.3–0.5; dusk is a low warm sun at 1–2 with a strong dusty sky; night is a-moon at 0.1 with a blue world at 0.1. The fog colour is always the sky's **horizon** colour —-never white, never grey unless the brief says overcast.--| time of day | world | strength | sun W/m² | sun colour | sun elev | air density | fog density | fog colour |-|---|---|---|---|---|---|---|---|---|-| dawn | sky texture | 0.25 | 2.0 | (1.00, 0.69, 0.45) | 8° | 1.6 | 0.006 | (0.91, 0.63, 0.42) |-| morning | sky texture | 0.40 | 3.5 | (1.00, 0.95, 0.82) | 35° | 1.0 | 0.004 | (0.74, 0.84, 0.92) |-| noon | sky texture | 0.50 | 5.0 | (1.00, 0.98, 0.94) | 70° | 0.8 | 0.003 | (0.81, 0.89, 0.95) |-| golden | sky texture | 0.30 | 2.5 | (1.00, 0.76, 0.48) | 12° | 1.8 | 0.006 | (0.94, 0.66, 0.38) |-| overcast | flat colour (0.78, 0.81, 0.84) | 0.60 | 1.2 | (0.85, 0.87, 0.90) | 45° | — | 0.008 | (0.76, 0.79, 0.82) |-| dusk | sky texture | 0.20 | 1.2 | (1.00, 0.63, 0.38) | 6° | 2.0 | 0.006 | (0.85, 0.44, 0.23) |-| night (moon) | flat colour (0.05, 0.08, 0.19) | 0.10 | 0.12 | (0.66, 0.75, 1.00) | 40° | — | 0.004 | (0.13, 0.19, 0.35) |--```python-# role: env-TIME_OF_DAY = {- "dawn": {"sky": "texture", "world_strength": 0.25, "sun_energy": 2.0, "sun_color": (1.0, 0.69, 0.45), "sun_elevation": 8.0, "air": 1.6, "fog_density": 0.006, "fog_color": (0.91, 0.63, 0.42)},- "morning": {"sky": "texture", "world_strength": 0.40, "sun_energy": 3.5, "sun_color": (1.0, 0.95, 0.82), "sun_elevation": 35.0, "air": 1.0, "fog_density": 0.004, "fog_color": (0.74, 0.84, 0.92)},- "noon": {"sky": "texture", "world_strength": 0.50, "sun_energy": 5.0, "sun_color": (1.0, 0.98, 0.94), "sun_elevation": 70.0, "air": 0.8, "fog_density": 0.003, "fog_color": (0.81, 0.89, 0.95)},- "golden": {"sky": "texture", "world_strength": 0.30, "sun_energy": 2.5, "sun_color": (1.0, 0.76, 0.48), "sun_elevation": 12.0, "air": 1.8, "fog_density": 0.006, "fog_color": (0.94, 0.66, 0.38)},- "overcast": {"sky": (0.78, 0.81, 0.84), "world_strength": 0.60, "sun_energy": 1.2, "sun_color": (0.85, 0.87, 0.90), "sun_elevation": 45.0, "air": 1.0, "fog_density": 0.008, "fog_color": (0.76, 0.79, 0.82)},- "dusk": {"sky": "texture", "world_strength": 0.20, "sun_energy": 1.2, "sun_color": (1.0, 0.63, 0.38), "sun_elevation": 6.0, "air": 2.0, "fog_density": 0.006, "fog_color": (0.85, 0.44, 0.23)},- "night": {"sky": (0.05, 0.08, 0.19), "world_strength": 0.10, "sun_energy": 0.12, "sun_color": (0.66, 0.75, 1.0), "sun_elevation": 40.0, "air": 1.0, "fog_density": 0.004, "fog_color": (0.13, 0.19, 0.35)},-}---def apply_time_of_day(ctx, key):- """The world of the brief's time of day (env.py only: the world is the env's). A physical sky texture- by day (MULTIPLE_SCATTERING — 'NISHITA' no longer exists; its knobs are sun_elevation / sun_rotation /- air_density / ozone_density / altitude), a flat deep colour for overcast / night; the sun disc is off- because the Sun LAMP is the sun. Returns the row for the lamp and the fog."""- t = TIME_OF_DAY.get(key, TIME_OF_DAY["morning"])- world = bpy.data.worlds.new("Sky")- ctx.scene.world = world- nodes, links = world.node_tree.nodes, world.node_tree.links- bg = nodes["Background"]- if t["sky"] == "texture":- sky = nodes.new("ShaderNodeTexSky")- sky.sky_type = "MULTIPLE_SCATTERING"- sky.sun_disc = False- sky.sun_elevation = math.radians(t["sun_elevation"])- sky.sun_rotation = math.radians(SUN_AZIMUTH_DEG)- sky.air_density = t["air"] # hazier, warmer at a low sun- links.new(sky.outputs["Color"], bg.inputs["Color"])- else:- bg.inputs["Color"].default_value = (t["sky"][0], t["sky"][1], t["sky"][2], 1.0)- bg.inputs["Strength"].default_value = t["world_strength"]- return t-```--**Colour temperature contrast is the whole trick**: the key (sun) is warm, the fill (the sky-world) is cool — a sky texture gives you that for free; a flat warm world under a warm sun is-the monochrome-orange soup scenes are marked down for. Shade must carry sky colour, never-black: with the sun under 25° keep the world strength ≥ 0.2.--## Lighting for Cycles + AgX: sun, sky and area numbers (exposure stays 0)--The harness renders with Cycles at 32 samples + denoise, AgX, exposure 0, and you cannot-change any of it — so the NUMBERS are the lighting. Sun 1–5 W/m² (table above); the world-0.1–0.6; an Area light for a window or a studio key: 200–800 W at 1–2 m size (`shape =-'DISK'` or `'RECTANGLE'`, aimed with `to_track_quat('-Z', 'Y')`); a Spot 100–400 W, `spot_size`-45–60°, `spot_blend` 0.3; a practical Point 30–60 W with `shadow_soft_size` 0.3–0.5. Never a-light at 1000 W "to be safe": AgX rolls the highlights off and the frame reads blown-(`blown_frac`). Soft shadows come from the light's SIZE (`angle` on a Sun, `shadow_soft_size`-on a Point, `size` on an Area), not from a second light.--```python-def area_light(ctx, name, loc, target, color=(1.0, 0.93, 0.80), energy=400.0, size=1.5, shape="DISK"):- """An Area light aimed at `target` — a window, a studio key, a street lamp's throw."""- data = bpy.data.lights.new(name, "AREA")- data.energy = energy- data.color = color- data.size = size- data.shape = shape- ob = bpy.data.objects.new(name, data)- ob.location = loc- ob.rotation_euler = (Vector(target) - Vector(loc)).to_track_quat("-Z", "Y").to_euler()- ctx.collection.objects.link(ob)- return ob--key = area_light(ctx, "WindowKey", (6.0, -4.0, 3.2), (0.0, 0.0, 0.8))-print("area light", key.data.energy)-```--Zones add lights only for practicals and the odd window; the Sun and the world are-`src/env.py`'s (the lint rejects a world built anywhere else).--## Atmosphere volume: the fog box, local mist and light shafts--The env's fog box (`_atmosphere` above, density 0.003–0.008, the horizon colour) is the depth-cue that makes distance read. A local MIST — over a pond, in a hollow, under a lantern — is a-second, denser, lower box: a volume-only mesh is fog to the census (no placement row), so it-can sit anywhere. Light shafts are the same box with a higher `Anisotropy` (0.4–0.6) placed-where the sun crosses an opening; never a cone mesh with an emissive material.--```python-def mist(ctx, name, center, size, density=0.02, color=(0.80, 0.84, 0.88), anisotropy=0.0):- me = bpy.data.meshes.new(name)- bm = bmesh.new()- bmesh.ops.create_cube(bm, size=1.0)- bmesh.ops.scale(bm, vec=size, verts=bm.verts)- bmesh.ops.translate(bm, vec=center, verts=bm.verts)- bm.to_mesh(me)- bm.free()- mat = bpy.data.materials.new(name + "Vol")- nodes, links = mat.node_tree.nodes, mat.node_tree.links- nodes.remove(nodes["Principled BSDF"])- vol = nodes.new("ShaderNodeVolumePrincipled")- vol.inputs["Density"].default_value = density- vol.inputs["Color"].default_value = (color[0], color[1], color[2], 1.0)- vol.inputs["Anisotropy"].default_value = anisotropy- links.new(vol.outputs["Volume"], nodes["Material Output"].inputs["Volume"])- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- ctx.collection.objects.link(ob)- return ob--pond_mist = mist(ctx, "PondMist", (12.0, -8.0, 0.6), (16.0, 12.0, 1.2), density=0.03)-print("mist", pond_mist.name)-```--## Water--Water is a subdivided plane with a Principled BSDF that TRANSMITS (Transmission Weight 1, IOR-1.33, Roughness 0.05–0.15, a dark teal Base Color) over a bed carved BELOW the water level in-`height_at` (a radial depression — or the shore z-fights and the shallows never read), plus a-noise bump for ripples whose Mapping node scrolls between the two frames (the motion the judge-diffs). `lib.water.water_surface(...)` and `lib.materials.water(...)` are this in two calls;-`lib.water.pool_height` the bed. Name it `Water…` (the census classifies it; a foot at or-under the water is never "sunken").--```python-def water_plane(ctx, name, center, radius, level, color=(0.09, 0.25, 0.29), segments=48):- mat = bpy.data.materials.new(name + "Mat")- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Roughness"].default_value = 0.10- bsdf.inputs["IOR"].default_value = 1.33- bsdf.inputs["Transmission Weight"].default_value = 1.0- coords = nodes.new("ShaderNodeTexCoord")- mapping = nodes.new("ShaderNodeMapping")- ripple = nodes.new("ShaderNodeTexNoise")- ripple.inputs["Scale"].default_value = 0.8- ripple.inputs["Detail"].default_value = 8.0- bump = nodes.new("ShaderNodeBump")- bump.inputs["Strength"].default_value = 0.12- links.new(coords.outputs["Object"], mapping.inputs["Vector"])- links.new(mapping.outputs["Vector"], ripple.inputs["Vector"])- links.new(ripple.outputs["Factor"], bump.inputs["Height"])- links.new(bump.outputs["Normal"], bsdf.inputs["Normal"])- # the ripples travel 0.6 m / 0.2 m between the two sampled times: a still mirror reads as static- loc = mapping.inputs["Location"]- loc.default_value = (0.0, 0.0, 0.0)- loc.keyframe_insert("default_value", frame=ctx.frame(0.0))- loc.default_value = (0.6, 0.2, 0.0)- loc.keyframe_insert("default_value", frame=ctx.frame(1.5))- me = bpy.data.meshes.new(name)- bm = bmesh.new()- bmesh.ops.create_circle(bm, cap_ends=True, segments=segments, radius=radius)- bm.to_mesh(me)- bm.free()- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- ob.location = (center[0], center[1], level)- ctx.collection.objects.link(ob)- return ob--pond = water_plane(ctx, "WaterPond", (12.0, -8.0), 6.0, -0.25)-print("water", pond.name)-```--## Vegetation that reads real (species, jitter, clusters, ground cover)--A ring of identical cones is the second most common complaint. Fix it with **three to five-species** (`lib.vegetation.tree(...)`: broadleaf / cypress / oak / pine; `shrub`, `fern`,-`tropical`), per-instance **scale / hue / rotation jitter**, **clustered** placement and a-**ground-cover** layer. Raw: each tree is ONE mesh with two material slots (one placement-row), its hue jitter through `Object Info → Color` so a dozen trees share one material and-each still differs:--```python-def foliage_material(name, base=(0.22, 0.38, 0.14)):- """Base colour = the OBJECT's colour (ob.color), so one material serves every tree with its own hue."""- mat = bpy.data.materials.new(name)- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- bsdf.inputs["Roughness"].default_value = 0.85- info = nodes.new("ShaderNodeObjectInfo")- links.new(info.outputs["Color"], bsdf.inputs["Base Color"])- return mat---def tree_mesh(kind, k, rng):- """trunk + crown in one bmesh; the crown's faces get material slot 1. k = scale jitter (0.8-1.5)."""- bm = bmesh.new()- bmesh.ops.create_cone(bm, cap_ends=True, segments=7, radius1=0.20 * k, radius2=0.10 * k, depth=2.6 * k)- bmesh.ops.translate(bm, vec=(0.0, 0.0, 1.3 * k), verts=bm.verts)- n_trunk = len(bm.faces)- if kind == "conifer":- crown = bmesh.ops.create_cone(bm, cap_ends=True, segments=8, radius1=1.15 * k, radius2=0.0, depth=4.4 * k)- bmesh.ops.translate(bm, vec=(0.0, 0.0, 4.4 * k), verts=crown["verts"])- else: # broadleaf / scrub: a displaced ball, flattened- r = (1.7 if kind == "broadleaf" else 0.75) * k- crown = bmesh.ops.create_icosphere(bm, subdivisions=2, radius=r)- off = Vector((rng.uniform(0.0, 100.0), rng.uniform(0.0, 100.0), 0.0)) # a different crown every tree- for v in crown["verts"]:- v.co *= 1.0 + 0.28 * noise.noise(v.co * 1.3 + off)- bmesh.ops.scale(bm, vec=(1.0, 1.0, 0.8), verts=crown["verts"])- bmesh.ops.translate(bm, vec=(0.0, 0.0, (3.4 if kind == "broadleaf" else 1.0) * k), verts=crown["verts"])- bm.faces.ensure_lookup_table()- for f in bm.faces[n_trunk:]:- f.material_index = 1- for f in bm.faces:- f.smooth = kind != "conifer"- me = bpy.data.meshes.new("Tree")- bm.to_mesh(me)- bm.free()- return me---def clustered_points(n, area, rng, clusters=0):- """area = (cx, cy, w, d); K cluster seeds, members scattered around them (Poisson-ish, never a grid)."""- cx, cy, w, d = area- k = clusters or max(2, round(n / 7))- seeds = [(cx + (rng.random() - 0.5) * w * 0.9, cy + (rng.random() - 0.5) * d * 0.9) for _ in range(k)]- sp = min(w, d) * 0.13- out = []- for i in range(n):- sx, sy = seeds[i % k]- a, r = rng.random() * math.tau, sp * math.sqrt(rng.random())- out.append((sx + math.cos(a) * r, sy + math.sin(a) * r))- return out---def forest(ctx, name, area, mix, bark, leaves, rng, height_at):- """mix = {kind: count}; one mesh object per tree (ONE placement row each), seated 3 cm into the ground."""- objs = []- i = 0- for kind, count in mix.items():- for x, y in clustered_points(count, area, rng):- k = rng.uniform(0.8, 1.5)- me = tree_mesh(kind, k, rng)- me.materials.append(bark)- me.materials.append(leaves)- ob = bpy.data.objects.new(f"{name}{kind.capitalize()}_{i}", me)- ob.location = (x, y, height_at(x, y) - 0.03)- ob.rotation_euler = (rng.uniform(-0.05, 0.05), rng.uniform(-0.05, 0.05), rng.uniform(0.0, math.tau)) # a few degrees of lean, full yaw- hue = (0.22 + rng.uniform(-0.04, 0.04), 0.38 + rng.uniform(-0.08, 0.08), 0.14 + rng.uniform(-0.05, 0.05))- ob.color = (hue[0], hue[1], hue[2], 1.0) # hue + value jitter- ctx.collection.objects.link(ob)- objs.append(ob)- i += 1- return objs--bark = bpy.data.materials.new("Bark")-bark.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.33, 0.25, 0.17, 1.0)-bark.node_tree.nodes["Principled BSDF"].inputs["Roughness"].default_value = 0.95-trees = forest(ctx, "Grove", (0.0, 0.0, 40.0, 40.0), {"conifer": 5, "broadleaf": 4, "scrub": 6}, bark, foliage_material("Leaves"), rng, ctx.height_at)-print("trees", len(trees), "species", 3)-```--**Ground cover** turns "objects on a plane" into "plants growing out of the ground": a-geometry-nodes cloud of blades over a patch (`lib.vegetation.grass_patch(...)`) — an instance-cloud, counted as instances by the census and exempt from per-asset placement:--```python-def grass_patch(ctx, name, center, size, density, seed, height_at, color=(0.29, 0.42, 0.16)):- """A surface displaced by height_at + a hidden 3-sided blade instanced on it by geometry nodes."""- mat = bpy.data.materials.new(name + "Mat")- mat.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- me = bpy.data.meshes.new(name)- bm = bmesh.new()- bmesh.ops.create_grid(bm, x_segments=24, y_segments=24, size=size / 2)- for v in bm.verts:- v.co.z = height_at(center[0] + v.co.x, center[1] + v.co.y) - 0.02- bm.to_mesh(me)- bm.free()- patch = bpy.data.objects.new(name, me)- patch.location = (center[0], center[1], 0.0)- ctx.collection.objects.link(patch)- bme = bpy.data.meshes.new(name + "Blade")- bm = bmesh.new()- bmesh.ops.create_cone(bm, cap_ends=False, segments=3, radius1=0.05, radius2=0.0, depth=0.34) # 3 faces per blade- bmesh.ops.translate(bm, vec=(0.0, 0.0, 0.17), verts=bm.verts)- bm.to_mesh(bme)- bm.free()- bme.materials.append(mat)- blade = bpy.data.objects.new(name + "Blade", bme)- blade.hide_render = True # the source is never seen, only its instances- blade.hide_viewport = True- ctx.collection.objects.link(blade)- ng = bpy.data.node_groups.new(name + "Scatter", "GeometryNodeTree")- ng.interface.new_socket("Geometry", in_out="INPUT", socket_type="NodeSocketGeometry")- ng.interface.new_socket("Geometry", in_out="OUTPUT", socket_type="NodeSocketGeometry")- dens = ng.interface.new_socket("Density", in_out="INPUT", socket_type="NodeSocketFloat")- n = ng.nodes- gi, go = n.new("NodeGroupInput"), n.new("NodeGroupOutput")- dist = n.new("GeometryNodeDistributePointsOnFaces")- dist.inputs["Seed"].default_value = seed- scale = n.new("FunctionNodeRandomValue") # FLOAT (the default): inputs 0 / 1 are Min / Max- scale.inputs[0].default_value = 0.6- scale.inputs[1].default_value = 1.6- scale.inputs["Seed"].default_value = seed- inst = n.new("GeometryNodeInstanceOnPoints")- info = n.new("GeometryNodeObjectInfo")- info.inputs["Object"].default_value = blade- join = n.new("GeometryNodeJoinGeometry")- ng.links.new(gi.outputs["Geometry"], dist.inputs["Mesh"])- ng.links.new(gi.outputs["Density"], dist.inputs["Density"])- ng.links.new(dist.outputs["Points"], inst.inputs["Points"])- ng.links.new(dist.outputs["Rotation"], inst.inputs["Rotation"])- ng.links.new(scale.outputs["Value"], inst.inputs["Scale"])- ng.links.new(info.outputs["Geometry"], inst.inputs["Instance"])- ng.links.new(inst.outputs["Instances"], join.inputs["Geometry"])- ng.links.new(gi.outputs["Geometry"], join.inputs["Geometry"])- ng.links.new(join.outputs["Geometry"], go.inputs["Geometry"])- mod = patch.modifiers.new("Scatter", "NODES")- mod.node_group = ng- getattr(mod.properties.inputs, dens.identifier).value = density # Blender 5.2: inputs are RNA properties, never mod["Socket_2"]- return patch--cover = grass_patch(ctx, "GroundCover", (0.0, -14.0), 20.0, 6.0, 9, ctx.height_at)-print("ground cover", cover.name)-```--Density per 100 m² of planted zone: 2–5 trees, 8–20 shrubs, 250–600 blades (`density` 2.5–6-per m²), 30–80 litter pieces. Less and the judge writes *"monotonous / undressed"*.--## Rocks, cliffs and boulders that read organic (never a row of boxes)--Stacked cuboids read as buildings. A rock is a **noise-displaced icosphere, flattened and-yawed** (`lib.terrain.boulder`, `rock_field`, `talus`); a cliff is a **ridge polyline of rotated,-non-uniformly scaled chunks with jittered strata** (`lib.terrain.cliff`), never an axis-aligned-wall:--```python-def rock_geometry(bm, radius, rough, seed, detail=2):- """A displaced icosphere into `bm`; returns its verts. Flatter than tall = weathered."""- new = bmesh.ops.create_icosphere(bm, subdivisions=detail, radius=radius)- off = Vector((seed * 13.0, seed * 7.0, 0.0))- for v in new["verts"]:- d = 1.0 + rough * noise.noise(v.co * (1.7 / radius) + off)- v.co = Vector((v.co.x * d, v.co.y * d, v.co.z * d * 0.8))- return new["verts"]---def boulder(ctx, name, x, y, radius, rng, color=(0.42, 0.40, 0.37)):- mat = bpy.data.materials.new(name + "Mat")- bsdf = mat.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Roughness"].default_value = 0.95- bm = bmesh.new()- verts = rock_geometry(bm, radius, 0.34, rng.randrange(1000), detail=2)- bmesh.ops.scale(bm, vec=(rng.uniform(1.0, 1.4), rng.uniform(0.8, 1.1), 1.0), verts=verts) # non-uniform- for f in bm.faces:- f.smooth = True- me = bpy.data.meshes.new(name)- bm.to_mesh(me)- bm.free()- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- ob.location = (x, y, ctx.height_at(x, y) + radius * 0.45) # a rock sits partly IN the ground (allowed)- ob.rotation_euler = (0.0, 0.0, rng.uniform(0.0, math.tau))- ctx.collection.objects.link(ob)- return ob---def cliff_ridge(ctx, name, ridge, count, height, rng, strata=((0.55, 0.29, 0.18), (0.66, 0.40, 0.24), (0.75, 0.54, 0.35), (0.48, 0.23, 0.15))):- """Chunks straddling a polyline [(x, y), ...], stacked in strata bands, as ONE mesh with a per-vertex- 'Strata' colour (an Attribute node reads it)."""- mat = bpy.data.materials.new(name + "Mat")- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- bsdf.inputs["Roughness"].default_value = 0.95- attr = nodes.new("ShaderNodeAttribute")- attr.attribute_name = "Strata"- links.new(attr.outputs["Color"], bsdf.inputs["Base Color"])- bm = bmesh.new()- bands = []- for i in range(count):- u = i / (count - 1) * (len(ridge) - 1)- k = min(len(ridge) - 2, int(u))- f = u - k- bx = ridge[k][0] + (ridge[k + 1][0] - ridge[k][0]) * f + rng.uniform(-1.7, 1.7)- by = ridge[k][1] + (ridge[k + 1][1] - ridge[k][1]) * f + rng.uniform(-1.7, 1.7)- layer = i % len(strata)- lift = height * (0.18 + 0.26 * layer) * rng.uniform(0.75, 1.25)- verts = rock_geometry(bm, 1.0, 0.42, rng.randrange(1000), detail=1)- bmesh.ops.scale(bm, vec=(rng.uniform(2.6, 6.0), rng.uniform(2.2, 5.2), lift * rng.uniform(0.7, 1.3)), verts=verts)- bmesh.ops.rotate(bm, cent=(0.0, 0.0, 0.0), matrix=Euler((rng.uniform(-0.25, 0.25), rng.uniform(0.0, math.tau), rng.uniform(-0.25, 0.25))).to_matrix(), verts=verts)- bmesh.ops.translate(bm, vec=(bx, by, ctx.height_at(bx, by) + lift * 0.55), verts=verts)- bands.append((len(verts), strata[layer]))- for f in bm.faces:- f.smooth = True- me = bpy.data.meshes.new(name)- bm.to_mesh(me)- bm.free()- colour = me.color_attributes.new("Strata", "FLOAT_COLOR", "POINT")- j = 0- for n, (r, g, b) in bands: # verts were appended band by band, in order- for _ in range(n):- colour.data[j].color = (r, g, b, 1.0)- j += 1- me.materials.append(mat)- ob = bpy.data.objects.new(name, me)- ctx.collection.objects.link(ob)- return ob--rocks = [boulder(ctx, f"Boulder_{i}", -8.0 + i * 2.2, 12.0 + (i % 2) * 1.5, rng.uniform(0.4, 1.3), rng) for i in range(4)]-cliff = cliff_ridge(ctx, "CliffRidge", [(-30.0, 14.0), (-12.0, 10.0), (2.0, 6.0), (18.0, 9.0), (30.0, 16.0)], 26, 9.0, rng)-print("boulders", len(rocks), "cliff verts", len(cliff.data.vertices))-```--Rules: chunk yaw random over the full circle; scale non-uniform (x ≠ y ≠ z by ≥ 20 %);-strata luminance differing by ≥ 0.08; the ridge polyline bending ≥ 15° at least twice; floor-boulders reuse `rock_geometry` at 0.3–1.6 m and may sit a third of their height IN the ground-(the gate allows rocks, posts and bushes partly buried).--## Set dressing: how many props a place needs--Judges call a scene "sparse", "token" or "undressed" long before they call it wrong. Counts-that read as *lived in*, per zone (a zone is typically 10 × 10 m to 30 × 30 m):--| scene type | hero assets | mid props (0.3–1.5 m) | small props (< 0.3 m) | ground cover / litter |-|---|---|---|---|---|-| garden / park | 3–5 (lantern, bridge, bench) | 12–25 (rocks, planters, pots, stumps, buckets) | 25–60 (pebbles, leaves, tools, cups, twigs) | 300–800 blades |-| desert / canyon | 2–4 (hero boulder, arch, wreck) | 15–30 boulders in 3 size bands | 30–70 (pebbles, bones, dry brush) | 60–200 scrub clumps |-| harbour / street | 3–6 (boat, crane, cart) | 15–30 (crates, barrels, bollards, nets, lamps) | 30–80 (ropes, buckets, bottles, fish boxes) | 100–300 weeds / litter |-| interior | 3–6 (bench rows, a stove) | 15–30 (pots, tools, crates, stools) | 40–100 (labels, jars, gloves, cups) | n/a |--Cheap rules: 3 size bands per prop family; props go **against something** (a wall base, a-path edge, under a bench) — props alone in open ground read as scatter; never a grid or a-ring (≥ 20 % positional jitter, full yaw jitter); repeats are collection instances of an-asset, each with its own unique name (`lib.scatter.scatter(...)` does the names, the seating-and the jitter):--```python-def place_asset(ctx, source, name, x, y, rot_z, height_at, scale=1.0):- """ONE collection-instance Empty of an asset Collection, seated: one placement row, PascalCase unique name."""- ob = bpy.data.objects.new(name, None)- ob.instance_type = "COLLECTION"- ob.instance_collection = source- ob.location = (x, y, height_at(x, y))- ob.rotation_euler = (0.0, 0.0, rot_z)- ob.scale = (scale, scale, scale)- ctx.collection.objects.link(ob)- return ob---def along_seam(points, n, rng, offset=0.6):- """n (x, y, yaw) spots hugging a seam polyline, on its +side, jittered: props AGAINST a wall or a path edge."""- out = []- for i in range(n):- u = (i + 0.5 + rng.uniform(-0.3, 0.3)) / n * (len(points) - 1)- k = min(len(points) - 2, max(0, int(u)))- f = u - k- (ax, ay), (bx, by) = points[k], points[k + 1]- dx, dy = bx - ax, by - ay- length = math.hypot(dx, dy) or 1.0- nx, ny = -dy / length, dx / length # the seam's left normal- d = offset * rng.uniform(0.7, 1.4)- out.append((ax + dx * f + nx * d, ay + dy * f + ny * d, math.atan2(dy, dx) + rng.uniform(-0.4, 0.4)))- return out--source = ctx.assets.get("bollard") # a planned asset: ctx.assets['<snake>']-if source is None: # (no such plan asset: a stand-in crate)- cm = bpy.data.meshes.new("CrateStandIn")- cb = bmesh.new()- bmesh.ops.create_cube(cb, size=0.6)- bmesh.ops.translate(cb, vec=(0.0, 0.0, 0.3), verts=cb.verts)- cb.to_mesh(cm)- cb.free()- source = bpy.data.collections.new("CrateStandIn")- ctx.collection.children.link(source)- source.objects.link(bpy.data.objects.new("CrateStandIn", cm))-spots = along_seam([(-10.0, -4.0), (0.0, -4.0), (8.0, 2.0)], 9, rng)-props = [place_asset(ctx, source, f"QuayProp_{i}", x, y, yaw, ctx.height_at, scale=rng.uniform(0.85, 1.15)) for i, (x, y, yaw) in enumerate(spots)]-print("props against the seam", len(props))-```--## Scene layering: foreground, midground, background--A "diorama on an empty plane" scores ~0.5 whatever else you do. Every authored camera needs-**three depth layers**, built on purpose:--| layer | distance from camera | what lives there | how much of the frame |-|---|---|---|---|-| foreground frame | 1.5–5 m | a branch, a post, a parapet edge, a leaning tool, tall grass, an arch | 10–25% of the frame area, usually at an edge, may be partly cut off |-| midground subject | 8–30 m | the hero assets: what the brief is about | fills the centre third |-| background | 40 m–the haze | the backdrop ring, a distant treeline / skyline / mesas, the sky | the top third |--```python-CAMERAS = [((24.0, -26.0, 9.0), (0.0, 0.0, 2.0)), ((8.0, -22.0, 1.7), (0.0, 1.0, 1.4))] # the plan's, in this frame---def frame_foreground(ctx, cam, obj, dist=3.0, side=-1.0, lift=0.0):- """Place `obj` just off the camera's axis at `dist` so it brackets the shot (a hand-placed framer)."""- eye, at = Vector(cam[0]), Vector(cam[1])- fwd = (at - eye)- fwd.z = 0.0- fwd.normalize()- right = fwd.cross(Vector((0.0, 0.0, 1.0)))- p = eye + fwd * dist + right * (side * dist * 0.75)- obj.location = (p.x, p.y, ctx.height_at(p.x, p.y) + lift)- obj.rotation_euler = (0.0, 0.0, math.atan2(eye.y - p.y, eye.x - p.x))- return obj---def camera_mask(cameras, radius=4.0):- """(x, y) -> True inside a clearance disc around any camera, or on its first quarter towards the subject:- SKIP scattered instances there (scatter is blind; a tree 1 m in front of the lens ruins the shot)."""- discs = [(c[0][0], c[0][1], radius) for c in cameras]- for (px, py, _), (lx, ly, _) in cameras:- discs.append((px + (lx - px) * 0.22, py + (ly - py) * 0.22, radius * 0.6))- return lambda x, y: any((x - cx) ** 2 + (y - cy) ** 2 < r * r for cx, cy, r in discs)--fm = bpy.data.meshes.new("Framer")-fb = bmesh.new()-bmesh.ops.create_cone(fb, cap_ends=True, segments=8, radius1=0.08, radius2=0.05, depth=2.4)-bmesh.ops.translate(fb, vec=(0.0, 0.0, 1.2), verts=fb.verts)-fb.to_mesh(fm)-fb.free()-framer = bpy.data.objects.new("FramerPost", fm)-ctx.collection.objects.link(framer)-frame_foreground(ctx, CAMERAS[1], framer, side=-1.0)-blocked = camera_mask(CAMERAS)-print("framer at", tuple(round(v, 2) for v in framer.location), "mask blocks (8,-22)?", blocked(8.0, -22.0), "(0,0)?", blocked(0.0, 0.0))-```--**Keep the cameras' first metres clear**, and the establishing camera sits *above the-canopy* looking DOWN at the subject. Atmospheric perspective does the rest: with the fog the-horizon colour, a background object loses contrast and saturation with distance for free —-darken the distant material, never tint it.--## Motion you can SEE between t = 0 and t = 1.5 s--The harness renders every camera at t = 0 and t = 1.5 s (frames 1 and 46 at 30 fps) and the-judge diffs the two frames. Sub-centimetre sway is invisible at 1024 × 576 and scores as-`nothing_moves`. Animation is DATA: keyframes on `ctx.frame(0.0)` and `ctx.frame(1.5)`, or a-SIMPLE driver of `frame` (`lib.motion.keyframe_path`, `drift`, `sway`, `spin`, `scroll`,-`shape_key_sweep` are these in one call). Amplitudes that read:--| what moves | amplitude | note |-|---|---|---|-| foliage sway | ±0.10–0.20 rad (6–11°) | rotate the crown or the whole tree about its base, not the trunk's middle |-| grass / reeds | ±0.15 rad | phase-offset per patch |-| water | ripples scrolling ≥ 0.15 m/s (the Mapping keyframes above) and a surface bob ≥ 0.04 m | a still mirror reads as static |-| falling leaves / petals / snow / dust | ≥ 0.6 m of travel in 1.5 s | a small instance cloud, each with its own keyframes |-| flags / banners / string lights | ±0.12 rad | the classic "the scene is alive" cue |-| flame / lantern flicker | Emission Strength × 0.75…× 1.3 | keyframe the socket's `default_value` |-| vehicles / boats / birds / a mill | ≥ 1.5 m of travel, or a visible turn | one hero mover beats ten twitchers |--```python-def keyframe_linear(ctx, obj, path, index, v0, v1):- """Two keys on the harness's two times, LINEAR (an eased curve barely moves by t = 1.5). Blender 5.2:- the curves live in the action's channelbag — Action.fcurves is gone."""- setattr(obj, path, _set_index(getattr(obj, path), index, v0))- obj.keyframe_insert(path, index=index, frame=ctx.frame(0.0))- setattr(obj, path, _set_index(getattr(obj, path), index, v1))- obj.keyframe_insert(path, index=index, frame=ctx.frame(1.5))- act = obj.animation_data.action- for fc in act.layers[0].strips[0].channelbag(act.slots[0]).fcurves:- for kp in fc.keyframe_points:- kp.interpolation = "LINEAR"---def _set_index(vec, index, value):- out = list(vec)- out[index] = value- return out--hull_mat = bpy.data.materials.new("HullMat")-hull_mat.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.55, 0.12, 0.10, 1.0)-hm = bpy.data.meshes.new("Boat")-hb = bmesh.new()-bmesh.ops.create_cube(hb, size=1.0)-bmesh.ops.scale(hb, vec=(2.0, 6.0, 1.2), verts=hb.verts)-bmesh.ops.translate(hb, vec=(0.0, 0.0, 0.6), verts=hb.verts)-hb.to_mesh(hm)-hb.free()-hm.materials.append(hull_mat)-boat = bpy.data.objects.new("Boat_0", hm)-boat.location = (14.0, -6.0, -0.35) # its waterline on the water (z = -0.25)-ctx.collection.objects.link(boat)-keyframe_linear(ctx, boat, "location", 1, -6.0, -3.0) # drifts 3 m along +Y in 1.5 s: the hero motion-keyframe_linear(ctx, boat, "rotation_euler", 0, -0.04, 0.04) # and rolls 4.6 degrees-pivot = bpy.data.objects.new("MillPivot", None) # a spinning thing: a SIMPLE driver on frame-pivot.location = (-6.0, 8.0, ctx.height_at(-6.0, 8.0) + 3.0)-pivot["placement"] = "free" # an Empty up in the air is exempt BY DESIGN-ctx.collection.objects.link(pivot)-drv = pivot.driver_add("rotation_euler", 1).driver-drv.type = "SCRIPTED"-drv.expression = "frame * 0.12" # 5.4 rad over the 46 frames; inside the simple subset-print("boat keys", boat.animation_data.action is not None, "driver simple", drv.is_simple_expression)-```--Give the scene **one unmistakable hero motion** (a drifting boat, turning sails, falling-leaves, a flock) plus the ambient ones. A driver that needs Python (`noise.*`, `**`, `%`,-attribute access, `use_self`) evaluates to 0 in this build — the lint and the census both-reject it. Self-check: after `scene_views` compare the two sheets; if you cannot point at-what changed, double the amplitude.--## Soft particles: steam, smoke, dust, motes and sparks (never a hard-edged quad)--The judge's `hard_edged_particles` defect — and the brief's "a soft particle effect … never-hard-edged quads" must-item, which caps the whole score — fired on what 8 of 30 argon Blender-scenes built on 2026-10-15: ico-sphere "puffs" wearing a translucent Principled BSDF, metaballs,-stacked tori, flat discs and polygon "sparks". A SURFACE shader always has a silhouette. In-Cycles a soft thing is a VOLUME: `lib.materials.volume` on a cloud of subdivision-3 spheres renders-with no edge at all (measured on Blender 5.2.2: 40 puffs add 0.7 s to a 32-spp GPU frame).--```python-from lib.materials import emissive, volume-from lib.mesh import Batch-from lib.motion import drift--# 1. steam / smoke / dust: ONE Batch of overlapping volume spheres = one placement row, tagged free-steam = volume("KettleSteam", "ECE9E4", density=0.3, noise_scale=4.0) # dust: density .15-.25; smoke: .5-.8 and a darker colour-rng = ctx.rng(31)-plume = Batch("KettleSteam")-for i in range(22):- r = 0.14 + 0.03 * i + rng.uniform(-0.03, 0.03) # widens as it rises- spread = 0.06 * (1.0 + 0.3 * i)- plume.sphere(steam, (rng.uniform(-spread, spread), rng.uniform(-spread, spread), 0.10 + 0.11 * i), (r, r, 0.8 * r), subdivision=3)-steam_root = plume.finish(ctx.collection)[0] # [0] is the batch's root Empty-steam_root.location = (4.0, -2.0, ctx.height_at(4.0, -2.0) + 0.9) # the spout / vent / chimney top-steam_root["placement"] = "free"-drift(steam_root, (0.0, 0.0, 0.7), ctx) # rises 0.7 m in 1.5 s: motion the frames show--# 2. motes / sparks / embers: tiny EMISSIVE spheres (<= 1.5 cm): at that size subdivision 2 shows no facet-spark = emissive("Spark", "FFB347", 30.0)-cloud = Batch("ForgeSparks")-for i in range(90):- cloud.sphere(spark, (rng.uniform(-0.5, 0.5), rng.uniform(-0.5, 0.5), rng.uniform(0.0, 1.6)), rng.uniform(0.006, 0.014), subdivision=2)-spark_root = cloud.finish(ctx.collection)[0]-spark_root.location = (-3.0, 1.0, ctx.height_at(-3.0, 1.0) + 0.6)-spark_root["placement"] = "free"-drift(spark_root, (0.2, 0.0, 0.9), ctx) # sparks climb; dust motes drift +/-0.3 m sideways instead-print("particles", steam_root.name, spark_root.name)-```--Rules: a particle cloud is ONE object (a `Batch`), tagged `placement = "free"`, and it MOVES-(`drift` / `sway`, >= 0.6 m in 1.5 s so the judge sees it); density 0.15-0.35 for steam and dust,-0.5-0.8 for smoke; no disc, plane, cone, torus, metaball or quad is ever a particle; a volume is-lit like everything else, so under a dim world give it `emission=0.3` or it comes out grey.--## Placement self-check (`lib.place.seat`, `clear_of`)--Placement is MEASURED (`check_placement`; the `scene_placement` gate runs on every build): each-root object in your zone collection is an asset; from its lowest evaluated vertices the harness-looks down for the nearest surface and up for one passing through it. A gap under the foot →-`floating` (ERROR at 0.08 m or past 2 floaters); a foot buried → `sunken` (ERROR at 0.20 m and a-fifth of the height; rocks, posts and bushes may sit partly in; stairs and ramps may follow the-slope; a foot at/under water is fine); bbox touching nothing → `unsupported`; two boxes sharing-more than 10% of the smaller → `interpenetration` (ERROR at 35%). `lib.place.seat(obj,-ctx.height_at)` samples the same foot columns the gate does; `lib.place.clear_of(objs)` is the-pair check.--**Scatter clear of what you placed.** 9 of the 13 argon Blender zones that shipped an-interpenetration ERROR in iteration 0 (2026-10-15) had scattered small props INTO a cart, a rack,-a shrub or a salt mound (100 % of the smaller box). Place the big things first, then mask their-footprints out of every scatter, then run `clear_of` on roots AND scattered Empties and delete-what it still names:--```python-from lib.materials import material-from lib.mesh import Batch-from lib.place import bbox_world, clear_mask, clear_of-from lib.scatter import poisson, scatter--cart = Batch("HandCart") # the big thing: placed by hand FIRST-cart.box(material("CartMat", "6B4A2B"), (0.0, 0.0, 0.5), (1.6, 2.4, 1.0))-cart_root = cart.finish(ctx.collection)[0]-cart_root.location = (2.0, 2.0, ctx.height_at(2.0, 2.0))-placed_roots = [cart_root] # every hand-placed root of this zone-rng = ctx.rng(11)-mask = clear_mask(placed_roots, margin=0.3)-pts = poisson(rng, area=(-1.0, -1.0, 5.0, 5.0), min_dist=0.9, max_count=40, mask=mask)-bollards = scatter(ctx.collection, ctx.assets["bollard"], "YardBollard", pts, height_at=ctx.height_at, rng=rng)-for a, b, frac in clear_of([*placed_roots, *bollards], overlap=0.10): # (name, name, fraction) rows- smaller = min((bpy.data.objects[a], bpy.data.objects[b]), key=lambda o: (lambda lo, hi: (hi - lo).length)(*bbox_world(o)))- bpy.data.objects.remove(smaller) # a prop you cannot move 0.3 m clear is a prop you do not need-print("scattered", len(bollards), "clear of", cart_root.name)-```--Raw, for a thing you built yourself:--```python-def foot_and_box(obj):- """World-space (lowest z, bbox min, bbox max) of the EVALUATED object (modifiers and parents included)."""- bpy.context.view_layer.update()- ev = obj.evaluated_get(bpy.context.evaluated_depsgraph_get())- corners = [ev.matrix_world @ Vector(c) for c in ev.bound_box]- lo = Vector((min(c.x for c in corners), min(c.y for c in corners), min(c.z for c in corners)))- hi = Vector((max(c.x for c in corners), max(c.y for c in corners), max(c.z for c in corners)))- return lo.z, lo, hi---def seat_on_ground(obj, height_at, sink=0.0):- """Lower / lift the object so its foot meets the ground under its centre (gap <= 0.02 m after)."""- foot, lo, hi = foot_and_box(obj)- cx, cy = (lo.x + hi.x) / 2, (lo.y + hi.y) / 2- obj.location.z += height_at(cx, cy) - sink - foot- return obj.location.z---def overlapping(objs, frac=0.20):- """Pairs whose boxes share more than `frac` of the smaller box's volume (the gate's interpenetration)."""- boxes = [(o, *foot_and_box(o)[1:]) for o in objs]- out = []- for i, (a, alo, ahi) in enumerate(boxes):- for b, blo, bhi in boxes[i + 1:]:- inter = 1.0- for k in range(3):- inter *= max(0.0, min(ahi[k], bhi[k]) - max(alo[k], blo[k]))- small = min((ahi - alo).x * (ahi - alo).y * (ahi - alo).z, (bhi - blo).x * (bhi - blo).y * (bhi - blo).z)- if small > 0 and inter / small > frac:- out.append((a.name, b.name))- return out--crate_mat = bpy.data.materials.new("CrateMat")-crate_mat.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.5, 0.36, 0.2, 1.0)-crates = []-for i in range(3):- cm = bpy.data.meshes.new(f"Crate_{i}")- cb = bmesh.new()- bmesh.ops.create_cube(cb, size=0.8)- cb.to_mesh(cm)- cb.free()- cm.materials.append(crate_mat)- ob = bpy.data.objects.new(f"Crate_{i}", cm)- ob.location = (2.0 + i * 0.95, 3.0, 5.0) # dropped from the air on purpose- ctx.collection.objects.link(ob)- seat_on_ground(ob, ctx.height_at) # ...and seated- crates.append(ob)-print("seated", [round(foot_and_box(c)[0] - ctx.height_at(c.location.x, c.location.y), 3) for c in crates], "overlaps", overlapping(crates))-```--A thing MEANT to hang in the air (a bird, a lantern on its chain, a kite) gets-`obj["placement"] = "free"` — the gate reports the share of tagged things, so it is never the-way around a seating problem. Instance clouds (geometry nodes) are not checked per asset.--## Instancing and scatter (collection instances vs geometry-nodes clouds)--Two ways to repeat, with different gate rows:--* **A collection instance** (`lib.scatter.instance` / `scatter`): an Empty with- `instance_type = 'COLLECTION'` pointing at `ctx.assets['<snake>']` (or a Collection you built- once). ONE placement row per instance — seated, named, measured against the plan's size.- Use it for anything the judge will look at: props, trees near a camera, a bench.-* **A geometry-nodes cloud** (`lib.scatter.gn_scatter`, `lib.vegetation.grass_patch`): points- distributed on a surface, an object instanced on them. Counted as instances by the census,- exempt from per-asset placement, one object. Use it for the hundreds: blades, pebbles,- litter, a far treeline.--```python-source = ctx.assets.get("bollard")-if source is None: # (no such plan asset: a stand-in post)- pm = bpy.data.meshes.new("PostStandIn")- pb = bmesh.new()- bmesh.ops.create_cone(pb, cap_ends=True, segments=8, radius1=0.08, radius2=0.08, depth=0.9)- bmesh.ops.translate(pb, vec=(0.0, 0.0, 0.45), verts=pb.verts)- pb.to_mesh(pm)- pb.free()- source = bpy.data.collections.new("PostStandIn")- ctx.collection.children.link(source)- source.objects.link(bpy.data.objects.new("PostStandIn", pm))-instances = []-for i in range(6): # a row of posts along the quay edge, jittered- x, y = -12.0 + i * 3.0 + rng.uniform(-0.2, 0.2), -9.0 + rng.uniform(-0.15, 0.15)- e = bpy.data.objects.new(f"QuayPost_{i}", None)- e.instance_type = "COLLECTION"- e.instance_collection = source- e.location = (x, y, ctx.height_at(x, y))- e.rotation_euler = (0.0, 0.0, rng.uniform(0.0, math.tau))- ctx.collection.objects.link(e)- instances.append(e)-print("instances", len(instances), "of", source.name)-```--A Collection you build for instancing (not a plan asset) lives inside your zone collection;-its source objects at the origin are seen unless you exclude it — simplest is to instance the-plan's assets (`ctx.assets`) and build one-offs as plain objects.--## Materials: Principled recipes and the lib palette--Every surface is a Principled BSDF with a COLOUR and a roughness; a grey default is graded-`placeholder_material`. Blender 5.2 socket names: `Base Color`, `Roughness`, `Metallic`, `IOR`,-`Alpha`, `Normal`, `Subsurface Weight`, `Specular IOR Level`, `Transmission Weight`, `Coat-Weight`, `Sheen Weight`, `Emission Color`, `Emission Strength` (the old `Specular`,-`Subsurface`, `Transmission`, `Emission` raise KeyError). Colour mixing is `ShaderNodeMix`-with `data_type = 'RGBA'` (inputs 6 and 7, output 2) — `ShaderNodeMixRGB` is gone. The lib-palette (`lib.materials`: `material`, `masonry`, `limestone`, `ashlar`, `woodgrain`,-`chipped_paint`, `worn_alloy`, `mineral_surface`, `water`, `glass`, `foliage`, `snow`, `ice`,-`emissive`, `tint`) builds these; the raw recipes:--```python-def material(name, color, roughness=0.5, metal=0.0, noise_scale=0.0, bump=0.08, emission=0.0):- """One Principled material; noise_scale > 0 adds a procedural bump so flat surfaces still catch light."""- mat = bpy.data.materials.new(name)- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Roughness"].default_value = roughness- bsdf.inputs["Metallic"].default_value = metal- if emission:- bsdf.inputs["Emission Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Emission Strength"].default_value = emission- if noise_scale:- tex = nodes.new("ShaderNodeTexNoise")- tex.inputs["Scale"].default_value = noise_scale- tex.inputs["Detail"].default_value = 8.0- b = nodes.new("ShaderNodeBump")- b.inputs["Strength"].default_value = bump- links.new(tex.outputs["Factor"], b.inputs["Height"])- links.new(b.outputs["Normal"], bsdf.inputs["Normal"])- return mat---def woodgrain(mat, dark=(0.16, 0.10, 0.06), light=(0.50, 0.35, 0.22), scale=3.0):- """Wave texture → Mix (RGBA) between two tones → Base Color; along the object's Y."""- nodes, links = mat.node_tree.nodes, mat.node_tree.links- bsdf = nodes["Principled BSDF"]- coords = nodes.new("ShaderNodeTexCoord")- wave = nodes.new("ShaderNodeTexWave")- wave.wave_type = "BANDS"- wave.bands_direction = "Y"- wave.inputs["Scale"].default_value = scale- wave.inputs["Distortion"].default_value = 4.0- wave.inputs["Detail"].default_value = 3.0- mix = nodes.new("ShaderNodeMix")- mix.data_type = "RGBA"- mix.inputs[6].default_value = (dark[0], dark[1], dark[2], 1.0)- mix.inputs[7].default_value = (light[0], light[1], light[2], 1.0)- links.new(coords.outputs["Object"], wave.inputs["Vector"])- links.new(wave.outputs["Factor"], mix.inputs["Factor"])- links.new(mix.outputs[2], bsdf.inputs["Base Color"])- bsdf.inputs["Roughness"].default_value = 0.65- return mat---def glass(name, color=(0.9, 0.95, 1.0), roughness=0.05, ior=1.5):- mat = material(name, color, roughness=roughness)- bsdf = mat.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Transmission Weight"].default_value = 1.0- bsdf.inputs["IOR"].default_value = ior- return mat--stone = material("Granite", (0.43, 0.42, 0.39), roughness=0.9, noise_scale=12.0, bump=0.15)-oak = woodgrain(material("Oak", (0.5, 0.35, 0.22)))-pane = glass("Pane")-brass = material("Brass", (0.80, 0.62, 0.30), roughness=0.35, metal=1.0)-lamp_glow = material("Glow", (1.0, 0.72, 0.45), emission=6.0)-sm = bpy.data.meshes.new("MaterialSampler")-sb = bmesh.new()-bmesh.ops.create_cube(sb, size=0.5)-bmesh.ops.translate(sb, vec=(0.0, 0.0, 0.25), verts=sb.verts)-sb.to_mesh(sm)-sb.free()-for m in (stone, oak, pane, brass, lamp_glow):- sm.materials.append(m)-sampler = bpy.data.objects.new("MaterialSampler", sm)-sampler.location = (-4.0, -4.0, ctx.height_at(-4.0, -4.0))-ctx.collection.objects.link(sampler)-print("materials", [m.name for m in sm.materials])-```--Albedos belong in 0.02–0.8 linear (pure black and pure white are always wrong); wood and-stone roughness 0.6–0.95, metals `Metallic` 1 with roughness 0.2–0.5, glass transmission 1;-an emissive at strength 5–10 blooms, 50 whites the frame out.--## Assets (`src/assets/<snake>.py`): `build_<snake>` returning a Collection at the origin, base z = 0--An asset module builds EVERY part into `ctx.collection` (its own, pre-made) at the origin,-base on z = 0, front facing −Y, and returns `ctx.collection`; the harness builds it once,-hides the source and the zones place collection instances of it. Several parts with distinct-materials, unique names, under the triangle budget (15000 per asset); `variant` (0..n) changes-the SILHOUETTE, not just the scale. A hero (`blender_glb`) is built by the object track instead-and imported for you. The shape, inline (in a real asset file `build_lantern` is the module's-top-level function):--```python-def _mat(name, color, roughness=0.5, metal=0.0, emission=0.0):- mat = bpy.data.materials.new(name)- bsdf = mat.node_tree.nodes["Principled BSDF"]- bsdf.inputs["Base Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Roughness"].default_value = roughness- bsdf.inputs["Metallic"].default_value = metal- if emission:- bsdf.inputs["Emission Color"].default_value = (color[0], color[1], color[2], 1.0)- bsdf.inputs["Emission Strength"].default_value = emission- return mat---def build_lantern(ctx, variant=0):- iron = _mat("LanternIron", (0.12, 0.12, 0.13), roughness=0.5, metal=0.8)- glow = _mat("LanternGlow", (1.0, 0.78, 0.45), emission=6.0)- post_h = 2.2 if variant == 0 else 1.6- bm = bmesh.new()- bmesh.ops.create_cone(bm, cap_ends=True, segments=10, radius1=0.04, radius2=0.03, depth=post_h)- bmesh.ops.translate(bm, vec=(0.0, 0.0, post_h / 2), verts=bm.verts)- cage = bmesh.ops.create_cone(bm, cap_ends=True, segments=6, radius1=0.14, radius2=0.12, depth=0.26)- bmesh.ops.translate(bm, vec=(0.0, 0.0, post_h + 0.13 - 0.004), verts=cage["verts"]) # overlaps the post by 4 mm- me = bpy.data.meshes.new("LanternBody")- bm.to_mesh(me)- bm.free()- me.materials.append(iron)- body = bpy.data.objects.new("LanternBody", me)- ctx.collection.objects.link(body)- gm = bpy.data.meshes.new("LanternGlass")- bm = bmesh.new()- bmesh.ops.create_icosphere(bm, subdivisions=2, radius=0.08)- bm.to_mesh(gm)- bm.free()- gm.materials.append(glow)- bulb = bpy.data.objects.new("LanternGlass", gm)- bulb.parent = body- bulb.location = (0.0, 0.0, post_h + 0.13)- ctx.collection.objects.link(bulb)- return ctx.collection--built = build_lantern(ctx, variant=1)-print("asset parts", [o.name for o in built.objects if o.name.startswith("Lantern")])-```--Why: a scene mixes cheap instanced props with a few hero assets; the harness hands every-asset to the zones the same way (`ctx.assets['<snake>']`), so a zone places a procedural-module and an imported GLB with the same four lines.--## Interiors: the room shell is the env's--A brief set INSIDE a built space (`interior: true` in the plan) gets its floor, walls and-ceiling from `src/env.py` — `lib.architecture.room_shell(collection, mat, center=…,-extents=…, thickness=0.2, openings=(…))` on the bounds' faces, named `RoomShell…` /-`Ceiling…` so the overview rig can lift the lid — with the windows and doors cut as openings-and the inside LIT (an Area light per window, practicals; a closed room under a sun reads-black). Zones dress the inside and never build walls; a fixture on a wall sits flush against-the inner face of the bounds. Measured 2026-09-07 over six interior runs: with no owner for-walls and roof, every one was judged "not enclosed, a diorama on a flat plane" (0.0–0.3).--## Traps (Blender 5.2 LTS API facts; each is a build error or a silent zero)--1. **`use_nodes` is deprecated** — materials, worlds and lights always have a node tree; a- new material already carries `Principled BSDF` and `Material Output`.-2. **`sky_type = 'NISHITA'` raises** — it is `'MULTIPLE_SCATTERING'`.-3. **Principled sockets renamed** — `Specular IOR Level`, `Subsurface Weight`, `Transmission- Weight`, `Emission Color` + `Emission Strength`, `Coat Weight`, `Sheen Weight`.-4. **`ShaderNodeMixRGB` is gone** — `ShaderNodeMix` with `data_type = 'RGBA'`: inputs 6 / 7,- output 2.-5. **Boolean solvers are `FLOAT` / `EXACT` / `MANIFOLD`** — `'FAST'` raises.-6. **Geometry-nodes inputs are RNA properties** — `getattr(mod.properties.inputs,- "Socket_2").value = v`; `mod["Socket_2"] = v` raises TypeError.-7. **`Action.fcurves` is gone** — `action.layers[0].strips[0].channelbag(action.slots[0]).- fcurves` for the interpolation.-8. **`Mesh.calc_normals()` and `use_auto_smooth` are gone** — `for f in bm.faces: f.smooth =- True` or `me.shade_smooth()`.-9. **No `bpy.ops` in loops** — every operator rebuilds the scene state; build with `bmesh` and- `bpy.data`, place collection instances, scatter with geometry nodes.-10. **`bpy.context.object` / `selected_objects` after `bpy.data.objects.new`** — nothing is- selected in background mode; keep your own references.-11. **A driver that needs Python evaluates to 0** — only `frame`, `sin / cos / min / max /- clamp / lerp`, `+ - * /` and comparisons; no `noise`, `**`, `%`, attribute access,- `use_self`.-12. **A Python world outside `env.py`**, a camera, `frame_set`, `scene.render.*` — lint ERRORS- that fail the build gate; the harness owns them.-13. **Names are global** — `Lantern_0` twice becomes `Lantern_0.001`; number every placed- copy per zone family and never reuse another zone's base name.-14. **`bm.verts[i]` before `ensure_lookup_table()`** — IndexError; call it after any topology- change, or iterate instead of indexing.-15. **Triangle budgets** — 15000 per asset instance, 40000 for a hero, 3,000,000 unique- triangles for the whole scene (a gate ERROR past it); instance clouds count their- instances, so a 200-blade cloud over 400 points is 240,000 rendered triangles but 600- unique ones.-16. **`matrix_world` of a fresh `bpy.data` object is identity** until the view layer updates —- parent with a RELATIVE `location` (the practical recipe), or call- `bpy.context.view_layer.update()` before reading it.--## Self-check (before you call it done)--Composition self-check on every authored frame (the judge grades exactly these):--* three depth layers — something inside 5 m, the subject at 8–30 m, a backdrop and sky above;-* no hard world edge anywhere against the sky; the fog the horizon's colour;-* the ground shows ≥ 3 blended colours and at least one path / worn area;-* vegetation shows ≥ 3 silhouettes and visible hue / scale variation, in clusters not a ring;-* ≥ 12 mid props and ≥ 25 small props per dressed zone, placed against things, every one seated;-* shade is coloured (the sky's), not black; the key and the world differ in hue;-* t = 0 and t = 1.5 are visibly different.--Then: `build` → `check_placement` (floating / sunken / unsupported / interpenetration + the-fix per asset, in metres) → `scene_probe` (unique triangles, drivers, the world, console) →-`scene_views` (authored cameras + the overview rig, with `camera_checks`) → fix the worst →-repeat. Look at every camera's frame AND its numbers: no black frames, no white-out, the-subject (not sky / ground) fills the establishing shot, `camera_in_geometry` false, and-`check_placement` clean.diff --git a/harness/codeverse3d/prompts/scene_blender/effects_catalog.md b/harness/codeverse3d/prompts/scene_blender/effects_catalog.mdindex 0cb2cdf2..6ff4ac27 100644--- a/harness/codeverse3d/prompts/scene_blender/effects_catalog.md+++ b/harness/codeverse3d/prompts/scene_blender/effects_catalog.md@@ -1,4 +1,4 @@-# The shipped bpy library — call these before writing your own+# The shipped bpy library — an optional toolbox`src/lib/` is in your workspace already: thirteen modules of Blender 5.2 LTS bpythat build, seat, light and animate what a scene needs. They are not an@@ -6,9 +6,10 @@ outside package — they are harness code shipped into the workspace, soimporting them is allowed where "never import a helper SDK" still forbidseverything else (and a write to `src/lib/` is reverted).-Reach for one FIRST. Write your own only for something no entry here covers,-and then build it with `Batch` from `lib/mesh.py` — plain vertex and face lists,-never `bpy.ops` primitives in a loop.+These calls are available and already pass the gates (seating, naming, the 5.2+API). Use them, extend them or write your own raw bpy / bmesh — only the gates+and the brief decide. `Batch` from `lib/mesh.py` (plain vertex and face lists)+is one way to build a many-part prop as one object; `bpy.data` + `bmesh` is another.Import with the package path from any file — `src/env.py`, `src/zones/x.py`and `src/assets/x.py` all say `from lib.materials import material` or@@ -17,60 +18,60 @@ other the same way).| Want | Call || --- | --- |-| noise on the CPU, a seeded generator, a cheap per-item jitter | `rng(seed)` (THE random: never the module-level `random`) · `hash01(i, seed=0)` 0..1 from an index · `fbm2(x, y, *, octaves=4, lacunarity=2.0, gain=0.5, seed=0)` / `fbm3(x, y, z, *, …)` gradient noise about -1..1 with 1 unit = one feature (call with `x / scale_m`) · `ridged(x, y, *, seed=0, octaves=5)` 0..1 crests · `mountain_height(x, y, *, seed=0, amplitude=45.0, frequency=0.013)` a horizon ridge in metres · `height_field(size, segments, fn)` a row-major grid of samples — `lib/noise.py`; pure python: a 96 x 96 field with four octaves is ~60 ms, so keep heavy fields to the env |+| noise on the CPU, a seeded generator, a cheap per-item jitter | `rng(seed)` (THE random: never the module-level `random`) · `hash01(i, seed=0)` 0..1 from an index · `fbm2(x, y, *, octaves=4, lacunarity=2.0, gain=0.5, seed=0)` / `fbm3(x, y, z, *, …)` gradient noise about -1..1 with 1 unit = one feature (call with `x / scale_m`) · `ridged(x, y, *, seed=0, octaves=5)` 0..1 crests · `mountain_height(x, y, *, seed=0, amplitude=45.0, frequency=0.013)` a ridge line in metres · `height_field(size, segments, fn)` a row-major grid of samples — `lib/noise.py`; pure python: a 96 x 96 field with four octaves is ~60 ms, so keep heavy fields to the env || a prop built from parts as ONE object (one placement row, one mesh per material) | `Batch(name)` then `.box(mat, loc, size, rotation=0.0)` (loc = centre, 12 triangles) · `.sphere(mat, loc, scale, subdivision=1)` (level 1 = 20 triangles, 2 = 80, 3 = 320, 4 = 1 280) · `.lathe(mat, xy, profile, sides=32, phase=0.0)` (profile = [(radius, z), …], capped) · `.cone(mat, loc, radius, height, top=0.0, sides=24)` (loc = base centre) · `.beam(mat, a, b, radius, end=None, sides=8)` (a capped tube; `end` tapers) · `.torus(mat, loc, radius, tube, major=64, minor=8)` · `.ring(mat, center, normal, radius, tube, segments=96)` (a hoop about `normal`) · `.add(mat, vertices, faces, smooth=False)` raw lists · `.transformed(matrix)` a view whose additions are transformed (a figure turned to its heading) · `.finish(collection, *, bevel=0.0, parent=True, name_prefix="")` → `[root, mesh, …]`: ONE root Empty named after the batch (the placement row; `root["placement"] = "free"` for a hanging thing), origin at the base centre; `parent=False` for an asset's own collection · `mesh_object(name, vertices, faces, mat, collection, *, smooth=False)` · `curve_object(name, points, radius, mat, collection, *, cyclic=False)` a rope / cable / vine · `sphere_template(level)` an icosphere's lists · `parent_under(objects, collection, name)` several objects as one row — `lib/mesh.py`; metres, Z up, -Y front |-| a textured Principled material without a texture file | `material(name, color, roughness=.5, metal=0.0, *, noise_scale=0.0, bump=.08, emission=0.0)` (hex `"8A6A3F"` or a linear tuple; `noise_scale` features / m adds breakup + bump) · `masonry(name, color, mortar="625D66", scale=2.0)` rows / m · `limestone(name, color, scale=1.2)` · `ashlar(name, color)` 1.2 x 0.4 m blocks · `woodgrain(mat, dark="29190F", light="805939", direction=(3,.1,5))` on an existing material · `chipped_paint(mat, paint, substrate, scale=6)` · `worn_alloy(name, color, *, seed=0, metal=.55)` · `mineral_surface(name, color, *, stone=False)` rock / soil, cracks when `stone` · `water(name, color="163F4A", roughness=.12, scale=.8, *, flow=(0.6,0.2), ctx=None)` ONE refracting surface (give it a bed; ripples drift with `ctx`) · `clear_water(name)` a basin · `glass(name, color="FFFFFF", roughness=.05, ior=1.5)` · `foliage(name, color, variants=3)` → a LIST of leaf materials (give neighbours different ones) · `snow(name="Snow")` · `ice(name="Ice")` · `emissive(name, color, strength)` a light-giving skin (3-8 reads as a lamp) · `tint(mat, variant)` a shifted copy (-1..1) · `volume(name, color, density=.4, *, anisotropy=.3, noise_scale=0.0, emission=0.0)` a Principled VOLUME with no surface — the ONLY soft steam / smoke / dust / spark haze in Cycles, on a `Batch` of subdivision-3 spheres (see "Soft particles" in the cookbook) — `lib/materials.py`; patterns read OBJECT coordinates so they keep their metre scale; albedos belong in 0.02-0.8 linear |-| the ground, hills, rock | `make_height_at(*, seed=0, relief=3.0, scale=60.0, flat_radius=45.0, base=0.0)` → THE `height_at` function of (x, y) (level inside `flat_radius`, hills of `relief` m beyond; env.py returns it) · `ground(name, collection, *, size, segments, height_at, material, center=(0,0), smooth=True)` the terrain mesh (name it `Ground…`; 96 segments = 18 k triangles) · `cliff(name, collection, *, length, height, height_at, material, seed=0)` a rock face along +X (~2.4 k) · `boulder(batch, mat, center, scale, *, seed=0, detail=3)` standing on `center` z (80 / 320 / 1 280 triangles at detail 2 / 3 / 4) · `rock_field(batch, mat, center, radius, count, height_at, rng)` 80 apiece · `talus(batch, mat, center, scale, seed)` a scree heap (~800) · `basalt_column(batch, materials, center, radius, height, rng, lean=(0,0))` a hexagonal cluster (~300) · `shoreline_mask(x, y, water_level, height_at)` 0 in the water, 1 half a metre up — `lib/terrain.py`; every recipe's `center` is the GROUND point: pass `height_at` (x, y) |+| a textured Principled material without a texture file | `material(name, color, roughness=.5, metal=0.0, *, noise_scale=0.0, bump=.08, emission=0.0)` (hex `"8A6A3F"` or a linear tuple; `noise_scale` features / m adds breakup + bump) · `masonry(name, color, mortar="625D66", scale=2.0)` rows / m · `limestone(name, color, scale=1.2)` · `ashlar(name, color)` 1.2 x 0.4 m blocks · `woodgrain(mat, dark="29190F", light="805939", direction=(3,.1,5))` on an existing material · `chipped_paint(mat, paint, substrate, scale=6)` · `worn_alloy(name, color, *, seed=0, metal=.55)` · `mineral_surface(name, color, *, stone=False)` rock / soil, cracks when `stone` · `water(name, color="163F4A", roughness=.12, scale=.8, *, flow=(0.6,0.2), ctx=None)` ONE refracting surface (give it a bed; ripples drift with `ctx`) · `clear_water(name)` a basin · `glass(name, color="FFFFFF", roughness=.05, ior=1.5)` · `foliage(name, color, variants=3)` → a LIST of leaf materials (give neighbours different ones) · `snow(name="Snow")` · `ice(name="Ice")` · `emissive(name, color, strength)` a light-giving skin (3-8 reads as a lamp) · `tint(mat, variant)` a shifted copy (-1..1) · `volume(name, color, density=.4, *, anisotropy=.3, noise_scale=0.0, emission=0.0)` a Principled VOLUME with no surface — the only edgeless steam / smoke / dust / spark haze Cycles can draw (the contract's renderer facts); a cloud of `Batch` spheres wearing it is one root — `lib/materials.py`; patterns read OBJECT coordinates so they keep their metre scale; albedos outside 0.02-0.8 linear push the frame toward dark_frame / blown |+| the ground, hills, rock | `make_height_at(*, seed=0, relief=3.0, scale=60.0, flat_radius=0.0, base=0.0)` → one landform among many: rolling fbm hills of up to `relief` m, features `scale` m wide, a level pad only if you pass `flat_radius`; return it from env.py, compose it into your own terrain, or write any function of (x, y) — only the signature is the contract · `ground(name, collection, *, size, segments, height_at, material, center=(0,0), smooth=True)` the terrain mesh (name it `Ground…`; 96 segments = 18 k triangles) · `cliff(name, collection, *, length, height, height_at, material, seed=0)` a rock face along +X (~2.4 k) · `boulder(batch, mat, center, scale, *, seed=0, detail=3)` standing on `center` z (80 / 320 / 1 280 triangles at detail 2 / 3 / 4) · `rock_field(batch, mat, center, radius, count, height_at, rng)` 80 apiece · `talus(batch, mat, center, scale, seed)` a scree heap (~800) · `basalt_column(batch, materials, center, radius, height, rng, lean=(0,0))` a hexagonal cluster (~300) · `shoreline_mask(x, y, water_level, height_at)` 0 in the water, 1 half a metre up — `lib/terrain.py`; every recipe's `center` is the GROUND point: pass `height_at` (x, y) || the sky, fog, night dressing (world setters are ENV ONLY) | `sun_world(scene, *, elevation_deg=12.0, azimuth_deg=125.0, strength=.2, dust=2.0)` the physical MULTIPLE_SCATTERING sky, compass 0 = +X / 90 = +Y like the Sun lamp, disc off (the lamp is the sun) · `night_world(scene, color="17273F", strength=.3)` · `gradient_world(scene, stops, *, clouds=True, strength=.7)` stops = `[(0, "F2C9A0"), (1, "1F4A8E")]` horizon → zenith · `haze(collection, loc, size, density=.003, color="ADC9E1", name="Atmosphere")` a bounded fog box (volume-only: the census reports it as fog, never as matter; 0.002 clear, 0.01 mist, 0.03 fog) · `aurora(name, collection, center, *, span=560, height=72, seed=0, strength=.24, ctx=None)` a curtain at `center` (x, y, altitude), tagged free — NAME it with a sky word (`"AuroraSky"`) so the census files it as sky · `stars(batch, mat, *, seed=0, count=900, radius=600)` into a batch named `Stars…` with an `emissive` mat; tag its root free — `lib/sky.py`; no clouds volume, no moon disc |-| lamps | `sun(collection, *, azimuth_deg, elevation_deg, color="FFCF9C", energy=3.0, angle_deg=2.0, name="Sun")` → `(lamp, towards_sun)`, W/m² (3-5 day, 0.3-1 dusk) · `area_light(collection, name, loc, color, energy, *, size=5.0, target=None, shape="DISK")` Watts · `point_light(collection, name, loc, color, energy, *, radius=.05)` · `spot(collection, name, loc, color, energy, *, size_deg=45.0, blend=.3, target=None)` · `practical(collection, name, loc, color="FFB270", energy=300, *, size=.42, target=None)` the light a visible fixture throws (pair it with an `emissive` skin) · `aim(obj, target)` — `lib/lighting.py`; exposure and the view transform are the harness's: light the scene, never the camera |+| lamps | `sun(collection, *, azimuth_deg, elevation_deg, color="FFCF9C", energy=3.0, angle_deg=2.0, name="Sun")` → `(lamp, towards_sun)`, W/m² (3-5 day, 0.3-1 dusk have passed the frame gate) · `area_light(collection, name, loc, color, energy, *, size=5.0, target=None, shape="DISK")` Watts · `point_light(collection, name, loc, color, energy, *, radius=.05)` · `spot(collection, name, loc, color, energy, *, size_deg=45.0, blend=.3, target=None)` · `practical(collection, name, loc, color="FFB270", energy=300, *, size=.42, target=None)` the light a visible fixture throws (pair it with an `emissive` skin) · `aim(obj, target)` — `lib/lighting.py`; exposure and the view transform are the harness's: light the scene, never the camera || water: a lake, a fall, jets, spray | `water_surface(name, collection, *, size, level, material=None, ripple=0.045, seed=0, height_fn=None)` ONE plane at z = `level` centred on the origin — move the object; `height_fn` drops cells where the ground stands above the water (name it `…Water` / `…Lake`: a foot in it is "on water", never floating; ~4.6 k) · `pool_height(x, y, *, level=-.25)` a `height_at` for things that float · `waterfall(name, collection, center, *, width, height, seed=0, ctx=None, layers=4)` foam sheets dropping onto `center` (the impact level), flow toward -Y, ~400 per layer · `hanging_fall(name, collection, outlet, along, across, *, width, height, seed=0, ctx=None)` one sheet from a spout · `fountain_jets(batch, collection, water_mat, *, center, nozzle_r, landing_r, count=14, rise=1.85, ctx=None, seed=0)` parabolic tubes + spray (~220 per jet) · `droplets(batch, mat, center, width, bottom, rng, count=260)` 4 triangles each · `foam_shader(name)` — `lib/water.py`; no fluid solver, no caustics: a fall is sheets whose texture streams with `ctx` || trees, shrubs, ferns, grass, flowers | `tree(batch, loc, height, bark, foliage, *, seed=0, kind="broadleaf", max_leaves=4000)` kinds broadleaf / oak / cypress / pine — a crown of leaf CARDS (3-9 k triangles; `max_leaves` caps it; pine ≈ 350) · `shrub(batch, bark, foliage, center, *, scale=1.0, seed=0)` (~300) · `leaf_spray(batch, foliage, center, rng, *, radius=.32, count=35)` a vine knot · `fern(batch, mat, center, *, scale=1.0, seed=0)` · `tropical(batch, leaves, stem, center, *, scale=1.0, seed=0)` · `grass_clump(batch, mats, x, y, z, rng)` 12 blades · `perennial_bed(batch, center, radius, height_at, foliage, petals, rng)` (~1.1 k) · `grass_patch(name, collection, surface, *, blade=None, density=5.0, seed=0, height=.3, color="4A6B2A")` a geometry-nodes instance CLOUD on `surface` (a hidden `terrain.ground` patch: `hide_render = True`) — exempt from per-asset placement, 3 quads per blade · `tree_stand(collection, batch, positions, height_at, rng, bark=…, foliage=…, height=7.0, kind=…)` a copse as ONE object — `lib/vegetation.py`; every `loc` / `center` is the ground point |-| buildings, roofs, bridges, paving, a room, lettering | `timber_house(batch, roofs, x, y, width, depth, floors, mats, rng, index)` half-timbered, `mats` = {wall, timber, door, window}, `roofs` = {tile, trim}; returns the ridge height (≤ 14 k) · `tiled_roof(batch, tile, trim, center, width, depth, rise, rng)` ridge along X on `center` (x, y, eave z) · `clay_roof(batch, frame, tiles, timber, center, width, depth, rise, rng)` pantiles · `fret_window(batch, wood, paper, x, y, z, width, height, direction, *, pattern=0)` facing compass `direction` · `arched_opening(batch, mat, center, width, height, *, depth=.28, thickness=.2)` · `stone_bridge(batch, stone, dark, *, center, span=27.6, width=4.7, rise=3.9, height_at=None)` hump-backed along X (~700) · `arched_footbridge(batch, wood, stone, *, start, end, rise=1.5, height_at=None)` (~1 k; give it `height_at` on a bank) · `tower(batch, mat, center, radius, low, high, windows, *, count=8)` · `paving(batch, mats, *, center, inner_r, rings, seed)` fan-set rings, 2 cm thick (~350 per ring) · `paving_grid(batch, mats, center, size, stone, joint, rng)` flagstones · `room_shell(collection, mat, *, center, extents, thickness=.2, openings=(), glazed=False)` an interior's floor, walls and `Ceiling` under a `RoomShell` root (env.py; openings = `(wall, offset, width, sill, head)`; `glazed=True` is a glass house — a conservatory, a greenhouse, a glass atrium: every wall panel and the lid become `materials.glass` panes that cast no shadow on an iron-frame grid of `mat` bars, so the sun comes through and the frame's grid shadows the floor, which stays an opaque slab of `mat`; the names stay, a pane being its panel's name + `Glass`) · `lantern(batch, silk, wood, center, *, radius=.35, length=None)` (~550; an `emissive` silk) · `text_mesh(name, collection, body, loc, size, mat, *, rotation=(pi/2,0,0), align="CENTER", extrude=.005)` readable lettering (~300 per letter) — `lib/architecture.py`; `center` / (x, y) sit on the ground z you pass |-| placing copies: instances and clouds | `instance(collection, source, name, x, y, *, height_at, rot_z=0.0, scale=1.0, sink=0.0)` ONE seated collection-instance Empty of `ctx.assets["<snake>"]` (the placement row) · `scatter(collection, source, prefix, points, *, height_at, rng, rot="random", scale=(1,1))` one per point, named `<prefix>_<i>` · `poisson(rng, *, area, min_dist, max_count, mask=None)` points in (x0, y0, x1, y1) at least `min_dist` apart; `mask` of (x, y) → 0..1 keeps a shoreline clear · `along_path(points, n, *, jitter=0.0, rng=None)` · `grid(center, size, spacing, rng, *, jitter=.3)` · `gn_scatter(name, collection, surface, instance_obj, *, density, seed=0, align_normal=True, scale_range=(.8,1.2))` an instance cloud (pebbles, tufts, hundreds+) — one object, exempt from per-asset placement — `lib/scatter.py`; a cloud cannot be measured per copy: anything the plan COUNTS (a bench, a cart, a tree) is an `instance` |-| seating, facing, the zone's own placement check | `seat(obj, height_at, *, sink=0.0, columns=5)` drop a ROOT until its lowest foot column rests on the ground (the gate's own columns: lowest + ±x / ±y of the foot band) · `seat_instance(empty, source, height_at, *, sink=0.0)` · `rest_on(obj, support, *, offset=0.0)` a lantern on a table · `bbox_world(obj, *, evaluated=True)` (min, max) incl. children and instances · `face_toward(obj, target)` / `heading(a, b)` for -Y-front things · `clear_of(objs, min_gap=.02, *, overlap=0.10)` → `[(a, b, fraction)]` AABB overlaps the gate would call interpenetration: run it on your roots before returning · `clear_mask(objs, margin=.3)` → an (x, y) mask for the scatter module's poisson `mask` argument that keeps scatter points out of the placed roots' footprints (+ `margin` m): build it BEFORE you scatter the small stuff · `keep_inside(obj, bbox)` the plan's box · `unique_name(base, i)` `Base_i`, bumped past an existing name (names are global in Blender) · `world_matrix(obj)` the matrix NOW (`obj.matrix_world` is stale until the depsgraph runs) — `lib/place.py`; contact is 2 cm, floating starts at 5 cm outdoors / 2 cm indoors, sunk at 10 cm |+| buildings, roofs, bridges, paving, a room, lettering | `timber_house(batch, roofs, x, y, width, depth, floors, mats, rng, index)` half-timbered, `mats` = {wall, timber, door, window}, `roofs` = {tile, trim}; returns the ridge height (≤ 14 k) · `tiled_roof(batch, tile, trim, center, width, depth, rise, rng)` ridge along X on `center` (x, y, eave z) · `clay_roof(batch, frame, tiles, timber, center, width, depth, rise, rng)` pantiles · `fret_window(batch, wood, paper, x, y, z, width, height, direction, *, pattern=0)` facing compass `direction` · `arched_opening(batch, mat, center, width, height, *, depth=.28, thickness=.2)` · `stone_bridge(batch, stone, dark, *, center, span=27.6, width=4.7, rise=3.9, height_at=None)` hump-backed along X (~700) · `arched_footbridge(batch, wood, stone, *, start, end, rise=1.5, height_at=None)` (~1 k; give it `height_at` on a bank) · `tower(batch, mat, center, radius, low, high, windows, *, count=8)` · `paving(batch, mats, *, center, inner_r, rings, seed)` fan-set rings, 2 cm thick (~350 per ring) · `paving_grid(batch, mats, center, size, stone, joint, rng)` flagstones · `room_shell(collection, mat, *, center, extents, thickness=.2, openings=(), glazed=False)` a box interior's floor, walls and `Ceiling` under a `RoomShell` root (env.py; openings = `(wall, offset, width, sill, head)`; `glazed=True` is a glass house — a conservatory, a greenhouse, a glass atrium: every wall panel and the lid become `materials.glass` panes that cast no shadow on an iron-frame grid of `mat` bars, so the sun comes through and the frame's grid shadows the floor, which stays an opaque slab of `mat`; the names stay, a pane being its panel's name + `Glass`) · `lantern(batch, silk, wood, center, *, radius=.35, length=None)` (~550; an `emissive` silk) · `text_mesh(name, collection, body, loc, size, mat, *, rotation=(pi/2,0,0), align="CENTER", extrude=.005)` readable lettering (~300 per letter) — `lib/architecture.py`; `center` / (x, y) sit on the ground z you pass |+| placing copies: instances and clouds | `instance(collection, source, name, x, y, *, height_at, rot_z=0.0, scale=1.0, sink=0.0)` ONE seated collection-instance Empty of `ctx.assets["<snake>"]` (the placement row) · `scatter(collection, source, prefix, points, *, height_at, rng, rot="random", scale=(1,1))` one per point, named `<prefix>_<i>` · `poisson(rng, *, area, min_dist, max_count, mask=None)` points in (x0, y0, x1, y1) at least `min_dist` apart; `mask` of (x, y) → 0..1 keeps a region clear · `along_path(points, n, *, jitter=0.0, rng=None)` · `grid(center, size, spacing, rng, *, jitter=.3)` · `gn_scatter(name, collection, surface, instance_obj, *, density, seed=0, align_normal=True, scale_range=(.8,1.2))` an instance cloud (pebbles, tufts, hundreds+) — one object, exempt from per-asset placement — `lib/scatter.py`; a cloud cannot be measured per copy: anything the plan COUNTS (a bench, a cart, a tree) is an `instance` |+| seating, facing, the zone's own placement check | `seat(obj, height_at, *, sink=0.0, columns=5)` drop a ROOT until its lowest foot column rests on the ground (the gate's own columns: lowest + ±x / ±y of the foot band) · `seat_instance(empty, source, height_at, *, sink=0.0)` · `rest_on(obj, support, *, offset=0.0)` a lantern on a table · `bbox_world(obj, *, evaluated=True)` (min, max) incl. children and instances · `face_toward(obj, target)` / `heading(a, b)` for -Y-front things · `clear_of(objs, min_gap=.02, *, overlap=0.10)` → `[(a, b, fraction)]` AABB overlaps the gate would call interpenetration: run it on your roots before returning · `clear_mask(objs, margin=.3)` → an (x, y) mask for the scatter module's poisson `mask` argument that keeps scatter points out of the placed roots' footprints (+ `margin` m) · `keep_inside(obj, bbox)` the plan's box · `unique_name(base, i)` `Base_i`, bumped past an existing name (names are global in Blender) · `world_matrix(obj)` the matrix NOW (`obj.matrix_world` is stale until the depsgraph runs) — `lib/place.py`; contact is 2 cm, floating starts at 5 cm outdoors / 2 cm indoors, sunk at 10 cm || a person, a crowd | `figure(batch, cloth, skin, center, *, scale=1.0, heading=0.0, pose=0.0)` 1.72 m, facing -Y turned by `heading`, `pose` 0 standing → 1 striding (~530) · `visitor(batch, cloth, mats, center, *, scale=1.0, heading=0.0, pose=0.0, variant=0)` a coat over `mats[variant]` legs, `mats[-1]` the skin · `crowd(batch, mats, points, rng, scale=1.0)` one per (x, y, z) — `lib/figure.py`; no faces, no hands with fingers: a figure reads at 3 m and beyond || motion between t = 0 and 1.5 s | `keyframe_path(obj, points, ctx, *, t0=0.0, t1=None, interpolation="LINEAR")` · `drift(obj, delta, ctx)` a boat, a balloon, a leaf · `spin(obj, axis="Z", turns_per_s=.25, ctx=None)` a SIMPLE driver `frame * k` (a wheel, a vane) · `sway(obj, axis, amplitude, period_s, ctx)` a SIMPLE driver, a sine of `frame` (a hanging lantern, a mast) · `scroll(mapping_node, velocity, ctx)` a texture that flows · `shape_key_sweep(obj, key_name, ctx, *, from_value=0.0, to_value=1.0)` a sail filling · `fcurves(id_data)` / `set_interpolation(id_data, interpolation="LINEAR")` the 5.2 slotted-action curves — `lib/motion.py`; keyframes land on `ctx.frame(t)`; a driver that needs Python evaluates to 0 in the build and fails it |-## The six rules that apply to all of them+## Six facts about all of them**1. Collection, name, seed.** Every factory takes the collection it links into(`ctx.collection` — never `bpy.context.collection`), a name, and a `seed` or`rng` wherever it draws: the same seed gives the same scene on every machine,-and `ctx.rng(seed)` is the ONLY randomness a zone uses. Names are global in+and `ctx.rng(seed)` is the only randomness the lint accepts. Names are global inBlender: `place.unique_name("Lantern", i)` — a duplicate silently becomes`Lantern_0.001` and reads as a stray instance.-**2. Seat everything.** A placed thing is a ROOT object in the zone's+**2. Seating is measured.** A placed thing is a ROOT object in the zone'scollection: a `Batch.finish` root, a `scatter.instance` Empty, a`mesh_object`. The gate samples its foot columns against what is under them:a gap over 5 cm (2 cm indoors) is floating, a burial over 10 cm is sunk, an AABBoverlap over 10 % of the smaller box is interpenetration, and a measureddefect caps the score. Batch recipes stand on the ground z you pass-(`height_at` (x, y)); instances seat themselves; anything else goes through-`place.seat(root, ctx.height_at)`. `obj["placement"] = "free"` ONLY for a thing-that really hangs or flies — the gate reports the share of free-tagged assets.+(`height_at` (x, y)); instances seat themselves; anything else can go through+`place.seat(root, ctx.height_at)` or your own seating. `obj["placement"] = "free"`+only for a thing that really hangs or flies — the gate reports the share of+free-tagged assets.**3. Motion is data on `ctx.frame(t)`.** Keyframes through `lib.motion`, or asimple driver of `frame`; never `frame_set`, handlers or Python drivers. Theharness renders `ctx.times` = 0 and 1.5 s and reads the .blend it saved.-**4. The world and the sun belong to `src/env.py`.** `sun_world` /-`night_world` / `gradient_world` and `lighting.sun` run in `build_env` and nowhere-else (the lint rejects a world in a zone); zones add their own practicals and-read `ctx.env["sun_direction"]`. Give the sky and the Sun lamp the SAME+**4. The world belongs to `src/env.py`.** `sun_world` / `night_world` /+`gradient_world` run in `build_env` and nowhere else (the lint rejects a world in+a zone); zones add the local lights their place has and may read what `build_env`+returned (`ctx.env`). A sky world and a Sun lamp agree when they share the sameazimuth / elevation.**5. Instances versus clouds.** A thing the plan counts (a bench, a cart, a-tree) is a `scatter.instance` of its asset collection: one row the gate can-name. Ground cover by the hundred (blades, pebbles, tufts) is a `gn_scatter` /-`grass_patch` cloud: one object, counted as instances, exempt from per-asset-placement. A prop is ONE `Batch`, not twenty primitives: the census and the-renderer are per object.+tree) is one root the gate can name — a `scatter.instance` of its asset+collection is the ready-made one. Ground cover by the hundred (blades, pebbles,+tufts) can be a `gn_scatter` / `grass_patch` cloud: one object, counted as+instances, exempt from per-asset placement. A thing the plan counts must be ONE+root object (the placement row and the census are per root): a `Batch`, a parent+Empty over parts, or a collection instance — never twenty loose primitives.-**6. Import only what you CALL.** `from lib.materials import material, woodgrain`-— not a module's whole export list. Measured on the three.js library's first-six scenes: 120 imported names were never used, and every later round had to-read them.+**6. Import only what you call.** `from lib.materials import material, woodgrain`+— not a module's whole export list; every later round has to read the imports.## What differs on this renderer@@ -79,21 +80,22 @@ read them.writes). There is NO post chain and NO bloom: an `emissive` skin atstrength 3-8 reads as a lamp, 20+ as a sun-bright source, and a lamp beside it(`lighting.practical`) is what actually lights the wall. Non-emissive albedos- belong in **0.02-0.8** linear.+ outside **0.02-0.8** linear push the frame gate toward dark / blown.* **The census is the evaluated depsgraph**: modifiers, geometry nodes andinstances count exactly as they render; a volume-only material is fog, notmatter (the `haze` box never appears as a placed thing). Unique trianglesare capped at 3 M; a tree is 3-9 k, a two-storey house ~10 k, so a hamlet anda wood fit with room to spare.-* **Blender 5.2 API facts the library already follows** (and you must too):- no `use_nodes`; `ShaderNodeMix` (not MixRGB) with RGBA on inputs 6 / 7 and- output 2; the Principled sockets are `Emission Color` / `Emission Strength` /- `Transmission Weight` / `Coat Weight` / `Specular IOR Level`; the sky is+* **Blender 5.2 API facts the library already follows** (the contract lists+ them): no `use_nodes`; `ShaderNodeMix` (not MixRGB) with RGBA on inputs 6 / 7+ and output 2; the Principled sockets are `Emission Color` / `Emission Strength`+ / `Transmission Weight` / `Coat Weight` / `Specular IOR Level`; the sky is`MULTIPLE_SCATTERING` with `aerosol_density`; boolean solvers are MANIFOLD /EXACT / FLOAT; geometry-nodes inputs are`getattr(mod.properties.inputs, "Socket_2").value = v`; actions are slotted(`lib.motion.fcurves`, not `action.fcurves`); `obj.matrix_world` is stale untilthe depsgraph runs (`lib.place.world_matrix`).* **One refracting water plane, no planar reflector budget to spend**: Cycles- refracts and reflects whatever is there. Keep the ground under the water (a- basin in `height_at`) so there is a bed to see.+ refracts and reflects whatever is there. Water that refracts needs a bed+ below its level in `height_at` (whatever shape the brief's water has) so there+ is something to see through it.diff --git a/harness/codeverse3d/prompts/scene_blender/system.md b/harness/codeverse3d/prompts/scene_blender/system.mdindex 6c398419..97264454 100644--- a/harness/codeverse3d/prompts/scene_blender/system.md+++ b/harness/codeverse3d/prompts/scene_blender/system.md@@ -3,15 +3,17 @@ headless harness builds and renders in Blender 5.2 LTS (Cycles, AgX). No SDKs,no file IO, no network: `bpy`, `bmesh`, `mathutils`, `math`, `numpy` and the workspace's own`lib.*` / `env` modules, nothing else. The harness owns the process, the render settings,the cameras, the frame clock and the export — you build geometry, materials, lights, the-world and the motion into the Collection you are handed.+world and the motion into the Collection you are handed. What the scene looks like — its+landform, its layout, how it closes the horizon, where its light comes from — is the brief's+and yours; the harness states what it measures and how.| file | you define | the harness calls it || --- | --- | --- |-| `src/env.py` | `height_at(x, y) -> z`, `build_env(ctx) -> dict` | first: world, sun, ground, atmosphere (an interior's shell) |+| `src/env.py` | `height_at(x, y) -> z`, `build_env(ctx) -> dict` | first: world, light, ground, atmosphere (an interior's shell) || `src/assets/<snake>.py` | `build_<snake>(ctx, variant=0) -> Collection` | once each, at the origin, base on z = 0 → `ctx.assets['<snake>']` || `src/zones/<snake>.py` | `build(ctx) -> Collection` | once each, into `ctx.collection`; a raise drops THAT zone only || `src/scene.py` | nothing — harness data | the entry; re-assembly overwrites it |-| `src/lib/*.py` | nothing — harness library | you import and call it (the catalog is in every brief) |+| `src/lib/*.py` | nothing — harness library | an optional toolbox you may import and call (the catalog is in every brief) |What the gates measure — deterministically, on the census of the built scene, before anypicture is judged:@@ -19,13 +21,19 @@ picture is judged:* **Placement.** Every root object you link into a zone is a row: a foot more than 0.05 mabove what is under it (0.02 m indoors) is `floating`, a foot buried past 0.10 m is`sunken`, two boxes sharing more than 10% of the smaller one is `interpenetration`, a- bbox touching nothing is `unsupported` — ERRORS at 0.08 m / 0.20 m / 35%. Seat things- with `lib.place.seat(obj, ctx.height_at)` or `lib.scatter.instance(..., height_at=- ctx.height_at)` and they pass; `obj["placement"] = "free"` is for things that hang in the- air, and the share of tagged things is reported.-* **Frames.** Every authored camera at t = 0 and t = 1.5 s: too dark, blown out, mostly sky or- ground, the camera inside geometry or below the terrain. Exposure is fixed (0): a dark- brief is lit by its practicals and a tinted world, never by hiding the sun.+ bbox touching nothing is `unsupported` — ERRORS at 0.08 m / 0.20 m / 35%.+ `lib.place.seat(obj, ctx.height_at)` and `lib.scatter.instance(..., height_at=ctx.height_at)`+ seat through the same foot columns the gate samples; your own seating passes the same way.+ `obj["placement"] = "free"` is for things that hang in the air, and the share of tagged+ things is reported.+* **Frames.** Every authored camera at t = 0 and t = 1.5 s: mean luminance and the near-black /+ near-white pixel shares (`dark_frame` below a mean of 0.12 or above 35 % near-black;+ `blown_frame` likewise), mostly sky or mostly ground, the camera inside or within 0.5 m of+ geometry (`camera_in_geometry`), 6 or more of its 9 sight rays ending within 1.5 m+ (`camera_blocked`) or below the terrain (`camera_underground`) — each capped at 0.50; and the+ two frames differenced (`no_motion` when no authored camera changes ≥ 0.4 % of its pixels).+ Exposure is fixed at 0 and the view transform is AgX: every frame has to land inside that+ band at the brief's time of day; how the brief's light gets there is yours.* **The probe.** Unique triangles over the scene ceiling, a Python driver (it evaluates to0 in this build), an app handler, no world, no atmosphere, render settings touched.@@ -43,37 +51,39 @@ you the exposure numbers directly — there is no reason to guess whether a duskYou cannot run anything: this is a single-shot session with no tools, so the code youreturn is the code that ships. Budget your care accordingly: seat every object through`ctx.height_at` (the gate measures the gap), keep every name unique, and light the brief's-time of day with numbers from the recipes rather than instinct — the failures below happen-in a build you cannot see.+time of day in physical units (Cycles reads W/m² and Watts; the frame gate's band is the one+check you will not see) — the failures below happen in a build you cannot see.{% endif %}-Rules that survive every brief:+What holds whatever the brief is:-* **The brief's time of day is a hard constraint, not a mood suggestion.** Decide it once,- write it down as constants in `src/env.py` (`SUN_AZIMUTH_DEG`, `SUN_ELEVATION_DEG`, the- world strength, the fog density) and make every zone read `ctx.env`. A night brief- rendered as noon is the wrong scene whatever is in it, and the frame gate cannot save- you: it only measures too-dark and too-bright.-* **The environment IS the scene, not its backdrop.** Sky, sun, ground material and- atmosphere carry more of the verdict than any prop. Build them FIRST and specific to the- brief (snow, wet cobbles, desert haze); a default sky over a flat single-colour ground- reads as "unfinished" however good the props on top are.-* **Light before colour, light before detail.** Cycles reads physical units: a Sun lamp of- 2–5 W/m² with a sky world at strength 0.2–0.5 for day, practicals (an emissive surface- plus a Point light with a radius) for dusk and night. Hue, material and geometry work are+* **The brief's time of day is a hard constraint, not a mood suggestion.** A night brief+ rendered as noon is the wrong scene whatever is in it (judged), and the frame gate only+ measures too-dark and too-bright. Decide it once in `src/env.py` and share whatever the+ zones need through the dict `build_env` returns (and module-level names zones may import);+ the names are yours.+* **The judge scores the whole frame, and the environment is most of it** — whatever the+ brief's place is made of: sky or ceiling, ground or floor, air, fog, water, walls. Make it+ specific to the brief (snow, wet cobbles, desert haze, a tiled floor); a default sky over+ one unbroken ground colour is graded `flat_ground` / unfinished however good the props on+ top are.+* **Light is physical units.** Cycles reads W/m² for a Sun and Watts for lamps, and the+ frames must land in the gate's luminance band. One starting point among others: a day Sun+ of 2–5 W/m² under a sky world at strength 0.2–0.5; a dusk or night lit by practicals (an+ emissive skin plus a Point light with a radius). Hue, material and geometry work areinvisible on near-black pixels.* **Things rest on things, and things stay out of each other.** `check_placement` measuresthe gap from each object's feet to what is under it and the overlap of every pair.- Compute where the ground is at that (x, y) and put the object there — never at z = 0 and- hope the terrain is flat; give neighbours room — never let a crate's box run through a- wall's.-* **One object = one thing.** A placed prop is ONE root object (a mesh, or an Empty with- its parts parented under it, or a collection instance of an asset) with a unique- PascalCase name; repeats are collection instances of `ctx.assets[...]`, fields of small- things are geometry-nodes clouds. Never `bpy.ops` in a loop.+ Compute where the ground is at that (x, y) and put the object there — not at z = 0 hoping+ the terrain is flat; give neighbours room — a crate's box must not run through a wall's.+* **One root = one placed thing.** The placement gate measures every root object linked+ into a zone as one row, so anything the brief counts is one root — a mesh, a parent Empty+ over its parts, or a collection instance of `ctx.assets[...]` — with a unique PascalCase+ name. Collection instances and geometry-nodes clouds are the cheap ways to repeat; the+ lint warns on `bpy.ops.mesh.primitive_*` inside a loop (each call rebuilds the scene state).* **Split the scene across modules** as the contract says, link everything into`ctx.collection`, and keep every import resolvable in the build. A module that raisestakes its whole zone out of the picture.A simple scene that is seated, lit and legible beats an elaborate one that floats in the-dark. Get the floor and the light right first; spend everything after that on the brief.+dark. Get the floor and the light right; spend everything after that on the brief.diff --git a/harness/codeverse3d/prompts/scene_threejs/asset.md b/harness/codeverse3d/prompts/scene_threejs/asset.mdindex 59291686..a7ded8d4 100644--- a/harness/codeverse3d/prompts/scene_threejs/asset.md+++ b/harness/codeverse3d/prompts/scene_threejs/asset.md@@ -1,13 +1,14 @@You write ONE self-contained three.js ESM asset module for a larger scene — a factory-function returning a `THREE.Group`, built from raw geometry primitives. Raw three.js only:+function returning a `THREE.Group`, built from procedural geometry. Raw three.js only:no DOM, no texture or image loading, no fetch. Imports: `import * as THREE from 'three'`, andthe scene's shipped effect library `../lib/*.js` when the task sheet names one of its factories —-it is harness code that ships with every scene, not an outside package.+it is harness code that ships with every scene, not an outside package, and it is optional.-The module is judged as a prop, at scene distance: silhouette first, then the 2-3-recognisable features a person would name, then wear that makes it look used. The task-sheet's exact export name, size and `opts` contract outrank everything else — zone code-calls your factory sight unseen and places the group by its origin, so a wrong export-name or an off-origin footprint fails the whole placement, not just this file.+The asset is judged as a prop, at scene distance: it must be recognisable as the thing the+plan's description names, and the description decides which features that takes and what+condition it is in. The task sheet's exact export name, size and `opts` contract outrank+everything else — zone code calls your factory sight unseen and places the group by its+origin, so a wrong export name or an off-origin footprint fails the whole placement, not just+this file.Write the one file completely and stop. No commentary, no extra files.diff --git a/harness/codeverse3d/prompts/scene_threejs/contract.md b/harness/codeverse3d/prompts/scene_threejs/contract.mdindex f3f28d14..54c8c0e3 100644--- a/harness/codeverse3d/prompts/scene_threejs/contract.md+++ b/harness/codeverse3d/prompts/scene_threejs/contract.md@@ -4,11 +4,12 @@```src/scene.js export async function createScene({ THREE, renderer, loaders })→ { scene, cameras, update(t, dt) }-src/env.js export const BOUNDS; export function heightAt(x, z); export function buildEnv(ctx) → { update(t, dt) }-src/zones/<snake>.js export function build(ctx) → THREE.Group (ctx = { THREE, scene, heightAt, loaders, env, ... })-src/assets/<snake>.js export function build<Asset>(THREE, opts = {}) → THREE.Group (procedural, Y-up, on y = 0)+src/env.js export function heightAt(x, z); export function buildEnv(ctx) → { update(t, dt) }+ (+ export const SUN_AZIMUTH_DEG, a plain number — see "The assembler")+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, Y-up, lowest point on y = 0)src/shaders/<snake>.js export function make<Name>Material(THREE, opts = {}) → THREE.ShaderMaterial | patched material-src/lib/*.js HARNESS-OWNED effect library — import and call, never rewrite+src/lib/*.js HARNESS-OWNED effect library — an optional toolbox: import and call; writes to it are revertedpublic/assets/<snake>.glb (optional) Blender-built assets — the assembled scene.js preloads each into ctx.assets['<snake>']; zones clone it (its clips play by themselves)```The harness serves the workspace root over http (`public/assets/` is mounted at@@ -16,22 +17,64 @@ The harness serves the workspace root over http (`public/assets/` is mounted at`WebGLRenderer` (shadows on, ACES tone mapping, sRGB output; logarithmic depth may be onor off — write shaders that work either way) and `loaders = { gltf, texture, cube,manager }` (GLTFLoader etc.). It awaits `createScene`, validates the return value, then-for each camera renders at t ∈ {0, 1.5} s (calling `update`) and takes probes (tris, draw-calls, console/shader errors, camera-inside-geometry, black/blown frames, content coverage,-fps). Frame gate (`scene_frames`, ERROR on authored cameras): too dark, blown out, or an-establishing shot that is mostly sky/ground. Dusk/night = coloured, never black-(cookbook: "Dusk / night lighting recipe").+renders every camera at t = 0 and t = 1.5 s (calling `update`) and takes probes (tris, draw+calls, console/shader errors, camera-inside-geometry, dark/blown/flat frames, content+coverage, fps, the difference between the two frames). The plan's **bounds** are the region+the content census and the placement gate measure against; the world a camera sees may+extend as far past them as the brief needs.## createScene return value-* `scene`: `THREE.Scene` with `scene.fog` set and a background colour or sky dome.-* `cameras`: 3–4 **plain objects** `{ name, position: [x, y, z], lookAt: [x, y, z], fov }`- (the harness builds the PerspectiveCameras: aspect 16/9, near 0.1, far from bounds).- Names PascalCase from the plan (`Establishing`, `HarbourMid`, `LanternDetail`); fov- 35–60; eye height ≈ 1.6 m for human views; never inside or up against geometry; the- first camera is the establishing shot showing ≥ 70 % of the bounds.+* `scene`: a `THREE.Scene`. Whatever a camera can see must terminate in something the brief+ justifies — sky, a wall, a ceiling, fog, darkness. The census reads `scene.fog` and+ `scene.background` on every boot (unset = `no_fog` / `no_background`, ERROR), the world-edge+ finding reads a ground edge meeting the sky, and the flat-frame gate reads a single-band frame.+* `cameras`: a non-empty list of **plain objects** `{ name, position: [x, y, z], lookAt: [x, y, z], fov }`+ (the harness builds the PerspectiveCameras: aspect 16/9, near 0.1, far from bounds). The+ plan's camera list decides how many; each is rendered twice and gated. Names PascalCase from+ the plan. `cameras[0]` is measured as the establishing view:+ ≥ 20 % of its frame must be content, not sky or ground; what it establishes — a street+ receding, a canyon wall, a room — is the brief's, and it need not contain the whole bounds.+ fov and eye height are the brief's; the gate requires the eye ≥ 0.3 m above the ground under+ it (`camera_low` WARN; `camera_high` WARN above 80 m), ≥ 0.5 m from every surface+ (`camera_in_geometry`, ERROR, cap 0.50), no more than 5 of its 9 sight rays ending within+ 1.5 m (`camera_blocked`, ERROR, cap 0.50), and the line of sight to `lookAt` not cut in its+ first half. Compute y from `heightAt(x, z)` (or the floor it stands on): a camera below the+ ground under it is `camera_underground` (cap 0.50).* `update(t, dt)`: advance animation (t seconds since start, dt seconds). MUST be cheap- (no allocations, no traversals — cache lists of animated objects / materials at build- time). Deterministic: the same t always gives the same frame.+ (no allocations, no traversals, no material or shader creation — cache lists of animated+ objects / materials at build time). Deterministic: the same t always gives the same frame.++## The assembler (staged runs)+In a staged run `src/scene.js` is **written by the harness** from your `src/env.js` and+`src/zones/*.js`, and overwrites anything you put there. That generated file is the only+caller of your modules, so these signatures are the whole interface — get one wrong and the+module is silently dropped or its animation never runs:++```js+const ctx = { THREE, scene, renderer, loaders, heightAt, assets };+const env = (await buildEnv(ctx)) || {}; // src/env.js → ONE argument: ctx+ctx.env = env;+const g = await build(ctx); // src/zones/<snake>.js → the export is named `build`+if (!g || !g.isObject3D) throw new Error(...); // must return a Group / Object3D+scene.add(g);+function update(t, dt) {+ if (env.update) env.update(t, dt); // env animation ONLY via the returned update+ for (const z of zones) if (z.userData.update) z.userData.update(t, dt); // zone animation ONLY via userData.update+}+```+* `tickEnv`, `userData.tick`, `buildEnv(THREE, scene)` and `build<Zone>(ctx)` are NEVER called.+ An asset's own `userData.update` runs only if its zone caches it at build time and calls it+ from the zone's `userData.update`; a hook that is never called stands still, and calling a+ missing hook throws.+* `src/env.js` also exports `heightAt(x, z)` — the surface every zone seats on: deterministic,+ cheap, `0` for a flat floor; any walkable surface the brief has (a path, a road, a deck) is part+ of it, and the placement gate measures against it, so it must agree with the mesh — and+ `SUN_AZIMUTH_DEG` (a plain numeric `export const`, read by regex to put the overview cameras on+ the sun side; omitted, the rig guesses 45°). Nothing else in `env.js` is read by the harness:+ whatever else it exports (shared materials, a water level, a route) is a convention between+ you and the zones, named as you like, and zones may `import` it.+* Without the assembler the harness asks for `src/scene.js` by hand: exactly the wiring above,+ returning `{ scene, cameras, update }`.## Imports (only these resolve)`three`, `three/addons/*` (GLTFLoader, BufferGeometryUtils, Sky, Water, EffectComposer…).@@ -66,103 +109,123 @@ perform browser loading in `createScene`, and pass already loaded text where nee`update(t, dt)` changes uniforms or transforms, without loading or shader compilation.For GLSL 3 use `glslVersion: THREE.GLSL3`, explicit `in`/`out` varyings and a fragmentoutput; let Three add the version line instead of adding a second `#version`.+A hand-written shader loses Three's fog and depth chunks unless it is built with+`makeShaderMaterial` / `patchStandard` from `lib/shader.js`, which keep them.`src/lib/` is NOT a helper SDK and the "raw language only" law does not exclude it: it isharness-owned source shipped into this workspace, every module compiled and rendered on-this renderer, and writes to it are reverted. Reach for it before writing your own-version of the same effect — the want → call table ships with this brief.+this renderer, and writes to it are reverted. It is an optional toolbox — the want → call+table ships with this brief; use an entry when it fits the brief, write your own when it does+not. Import only the names you call (measured over six scenes: 120 imported names were never+used — dead weight every later round re-reads), and only names the catalog prints for a module:+importing a name a module does not export is a SyntaxError that drops the whole zone.The harness renders scene pictures THROUGH a post chain (GTAO + a selective emissive-bloom + a grade that is identity unless `scene.userData.grade` is set). So emissives DO-bloom: author them at the cookbook's practical level (`PRACTICAL` in `lib/environment.js`),-not 20. `--no-post` / `C3D_POST=0` turns it off.+bloom + a grade that is identity unless `scene.userData.grade` is set), and the scene must+still read without it. Emissives DO bloom: author them at the practical level (`PRACTICAL`+in `lib/environment.js`; peak 1.5–4, not 20); a material opts in or out with+`material.userData.bloom = false | true | <colour>`. Do not build an `EffectComposer`:+nothing reads one. `--no-post` / `C3D_POST=0` turns the chain off.## Forbidden-`document.*` / `window.*` except `window.innerWidth` — never create canvases or DOM;-external network requests or arbitrary `fetch`/XHR (use `loaders.gltf` for assets+`document.*` / `window.*` except `window.innerWidth` and `document.createElement('canvas')` for+a procedural texture (the one DOM call the lint allows; no other DOM); external network requests or arbitrary `fetch`/XHR (use `loaders.gltf` for assetsand the local FileLoader pattern above for shader text); `Math.random()` (use `mulberry32(seed)` from `lib/noise.js`);`Date.now()`/`performance.now()` (use `t`); `requestAnimationFrame`; creating a renderer;changing renderer settings; environment sniffing (`navigator.userAgent`, headless checks).+Textures: the shipped procedural materials (including their DataTextures) or the provided+`loaders.texture` for files actually present in the workspace — nothing fetched.-## Efficiency-InstancedMesh for anything repeated > 5×; textures: the shipped procedural materials-(including their DataTextures) or the provided `loaders.texture` for textures actually-present in the workspace; `update` allocates nothing and traverses nothing.+## What is measured (the gates and probes, with their thresholds)+* **Placement** (`check_placement`; the `scene_placement` gate 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. A 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; things that are buried, slope-following+ or driven in by nature are exempt, as is a foot at or under water); a bbox touching nothing =+ `unsupported`; two boxes sharing > 10 % of the smaller one = `interpenetration` (ERROR at+ 35 %). A Group holding several props is measured as ONE object whose box is their union, so+ every prop inside it reads as interpenetrating it: one placed thing = one direct child; a prop+ built from parts is one Group; many of one thing is one `InstancedMesh` (instances are not+ checked one by one, but a scattered instance inside a placed thing is that thing's+ interpenetration). A thing meant to hang in the air carries `obj.userData.placement = 'free'`+ (`free_exempt`: WARN when more than 25 % of the placed objects are tagged, ERROR past 50 %).+ A thing resting on one corner with the others in the air — four or more foot columns, at most+ one touching, the worst gap > 0.05 m — is `cantilevered` (WARN). A placed asset is measured+ as ONE object against the plan's `approx_size_m`: WARN beyond 2.5 × (or under 1 / 2.5), ERROR+ beyond 4 × (`scale`; the judge's `wrong_scale`, cap 0.75, is perceptual); a part that must+ reach further is a separate object.+* **Bounds and density.** A PLANNED content placed entirely outside the plan bounds plus+ max(5 m, 10 % of the span) is `out_of_bounds` (a WARN; scenery that continues the place past+ the bounds is never reported); a zone group missing or empty is `zone_empty`; a planned asset+ not placed is `missing_content`; a zone under half the instances its layout counted gets an+ INFO `density_note` (the counts the brief states are its acceptance items).+* **The world's extent** (exteriors only). Standing geometry ≥ 2 m tall must reach at least+ 1.25 × the bounds half-extent from the bounds centre (`world_edge`, a WARN); fog far must be ≥ 2 × the+ plan span — or, for `FogExp2`, 1 / density ≥ span / 1.5 — (`fog_short`: past fog far the land+ turns the background colour while the unfogged sky stays sharp); ≥ 8 same-size copies evenly on a circle round the world's edge is a+ `stamped_ring` (the judge reads it as "identical pyramids stamped in a ring"). What continues+ the world — a street's next block, more forest, open sea, a wall, a skyline on one side, haze —+ is the brief's.+* **Frames** (`scene_frames`, per authored camera): the exposure band (`dark_frame`,+ `blown_frame`, `flat_frame`), camera placement (`camera_in_geometry`, `camera_blocked`,+ `camera_underground`, `camera_low`, `camera_high`) and content fraction (`content_small`) the+ system prompt states; `scene_views(times=[0, 1.5])` prints the frame table and the measured+ motion per camera. Non-solid cards (haze quads, shafts) near a camera read as geometry to the+ raycast: give them `mesh.raycast = () => {};` — never real geometry.+* **Motion** (`frame_motion`, per authored camera): the t = 0 and t = 1.5 s frames are+ differenced; 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); the judge's+ `nothing_moves` follows it.+* **A hero GLB in frame** (`hero_unseen`): a `public/assets/*.glb` hero covering < 0.5 % of the+ frame in EVERY authored camera is an ERROR; < 2 % in the camera the plan names for it is a WARN.+* **Shaders and errors**: a console or shader error in any module is a build finding;+ `shader_probe` compiles a material before it renders black.+* **Assets**: a procedural asset module is imported and built in node when written; one instance+ is budgeted at 15 000 triangles, its lowest point at y = 0, its footprint centred on the origin,+ its size the plan's (the check errors beyond 2.5 × or under 0.4 × the plan's on any axis, and on+ a single-box blockout).## NamingZones are Groups named PascalCase (plan zone names); assets Groups PascalCase; every-animated object has a stable `.name`; ShaderMaterials `mat.name = 'Water'`.+animated object has a stable `.name`; ShaderMaterials `mat.name = 'Water'`; the ground mesh is+named `Ground`; backdrop geometry beyond the content is named `Sky…` (classified as sky, so it+does not inflate the content box or the overview fit); an interior's lid meshes are named+`Ceiling…` / `RoomShell…` so the overview rig can lift them.++## Language facts that are build errors or silent failures+* `Math.random()` gives different geometry every build and un-reproducible renders: `mulberry32(seed)`.+* 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 — check before `computeVertexNormals`.+* `walk(fig, t)` (lib/figure.js) runs only inside `userData.update(t)`; at build time it throws+ `time must be finite`.+* A GLB hero is visible only if the zone clones `ctx.assets['<snake>']` (nothing loads a GLB+ itself); its pivot is at its base; `clone.userData.clipOffset = <seconds>` de-phases a copy.+* `makeText` (lib/signage.js) is async: await it ONCE at module top level, `.clone()` per copy.+* Water: inside any shoreline the terrain must lie below the water level or the shore z-fights.+* A camera below the terrain under it, or inside a mesh, is a gate ERROR capped at 0.50: the+ plan's camera heights are absolute metres, so compute y from `heightAt(x, z)` (or the floor+ it stands on), never from a guess.+* 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 })`+ fits frustum, map size and bias to the radius it is given, and a hand-set `sun.shadow.*`+ must meet the same texel size.+* `update` that allocates (`new Vector3`, `getSize` per frame) or traverses hitches the GC:+ hoist scratch objects to module scope and cache lists at build time.-## COMPLETE minimal example (verified in node: module evaluates, createScene resolves, cameras valid)+## The env module's shape (the interface, nothing else; the assembler block above is the rest)`src/env.js````jsimport * as THREE from 'three';-import { sunRig } from './lib/environment.js';-export const BOUNDS = { min: [-40, 0, -40], max: [40, 25, 40] };-export function heightAt(x, z) { // gentle rolling ground, deterministic- return 0.6 * Math.sin(x * 0.12) * Math.cos(z * 0.09) + 0.2 * Math.sin((x + z) * 0.31);-}+export const SUN_AZIMUTH_DEG = 250; // the plan's light, as a plain number (0 = +X, 90 = +Z; read by regex)+export function heightAt(x, z) { return 0; } // the brief's surface — any function of (x, z) that agrees with the ground meshexport function buildEnv({ THREE, scene }) {- scene.background = new THREE.Color(0x9fc4e8);- scene.fog = new THREE.Fog(0x9fc4e8, 40, 140);- // ONE rig: key + hemisphere fill + the environment map metals read from + disc + shadows- // fitted to BOUNDS; tint through sunColor / fillSky / fillGround, never a second sun- const rig = sunRig({ mood: 'day', azimuth: 35, elevation: 48, bounds: 45 });- scene.add(rig.sun, rig.sun.target, rig.fill);- if (rig.sunDisc) scene.add(rig.sunDisc);- scene.environment = rig.envTex;- const geo = new THREE.PlaneGeometry(80, 80, 80, 80); geo.rotateX(-Math.PI / 2);- const pos = geo.attributes.position;- for (let i = 0; i < pos.count; i++) pos.setY(i, heightAt(pos.getX(i), pos.getZ(i)));- geo.computeVertexNormals();- const ground = new THREE.Mesh(geo, new THREE.MeshStandardMaterial({ color: 0x5e7a3a, roughness: 1 }));- ground.name = 'Ground'; ground.receiveShadow = true; scene.add(ground);- return { update(t, dt) {} };-}-```-`src/zones/grove.js`-```js-import * as THREE from 'three';-import { mulberry32 } from '../lib/noise.js';-export function build({ THREE, heightAt }) {- const rand = mulberry32(7); // seeded: the same grove every build- const zone = new THREE.Group(); zone.name = 'Grove';- const N = 40;- const trunk = new THREE.InstancedMesh(new THREE.CylinderGeometry(0.12, 0.18, 2.4, 8),- new THREE.MeshStandardMaterial({ color: 0x5a3b22, roughness: 0.9 }), N);- const crown = new THREE.InstancedMesh(new THREE.ConeGeometry(1.4, 3.2, 9),- new THREE.MeshStandardMaterial({ color: 0x2f6b2a, roughness: 0.8 }), N);- const m = new THREE.Matrix4(), q = new THREE.Quaternion(), s = new THREE.Vector3(), p = new THREE.Vector3();- for (let i = 0; i < N; i++) {- const x = -18 + 36 * rand(), z = -18 + 36 * rand(), y = heightAt(x, z);- const k = 0.8 + 0.5 * rand();- p.set(x, y + 1.2 * k, z); s.set(k, k, k); m.compose(p, q, s); trunk.setMatrixAt(i, m);- p.set(x, y + 2.4 * k + 1.4 * k, z); m.compose(p, q, s); crown.setMatrixAt(i, m);- }- trunk.castShadow = crown.castShadow = true;- trunk.computeBoundingSphere(); crown.computeBoundingSphere();- zone.add(trunk, crown);- zone.userData.update = (t) => { crown.rotation.y = 0.0; }; // hook for per-zone motion- return zone;-}-```-`src/scene.js`-```js-import * as THREE from 'three';-import { buildEnv, heightAt, BOUNDS } from './env.js';-import { build as buildGrove } from './zones/grove.js';-export async function createScene({ THREE, renderer, loaders }) {- const scene = new THREE.Scene();- const ctx = { THREE, scene, renderer, loaders, heightAt, assets: {} };- const env = buildEnv(ctx); ctx.env = env;- const grove = buildGrove(ctx);- scene.add(grove);- const cameras = [ // plain objects; the harness builds the cameras- { name: 'Establishing', position: [38, 14, 42], lookAt: [0, 2, 0], fov: 40 },- { name: 'GroveWalk', position: [6, heightAt(6, 20) + 1.6, 20], lookAt: [0, 2, 0], fov: 55 },- { name: 'GroveDetail', position: [-4, heightAt(-4, 9) + 1.6, 9], lookAt: [-6, 1.2, 4], fov: 45 },- ];- const movers = [grove];- return { scene, cameras, update(t, dt) { env.update(t, dt); for (const m of movers) m.userData.update?.(t, dt); } };+ // the brief's sky, light, ground (a mesh named 'Ground…' sampled from heightAt) and atmosphere go here:+ // scene.fog + scene.background set (no_fog / no_background), scene.environment an env texture+ return { update(t, dt) {} }; // the ONLY env hook the assembler calls}```+A zone module is `export function build(ctx) → THREE.Group` with its animation on+`group.userData.update`; a hand-written `src/scene.js` is the assembler block above verbatim,+returning `{ scene, cameras, update }` with the plan's camera list.diff --git a/harness/codeverse3d/prompts/scene_threejs/cookbook.md b/harness/codeverse3d/prompts/scene_threejs/cookbook.mddeleted file mode 100644index 5ccd829d..00000000--- a/harness/codeverse3d/prompts/scene_threejs/cookbook.md+++ /dev/null@@ -1,1015 +0,0 @@-# Scene cookbook — multi-file three.js scenes (r182), headless-rendered by the harness--Every `js` snippet runs as-is in node (the harness test suite concatenates them with-`THREE` and the named addons in scope). Y-up, +Z front, meters. GLSL goes through-`lib/shader.js` — use its `makeShaderMaterial(opts)` for every custom shader.-The harness inlines the relevant chapters into your prompts; the full file is at-`.3dcode/cookbook.md` in your workspace.--**The chapters that decide the score.** Scenes on this track lose most of their points to-five repeatable defects, one chapter each:--| the judge writes | read this chapter |-|---|---|-| "flat ground plane", "one colour", "no paths" | Ground that reads real |-| "a hard world edge is visible against the sky" | Horizon: the world must not end |-| "monotonous / identical cones", "primitive stacked shapes" | Vegetation that reads real · Rocks, cliffs and boulders |-| "sparse", "a diorama on an empty plane", "no midground" | Scene layering · Set dressing |-| "flat light", "too dark", "monochrome", "jagged shadows" | Atmosphere: time-of-day triads |-| "frames at t=0 and t=1.5 are identical" | Motion you can SEE between t = 0 and t = 1.5 s |--## Environment (`src/env.js`): sun + sky + fog + ground — the scene's floor comes first--```js-const BOUNDS = { min: [-50, 0, -50], max: [50, 30, 50] }; // export const in real env.js-const rand = mulberry32(7); // lib/noise.js: the seeded PRNG — never Math.random--function heightAt(x, z) {- // deterministic analytic terrain — EVERY placement must call this, or things float- return 0.8 * Math.sin(x * 0.09) * Math.cos(z * 0.07) + 0.35 * Math.sin((x * 0.31 + z * 0.23));-}--function buildEnv({ THREE, scene }) {- // fog + matching background: the single biggest depth cue- scene.fog = new THREE.Fog(0xa8c4dd, 45, 160); // near ≈ bounds/2, far ≈ 1.6 × diagonal- scene.background = new THREE.Color(0xa8c4dd);- // sky dome gradient (cheap, always works; the Sky addon is the fancy alternative)- const skyGeo = new THREE.SphereGeometry(240, 24, 12);- const skyMat = makeShaderMaterial({ // lib/shader.js: tonemap + colorspace included- name: 'SkyDome', side: THREE.BackSide, fog: false, depthWrite: false,- uniforms: { uTop: { value: new THREE.Color(0x4e7fb8) }, uHorizon: { value: new THREE.Color(0xd8e4ec) } },- varyings: 'varying vec3 vP;', vertexMain: ' vP = position;',- fragmentHead: 'uniform vec3 uTop; uniform vec3 uHorizon;',- fragmentMain: ' float h = clamp(normalize(vP).y, 0.0, 1.0); gl_FragColor = vec4(mix(uHorizon, uTop, pow(h, 0.55)), 1.0);',- });- const sky = new THREE.Mesh(skyGeo, skyMat); sky.name = 'SkyDome'; scene.add(sky);- // lights: ONE sunRig (lib/environment.js) — key, hemisphere fill, the environment map,- // the disc, and a shadow camera, map size and bias it fits to `bounds` itself- const rig = sunRig({ mood: 'day', azimuth: 35, elevation: 48, bounds: 50 });- scene.add(rig.sun, rig.sun.target, rig.fill);- if (rig.sunDisc) scene.add(rig.sunDisc);- scene.environment = rig.envTex;- // ground displaced by heightAt, vertex-coloured by slope/height (no textures)- const g = new THREE.PlaneGeometry(100, 100, 128, 128); g.rotateX(-Math.PI / 2);- const pos = g.attributes.position, col = new Float32Array(pos.count * 3);- const grass = new THREE.Color(0x5d7c3a), dirt = new THREE.Color(0x77644a), c = new THREE.Color();- for (let i = 0; i < pos.count; i++) {- const y = heightAt(pos.getX(i), pos.getZ(i));- pos.setY(i, y);- c.copy(dirt).lerp(grass, THREE.MathUtils.clamp(0.5 + y * 0.5, 0, 1));- col.set([c.r, c.g, c.b], i * 3);- }- g.setAttribute('color', new THREE.BufferAttribute(col, 3));- g.computeVertexNormals();- const ground = new THREE.Mesh(g, new THREE.MeshStandardMaterial({ vertexColors: true, roughness: 1.0 }));- ground.name = 'Ground'; ground.receiveShadow = true; scene.add(ground);- return { update(t, dt) {} };-}-```--Numbers: the rig's own per-mood intensities (tint it, do not add lights); `bounds` = the-content radius, which fits the shadows; fog near ≈ half the bounds, far ≈ 2 × the diagonal; ground ≈ 1-segment per metre. Full palettes per time of day are in the time-of-day chapter.--## The exact contract the harness assembler enforces--`src/scene.js` is **written by the harness**, not by you — it is regenerated from your-`src/env.js` + `src/zones/*.js` and overwrites anything you put there during the stages.-That generated file is the only caller of your modules, so these five signatures are the-whole interface. Get one wrong and your module is silently dropped or your animation-never runs.--```js-// This is (verbatim) what the assembler generates and calls:-//-// const ctx = { THREE, scene, renderer, loaders, heightAt, assets };-// const env = (await buildEnv(ctx)) || {}; // src/env.js -> ONE argument: ctx-// ctx.env = env;-// const g = await build(ctx); // src/zones/<snake>.js -> export name is `build`-// if (!g || !g.isObject3D) throw ... // must return a Group/Object3D-// scene.add(g);-// function update(t, dt) {-// if (env.update) env.update(t, dt); // env animation ONLY via env.update-// for (const z of zones) if (z.userData.update) z.userData.update(t, dt);-// } // zone animation ONLY via userData.update-//-// So:-// src/env.js export function buildEnv(ctx) -> { ..., update(t, dt) } (+ heightAt, BOUNDS,-// SUN_AZIMUTH_DEG, MATS)-// src/zones/<snake>.js export function build(ctx) -> THREE.Group with .userData.update-// src/assets/<snake>.js export function build<Asset>(THREE, opts) -> THREE.Group (called by zones)-//-// `tickEnv`, `userData.tick`, `buildEnv(THREE, scene)` and `build<Zone>(ctx)` are NEVER called.-// An asset's own hook is only run if its zone forwards it (pattern below).-function assemblerContractDemo(THREE) {- const zone = new THREE.Group(); zone.name = 'Demo';- const asset = new THREE.Group(); // an asset that animates itself- asset.userData.update = (t) => { asset.rotation.y = t * 0.8; };- zone.add(asset);- const movers = [asset]; // cache ONCE at build time- zone.userData.update = (t, dt) => { for (const a of movers) a.userData.update(t, dt); };- return zone;-}-const contractDemo = assemblerContractDemo(THREE);-contractDemo.userData.update(1.5, 0.016);-console.log('assembler contract demo rotated to', contractDemo.children[0].rotation.y.toFixed(2));-```--`SUN_AZIMUTH_DEG` (a plain `export const`, degrees) is read out of `src/env.js` **by-regex** and used to place the harness's overview cameras on the sun side. Export it or-the overview rig guesses 45° and may shoot into the sun.--If the assembler is unavailable the harness asks you to write `src/scene.js` by hand: then-write exactly the code in the comment above — `createScene({THREE, renderer, loaders})`-returning `{ scene, cameras, update }`, cameras as plain `{name, position, lookAt, fov}`-objects, animation fanned out through `env.update` and `zone.userData.update`.--## Ground that reads real (blend, paths, edges — never one flat colour)--A single-colour plane is the #1 reason a scene reads as a toy. Real ground is **three or-four materials blended by height, slope and noise**, with paths carved into the height-function itself and dressed edges where anything meets it.--```js-// --- deterministic value noise (no textures, no Math.random) ------------------const gHash = (x, z) => { const s = Math.sin(x * 127.1 + z * 311.7) * 43758.5453; return s - Math.floor(s); };-function gNoise(x, z) { // smooth, C1, cheap- const xi = Math.floor(x), zi = Math.floor(z), fx = x - xi, fz = z - zi;- const u = fx * fx * (3 - 2 * fx), v = fz * fz * (3 - 2 * fz);- return (gHash(xi, zi) * (1 - u) + gHash(xi + 1, zi) * u) * (1 - v)- + (gHash(xi, zi + 1) * (1 - u) + gHash(xi + 1, zi + 1) * u) * v;-}-function gFbm(x, z) { return 0.6 * gNoise(x, z) + 0.3 * gNoise(x * 2.1, z * 2.1) + 0.1 * gNoise(x * 4.3, z * 4.3); }--// --- the path is part of heightAt, so everything placed on it lands on it ------const PATH = [[-26, -20], [-9, -7], [4, 2], [17, 15], [26, 26]]; // polyline in meters-const PATH_HALF_W = 0.9; // 1.8 m wide path-function distToPath(x, z) {- let best = 1e9;- for (let i = 0; i < PATH.length - 1; i++) {- const [ax, az] = PATH[i], [bx, bz] = PATH[i + 1];- const vx = bx - ax, vz = bz - az, wx = x - ax, wz = z - az;- const t = Math.max(0, Math.min(1, (wx * vx + wz * vz) / (vx * vx + vz * vz)));- const dx = wx - t * vx, dz = wz - t * vz;- best = Math.min(best, Math.sqrt(dx * dx + dz * dz));- }- return best;-}-function terrainHeight(x, z) {- const base = 1.1 * gFbm(x * 0.035, z * 0.035) - 0.55 + 0.25 * Math.sin(x * 0.08) * Math.cos(z * 0.06);- const d = distToPath(x, z);- const flat = 1 - Math.min(1, Math.max(0, (d - PATH_HALF_W) / 2.2)); // 1 on the path → 0 at 3.1 m- return base * (1 - 0.85 * flat) - 0.05 * flat; // path is flat and slightly sunken-}--// --- colour by height + slope + noise + path -----------------------------------const GROUND_PALETTE = {- grass: 0x54702f, // flat, low, wet- dry: 0x8a8148, // flat, high- dirt: 0x6b5334, // moderate slope- rock: 0x6e6a63, // steep slope- path: 0xa89a7c, // gravel / packed earth-};-function buildBlendedGround(THREE, opts = {}) {- const size = opts.size ?? 160, seg = opts.seg ?? 160, h = opts.heightAt ?? terrainHeight;- const P = Object.assign({}, GROUND_PALETTE, opts.palette);- const g = new THREE.PlaneGeometry(size, size, seg, seg); g.rotateX(-Math.PI / 2);- const pos = g.attributes.position, col = new Float32Array(pos.count * 3);- const grass = new THREE.Color(P.grass), dry = new THREE.Color(P.dry), dirt = new THREE.Color(P.dirt);- const rock = new THREE.Color(P.rock), path = new THREE.Color(P.path), c = new THREE.Color();- const e = size / seg;- for (let i = 0; i < pos.count; i++) {- const x = pos.getX(i), z = pos.getZ(i), y = h(x, z);- pos.setY(i, y);- const slope = Math.min(1, (Math.abs(h(x + e, z) - y) + Math.abs(h(x, z + e) - y)) / (e * 1.2));- const n = gFbm(x * 0.35, z * 0.35); // breaks every band into patches- c.copy(grass).lerp(dry, THREE.MathUtils.clamp(0.35 + y * 0.5 + (n - 0.5) * 0.9, 0, 1));- c.lerp(dirt, THREE.MathUtils.smoothstep(slope, 0.12, 0.45));- c.lerp(rock, THREE.MathUtils.smoothstep(slope, 0.45, 0.9));- const onPath = 1 - THREE.MathUtils.smoothstep(distToPath(x, z), PATH_HALF_W, PATH_HALF_W + 1.4);- c.lerp(path, onPath * (0.75 + 0.25 * n));- c.offsetHSL(0, 0, (n - 0.5) * 0.05); // last 5 % of tonal break-up- col.set([c.r, c.g, c.b], i * 3);- }- g.setAttribute('color', new THREE.BufferAttribute(col, 3));- g.computeVertexNormals();- const mesh = new THREE.Mesh(g, new THREE.MeshStandardMaterial({ vertexColors: true, roughness: 1.0, metalness: 0.0 }));- mesh.name = 'Ground'; mesh.receiveShadow = true;- return mesh;-}-const groundDemo = buildBlendedGround(THREE, { size: 120, seg: 120 });-console.log('ground verts', groundDemo.geometry.attributes.position.count, 'coloured', !!groundDemo.geometry.attributes.color);-```--**Edge dressing.** Where anything meets the ground (fence, wall, deck, raised bed) sink it-3–5 cm in AND scatter 6–15 small pieces (tufts, pebbles, leaves, moss) along the seam;-raised platforms get a chamfered kerb, never a naked box edge.--```js-function dressSeam(THREE, { path, n = 24, radius = 0.35, spread = 0.5, color = 0x4f6b2c, heightAt = terrainHeight, seed = 3 }) {- // path = [[x, z], ...] the seam polyline; returns ONE InstancedMesh of tufts hugging it- const geo = new THREE.IcosahedronGeometry(radius, 0);- const mesh = new THREE.InstancedMesh(geo, new THREE.MeshStandardMaterial({ color, roughness: 1, flatShading: true }), n);- const m = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0), p = new THREE.Vector3(), s = new THREE.Vector3();- for (let i = 0; i < n; i++) {- const u = (i + 0.5) / n * (path.length - 1), k = Math.min(path.length - 2, Math.floor(u)), f = u - k;- const x = path[k][0] + (path[k + 1][0] - path[k][0]) * f + (gHash(seed + i, 1) - 0.5) * spread;- const z = path[k][1] + (path[k + 1][1] - path[k][1]) * f + (gHash(seed + i, 2) - 0.5) * spread;- const sc = 0.5 + 0.9 * gHash(seed + i, 3);- q.setFromAxisAngle(up, gHash(seed + i, 4) * 6.283);- p.set(x, heightAt(x, z) - radius * 0.35 * sc, z); s.set(sc, sc * 0.6, sc);- m.compose(p, q, s); mesh.setMatrixAt(i, m);- }- mesh.instanceMatrix.needsUpdate = true; mesh.computeBoundingSphere();- mesh.name = 'SeamTufts'; mesh.castShadow = false; mesh.receiveShadow = true;- return mesh;-}-console.log('seam tufts', dressSeam(THREE, { path: [[-6, -6], [6, -6], [6, 6]] }).count);-```--Numbers: ground segments ≈ 1 per metre (160 × 160 for 160 m); ≥ 3 blended colours, each-with ≥ 8 % of the visible area; path 1.2–2.0 m wide; a ground plane that is one flat-colour, or a raised bed that is a sharp box on top of grass, are both graded as defects-(`flat_ground`, `undressed_scene`).--## Horizon: the world must not end (fixing `world_edge_visible`)--The single most repeated judge complaint on this track is *"a hard world edge is visible-against the sky"*. Five rules kill it for good — and rules 4 and 5 are what separate a-hazy horizon from *"plain untextured beige cut-outs"*, which scores worse than no backdrop:--1. **Ground reaches past the fog.** Ground size ≥ `2.4 × fogFar`. Detail only needs to- exist inside the bounds; beyond that, one big low-resolution disc is enough.-2. **Fog colour == sky colour at the horizon.** Then the ground fades into the sky- instead of ending at it — and `fogFar` must be scaled to the scene (see the- time-of-day chapter: the table is for a 100 m scene, multiply by `diag / 100`).-3. **A silhouette ring** at `radius ≈ 0.6 × fogFar` (and ≥ 2 × the bounds half-diagonal):- 24–40 low-poly hills / treeline / rooftops / mesa blocks, height 0.06–0.12 × radius.- Measured on a 45 m garden with fog 16/77 m: a ring at 46 m reads as distant hills, the- same ring at 95 m reads as a spiky crater wall, at 20 m as a stone circle.-4. **Never hand-tint the backdrop toward the fog colour.** `scene.fog` already blends- every fogged material toward the fog colour by distance; lerping the material as well- double-applies it, and against a *light* fog (a golden or overcast horizon) it makes the- backdrop BRIGHTER than the terrain — which renders as pale cardboard and is graded- `placeholder_material`. Give it its natural colour **darkened**- (`base.multiplyScalar(0.6–0.8)`) and let fog do the haze. Verified A/B on one frame- with fog 0xf7cf9e: hand-lerped = beige cut-outs, darkened = receding hazy hills.-5. **Solid geometry, never flat cut-outs.** A distant treeline is cones/boxes with volume;- a `PlaneGeometry` billboard reads as cardboard from every oblique and overview camera,- and its base floats.--```js-function buildHorizonRing(THREE, opts = {}) {- const r = opts.radius ?? (opts.fogFar ? opts.fogFar * 0.6 : 60); // 0.6 x fog far- const n = opts.count ?? 30, h0 = opts.minHeight ?? r * 0.06, h1 = opts.maxHeight ?? r * 0.12;- const base = new THREE.Color(opts.color ?? 0x3d5236), fog = new THREE.Color(opts.fogColor ?? 0xa8c4dd);- const dark = opts.darken ?? 0.72; // scene.fog supplies the haze; we only darken- const shape = opts.shape ?? 'hill'; // 'hill' (cone) | 'block' (city) | 'mesa'- const geo = shape === 'hill' ? new THREE.ConeGeometry(1, 1, 7)- : shape === 'mesa' ? new THREE.CylinderGeometry(0.75, 1, 1, 6)- : new THREE.BoxGeometry(1, 1, 1);- geo.translate(0, 0.5, 0); // origin at the base- // hazeMix stays 0 unless the ring sits past fog.far, where fog can no longer reach it- const mat = new THREE.MeshStandardMaterial({ color: base.clone().multiplyScalar(dark).lerp(fog, opts.hazeMix ?? 0), roughness: 1, flatShading: true });- const mesh = new THREE.InstancedMesh(geo, mat, n);- const m = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0), p = new THREE.Vector3(), s = new THREE.Vector3();- for (let i = 0; i < n; i++) {- const a = (i + 0.35 * gHash(i, 7)) / n * Math.PI * 2;- const rr = r * (0.82 + 0.3 * gHash(i, 11));- const hgt = h0 + (h1 - h0) * gHash(i, 13);- const wid = hgt * (1.1 + 1.6 * gHash(i, 17));- q.setFromAxisAngle(up, gHash(i, 19) * 6.283);- p.set(Math.cos(a) * rr, -1.5, Math.sin(a) * rr); s.set(wid, hgt, wid);- m.compose(p, q, s); mesh.setMatrixAt(i, m);- }- mesh.instanceMatrix.needsUpdate = true; mesh.computeBoundingSphere();- mesh.name = 'HorizonRing'; mesh.castShadow = false; mesh.receiveShadow = false;- return mesh; // add to the SCENE (env), never to a zone-}-const ringDemo = buildHorizonRing(THREE, { shape: 'block', color: 0x2b3140, fogFar: 77 });-console.log('horizon ring', ringDemo.count, 'r', (77 * 0.6).toFixed(1), '#' + ringDemo.material.color.getHexString());-```--Indoor scenes (greenhouse, cabin) need no ring — but the *outside* seen through the glass-must still be something: a haze gradient plus 5–10 silhouette shapes.--## Dusk / night lighting recipe (dark scenes are the #1 gate failure)--"Dusk", "night", "moonlit", "lantern-lit" means COLOURED darkness, never black. The harness-measures every camera's frame; a frame that is too dark is a gate ERROR-(`scene_frames: dark_frame`) capping the score at 0.55. Take the `dusk` / `night`-row of the time-of-day table below for sky, sun, fill and fog, then add **practicals** —-every lantern, window and fire near the camera is an emissive surface plus its own small-PointLight (the emissive glows and blooms but lights nothing; the PointLight lights the-ground around it). The numbers are `PRACTICAL` from `lib/environment.js` —-`emissiveIntensity` 3, a PointLight of 1.5 reaching 9 m, decay 2 — and this is the one-place they are stated:--```js-import { PRACTICAL } from './lib/environment.js';-function addPracticals(THREE, scene, spots) { // none cast shadows- const glowMat = new THREE.MeshStandardMaterial({ color: 0xffc070, emissive: 0xffa040,- emissiveIntensity: PRACTICAL.emissiveIntensity });- return spots.map(([x, y, z], i) => {- const bulb = new THREE.Mesh(new THREE.SphereGeometry(0.15, 12, 8), glowMat);- bulb.position.set(x, y, z); bulb.name = `Practical_${i}`;- const light = new THREE.PointLight(0xffa040, PRACTICAL.intensity, PRACTICAL.distance, PRACTICAL.decay);- light.position.set(x, y, z);- scene.add(bulb, light); return light; // flicker from update(): ×0.75…×1.3- });-}-console.log('practicals', addPracticals(THREE, new THREE.Scene(), [[4, 1.8, 2], [-3, 2.1, 5]]).length);-```--Rules of thumb: the starter's `env.js` lights the scene with ONE `sunRig({...})` from-`lib/environment.js` — key, hemisphere fill, the environment map metals read from, the disc-and fitted shadows — and clamps `intensity` / `fill` UP to per-mood floors (day and golden-sun ≥ 4.5 with fill ≥ 1.0–1.2, overcast 2.0 / 1.6, the night moon 2.2 / 0.8); turning the key-down is NOT how you make dusk, tinting it is (`sunColor`, `fillSky`, `fillGround`, `zenith`,-`horizon`, and a set sun — `elevation` < 0 — is the night rig); ground albedo ≥ 0.25; no-black `scene.background` (the sky gradient's horizon band is the brightest thing in the frame).--**Exposure self-check (after each build):** `scene_views` → the frame table-(`camera_checks` in metrics.json) for every authored camera: read `mean_lum` / `dark_frac` /-`blown_frac` / `content_frac` and any finding it names. If a frame is dark, raise `fill` by-+0.3 and `intensity` by +0.8 in the `sunRig({...})` call and re-render — never a second-DirectionalLight beside the rig (measured 2026-09-07: a blue-hour lighthouse stacked a-"TwilightKey" on the night rig and still read 0.13). Black shade is the most-common cause: at sun elevation < 25° keep `fill` ≥ 1.0.--## Atmosphere: time-of-day triads with numbers--Pick the row, hand its colours to the rig, then only tune exposure. `sun` = the rig's key-(`sunColor`, `elevation`; `intensity` is the mood's floor or higher), `hemi` = the rig's fill-(`fillSky` / `fillGround`; `fill` ≥ the floor). Bare-light intensities measured without the-rig's environment map sit below its floors — the colours, elevations and fog are what a row-gives you. Fog colour is always the sky's **horizon** colour — never white, never grey-unless the brief says overcast.--| time of day | rig mood | sky zenith | sky horizon = fog | sun colour | sun elev | fill sky / ground | fog near/far (100 m scene) |-|---|---|---|---|---|---|---|---|-| dawn | golden | 0x2f4a72 | 0xe8a06a | 0xffb073 | 8° | 0x7d94c4 / 0x4a3a2c | 25 / 150 |-| morning | day | 0x3d76c2 | 0xbcd6ea | 0xfff1d0 | 35° | 0xbfd6f0 / 0x5e5442 | 45 / 190 |-| noon | day | 0x2f6fd0 | 0xcfe2f2 | 0xfffaf0 | 70° | 0xcfe2f2 / 0x6b6152 | 60 / 220 |-| golden hour | golden | 0x3b5f96 | 0xf0a860 | 0xffc27a | 12° | 0x86a8d8 / 0x5c4630 | 35 / 170 |-| overcast | overcast | 0x8e9aa6 | 0xc3cad1 | 0xd8dee4 | 45° | 0xc3cad1 / 0x6f6a62 | 30 / 160 |-| dusk | golden | 0x33285c | 0xd9703a | 0xffa060 | 6° | 0x7a5aa0 / 0x3a2e22 | 30 / 140 |-| night (moon) | night | 0x0d1430 | 0x22305a | 0xa8c0ff | 40° | 0x36406e / 0x1a1c24 | 25 / 120 |--**Colour temperature contrast is the whole trick**: the key light is warm, the fill is the-*opposite* hue (cool blue sky bounce). A scene lit warm-on-warm — orange sun with an-orange hemisphere — comes out as the monochrome-orange soup the rooftop run was marked-down for. Keep `fillSky` at least 60° of hue away from `sunColor`.--```js-import { sunRig } from './lib/environment.js';-const TIME_OF_DAY = {- dawn: { mood: 'golden', zenith: 0x2f4a72, horizon: 0xe8a06a, sun: 0xffb073, elev: 8, fillSky: 0x7d94c4, fillGround: 0x4a3a2c, fog: [25, 150] },- morning: { mood: 'day', zenith: 0x3d76c2, horizon: 0xbcd6ea, sun: 0xfff1d0, elev: 35, fillSky: 0xbfd6f0, fillGround: 0x5e5442, fog: [45, 190] },- noon: { mood: 'day', zenith: 0x2f6fd0, horizon: 0xcfe2f2, sun: 0xfffaf0, elev: 70, fillSky: 0xcfe2f2, fillGround: 0x6b6152, fog: [60, 220] },- goldenHour: { mood: 'golden', zenith: 0x3b5f96, horizon: 0xf0a860, sun: 0xffc27a, elev: 12, fillSky: 0x86a8d8, fillGround: 0x5c4630, fog: [35, 170] },- overcast: { mood: 'overcast', zenith: 0x8e9aa6, horizon: 0xc3cad1, sun: 0xd8dee4, elev: 45, fillSky: 0xc3cad1, fillGround: 0x6f6a62, fog: [30, 160] },- dusk: { mood: 'golden', zenith: 0x33285c, horizon: 0xd9703a, sun: 0xffa060, elev: 6, fillSky: 0x7a5aa0, fillGround: 0x3a2e22, fog: [30, 140] },- night: { mood: 'night', zenith: 0x0d1430, horizon: 0x22305a, sun: 0xa8c0ff, elev: 40, fillSky: 0x36406e, fillGround: 0x1a1c24, fog: [25, 120] },-};--function applyTimeOfDay(THREE, scene, key, opts = {}) {- const T = TIME_OF_DAY[key] || TIME_OF_DAY.morning;- // the table's fog is calibrated for a 100 m scene: scale it by the bounds diagonal or- // a 30 m garden disappears into soup (and its horizon ring never hazes).- const fs = opts.fogScale ?? Math.min(2.5, Math.max(0.3, (opts.boundsDiagonal ?? 100) / 100));- scene.fog = new THREE.Fog(T.horizon, T.fog[0] * fs, T.fog[1] * fs);- scene.background = new THREE.Color(T.horizon);- // ONE rig: key, hemisphere fill, environment map, disc, and shadows whose frustum and map- // are fitted to `bounds` (texel ≤ 0.05 m) — never a second DirectionalLight beside it- const bounds = opts.bounds ?? 60;- const rig = sunRig({ mood: T.mood, azimuth: opts.azimuthDeg ?? 135, elevation: opts.elevationDeg ?? T.elev,- sunColor: T.sun, fillSky: T.fillSky, fillGround: T.fillGround, zenith: T.zenith, horizon: T.horizon,- bounds, fill: opts.fill, intensity: opts.intensity });- scene.add(rig.sun, rig.sun.target, rig.fill);- if (rig.sunDisc) scene.add(rig.sunDisc);- scene.environment = rig.envTex;- return { rig, palette: T, fogFar: scene.fog.far, shadowTexelM: (2 * bounds) / rig.sun.shadow.mapSize.x };-}-const todScene = new THREE.Scene();-const tod = applyTimeOfDay(THREE, todScene, 'goldenHour', { azimuthDeg: 250, bounds: 26, boundsDiagonal: 45 });-console.log('golden hour shadow texel (m)', tod.shadowTexelM.toFixed(3), 'fog far', tod.fogFar.toFixed(1), 'ring radius', (tod.fogFar * 0.6).toFixed(1));-```--**Haze layering / light shafts.** Three or four horizontal haze quads at 1–6 m-(`depthWrite: false`, opacity 0.04–0.10, tinted the fog colour) make distance read even in-a flat scene; light shafts are thin additive cones along the sun, ≤ 0.12 opacity or milk.--```js-function buildHazeBands(THREE, opts = {}) {- const n = opts.count ?? 4, size = opts.size ?? 200, color = opts.color ?? 0xd9c7a8;- const g = new THREE.Group(); g.name = 'HazeBands';- for (let i = 0; i < n; i++) {- const q = new THREE.Mesh(new THREE.PlaneGeometry(size, size).rotateX(-Math.PI / 2),- new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.035 + 0.02 * i, depthWrite: false, fog: false, side: THREE.DoubleSide }));- q.position.y = (opts.base ?? 3.0) + i * (opts.step ?? 1.8); // clear of eye-level cameras- q.renderOrder = 5 + i; g.add(q);- }- return g;-}-function buildLightShaft(THREE, opts = {}) {- const len = opts.length ?? 14, r = opts.radius ?? 1.6;- const cone = new THREE.Mesh(new THREE.CylinderGeometry(r * 0.25, r, len, 12, 1, true),- new THREE.MeshBasicMaterial({ color: opts.color ?? 0xffe6b8, transparent: true, opacity: opts.opacity ?? 0.09,- depthWrite: false, fog: false, side: THREE.DoubleSide, blending: THREE.AdditiveBlending }));- cone.name = 'LightShaft'; cone.renderOrder = 9;- const dir = (opts.dir ?? new THREE.Vector3(-0.4, -1, -0.25)).clone().normalize();- cone.position.copy(opts.at ?? new THREE.Vector3(0, len * 0.5, 0));- cone.quaternion.setFromUnitVectors(new THREE.Vector3(0, -1, 0), dir);- return cone;-}-console.log('haze bands', buildHazeBands(THREE).children.length, 'shaft', buildLightShaft(THREE).name);-```--Camera safety: the harness raycasts from every authored camera and calls geometry right in-front of the lens "camera inside geometry" (an ERROR). Keep haze bands and shafts at least 1 m clear-of every eye-level camera, or — since these cards are not solid surfaces — give them-`mesh.raycast = () => {};` so the probe ignores them. Never do that to real geometry.--## Water plane (use makeWaterMaterial from src/shaders/water.js)--```js-function buildLake(THREE, waterMat, x, z, r, level) {- const lake = new THREE.Mesh(new THREE.CircleGeometry(r, 48).rotateX(-Math.PI / 2), waterMat);- lake.name = 'Lake'; lake.position.set(x, level, z); lake.renderOrder = 2; // after opaque terrain- return lake; // carve the terrain BELOW level around (x, z) in heightAt, or the shore z-fights-}-```--Why: water is a flat plane + the shader; `heightAt` must dip below the water level inside-the shoreline (a radial depression term) or the shore z-fights.--## Vegetation that reads real (species, jitter, clusters, ground cover)--A ring of identical cones is the second most common complaint. Fix it with **three to five-species**, per-instance **scale / hue / rotation jitter**, **clustered** placement and a-**ground-cover** layer — all instanced, so a whole forest is 6–10 draw calls.--```js-// One species = a trunk + a crown with its own silhouette + hue band. A conifer's crown is-// a cone; a broadleaf or scrub crown is LEAVES — `makeCanopy` (lib/canopy.js), never an-// icosahedron or any displaced ball (the catalog's crown rule).-function speciesGeometries(THREE) {- return {- conifer: { trunk: new THREE.CylinderGeometry(0.10, 0.20, 3.0, 6).translate(0, 1.5, 0),- crown: new THREE.ConeGeometry(1.15, 4.4, 8).translate(0, 4.4, 0), hue: 0.32, sat: 0.42, lum: 0.20, h: [0.8, 1.5] },- broadleaf: { trunk: new THREE.CylinderGeometry(0.14, 0.26, 2.4, 7).translate(0, 1.2, 0),- canopy: { y: 3.4, radius: 1.7 }, hue: 0.24, sat: 0.45, lum: 0.28, h: [0.9, 1.6] },- scrub: { trunk: new THREE.CylinderGeometry(0.07, 0.11, 0.7, 5).translate(0, 0.35, 0),- canopy: { y: 1.0, radius: 0.75 }, hue: 0.18, sat: 0.35, lum: 0.30, h: [0.7, 1.3] },- };-}--// Clustered scatter: pick K cluster seeds, then drop members around them (Poisson-ish).-function clusteredPoints(n, area, seed = 5, clusters = 0, spread = 0) {- const K = clusters || Math.max(2, Math.round(n / 7));- const sp = spread || Math.min(area.w, area.d) * 0.13;- const out = [];- for (let i = 0; i < n; i++) {- const k = i % K;- const cx = area.x + (gHash(seed + k, 101) - 0.5) * area.w * 0.9;- const cz = area.z + (gHash(seed + k, 103) - 0.5) * area.d * 0.9;- const a = gHash(seed + i, 107) * 6.283, r = sp * Math.sqrt(gHash(seed + i, 109));- out.push([cx + Math.cos(a) * r, cz + Math.sin(a) * r, k]);- }- return out;-}--function buildForest(THREE, opts = {}) {- const area = opts.area ?? { x: 0, z: 0, w: 70, d: 70 };- const mix = opts.mix ?? { conifer: 34, broadleaf: 22, scrub: 40 };- const heightAtFn = opts.heightAt ?? terrainHeight, seed = opts.seed ?? 5;- const SP = speciesGeometries(THREE), group = new THREE.Group(); group.name = opts.name ?? 'Vegetation';- const bark = new THREE.MeshStandardMaterial({ color: 0x53412c, roughness: 0.95 });- const m = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0);- const p = new THREE.Vector3(), s = new THREE.Vector3(), tint = new THREE.Color();- let si = 0;- for (const [name, count] of Object.entries(mix)) {- const sp = SP[name]; if (!sp || count <= 0) continue;- const trunks = new THREE.InstancedMesh(sp.trunk, bark, count);- const crowns = sp.crown ? new THREE.InstancedMesh(sp.crown, new THREE.MeshStandardMaterial({ roughness: 0.85, flatShading: true }), count) : null;- const leafy = []; // this species' makeCanopy crowns- const pts = clusteredPoints(count, area, seed + si * 37);- pts.forEach(([x, z], i) => {- const k = sp.h[0] + (sp.h[1] - sp.h[0]) * gHash(seed + si * 31 + i, 211); // 1) scale jitter- const lean = (gHash(seed + i, 213) - 0.5) * 0.10; // 2) a few degrees of lean- q.setFromAxisAngle(up, gHash(seed + i, 217) * 6.283); // 3) yaw jitter- const qq = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(1, 0, 0.3).normalize(), lean).multiply(q);- p.set(x, heightAtFn(x, z), z); s.set(k * (0.85 + 0.3 * gHash(i, 219)), k, k * (0.85 + 0.3 * gHash(i, 221)));- m.compose(p, qq, s); trunks.setMatrixAt(i, m);- if (!crowns) { leafy.push({ position: [x, p.y + sp.canopy.y * k, z], radius: sp.canopy.radius * k }); return; }- crowns.setMatrixAt(i, m);- tint.setHSL(sp.hue + (gHash(seed + i, 223) - 0.5) * 0.055, // 4) hue jitter ±0.03- sp.sat + (gHash(seed + i, 227) - 0.5) * 0.18,- sp.lum + (gHash(seed + i, 229) - 0.5) * 0.10); // 5) value jitter- crowns.setColorAt(i, tint);- });- trunks.instanceMatrix.needsUpdate = true; trunks.castShadow = true;- trunks.computeBoundingSphere(); trunks.name = `${name}Trunks`; group.add(trunks);- if (crowns) {- crowns.instanceMatrix.needsUpdate = true;- if (crowns.instanceColor) crowns.instanceColor.needsUpdate = true;- crowns.castShadow = crowns.receiveShadow = true; crowns.computeBoundingSphere();- crowns.name = `${name}Crowns`; group.add(crowns);- } else { // one leaf mesh per species- group.add(makeCanopy({ crowns: leafy, color: new THREE.Color().setHSL(sp.hue, sp.sat, sp.lum), seed: seed + si, name: `${name}Crowns` }));- }- si++;- }- return group;-}-const forestDemo = buildForest(THREE, { area: { x: 0, z: 0, w: 60, d: 60 } });-console.log('forest draw calls', forestDemo.children.length, 'names', forestDemo.children.map(c => c.name).join(','));-```--**Ground cover + litter** turns "objects on a plane" into "plants growing out of the-ground": one InstancedMesh of small tapered blades (no textures needed).--```js-function buildGroundCover(THREE, opts = {}) {- const n = opts.count ?? 900, area = opts.area ?? { x: 0, z: 0, w: 40, d: 40 };- const heightAtFn = opts.heightAt ?? terrainHeight, seed = opts.seed ?? 9;- const blade = new THREE.ConeGeometry(0.09, 0.34, 3).translate(0, 0.17, 0); // 3-sided = 1 tri/face, cheap- const mesh = new THREE.InstancedMesh(blade, new THREE.MeshStandardMaterial({ roughness: 1, flatShading: true }), n);- const m = new THREE.Matrix4(), q = new THREE.Quaternion(), up = new THREE.Vector3(0, 1, 0);- const p = new THREE.Vector3(), s = new THREE.Vector3(), c = new THREE.Color();- const pts = clusteredPoints(n, area, seed, Math.round(n / 25));- pts.forEach(([x, z], i) => {- const k = 0.6 + 1.1 * gHash(seed + i, 307);- q.setFromAxisAngle(up, gHash(seed + i, 311) * 6.283);- p.set(x, heightAtFn(x, z) - 0.02, z); s.set(k, k * (0.7 + 0.8 * gHash(i, 313)), k);- m.compose(p, q, s); mesh.setMatrixAt(i, m);- c.setHSL(0.25 + (gHash(seed + i, 317) - 0.5) * 0.06, 0.40 + 0.2 * gHash(i, 319), 0.22 + 0.14 * gHash(i, 323));- mesh.setColorAt(i, c);- });- mesh.instanceMatrix.needsUpdate = true; if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;- mesh.computeBoundingSphere(); mesh.name = opts.name ?? 'GroundCover';- mesh.castShadow = false; mesh.receiveShadow = true;- return mesh;-}-const coverDemo = buildGroundCover(THREE, { count: 400, area: { x: 0, z: 0, w: 24, d: 24 } });-console.log('ground cover', coverDemo.count, 'tris', coverDemo.count * 3);-```--Density per 100 m² of planted zone: 2–5 trees, 8–20 shrubs, 250–600 tufts, 30–80 litter-pieces. Less and the judge writes *"monotonous / undressed"*.--## Rocks, cliffs and boulders that read organic (never a row of boxes)--Stacked cuboids read as buildings — the desert-canyon run lost 0.2 to exactly that. A rock-is a **noise-displaced polyhedron**; a cliff is a **ridge polyline of rotated, non-uniformly-scaled chunks with jittered strata**, never an axis-aligned wall.--```js-function rockGeometry(THREE, { radius = 1, detail = 1, rough = 0.34, seed = 1 } = {}) {- const g = new THREE.IcosahedronGeometry(radius, detail);- const pos = g.attributes.position;- for (let i = 0; i < pos.count; i++) {- const x = pos.getX(i), y = pos.getY(i), z = pos.getZ(i);- const d = 1 + rough * (gFbm(x * 1.7 + seed * 13, z * 1.7 + y * 1.1) - 0.5) * 2;- pos.setXYZ(i, x * d, y * d * 0.8, z * d); // flatter than tall = looks weathered- }- g.computeVertexNormals(); return g;-}--function buildCliffRidge(THREE, opts = {}) {- // ridge = [[x, z], ...]; chunks straddle it with random yaw/tilt and strata colour bands- const ridge = opts.ridge ?? [[-30, -14], [-12, -10], [2, -6], [18, -9], [30, -16]];- const n = opts.count ?? 26, height = opts.height ?? 9, seed = opts.seed ?? 21;- const heightAtFn = opts.heightAt ?? terrainHeight;- const strata = (opts.strata ?? [0x8c4a2f, 0xa8663c, 0xc08a5a, 0x7a3b26]).map(h => new THREE.Color(h));- const group = new THREE.Group(); group.name = opts.name ?? 'CliffRidge';- const geo = rockGeometry(THREE, { radius: 1, detail: 1, rough: 0.42, seed });- const mesh = new THREE.InstancedMesh(geo, new THREE.MeshStandardMaterial({ roughness: 0.95, flatShading: true }), n);- const m = new THREE.Matrix4(), e = new THREE.Euler(), q = new THREE.Quaternion(), p = new THREE.Vector3(), s = new THREE.Vector3();- for (let i = 0; i < n; i++) {- const u = i / (n - 1) * (ridge.length - 1), k = Math.min(ridge.length - 2, Math.floor(u)), f = u - k;- const bx = ridge[k][0] + (ridge[k + 1][0] - ridge[k][0]) * f;- const bz = ridge[k][1] + (ridge[k + 1][1] - ridge[k][1]) * f;- const layer = i % strata.length; // stack in strata bands- const y0 = heightAtFn(bx, bz);- const lift = height * (0.18 + 0.26 * layer) * (0.75 + 0.5 * gHash(seed + i, 401));- const jx = (gHash(seed + i, 403) - 0.5) * 3.4, jz = (gHash(seed + i, 407) - 0.5) * 3.4;- e.set((gHash(seed + i, 409) - 0.5) * 0.5, gHash(seed + i, 411) * 6.283, (gHash(seed + i, 413) - 0.5) * 0.5);- q.setFromEuler(e);- p.set(bx + jx, y0 + lift * 0.55, bz + jz);- s.set(2.6 + 3.4 * gHash(seed + i, 415), lift * (0.7 + 0.6 * gHash(seed + i, 417)), 2.2 + 3.0 * gHash(seed + i, 419));- m.compose(p, q, s); mesh.setMatrixAt(i, m);- mesh.setColorAt(i, strata[layer].clone().offsetHSL(0, 0, (gHash(seed + i, 421) - 0.5) * 0.08));- }- mesh.instanceMatrix.needsUpdate = true; if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;- mesh.computeBoundingSphere(); mesh.castShadow = mesh.receiveShadow = true; mesh.name = 'CliffChunks';- group.add(mesh); return group;-}-const cliffDemo = buildCliffRidge(THREE);-console.log('cliff chunks', cliffDemo.children[0].count);-```--Rules: chunk yaw random over the full circle (an axis-aligned box gives it away); scale-non-uniform (x ≠ y ≠ z by ≥ 20 %); strata luminance differing by ≥ 0.08; the ridge-polyline bending ≥ 15° at least twice; floor boulders reuse `rockGeometry` at 0.3–1.6 m.--## Set dressing: how many props a place needs--Judges call a scene "sparse", "token" or "undressed" long before they call it wrong.-Counts that read as *lived in*, per zone (a zone is typically 10 × 10 m to 30 × 30 m):--| scene type | hero assets | mid props (0.3–1.5 m) | small props (< 0.3 m) | ground cover / litter |-|---|---|---|---|---|-| garden / park | 3–5 (lantern, bridge, bench) | 12–25 (rocks, planters, pots, stumps, buckets) | 25–60 (pebbles, leaves, tools, cups, twigs) | 300–800 tufts |-| desert / canyon | 2–4 (hero boulder, arch, wreck) | 15–30 boulders in 3 size bands | 30–70 (pebbles, bones, dry brush) | 60–200 scrub clumps |-| rooftop / urban | 3–6 (pergola, planters, lounge) | 15–30 (pots, crates, lamps, chairs, vents, ducts) | 30–80 (cups, books, cushions, cables, bottles) | 100–300 plant tufts |-| interior | 3–6 (bench rows, water feature) | 15–30 (pots, tools, watering cans, crates) | 40–100 (labels, trowels, gloves, jars) | n/a |--Cheap rules: 3 size bands per prop family, one InstancedMesh per band; place props-**against something** (wall base, path edge, under a bench) — props alone in open ground-read as scatter; never a grid or ring (≥ 20 % positional jitter, full yaw jitter).--## Zones (`src/zones/*.js`): Groups with a bbox discipline--```js-// Each zone owns a rectangle of the plan; everything it adds stays inside it and sits on-// heightAt (or on a structure the zone built). Naming: zone Group = plan zone name.-function buildCampfire(THREE, { heightAt }) {- const zone = new THREE.Group(); zone.name = 'Campfire';- const cx = -14, cz = 10, cy = heightAt(-14, 10);- const stoneGeo = new THREE.IcosahedronGeometry(0.22, 0);- const stones = new THREE.InstancedMesh(stoneGeo, new THREE.MeshStandardMaterial({ color: 0x8b8b90, roughness: 0.95 }), 9);- const m = new THREE.Matrix4();- for (let i = 0; i < 9; i++) {- const a = i / 9 * Math.PI * 2;- m.makeTranslation(cx + Math.cos(a) * 0.8, heightAt(cx + Math.cos(a) * 0.8, cz + Math.sin(a) * 0.8) + 0.08, cz + Math.sin(a) * 0.8);- stones.setMatrixAt(i, m);- }- stones.computeBoundingSphere(); zone.add(stones);- const fire = new THREE.PointLight(0xff8033, 8.0, 12, 2); // physical falloff; small radius- fire.position.set(cx, cy + 0.5, cz); zone.add(fire);- zone.userData.update = (t) => { fire.intensity = 7.0 + Math.sin(t * 9.0) * 1.2 + Math.sin(t * 23.0) * 0.6; };- return zone;-}-const campfireDemo = buildCampfire(THREE, { heightAt }); campfireDemo.userData.update(1.0);-```--Rules: shadows come from the sun and the hero lights only; decorative lights get-`castShadow = false` and distance-limited falloff.--Placement is MEASURED (`check_placement`; the `scene_placement` gate runs on every build): each-direct child of your zone group is an asset; from its lowest vertices the harness looks down for the-nearest surface and up for one passing through it. A gap under the foot → `floating`; a foot buried-under a surface → `sunken` (rocks, posts and bushes may sit partly in the ground; stairs, ramps and paths may follow the slope; a basin-or pit never counts; a foot at/under water is fine); bbox touching nothing → `unsupported`; boxes sharing-a large share of their volume → `interpenetration`. Seat things with `heightAt(x, z)` and they pass. A thing MEANT to hang in-the air (bird, drone): `obj.userData.placement = 'free'` on it or its zone = exempt. Instanced meshes are not checked.--Three placement rules the argon loop's iteration 0 paid for (2026-10-15: 7 of 30 zones shipped-interpenetration ERRORs, 5 shipped sunken ones):--1. **One placed thing = one direct child of the zone group.** Never wrap several props in a- `MidProps` / `Dressing` / `SeamDressing` Group: the gate measures that Group as ONE asset whose- box is the union, so every prop inside it reads as interpenetrating it (11 of 29 rows). A prop- built from parts is one Group; hundreds of the same thing are one `InstancedMesh`.-2. **Scatter clear of what you placed.** Keep the boxes of the hand-placed things and skip every- scatter point inside them (+0.3 m); a scattered rock, fern or crate inside a placed table,- rockery or tower is an interpenetration at 100 % of the smaller box:--```js-const placed = []; // push after every hand placement-function keepClear(THREE, obj, margin = 0.3) { placed.push(new THREE.Box3().setFromObject(obj).expandByScalar(margin)); }-const isClear = (x, z) => !placed.some((b) => x >= b.min.x && x <= b.max.x && z >= b.min.z && z <= b.max.z);-// inside a scatter loop: if (!isClear(x, z)) { m.makeScale(0, 0, 0); mesh.setMatrixAt(i, m); continue; }-```--3. **A wide flat thing on a slope** (a talus field, a long conveyor, a bench row) is measured at- its lowest vertices against the ground under THEM: conform each piece to `heightAt` or split it,- or its uphill end is `sunken` by the slope's rise (0.24-0.36 m in iteration 0).--## Assets (`src/assets/*.js`) and GLB assets from Blender--```js-// Procedural asset factory: exactly like a static object part — Y-up, on y = 0, PascalCase.-function buildLantern(THREE, opts = {}) {- const g = new THREE.Group(); g.name = 'Lantern';- const metal = new THREE.MeshStandardMaterial({ color: 0x2c2c30, roughness: 0.5, metalness: 0.8 });- const post = new THREE.Mesh(new THREE.CylinderGeometry(0.03, 0.04, 2.2, 10), metal);- post.position.y = 1.1; g.add(post);- const cage = new THREE.Mesh(new THREE.CylinderGeometry(0.12, 0.14, 0.26, 6), metal);- cage.position.y = 2.2 + 0.13 - 0.004; g.add(cage);- const glow = new THREE.Mesh(new THREE.SphereGeometry(0.08, 12, 8),- new THREE.MeshStandardMaterial({ color: 0xffe6b0, emissive: 0xffc46a, emissiveIntensity: 3.0 }));- glow.position.y = 2.33; g.add(glow);- return g;-}-// GLB asset (built in Blender, compiled to public/assets/<snake>.glb): the assembled scene.js-// preloads it — named, shadowed, its clips kept — into ctx.assets['<snake>']. A zone only clones:-function placeHero(ctx, key, x, z) {- const hero = ctx.assets[key] && ctx.assets[key].clone(); // Y-up meters, base at y = 0, clips play by themselves- if (hero) hero.position.set(x, ctx.heightAt(x, z), z);- return hero; // null when the hero was NOT AVAILABLE — build a procedural stand-in instead-}-console.log('lantern ok', buildLantern(THREE).children.length);-```--Why: a scene mixes cheap instanced fillers with a few hero assets; GLBs come in Y-up meters-(same frame), so a loaded asset is placed exactly like a procedural one.--## Animation: update(t, dt) patterns + particles--```js-// Rigid movers: cache a `home` Vector3 at build time, then set (never accumulate) the-// pose from t — `obj.position.y = home.y + Math.sin(t * 0.9) * 0.06` etc.-// Particles: THREE.Points with a RADIAL alpha sprite (`softDot`) — a bare PointsMaterial-// draws SQUARES, which is the judge's `hard_edged_particles` defect (see "Soft particles").-function softDot(THREE, size = 64) {- const data = new Uint8Array(size * size * 4); // no DOM: a DataTexture, not a canvas- for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {- const r = Math.min(1, Math.hypot((x + 0.5) / size - 0.5, (y + 0.5) / size - 0.5) * 2);- const i = (y * size + x) * 4;- data[i] = data[i + 1] = data[i + 2] = 255; data[i + 3] = Math.round(255 * (1 - r) * (1 - r));- }- const tex = new THREE.DataTexture(data, size, size); tex.needsUpdate = true; return tex;-}-function buildFireflies(THREE, n = 120, area = { x: 0, z: 0, w: 30, d: 30 }) {- const pos = new Float32Array(n * 3);- const rnd = mulberry32(11);- for (let i = 0; i < n; i++) pos.set([area.x + (rnd() - 0.5) * area.w, 0.6 + rnd() * 2.2, area.z + (rnd() - 0.5) * area.d], i * 3);- const geo = new THREE.BufferGeometry(); geo.setAttribute('position', new THREE.BufferAttribute(pos, 3));- const pts = new THREE.Points(geo, new THREE.PointsMaterial({ map: softDot(THREE), color: 0xd9f76e, size: 0.06, sizeAttenuation: true,- transparent: true, opacity: 0.9, depthWrite: false, alphaTest: 0.02, blending: THREE.AdditiveBlending })); // NormalBlending for dust/snow- pts.name = 'Fireflies';- const base = pos.slice();- pts.userData.update = (t) => {- const p = geo.attributes.position.array;- for (let i = 0; i < n; i++) {- p[i * 3] = base[i * 3] + Math.sin(t * 0.7 + i) * 0.4;- p[i * 3 + 1] = base[i * 3 + 1] + Math.sin(t * 1.3 + i * 2.1) * 0.25;- p[i * 3 + 2] = base[i * 3 + 2] + Math.cos(t * 0.5 + i * 0.7) * 0.4;- }- geo.attributes.position.needsUpdate = true;- };- return pts;-}-const ff = buildFireflies(THREE); ff.userData.update(2.0);-console.log('fireflies', ff.geometry.attributes.position.count);-```--Rules: `update` mutates cached objects only — no `new`, no `traverse`, no material-creation per frame. Everything is a function of `t` (deterministic renders at t = 1.5).--## Motion you can SEE between t = 0 and t = 1.5 s--The harness renders every camera at t = 0 and t = 1.5 s and the judge diffs the two-frames. Sub-centimetre sway is invisible at 1024 × 576 and scores as `nothing_moves`-(−0.05 and the whole animation criterion). Amplitudes that actually read:--| what moves | amplitude | period | note |-|---|---|---|---|-| foliage sway | ±0.10–0.20 rad (6–11°) | 1.6–3 s | rotate the crown/branch group, not the trunk base |-| grass / reeds | ±0.15 rad | 1.2–2 s | phase-offset per instance |-| water | wave height ≥ 0.04 m **and** a scrolling normal/uv at ≥ 0.15 m/s | 2–4 s | a still mirror reads as static |-| falling leaves / petals / snow / dust | ≥ 0.6 m of travel in 1.5 s | recycle over 6–12 s | 60–250 particles |-| flags / banners / string lights | ±0.12 rad | 1.2 s | the classic "the scene is alive" cue |-| flame / lantern flicker | intensity ×0.75…×1.3 | 0.1–0.3 s | plus emissiveIntensity on the material |-| vehicles / boats / birds | ≥ 1.5 m of travel in 1.5 s | loop | one hero mover beats ten twitchers |--Give the scene **one unmistakable hero motion** (rotating beam, drifting boat, falling-leaves, spinning wheel, flock) plus the ambient ones — all pure functions of `t`.--```js-function makeSwayGroup(THREE, child, opts = {}) {- // wrap anything in a pivot that sways visibly; pivot at the BASE so it bends, not slides- const pivot = new THREE.Group(); pivot.name = opts.name ?? 'Sway';- pivot.add(child);- const amp = opts.amp ?? 0.14, per = opts.period ?? 2.2, ph = opts.phase ?? 0;- pivot.userData.update = (t) => {- pivot.rotation.z = Math.sin((t / per) * 6.283 + ph) * amp;- pivot.rotation.x = Math.sin((t / (per * 1.37)) * 6.283 + ph * 1.7) * amp * 0.55;- };- return pivot;-}-const swayDemo = makeSwayGroup(THREE, new THREE.Mesh(new THREE.ConeGeometry(0.6, 2, 6), new THREE.MeshStandardMaterial({ color: 0x3f6b2a })));-swayDemo.userData.update(0); const a0 = swayDemo.rotation.z;-swayDemo.userData.update(1.5); const a1 = swayDemo.rotation.z;-console.log('sway delta (rad) over 1.5s', Math.abs(a1 - a0).toFixed(3), (Math.abs(a1 - a0) > 0.05 ? 'VISIBLE' : 'TOO SMALL'));-```--Self-check: after `scene_views(times=[0, 1.5])` compare the two sheets. If you cannot-point at what changed, double the amplitude.--## Soft particles: steam, smoke, dust, motes and sparks (never a hard-edged quad)--The judge's `hard_edged_particles` defect — and the brief's "a soft particle effect … never-hard-edged quads" must-item, which caps the whole score — fired on 5 of 30 argon scenes on-2026-10-15: bare `PointsMaterial` squares for motes, a chain of opaque spheres for a steam jet,-polygon "sparks". The library already does the soft version — prefer it:--| want | call |-|---|---|-| steam from a vent, a cup, a chimney; rising smoke | `makeSmoke({ height, radius, wind, riseSpeed, seed })` · `makeSteam({ height, radius })` (`lib/smoke.js`) — a bounded density field, no edge anywhere |-| dust motes, pollen, drifting sparkle | `makeMotes({ extent, height, count, size, color, seed })` (`lib/veils.js`) — glinting specks with radial falloff |-| snow, distant rain | `makeSnowfall` · `makeRainVeil` (`lib/veils.js`) |-| sparks and embers | `makeFire` / `makeFireField` (`lib/fire.js`, `lib/firefield.js`) — the embers ride the flame |-| a cloud of your own | `THREE.Points` + `PointsMaterial({ map: softDot(THREE), transparent: true, depthWrite: false, alphaTest: 0.02 })` — the `softDot` sprite from the Animation chapter; `AdditiveBlending` for fireflies and sparks, `NormalBlending` for dust and snow |--Rules: every point carries a radial alpha sprite or it is a square; a steam jet is ONE-`makeSteam` / `makeSmoke`, never spheres in a row; sparks are points, never triangles or-hexagons; the cloud MOVES (>= 0.6 m of travel in 1.5 s, see the motion table) or it is a-static decal; keep it to 60-400 points — a fog of them reads as noise.--## Scene layering: foreground, midground, background--A "diorama on an empty plane" scores ~0.5 whatever else you do. Every authored camera needs-**three depth layers**, built on purpose:--| layer | distance from camera | what lives there | how much of the frame |-|---|---|---|---|-| foreground frame | 1.5–5 m | a branch, a post, a parapet edge, a leaning tool, tall grass, an arch | 10–25 % of the frame area, usually at an edge/corner, may be partly cut off |-| midground subject | 8–30 m | the hero assets: what the brief is about | fills the centre third |-| background | 40 m–fog far | silhouette ring, distant treeline / skyline / mesas, sky gradient | the top third |--```js-// Place a framing element just off the camera's axis, at 2-4 m, so it brackets the shot.-function frameForeground(THREE, cam, object, opts = {}) {- const dist = opts.dist ?? 3.0, side = opts.side ?? -1, lift = opts.lift ?? 0;- const eye = new THREE.Vector3().fromArray(cam.position);- const at = new THREE.Vector3().fromArray(cam.lookAt);- const fwd = at.clone().sub(eye).setY(0).normalize();- const right = new THREE.Vector3().crossVectors(fwd, new THREE.Vector3(0, 1, 0)).normalize();- const pos = eye.clone().add(fwd.multiplyScalar(dist)).add(right.multiplyScalar(side * dist * 0.75));- object.position.set(pos.x, (opts.heightAt ?? terrainHeight)(pos.x, pos.z) + lift, pos.z);- object.rotation.y = Math.atan2(eye.x - pos.x, eye.z - pos.z) + (opts.yaw ?? 0);- return object;-}-const camDemo = { name: 'Establishing', position: [24, 9, 26], lookAt: [0, 2, 0], fov: 42 };-const framer = frameForeground(THREE, camDemo, new THREE.Mesh(rockGeometry(THREE, { radius: 1.4, seed: 4 }),- new THREE.MeshStandardMaterial({ color: 0x5b5348, roughness: 1, flatShading: true })), { side: -1 });-console.log('foreground framer at', framer.position.toArray().map(v => +v.toFixed(2)).join(','));-```--**Keep the cameras' first metres clear.** Scatter is blind: it will happily plant a-conifer 1 m in front of the establishing camera and turn the money shot into a wall of-bark (measured — it cost a whole grade before the mask was added). Every scatter loop-skips instances inside a clearance disc around each authored camera, and the establishing-camera sits *above the canopy*: `y ≥ tallest thing in the shot + 0.30 × distance to the-subject`, looking DOWN at the subject.--```js-// Give every zone the authored camera list, then mask the SCATTER with it (deliberate-// foreground props are placed by hand afterwards and are not masked).-function cameraMask(cameras, opts = {}) {- // 2.5-5 m is enough: bigger discs leave bald patches in a small scene- const r = opts.radius ?? 4, discs = cameras.map(c => [c.position[0], c.position[2], r]);- for (const c of cameras) { // also clear 25 % of the way to the subject- const dx = c.lookAt[0] - c.position[0], dz = c.lookAt[2] - c.position[2];- discs.push([c.position[0] + dx * 0.22, c.position[2] + dz * 0.22, r * 0.6]);- }- return (x, z) => discs.some(([cx, cz, rr]) => (x - cx) ** 2 + (z - cz) ** 2 < rr * rr);-}-const maskDemo = cameraMask([{ name: 'Establishing', position: [8, 10.5, 22], lookAt: [0, 1.4, -1], fov: 44 }]);-console.log('camera mask blocks (8,22)?', maskDemo(8, 22), ' blocks (0,0)?', maskDemo(0, 0));-```--Skipped instances are not deleted — write a zero-scale matrix (`m.makeScale(0, 0, 0)`) so-the instance count and every index stay stable.--**Atmospheric perspective** does the rest: with fog matching the sky, a background object-loses contrast and saturation with distance for free — do not hand-tint on top of it (see-the horizon chapter); darken the distant material instead.--## Cameras: measured, never guessed--```js-function planCameras(THREE, scene) {- const box = new THREE.Box3(); // measure CONTENT, not the 240 m sky dome- scene.traverse(o => { if (o.isMesh && o.name !== 'SkyDome') box.expandByObject(o); });- if (box.isEmpty()) box.set(new THREE.Vector3(-20, 0, -20), new THREE.Vector3(20, 10, 20));- const size = box.getSize(new THREE.Vector3()), c = box.getCenter(new THREE.Vector3());- const d = Math.max(size.x, size.z);- return [- // 1) establishing: high 3/4, sees ≥70% of bounds, sun BEHIND the camera shoulder- { name: 'Establishing', position: [c.x + d * 0.55, size.y * 1.1 + 6, c.z + d * 0.6], lookAt: [c.x, 2, c.z], fov: 42 },- // 2) mid: inside the scene at eye height, aimed at a zone's focal point- { name: 'GroveMid', position: [8, heightAt(8, 6) + 1.6, 6], lookAt: [0, heightAt(0, -10) + 2.0, -10], fov: 50 },- // 3) detail: 2-4 m from a hero object, slightly above eye line- { name: 'CampfireDetail', position: [-11, heightAt(-11, 8) + 1.8, 8], lookAt: [-14, heightAt(-14, 10) + 0.6, 10], fov: 45 },- ];-}-console.log('cameras', planCameras(THREE, new THREE.Scene()).map(c => c.name));-```--Rules: eye height 1.6 m (+ terrain!), fov 35–60, look at a focal POINT (an object, not-the horizon), never inside geometry or up against a surface, 3–4 cameras:-establishing → mid → detail. Compute positions from measured bounds/heightAt, not vibes.--## Post-processing (the harness's own chain, ON by default)--The harness renders scene pictures through its own post chain (GTAO + a selective emissive-bloom + a grade that is identity unless `scene.userData.grade` is set), and the scene must-still read without it (emissives at the practical level of the dusk/night recipe, no-white-out). Do not build an-`EffectComposer`: nothing reads one exported from `scene.js`.--## Performance--* Anything placed > 5 × is an InstancedMesh, static one-material clutter is `mergeGeometries`.-* `update` caches lists, mutates in place, allocates nothing per frame.-* `scene_probe` reports draws/tris — run it before polishing. When it is slow the usual- criminals are un-instanced repeats, per-frame `traverse`, and 4096² shadow maps.--## Pitfalls (symptom → cause → fix)--1. **Everything floats / sinks on a slope** → placement ignored `heightAt`; every position- is `(x, heightAt(x, z) + halfHeightOrRootOffset, z)`.-2. **Black frame** → no lights, or fog far < camera distance, or camera inside a hill.- **White frame** → sun + hemisphere both high + fog colour white + bloom.-3. **Scene washed out** → ambient/hemisphere too strong; contrast comes from the sun/shadow- ratio (sun ≈ 4–6 × hemisphere).-4. **Shadows missing** → `castShadow` on the light AND meshes, `receiveShadow` on ground,- shadow camera frustum too small, or light too far (increase `far`).-5. **Shadow acne / peter-panning** → a hand-set bias or map size on the rig's sun; `sunRig`- fits both to `bounds` — pass the content radius and leave them alone.-6. **`Math.random()` anywhere** → different geometry every build; renders not reproducible;- use `mulberry32(seed)` from `lib/noise.js`.-7. **Low fps** → count draw calls first (`scene_probe`); the usual criminals: hundreds of- Meshes that should be instances, per-frame `traverse`, 4096 shadow maps, fog off with a- 500 m far plane.-8. **Fog hides everything** → `Fog(near, far)` in metres — near 45/far 160 for a 100 m- scene; never near 1/far 10.-9. **Sky dome black or fogged** → sky material needs `fog: false`, `side: BackSide`,- `depthWrite: false`, and the tonemap/colorspace includes (see the env recipe).-10. **GLB asset invisible** → the zone never cloned `ctx.assets['<snake>']` (nothing loads a GLB- itself), or its pivot is not at the base; re-export from Blender with the object on z = 0.-11. **Camera inside a tree / wall** → positions are guesses; compute from `heightAt` +- known object positions, then check with `scene_views` (the harness flags- camera-inside-geometry).-12. **update() allocates** (`new Vector3` per frame, `getSize` per frame) → GC hitches;- hoist scratch objects to module scope.-13. **Zones overlap / fight** → each zone stays in its plan rectangle; shared borders- belong to the env (paths, fences).-14. **Lights per lantern** → a real PointLight on every lamp down a long street is slow- and flat; the practicals near the camera path get their own (the dusk/night recipe),- the far ones share ONE emissive material and light nothing.-15. **`nothing_moves` although you animated things** → the hook is named `userData.tick`- (never called), or `tickEnv` (never called), or the amplitude is < 2 cm / < 0.05 rad so- t=0 and t=1.5 look identical. Hook = `userData.update`; amplitudes from- "Motion you can SEE".-16. **A tree 1 m in front of the establishing camera** → the scatter loop had no camera- mask; see `cameraMask` in "Scene layering".-17. **The backdrop reads as pale cardboard** → hand-lerped toward a light fog colour- (double haze → brighter than the ground) and/or built from flat planes. Darken the- base colour, let `scene.fog` haze it, use solid geometry.-18. **Jagged / stair-stepped shadows** → the shadow span is the whole terrain instead of the- content: `sunRig({ bounds })` sizes the map to the span it is given, so give it the- content radius, not the ground size.-19. **Monochrome orange (or blue) frame** → key and fill share a hue. The fill- (HemisphereLight sky colour) must be ≥ 60° of hue away from the sun colour.-20. **The scene is a diorama on a plane** → no foreground layer and no background layer.- Three depth layers per authored camera, always ("Scene layering").-21. **A pond / terrace / lawn is a hard-edged disc or square lying ON the ground** → carve- it into `heightAt` (a radial depression for water, a shallow shelf for a terrace) and- ring the seam with a kerb + dressing; a plane laid on top always shows its outline.-22. **`camera is N m below ground level`** → the plan's camera heights are absolute- (metres above y = 0) but the terrain lifted the floor. Keep `heightAt` within about- ±1.5 m of 0 inside the bounds, or add `heightAt(x, z)` to the camera's y in scene.js.--## Self-check (before you call it done)--```js-function sceneSelfcheck(THREE, scene, cameras) {- let tris = 0, draws = 0, lights = 0, shadowLights = 0;- scene.traverse(o => {- if (o.isLight) { lights++; if (o.castShadow) shadowLights++; }- if (o.isMesh || o.isPoints) {- draws++;- const g = o.geometry, n = g.index ? g.index.count / 3 : g.attributes.position.count / 3;- tris += n * (o.isInstancedMesh ? o.count : 1);- }- });- if (!scene.fog) throw new Error('scene.fog not set');- if (!cameras || cameras.length < 3) throw new Error('need 3-4 cameras');- console.log(`[selfcheck] draws=${draws} tris=${Math.round(tris)} lights=${lights} shadowLights=${shadowLights} cameras=${cameras.length}`);-}-const demoScene = new THREE.Scene(); buildEnv({ THREE, scene: demoScene });-demoScene.add(forestDemo, coverDemo, campfireDemo, ff);-sceneSelfcheck(THREE, demoScene, planCameras(THREE, demoScene));-```--Composition self-check on every authored frame (the judge grades exactly these):--* three depth layers — something inside 5 m, the subject at 8–30 m, a silhouette/sky band above;-* no hard world edge anywhere against the sky;-* the ground shows ≥ 3 blended colours and at least one path / worn area;-* vegetation shows ≥ 3 silhouettes and visible hue/scale variation, in clusters not a ring;-* ≥ 12 mid props and ≥ 25 small props per dressed zone, placed against things;-* shade is coloured (sky-tinted), not black; key and fill hues differ;-* t=0 and t=1.5 are visibly different.--Then: `build` → `check_placement` (floating/sunken/interpenetration + the fix per asset) → `scene_probe` (draws/tris/console) → `scene_views` (authored cameras +-overview rig, with `camera_checks`) → `shader_probe` if you wrote GLSL → fix the worst →-repeat. Look at every camera's frame AND its numbers: no black frames, no white-out, the-subject (not sky/ground) fills the establishing shot, `camera_in_geometry` false, and `check_placement`-clean (nothing floating, sunken or interpenetrating).diff --git a/harness/codeverse3d/prompts/scene_threejs/effects_catalog.md b/harness/codeverse3d/prompts/scene_threejs/effects_catalog.mdindex 91de7100..856db474 100644--- a/harness/codeverse3d/prompts/scene_threejs/effects_catalog.md+++ b/harness/codeverse3d/prompts/scene_threejs/effects_catalog.md@@ -1,4 +1,4 @@-# The shipped effect library — call these before writing your own+# The shipped effect library — an optional toolbox`src/lib/` is in your workspace already: the shipped modules are compiledand rendered on THIS renderer. They carry the depth and fog chunks a@@ -6,9 +6,9 @@ hand-written shader silently loses, and they are not an outside package — theyare harness code shipped into the workspace, so importing them is allowed where"never import a helper SDK" still forbids everything else.-Reach for one FIRST. Write your own only for something no entry here covers,-and then build it with `makeShaderMaterial` / `patchStandard` from-`lib/shader.js`.+Each entry lists what it does and its API. Use one when it fits the brief, or write+your own; `makeShaderMaterial` / `patchStandard` from `lib/shader.js` keep Three's fog+and depth chunks in a shader of your own if you want them.Import with a relative path from the file you are writing — `src/zones/x.js`and `src/assets/x.js` say `import { makeGrass } from '../lib/grass.js';`,@@ -19,7 +19,7 @@ and `src/assets/x.js` say `import { makeGrass } from '../lib/grass.js';`,| a small flame or wax candle | `makeFire({ radius, height, seed, quality: 'high' })` · `makeCandle({ radius, height, seed, lit: true })` — `lib/fire.js`; volumetric flame, moving illumination, wick and wax. Returns a Group with `userData.update(t, dt)`; use metres (candle radius about 0.025, height 0.15). Fire is transparent: avoid intersecting glass volumes. || a campfire, large fuel bed or flames through a building | `makeFireField({ emitters: [{ position: [0,0,0], radius: 0.3, height: 1, strength: 1 }], wind: [0.15,0], smoke: {height: 3, density: 0.65}, occluders: [fuel, walls], quality: 'balanced', seed })` — `lib/firefield.js`; all sources share one flame/soot integration. Wind is local metres/second. Optional borrowed opaque occluders truncate rays, including instancing/alpha cuts; custom deformation needs customDepthMaterial. No glass interleaving, skinned occluders or log-depth capture. Layout/wind are baked: rebuild to change them. Group provides update/dispose, bounds, sampleField(x,y,z,t), sampleEmber(index,t) and cost. Start with one field: each field adds a ray march over 3D textures, plus a depth pass when occluders are given. || rising smoke, steam from a cup or vent | `makeSmoke({ height: 3, radius: 0.14, wind: [0.06, 0], riseSpeed: 0.7, seed, quality: 'balanced' })` · `makeSteam({ height: 0.5, radius: 0.03 })` — `lib/smoke.js`; bounded 3D density with upward advection, widening, dilution and internal light attenuation. Mesh origin is the emitter at local y=0. `userData.update(t)`, `userData.sampleDensity(x,y,z,t)` and `userData.dispose()`. Directional/point/ambient scene lights illuminate it. Keep opaque geometry outside its `userData.bounds`; intersections and overlapping transparent volumes are not depth-resolved. |-| the OCEAN, a lake or any sizeable water body | `makeOceanSurface({ width, depth, waveHeight, wavelength, windDirection: [1, 0.2], seed })` — `lib/ocean.js`, the ocean: dispersive Gerstner waves on real displaced geometry, reflected scene, crest foam; Group with `userData.update(t, dt)` and `userData.sampleHeight(x, z, t)`. Its flat option, for calm or distant water where no wave shape reads (a pond, a far lake): `makeOcean(w, d, { sunDir })` — `lib/water.js`, a normal-mapped mirror plane. ONE reflective water body per scene. |+| the OCEAN, a lake or any sizeable water body | `makeOceanSurface({ width, depth, waveHeight, wavelength, windDirection: [1, 0.2], seed })` — `lib/ocean.js`, the ocean: dispersive Gerstner waves on real displaced geometry, reflected scene, crest foam; Group with `userData.update(t, dt)` and `userData.sampleHeight(x, z, t)`. Its flat option, for calm or distant water where no wave shape reads (a pond, a far lake): `makeOcean(w, d, { sunDir })` — `lib/water.js`, a normal-mapped mirror plane. Each planar reflector re-renders the scene once per frame: keep the total inside the fps / draw budget `scene_probe` reports (one is the safe default). || a curved shallow STREAM | `makeStream({ points: [[0, 0.6, -8], [2, 0.3, 0], [0, 0, 8]], width: 2, depth: 0.3, speed: 1, seed })` — `lib/stream.js`; points run upstream → downstream, decreasing Y. Refracts the opaque bed/scene through depth-varying water; flowing ripples, stone wakes and approximate caustics. `waterColor: 0x80b6a6, attenuationDistance: 3` controls volume absorption over a distance in metres. Optional `reflectionSize: 512` captures the banks; default 0, and at most ONE planar reflector per scene. Group with `userData.update(t, dt)`, `userData.sample(u, lateral, t)`. Keep terrain BELOW the bed inside the channel. || a falling sheet of water over a weir | `makeWaterfall({ width: 2, height: 3, speed: 1, thickness: 0.045, foam: 0.65, seed })` — `lib/waterfall.js`; gravity accelerates and thins the sheet, with advected ripples, local aeration and impact spray. Origin is impact water level, lip is `[0,height,0]`, flow is +Z. Supply the upstream water, cliff and pool. `userData.sample(u,lateral,t)` uses u=0..1 and lateral=-0.5..0.5; `userData.impact` gives the receiving point. No collision/fluid solver; opaque-scene refraction only. || thick broken ice with actual open fissures | `makeFracturedIce({ size: [8,6], thickness: 0.28, crackDensity: 0.65, frost: 0.35, seed })` — `lib/ice.js`; closed floes, bevels, internal air and local optical thickness. Nominal top is y=0. `userData.sampleHeight(x,z)` returns local top height or null in a gap. Supply an opaque lakebed/water backing: transparent volumes are not recursively refracted. |@@ -28,7 +28,7 @@ and `src/assets/x.js` say `import { makeGrass } from '../lib/grass.js';`,| close-view grass with folded blades and flowing wind | `makeMeadow({ size: [8, 8], height: 0.3, density: 900, heightAt, mask, seed, wind: { dir: [1, 0.3], strength: 1.2, speed: 1 } })` — `lib/meadow.js`; every effect's wind option (wind; the veils' direction and drift; the ocean's and sand's windDirection) is read by ONE reader, `readWind` in `lib/shader.js` — a number, `[x, z]`, a vector or this object — so one wind object moves meadow, grass, trees, fire, smoke and rain alike; mask(x,z) is 0..1 coverage; Group with `userData.update(t, dt)`. Set `ground: false` over an existing terrain. Fit the sun shadow frustum tightly; blades need millimetre-scale shadow texels. || a grassy surface | `makeGrass({ extent, density, height, heightAt, patchy })` — `lib/grass.js` || a complete near/middle-distance tree or shrub | `makeTree({ species: 'oak', height: 6, crownRadius: 2.5, leafDensity: 1, seed, wind: { dir: [1,0.3], strength: 0.5, speed: 1 } })` · `makeShrub` — `lib/tree.js`; oak/birch/willow, connected branches, individual leaves and matching moving shadows. Root at y=0, actual envelope in `userData.bounds`. A default tree is heavy geometry. `leafSegments: 4` reduces per-leaf geometry while preserving crown density; species defaults are 10–16 for close views. Also lower `opts.maxLeaves`/`opts.leafDensity`, or use distant imposters when leaves are unresolved. |-| A CROWN OF LEAVES — every broadleaf tree, hedge and bush | `makeCanopy({ crowns: [{position, radius, height}] — or [{position, size:[x,y,z]}] for a mass that is not a ball, which is how a HEDGE is built — color, hue, wind })` — `lib/canopy.js`. NEVER a displaced sphere: see the rule at the end. |+| a crown of leaves for a broadleaf tree, a hedge or a bush | `makeCanopy({ crowns: [{position, radius, height}] — or [{position, size:[x,y,z]}] for a mass that is not a ball, which is how a hedge is built — color, hue, wind })` — `lib/canopy.js`; thousands of leaf cards as one draw call. Foliage is judged on whether it reads as leaves (silhouette break-up, light through it, hue spread): this is one construction that does — see the measurement at the end. || trees, bushes, leaves | `patchLeafSSS` · `patchWind` · `patchRootContact` — `lib/foliage_shade.js` || bark, and a forest at distance | `patchBark` · `makeImposters` — `lib/woodland.js` || light through a canopy | `patchDappledLight` · `patchCanopyShade` — `lib/dapple.js`; goes on the surface being LIT, not on the tree |@@ -42,13 +42,13 @@ and `src/assets/x.js` say `import { makeGrass } from '../lib/grass.js';`,| moss, damp near water, dried mud | `patchMoss` · `patchMoisture` · `patchCrackedMud` — `lib/damp.js` || a polished or wet floor | `makeMirrorFloor(w, d)` — `lib/wetground.js`; re-renders the scene like the water bodies — use one or the other || rock, cliff, ground | `patchTriplanar` · `patchSlopeSplat` — `lib/terrain_shade.js` |-| ground and cliff geometry | `ground({ size, rand: mulberry32(seed), relief, flat })` returns `{ mesh, height }` — seat every asset at height(x, z); with no seeded rand the ground is flat · `cliff({ length, height, rand })` — `lib/terrain.js` |+| ground and cliff geometry | `ground({ size, rand: mulberry32(seed), relief, flat })` returns `{ mesh, height }` — one terrain option (a displaced plane with a seeded heightfield and an optional flat mask; with no seeded rand it is flat); whatever the env's heightAt(x, z) returns must be its real height · `cliff({ length, height, rand })` — `lib/terrain.js`. The brief decides the landform; a floor, terraces or a canyon are not this call. || placing a camera or a prop by intent | `seat` · `establishingShot` · `faceToward` · `alongPath` · `crowdOn` — `lib/place.js` || a cliff that reads as rock | `patchRockStrata` · `patchErosionStreaks` — `lib/strata.js`; bedding by world altitude, so every cliff in a scene shares one bedding plane |-| the land between the content and the horizon | `makeOutskirts({ inner, baseY, heightAt, shellRadius, colors, seed })` — `lib/environment.js`; seam-matched relief, field patchwork and wooded clusters. A bare oversized ground plane measured as "a diorama on a vast, empty flat plane" |+| countryside continuing beyond the content | `makeOutskirts({ inner, baseY, heightAt, shellRadius, colors, seed })` — `lib/environment.js`; seam-matched relief, field patchwork and wooded clusters — one option for a rural setting. The requirement is that no camera sees the ground end against the sky (`world_edge_visible`) or a diorama on an empty plane (judged); how the world continues — a street that keeps going, a sea, a canyon wall, a city, fog that closes — is the brief's. || a Blender hero's own keyframed motion (the GLB carries a clip) | nothing to call — the assembled scene plays every clone's clips; `clone.userData.clipOffset = 0.7` de-phases a copy || the sun, the fill and the baked environment | `sunRig({ azimuth, elevation })` — `lib/environment.js`; returns `{ sun, fill, sunDisc, envTex, sunDir }`. Add the lights, assign `scene.environment = rig.envTex` |-| an interior's walls, ceiling and window/door openings | `roomShell({ center, extents, openings, thickness, wallColor, ceilingColor, glazed, frameColor, bay })` — `lib/environment.js`; walls outward of the bounds' faces (inner face = bounds face), openings cut as span / sill / lintel panels; glazed: true makes every wall and the roof glass on an iron frame grid (a conservatory, greenhouse, glass atrium). The skeleton's env.js builds it from its INTERIOR constant for an interior plan; six runs measured "not enclosed, a diorama on a flat plane" without one |+| a rectangular interior's walls, ceiling and window/door openings | `roomShell({ center, extents, openings, thickness, wallColor, ceilingColor, glazed, frameColor, bay })` — `lib/environment.js`; walls sit outward of the box you pass (inner face = that box's face, which need not be the plan bounds), openings cut as span / sill / lintel panels; glazed: true makes every wall and the roof glass on an iron frame grid (a conservatory, greenhouse, glass atrium). One option for a box-shaped room; the requirement for any interior is that it reads as enclosed from every camera (six runs measured "not enclosed, a diorama on a flat plane" with no walls or roof) || the sky itself | `makeSky(scene, { rig })` — `lib/sky.js`; the dome IS the backdrop, so `scene.background` stays null || cloud, cirrus | `makeClouds({ preset, sunDir, quality: 'balanced' })` · `makeCirrus()` — one ray-marched cloud deck with scene-lit self-shadowing; `lib/clouds.js` || volumetric cumulus with internal sunlight attenuation | `makeCloudVolume({ size: [600,180,360], coverage: 0.55, density: 0.028, wind: [2.5,0.4], seed, quality: 'balanced' })` — `lib/cloudvolume.js`; Mesh centred on its local origin. Move it to cloud altitude. Wind advects density/erosion inside a bounded billow scaffold; translate the Mesh to move the whole cloud. `userData.sampleDensity(x,y,z,t)` mirrors the GPU field. Use one bounded sky volume and inspect its screen cost. No terrain shadows or opaque-depth intersections. |@@ -150,23 +150,22 @@ round has to read.* Grading is per scene: set `scene.userData.grade = { exposure, contrast,saturation, warmth, tint, … }`. Leave it unset for identity.* Tone mapping is ACES at exposure **1.0** and output is sRGB. Non-emissive- albedos belong in **0.02–0.8** linear; a pure black or a pure white albedo is- always wrong.+ albedos belong in **0.02–0.8** linear: a pure black albedo renders as void and a+ pure white one blows out (the `dark_frame` / `blown` gates read both).* `logarithmicDepthBuffer` is OFF by default, so the library's log-depth chunkscompile to nothing here. They cost nothing and `--log-depth` is a hostoption, so leave them alone.* Everything reads `scene.environment` and the sun direction. Do not hardcode alight colour inside an effect; pass `sunDir` / the rig.-## A crown is leaves, not a lumpy ball--The single most common way a scene reads as plastic is a tree whose foliage is-displaced Icosahedra. It is not for want of effort — a measured avenue stacked-32 of them per tree with four octaves of noise and still shipped what the-renderer flagged as "a single flat untextured material, an unreadable slab". A-closed surface has no silhouette to read, lets no light through, and carries ONE-hue however carefully that hue is picked. `makeCanopy` places a few thousand-separate leaf cards as one draw call instead: on the same tree the hue spread-across the crown went from 3.6° to 9.4° and the 5–95 range from 10 to 22 — a-photograph carries 25–45. Use it for every broadleaf crown, hedge and bush near-enough for a camera to resolve; `makeImposters` still owns the far treeline.+## What a crown that reads as leaves measures++A closed displaced surface (an icosahedron with noise, however many octaves) has no+silhouette to read, lets no light through, and carries ONE hue: a measured avenue+stacked 32 of them per tree and shipped what the renderer flagged as "a single flat+untextured material, an unreadable slab" (judged `asset_quality_detail`). Measured on+the same tree: hue spread across the crown went from 3.6° to 9.4° and the 5–95 range+from 10 to 22 when the crown became separate leaf cards — a photograph carries 25–45.+Any construction that gets there is fine; `makeCanopy` (near crowns, hedges, bushes)+and `makeImposters` (a far treeline) are two shipped options, and a stylised brief+(low-poly, paper-craft) may legitimately want something else.diff --git a/harness/codeverse3d/prompts/scene_threejs/system.md b/harness/codeverse3d/prompts/scene_threejs/system.mdindex 5a0b6d58..01ed94ab 100644--- a/harness/codeverse3d/prompts/scene_threejs/system.md+++ b/harness/codeverse3d/prompts/scene_threejs/system.md@@ -10,76 +10,70 @@ ShaderMaterial/RawShaderMaterial before returning. These are ordinary source filnot JavaScript imports; no bundler `?raw` syntax or remote requests. Keep synchronousasset builders free of loading, and never fetch/recompile during `update`.-This track scores lower than any other in the harness (baseline mean **0.297** over 32-recorded runs) and the reason is not modelling. It is that **the picture is black**.-{% if tools %}The loop that decides whether your work ships:- write → `build` → `scene_views` → read `camera_checks.mean_lum` →- fix the exposure → `check_placement` → fix what floats or sinks →- repeat → LOOK at the sheet → only then finish.+ write → `build` → `check_placement` → `scene_views` → read the placement rows and the+ frame table → fix what they name → repeat → LOOK at the sheet → only then finish.-`scene_views` hands you the exposure numbers directly. There is no reason to guess whether-a night scene reads — read `mean_lum` and `lum_std`. `shader_probe` compiles a-ShaderMaterial before it silently renders black.+`scene_views` prints every authored camera's `mean_lum` / `lum_std` / `dark_frac` /+`blown_frac` / `content_frac` and its measured motion; `check_placement` prints every+floating / sunken / interpenetrating row with the metres to move it; `shader_probe` compiles+a ShaderMaterial before it silently renders black. There is no reason to guess whether a+frame reads — read the numbers.{% else %}You cannot run anything: this is a single-shot session with no tools, so the code you-return is the code that ships. Budget your care accordingly — the failure below is a-lighting failure, and it happens in the dark where you cannot see it.+return is the code that ships. Everything below is measured on it blind.{% endif %}-What the gates name, measured over 32 recorded runs of this exact track:--* **The frame is too dark** — 153 findings, more than every other defect on this track- combined. The gate fails a view that is too dark on average or mostly near-black. A- dusk or night brief is orange, purple or deep blue — it is *not* black. Give the sky,- the fog and the ground a colour that is actually a colour.-* **But dim-and-lit is not the same as unlit, and the fix is opposite.** If the frame has- real contrast it is low-key by design and adding `AmbientLight` or- `HemisphereLight` will destroy it — measured: a night temple was given flat fill, the- granite washed to near-white, the scene flattened to "snow at dawn" and a working water- shader drowned. Lift a dim scene **where its light comes from**: the lamps' own- emissive plus a small `PointLight` at each practical (the cookbook's dusk/night recipe),- and give dark materials a low but non-zero base colour so they read as- material rather than as void. Let the shadows stay dark.-* **Flat frame** — one luminance band holding almost all of the pixels. Fill light with no key- produces this. So does fog whose colour does not match the sky.-* **The camera is in the wrong place** (42 findings) — below the highest ground surface,- or inside geometry. Keep the eye **above the ground** and **clear of every surface**, and keep- `lookAt` on the content.-* **Draw calls** — instance repeated geometry (`InstancedMesh`);- a thousand individual trees is a frame-rate failure, not a detailed forest.+What is measured on every authored camera (the `scene_frames` gate, ERROR on failure):-Rules that survive every brief:+* **Exposure.** A frame whose mean luminance is below 0.12, or with more than 35 % of its+ pixels near black, fails as `dark_frame` — unless its luminance std is ≥ 0.12 with no more+ than 35 % near-black pixels, in which case it is low-key but LIT and passes. More than 20 %+ blown pixels fails as `blown_frame`; more than 85 % of the pixels in one luminance band is+ `flat_frame` (ERROR above 92 %). A dusk or night brief passes as a coloured low-key frame with contrast;+ flat fill (`AmbientLight`, a hemisphere with no key) is what turns a lit night into a grey+ wash — measured: a night temple given flat fill washed its granite to near-white, flattened+ to "snow at dawn" and drowned a working water shader. Where a dim frame needs more light,+ add it where the brief's light comes from (the sources the setting contains — emissive plus+ a local light; a low moon; a lit window's spill), and give dark materials a low but non-zero+ base colour so they read as material rather than void. Shadows may stay dark.+* **Camera placement.** The eye must be ≥ 0.3 m above the ground under it (`camera_low`; above+ 80 m is `camera_high`), ≥ 0.5 m from every surface and not inside geometry+ (`camera_in_geometry`, cap 0.50), with no more than 5 of its 9 sight rays ending within 1.5 m+ (`camera_blocked`, cap 0.50 — a camera 1 m behind a crate passes the 0.5 m rule and still+ fails this one) and the line of sight to `lookAt` not cut in its first half. An authored frame+ must be ≥ 10 % content; the first camera is measured as the establishing view and must be+ ≥ 20 % content (mostly sky or ground fails it as `content_small`).+* **Motion.** Every camera is rendered at t = 0 and t = 1.5 s and the two frames are+ differenced; 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); the judge's+ `nothing_moves` follows it.+* **Budget.** `scene_probe` reports draw calls and triangles (WARN above 5 000 draws, ERROR+ above 15 000; 3 000 000 unique triangles). Instancing (`InstancedMesh`, `mergeStatic`) is+ how repeated geometry usually stays inside it.-* **The brief's time of day is a hard constraint, not a mood suggestion.** Decide it- once, write it down as a constant (`const MOOD = 'night'`, a sun azimuth, a sky colour,- a fog colour) and make every zone read it. Measured 2026-08-30 on this exact battery:- a "cozy izakaya at NIGHT" rendered under a plain blue daytime sky over flat green- ground — the lanterns and the chef were built well and the scene still lost, because a- night brief rendered as noon is the wrong scene no matter what is in it. The frame- gate cannot save you here: it only measures too-dark and too-bright, and a sunny day is- neither. A night that reads as night is dim but coloured, clearly darker than day.-* **The environment IS the scene, not its backdrop.** Sky, ground material, fog and the- key light carry more of the verdict than any single prop. Build them FIRST and make- them specific to the brief (snow, wet cobbles, desert haze); a default blue sky over- default green ground reads as "unfinished" however good the props on top are.-* **Light before colour, and light before detail.** Get the frame into a readable band- first. Hue, material and geometry work are all invisible on near-black pixels, and every- hour you spend on them before the exposure is right is an hour the judge cannot see.- The starter's `env.js` already builds the light that reads: `sunRig({ mood, azimuth,- elevation, … })` from `lib/environment.js` — sun, hemisphere fill, the environment map- metals read from, the disc, and per-mood floors it clamps UP to. Pick the mood, tint- through `sunColor` / `fillSky` / `fillGround`, raise `intensity` / `fill`; never a second- DirectionalLight on top of it. `scene.fog` is the sky's horizon colour.-* **Author a camera.** The harness's orbit rig is a fallback, not your picture; a scene- judged only on the rig is a scene you did not frame.-* **Things rest on things.** `check_placement` measures the gap from each asset's feet to- what is under them. Compute where the ground is at that x/z and put the object there —- do not place at `y = 0` and hope the terrain is flat.-* **Split the scene across modules** as the contract says, and keep every import relative- and real. A module that throws takes the whole frame black.+Requirements that hold for every brief:-A simple scene that is legibly lit beats an elaborate one rendered in the dark. Get-the exposure right first; spend everything after that on the brief.+* **The brief's time of day and weather are hard constraints.** The judge compares every frame+ against them: a "cozy izakaya at NIGHT" rendered under a noon sky over flat green ground lost+ (measured 2026-08-30) with its lanterns and chef built well, because the wrong scene scores+ as the wrong scene. The frame gate only measures too-dark and too-bright, so a sunny day+ passes it. How the time of day is encoded is yours; every module must agree with it.+* **The environment the brief describes is judged as heavily as the props** — its sky or+ ceiling, its surface, its atmosphere, its light (judge `brief_fidelity`, `lighting_atmosphere`,+ `flat_ground`, `diorama_look`). Make it specific to the brief (snow, wet cobbles, desert haze,+ a vaulted roof); a default blue sky over default green ground is graded as unfinished whatever+ stands on it. The order you build in is yours.+* **Exposure is gated before anything is judged.** A frame that fails the gate scores nothing+ for what is in it: hue, material and geometry work are invisible until the frame reads.+* **Author the cameras the plan lists.** The harness's orbit rig is a fallback, not your+ picture; a scene judged only on the rig is a scene you did not frame.+* **Things rest on things.** `check_placement` measures the gap from each placed object's+ lowest vertices to the surface under them (floating above 0.05 m outdoors / 0.02 m indoors,+ ERROR at 0.08 m; sunken below 0.10 m, ERROR at 0.20 m). Compute where the surface is at that+ x/z and put the object there — never at `y = 0` on the assumption that the ground is flat.+* **Split the scene across modules** as the contract says, and keep every import relative and+ real. A module that throws takes the whole frame black; a zone that throws is dropped and+ scores nothing.diff --git a/harness/codeverse3d/prompts/system/role_asset.j2 b/harness/codeverse3d/prompts/system/role_asset.j2index d48ecefc..1233fe29 100644--- a/harness/codeverse3d/prompts/system/role_asset.j2+++ b/harness/codeverse3d/prompts/system/role_asset.j2@@ -1,7 +1,7 @@For this task the object you are building is a PROP for a larger scene, not a standalonedeliverable. What changes:-* The asset sheet in the task below is the contract — its name, size (±5%) and description+* The asset sheet in the task below is the contract — its name, size (measured) and descriptionoutrank any instinct about what the "complete" object would have. The scene only sees itat scene distance; spend detail on silhouette and the 2-3 features a person would name,not on close-up hardware.diff --git a/harness/codeverse3d/prompts/tracks/plan_scene.j2 b/harness/codeverse3d/prompts/tracks/plan_scene.j2index 9d7397e3..ddd58330 100644--- a/harness/codeverse3d/prompts/tracks/plan_scene.j2+++ b/harness/codeverse3d/prompts/tracks/plan_scene.j2@@ -1,164 +1,180 @@You are the SCENE DIRECTOR for a real-time three.js scene that several code-writing models willbuild in parallel from your plan alone (one per asset, one per zone, one for the environment).-Write the plan as exact numbers and concrete nouns; keep it lean (cost matters).+Write the plan as exact numbers and concrete nouns; keep it lean (cost matters). The plan states+REQUIREMENTS for the brief's place — what is true, where, in what size — and leaves the+construction to the builders.{{ frame_doc }}-The scene uses the same frame: Y up, meters; the ground is around y=0 unless you say otherwise.+The scene uses the same frame: Y up, meters; say where the ground is (it is around y=0 unless+the plan puts it elsewhere).LANGUAGE CONTRACT THE BUILDERS WILL FOLLOW:{{ contract }}-SHIPPED NATURAL EFFECTS:+SHIPPED LIBRARY (optional toolbox):The scene workspace already contains, under `src/lib/`: `fire.js` (`makeFire`, `makeCandle`),`firefield.js` (`makeFireField`), `smoke.js` (`makeSmoke`, `makeSteam`), `cloudvolume.js`(`makeCloudVolume`), `ocean.js` (`makeOceanSurface`), `stream.js` (`makeStream`),`waterfall.js` (`makeWaterfall`), `ice.js` (`makeFracturedIce`), `sand.js` (`makeSandTerrain`),`rock.js` (`makeRock`, `makeRockField`: sandstone / granite / basalt rocks and talus),-`tree.js` (`makeTree`: oak / birch / willow, for a few near or hero trees; `makeShrub`), `meadow.js` (`makeMeadow`) and-`paving.js` (`makePaving`). When they cover the brief, describe their calls and dimensions in-the owning zone description / environment / effects. Do not request an asset that rebuilds-one of them (a Waterfall, OakTree, BoulderCluster, StreamRibbon, Flame or GrassPatch asset);-an element they do not cover (a pine, a palm, a carved stone) is still an asset, and so is a-grove or forest of many trees: each `makeTree` is a full tree, heavy enough that a whole grove of-them can crash the page.-A `threejs` asset may compose a factory with its own parts (a shrine with a `makeTree` beside it,-a well ringed by `makeRock`s): name the call and its module (`makeTree`, `tree.js`) in that-asset's description, and the asset imports `../lib/`. A `blender_glb` hero cannot. Zone-`contents` still lists only actual asset names; library effects a zone places itself belong in-prose, not invented asset ids.-Plan the stream's upstream-to-downstream path once, with nonincreasing Y, and-require terrain banks to use that same surface sampler and local coordinate frame.-The zone drives each effect's `userData.update(t, dt)` exactly once per frame.+`tree.js` (`makeTree`: oak / birch / willow; `makeShrub`), `meadow.js` (`makeMeadow`) and+`paving.js` (`makePaving`). Use a call when its output fits the brief: name it, its module and+its dimensions in the owning zone description / environment / effects. An element the library+does not grow in the form the brief wants (a pine, a palm, a carved stone, a different kind of+boat) is an asset built from scratch within the triangle budget below; so is a grove or forest,+because each `makeTree` is a full tree and the build census counts every triangle.+Interface: a `threejs` asset may compose a factory with its own parts (a shrine with a `makeTree`+beside it) — name the call and its module in that asset's description, and the asset imports+`../lib/`; a `blender_glb` hero cannot. Zone `contents` lists only actual asset names; library+effects a zone places itself belong in its prose, not in invented asset ids. A stream or river+has one upstream-to-downstream path with nonincreasing Y, and its banks sample the same terrain+height function. The zone drives each effect's `userData.update(t, dt)` exactly once per frame.-## What this track is graded on (write the plan that wins these points)-A scene scores 0.8+ only when every authored camera makes a PICTURE: three depth layers-(something within 5 m framing the shot, the subject at 8-30 m, a hazy horizon above), ground-that is several blended materials with paths and worn edges, vegetation/rock in 3+ species with-size and hue variation in clusters, a lived-in amount of small props, coloured atmosphere with-warm key vs cool fill, and motion you can see between t=0 s and t=1.5 s. A correct-but-bare-scene — a diorama of a few objects on one flat coloured plane, ringed by identical cones, under-flat light — scores ~0.5 no matter how well it is coded. Your plan must make the bare version-impossible: put the counts, the layers, the colours and the amplitudes in the text.+## What the harness measures and the judge sees (plan so these hold)+- Every authored camera is rendered at t=0 s and t=1.5 s and judged as a picture of the brief's+ place. `cameras[0]` is measured as the establishing shot: content covers >= 20 % of its frame;+ every other authored camera >= 10 % (the rest being sky/ground). A lens inside a mesh or+ within 0.5 m of a surface caps the whole run.+- No world edge, horizon seam or box boundary is visible from any authored camera (judge; and+ outdoors the census checks that standing geometry >= 2 m tall reaches past 1.25 x the bounds'+ half-extent, and that fog far is >= 2 x the plan span — a shorter fog reads as an edge). How+ the world continues is the environment builder's choice for this place.+- The ground is a believable landform for the place (judge): flat, sloped, terraced, a shore, a+ cliff — whatever the brief implies; every placed thing is seated on it or on what it stands on+ (placement gate: a gap > 0.05 m outdoors / 0.02 m indoors is floating, > 0.10 m into the+ support is sunken, overlapping neighbours interpenetrate — each caps the score).+- The lighting reads as the stated time of day and weather, and the frame is not monochrome+ unless the brief asks for it (judge; exposure is measured against a luminance band).+- Something moves visibly between t=0 s and t=1.5 s (motion probe), and motion the brief names+ is visible from the establishing camera.+- Repeated elements do not read as identical copies (judge), and >= 8 same-size copies spaced+ evenly on a ring round the world are measured as a stamped backdrop. A deliberately regular+ row the brief implies (an orchard, a colonnade, bollards along a quay) is fine.+- The place carries what its activity implies; a bare diorama on one plane is a judged defect,+ and a zone under half its layout's count gets an INFO note (the counts the brief states are acceptance items).+- The brief's must-haves are acceptance items; an unmet `must` caps the run at 0.60.WHAT TO PRODUCE (JSON, fields: {{ schema_fields }}):1. `title`, `summary` (two sentences), `setting` (place, era, weather, time of day), `mood`.-2. `bounds` — centre + extents in meters of the whole playable area (a garden 30 x 10 x 30 m; a- harbour 120 x 30 x 120 m). Keep it as small as the brief allows: detail beats acreage.-3. `environment` — ONE paragraph, all numbers, covering IN THIS ORDER:- (a) sky zenith + horizon hex and the sun/moon azimuth + elevation in degrees;- (b) key light hex + intensity AND fill (hemisphere) sky/ground hex + intensity — the fill hue- must be at least 60 degrees away from the key hue (warm sun, cool sky) or the frame comes- out monochrome;- (c) fog hex (= the sky HORIZON colour, never white or grey unless overcast) + near/far in- meters, scaled to this scene: near ~ 0.4 x the bounds diagonal, far ~ 2 x the diagonal;- (d) ground: the terrain stays within about +/-1.5 m of y = 0 inside the bounds (camera- heights below are absolute, and a lifted floor puts them underground); ponds, terraces- and gravel beds are carved INTO the terrain, never laid on it as flat discs;- the 3-4 material colours that blend across it (e.g. moss 0x4a602e, dry grass- 0x8a8148, packed dirt 0x6b5334, gravel 0xa89a7c), which drives the blend (height, slope,- noise), and where the PATH runs as a polyline of 3-5 (x, z) points, 1.2-2.0 m wide;- (e) the BACKDROP that hides the world edge: a silhouette ring (hills / treeline / rooftops /- mesas) at radius ~ 0.6 x fog far, 24-40 SOLID pieces (never flat cut-out planes) in- their own colour darkened 0.6-0.8x — the scene fog supplies the haze, so never tint- them toward the fog colour — or, for an interior, what is seen through the glass;- (f) water plane height + colour, if any.-4. `zones` — 3 to 6 spatial regions with PascalCase names, a `bbox`, and `contents` = asset names- placed there. Zone bboxes tile the bounds without overlapping by more than 1 m.- Each zone `description` MUST state, as numbers:- - its DEPTH ROLE for the cameras: `foreground frame`, `midground subject` or `background`;- - the layout (paths, clusters, spacing in meters, what faces what);- - DENSITY COUNTS: how many trees / shrubs / rocks / mid props (0.3-1.5 m) / small props- (< 0.3 m) / ground-cover tufts it contains. Target per zone: 12-25 mid props, 25-60 small- props, 300-800 ground-cover tufts for a planted zone (desert: 15-30 boulders in 3 size- bands, 60-200 scrub clumps; interior: 15-30 mid, 40-100 small);- - the VARIATION rule: at least 3 distinct silhouettes for any repeated natural element, with- +/-30 % scale jitter and +/-0.03 hue jitter — never one shape stamped in a ring or grid.-5. `assets` — 4 to 8 reusable things placed in zones. PascalCase `name`; `kind` = `threejs` for- procedural shapes (fences, lanterns, benches, boats, trees the library does not grow) or `blender_glb` ONLY for- 1-2 hero objects that need sculpted/bevelled detail (a hero may also carry ONE 2 s keyframed- motion — a swinging lamp, a turning wheel — say so in its description); `description` with construction numbers- and colours; `approx_size_m` = width x height x depth in meters (a stone lantern- 0.5 x 1.6 x 0.5; a bench 1.6 x 0.9 x 0.6; a pine 3 x 7 x 3); `instances_hint` = how many- appear in total. Prefer FEWER asset modules with a `variant` range (say "5 variants via- opts.variant: three trunk shapes, two crown shapes") over many near-duplicate modules —- variation belongs inside an asset, not in the asset list. Ground cover, terrain, water,- backdrop and sky are NOT assets — they belong to the environment / zones.-6. `effects` — 1 to 4: `glsl_material` (water ripple, lantern glow, wind-swayed foliage),- `particles` (petals, sparks, snow), `animated_geometry`, or `postprocess`; say which zone/asset.-7. `animation` — 2 to 6 lines of what moves, each with an amplitude that is VISIBLE in a- 1024x576 frame after 1.5 s: foliage sway +/-0.10-0.20 rad over 1.6-3 s; grass +/-0.15 rad;- water waves >= 0.04 m plus a scroll >= 0.15 m/s; particles travelling >= 0.6 m per 1.5 s;- vehicles/boats/beams >= 1.5 m or a full revolution per 1.5 s; light flicker x0.75-x1.3.- Exactly one of them is the HERO motion: the single thing a viewer cannot miss.-8. `cameras` — 3 to 4 authored cameras. The harness uses your numbers LITERALLY, so compute them:- - `cameras[0]` is the establishing shot. Pick the SUBJECT (the hero asset or the zone the- brief is about) and its centre point S. Put the camera at distance- D = 1.5 x (subject radius) / tan(fov/2) from S, at height- y = (tallest thing between camera and subject) + 0.30 x D, looking AT S (not at the bounds- centre, not at the horizon). It must see 2+ zones and be mostly content rather than empty- sky/ground.- - one eye-level camera INSIDE the scene at y = ground + 1.6-1.8 m, aimed along a path or- across the subject so that something within 5 m frames one edge of the shot;- - one detail camera 2-4 m from the hero asset, slightly above its mid height.- - `purpose` must name the subject, the foreground framing element and what is on the horizon- for that shot ("establishing: the arched bridge at 14 m, framed by the maple on the right at- 3 m, cedar ridge on the horizon").- - No camera may be inside or up against geometry; fov 35-60.-9. `acceptance` — 6 to 12 items covering: each must-have from the brief, the hero assets visible- from the establishing camera, time-of-day lighting reads correctly, the hero motion is visible- between t=0 and t=1.5 s, no floating or sunken assets (`how: probe`), no hard world edge from- any authored camera.+2. `bounds` — centre + extents in meters of the DETAILED area: where the builders spend their+ detail and what the harness measures against (zone layouts, placed assets — one sitting+ entirely outside is noted — and camera clearance). It is not a cage: the world continues past+ it as the place does — a road or river running out, a wall, a shoreline, far buildings,+ terrain that keeps going — and the environment builder builds that continuation. Size and+ proportion it to the brief's subject: a street is long and narrow, a courtyard small, a+ valley wide; a bigger box is not more detail.+3. `environment` — ONE paragraph of concrete numbers for what the brief's place needs:+ sky colours and the sun/moon azimuth + elevation in degrees; key light hex + intensity and+ fill (hemisphere) sky/ground hex + intensity for that time of day and weather (a fill hue well+ away from the key's is one way to keep the frame from going monochrome); atmosphere: fog hex ++ near/far in meters as the weather needs it (fog is measured: present, far >= 2 x the plan+ span); the LANDFORM — what the land does across the bounds and its height at each authored+ camera position (camera heights are absolute) — and the ground surface(s) with colours and+ where walkways, roads or tracks run, as (x, z) routes with widths, when the brief has them+ (the zone layouts read them as `path_points`); how the world continues beyond the bounds in+ each direction and what the horizon is from the authored cameras (for an interior: what is+ seen through the openings); water height + colour, if any. Ponds, terraces and beds meet the+ terrain with no floating edge (placement gate).+4. `zones` — the brief's places, one builder each, with PascalCase names, a `bbox` (where that+ builder may place: layouts are validated against it with 1 m of slack) and `contents` = asset+ names placed there. Lay them out as the place is laid out — along a street, round a corner,+ radially about a well, scattered over a slope, one inside another — in any number and size;+ they need not cover the bounds, open ground between them is allowed, and two bboxes overlap by+ at most 1 m so their placements cannot collide. Each zone `description` states, as numbers:+ - what the place is and what happens there, and which authored cameras see it;+ - the layout: what stands where, spacing in meters, what faces what, what stands ON what;+ - the counts the brief fixes, and how much loose dressing this zone carries beyond its+ contents, as the place needs (the zone layout counts it in three fields — mid props, small+ props, ground cover — and the census notes a zone under half its count): a market is crowded,+ a quarry floor nearly bare, zero is a valid answer;+ - how repeated natural elements vary (silhouette, scale, hue) or why a regular row is right.+5. `assets` — the reusable things the brief needs; each is one builder session inside the run's+ time and cost ceiling. PascalCase `name`; `kind` = `threejs` (a procedural module) or+ `blender_glb` (built in Blender and shipped as a GLB: slower and costlier, so for the hero+ that needs sculpted or bevelled detail; a hero may also carry ONE 2 s keyframed motion — say so+ in its description); `description` with construction numbers and colours; `approx_size_m` =+ width x height x depth in meters (the built asset is measured against it: a stone lantern+ 0.5 x 1.6 x 0.5, a bench 1.6 x 0.9 x 0.6, a pine 3 x 7 x 3); `instances_hint` = how many+ appear in total. Triangle budget: <= 15 000 triangles per module, <= 40 000 for a hero+ (measured by the build census). Variation belongs inside an asset (say "5 variants via+ opts.variant: three trunk shapes, two crown shapes") rather than in near-duplicate modules.+ Ground cover, terrain, water, sky and whatever continues the world beyond the bounds are built+ by the environment / zone builders, not as assets.+6. `effects` — 0 or more: `glsl_material` (water ripple, lantern glow, wind-swayed foliage),+ `particles` (petals, sparks, snow), `animated_geometry`, or `postprocess`; say which zone/asset+ owns each.+7. `animation` — what moves, each line with an amplitude visible in a 1024x576 frame between t=0+ and t=1.5 s (motion probe). Amplitudes that have measured as visible: foliage sway+ +/-0.10-0.20 rad over 1.6-3 s; water waves >= 0.04 m or a scroll >= 0.15 m/s; particles+ travelling >= 0.6 m per 1.5 s; vehicles/boats/beams >= 1.5 m or a full revolution per 1.5 s;+ light flicker x0.75-x1.3. Motion the brief names is visible from the establishing camera.+8. `cameras` — 1 to 6 authored shots; the harness uses your numbers LITERALLY, so compute them+ from where the subject is and how big it is. `cameras[0]` is measured as the establishing+ shot: it shows the brief's subject clearly, with content >= 20 % of the frame. Every camera+ stands above the terrain at its own (x, z), keeps its lens >= 0.5 m from any surface and+ looks at content (>= 10 %). `purpose` says what the shot is of and what the judge should see+ in it. `fov` is yours (schema 5-150). How many shots, from where and at what height is the+ brief's: a long open vista, a close interior, a walk along a street or a top-down court are each+ right when the place is.+9. `acceptance` — one item per must-have in the brief, plus the measured checks: nothing floating+ or sunken (`how: probe`), the named motion visible between t=0 and t=1.5 s (`probe`), no world+ edge from any authored camera (`visual`), lighting reads as the stated time of day (`visual`).**`priority` matters more than anything else in this list.** ANY unmet `must` item caps thewhole run's score at 0.60, however good the pictures are — one over-specified detail throwsaway a passing scene. So:- - mark at most 4-6 items `must`, and only ones that restate a hard requirement of the brief- itself, that a person can confirm from ONE rendered frame, and that name no incidental- detail: "a raked gravel area is visible in the zen garden" is a `must`; "raked gravel with- concentric rings around each rock" is a `should`;- - `a1` is ALWAYS the premise: the kind of PLACE the brief describes, in the plainest words- that would be false if the scene were somewhere else — "the view is from inside an- enclosed workshop", "the courtyard is lit only by its lanterns at night". Measured- 2026-08-25: a brief reading "INSIDE a boatbuilder's workshop, sun raking through a dusty- window wall" was planned as "Coastal boatyard, clear dusk" and built faithfully as an- outdoor yard with no walls and no roof — it passed every gate and scored 0.4653. Write- the premise down and the rest of the plan stays anchored to it — and when that premise- is INSIDE a built space, set `interior: true`: the environment module then builds the- enclosure on the bounds' faces (floor, walls, ceiling, with openings where `environment`- puts the windows and doors) and the zones dress the inside. Measured 2026-09-07 on- six interior runs: with no owner for walls and roof, every one was judged "not- enclosed, a diorama on a flat plane" (0.0–0.3) until a refine round built them.- When the enclosure itself is glass on a frame (a conservatory, greenhouse, palm house,- glass atrium) also set `glazed: true`: the walls and roof are then glass on an iron- grid that the sun and the outside come through — an opaque room around a glass house- was judged "a solid box blocking the exterior view and lighting";- - mark everything else `priority: should` — craft goals, counts, specific patterns, exact+ - mark `must` only items that restate a hard requirement of the brief itself, that a person+ can confirm from ONE rendered frame, and that name no incidental detail: "a raked gravel+ area is visible in the zen garden" is a `must`; "raked gravel with concentric rings around+ each rock" is a `should`;+ - `a1` is the premise: the kind of PLACE the brief describes, in the plainest words that+ would be false if the scene were somewhere else — "the view is from inside an enclosed+ workshop", "the courtyard is lit only by its lanterns at night". Measured 2026-08-25: a+ brief reading "INSIDE a boatbuilder's workshop" was planned as "Coastal boatyard, clear+ dusk", built faithfully as an outdoor yard, passed every gate and scored 0.4653. When the+ premise is INSIDE a built space, set `interior: true`: the environment module then owns the+ enclosure (floor, walls, ceiling, openings where `environment` puts them; the skeleton+ starts it on the bounds' faces and the builder may reshape it) and the zones dress the+ inside — six interior runs with no owner for walls and roof were each judged "not enclosed,+ a diorama on a flat plane" (0.0-0.3). When the enclosure itself is glass on a frame (a+ conservatory, greenhouse, palm house, glass atrium) also set `glazed: true`: the walls and+ roof are then glass on a grid that the sun and the outside come through;+ - everything else is `priority: should` — craft goals, counts, specific patterns, exactheights and anything needing evidence the judge may not have;- - never write a `must` whose wording contains a number, a named style, or the word "and"- joining two independent claims — split it or demote it.+ - a `must` whose wording carries a number, a named style, or "and" joining two independent+ claims is rarely confirmable from one frame: split it or demote it.RULES-- Every name in `zones[].contents` must be an asset name; asset names unique; zone names unique.+- Every name in `zones[].contents` is an asset name; asset names unique; zone names unique.- Realistic scale: people 1.7 m, doors 2.1 m, steps 0.17 m, benches 0.45 m seat height.-- Prefer <= 8 assets and 3-5 zones for modest briefs. No prose outside the JSON.+- No prose outside the JSON.-WORKED EXAMPLE (field SHAPE only — its prose is deliberately terse and does NOT meet the-`environment` / zone-description / camera-purpose requirements above):+WORKED EXAMPLE — field SHAPE only. It is ONE place's plan (a harbour: an L of quay along one+side, open water on the other, the mole and the village street running out of the bounds); the+brief's place has its own shape, and its prose is terser than the plan you write:{{ example_json }}-HOW THE THREE PROSE FIELDS MUST ACTUALLY READ (style, not values):-- environment: "Sky zenith 0x3b5f96 to horizon 0xf0a860, sun azimuth 250 deg elevation 12 deg,- key 0xffc27a at 2.8, hemisphere sky 0x86a8d8 / ground 0x5c4630 at 0.85 (cool fill against the- warm key); fog 0xf0a860 near 16 m far 77 m (bounds diagonal 45 m); ground blends moss 0x4a602e,- dry grass 0x8a8148, packed dirt 0x6b5334 and gravel 0xa89a7c by slope and noise, with a 1.6 m- gravel path through (-14,-11), (-5,-4), (2,1), (9,8) flattened into heightAt; backdrop = 30- cedar-ridge silhouettes at radius 46 m, 3-6 m tall, tinted 70 % to the fog colour; pond plane- at y=-0.35, 0x2c4a52."-- zone description: "MIDGROUND SUBJECT. The koi pond and arched bridge on the path's east bend.- 1 bridge, 2 stone lanterns 4 m apart facing the path, 3 pond rocks in 3 sizes, 18 mid props- (potted shrubs, a water basin, a stacked-stone kerb, a bucket, a bamboo scoop), 34 small props- (pebbles along the pond rim, fallen maple leaves, a rope coil, moss patches), 500 ground-cover- tufts outside the gravel. Vegetation uses 3 silhouettes (upright pine, low maple, round shrub)- with +/-30 % scale and +/-0.03 hue jitter, in 4 clusters, never a ring."-- camera purpose: "establishing: the arched bridge (subject centre 1.5, 0.9, -0.8, radius 4.5 m)- from the south-east above the maples, framed by the lantern at 3 m on the left edge, cedar ridge- on the horizon; sees PondBasin and ZenGarden."+EXAMPLES OF THE CONCRETENESS WANTED — one bullet per place, none of them the harbour above; the+brief's place gets its own numbers:+- environment, a hangar interior: "Overcast noon through the open doors: no sun lamp; sky+ 0xcfd6de seen through the 40 x 12 m door opening on the south face, key from it 0xdde4ea at 1.4,+ fill 0x8a9098 / 0x3a3a3a at 0.6, twelve roof lamps 0xfff1d8 at 2.0 on 8 m centres; no fog, a+ faint 0xb0b4b8 dust haze near 10 m far 140 m. Floor flat concrete 0x7a7b78 at y=0, 60 x 90 m,+ painted bay lines 0xd8c25a every 15 m; the bounds are the hangar; outside the doors the apron+ continues 200 m to a treeline."+- environment, a slot canyon: "Noon sun azimuth 190 deg elevation 72 deg, key 0xfff0dc at 3.0+ reaching the floor only in a 3 m band; fill 0xe0b088 / 0x5a3a28 at 0.9 (the walls bounce+ orange); fog 0xd9a070 near 15 m far 90 m (span 60 m). The floor is a sand wash 0xc8a070+ falling 4 m along z from +30 to -30 and keeps falling past the bounds; walls 14-22 m high+ 2-4 m apart, sandstone 0xb8683a banded 0x8a4a2a every 0.6 m, both run out of the bounds."+- environment, a night market: "22:00, no moon: sky 0x0c1020, no sun lamp; key is the stall+ lamps 0xffc070 at 2.5 every 4 m along the lane and the shop signs 0xff5a8a / 0x40c8ff at 1.5;+ fill 0x203048 / 0x100c08 at 0.25; fog 0x141826 near 20 m far 160 m (span 80 m). The lane is+ flat wet asphalt 0x24262a at y=0, 6 m wide, running out of the bounds both ways; two-storey+ shophouses 0x6a5a48 line it on both sides and continue past the bounds."+- a dense zone: "The lane's west side, seen by LaneWalk and Overview: 7 stalls 4 m apart facing+ the lane, each with its lamp and a crowd of 3-5 people in front, ~25 mid props (stools, crates,+ bins), ~60 small props (bowls, bottles, signs), no ground cover on the asphalt."+- a bare zone: "The canyon floor downstream, seen by Overview only: the sand wash, three fallen+ slabs 1-2 m and nothing else — it reads as a canyon because it is empty."+- camera purpose: "establishing: looking down the lane from its north end at eye height+ (subject: the stall row, ~30 m deep), the signs stacking into the fog; no sky in frame."diff --git a/harness/codeverse3d/prompts/tracks/plan_scene_bpy.j2 b/harness/codeverse3d/prompts/tracks/plan_scene_bpy.j2index f247d9a1..27e49813 100644--- a/harness/codeverse3d/prompts/tracks/plan_scene_bpy.j2+++ b/harness/codeverse3d/prompts/tracks/plan_scene_bpy.j2@@ -1,18 +1,20 @@You are the SCENE DIRECTOR for a Blender (bpy, Cycles) scene that several code-writing models willbuild in parallel from your plan alone (one per asset, one for every zone, one for the environment).-Write the plan as exact numbers and concrete nouns; keep it lean (cost matters).+Write the plan as exact numbers and concrete nouns; keep it lean (cost matters). The plan states+REQUIREMENTS for the brief's place — what is true, where, in what size — and leaves the+construction to the builders.THE PLAN'S FRAME: write every number — bounds, zone bboxes, asset sizes (width × height × depth),camera positions — in the Y-up GLB frame (Y up, +Z towards the viewer, metres, the ground around-y = 0), exactly as a three.js director would. The builders author Blender Z-up modules, and the-HARNESS converts every number it prints for them (their skeleton, their briefs, the layouts): you-never write Z-up numbers, and `environment` prose should say "y" for up. (The language frame the-builders see, for reference: {{ frame_doc }})+y = 0 unless the plan puts it elsewhere), exactly as a three.js director would. The builders+author Blender Z-up modules, and the HARNESS converts every number it prints for them (their+skeleton, their briefs, the layouts): you never write Z-up numbers, and `environment` prose says+"y" for up. (The language frame the builders see, for reference: {{ frame_doc }})LANGUAGE CONTRACT THE BUILDERS WILL FOLLOW:{{ contract }}-SHIPPED BPY LIBRARY:+SHIPPED BPY LIBRARY (optional toolbox):The scene workspace already contains, under `src/lib/`: `noise.py` (`fbm2`, `ridged`,`mountain_height`, `height_field`), `mesh.py` (`Batch`: box / sphere / lathe / cone / beam / torus,`mesh_object`, `curve_object`), `materials.py` (`material`, `masonry`, `limestone`, `woodgrain`,@@ -27,152 +29,168 @@ The scene workspace already contains, under `src/lib/`: `noise.py` (`fbm2`, `rid`room_shell`, `lantern`, `text_mesh`), `scatter.py` (`instance`, `scatter`, `poisson`,`along_path`, `grid`, `gn_scatter`), `place.py` (`seat`, `rest_on`, `clear_of`, `unique_name`),`figure.py` (`figure`, `visitor`, `crowd`) and `motion.py` (`keyframe_path`, `drift`, `spin`,-`sway`, `scroll`, `shape_key_sweep`). When they cover the brief, describe their calls and-dimensions in the owning zone description / environment / effects. Do not request an asset that-rebuilds one of them (a Waterfall, OakTree, BoulderCluster, GrassPatch or Lantern asset); an-element they do not cover (a carved stone, a fishing boat, a market stall) is still an asset.-A `bpy` asset may compose a library call with its own parts (a shrine with a `tree(...)` beside it,-a well ringed by `boulder(...)`s): name the call and its module (`tree`, `lib/vegetation.py`) in that-asset's description. A `blender_glb` hero cannot. Zone `contents` still lists only actual asset-names; library effects a zone places itself belong in prose, not invented asset ids.-Water and terrain share ONE surface sampler (`height_at` from the environment; a pond is a basin-carved into it) and every placed thing is seated on it or on what it stands on — the harness-measures the gap.+`sway`, `scroll`, `shape_key_sweep`). Use a call when its output fits the brief: name it, its+module and its dimensions in the owning zone description / environment / effects. An element the+library does not give in the form the brief wants (a carved stone, a fishing boat, a market stall,+a different kind of tree) is an asset built from scratch within the triangle budget below.+Interface: a `bpy` asset may compose a library call with its own parts (a shrine with a `tree(...)`+beside it) — name the call and its module (`tree`, `lib/vegetation.py`) in that asset's+description; a `blender_glb` hero cannot. Zone `contents` lists only actual asset names; library+effects a zone places itself belong in its prose, not in invented asset ids. Water and terrain+share ONE surface sampler (`height_at` from the environment) and every placed thing is seated on+it or on what it stands on — the harness measures the gap. Geometry that exists only to continue+the world beyond the bounds is named with the `Sky` prefix (the census then keeps it out of the+content bbox).-## What this track is graded on (write the plan that wins these points)-A scene scores 0.8+ only when every authored camera makes a PICTURE: three depth layers-(something within 5 m framing the shot, the subject at 8-30 m, a hazy horizon above), ground-that is several blended materials with paths and worn edges, vegetation/rock in 3+ species with-size and hue variation in clusters, a lived-in amount of small props, coloured atmosphere with a-warm sun under a cool sky, and motion you can see between t=0 s and t=1.5 s — and NOTHING floating,-sunken or passing through its neighbour (the placement gate measures every placed thing and caps-the score). A correct-but-bare scene — a diorama of a few objects on one flat coloured plane,-ringed by identical cones, under flat light — scores ~0.5 no matter how well it is coded. Your-plan must make the bare version impossible: put the counts, the layers, the colours and the-amplitudes in the text.+## What the harness measures and the judge sees (plan so these hold)+- Every authored camera is rendered at t=0 s and t=1.5 s and judged as a picture of the brief's+ place. `cameras[0]` is measured as the establishing shot: content covers >= 20 % of its frame;+ every other authored camera >= 10 % (the rest being sky/ground). A lens inside a mesh or+ within 0.5 m of a surface caps the whole run.+- No world edge, horizon seam or box boundary is visible from any authored camera (judge; and+ outdoors the census checks that standing geometry >= 2 m tall reaches past 1.25 x the bounds'+ half-extent, and that the atmosphere's 1 / density is >= the plan span / 1.5 — a denser fog+ dissolves the world inside the content and reads as an edge). How the world continues is the environment builder's choice for this+ place.+- The ground is a believable landform for the place (judge): flat, sloped, terraced, a shore, a+ cliff — whatever the brief implies; every placed thing is seated on it or on what it stands on+ (placement gate: a gap > 0.05 m outdoors / 0.02 m indoors is floating, > 0.10 m into the+ support is sunken, overlapping neighbours interpenetrate — each caps the score).+- The lighting reads as the stated time of day and weather, and the frame is not monochrome+ unless the brief asks for it (judge; exposure is measured against a luminance band).+- Something moves visibly between t=0 s and t=1.5 s (motion probe), and motion the brief names+ is visible from the establishing camera.+- Repeated elements do not read as identical copies (judge), and >= 8 same-size copies spaced+ evenly on a ring round the world are measured as a stamped backdrop. A deliberately regular+ row the brief implies (an orchard, a colonnade, bollards along a quay) is fine.+- The place carries what its activity implies; a bare diorama on one plane is a judged defect,+ and a zone under half its layout's count gets an INFO note (the counts the brief states are acceptance items).+- The brief's must-haves are acceptance items; an unmet `must` caps the run at 0.60.WHAT TO PRODUCE (JSON, fields: {{ schema_fields }}):1. `title`, `summary` (two sentences), `setting` (place, era, weather, time of day), `mood`.-2. `bounds` — centre + extents in meters of the whole playable area (a garden 30 x 10 x 30 m; a- harbour 120 x 30 x 120 m). Keep it as small as the brief allows: detail beats acreage.-3. `environment` — ONE paragraph, all numbers, covering IN THIS ORDER:- (a) the sun / moon azimuth (compass: 0 = +X, 90 = +Y) + elevation in degrees and the time of day- (dawn / morning / noon / golden / overcast / dusk / night — the builders' lighting table);- (b) the Sun lamp's colour + energy in W/m² (day 3-5, golden 2-2.5, dusk 1-1.5, a moon 0.1-0.3)- AND the sky world strength (day 0.4-0.5, dusk 0.2, night 0.1) — a warm sun under a cool- physical sky, or the frame comes out monochrome;- (c) the fog: density (0.003-0.008) + colour (= the sky HORIZON colour, never white or grey unless- overcast), as a bounded volume over the whole ground;- (d) ground: the terrain stays within about +/-1.5 m of y = 0 inside the bounds (camera heights- below are absolute, and a lifted floor puts them underground); ponds, terraces and gravel- beds are carved INTO the terrain, never laid on it as flat discs; the 3-4 material colours- that blend across it (e.g. moss (0.29, 0.38, 0.18), dry grass (0.54, 0.51, 0.28), packed- dirt (0.42, 0.33, 0.20), gravel (0.66, 0.60, 0.49)), what drives the blend (height, slope,- noise), and where the PATH runs as a polyline of 3-5 (x, z) points, 1.2-2.0 m wide;- (e) the BACKDROP that hides the world edge: a sky-named silhouette ring (hills / treeline /- rooftops / mesas) at radius ~ 0.6 x the visible range, 24-40 SOLID pieces (never flat- cut-out planes) in their own colour darkened 0.6-0.8x — the fog supplies the haze, so never- tint them toward the fog colour — or, for an interior, what is seen through the glass;- (f) water plane height + colour, if any.-4. `zones` — 3 to 6 spatial regions with PascalCase names, a `bbox`, and `contents` = asset names- placed there. Zone bboxes tile the bounds without overlapping by more than 1 m.- Each zone `description` MUST state, as numbers:- - its DEPTH ROLE for the cameras: `foreground frame`, `midground subject` or `background`;- - the layout (paths, clusters, spacing in meters, what faces what, what stands ON what);- - DENSITY COUNTS: how many trees / shrubs / rocks / mid props (0.3-1.5 m) / small props- (< 0.3 m) / ground-cover blades it contains. Target per zone: 12-25 mid props, 25-60 small- props, 300-800 ground-cover blades for a planted zone (desert: 15-30 boulders in 3 size- bands, 60-200 scrub clumps; interior: 15-30 mid, 40-100 small);- - the VARIATION rule: at least 3 distinct silhouettes for any repeated natural element, with- +/-30 % scale jitter and hue jitter — never one shape stamped in a ring or grid.-5. `assets` — 4 to 8 reusable things placed in zones. PascalCase `name`; `kind` = `bpy` for- procedural props (fences, lanterns, benches, boats, trees the library does not grow) built as a- bpy module and placed as collection instances, or `blender_glb` ONLY for 1-2 hero objects that- need sculpted/bevelled detail (a hero may also carry ONE 2 s keyframed motion — a swinging lamp,- a turning wheel — say so in its description); `description` with construction numbers and- colours; `approx_size_m` = width x height x depth in meters (a stone lantern 0.5 x 1.6 x 0.5; a- bench 1.6 x 0.9 x 0.6; a pine 3 x 7 x 3); `instances_hint` = how many appear in total. Prefer- FEWER asset modules with a `variant` range (say "5 variants via variant: three trunk shapes, two- crown shapes") over many near-duplicate modules — variation belongs inside an asset, not in the- asset list. Ground cover, terrain, water, backdrop and sky are NOT assets — they belong to the- environment / zones.-6. `effects` — 1 to 4: `glsl_material` (a shader-node effect: water ripple, lantern glow, a+2. `bounds` — centre + extents in meters of the DETAILED area: where the builders spend their+ detail and what the harness measures against (zone layouts, placed assets — one sitting+ entirely outside is noted — and camera clearance). It is not a cage: the world continues past+ it as the place does — a road or river running out, a wall, a shoreline, far buildings,+ terrain that keeps going — and the environment builder builds that continuation. Size and+ proportion it to the brief's subject: a street is long and narrow, a courtyard small, a+ valley wide; a bigger box is not more detail.+3. `environment` — ONE paragraph of concrete numbers for what the brief's place needs:+ the sun / moon azimuth (compass: 0 = +X, 90 = +Y) + elevation in degrees and the time of day+ (dawn / morning / noon / golden / overcast / dusk / night — the builders' lighting table); the+ Sun lamp's colour + energy in W/m² and the sky world strength such that the judged frames land+ in the measured luminance band (pairs that did: day 3-5 W/m² at world 0.4-0.5, dusk 1-1.5 at+ 0.2, a moon 0.1-0.3 at 0.1), coloured for the weather; atmosphere: fog density + colour as a+ volume over the ground when the weather needs it (the census reads its density: 1 / density+ >= the plan span / 1.5); the LANDFORM — what the land does across the bounds and its height at each+ authored camera position (camera heights are absolute) — and the ground surface(s) with+ colours (RGB 0-1) and where walkways, roads or tracks run, as (x, z) routes with widths, when+ the brief has them (the zone layouts read them as `path_points`); how the world continues+ beyond the bounds in each direction and what the horizon is from the authored cameras (for an+ interior: what is seen through the openings); water height + colour, if any. Ponds, terraces+ and beds meet the terrain with no floating edge (placement gate).+4. `zones` — the brief's places, one builder each, with PascalCase names, a `bbox` (where that+ builder may place: layouts are validated against it with 1 m of slack) and `contents` = asset+ names placed there. Lay them out as the place is laid out — along a street, round a corner,+ radially about a well, scattered over a slope, one inside another — in any number and size;+ they need not cover the bounds, open ground between them is allowed, and two bboxes overlap by+ at most 1 m so their placements cannot collide. Each zone `description` states, as numbers:+ - what the place is and what happens there, and which authored cameras see it;+ - the layout: what stands where, spacing in meters, what faces what, what stands ON what;+ - the counts the brief fixes, and how much loose dressing this zone carries beyond its+ contents, as the place needs (the zone layout counts it in three fields — mid props, small+ props, ground cover — and the census notes a zone under half its count): a market is crowded,+ a quarry floor nearly bare, zero is a valid answer;+ - how repeated natural elements vary (silhouette, scale, hue) or why a regular row is right.+5. `assets` — the reusable things the brief needs; each is one builder session inside the run's+ time and cost ceiling. PascalCase `name`; `kind` = `bpy` (a procedural module placed as+ collection instances) or `blender_glb` (built as an object and shipped as a GLB: slower and+ costlier, so for the hero that needs sculpted or bevelled detail; a hero may also carry ONE+ 2 s keyframed motion — say so in its description); `description` with construction numbers+ and colours; `approx_size_m` = width x height x depth in meters (the built asset is measured+ against it: a stone lantern 0.5 x 1.6 x 0.5, a bench 1.6 x 0.9 x 0.6, a pine 3 x 7 x 3);+ `instances_hint` = how many appear in total. Triangle budget: <= 15 000 triangles per module,+ <= 40 000 for a hero (measured by the build census). Variation belongs inside an asset (say+ "5 variants via variant: three trunk shapes, two crown shapes") rather than in near-duplicate+ modules. Ground cover, terrain, water, sky and whatever continues the world beyond the bounds+ are built by the environment / zone builders, not as assets.+6. `effects` — 0 or more: `glsl_material` (a shader-node effect: water ripple, lantern glow, atranslucent leaf), `particles` (petals, sparks, snow — a small keyframed instance cloud),- `animated_geometry`, or `postprocess` (a volume: mist, light shafts); say which zone/asset.-7. `animation` — 2 to 6 lines of what moves, each with an amplitude that is VISIBLE in a- 1024x576 frame after 1.5 s: foliage sway +/-0.10-0.20 rad; grass +/-0.15 rad; water ripples- scrolling >= 0.15 m/s plus a bob >= 0.04 m; particles travelling >= 0.6 m per 1.5 s;- vehicles/boats/sails >= 1.5 m or a visible turn per 1.5 s; lantern flicker x0.75-x1.3.- Exactly one of them is the HERO motion: the single thing a viewer cannot miss.-8. `cameras` — 3 to 4 authored cameras. The harness uses your numbers LITERALLY, so compute them:- - `cameras[0]` is the establishing shot. Pick the SUBJECT (the hero asset or the zone the- brief is about) and its centre point S. Put the camera at distance- D = 1.5 x (subject radius) / tan(fov/2) from S, at height- y = (tallest thing between camera and subject) + 0.30 x D, looking AT S (not at the bounds- centre, not at the horizon). It must see 2+ zones and be mostly content rather than empty- sky/ground.- - one eye-level camera INSIDE the scene at y = ground + 1.6-1.8 m, aimed along a path or- across the subject so that something within 5 m frames one edge of the shot;- - one detail camera 2-4 m from the hero asset, slightly above its mid height.- - `purpose` must name the subject, the foreground framing element and what is on the horizon- for that shot ("establishing: the arched bridge at 14 m, framed by the maple on the right at- 3 m, cedar ridge on the horizon").- - No camera may be inside or up against geometry; fov 35-60 (vertical).-9. `acceptance` — 6 to 12 items covering: each must-have from the brief, the hero assets visible- from the establishing camera, time-of-day lighting reads correctly, the hero motion is visible- between t=0 and t=1.5 s, no floating or sunken assets (`how: probe`), no hard world edge from- any authored camera.+ `animated_geometry`, or `postprocess` (a volume: mist, light shafts); say which zone/asset owns+ each.+7. `animation` — what moves, each line with an amplitude visible in a 1024x576 frame between t=0+ and t=1.5 s (motion probe). Amplitudes that have measured as visible: foliage sway+ +/-0.10-0.20 rad; water ripples scrolling >= 0.15 m/s or a bob >= 0.04 m; particles travelling+ >= 0.6 m per 1.5 s; vehicles/boats/sails >= 1.5 m or a visible turn per 1.5 s; lantern flicker+ x0.75-x1.3. Motion the brief names is visible from the establishing camera.+8. `cameras` — 1 to 6 authored shots; the harness uses your numbers LITERALLY, so compute them+ from where the subject is and how big it is. `cameras[0]` is measured as the establishing+ shot: it shows the brief's subject clearly, with content >= 20 % of the frame. Every camera+ stands above the terrain at its own (x, z), keeps its lens >= 0.5 m from any surface and+ looks at content (>= 10 %). `purpose` says what the shot is of and what the judge should see+ in it. `fov` (vertical) is yours (schema 5-150). How many shots, from where and at what height+ is the brief's: a long open vista, a close interior, a walk along a street or a top-down court are+ each right when the place is.+9. `acceptance` — one item per must-have in the brief, plus the measured checks: nothing floating+ or sunken (`how: probe`), the named motion visible between t=0 and t=1.5 s (`probe`), no world+ edge from any authored camera (`visual`), lighting reads as the stated time of day (`visual`).**`priority` matters more than anything else in this list.** ANY unmet `must` item caps thewhole run's score at 0.60, however good the pictures are — one over-specified detail throwsaway a passing scene. So:- - mark at most 4-6 items `must`, and only ones that restate a hard requirement of the brief- itself, that a person can confirm from ONE rendered frame, and that name no incidental- detail: "a raked gravel area is visible in the zen garden" is a `must`; "raked gravel with- concentric rings around each rock" is a `should`;- - `a1` is ALWAYS the premise: the kind of PLACE the brief describes, in the plainest words- that would be false if the scene were somewhere else — "the view is from inside an- enclosed workshop", "the courtyard is lit only by its lanterns at night". Measured- 2026-08-25: a brief reading "INSIDE a boatbuilder's workshop, sun raking through a dusty- window wall" was planned as "Coastal boatyard, clear dusk" and built faithfully as an- outdoor yard with no walls and no roof — it passed every gate and scored 0.4653. Write- the premise down and the rest of the plan stays anchored to it — and when that premise- is INSIDE a built space, set `interior: true`: the environment module then builds the- enclosure on the bounds' faces (floor, walls, ceiling, with openings where `environment`- puts the windows and doors) and the zones dress the inside. Measured 2026-09-07 on- six interior runs: with no owner for walls and roof, every one was judged "not- enclosed, a diorama on a flat plane" (0.0–0.3) until a refine round built them.- When the enclosure itself is glass on a frame (a conservatory, greenhouse, palm house,- glass atrium) also set `glazed: true`: the walls and roof are then glass on an iron- grid that the sun and the outside come through — an opaque room around a glass house- was judged "a solid box blocking the exterior view and lighting";- - mark everything else `priority: should` — craft goals, counts, specific patterns, exact+ - mark `must` only items that restate a hard requirement of the brief itself, that a person+ can confirm from ONE rendered frame, and that name no incidental detail: "a raked gravel+ area is visible in the zen garden" is a `must`; "raked gravel with concentric rings around+ each rock" is a `should`;+ - `a1` is the premise: the kind of PLACE the brief describes, in the plainest words that+ would be false if the scene were somewhere else — "the view is from inside an enclosed+ workshop", "the courtyard is lit only by its lanterns at night". Measured 2026-08-25: a+ brief reading "INSIDE a boatbuilder's workshop" was planned as "Coastal boatyard, clear+ dusk", built faithfully as an outdoor yard, passed every gate and scored 0.4653. When the+ premise is INSIDE a built space, set `interior: true`: the environment module then owns the+ enclosure (floor, walls, ceiling, openings where `environment` puts them; the skeleton+ starts it on the bounds' faces and the builder may reshape it) and the zones dress the+ inside — six interior runs with no owner for walls and roof were each judged "not enclosed,+ a diorama on a flat plane" (0.0-0.3). When the enclosure itself is glass on a frame (a+ conservatory, greenhouse, palm house, glass atrium) also set `glazed: true`: the walls and+ roof are then glass on a grid that the sun and the outside come through;+ - everything else is `priority: should` — craft goals, counts, specific patterns, exactheights and anything needing evidence the judge may not have;- - never write a `must` whose wording contains a number, a named style, or the word "and"- joining two independent claims — split it or demote it.+ - a `must` whose wording carries a number, a named style, or "and" joining two independent+ claims is rarely confirmable from one frame: split it or demote it.RULES-- Every name in `zones[].contents` must be an asset name; asset names unique; zone names unique.+- Every name in `zones[].contents` is an asset name; asset names unique; zone names unique.- Realistic scale: people 1.7 m, doors 2.1 m, steps 0.17 m, benches 0.45 m seat height.-- Prefer <= 8 assets and 3-5 zones for modest briefs. No prose outside the JSON.+- No prose outside the JSON.-WORKED EXAMPLE (field SHAPE only — its prose is deliberately terse and does NOT meet the-`environment` / zone-description / camera-purpose requirements above):+WORKED EXAMPLE — field SHAPE only. It is ONE place's plan (a harbour: an L of quay along one+side, open water on the other, the mole and the village street running out of the bounds); the+brief's place has its own shape, and its prose is terser than the plan you write:{{ example_json }}-HOW THE THREE PROSE FIELDS MUST ACTUALLY READ (style, not values):-- environment: "Dusk: sun azimuth 250 deg elevation 8 deg, Sun lamp (1.0, 0.63, 0.38) at 1.2 W/m2- under a physical sky world at strength 0.2 (cool fill against the warm key); fog density 0.006,- colour (0.85, 0.44, 0.23) (the horizon), as a volume over the whole ground; ground blends moss- (0.29, 0.38, 0.18), dry grass (0.54, 0.51, 0.28), packed dirt (0.42, 0.33, 0.20) and gravel (0.66,- 0.60, 0.49) by slope and noise, with a 1.6 m gravel path through (-14,-11), (-5,-4), (2,1), (9,8)- flattened into the terrain; backdrop = 30 cedar-ridge silhouettes at radius 46 m, 3-6 m tall, in- their own green darkened 0.7x; pond basin carved to y=-0.35, water (0.09, 0.25, 0.29)."-- zone description: "MIDGROUND SUBJECT. The koi pond and arched bridge on the path's east bend.- 1 bridge, 2 stone lanterns 4 m apart facing the path, 3 pond rocks in 3 sizes, 18 mid props- (potted shrubs, a water basin, a stacked-stone kerb, a bucket, a bamboo scoop), 34 small props- (pebbles along the pond rim, fallen maple leaves, a rope coil, moss patches), 500 ground-cover- blades outside the gravel. Vegetation uses 3 silhouettes (upright pine, low maple, round shrub)- with +/-30 % scale and hue jitter, in 4 clusters, never a ring; everything seated on the terrain."-- camera purpose: "establishing: the arched bridge (subject centre 1.5, 0.9, -0.8, radius 4.5 m)- from the south-east above the maples, framed by the lantern at 3 m on the left edge, cedar ridge- on the horizon; sees PondBasin and ZenGarden."+EXAMPLES OF THE CONCRETENESS WANTED — one bullet per place, none of them the harbour above; the+brief's place gets its own numbers:+- environment, a hangar interior: "Overcast noon through the open doors: no sun lamp; sky+ (0.81, 0.84, 0.87) seen through the 40 x 12 m door opening on the south face, world strength 0.5, twelve roof+ area lights (1.0, 0.95, 0.85) at 400 W on 8 m centres; a faint dust volume density 0.002 colour (0.69, 0.71, 0.72). Floor flat concrete (0.48, 0.48, 0.47) at y=0, 60 x 90 m,+ painted bay lines (0.85, 0.76, 0.35) every 15 m; the bounds are the hangar; outside the doors the apron+ continues 200 m to a treeline."+- environment, a slot canyon: "Noon sun azimuth 190 deg elevation 72 deg, Sun lamp (1.0, 0.94, 0.86)+ at 4.0 W/m2 reaching the floor only in a 3 m band, world strength 0.3 (the walls bounce+ orange); fog density 0.006 colour (0.85, 0.63, 0.44) in the slot (span 60 m). The floor is a sand wash (0.78, 0.63, 0.44)+ falling 4 m along z from +30 to -30 and keeps falling past the bounds; walls 14-22 m high+ 2-4 m apart, sandstone (0.72, 0.41, 0.23) banded (0.54, 0.29, 0.16) every 0.6 m, both run out of the bounds."+- environment, a night market: "22:00, no moon: world (0.05, 0.06, 0.12) at strength 0.15, no sun lamp; the+ stall lamps (1.0, 0.75, 0.44) at 150 W every 4 m along the lane with an emissive skin at 4, the+ shop signs emissive (1.0, 0.35, 0.54) / (0.25, 0.78, 1.0) at 6; fog density 0.004 colour (0.08,+ 0.09, 0.15) (span 80 m). The lane is+ flat wet asphalt (0.14, 0.15, 0.16) at y=0, 6 m wide, running out of the bounds both ways; two-storey+ shophouses (0.42, 0.35, 0.28) line it on both sides and continue past the bounds."+- a dense zone: "The lane's west side, seen by LaneWalk and Overview: 7 stalls 4 m apart facing+ the lane, each with its lamp and a crowd of 3-5 people in front, ~25 mid props (stools, crates,+ bins), ~60 small props (bowls, bottles, signs), no ground cover on the asphalt."+- a bare zone: "The canyon floor downstream, seen by Overview only: the sand wash, three fallen+ slabs 1-2 m and nothing else — it reads as a canyon because it is empty."+- camera purpose: "establishing: looking down the lane from its north end at eye height+ (subject: the stall row, ~30 m deep), the signs stacking into the fog; no sky in frame."diff --git a/harness/codeverse3d/prompts/tracks/plan_zone_layout.j2 b/harness/codeverse3d/prompts/tracks/plan_zone_layout.j2index 0cc32a19..da12fbc4 100644--- a/harness/codeverse3d/prompts/tracks/plan_zone_layout.j2+++ b/harness/codeverse3d/prompts/tracks/plan_zone_layout.j2@@ -1,24 +1,27 @@You are the ZONE DIRECTOR for one zone of `{{ title }}`. The scene director already fixed the-world ({{ setting }} — mood: {{ mood }}); a builder model will realise YOUR layout verbatim, so-answer with exact numbers, all in WORLD meters, and nothing outside the JSON.+world ({{ setting }} — mood: {{ mood }}); a builder model reads YOUR layout as its proposal — the+contents it names are measured as present, its positions and counts kept unless the place reads+better otherwise — so answer with exact numbers, all in WORLD meters, and nothing outside the JSON.Environment (for light/path context only — do not restate it):{{ environment }}## The zone- Name: {{ zone.name }}-- Bbox: x {{ '%.1f'|format(zone.bbox.min[0]) }}..{{ '%.1f'|format(zone.bbox.max[0]) }}, z {{ '%.1f'|format(zone.bbox.min[2]) }}..{{ '%.1f'|format(zone.bbox.max[2]) }} — every cluster centre stays INSIDE it.-- Description (binding, including its density counts): {{ zone.description }}+- Bbox: x {{ '%.1f'|format(zone.bbox.min[0]) }}..{{ '%.1f'|format(zone.bbox.max[0]) }}, z {{ '%.1f'|format(zone.bbox.min[2]) }}..{{ '%.1f'|format(zone.bbox.max[2]) }} — every cluster centre is validated against it (1 m of slack).+- Description: {{ zone.description }}+ (what the brief fixes in it is binding; its dressing counts are the director's intent and may+ be adjusted to the space, the activity and the triangle budget.)-Neighbouring zones (do not place into them):+Neighbouring zones (their bboxes, where their own builders place):{% for n in neighbours %}- {{ n }}{% endfor %}-## Authored cameras (the shots this scene is graded on — their first metres MUST stay clear)+## Authored cameras (the shots this scene is graded on){% for c in cameras %}- {{ c }}-{% endfor %}No cluster centre may sit within ~2 m + half the asset's footprint of any camera position —-a counter placed at a camera puts the lens INSIDE the geometry and caps the whole run.-Foreground framing near a camera is the zone builder's hand-placed job, never a cluster.+{% endfor %}A cluster whose footprint reaches a camera position puts the lens INSIDE the geometry and caps+the whole run (measured: half the asset's footprint + half the spread + 0.4 m, at least 0.8 m);+anything meant to stand close to a camera is placed by hand in the zone module, not as a cluster.## Assets to place (measured sizes){% for a in assets %}- {{ a }}@@ -28,10 +31,11 @@ WHAT TO PRODUCE (JSON, fields: {{ schema_fields }}):- `placements` — one row per contents asset (split an asset into 2-3 rows when it appears indistinct spots): `count`, `cluster` (x, z), `spread_m`, `faces` (what they look at — a path,a doorway, an azimuth), `support` (`ground`, or the asset they stand ON, e.g. bottles on a- counter). Compose PICTURES, not scatter: things line paths and edges, face what they serve,- stand in clusters with breathing room for the cameras. Respect each asset's footprint — two- clusters closer than the assets are wide will interpenetrate.+ counter). Put things where the place's activity puts them (stalls line the lane and face it;+ boats lie along the quay edge; a well stands alone) and respect each asset's footprint — two+ clusters closer than the assets are wide will interpenetrate (measured).- `path_points` — the walkway through this zone as 2-4 (x, z) points, if the description has one.-- `mid_props`, `small_props`, `ground_cover` — the dressing counts the description demands- beyond the placements (the builder invents WHAT they are; you fix HOW MANY).-- `notes` — one line of intent the builder must keep, e.g. "stalls face the lane, gap at the gate".+- `mid_props`, `small_props`, `ground_cover` — how much loose dressing this zone carries beyond+ the placements (the builder invents WHAT they are; you fix HOW MANY; 0 is right for a bare+ place). The census measures the built zone against these numbers.+- `notes` — one line of intent the builder keeps, e.g. "stalls face the lane, gap at the gate".diff --git a/harness/codeverse3d/prompts/tracks/scene_asset.j2 b/harness/codeverse3d/prompts/tracks/scene_asset.j2index 4f4aef66..07e5f339 100644--- a/harness/codeverse3d/prompts/tracks/scene_asset.j2+++ b/harness/codeverse3d/prompts/tracks/scene_asset.j2@@ -19,9 +19,11 @@ Scene: {{ spec_prompt }}{{ frame_doc }}{{ contract }}- Build the asset standing on the ground (lowest point at z=0), footprint centred on the origin,- total size as stated (±5%). One Blender object per plan part, named exactly as the plan says.-- Materials with colours (Principled BSDF base colour), roughness 0.4-0.8 for wood/stone; one- material per material class (wood / iron / cloth …), never one vertex-painted mesh.+ total size as stated (the check errors beyond 2.5 × or under 0.4 × on any axis). One Blender+ object per plan part, named exactly as the plan says.+- Every surface carries a material with a real base colour and a roughness that matches what it+ is (a grey default reads as `placeholder_material`); one material per material class (wood /+ iron / cloth …) is the usual organisation.{{ detail_advice }}- No camera/light/render/export calls.- MOTION (only when the description names a moving part — a swinging lamp, a turning wheel, a lid@@ -45,37 +47,42 @@ Scene: {{ spec_prompt }}{% else %}## Contract (raw three.js ESM module){{ frame_doc }}-{{ contract }}- `{{ asset_file }}` must `export function build{{ asset_name }}(THREE, opts = {}) { ... return group; }`where `group` is a `THREE.Group` whose lowest point is at y=0 and whose footprint is centred on- the origin, sized as stated (±5%). `opts.seed` (number) and `opts.variant` (0..n) may vary- details deterministically (use a tiny mulberry32 PRNG inside the file — never Math.random).-- Build from primitives (Box/Cylinder/Cone/Sphere/Lathe/Extrude/Tube) with MeshStandardMaterial- colours in hex.+ the origin, sized as stated (the check errors beyond 2.5 × or under 0.4 × the stated size on any+ axis; the zones place it at scale 1, so the stated size is the target). `opts.seed` (number) and+ `opts.variant` (0..n) may vary details deterministically (`mulberry32(seed)` from `../lib/noise.js`+ or a tiny PRNG inside the file — never Math.random).+- Imports: `three`, `three/addons/*`, `../lib/*.js` and your own relative files — no CDN, no other+ package. Forbidden: `document.*` / `window.*`, fetch or XHR, `Math.random()`, `Date.now()` /+ `performance.now()`, `requestAnimationFrame`, creating a renderer. The module is imported and+ built in node (no DOM, no WebGL) the moment it is written: anything that needs a browser throws+ there and the asset is reported broken.+- Procedural geometry built in code (any THREE geometry, including a BufferGeometry you fill+ yourself); no loaded files. Every surface carries a material with a real colour.- Set `group.userData.size = [w, h, d]` to the measured size. Optional animation hook:`group.userData.update = (t, dt) => {...}` (the zone that places you caches it and calls it;`userData.tick` is never called by anything). Amplitudes must be visible after 1.5 s:>= 0.10 rad of rotation or >= 0.05 m of travel — not sub-centimetre jitter.-- Segments 12-24.+- Triangle budget: at most 15 000 triangles for one instance (measured when the module is+ imported and built); segment counts are yours within it.{% if library_rows %}-- The sheet names shipped effect-library factories. `src/lib/` ships with the scene: import them- (`import { makeTree } from '../lib/tree.js'`) and compose what they return into your group- instead of rebuilding them. Each returned object stands on its own origin; place it by that- origin, and pass the lighter options its row names when the asset is repeated.+- The sheet lists shipped effect-library factories that may fit. `src/lib/` ships with the scene+ and is optional: import one (`import { makeTree } from '../lib/tree.js'`) and compose what it+ returns into your group, or build your own. Each returned object stands on its own origin;+ place it by that origin, and pass the lighter options its row names when the asset is repeated.{{ library_rows }}{% endif %}{% endif %}## DO / DON'T- DO use the exact size numbers above; the zone builders rely on them.-- DO give it the 3-4 recognisable features a person would name (a stone lantern: base, post, light- box with 4 windows, curved roof, finial) — plus 2-3 pieces of wear or incident that make it look- used: a chipped corner, a leaning post, moss at the base, a rope, a hanging tool.-- DO make `opts.variant` (0..n) change the SILHOUETTE, not just the scale: at least 3 visibly- different versions (a different crown shape, a different roof pitch, a broken vs whole rail).- Zones rely on this for variety, so a plain `variant` that only scales is a wasted asset.-- DO give any repeated natural asset per-instance hue room: expose `opts.hue`/`opts.tint` (or- accept `opts.seed` and vary the colour from it) so 20 copies are not one colour.+- DO make it recognisable as the named thing at scene distance; the description decides which+ features that takes and whether it looks new or used.+- DO make `opts.variant` (0..n) change the silhouette, not just the scale, when the plan places+ several copies: the judge reads identical copies; how many variants is the plan's count.+- DO give a repeated natural asset colour room across copies (`opts.hue` / `opts.tint`, or a+ colour varied from `opts.seed`) so twenty copies are not one colour.- DON'T model a flat plane with a colour where the thing has real thickness (a fence is stalks andrails, not a textured quad) — closeups are judged.- DON'T leave floating pieces: every sub-shape overlaps a neighbour by ≥ 2 mm.diff --git a/harness/codeverse3d/prompts/tracks/scene_asset_bpy.j2 b/harness/codeverse3d/prompts/tracks/scene_asset_bpy.j2index aed3579f..3ca59349 100644--- a/harness/codeverse3d/prompts/tracks/scene_asset_bpy.j2+++ b/harness/codeverse3d/prompts/tracks/scene_asset_bpy.j2@@ -16,28 +16,28 @@ Scene: {{ spec_prompt }}## Contract (raw bpy module; the harness builds it once and the zones instance it){{ frame_doc }}-{{ contract }}+{{ asset_contract }}- `{{ asset_file }}` must define `def build_{{ asset_file.rsplit('/', 1)[-1][:-3] }}(ctx, variant=0)` that linksevery part into `ctx.collection` (its own Collection, pre-made and active) and returns it: built atthe origin, lowest point on z = 0, footprint centred on the origin, front facing −Y, sized as stated- (±5 %). Zone code places collection instances of `ctx.assets['{{ asset_file.rsplit('/', 1)[-1][:-3] }}']` by+ (the check errors beyond 2.5 × or under 0.4 × on any axis; zones instance it at scale 1). Zone code places collection instances of `ctx.assets['{{ asset_file.rsplit('/', 1)[-1][:-3] }}']` bythat origin and never calls you.-- Build from bmesh (`create_cube` / `create_cone` / `create_icosphere` / `create_circle`, scaled and- translated) and Principled materials with colours (`Base Color`, `Roughness`, `Metallic`; a noise- bump; `lib/materials.py` has the palette) — several parts with distinct materials, each a uniquely- named PascalCase object (one root mesh, or children parented under it with a RELATIVE location).+- Procedural mesh built in code (bmesh or `from_pydata`, any construction); every part carries a+ Principled material with a real colour and roughness (`Base Color`, `Roughness`, `Metallic`;+ `lib/materials.py` is one palette). Objects are uniquely named PascalCase: one root mesh, or+ children parented under it at RELATIVE locations.- `variant` (0..n) and `ctx.rng(seed)` may vary details deterministically; `random.*` is a lint error.-- Segments 10–24; at most 15000 triangles for the whole asset (it is instanced).-- No lights, no cameras, no world, no `bpy.ops` in loops, no file IO; nothing outside the asset- itself (no ground plane).+- At most 15000 triangles for the whole asset (it is instanced; the census counts them).+- No lights, no cameras, no world, no file IO; the lint warns on `bpy.ops.mesh.primitive_*` in a loop;+ nothing outside the asset itself (no ground plane).- MOTION (only when the description names a moving part — a swinging lamp, a turning wheel): keyframethat part's OWN rotation/location on `ctx.frame(0.0)` and `ctx.frame(1.5)` (LINEAR), or a simpledriver of `frame` (`frame * 0.2`); put the part's origin at its pivot. Amplitude must read at scene- distance (≥ 0.15 rad or ≥ 0.05 m).+ distance (≥ 0.15 rad or ≥ 0.05 m registers in the frame difference).{% if library_rows %}-- The sheet names shipped library calls. `src/lib/` ships with the scene: import them- (`from lib.vegetation import tree`) and compose what they build into `ctx.collection` instead of- rebuilding them; every factory takes the collection, a name and a seed.+- The sheet names shipped library calls — optional: `src/lib/` ships with the scene, so you may import+ them (`from lib.vegetation import tree`) and compose what they build into `ctx.collection`; every+ factory takes the collection, a name and a seed.{{ library_rows }}{% endif %}{% if skeleton_files is defined and skeleton_files %}@@ -53,14 +53,12 @@ Scene: {{ spec_prompt }}## DO / DON'T- DO use the exact size numbers above; the zone builders and the placement gate rely on them.-- DO give it the 3–4 recognisable features a person would name (a stone lantern: base, post, light- box with 4 windows, curved roof, finial) — plus 2–3 pieces of wear or incident that make it look- used: a chipped corner, a leaning post, moss at the base, a rope, a hanging tool.-- DO make `variant` (0..n) change the SILHOUETTE, not just the scale: at least 3 visibly different- versions (a different crown shape, a different roof pitch, a broken vs whole rail). Zones rely on- this for variety, so a `variant` that only scales is a wasted asset.-- DO give any repeated natural asset per-instance hue room: vary the colour from `variant` /- `ctx.rng(seed)` so 20 copies are not one colour.+- DO make it recognisable as the named thing at scene distance; the description decides its features+ and its condition.+- DO make `variant` (0..n) differ in SILHOUETTE when several copies are placed (the plan's count decides+ how many); a `variant` that only scales is a wasted asset.+- DO give a repeated natural asset colour room — `variant` / `ctx.rng(seed)`-driven colour is one way —+ so many copies do not read as one colour.- DON'T model a flat plane with a colour where the thing has real thickness (a fence is stakes andrails, not a textured quad) — closeups are judged.- DON'T leave floating pieces: every sub-shape overlaps a neighbour by ≥ 2 mm, and the lowest pointdiff --git a/harness/codeverse3d/prompts/tracks/scene_env.j2 b/harness/codeverse3d/prompts/tracks/scene_env.j2index fb4b747a..200d4019 100644--- a/harness/codeverse3d/prompts/tracks/scene_env.j2+++ b/harness/codeverse3d/prompts/tracks/scene_env.j2@@ -2,27 +2,34 @@Scene: {{ spec_prompt }}Setting: {{ setting }}. Mood: {{ mood }}.-Bounds: {{ bounds }}+Bounds: {{ bounds }} — the region the cameras and the census cover; the world you build extends+past it as far as this setting needs.-## Environment plan (realise these numbers)+## Environment plan (the brief's intent, with target numbers){{ environment }}+The numbers are targets the frame table and the gates check; the form of the world is the brief's.{% if interior and glazed %}-## This is a GLASS HOUSE — the enclosure is yours-The skeleton already builds it: `export const INTERIOR = { center, extents, openings, glazed: true }`-feeds `roomShell()` from `lib/environment.js` — floor (the ground), glass walls and a glass roof on-the bounds' faces, on an iron frame grid (`frameColor`, `bay`), with the land outside built beyond-it. Keep it. Your job: cut the plan's doors as `openings`, tune the frame, and let the SUN do the-lighting — it comes through the glass and the frame throws its grid of shadows on the floor. Never-put an opaque wall or roof around it.+## This is a GLASS HOUSE+It must read as enclosed in glass from every authored camera (judged: enclosed, not a diorama on+a flat plane), with the sun coming through the glazing and the frame throwing its shadows inside.+Name the roof / lid meshes `Ceiling…` / `RoomShell…` so the overview rig can lift them.+`roomShell({ glazed: true, frameColor, bay, openings })` from `lib/environment.js` builds a glazed+box on the room box you give it (the starter's `export const INTERIOR = { center, extents,+openings, glazed: true }` feeds it) — one option; a lean-to, a dome or a vault is yours to build.+Cut the plan's doors as `openings`. What is seen through the glass must be something the brief+implies, never a void or a flat colour.{% elif interior %}-## This is an INTERIOR — the enclosure is yours-The skeleton already builds the room: `export const INTERIOR = { center, extents, openings }` feeds-`roomShell()` from `lib/environment.js` — floor (the ground), four walls and a ceiling on the bounds'-faces. Keep it. Your job: cut the plan's windows and doors as `openings` (face, centre along the-wall / up from the floor, size, metres), glaze or frame them, and LIGHT THE INSIDE (the sun rig is-outside: without openings and practicals a closed room reads black). Measured 2026-09-07 over six-interior runs: with no owner for walls and roof, every one was judged "not enclosed, a diorama on-a flat plane, tool racks floating at a missing wall" (0.0–0.3).+## This is an INTERIOR+It must be enclosed — walls and a ceiling exist from every authored camera. Measured 2026-09-07+over six interior runs: with no owner for walls and roof, every one was judged "not enclosed, a+diorama on a flat plane, tool racks floating at a missing wall" (0.0–0.3). Name the lid meshes+`Ceiling…` / `RoomShell…` so the overview rig can lift them. `roomShell({ center, extents,+openings })` from `lib/environment.js` is one way (a box on the room box you give it; the starter's+`export const INTERIOR = { center, extents, openings }` feeds it); a vault, a tent, a cave or an+irregular room is yours. Cut the plan's windows and doors as openings (face, centre along the+wall / up from the floor, size, metres) and light the inside from the sources the brief names — a+sun rig stays outside, and a closed room with no openings and no practicals renders black and+fails the exposure gate.{% endif %}## Contract@@ -35,68 +42,66 @@ const ctx = { THREE, scene, renderer, loaders, heightAt, assets };const env = (await buildEnv(ctx)) || {}; // ONE argument, and it is ctx (not THREE, not scene)function update(t, dt) { if (env.update) env.update(t, dt); /* then every zone */ }```-So `src/env.js` must export exactly:-- `export function buildEnv(ctx)` — reads `ctx.scene` / `ctx.THREE`, adds sky, lights, ground,- backdrop and water to `ctx.scene`, and **returns an object carrying `update(t, dt)`**:- `{ sun, hemi, sky, ground, water, heightAt, update(t, dt) {} }`. A separate `tickEnv` export is- NEVER called — animated sky/water/fog uniforms must be driven from the returned `update`.-- `export function heightAt(x, z)` — terrain height (0 for flat ground), deterministic and cheap;- every zone places things with it. The PATH is part of this function (flatten it there) so props- on the path sit on the path.-- `export const BOUNDS = { min: [x, y, z], max: [x, y, z] }` from the plan bounds.+So the interface of `src/env.js` is three exports:+- `export function buildEnv(ctx)` — reads `ctx.scene` / `ctx.THREE`, adds whatever this brief's+ environment is (its sky or ceiling, its light, its ground or floor, its atmosphere; water or a+ backdrop only if the brief's world has them) to `ctx.scene`, and **returns an object carrying+ `update(t, dt)`** — the only env hook the assembler calls. A separate `tickEnv` export is+ NEVER called; animated sky / water / fog uniforms are driven from the returned `update`.+- `export function heightAt(x, z)` — the surface height every zone seats on (deterministic, cheap;+ `0` for a flat floor). Any walkable surface the brief has (a path, a road, a terrace, a deck) is+ part of it so what stands on it seats on it: the placement gate measures against it, so it has+ to agree with the ground mesh. A route the zones must agree with (a lane, a towpath) is part of+ `heightAt`, or exported from here as the one ground authority — the name is yours.- `export const SUN_AZIMUTH_DEG = <number>` — read by the harness (regex) to put the overviewcameras on the sun side. Omit it and the overview rig shoots into the sun.-- `export const MATS = { ... }` — shared `MeshStandardMaterial`s (stone, wood, leaf, water, metal)- with hex colours so zones look coherent.+Anything else you export (shared materials, a water level, the route) is a convention between you+and the zones, read by nothing in the harness.-## What this module is graded on-The chapters behind these rules are printed in full at the end of this brief-(**Recipes**) — copy their numbers and snippets; do not invent your own.--1. **Ground must not be one flat colour.** The skeleton already ships the library's ground- (`ground()` from `lib/terrain.js`: textured, displaced, level inside `CONTENT_RADIUS` and- rolling beyond, and `heightAt` IS its height function): tune its material, relief, scale and- `flat` areas and carve the path in both height and colour — never replace it with a- single-colour `MeshStandardMaterial` plane, a scored defect (`flat_ground`).-2. **No world edge.** The skeleton already closes the world: `worldShell()` (sky gradient, the- horizon's silhouette ring, fog the colour of the horizon — `scene.fog` and `scene.background` are its)- and `makeOutskirts()` (relief, fields and copses between the content and the ridge). Set- `MOOD`, the shell's `zenith` / `horizon` and the outskirts' `colors` to the brief; replace- the ridge only with something of the brief's own (rooftops, mesas, a treeline) and keep- fog == horizon == background, the land reaching past fog far. Scale fog to THIS scene, not- to a 100 m default.- Two rules decide whether that ring reads as a hazy horizon or as cardboard:- - Build it from SOLID geometry (cones, boxes, mesas). Flat `PlaneGeometry` cut-outs are- instantly readable as cardboard from every oblique and overview camera.- - Do NOT lerp its colour toward the fog colour. `scene.fog` already hazes it by distance;- tinting as well double-applies and, against a light golden/overcast horizon, makes the- backdrop BRIGHTER than the ground — measured, and scored as `placeholder_material`.- Use its natural colour darkened (`base.multiplyScalar(0.6-0.8)`) and let fog do the rest.-3. **The floor stays near y = 0.** The plan's camera heights are absolute metres above y = 0- and were written before your terrain existed: keep `heightAt` within about +/-1.5 m of 0- inside the bounds (a knoll or a pond basin is fine, a 7 m plateau is not), or the harness- reports "camera N m below ground level" and caps the score at 0.50.- Ponds, terraces, lawns and gravel beds are CARVED INTO `heightAt` (a radial depression, a- shallow shelf) — never a hard-edged disc or square laid on top of the ground, which always- shows its outline from the overview cameras.-4. **Coloured atmosphere, not monochrome.** Warm key + cool fill (or the reverse) with >= 60- degrees of hue between them (`sunColor` vs `fillSky` on the rig); shade must carry sky- colour, never black — with the sun below 25 degrees elevation keep the rig's `fill` >= 1.0- or the shadows render pitch black and trip the `unlit_or_blown` defect (cap 0.60). Add 3-4 haze bands- (`depthWrite:false`, opacity 0.04-0.10, fog colour) for aerial perspective, and light shafts- if the brief mentions sun through something.-4b. **Keep `scene.environment`.** The skeleton lights the scene with `sunRig()` from- `lib/environment.js` and assigns its `envTex` to `scene.environment`; metals and glass read- from that map and render near black without it. Change the mood/azimuth through the rig's- options, not by replacing it with bare lights.-5. **Shadows must not be jagged.** `sunRig` fits the shadow camera, map size and bias to its- `bounds`: pass the content radius (the plan bounds, not the whole ground) and never set- `sun.shadow.*` by hand.+## What is measured on this module+1. **The ground reads as this setting's surface.** The judge flags `flat_ground` where the+ setting would show variation (material blending, wear along routes, undressed seams) and the+ ground is one flat colour; a paved yard, a snowfield or a concrete floor is legitimately+ uniform. The landform is the brief's — a street is flat and paved, a hillside slopes through+ the content, a quarry steps down — with one measured constraint: every plan camera's height is+ absolute, so at each camera position `heightAt` stays below the eye (the gate reports+ "camera N m below ground level" and caps the score at 0.50; `src/scene.js` is assembled with+ the plan's numbers, so the land under the camera is this module's only lever).+2. **The world does not end in frame.** From no authored camera may the ground end against the+ sky or a void (judge defect `world_edge_visible`; the frame census reports "terrain ends N m+ ahead"). Measured on exteriors: standing geometry ≥ 2 m tall out to ≥ 1.25 × the bounds+ half-extent (`world_edge`), fog far ≥ 2 × the plan span (`fog_short`), `scene.fog` and+ `scene.background` set (`no_fog` / `no_background`), and ≥ 8 same-size copies evenly round the+ edge is a `stamped_ring`. What continues the world is the setting's: a street's next block,+ more forest, open sea, a wall, a skyline on one side, a range in one direction, haze that+ closes. Whatever stands at a distance must not read as cardboard (judge+ `placeholder_material`): flat billboards do; volumes, or far ground that simply continues+ under fog, do not. Measured A/B: distant forms hand-lerped toward a light fog colour render+ BRIGHTER than the terrain; natural colour, darkened, left to the fog, reads as receding haze.+3. **Surface features meet the ground.** Where a pond, terrace, bed or lawn meets the terrain+ its edge must not read as an outline lying on the ground from the overview cameras (judge:+ `flat_ground`, `floating_asset` / `sunken_asset`); carving it into `heightAt`, edging it, or a+ setting that justifies a flat slab (a paved terrace) are all ways. Inside a shoreline the+ terrain lies below the water level or the shore z-fights.+4. **Light that passes the exposure band and matches the brief.** Every authored camera must+ pass the frame gate (mean luminance ≥ 0.12, or low-key with luminance std ≥ 0.12; blown+ ≤ 20 %; no single band > 85 %). Shade must carry colour, not crush to black (`dark_frac`),+ and the light must not read as monochrome (judged) — a key / fill hue split is one way+ when the brief's weather allows it; an overcast or sodium-lit scene is legitimately+ low-contrast. `scene.environment` must be an environment texture (metals and glass render+ near black without one). `sunRig()` from `lib/environment.js` gives a fitted key, hemisphere+ fill, env map, disc and shadows for a sunlit exterior in one call — one option; any light set+ that passes the gate and matches the brief's sources is as good.+ Aerial perspective is judged (`thin_atmosphere`: "horizon with no atmospheric falloff"): fog+ does most of it; `makeHeightFog` / `patchAerialPerspective` in `lib/atmosphere.js` are optional+ extras, kept subtle or the frame reads milky (`blown_frac`).+5. **Shadows are not jagged** (judged): a shadow texel ≤ ~0.05 m over the content.+ `sunRig({ bounds })` fits frustum, map size and bias to the radius it is given — pass the+ content radius, not the ground size; a hand-set `sun.shadow.*` must meet the same texel size.6. No {% if not (textures is defined and textures) %}textures, no {% endif %}DOM, no fetch, no Math.random.## DON'T- No assets/zones here (they come from other modules). No cameras. No `scene.background` image loads.-- Do not re-declare the path polyline in a zone: export it (or `distToPath`) from here.## Effects planned (only the ones targeting the environment){{ effects }}@@ -104,19 +109,14 @@ The chapters behind these rules are printed in full at the end of this brief## Tools{{ tool_cards }}-After editing run `build`, then `scene_views` and LOOK: is the horizon hazy, is the ground-multi-coloured, is the shade coloured rather than black? Read the frame table it prints:-every authored camera must pass the exposure checks.+After editing run `build`, then `scene_views` and LOOK: does the world end anywhere in view, is+the ground one flat colour where the setting would vary, is the shade black? Then read the frame+table it prints: every authored camera must pass the exposure checks.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}diff --git a/harness/codeverse3d/prompts/tracks/scene_env_bpy.j2 b/harness/codeverse3d/prompts/tracks/scene_env_bpy.j2index e9872456..c9775c8d 100644--- a/harness/codeverse3d/prompts/tracks/scene_env_bpy.j2+++ b/harness/codeverse3d/prompts/tracks/scene_env_bpy.j2@@ -4,25 +4,26 @@ Scene: {{ spec_prompt }}Setting: {{ setting }}. Mood: {{ mood }}.Bounds (Z up, −Y front, metres — already converted from the plan): {{ bounds }}-## Environment plan (realise these numbers; its prose is Y-up: "y up" there is z here, "+z" there is −y here)+## Environment plan (the brief's intent with its target numbers — checked by the frame table and the gates; its prose is Y-up: "y up" there is z here, "+z" there is −y here){{ environment }}{% if interior and glazed %}## This is a GLASS HOUSE — the enclosure is yours-Build the glass walls and roof on the bounds' faces with `room_shell(ctx.collection, frame_mat,-center=…, extents=…, thickness=0.2, openings=(…), glazed=True)` from `lib/architecture.py` — an iron-frame grid with glass panes, named `RoomShell…` / `Ceiling…` so the overview rig can lift the lid-— cut the plan's doors as openings, and let the SUN do the lighting: it comes through the glass and-the frame throws its grid of shadows on the floor. Never put an opaque wall or roof around it.+The place must read enclosed in glass from every authored camera and be lit by what comes through it+(the frame gate's luminance band). Name the shell and lid meshes `RoomShell…` / `Ceiling…` so the+overview rig can lift the lid, and cut the plan's doors as openings. `room_shell(ctx.collection,+frame_mat, center=…, extents=…, thickness=0.2, openings=(…), glazed=True)` from `lib/architecture.py`+builds an iron-frame box with glass panes on the bounds' faces if that is the brief's shape; other+shapes are yours to build.{% elif interior %}## This is an INTERIOR — the enclosure is yours-Build the room on the bounds' faces with `room_shell(ctx.collection, wall_mat, center=…, extents=…,-thickness=0.2, openings=(…))` from `lib/architecture.py` — floor, four walls and a ceiling named-`RoomShell…` / `Ceiling…` (the overview rig lifts the lid by name). Cut the plan's windows and doors-as openings (face, centre along the wall / up from the floor, size, metres), glaze or frame them, and-LIGHT THE INSIDE: an Area light per window aimed into the room, practicals where the brief has lamps-(the sun is outside: without openings and lights a closed room reads black). Measured 2026-09-07-over six interior runs: with no owner for walls and roof, every one was judged "not enclosed, a-diorama on a flat plane, tool racks floating at a missing wall" (0.0–0.3).+An interior must read enclosed from every authored camera (measured 2026-09-07 over six interior runs+with no owner for walls and roof: every one was judged "not enclosed, a diorama on a flat plane",+0.0–0.3) and be LIT INSIDE (the frame gate's luminance band; the sun is outside, so a closed room+without openings and lights reads black). Name the lid meshes `RoomShell…` / `Ceiling…` (the overview+rig lifts the lid by name); windows and doors are openings the zones glaze or frame.+`room_shell(ctx.collection, wall_mat, center=…, extents=…, thickness=0.2, openings=(…))` from+`lib/architecture.py` is the box option (an opening = face, centre along the wall / up from the floor,+size, metres); the room's shape and extent are the brief's.{% endif %}## Contract@@ -37,48 +38,51 @@ ctx.env = out if isinstance(out, dict) else {} # what the zones read as ctx.enctx.height_at = env.height_at # THE ground every zone seats on```So `{{ env_file }}` must define exactly:-- `def height_at(x, y) -> z` — the terrain height (0.0 for flat ground), deterministic and cheap; every- zone places things with it, so the PATH, a pond basin and a terrace are carved INTO it (then what- stands on the path stands on the path). Keep it within about ±1.5 m of 0 inside the bounds: the- plan's camera heights are absolute.-- `def build_env(ctx) -> dict` — builds the world (sky), the Sun lamp, the ground mesh (sampled from- `height_at`, named `Ground…`), the atmosphere (a bounded fog volume) and the backdrop (a sky-named- horizon ring) into `ctx.collection`, and RETURNS the dict zones share: `{"ground_material": …,- "sun_direction": (x, y, z), "water_level": …, "palette": …}`.-- module constants `SUN_AZIMUTH_DEG` (compass: 0 = +X, 90 = +Y) and `SUN_ELEVATION_DEG` — zones and- the harness's overview rig read the sun side from them.-The world (`bpy.data.worlds.new`, `ctx.scene.world =`) is YOURS and nobody else's: a zone that-builds one fails the lint. No cameras (the plan's), no `scene.render.*`, no frame changes.+- `def height_at(x, y) -> z` — the ground every zone seats on, deterministic and cheap; any walkable+ surface the brief's place has (a path, a terrace, a pond basin, a floor) is part of it, so what stands+ there stands on it. Under every plan camera position the ground stays below the camera (gate+ `camera_underground`, cap 0.50); otherwise the landform is the brief's — a floor, a slope, a basin, a+ street, a cliff are all valid.+- `def build_env(ctx) -> dict` — builds the world (sky), the scene's sun or moon lamp if the brief has+ one, the ground mesh (sampled from `height_at`, named `Ground…`), the atmosphere the probe requires (a+ volume) and whatever continues the world past the content (far geometry named `Sky…` so the census files+ it as backdrop) into `ctx.collection`, and RETURNS the dict zones read as `ctx.env` — e.g.+ `{"ground_material": …, "sun_direction": (x, y, z), "water_level": …}`; the keys are yours to name.+- Module-level names zones may `from env import …` (the skeleton's `SUN_AZIMUTH_DEG` / `SUN_ELEVATION_DEG`,+ compass 0 = +X / 90 = +Y, are one example).+The world (`bpy.data.worlds.new`, `ctx.scene.world =`) is YOURS and nobody else's: a zone that builds one+fails the lint. No cameras (the plan's), no `scene.render.*`, no frame changes.-## What this module is graded on-The chapters behind these rules are printed in full at the end of this brief (**Recipes**) — copy-their numbers and snippets; the shipped `lib/` does each in one call (the catalog follows).--1. **Ground must not be one flat colour.** Three or four colours blended by height, slope and- noise (a `FLOAT_COLOR` attribute read by an Attribute node, or `lib.terrain.ground` with- `lib.materials.mineral_surface`), relief from `lib.terrain.make_height_at`, the path carved into- `height_at` in both height and colour — never a single-colour plane, a scored defect- (`flat_ground`).-2. **No world edge.** The ground reaches ≥ 2.5 × the plan span; the fog box covers all of it in the- sky's HORIZON colour (`lib.sky.haze`); a sky-named silhouette ring (`SkyRidge`: hills, rooftops,- mesas, a treeline — solid geometry, never flat cut-outs) at ~0.6 × the visible range in its own- colour DARKENED 0.6–0.8 × — the fog hazes it, never tint it yourself.-3. **The floor stays near z = 0** (rule above): a knoll or a pond basin is fine, a 7 m plateau puts- every plan camera underground (`camera_underground`, cap 0.50). Ponds, terraces and gravel beds- are CARVED INTO `height_at`, never a hard-edged disc laid on the ground.-4. **Coloured atmosphere, not monochrome.** The brief's time of day as the recipes' numbers: a- physical sky world (`lib.sky.sun_world`, MULTIPLE_SCATTERING) or a deep flat colour for night,- a Sun lamp of 1–5 W/m² (`lib.lighting.sun`; a moon at 0.05–0.3), the world strength 0.1–0.6, the- fog 0.003–0.008. A warm sun under a cool sky is the whole trick; shade must carry sky colour,- never black — with the sun under 25° keep the world strength ≥ 0.2 or the frame trips- `dark_frame` (cap 0.55). Exposure is fixed at 0 and the harness owns it.-5. **Shadows must read.** The Sun's `angle` 1–3° (soft but defined); never a second Sun to fill — the- sky world is the fill.-6. No {% if not (textures is defined and textures) %}image textures, no {% endif %}file IO, no `bpy.ops` in loops, no unseeded randomness (`ctx.rng(seed)`).+## What this module is graded on (the requirement, and how it is measured)+1. **The ground reads as the brief's material**, not one flat untextured colour (judge `flat_ground`: no+ blending, no wear, undressed seams). Paving, snow, sand, decking, mud, a tiled floor all count; a+ height / slope / noise colour blend (`lib.terrain.ground` + `lib.materials.mineral_surface`) is one tool+ among others.+2. **The world does not end in view.** From no authored camera may the ground stop against the sky or a+ backdrop float (judge `world_edge_visible`; the frame census reports "terrain ends N m ahead"). Two+ gates measure it outdoors: `world_edge` (standing geometry must reach past 1.25 × the bounds'+ half-extent) and `fog_short` (the census reads the volume's density: 1 / density has to stay ≥ span / 1.5). What+ continues the world is the brief's place — a street, a sea, a cliff, a forest, walls, hills on one side+ and open sky on another; far geometry is named `Sky…`, standing geometry is seated, and nothing is+ pre-tinted toward the fog (it reads as cardboard: judge `placeholder_material`).+3. **No plan camera below the ground** (`camera_underground`, cap 0.50): `height_at` under every camera+ position stays below its z. A ground feature must not read as a plate laid on the terrain from the+ overview cameras (judge `flat_ground`): carving it into `height_at` or giving it a built edge both work.+4. **Every authored frame lands in the exposure band** at the brief's time of day (`dark_frame`: mean+ luminance < 0.12 or > 35 % near-black, cap 0.55; blown frames likewise) and the light is not monochrome+ (judged). Cycles is physical. Starting values that have passed on a mid-albedo ground: a Sun of+ 1–5 W/m² (a moon 0.05–0.3), a world (`lib.sky.sun_world`, or a deep colour for night) at strength+ 0.1–0.6, fog density 0.003–0.008 (`lib.sky.haze`); a brief lit by fire, neon, storm or nothing sets+ its own and reads `camera_checks.mean_lum`. Exposure is fixed at 0.+5. **Shadows read and shade carries colour** (judge `unlit_or_blown`, `lighting_atmosphere`: "flat+ shadows", "black shade"; the gate's `dark_frac`): a Sun `angle` of 1–3° with the sky world as fill is one+ way; any fill lamp you add is yours to justify by the frame table.+6. No {% if not (textures is defined and textures) %}image textures, no {% endif %}file IO, no unseeded randomness (`ctx.rng(seed)`); the lint warns on `bpy.ops.mesh.primitive_*` in a loop.## DON'T- No assets or zones here (they come from other modules). No cameras. No `scene.*` render / view settings.-- Do not re-declare the path polyline in a zone: export it (or a `dist_to_path`) from here.+- A route the zones must agree with (a lane, a towpath) is part of `height_at`, or a module-level name+ here that zones import — the one ground authority; the name is yours.## Effects planned (only the ones targeting the environment){{ effects }}@@ -86,20 +90,15 @@ their numbers and snippets; the shipped `lib/` does each in one call (the catalo## Tools{{ tool_cards }}-After editing run `build`, then `scene_views` and LOOK: is the horizon hazy, is the ground-multi-coloured, is the shade coloured rather than black? Read the frame table it prints:-every authored camera must pass the exposure checks. `scene_probe` says whether the world+After editing run `build`, then `scene_views` and LOOK at every frame against the brief: does the+world end anywhere in view, is the ground one flat colour, is the shade black? Read the frame table+it prints: every authored camera must pass the exposure checks. `scene_probe` says whether the worldand the atmosphere were found.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}diff --git a/harness/codeverse3d/prompts/tracks/scene_refine.j2 b/harness/codeverse3d/prompts/tracks/scene_refine.j2index c8a7f26b..32a52608 100644--- a/harness/codeverse3d/prompts/tracks/scene_refine.j2+++ b/harness/codeverse3d/prompts/tracks/scene_refine.j2@@ -38,33 +38,34 @@ Animation: {{ animation }}## Reminders{{ frame_doc }}-- A lighting/mood/ground/horizon change lives in `src/env.js` (sun colour/intensity/azimuth, fog- colour + near/far, sky hex, ground vertex colours, backdrop ring).+- A lighting / atmosphere / terrain / horizon change lives in `src/env.js`.- A composition/camera change lives in `src/scene.js` (camera position/lookAt/fov numbers only).- A zone change lives in its `src/zones/<zone>.js` (`export function build(ctx)`, animation on`group.userData.update`); an asset change in `src/assets/<asset>.js`.- Console/shader errors: fix the named module; never wrap in try/catch to hide them.-- Everything rests on `heightAt(x, z)`; nothing floats or sinks; InstancedMesh for repeats.-- No DOM, no textures, no fetch, no Math.random, no CDN imports.+- Everything is seated on `heightAt(x, z)` or the structure it stands on; nothing floats or sinks;+ stay inside the draw / triangle budget `scene_probe` reports.+- No DOM, no fetch, no Math.random, no CDN imports; textures only via `loaders.texture` for files+ in the workspace or procedural DataTextures.-## The recurring defects on this track and the cookbook chapter that fixes each-Do not re-explain the problem back — apply the recipe (the named chapters are printed in full-under **Recipes** at the end of this brief) and change the numbers. If the judge repeated an issue from the previous round, the earlier fix was too-timid: double the amplitude / the count / the contrast this time.+## The recurring findings on this track, and what each one measures+Do not re-explain the problem back — change the thing the finding measures. If a measured+finding repeats from the previous round, re-read its number and change what it measures until+the number passes; a judge note that repeats needs a visible change in the named view.-| what the judge wrote | fix it with |+| what the judge or gate wrote | the requirement behind it ||---|---|-| flat / one-colour ground, no paths, hard raised-bed edges | `"Ground that reads real"` — vertex-colour blend, carve the path into `heightAt`, dress the seams |-| a hard world edge against the sky, missing horizon | `"Horizon: the world must not end"` — ground ≥ 2.4 × fog far, fog = sky horizon colour, silhouette ring at 0.6 × fog far |-| the backdrop looks like flat / beige / untextured cut-outs | same chapter, rules 4-5 — solid geometry, darken the base colour, never lerp it toward the fog colour |-| a pond / terrace is a hard-edged plane sitting on the ground | carve it into `heightAt` in `src/env.js` and dress the seam (`"Ground that reads real"`) |-| "camera is N m below ground level" | the terrain lifted the floor: flatten `heightAt` toward y = 0 inside the bounds, or add `heightAt(x, z)` to that camera's y in `src/scene.js` |-| identical cones / stacked blocks / primitive repetition | `"Vegetation that reads real"`, `"Rocks, cliffs and boulders that read organic"` — 3+ silhouettes, clustered, scale/hue jitter, no axis-aligned stacks |-| sparse, token, "a diorama on a plane", empty midground | `"Set dressing"` + `"Scene layering"` — hit the per-zone prop counts, add a foreground element 2-4 m from each camera |-| flat / dark / monochrome light, black shade, jagged shadows | `"Atmosphere: time-of-day triads with numbers"` — warm key vs cool fill ≥ 60° apart, shadow texel ≤ 0.05 m |-| frames at t=0 and t=1.5 identical, "nothing moves" | `"Motion you can SEE between t = 0 and t = 1.5 s"` — the hook is `userData.update` (never `tick`), amplitudes from the table |-| `hard_edged_particles`, "sharp-edged quads / spheres / discs for steam, dust, sparks", the brief's "soft particle effect" must-item unverified | `"Soft particles"` — `makeSmoke` / `makeSteam` / `makeMotes` / `makeFire`, or a `softDot` sprite on every point; never a bare `PointsMaterial` or a chain of spheres |-| camera inside geometry / shows only sky or a wall | move the camera in `src/scene.js` and mask scatter within ~4 m of it (`cameraMask`) |+| flat / one-colour ground, no paths, hard raised-bed edges | the surface needs visible variation that matches the brief (material, relief, wear) where the setting would show it (judge `flat_ground`) |+| a hard world edge against the sky, missing horizon | from no camera may the ground end against the sky (`world_edge_visible`; the gate reads standing geometry to 1.25 × the bounds half-extent, fog far ≥ 2 × the plan span); what continues the world is the brief's — the street keeps going, the sea, a cliff, a forest, a city, a wall, or fog that closes |+| the backdrop looks like flat / beige / untextured cut-outs | distant forms need volume and shading consistent with the sky's light (judge `placeholder_material`); aerial perspective comes from the fog, not from pre-tinting the material toward it |+| a pond / terrace is a hard-edged plane sitting on the ground | a water body or terrace must meet the ground without a visible hard seam (judge); carving the terrain or dressing the edge are two options |+| "camera is N m below ground level" | the eye must be ≥ 0.3 m above the ground under it: compute the camera's y from `heightAt(x, z)` (or the floor it stands on) in `src/scene.js` |+| identical cones / stacked blocks / primitive repetition | the judge reads identical copies and primitive stacks; vary silhouette, scale and colour where the brief has natural variety (a planted avenue or a container stack IS regular — the brief decides) |+| sparse, token, "a diorama on a plane", empty midground | the description's contents are requirements (the census compares them: `missing_content`, `zone_empty`; a count under half the layout's is an INFO `density_note`); "sparse / diorama" means the frame has empty regions the brief would fill — fill them with what the brief implies |+| flat / dark / monochrome light, black shade, jagged shadows | flat / dark frames are measured (mean lum, std, flat band); jagged shadows mean shadow texels larger than ~0.05 m over the content — tighten the frustum (`sunRig({ bounds })` with the content radius); the light's colours are the brief's time of day and sources |+| frames at t=0 and t=1.5 identical, "nothing moves", `no_motion` | a camera moves when ≥ 0.4 % of its pixels change by more than 8/255 (or ≥ 0.08 % by more than 60/255); none moving is the gate's `no_motion` ERROR and the judge's `nothing_moves`; the hook is `userData.update` (never `tick`), and the amplitude has to show at 1024×576 (foliage ±0.10–0.20 rad, particles ≥ 0.6 m per 1.5 s, water ≥ 3 cm or a scrolling normal are amplitudes that have passed) |+| `hard_edged_particles`, "sharp-edged quads / spheres / discs for steam, dust, sparks", the brief's "soft particle effect" must-item unverified | the finding measures sharp-edged particle sprites; any soft-edged construction passes (the library's `makeSmoke` / `makeSteam` / `makeMotes` / `makeFire` volumes, or a radial-alpha sprite on every point) |+| camera inside geometry / shows only sky or a wall | the eye must be ≥ 0.5 m from every surface and the frame ≥ 10 % content (20 % for the establishing view): move the camera in `src/scene.js` or what blocks it |{% if current_files %}## Current file contents (edit and return each COMPLETE)@@ -84,16 +85,5 @@ finish only when both are clean. `check_placement` measures floating / sunken /interpenetrating assets deterministically — its numbers, not your impression. `scene_views` prints theframe table and the MEASURED MOTION per camera — use those numbers, not your impression.{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — the chapters for the files you own; copy their numbers)-{{ recipes }}-{% endif %}--{% if effects_catalog is defined and effects_catalog %}--{{ effects_catalog }}-{% endif %}-## Output{{ output_format }}diff --git a/harness/codeverse3d/prompts/tracks/scene_refine_bpy.j2 b/harness/codeverse3d/prompts/tracks/scene_refine_bpy.j2index 31516bce..3481ef26 100644--- a/harness/codeverse3d/prompts/tracks/scene_refine_bpy.j2+++ b/harness/codeverse3d/prompts/tracks/scene_refine_bpy.j2@@ -39,9 +39,8 @@ Animation: {{ animation }}## Reminders{{ frame_doc }}-- A lighting/mood/ground/horizon change lives in `{{ env_file }}` (the world, `SUN_AZIMUTH_DEG` /- `SUN_ELEVATION_DEG` and the Sun's energy, the fog box's density and colour, the ground's blend,- the sky-named backdrop ring).+- A lighting / atmosphere / terrain / horizon change lives in `{{ env_file }}` (the world, the sun or+ moon lamp, the atmosphere volume, the ground and `height_at`, whatever continues the world).- A composition/camera change is the plan's: `{{ entry_file }}` is harness data — move the SUBJECT(a zone's placement) rather than the camera.- A zone change lives in its `src/zones/<zone>.py` (`def build(ctx)`, motion as keyframes on@@ -49,31 +48,30 @@ Animation: {{ animation }}(`build_<asset>(ctx, variant=0)`).- A dropped zone / asset (`zone_error`, `asset_error`): fix the named line; never wrap the wholebuilder in try/except to hide it.-- Everything rests on `ctx.height_at(x, y)` or on its support (`lib.place.seat`); nothing floats,- sinks or runs through a neighbour (`lib.place.clear_of`); repeats are collection instances.+- Everything rests on `ctx.height_at(x, y)` or on its support (`lib.place.seat` or your own seating);+ nothing floats, sinks or runs through a neighbour (`lib.place.clear_of`).- No world or cameras outside `{{ env_file }}`, no file IO, no `random.*`, no Python drivers.-## The recurring defects on this track and the cookbook chapter that fixes each-Do not re-explain the problem back — apply the recipe (the named chapters are printed in full-under **Recipes** at the end of this brief) and change the numbers. If the judge repeated an issue-from the previous round, the earlier fix was too timid: double the amplitude / the count / the-contrast this time.+## The recurring findings on this track — what each measures, and where the requirement is stated+Do not re-explain the problem back — change what the finding measures. If a measured finding repeats,+change what it measures until its number passes; a repeated judge note needs a visible change in the+named view. The skills named below are in your session's skill list; the contract is above.-| what the judge wrote | fix it with |-|---|---|-| flat / one-colour ground, no paths, hard raised-bed edges | `"Ground that reads real"` — the colour-attribute blend, carve the path into `height_at`, dress the seams |-| a hard world edge against the sky, missing horizon | `"Horizon: the world must not end"` — ground ≥ 2.5 × the span, fog = the sky's horizon colour, a `SkyRidge` at 0.6 × the visible range |-| the backdrop looks like flat / beige / untextured cut-outs | same chapter, rules 4–5 — solid geometry, darken the base colour, never tint it toward the fog |-| a pond / terrace is a hard-edged plane sitting on the ground | carve it into `height_at` in `{{ env_file }}` and dress the seam (`"Ground that reads real"`); water is `"Water"` |-| `floating` / `sunken` / `interpenetration` / `unsupported` (the placement gate's metres) | `"Placement self-check"` — `lib.place.seat` / `rest_on`, `clear_of`; a rock may sit a third in, a crate may not |-| "camera is N m below ground level" / `camera_in_geometry` | the terrain lifted the floor: flatten `height_at` toward z = 0 inside the bounds, or move the thing in front of the lens |-| identical cones / stacked blocks / primitive repetition | `"Vegetation that reads real"`, `"Rocks, cliffs and boulders that read organic"` — 3+ silhouettes, clustered, scale / hue jitter, no axis-aligned stacks |-| sparse, token, "a diorama on a plane", empty midground | `"Set dressing"` + `"Scene layering"` — hit the per-zone prop counts, add a foreground element 2–4 m from each camera |-| flat / dark / monochrome light, black shade, `dark_frame` | `"Atmosphere: time-of-day triads with numbers"`, `"Dusk / night lighting recipe"`, `"Lighting for Cycles + AgX"` — the table's sun / world / fog numbers, practicals with a radius |-| frames at t=0 and t=1.5 identical, "nothing moves", `nothing_moves` | `"Motion you can SEE between t = 0 and t = 1.5 s"` — LINEAR keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)`, amplitudes from the table; `python_driver` = a driver that needs Python, rewrite it as `frame * k` |-| `hard_edged_particles`, "sharp-edged quads / spheres / discs for steam, dust, sparks", the brief's "soft particle effect" must-item unverified | `"Soft particles"` — `lib.materials.volume` on a `Batch` of subdivision-3 spheres, tagged free, drifting ≥ 0.6 m; never a translucent Principled puff, metaball, torus or disc |-| "plastic", "one grey material", `placeholder_material` | `"Materials: Principled recipes and the lib palette"` — a colour and a roughness on every surface, a noise bump, wood grain, the lib palette |-| `zone_error` / `asset_error` (a dropped module) | the named `file:line` — fix the raise; Blender 5.2 facts in `"Traps"` (no `use_nodes`, `Factor` not `Fac`, `ShaderNodeMix`, `Action.fcurves` is gone, GN inputs via `mod.properties.inputs`) |+| what the judge / gate wrote | the requirement (and how it is measured) | stated in |+|---|---|---|+| flat / one-colour ground, hard raised-bed edges | the surface needs visible variation that matches the brief's material, and its seams dressed (judge `flat_ground`) | the env brief § 1; skill `c3d-bpy-scene-materials` |+| a hard world edge against the sky, missing horizon | from no camera may the ground end against the sky (`world_edge_visible`; gates `world_edge` / `fog_short`); what continues the world is the brief's — street, sea, cliff, forest, wall, fog | contract § What else the gates measure; skill `c3d-scene-atmosphere` |+| the backdrop looks like flat / beige / untextured cut-outs | a distant backdrop needs volume and lighting consistent with the sky; aerial perspective is the fog's job, never a pre-tint (`placeholder_material`) | skill `c3d-scene-atmosphere` |+| a pond / terrace is a hard-edged plane sitting on the ground | water and terraces meet the ground without a visible seam: carving into `height_at` (`{{ env_file }}`) or dressing the seam (the zone) are options; water is named `…Water` | skill `c3d-scene-water`; skill `c3d-bpy-scene-placement` |+| `floating` / `sunken` / `interpenetration` / `unsupported` (the placement gate's metres) | `lib.place.seat` / `rest_on`, `clear_of` — or your own seating through the same foot columns; a rock may sit a third in, a crate may not | contract § Placement; skill `c3d-bpy-scene-placement` |+| "camera is N m below ground level" / `camera_in_geometry` | the eye must be above the ground under it and ≥ 0.5 m from any surface: move the subject or the zone's placement; the landform is the brief's | contract § What else the gates measure |+| identical cones / stacked blocks / primitive repetition | identical copies and primitive stacks are what the judge reads (`monotonous_vegetation`); vary where the brief has natural variety, regular things stay regular | the zone brief § 2 |+| sparse, token, "a diorama on a plane", empty midground | the brief's stated counts are requirements (the census compares them); empty regions the brief would fill get what it implies (`undressed_scene`, `empty_midground`) | the zone brief § 1; skill `c3d-scene-composition` |+| flat / dark / monochrome light, black shade, `dark_frame` | measured per camera (`mean_lum` / `dark_frac` / `blown_frac`); the brief's time of day and light sources decide; the lighting skill lists starting values that have passed | skill `c3d-bpy-scene-lighting`; skill `c3d-scene-night` |+| frames at t=0 and t=1.5 identical, "nothing moves", `nothing_moves` | the frame difference is measured per camera: LINEAR keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` or `frame * k`; `python_driver` = a driver that needs Python, rewrite it | contract § Motion; skill `c3d-scene-motion` |+| `hard_edged_particles`, "sharp-edged quads / spheres / discs for steam, dust, sparks", the brief's "soft particle effect" must-item unverified | the finding measures sharp-edged particle geometry: in Cycles only a volume renders edgeless (`lib.materials.volume` on a `Batch` is one way), one root tagged free, moving ≥ 0.6 m | contract § What the renderer does |+| "plastic", "one grey material", `placeholder_material` | flags a surface with no authored colour / roughness; every surface needs a material that matches what it is (the lib palette is one source) | skill `c3d-bpy-scene-materials` |+| `zone_error` / `asset_error` (a dropped module) | the named `file:line` — fix the raise; Blender 5.2 facts (no `use_nodes`, `Factor` not `Fac`, `ShaderNodeMix`, `Action.fcurves` is gone, GN inputs via `mod.properties.inputs`) | contract § Blender 5.2 API facts |{% if current_files %}## Current file contents (edit and return each COMPLETE)@@ -93,16 +91,6 @@ finish only when both are clean. `check_placement` measures floating / sunken /interpenetrating assets deterministically — its numbers, not your impression. `scene_views` prints theframe table and the MEASURED MOTION per camera — use those numbers, not your impression.{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — the chapters for the files you own; copy their numbers)-{{ recipes }}-{% endif %}--{% if effects_catalog is defined and effects_catalog %}--{{ effects_catalog }}-{% endif %}## Output{{ output_format }}diff --git a/harness/codeverse3d/prompts/tracks/scene_zone.j2 b/harness/codeverse3d/prompts/tracks/scene_zone.j2index 0f4f9466..e17155e2 100644--- a/harness/codeverse3d/prompts/tracks/scene_zone.j2+++ b/harness/codeverse3d/prompts/tracks/scene_zone.j2@@ -3,38 +3,47 @@Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}## This zone-- Description (density counts and depth role are binding): {{ zone_description }}-- Bbox: {{ zone_bbox }} — place EVERYTHING inside it (x/z), on the ground via `heightAt`.-{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.js`'s `roomShell` on the scene bounds' faces —- never build walls or a roof here. Fixtures on a wall sit flush against the inner face of the bounds;- a window or door is an OPENING env cut, so glazing and door leaves go in the opening, not through the wall.+- Description (the brief's facts in it are binding; its counts are the layout's intent, checked against the census): {{ zone_description }}+- Bbox: {{ zone_bbox }} — the planned contents are measured against it and the plan bounds (a planned+ content entirely outside the bounds + max(5 m, 10 % of the span) is `out_of_bounds`, a WARN; scenery+ may continue past it as the place implies), and every placed root object is seated on the surface+ it stands on — terrain via `heightAt`, or a structure (a shelf, a roof, a deck). Deliberately+ airborne things carry `userData.placement = 'free'`.+{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.js`'s — do not build walls or a roof here.+ Fixtures on a wall sit flush against its inner face; a window or door is an OPENING env cuts, so+ glazing and door leaves go in the opening, not through the wall.{% endif %}- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from primitives)' }}-- Every builder returns its asset AT THE SIZE the asset API states; place it at scale 1 (per-instance jitter- within +/-30 %, never a re-size to "fit"). The placement gate measures every placed thing against the- plan's size, and a mismatch is a finding the judge repeats (measured 2026-09-08, round 0: a 1.15 m stove- placed at 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the round). The same gate measures a placed- asset as ONE object, parts included: never stretch or re-scale a part of a placed clone (a stove whose- flue you pulled up to the roof reads as a 4.8 m stove — three runs lost their round to it); a chimney,- pipe or cable that must reach further is a SEPARATE object you add beside it.--{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world meters)+- Every builder returns its asset AT THE SIZE the asset API states; place it at scale 1. The+ placement gate measures every placed thing as ONE object, parts included, against the plan's+ `approx_size_m`: a WARN beyond 2.5 × (or under 1 / 2.5), an ERROR beyond 4 × (`scale`), and the+ judge's `wrong_scale` on top (measured 2026-09-08, round 0: a 1.15 m stove placed at 3.60 m,+ 0.48 m oil lamps at 0.03 m — both cost the round; a stove whose flue was pulled up to the roof+ read as a 4.8 m stove — three runs lost their round to it). Never re-scale to "fit", never+ stretch a part of a placed clone; a chimney, pipe or cable that must reach further is a+ SEPARATE object you add beside it.++{% if layout is defined and layout %}## Zone director's layout (the contents it names are measured as present; its positions and counts are the director's proposal in world metres — keep them unless the place reads better otherwise){{ layout }}-{% endif %}Neighbouring zones (do not build into them):+{% endif %}Neighbouring zones (their builders place there; a thing of yours running into a thing of theirs+is an `interpenetration` row like any other):{% for n in neighbours %}- {{ n }}{% endfor %}--Authored cameras that will photograph this scene (keep their first metres clear, and give the-ones that look at this zone a foreground element):+{% if shared is not defined or shared %}+Authored cameras that will photograph this scene — nothing this zone builds may sit inside or+right against one (`scene_views` reports `camera_in_geometry`, the eye's clearance from every+surface — ≥ 0.5 m — and `camera_blocked`: 6 of the 9 sight rays ending within 1.5 m); what, if+anything, frames a shot is this zone's choice:{{ cameras }}## Assets available (sizes are measured, meters w×h×d){{ asset_api }}Those paths are written relative to `src/`; **from `src/zones/` prefix them with `../`**-(`import { buildStoneLantern } from '../assets/stone_lantern.js';`). Shared materials and the-terrain come from the environment: `import { MATS, heightAt } from '../env.js';` (or use-`ctx.heightAt`). A GLB asset is already loaded for you at `ctx.assets['<snake_name>']` — add+(`import { buildStoneLantern } from '../assets/stone_lantern.js';`). The terrain comes from the+environment (`ctx.heightAt`, or `import { heightAt } from '../env.js'`), and so does whatever else+`env.js` chose to export (shared materials, a water level, a route — its names, read+`src/env.js`). A GLB asset is already loaded for you at `ctx.assets['<snake_name>']` — add`.clone()` of it, never `loaders.gltf` again. A clone that carries clips (a keyframed Blender part) playsthem by itself; set `clone.userData.clipOffset = <seconds>` to de-phase copies. There is no `ctx.rand` and no `ctx.MATS`.@@ -54,39 +63,51 @@ So `{{ zone_file }}` exports `export function build(ctx) → THREE.Group` named`userData.update`, cache it at build time and call it from the zone's `userData.update`.`ctx` also gives you `ctx.env` (whatever `buildEnv` returned) and `ctx.heightAt`.-## What this zone is graded on-The recipes for all five points below are printed in full at the end of this brief-(**Recipes**) — copy their numbers and snippets; do not invent your own.--1. **Hit the density counts in the description.** A zone with 5 objects in it reads as a token- gesture; the counts are the difference between 0.5 and 0.8. Props go **against** things- (path edges, wall bases, under benches, in corners), never in a grid or a perfect ring, with- >= 20 % positional jitter and full yaw jitter.-2. **Variation, not clones.** Any repeated natural element needs >= 3 distinct silhouettes- (different geometry, not just scale), per-instance scale jitter +/-30 %, hue jitter +/-0.03- via `setColorAt`, full yaw jitter and a few degrees of lean. Clustered placement (cluster- seeds + members around them), never uniform scatter and never a ring of identical cones.-3. **Blend into the ground.** Anything that meets the terrain sinks 3-5 cm into it and gets- 6-15 dressing pieces along the seam (tufts, pebbles, leaves). A raised bed gets a chamfered- kerb, not a naked box on grass. NEVER lay a hard-edged disc or square (a pond, a gravel- bed, a terrace, a lawn patch) flat on top of the ground: use the depression `heightAt`- already carves for it and ring the seam with a kerb + dressing, or its outline shows from- every overview camera (`flat_ground` / `floating_or_sunken_asset`). Add the zone's share of- ground cover (300-800 instanced tufts for a planted zone) unless the description says bare.-4. **Serve the cameras.** Skip any SCATTER instance inside a ~4 m disc around an authored camera- (write a zero-scale matrix, keep the index; `cameraMask` in the cookbook) — a tree 1 m in front- of the establishing camera ruins the shot. Then, by hand (not scatter, so the mask does not- remove it), place ONE element 2.5-4 m from a camera that looks across this zone, off to one- side, as its foreground frame.-5. **Motion that shows.** Amplitudes from the Recipes table (foliage +/-0.10-0.20 rad, particles- >= 0.6 m per 1.5 s). The harness DIFFERENCES the t=0 and t=1.5 frames pixel by pixel and- reports the number: too small a change counts as `nothing_moves` (-0.05 and the animation- criterion). Sub-centimetre sway is invisible at 1024x576. Give this- zone at least one motion big enough to see across the frame, and everything a pure function of `t`.-6. Use `InstancedMesh` for anything repeated > 5x.+## What is measured on this zone+1. **The description's contents are present.** `check_placement` compares what is placed against+ the plan: a planned asset not placed is `missing_content`, an empty group is `zone_empty`, a zone+ under half the instances its layout counted gets an INFO `density_note`; the judge+ compares the frame against the description (`missing_planned_element`, `empty_zone`). Where+ the description gives no count, dress to what this setting would contain — the judge flags+ `undressed_scene` by perception, not by number. Place props where the setting puts them;+ regular arrangements only where the brief or setting implies them (a formal parterre, a row of+ parked scooters, a colonnade), otherwise expect the judge to read an unmotivated grid or ring+ as identical copies (`monotonous_vegetation`, `diorama_look`).+2. **Repeated things read as individuals** where the setting has natural variety (judge:+ `monotonous_vegetation`, "identical copies", "primitive stacks"); the brief decides whether they+ grow in clusters, rows, an orchard or a canopy. The assets' `variant` / `seed` / `hue` options+ exist for this; several geometries plus scale / hue / yaw variation is one way.+3. **Everything is seated.** `check_placement` reports a foot > 0.05 m above its surface+ (0.02 m indoors) as `floating` (ERROR at 0.08 m) and > 0.10 m below as `sunken` (ERROR at+ 0.20 m); two boxes sharing > 10 % of the smaller one as `interpenetration` (ERROR at 35 %).+ One placed thing = one direct child of the zone group: a Group holding several props is+ measured as ONE box, their union, and every prop inside it reads as interpenetrating it; a+ prop built from parts is one Group; many of one thing is one `InstancedMesh`. A scattered+ instance inside a placed thing is an interpenetration at 100 % of the smaller box — scatter+ clear of what you placed. A wide flat thing on a slope is measured at its lowest vertices+ against the ground under THEM: conform each piece to `heightAt` or split it. How a seam reads+ is the setting's call; the judge flags a visibly hovering base as `floating_asset` / `sunken_asset`+ and a ground feature that reads as a plate lying on the ground as `flat_ground`.+4. **The cameras stay clear.** No authored camera may be inside or blocked by what this zone+ builds (`camera_in_geometry`, `camera_blocked`; both cap the run at 0.50); how you keep the+ near field clear is yours.+5. **Motion that shows.** The harness differences the t = 0 and t = 1.5 s frames of every camera+ and reports the number: 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` (−0.05 and the animation criterion). Sub-centimetre sway is invisible+ at 1024×576. What moves is the brief's; give this zone at least one motion big enough to see+ across the frame, everything a pure function of `t`, driven from `userData.update`. Particles+ must be soft-edged (judge `hard_edged_particles`: bare `PointsMaterial` squares, a chain of+ spheres for a steam jet, polygon sparks all fire it, and with it the brief's "soft particle+ effect" must-item) — the library's volumes or a radial-alpha sprite both pass.+6. **Budget.** Stay inside the draw-call / triangle budget `scene_probe` reports (WARN above 5 000+ draws, ERROR above 15 000; 3 000 000 unique triangles); `InstancedMesh` / `mergeStatic` are the cheap+ ways to repeat.## DON'T-- No lights except small point lights for lanterns; no cameras; no sky/ground here.+- Sun, sky, ground and cameras are the env's. This zone may add the practical lights its setting+ contains (a lantern, a neon sign, a forge, a campfire), within the exposure band and the perf+ budget — a shadow-casting light per practical is the usual budget blow-out.- No DOM, {% if not (textures is defined and textures) %}no textures, {% endif %}no fetch, no Math.random (`mulberry32(seed)` from `lib/noise.js`).- Do not import assets marked NOT AVAILABLE; do not edit other files.{% if tool_cards and not single_shot %}@@ -95,20 +116,15 @@ The recipes for all five points below are printed in full at the end of this bri{{ tool_cards }}After editing run `build` → `check_placement` (it names every asset that floats, is sunken,touches nothing or interpenetrates another, with the exact "lower X by 0.23 m onto Terrain"-fix; a deliberately airborne thing gets `obj.userData.placement = 'free'`) → fix → `build`-again, then `scene_views` and LOOK at the frames: count the silhouettes, look-for a flat colour under your props, and read the MEASURED MOTION line it prints — if it reports your-zone's cameras as STATIC, double the amplitude and render again.+fix; a deliberately airborne thing gets `obj.userData.placement = 'free'`) → fix every row →+`build` again, then `scene_views`: check that each authored frame shows what the description+says, and read the MEASURED MOTION line it prints — if it reports your zone's cameras as+STATIC, double the amplitude and render again.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}@@ -116,3 +132,4 @@ zone's cameras as STATIC, double the amplitude and render again.## Output{{ output_format }}+{% endif %}diff --git a/harness/codeverse3d/prompts/tracks/scene_zone_bpy.j2 b/harness/codeverse3d/prompts/tracks/scene_zone_bpy.j2index 23620a34..9e605b48 100644--- a/harness/codeverse3d/prompts/tracks/scene_zone_bpy.j2+++ b/harness/codeverse3d/prompts/tracks/scene_zone_bpy.j2@@ -3,29 +3,33 @@Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}## This zone-- Description (density counts and depth role are binding): {{ zone_description }}-- Bbox (Z up, −Y front, metres — already converted from the plan): {{ zone_bbox }} — place EVERYTHING- inside it (x/y), on the ground via `ctx.height_at(x, y)` or on the surface it stands on.-{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.py`'s `room_shell` on the scene bounds' faces —- never build walls or a roof here. Fixtures on a wall sit flush against the inner face of the bounds;- a window or door is an OPENING env cut, so glazing and door leaves go in the opening, not through the wall.+- Description (the brief's facts in it are binding; its counts are the layout's intent, checked against the placement census): {{ zone_description }}+- Bbox (Z up, −Y front, metres — already converted from the plan): {{ zone_bbox }} — placed assets are+ measured against it and the plan bounds (a planned content entirely outside the bounds + max(5 m, 10 % of the+ span) is `out_of_bounds`, a WARN; scenery may continue past them as the place implies); seat each on+ the ground via `ctx.height_at(x, y)` or on the surface it stands on.+{% if interior %}- INTERIOR: the shell (floor, walls, lid) is `env.py`'s; a partition, counter or alcove this zone needs+ is yours, seated and clear of the shell (placement gate). A window or door is an OPENING env cut:+ glazing and door leaves go in the opening, not through the wall.{% endif %}- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from bmesh)' }}-- Every asset in `ctx.assets` is a Collection AT THE SIZE the asset API states; place it at scale 1- (per-instance jitter within ±30 %, never a re-size to "fit"). The placement gate measures every- placed thing against the plan's size, and a mismatch is a finding the judge repeats (measured- 2026-09-08, round 0: a 1.15 m stove placed at 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the- round). The same gate measures a placed asset as ONE object: never stretch a part of an instance; a- chimney, pipe or cable that must reach further is a SEPARATE object you add beside it.+- Every asset in `ctx.assets` is a Collection AT THE SIZE the asset API states and is measured as ONE+ object against the plan's `approx_size_m`: a WARN beyond 2.5 × (or under 1 / 2.5), an ERROR beyond 4 ×+ (`scale`), and the judge's `wrong_scale` on top (measured 2026-09-08, round 0: a 1.15 m stove placed at+ 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the round). Never re-scale to fit or stretch a part of+ an instance; a chimney, pipe or cable that must reach further is a SEPARATE object you add beside it.-{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world metres (x, y) in THIS frame)+{% if layout is defined and layout %}## Zone director's layout (the contents it names are measured as present; its positions and counts are the director's proposal, world metres (x, y) in THIS frame — keep them unless the place reads better otherwise){{ layout }}-{% endif %}Neighbouring zones (do not build into them):+{% endif %}Neighbouring zones (their builders place there; a thing of yours running into a thing of theirs is an+`interpenetration` row like any other):{% for n in neighbours %}- {{ n }}{% endfor %}--Authored cameras that will photograph this scene (Z up, metres; keep their first metres clear, and-give the ones that look at this zone a foreground element):+{% if shared is not defined or shared %}+Authored cameras that will photograph this scene (Z up, metres; nothing may sit inside or within+0.5 m of a lens — `scene_views` camera_checks, `camera_in_geometry` cap 0.50 — and no more than 5 of a+camera's 9 sight rays may end within 1.5 m, `camera_blocked`, the same cap; the framing is this zone's+choice):{{ cameras }}## Assets available (sizes are measured, metres)@@ -33,10 +37,11 @@ give the ones that look at this zone a foreground element):Place one with `instance(ctx.collection, ctx.assets['<snake>'], unique_name('Name', i), x, y,height_at=ctx.height_at, rot_z=…)` from `lib/scatter.py` + `lib/place.py` (a collection-instance-Empty seated on the ground = ONE placement row), or scatter many with `scatter(...)`. Shared materials-and the terrain come from the environment: `ctx.env['ground_material']`, `ctx.env['sun_direction']`,-`ctx.height_at`; zones may also `from env import SUN_AZIMUTH_DEG`. A hero GLB is already imported for-you as `ctx.assets['<snake>']` — instance it, never import a file. There is no `ctx.rand` and no+Empty seated on the ground = ONE placement row), or scatter many with `scatter(...)`, or build your+own collection-instance Empties. Shared materials and the terrain come from the environment:+`ctx.env[...]` (the keys `build_env` returned), `ctx.height_at`; zones may also `from env import …`+whatever `env.py` defines at module level. A hero GLB is already imported for you as+`ctx.assets['<snake>']` — instance it, never import a file. There is no `ctx.rand` and no`ctx.materials`; randomness is `rng = ctx.rng(<seed>)`.## Contract@@ -54,43 +59,50 @@ So `{{ zone_file }}` defines `def build(ctx) -> bpy.types.Collection` that linksAnimation is DATA: keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` and simple drivers of `frame`(`lib/motion.py`); there is no per-frame hook.-## What this zone is graded on-The recipes for the points below are printed in full at the end of this brief (**Recipes**) — copy-their numbers and snippets; the `lib/` catalog does each in one call.--1. **Hit the density counts in the description.** A zone with 5 objects in it reads as a token- gesture; the counts are the difference between 0.5 and 0.8. Props go **against** things (path- edges, wall bases, under benches, in corners), never in a grid or a perfect ring, with ≥ 20 %- positional jitter and full yaw jitter (`lib.scatter.scatter`, `along_path`, `poisson`).-2. **Variation, not clones.** Any repeated natural element needs ≥ 3 distinct silhouettes- (`lib.vegetation.tree` kinds, `shrub`, `fern`; `lib.terrain.boulder` seeds), per-instance scale- jitter ±30 %, hue jitter (`lib.materials.tint` or `ob.color` through an Object Info node), full yaw- jitter and a few degrees of lean. Clustered placement, never uniform scatter, never a ring of- identical cones.-3. **Seated, and clear of each other — measured.** Every placed root object: its feet on- `ctx.height_at` or on what it stands on (`lib.place.seat`, `rest_on`; gap ≤ 0.02 m), sunk 3–5 cm- where it meets soil, with 6–15 dressing pieces along the seam. Run `lib.place.clear_of(objs)` before- you finish: two boxes sharing > 10% of the smaller one are `interpenetration` (ERROR at 35%), a- foot 0.05 m up is `floating` (ERROR at 0.08 m), a foot 0.10 m under is `sunken` (ERROR at 0.20 m).+## What this zone is graded on (the requirement, and how it is measured)+1. **What the description names is here.** Counts the plan states are compared with the placement+ census (`missing_planned_element`, `empty_zone`), and a place that reads as sparse for what the brief+ describes is judged `undressed_scene`. Place props where the setting puts them; regular arrangements+ only where the brief implies them. `lib.scatter` offers `scatter`, `along_path`, `poisson`, `grid`+ if you want them.+2. **Repeated natural elements read as individuals** from the cameras (judge `monotonous_vegetation`:+ one shape stamped many times, in a ring or a grid). The lib's `tree` kinds, `shrub`, `fern`,+ `boulder` seeds, `materials.tint` and per-instance rotation / scale are one way; regular things (a+ colonnade, a row of bollards) stay regular.+3. **Seated, and clear of each other — measured.** Every placed root object rests on the surface it+ stands on (`lib.place.seat` / `rest_on`, or your own seating — the gate samples the foot columns):+ a foot 0.05 m up is `floating` (ERROR at 0.08 m), 0.10 m under is `sunken` (ERROR at 0.20 m), two+ boxes sharing > 10 % of the smaller one are `interpenetration` (ERROR at 35 %). Run+ `lib.place.clear_of(objs)` over your roots AND the neighbours' placed things before you finish.`obj["placement"] = "free"` only for things that hang in the air; the share of tagged things is- reported. NEVER lay a hard-edged disc (a pond, a gravel bed, a terrace) flat on the ground: use the- depression `height_at` already carves for it and ring the seam with a kerb + dressing.-4. **Serve the cameras.** Skip any SCATTER point inside a ~4 m disc around an authored camera (the- `camera_mask` recipe) — a tree 1 m in front of the establishing camera ruins the shot. Then, by- hand, place ONE element 2.5–4 m from a camera that looks across this zone, off to one side, as its- foreground frame.-5. **Motion that shows.** Amplitudes from the Recipes table (foliage ±0.10–0.20 rad, a mover ≥ 0.6 m- per 1.5 s), as keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` (LINEAR) or a simple driver of- `frame`. The harness DIFFERENCES the t=0 and t=1.5 frames pixel by pixel and reports the number:- too small a change counts as `nothing_moves`. Give this zone at least one motion big enough to see- across the frame.-6. **One object = one thing; names unique.** A multi-part prop is one mesh or one parent Empty with- children; repeats are collection instances; the hundreds (blades, pebbles, litter) are a- geometry-nodes cloud (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`). Every placed copy- `unique_name(base, i)`; never `bpy.ops` in a loop.+ reported. A built thing on soil must not read as pasted on (judge `flat_ground`: undressed seams):+ a few centimetres of sink (the gate allows up to 0.10 m) or dressing along the seam are options; a+ ground feature (a pond, a bed, a terrace) must not read as a plate on the terrain from the overview+ cameras — carving in `height_at` (the env's) or a built edge both work.+4. **The cameras stay clear.** No authored camera may be inside or blocked by what this zone builds+ (`scene_views` camera_checks: nothing within 0.5 m of a lens, `camera_in_geometry`; 6 of 9 sight+ rays within 1.5 m, `camera_blocked` — each an ERROR capped at 0.50). `lib.place.clear_mask` / a+ poisson `mask` keeps scatter out of any region you choose. Framing is yours.+5. **Motion that shows.** The harness DIFFERENCES the t=0 and t=1.5 frames per camera and reports the+ number: 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), the judge's `nothing_moves`.+ Keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` (LINEAR) or a simple driver of `frame`; what moves+ is the brief's (amplitudes that have registered at 1024 × 576: ≥ 0.10 rad, ≥ 0.05 m, a particle /+ leaf / boat ≥ 0.6 m per 1.5 s).+6. **One root = one thing; names unique.** `check_placement` measures each root object in+ `ctx.collection` as one placed thing: a multi-part prop has one root (a mesh, a parent Empty, a+ collection instance) and every root a unique name (`unique_name(base, i)`). Stay inside the triangle+ budget `scene_probe` reports; collection instances and geometry-nodes clouds+ (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`) are the cheap ways to repeat, and the lint+ warns on `bpy.ops.mesh.primitive_*` inside a loop.+7. **A soft particle has no silhouette.** In Cycles only a volume renders without an edge+ (`lib.materials.volume`); a translucent surface puff, metaball, torus or disc is graded+ `hard_edged_particles` and fails the brief's must-item. It is one root tagged free, and it moves+ ≥ 0.6 m between the two frames.## DON'T-- No world, no sun, no cameras, no ground here (the env's); lights only as practicals and the odd window.+- No world, no sun, no cameras, no ground here (the env's; the lint rejects a world in a zone); the local+ lights the brief's place has are yours.- No file IO, {% if not (textures is defined and textures) %}no image textures, {% endif %}no `random.*` (`ctx.rng(seed)`), no Python drivers, no `scene.*` settings.- Do not place assets marked NOT AVAILABLE; do not edit other files.{% if tool_cards and not single_shot %}@@ -100,19 +112,13 @@ their numbers and snippets; the `lib/` catalog does each in one call.After editing run `build` → `check_placement` (it names every asset that floats, is sunken, touchesnothing or interpenetrates another, with the exact "lower X by 0.23 m onto Ground" fix; adeliberately airborne thing gets `obj["placement"] = "free"`) → fix → `build` again, then-`scene_views` and LOOK at the frames: count the silhouettes, look for a flat colour under your-props, and read the MEASURED MOTION line it prints — if it reports your zone's cameras as STATIC,-double the amplitude and render again.+`scene_views` and LOOK at the frames against the brief, and read the MEASURED MOTION line it prints —+STATIC means this zone's motion is below the threshold.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}@@ -122,3 +128,4 @@ check_existing=True)` into an Image Texture node; the build runs with the worksp## Output{{ output_format }}+{% endif %}diff --git a/harness/codeverse3d/prompts/variants/argon/README.md b/harness/codeverse3d/prompts/variants/argon/README.mdindex 88b5565a..16269238 100644--- a/harness/codeverse3d/prompts/variants/argon/README.md+++ b/harness/codeverse3d/prompts/variants/argon/README.md@@ -2,7 +2,7 @@This directory is a **variant** (D105, 2026-10-14): an overlay on `codeverse3d/prompts/`.A file placed here shadows the base file of the same relative path for every run that-activates the variant — `scene_threejs/cookbook.md` here replaces the base cookbook,+activates the variant — `scene_threejs/system.md` here replaces the base system prompt,`tracks/scene_zone.j2` the zone template — and a file that is not here is read from the base.A template here may `include` or `extends` a base file (the variant's loader falls through tothe base directory).diff --git a/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone.j2 b/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone.j2index ef1ccf0d..d0a2092e 100644--- a/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone.j2+++ b/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone.j2@@ -3,38 +3,47 @@Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}## This zone-- Description (density counts and depth role are binding): {{ zone_description }}-- Bbox: {{ zone_bbox }} — place EVERYTHING inside it (x/z), on the ground via `heightAt`.-{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.js`'s `roomShell` on the scene bounds' faces —- never build walls or a roof here. Fixtures on a wall sit flush against the inner face of the bounds;- a window or door is an OPENING env cut, so glazing and door leaves go in the opening, not through the wall.+- Description (the brief's facts in it are binding; its counts are the layout's intent, checked against the census): {{ zone_description }}+- Bbox: {{ zone_bbox }} — the planned contents are measured against it and the plan bounds (a planned+ content entirely outside the bounds + max(5 m, 10 % of the span) is `out_of_bounds`, a WARN; scenery+ may continue past it as the place implies), and every placed root object is seated on the surface+ it stands on — terrain via `heightAt`, or a structure (a shelf, a roof, a deck). Deliberately+ airborne things carry `userData.placement = 'free'`.+{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.js`'s — do not build walls or a roof here.+ Fixtures on a wall sit flush against its inner face; a window or door is an OPENING env cuts, so+ glazing and door leaves go in the opening, not through the wall.{% endif %}- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from primitives)' }}-- Every builder returns its asset AT THE SIZE the asset API states; place it at scale 1 (per-instance jitter- within +/-30 %, never a re-size to "fit"). The placement gate measures every placed thing against the- plan's size, and a mismatch is a finding the judge repeats (measured 2026-09-08, round 0: a 1.15 m stove- placed at 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the round). The same gate measures a placed- asset as ONE object, parts included: never stretch or re-scale a part of a placed clone (a stove whose- flue you pulled up to the roof reads as a 4.8 m stove — three runs lost their round to it); a chimney,- pipe or cable that must reach further is a SEPARATE object you add beside it.--{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world meters)+- Every builder returns its asset AT THE SIZE the asset API states; place it at scale 1. The+ placement gate measures every placed thing as ONE object, parts included, against the plan's+ `approx_size_m`: a WARN beyond 2.5 × (or under 1 / 2.5), an ERROR beyond 4 × (`scale`), and the+ judge's `wrong_scale` on top (measured 2026-09-08, round 0: a 1.15 m stove placed at 3.60 m,+ 0.48 m oil lamps at 0.03 m — both cost the round; a stove whose flue was pulled up to the roof+ read as a 4.8 m stove — three runs lost their round to it). Never re-scale to "fit", never+ stretch a part of a placed clone; a chimney, pipe or cable that must reach further is a+ SEPARATE object you add beside it.++{% if layout is defined and layout %}## Zone director's layout (the contents it names are measured as present; its positions and counts are the director's proposal in world metres — keep them unless the place reads better otherwise){{ layout }}-{% endif %}Neighbouring zones (do not build into them):+{% endif %}Neighbouring zones (their builders place there; a thing of yours running into a thing of theirs+is an `interpenetration` row like any other):{% for n in neighbours %}- {{ n }}{% endfor %}--Authored cameras that will photograph this scene (keep their first metres clear, and give the-ones that look at this zone a foreground element):+{% if shared is not defined or shared %}+Authored cameras that will photograph this scene — nothing this zone builds may sit inside or+right against one (`scene_views` reports `camera_in_geometry`, the eye's clearance from every+surface — ≥ 0.5 m — and `camera_blocked`: 6 of the 9 sight rays ending within 1.5 m); what, if+anything, frames a shot is this zone's choice:{{ cameras }}## Assets available (sizes are measured, meters w×h×d){{ asset_api }}Those paths are written relative to `src/`; **from `src/zones/` prefix them with `../`**-(`import { buildStoneLantern } from '../assets/stone_lantern.js';`). Shared materials and the-terrain come from the environment: `import { MATS, heightAt } from '../env.js';` (or use-`ctx.heightAt`). A GLB asset is already loaded for you at `ctx.assets['<snake_name>']` — add+(`import { buildStoneLantern } from '../assets/stone_lantern.js';`). The terrain comes from the+environment (`ctx.heightAt`, or `import { heightAt } from '../env.js'`), and so does whatever else+`env.js` chose to export (shared materials, a water level, a route — its names, read+`src/env.js`). A GLB asset is already loaded for you at `ctx.assets['<snake_name>']` — add`.clone()` of it, never `loaders.gltf` again. A clone that carries clips (a keyframed Blender part) playsthem by itself; set `clone.userData.clipOffset = <seconds>` to de-phase copies. There is no `ctx.rand` and no `ctx.MATS`.@@ -54,36 +63,46 @@ So `{{ zone_file }}` exports `export function build(ctx) → THREE.Group` named`userData.update`, cache it at build time and call it from the zone's `userData.update`.`ctx` also gives you `ctx.env` (whatever `buildEnv` returned) and `ctx.heightAt`.-## What this zone is graded on-The recipes for all five points below are printed in full at the end of this brief-(**Recipes**) — copy their numbers and snippets; do not invent your own.--1. **Hit the density counts in the description.** A zone with 5 objects in it reads as a token- gesture; the counts are the difference between 0.5 and 0.8. Props go **against** things- (path edges, wall bases, under benches, in corners), never in a grid or a perfect ring, with- >= 20 % positional jitter and full yaw jitter.-2. **Variation, not clones.** Any repeated natural element needs >= 3 distinct silhouettes- (different geometry, not just scale), per-instance scale jitter +/-30 %, hue jitter +/-0.03- via `setColorAt`, full yaw jitter and a few degrees of lean. Clustered placement (cluster- seeds + members around them), never uniform scatter and never a ring of identical cones.-3. **Blend into the ground.** Anything that meets the terrain sinks 3-5 cm into it and gets- 6-15 dressing pieces along the seam (tufts, pebbles, leaves). A raised bed gets a chamfered- kerb, not a naked box on grass. NEVER lay a hard-edged disc or square (a pond, a gravel- bed, a terrace, a lawn patch) flat on top of the ground: use the depression `heightAt`- already carves for it and ring the seam with a kerb + dressing, or its outline shows from- every overview camera (`flat_ground` / `floating_or_sunken_asset`). Add the zone's share of- ground cover (300-800 instanced tufts for a planted zone) unless the description says bare.-4. **Serve the cameras.** Skip any SCATTER instance inside a ~4 m disc around an authored camera- (write a zero-scale matrix, keep the index; `cameraMask` in the cookbook) — a tree 1 m in front- of the establishing camera ruins the shot. Then, by hand (not scatter, so the mask does not- remove it), place ONE element 2.5-4 m from a camera that looks across this zone, off to one- side, as its foreground frame.-5. **Motion that shows.** Amplitudes from the Recipes table (foliage +/-0.10-0.20 rad, particles- >= 0.6 m per 1.5 s). The harness DIFFERENCES the t=0 and t=1.5 frames pixel by pixel and- reports the number: too small a change counts as `nothing_moves` (-0.05 and the animation- criterion). Sub-centimetre sway is invisible at 1024x576. Give this- zone at least one motion big enough to see across the frame, and everything a pure function of `t`.-6. Use `InstancedMesh` for anything repeated > 5x.+## What is measured on this zone+1. **The description's contents are present.** `check_placement` compares what is placed against+ the plan: a planned asset not placed is `missing_content`, an empty group is `zone_empty`, a zone+ under half the instances its layout counted gets an INFO `density_note`; the judge+ compares the frame against the description (`missing_planned_element`, `empty_zone`). Where+ the description gives no count, dress to what this setting would contain — the judge flags+ `undressed_scene` by perception, not by number. Place props where the setting puts them;+ regular arrangements only where the brief or setting implies them (a formal parterre, a row of+ parked scooters, a colonnade), otherwise expect the judge to read an unmotivated grid or ring+ as identical copies (`monotonous_vegetation`, `diorama_look`).+2. **Repeated things read as individuals** where the setting has natural variety (judge:+ `monotonous_vegetation`, "identical copies", "primitive stacks"); the brief decides whether they+ grow in clusters, rows, an orchard or a canopy. The assets' `variant` / `seed` / `hue` options+ exist for this; several geometries plus scale / hue / yaw variation is one way.+3. **Everything is seated.** `check_placement` reports a foot > 0.05 m above its surface+ (0.02 m indoors) as `floating` (ERROR at 0.08 m) and > 0.10 m below as `sunken` (ERROR at+ 0.20 m); two boxes sharing > 10 % of the smaller one as `interpenetration` (ERROR at 35 %).+ One placed thing = one direct child of the zone group: a Group holding several props is+ measured as ONE box, their union, and every prop inside it reads as interpenetrating it; a+ prop built from parts is one Group; many of one thing is one `InstancedMesh`. A scattered+ instance inside a placed thing is an interpenetration at 100 % of the smaller box — scatter+ clear of what you placed. A wide flat thing on a slope is measured at its lowest vertices+ against the ground under THEM: conform each piece to `heightAt` or split it. How a seam reads+ is the setting's call; the judge flags a visibly hovering base as `floating_asset` / `sunken_asset`+ and a ground feature that reads as a plate lying on the ground as `flat_ground`.+4. **The cameras stay clear.** No authored camera may be inside or blocked by what this zone+ builds (`camera_in_geometry`, `camera_blocked`; both cap the run at 0.50); how you keep the+ near field clear is yours.+5. **Motion that shows.** The harness differences the t = 0 and t = 1.5 s frames of every camera+ and reports the number: 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` (−0.05 and the animation criterion). Sub-centimetre sway is invisible+ at 1024×576. What moves is the brief's; give this zone at least one motion big enough to see+ across the frame, everything a pure function of `t`, driven from `userData.update`. Particles+ must be soft-edged (judge `hard_edged_particles`: bare `PointsMaterial` squares, a chain of+ spheres for a steam jet, polygon sparks all fire it, and with it the brief's "soft particle+ effect" must-item) — the library's volumes or a radial-alpha sprite both pass.+6. **Budget.** Stay inside the draw-call / triangle budget `scene_probe` reports (WARN above 5 000+ draws, ERROR above 15 000; 3 000 000 unique triangles); `InstancedMesh` / `mergeStatic` are the cheap+ ways to repeat.## Before you return — what the argon scenes of iteration 0 lost their points toThirty argon three.js scenes were measured on 2026-10-15 (mean 0.76). Every point below is one@@ -91,20 +110,22 @@ tool call away and cost whole rounds:1. **Your LAST `check_placement` of this session shows 0 ERROR rows for this zone.** Everysession ran the check; the rounds that still shipped 29 interpenetration + 9 sunken ERRORsedited again afterwards and never re-checked. Edit → `build` → `check_placement` → fix EVERY- row it names (move the smaller thing 0.3 m clear; lower / raise by the stated metres) → `build`- → `check_placement` again until clean → only then `scene_views`.+ row it names (move the smaller thing until no pair shares more than the gate's 10 %; lower /+ raise by the stated metres) → `build` → `check_placement` again until clean → only then+ `scene_views`.2. **One placed thing = one direct child of the zone group.** A `…MidProps` / `…Dressing` /`SeamDressing` Group holding several props is measured as ONE asset whose box is their union,so every prop inside it reads as interpenetration (11 of 29 rows). Add each prop to the zonegroup itself; a prop built from parts is one Group; hundreds of one thing are one InstancedMesh.-3. **Scatter clear of what you placed** (`keepClear` / `isClear` in the Zones chapter of the- cookbook): a scattered rock, fern or crate inside a placed table, rockery or tower is an- interpenetration at 100 % of the smaller box. A wide flat thing on a slope (a talus field, a- stockpile conveyor) is `sunken` at its uphill end unless each piece follows `heightAt`.-4. **Particles are soft or absent**: `makeSmoke` / `makeSteam` / `makeMotes` / `makeFire`, or- `softDot` sprites (the "Soft particles" chapter below). A bare `PointsMaterial`, a chain of- spheres for a steam jet or polygon sparks is `hard_edged_particles` AND fails the brief's "soft- particle effect" must-item — both fired together in 5 of 30 scenes.+3. **Scatter clear of what you placed**: a scattered rock, fern or crate inside a placed table,+ rockery or tower is an interpenetration at 100 % of the smaller box — keep the boxes of the+ hand-placed things and skip the scatter points that fall inside them. A wide flat thing on a+ slope (a talus field, a stockpile conveyor) is `sunken` at its uphill end unless each piece+ follows `heightAt`.+4. **Particles are soft or absent**: the library's volumes (`makeSmoke` / `makeSteam` /+ `makeMotes` / `makeFire`) or a radial-alpha sprite on every point. A bare `PointsMaterial`, a+ chain of spheres for a steam jet or polygon sparks is `hard_edged_particles` AND fails the+ brief's "soft particle effect" must-item — both fired together in 5 of 30 scenes.5. **A zone that throws at build time is DROPPED and scores nothing** — three runs lost 2-3zones each: `walk(fig, t)` runs ONLY inside `userData.update(t)` (a build-time `walk(fig)`throws `time must be finite`); import only names the effects catalog prints for a module@@ -113,29 +134,27 @@ tool call away and cost whole rounds:your last edit and read its zone list.## DON'T-- No lights except small point lights for lanterns; no cameras; no sky/ground here.+- Sun, sky, ground and cameras are the env's. This zone may add the practical lights its setting+ contains (a lantern, a neon sign, a forge, a campfire), within the exposure band and the perf+ budget — a shadow-casting light per practical is the usual budget blow-out.- No DOM, {% if not (textures is defined and textures) %}no textures, {% endif %}no fetch, no Math.random (`mulberry32(seed)` from `lib/noise.js`).- Do not import assets marked NOT AVAILABLE; do not edit other files.+{% if tool_cards and not single_shot %}## Tools{{ tool_cards }}After editing run `build` → `check_placement` (it names every asset that floats, is sunken,touches nothing or interpenetrates another, with the exact "lower X by 0.23 m onto Terrain"-fix; a deliberately airborne thing gets `obj.userData.placement = 'free'`) → fix → `build`-again, then `scene_views` and LOOK at the frames: count the silhouettes, look-for a flat colour under your props, and read the MEASURED MOTION line it prints — if it reports your-zone's cameras as STATIC, double the amplitude and render again.+fix; a deliberately airborne thing gets `obj.userData.placement = 'free'`) → fix every row →+`build` again, then `scene_views`: check that each authored frame shows what the description+says, and read the MEASURED MOTION line it prints — if it reports your zone's cameras as+STATIC, double the amplitude and render again.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}@@ -143,3 +162,4 @@ zone's cameras as STATIC, double the amplitude and render again.## Output{{ output_format }}+{% endif %}diff --git a/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone_bpy.j2 b/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone_bpy.j2index efdae8de..dd57f1b6 100644--- a/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone_bpy.j2+++ b/harness/codeverse3d/prompts/variants/argon/tracks/scene_zone_bpy.j2@@ -3,29 +3,33 @@Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}## This zone-- Description (density counts and depth role are binding): {{ zone_description }}-- Bbox (Z up, −Y front, metres — already converted from the plan): {{ zone_bbox }} — place EVERYTHING- inside it (x/y), on the ground via `ctx.height_at(x, y)` or on the surface it stands on.-{% if interior %}- INTERIOR: the enclosure (walls, ceiling, roof) is `env.py`'s `room_shell` on the scene bounds' faces —- never build walls or a roof here. Fixtures on a wall sit flush against the inner face of the bounds;- a window or door is an OPENING env cut, so glazing and door leaves go in the opening, not through the wall.+- Description (the brief's facts in it are binding; its counts are the layout's intent, checked against the placement census): {{ zone_description }}+- Bbox (Z up, −Y front, metres — already converted from the plan): {{ zone_bbox }} — placed assets are+ measured against it and the plan bounds (a planned content entirely outside the bounds + max(5 m, 10 % of the+ span) is `out_of_bounds`, a WARN; scenery may continue past them as the place implies); seat each on+ the ground via `ctx.height_at(x, y)` or on the surface it stands on.+{% if interior %}- INTERIOR: the shell (floor, walls, lid) is `env.py`'s; a partition, counter or alcove this zone needs+ is yours, seated and clear of the shell (placement gate). A window or door is an OPENING env cut:+ glazing and door leaves go in the opening, not through the wall.{% endif %}- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from bmesh)' }}-- Every asset in `ctx.assets` is a Collection AT THE SIZE the asset API states; place it at scale 1- (per-instance jitter within ±30 %, never a re-size to "fit"). The placement gate measures every- placed thing against the plan's size, and a mismatch is a finding the judge repeats (measured- 2026-09-08, round 0: a 1.15 m stove placed at 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the- round). The same gate measures a placed asset as ONE object: never stretch a part of an instance; a- chimney, pipe or cable that must reach further is a SEPARATE object you add beside it.--{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world metres (x, y) in THIS frame)+- Every asset in `ctx.assets` is a Collection AT THE SIZE the asset API states and is measured as ONE+ object against the plan's `approx_size_m`: a WARN beyond 2.5 × (or under 1 / 2.5), an ERROR beyond 4 ×+ (`scale`), and the judge's `wrong_scale` on top (measured 2026-09-08, round 0: a 1.15 m stove placed at+ 3.60 m, 0.48 m oil lamps at 0.03 m — both cost the round). Never re-scale to fit or stretch a part of+ an instance; a chimney, pipe or cable that must reach further is a SEPARATE object you add beside it.++{% if layout is defined and layout %}## Zone director's layout (the contents it names are measured as present; its positions and counts are the director's proposal, world metres (x, y) in THIS frame — keep them unless the place reads better otherwise){{ layout }}-{% endif %}Neighbouring zones (do not build into them):+{% endif %}Neighbouring zones (their builders place there; a thing of yours running into a thing of theirs is an+`interpenetration` row like any other):{% for n in neighbours %}- {{ n }}{% endfor %}--Authored cameras that will photograph this scene (Z up, metres; keep their first metres clear, and-give the ones that look at this zone a foreground element):+{% if shared is not defined or shared %}+Authored cameras that will photograph this scene (Z up, metres; nothing may sit inside or within+0.5 m of a lens — `scene_views` camera_checks, `camera_in_geometry` cap 0.50 — and no more than 5 of a+camera's 9 sight rays may end within 1.5 m, `camera_blocked`, the same cap; the framing is this zone's+choice):{{ cameras }}## Assets available (sizes are measured, metres)@@ -33,10 +37,11 @@ give the ones that look at this zone a foreground element):Place one with `instance(ctx.collection, ctx.assets['<snake>'], unique_name('Name', i), x, y,height_at=ctx.height_at, rot_z=…)` from `lib/scatter.py` + `lib/place.py` (a collection-instance-Empty seated on the ground = ONE placement row), or scatter many with `scatter(...)`. Shared materials-and the terrain come from the environment: `ctx.env['ground_material']`, `ctx.env['sun_direction']`,-`ctx.height_at`; zones may also `from env import SUN_AZIMUTH_DEG`. A hero GLB is already imported for-you as `ctx.assets['<snake>']` — instance it, never import a file. There is no `ctx.rand` and no+Empty seated on the ground = ONE placement row), or scatter many with `scatter(...)`, or build your+own collection-instance Empties. Shared materials and the terrain come from the environment:+`ctx.env[...]` (the keys `build_env` returned), `ctx.height_at`; zones may also `from env import …`+whatever `env.py` defines at module level. A hero GLB is already imported for you as+`ctx.assets['<snake>']` — instance it, never import a file. There is no `ctx.rand` and no`ctx.materials`; randomness is `rng = ctx.rng(<seed>)`.## Contract@@ -54,40 +59,46 @@ So `{{ zone_file }}` defines `def build(ctx) -> bpy.types.Collection` that linksAnimation is DATA: keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` and simple drivers of `frame`(`lib/motion.py`); there is no per-frame hook.-## What this zone is graded on-The recipes for the points below are printed in full at the end of this brief (**Recipes**) — copy-their numbers and snippets; the `lib/` catalog does each in one call.--1. **Hit the density counts in the description.** A zone with 5 objects in it reads as a token- gesture; the counts are the difference between 0.5 and 0.8. Props go **against** things (path- edges, wall bases, under benches, in corners), never in a grid or a perfect ring, with ≥ 20 %- positional jitter and full yaw jitter (`lib.scatter.scatter`, `along_path`, `poisson`).-2. **Variation, not clones.** Any repeated natural element needs ≥ 3 distinct silhouettes- (`lib.vegetation.tree` kinds, `shrub`, `fern`; `lib.terrain.boulder` seeds), per-instance scale- jitter ±30 %, hue jitter (`lib.materials.tint` or `ob.color` through an Object Info node), full yaw- jitter and a few degrees of lean. Clustered placement, never uniform scatter, never a ring of- identical cones.-3. **Seated, and clear of each other — measured.** Every placed root object: its feet on- `ctx.height_at` or on what it stands on (`lib.place.seat`, `rest_on`; gap ≤ 0.02 m), sunk 3–5 cm- where it meets soil, with 6–15 dressing pieces along the seam. Run `lib.place.clear_of(objs)` before- you finish: two boxes sharing > 10% of the smaller one are `interpenetration` (ERROR at 35%), a- foot 0.05 m up is `floating` (ERROR at 0.08 m), a foot 0.10 m under is `sunken` (ERROR at 0.20 m).+## What this zone is graded on (the requirement, and how it is measured)+1. **What the description names is here.** Counts the plan states are compared with the placement+ census (`missing_planned_element`, `empty_zone`), and a place that reads as sparse for what the brief+ describes is judged `undressed_scene`. Place props where the setting puts them; regular arrangements+ only where the brief implies them. `lib.scatter` offers `scatter`, `along_path`, `poisson`, `grid`+ if you want them.+2. **Repeated natural elements read as individuals** from the cameras (judge `monotonous_vegetation`:+ one shape stamped many times, in a ring or a grid). The lib's `tree` kinds, `shrub`, `fern`,+ `boulder` seeds, `materials.tint` and per-instance rotation / scale are one way; regular things (a+ colonnade, a row of bollards) stay regular.+3. **Seated, and clear of each other — measured.** Every placed root object rests on the surface it+ stands on (`lib.place.seat` / `rest_on`, or your own seating — the gate samples the foot columns):+ a foot 0.05 m up is `floating` (ERROR at 0.08 m), 0.10 m under is `sunken` (ERROR at 0.20 m), two+ boxes sharing > 10 % of the smaller one are `interpenetration` (ERROR at 35 %). Run+ `lib.place.clear_of(objs)` over your roots AND the neighbours' placed things before you finish.`obj["placement"] = "free"` only for things that hang in the air; the share of tagged things is- reported. NEVER lay a hard-edged disc (a pond, a gravel bed, a terrace) flat on the ground: use the- depression `height_at` already carves for it and ring the seam with a kerb + dressing.-4. **Serve the cameras.** Skip any SCATTER point inside a ~4 m disc around an authored camera (the- `camera_mask` recipe) — a tree 1 m in front of the establishing camera ruins the shot. Then, by- hand, place ONE element 2.5–4 m from a camera that looks across this zone, off to one side, as its- foreground frame.-5. **Motion that shows.** Amplitudes from the Recipes table (foliage ±0.10–0.20 rad, a mover ≥ 0.6 m- per 1.5 s), as keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` (LINEAR) or a simple driver of- `frame`. The harness DIFFERENCES the t=0 and t=1.5 frames pixel by pixel and reports the number:- too small a change counts as `nothing_moves`. Give this zone at least one motion big enough to see- across the frame.-6. **One object = one thing; names unique.** A multi-part prop is one mesh or one parent Empty with- children; repeats are collection instances; the hundreds (blades, pebbles, litter) are a- geometry-nodes cloud (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`). Every placed copy- `unique_name(base, i)`; never `bpy.ops` in a loop.+ reported. A built thing on soil must not read as pasted on (judge `flat_ground`: undressed seams):+ a few centimetres of sink (the gate allows up to 0.10 m) or dressing along the seam are options; a+ ground feature (a pond, a bed, a terrace) must not read as a plate on the terrain from the overview+ cameras — carving in `height_at` (the env's) or a built edge both work.+4. **The cameras stay clear.** No authored camera may be inside or blocked by what this zone builds+ (`scene_views` camera_checks: nothing within 0.5 m of a lens, `camera_in_geometry`; 6 of 9 sight+ rays within 1.5 m, `camera_blocked` — each an ERROR capped at 0.50). `lib.place.clear_mask` / a+ poisson `mask` keeps scatter out of any region you choose. Framing is yours.+5. **Motion that shows.** The harness DIFFERENCES the t=0 and t=1.5 frames per camera and reports the+ number: 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), the judge's `nothing_moves`.+ Keyframes on `ctx.frame(0.0)` / `ctx.frame(1.5)` (LINEAR) or a simple driver of `frame`; what moves+ is the brief's (amplitudes that have registered at 1024 × 576: ≥ 0.10 rad, ≥ 0.05 m, a particle /+ leaf / boat ≥ 0.6 m per 1.5 s).+6. **One root = one thing; names unique.** `check_placement` measures each root object in+ `ctx.collection` as one placed thing: a multi-part prop has one root (a mesh, a parent Empty, a+ collection instance) and every root a unique name (`unique_name(base, i)`). Stay inside the triangle+ budget `scene_probe` reports; collection instances and geometry-nodes clouds+ (`lib.vegetation.grass_patch`, `lib.scatter.gn_scatter`) are the cheap ways to repeat, and the lint+ warns on `bpy.ops.mesh.primitive_*` inside a loop.+7. **A soft particle has no silhouette.** In Cycles only a volume renders without an edge+ (`lib.materials.volume`); a translucent surface puff, metaball, torus or disc is graded+ `hard_edged_particles` and fails the brief's must-item. It is one root tagged free, and it moves+ ≥ 0.6 m between the two frames.## Before you return — what the argon scenes of iteration 0 lost their points toThirty argon Blender scenes were measured on 2026-10-15 (mean 0.75). Every point below is one@@ -95,28 +106,34 @@ tool call away and cost whole rounds:1. **Your LAST `check_placement` of this session shows 0 ERROR rows for this zone.** Everysession ran the check; 13 of 30 picked rounds still shipped interpenetration ERRORs because thezone was edited again afterwards and never re-checked. Edit → `build` → `check_placement` →- fix EVERY row it names (move the smaller thing 0.3 m clear; lower / raise by the stated metres)- → `build` → `check_placement` again until clean → only then `scene_views`.-2. **Scatter clear of what you placed**: `mask = clear_mask(placed_roots, margin=0.3)` from- `lib.place`, then `poisson(rng, area=…, min_dist=…, max_count=…, mask=mask)` (or keep only the- `along_path` / `grid` points with `mask(x, y) > 0`) BEFORE `scatter(...)` — 9 of the 13 were- small props scattered INTO a cart, a rack, a shrub or a salt mound (100 % of the smaller box).- Then `for a, b, frac in clear_of([*roots, *scattered]):` and delete the smaller offender- (`bpy.data.objects.remove`), as the placement self-check chapter shows.+ fix EVERY row it names (move the smaller thing until `clear_of` reports no pair over the gate's+ 10 %; lower / raise by the stated metres) → `build` → `check_placement` again until clean →+ only then `scene_views`.+2. **Scatter clear of what you placed**: 9 of the 13 were small props scattered INTO a cart, a+ rack, a shrub or a salt mound (100 % of the smaller box). Place the big things first, keep every+ scatter point out of their footprints (`mask = clear_mask(placed_roots, margin=0.3)` from+ `lib.place` as the `poisson(..., mask=mask)` argument, or your own test), then+ `for a, b, frac in clear_of([*roots, *scattered]):` and move or delete the smaller offender+ (`bpy.data.objects.remove`) — the placement skill shows the loop.3. **A pit, a bank or a floor you carve in this zone is the ground for what stands in it**: seatthose things on YOUR surface (`rest_on(obj, pit_floor)`), not on `ctx.height_at`, or the gatereads the sheaves 0.4 m sunk and the anchor plates 0.28 m floating (as in one iteration-0 run).-4. **Particles are volumes**: `lib.materials.volume` on a `Batch` of subdivision-3 spheres, tagged- `placement = "free"`, drifting >= 0.6 m (the "Soft particles" chapter below). Translucent+4. **A soft particle has no silhouette**: in Cycles only a volume renders without an edge+ (`lib.materials.volume`; a cloud of `Batch` spheres wearing it is one root). TranslucentPrincipled puffs, metaballs, tori and discs were `hard_edged_particles` in 8 of 30 scenes AND- failed the brief's "soft particle effect" must-item every time.-5. **Stay inside your bbox**: two runs shipped cross-zone overlaps (a wind pump into a salt- mound, a lane prop into a canopy frame); `keep_inside(obj, bbox)` before you return.+ failed the brief's "soft particle effect" must-item every time. Tag the root+ `placement = "free"` and move it ≥ 0.6 m between the two frames.+5. **A cross-zone overlap is an `interpenetration` row like any other**: two runs shipped one (a+ wind pump into a salt mound, a lane prop into a canopy frame). Run `clear_of` over your roots+ and the neighbours' placed things; the bbox is where the plan's contents are measured, not a+ fence.## DON'T-- No world, no sun, no cameras, no ground here (the env's); lights only as practicals and the odd window.+- No world, no sun, no cameras, no ground here (the env's; the lint rejects a world in a zone); the local+ lights the brief's place has are yours.- No file IO, {% if not (textures is defined and textures) %}no image textures, {% endif %}no `random.*` (`ctx.rng(seed)`), no Python drivers, no `scene.*` settings.- Do not place assets marked NOT AVAILABLE; do not edit other files.+{% if tool_cards and not single_shot %}## Tools@@ -124,19 +141,13 @@ tool call away and cost whole rounds:After editing run `build` → `check_placement` (it names every asset that floats, is sunken, touchesnothing or interpenetrates another, with the exact "lower X by 0.23 m onto Ground" fix; adeliberately airborne thing gets `obj["placement"] = "free"`) → fix → `build` again, then-`scene_views` and LOOK at the frames: count the silhouettes, look for a flat colour under your-props, and read the MEASURED MOTION line it prints — if it reports your zone's cameras as STATIC,-double the amplitude and render again.+`scene_views` and LOOK at the frames against the brief, and read the MEASURED MOTION line it prints —+STATIC means this zone's motion is below the threshold.{% endif %}{% if effects_catalog is defined and effects_catalog %}{{ effects_catalog }}{% endif %}-{% if recipes is defined and recipes %}--# Recipes (from the scene cookbook — copy these numbers and snippets)-{{ recipes }}-{% endif %}{% if textures is defined and textures %}{{ textures }}@@ -146,3 +157,4 @@ check_existing=True)` into an Image Texture node; the build runs with the worksp## Output{{ output_format }}+{% endif %}diff --git a/harness/codeverse3d/prompts/variants/argon/variant.toml b/harness/codeverse3d/prompts/variants/argon/variant.tomlindex 1a7873d4..6f1dfacb 100644--- a/harness/codeverse3d/prompts/variants/argon/variant.toml+++ b/harness/codeverse3d/prompts/variants/argon/variant.toml@@ -1,6 +1,6 @@# The `argon` variant: gemini-4-argon on the scene track (threejs + blender). D105, 2026-10-14.#-# This directory mirrors codeverse3d/prompts/: a file placed here (scene_threejs/cookbook.md,+# This directory mirrors codeverse3d/prompts/: a file placed here (scene_threejs/system.md,# tracks/scene_zone.j2, ...) shadows the base file of the same relative path for every run that# activates the variant; a file not placed here is read from the base. The overlay ships EMPTY# so iteration 0 of eval/bench/loop.py measures the base prompts under the variant plumbing;@@ -9,8 +9,9 @@# Iteration 1 (2026-10-15): tracks/scene_zone.j2 and tracks/scene_zone_bpy.j2 shadow the base zone# briefs with a "Before you return" block — the last check_placement must be clean, one placed thing# per zone child, scatter clear of placed roots (lib.place.clear_mask), volumes for particles, and-# the three build-time crashes that dropped zones; skills/variants/argon/routes.toml boosts the two-# placement skills to the top of the standing list.+# the three build-time crashes that dropped zones; skills/variants/argon/routes.toml boosts the Blender+# placement skill to the top of the standing list (the three.js composition boost was withdrawn under+# D106, 2026-10-15: that bundle carried the template every iteration-0 scene reproduced).## Selection is explicit, never a regex over the model id: `3dcode make --variant argon`,# C3D_VARIANT=argon, or C3D_VARIANTS='{"agy:gemini-4-argon": "argon"}' (by the served model, sodiff --git a/harness/codeverse3d/skills/_claims/c3d-bpy-scene-placement.toml b/harness/codeverse3d/skills/_claims/c3d-bpy-scene-placement.tomlindex 5da9f49d..7ddd98bd 100644--- a/harness/codeverse3d/skills/_claims/c3d-bpy-scene-placement.toml+++ b/harness/codeverse3d/skills/_claims/c3d-bpy-scene-placement.toml@@ -14,6 +14,38 @@ js = "runtime_js/lib/host_placement.mjs:MAX_COLUMNS"format = "{:.0f}"context = "foot columns"+# the outdoor world_edge check: standing geometry reaches past the bounds++[[claim]]+key = "world_edge_reach_factor"+text = "1.25"+python = "codeverse3d.spatial.scene_placement:WORLD_EDGE_REACH_FACTOR"+format = "{:.2f}"+context = "half-extent"++[[claim]]+key = "world_edge_min_height"+text = "2 m"+python = "codeverse3d.spatial.scene_placement:WORLD_EDGE_MIN_HEIGHT_M"+format = "{:.0f} m"+context = "tall"++[[claim]]+key = "world_edge_reach_factor"+file = "references/finding-to-fix.md"+text = "1.25"+python = "codeverse3d.spatial.scene_placement:WORLD_EDGE_REACH_FACTOR"+format = "{:.2f}"+context = "half-extent"++[[claim]]+key = "world_edge_min_height"+file = "references/finding-to-fix.md"+text = "2 m"+python = "codeverse3d.spatial.scene_placement:WORLD_EDGE_MIN_HEIGHT_M"+format = "{:.0f} m"+context = "tall"+# references/finding-to-fix.md[[claim]]diff --git a/harness/codeverse3d/skills/c3d-bpy-scene-lighting/SKILL.md b/harness/codeverse3d/skills/c3d-bpy-scene-lighting/SKILL.mdindex afe8a548..5f491eb7 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-lighting/SKILL.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-lighting/SKILL.md@@ -1,17 +1,17 @@---name: c3d-bpy-scene-lighting-description: "Use when lighting a scene_blender env, zone, refine or rebuild session, or when scene_frames called a Blender frame too dark, blown out or flat. The harness renders with Cycles under AgX at exposure 0 and owns every render setting, so lamp energies, the world strength and the albedos are the only dials. Gives what the frame gate measures with its thresholds, the measured exposure bands of sky, sun, night and interior setups under this renderer, the sun-and-sky, night, interior and practical recipes through lib.sky and lib.lighting, the one-sun rule, why an emissive mesh is not a lamp at 32 samples, and how to prove the band on every camera including the harness rig."+description: "Use when lighting a scene_blender env, zone, refine or rebuild session, or when scene_frames called a Blender frame too dark, blown out or flat. The harness renders with Cycles under AgX at exposure 0 and owns every render setting, so lamp energies, the world strength and the albedos are the only dials. Gives what the frame gate measures with its thresholds, the exposure bands measured for sky, sun, night, practical and interior setups under this renderer, the interface facts (the world is build_env's, what the census counts as atmosphere, which ceilings the overview rig lifts), lib.sky and lib.lighting as an optional toolbox, why an emissive mesh is not a lamp at 32 samples, and how to prove the band on every camera including the harness rig."license: Apache-2.0compatibility: Blender 5.2.2 LTS headless, scene_blender runtime; Cycles 32 samples + OIDN, AgX view transform, look None, exposure 0 — all harness-owned (render_bpy_scene.setup_render).metadata:evidence: mixed- evidence_note: 'The gate thresholds are read from live code (spatial/frame_metrics.py, runtime_js/lib/host_metrics.mjs) and the render setup from languages/wrappers/render_bpy_scene.py on 2026-10-14; the exposure bands were measured that day on Blender 5.2.2 LTS with that exact setup on a synthetic test scene (references/exposure-bands.md says how), not on run output. The corpus half is empty: zero gated scene_blender runs exist on 2026-10-14; the first loop iteration attaches numbers.'- verified: "2026-10-14"+ evidence_note: 'The gate thresholds are read from live code (spatial/frame_metrics.py, runtime_js/lib/host_metrics.mjs) and the render setup from languages/wrappers/render_bpy_scene.py on 2026-10-14; the exposure bands were measured that day on Blender 5.2.2 LTS with that exact setup on a synthetic test scene (references/exposure-bands.md says how), not on run output. The corpus half is empty: the argon loop iteration 0 (2026-10-15) has not yet been tabulated per frame finding.'+ verified: "2026-10-15"target_metric: "bpy_exposure_findings"target_direction: "down"target_unit: "findings per run"target_measurable: "true"- target_baseline: "n=0 — no gated scene_blender runs yet (2026-10-14); measured on the first loop iteration"+ target_baseline: "n=0 — the argon loop iteration 0 (2026-10-15, 30 scene_blender runs) is the first sample; not yet tabulated"---# Lighting a Cycles scene the frame gate will accept@@ -37,7 +37,7 @@ with — per camera `mean_lum`, `lum_std`, `dark_frac`, `blown_frac` and `modal_An ERROR of each kind is a score ceiling in the scene rubric, and every finding's hint carries thescene_blender wording (lamps, world nodes, `ctx.height_at`), not the three.js one. The rig views-(`overview_*`) are WARN-only; fix them anyway — the judge reads those pictures.+(`overview_*`) are WARN-only; the judge reads those pictures too.## The bands, measured on this renderer@@ -63,60 +63,72 @@ other two kinds: a uniformly coloured ground seen from the overview rig sat in tshadow-casting content are what break it, not more light. And at night the lamps that make thepicture pass are an order of magnitude stronger than the ones that make the fixtures glow.-## The recipe+## Interface, requirements, and ways that measured inside the band-* **Sky and sun from `src/env.py` only.** `lib.sky.sun_world(scene, elevation_deg=..., azimuth_deg=..., strength=..., dust=...)`+* **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. `lib.sky.sun_world(scene, elevation_deg=..., azimuth_deg=..., strength=..., dust=...)`and `lib.lighting.sun(collection, azimuth_deg=..., elevation_deg=..., color=..., energy=..., angle_deg=...)`- are a pair: ONE world, ONE sun lamp, the same compass angles. `sun_world` switches the sky's- own sun disc OFF because the lamp is the sun — a world built by hand with the disc on, plus a- lamp, is two suns (the fourth row of the table). The world is `build_env`'s — a world created- or assigned anywhere else is a harness-owned lint ERROR — and a second sun lamp in a zone- doubles the shadows. Fix a dark day with the albedos and the sun's `energy`, not by raising- the world strength.-* **Dusk and overcast** are `lib.sky.gradient_world(scene, stops, clouds=..., strength=...)` with- a low warm sun; **night** is `lib.sky.night_world(scene, color=..., strength=...)` with a weak,- cool `sun` as the moon and the practicals doing the work.-* **Atmosphere is a bounded box**, `lib.sky.haze(collection, loc, size, density=..., color=...)`:- volume-only, which the census counts as fog (the `no_fog` plan check wants one) and the- placement gate ignores. A world volume over a large scene swallows the sun and flattens the frame.+ are a matched pair (the world's disc off, the lamp casting the shadows, the same compass+ angles); a hand-built world is fine when it meets the same. 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.** `lib.sky.gradient_world(scene, stops, clouds=..., strength=...)`+ and `lib.sky.night_world(scene, color=..., strength=...)` with a low or cool `sun` 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) counts, and the placement gate ignores it. `lib.sky.haze(collection, loc, size, density=..., color=...)`+ makes one as a box; 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** — `lib.lighting.area_light`, `point_light`, `spot`, and`practical(collection, name, loc, color=..., energy=..., size=..., target=...)`, a small soft- area lamp for every lantern, window, fire or sign, aimed with `aim`. Its default energy is the+ area lamp beside a lantern, window, fire or sign, aimed with `aim`. Its default energy is thefixture's own glow on the surfaces beside it, not illumination that carries a frame: two ofthem at that default measured `mean_lum` 0.05 (an ERROR); hundreds of watts each is where a- night frame passes. The lib creates lamps through `bpy.data.lights.new`; never through- `bpy.ops` — 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.+ night frame passed. The lib creates 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 emissivesurface, but a fixture-sized emitter throws almost nothing a frame can measure: two 0.15 memissive 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; thesame scene passed once each sphere had a 500 W `practical` beside it (reference, section 4).- Keep the emission on the fixture (`lib.materials.emissive`), put the illumination in a lamp,- and keep the emission modest: AgX pulls a saturated emitter toward white, so a strong neon- tube renders as a white bar.-* **Interiors**: `lib.architecture.room_shell` gives walls, floor and a ceiling the rig lifts; one- or two ceiling `area_light`s sized to the room, plus the practicals the brief names; a window is- an emissive pane with an `area_light` just inside it. The indoor placement tolerance is tighter,- so a lamp on a table is a `rest_on` case too.+ Emission on the fixture (`lib.materials.emissive`), 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). `lib.architecture.room_shell` builds a shell+ named 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_light` 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 a `rest_on` case 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. Set the large surfaces' albedo- first, then the sun, then the practicals.+ 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-A lantern-lit night is dim on average with real contrast — the "dim but lit" WARN, and that is-the target. 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. So: `night_world` low, every fixture paired with a `practical` strong enough-that the pools overlap into a readable picture, dark materials with a low but non-zero Base-Color, shadows left dark, and no fill lamp "to lift the average".+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` 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 visibleThe 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. Give it its own key — a `practical` or a `spot` aimed at-it with `aim(obj, target)` — and look at its camera's frame.+night is a hero the judge cannot find. Its own key — a `practical` or a `spot` aimed at it with+`aim(obj, target)` — and a look at its camera's frame.## Prove it@@ -124,4 +136,4 @@ it with `aim(obj, target)` — and look at its camera's frame.first table: the same five numbers the gate uses. A Blender view costs seconds, so render onceper change, all cameras, and fix whatever the finding names on EVERY camera, rig views included.-Full measured tables, the night and interior recipes as code: `references/exposure-bands.md`.+Full measured tables, the night and interior setups as code: `references/exposure-bands.md`.diff --git a/harness/codeverse3d/skills/c3d-bpy-scene-lighting/references/exposure-bands.md b/harness/codeverse3d/skills/c3d-bpy-scene-lighting/references/exposure-bands.mdindex c301136c..e48f96ab 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-lighting/references/exposure-bands.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-lighting/references/exposure-bands.md@@ -91,12 +91,11 @@ mean barely moves until the fixture is a white blob, which the judge grades as b```pythonfrom lib import lighting, materials, sky-def build_env(ctx): # a lantern-lit night+def build_env(ctx): # a lantern-lit night, one waysky.night_world(ctx.scene, color=<deep blue hex>, strength=<low>)lighting.sun(ctx.collection, azimuth_deg=<behind the hero>, elevation_deg=<low>, color=<cool hex>,energy=<a fraction of one>, name="Moon")sky.haze(ctx.collection, <centre>, <size>, density=<thin>, color=<the sky colour>)- ...# in a zone: each fixture is a look (emissive) AND a light (practical)mat = materials.emissive("LanternGlow", <warm hex>, <modest strength>)diff --git a/harness/codeverse3d/skills/c3d-bpy-scene-materials/SKILL.md b/harness/codeverse3d/skills/c3d-bpy-scene-materials/SKILL.mdindex e8c6fcce..ca3add1f 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-materials/SKILL.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-materials/SKILL.md@@ -1,17 +1,17 @@---name: c3d-bpy-scene-materials-description: "Use in every scene_blender env, zone, asset or refine session that authors a surface — ground, walls, props, foliage, water, glass, a glowing sign. Cycles renders every node you wire, but the harness's census reads only three Principled sockets, so no gate rewards material work and the judge penalises the lack of it. Gives the Blender 5.2 node facts (no use_nodes, the 4.x socket names, ShaderNodeMix), the lib.materials recipes, variation across copies without identical twins, ground layering and the seam under props, water, glass and emissive done as dielectrics and fixtures, and what to zoom on before you finish."+description: "Use in every scene_blender env, zone, asset or refine session that authors a surface — ground, walls, props, foliage, water, glass, a glowing sign, steam. Cycles renders every node you wire, but the harness's census reads only three Principled sockets, so no gate rewards material work and the judge penalises the lack of it. Gives the Blender 5.2 node facts (no use_nodes, the 4.x socket names, ShaderNodeMix), what the judge names and what it measures, lib.materials as an optional palette, variation across copies without identical twins, ground that varies where the brief's surface does, water, glass and emissive done as dielectrics and fixtures, soft particles as volumes, and what to zoom on before you finish."license: Apache-2.0compatibility: Blender 5.2.2 LTS headless, scene_blender runtime; Cycles 32 samples + OIDN under AgX (the harness's render settings), Principled BSDF 4.x socket names.metadata:evidence: mixed- evidence_note: 'The census facts are read from live code on 2026-10-14 (wrappers/_census_glb.py, wrappers/_census.py, the languages/blender lint tables verified against Blender 5.2.2 LTS) and the defect wording from the scene judge rubric; the recipes restate the scene_blender starter library. The corpus half is empty: zero graded scene_blender runs exist on 2026-10-14; the first loop iteration attaches numbers.'- verified: "2026-10-14"+ evidence_note: 'The census facts are read from live code on 2026-10-14 (wrappers/_census_glb.py, wrappers/_census.py, the languages/blender lint tables verified against Blender 5.2.2 LTS) and the defect wording from the scene judge rubric; the recipes restate the scene_blender starter library. The corpus half is the argon loop iteration 0 of 2026-10-15 (30 scene_blender runs): 8 scenes built hard-edged particles from surface shaders.'+ verified: "2026-10-15"target_metric: "flat_principled_materials"target_direction: "down"target_unit: "materials whose Base Color, Roughness and Metallic are all unlinked constants (prospective census)"target_measurable: "false"- target_baseline: "n=0 — no graded scene_blender runs yet (2026-10-14); the first loop iteration attaches numbers once the census records the count"+ target_baseline: "n=0 — the census does not yet record the count; the argon loop iteration 0 (2026-10-15) is the first sample once it does"---# Surfaces that read as a place — Principled recipes the census cannot see@@ -21,9 +21,10 @@ metadata:The judge sees Cycles pixels: every noise texture, bump and vertex colour you wire is in thepicture, and the rubric names the failures directly — `placeholder_material` (default-grey oruntextured flat surfaces, with a score ceiling of its own), `flat_ground` (one flat colour with-a hard undressed seam where objects meet it) and `monotonous_vegetation` (one shape stamped many-times with no variation in hue or size) — 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`,+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. Sono gate measures material work; this sheet is about the judge's picture, plus the one censusfact that does bite — a mesh with no material at all is warned as exporting grey.@@ -35,25 +36,26 @@ fact that does bite — a mesh with no material at all is warned as exporting grreports 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`. Never write the old `Specular`,- `Transmission`, `Emission`, `Subsurface` or `Clearcoat` keys: they raise, and the lint names the- renamed ones for you. `Specular Tint` is a colour, so assign a 4-tuple.+ `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), not `ShaderNodeMixRGB`, which is gone.+ `Result` out); `ShaderNodeMixRGB` is gone.* Per-face materials: set `material_index` on the bmesh faces BEFORE `bm.to_mesh`. Every newpolygon starts on slot 0, and the census warns about slots no polygon uses — the part wasauthored in four colours and exports in one.-## The recipes — `lib.materials` first+## The palette — `lib.materials`, one optionEvery call takes a name and returns a material; colours are sRGB hex strings (`rgba` decodesthem to linear). Procedural detail reads OBJECT coordinates, so `noise_scale` is features permetre whatever the object's size, and the lib's own band for a non-emissive albedo is 0.02-0.8-linear: pure black reads as a hole, pure white as a blown surface.+linear: pure black reads as a hole, pure white as a blown surface. Nodes you wire yourself do the+same job (`references/principled-recipes.md` has the snippets).| want | call ||---|---|-| any surface with value variance | `material(name, color, roughness=..., metal=..., noise_scale=..., bump=..., emission=...)` — a `noise_scale` above zero is the low-contrast map every large surface needs |+| a surface with value variance | `material(name, color, roughness=..., metal=..., noise_scale=..., bump=..., emission=...)` — `noise_scale` above zero adds the low-contrast variation that stops a large surface reading as a flat placeholder (judged); where the brief's material has it || stone, brick, plaster | `masonry(name, color, mortar=..., scale=...)`, `limestone(name, color, scale=...)`, `ashlar(name, color)`, `mineral_surface(name, color, stone=...)` || wood | `woodgrain(mat, dark=..., light=..., direction=...)` on an existing material || worn paint, used metal | `chipped_paint(mat, paint, substrate, scale=...)`, `worn_alloy(name, color, seed=..., metal=...)` |@@ -61,6 +63,7 @@ linear: pure black reads as a hole, pure white as a blown surface.| water | `water(name, color=..., roughness=..., scale=..., flow=..., ctx=ctx)` for a tinted, moving surface; `clear_water(name)` for shallow, almost colourless water (a basin, a bowl, a stream) || glass | `glass(name, color=..., roughness=..., ior=...)` || a glowing fixture | `emissive(name, color, strength)` — the look only; the light is a `practical` lamp (c3d-bpy-scene-lighting) |+| steam, smoke, dust, mist | `volume(name, color, density=..., anisotropy=..., noise_scale=..., emission=...)` — volume-only, no silhouette || a copy that is not a twin | `tint(mat, variant)` — a copy with its Base Color shifted, one per VARIANT and shared by that variant's copies; it leaves a LINKED Base Color alone, so a noise-mapped material gets its variant from `material` called with another colour |## Variation without twins@@ -73,28 +76,39 @@ over many copies, an Object Info node's `Random` output driving a hue shift, whievaluates per instance. The `stamped_ring` plan check measures rings of identical copies at oneradius, and the judge calls the result monotonous vegetation.-## Ground: layers, not a colour+## Ground: what `flat_ground` means-`lib.terrain.ground` takes ONE material; make it earn its area. `mineral_surface` or-`material(..., noise_scale=...)` as the base, a second colour mixed in by slope (the Geometry-node's `Normal`, its Z through a ColorRamp into the mix factor) and by height (object Z from-Texture Coordinate) — grass to earth to rock — plus a worn band as a noise-masked third colour-where the plan's paths run. The seam under a building is `flat_ground`'s own wording: a darker,-rougher band of ground tint under big structures, and ground cover (`gn_scatter`, `grass_patch`)-along their feet. A colour attribute on the ground mesh read by a Color Attribute node does the-same job when the bands are easier to paint per vertex than to compute per pixel.+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.+`lib.terrain.ground` takes 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 (`gn_scatter`, `grass_patch`), 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 (`lib.architecture.paving`,+`paving_grid`) 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: `water` and `clear_water` set transmission, a low roughness and- `Metallic` at zero — never a metallic mirror plane. Moving water scrolls its mapping node on- `ctx.frame(t)` through `lib.motion.scroll`, which is why `water(..., ctx=ctx)` wants the context.+ `Metallic` at zero; a metallic mirror plane reads as chrome, not water. Moving water scrolls its+ mapping node on `ctx.frame(t)` through `lib.motion.scroll`, which is why `water(..., ctx=ctx)`+ wants the context.* Glass is `glass`: full `Transmission Weight`, low roughness, the lib's default IOR. The bouncebudget is the harness's, so a stack of transmissive layers along one sight line goes dark —- keep it to one or two.-* Fog is a VOLUME-ONLY material on a box (`lib.sky.haze`): only the Material Output's Volume- socket linked. A box 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.+ one or two read.+* Fog is a VOLUME-ONLY material on any mesh (`lib.sky.haze` makes a box): 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`. `lib.materials.volume` on a+ cloud of spheres (one `Batch`, one object, tagged `placement = "free"`, moved with+ `lib.motion.drift` or `sway` 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@@ -106,9 +120,9 @@ under a black world is a black shape.## Verify before you finish`scene_views(cameras="authored", times=[0.0])` and zoom one frame: a wall or a ground that is one-flat value needs `noise_scale`; 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 `scene_probe`-for triangle counts — materials are free, geometry is not.+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 `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 box, the socket rename table — in `references/principled-recipes.md`.+volume-only material, the socket rename table — in `references/principled-recipes.md`.diff --git a/harness/codeverse3d/skills/c3d-bpy-scene-materials/references/principled-recipes.md b/harness/codeverse3d/skills/c3d-bpy-scene-materials/references/principled-recipes.mdindex 71758138..6207b1d9 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-materials/references/principled-recipes.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-materials/references/principled-recipes.md@@ -25,8 +25,7 @@ Prefer the `lib.materials` call that does the same thing; write nodes only for w```pythonnoise = nodes.new("ShaderNodeTexNoise")-noise.inputs["Scale"].default_value = <texels per metre: 2-5 cm at walking distance>-noise.inputs["Detail"].default_value = 6.0+noise.inputs["Scale"].default_value = <features per metre: 2-5 cm at walking distance>mix = nodes.new("ShaderNodeMix")mix.data_type = "RGBA"mix.inputs["A"].default_value = (<r>, <g>, <b>, 1.0) # the base colour@@ -49,8 +48,7 @@ geo = nodes.new("ShaderNodeNewGeometry")sep = nodes.new("ShaderNodeSeparateXYZ")links.new(geo.outputs["Normal"], sep.inputs["Vector"])ramp = nodes.new("ShaderNodeValToRGB") # a ColorRamp: slope -> 0..1-ramp.color_ramp.elements[0].position = <cos of the rock angle, e.g. 0.65>-ramp.color_ramp.elements[1].position = <a few hundredths higher: a soft edge>+ramp.color_ramp.elements[0].position = <cos of the rock angle> # element 1 a few hundredths higher: a soft edgelinks.new(sep.outputs["Z"], ramp.inputs["Fac"])mix = nodes.new("ShaderNodeMix")mix.data_type = "RGBA"@@ -61,7 +59,8 @@ links.new(mix.outputs["Result"], bsdf.inputs["Base Color"])```Height bands use the Object output of a Texture Coordinate node, Z through a second ramp.-A worn path is a third colour masked by a low-frequency noise sampled along the path's polyline.+A worn route is a further colour masked by a low-frequency noise along its polyline. These are+options for natural ground; built ground (paving, a floor) carries its own material instead.## 4. One material, many copies: the Object Info tint@@ -102,8 +101,9 @@ vol.inputs["Density"].default_value = <0.002-0.02>links.new(vol.outputs["Volume"], nodes["Material Output"].inputs["Volume"])```-`lib.sky.haze(collection, loc, size, density=..., color=...)` builds this on a box sized to the-play area. Leave the Surface socket unlinked: a box with both is a placed asset to the gate.+`lib.sky.haze(collection, loc, size, density=..., color=...)` builds this on a box; any mesh whose+only linked output is Volume is fog to the census. With the Surface socket linked as well it is a+placed asset to the gate. `lib.materials.volume` is the same shader with noise, for steam and mist.## 7. Water and glass, as the lib sets themdiff --git a/harness/codeverse3d/skills/c3d-bpy-scene-placement/SKILL.md b/harness/codeverse3d/skills/c3d-bpy-scene-placement/SKILL.mdindex f2229017..f221cc10 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-placement/SKILL.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-placement/SKILL.md@@ -1,26 +1,24 @@---name: c3d-bpy-scene-placement-description: "Use in every scene_blender env, zone, refine or rebuild session that places anything, and whenever check_placement or the scene_placement gate reported a floating, sunken, unsupported, interpenetrating or cantilevered asset, or too many free-tagged ones. Everything placed is ONE row in a measured table and its feet are sampled against what is under them. Gives what the gate measures and on which geometry, how a collection instance differs from a geometry-nodes cloud, the lib.place calls that seat a thing the way the gate samples it, the self-check to run before the build, and the finding-to-fix table."+description: "Use in every scene_blender env, zone, refine or rebuild session that places anything, and whenever check_placement or the scene_placement gate reported a floating, sunken, unsupported, interpenetrating, cantilevered or out-of-bounds asset, too many free-tagged ones, or a world that ends at its bounds (world_edge). Everything placed is ONE row in a measured table and its feet are sampled against what is under them. Gives what the gate measures and on which geometry, how a collection instance differs from a geometry-nodes cloud, the requirements with their measurements, the lib.place / lib.scatter / lib.terrain calls as an optional toolbox that samples what the gate samples, the self-check, and the finding-to-fix table."license: Apache-2.0compatibility: Blender 5.2.2 LTS headless, scene_blender runtime; the gate measures the harness-written census GLB (the evaluated depsgraph), never the .blend.metadata:evidence: mixed- evidence_note: 'The instrument half is read from live code on 2026-10-14 (spatial/scene_placement.py, runtime_js/lib/host_placement.mjs, config.Placement, wrappers/_census_glb.py) and the lib calls from the scene_blender starter library. The corpus half is empty: zero gated scene_blender runs exist on 2026-10-14; the first loop iteration attaches numbers.'- verified: "2026-10-14"+ evidence_note: 'The instrument half is read from live code on 2026-10-14 (spatial/scene_placement.py, runtime_js/lib/host_placement.mjs, config.Placement, wrappers/_census_glb.py) and the lib calls from the scene_blender starter library. The corpus half is the argon loop iteration 0 of 2026-10-15 (30 scene_blender runs): 13 zones with an interpenetration ERROR, 9 of them a scatter into a hand-placed prop.'+ verified: "2026-10-15"target_metric: "bpy_placement_errors"target_direction: "down"target_unit: "ERROR findings per run"target_measurable: "true"- target_baseline: "n=0 — no gated scene_blender runs yet (2026-10-14); measured on the first loop iteration"+ target_baseline: "n=30 scene_blender runs, argon loop iteration 0 (2026-10-15): 13 zones shipped an interpenetration ERROR; the per-run ERROR count is not yet tabulated"---# Everything sits on something — placement the gate can measure**Read this if** you are writing a zone, the env, or fixing a `check_placement` finding. The-placement gate is deterministic and strict (the 2026-10-14 standards: 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 — a hover that is invisible in an overview is graded at-full size.+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@@ -32,10 +30,10 @@ direct child of a zone collection that has mesh descendants, and each one is ONE|---|---|---|| a mesh object, with or without children | 1 — the whole subtree | yes || a collection-instance Empty (`lib.scatter.instance`) | 1 per placed copy | yes — its clones are sampled like a mesh |-| a multi-part prop finished under one root Empty (`Batch.finish`, `parent_under`) | 1 | yes |-| twelve loose meshes that together are a hut | 12 | yes, each at its own feet: the roof floats |+| a multi-part prop under one root (a parent Empty, `Batch.finish`, `parent_under`, or joined meshes) | 1 | yes |+| twelve loose meshes that together are a hut | 12 | yes, each at its own feet || a geometry-nodes or particle cloud (`gn_scatter`, `grass_patch`) | 1, exempt as instanced | no — and never a support either |-| a volume-only mesh (`lib.sky.haze`) | exempt as volumetric | no, and never a support or an overlap partner |+| a volume-only mesh (`lib.sky.haze`, `lib.materials.volume`) | exempt as volumetric | no, and never a support or an overlap partner || ground, water and sky by name and shape; a shell that swallows the content box | exempt as backdrop or enclosure | no || anything tagged `obj["placement"] = "free"`, or its whole zone collection | exempt as free | no — but counted, see below |@@ -47,74 +45,85 @@ its leg tips, not under its top:* `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 and how far the worst one hangs.+* `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 when it passes `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 one 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 `check_placement` prints the values it-used; this sheet does not restate them. Interiors get the tighter tolerance, and the plan's-setting words decide that (`is_interior`), not your zone.+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 `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 theboot-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. Name things what they are and the gate-already knows how they sit. Renaming a bench "Rock" to dodge the check is pointless: the judge-grades the crop.--## Build so the rows come out right--1. **One height authority.** `height_at(x, y)` in `src/env.py` is the ground: build it with- `lib.terrain.make_height_at`, let `lib.terrain.ground` mesh it, and let every zone read- `ctx.height_at`. A zone that flattens its own patch to zero is how a bench ends up buried on- one side and floating on the other.-2. **Seat with the lib, not by eye.** `lib.place.seat(obj, ctx.height_at, sink=...)` samples the- same foot columns the gate does and returns the move it made. A placed copy of an asset is- `lib.scatter.instance(ctx.collection, ctx.assets["<snake>"], name, x, y, height_at=ctx.height_at, rot_z=..., scale=..., sink=...)`- — one Empty, already seated (an instance Empty you built yourself: `lib.place.seat_instance`).- A thing ON a thing — a cup on a table, a lantern on a post — is `lib.place.rest_on(obj, support)`:- the gate measures the gap to the SUPPORT, and `ctx.height_at` would drop it through the table.- Every `lib.place` call reads the point set the gate measures — the object, its children and,- for an instance Empty, the source collection under the Empty's transform — so pass the root.-3. **Sink only what sinks.** `sink` is for things whose name says they sink — a rock, a post, a- tree with modelled roots; the words file tolerates those. A crate sunk "so it cannot float" is- a `sunken` finding and a crop of a crate in the ground.-4. **Slopes.** `seat` rests the foot that stands over the lowest ground and buries the rest, so- a wide thing on a slope comes back `sunken` on its uphill side; placing a thing at the ground- height of its CENTRE instead (`height_at` of one point, the old skeleton's way) leaves the- downhill feet hanging, which is the `cantilevered` finding. For wide things on a slope, flatten- a pad in `height_at` under them (the ground mesh follows), split a long wall into segments each- seated with `seat`, or turn it along the contour with `lib.place.face_toward`.-5. **A prop is one row.** Build its parts in one `lib.mesh.Batch` and `Batch.finish(ctx.collection, parent=True)`:- ONE root Empty, one row, one seat. Twelve loose meshes are twelve rows with twelve chances to- float, and twelve overlap partners for each other.-6. **Copies vs clouds.** Things the brief counts — props, trees near a camera, figures — are- collection instances (`lib.scatter.instance`, `lib.scatter.scatter`): each is a row, each- seated. Ground cover — grass, pebbles, leaves — is `gn_scatter` or `grass_patch`: exempt,- cheap, never a support. Do not scatter benches with `gn_scatter` to escape the gate: the- plan-contents check counts instances either way and the judge still sees a floating bench.-7. **`free` is for hanging and airborne things only** — a bird, a kite, a lantern on a chain, a- drone. The gate reports the share of free-tagged assets (`free_exempt`), and the judge's+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: `lib.terrain.make_height_at` (rolling noise hills,+ a level pad only if asked) is one option; a slope to a river from `lib.noise.fbm2`, a ridge from+ `lib.noise.ridged`, a terrace, a quay stepping down to `lib.water.pool_height`, a plaza flat+ everywhere are others, and `lib.terrain.ground` meshes whatever you hand 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). `lib.place.seat(obj, ctx.height_at, sink=...)` samples the+ same columns and returns the move it made; `lib.scatter.instance(ctx.collection, ctx.assets["<snake>"], name, x, y, height_at=ctx.height_at, ...)`+ places a copy already seated; a thing ON a thing — a cup on a table, a lantern on a post — is+ `lib.place.rest_on(obj, support)`, because the gate measures the gap to the SUPPORT. Every+ `lib.place` call reads the point set the gate measures, so pass the root. Any placement that+ passes `check_placement` is acceptable.+3. **`sink` 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.** `seat` 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 with `lib.place.face_toward`.+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, joined meshes, `lib.mesh.parent_under` or+ `lib.mesh.Batch.finish(ctx.collection, parent=True)` all do 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. `lib.scatter.instance` / `scatter` make rows; `gn_scatter` and+ `grass_patch` make clouds — the toolbox for the hundreds (blades, pebbles, litter, a far treeline).+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'sfloating defect still sees a free-tagged crate in the air.-8. **Stay inside.** `lib.place.keep_inside(obj, bbox)` with the zone's plan box as (centre,- extents) slides it back horizontally. A thing entirely outside the plan bounds is the- `out_of_bounds` kind, and one far from its planned `approx_size_m` is the `scale` kind — both- target the zone, and the fix for the second is the SOURCE asset's build, not the Empties.-9. **Names are global in Blender.** `lib.place.unique_name(base, i)`; a second `Lantern_0` in- another zone becomes `Lantern_0.001` and the plan-contents check loses it.+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. `lib.place.keep_inside(obj, bbox)` with the zone's plan box as (centre, extents)+ 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.** `lib.place.unique_name(base, i)`; a second `Lantern_0`+ becomes `Lantern_0.001` and the plan-contents check loses it.## The self-check, then the gate-Before the build, `lib.place.clear_of(objs)` lists the pairs whose boxes overlap past the gate's-own interpenetration band, as (name, name, fraction) — run it over the zone's root objects and-fix every pair it names (move, shrink, or make the two ONE prop). Then `build`, then-`check_placement`, which prints the findings with their fix hints and the table behind them:+`lib.place.clear_of(objs)` lists the pairs whose boxes overlap past the interpenetration band,+as (name, name, fraction) — over the zone's roots AND its scattered Empties. `lib.place.clear_mask(objs, margin=...)`+is a `scatter.poisson(mask=...)` filter that keeps scatter points out of the footprints 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+`build`, then `check_placement`, which prints the findings with their fix hints and the table:```asset | gap to support (m) | support | sunk (m) | into | water | attached@@ -122,17 +131,17 @@ Market/Bench_0 | +0.236 | Terrain | 0.000 | - | - | -interpenetration Market/Cart_1 × Market/Stall_0: 41% box, 23% inside```-Apply the hint's number literally — `lower Bench_0 by 0.24 m onto Terrain` means `seat` it,-not "move it down a bit" — then `build` again. Do not finish a round whose last-`check_placement` still lists an ERROR: the rubric caps the run on each one, and a PASSED gate is-what vetoes the judge's own floating claim.+The hint's number is the measured gap (`seat` applies it). A round whose last `check_placement`+lists an ERROR is capped by the rubric on each one; a PASSED gate vetoes the judge's own floating claim.-## Motion does not excuse the feet+## Motion, and the feet-The census is taken at the build's current frame, so a moving thing must be seated at every time-the harness samples. Keep a swaying tree's origin at its base (it rotates about its feet), drift-a boat ON water (`on_water` makes it supported), and let a bird be free. Keyframes go through-`lib.motion` on `ctx.frame(t)`; never move an object by shifting its mesh data after seating it.+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` (`lib.motion.keyframe_path`, `drift`, `sway`, `spin`, `scroll`, `shape_key_sweep`+are these in one call; 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 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, where the rows come from in the census GLB, and the finding-to-fix table:-`references/finding-to-fix.md`.+Worked zone, row provenance and the finding-to-fix table: `references/finding-to-fix.md`.diff --git a/harness/codeverse3d/skills/c3d-bpy-scene-placement/references/finding-to-fix.md b/harness/codeverse3d/skills/c3d-bpy-scene-placement/references/finding-to-fix.mdindex ac75c865..69218dff 100644--- a/harness/codeverse3d/skills/c3d-bpy-scene-placement/references/finding-to-fix.md+++ b/harness/codeverse3d/skills/c3d-bpy-scene-placement/references/finding-to-fix.md@@ -3,25 +3,27 @@Companion to `c3d-bpy-scene-placement`. Read against `codeverse3d/spatial/scene_placement.py`,`runtime_js/lib/host_placement.mjs`, `codeverse3d/languages/wrappers/_census_glb.py` and the`Placement` section of `codeverse3d/config.py` on 2026-10-14. The lib calls are the scene_blender-starter's (`src/lib/`, harness-owned: call it, never edit it).+starter's (`src/lib/`, harness-owned: call it, never edit it) and are one way to meet each row;+any construction that passes `check_placement` is as good.## 1. Finding to fix-| kind, and what the line says | severity | it means | do this |+| kind, and what the line says | severity | it means | what meets it ||---|---|---|---|-| `floating` — `X is floating 0.24 m above Terrain (touches nothing)` | WARN; ERROR past `floating_error_m`, or when more than `floating_error_count` assets float | the lowest foot column hangs in the air | `lib.place.seat(obj, ctx.height_at)`, or `lib.place.rest_on(obj, support)` for a thing on a thing; the printed number IS the gap |-| `unsupported` — `X is unsupported: hovers 0.03 m above Terrain and touches nothing` | WARN | off the contact tolerance but inside the floating band | `seat` it; if it really hangs, tag it `obj["placement"] = "free"` |+| `floating` — `X is floating 0.24 m above Terrain (touches nothing)` | WARN; ERROR past `floating_error_m`, or when more than `floating_error_count` assets float | the lowest foot column hangs in the air | lower it by the printed number: `lib.place.seat(obj, ctx.height_at)`, or `lib.place.rest_on(obj, support)` for a thing on a thing |+| `unsupported` — `X is unsupported: hovers 0.03 m above Terrain and touches nothing` | WARN | off the contact tolerance but inside the floating band | seat it; if it really hangs, tag it `obj["placement"] = "free"` || `sunken` — `X is sunken 0.31 m into Terrain` | WARN; ERROR past `sunk_error_m` when the burial also passes `sunk_error_frac` of the height | a foot column sits below the surface | raise it by the number, drop its `sink`, or — only if it is driven or grown in — give it a `partial_ok` name |-| `interpenetration` — `A and B overlap (41% of the smaller box; 23% of its vertices inside the other)` | WARN past `overlap_warn`, ERROR past `overlap_error` | two rows share volume | move the smaller one out, shrink one, or make them ONE prop (`lib.mesh.parent_under`, or one `Batch`) so there is one row |-| `cantilevered` — one column rests, the worst one hangs | WARN | a thing placed at its centre's ground height on a slope or a bump: the downhill feet hang | `seat` it (the lowest ground wins, the rest sink), then flatten a pad in `height_at`, split it into seated segments, or turn it along the contour |-| `free_exempt` — too many assets tagged free | WARN past `free_exempt_warn`, ERROR past `free_exempt_error` | the tag is hiding things from the gate | untag everything that stands; `free` is for hanging and airborne things only |+| `interpenetration` — `A and B overlap (41% of the smaller box; 23% of its vertices inside the other)` | WARN past `overlap_warn`, ERROR past `overlap_error` | two rows share volume | move the smaller one out, shrink one, remove one, or make them ONE row (`lib.mesh.parent_under`, one `Batch`, a joined mesh) |+| `cantilevered` — one column rests, the worst one hangs | WARN | a thing placed at its centre's ground height on a slope or a bump: the downhill feet hang | seat it (the lowest ground wins, the rest sink), a pad in `height_at`, seated segments, or a turn along the contour |+| `free_exempt` — too many assets tagged free | WARN past `free_exempt_warn`, ERROR past `free_exempt_error` | the tag is hiding things from the gate | untag everything that stands; `free` is for hanging and airborne things || `scale` — `each of the 6 lantern instances in Square/Lanterns measures 2.80 m but the plan sized lantern at ~0.60 m (4.7x)` | WARN, ERROR by factor | the asset is built at the wrong size | scale the SOURCE collection's build, not the Empties |-| `out_of_bounds` — `X sits entirely outside the plan bounds` | ERROR | wrong coordinates | `lib.place.keep_inside(obj, bbox)` with the zone bbox |+| `out_of_bounds` — `X (planned content 'bollard') sits entirely outside the plan bounds + 8 m` | WARN | a row carrying a PLANNED content's name lies wholly past the bounds plus max(5 m, 10 % of the span); unplanned scenery past the bounds is never reported | move it in (`lib.place.keep_inside(obj, bbox)` with the zone bbox is one way), or leave it if the brief puts it there and say so |+| `world_edge` — `the world ends at its bounds: the farthest standing geometry (>= 2 m tall) reaches N m from the bounds centre` | WARN | an outdoor plan whose content or ground groups at least 2 m tall all stop inside 1.25 × the bounds' half-extent | whatever the brief's horizon holds, continued past the bounds from the env and named `Sky…` when wide || `truncated` — `… and 4 more floating finding(s) not listed` | INFO | the report keeps the worst 8 per kind | fix the listed ones, rebuild, read the next batch |The table under the findings stops at 400 assets or after 4 s of sampling and says so; a scene-that hits either limit has more placed rows than a judge can read anyway — merge props and move-ground cover to `gn_scatter`.+that hits either limit has more placed rows than a judge can read anyway — fewer, merged rows,+with the hundreds as instanced clouds, is what fits.## 2. Where a row comes from@@ -41,12 +43,12 @@ The census GLB writer walks the evaluated depsgraph; the placement table reads tSupports are the OTHER rows' meshes plus the terrain and floors: a lantern resting on a post ismeasured to the post, a crate on a jetty to the jetty, a boat on a water-named plane is on water.-`seat`, `seat_instance`, `rest_on`, `clear_of`, `keep_inside` and `bbox_world` all read the same-point set the gate measures — an object's own geometry, its children's and, for a collection-instance, the source collection's under the Empty's transform — so an instance Empty is a valid-argument to every one of them, and the root of a finished prop is the thing to seat.+`seat`, `seat_instance`, `rest_on`, `clear_of`, `clear_mask`, `keep_inside` and `bbox_world` all+read the same point set the gate measures — an object's own geometry, its children's and, for a+collection instance, the source collection's under the Empty's transform — so an instance Empty+is a valid argument to every one of them, and the root of a finished prop is the thing to seat.-## 3. A worked zone+## 3. A worked zone, one way```pythonfrom lib import place, scatter@@ -54,23 +56,18 @@ from lib import place, scatterdef build(ctx):rng, h = ctx.rng(11), ctx.height_atbench = scatter.instance(ctx.collection, ctx.assets["bench"], place.unique_name("Bench", 0),- 3.0, -2.0, height_at=h, rot_z=0.4) # one Empty, seated: ONE row- pts = scatter.poisson(rng, area=(<x0>, <y0>, <x1>, <y1>), min_dist=2.5, max_count=12) # the zone's plan box- for i, (x, y) in enumerate(pts):- scatter.instance(ctx.collection, ctx.assets["shrub"], place.unique_name("Shrub", i), x, y,- height_at=h, rot_z=rng.uniform(0.0, 6.28), scale=rng.uniform(0.8, 1.2), sink=0.03)- lantern = <a lib.mesh prop built in this zone, finished under one root> # a mesh root: one row- place.rest_on(lantern, bench) # measured to the BENCH- kite = <a lib.mesh prop>- kite.location.z += 4.0- kite["placement"] = "free" # airborne by design- for a, b, frac in place.clear_of([o for o in ctx.collection.objects if o.parent is None]):- print("overlap before build:", a, b, frac) # fix every pair it names+ <x>, <y>, height_at=h, rot_z=<yaw>) # one Empty, seated: ONE row+ mask = place.clear_mask([bench], margin=0.3) # scatter clear of it+ pts = scatter.poisson(rng, area=(<x0>, <y0>, <x1>, <y1>), min_dist=<m>, max_count=<n>, mask=mask)+ shrubs = scatter.scatter(ctx.collection, ctx.assets["shrub"], "Shrub", pts, height_at=h, rng=rng)+ place.rest_on(<a lantern built in this zone, under one root>, bench) # measured to the BENCH+ for a, b, frac in place.clear_of([bench, *shrubs]): print("overlap:", a, b, frac) # fix every pairreturn ctx.collection```-`Shrub` carries a `partial_ok` word, so its small `sink` is accepted; the bench, the lantern and-the kite carry no such word and are measured as they stand.+`Shrub` carries a `partial_ok` word, so a small `sink` on it is accepted; the bench and the+lantern carry no such word and are measured as they stand. A kite with `kite["placement"] = "free"`+is airborne by design.## 4. The loop@@ -78,5 +75,5 @@ the kite carry no such word and are measured as they stand.build -> check_placement -> fix every ERROR, then the deepest WARN -> build```-`check_placement` reads the census of the last build; pass `rebuild=true` only when you doubt-that census. Never finish a round on an ERROR.+`check_placement` reads the census of the last build; `rebuild=true` re-takes the census when+you doubt it. A round that ends on an ERROR is capped by the rubric on each one.diff --git a/harness/codeverse3d/skills/c3d-scene-atmosphere/SKILL.md b/harness/codeverse3d/skills/c3d-scene-atmosphere/SKILL.mdindex c9b75282..289b7d71 100644--- a/harness/codeverse3d/skills/c3d-scene-atmosphere/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-atmosphere/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-atmosphere-description: "Use when a scene_threejs env, baseline or refine session builds the sky, the environment map, clouds or fog. The sky is not a backdrop: it is the light source every PBR material reflects. Gives the sky-dome shader, the equirect bake that turns it into scene.environment (with the one-line orientation bug that blackens water), the cloud recipes that read in a still frame, and the fog numbers that add depth instead of eating the scene."+description: "Use when a scene_threejs env, baseline or refine session builds the sky, the environment map, clouds or fog. The sky is not a backdrop: it is the light source every PBR material reflects. States what has to be true (scene.environment set before the first frame and agreeing with the visible sky; clouds that read as volumes; haze that leaves the midground readable) and how it is read, with the library's sky, cloud and fog modules as the strong options and the one-line equirect orientation bug that blackens water."license: Apache-2.0compatibility: three r0.182, headless WebGL; renderer fixed at ACES Filmic tone mapping, exposure 1.0, sRGB output.metadata:evidence: inherited-unverified- evidence_note: 'Recipes ported 2026-09-01 from the scene_multifile_graphics reference harness, where they carry measured origins: its audit found the equirect bake INVERTED in 4 of 9 delivered scenes (a Venice canal at patch RGB 35,27,18 went to 100,87,43 by flipping one line), and its PMREM note is from three.js source (cube size = width/4). Not yet A/B-validated on this harness; the sceneloop battery attaches our own numbers.'- verified: "2026-09-01"+ evidence_note: 'Recipes ported 2026-09-01 from the scene_multifile_graphics reference harness, where they carry measured origins: its audit found the equirect bake INVERTED in 4 of 9 delivered scenes (a Venice canal at patch RGB 35,27,18 went to 100,87,43 by flipping one line), and its PMREM note is from three.js source (cube size = width/4). Not yet A/B-validated on this harness; the sceneloop battery attaches our own numbers. Condensed to requirements + options 2026-10-15.'+ verified: "2026-10-15"target_metric: "env_bake_orientation_flags"target_direction: "down"target_unit: "inverted bakes per run (prospective census)"@@ -14,35 +14,34 @@ metadata:target_baseline: "n=0 — no measured runs yet (2026-09-01); the sceneloop A/B battery sets it"----# Sky, environment and air — the frame's light source comes first+# Sky, environment and air — the frame's light source-Build the sky BEFORE any PBR material exists. `scene.environment` is what makes-metal, glass, water and wet ground live; a scene assembled first and skied later-has every reflective surface already born dead.+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 dome+## The sky-A big sphere, `side: THREE.BackSide`, `depthWrite: false`, named `Sky`, with a-ShaderMaterial over the view direction `d = normalize(vWorldPos)`:+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).-```glsl-vec3 col = mix(horizonColor, zenithColor, pow(clamp(d.y, 0., 1.), 0.6));-float sunAmt = max(dot(d, sunDir), 0.0);-col += hazeColor * pow(sunAmt, 8.0) * 0.25; // mie halo-col += sunColor * smoothstep(0.9993, 0.9998, sunAmt); // sun disk-col = mix(col, horizonColor, pow(1.0 - clamp(d.y, 0., 1.), 8.0)); // haze band-```--* Sunset: sun low (`sunDir.y` around 0.1), horizon orange/rose, widen the halo- (`pow(sunAmt, 4.0) * 0.6`).-* Night: zenith around #050a18, horizon #0d1626; stars by hashing the direction- (`vec3 c = floor(d*300.); step(0.9985, hash(c.xy + c.z))`, vary brightness);- a moon disk shaded with fbm and ONE slate-blue DirectionalLight.+Strong options: `makeSky(scene, { rig })` from `lib/sky.js` is the shipped dome, lit from the+same `sunRig` as the scene (`scene.background` stays null). 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+(`makeStars`, `makeAurora` in `lib/celestial.js` do it for you) and shades a moon.## Bake the SAME sky into `scene.environment`-Mirror the sky function in JS and bake it into an equirect `DataTexture`, then-`scene.environment = tex`. Rules that are bugs when broken:+`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`; a64x32 bake gives 16-pixel cube faces — technically valid, visually useless.@@ -59,35 +58,29 @@ Mirror the sky function in JS and bake it into an equirect `DataTexture`, then* Keep dome and bake the same function, and paint the cloud shapes faintly intothe bake too, so reflections agree with the sky the camera sees.-## Clouds that read in a still frame--Billboard sprite puffs beat everything else per token:--* ONE shared CanvasTexture: 4-8 overlapping white radial gradients on 128 px.-* Per cloud: 6-15 `THREE.Sprite`s in a flattened ellipsoid (x-spread 2-3x the- y), scales 8-25 m, opacity 0.35-0.7, bottoms tinted darker,- `depthWrite: false`.-* Overcast / cirrus: 1-3 huge planes at altitude with- `alpha = smoothstep(.5, .75, fbm(uv * k + t * dir))`, kept well above every- camera.-* Raymarched volumetrics only when clouds ARE the subject of the brief.--## Fog adds depth or eats the scene — nothing in between+## Clouds-`FogExp2` density 0.002-0.01 outdoors, always in the sky's hue family. Fog that-softens the far hills sells the depth; fog that hides the mid-ground kills the-frame, and the frame gate reads it as washed out. The shader-trap skill covers-the fog uniforms custom shaders must honour; this one only sets the numbers.+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: `makeClouds` / `makeCirrus` from `lib/clouds.js` (one ray-marched deck,+scene-lit); `makeCloudVolume` from `lib/cloudvolume.js` when a cumulus is close enough to+need internal light; 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.-## Order of operations+## Haze-1. Sky dome + sun direction. 2. JS mirror -> equirect bake ->-`scene.environment`. 3. Lights (see c3d-scene-lighting). 4. Only THEN-materials, water, assets — they are all downstream of the environment.+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`. `makeHeightFog` and `patchAerialPerspective` from+`lib/atmosphere.js` do ground fog and distance haze; `scene.fog` alone does the simplest+version. A clear dry day may have almost none. The shader-trap skill covers the fog uniforms+custom shaders must honour.## Verify before you finishRender one frame and look at a reflective surface: water or glass mirroring aBRIGHT sky half means the bake is upright; mirroring darkness at midday meansrow 0 went to the zenith. `references/exotic-space.md` holds the validated-black-hole / nebula / planet recipes for space briefs.+black-hole / nebula / planet notes for space briefs.diff --git a/harness/codeverse3d/skills/c3d-scene-atmosphere/references/exotic-space.md b/harness/codeverse3d/skills/c3d-scene-atmosphere/references/exotic-space.mdindex b6e79e33..4c7a4144 100644--- a/harness/codeverse3d/skills/c3d-scene-atmosphere/references/exotic-space.md+++ b/harness/codeverse3d/skills/c3d-scene-atmosphere/references/exotic-space.md@@ -1,58 +1,48 @@-# Exotic space recipes (black hole, wormhole, nebula, planet)+# Exotic space notes (black hole, wormhole, nebula, planet)Ported 2026-09-01 from the scene_multifile_graphics reference ledger; the black-hole recipe was validated live there (mf36_blackhole, 2026-07-29) including two-measured failure modes quoted below. Everything is raw three.js + GLSL.+hole approach was validated live there (mf36_blackhole, 2026-07-29) including two+measured failure modes quoted below. Everything is raw three.js + GLSL; each is one+option that has been seen to work, for a brief that asks for it.## Black hole — one shader, not meshes-Scene-graph rings read as neon toys. The Interstellar look is ONE-ShaderMaterial on a shell — `SphereGeometry(2.5 * r_out)`, `side: BackSide`,-`transparent: true`, `depthWrite: false` — centred on the hole, raymarched in-the fragment shader with bent rays. Camera-independent: ray origin from the-built-in `cameraPosition` uniform.--* FAST-FORWARD the ray to the hole first — `float toHole = dot(-ro, rd);- ro += rd * max(0.0, toHole - 1.5 * r_out);` — or a distant camera exhausts- the step budget before the disk and the hole renders as a bare ring- (steps x dt must exceed ~3x r_out of REMAINING path, never camera distance).-* Step 30-40 times: `vec3 g = -p * strength / pow(dot(p,p), 1.5);- rd = normalize(rd + g*dt); p += rd*dt;`-* Disk accumulation wherever the bent ray crosses the equatorial plane inside- [r_in, r_out]: temperature ramp white-hot -> orange -> deep red by radius,- x azimuthal fbm streaks sheared Keplerian (`phi + t / pow(r, 1.5)`),- x Doppler boost `1.0 + 0.6 * dot(diskTangent, -rd)`.-* Sample the disk as a THIN SLAB, not only on sign crossings:- `bool crossed = (pn.y > 0.) != (p.y > 0.); bool inSlab = abs(pn.y) < 1.5;`- accumulate on either (slab samples weighted ~0.22). Crossing-only sampling- makes the disk VANISH edge-on — rays parallel to the plane never flip sign+Scene-graph rings read as neon toys. The lensed look is ONE ShaderMaterial on a+`BackSide` shell around the hole, raymarched in the fragment shader with bent rays,+camera-independent (ray origin from the built-in `cameraPosition` uniform).++* Fast-forward the ray to the hole first (`ro += rd * max(0.0, toHole - 1.5 * r_out)`),+ or a distant camera exhausts the step budget before the disk and the hole renders as+ a bare ring: steps x dt has to cover the REMAINING path, not the camera distance.+* Bend per step: `rd = normalize(rd + g*dt)` with `g = -p * strength / pow(dot(p,p), 1.5)`.+* Accumulate the disk wherever the bent ray crosses the equatorial plane inside the+ disk's radii: a temperature ramp by radius, azimuthal fbm streaks sheared Keplerian,+ a Doppler boost from the disk tangent.+* Sample the disk as a THIN SLAB, not only on sign crossings — crossing-only sampling+ makes the disk VANISH edge-on, because rays parallel to the plane never flip sign(measured live in the reference run).-* Rays spiralling inside ~1.4 r_s terminate BLACK with alpha 1 — the shader- paints its own shadow; remove any solid black sphere mesh or it occludes the- fold. Scale `dt ~ r_out / 20` so ~90 steps cross the shell (a dt tuned on a- small test hole renders a big one invisible).-* The far-side fold over/under the horizon and the photon ring come free from- the bending — never model them as geometry. Background lensing: the- starfield sphere's fragment offsets its sample direction toward the hole by- `strength / b2` outside the shadow radius.+* Rays spiralling inside the horizon terminate BLACK with alpha 1 — the shader paints+ its own shadow; a solid black sphere mesh occludes the fold. Scale `dt` with the shell+ (a dt tuned on a small test hole renders a big one invisible).+* The far-side fold and the photon ring come free from the bending; modelling them as+ geometry is what reads as a toy. Background lensing: the starfield's fragment offsets+ its sample direction toward the hole outside the shadow radius.## Wormhole-Camera-facing open `TubeGeometry` along a curved spine (`side: BackSide`),-polar-uv fbm palette scrolling toward the far end, bright rim at the mouth,-radial streaks converging inward; a DIFFERENT star pattern visible through the-throat is what sells it.+A camera-facing open `TubeGeometry` along a curved spine (`side: BackSide`), a polar-uv+fbm palette scrolling toward the far end, a bright rim at the mouth; a DIFFERENT star+pattern visible through the throat is what sells it.## Nebula and starfield-10-30 large additive fbm-canvas billboards (alpha = fbm^2, magenta/cyan/orange)-plus a few near-black NORMAL-blended dust-lane sprites. Starfield: `Points`-5-10k with power-law brightness (`pow(rand(), 3.0)`), slight colour spread,-3-5 hero stars with cross-flare sprites.+Large additive fbm-canvas billboards (alpha = fbm squared) in two or three hues, plus a+few near-black NORMAL-blended dust-lane sprites. Starfield: `makeStars` from+`lib/celestial.js`, or `Points` with power-law brightness, a slight colour spread and a+few hero stars with cross-flare sprites.## Planet-Sphere with canvas-baked fbm continents + bumpMap; atmosphere rim = 1.03x-sphere, `side: BackSide`, additive fresnel (`pow(1. - dot(N, V), 3.5)`); cloud-shell at 1.01x. Space background is never pure #000 (additive blending clips) —-use #020208.+A sphere with canvas-baked fbm continents and a bump map; an atmosphere rim as a slightly+larger `BackSide` shell with an additive fresnel; a cloud shell just above the surface. A+space background of pure black clips additive blending; a very dark blue-black does not.diff --git a/harness/codeverse3d/skills/c3d-scene-composition/SKILL.md b/harness/codeverse3d/skills/c3d-scene-composition/SKILL.mdindex ff4cfbe2..864a5fc7 100644--- a/harness/codeverse3d/skills/c3d-scene-composition/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-composition/SKILL.md@@ -1,13 +1,13 @@---name: c3d-scene-composition-description: "Use when a scene_threejs session owns the environment, a zone's placement or the camera list, or when scene_frames reported a camera problem. Lay out the scene so the harness's deterministic instruments agree with the picture - one height function everything samples, a world that does not end in shot, and cameras computed from measured bounds instead of guessed. Includes the sky/ground/content classifier that silently decides two gate findings, and the camera-placement rules and score caps scene_frames checks."+description: "Use when a scene_threejs session owns the environment, a zone's placement or the camera list, or when scene_frames reported a camera problem. States what the harness's deterministic instruments require of a composition - one height function everything samples, a world that does not end in shot, cameras whose eye, clearance and coverage are measured - and how each is measured, so the brief's own place can satisfy them in its own way. Includes the sky/ground/content classifier that silently decides two gate findings, the camera score caps, and a menu of horizon treatments."license: Apache-2.0compatibility: track scene, language scene_threejs (three r182, headless Chrome, the harness builds the cameras from your plain camera objects).metadata:evidence: mixedevidence_note: "Camera checks, score caps and the backdrop classifier are read from live code (spatial/frame_metrics.py, judges/rubrics/scene_v2.yaml, runtime_js/lib/backdrop.mjs, runtime_js/lib/scene_host.mjs). The corpus behind them is thin: only 3 graded scene runs exist, so every count below names its n."- verified: "2026-08-25"- corpus: "3 graded scene_threejs runs with gate artefacts, mined 2026-08-25"+ verified: "2026-10-15"+ corpus: "3 graded scene_threejs runs with gate artefacts, mined 2026-08-25; 60 argon iteration-0 scenes re-read 2026-10-15 for the sameness audit"target_metric: "camera_placement_findings"target_direction: "down"target_unit: "findings per run"@@ -18,19 +18,27 @@ metadata:# Composing a scene the instruments can read**Read this if** you are writing `env.js`, placing a zone, or returning the `cameras`-array. Two of the three graded scene runs in this corpus carry a composition issue and it is-the same one in both — a visible world edge — and one of those two also placed three-authored cameras below the ground. Both failures are arithmetic, not taste.--## Build in this order--1. **Bounds** — read `BOUNDS` from the plan. Everything below is derived from its- horizontal diagonal `diag`.-2. **One height function.** `heightAt(x, z)` in `env.js` is the only terrain authority.- The ground mesh samples it, every zone samples it, every camera samples it. A zone that- invents its own ground level is how props end up buried and cameras end up underground.-3. **Ground**, then **horizon**, then zones, then cameras. Cameras last, because they are- computed from what exists.+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@@ -47,7 +55,7 @@ coverage gate) and `ground_y` (the camera-height gate). The rules, in order:| span > 40 m and height < 2% of span (any name) | ground || everything else | content |-Three consequences you must design around:+Three consequences to design around:* **A wide flat slab is ground whatever you call it.** A 50 m plaza deck or a big pond isclassified ground, so it stops counting as content, and its *top* raises `ground_y`.@@ -55,9 +63,9 @@ Three consequences you must design around: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.-* **Instanced scatter always counts as content.** The cheapest way to lift a thin- establishing shot is more instanced planting and props, not a- bigger ground plane (which counts against you).+* **`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@@ -69,21 +77,24 @@ turns those ERRORs into score ceilings:|---|---|---|---|| nearest surface < 0.5 m, or the camera is inside a mesh box | `NEAR_HIT_M` | `camera inside / touching geometry` | **0.50** || eye below ground and the frame corroborates it (dark, empty or one-colour) | — | `camera_underground` | **0.50** |-| establishing shot that is mostly sky/ground | — | `establishing shot shows too little content` | **0.60** |+| the first camera (measured as the establishing shot) shows < 20 % content | — | `establishing shot shows too little content` | **0.60** || any authored shot that is almost all sky/ground | — | `shot shows little content` | WARN || eye less than 0.3 m above ground | `EYE_MIN_ABOVE_GROUND_M` | `ant's-eye view` | WARN || eye more than 80 m above ground | `EYE_MAX_ABOVE_GROUND_M` | `satellite view, not a shot` | WARN || one luminance band dominates the frame | — | `flat frame` | WARN; ERROR and **0.65** when it holds nearly all of it |-So compute, never guess:+So compute the eye from the terrain and aim each camera at the subject the brief gives it:```js-const y = heightAt(x, z) + 1.6; // human shot: terrain FIRST, then eye height-const d = Math.max(size.x, size.z); // measured content span, sky dome excluded-const establishing = { name: 'Establishing', fov: 42,- position: [c.x + d * 0.55, size.y * 1.1 + 6, c.z + d * 0.6], lookAt: [c.x, 2, c.z] };+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. A strong+option for the establishing shot is `establishingShot` from `lib/place.js`, which takes the+hero object and derives distance and height from its measured box; `seat` and `shot` in+the same module place a camera or a prop on the surfaces you pass. Whatever you use, 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@@ -91,36 +102,42 @@ Two notes that save a wasted repair round: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 horizon ring or sky dome is never clipped.--## The world must not end in shot--This is the most repeated judge complaint on the track and **no gate catches it** — all 4-composition issues recorded across the 3 graded scene runs (2 major, 2 minor, mined-2026-08-25) are the same sentence: *a hard world edge is visible where the ground plane ends-and meets the sky*. The arithmetic that kills it, all derived from `diag`:--```-fogScale = clamp(diag / 100, 0.3, 2.5) // the cookbook's fog table is for 100 m-fogFar = fogScale * (the time-of-day row's far)-groundSize >= 2.4 * fogFar // ground reaches past the fog-ringRadius = max(0.6 * fogFar, 2 * (diag / 2)) // silhouette ring, 24-40 solid shapes-skyRadius > ringRadius // the dome has to contain the ring-fog colour == the sky's horizon colour // or the ground ends AT the sky, not IN it-```--Solid shapes, never plane billboards, and never hand-tint the ring toward the fog colour —-`scene.fog` already does that by distance, and doing it twice produces the pale cardboard-the judge grades as a placeholder material. Code: the cookbook section "Horizon: the world-must not end" and the cookbook section "Atmosphere: time-of-day triads with numbers"-for the fog row.--## What you have already been given, and what you have not--`env` sessions receive the *Ground that reads real*, *Horizon*, *Atmosphere* and *Dusk /-night lighting* chapters inlined in the prompt. **Zone, compose and refine sessions do-not** — if you own a zone or the camera list, this skill plus the cookbook is the whole-of your guidance on the horizon and on camera placement.+ 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** (`makeImposters` from `lib/woodland.js` at distance) or an orchard edge.+* **A far skyline** — `cityFabric` from `lib/building.js`, a harbour wall, a viaduct.+* **A shoreline**: `makeOceanSurface` or `makeOcean` 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 (`makeHeightFog`, `patchAerialPerspective` from `lib/atmosphere.js`).+* **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@@ -130,5 +147,5 @@ those six numbers against the table above rather than judging the thumbnails by`scene_probe` for triangles, draw calls and fps. A camera that fails the table fails itdeterministically; there is nothing to argue with.-Worked derivations — bounds to fog to ring to the three cameras, and the coverage-repair-checklist — are in `references/measured-cameras.md`.+`references/measured-cameras.md` holds the finding-to-fix table and the naming rules the+classifier reads.diff --git a/harness/codeverse3d/skills/c3d-scene-composition/references/measured-cameras.md b/harness/codeverse3d/skills/c3d-scene-composition/references/measured-cameras.mdindex 69ca4ff5..a4c9a6b8 100644--- a/harness/codeverse3d/skills/c3d-scene-composition/references/measured-cameras.md+++ b/harness/codeverse3d/skills/c3d-scene-composition/references/measured-cameras.md@@ -1,65 +1,39 @@-# From bounds to cameras, by arithmetic+# The camera instruments, and what each finding asks you to changeCompanion to `c3d-scene-composition`. Constants read from`codeverse3d/spatial/frame_metrics.py`, `codeverse3d/judges/rubrics/scene_v2.yaml`,`runtime_js/lib/backdrop.mjs`, `runtime_js/lib/host_census.mjs` and-`runtime_js/lib/scene_host.mjs` on 2026-08-25.+`runtime_js/lib/scene_host.mjs` on 2026-08-25, re-read 2026-10-15.-## 1. One derivation, top to bottom+## 1. Measure the content, then place the eye-```js-import { BOUNDS, heightAt } from './env.js';--const span = [BOUNDS.max[0] - BOUNDS.min[0], BOUNDS.max[2] - BOUNDS.min[2]];-const diag = Math.hypot(span[0], span[1]); // horizontal diagonal of the plan bounds-const fogSc = Math.min(2.5, Math.max(0.3, diag / 100)); // the cookbook fog table is for 100 m-const fogFar = FOG_FAR_FOR_TIME_OF_DAY * fogSc; // e.g. dusk = 140 * fogSc-const ground = 2.4 * fogFar; // ground plane side length, minimum-const ringR = Math.max(0.6 * fogFar, diag); // silhouette ring radius (2 x half-diagonal)-const skyR = ringR * 1.35; // the dome must contain the ring-```--A 45 m garden at dusk: `fogSc = 0.45`, `fogFar = 63 m`, ground >= 151 m, ring at 38 m, dome-at 51 m. A 240 m valley at noon: `fogSc = 2.4`, `fogFar = 528 m`, ground >= 1267 m, ring at-317 m. Those are the numbers; do not carry the 100 m table across unscaled.--## 2. The three cameras, computed+The content box is what the cameras are derived from — measured, with the sky excluded:```js-function planCameras(THREE, scene, heightAt, hero /* {x, z} of the hero prop */) {- const box = new THREE.Box3();- scene.traverse(o => { if (o.isMesh && !/sky|dome|horizon/i.test(o.name)) box.expandByObject(o); });- const size = box.getSize(new THREE.Vector3()), c = box.getCenter(new THREE.Vector3());- const d = Math.max(size.x, size.z);- const eye = (x, z) => heightAt(x, z) + 1.6;- return [- { name: 'Establishing', fov: 42,- position: [c.x + d * 0.55, size.y * 1.1 + 6, c.z + d * 0.6], lookAt: [c.x, 2, c.z] },- { name: 'CourtyardMid', fov: 50,- position: [c.x + 8, eye(c.x + 8, c.z + 6), c.z + 6], lookAt: [c.x, 2, c.z - 6] },- { name: 'LanternDetail', fov: 45,- position: [hero.x + 2.5, eye(hero.x + 2.5, hero.z + 1.5), hero.z + 1.5],- lookAt: [hero.x, 0.6, hero.z] },- ];-}+const box = new THREE.Box3();+scene.traverse(o => { if (o.isMesh && !/sky|dome/i.test(o.name)) box.expandByObject(o); });+const size = box.getSize(new THREE.Vector3()), c = box.getCenter(new THREE.Vector3());+const eye = (x, z) => heightAt(x, z) + EYE; // the brief's eye height, on the terrain```-`hero` is the hero prop's own position — take it from the zone that built it, not from a-number you remember. Then check each one against the table in the skill before you-build anything else.+From there every camera is the brief's: what it looks at, from where, how many. A hero's+position comes from the zone that built it, not from a number you remember. The first+camera in the array is measured as the establishing shot (>= 20 % of its frame content).+`establishingShot`, `seat` and `shot` in `lib/place.js` derive a camera from an object's+measured box and the surfaces you pass, if you want the arithmetic done for you.-## 3. When a finding fires: what to change+## 2. When a finding fires: what to change| finding | the number that is wrong | change ||---|---|---|| `camera inside / touching geometry: inside ['CityTower']` (cap 0.50) | the camera sits in a mesh box | move it out along the lookAt direction until `nearest_hit_m >= 0.5`; do not shrink the building || `camera is N m below the ground level` with a dark or empty frame (cap 0.50) | you used an absolute y | `position[1] = heightAt(x, z) + 1.6` || same finding but the frame renders fine | nothing, probably | a hill or terrace is above the camera; verify with the frame, then leave it |-| `establishing shot shows too little content: content 11% (sky 52%, ground 37%)` (cap 0.60) | the shot is mostly backdrop | pull the camera in to about 1.2 x the content span, lower it, or add instanced content — a bigger ground plane makes this **worse**, because ground is not content |+| `establishing shot shows too little content: content 11% (sky 52%, ground 37%)` (cap 0.60) | the shot is mostly backdrop | bring the camera closer to the subject, lower it, or put more of the place in that view — a bigger ground plane makes this **worse**, because ground is not content || `flat frame: one luminance band holds 100% of the pixels` | no tonal range | aim at content, add a shadow-casting key, vary materials; recorded twice in one desert-canyon run at 85% and 100% || `frame too dark: mean luminance 0.06` | exposure | that is `c3d-scene-lighting`'s table, not composition |-## 4. Naming, because names change the classification+## 3. Naming, because names change the classification| you want it to be | name it | and shape it ||---|---|---|@@ -71,7 +45,7 @@ The trap is the accidental one: a wide flat mesh over 40 m across and flatter thspan is classified **ground whatever its name**, so a big deck, jetty or plaza silently stopscounting as content, and its top surface becomes `ground_y` for every camera check.-## 5. Cheap self-check before you finish+## 4. Cheap self-check before you finish```scene_probe -> triangles, draws, console errors, custom-shader mesh countdiff --git a/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md b/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.mdindex f2b0fba2..ace9dbdf 100644--- a/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-lighting-description: "Use when lighting a scene_threejs baseline, env or refine session, or when scene_frames called a frame too dark, blown out or flat. Light the scene so the frame gate passes and the mood still reads. Gives what the frame gate measures, the key / fill / practical recipe with numbers, and the one thing hex colours hide - how dark an albedo really is once the renderer works in linear light."+description: "Use when lighting a scene_threejs baseline, env or refine session, or when scene_frames called a frame too dark, blown out or flat. Light the scene so the frame gate passes and the mood still reads. Gives what the frame gate measures (the exposure band every authored camera has to sit in), the one thing hex colours hide - how dark an albedo really is once the renderer works in linear light - and the sky-lit / practical-lit cases with the starter sunRig as one toolbox."license: Apache-2.0compatibility: three r0.182, headless WebGL; renderer fixed at ACES Filmic tone mapping, exposure 1.0, sRGB output.metadata:evidence: mixedevidence_note: 'The checks and renderer settings are read from live code, namely spatial/frame_metrics.py and runtime_js/lib/browser/renderer.js, and the luminance figures are computed from those settings. The corpus half is thin and labelled as such, being 4 scene_threejs runs in scenes_v1_flash mined 2026-08-25, so it is quoted as examples and never as a rate.'- verified: "2026-08-25"+ verified: "2026-10-15"target_metric: "dark_or_flat_frames"target_direction: "down"target_unit: "findings per run"@@ -22,9 +22,9 @@ The harness renders every camera and scores the pixels (`spatial/frame_metrics.p| finding | fires when | severity ||---|---|---|-| too dark | dim on average *or* mostly near-black pixels | ERROR on an authored camera, WARN on a harness rig view |-| blown out | a large share of pixels pure white | same |-| flat frame | one luminance band dominates the frame (an ERROR on an authored camera when it holds nearly all of it) | WARN / ERROR |+| too dark | mean luminance under 0.12 *or* more than 35 % of pixels near-black | ERROR on an authored camera (cap 0.55), WARN on a harness rig view |+| blown out | more than 20 % of pixels pure white | same (cap 0.60) |+| flat frame | one luminance band dominates the frame (an ERROR, cap 0.65, when it holds more than 92 %) | WARN / ERROR |Two consequences people get wrong:@@ -54,78 +54,66 @@ everything else equal:A scene made of dark foliage stays dim **even when it is fully lit**, and doublingthe key only moves it to 0.27. Neither more light nor more exposure changes the ratio — only-a lighter albedo does. So: lift the albedos of the large surfaces first, then light. Ground-albedo below about 0.25 is a scene that cannot pass without heroic lighting.+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 nearthe floor.-## The recipe--* **Tint, do not dim** — for DUSK, and for a night lit from the sky. Dusk is coloured- darkness, so change the key's hue and the hemisphere's rather than turning the key down.- Take the whole row from the cookbook's time-of-day table rather than inventing a triad.-* **But a PRACTICAL-lit night really is dim, and fill will ruin it.** When the brief says- the light comes from lanterns, lamps, fire, neon or windows, the picture is supposed to- be dark between them: that contrast IS the subject. Adding AmbientLight or a- HemisphereLight to lift the average is the single most destructive thing you can do to- such a scene — measured 2026-08-25 on a lantern-lit temple courtyard, the added fill- washed dark granite paving to near-white, flattened the whole frame to "snow at dawn",- and drowned a KoiWater ShaderMaterial that was running correctly the entire time. Light- it from its own practicals instead: emissive on the lamp, a PointLight at each one, a- low but non-zero base colour on dark materials so they read as material and not as void,- and shadows left dark. The gate now tells these two cases apart — a dim frame WITH- real contrast is reported as "dim but lit" and is only a WARN.-* **The sun is white at noon and warm only near the horizon.** A warm sun at high elevation- reads as an error, not as mood.-* **The fill is the opposite hue from the key.** Hemisphere light is sky colour above,- ground bounce below; keep its colour at least 60 degrees of hue from the sun's. Warm key- plus warm fill is the monochrome-orange soup that gets marked down.-* **Emissive is a material, not a light.** An emissive surface glows in the image (the- default post chain blooms it) and illuminates nothing. Pair every lantern, window or fire- with a small PointLight.-* **Fog colour is the sky's horizon colour**, never white or grey unless the brief says- overcast, and never a black background.--Working numbers for a scene lit from the SKY (day, overcast, dusk), straight from the-gate's fix hint: the starter's `sunRig({ mood, intensity, fill, sunColor, fillSky, fillGround })`-— pick the mood (`day | golden | night | overcast`; a set sun is the night rig), raise-`intensity` / `fill` (the rig clamps requests below its floors UP, so under-lighting is not-reachable through it), never a second DirectionalLight on top — plus the practicals of-cookbook section "Dusk / night lighting recipe" (an emissive and its own small PointLight,-numbers from `PRACTICAL` in `lib/environment.js`). If the frame is blown instead: `intensity`-at the floor, `fill` <= 1.2, sky below 0.9 white, large emissive surfaces back at the-practical level.--For a scene lit from its PRACTICALS the target is contrast, not average — but it is a-BAND, not a floor you can fall through. Aim at real contrast with a dim-but-lit mean and-little pure black on every authored camera. Keep the starter's night rig as it is — its-moon key and hemisphere fill (clamped up to a measured readability floor) are what "dark but-lit" was measured with — and add no AmbientLight, no second HemisphereLight and no second-DirectionalLight on top of it.--Both ends of that band are measured failures, one week apart in the same wave:-* Over the top: chasing a sky-lit average in a lantern-lit courtyard produced a- flat grey wash whose granite paving read as snow and whose working water shader was- invisible.+## 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. The- reason is the rule three bullets up — **emissive illuminates nothing**. A glowing sign- with no PointLight beside it lights the frame exactly as much as an unlit one does.--One run managed both ends at once, which is the clearest sign that "darker" is not the-instruction: in the same temple scene, the CenserDetail frame was a near-black silhouette-where only the censer's glowing interior was legible, while the overview cameras looked-across a pale washed-out ground plane. Under-lit where it was art-directed, over-lit where-it was not. Check the band on EVERY camera, including the harness rig views nobody wrote-a shot for — that is where a scene quietly keeps the failure you thought you had fixed.--So removing fill is only half the instruction and is destructive alone. Every lantern,-lamp, sign, window or fire near the camera needs its OWN `PointLight` next to its emissive-surface — the cookbook recipe's `PRACTICAL` — so that the lit pools overlap into a readable-picture. The practicals are the lighting rig; the emissive is only what the fixture looks-like.+ 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; `makeNeonTube` + `patchNeonSpill` in `lib/neon.js` do a sign and the+light it throws), 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 withgenuinely different albedos, and a camera aimed at content rather than at sky.@@ -138,8 +126,5 @@ there is no reason to guess. A dark harness rig view is only a WARN, but the codwrites these findings records a measured case where exactly that cost a battery a 0.60 capthree rounds running — fix it anyway.-Code and the full palette table: cookbook `scene_threejs` sections *Dusk / night lighting-recipe*, *Atmosphere: time-of-day triads with numbers*.-Worked numbers, the linear-luminance arithmetic and a per-time-of-day check:`references/exposure-math.md`.diff --git a/harness/codeverse3d/skills/c3d-scene-lighting/references/exposure-math.md b/harness/codeverse3d/skills/c3d-scene-lighting/references/exposure-math.mdindex 97a81f07..d827bfb3 100644--- a/harness/codeverse3d/skills/c3d-scene-lighting/references/exposure-math.md+++ b/harness/codeverse3d/skills/c3d-scene-lighting/references/exposure-math.md@@ -33,6 +33,7 @@ pixels in the frame).## Step 3 — where the headroom is+| frame value | linear scene luminance ||---|---|| 0.12 | 0.029 || 0.15 | 0.037 |@@ -47,8 +48,8 @@ the number a lot; that is the cheapest place to fix a dark scene.## Step 4 — sanity numbers for the coloured-darkness rows-Relative luminance of the cookbook's dusk and night palette entries, so you can see that-"dark" there means roughly 0.03 and not 0.00:+Relative luminance of a few dusk and night swatches (the starter rig's moods use colours in+this range), so you can see that "dark" there means roughly 0.03 and not 0.00:| swatch | linear luminance ||---|---|diff --git a/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md b/harness/codeverse3d/skills/c3d-scene-materials/SKILL.mdindex 1c784203..15c8e49a 100644--- a/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-materials-description: "Use in every scene_threejs build or refine session that authors surfaces - terrain, buildings, props, vegetation. The strongest 'plastic toy' tell is a flat albedo; the second is identical twins. Gives the photographic checklist: procedural variance on every large surface, per-instance jitter, roughness as the realism dial, bevels near the camera, the tight shadow camera, domain-warped terrain with banded colour, and scatter that is intentional instead of uniform."+description: "Use in every scene_threejs build or refine session that authors surfaces - terrain, buildings, props, vegetation. The strongest 'plastic toy' tell is a flat albedo; the second is identical twins. States what the judge reads at crop scale (placeholder_material, flat_ground, monotonous_vegetation, undressed_scene, asset_quality_detail) and what the placement gate measures, then offers short optional practices with the shipped library's real API: surface variance, per-copy variation, roughness, edges near the lens, terrain that reads as a landform, vegetation variety, dressing and seating."license: Apache-2.0compatibility: three r0.182, headless WebGL; ACES tone mapping, GTAO + soft bloom supplied by the renderer.metadata:evidence: inherited-unverified- evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger (its 18-reviewer audit of 137 scenes; flat walls and duplicated assets are among its most-cited defects, and trees/rocks its two weakest measured classes). Not yet A/B-validated here; the sceneloop battery attaches our numbers.'- verified: "2026-09-01"+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger (its 18-reviewer audit of 137 scenes; flat walls and duplicated assets are among its most-cited defects, and trees/rocks its two weakest measured classes). Not yet A/B-validated here; the sceneloop battery attaches our numbers. Condensed to requirements + optional practices 2026-10-15 after 60 argon scenes copied one recipe.'+ verified: "2026-10-15"target_metric: "flat_albedo_surfaces"target_direction: "down"target_unit: "large surfaces with zero value variance (prospective census)"@@ -16,78 +16,102 @@ metadata:# 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.+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.-## Never ship a flat albedo+## No large surface reads as one flat value-One constant `color` per large surface is the strongest plastic tell. Give-every large surface a subtle procedural map: a CanvasTexture of low-contrast-fbm (use the shared noise block from c3d-scene-water) as `map` multiplied-into the tint, or as `roughnessMap`; `repeat` scaled so one texel is 2-5 cm at-walking distance. Stone, plaster, soil and wood all read instantly better with-5-15% value noise.+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; `patchMicroBreakup` and `patchEdgeWear` from+`lib/surface_wear.js` chain onto any material you made yourself. A `noiseTexture` from the+same module as `roughnessMap` breaks a highlight into something other than a perfect oval.-## Vary per instance+## Copies do not read as twins-Copies of one asset get +-6% hue and +-10% lightness jitter — clone the-material once per VARIANT, not per instance — plus scale 0.7-1.3, random-Y-rotation and a tiny tilt. Identical twins read as duplicated geometry;-slight variance reads as a place.+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); `instanceAsset` from `lib/instancing.js` takes+per-placement scale and rotation.## Roughness is the realism dial-Real surfaces are rarely uniform. Working numbers: wet stone 0.25, dry stone-0.85, painted wood 0.6, weathered wood 0.9, glass 0.05 with `envMapIntensity`-1.5, brushed metal 0.35 with metalness 0.8, foliage 0.75 with slight sheen.-Push a `roughnessMap` (same noise) so highlights break up instead of forming-perfect ovals.--## Bevel what the camera approaches--Razor 90-degree edges catch light unnaturally and read as CAD. Anything within-a few metres of a camera gets `ExtrudeGeometry` with `bevelEnabled` or an-equivalent chamfer. Background boxes can stay sharp.--## Terrain that is landscape, not noise blob--Heightfield: `PlaneGeometry(W, D, N, N)` displaced by 5-octave fbm with DOMAIN-WARP and a power curve — that pair is what separates hills from static:--```js-const y = Math.pow(fbm(x + 30 * fbm2(x * .008, z * .008), z), 1.6);-```--Recompute vertex normals AFTER displacing. Colour by slope and height bands-via vertexColors: rock where `normal.y < 0.65`, else sand -> grass -> rock ->-snow with smoothstep blends and +-5% hue jitter — never one flat green.--## Scatter intentionally--Uniform random scatter reads as noise. Jittered grid (spacing = the mean-distance you want, +-40% jitter), times a clump mask so groves and clearings-form (threshold the shared low-frequency noise at 0.5), times slope/height-rejection. Every instance: y from the SHARED height function, sunk 0.1 m so nothing-hovers on a blade of grass — the placement gate measures floaters.--## The tight shadow camera--The key and the fill are the starter's `sunRig` (its numbers: cookbook section-"Dusk / night lighting recipe"), and no third light without a reason. Its shadow camera-is fitted to `bounds`, so pass the radius the cameras can actually see, not the-world's: a shadow map stretched over two kilometres has metre-wide pixels and every-shadow is mush.--## Ground the frame--A low, wide gradient patch of darker ground colour under big structures, plus-the slight darkening where verticals meet the ground, anchors everything the-AO pass does not reach.+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`), a bevelled+`makePaving` for 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 — `patchSlopeSplat` and `patchTriplanar` from `lib/terrain_shade.js`+do that in the shader; 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, `makeCanopy` for every broadleaf crown and hedge,+`makeImposters` for a forest at distance), clusters with clearings rather than a lattice+(`scatterGrid` with jitter times a clump mask from `fbm2` is one option), and a ground+cover layer (`makeGrass`, `makeMeadow`) 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. `patchSeamBand` and `patchTracks` (`lib/roadway.js`) 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` (`seat` from `lib/place.js` seats an object on the surfaces+you pass); 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 the noise map. Find two copies of the same asset: if you-cannot tell them apart, jitter is missing. Look at one shadow edge: mush means-the shadow camera is too wide.+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.diff --git a/harness/codeverse3d/skills/c3d-scene-materials/references/terrain-and-scatter.md b/harness/codeverse3d/skills/c3d-scene-materials/references/terrain-and-scatter.mdindex 22241d25..7b3bc7bf 100644--- a/harness/codeverse3d/skills/c3d-scene-materials/references/terrain-and-scatter.md+++ b/harness/codeverse3d/skills/c3d-scene-materials/references/terrain-and-scatter.md@@ -1,48 +1,47 @@# Terrain and scatter — the deeper cut-## Domain warp, in full+Optional practices for a brief whose place has rolling or broken ground and natural+cover. A quay, a plaza, a street or a cave has other grounds; the brief decides.-Plain fbm terrain reads as static. Warping the INPUT coordinates by another-noise breaks the isotropy into ridgelines and valleys:+## Domain warp++Plain fbm terrain reads as static. Warping the INPUT coordinates by another noise breaks+the isotropy into ridgelines and valleys:```jsfunction height(x, z) {- const wx = x + 30 * fbm(x * 0.008, z * 0.008);- const wz = z + 30 * fbm(x * 0.008 + 100, z * 0.008 + 100);- return Math.pow(fbm(wx * 0.02, wz * 0.02), 1.6) * H_MAX;+ const wx = x + W * fbm2(x * 0.008, z * 0.008);+ const wz = z + W * fbm2(x * 0.008 + 100, z * 0.008 + 100);+ return Math.pow(fbm2(wx * 0.02, wz * 0.02), P) * H_MAX;}```-* The warp amplitude (30) is in METRES — scale it with the scene.-* The power curve (1.6-2.2) flattens lowlands and steepens peaks; without it- everything is rolling dough.-* This function is THE height authority: terrain mesh, water shoreline, every- scattered instance's y, and building foundations all call it. Two height- sources = floating trees, drowned paths (the placement gate measures both).--## Colour bands with jitter--Vertex colours, blended by smoothstep over height with a slope override:+* `W` (the warp) is in METRES — scale it with the scene; `fbm2` is `lib/noise.js`.+* The power curve `P` above 1 flattens lowlands and steepens peaks; without it everything+ is rolling dough.+* This function is THE height authority: terrain mesh, water shoreline, every scattered+ instance's y, and building foundations all call it. Two height sources = floating trees,+ drowned paths (the placement gate measures both).+* A landform is more than noise: a slope that drains to the water, a flat where the path+ runs, a terrace the buildings sit on. Add those terms to the function deliberately.- slope: normal.y < 0.65 -> rock gray- height < shore + 1 -> wet sand- < treeline -> grass (hue-jittered +-5%)- < snowline -> rock- else -> snow+## Colour by slope and height-Jitter every band's colour per-vertex by a high-frequency noise at +-5% value;-band edges get a 2-4 m smoothstep overlap, never a hard line.+Vertex colours or `patchSlopeSplat` (`lib/terrain_shade.js`): a steep-slope material+(rock, bare earth) overriding by `normal.y`, then height bands blended by smoothstep with+the materials the place has, each band jittered by a high-frequency noise, band edges+overlapping rather than a hard line.## Scatter masksThree multiplied gates, in order of visual weight:-1. Clump mask: low-frequency noise thresholded at ~0.5 — groves and clearings.-2. Slope rejection: no trees where normal.y < 0.75; no rocks on cliffs- steeper than ~55 degrees (they roll off in the viewer's head).-3. Jittered grid: spacing = target mean distance, +-40% uniform jitter — the- Poisson look without the Poisson cost.+1. Clump mask: low-frequency noise thresholded — groves and clearings.+2. Slope rejection: no trees on cliffs; rocks roll off steep faces in the viewer's head.+3. A jittered grid (`scatterGrid` from `lib/instancing.js`) — the Poisson look without+ the Poisson cost.-Per instance: y from the height authority sunk 0.1 m, random Y rotation, scale-0.7-1.3, tilt up to ~4 degrees along the slope normal, hue/lightness jitter-from the materials checklist. InstancedMesh for anything over ~40 copies.+Per instance: y from the height authority, yaw and scale varied, hue/lightness from+`tint`; `InstancedMesh` for anything repeated more than a handful of times (the contract's+efficiency rule). Keep each authored camera's first metres free of scatter: the frame gate+needs `nearest_hit_m` >= 0.5 m.diff --git a/harness/codeverse3d/skills/c3d-scene-motion/SKILL.md b/harness/codeverse3d/skills/c3d-scene-motion/SKILL.mdindex 1e577fa0..f18f8724 100644--- a/harness/codeverse3d/skills/c3d-scene-motion/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-motion/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-motion-description: "Use when a scene_threejs session authors or refines animation, or when scene_frames reported no motion or the judge said nothing_moves. Make the scene visibly move between the two frames the harness photographs, and survive the four mechanisms that silently freeze it. Applies to baseline, zone, refine and compose sessions. Covers how motion is measured, the single update hook the harness actually calls, the amplitudes that read at 1024 x 576, and why clearing the motion gate is not the same as scoring animation_life - that is judged per item against the plan animation list."+description: "Use when a scene_threejs session authors or refines animation, or when scene_frames reported no motion or the judge said nothing_moves. Make the scene visibly move between the two frames the harness photographs, and survive the four mechanisms that silently freeze it. Applies to baseline, zone, refine and compose sessions. Covers how motion is measured, the single update hook the harness actually calls, the amplitudes measured to read at 1024 x 576, and why clearing the motion gate is not the same as scoring animation_life - that is judged per item against the plan animation list."license: Apache-2.0compatibility: "scene track, language scene_threejs. three r182 in headless Chrome; the harness photographs each camera at t = 0 s and t = 1.5 s and diffs the pair."metadata:evidence: mixedevidence_note: "The mechanism and hook are read from live code (spatial/frame_motion.py, spatial/frame_metrics.py, runtime_js/lib/scene_host.mjs) and are exact. The corpus behind them is thin: 3 graded scene runs / 8 judged rounds on scenes_v1_flash, 2026-08-23. Where a number is from that battery it says so."- verified: "2026-08-25"+ verified: "2026-10-15"pairs_with: "c3d-scene-composition, c3d-scene-lighting, c3d-threejs-shader-traps"target_metric: "min_authored_changed_frac"target_direction: "up"@@ -39,7 +39,7 @@ camera and hands the judge the number:"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 target is concrete: **at least one authored camera visibly changes between+So the requirement is concrete: **at least one authored camera visibly changes betweent = 0 and t = 1.5 s.** A few centimetres of sway on a scene tens of metres widedoes not do it.@@ -48,8 +48,7 @@ does not do it.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.+`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 plannedanimations for water and falling leaves are completely static", "the planned@@ -60,8 +59,8 @@ moved; the things the plan promised did not.`animation` list verbatim, item by item, alongside the measured motion table. Sothe criterion is scored per item, not globally:-* **Every named item in the plan's animation list must be visibly moving on an- authored camera.** One hero mover clears the gate; it does not discharge a+* **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 afour-item animation plan.* **The amplitude written in the plan is intent, not a spec.** That rooftopscene's plan asked for "sway with sine displacement amplitude 0.035 m" and@@ -96,30 +95,28 @@ planned animation was absent while the code for it sat in `src/`.`update_ok: false` with the message — check it before you conclude theamplitude 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 hero motion in the- frame the first camera looks at.+ behind the establishing camera is worth nothing; put the motion in the+ frames the authored cameras look at.-## The shape that works+## 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`:```js-export async function createScene({ THREE, renderer, loaders }) {- const scene = new THREE.Scene();- const ctx = { THREE, scene, renderer, loaders }, env = buildEnv(ctx);- const zones = [buildGrove(ctx), buildHarbour(ctx)];- scene.add(...zones);- const movers = [env, ...zones].filter(Boolean);- return {- scene, cameras,- update(t, dt) {- for (const m of movers) (m.userData?.update ?? m.update)?.(t, dt);- },- };-}+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);+} };```-One list, built once, walked by the single hook the harness calls. 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.+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+(`makeFire`, `makeSmoke`, `makeOceanSurface`, `makeFlag` …) 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`@@ -130,47 +127,40 @@ on how many steps ran, which is exactly the thing a refine round changes byaccident. Write the pose, do not integrate it:```js-// yes-pivot.rotation.z = Math.sin(t / PERIOD * 6.283 + phase) * AMP;-leaf.position.y = home.y - ((t * FALL_SPEED + phase) % CYCLE);-// no-pivot.rotation.z += dt * SPEED;+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 more rules that follow from the pair of frames:+Two things that have made the difference register in the pair of frames:-* **Start mid-phase.** `Math.sin(0) = 0`, so a pure sine puts every sway at rest+* **Starting mid-phase.** `Math.sin(0) = 0`, so a pure sine puts every sway at restin the t = 0 photograph and the scene reads dead in the very frame the judge- looks at first. Give each element a phase offset, or drive it with- `Math.sin(t / P * 6.283 + 1.0)`.-* **Seed the phase per instance.** `phase = rand() * 6.283` 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.+ 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.-Never use `Math.random()`, `Date.now()` or `performance.now()` — the contract-forbids all three, and a non-deterministic scene makes the two frames-incomparable.+`Math.random()`, `Date.now()` and `performance.now()` are forbidden by the contract — a+non-deterministic scene makes the two frames incomparable.## Amplitudes that read-Give the scene **one unmistakable hero motion** — a turning wheel, a drifting-boat, falling leaves, a rotating beam, a flock — and then give every remaining-item on the plan's animation list an amplitude from this table. The hero clears-the gate; the rest of the list is what the criterion is scored against.+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 moves | amplitude over 1.5 s | period ||---|---|---|| foliage / banner sway | 0.10–0.20 rad (6–11 degrees) at the pivot | 1.6–3 s || grass, reeds | 0.15 rad, phase-offset per instance | 1.2–2 s || water | wave height at least 0.04 m **and** a scrolling uv/normal at 0.15 m/s | 2–4 s |-| falling leaves, petals, snow, dust | at least 0.6 m of travel, 60–250 particles | recycle over 6–12 s |+| falling leaves, petals, snow, dust | at least 0.6 m of travel | recycle over 6–12 s || flame / lantern flicker | intensity x0.75 to x1.3, plus `emissiveIntensity` | 0.1–0.3 s || vehicles, boats, birds | at least 1.5 m of travel | loop |-Pivot placement matters as much as amplitude: rotate a group whose origin is at-the **base** of the trunk or the **top** of the flagpole, so the far end swings.-Rotating the mesh about its own centre moves half as many pixels for the same+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 sameangle.## Prove it before you finish@@ -185,26 +175,26 @@ move the mover into frame. Do not ship on the strength of having written thecode — and if nothing at all moved, run `scene_probe` first: a frozen scene ismore often a thrown `update` than a small amplitude.-## People, vehicles, weather--* **A walking figure**: hierarchy person -> hips -> legs, torso -> arms,- pivots AT the joints, posed from t: `ph = t*3.2 + seed*6.283;- legL.rotation.x = sin(ph)*0.6; legR = -legL;` arms opposite-phase at 0.4x;- bob hips by `abs(cos(ph))*0.04`. Per-person seed on phase and speed- (+-20%) prevents lockstep; frozen mid-stride reads perfectly.-* **Paths**: people and vehicles ride a `CatmullRomCurve3` —- `getPointAt((t*speed/len + u0) % 1)`, face the tangent; distinct `u0`- offsets space the traffic; wheels spin `t*speed/wheelR`.-* **Rain is streaks, not dots**: `LineSegments` pairs `[p, p+vec3(.1,-1.4,0)]`- at opacity 0.3-0.5 — elongation IS the motion cue. Snow: soft-sprite- `Points` with per-flake sine sway. Every particle gets a random phase so a- frozen frame is mid-motion, never at a synchronized extreme.-* **Fire additive, smoke normal** — never swap: fire is crossed planes- scrolling fbm through a flame mask (`AdditiveBlending`) plus a flickering- orange PointLight; smoke is gray soft sprites, NORMAL blending.+## 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**: `figure` + `walk` from `lib/figure.js`; or 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**: `alongPath` / `route` / `crowdOn` in `lib/place.js`, or a `CatmullRomCurve3`+ sampled at `(t * speed / len + u0) % 1`, facing the tangent; distinct `u0` offsets space+ the traffic.+* **Rain** as elongated streaks (`makeRain`, `makeRainVeil` at distance) — elongation is+ the motion cue; **snow** as soft sprites with per-flake sway (`makeSnowfall`); **motes**+ and pollen from `makeMotes`; every particle gets its own phase so a frozen frame is+ mid-motion, never at a synchronized extreme.+* **Fire additive, smoke normal**: `makeFire` / `makeFireField` with a flickering light,+ `makeSmoke` / `makeSteam` as a bounded density — a chain of spheres is not steam.## Depth-`references/motion_recipes.md` — the sway pivot, the recycling particle field,-the scrolling-water uniform and the mover-registration pattern, each as code you-can paste and adapt.+`references/motion_recipes.md` — the sway pivot, a recycling particle field, the+scrolling-water uniform and the mover-registration pattern, short enough to adapt.diff --git a/harness/codeverse3d/skills/c3d-scene-motion/references/motion_recipes.md b/harness/codeverse3d/skills/c3d-scene-motion/references/motion_recipes.mdindex c6143ad1..1e4b96b3 100644--- a/harness/codeverse3d/skills/c3d-scene-motion/references/motion_recipes.md+++ b/harness/codeverse3d/skills/c3d-scene-motion/references/motion_recipes.md@@ -1,110 +1,60 @@-# Motion recipes+# Motion — what the measure needs, and the library's movers-Executed against the harness's own `[email protected]` in node on 2026-08-25; the-printed values are quoted under each block.+The measure: each authored camera is rendered at t = 0 and t = 1.5 s and the two frames are+differenced; a camera MOVES when ≥ 0.4 % of its pixels change by more than 8/255 (or ≥ 0.08 %+by more than 60/255). None moving is the gate's `no_motion` ERROR and the judge's+`nothing_moves`. Everything below is one way to clear it; the library's own movers+(`makeFalling` in `lib/flowers.js`, `makeSnowfall` / `makeMotes` in `lib/veils.js`,+`makeFlock` in `lib/flock.js`, `makeFlag` in `lib/cloth.js`, `patchWind` in `lib/foliage_shade.js`)+cover the common cases without any code of+yours, and each carries `userData.update(t, dt)` for the zone to call.-## The seeded hash you need first+## Seeded randomness`Math.random()` is forbidden (a non-deterministic scene makes the two photographs-incomparable, and the lint warns on it).--```js-const rand = (i) => { const s = Math.sin(i * 12.9898 + 78.233) * 43758.5453; return s - Math.floor(s); };-```--## Sway pivot — base-anchored, phase-seeded, mid-phase at t = 0--```js-function swayPivot(THREE, child, { name = 'Sway', amp = 0.14, period = 2.2, seed = 0 } = {}) {- const pivot = new THREE.Group(); pivot.name = name; pivot.add(child);- const phase = rand(seed) * 6.2832 + 0.8; // + 0.8 so t = 0 is NOT the rest pose- pivot.userData.update = (t) => {- pivot.rotation.z = Math.sin(t / period * 6.2832 + phase) * amp;- pivot.rotation.x = Math.sin(t / (period * 1.37) * 6.2832 + phase * 1.7) * amp * 0.55;- };- return pivot;-}-// seed 3, amp 0.14: rotation.z moves 0.209 rad between t = 0 and t = 1.5, and-// sits at -0.069 rad in the t = 0 frame rather than dead upright.-```--Three things are load-bearing and all three are cheap:--* the pivot Group's origin is at the **base** of what sways, so the far end- travels; the child geometry is translated up into it, not centred on it-* the two axes use incommensurate periods (`period` and `period * 1.37`) so the- motion never repeats exactly and never looks like a metronome-* `+ 0.8` in the phase means the t = 0 photograph catches the element already- leaning. A pure `Math.sin(t * k)` is exactly zero at t = 0, which is the frame- the judge sees first.--Wrap each instance with its own `seed` (its index in the scatter loop). A hundred-trees on one phase is one large object nodding — and worse for the pixel diff,-symmetrical crowds partly cancel: half the copies move into the pixels the other-half vacated.--## Falling particles — recycled, pure function of t--```js-function fallingField(THREE, n, area, { fall = 0.9, cycle = 8, seed = 0 } = {}) {- const pos = new Float32Array(n * 3), base = new Float32Array(n * 3), ph = new Float32Array(n);- for (let i = 0; i < n; i++) {- base[i*3] = area.x + (rand(i + seed) - 0.5) * area.w;- base[i*3+1] = area.top;- base[i*3+2] = area.z + (rand(i + seed + 600) - 0.5) * area.d;- ph[i] = rand(i + seed + 900) * cycle; // stagger, or they fall as one sheet- }- const geo = new THREE.BufferGeometry();- geo.setAttribute('position', new THREE.BufferAttribute(pos, 3));- const pts = new THREE.Points(geo, new THREE.PointsMaterial({ size: 0.05 }));- pts.name = 'Leaves';- pts.userData.update = (t) => {- const p = geo.attributes.position.array;- for (let i = 0; i < n; i++) {- const u = ((t + ph[i]) % cycle) / cycle; // wraps; no state accumulates- p[i*3] = base[i*3] + Math.sin((t + ph[i]) * 0.8) * 0.35;- p[i*3+1] = base[i*3+1] - u * fall * cycle;- p[i*3+2] = base[i*3+2] + Math.cos((t + ph[i]) * 0.6) * 0.35;- }- geo.attributes.position.needsUpdate = true; // without this nothing moves at all- };- return pts;-}-// 160 particles, fall 0.9 m/s: a leaf travels 1.35 m between t = 0 and t = 1.5,-// and calling update(1.5) twice returns the identical value.-```--The modulo is what makes recycling stateless: no counter to drift, no reset to-miss, and `update(1.5)` gives the same frame however many times it is called.-Allocate `pos`, `base` and `ph` once at build time — the contract forbids-per-frame allocation and `traverse` in `update`.+incomparable, and the lint warns on it). `mulberry32` from `lib/noise.js` is the shipped+generator (`lehmer` is the lighter one); one call per instance at build time gives each its+phase.++## A sway that registers++What has measured as visible (`[email protected]` in node, 2026-08-25): a pivot group whose origin+is at the BASE of what sways (the child translated up into it, not centred on it), a rotation+written as a pure function of `t` — a sine over the period the plan gives, with a per-instance+phase from the seeded generator so the t = 0 photograph catches the element already leaning —+and a second axis at an incommensurate period so the motion never reads as a metronome. At+0.14 rad amplitude a trunk swung 0.209 rad between the two frames and sat 0.069 rad off+upright in the first one; the plan's amplitude table says what reads for each kind of mover.+A hundred trees on one phase is one large object nodding, and symmetrical crowds partly+cancel in the pixel diff.++## Falling particles — recycled, a pure function of t++Allocate the position, home and phase arrays once at build time (the contract forbids+per-frame allocation and `traverse` in `update`); each frame then sets every particle's+position from `t` alone — the fall is `(t + phase) mod cycle` scaled by the speed, with a+small lateral drift from the same clock — and sets `geometry.attributes.position.needsUpdate+= true` (without it nothing moves at all). The modulo is what makes recycling stateless: no+counter to drift, no reset to miss. 160 particles at 0.9 m/s travelled 1.35 m between the+frames, and calling `update(1.5)` twice returned the identical value. The `PointsMaterial`+needs a radial-alpha sprite `map` with `transparent: true` and `depthWrite: false`, or every+particle is a square (`hard_edged_particles`, judged).## Registering movers-```js-// in each zone / asset builder-zone.userData.update = (t, dt) => { /* ... */ };--// in src/scene.js — ONE list, built once, walked by the one hook the harness calls-const movers = [env, ...zones, ...assets].filter(Boolean);-return { scene, cameras, update(t, dt) { for (const m of movers) (m.userData?.update ?? m.update)?.(t, dt); } };-```--Add to `movers` in the same edit that creates the mover. The harness calls-nothing else: not `userData.tick`, not `animate`, not a `requestAnimationFrame`-callback (that function is a stub here that returns 0 and never fires).+A zone's `group.userData.update = (t, dt) => { ... }` is the only zone hook the assembled+`src/scene.js` calls, and it calls it once per frame; an asset's own `userData.update` runs+only if its zone caches it at build time and calls it from there. The harness calls nothing+else: not `userData.tick`, not `animate`, not a `requestAnimationFrame` callback (that+function is a stub here that returns 0 and never fires). Register a mover in the same edit+that creates it.## Scrolling a shader without a clock of its own-A `ShaderMaterial` animates by having its `uTime` uniform written from the same-`update`, never by reading a clock inside itself (`Date.now` and-`performance.now` are forbidden, and the render happens at a simulated time, not-a wall-clock one).--```js-const water = makeWaterMaterial(THREE, { /* ... */ }); // uniforms: { uTime: { value: 0 }, ... }-group.userData.update = (t) => { water.uniforms.uTime.value = t; };-```+A `ShaderMaterial` animates by having its `uTime` uniform written from the same `update`,+never by reading a clock inside itself (`Date.now` and `performance.now` are forbidden, and+the render happens at a simulated time, not a wall-clock one): `mat.uniforms.uTime.value = t`+from the zone's hook.Two failure shapes to avoid: a uniform declared in the shader but missing from`uniforms` (`runtime_js/lib/host_compile.mjs` reports that as an `unbound_uniform`diff --git a/harness/codeverse3d/skills/c3d-scene-night/SKILL.md b/harness/codeverse3d/skills/c3d-scene-night/SKILL.mdindex cb54e9f1..5a55bbc0 100644--- a/harness/codeverse3d/skills/c3d-scene-night/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-night/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-night-description: "Use when a scene_threejs brief says night, dusk, evening, neon, lamplit or moonlit. Night scenes fail two ways: black frames (the gate catches those) and the CHRISTMAS-TREE look - every window a flat glow, light shafts like white tents, twelve competing hues. Gives the emissive-window recipe, glow without postprocessing, fake light pools, the measured shaft opacity, wet-road numbers, and the discipline of two light temperatures."+description: "Use when a scene_threejs brief says night, dusk, evening, neon, lamplit or moonlit. Night scenes fail two ways: black frames (the gate catches those) and the CHRISTMAS-TREE look - every window a flat glow, light shafts like white tents, twelve competing hues. States what is measured and judged, then the strong options: the library's night windows and neon, glow without postprocessing, fake light pools, the measured shaft ceiling, a wet road with something to mirror, and few light temperatures."license: Apache-2.0compatibility: three r0.182, headless WebGL; ACES tone mapping, exposure 1.0.metadata:evidence: inherited-unverified- evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger; the shaft-opacity ceiling is its measured finding (a normal-blended shaft at 0.3+ rendered as a solid white tent and buried the scene). Pair with c3d-scene-lighting, whose linear-vs-hex table is the other half of every night failure. Not yet A/B-validated here; the sceneloop battery attaches our numbers.'- verified: "2026-09-01"+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger; the shaft-opacity ceiling is its measured finding (a normal-blended shaft at 0.3+ rendered as a solid white tent and buried the scene). Pair with c3d-scene-lighting, whose linear-vs-hex table is the other half of every night failure. Not yet A/B-validated here; the sceneloop battery attaches our numbers. Condensed to requirements + options 2026-10-15.'+ verified: "2026-10-15"target_metric: "overbright_shaft_findings"target_direction: "down"target_unit: "solid-reading light shafts per run (prospective census)"@@ -16,56 +16,63 @@ metadata:# Night light — few sources, believable glow, no tents-The frame gate stops black frames; this skill is about the opposite failure:-night scenes lit like a fairground. Real night is ONE or TWO light temperatures-and a lot of dark. 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.+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 (buildings at night)+## Emissive windows-Per building ARCHETYPE (not per building), one CanvasTexture: dark facade,-window grid, ~35% of the rects lit warm with jitter, a few TV-blue. Use it as-`map` AND `emissiveMap`, `emissiveIntensity` 1-2. Emissive does NOT illuminate-anything else — pair each big lit facade or sign with one dim matching-PointLight so the street below agrees with the window above.+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). Strong option: `makeNightWindows(mesh)`+and `patchWindowInteriors` from `lib/windows.js`, which light a jittered fraction of the+grid with per-window colour; pair each big lit facade with one dim matching PointLight.+`references/window-canvas.md` describes the hand-made canvas version.## Glow without postprocessing-Two layered additive sprites per source: a small bright core plus a large faint-halo at ~0.15 opacity, both `depthWrite: false`; the bulb mesh itself is-`MeshBasicMaterial` (a lit bulb does not shade). One sprite reads as a sticker;-the two-layer stack is what reads as bloom.+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-The pool of light on the ground is an additive radial-gradient disc ON the-ground plus a faint gradient cone for the shaft. Keep real `PointLight`s (decay 2)-to the foreground lamps — WebGL forward lighting costs per-fragment per-light, and-thirty real lights is both slow and flat.+WebGL forward lighting costs per fragment per light, and thirty real lights is both slow and+flat. One option: real `PointLight`s (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-Additive blending, opacity 0.03-0.08, alpha fading along the cone. The-reference harness measured the failure: a NORMAL-blended shaft at 0.3+ opacity-renders as a solid white TENT and buries the scene behind it. If the shaft-reads clearly in a thumbnail, it is too strong.+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; `makeGodRays` from `lib/godrays.js`+does it with its own ceiling. If the shaft reads clearly in a thumbnail, it is too strong.-## Wet road (the night city's best friend)+## Wet road-Near-black road, `roughness 0.12-0.25`, `metalness ~0.8`, and a night-environment bake whose LOWER half carries the window/neon colours (the road-mirrors what is above it — see c3d-scene-atmosphere for the bake). Puddles:-a few irregular darker planes at `roughness 0.03`. Without the coloured bake+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) — `makeMirrorFloor` from `lib/wetground.js` and+`wetten` / `makePuddle` from `lib/rain.js` are the shipped versions. Without a coloured bakethe wet road has nothing to mirror and just goes black.-## Discipline: two temperatures+## Light that agrees with itself-Pick 1-2 dominant temperatures — sodium orange + cool white is the classic —-plus RARE neon accents. Every additional hue divides the frame's coherence.-The moon is one slate-blue DirectionalLight, not a second sun.+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 (more than 3 is a fairground);-check one lamp's ground pool exists; check no shaft reads as a solid; check-the road mirrors colour, not blackness.+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.diff --git a/harness/codeverse3d/skills/c3d-scene-night/references/window-canvas.md b/harness/codeverse3d/skills/c3d-scene-night/references/window-canvas.mdindex 185cd755..3b481eff 100644--- a/harness/codeverse3d/skills/c3d-scene-night/references/window-canvas.md+++ b/harness/codeverse3d/skills/c3d-scene-night/references/window-canvas.md@@ -1,24 +1,27 @@-# The emissive window canvas — exact construction+# The emissive window canvas — the hand-made version-One CanvasTexture per building ARCHETYPE. 256x256 canvas:+`makeNightWindows` and `patchWindowInteriors` in `lib/windows.js` do this for you; what+follows is how to build the same thing by hand when a facade needs a layout the library+does not have.-1. Fill the facade colour first — near-black warm gray (#141210), not #000.-2. Window grid: compute rows/cols from storey height (~3 m) and window pitch- (~1.8 m) so the texture's repeat over the building gives plausible storeys.-3. Per window rect (inset ~30% of the cell): lit with probability ~0.35.- Lit colour: warm white base (#ffd9a0) with per-window jitter of +-8% hue and- +-15% lightness; roughly 1 in 12 lit windows TV-blue (#9fc4ff) at lower- alpha. Unlit windows: slightly darker than the facade, never pure black.-4. A faint 1-px sill line under each window sells the relief at distance.+One CanvasTexture per building ARCHETYPE, not per building:-Use the SAME canvas as `map` and `emissiveMap`; `emissiveIntensity` 1-2;-`roughness` 0.9 on the facade so the windows, not the wall, carry the light.+1. Fill the facade colour first — a near-black warm grey, not pure black.+2. A window grid whose rows and columns come from the storey height and window pitch,+ so the texture's repeat over the building gives plausible storeys.+3. Per window rect, lit with a probability well under half, in a warm white with+ per-window hue and lightness jitter and the occasional cooler TV-blue at lower alpha.+ Unlit windows slightly darker than the facade, never pure black.+4. A faint sill line under each window sells the relief at distance.-Pair each large lit facade with ONE dim warm PointLight at street level in-front of it (intensity ~0.3, decay 2, distance ~2 storeys): emissive maps do-not light the street, and the missing bounce is what makes fake buildings+Use the SAME canvas as `map` and `emissiveMap`, with a high facade roughness so the windows,+not the wall, carry the light. The post chain blooms the emissive; a peak of a few units is+enough.++Pair each large lit facade with ONE dim warm PointLight at street level in front of it:+emissive maps do not light the street, and the missing bounce is what makes fake buildingsfloat in the dark.-Distant buildings: skip geometry relief entirely — a box with this texture-reads correctly past ~80 m. Near buildings: model the ground floor for real-(doors, awnings) and let the texture carry storeys 2+.+Distant buildings: a box with this texture reads correctly at distance. Near buildings:+model the ground floor for real (doors, awnings) and let the texture carry the storeys+above.diff --git a/harness/codeverse3d/skills/c3d-scene-water/SKILL.md b/harness/codeverse3d/skills/c3d-scene-water/SKILL.mdindex b2763368..353e09c7 100644--- a/harness/codeverse3d/skills/c3d-scene-water/SKILL.md+++ b/harness/codeverse3d/skills/c3d-scene-water/SKILL.md@@ -1,12 +1,12 @@---name: c3d-scene-water-description: "Use when a scene_threejs session builds water in any form - pond, lake, harbor, river, ocean, pool, canal, waterfall or fountain. Water is a dielectric, not a mirror: the single most common water bug is metalness, and the second is an environment bake it has nothing to reflect. Gives the material numbers, the shared noise block that keeps terrain, shoreline and scatter agreeing, the Gerstner ocean, and foam that reads."+description: "Use when a scene_threejs session builds water in any form - pond, lake, harbor, river, ocean, pool, canal, waterfall or fountain. Water is a dielectric, not a mirror: the single most common water bug is metalness, and the second is an environment bake it has nothing to reflect. States what has to be true and how the judge and the motion probe read it, then the library's water modules as the strong options, the shared noise block that keeps terrain, shoreline and scatter agreeing, Gerstner for open water, and foam that reads."license: Apache-2.0compatibility: three r0.182, headless WebGL; ACES tone mapping, exposure 1.0.metadata:evidence: inherited-unverified- evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger, which shipped the metallic-water mistake once and documented the fix, and whose equirect audit showed dark water is usually the ENVIRONMENT bake, not the water (see c3d-scene-atmosphere). Not yet A/B-validated here; the sceneloop battery attaches our numbers.'- verified: "2026-09-01"+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger, which shipped the metallic-water mistake once and documented the fix, and whose equirect audit showed dark water is usually the ENVIRONMENT bake, not the water (see c3d-scene-atmosphere). Not yet A/B-validated here; the sceneloop battery attaches our numbers. Condensed to requirements + options 2026-10-15.'+ verified: "2026-10-15"target_metric: "metallic_water_planes"target_direction: "down"target_unit: "water materials with metalness above 0.3 (prospective census)"@@ -16,71 +16,68 @@ metadata:# Water — a dielectric with something to reflect-Two facts produce almost every convincing water plane: water reflects the-ENVIRONMENT (build c3d-scene-atmosphere's bake first), and water is a-DIELECTRIC — it reflects ~2% head-on and ~100% at grazing angles. That fresnel-ramp is why real water is dark at your feet and mirror-bright at the horizon.--## The material (lake, harbor, pond, pool)--Flat plane + `MeshPhysicalMaterial`:--* `metalness: 0` and `ior: 1.333` — NON-NEGOTIABLE. Metallic water is a- uniformly tinted mirror at every angle: the dirty-chrome-puddle look. Do not- raise metalness to "make it reflective"; reflectivity comes from the- environment map through the fresnel ramp.-* `roughness: 0.05-0.15`, base colour a DARK blue-green (the environment- supplies the brightness).-* Motion: a small fbm normal `DataTexture` (RepeatWrapping), scrolled as TWO- copies at different scales and directions via `onBeforeCompile` (two layers- kill tiling), driven by the shared `uTime`.-* Bias the water plane ~0.02 BELOW the shore ground, or the shoreline- z-fights.--## The shared noise block (one source of truth for height)--Terrain height, water shorelines, foam and scatter masks must AGREE, so ship-value-noise + fbm ONCE in GLSL and mirror it exactly in JS:--```glsl-float hash(vec2 p){ return fract(sin(dot(p, vec2(127.1,311.7))) * 43758.5453); }-float noise(vec2 p){ vec2 i = floor(p), f = fract(p); f = f*f*(3.-2.*f);- return mix(mix(hash(i), hash(i+vec2(1,0)), f.x),- mix(hash(i+vec2(0,1)), hash(i+vec2(1,1)), f.x), f.y); }-float fbm(vec2 p){ float v = 0., a = .5;- for (int i = 0; i < 5; i++){ v += a * noise(p); p *= 2.03; a *= .5; } return v; }-```--One height function `h(x, z)` sampled by the terrain mesh, the shoreline foam,-tree placement and building foundations is the single biggest coherence win a-scene can buy.--## Shoreline foam beats crest foam--In the water fragment shader, foam from DEPTH against the shared height —-`1. - smoothstep(0., 1.2, waterLevel - h(x, z))`, multiplied by noise — hugs-the banks and reads instantly. Crest foam on open water is harder and pays-less.--## Open ocean — Gerstner, not scrolling normals--ShaderMaterial vertex shader summing 3-4 Gerstner waves:-`k = 2.*PI/L; f = k*dot(D, p.xz) - sqrt(9.8*k)*t;` displace xz by-`Q*A*D*cos(f)`, y by `A*sin(f)`. Keep the sum of Q*A*k below 1 (above it the-crests loop over). Grid 256x256 or denser; get normals by finite-differencing-the DISPLACED surface, not from the flat plane. Fragment side: fresnel mix to-the horizon colour (`pow(1. - dot(N, V), 5.)`).--## Waterfall and fountain--Waterfall: a curved plane whose fragment shader scrolls vertical fbm streaks,-thresholded to white over translucent blue; mist is a cluster of soft sprites-at the base. Fountain: `THREE.Points` where each particle's position is a pure-ballistic arc of `fract(seed + t * rate)` — frozen mid-flight it still reads.+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 (the library's reflectors each re-render the scene).++## Strong options from the library++`makeOceanSurface` from `lib/ocean.js` for the ocean, a lake or any sizeable body+(dispersive Gerstner waves on displaced geometry, reflected scene, crest foam);+`makeOcean` from `lib/water.js` for calm or distant water where no wave shape reads;+`makeStream` for a curved shallow stream that refracts its bed; `makeWaterfall` for a sheet+over a weir with its own spray; `makeWaterMist` / `makeSpray` from `lib/watermist.js`;+`patchShoreWet` / `patchShoreFoam` / `patchShallowWater` from `lib/waterside.js` on the+bank; `patchCaustics` on the bed and `patchUnderwater` on anything below the surface. Each+carries `userData.update(t, dt)` — call it from the zone's own update.++## 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 — `makeOceanSurface` ships them; your own keeps the+steepness sum below 1 or the crests loop over, and takes 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+(`makeWaterfall`, `makeWaterMist`); 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).+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.diff --git a/harness/codeverse3d/skills/c3d-scene-water/references/gerstner-and-foam.md b/harness/codeverse3d/skills/c3d-scene-water/references/gerstner-and-foam.mdindex c96e0d6b..ff28d14c 100644--- a/harness/codeverse3d/skills/c3d-scene-water/references/gerstner-and-foam.md+++ b/harness/codeverse3d/skills/c3d-scene-water/references/gerstner-and-foam.md@@ -1,13 +1,15 @@# Gerstner waves and shoreline foam — the deeper cut+`makeOceanSurface` in `lib/ocean.js` already does all of this; what follows is for a water+body the library's options cannot shape.+## Why Gerstner and not displaced noise-Noise-displaced water bobs; Gerstner water TRAVELS. Each wave moves vertices in-a circle — horizontally toward the crest, vertically over it — which is what-sharpens crests and flattens troughs like real deep-water waves.+Noise-displaced water bobs; Gerstner water TRAVELS. Each wave moves vertices in a circle —+horizontally toward the crest, vertically over it — which is what sharpens crests and+flattens troughs like real deep-water waves.-Per wave i, with direction D_i (unit, xz), wavelength L_i, amplitude A_i,-steepness Q_i:+Per wave i, with direction D_i (unit, xz), wavelength L_i, amplitude A_i, steepness Q_i:k = 2*PI / Lc = sqrt(9.8 / k) // deep-water phase speed, m/s@@ -15,26 +17,26 @@ steepness Q_i:xz += Q * A * D * cos(f)y += A * sin(f)-* Sum 3-4 waves: one long swell (L 18-40 m, A 0.4-0.8), two mid chops at- 30-60 degrees off the swell, one short ripple. Randomize phases.-* STABILITY: sum of Q*A*k must stay below 1.0, or crests loop into- self-intersecting curls. Budget Q per wave as Q_total / n_waves.-* Normals: finite-difference the DISPLACED positions (sample the full sum at- p+dx and p+dz). Analytic normals from one wave look wrong the moment you sum.-* Grid: 256x256 minimum for L >= 18 m; halve the wavelength, double the grid.+* Sum a few waves: one long swell, a couple of mid chops some tens of degrees off the+ swell, one short ripple; randomize phases.+* STABILITY: the sum of Q*A*k stays below 1.0, or crests loop into self-intersecting+ curls. Budget Q per wave as a share of that total.+* Normals: finite-difference the DISPLACED positions (sample the full sum at p+dx and+ p+dz). Analytic normals from one wave look wrong the moment you sum.+* Grid density follows the shortest wavelength: halve the wavelength, double the grid.## Foam, ranked by payoff-1. SHORELINE foam (best): needs the shared height function. In the fragment- shader, `shore = 1. - smoothstep(0.0, 1.2, waterLevel - h)` then multiply by- scrolling fbm and add as near-white. Hugs banks, islands, piers.-2. Contact foam around obstacles: same trick with distance to the obstacle's- footprint circle.-3. Crest foam (skip unless asked): threshold on the Jacobian of the Gerstner- displacement; expensive to get right, subtle in stills.+1. SHORELINE foam (best): needs the shared height function. In the fragment shader,+ `shore = 1. - smoothstep(0.0, 1.2, waterLevel - h)` then multiply by scrolling fbm and+ add as near-white. Hugs banks, islands, piers.+2. Contact foam around obstacles: the same trick with distance to the obstacle's+ footprint.+3. Crest foam: a threshold on the Jacobian of the Gerstner displacement; expensive to get+ right, subtle in stills.## Frozen-frame checks-At the fixed capture time the surface must show asymmetric crests (travel-direction readable), no through-floor dips at the shore (bias the plane down-0.02), and foam only where geometry explains it.+At the fixed capture time the surface shows asymmetric crests (travel direction readable),+no through-floor dips at the shore (the plane biased a little below the bank), and foam+only where geometry explains it.diff --git a/harness/codeverse3d/skills/registry.py b/harness/codeverse3d/skills/registry.pyindex e5d8c60e..b24bd060 100644--- a/harness/codeverse3d/skills/registry.py+++ b/harness/codeverse3d/skills/registry.py@@ -52,7 +52,7 @@ MOTION_WRONG_DIRECTION = "motion_direction/wrong_direction"LINT = "lint/*"LINT_PART_NOT_IMPORTED = f"lint/{LintKind.PART_NOT_IMPORTED.value}"#: the scene_placement gate's seating kinds (spatial/scene_placement.py; ``free_exempt`` and-#: ``cantilevered`` are 2026-10-14's, D105). Its PLAN kinds (no_fog, no_backdrop, scale, zone_empty, …)+#: ``cantilevered`` are 2026-10-14's, D105). Its PLAN kinds (no_fog, world_edge, scale, zone_empty, …)#: are deliberately not here: they are env / composition findings, not seating.SCENE_PLACEMENT_FLOATING = "scene_placement/floating"SCENE_PLACEMENT_SUNKEN = "scene_placement/sunken"diff --git a/harness/codeverse3d/skills/variants/argon/routes.toml b/harness/codeverse3d/skills/variants/argon/routes.tomlindex 9d18bf0d..cbce17a7 100644--- a/harness/codeverse3d/skills/variants/argon/routes.toml+++ b/harness/codeverse3d/skills/variants/argon/routes.toml@@ -19,14 +19,16 @@# why = "flat albedo is the audit's most-cited surface defect on argon zones"# Iteration 1 (2026-10-15): placement is the measured defect that capped the most iteration-0-# rounds (threejs 7/30 interpenetration + 5/30 sunken; blender 13/30 + 5/30), and the skills that-# teach it sat behind lighting / materials in the attached list. The boosts put them FIRST in-# every standing zone / env / refine session (R14 75 -> 89, R29 80 -> 89; the gate-fired rows-# R30 / R34 already route at 95).-[[boost]]-skill = "c3d-scene-composition"-delta = 14-+# rounds (threejs 7/30 interpenetration + 5/30 sunken; blender 13/30 + 5/30), and the Blender+# skill that teaches it sat behind lighting / materials in the attached list. The boost puts it+# FIRST in every standing zone / env / refine session (R29 80 -> 89; the gate-fired rows R30 / R34+# already route at 95).+#+# The matching three.js boost (c3d-scene-composition +14) was withdrawn the same day: that bundle+# carried the build order, the bounds-centre establishing formula and the ring arithmetic that all+# 60 iteration-0 scenes reproduced, and putting it first in every session amplified the template.+# It is now a sheet of measured requirements and routes at its base priority (R14 75); the+# three.js placement findings reach the agent through the gate's own fix hints (R34 at 95).[[boost]]skill = "c3d-bpy-scene-placement"delta = 9diff --git a/harness/codeverse3d/spatial/frame_metrics.py b/harness/codeverse3d/spatial/frame_metrics.pyindex 2fa9f2b4..731677f8 100644--- a/harness/codeverse3d/spatial/frame_metrics.py+++ b/harness/codeverse3d/spatial/frame_metrics.py@@ -49,14 +49,16 @@ TARGET_BLOCKED_FRAC = 0.5 # the line of sight to lookAt is cut before thisBLOCKED_RAYS_MIN = 6 # of the 3 x 3 sight rays, within near_limit_m (host BLOCKED_M)EYE_MAX_ABOVE_GROUND_M = 80.0-#: for a frame that is dark AND flat -- nothing is lit, so adding light is right+#: for a frame that is dark AND flat -- nothing is lit, so adding light is right. The hints+#: state the measurement and leave the construction open (owner's rule, 2026-10-15): a library+#: call or a number is an example, never the fix._DARK_HINT = (- "raise the light through the rig env.js already builds — `sunRig({ mood: 'day'|'golden'|'night'|'overcast', "- "intensity, fill, … })`: pick the brief's mood (a set sun, elevation < 0, is the night rig), raise `intensity` (key, "- "the rig clamps requests below its floor UP) and `fill` (the hemisphere) — do not add a second sun on top; "- "add emissive lights where the brief has them (lantern glow: the cookbook's practical-light recipe, `PRACTICAL` "- "from lib/environment.js — an emissive face plus one PointLight per lantern); scene.fog colour must match the sky "- "colour; dusk/night is orange/purple/deep blue, NOT black (check with scene_views: camera_checks.mean_lum)"+ "the frame is too dark (the gate wants mean luminance >= 0.12, or real contrast with <= 35 % near-black pixels): "+ "raise the key and the fill until the authored frames measure over the line without flattening them (scene_views: "+ "camera_checks.mean_lum) — a stronger sun / hemisphere, or emissive practicals where the brief has lamps (an emissive "+ "face plus a PointLight each; `PRACTICAL` in lib/environment.js is one); the library's `sunRig({ mood, intensity, "+ "fill })` is one way to a balanced rig, and a set sun (elevation < 0) is its night rig; a fog colour that matches "+ "the sky keeps the distance readable; dusk and night are colour, not black")#: for a frame that is dark but CONTRASTY -- something IS lit, so adding fill is the#: wrong move and actively destroys the picture. Measured 2026-08-25: temple_night was@@ -65,71 +67,87 @@ _DARK_HINT = (#: drowned a working KoiWater ShaderMaterial -- the effect was running the whole time.#: The judge then scored the washed-out version 0.7287 and passed it._LOWKEY_HINT = (- "this frame is DIM BUT LIT — it has real contrast, so do NOT add AmbientLight or HemisphereLight and do NOT "- "raise a DirectionalLight to fix it: flat fill is what turns a night scene into a grey wash, washes dark "- "materials out to near-white and drowns emissive/shader effects. Instead lift the picture where the light "- "actually comes from: raise emissiveIntensity on the lamps/lanterns themselves, add or brighten a PointLight "- "at each practical light, give dark materials a low but non-zero base colour so they read as material and not "- "as void, and let the shadowed areas stay dark. Only if the frame is ALSO flat (no contrast) does it need key/fill."+ "this frame is DIM BUT LIT — it has real contrast, so flat fill (an AmbientLight / HemisphereLight, a stronger "+ "DirectionalLight) is the wrong move: it turns a night scene into a grey wash, washes dark materials out to "+ "near-white and drowns emissive/shader effects. Lift the picture where the light actually comes from: raise "+ "emissiveIntensity on the lamps/lanterns themselves, add or brighten a PointLight at each practical light, give dark "+ "materials a low but non-zero base colour so they read as material and not as void, and let the shadowed areas "+ "stay dark. Only a frame that is ALSO flat (no contrast) needs key/fill.")_BLOWN_HINT = (- "lower exposure: DirectionalLight ≤ 3, HemisphereLight ≤ 1.0, no MeshBasicMaterial white planes; "- "sky colour below 0.9 white; emissiveIntensity ≤ 4 on large surfaces"+ "the frame is blown out (the limit is 20 % pure-white pixels): lower the exposure until it measures under — "+ "typically a key light <= 3, hemisphere <= 1, no flat-white unlit planes, sky below 0.9 white, emissive <= 4 on "+ "large surfaces")_FLAT_HINT = (- "one colour dominates the frame: aim the camera at content (lookAt the zone centre), add contrast with a shadow-casting "- "DirectionalLight, vary materials, and make sure the sky gradient / fog is not a single flat tint"+ "one luminance band dominates the frame: aim the camera at its subject (not at a wall, the sky or bare ground) and "+ "give the frame contrast — a shadow-casting key light, varied materials, a sky / fog gradient rather than one flat tint")-_NEAR_HINT = "move the camera ≥ 0.5 m away from every surface (raise it above ground/terrain, pull it out of walls and trees) and keep lookAt on the content"+_NEAR_HINT = ("move the camera >= 0.5 m away from every surface (raise it above ground/terrain, pull it out of walls and "+ "trees) and keep lookAt on its subject")_STATIC_HINT = (- "nothing moved between the animation times: give the planned motion a visible amplitude — foliage/banner sway "- "±0.10–0.20 rad, water surface ≥ 3 cm vertical or a scrolling normal/uv, particles ≥ 0.6 m of travel per 1.5 s, "- "rotating parts ≥ 20°/s — and drive it from the ONE hook the harness calls: the object returned by createScene "- "(update(t, dt)) → env.update → each zone's group.userData.update(t, dt). Everything must be a pure function of t"+ "nothing moved between the animation times (measured: under 0.4 % of an authored frame's pixels changed by more than "+ "8/255, and under 0.08 % by more than 60): the planned motion has to be visible from an authored camera at t = 0 and "+ "t = 1.5 s — for example sway of ±0.1-0.2 rad, >= 3 cm of water displacement or a scrolling normal/uv, >= 0.6 m of "+ "particle travel, >= 20°/s of rotation — and driven from the one hook the harness calls: the object createScene "+ "returns (update(t, dt)) → env.update → each zone group's userData.update(t, dt), as a pure function of t")_SMALL_HINT = (- "the shot shows mostly sky/ground: move the camera closer to the content (distance ≈ 1.2 × the content's widest span), "- "lower it toward eye level, point lookAt at the content centre, or fill the bounds with more zones/assets"+ "the frame is mostly sky / bare ground: aim this camera at what the brief says this viewpoint looks at, and make "+ "sure that subject is built and in the line of sight (a camera_target_blocked finding names what cuts it); the "+ "gate counts built geometry other than ground and water as content — check with scene_views")-_EYE_HINT = "set position[1] = heightAt(x, z) + 1.6 (eye level) — never below the terrain"-_LOW_HINT = "human shots: position[1] = heightAt(x, z) + 1.6; establishing: 6–20 m above ground looking down 15–30°"+_EYE_HINT = ("stand the camera on the surface under it: position[1] = heightAt(x, z) at its standpoint plus the height "+ "the brief gives this viewpoint (eye level ~1.6 m, a balcony, a tower) — never below the terrain")+_LOW_HINT = ("the eye has to be >= 0.3 m above the surface beneath it (measured: ground_below_m): set position[1] = "+ "heightAt(x, z) + the height the brief describes for this viewpoint — eye level (~1.6 m), a balcony, a "+ "tower — and look at the subject")+_HIGH_HINT = ("bring the camera below 80 m above the surface it stands over (measured: ground_below_m), to a height the "+ "brief's viewpoint justifies — a tower top, a ridge, a rooftop, eye level — still aimed at its subject")#: scene_blender's words for the same fixes (D1, lane B): bpy lamps / world nodes / keyframes, the#: Blender frame (z up), ``ctx.height_at``. The thresholds are the same; only the advice differs._BPY_HINTS: dict[str, str] = {"dark": (- "raise the light in build_env (src/env.py): the Sun lamp's strength (`sun.data.energy` 3–5 for day, 1–2 at golden "- "hour; a sun below the horizon is the night rig) and the world Background / Sky Texture Strength (the fill) — do not "- "add a second sun; add practical lights where the brief has them (a Point lamp of 20–200 W at each lantern plus an "- "Emission shader on the lamp mesh); keep a world Volume thin (density ≤ 0.02) or it swallows the light; dusk/night is "- "orange/purple/deep blue, NOT black (check with scene_views: camera_checks.mean_lum)"),+ "the frame is too dark (the gate wants mean luminance >= 0.12, or real contrast with <= 35 % near-black pixels): "+ "raise the light in build_env (src/env.py) until the authored frames measure over the line without flattening them "+ "(scene_views: camera_checks.mean_lum) — the Sun lamp's strength (`sun.data.energy`, typically 3-5 by day, 1-2 at "+ "golden hour; a sun below the horizon is a night rig) and the world Background / Sky Texture strength (the fill), "+ "practical lights where the brief has lamps (a Point lamp of 20-200 W plus an Emission shader on the lamp mesh); "+ "a world Volume thicker than ~0.02 swallows the light; dusk and night are colour, not black"),"lowkey": (- "this frame is DIM BUT LIT — it has real contrast, so do NOT raise the world Background strength or add a big "- "area/sun lamp to fix it: flat fill turns a night scene into a grey wash, washes dark materials out and drowns "- "emissive effects. Lift the picture where the light actually comes from: raise the Emission Strength of the "- "lamps/lanterns, add or brighten a Point lamp at each practical light, give dark materials a low but non-zero Base "- "Color so they read as material and not as void, and let the shadowed areas stay dark. Only if the frame is ALSO "- "flat (no contrast) does it need key/fill."),+ "this frame is DIM BUT LIT — it has real contrast, so flat fill (a stronger world Background, a big area / sun "+ "lamp) is the wrong move: it turns a night scene into a grey wash, washes dark materials out and drowns emissive "+ "effects. Lift the picture where the light actually comes from: raise the Emission Strength of the lamps/lanterns, "+ "add or brighten a Point lamp at each practical light, give dark materials a low but non-zero Base Color so they "+ "read as material and not as void, and let the shadowed areas stay dark. Only a frame that is ALSO flat (no "+ "contrast) needs key/fill."),"blown": (- "lower exposure: Sun lamp strength ≤ 5, world Background / Sky Texture strength ≤ 1.5, no white Emission planes, "- "Emission Strength ≤ 5 on large surfaces — the harness renders AgX at exposure 0 and owns the view settings"),+ "the frame is blown out (the limit is 20 % pure-white pixels): lower the exposure until it measures under — "+ "typically a Sun lamp strength <= 5, world Background / Sky Texture strength <= 1.5, no white Emission planes, "+ "Emission Strength <= 5 on large surfaces; the harness renders AgX at exposure 0 and owns the view settings"),"flat": (- "one colour dominates the frame: aim the camera at content (look_at the zone centre), add contrast with a Sun lamp "- "that casts shadows, vary materials, and make sure the world (Sky Texture / Background) and any Volume are not one "- "flat tint"),- "near": ("move the camera ≥ 0.5 m away from every surface (raise it above ground/terrain: z = ctx.height_at(x, y) + 1.6, "- "pull it out of walls and trees) and keep look_at on the content"),+ "one luminance band dominates the frame: aim the camera at its subject (not at a wall, the sky or bare ground) and "+ "give the frame contrast — a Sun lamp that casts shadows, varied materials, a world (Sky Texture / Background) and "+ "Volume that are not one flat tint"),+ "near": ("move the camera >= 0.5 m away from every surface (raise it above ground/terrain: z = ctx.height_at(x, y) + its "+ "height, pull it out of walls and trees) and keep look_at on its subject"),"static": (- "nothing moved between the animation times: give the planned motion a visible amplitude — foliage/banner sway "- "±0.10–0.20 rad, water surface ≥ 3 cm vertical, particles ≥ 0.6 m of travel per 1.5 s, rotating parts ≥ 20°/s — "- "as DATA the .blend plays by itself: keyframes (object location/rotation, node inputs, shape keys), a "- "simple-expression driver on `frame` (e.g. `sin(frame*0.2)*0.15`; python-function drivers never run here) or the "+ "nothing moved between the animation times (measured: under 0.4 % of an authored frame's pixels changed by more "+ "than 8/255, and under 0.08 % by more than 60): the planned motion has to be visible from an authored camera at "+ "t = 0 and t = 1.5 s — for example sway of ±0.1-0.2 rad, >= 3 cm of water displacement, >= 0.6 m of particle "+ "travel, >= 20°/s of rotation — as DATA the .blend plays by itself: keyframes (object location/rotation, node "+ "inputs, shape keys), a simple-expression driver on `frame` (python-function drivers never run here) or the ""geometry-nodes Scene Time node. The harness renders t = 0 s and t = 1.5 s as frames 1 and 46 (30 fps)"),"small": _SMALL_HINT.replace("lookAt", "look_at"),- "eye": "set the camera's z = ctx.height_at(x, y) + 1.6 (eye level) — never below the terrain",- "low": "human shots: z = ctx.height_at(x, y) + 1.6; establishing: 6–20 m above ground looking down 15–30°",+ "eye": ("stand the camera on the surface under it: z = ctx.height_at(x, y) at its standpoint plus the height the brief "+ "gives this viewpoint (eye level ~1.6 m, a balcony, a tower) — never below the terrain"),+ "low": ("the eye has to be >= 0.3 m above the surface beneath it (measured: ground_below_m): set z = ctx.height_at(x, y) "+ "+ the height the brief describes for this viewpoint — eye level (~1.6 m), a balcony, a tower — and look at "+ "the subject"),+ "high": _HIGH_HINT,"unused_glb": ("the hero GLB is imported into ctx.assets['<key>'] and nothing places it — add a collection-instance Empty of ""ctx.assets['<key>'] inside the zone the plan puts it in. If a refine round replaced the hero with a procedural "@@ -140,7 +158,8 @@ _BPY_HINTS: dict[str, str] = {#: every recorded round is)HINTS: dict[str, dict[str, str]] = {"scene_threejs": {"dark": _DARK_HINT, "lowkey": _LOWKEY_HINT, "blown": _BLOWN_HINT, "flat": _FLAT_HINT,- "near": _NEAR_HINT, "static": _STATIC_HINT, "small": _SMALL_HINT, "eye": _EYE_HINT, "low": _LOW_HINT},+ "near": _NEAR_HINT, "static": _STATIC_HINT, "small": _SMALL_HINT, "eye": _EYE_HINT, "low": _LOW_HINT,+ "high": _HIGH_HINT},"scene_blender": _BPY_HINTS,}@@ -269,7 +288,7 @@ def _geometry_findings(chk: dict[str, Any], *, authored: bool, ground_y: float |kind="camera_low", view=name, eye_height_m=eye, ground_below_m=below))elif below > EYE_MAX_ABOVE_GROUND_M:out.append(_f(Severity.WARN, name, f"camera {below:.0f} m above {under} — satellite view, not a shot",- "bring the camera down: establishing 6–20 m above ground at ~1.2 × the content span",+ hints["high"],kind="camera_high", view=name, eye_height_m=eye, ground_below_m=below))elif authored and eye is not None and ground_y is not None:# Nothing beneath the lens (under the terrain, off the ground's edge) or an older@@ -277,7 +296,7 @@ def _geometry_findings(chk: dict[str, Any], *, authored: bool, ground_y: float |above = eye - ground_yif above < -0.2:# ``ground_y`` is the TOP of every ground-classified mesh in the scene (census),- # so a hill, a terrace or a raised backdrop ring puts it metres above a camera+ # so a hill, a terrace or a raised backdrop puts it metres above a camera# that is standing in the open. Only call the camera buried when the frame# agrees: a buried camera renders dark, empty or from inside geometry.buried = _frame_looks_buried(chk)@@ -294,7 +313,7 @@ def _geometry_findings(chk: dict[str, Any], *, authored: bool, ground_y: float |kind="camera_low", view=name, eye_height_m=eye, ground_y=ground_y))elif above > EYE_MAX_ABOVE_GROUND_M:out.append(_f(Severity.WARN, name, f"camera {above:.0f} m above ground — satellite view, not a shot",- "bring the camera down: establishing 6–20 m above ground at ~1.2 × the content span",+ hints["high"],kind="camera_high", view=name, eye_height_m=eye, ground_y=ground_y))return out@@ -320,15 +339,17 @@ def _coverage_finding(chk: dict[str, Any], *, role: str, hints: dict[str, str])sky, ground = _num(chk, "sky_frac"), _num(chk, "ground_frac")detail = f"content {content:.0%} of the frame (sky {sky or 0:.0%}, ground {ground or 0:.0%})"if role == "establishing" and content < CONTENT_MIN_ESTABLISHING:- return _f(Severity.ERROR, name, f"establishing shot shows too little content: {detail}", hints["small"],+ return _f(Severity.ERROR, name, f"establishing shot (the first authored camera) shows too little content: {detail}",+ hints["small"],kind="content_small", view=name, content_frac=content, sky_frac=sky, ground_frac=ground, role=role)if role == "authored" and content < CONTENT_MIN_AUTHORED:return _f(Severity.WARN, name, f"shot shows little content: {detail}", hints["small"],kind="content_small", view=name, content_frac=content, sky_frac=sky, ground_frac=ground, role=role)if role == "overview" and content < CONTENT_MIN_OVERVIEW:return _f(Severity.WARN, name, f"overview rig sees sparse content: {detail}",- "the plan bounds are mostly empty ground: add the planned zones/assets, or densify (instanced scatter, props) "- "so the content fills the bounds", kind="content_small", view=name, content_frac=content, role=role)+ "the overview rig sees little built geometry inside the plan bounds: check that the planned zones and "+ "assets exist where the plan puts them (zone_empty / missing_content name what is absent), or that the "+ "bounds describe the area actually built", kind="content_small", view=name, content_frac=content, role=role)return None@@ -462,8 +483,8 @@ def _hero_findings(checks: list[dict[str, Any]], census: dict[str, Any]) -> listif url in named.get(cam, ()) and v < HERO_DETAIL_MIN_FRAC:out.append(_f(Severity.WARN, cam,f"{cam} is named for {base} but shows it at {v:.1%} of the frame (its best view is {best:.1%})",- "a detail shot fills 10-40% of the frame with its subject: move the camera closer along "- "the sightline or clear what stands between",+ "the camera named for a hero shows it plainly (the floor is 2 % of the frame): move closer "+ "along the sightline or clear what stands between, until the hero is the subject of that shot",kind="hero_small_in_its_camera", url=url, frac=v, best_frac=best))return outdiff --git a/harness/codeverse3d/spatial/scene_placement.py b/harness/codeverse3d/spatial/scene_placement.pyindex 339482e2..05c5c896 100644--- a/harness/codeverse3d/spatial/scene_placement.py+++ b/harness/codeverse3d/spatial/scene_placement.py@@ -224,12 +224,9 @@ LANGUAGE_WORDS: dict[str, dict[str, str]] = {"no_fog": "in buildEnv set scene.fog = new THREE.Fog(<sky horizon hex>, near, far) with the plan's numbers","no_background_msg": "scene.background is not set (renders on the raw clear colour)","no_background": "in buildEnv set scene.background to the sky colour or sky texture the plan names",- "fog_far": ("fog far >= {need:.0f} m ({spans:g} x the plan span; the starter's shell fog is scaled to it: keep "- "`scene.fog = shell.fog`, or lengthen yours) and let the horizon ridge / outskirts close the world"),- "underdressed": ("the layout's dressing counts are binding: add the missing props and the instanced ground cover "- "(tufts/pebbles count via InstancedMesh.count)"),- "ring": ("vary them — at least 3 silhouettes, scale 0.6-1.6x, radius +-25 %, random yaw, clusters rather than a "- "ring — or drop the ring and let the starter's worldShell ridge and makeOutskirts hills close the horizon"),+ "fog_far": ("fog far must reach >= {need:.0f} m ({spans:g} x the plan span; measured from scene.fog) so whatever "+ "lies past the bounds fades with distance instead of cutting off — the terrain, buildings, trees or "+ "water out there then read as aerial perspective"),"place": "import its builder / clone its GLB","free_exempt": ("userData.placement = 'free' is for hanging / airborne things only (a bird, a hung lantern, a drone): ""delete the tag on everything that stands on something and seat it with heightAt(x, z) or on its support"),@@ -243,12 +240,9 @@ LANGUAGE_WORDS: dict[str, dict[str, str]] = {"0.002-0.02, tinted like the sky horizon) or place a bounded fog volume over the play area"),"no_background_msg": "the world has no sky: no Sky Texture or Background colour on the world output","no_background": "in build_env give scene.world a Sky Texture (or the plan's sky colour on its Background node)",- "fog_far": ("thin the fog so 1/density >= {need:.0f} m ({spans:g} x the plan span) and let the horizon ridge / "- "outskirts close the world"),- "underdressed": ("the layout's dressing counts are binding: add the missing props and the instanced ground cover "- "(every collection instance / geometry-nodes instance counts)"),- "ring": ("vary them — at least 3 silhouettes, scale 0.6-1.6x, radius +-25 %, random yaw, clusters rather than a "- "ring — or drop the ring and close the horizon with terrain ridges and hills"),+ "fog_far": ("thin the fog so 1/density >= {need:.0f} m ({spans:g} x the plan span; measured from the world volume) "+ "so whatever lies past the bounds fades with distance instead of cutting off — the terrain, buildings, "+ "trees or water out there then read as aerial perspective"),"place": "place a collection-instance Empty of ctx.assets['<snake>']","free_exempt": ('obj["placement"] = "free" is for hanging / airborne things only (a bird, a hung lantern, a drone): '"delete the tag on everything that stands on something and seat it with ctx.height_at(x, y) / lib.place.seat"),@@ -472,20 +466,20 @@ SCALE_WARN, SCALE_ERROR = 2.5, 4.0#: linear fog must reach past the plan's far side (fog far >= this many plan spans); exp fog#: must not dissolve it (1/density >= span / this)FOG_FAR_MIN_SPANS, FOG_DENSITY_MAX_PER_SPAN = 2.0, 1.5-BOUNDS_MARGIN_MIN_M = 2.0-#: a zone whose census instance count is under this fraction of its L2 layout budget is-#: underdressed. Measured on scene_final_v1 (n=19): flat_ground 12 / undressed 11 /-#: monotonous 10 were the top standing defects while every zone had a layout with binding-#: mid/small/ground-cover counts nobody enforced. Half is deliberately generous — the-#: budget mixes props with instanced tufts, and only a gross shortfall should gate.-DENSITY_FRACTION = 0.5-DENSITY_MIN_BUDGET = 20-#: an outdoor scene with no geometry reaching past this multiple of the bounds-#: half-extent has no backdrop ring — the world edge shows from every overview camera.-#: world_edge_visible stood in 11/19 scene_final_v1 verdicts and 3/6 of the density-#: arm while the plan's env contract demands a silhouette ring at ~0.6 x fog-far-#: (well beyond bounds); 1.25x the half-extent is a deliberately lenient floor.-BACKDROP_REACH_FACTOR = 1.25+#: the tolerance on a PLANNED asset's position against the plan bounds: ``max(this, 10 % of the+#: span)``. Generous on purpose (owner, 2026-10-15): the bounds are where the plan's named+#: contents are measured, not a wall the place stops at — scenery past them is the world+#: continuing, which ``world_edge`` below asks for.+BOUNDS_MARGIN_MIN_M = 5.0+BOUNDS_MARGIN_FRAC = 0.10+#: the world continues past the bounds: outdoors, something standing (``WORLD_EDGE_MIN_HEIGHT_M``+#: or taller — terrain, buildings, trees, walls, cliffs, whatever the place has) reaches past this+#: multiple of the bounds half-extent, or the edge of the built world is in view from every camera+#: that looks outward (world_edge_visible stood in 11/19 scene_final_v1 verdicts). 1.25x the+#: half-extent is a deliberately lenient floor; WHAT continues the place is the brief's choice,+#: and the fog gate covers the far distance.+WORLD_EDGE_REACH_FACTOR = 1.25+WORLD_EDGE_MIN_HEIGHT_M = 2.0#: stamped ring (host_census `stamps`): copies, where the ring sits relative to the plan's#: half-extent, and how even / alike it must be before it is called stampedRING_MIN_COPIES = 8@@ -493,7 +487,14 @@ RING_BACKDROP_FRAC = 0.6RING_RADIUS_CV_MAX = 0.08RING_GAP_CV_MAX = 0.25RING_SIZE_CV_MAX = 0.25 # loop 24's ski station: 32 peaks, radius spread 0.8 %, SIZE spread 15 % — still "identical pyramids stamped in a ring" to the judge-BACKDROP_MIN_HEIGHT_M = 2.0+#: the two hints that name no language API — the same words for both scene languages+RING_HINT = ("break the pattern — uneven spacing, mixed sizes and silhouettes, clusters and gaps — or close the distance "+ "some other way the place suggests (a ridge line, a treeline, buildings, open water); the check calls a ring "+ "when >= {min_n} copies have radius spread <= {rcv:.0%}, spacing spread <= {gcv:.0%} and size spread <= {scv:.0%}")+WORLD_EDGE_HINT = ("continue the place past the bounds in whatever form the brief implies — more of the same terrain, the "+ "rest of the street, a treeline, water to the horizon, a wall — with something >= {min_h:.0f} m tall "+ "reaching past ~{need:.0f} m from the bounds centre, and the fog closing the distance (fog_short measures "+ "its reach); vary any repeated element out there (stamped_ring measures radius / spacing / size spread)")def _plan_zones(plan: Any) -> list[tuple[str, list[str]]]:@@ -564,9 +565,10 @@ def _row_names(row: AssetRow) -> str:def contract_findings(census: dict[str, Any] | None, plan: Any,layouts: dict[str, Any] | None = None, unavailable: Sequence[str] = ()) -> list[GateFinding]:- """Deterministic plan-vs-census checks: env atmosphere present, every zone dressed- with its planned contents, plausible scale, content inside the world bounds — and,- when the zone has an L2 layout, its density budget actually met.+ """Deterministic plan-vs-census checks: env atmosphere present, the world continuing+ past the bounds, every zone dressed with its planned contents, plausible scale, planned+ contents inside the world bounds — and, when a zone has an L2 layout, an INFO line with+ its census count against that layout's own budget.``unavailable`` = assets the asset stage could not build (the zones were told"NOT AVAILABLE — do not reference"): a zone is not missing what it was told not to@@ -577,23 +579,25 @@ def contract_findings(census: dict[str, Any] | None, plan: Any,return []words = placement_words(census.get("language"))out: list[GateFinding] = []- # -- density: the layout's counts are binding, and the census counts every instance+ # -- density, as a NOTE: the census count against the L2 layout's own budget. Until+ # 2026-10-15 a zone under half its budget was an ERROR ("underdressed"), which made the+ # layout's prop / ground-cover bands a requirement the brief never stated (owner's rule:+ # the harness states requirements, not templates). The counts a brief DOES state are+ # its acceptance items, verified by name by the judge; this line only informs.groups = {to_snake(g.get("name", "")): g for g in (census.get("groups") or [])if isinstance(g, dict)}for zone_name, layout in (layouts or {}).items():budget = _layout_budget(layout)- if budget < DENSITY_MIN_BUDGET:- continueg = groups.get(to_snake(zone_name))- if g is None:+ if g is None or budget <= 0:continue # zone_empty below covers a missing grouphave = int(g.get("instances") or 0)- if have < DENSITY_FRACTION * budget:- out.append(_f(Severity.ERROR,- f"zone {zone_name} holds ~{have} instances but its layout budgeted {budget} "- f"(placements + mid/small props + ground cover)",- target=zone_name, kind="underdressed", have=have, budget=budget,- hint=words["underdressed"]))+ if have < budget:+ out.append(_f(Severity.INFO,+ f"zone {zone_name} holds ~{have} instances; its layout planned {budget} "+ f"(placements + props + ground cover) — a note, not a requirement: the counts the brief "+ "states are its acceptance items",+ target=zone_name, kind="density_note", have=have, budget=budget))# -- atmosphere: the two env facts the census measures on every bootif "fog" in census and census.get("fog") is None:out.append(_f(Severity.ERROR, words["no_fog_msg"], target="env", kind="no_fog", hint=words["no_fog"]))@@ -642,32 +646,36 @@ def contract_findings(census: dict[str, Any] | None, plan: Any,f"(radius spread {rcv:.0%}, spacing spread {gcv:.0%}, size spread {scv:.0%}) — a toy backdrop",target=str(g.get("name", "overall")), kind="stamped_ring", n=n, radius_m=r,radius_cv=rcv, gap_cv=gcv, size_cv=scv,- hint=words["ring"]))- # -- backdrop ring: outdoor worlds must have geometry past the play area+ hint=RING_HINT.format(min_n=RING_MIN_COPIES, rcv=RING_RADIUS_CV_MAX, gcv=RING_GAP_CV_MAX,+ scv=RING_SIZE_CV_MAX)))+ # -- the world continues past the bounds (outdoors): a WARN-level note when nothing standing+ # reaches past WORLD_EDGE_REACH_FACTOR x the half-extent. Until 2026-10-15 this was the+ # "no_backdrop" ERROR whose hint prescribed a silhouette ring of 24-40 pieces — the one+ # construction 57 of 59 iteration-0 plans then built. The measurement is unchanged; what+ # continues the place is the brief's.groups = census.get("groups")if bounds and isinstance(groups, list) and not is_interior(plan):lo, hi = boundscx, cz = (lo[0] + hi[0]) / 2, (lo[2] + hi[2]) / 2half = max(hi[0] - lo[0], hi[2] - lo[2]) / 2- need = BACKDROP_REACH_FACTOR * half+ need = WORLD_EDGE_REACH_FACTOR * halfreach = 0.0for g in groups:b = g.get("bbox") if isinstance(g, dict) else Nonebmin, bmax = (_nums(b.get("min")), _nums(b.get("max"))) if isinstance(b, dict) else (None, None)if bmin is None or bmax is None or g.get("kind") not in ("content", "ground"):continue- if (bmax[1] - bmin[1]) < BACKDROP_MIN_HEIGHT_M:+ if (bmax[1] - bmin[1]) < WORLD_EDGE_MIN_HEIGHT_M:continuer = max(abs(bmin[0] - cx), abs(bmax[0] - cx), abs(bmin[2] - cz), abs(bmax[2] - cz))reach = max(reach, r)if 0 < reach < need:- out.append(_f(Severity.ERROR,- f"no backdrop ring: the farthest standing geometry reaches {reach:.0f} m from centre "- f"but the world edge hides only past ~{need:.0f} m",- target="env", kind="no_backdrop", reach_m=round(reach, 1), need_m=round(need, 1),- hint="build the env plan's silhouette ring (24-40 SOLID pieces — hills / treeline / "- "rooftops — at ~0.6 x fog-far radius, 3-8 m tall, darkened): the fog supplies the "- "haze, the ring hides the edge"))+ out.append(_f(Severity.WARN,+ f"the world ends at its bounds: the farthest standing geometry (>= {WORLD_EDGE_MIN_HEIGHT_M:.0f} m "+ f"tall) reaches {reach:.0f} m from the bounds centre and nothing stands past ~{need:.0f} m — "+ "the edge of the built world is in view from every camera that looks outward",+ target="env", kind="world_edge", reach_m=round(reach, 1), need_m=round(need, 1),+ hint=WORLD_EDGE_HINT.format(min_h=WORLD_EDGE_MIN_HEIGHT_M, need=need)))table = census.get("placement") if isinstance(census.get("placement"), dict) else Nonerows = [AssetRow.model_validate(r) for r in (table.get("assets") or [])] if table else []if not rows:@@ -725,22 +733,34 @@ def contract_findings(census: dict[str, Any] | None, plan: Any,out.append(_f(sev, f"{what} measures {measured:.2f} m but the plan sized {key} at ~{sizes[key]:.2f} m ({f:.1f}x)",target=r.qualified, kind="scale", factor=round(f, 2), zone=r.zone, instances=n, bbox=r.bbox_data(),hint=f"scale {'each ' + key if n else r.name} so its largest dimension is ~{sizes[key]:.2f} m as planned"))- # -- content inside the world bounds+ # -- PLANNED contents inside the world bounds: a row carrying a planned asset's name (matched+ # the way missing_content matches it) is measured against the bounds + a generous margin,+ # as a WARN. Anything else past the bounds — the rest of the street, outlying trees, the far+ # shore — is the place continuing, which the world_edge check asks for, and is not reported.+ # Until 2026-10-15 every placed row outside bounds + max(2 m, 5 %) was an ERROR: with the+ # world-edge check that left a ring round the centre as the only legal way to continue.bounds = _plan_bounds(plan)if bounds:lo, hi = bounds- margin = max(BOUNDS_MARGIN_MIN_M, 0.05 * max(hi[0] - lo[0], hi[2] - lo[2]))+ margin = max(BOUNDS_MARGIN_MIN_M, BOUNDS_MARGIN_FRAC * max(hi[0] - lo[0], hi[2] - lo[2]))+ planned = {to_snake(c) for _, contents in _plan_zones(plan) for c in contents}for r in rows:bmin, bmax = _nums((r.bbox or {}).get("min")), _nums((r.bbox or {}).get("max"))if r.exempt or bmin is None or bmax is None:continue+ names = _row_names(r)+ key = next((c for c in sorted(planned) if c in names), "")+ if not key:+ continuefully_out = (bmin[0] > hi[0] + margin or bmax[0] < lo[0] - marginor bmin[2] > hi[2] + margin or bmax[2] < lo[2] - margin)if fully_out:- out.append(_f(Severity.ERROR, f"{r.qualified} sits entirely outside the plan bounds "- f"(x {bmin[0]:.0f}..{bmax[0]:.0f}, z {bmin[2]:.0f}..{bmax[2]:.0f})",- target=r.qualified, kind="out_of_bounds", zone=r.zone, bbox=r.bbox_data(),- hint="move it inside the plan bounds or into its zone bbox"))+ out.append(_f(Severity.WARN, f"{r.qualified} (planned content '{key}') sits entirely outside the plan "+ f"bounds + {margin:.0f} m (x {bmin[0]:.0f}..{bmax[0]:.0f}, z {bmin[2]:.0f}..{bmax[2]:.0f})",+ target=r.qualified, kind="out_of_bounds", zone=r.zone, bbox=r.bbox_data(), planned=key,+ margin_m=round(margin, 1),+ hint="a planned asset is measured where the plan puts it (inside its zone bbox / the plan "+ "bounds); scenery that continues the place past the bounds is free and is not this"))return out@@ -774,8 +794,8 @@ def placement_gate(ws: Workspace, census: dict[str, Any] | None, plan: Any) -> G``check_placement`` tool both return it, on the same inputs — the census, the plan andwhat the run's stages recorded in the workspace (the L2 zone layouts, the assets theasset stage could not build). Until 2026-09-22 the tool reported- :func:`placement_findings` alone, so it never showed the plan checks (fog, backdrop,- zone contents, scale, bounds, density) the round then failed on."""+ :func:`placement_findings` alone, so it never showed the plan checks (fog, world edge,+ zone contents, scale, bounds) the round then failed on."""assets = _stage_result(ws, "assets")unavailable = [name for name, r in assets.items() if isinstance(r, dict) and not r.get("ok", True)]return placement_gate_safe(census, plan=plan, layouts=_stage_result(ws, "layouts"), unavailable=unavailable)diff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.pyindex af6b7f52..5b6be784 100644--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@ -511,7 +511,8 @@ class BaseTrack:ctx.cookbook_text = language_text(spec.language, "cookbook.md")ctx.tool_cards = self.services.tool_cards(self.track.value, spec.language.value)for name, text in (("contract", ctx.contract_text), ("cookbook", ctx.cookbook_text)):- ctx.record_prompt(name, text)+ if text: # a language without a cookbook (the scene languages) records no hash for one+ ctx.record_prompt(name, text)return ctxdef _resolve_candidates(self, spec: Spec, settings: Settings) -> int:diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.pyindex a34c1250..0a8cc080 100644--- a/harness/codeverse3d/tracks/planner.py+++ b/harness/codeverse3d/tracks/planner.py@@ -47,7 +47,7 @@ from codeverse3d.models import get_chat_modelfrom codeverse3d.models.schema_utils import ask_structured, parse_json_lenientfrom codeverse3d.proc import NULL_EVENTS, sha256_file, write_text_atomicfrom codeverse3d.prompts import load_text, prompt_hash, render-from codeverse3d.prompts.catalog import language_text+from codeverse3d.prompts.catalog import contract_sections, language_textfrom codeverse3d.tracks.prompting import constraints_textfrom codeverse3d.workspace import Workspace@@ -498,14 +498,27 @@ def plan_example(track: Track, language: Language | None = None) -> dict[str, An],}if track is Track.SCENE:+ # ONE place's plan, shaped like that place (an L of quay on the west, open water east and+ # running OUT of the bounds, the mole and the village street running out too, open quay-head+ # ground the zones do not cover) — never a layout to copy. Its bounds centre, Quay bbox and+ # Overview position are pinned by tests/scene_blender/test_prompts.return {- "title": "Harbour at dusk", "summary": "Small fishing harbour: quay, two boats, lighthouse, calm water.",+ "title": "Harbour at dusk", "summary": "Small fishing harbour: an L of granite quay on the west side, two boats "+ "moored against it, the basin opening east to the sea; the mole runs out of the bounds to the north-east.","setting": "Breton coast, 1960s, clear dusk", "mood": "calm, warm low sun",- "bounds": {"center": [0, 5, 0], "extents": [120, 30, 120]},- "environment": "Sky gradient orange→indigo, sun at azimuth 250° elevation 8°, light fog density 0.004, flat sea plane y=0, stone quay at y=1.2.",+ "bounds": {"center": [0, 5, 0], "extents": [100, 30, 70]},+ "environment": "Sky zenith 0x2b3f6e to horizon 0xf0a060, sun azimuth 250° elevation 8°; fog 0xe8a070 near 60 m far "+ "320 m; sea plane y=0 colour 0x2f4a55 to the east horizon; the quay deck is flat at y=1.2 along x -40..0 and "+ "the village street climbs 3 m out of the bounds to the west; the mole continues 60 m past the bounds to the "+ "north-east with the lighthouse at its end; low headland 300 m off to the south.","zones": [- {"name": "Quay", "description": "L-shaped granite quay with bollards and crates", "bbox": {"center": [-20, 1.2, 0], "extents": [40, 3, 60]}, "contents": ["Bollard", "Crate"]},- {"name": "Water", "description": "calm harbour basin with two moored boats", "bbox": {"center": [20, 0, 0], "extents": [60, 1, 80]}, "contents": ["FishingBoat"]},+ {"name": "Quay", "description": "L-shaped granite quay deck at y=1.2 along the west and north edges; bollards every "+ "6 m on the edge, crates stacked by the net shed; seen by Overview and QuayEye",+ "bbox": {"center": [-20, 1.2, 0], "extents": [40, 3, 60]}, "contents": ["Bollard", "Crate"]},+ {"name": "Water", "description": "the basin: two boats moored bow-in against the quay edge 12 m apart, open water "+ "east of them past the bounds to the sea (the zone runs out of the bounds on the east; the quay head "+ "north of z=-30 is open ground no zone covers)", "bbox": {"center": [30, 0, 5], "extents": [60, 1, 60]},+ "contents": ["FishingBoat"]},],"assets": [{"name": "FishingBoat", "kind": "threejs", "description": "8 m wooden boat, wheelhouse aft, red hull", "approx_size_m": [8, 3.5, 3], "instances_hint": 2},@@ -514,8 +527,11 @@ def plan_example(track: Track, language: Language | None = None) -> dict[str, An],"effects": [{"name": "WaterRipple", "kind": "glsl_material", "description": "animated normal ripples on the sea plane", "target": "Water"}],"animation": ["boats bob ±0.05 m at 0.3 Hz", "water ripples scroll"],- "cameras": [{"name": "Overview", "position": [45, 18, 55], "look_at": [0, 1, 0], "fov": 50, "purpose": "establishing shot"},- {"name": "QuayEye", "position": [-5, 2.8, 25], "look_at": [15, 1, -10], "fov": 60, "purpose": "eye level along the quay"}],+ "cameras": [{"name": "Overview", "position": [38, 4, -30], "look_at": [-12, 1.5, 6], "fov": 48,+ "purpose": "establishing: low over the basin from the mole to the north-east, looking back along the quay "+ "at the two moored boats; the village street climbs out of frame behind them, open water right"},+ {"name": "QuayEye", "position": [-5, 2.8, 25], "look_at": [8, 1, -8], "fov": 60,+ "purpose": "eye level on the quay deck, looking along the edge at the nearer boat"}],"acceptance": [{"id": "a1", "text": "Two boats float on the water inside the basin", "how": "visual", "priority": "must"},{"id": "a2", "text": "Quay top at y≈1.2 m, boats' waterline at y≈0", "how": "probe", "priority": "must"}],}@@ -958,6 +974,24 @@ def _echo(raw: Any, text: str) -> ChatMessage:# ----------------------------------------------------------------------------- prompts+#: the ``## `` headings of a scene contract the PLANNER acts on: it writes JSON, so it reads the+#: files the builders will own and what is measured on them — not the assembler wiring, the shader+#: loading or the worked modules (the copyability review of 2026-10-15: +38 % on the planner brief)+PLANNER_CONTRACT_SECTIONS: dict[Language, tuple[str, ...]] = {+ Language.SCENE_THREEJS: ("Files", "createScene return value", "What is measured", "Naming"),+ Language.SCENE_BLENDER: ("Files", "Frame and units", "What the renderer does", "Motion", "Naming", "Placement",+ "What else the gates measure", "Interiors"),+}+++def planner_contract(lang: Language) -> str:+ """The contract text a planner of ``lang`` reads: the scene languages' measured sections only,+ every other language's contract whole."""+ text = language_text(lang, "contract.md")+ headings = PLANNER_CONTRACT_SECTIONS.get(lang)+ return contract_sections(text, headings) if headings else text++def build_system_prompt(spec: Spec, plan_model: type[BaseModel], *, budget: PlanBudget | None = None) -> str:lang: Language = spec.languagebudget = budget or plan_budget(spec)@@ -966,7 +1000,7 @@ def build_system_prompt(spec: Spec, plan_model: type[BaseModel], *, budget: Plantrack=spec.track.value,language=lang.value,frame_doc=frame_doc(LANGUAGE_FRAME[lang.value]),- contract=language_text(lang, "contract.md"),+ contract=planner_contract(lang),example_json=json.dumps(plan_example(spec.track, lang), indent=1),schema_fields=", ".join(plan_model.model_json_schema().get("properties", {}).keys()),target_parts=budget.target_parts,@@ -1010,8 +1044,8 @@ def ensure_acceptance[P: BaseModel](plan_obj: P, spec: Spec) -> P:A *must* item that the judge cannot verify caps the score (``missing_must_acceptance``)AND fails the run outright, so only the items the harness can hold the builder to maycarry that priority. On the SCENE track the planner writes its own checklist before- the scene exists ("the parapet is 1.05 m high", "the establishing camera frames 70 % of- the gorge") and there is no measurement pass to settle them — a flash planner's private+ the scene exists ("the parapet is 1.05 m high", "the gorge reads 200 m+ deep") and there is no measurement pass to settle them — a flash planner's privatewishes were capping finished scenes at 0.60. The spec's ``must_have`` list is thecontract with the user, so on that track the plan's own items stay on the checklist as``should`` (the judge still answers them, the refine loop still reads them) and only thediff --git a/harness/codeverse3d/tracks/prompting.py b/harness/codeverse3d/tracks/prompting.pyindex dcc1abdd..ce13c55d 100644--- a/harness/codeverse3d/tracks/prompting.py+++ b/harness/codeverse3d/tracks/prompting.py@@ -24,7 +24,7 @@ from codeverse3d.contracts.plan import Plan, StaticPlanfrom codeverse3d.contracts.run import RoundRecordfrom codeverse3d.conventions import LANGUAGE_FRAME, fmt3, frame_doc, to_authoring_frame, to_snakefrom codeverse3d.prompts import render-from codeverse3d.prompts.catalog import language_prompt, language_text+from codeverse3d.prompts.catalog import contract_sections, language_prompt, language_textfrom codeverse3d.tracks.common import RunContextfrom codeverse3d.tracks.depth import (DETAIL_ADVICE,@@ -133,37 +133,6 @@ def constraints_text(spec: Any) -> str:return "\n".join(lines) or "(none)"-def cookbook_sections(ctx: RunContext, names: Sequence[str], *, max_chars: int = 24_000) -> str:- """The named cookbook chapters, inlined verbatim, for a prompt to carry.-- Measured on the scenes_v1 battery: every zone and env session was told to call- ``read_cookbook(section=...)`` for its chapters and NOT ONE of the 20 sessions did —- flash writes the file immediately. A chapter the model never reads teaches nothing,- so the chapters that decide the score (ground, horizon, vegetation, rocks, dressing,- layering, motion) travel inside the prompt instead; the tool stays for everything else.- """- from codeverse3d.prompts.sections import find_section, split_sections-- md = ctx.cookbook_text or ""- if not md.strip():- return ""- sections = split_sections(md)- out: list[str] = []- seen: set[str] = set()- for name in names:- sec = find_section(sections, name)- if sec is None or sec.title in seen:- continue- seen.add(sec.title)- out.append(sec.body.rstrip())- text = "\n\n".join(out)- if len(text) > max_chars:- text = (- text[:max_chars].rstrip() + "\n\n…[clipped — the whole cookbook is at .3dcode/cookbook.md]"- )- return text--#: brief words → cookbook chapter titles (case-insensitive substrings of a ``## `` heading) they call forCOOKBOOK_SYNONYMS: dict[str, tuple[str, ...]] = {"aurora": ("Light phenomena",), "curtain": ("Light phenomena",), "curtains": ("Light phenomena",),@@ -275,6 +244,11 @@ def language_system_prompt(language: Language, *, role: str = "", tools: bool =return base + "\n\n" + render(f"system/role_{role}.j2", language=language.value, **vars).strip()+#: the ``## `` headings of a scene contract an ASSET session acts on (``contract_sections``)+ASSET_CONTRACT_SECTIONS: tuple[str, ...] = ("Files", "The `ctx`", "Allowed imports", "FORBIDDEN", "Blender 5.2 API facts",+ "What the renderer does", "Naming")++def base_prompt_context(ctx: RunContext, **extra: Any) -> dict[str, Any]:"""Variables every tracks/*.j2 template may use (StrictUndefined → all present)."""plan = ctx.plan@@ -284,6 +258,10 @@ def base_prompt_context(ctx: RunContext, **extra: Any) -> dict[str, Any]:"language": ctx.language.value,"frame_doc": frame_doc(LANGUAGE_FRAME[ctx.language.value]),"contract": ctx.contract_text,+ # a scene_blender asset session writes ONE module the zones instance: it is handed the+ # contract's ctx table, imports, lint policy, API facts and render budgets, not the+ # assembler, the cameras or the worked env / zone modules it must not write+ "asset_contract": contract_sections(ctx.contract_text, ASSET_CONTRACT_SECTIONS),# the whole cookbook. It used to be ctx.cookbook_text[:6000] — a blind byte# prefix that delivered 13 % of blender's and 10 % of scene_threejs's, cutting# mid-snippet, and the read_cookbook tool that was supposed to fetch the restdiff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.pyindex fec27c34..4d5f294f 100644--- a/harness/codeverse3d/tracks/scene.py+++ b/harness/codeverse3d/tracks/scene.py@@ -52,7 +52,6 @@ from codeverse3d.tracks.generation import GenerationResult, GenerationTaskfrom codeverse3d.tracks.lifecycle import CLOCK, MATERIALIZE, SKELETON, BaseTrack, StageNodefrom codeverse3d.tracks.prompting import (base_prompt_context,- cookbook_sections,judge_digest,reference_images,refine_inline_files,@@ -73,20 +72,10 @@ log = logging.getLogger(__name__)SCENE_TIMES: tuple[float, float] = (0.0, 1.5)MAX_CONSOLE_ERRORS = 8-#: cookbook chapters inlined into the env / zone prompts (the sessions never call-#: read_cookbook on their own — measured on scenes_v1: 0 of 20 sessions did)-ENV_RECIPES: tuple[str, ...] = (- "Ground that reads real", "Horizon: the world must not end", "Atmosphere: time-of-day triads with numbers",- "Dusk / night lighting recipe",-)-ZONE_RECIPES: tuple[str, ...] = (- "Vegetation that reads real", "Rocks, cliffs and boulders that read organic",- "Set dressing: how many props a place needs", "Scene layering: foreground, midground, background",- "Motion you can SEE between t = 0 and t = 1.5 s", "Soft particles",-)-#: the zone chapters above run to ~25 k chars on scene_blender: the inlining budget must hold them all-#: (the default 24 k clipped the LAST chapter, which is the one iteration 0 needed — 2026-10-15)-ZONE_RECIPES_MAX_CHARS = 30_000+# No cookbook on this track (owner, 2026-10-15): the same four ENV and six ZONE chapters used to be+# inlined into every session whatever the brief, and the 60 iteration-0 scenes executed them+# verbatim. Interface facts live in contract.md / system.md, the craft in the skills as short+# optional practices; the prompts state requirements and what measures them.ENV_TIMEOUT_S = 420ZONE_TIMEOUT_S = 600#: a refine session that runs for half an hour (the desert-canyon round 1 did) spends the@@ -359,7 +348,7 @@ class SceneTrack(BaseTrack):return {"ok": res.ok, "files": [c.path for c in res.files_changed], "notes": res.notes}def _env_task(self, ctx: RunContext) -> GenerationTask:- prompt = render(scene_templates(ctx.language).env, **self._ctx(ctx, recipes=cookbook_sections(ctx, ENV_RECIPES)))+ prompt = render(scene_templates(ctx.language).env, **self._ctx(ctx))ctx.record_prompt("scene_env", prompt)return GenerationTask(label="env", prompt=prompt, system=self.system_prompt(ctx), files_hint=[env_file(ctx)], round=0, kind="env",temperature=0.5, timeout_s=ctx.budget.timeout_s(ENV_TIMEOUT_S, floor_s=120),@@ -406,30 +395,35 @@ class SceneTrack(BaseTrack):plan: ScenePlan = ctx.plan # type: ignore[assignment]names = [z.name for z in batch]files = [ctx.runtime.zone_file(z.name) for z in batch]- recipes = cookbook_sections(ctx, ZONE_RECIPES, max_chars=ZONE_RECIPES_MAX_CHARS)template = scene_templates(ctx.language).zonebriefs = []for i, zone in enumerate(batch):neighbours = [f"{z.name}: {plan_bbox_line(z.bbox, ctx.language)}" for z in plan.zones if z.name != zone.name]- # a batched session reads ONE copy of the recipes (they are identical per zone)- briefs.append(render(template, **self._ctx(ctx, recipes=recipes if i == 0 else "", zone_name=zone.name, zone_description=zone.description,+ # the brief's per-zone head for every zone; the shared tail (cameras, assets, the+ # contract, the measured list, tools, the catalog, the output rules) ONCE, after the+ # last head — a two-zone session used to read the contract and the 25k catalog twice+ # with "HOW TO FINISH" landing between zone 1 and zone 2 (2026-10-15)+ briefs.append(render(template, **self._ctx(ctx, zone_name=zone.name, zone_description=zone.description,zone_bbox=plan_bbox_line(zone.bbox, ctx.language), zone_contents=zone.contents,zone_file=ctx.runtime.zone_file(zone.name), neighbours=neighbours,- layout=layout_block(ctx.extra.get("layouts", {}).get(zone.name), language=ctx.language))))+ layout=layout_block(ctx.extra.get("layouts", {}).get(zone.name), language=ctx.language),+ shared=(i == len(batch) - 1))))if len(batch) == 1:prompt, label = briefs[0], f"zone_{to_snake(names[0])}"else:header = (f"# {len(batch)} zone modules in ONE session — write ALL of: {', '.join(files)}\n\n"f"You own exactly these files and nothing else. {len(batch)} complete zone briefs follow, "- "separated by a horizontal rule; implement each one in its own file exactly as its brief says. "+ "separated by a horizontal rule; implement each one in its own file as its brief says. "+ "These are EVERY zone of the scene and you are its one author: keep scale, materials and "- "placement coherent across them — nothing floats, nothing interpenetrates a neighbour, every "- "content at the plan's size, and the zones meet at their shared edges as one place. "- f"This session covers {len(batch)} zones: build EACH zone to "- "its brief's full density counts and dressing before you finish — one author measured "- "2026-09-08 finished four zones in 5 minutes as a block-out (\"missing stove\", \"shelves "- "missing\", \"primitive tools\") and scored 0.32 where the brief-by-brief fan-out reached 0.60. "- + "The recipes printed in the first brief apply to every zone in this session.\n")+ "placement coherent across them — nothing floats, nothing interpenetrates a neighbour "+ "(measured: scene_placement), every planned content at the plan's size (measured), and the "+ "zones read as ONE continuous place (judged): where the plan puts them side by side, nothing "+ "may stop dead at a zone edge. "+ f"This session covers {len(batch)} zones: finish EACH zone — every content its brief lists "+ "present and seated (measured: scene_placement) and the zone reading as the brief describes, "+ "not as a block-out (judged) — before you stop; one author measured 2026-09-08 finished four "+ "zones in 5 minutes as a block-out (\"missing stove\", \"shelves missing\", \"primitive tools\") "+ "and scored 0.32 where the brief-by-brief fan-out reached 0.60.\n")prompt = header + "\n\n---\n\n".join(briefs)label = "zones_" + "_".join(to_snake(n) for n in names)ctx.record_prompt("scene_zone", prompt) # the whole prompt the session read, not its first brief@@ -474,7 +468,7 @@ class SceneTrack(BaseTrack):def _refine_task(self, ctx: RunContext, group: TaskGroup, last: RoundRecord, index: int, *, parallel: bool) -> GenerationTask:files = group.files or ctx.runtime.expected_files(ctx.plan)lines = compact_instructions(group.tasks, max_lines=ctx.policy.max_instructions_per_task)- prompt = render(scene_templates(ctx.language).refine, **self._ctx(ctx, recipes=refine_recipes(ctx, files), round_index=index, tasks=lines,+ prompt = render(scene_templates(ctx.language).refine, **self._ctx(ctx, round_index=index, tasks=lines,targets=group.targets, files=files, edit_only_these=parallel,judge_summary=judge_digest(last),current_files=refine_inline_files(ctx, files)))@@ -489,14 +483,15 @@ class SceneTrack(BaseTrack):and the preflight's findings are the build's log tail), targeted at the failingmodule when the build names one."""lint = next((g for g in last.gates if g.gate.startswith("lint")), GateReport(gate="lint", passed=True))- report = format_error_report(last.build, lint, ctx.cookbook_text) if last.build else "build did not run"+ # no cookbook section in the report: the scene languages ship none (the "" is explicit, not a lookup)+ report = format_error_report(last.build, lint, "") if last.build else "build did not run"files: list[str] = []if last.build is not None and last.build.error_file:rel = last.build.error_file.removeprefix(str(ctx.ws.root)).lstrip("/")if (ctx.ws.root / rel).is_file():files = [rel]files = files or ctx.runtime.expected_files(ctx.plan)- prompt = render(scene_templates(ctx.language).refine, **self._ctx(ctx, recipes="", round_index=index, tasks=[report], targets=["build"],+ prompt = render(scene_templates(ctx.language).refine, **self._ctx(ctx, round_index=index, tasks=[report], targets=["build"],files=files, edit_only_these=False,judge_summary="(no judgment: the scene did not build — fix the errors above first)",current_files=refine_inline_files(ctx, files)))@@ -510,7 +505,12 @@ class SceneTrack(BaseTrack):"""The variables every scene template may use. Plan numbers are printed in the AUTHORINGframe of the run's language (``plan_vec``: the identity for three.js, so those prompts arebyte-identical; a bpy author reads Z-up points and (w, d, h) sizes, D12), plus the- runtime's file names (``env_file`` / ``entry_file``) so a template never spells a path."""+ runtime's file names (``env_file`` / ``entry_file``) so a template never spells a path.++ ``bounds`` is the extent of the PLANNED content and the cameras' subject — what the+ placement gate measures placed assets against — not the edge of the world: terrain,+ backdrop and scenery continue beyond it as the brief implies, and a template that+ reads it must say so (owner, 2026-10-15)."""plan: ScenePlan = ctx.plan # type: ignore[assignment]lang = ctx.languagezones_table = "\n".join(f"- {z.name}: {z.description} — {plan_bbox_line(z.bbox, lang)}; contents: {', '.join(z.contents) or '-'}"@@ -527,18 +527,6 @@ class SceneTrack(BaseTrack):# ----------------------------------------------------------------------------- helpers-def refine_recipes(ctx: RunContext, files: Sequence[str]) -> str:- """The cookbook chapters that match the files this refine task owns (env / zones), told apart- by the RUNTIME's file names (``env_file``, ``zone_file``), never by a suffix test."""- zone_files = {ctx.runtime.zone_file(z.name) for z in (getattr(ctx.plan, "zones", None) or [])}- names: list[str] = []- if env_file(ctx) in files:- names += list(ENV_RECIPES)- if any(f in zone_files for f in files) or not names:- names += list(ZONE_RECIPES)- return cookbook_sections(ctx, names)--def _touched(path: Any, since: float) -> bool:"""Was ``path`` (re)written after ``since``? (mtime beats existence: every zonepath already holds a skeleton stub.)"""diff --git a/harness/codeverse3d/tracks/zone_layout.py b/harness/codeverse3d/tracks/zone_layout.pyindex 3473afb1..66b21f65 100644--- a/harness/codeverse3d/tracks/zone_layout.py+++ b/harness/codeverse3d/tracks/zone_layout.py@@ -164,7 +164,8 @@ def _one_layout(zone: ZonePlan, plan: ScenePlan, model: Any, budget: Any, eventssystem = render(LAYOUT_TEMPLATE, title=plan.title, setting=plan.setting, mood=plan.mood,environment=plan.environment[:600], zone=zone, neighbours=neighbours, assets=assets,cameras=cameras, schema_fields=", ".join(ZoneLayout.model_fields))- user = f"Lay out zone {zone.name}. Description (binding): {zone.description}\nContents to place: {', '.join(zone.contents) or '(none)'}"+ user = (f"Lay out zone {zone.name}. Description (the brief's facts in it are binding; its counts are intent): "+ f"{zone.description}\nContents to place: {', '.join(zone.contents) or '(none)'}")complaint = ""for attempt in (0, 1):# the run clock outranks the layout (review-3 S3): past the hard ceiling thediff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex ec63b1ae..a6aa33cc 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -45,7 +45,11 @@ round and runs the optional **texture pass** on it. The record (plus git historwithout a rebuild; the workspace ends at the last round. Textures are a *derived asset pack*(`object_textured.glb` + `artifacts/textures/`); `object.glb` is never touched.2. **Concrete beats abstract.** Contracts are delivered as skeleton code, exact- numbers and copyable snippets (cookbooks), never as clauses.+ numbers and copyable snippets (cookbooks), never as clauses. **Except on the scene track+ (D106, 2026-10-15)**: there the harness states requirements — interface, sandbox, measured+ thresholds — and never a template; the two scene cookbooks are gone, the skeletons are+ placeholders, and a code block in a scene prompt or skill is at most ~12 lines (60 argon+ scenes of one shape were the inlined chapters executed verbatim).3. **Code answers when code can answer.** Deterministic gates / measurements runby the harness; the VLM is used only for perception and judgement, and itsscore is computed in code from rubric weights.@@ -246,7 +250,8 @@ codeverse3d/static single-file form), theme.py (CSS + the index-page JS)prompts/ EVERY piece of prompt material the harness writes, and the only place itlives: <lang>/{system,contract,cookbook}.md (incl. glsl_shader/,- opengl_python/), system/* (harness contract, single-shot envelope,+ opengl_python/; the scene languages ship NO cookbook, D106 — contract.md+ and system.md carry their interface facts), system/* (harness contract, single-shot envelope,role_{scope,asset,repair}.j2), texturing/*.md, tracks/*.j2.catalog.py answers "what exists and how does each piece reach the model"— including the ONE per-language lookup, language_prompt(language, name) /@@ -254,7 +259,8 @@ codeverse3d/(the prompts/<dir> mapping used to be copied four times and missing in a fifth;until 2026-09-22 the contract came through the runtime, the cookbook throughtracks/common, the system prompt and the catalog through tracks/prompting). sections.py splits that- markdown into chapters so a STAGE can name the recipes it needs.+ markdown into chapters so a STAGE can name the recipes it needs (graphics+ only since D106; the scene track inlines nothing).variants.py (D105): per-model OVERLAYS — variants/<name>/<rel> shadows <rel> forload_text / render / language_text while that variant is active (a ContextVarBaseTrack.run sets around the whole run from RunOptions.variant, else thediff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 203c860a..e87811d3 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -209,7 +209,8 @@ from codeverse3d.agents import get_coding_agent # (agent_id) -> Codingfrom codeverse3d.agents.materialize import materialize_workspace, codex_mcp_overridesmaterialize_workspace(ws, *, agent_kind, contract_md, cookbook_text, spatial_tools, mcp_command=None) -> None# cookbook_text = RunContext.cookbook_text, the catalog's text (Δ 2026-09-22: was cookbook_rel, resolved workspace-first,-# so an agent-written <ws>/<lang>/cookbook.md shadowed the harness cookbook); "" → "No cookbook is available" + a warning+# so an agent-written <ws>/<lang>/cookbook.md shadowed the harness cookbook); "" → no "## Cookbook" section, no .3dcode/cookbook.md+# (a stale one is removed), no warning — the scene languages ship none (D106)# mcp_command defaults to cli_common.default_mcp_command(ws) = [sys.executable, -m codeverse3d.spatial.mcp_server --workspace …]# (None/[] = the default — no ValueError); tracks/common.Services.materialize takes no mcp_command# writes AGENTS.md + CLAUDE.md (same body; Δ D103 no GEMINI.md — agy reads it AND AGENTS.md, so the body loaded@@ -423,6 +424,10 @@ from codeverse3d.spatial.scene_placement import placement_findings, placement_gaplacement_census(ws, probe, *, force_probe=False, timeout_s=60.0) -> dict # Δ D101: probe = the language's SceneRuntime.probeplacement_findings(table, *, indoor=False, language=None, thresholds=None) -> GateReport # gate "scene_placement"; data.kind ∈ floating | sunken |# unsupported | interpenetration | summary | probe_failed; target "Zone/Asset" (routes to src/zones/<zone>.js);+ # Δ D106 (2026-10-15) the PLAN kinds placement_gate adds: zone_empty | missing_content | scale | stamped_ring (WARN) | no_fog |+ # fog_short | world_edge (WARN; was no_backdrop ERROR: standing geometry ≥ WORLD_EDGE_MIN_HEIGHT_M past WORLD_EDGE_REACH_FACTOR ×+ # the half-extent) | density_note (INFO; was underdressed ERROR) | out_of_bounds (WARN on rows carrying a PLANNED content's name+ # only, margin max(BOUNDS_MARGIN_MIN_M 5, BOUNDS_MARGIN_FRAC 10 % of span); unplanned geometry past the bounds is never reported)# messages carry the scene_v2 cap words (floating / sunken / interpenetration / scale / free_exempt); reads artifacts/census.json["placement"] (host_placement.mjs)# Δ D105 (2026-10-14): thresholds = Settings.placement (config.Placement) read at CALL time, `thresholds=` overrides; the# summary INFO's data carries `thresholds` (what graded) + `counts` (measured) / `listed` (after the per-kind cap);diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex 7e2a5377..de72be54 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -106,7 +106,9 @@ round, then ≈ $0.36 / ~7 min per refine (give scenes `--max-minutes 60`).* Workspace files: `AGENTS.md` + `CLAUDE.md` (no `GEMINI.md`: agy reads both it and AGENTS.md)and `.antigravityignore`, which hides only noise (renders/judge output, the whole`trajectories/`); build/census/measurement JSON stay readable.-* Cookbook copied to `ws/.3dcode/cookbook.md` (an agent may not read outside the ws).+* Cookbook copied to `ws/.3dcode/cookbook.md` (an agent may not read outside the ws) — for a+ language that ships one; the scene languages ship none (D106), so their workspaces get no file+ and no "## Cookbook" section.* MCP server argv is `[sys.executable, -m, codeverse3d.spatial.mcp_server, --workspace, ws]`;server name `3dcode` → tools appear as `mcp__3dcode__<name>` (claude). `3dcode mcp --workspace runs/<slug>` execs the same server;`python -m codeverse3d.spatial.mcp_server --workspace ws --list` prints the tools.@@ -384,7 +386,9 @@ weather: they leave the provider's errors out (docs/COST.md §31); the ceiling dread its report with `_common.compose_build_result`, which publishes the final `build.json`); branch in`languages/base.py::get_runtime`; `prompts/<lang>/{system,contract,cookbook}.md` (found by`prompts/catalog.language_prompt`; every cookbook snippet must run — `tests/prompts`- executes them).+ executes them; a scene language has no cookbook and its prompts state requirements, never+ templates — D106: no code block over ~12 lines, numbers only where a gate or the judge+ measures them).* **Changing what a model is shown** (a prompt file or template variable, a cookbook, a skill,a rubric's text, a tool description, anything a session or a judge reads):`tests/prompts/test_manifest.py` pins every payload of offline scenarios across the four tracksdiff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.mdindex ce80170e..63c341cb 100644--- a/harness/docs/SKILLS.md+++ b/harness/docs/SKILLS.md@@ -4,9 +4,14 @@ A **skill** is a task-scoped rule sheet the harness attaches to a coding sessionautomatically — from the track, the language, the round kind, the plan, and **the previousround's gate findings**. Nobody writes `skills: [...]`.-It is not a renamed cookbook chapter. The cookbook (`codeverse3d/prompts/<lang>/cookbook.md`)-stays the reference manual with the copyable code; a skill states rules and numbers and-names the cookbook section to fetch. Two libraries of truth would be worse than one.+It is not a renamed cookbook chapter. Where a language ships a cookbook+(`codeverse3d/prompts/<lang>/cookbook.md`) it stays the reference manual with the copyable code;+a skill states rules and numbers and names the cookbook section to fetch. Two libraries of truth+would be worse than one. **The scene languages ship no cookbook (D106, 2026-10-15)**: their+interface facts live in `contract.md` / `system.md`, and a scene skill is a sheet of measured+requirements with a few SHORT optional practices (library API names, numbers only where a gate or+the judge measures them, no code block over ~12 lines) — never a chapter to copy, since the 60+iteration-0 argon scenes were the inlined chapters executed verbatim.`SKILL.md` is an open standard (agentskills.io, Dec 2025), which is why the format below isnot ours to bend: **claude-code, codex and agy discover these bundles@@ -145,21 +150,21 @@ This is the difference between a metric and a number that would have read 100% f| `c3d-repeats-and-mirrors` | object tracks | any | measured | 112 | 1,527 | R6, R7 || `c3d-blender-forms` | any | blender, urdf_blender | measured | 97 | 1,811 | R8, R9 || `c3d-urdf-joints` | articulated_object | urdf_blender | measured | 139 | 1,989 | R12, R13 |-| `c3d-scene-composition` | scene | scene_threejs | mixed | 118 | 1,691 | R14, R15, R34 |-| `c3d-scene-lighting` | scene | scene_threejs | mixed | 126 | 1,959 | R16, R17 |-| `c3d-scene-motion` | scene | scene_threejs | mixed | 178 | 2,223 | R18, R19 |+| `c3d-scene-composition` | scene | scene_threejs | mixed | 135 | 2,119 | R14, R15, R34 |+| `c3d-scene-lighting` | scene | scene_threejs | mixed | 115 | 1,748 | R16, R17 |+| `c3d-scene-motion` | scene | scene_threejs | mixed | 185 | 2,472 | R18, R19 || `c3d-threejs-shader-traps` | scene + static | threejs both | mixed | 112 | 1,734 | R20, R21 || `c3d-glsl-craft` | graphics | glsl_shader | mixed | 140 | 1,958 | R22, R24-glsl || `c3d-opengl-pipeline` | graphics | opengl_python | mixed | 98 | 1,497 | R23, R24-opengl || `c3d-cadquery-forms` | any | cadquery | **inherited-unverified** | 82 | 1,482 | R10 || `c3d-threejs-forms` | static_object | threejs | **inherited-unverified** | 120 | 1,929 | R11 |-| `c3d-scene-atmosphere` | scene | scene_threejs | **inherited-unverified** | 78 | 936 | R25 |-| `c3d-scene-water` | scene | scene_threejs | **inherited-unverified** | 71 | 806 | R26 |-| `c3d-scene-night` | scene | scene_threejs | **inherited-unverified** | 56 | 656 | R27 |-| `c3d-scene-materials` | scene | scene_threejs | **inherited-unverified** | 78 | 832 | R28 |-| `c3d-bpy-scene-placement` | scene | scene_blender | mixed | 124 | 2,209 | R29, R30 |-| `c3d-bpy-scene-lighting` | scene | scene_blender | mixed | 112 | 2,045 | R31, R32 |-| `c3d-bpy-scene-materials` | scene | scene_blender | mixed | 99 | 1,741 | R33 |+| `c3d-scene-atmosphere` | scene | scene_threejs | **inherited-unverified** | 76 | 1,030 | R25 |+| `c3d-scene-water` | scene | scene_threejs | **inherited-unverified** | 84 | 1,144 | R26 |+| `c3d-scene-night` | scene | scene_threejs | **inherited-unverified** | 60 | 787 | R27 |+| `c3d-scene-materials` | scene | scene_threejs | **inherited-unverified** | 99 | 1,434 | R28 |+| `c3d-bpy-scene-placement` | scene | scene_blender | mixed | 133 | 2,496 | R29, R30 |+| `c3d-bpy-scene-lighting` | scene | scene_blender | mixed | 124 | 2,356 | R31, R32 |+| `c3d-bpy-scene-materials` | scene | scene_blender | mixed | 113 | 2,075 | R33 |**All twenty route by default since 2026-09-22** (the three `c3d-bpy-scene-*` bundles since 2026-10-14, D105) (`C3D_SKILLS` and`C3D_SKILLS_UNVERIFIED` both default on; `C3D_SKILLS=0` turns the system off,@@ -713,9 +718,10 @@ so; the rest are live.three cookbooks still teach 2–5 mm, at or above `PENETRATION_WARN_M`. **This is the singlemost likely reason `c3d-part-contact` would fail to move the number it targets, and it isa prompt-corpus change with its own measurement. Do it before re-running that A/B.**-* **`ENV_RECIPES` / `ZONE_RECIPES` inlining in `tracks/scene.py` is untouched** — up to 6,000- unconditional tokens per env/zone session, never A/B'd against a routed skill. Now that the- scene stages deliver skills, this is the obvious comparison.+* **`ENV_RECIPES` / `ZONE_RECIPES` inlining in `tracks/scene.py` is GONE (D106, 2026-10-15)** —+ it was up to 6,000 unconditional tokens per env/zone session, never A/B'd against a routed+ skill, and iteration 0 of the argon loop showed what it bought: 60 scenes of one shape. The+ scene skills are now the only craft a scene session is offered, as short optional practices.* **Corpus percentages are checked for provenance, not recomputed.** A body's "47 gradedblender runs" is a *slice*; without each claim declaring its query, a tight recomputationcompares two different populations. Enforced today: a claim may not exceed what `eval/bench/out`diff --git a/harness/docs/SKILLS_LEDGER.md b/harness/docs/SKILLS_LEDGER.mdindex a4a88527..026c3402 100644--- a/harness/docs/SKILLS_LEDGER.md+++ b/harness/docs/SKILLS_LEDGER.md@@ -228,9 +228,9 @@ so every number below carries the snapshot it was read from.| **c3d-threejs-shader-traps** | mixed | `shader_preflight_findings` | down | **0.00**, n=9 | 0.00, n=9 | 9 | **NOT INSTRUMENTED** — see §4 | **revised (delivery).** Every listing it has ever had was in a scene session that was never offered the read tool, so it is *unmeasured*, not unread || **c3d-cadquery-forms** | inherited-unverified | `build_failure_rate` | down | 0.00, n=4 (all 4 built) | same | **4** | no variance to move | **routed OFF.** Needs 20 graded cadquery runs; has **4**. Read 2/2 when forced on || **c3d-threejs-forms** | inherited-unverified | `missing_parts` | down | 0.00, n=3 | same | **3** | no variance to move | **routed OFF.** Needs 20 graded threejs runs; has 3. Read 2/2 when forced on |-| **c3d-bpy-scene-placement** | mixed (gate code read 2026-10-14; no corpus) | `bpy_placement_errors` | down | **n=0** — no gated scene_blender runs (2026-10-14) | — | 0 | not yet measured | **new (D105).** Routed R29 (standing, 80) and R30 (gate-fired, the six seating kinds). The metric is the loop's own accept veto (floating + sunken + interpenetration ERRORs per run), so iteration 0 reads it for free. `unsupported` is WARN-only today and counts zero |-| **c3d-bpy-scene-lighting** | mixed (gate code read 2026-10-14; bands measured that day on a synthetic scene, not on runs) | `bpy_exposure_findings` | down | **n=0** — no gated scene_blender runs (2026-10-14) | — | 0 | not yet measured | **new (D105).** Routed R31 / R32. Counts the same three `scene_frames` kinds as `c3d-scene-lighting` over `scene_blender` only — a run is one language, so each A/B keeps one owner; `test_no_two_bundles_claim_the_same_quantity` has to key on (kind, language) |-| **c3d-bpy-scene-materials** | mixed (census code read 2026-10-14; no corpus) | `flat_principled_materials` | down | **UNMEASURABLE** (`measurable=false`) — see §6 | — | 0 | — | **new (D105).** Routed R33 (standing only: no gate sees material work). The census GLB reads three Principled default values and a linked socket exports as its default, so the honest instrument — a per-material linked-socket census — is a harness change, not a skill change (`wrappers/_census_glb.py`) |+| **c3d-bpy-scene-placement** | mixed (gate code read 2026-10-14; no corpus) | `bpy_placement_errors` | down | **n=0** — no gated scene_blender runs (2026-10-14) | — | 0 | not yet measured | **new (D105).** Routed R29 (standing, 80) and R30 (gate-fired, the six seating kinds). The metric is the loop's own accept veto (floating + sunken + interpenetration ERRORs per run), so iteration 0 reads it for free. `unsupported` is WARN-only today and counts zero. **De-templated 2026-10-15** (owner's rule): requirements + their measurements, `lib.place` / `lib.scatter` / `lib.terrain` as an optional toolbox, `make_height_at` one landform option, the world continuing past the bounds, `world_edge` (was `no_backdrop`) stated as its measure (1.25 × half-extent), no ring / plate / counts |+| **c3d-bpy-scene-lighting** | mixed (gate code read 2026-10-14; bands measured that day on a synthetic scene, not on runs) | `bpy_exposure_findings` | down | **n=0** — no gated scene_blender runs (2026-10-14) | — | 0 | not yet measured | **new (D105).** Routed R31 / R32. Counts the same three `scene_frames` kinds as `c3d-scene-lighting` over `scene_blender` only — a run is one language, so each A/B keeps one owner; `test_no_two_bundles_claim_the_same_quantity` has to key on (kind, language). **De-templated 2026-10-15**: the band as the requirement, the lib pairs as measured ways, the `no_fog` census fact and the rig's `Ceiling…`/`RoomShell…` lid rule stated as interface, the one-sun rule replaced by the 0.83 two-sun measurement |+| **c3d-bpy-scene-materials** | mixed (census code read 2026-10-14; no corpus) | `flat_principled_materials` | down | **UNMEASURABLE** (`measurable=false`) — see §6 | — | 0 | — | **new (D105).** Routed R33 (standing only: no gate sees material work). The census GLB reads three Principled default values and a linked socket exports as its default, so the honest instrument — a per-material linked-socket census — is a harness change, not a skill change (`wrappers/_census_glb.py`). **De-templated 2026-10-15**: `flat_ground` stated as the judged requirement with options by brief (slope/height mix, worn band, apron, vertex colours, paving), `noise_scale` where the brief's material varies, soft particles as volumes (8 of 30 iteration-0 scenes graded `hard_edged_particles`) |**Cut this wave:** `c3d-form-manifest` (text in git history; `docs/skills-attic/` was removed 2026-09-21).diff --git a/harness/tests/agents/test_materialize.py b/harness/tests/agents/test_materialize.pyindex 50acb663..c0f31ac7 100644--- a/harness/tests/agents/test_materialize.py+++ b/harness/tests/agents/test_materialize.py@@ -50,7 +50,23 @@ def test_no_mcp_config_and_no_gemini_body_is_written_into_the_workspace(tmp_ws:assert {p.name for p in tmp_ws.root.glob("*.md")} >= {"AGENTS.md", "CLAUDE.md"}-def test_ignore_files_keep_agent_facing_paths_readable_and_a_missing_cookbook_is_said(tmp_ws: Workspace):+def test_a_language_without_a_cookbook_gets_no_section_and_no_file(tmp_ws: Workspace):+ """The scene languages ship no cookbook (owner, 2026-10-15): the body carries no "## Cookbook"+ section — not a note saying one is missing, which only sends the agent looking — and no+ ``.3dcode/cookbook.md`` is written (a stale one from an earlier materialisation goes). A+ language that ships one still gets the section and the file."""+ tmp_ws.spec_path.write_text(json.dumps({"id": "t", "track": "scene", "language": "scene_threejs", "prompt": "p"}))+ _mat(tmp_ws, cookbook="# a cookbook\n\nsnippets\n")+ body = (tmp_ws.root / "AGENTS.md").read_text()+ assert "## Cookbook" in body and (tmp_ws.root / ".3dcode" / "cookbook.md").read_text() == "# a cookbook\n\nsnippets\n"+ _mat(tmp_ws, cookbook="")+ body = (tmp_ws.root / "AGENTS.md").read_text()+ assert "## Cookbook" not in body and "cookbook" not in body.lower()+ assert not (tmp_ws.root / ".3dcode" / "cookbook.md").exists()+ assert body.index("## Spatial tools") < body.index("## Language contract") # the sections around it stay in order+++def test_ignore_files_keep_agent_facing_paths_readable(tmp_ws: Workspace):"""Ignored paths are hidden from the agent: census and tool renders stay readable."""import fnmatch@@ -79,8 +95,6 @@ def test_ignore_files_keep_agent_facing_paths_readable_and_a_missing_cookbook_is"trajectories/baseline_r00/prompt.md", "trajectories/baseline_r00/agy.log","trajectories/baseline_r00/stderr.log", "node_modules/three/x.js", ".git/HEAD"):assert ignored(hidden, lines), hidden- # no cookbook resolved (the default here): the body says so rather than naming a missing file- assert "No cookbook is available" in (tmp_ws.root / "AGENTS.md").read_text()def test_kind_specific_tool_hint_and_spatial_disabled_documents_absence(tmp_ws: Workspace):diff --git a/harness/tests/core/test_config_env_aliases.py b/harness/tests/core/test_config_env_aliases.pyindex f839511b..b7256a04 100644--- a/harness/tests/core/test_config_env_aliases.py+++ b/harness/tests/core/test_config_env_aliases.py@@ -47,7 +47,7 @@ def test_the_in_flight_cap_spellings_empty_zero_and_garbage(monkeypatch):assert Settings().render.gpu == "on"monkeypatch.delenv("C3D_RATE__MAX_IN_FLIGHT", raising=False)monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "")- assert Settings().rate.max_in_flight == 64+ assert Settings().rate.max_in_flight == 96assert Rate(max_in_flight=0).max_in_flight == 0, "0 stays legal: it means unlimited"monkeypatch.setenv("C3D_MAX_IN_FLIGHT", "sixteen")with pytest.raises(ValueError, match="max_in_flight"):diff --git a/harness/tests/core/test_doctor.py b/harness/tests/core/test_doctor.pyindex cbcd854b..e827bdbd 100644--- a/harness/tests/core/test_doctor.py+++ b/harness/tests/core/test_doctor.py@@ -128,4 +128,4 @@ def test_doctor_skills_reports_the_shipped_argon_overlay(monkeypatch):get_settings.cache_clear()assert rows["skills library"][0] == "OK"status, detail = rows["skills overlay"]- assert status == "OK" and detail.startswith("argon: 0 bundles, 0 invalid") and "2 boost(s)" in detail+ assert status == "OK" and detail.startswith("argon: 0 bundles, 0 invalid") and "1 boost(s)" in detaildiff --git a/harness/tests/judges/test_scene_judge.py b/harness/tests/judges/test_scene_judge.pyindex 49ef5259..a5d847e5 100644--- a/harness/tests/judges/test_scene_judge.py+++ b/harness/tests/judges/test_scene_judge.py@@ -316,9 +316,22 @@ def test_scene_v2_numbers_are_pinned():defects = {d.id: (d.penalty, d.cap) for d in S.defects}assert "floating_or_sunken_asset" not in defectsassert {k: defects[k] for k in ("floating_asset", "sunken_asset", "interpenetration", "wrong_scale", "hard_edged_particles",- "missing_planned_element", "hero_misplaced")} == {+ "missing_planned_element", "hero_misplaced", "diorama_look")} == {"floating_asset": (0.10, 0.60), "sunken_asset": (0.08, 0.65), "interpenetration": (0.08, 0.70), "wrong_scale": (0.06, 0.75),- "hard_edged_particles": (0.04, None), "missing_planned_element": (0.06, None), "hero_misplaced": (0.06, None)}+ "hard_edged_particles": (0.04, None), "missing_planned_element": (0.06, None), "hero_misplaced": (0.06, None),+ "diorama_look": (0.05, None)}+ # 2026-10-15 (owner's rule): the craft criteria and defects judge against the BRIEF's place, not one recipe;+ # `diorama_look` names the template (a block on a plate ringed by a uniform backdrop, nothing beyond) and+ # asks for the view; nothing in the rubric prescribes blended ground + paths, clusters, a foreground frame+ # within a few metres, or fog + a two-hue key/fill for every scene+ diorama = S.defect("diorama_look").text+ assert "flat plate" in diorama and "uniform backdrop" in diorama and "nothing" in diorama and "Cite the view" in diorama+ whole = (S.extra_instructions + " " + " ".join(d.text for d in S.defects) + " " + " ".join(+ c.description + " " + " ".join(c.anchors.values()) for c in S.criteria)).lower()+ for recipe in ("blended materials with paths", "in clusters", "rather than clusters", "within a few metres",+ "warm key against a cooler fill", "fog/haze", "litter", "no haze", "boxes-and-cones"):+ assert recipe not in whole, recipe+ assert "brief's weather" in whole and "arranged as the place would arrange them" in whole# six anchors on every criterion; the weights are v1'sfor c in S.criteria:assert sorted(c.anchors, key=float) == ["0.1", "0.4", "0.55", "0.7", "0.85", "1.0"], c.iddiff --git a/harness/tests/orchestrator_tracks/test_prompts_assets.py b/harness/tests/orchestrator_tracks/test_prompts_assets.pyindex 432886d6..cfa60925 100644--- a/harness/tests/orchestrator_tracks/test_prompts_assets.py+++ b/harness/tests/orchestrator_tracks/test_prompts_assets.py@@ -95,7 +95,7 @@ def test_scene_templates_render_and_asset_stage_with_blender(tmp_ws, settings):from codeverse3d.tracks.scene_assets import _asset_promptshrine = plan.assets[0].model_copy(update={"description": "a wayside shrine with a birch (makeTree) beside it"})- lead = "The sheet names shipped effect-library factories"+ lead = "The sheet lists shipped effect-library factories" # the optional-toolbox wording (2026-10-15)with_lib = _asset_prompt(ctx, shrine, "src/assets/shrine.js", language=Language.SCENE_THREEJS)assert lead in with_lib and "leafSegments" in with_lib and "`lib/rock.js`" not in with_libassert lead not in _asset_prompt(ctx, plan.assets[0], "src/assets/x.js", language=Language.SCENE_THREEJS)diff --git a/harness/tests/prompts/test_files.py b/harness/tests/prompts/test_files.pyindex 0302ba95..fb5d61ee 100644--- a/harness/tests/prompts/test_files.py+++ b/harness/tests/prompts/test_files.py@@ -23,16 +23,27 @@ def test_prompt_file_contract(rel: str) -> None:assert seq not in raw, f"{rel} contains {seq!r} which breaks jinja rendering"-def test_every_language_ships_a_system_prompt_a_contract_and_a_cookbook() -> None:- """A missing per-language file silently reads as "" through ``language_text`` — every language,- scene_blender included (its prompts landed with the argon scene-tuning program, 2026-10-14)."""+#: the scene languages ship NO cookbook (owner, 2026-10-15): its interface facts are in contract.md /+#: system.md, its craft in the skills as short optional practices — nothing a model can copy verbatim+NO_COOKBOOK = frozenset({Language.SCENE_THREEJS, Language.SCENE_BLENDER})+++def test_every_language_ships_a_system_prompt_and_a_contract_and_the_scene_languages_no_cookbook() -> None:+ """A missing per-language file silently reads as "" through ``language_text`` — so the two files+ every language needs are pinned present, and the cookbook pinned present OR absent per language:+ a scene cookbook that came back would reach every session again through ``cookbook_text``."""+ from codeverse3d.prompts.catalog import language_textfrom codeverse3d.tracks.prompting import language_system_promptfor lang in Language:text = language_system_prompt(lang)assert text.strip(), f"{lang.value}: empty system prompt"- for name in ("system.md", "contract.md", "cookbook.md"):+ for name in ("system.md", "contract.md"):assert (PROMPTS_DIR / language_prompt(lang, name)).is_file(), (lang.value, name)+ has_cookbook = (PROMPTS_DIR / language_prompt(lang, "cookbook.md")).is_file()+ assert has_cookbook == (lang not in NO_COOKBOOK), (lang.value, "cookbook.md", has_cookbook)+ for lang in NO_COOKBOOK:+ assert language_text(lang, "cookbook.md") == ""assert language_prompt(Language.URDF_BLENDER, "cookbook.md") == "urdf/cookbook.md"for role in ("scope", "repair"):assert (PROMPTS_DIR / "system" / f"role_{role}.j2").is_file(), rolediff --git a/harness/tests/prompts/test_snippets_run.py b/harness/tests/prompts/test_snippets_run.pyindex a016de3a..9a8a5c7f 100644--- a/harness/tests/prompts/test_snippets_run.py+++ b/harness/tests/prompts/test_snippets_run.py@@ -1,9 +1,10 @@-"""The cookbooks' promise: every snippet RUNS.+"""The cookbooks' and contracts' promise: every snippet RUNS.* cadquery blocks run in-process (cadquery is a plain library).* bpy blocks run in real headless Blender (marker: blender).* js blocks run in real node against runtime_js/node_modules (marker: node).-* GLSL factories compile in real headless-Chrome WebGL (marker: node).+* the scene languages ship no cookbook (owner, 2026-10-15): their contracts' COMPLETE examples+ run through the real runtimes below, and that is the whole of their runnable prompt material."""from __future__ import annotations@@ -21,7 +22,6 @@ from tests.prompts.conftest import (run_node_module,strip_imports_exports,)-from tests.scene_runtime.lib._probe import compile_scene# --------------------------------------------------------------------- cadquery@@ -171,103 +171,36 @@ console.log('GLB_OK', verts, buf.byteLength);assert (tmp_path / "object.glb").stat().st_size > 1000-# the lib calls the scene cookbook's snippets make (their `import` lines are stripped)-_SCENE_LIB_IMPORTS = (- "import { mulberry32 } from './lib/noise.js';\n"- "import { makeShaderMaterial } from './lib/shader.js';\n"- "import { makeCanopy } from './lib/canopy.js';\n"- "import { PRACTICAL } from './lib/environment.js';\n"-)--@pytest.mark.node-def test_scene_cookbook_runs(tmp_path) -> None:- stub = (- _SCENE_LIB_IMPORTS +- "function collectAnimatedMaterials(scene){const mats=[];scene.traverse(o=>{"- "const l=Array.isArray(o.material)?o.material:(o.material?[o.material]:[]);"- "for(const m of l) if(m.userData&&typeof m.userData.update==='function'&&!mats.includes(m))"- "mats.push(m);});return mats;}\n"- )- body = "".join(- f"\nconsole.log('--- block {i} ---');\n" + strip_imports_exports(b)- for i, b in enumerate(blocks("scene_threejs/cookbook.md", "js"))- )- out = run_node_module(tmp_path, js_prelude(stub) + body + "\nconsole.log('JS_BLOCKS_OK');\n")- assert "JS_BLOCKS_OK" in out and "[selfcheck]" in out---def test_scene_contract_example_shape(tmp_path) -> None:+def test_scene_contract_env_example_is_the_interface_and_nothing_else(tmp_path) -> None:+ """The contract's one labelled file is ``src/env.js`` with the three exports the assembler reads and+ no scene inside it (the complete day scene it used to carry — a sun rig, a grove of cones, the+ +X+Z corner camera — was the most pasteable passage of the prompt corpus, 2026-10-15)."""files = labelled_files("scene_threejs/contract.md")- assert set(files) == {"src/env.js", "src/zones/grove.js", "src/scene.js"}- for rel, body in files.items():- p = tmp_path / rel- p.parent.mkdir(parents=True, exist_ok=True)- p.write_text(body)+ assert set(files) == {"src/env.js"}+ body = files["src/env.js"]+ assert len(body.strip().splitlines()) <= 12+ for word in ("sunRig", "Fog(", "PlaneGeometry", "position: [", "Cone"):+ assert word not in body, word+ p = tmp_path / "src" / "env.js"+ p.parent.mkdir(parents=True, exist_ok=True)+ p.write_text(body)runner = """import * as THREE from 'three';-import { createScene } from './src/scene.js';-const r = await createScene({ THREE, renderer: null, loaders: {} });-if (!r.scene || !r.scene.isScene) throw new Error('no scene');-if (!r.scene.fog) throw new Error('no fog');-if (!Array.isArray(r.cameras) || r.cameras.length < 2) throw new Error('cameras');-for (const c of r.cameras) {- if (typeof c.name !== 'string' || !Array.isArray(c.position) || !Array.isArray(c.lookAt))- throw new Error('camera shape: ' + JSON.stringify(c));-}-r.update(0, 0); r.update(1.5, 0.016);-console.log('SCENE_OK', r.cameras.map((c) => c.name).join(','));+import * as env from './src/env.js';+if (typeof env.heightAt !== 'function' || typeof env.heightAt(3, 4) !== 'number') throw new Error('heightAt');+if (typeof env.SUN_AZIMUTH_DEG !== 'number') throw new Error('SUN_AZIMUTH_DEG');+const scene = new THREE.Scene();+const out = env.buildEnv({ THREE, scene });+if (!out || typeof out.update !== 'function') throw new Error('buildEnv must return { update }');+out.update(0, 0); out.update(1.5, 0.016);+console.log('ENV_OK');"""out = run_node_module(tmp_path, runner)- assert "SCENE_OK" in out---def test_scene_cookbook_sky_shader_compiles() -> None:- """The sky dome the scene cookbook builds with makeShaderMaterial must also compile — as a Mesh- (the dome) and as an InstancedMesh, through the production host (``check_shaders.mjs``)."""- body = "".join("\n" + strip_imports_exports(b) for b in blocks("scene_threejs/cookbook.md", "js")[:2])- scene = (- "import * as THREE from 'three';\nimport { sunRig } from './lib/environment.js';\n"- "import { mulberry32 } from './lib/noise.js';\nimport { makeShaderMaterial } from './lib/shader.js';\n"- + body- + "\nexport function createScene() {\n"- " const scene = new THREE.Scene();\n"- " const env = buildEnv({ THREE, scene });\n"- " const sky = scene.getObjectByName('SkyDome');\n"- " scene.add(new THREE.InstancedMesh(new THREE.PlaneGeometry(2, 2), sky.material, 4));\n"- " return { scene, cameras: [{ name: 'a', position: [3, 3, 5], lookAt: [0, 0, 0] }], update: env.update };\n"- "}\n"- )- code, out = compile_scene(scene, ("environment.js", "sky.js"))- assert code == 0, f"sky shader failed to compile:\n{out}"+ assert "ENV_OK" in out# --------------------------------------------------------------------- scene_blender-#: what the scene_blender cookbook's header promises every zone-body snippet has in scope-_BPY_PRELUDE = "import math\n\nimport bmesh\nimport bpy\nfrom mathutils import Euler, Matrix, Vector, noise\n"-#: a block that is module-level ``src/env.py`` code instead (the world is only ever built there)-BPY_ENV_ROLE = "# role: env"---def bpy_snippet_modules(rel: str) -> tuple[str, dict[str, str]]:- """``(src/env.py source, {zone snake: zone module source})`` for the python blocks of ``rel``: the- ``# role: env`` blocks concatenated in order into ONE env module, every other block the body of its- own zone's ``build(ctx)`` under the prelude the cookbook header states."""- env_blocks: list[str] = []- zones: dict[str, str] = {}- for i, body in enumerate(blocks(rel, "python")):- if body.lstrip().startswith(BPY_ENV_ROLE):- env_blocks.append(body)- continue- indented = "".join((" " + line) if line.strip() else line for line in body.splitlines(keepends=True))- zones[f"snippet_{i:02d}"] = (f'"""block {i} of {rel}, run as a zone by tests/prompts/test_snippets_run.py."""\n'- + _BPY_PRELUDE + "\n\ndef build(ctx):\n rng = ctx.rng(7)\n" + indented- + ("" if indented.endswith("\n") else "\n") + " return ctx.collection\n")- return "\n\n".join(env_blocks), zones--def _bpy_workspace(tmp_path):"""The scratch workspace the scene_blender snippets run in: the skeleton of the bpy worked example(its two module assets build first → ``ctx.assets``), through the real runtime."""@@ -287,37 +220,30 @@ def _bpy_workspace(tmp_path):@pytest.mark.blender-def test_scene_blender_cookbook_runs_inside_zones_and_lints_clean(tmp_path) -> None:- """The bpy cookbook's promise: every snippet runs in Blender 5.2.2 under the ctx the wrapper hands- out (one process for all of them) and passes the scene lint for its role with no WARN."""- from codeverse3d.contracts.artifacts import Severity+def test_the_bpy_plan_skeleton_builds_in_blender_as_written(tmp_path) -> None:+ """The fresh skeleton (a stub env — a level plate and nothing that passes: no world, lamp or+ atmosphere — and a TODO stub per zone) builds in Blender 5.2.2 before an author touches it: every+ zone ok, no env error, a ground in the census and no fog or light until the author writes the+ brief's (2026-10-15)."""from codeverse3d.conventions import to_pascal- from codeverse3d.languages.scene_blender import lint_scene_source-- ws, rt, _ = _bpy_workspace(tmp_path)- env_src, zones = bpy_snippet_modules("scene_blender/cookbook.md")- assert env_src and len(zones) >= 10- (ws.src / "env.py").write_text(env_src)- for name, src in zones.items():- (ws.src / "zones" / f"{name}.py").write_text(src)- bad = {}- for rel, src, role in [("src/env.py", env_src, "env"), *((f"src/zones/{n}.py", s, "zone") for n, s in zones.items())]:- findings = [f for f in lint_scene_source(src, target=rel, role=role) if f.severity is not Severity.INFO]- if findings:- bad[rel] = [(f.severity.value, f.message) for f in findings]- assert not bad, bad++ ws, rt, plan = _bpy_workspace(tmp_path)+ zones = {rt.zone_file(z.name).rsplit("/", 1)[-1][:-3] for z in plan.zones}run = rt.run_wrapper(ws, ws.artifacts, zones={n: to_pascal(n) for n in zones}, blend=False, timeout_s=600)- errors = [(e.get("stage"), e.get("name"), e.get("error_file"), e.get("error_line"), e.get("error_message")) for e in run.report.get("errors") or []]+ errors = [(e.get("stage"), e.get("name"), e.get("error_file"), e.get("error_line"), e.get("error_message"))+ for e in run.report.get("errors") or []]assert run.result.ok and not errors, (run.result.error_type, run.result.error_message, errors)assert sorted(run.report["zones_ok"]) == sorted(zones)- assert not run.report.get("warnings"), run.report.get("warnings")+ assert run.facts.get("fog") is None and not run.facts.get("lights"), {k: run.facts.get(k) for k in ("fog", "lights")}@pytest.mark.blender@pytest.mark.nodedef test_scene_blender_contract_examples_build_through_the_runtime(tmp_path) -> None:"""The contract's two COMPLETE files (built on the shipped bpy library, D51) lint clean, assemble,- build and seat what they place — through the real runtime, gates included."""+ build and seat what they place — through the real runtime, gates included. The contract's python+ blocks are exactly these two labelled files: nothing else of the bpy prompt material is code."""+ assert len(blocks("scene_blender/contract.md", "python")) == len(labelled_files("scene_blender/contract.md", tag="python"))from codeverse3d.contracts.artifacts import Severityfrom codeverse3d.languages import scene_blender as sbfrom tests.scene_runtime.conftest import browser_availablediff --git a/harness/tests/prompts/test_variants.py b/harness/tests/prompts/test_variants.pyindex 22c37ffd..186a542f 100644--- a/harness/tests/prompts/test_variants.py+++ b/harness/tests/prompts/test_variants.py@@ -224,7 +224,8 @@ def test_variant_hash_covers_both_overlays_and_ignores_readmes(overlay, tmp_pathdef test_the_argon_variant_ships_the_iteration_1_overlays():"""Iteration 0 of the loop measured the base prompts under the plumbing (an empty overlay);- iteration 1 (2026-10-15) shadows the two zone briefs and boosts the two placement skills — the+ iteration 1 (2026-10-15) shadows the two zone briefs and boosts the Blender placement skill (the+ three.js composition boost was withdrawn under D106: that bundle carried the template) — thewhole overlay is these files, nothing else, and the hash covers them."""from codeverse3d.skills import variant_dir, variants_table@@ -240,7 +241,7 @@ def test_the_argon_variant_ships_the_iteration_1_overlays():assert sorted(p.name for p in variant_dir("argon").iterdir()) == ["README.md", "routes.toml"]table = variants_table("argon")assert not table.empty and table.variant == "argon" and not table.routes and not table.disabled- assert {(b.skill, b.delta) for b in table.boosts} == {("c3d-scene-composition", 14), ("c3d-bpy-scene-placement", 9)}+ assert {(b.skill, b.delta) for b in table.boosts} == {("c3d-bpy-scene-placement", 9)} # the composition boost was withdrawn (D106)assert len(variant_hash("argon")) == 12diff --git a/harness/tests/scene_blender/test_build.py b/harness/tests/scene_blender/test_build.pyindex 81e16fbe..02a23f40 100644--- a/harness/tests/scene_blender/test_build.py+++ b/harness/tests/scene_blender/test_build.py@@ -99,13 +99,16 @@ def test_the_skeleton_builds_and_passes(tmp_ws) -> None:res = rt.build(tmp_ws)assert res.ok, res.stdout_tailc = res.census- assert c["fog"]["type"] == "VolumeBox" and c["background"] == "sky:MULTIPLE_SCATTERING"- assert "Atmosphere" in c["bpy"]["glb"]["volumes_skipped"]+ # the stub env ships a plate and nothing that passes: no world, no atmosphere, no lamp until the author+ # writes the brief's (a placeholder that passed was kept by every author, 2026-10-15)+ assert c["fog"] is None and c["background"] is None and not c["bpy"]["glb"]["volumes_skipped"]assert {g["name"] for g in c["groups"]} >= {"Quay", "Water", "Ground"}- assert c["light_types"] == {"SUN": 1} and c["bpy"]["drivers_invalid"] == []- # every planned asset the stubs placed (lib.scatter.instance) is seated on the library's ground+ assert c["light_types"] == {} and c["bpy"]["drivers_invalid"] == []+ # the zone stubs place NOTHING (D106: they name the plan's contents and decide no position — the+ # grid of placeholders inside the bbox was the seed of the block-on-a-plate look), so the fresh+ # skeleton's placement table is empty and anything an author then places is measured on its ownplaced = [r for r in c["placement"]["assets"] if r["zone"] in ("Quay", "Water") and not r["exempt"]]- assert placed and all(r["supported"] and not r["floating"] and r["sunk_m"] <= 0.10 for r in placed), placed+ assert placed == [], placedprobe = json.loads((tmp_ws.artifacts / "scene_probe.json").read_text())# the plan's cameras, named as scene_threejs's assembler names themassert [cam["name"] for cam in probe["boot"]["cameras"]] == [to_snake(c.name) for c in plan.cameras[:6]]diff --git a/harness/tests/scene_blender/test_layout.py b/harness/tests/scene_blender/test_layout.pyindex ebb2e5f1..f7e74e9a 100644--- a/harness/tests/scene_blender/test_layout.py+++ b/harness/tests/scene_blender/test_layout.py@@ -98,17 +98,21 @@ def test_the_skeleton_writes_the_layout(tmp_ws) -> None:assert want <= pathsfor p in paths:compile((tmp_ws.root / p).read_text(), p, "exec")- # a Blender object name is global: two zones never place the same <Name>_<i>- names = [n for z in ("quay", "water")- for n in re.findall(r'place\(ctx, "\w+", "(\w+)"', (tmp_ws.src / "zones" / f"{z}.py").read_text())]- assert names- assert len(names) == len(set(names))+ # the zone stub names its planned contents (the census measures them as present) and decides+ # no position: the grid of place() calls inside the bbox was the seed of the block-on-a-plate+ # look (D106)+ for z, contents in (("quay", ("Bollard", "Crate")), ("water", ("FishingBoat",))):+ text = (tmp_ws.src / "zones" / f"{z}.py").read_text()+ assert all(f"- {c}: ctx.assets['" in text for c in contents), text+ assert "place(ctx" not in text and "keep them inside" not in text and "ctx.height_at" in text# the library ships with the plan skeleton (D51: a catalog with no src/lib/ to import from# made every library import a build error on the three.js side), and the env / stubs USE itlib = {p.rsplit("/", 1)[1] for p in paths if p.startswith("src/lib/")}assert lib == {p.name for p in lib_files()} | {"__init__.py"} and len(lib) == 14- assert "from lib import architecture, lighting, materials, sky, terrain" in (tmp_ws.src / "env.py").read_text()- assert "from lib.scatter import instance" in (tmp_ws.src / "zones" / "quay.py").read_text()+ env = (tmp_ws.src / "env.py").read_text()+ assert "from lib import materials, terrain" in env # the placeholder plate uses the toolbox+ assert "sky.sun_world(" not in env and "sky.haze(" not in env and "lighting.sun(" not in env # no light or atmosphere decided (2026-10-15)+ assert "lib.scatter.instance" in (tmp_ws.src / "zones" / "quay.py").read_text() # named as one wayassert "from lib.mesh import Batch" in (tmp_ws.src / "assets" / "bollard.py").read_text()diff --git a/harness/tests/scene_blender/test_library.py b/harness/tests/scene_blender/test_library.pyindex 1c1ef715..fcc53131 100644--- a/harness/tests/scene_blender/test_library.py+++ b/harness/tests/scene_blender/test_library.py@@ -191,11 +191,11 @@ def _prose_spans(text: str):yield n, span-def test_the_cookbook_and_the_bpy_skills_never_print_a_keyword_only_parameter_positionally() -> None:- """The weaker rule for prose the catalog does not own (the cookbook's snippets RUN in Blender —- tests/prompts/test_snippets_run.py — so only its printed signatures can mislead): a keyword-only- parameter is never printed bare, a printed ``*`` sits where the lib's is, every name exists.- Lib names are unique across the modules, so a bare name finds its def."""+def test_the_bpy_skills_never_print_a_keyword_only_parameter_positionally() -> None:+ """The weaker rule for prose the catalog does not own (the skills; the cookbook that once joined+ them is gone, 2026-10-15): a keyword-only parameter is never printed bare, a printed ``*`` sits+ where the lib's is, every name exists. Lib names are unique across the modules, so a bare name+ finds its def."""funcs: dict[str, ast.FunctionDef] = {}methods: dict[str, ast.FunctionDef] = {}for stem in MODULES:@@ -206,9 +206,8 @@ def test_the_cookbook_and_the_bpy_skills_never_print_a_keyword_only_parameter_pofor cls, ms in classes.items():funcs[cls] = ms.get("__init__", funcs.get(cls))methods.update(ms)- texts = {"scene_blender/cookbook.md": language_text(Language.SCENE_BLENDER, "cookbook.md")}- texts |= {str(md.relative_to(skills_dir().parent)): md.read_text() for md in sorted(skills_dir().glob("c3d-bpy-scene-*/**/*.md"))}- assert len(texts) >= 4, sorted(texts) # the cookbook and three SKILL.md at least+ texts = {str(md.relative_to(skills_dir().parent)): md.read_text() for md in sorted(skills_dir().glob("c3d-bpy-scene-*/**/*.md"))}+ assert len(texts) >= 3, sorted(texts) # three SKILL.md at leastfaults: list[str] = []for where, text in texts.items():for n, span in _prose_spans(text):@@ -219,7 +218,7 @@ def test_the_cookbook_and_the_bpy_skills_never_print_a_keyword_only_parameter_poassert not faults, "\n".join(faults)-# --------------------------------------------------------------------------- the signatures the cookbook cites+# --------------------------------------------------------------------------- the signatures the catalog and the skills citeSIGNATURES = [("noise", "fbm2", ["x", "y", "*", "octaves", "lacunarity", "gain", "seed"]),("noise", "mountain_height", ["x", "y", "*", "seed", "amplitude", "frequency"]),@@ -249,7 +248,7 @@ SIGNATURES = [@pytest.mark.parametrize(("stem", "name", "params"), SIGNATURES, ids=[f"{s}.{n}" for s, n, _ in SIGNATURES])-def test_the_signatures_the_catalog_and_cookbook_cite(stem: str, name: str, params: list[str]) -> None:+def test_the_signatures_the_catalog_and_skills_cite(stem: str, name: str, params: list[str]) -> None:"""Names AND the keyword-only boundary (``"*"``): the prompts cite these by position."""funcs, classes = _defs(stem)fn = classes[name.split(".")[0]][name.split(".")[1]] if "." in name else funcs[name]diff --git a/harness/tests/scene_blender/test_prompts.py b/harness/tests/scene_blender/test_prompts.pyindex 2c9fa9a4..ed6f6414 100644--- a/harness/tests/scene_blender/test_prompts.py+++ b/harness/tests/scene_blender/test_prompts.py@@ -19,7 +19,6 @@ from codeverse3d.languages.scene_blender import LIB_DIRfrom codeverse3d.proc import EventLogfrom codeverse3d.prompts import PROMPTS_DIR, renderfrom codeverse3d.prompts.catalog import language_text-from codeverse3d.prompts.sections import find_section, split_sectionsfrom codeverse3d.skills import skills_dirfrom codeverse3d.tracks import scene_assets as SAfrom codeverse3d.tracks.planner import (@@ -29,17 +28,14 @@ from codeverse3d.tracks.planner import (plan_schema,plan_template,)-from codeverse3d.tracks.prompting import cookbook_sections, language_system_prompt+from codeverse3d.tracks.prompting import language_system_promptfrom codeverse3d.tracks.scene import (ENV_FILES,- ENV_RECIPES,SCENE_TEMPLATES,- ZONE_RECIPES,SceneTrack,_guess_target,env_file,plan_bbox_line,- refine_recipes,scene_templates,)from codeverse3d.tracks.scene_assets import (@@ -74,32 +70,18 @@ def settings(tmp_path):# --------------------------------------------------------------------------- the files-def test_the_language_ships_its_four_prompt_files_and_the_system_prompt_knows_about_tools() -> None:- for name in ("system.md", "contract.md", "cookbook.md", "asset.md"):+def test_the_language_ships_its_three_prompt_files_and_the_system_prompt_knows_about_tools() -> None:+ """system / contract / asset — and no cookbook (owner, 2026-10-15; tests/prompts/test_files.py pins+ its absence): the Blender 5.2 facts (D104) that lived in it are the contract's."""+ for name in ("system.md", "contract.md", "asset.md"):assert language_text(BPY, name).strip(), namewith_tools, without = language_system_prompt(BPY, tools=True), language_system_prompt(BPY, tools=False)assert "check_placement" in with_tools and "single-shot" not in with_toolsassert "single-shot" in without and "`build` →" not in withoutassert "Blender 5.2" in with_tools- for text in (language_text(BPY, "contract.md"), language_text(BPY, "cookbook.md")):- assert "use_nodes" in text and "MULTIPLE_SCATTERING" in text # Blender 5.2 facts (D104), not 4.x ones- assert "Action.fcurves" in text and "mod.properties.inputs" in text---def test_the_cookbook_has_every_chapter_the_stages_inline() -> None:- """``cookbook_sections`` finds a chapter by title (exact, then substring): every ENV / ZONE recipe- must resolve to ITS chapter, not to the word-overlap fallback."""- md = language_text(BPY, "cookbook.md")- sections = split_sections(md)- for title in (*ENV_RECIPES, *ZONE_RECIPES):- found = find_section(sections, title)- assert found is not None and title.lower() in found.title.lower(), (title, found and found.title)- ctx = SimpleNamespace(cookbook_text=md)- env_text, zone_text = cookbook_sections(ctx, ENV_RECIPES), cookbook_sections(ctx, ZONE_RECIPES)- assert "# role: env" in env_text and "MULTIPLE_SCATTERING" in env_text and "TIME_OF_DAY" in env_text- for token in ("tree_mesh", "clustered_points", "camera_mask", "keyframe_linear", "along_seam", "rock_geometry"):- assert token in zone_text, token- assert len(zone_text) > 12_000 and "# role: env" not in zone_text+ text = language_text(BPY, "contract.md")+ assert "use_nodes" in text and "MULTIPLE_SCATTERING" in text # Blender 5.2 facts (D104), not 4.x ones+ assert "Action.fcurves" in text and "mod.properties.inputs" in textdef _clear_of_loops(text: str) -> list[ast.For]:@@ -108,9 +90,13 @@ def _clear_of_loops(text: str) -> list[ast.For]:for line in text.splitlines():head = line.strip()if head.startswith("for ") and "clear_of(" in head:- try:- node = ast.parse(head + "\n pass").body[0]- except SyntaxError:+ for attempt in (head + "\n pass", head): # a bare header (maybe with a trailing comment), or a one-liner with its body+ try:+ node = ast.parse(attempt).body[0]+ break+ except SyntaxError:+ continue+ else:pytest.fail(f"{head!r} is not a python loop header")assert isinstance(node, ast.For), headloops.append(node)@@ -143,37 +129,89 @@ def _bpy_ctx(tmp_ws, settings, *, agent=None, agent_id="fake:x", services=None):plan_obj = small_scene(BPY)spec = make_spec(Track.SCENE, BPY)ctx = _ctx(tmp_ws, settings, spec, plan_obj, agent_id=agent_id, services=services, agent=agent)- ctx.cookbook_text = language_text(BPY, "cookbook.md")ctx.extra["asset_api"] = asset_api_summary(plan_obj, {}, language=BPY)return ctx, plan_obj+def test_the_bpy_skeleton_is_an_interface_stub_without_a_landform(tmp_ws, settings) -> None:+ """The env stub hands the plan over as data and a PLACEHOLDER that builds; the landform is the+ author's (the stub used to be a level pad of the bounds' half-span + 15 m with fbm hills beyond,+ a mossy ground, a fog box and — for an interior — a room shell with one ceiling light: 30/30+ iteration-0 scenes kept its shape). A zone stub is the interface and a TODO naming the plan's+ contents — no grid of positions, no "keep them inside the bbox" (owner, 2026-10-15)."""+ from codeverse3d.languages.scene_blender import lint, write_skeleton++ ctx, plan_obj = _bpy_ctx(tmp_ws, settings)+ write_skeleton(tmp_ws, plan_obj)+ env = (tmp_ws.src / "env.py").read_text()+ for landform in ("FLAT_RADIUS", "make_height_at", "room_shell(", "area_light(", "4A5A3A", "noise_scale", "40.0)"):+ assert landform not in env, landform+ assert "def height_at(x, y):" in env and "def build_env(ctx):" in env and "PLACEHOLDER" in env+ assert "not the edge of the world" in env and "OPTIONAL toolbox" in env and "no_fog" in env+ span = max(plan_obj.bounds.extents[0], plan_obj.bounds.extents[2])+ assert f"GROUND_SIZE = {span * 3.0:.1f}" in env and "INTERIOR = False" in env+ quay = (tmp_ws.src / "zones" / "quay.py").read_text()+ assert "def build(ctx):" in quay and "return ctx.collection" in quay and "TODO" in quay+ assert "place(" not in quay and "from lib" not in quay and "inside the bbox" not in quay+ assert "continue past the bbox" in quay and "scene_placement" in quay+ for content in plan_obj.zones[0].contents:+ assert f"- {content}:" in quay, content+ bollard = (tmp_ws.src / "assets" / "bollard.py").read_text()+ assert "def build_bollard(ctx, variant=0):" in bollard and "PLACEHOLDER" in bollard and "optional" in bollard+ assert "one mesh per material" not in bollard+ rep = lint(tmp_ws)+ assert rep.passed and not [f for f in rep.findings if f.severity.value != "info"], [(f.target, f.message) for f in rep.findings]+ # an interior plan: the room box is DATA; nothing instantiates an enclosure or a ceiling light+ inside = Workspace(tmp_ws.root.parent / "inside")+ write_skeleton(inside, plan_obj.model_copy(update={"interior": True, "glazed": True}))+ env = (inside.src / "env.py").read_text()+ assert "INTERIOR = True" in env and "GLAZED = True" in env and "room_shell(" not in env and "CeilingLight" not in env++def test_the_bpy_templates_render_with_the_plan_in_the_z_up_frame(tmp_ws, settings) -> None:"""The plan stays Y-up (D12); every number the bpy author reads is converted: the harbour'sbounds centre (0, 5, 0) prints as (0, 0, 5), the Quay zone (-20, 1.2, 0) / 40 × 3 × 60 as- (-20, 0, 1.2) / 40 × 60 × 3, a camera at (45, 18, 55) as (45, -55, 18)."""+ (-20, 0, 1.2) / 40 × 60 × 3, a camera at (38, 4, -30) as (38, 30, 4)."""ctx, plan_obj = _bpy_ctx(tmp_ws, settings)st = SceneTrack(services=ctx.services)t = scene_templates(BPY)quay = plan_obj.zones[0]- env = render(t.env, **st._ctx(ctx, recipes=cookbook_sections(ctx, ENV_RECIPES)))+ env = render(t.env, **st._ctx(ctx))assert "write `src/env.py`" in env and "centre (0.000, 0.000, 5.000) m" in env and "build_env(ctx)" in env- assert "# role: env" in env # the recipes travel inside the brief- zone = render(t.zone, **st._ctx(ctx, recipes="", zone_name=quay.name, zone_description=quay.description,+ assert "# role: env" not in env and "copy these numbers" not in env # no recipes travel in the brief (2026-10-15)+ zone = render(t.zone, **st._ctx(ctx, zone_name=quay.name, zone_description=quay.description,zone_bbox=plan_bbox_line(quay.bbox, BPY), zone_contents=quay.contents, zone_file="src/zones/quay.py",neighbours=[], layout=layout_block({"zone": "Quay", "placements": [{"asset": "Bollard", "count": 2, "cluster": [3.0, -4.0], "spread_m": 0.5}]}, language=BPY)))assert "centre (-20.000, 0.000, 1.200) m, extents (40.000, 60.000, 3.000) m" in zone- assert "position (45.0, -55.0, 18.0)" in zone and "2x Bollard around (3.0, 4.0)" in zone+ assert "position (38.0, 30.0, 4.0)" in zone and "2x Bollard around (3.0, 4.0)" in zoneassert "ctx.assets['bollard']" in zone and "def build(ctx)" in zone and "import {" not in zone- refine = render(t.refine, **st._ctx(ctx, recipes=refine_recipes(ctx, ["src/env.py"]), round_index=1, tasks=["t"], targets=["Quay"],+ refine = render(t.refine, **st._ctx(ctx, round_index=1, tasks=["t"], targets=["Quay"],files=["src/env.py"], edit_only_these=False, judge_summary="j", current_files={}))- assert "src/env.py" in refine and "src/scene.py" in refine and "Horizon: the world must not end" in refine+ assert "src/env.py" in refine and "src/scene.py" in refine and "# role: env" not in refine# the three.js templates still print the plan's own numbers (the identity conversion): byte-identical promptsassert "centre (0.000, 5.000, 0.000) m" in plan_bbox_line(plan_obj.bounds, Language.SCENE_THREEJS)assert SCENE_TEMPLATES[Language.SCENE_THREEJS].env == "tracks/scene_env.j2"+def test_a_multi_zone_session_reads_the_shared_tail_once(tmp_ws, settings) -> None:+ """Two zones in one session: a per-zone head for each (bbox, contents, layout, neighbours) and the+ shared tail — cameras, assets, the contract, the measured list, the output rules — ONCE, after the+ last head. A two-zone prompt used to carry the contract and the catalog twice, with "HOW TO+ FINISH" landing between zone 1 and zone 2 (the copyability review of 2026-10-15)."""+ ctx, plan_obj = _bpy_ctx(tmp_ws, settings)+ st = SceneTrack(services=ctx.services)+ task = st._zone_task(ctx, list(plan_obj.zones))+ prompt = task.prompt+ for z in plan_obj.zones:+ assert f"# Zone `{z.name}` of" in prompt and f"write `src/zones/{z.name.lower()}.py`" in prompt+ assert prompt.count("## Contract") == 1 and prompt.count("## Output") == 1 and prompt.count("## Assets available") == 1+ assert prompt.index("# Zone `Water` of") < prompt.index("## Contract") # every head before the one tail+ assert prompt.rstrip().endswith("OUT") or "## Output" in prompt[-2000:]+ single = st._zone_task(ctx, [plan_obj.zones[0]]).prompt+ assert single.count("## Contract") == 1 and "## Output" in single++def test_layout_block_prints_ground_points_in_the_authoring_frame() -> None:lay = ZoneLayout(zone="Quay", placements=[{"asset": "Bollard", "count": 3, "cluster": (3.0, -4.0), "spread_m": 1.0},{"asset": "Crate", "count": 2, "cluster": (3.0, 0.0), "spread_m": 1.0}],@@ -341,7 +379,7 @@ def test_variant_shims_and_catalog_rows_per_language(tmp_ws, monkeypatch) -> Non# --------------------------------------------------------------------------- track plumbing-def test_env_file_recipes_and_console_targets_follow_the_runtime(tmp_ws, settings) -> None:+def test_env_file_and_console_targets_follow_the_runtime(tmp_ws, settings) -> None:ctx, plan_obj = _bpy_ctx(tmp_ws, settings)assert env_file(ctx) == ENV_FILES[BPY] == "src/env.py" and ctx.runtime.env_file == "src/env.py"ctx.runtime = SimpleNamespace(zone_file=ctx.runtime.zone_file) # a runtime without the attribute: the typed table@@ -349,11 +387,6 @@ def test_env_file_recipes_and_console_targets_follow_the_runtime(tmp_ws, settingassert _guess_target("Traceback: src/env.py:12 ValueError", ctx) == "env"assert _guess_target("KeyError in src/scene.py", ctx) == "composition"assert _guess_target("zone quay raised KeyError", ctx) == "Quay" and _guess_target("nothing named", ctx) == "overall"- env_only = refine_recipes(ctx, ["src/env.py"])- zones_only = refine_recipes(ctx, ["src/zones/quay.py"])- assert "# role: env" in env_only and "tree_mesh" not in env_only- assert "tree_mesh" in zones_only and "# role: env" not in zones_only- assert refine_recipes(ctx, ["src/assets/bollard.py"]) == zones_only # neither env nor a zone: the zone chaptersclass _TransientOnceAgent(FakeAgent):diff --git a/harness/tests/scene_gates/test_frame_metrics.py b/harness/tests/scene_gates/test_frame_metrics.pyindex 4daa2c37..30d0a3c5 100644--- a/harness/tests/scene_gates/test_frame_metrics.py+++ b/harness/tests/scene_gates/test_frame_metrics.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom codeverse3d.contracts.artifacts import Severityfrom codeverse3d.judges.rubrics import apply_caps, load_rubricfrom codeverse3d.spatial.frame_metrics import (+ HINTS,frame_findings,frame_summary_text,)@@ -106,6 +107,34 @@ def test_content_small_roles():assert rep.findings[0].data["role"] == "establishing" and not rep.passed+def test_no_hint_prescribes_one_camera_or_light_construction():+ """2026-10-15 (owner's rule): a fix hint states the measured requirement and leaves the construction+ open. The old hints were the diorama shot — stand at 1.2x the content span, 6-20 m up, lookAt the+ bounds centre, fill the bounds — and the library's rig as THE light; every refine round read them."""+ rep = frame_findings(_metrics(+ _chk("Establishing", content_frac=0.12, sky_frac=0.5, ground_frac=0.38),+ _chk("Ant", eye_height_m=3.2, ground_below_m=0.06, ground_below_name="SnowTerrain"),+ _chk("Drone", eye_height_m=98.0, ground_below_m=95.0, ground_below_name="Ground"),+ _chk("Flat", modal_frac=0.95), _chk("Dark", mean_lum=0.05, dark_frac=0.6), _chk("Blown", blown_frac=0.3),+ _chk("overview_top", "orbit", content_frac=0.03)))+ hints = {(f.data["kind"], f.target): f.fix_hint for f in rep.findings}+ text = " ".join(hints.values())+ for recipe in ("1.2 ×", "1.2 x", "6–20 m", "6-20 m", "fill the bounds", "zone centre", "content centre", "looking down 15",+ "densify", "+ 1.6 (eye level)", "do not add a second sun"):+ assert recipe not in text, recipe+ # what each hint states instead: the measurement, and the brief's viewpoint as the construction's owner+ assert "what the brief says this viewpoint looks at" in hints[("content_small", "Establishing")]+ assert ">= 0.3 m above the surface beneath it" in hints[("camera_low", "Ant")] and "balcony" in hints[("camera_low", "Ant")]+ assert "below 80 m" in hints[("camera_high", "Drone")] and "tower top" in hints[("camera_high", "Drone")]+ assert "mean luminance >= 0.12" in hints[("dark_frame", "Dark")] and "one way" in hints[("dark_frame", "Dark")]+ assert "20 % pure-white" in hints[("blown_frame", "Blown")] and "typically" in hints[("blown_frame", "Blown")]+ assert "aim the camera at its subject" in hints[("flat_frame", "Flat")]+ assert "zone_empty / missing_content" in hints[("content_small", "overview_top")]+ # both languages carry the same set of hints, worded for their API+ assert set(HINTS["scene_blender"]) == set(HINTS["scene_threejs"]) and "high" in HINTS["scene_threejs"]+ assert "ctx.height_at" in HINTS["scene_blender"]["low"] and "80 m" in HINTS["scene_blender"]["high"]++def test_scene_rubric_caps_fire_on_frame_kinds():rubric = load_rubric("scene_v2")rep = frame_findings(_metrics(_chk("Establishing", mean_lum=0.07, dark_frac=0.41, content_frac=0.1)))diff --git a/harness/tests/scene_gates/test_frame_motion.py b/harness/tests/scene_gates/test_frame_motion.pyindex a297bf71..bd6d6ef8 100644--- a/harness/tests/scene_gates/test_frame_motion.py+++ b/harness/tests/scene_gates/test_frame_motion.py@@ -100,7 +100,8 @@ def test_frame_gate_reports_motion_as_info_and_freeze_as_error(tmp_path: Path) -rep2 = frame_findings(frozen)f = next(f for f in rep2.findings if f.data["kind"] == "no_motion")assert f.severity is Severity.ERROR and not rep2.passed- assert "amplitude" in f.fix_hint and "0.10" in f.fix_hint+ # the hint states the measure and the hook, not a list of required motions (D106)+ assert "0.4 %" in f.fix_hint and "userData.update(t, dt)" in f.fix_hint and "must" not in f.fix_hintdef test_stored_motion_ignores_junk() -> None:diff --git a/harness/tests/scene_gates/test_live_frames.py b/harness/tests/scene_gates/test_live_frames.pyindex 34daf81b..b2002e17 100644--- a/harness/tests/scene_gates/test_live_frames.py+++ b/harness/tests/scene_gates/test_live_frames.py@@ -35,11 +35,11 @@ def _darken(ws: Workspace) -> None:# the env map, which lights metals and glass on its owntext = text.replace(" scene.environment = rig.envTex;"," scene.environment = null; sun.intensity = 0.05; hemi.intensity = 0.02; hemi.color.set(0x101018); hemi.groundColor.set(0x000000);")- # the world shell's sky is unlit (D71): black it out too, or half the frame stays bright sky- text = text.replace("worldShell({ rand: mulberry32(SEED + 1), mood: MOOD,",- "worldShell({ rand: mulberry32(SEED + 1), mood: 'night', zenith: 0x000000, horizon: 0x000000, ridgeColor: 0x000000,")- text = text.replace("scene.background = new THREE.Color(shell.fog.color)", "scene.background = new THREE.Color(0x000000)")- assert "0.05" in text and text.count("0x000000") >= 4+ # the placeholder starter's sky is its fog colour (D106: no world shell): black both out, or+ # half the frame stays bright sky+ text = text.replace("scene.fog = new THREE.Fog(0xbfc6cc,", "scene.fog = new THREE.Fog(0x000000,")+ text = text.replace("scene.background = new THREE.Color(scene.fog.color)", "scene.background = new THREE.Color(0x000000)")+ assert "0.05" in text and text.count("0x000000") >= 3env.write_text(text)@@ -114,6 +114,6 @@ def test_dark_variant_raises_dark_frame_errors(starter_ws: Workspace):assert not gate.passeddark = [f for f in gate.findings if f.data.get("kind") == "dark_frame"]assert dark and all(f.severity == "error" for f in dark)- assert dark[0].target == "overview" and "sunRig(" in dark[0].fix_hint and "NOT black" in dark[0].fix_hint+ assert dark[0].target == "overview" and "0.12" in dark[0].fix_hint and "35 %" in dark[0].fix_hint # the measure, not a rig recipe (D106)assert dark[0].data["mean_lum"] < 0.12 or dark[0].data["dark_frac"] > 0.35diff --git a/harness/tests/scene_gates/test_placement.py b/harness/tests/scene_gates/test_placement.pyindex d16aa4bf..fc5be437 100644--- a/harness/tests/scene_gates/test_placement.py+++ b/harness/tests/scene_gates/test_placement.py@@ -215,14 +215,21 @@ def _contract_plan() -> ScenePlan:def test_contract_checks_fire_on_atmosphere_contents_scale_and_bounds():- far = _row("FarCrate")+ far = _row("FarLantern") # a PLANNED content, 100 m out: measured against the boundsfar["bbox"] = {"min": [100, 0, 100], "max": [101, 1, 101], "size": [1, 1, 1]}+ outlier = _row("OutlyingBarn") # not in the plan: the place continuing — never reported+ outlier["bbox"] = {"min": [100, 0, -100], "max": [108, 6, -92], "size": [8, 6, 8]}census = {"fog": None, "background": None,- "placement": _table(_row("Lantern", h=3.0), far)} # lantern 5x the planned 0.6 m+ "placement": _table(_row("Lantern", h=3.0), far, outlier)} # lantern 5x the planned 0.6 mrep = placement_gate_safe(census, plan=_contract_plan())kinds = {f.data.get("kind") for f in rep.findings}assert {"no_fog", "no_background", "missing_content", "zone_empty", "scale", "out_of_bounds"} <= kindsassert not rep.passed+ # out_of_bounds (2026-10-15): a WARN on planned contents only, past a generous margin (max(5 m, 10 % of the+ # span)); scenery past the bounds is what the world_edge check asks for and is free+ oob = [f for f in rep.findings if f.data.get("kind") == "out_of_bounds"]+ assert [(f.target, f.severity, f.data["planned"], f.data["margin_m"]) for f in oob] == [("Yard/FarLantern", Severity.WARN, "lantern", 5.0)]+ assert "planned content 'lantern'" in oob[0].message and "scenery that continues the place past the bounds is free" in oob[0].fix_hintmissing = next(f for f in rep.findings if f.data.get("kind") == "missing_content")assert missing.target == "Yard" and "Bench" in missing.messageempty = next(f for f in rep.findings if f.data.get("kind") == "zone_empty")@@ -304,41 +311,56 @@ def test_interpenetration_bands_are_the_strict_ones():assert {f.target: f.severity for f in _by_kind(lenient, "interpenetration")} == {"Yard/Bench": Severity.WARN}-def test_density_gate_fires_on_a_zone_far_under_its_layout_budget():+def test_the_layout_budget_is_a_note_not_a_gate():+ """2026-10-15 (owner's rule): the L2 layout's prop / ground-cover counts were never the brief's, so a+ zone under them is an INFO line (``density_note``), never the ``underdressed`` ERROR that enforced the+ planner's dressing bands as a requirement. The counts a brief states are acceptance items."""layouts = {"Yard": {"placements": [{"asset": "Lantern", "count": 6}],"mid_props": 20, "small_props": 40, "ground_cover": 400},- "House": {"placements": [], "mid_props": 2}} # budget 2 < threshold: ignored+ "House": {"placements": [], "mid_props": 2}}census = {"fog": {"type": "Fog"}, "background": "#aabbcc","groups": [{"name": "Yard", "instances": 30}, {"name": "House", "instances": 1}],- "placement": _table(_row("Lantern", h=0.6))}- rep = placement_gate_safe(census, plan=_contract_plan(), layouts=layouts)- under = [f for f in rep.findings if f.data.get("kind") == "underdressed"]- assert len(under) == 1 and under[0].target == "Yard"- assert "466" in under[0].message and "~30" in under[0].message- # the same zone with the budget met is quiet- census["groups"][0]["instances"] = 240 # >= half of 466+ "placement": _table(_row("Lantern", h=0.6), _row("Bench", h=0.9), _row("BenchB", zone="House", h=0.9))}rep = placement_gate_safe(census, plan=_contract_plan(), layouts=layouts)assert not [f for f in rep.findings if f.data.get("kind") == "underdressed"]+ notes = {f.target: f for f in rep.findings if f.data.get("kind") == "density_note"}+ assert set(notes) == {"Yard", "House"} and all(f.severity == Severity.INFO for f in notes.values())+ assert "466" in notes["Yard"].message and "~30" in notes["Yard"].message and "not a requirement" in notes["Yard"].message+ assert rep.passed, "a note never fails the gate"+ # a zone at or over its layout count says nothing+ census["groups"][0]["instances"] = 466+ rep = placement_gate_safe(census, plan=_contract_plan(), layouts=layouts)+ assert [f.target for f in rep.findings if f.data.get("kind") == "density_note"] == ["House"]-def test_no_backdrop_fires_outdoors_and_stays_quiet_with_a_ring_or_indoors():+def test_world_edge_is_a_warn_note_outdoors_and_quiet_when_the_place_continues_or_indoors():+ """Until 2026-10-15 this was the ``no_backdrop`` ERROR whose hint prescribed a silhouette ring of+ 24-40 pieces. The measurement stands (something >= 2 m tall past 1.25x the half-extent); the finding+ is a WARN that states the requirement, and neither its name nor its hint names a ring."""base = {"fog": {"type": "Fog"}, "background": "#aabbcc","placement": _table(_row("Lantern_3", h=0.6), _row("Bench", h=0.9),_row("BenchB", zone="House", h=0.9))}near_only = dict(base, groups=[{"name": "Yard", "kind": "content", "bbox": {"min": [-10, 0, -10], "max": [10, 4, 10]}}])rep = placement_gate_safe(near_only, plan=_contract_plan(), layouts=None)- hits = [f for f in rep.findings if f.data.get("kind") == "no_backdrop"]- assert len(hits) == 1 and hits[0].target == "env" and "25 m" in hits[0].message- # a silhouette ring past 1.25x the half-extent quiets it- ringed = dict(base, groups=near_only["groups"] + [- {"name": "BackdropHills", "kind": "content", "bbox": {"min": [-40, 0, -40], "max": [40, 5, 40]}}])- rep = placement_gate_safe(ringed, plan=_contract_plan(), layouts=None)+ hits = [f for f in rep.findings if f.data.get("kind") == "world_edge"]+ assert len(hits) == 1 and hits[0].target == "env" and hits[0].severity == Severity.WARN+ assert "25 m" in hits[0].message and hits[0].data == {"kind": "world_edge", "reach_m": 10.0, "need_m": 25.0}assert not [f for f in rep.findings if f.data.get("kind") == "no_backdrop"]+ assert rep.passed, "a WARN-level note; the ERROR that routed a ring into refine is gone"+ text = (hits[0].message + " " + hits[0].fix_hint).lower()+ assert "ring" not in text.replace("stamped_ring", "") and "24" not in text and "silhouette" not in text+ for option in ("more of the same terrain", "rest of the street", "treeline", "water to the horizon", "a wall", "25 m"):+ assert option in hits[0].fix_hint, option+ # the place continuing past 1.25x the half-extent — in ANY form (farmland here) — quiets it+ continued = dict(base, groups=near_only["groups"] + [+ {"name": "FarFields", "kind": "content", "bbox": {"min": [-40, 0, -40], "max": [40, 5, 40]}}])+ rep = placement_gate_safe(continued, plan=_contract_plan(), layouts=None)+ assert not [f for f in rep.findings if f.data.get("kind") == "world_edge"]# an interior never asks for oneindoor = _contract_plan().model_copy(update={"setting": "a candlelit library interior"})rep = placement_gate_safe(near_only, plan=indoor, layouts=None)- assert not [f for f in rep.findings if f.data.get("kind") == "no_backdrop"]+ assert not [f for f in rep.findings if f.data.get("kind") == "world_edge"]def test_a_group_or_row_with_a_null_box_is_skipped_not_a_crash():@@ -350,7 +372,7 @@ def test_a_group_or_row_with_a_null_box_is_skipped_not_a_crash():{"name": "Yard", "kind": "content", "bbox": {"min": [-10, 0, -10], "max": [10, 4, 10]}}]}rep = placement_gate_safe(census, plan=_contract_plan())kinds = {f.data.get("kind") for f in rep.findings}- assert {"no_fog", "scale", "no_backdrop"} <= kinds # every check still ran around the null box+ assert {"no_fog", "scale", "world_edge"} <= kinds # every check still ran around the null boxassert not [f for f in rep.findings if "failed" in f.message.lower()]@@ -364,6 +386,9 @@ def test_a_ring_of_identical_copies_round_the_world_is_warned_but_not_a_rotunda(hits = [f for f in placement_gate_safe(census, plan=plan).findings if f.data.get("kind") == "stamped_ring"]assert len(hits) == 1 and hits[0].severity == Severity.WARN and "FarShore/FarPeaks: 16 near-identical copies" in hits[0].messageassert "36 m ring" in hits[0].message and "silhouettes" in hits[0].fix_hint+ # the hint states the measurement and leaves the closure open: no library landform, no ring to vary+ assert ">= 8 copies have radius spread <= 8%" in hits[0].fix_hint and "open water" in hits[0].fix_hint+ assert "worldShell" not in hits[0].fix_hint and "makeOutskirts" not in hits[0].fix_hint and "vary them" not in hits[0].fix_hintcensus["groups"][0]["stamps"] = [dict(ring, size_cv=0.15)] # loop 24: a 15 % size jitter is still a stampassert [f for f in placement_gate_safe(census, plan=plan).findings if f.data.get("kind") == "stamped_ring"]census["groups"][0]["stamps"] = [dict(ring, size_cv=0.3, radius_cv=0.2)] # varied: a real skyline@@ -445,7 +470,7 @@ def test_cantilevered_rests_on_one_of_four_columns():def test_every_asset_and_pair_finding_carries_its_box():"""``data.bbox`` = GLB-frame centre + size from the row: the judge's contact crops aim at it."""- far = _row("FarCrate")+ far = _row("FarLantern") # planned content (Lantern), 100 m outfar["bbox"] = {"min": [100, 0, 100], "max": [101, 1, 101], "size": [1, 1, 1]}census = {"fog": {"type": "Fog"}, "background": "#aabbcc", "placement": _table(_row("Lantern", gap=0.3, h=3.0), _row("Cup", gap=0.03, support="Table"), _row("Bench", sunk=0.25, into="Terrain"),diff --git a/harness/tests/scene_gates/test_scene_textures_stage.py b/harness/tests/scene_gates/test_scene_textures_stage.pyindex fecf4f65..09210513 100644--- a/harness/tests/scene_gates/test_scene_textures_stage.py+++ b/harness/tests/scene_gates/test_scene_textures_stage.py@@ -28,10 +28,11 @@ def _render(name: str, **extra):@pytest.mark.parametrize("template", ["scene_env.j2", "scene_zone.j2"])-def test_the_pack_has_the_last_word_over_the_recipes(template: str):- """The cookbook's ground chapter is long and specific; whichever comes last wins."""+def test_the_pack_renders_and_no_recipe_block_competes_with_it(template: str):+ """The inlined cookbook chapters that used to sit above the pack are gone (D106): the pack+ is the only material block, and a stray ``recipes`` variable renders nothing."""out = _render(template, textures="TEXTURE_BLOCK_MARKER", recipes="RECIPE_MARKER")- assert out.index("RECIPE_MARKER") < out.index("TEXTURE_BLOCK_MARKER")+ assert "TEXTURE_BLOCK_MARKER" in out and "RECIPE_MARKER" not in out and "# Recipes" not in out@pytest.mark.parametrize("template", ["scene_env.j2", "scene_zone.j2"])diff --git a/harness/tests/scene_prompts/test_bpy_templates.py b/harness/tests/scene_prompts/test_bpy_templates.pyindex 57653cb3..48ee86e2 100644--- a/harness/tests/scene_prompts/test_bpy_templates.py+++ b/harness/tests/scene_prompts/test_bpy_templates.py@@ -10,7 +10,7 @@ from codeverse3d.languages.wrappers import run_bpy_scenefrom codeverse3d.prompts import PROMPTS_DIR, load_text, renderBASE = dict(title="t", spec_prompt="p", setting="s", mood="m", bounds="b", environment="e", frame_doc="", contract="",- zones_table="", cameras="", effects="", animation="", asset_api="", textures="", recipes="", constraints_text="",+ zones_table="", cameras="", effects="", animation="", asset_api="", textures="", constraints_text="",references="", skills="", tool_cards="", zone_name="Z", zone_description="d", zone_bbox="bb", zone_contents=[],zone_file="src/zones/z.py", neighbours=[], layout="", env_file="src/env.py", entry_file="src/scene.py",single_shot=False, output_format="OUT", effects_catalog="")@@ -31,14 +31,16 @@ def test_the_bpy_templates_teach_the_hooks_the_wrapper_calls() -> None:assert "userData.update" not in text and "createScene" not in text and "THREE" not in text-def test_the_catalog_reaches_env_zone_and_refine_but_not_the_asset_sheet() -> None:- """A bpy asset session gets the rows its sheet names (``library_rows``), never the whole catalog —- exactly the three.js split (tests/scene_runtime/test_skeleton.py)."""+def test_the_catalog_reaches_env_and_zone_but_not_the_asset_sheet_or_the_refine() -> None:+ """A bpy asset session gets the rows its sheet names (``library_rows``), never the whole catalog;+ a refine session edits one file with src/lib in the workspace and the skills routed, so it carries+ none either — exactly the three.js split (tests/scene_runtime/test_skeleton.py)."""tpl = PROMPTS_DIR / "tracks"- for name in ("scene_env_bpy.j2", "scene_zone_bpy.j2", "scene_refine_bpy.j2"):+ for name in ("scene_env_bpy.j2", "scene_zone_bpy.j2"):assert "effects_catalog" in (tpl / name).read_text(), name+ assert "effects_catalog" not in (tpl / "scene_refine_bpy.j2").read_text()asset = (tpl / "scene_asset_bpy.j2").read_text()- assert "effects_catalog" not in asset and "library_rows" in asset+ assert "effects_catalog" not in asset and "library_rows" in asset and "asset_contract" in assetdef test_the_bpy_env_and_zone_briefs_hand_the_enclosure_to_env_for_an_interior() -> None:@@ -46,24 +48,12 @@ def test_the_bpy_env_and_zone_briefs_hand_the_enclosure_to_env_for_an_interior()env_in = render("tracks/scene_env_bpy.j2", **BASE, interior=True, glazed=False)env_glass = render("tracks/scene_env_bpy.j2", **BASE, interior=True, glazed=True)env_out = render("tracks/scene_env_bpy.j2", **BASE, interior=False, glazed=False)- assert "the enclosure is yours" in env_in and "room_shell" in env_in and "openings" in env_in+ assert "This is an INTERIOR" in env_in and "room_shell" in env_in and "openings" in env_inassert "GLASS HOUSE" in env_glass and "glazed=True" in env_glass- assert "enclosure is yours" not in env_out+ assert "INTERIOR" not in env_out and "GLASS HOUSE" not in env_out+ # the zone brief names env.py as the enclosure's owner only for an interior (the wording is the prompt's;+ # the ownership is the contract: the wrapper builds env first, zones link into their own collection)zone_in = render("tracks/scene_zone_bpy.j2", **BASE, interior=True)zone_out = render("tracks/scene_zone_bpy.j2", **BASE, interior=False)- assert "never build walls or a roof" in zone_in and "flush against the inner face" in zone_in- assert "never build walls" not in zone_out---def test_the_bpy_refine_brief_names_the_cookbook_chapters_the_stages_inline() -> None:- """The defect → chapter table must point at chapters that exist (``cookbook_sections`` finds them- by title), or a refine session is sent to a recipe that is not in its prompt."""- from codeverse3d.prompts.sections import find_section, split_sections- from codeverse3d.tracks.scene import ENV_RECIPES, ZONE_RECIPES-- sections = split_sections(load_text("scene_blender/cookbook.md"))- refine = load_text("tracks/scene_refine_bpy.j2")- for title in (*ENV_RECIPES, *ZONE_RECIPES, "Placement self-check", "Materials: Principled recipes", "Water", "Traps"):- assert f'"{title.split(":")[0]}' in refine, title # quoted as the chapter's name (its head before any colon)- found = find_section(sections, title)- assert found is not None and title.lower() in found.title.lower(), (title, found and found.title)+ assert "INTERIOR" in zone_in and "`env.py`'s" in zone_in+ assert "INTERIOR" not in zone_outdiff --git a/harness/tests/scene_prompts/test_quality_teaching.py b/harness/tests/scene_prompts/test_quality_teaching.pyindex 91b66bff..f0756876 100644--- a/harness/tests/scene_prompts/test_quality_teaching.py+++ b/harness/tests/scene_prompts/test_quality_teaching.py@@ -19,32 +19,32 @@ def test_scene_rubric_craft_defects_inform_and_cannot_zero_a_scene() -> None:assert 0.0 < d.penalty <= 0.05 and d.cap is None, did# the five craft items together take at most 0.20: they inform, they cannot sink a sceneassert sum(r.defect(did).penalty for did in COMPOSITION_DEFECTS) == pytest.approx(0.18)- # scene_v2 (2026-10-14): the whole checklist sums to 1.02 (was 0.60 under v1's 0.62 bound). The- # 0.42 that moved is the placement / detail items — floating 0.10, sunken 0.08, interpenetration+ # scene_v2 (2026-10-14): the whole checklist sums past 1.0 (was 0.60 under v1's 0.62 bound). The+ # weight that moved is the placement / detail items — floating 0.10, sunken 0.08, interpenetration# 0.08, wrong_scale 0.06, missing_planned_element 0.06, hero_misplaced 0.06, hard-edged particles# 0.04 — the same weights the object rubric gives floating_part / interpenetration, and each of# the four measured ones also caps (0.60-0.75) so the penalty only matters under the cap. A# scene with EVERY item present is a wrong, unlit, floating, clipping world: zero is its score.+ # The exact figure is tests/judges/test_scene_judge.py's (the judge lane adds items such as+ # diorama_look, 2026-10-15); this test keeps the invariant.total = sum(d.penalty for d in r.defects)- assert total == pytest.approx(1.02) and total <= 1.05+ assert 1.0 <= total <= 1.10, totalassert sum(d.penalty for d in load_rubric("scene_v1").defects) <= 0.62 # the frozen replay rubric-def test_cookbook_sections_inlines_whole_chapters_and_clips_safely(tmp_path) -> None:- from types import SimpleNamespace+def test_no_scene_stage_inlines_cookbook_recipes() -> None:+ """Owner, 2026-10-15: the same four ENV and six ZONE cookbook chapters used to be inlined into+ every env / zone / refine session whatever the brief ("copy these numbers and snippets"), and+ the 60 iteration-0 scenes executed them verbatim. The track has no recipe tables, no recipe+ inliner and passes no ``recipes`` variable; the scene templates render without one."""+ import inspect- from codeverse3d.tracks.prompting import cookbook_sections- from codeverse3d.tracks.scene import ZONE_RECIPES+ from codeverse3d.tracks import prompting, scene- ctx = SimpleNamespace(cookbook_text=load_text("scene_threejs/cookbook.md"))- text = cookbook_sections(ctx, ZONE_RECIPES)- assert all(f"## {t.split(':')[0]}" in text or t.split(":")[0] in text for t in ZONE_RECIPES)- for token in ("setColorAt", "cameraMask", "foreground frame", "±0.10–0.20 rad"):- assert token in text, token- assert len(text) > 12_000- assert cookbook_sections(ctx, ZONE_RECIPES, max_chars=500).rstrip().endswith("cookbook.md]")- assert cookbook_sections(SimpleNamespace(cookbook_text=""), ZONE_RECIPES) == ""- assert cookbook_sections(ctx, ["zzz qqq"]) == "" # no match → nothing, never junk+ for gone in ("ENV_RECIPES", "ZONE_RECIPES", "ZONE_RECIPES_MAX_CHARS", "refine_recipes"):+ assert not hasattr(scene, gone), gone+ assert not hasattr(prompting, "cookbook_sections")+ assert "recipes=" not in inspect.getsource(scene)def test_the_env_and_zone_briefs_hand_the_enclosure_to_env_for_an_interior() -> None:@@ -52,24 +52,26 @@ def test_the_env_and_zone_briefs_hand_the_enclosure_to_env_for_an_interior() ->from codeverse3d.prompts import renderbase = dict(title="t", spec_prompt="p", setting="s", mood="m", bounds="b", environment="e", frame_doc="", contract="",- zones_table="", cameras="", effects="", animation="", asset_api="", textures="", recipes="", constraints_text="",+ zones_table="", cameras="", effects="", animation="", asset_api="", textures="", constraints_text="",references="", skills="", tool_cards="", zone_name="Z", zone_description="d", zone_bbox="bb", zone_contents=[],zone_file="src/zones/z.js", neighbours=[], layout="")- env_in = render("tracks/scene_env.j2", **base, interior=True)- env_out = render("tracks/scene_env.j2", **base, interior=False)- assert "the enclosure is yours" in env_in and "roomShell" in env_in and "openings" in env_in- assert "enclosure is yours" not in env_out+ env_in = render("tracks/scene_env.j2", **base, interior=True, glazed=False)+ env_out = render("tracks/scene_env.j2", **base, interior=False, glazed=False)+ assert "This is an INTERIOR" in env_in and "roomShell" in env_in and "openings" in env_in+ assert "INTERIOR" not in env_out+ # the zone brief names env.js as the enclosure's owner only for an interior (the wording is the prompt's;+ # the ownership is the contract: createScene builds env first, zones return their own group)zone_in = render("tracks/scene_zone.j2", **base, interior=True)zone_out = render("tracks/scene_zone.j2", **base, interior=False)- assert "never build walls or a roof" in zone_in and "flush against the inner face" in zone_in- assert "never build walls" not in zone_out+ assert "INTERIOR" in zone_in and "`env.js`'s" in zone_in+ assert "INTERIOR" not in zone_out-def test_the_practical_light_numbers_are_stated_once_and_are_the_libs() -> None:+def test_the_practical_light_numbers_live_in_the_lib_and_no_prompt_restates_them() -> None:"""Audit N41: one scene session read PointLight 0.5–2 (system prompt, skill) and 6–14 with10–16 lights (same skill), emissive 1.5–4 / ≤ 3 / 2–6, and a night rig of "moon ≤ 0.2, no- HemisphereLight" that sunRig never builds. `PRACTICAL` in environment.js owns the numbers;- the cookbook's dusk/night recipe states them once and every other text points there."""+ HemisphereLight" that sunRig never builds. `PRACTICAL` in environment.js owns the numbers+ (the cookbook that once restated them is gone, 2026-10-15); every text points there."""import refrom codeverse3d.languages.scene_threejs import lib_files@@ -79,11 +81,7 @@ def test_the_practical_light_numbers_are_stated_once_and_are_the_libs() -> None:body = re.search(r"export const PRACTICAL = Object\.freeze\(\{([^}]*)\}\)", env)assert body, "environment.js no longer exports PRACTICAL"practical = {k: float(v) for k, v in re.findall(r"(\w+): ([\d.]+)", body.group(1))}- cookbook = load_text("scene_threejs/cookbook.md")- stated = re.search(r"`emissiveIntensity` ([\d.]+), a PointLight of ([\d.]+) reaching ([\d.]+) m, decay ([\d.]+)",- cookbook)- assert stated and tuple(map(float, stated.groups())) == (- practical["emissiveIntensity"], practical["intensity"], practical["distance"], practical["decay"])+ assert {"emissiveIntensity", "intensity", "distance", "decay"} <= set(practical)others = {"system": load_text("scene_threejs/system.md"), "contract": load_text("scene_threejs/contract.md"),"lighting": (skills_dir() / "c3d-scene-lighting" / "SKILL.md").read_text(encoding="utf-8"),"materials": (skills_dir() / "c3d-scene-materials" / "SKILL.md").read_text(encoding="utf-8")}diff --git a/harness/tests/scene_runtime/lib/test_environment.py b/harness/tests/scene_runtime/lib/test_environment.pyindex a742d86b..4b285097 100644--- a/harness/tests/scene_runtime/lib/test_environment.py+++ b/harness/tests/scene_runtime/lib/test_environment.py@@ -1,6 +1,7 @@"""environment.js (91 recorded scenes import it through the starter's env.js): worldShell,makeOutskirts and the sunRig package, measured under node. A set sun (elevation < 0) is-night with a moon opposite the sun."""+night with a moon opposite the sun. The silhouette ridge and the outskirts' copses are+opt-in (2026-10-15: library defaults no longer pre-decide the backdrop)."""from __future__ import annotationsimport math@@ -79,7 +80,7 @@ _SHELL = """import * as THREE from 'three';import { worldShell } from './lib/environment.js';const rand = (() => { let s = 9; return () => (s = (s * 16807) % 2147483647) / 2147483647; })();-const env = worldShell({ rand, mood: 'day' });+const env = worldShell({ rand, mood: 'day', ridge: true });env.group.updateMatrixWorld(true);const hitsFor = (dir) => new THREE.Raycaster(new THREE.Vector3(0, 1.7, 0), dir.normalize()).intersectObject(env.group, true).map((h) => h.object.name);const outward = [];@@ -91,12 +92,24 @@ for (let i = 0; i < pos.count; i++) { if (pos.getY(i) > 3990) zenithB = cols.getlet tris = 0;env.group.traverse((o) => { if (o.isMesh) tris += o.geometry.attributes.position.count / 3; });const noRidge = worldShell({ rand, mood: 'day', ridge: false });+const bare = worldShell({ rand, mood: 'day' });const T = (rho, d) => Math.exp(-((rho * d) ** 2));const mk = () => () => 0.5;+// a directional crest: nothing to the east (0-90 deg), a full crest to the west+const shaped = worldShell({ rand, mood: 'day', ridge: true, ridgeHeight: 0.1,+ ridgeProfile: (az) => (az < 90 ? 0 : 1) }).group.getObjectByName('HorizonRidge');+const sp = shaped.geometry.attributes.position;+let eastTop = -1e9, westTop = -1e9;+for (let i = 0; i < sp.count; i++) {+ const az = (Math.atan2(sp.getZ(i), sp.getX(i)) * 180 / Math.PI + 360) % 360;+ if (az > 5 && az < 85) eastTop = Math.max(eastTop, sp.getY(i));+ if (az > 185 && az < 265) westTop = Math.max(westTop, sp.getY(i));+}const big = worldShell({ rand: mk(), mood: 'day', bounds: 1200 });const over = worldShell({ rand: mk(), mood: 'overcast', bounds: 1200 });console.log(JSON.stringify({ outward, fogHex: env.fog.color.getHexString(), zenithB, horizonB, tris: Math.round(tris),- ridgeOptional: !noRidge.group.getObjectByName('HorizonRidge'), fogIsExp2: env.fog.isFogExp2 === true,+ ridgeOptional: !noRidge.group.getObjectByName('HorizonRidge'), ridgeOffByDefault: !bare.group.getObjectByName('HorizonRidge'),+ bareOutward: hitsFor(new THREE.Vector3(1, 0, 0)), eastTop, westTop, fogIsExp2: env.fog.isFogExp2 === true,smallD: worldShell({ rand: mk(), mood: 'day', bounds: 150 }).fog.density, bareD: worldShell({ rand: mk(), mood: 'day' }).fog.density,bigFarT: T(big.fog.density, 2400), overFarT: T(over.fog.density, 2400), unclampedFarT: T(env.fog.density, 2400),explicitWins: worldShell({ rand: mk(), mood: 'day', bounds: 1200, fogDensity: 0.01 }).fog.density === 0.01 }));@@ -111,6 +124,7 @@ def shell() -> dict:def test_no_outward_ray_escapes_into_void(shell):for hits in shell["outward"]:assert "HorizonRidge" in hits and "SkyGradient" in hits, shell["outward"]+ assert "SkyGradient" in shell["bareOutward"], shell["bareOutward"] # the dome alone closes the skydef test_the_fog_matches_the_horizon_tint(shell):@@ -125,6 +139,14 @@ def test_the_shell_is_nearly_free_and_the_ridge_optional(shell):assert shell["tris"] < 2000 and shell["ridgeOptional"]+def test_the_ridge_is_opt_in_and_can_be_shaped_by_sector(shell):+ """A library default no longer rings every exterior with the same 360-degree crest: the+ ridge is off unless asked, and `ridgeProfile` makes it directional or partial."""+ assert shell["ridgeOffByDefault"]+ assert shell["eastTop"] <= 1e-6 < shell["westTop"], (shell["eastTop"], shell["westTop"])+ assert shell["westTop"] == pytest.approx(4000 * 0.1, rel=1e-6)++def test_fog_scales_with_the_world_it_wraps(shell):assert shell["smallD"] == pytest.approx(0.0018) and shell["bareD"] == pytest.approx(0.0018)assert shell["bigFarT"] >= 0.30 and shell["overFarT"] >= 0.30@@ -305,7 +327,7 @@ def test_outskirts_meets_the_scene_ground_at_its_seam():out = _measure("""import { makeOutskirts } from './lib/environment.js';const ground = (x, z) => 2.0 + 0.01 * x;-const g = makeOutskirts({ inner: 150, baseY: 0, heightAt: ground, relief: 30, seed: 9 });+const g = makeOutskirts({ inner: 150, baseY: 0, heightAt: ground, relief: 30, seed: 9, clumps: 140 });const land = g.children.find((o) => o.name === 'OutskirtsLand');const pos = land.geometry.attributes.position;let seamWorst = 0, maxR = 0, maxY = -1e9, farLift = 0, nFar = 0;@@ -323,8 +345,11 @@ let same = true, differ = false;for (let i = 0; i < a.count * 3; i++) { if (a.array[i] !== b.array[i]) same = false; if (a.array[i] !== c.array[i]) differ = true; }const reach = (o) => { const p = o.children[0].geometry.attributes.position; let r = 0;for (let i = 0; i < p.count; i++) r = Math.max(r, Math.hypot(p.getX(i), p.getZ(i))); return r; };+const bare = makeOutskirts({ inner: 100, seed: 4 });+const plain = makeOutskirts({ inner: 100, seed: 4, fields: false });console.log(JSON.stringify({ seamWorst, maxR, maxY, meanFarY: farLift / nFar, meshes: g.children.length,copseCount: copses ? copses.count : 0, patched: !!land.material.userData.astraShader, same, differ,+ bareMeshes: bare.children.length, plainPatched: !!plain.children[0].material.userData.astraShader,small: reach(makeOutskirts({ inner: 120, shellRadius: 1200, seed: 2 })), big: reach(makeOutskirts({ inner: 300, shellRadius: 9000, seed: 2 })),clamped: reach(makeOutskirts({ inner: 120, shellRadius: 1200, outer: 5000, seed: 2 })),shorter: reach(makeOutskirts({ inner: 120, shellRadius: 1200, outer: 600, seed: 2 })) }));@@ -332,6 +357,8 @@ console.log(JSON.stringify({ seamWorst, maxR, maxY, meanFarY: farLift / nFar, meassert out["seamWorst"] < 0.05, outassert 3279 <= out["maxR"] <= 3281 and out["maxY"] < 80 and out["meanFarY"] > 1.0, outassert out["meshes"] == 2 and out["copseCount"] > 50 and out["patched"], out+ assert out["bareMeshes"] == 1, "copses are opt-in (a temperate cue, not a default)"+ assert out["plainPatched"], "`fields: false` still patches the land shader (one tone, mottled)"assert out["same"] and out["differ"]assert abs(out["small"] - 984) < 1.5 and abs(out["big"] - 7380) < 2.0assert abs(out["clamped"] - 984) < 1.5 and abs(out["shorter"] - 600) < 1.5diff --git a/harness/tests/scene_runtime/lib/test_exterior_starter.py b/harness/tests/scene_runtime/lib/test_exterior_starter.pyindex 8765d126..3d6238b7 100644--- a/harness/tests/scene_runtime/lib/test_exterior_starter.py+++ b/harness/tests/scene_runtime/lib/test_exterior_starter.py@@ -1,5 +1,9 @@-"""The starter's outdoor world ships from the library (D71): terrain.ground(), worldShell()-and makeOutskirts()."""+"""The starter's env.js is the EXAMPLE scene's environment (the plan-less skeleton the live tests+build): a level plate named Ground, the library's sun rig and a fog — no landform, shell or+outskirts (the library landscape it used to ship was kept byte for byte by 29 of 30 iteration-0+scenes). A PLAN skeleton never ships it: ``_env_for_plan`` writes an interface stub with the+plan's data, a plate, and no light, sky or atmosphere — it fails the gates until the author writes+the brief's (a passing placeholder was kept for the same reason the landscape was; 2026-10-15)."""from __future__ import annotationsfrom pathlib import Path@@ -14,8 +18,8 @@ from codeverse3d.tracks.planner import plan_example_LIBS = ("environment.js", "terrain.js", "noise.js", "materials.js", "sky.js", "shader.js")-def _probe_script() -> str:- env = (STARTER_DIR / "env.js").read_text()+def _probe_script(env: str | None = None) -> str:+ env = (STARTER_DIR / "env.js").read_text() if env is None else envbody = env.replace("import * as THREE from 'three';", "").replace("export function", "function").replace("export const", "const")return f"""import * as THREE from 'three';@@ -26,33 +30,48 @@ const names = [];scene.traverse((o) => {{ if (o.name) names.push(o.name); }});const h = (x, z) => heightAt(x, z);console.log(JSON.stringify({{- names: names.filter((n) => ['Environment', 'Ground', 'WorldShell', 'SkyGradient', 'HorizonRidge', 'Outskirts', 'SunRigSun', 'SunRigFill'].includes(n)),- fogExp2: scene.fog && scene.fog.isFogExp2 === true,- bgIsFog: scene.background.getHex() === scene.fog.color.getHex(),- insideMax: Math.max(...[[0, 0], [20, 10], [-30, 25], [40, -15]].map(([x, z]) => Math.abs(h(x, z)))),- outsideSpread: Math.max(...[[70, 0], [0, -75], [60, 60]].map(([x, z]) => h(x, z))) - Math.min(...[[70, 0], [0, -75], [60, 60]].map(([x, z]) => h(x, z))),- groundTextured: !!(out.ground.material.map),+ names,+ fog: !!scene.fog,+ bgIsFog: !!scene.fog && scene.background.getHex() === scene.fog.color.getHex(),+ fogFar: scene.fog ? scene.fog.far : 0,+ lights: names.filter((n) => /Sun|Fill|Light/.test(n)).length,+ groundSize: out.ground.geometry.parameters.width,+ heights: [[0, 0], [20, 10], [-30, 25], [70, 0], [0, -75]].map(([x, z]) => h(x, z)),envMap: !!scene.environment,}}));"""-def test_the_starter_world_is_the_librarys_ground_shell_and_outskirts():+def test_the_example_env_passes_the_env_gates():got = measure(_probe_script(), _LIBS)- for n in ("Ground", "WorldShell", "SkyGradient", "HorizonRidge", "Outskirts", "SunRigSun", "SunRigFill"):+ for n in ("Environment", "Ground", "SunRigSun", "SunRigFill"):assert n in got["names"], (n, got["names"])- assert got["fogExp2"] and got["bgIsFog"] and got["groundTextured"] and got["envMap"], got- assert got["insideMax"] < 0.05, got # level where the plan's cameras were written for y ≈ 0- assert got["outsideSpread"] > 0.5, got # and rolling beyond the content radius+ for n in ("WorldShell", "SkyGradient", "HorizonRidge", "Outskirts"): # no landscape decided for the author+ assert n not in got["names"], (n, got["names"])+ assert got["fog"] and got["bgIsFog"] and got["envMap"], got # no_fog / no_background / lit PBR+ assert all(isinstance(v, (int, float)) and v == v for v in got["heights"]), got+ assert got["fogFar"] >= 2 * (got["groundSize"] / 3), got # fog_short on the plan the plate was sized for-def test_the_skeleton_fills_the_content_radius_from_the_plan_bounds():+def test_the_plan_stub_ships_a_plate_and_the_plans_light_and_nothing_that_passes():plan = ScenePlan.model_validate(plan_example(Track.SCENE))env = _env_for_plan(plan)- span = max(plan.bounds.extents[0], plan.bounds.extents[2], 40.0)- assert f"export const CONTENT_RADIUS = {int(max(20, span / 2))};" in env- assert "FOG_NEAR" not in env and "SKY_RADIUS" not in env- assert Path(STARTER_DIR / "env.js").read_text().count("export const CONTENT_RADIUS = 45;") == 1+ span = max(plan.bounds.extents[0], plan.bounds.extents[2])+ assert f"export const GROUND_SIZE = {int(span * 3)};" in env+ assert "export const SUN_AZIMUTH_DEG = 250;" in env and "export const SUN_ELEVATION_DEG = 8;" in env # the plan's, not a constant+ code = "\n".join(ln for ln in env.splitlines() if not ln.lstrip().startswith("//"))+ for word in ("CONTENT_RADIUS", "worldShell(", "makeOutskirts(", "flat:", "TUNE these", "sunRig(", "MOOD", "scene.fog =",+ "scene.background =", "scene.environment =", "Light("):+ assert word not in code, word+ assert "export function heightAt(x, z)" in env and "export function buildEnv(ctx)" in env and "ground.name = 'Ground'" in env+ # a plan that states no sun: the rig's own guess, flagged as such, never a decided light+ blank = _env_for_plan(plan.model_copy(update={"environment": "a cave; no sky"}))+ assert "export const SUN_AZIMUTH_DEG = 45;" in blank and "rig's guess" in blank and "SUN_ELEVATION_DEG = null" in blank+ got = measure(_probe_script(_env_for_plan(plan)), _LIBS)+ assert "Ground" in got["names"] and not got["fog"] and not got["envMap"] and not got["lights"], got # fails no_fog / dark_frame as shipped+ starter = Path(STARTER_DIR / "env.js").read_text()+ assert "export function heightAt(x, z)" in starter and "export function buildEnv(ctx)" in starter+ assert "export const SUN_AZIMUTH_DEG" in starterdef test_the_ground_height_is_finite_for_a_signed_zero_column():diff --git a/harness/tests/scene_runtime/lib/test_room_shell.py b/harness/tests/scene_runtime/lib/test_room_shell.pyindex e3f46600..f10ae965 100644--- a/harness/tests/scene_runtime/lib/test_room_shell.py+++ b/harness/tests/scene_runtime/lib/test_room_shell.py@@ -39,7 +39,11 @@ def test_the_shell_is_walls_and_ceiling_on_the_bounds_faces_with_openings_cut():assert got["placement"] == "free", got-def test_the_skeleton_env_carries_the_shell_only_for_an_interior_plan():+def test_the_skeleton_env_carries_the_room_box_only_for_an_interior_plan():+ """``INTERIOR`` is DATA the skeleton fills from the plan — the room box ``roomShell`` takes.+ The enclosure itself is the author's: the starter builds no shell and no outskirts (D106; it+ used to add ``roomShell(INTERIOR)`` and ``makeOutskirts`` itself, so every interior was a+ bounds-sized box)."""plan = ScenePlan.model_validate(plan_example(Track.SCENE))assert plan.interior is Falseoutdoor = _env_for_plan(plan)@@ -47,10 +51,10 @@ def test_the_skeleton_env_carries_the_shell_only_for_an_interior_plan():inside = _env_for_plan(plan.model_copy(update={"interior": True}))c, e = plan.bounds.center, plan.bounds.extentsassert f"export const INTERIOR = {{ center: [{c[0]}, {c[1]}, {c[2]}], extents: [{e[0]}, {e[1]}, {e[2]}], openings: [] }};" in inside- assert "if (INTERIOR) group.add(roomShell(INTERIOR));" in inside+ assert "roomShell(INTERIOR)" in inside and "group.add(roomShell(" not in inside # named as one way, not builtglass = _env_for_plan(plan.model_copy(update={"interior": True, "glazed": True}))assert "openings: [], glazed: true };" in glass- assert "if (!INTERIOR || INTERIOR.glazed) group.add(makeOutskirts(" in glass # the land outside is built+ assert "makeOutskirts(" not in glass_GLASS = """diff --git a/harness/tests/scene_runtime/test_assemble.py b/harness/tests/scene_runtime/test_assemble.pyindex a8b90292..c5e76363 100644--- a/harness/tests/scene_runtime/test_assemble.py+++ b/harness/tests/scene_runtime/test_assemble.py@@ -42,10 +42,10 @@ def test_cameras_from_specs_sun_side_and_order():assert [c.name for c in cams] == ["overview", "harbour_view", "market_view"]ov = cams[0]assert ov.position == (55.0, 22.0, 0.0) and ov.look_at == (10.0, 3.0, 0.0)- assert "sun side" in ov.purpose+ assert ov.purpose.startswith("fallback:") # a fitted camera is a fallback the plan did not name (D106)hv = cams[1]assert hv.position[0] > 10 and math.dist(hv.position, hv.look_at) > 10- assert cams[2].purpose == "zone Market from the sun side"+ assert cams[2].purpose.startswith("fallback: zone Market")def test_cameras_from_specs_fallback_without_zones_or_specs():diff --git a/harness/tests/scene_runtime/test_skeleton.py b/harness/tests/scene_runtime/test_skeleton.pyindex 4a06ad94..e914f03e 100644--- a/harness/tests/scene_runtime/test_skeleton.py+++ b/harness/tests/scene_runtime/test_skeleton.py@@ -26,26 +26,51 @@ def make_plan() -> ScenePlan:@needs_node-def test_plan_skeleton_writes_zone_and_asset_stubs_and_lints(ws):+def test_plan_skeleton_writes_interface_stubs_and_lints(ws):+ """The skeleton is the interface plus the plan's data: no landform, no positions, no example+ files. It used to be a finished landscape (a level disc of the bounds' radius with hills+ and a ridge beyond, kept byte for byte by 29 of 30 iteration-0 scenes), zone contents tiled+ on a grid inside each bbox under "keep everything inside the plan bbox", and a pine tree, a+ windmill and a pond shader copied in whatever the brief (owner, 2026-10-15)."""plan = make_plan()paths = write_skeleton(ws, plan)rel = {p.relative_to(ws.src).as_posix() for p in paths}- assert {"scene.js", "env.js", "zones/pier.js", "zones/fish_market.js", "assets/crate.js", "shaders/water.js"} <= rel+ assert {"scene.js", "env.js", "zones/pier.js", "zones/fish_market.js", "assets/crate.js", "lib/grass.js"} <= relassert "assets/crane.js" not in rel # blender_glb assets are loaded, not stubbed+ assert not {r for r in rel if r.startswith("shaders/") or r in ("assets/pine_tree.js", "assets/windmill.js")}, relscene = (ws.src / "scene.js").read_text()assert "export async function createScene" in sceneassert "'/assets/crane.glb'" in sceneassert "addZone(buildPier, 'Pier')" in scene and "addZone(buildFishMarket, 'FishMarket')" in sceneassert "name: 'pier_low'" in scenepier = (ws.src / "zones" / "pier.js").read_text()- assert "zone.name = 'Pier'" in pier and "buildCrate" in pier and "ctx.assets.crane" in pier+ assert "zone.name = 'Pier'" in pier and "import { buildCrate } from '../assets/crate.js';" in pier and "ctx.assets.crane" in pier+ # a TODO naming the plan's contents, no positions, no bbox wall+ assert "TODO" in pier and "- Crate:" in pier and "- Crane:" in pier and "place(" not in pier and "position.set" not in pier+ assert "inside the plan bbox" not in pier and "continue past the bbox" in pier and "scene_placement" in piercrate = (ws.src / "assets" / "crate.js").read_text()- assert "export function buildCrate" in crate+ assert "export function buildCrate" in crate and "PLACEHOLDER" in crate and "pine_tree" not in crate and "windmill" not in crateenv = (ws.src / "env.js").read_text()- assert "GROUND_SIZE = 200" in env # 80 m span * 2.5+ assert "GROUND_SIZE = 240" in env and "SHADOW_RADIUS" not in env # 80 m span × 3; no light rig to size a frustum for+ code = "\n".join(ln for ln in env.splitlines() if not ln.lstrip().startswith("//")) # the comments may NAME the lib's options+ for landform in ("CONTENT_RADIUS", "worldShell(", "makeOutskirts(", "roomShell(", "FLAT_RADIUS", "flat:",+ "sunRig(", "MOOD", "scene.fog =", "scene.environment ="): # no light, sky or fog decided either+ assert landform not in code, landform+ for mandate in ("TUNE these", "do not replace"):+ assert mandate not in env, mandate+ assert "export function heightAt" in env and "export function buildEnv" in env and "export const SUN_AZIMUTH_DEG" in env+ assert "ENV PLAN: calm sea" in env and "not the edge of the world" in env and "PLACEHOLDER" in env and "fog_short" in env+ assert "export const INTERIOR = null;" in envassert (ws.public / "assets").is_dir()rep = lint(ws)assert not rep.errors, [(f.target, f.message) for f in rep.errors]+ # an interior plan hands the room box over as DATA; the enclosure is the env author's+ inside = Workspace(ws.root.parent / "inside")+ write_skeleton(inside, plan.model_copy(update={"interior": True, "glazed": True}))+ env = (inside.src / "env.js").read_text()+ assert "export const INTERIOR = { center: [0.0, 5.0, 0.0], extents: [80.0, 20.0, 60.0], openings: [], glazed: true };" in env+ code = "\n".join(ln for ln in env.splitlines() if not ln.lstrip().startswith("//"))+ assert "roomShell(" not in code # not instantiated: one optional way, named in the comment# ------------------------------------------------------- the effect library (D51)@@ -53,7 +78,7 @@ def test_plan_skeleton_writes_zone_and_asset_stubs_and_lints(ws):def test_both_skeleton_paths_ship_the_effect_library(tmp_path):"""The library is only usable if it is IN the workspace, and plan mode is the- PRODUCTION path. It shipped `PATTERN_FILES` only, so a planned run would have+ PRODUCTION path. It once shipped the example's pattern files only, so a planned runcarried the effects catalog in its prompt with no `src/lib/` to import from —every `from './lib/grass.js'` an agent wrote would have been a build error."""from codeverse3d.languages.scene_threejs import lib_files@@ -122,10 +147,12 @@ def test_the_effects_catalog_reaches_the_scene_prompts_and_only_those():assert language_text(Language.GLSL_SHADER, "effects_catalog.md") == ""tpl = PROMPTS_DIR / "tracks"- for name in ("scene_env.j2", "scene_zone.j2", "scene_refine.j2"):+ for name in ("scene_env.j2", "scene_zone.j2"):assert "effects_catalog" in (tpl / name).read_text(), name- # the asset session authors BLENDER bpy, so it must NOT carry the table- assert "effects_catalog" not in (tpl / "scene_asset.j2").read_text()+ # the asset session authors BLENDER bpy, so it must NOT carry the table; a refine session edits+ # one file with src/lib in its workspace and the skills routed, so it carries none either (2026-10-15)+ for name in ("scene_asset.j2", "scene_refine.j2"):+ assert "effects_catalog" not in (tpl / name).read_text(), namedef test_the_catalog_names_every_library_module_and_no_other():diff --git a/harness/tests/skills/test_freshness.py b/harness/tests/skills/test_freshness.pyindex 897ff55e..8e488c76 100644--- a/harness/tests/skills/test_freshness.py+++ b/harness/tests/skills/test_freshness.py@@ -238,6 +238,24 @@ def test_every_named_cookbook_section_exists():)+#: the cookbook was ELIMINATED for the scene track (owner, 2026-10-15): its interface facts went+#: into contract.md / system.md and its craft into the skills as short optional practices, so a+#: scene bundle that still points the agent at a cookbook chapter points at nothing.+SCENE_LANGS = frozenset({"scene_threejs", "scene_blender"})+++def test_scene_bundles_name_no_cookbook_chapter():+ for s in SKILLS:+ langs = _languages_of(s.name)+ if not langs or not langs <= SCENE_LANGS:+ continue+ text = "\n".join([s.body] + [p.read_text() for p in sorted(s.dir.rglob("references/*.md"))])+ assert not _cookbook_sections_named_by(s), (+ f"{s.name} names cookbook sections {_cookbook_sections_named_by(s)}; the scene cookbooks are gone")+ assert not re.search(r"\bcookbook\b", text, re.I), (+ f"{s.name} still mentions a cookbook; the scene track has none")++def test_every_live_constant_named_by_a_skill_has_a_claim():from codeverse3d.addons.skill_targets import load_claims