Skip to content

Official Codebase of 3DCodeVerse

Python

scene: hierarchical zone layouts — an L2 zone director places, the builder realises

gaoypengf7a0c091da17
diff --git a/harness/codeverse/contracts/plan.py b/harness/codeverse/contracts/plan.py
index 52bc3625..92ddea89 100644
--- a/harness/codeverse/contracts/plan.py
+++ b/harness/codeverse/contracts/plan.py
@@ -511,6 +511,38 @@ class ScenePlan(BaseModel):
return self
+class ZonePlacement(BaseModel):
+ """One asset's placement inside a zone, decided by the L2 zone director.
+
+ Typed rows with concrete numbers on purpose (the RefDimension lesson: an
+ open-ended dict maps to a property-less schema and the model answers ``{}``)."""
+
+ asset: str = Field(description="asset name from the plan")
+ count: int = Field(ge=1, description="how many instances in this zone")
+ cluster: tuple[float, float] = Field(description="cluster centre (x, z) in WORLD meters, inside the zone bbox")
+ spread_m: float = Field(ge=0, description="radius the instances scatter within (0 = exactly at the centre)")
+ faces: str = Field(default="", description="what the instances face, e.g. 'the path', 'azimuth 220'")
+ support: str = Field(default="ground", description="'ground' or the asset they stand on")
+
+
+class ZoneLayout(BaseModel):
+ """The L2 layout for ONE zone: where its planned contents actually go.
+
+ Produced by a cheap structured call per zone (parallel, never an agent),
+ validated deterministically against the zone bbox and the plan before it is
+ handed to the zone builder — the builder realises a layout instead of
+ inventing one."""
+
+ zone: str = Field(description="the zone's name, exactly as planned")
+ 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")
+ notes: str = Field(default="", description="one line of layout intent, e.g. 'stalls face the lane'")
+
+
class RefDimension(BaseModel):
"""One reference dimension of the real object. A LIST of typed rows, not a free
``dict[str, float]``: an open-ended object maps to a property-less ``{"type":
diff --git a/harness/codeverse/prompts/tracks/plan_zone_layout.j2 b/harness/codeverse/prompts/tracks/plan_zone_layout.j2
new file mode 100644
index 00000000..fde23d74
--- /dev/null
+++ b/harness/codeverse/prompts/tracks/plan_zone_layout.j2
@@ -0,0 +1,31 @@
+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.
+
+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 }}
+
+Neighbouring zones (do not place into them):
+{% for n in neighbours %}- {{ n }}
+{% endfor %}
+
+## Assets to place (measured sizes)
+{% for a in assets %}- {{ a }}
+{% endfor %}
+
+WHAT TO PRODUCE (JSON, fields: {{ schema_fields }}):
+- `placements` — one row per contents asset (split an asset into 2-3 rows when it appears in
+ distinct 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.
+- `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".
diff --git a/harness/codeverse/prompts/tracks/scene_zone.j2 b/harness/codeverse/prompts/tracks/scene_zone.j2
index 3f014a54..e193e925 100644
--- a/harness/codeverse/prompts/tracks/scene_zone.j2
+++ b/harness/codeverse/prompts/tracks/scene_zone.j2
@@ -7,7 +7,10 @@ Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}
- Bbox: {{ zone_bbox }} — place EVERYTHING inside it (x/z), on the ground via `heightAt`.
- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from primitives)' }}
-Neighbouring zones (do not build into them):
+{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world meters)
+{{ layout }}
+
+{% endif %}Neighbouring zones (do not build into them):
{% for n in neighbours %}- {{ n }}
{% endfor %}
diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.py
index 22913586..d264ff85 100644
--- a/harness/codeverse/tracks/scene.py
+++ b/harness/codeverse/tracks/scene.py
@@ -65,6 +65,7 @@ from codeverse.tracks.scene_assets import (
select_assets,
single_shot_ctx,
)
+from codeverse.tracks.zone_layout import layout_block, layout_zones
from codeverse.workspace import Workspace
log = logging.getLogger(__name__)
@@ -199,8 +200,23 @@ class SceneTrack(BaseTrack):
# (each measured at ~+0.13). Workspace.commit serialises under its own lock,
# so the two stages' commits cannot race. One cached stage keeps resume
# atomic: both results or neither.
+ def _layouts() -> dict[str, Any]:
+ """L2 zone layouts (optional accelerator): planner-model calls, never fatal."""
+ try:
+ model = self._planner_model
+ if model is None:
+ from codeverse.models import get_chat_model
+
+ model = get_chat_model(ctx.spec.backends.planner)
+ layouts = layout_zones(plan, model, budget=ctx.budget, events=ctx.events)
+ return {k: v.model_dump(mode="json") for k, v in layouts.items()}
+ except Exception as e: # noqa: BLE001 — layouts accelerate, they must never kill
+ ctx.events.emit("layout.stage_failed", error=f"{type(e).__name__}: {e}"[:300])
+ return {}
+
def _assets_and_env() -> dict[str, Any]:
- thunks = {"assets": lambda: run_asset_stage(ctx), "env": lambda: self._env_stage(ctx)}
+ thunks = {"assets": lambda: run_asset_stage(ctx), "env": lambda: self._env_stage(ctx),
+ "layouts": _layouts}
results = fan_out(list(thunks.items()), lambda kv: kv[1](), max_workers=2,
label="assets+env", item_name=lambda kv: kv[0])
out: dict[str, Any] = {}
@@ -213,12 +229,14 @@ class SceneTrack(BaseTrack):
ctx.events.emit("stage.failed", stage=name, error=f"{type(r).__name__}: {r}")
else:
out[name] = {k: v.model_dump(mode="json") for k, v in r.items()} if name == "assets" else r
+ out.setdefault("layouts", {})
if first_exc is not None:
raise first_exc
return out
both = runner.stage("assets+env", _assets_and_env,
inputs={"assets": plan.assets, "plan_env": plan.environment,
- "setting": plan.setting, "agent": ctx.agent_id})
+ "setting": plan.setting, "zones": plan.zones, "agent": ctx.agent_id})
+ ctx.extra["layouts"] = (both or {}).get("layouts") or {}
assets = {k: AssetResult.model_validate(v) if isinstance(v, dict) else v
for k, v in ((both or {}).get("assets") or {}).items()}
# the merge map is a pure function of the plan, so a RESUMED run (cached asset
@@ -354,7 +372,8 @@ class SceneTrack(BaseTrack):
# a batched session reads ONE copy of the recipes (they are identical per zone)
briefs.append(render("tracks/scene_zone.j2", **self._ctx(ctx, recipes=recipes if i == 0 else "", zone_name=zone.name, zone_description=zone.description,
zone_bbox=bbox_line(zone.bbox), zone_contents=zone.contents,
- zone_file=zone_file(zone), neighbours=neighbours)))
+ zone_file=zone_file(zone), neighbours=neighbours,
+ layout=layout_block(ctx.extra.get("layouts", {}).get(zone.name)))))
ctx.record_prompt("scene_zone", briefs[0])
if len(batch) == 1:
prompt, label = briefs[0], f"zone_{to_snake(names[0])}"
diff --git a/harness/codeverse/tracks/zone_layout.py b/harness/codeverse/tracks/zone_layout.py
new file mode 100644
index 00000000..5e6d31a4
--- /dev/null
+++ b/harness/codeverse/tracks/zone_layout.py
@@ -0,0 +1,136 @@
+"""L2 zone layouts: one cheap structured call per zone, in parallel, validated.
+
+Why this layer exists (measured 2026-08-30 across the 48 scored scene runs):
+``ZonePlan.contents`` is a list of NAMES — the zone agent freehand-places
+everything, and the final rounds still carried 55 interpenetration, 38 sunken
+and 22 floating gate ERRORS, with undressed_scene standing in 31/48 verdicts.
+The layout is planning work, so it is done by the PLANNER model with a schema
+(never a coding agent), validated deterministically against the zone bbox and
+the plan, re-asked once with the exact complaint, and handed to the zone
+builder as numbers to realise.
+
+Layouts are an optional accelerator like the engineering brief: any failure
+returns no layout for that zone and generation proceeds exactly as before.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from codeverse.contracts.chat import ChatMessage, ChatRequest
+from codeverse.contracts.plan import ScenePlan, ZoneLayout, ZonePlan
+from codeverse.conventions import to_snake
+from codeverse.models.schema_utils import parse_json_lenient
+from codeverse.proc import fan_out
+from codeverse.prompts import render
+
+log = logging.getLogger(__name__)
+
+LAYOUT_TEMPLATE = "tracks/plan_zone_layout.j2"
+LAYOUT_MAX_TOKENS = 4000
+LAYOUT_WAIT_S = 300.0
+#: a placement may multiply the plan's instances_hint by at most this much
+COUNT_SLACK = 4
+#: cluster centres may sit this far outside the zone bbox (assets have radius)
+BBOX_MARGIN_M = 1.0
+
+
+def validate_layout(layout: ZoneLayout, zone: ZonePlan, plan: ScenePlan) -> str:
+ """"" when the layout is buildable; otherwise the exact complaint to re-ask with."""
+ problems: list[str] = []
+ known = {to_snake(a.name): a for a in plan.assets}
+ hints = {to_snake(a.name): max(1, a.instances_hint) for a in plan.assets}
+ lo, hi = zone.bbox.min, zone.bbox.max
+ for p in layout.placements:
+ k = to_snake(p.asset)
+ if k not in known:
+ problems.append(f"placement names unknown asset '{p.asset}' (plan assets: {', '.join(sorted(known))})")
+ continue
+ x, z = p.cluster
+ if not (lo[0] - BBOX_MARGIN_M <= x <= hi[0] + BBOX_MARGIN_M and lo[2] - BBOX_MARGIN_M <= z <= hi[2] + BBOX_MARGIN_M):
+ problems.append(f"{p.asset} cluster ({x:.1f}, {z:.1f}) is outside zone {zone.name} bbox "
+ f"x {lo[0]:.1f}..{hi[0]:.1f}, z {lo[2]:.1f}..{hi[2]:.1f}")
+ if p.count > COUNT_SLACK * hints[k]:
+ problems.append(f"{p.asset} count {p.count} is over {COUNT_SLACK}x the plan's instances_hint {hints[k]}")
+ placed = {to_snake(p.asset) for p in layout.placements}
+ missing = [c for c in zone.contents if to_snake(c) not in placed]
+ if missing:
+ problems.append(f"no placement for planned contents: {', '.join(missing)}")
+ return "; ".join(problems)
+
+
+def layout_block(layout: ZoneLayout | dict[str, Any] | None) -> str:
+ """The prompt table a zone builder realises (`""` when there is no layout)."""
+ if layout is None:
+ return ""
+ lay = layout if isinstance(layout, ZoneLayout) else ZoneLayout.model_validate(layout)
+ lines = []
+ for p in lay.placements:
+ faces = f", facing {p.faces}" if p.faces else ""
+ support = f", on {p.support}" if p.support and p.support != "ground" else ""
+ lines.append(f"- {p.count}x {p.asset} around ({p.cluster[0]:.1f}, {p.cluster[1]:.1f}) "
+ f"spread {p.spread_m:.1f} m{faces}{support}")
+ if lay.path_points:
+ pts = " -> ".join(f"({x:.1f}, {z:.1f})" for x, z in lay.path_points)
+ lines.append(f"- path polyline: {pts}")
+ dress = [f"{n} {label}" for n, label in ((lay.mid_props, "mid props"), (lay.small_props, "small props"),
+ (lay.ground_cover, "ground-cover instances")) if n]
+ if dress:
+ lines.append("- dressing beyond the placements: " + ", ".join(dress))
+ if lay.notes:
+ lines.append(f"- intent: {lay.notes}")
+ return "\n".join(lines)
+
+
+def _one_layout(zone: ZonePlan, plan: ScenePlan, model: Any, budget: Any, events: Any) -> ZoneLayout | None:
+ neighbours = [f"{z.name}: x {z.bbox.min[0]:.0f}..{z.bbox.max[0]:.0f}, z {z.bbox.min[2]:.0f}..{z.bbox.max[2]:.0f}"
+ for z in plan.zones if z.name != zone.name]
+ assets = [f"{a.name}: {a.approx_size_m[0]:g}x{a.approx_size_m[1]:g}x{a.approx_size_m[2]:g} m, ~{a.instances_hint} planned"
+ for a in plan.assets if to_snake(a.name) in {to_snake(c) for c in zone.contents}] or ["(no planned assets — dressing only)"]
+ system = render(LAYOUT_TEMPLATE, title=plan.title, setting=plan.setting, mood=plan.mood,
+ environment=plan.environment[:600], zone=zone, neighbours=neighbours, assets=assets,
+ 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)'}"
+ complaint = ""
+ for attempt in (0, 1):
+ ask = user if not complaint else f"{user}\n\nYour previous layout was rejected: {complaint}. Fix exactly these problems."
+ resp = model.generate(ChatRequest(messages=[ChatMessage.user(ask)], system=system,
+ response_schema=ZoneLayout.model_json_schema(), temperature=0.3,
+ thinking="low", max_output_tokens=LAYOUT_MAX_TOKENS,
+ max_wait_s=LAYOUT_WAIT_S, label="zone-layout"))
+ if budget is not None:
+ budget.add(resp.usage, stage="plan")
+ raw = resp.parsed if resp.parsed is not None else parse_json_lenient(resp.text or "{}")
+ layout = ZoneLayout.model_validate(raw)
+ layout.zone = zone.name # the name is an input, never model-invented
+ complaint = validate_layout(layout, zone, plan)
+ if not complaint:
+ if events is not None:
+ events.emit("layout.done", zone=zone.name, placements=len(layout.placements), reasked=bool(attempt))
+ return layout
+ if events is not None:
+ events.emit("layout.rejected", zone=zone.name, complaint=complaint[:300])
+ log.warning("zone layout for %s rejected twice (%s); building without one", zone.name, complaint)
+ return None
+
+
+def layout_zones(plan: ScenePlan, model: Any, *, budget: Any = None, events: Any = None,
+ max_workers: int = 6) -> dict[str, ZoneLayout]:
+ """One validated layout per zone, computed in parallel. Failures drop out silently
+ (an exception or double rejection yields no layout for that zone, never a dead run)."""
+
+ def _safe(zone: ZonePlan) -> ZoneLayout | None:
+ return _one_layout(zone, plan, model, budget, events)
+
+ results = fan_out(list(plan.zones), _safe, max_workers=max_workers, label="layouts",
+ item_name=lambda z: z.name)
+ out: dict[str, ZoneLayout] = {}
+ for zone, r in zip(plan.zones, results, strict=True):
+ if isinstance(r, Exception):
+ if events is not None:
+ events.emit("layout.failed", zone=zone.name, error=f"{type(r).__name__}: {r}"[:300])
+ log.warning("zone layout for %s failed (%s); building without one", zone.name, r)
+ elif r is not None:
+ out[zone.name] = r
+ return out
diff --git a/harness/tests/orchestrator_tracks/test_zone_layout.py b/harness/tests/orchestrator_tracks/test_zone_layout.py
new file mode 100644
index 00000000..b87a7873
--- /dev/null
+++ b/harness/tests/orchestrator_tracks/test_zone_layout.py
@@ -0,0 +1,83 @@
+"""L2 zone layouts: validator complaints, prompt table, parallel calls with one re-ask."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from codeverse.contracts.plan import AssetPlan, BBox, CameraPlan, ScenePlan, ZoneLayout, ZonePlan
+from codeverse.tracks.zone_layout import layout_block, layout_zones, validate_layout
+
+
+def _plan() -> ScenePlan:
+ return ScenePlan(
+ title="t", summary="s", setting="harbour, dusk", mood="calm",
+ bounds=BBox(center=(0, 0, 0), extents=(60, 10, 60)), environment="sky 0x223250",
+ zones=[ZonePlan(name="Quay", description="12 mid props", bbox=BBox(center=(-10, 0, 0), extents=(20, 8, 20)),
+ contents=["Bollard", "FishingBoat"]),
+ ZonePlan(name="Market", description="stalls", bbox=BBox(center=(10, 0, 0), extents=(20, 8, 20)),
+ contents=["Stall"])],
+ assets=[AssetPlan(name="Bollard", kind="threejs", description="d", approx_size_m=(0.3, 0.8, 0.3), instances_hint=6),
+ AssetPlan(name="FishingBoat", kind="threejs", description="d", approx_size_m=(6, 2.5, 2), instances_hint=2),
+ AssetPlan(name="Stall", kind="threejs", description="d", approx_size_m=(3, 2.5, 2), instances_hint=4)],
+ cameras=[CameraPlan(name="overview", position=(1, 1, 1), look_at=(0, 0, 0), fov=50, purpose="p")])
+
+
+def _layout(**over) -> ZoneLayout:
+ base = {"zone": "Quay",
+ "placements": [{"asset": "Bollard", "count": 6, "cluster": (-12.0, 3.0), "spread_m": 4.0},
+ {"asset": "FishingBoat", "count": 2, "cluster": (-8.0, -5.0), "spread_m": 2.0}]}
+ base.update(over)
+ return ZoneLayout.model_validate(base)
+
+
+def test_validator_accepts_a_buildable_layout_and_names_every_problem():
+ plan = _plan()
+ assert validate_layout(_layout(), plan.zones[0], plan) == ""
+ bad = _layout(placements=[{"asset": "Kraken", "count": 1, "cluster": (-12.0, 3.0), "spread_m": 1.0},
+ {"asset": "Bollard", "count": 99, "cluster": (55.0, 3.0), "spread_m": 1.0}])
+ complaint = validate_layout(bad, plan.zones[0], plan)
+ assert "unknown asset 'Kraken'" in complaint
+ assert "outside zone Quay bbox" in complaint
+ assert "count 99" in complaint
+ assert "no placement for planned contents: FishingBoat" in complaint
+
+
+def test_layout_block_renders_numbers_the_builder_can_follow():
+ text = layout_block(_layout(path_points=[(-18.0, 0.0), (-2.0, 4.0)], mid_props=12, ground_cover=400,
+ notes="boats face the quay"))
+ assert "6x Bollard around (-12.0, 3.0) spread 4.0 m" in text
+ assert "path polyline: (-18.0, 0.0) -> (-2.0, 4.0)" in text
+ assert "12 mid props" in text and "400 ground-cover" in text and "boats face the quay" in text
+ assert layout_block(None) == ""
+
+
+class _Model:
+ """Scripted planner: first answer per zone from the queue, then valid ones."""
+
+ def __init__(self, answers):
+ self.answers = list(answers)
+ self.calls = 0
+
+ def generate(self, req):
+ self.calls += 1
+ return SimpleNamespace(parsed=self.answers.pop(0), text="", usage=None)
+
+
+def test_layout_zones_runs_per_zone_and_reasks_once_with_the_complaint():
+ plan = _plan()
+ good_quay = _layout().model_dump(mode="json")
+ bad_quay = _layout(placements=[{"asset": "Kraken", "count": 1, "cluster": (0.0, 0.0), "spread_m": 1.0}]).model_dump(mode="json")
+ good_market = {"zone": "Market", "placements": [{"asset": "Stall", "count": 4, "cluster": (10.0, 0.0), "spread_m": 5.0}]}
+ # zones fan out with max_workers=1 so the scripted queue stays ordered
+ model = _Model([bad_quay, good_quay, good_market])
+ out = layout_zones(plan, model, max_workers=1)
+ assert set(out) == {"Quay", "Market"} and model.calls == 3
+ assert out["Quay"].placements[0].asset == "Bollard"
+
+
+def test_layout_zones_drops_a_twice_rejected_zone_instead_of_dying():
+ plan = _plan()
+ bad = {"zone": "Quay", "placements": [{"asset": "Kraken", "count": 1, "cluster": (0.0, 0.0), "spread_m": 1.0}]}
+ good_market = {"zone": "Market", "placements": [{"asset": "Stall", "count": 4, "cluster": (10.0, 0.0), "spread_m": 5.0}]}
+ out = layout_zones(plan, _Model([bad, bad, good_market]), max_workers=1)
+ assert set(out) == {"Market"}