Skip to content

Official Codebase of 3DCodeVerse

Python

scene: wire the texture pack into the loop, behind CV3D_SCENE_TEXTURES (off)

ziyaocca6e63539fd
diff --git a/harness/codeverse/config.py b/harness/codeverse/config.py
index fc0d945d..f9370aaa 100644
--- a/harness/codeverse/config.py
+++ b/harness/codeverse/config.py
@@ -174,6 +174,10 @@ class Judge(BaseModel):
FEWER_TURNS_ENV = "CV3D_FEWER_TURNS"
#: The recipe-seeding switch (Limits.seed_recipes); same call-time contract as FEWER_TURNS_ENV.
SEED_RECIPES_ENV = "CV3D_SEED_RECIPES"
+#: wire the scene texture pack into the scene loop (a stage before env/zones, and the
+#: pack description in both prompts). OFF by default: it adds an image-model call per
+#: run, and whether it earns that is a measurement nobody has made yet.
+SCENE_TEXTURES_ENV = "CV3D_SCENE_TEXTURES"
_TRUE_WORDS = frozenset({"1", "on", "true", "yes", "y"})
_FALSE_WORDS = frozenset({"0", "off", "false", "no", "n"})
@@ -209,6 +213,21 @@ def fewer_turns_enabled() -> bool:
return env_flag(FEWER_TURNS_ENV, get_settings().limits.fewer_turns)
+def scene_textures_enabled() -> bool:
+ """Is the scene texture stage on for THIS call? ``$CV3D_SCENE_TEXTURES``, else off.
+
+ The pack generator (``texturing.plan.scene_texture_pack``) and the prompt snippet that
+ describes it (``texture_pack_prompt`` — whose docstring already says "for zone/env
+ generation") have existed since the texturing work, but nothing in ``tracks/scene.py``
+ called either: the switch `Spec.options.texture` does nothing on this track and the
+ generator was never told a pack could exist. Measured on bench/out/scene_baseline
+ (2026-09-05): four of the five scored cells' judge complaints are the GROUND being a
+ flat untextured colour, in near-identical words, and that is the most consistent
+ defect in the battery.
+ """
+ return env_flag(SCENE_TEXTURES_ENV, False)
+
+
def seed_recipes_enabled() -> bool:
"""Is recipe seeding (``tracks/graphics.py:seed_recipes``) on for THIS call? ``$CV3D_SEED_RECIPES``
when it is set, else ``Settings.limits.seed_recipes`` (default ON)."""
diff --git a/harness/codeverse/prompts/tracks/scene_env.j2 b/harness/codeverse/prompts/tracks/scene_env.j2
index 3fdfcb45..8f85f823 100644
--- a/harness/codeverse/prompts/tracks/scene_env.j2
+++ b/harness/codeverse/prompts/tracks/scene_env.j2
@@ -86,6 +86,10 @@ every authored camera needs mean luminance >= 0.15 with dark <= 35 %.
{{ effects_catalog }}
{% endif %}
+{% if textures is defined and textures %}
+
+{{ textures }}
+{% endif %}
{% if recipes is defined and recipes %}
# Recipes (from the scene cookbook — copy these numbers and snippets)
diff --git a/harness/codeverse/prompts/tracks/scene_zone.j2 b/harness/codeverse/prompts/tracks/scene_zone.j2
index 782ad4e9..4ae9c981 100644
--- a/harness/codeverse/prompts/tracks/scene_zone.j2
+++ b/harness/codeverse/prompts/tracks/scene_zone.j2
@@ -94,6 +94,10 @@ motion is under 0.4 % of the frame, double the amplitude and render again.
{{ effects_catalog }}
{% endif %}
+{% if textures is defined and textures %}
+
+{{ textures }}
+{% endif %}
{% if recipes is defined and recipes %}
# Recipes (from the scene cookbook — copy these numbers and snippets)
diff --git a/harness/codeverse/tracks/plan_features.py b/harness/codeverse/tracks/plan_features.py
index a04f2cf5..a27ba867 100644
--- a/harness/codeverse/tracks/plan_features.py
+++ b/harness/codeverse/tracks/plan_features.py
@@ -80,6 +80,10 @@ LIVE_SWITCHES: dict[str, str] = {
# switch, read at call time by config.fewer_turns_enabled; acts after planning.
"CV3D_FEWER_TURNS": "codeverse/config.py",
"CV3D_SEED_RECIPES": "codeverse/config.py",
+ # wire the scene texture pack into the scene loop: a stage before env/zones, and the
+ # pack description (texturing.plan.texture_pack_prompt) in both prompts. OFF by
+ # default — it costs an image-model call per run and nobody has measured what it buys.
+ "CV3D_SCENE_TEXTURES": "codeverse/config.py",
# model-transport switches (2026-08-28, the hung-read waves): streaming with
# inter-chunk stall detection, and the IPv4-only transport. Read at call time
# by every gemini request, so a control arm can set either to 0.
diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.py
index 0dd6ef01..f844d9c8 100644
--- a/harness/codeverse/tracks/scene.py
+++ b/harness/codeverse/tracks/scene.py
@@ -26,6 +26,7 @@ import time
from collections.abc import Sequence
from typing import Any
+from codeverse.config import scene_textures_enabled
from codeverse.contracts.artifacts import (
BuildResult,
GateFinding,
@@ -43,6 +44,7 @@ from codeverse.proc import fan_out
from codeverse.prompts import render
from codeverse.spatial.frame_motion import motion_text_for
from codeverse.spatial.render_scene import JUDGE_MAX_VIEWS, perf_detail
+from codeverse.texturing.plan import texture_pack_prompt
from codeverse.tracks import skills_hook
from codeverse.tracks.common import RunContext, ServiceUnavailable
from codeverse.tracks.generation import GenerationResult, GenerationTask, generate
@@ -228,6 +230,11 @@ class SceneTrack(BaseTrack):
# fields; the old enumerated keys let a mood/title/bounds/camera-only re-plan
# hit a stale cached stage. Old "assets+env" composite entries are ignored.
key = {"plan": plan, "agent": ctx.agent_id}
+ # textures first and alone: env and zones can only name the files if they exist by
+ # the time those prompts are built (config.scene_textures_enabled explains why this
+ # is off by default and what it costs)
+ if scene_textures_enabled():
+ ctx.extra["textures"] = runner.stage("textures", lambda: self._textures_stage(ctx), inputs={"plan": plan}) or {}
stage_fns: dict[str, Any] = {"assets": lambda: run_asset_stage(ctx),
"env": lambda: self._env_stage(ctx), "layouts": _layouts}
results = fan_out(list(stage_fns.items()), lambda kv: runner.stage(kv[0], kv[1], inputs=key),
@@ -302,6 +309,27 @@ class SceneTrack(BaseTrack):
signal the delivery gap itself produced."""
skills_hook.record_usage(gen, index=0, kind=stage_kind)
+ def _textures_stage(self, ctx: RunContext) -> dict[str, Any]:
+ """Generate the scene's tileable texture pack into ``public/textures/``.
+
+ Runs BEFORE env / zones, because its whole point is that those prompts can name
+ the files. Advisory: a pack that cannot be generated leaves the run exactly as it
+ was before this stage existed (an empty manifest renders no prompt block)."""
+ from codeverse.reference import _image_model
+ from codeverse.texturing.plan import scene_texture_pack
+
+ plan: ScenePlan = ctx.plan # type: ignore[assignment]
+ try:
+ pack = scene_texture_pack(plan, ctx.ws.public / "textures", _image_model(""),
+ ctx.spec.backends.planner, cache_dir=ctx.settings.cache_dir / "textures")
+ except Exception as e: # noqa: BLE001 — textures accelerate, they must never kill a run
+ ctx.events.emit("textures.stage_failed", error=f"{type(e).__name__}: {e}"[:300])
+ return {}
+ manifest = pack.manifest()
+ ctx.ws.commit("textures")
+ ctx.events.emit("textures.done", n=len(manifest), cost_usd=round(pack.usage.cost_usd, 4), source=pack.source)
+ return manifest
+
def _env_stage(self, ctx: RunContext) -> dict[str, Any]:
gen = self._strategy(ctx, "env")
prompt = render("tracks/scene_env.j2", **self._ctx(gen, recipes=cookbook_sections(gen, ENV_RECIPES)))
@@ -480,7 +508,8 @@ class SceneTrack(BaseTrack):
return base_prompt_context(
ctx, title=plan.title, setting=plan.setting, mood=plan.mood, bounds=bbox_line(plan.bounds), environment=plan.environment,
zones_table=zones_table, cameras=cameras, effects=effects, animation="; ".join(plan.animation) or "(none)",
- asset_api=ctx.extra.get("asset_api", "(no assets)"), **extra)
+ asset_api=ctx.extra.get("asset_api", "(no assets)"),
+ textures=texture_pack_prompt(ctx.extra.get("textures") or {}), **extra)
# ----------------------------------------------------------------------------- helpers
diff --git a/harness/tests/scene_gates/test_scene_textures_stage.py b/harness/tests/scene_gates/test_scene_textures_stage.py
new file mode 100644
index 00000000..80bfb606
--- /dev/null
+++ b/harness/tests/scene_gates/test_scene_textures_stage.py
@@ -0,0 +1,113 @@
+"""The scene texture pack, wired into the loop.
+
+`texturing.plan.scene_texture_pack` generates a tileable pack into `public/textures/`,
+and `texture_pack_prompt` — whose own docstring says "Prompt snippet for zone/env
+generation" — describes it with the exact loading idiom. Nothing in `tracks/scene.py`
+called either: `Spec.options.texture` does nothing on this track, and the generator was
+never told a pack could exist.
+
+Measured on bench/out/scene_baseline (2026-09-05): of 24 judge issues over five scored
+cells, **four say the GROUND is a flat untextured colour**, in near-identical words
+("single flat brown color", "single flat color with no cobblestone texture", "flat,
+untextured blueish plane with no material blending"). It is the most consistent defect
+in the battery, and it is a harness gap rather than a limit of three.js.
+
+OFF by default: it costs an image-model call per run and what that buys is unmeasured.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codeverse.config import SCENE_TEXTURES_ENV, get_settings, scene_textures_enabled
+from codeverse.tracks.plan_features import LIVE_SWITCHES
+
+
[email protected](autouse=True)
+def _clean_settings(monkeypatch):
+ monkeypatch.delenv(SCENE_TEXTURES_ENV, raising=False)
+ get_settings.cache_clear()
+ yield
+ get_settings.cache_clear()
+
+
+def test_the_switch_is_off_by_default_and_readable_at_call_time(monkeypatch):
+ assert scene_textures_enabled() is False
+ monkeypatch.setenv(SCENE_TEXTURES_ENV, "1")
+ assert scene_textures_enabled() is True
+ monkeypatch.setenv(SCENE_TEXTURES_ENV, "false")
+ assert scene_textures_enabled() is False
+
+
+def test_the_switch_is_registered_as_live():
+ """An A/B arm that differs only by a switch no code reads is byte-identical to its
+ control; `plan_features` refuses such an arm, and only if the name is declared."""
+ assert LIVE_SWITCHES[SCENE_TEXTURES_ENV] == "codeverse/config.py"
+
+
+def _render(name: str, **extra):
+ from codeverse.prompts import render
+
+ base = dict(
+ title="t", setting="a yard", mood="calm", bounds="0 0 0 / 10 5 10", environment="sunny",
+ zones_table="- Yard: d", cameras="- overview", effects="(none)", animation="(none)",
+ asset_api="(no assets)", output_format="write the files", prompt="p", track="scene",
+ language="scene_threejs", tool_cards="", single_shot=False, recipes="", constraints="",
+ must_have="", dimensions="", zone_name="Yard", zone_description="d", zone_bbox="b",
+ zone_contents=[], zone_file="src/zones/yard.js", neighbours=[], layout="",
+ )
+ base.update(extra)
+ return render(f"tracks/{name}", **base)
+
+
+MANIFEST = {
+ "cobblestone": {"file": "cobblestone.png", "family": "stone", "role": "ground",
+ "tile_size_m": 2.0, "roughness": 0.85},
+}
+
+
[email protected]("template", ["scene_env.j2", "scene_zone.j2"])
+def test_the_pack_reaches_both_prompts(template: str):
+ from codeverse.texturing.plan import texture_pack_prompt
+
+ snippet = texture_pack_prompt(MANIFEST)
+ with_pack = _render(template, textures=snippet)
+ assert "/public/textures/cobblestone.png" in with_pack
+ assert "loaders.texture.load" in with_pack, "the loading idiom has to travel with the list"
+
+
[email protected]("template", ["scene_env.j2", "scene_zone.j2"])
+def test_no_pack_adds_nothing_to_either_prompt(template: str):
+ from codeverse.texturing.plan import texture_pack_prompt
+
+ assert texture_pack_prompt({}) == ""
+ empty = _render(template, textures="")
+ assert "textures" not in empty.lower().split("## output")[0] or "/public/textures/" not in empty
+
+
+def test_the_prompt_context_carries_the_manifest_the_stage_produced(monkeypatch):
+ """`_ctx` is the ONE place env and zone prompts get their context, so the manifest has
+ to arrive there or the stage generates textures nothing is told about — which is
+ exactly the state the loop was in before this."""
+ from types import SimpleNamespace
+
+ import codeverse.tracks.scene as S
+ from codeverse.contracts.plan import BBox, CameraPlan, ScenePlan, ZonePlan
+
+ seen: dict = {}
+ monkeypatch.setattr(S, "base_prompt_context", lambda ctx, **kw: seen.update(kw) or kw)
+
+ bb = BBox(center=(0, 0, 0), extents=(10, 5, 10))
+ plan = ScenePlan(title="t", summary="s", setting="yard", mood="calm", bounds=bb, environment="sunny",
+ zones=[ZonePlan(name="Yard", description="d", bbox=bb, contents=[])], assets=[],
+ cameras=[CameraPlan(name="overview", position=(1, 1, 1), look_at=(0, 0, 0), fov=50, purpose="p")],
+ animation=[], effects=[])
+
+ ctx = SimpleNamespace(plan=plan, extra={"textures": MANIFEST})
+ S.SceneTrack()._ctx(ctx) # type: ignore[arg-type]
+ assert "/public/textures/cobblestone.png" in seen["textures"]
+
+ ctx_none = SimpleNamespace(plan=plan, extra={})
+ seen.clear()
+ S.SceneTrack()._ctx(ctx_none) # type: ignore[arg-type]
+ assert seen["textures"] == "", "no pack, no prompt block"