Official Codebase of 3DCodeVerse
Python
"""Plans: the agent's structured decomposition, each with an acceptance checklist.
Written by the host agent as ``plan.json``, then validated in code (``3dcode validate-plan``)."""
from __future__ import annotations
import contextlib
import math
import re
from typing import Annotated, Any, Literal
from pydantic import AfterValidator, BaseModel, Field, field_validator, model_validator
from codeverse3d.contracts.common import (
Language,
MimicSpec,
Vec3,
mimic_issues,
)
from codeverse3d.conventions import to_snake
#: model ids / placeholders that leak into part names. High-precision patterns only:
#: "CameraFlash" or "ModelStand" must stay legal.
_MODEL_NAME_LEAK = re.compile(r"(?i)(gemini|gpt[-_ ]?\d|claude|llama|qwen|deepseek|placeholder)")
def reject_model_leak(v: str) -> str:
"""Reject (never mangle) part names that are model ids / placeholders."""
m = _MODEL_NAME_LEAK.search(v)
if m:
raise ValueError(
f"part name {v!r} contains {m.group(1)!r} — a model id or placeholder leaked from "
"thinking, not a component of the object. Name the real part (e.g. GrinderWheel).")
return v
LeakFreeName = Annotated[str, AfterValidator(reject_model_leak)]
class BBox(BaseModel):
"""Axis-aligned box in the plan's frame: centre + full extents (meters)."""
center: Vec3
extents: Vec3
@property
def min(self) -> tuple[float, float, float]:
return tuple(c - e / 2 for c, e in zip(self.center, self.extents, strict=True)) # type: ignore[return-value]
@property
def max(self) -> tuple[float, float, float]:
return tuple(c + e / 2 for c, e in zip(self.center, self.extents, strict=True)) # type: ignore[return-value]
class AcceptanceItem(BaseModel):
"""One verifiable requirement. ``how`` says which evidence proves it."""
id: str
text: str
how: Literal["measure", "visual", "probe", "articulation"] = "visual"
priority: Literal["must", "should"] = "must"
#: how far a sub-part may stick out of its parent's bbox: ``max(SUBPART_SLACK_M,
#: SUBPART_REL_SLACK × parent extent)`` per axis (planner boxes are design intent).
SUBPART_SLACK_M = 0.01
SUBPART_REL_SLACK = 0.15
#: A ``revolute`` range over 2π with both limits inside ±``DEGREES_MAX_ABS`` and a span of at
#: least ``DEGREES_MIN_SPAN`` is read as degrees; a smaller span over 2π is radians and becomes
#: ``continuous``.
DEGREES_MAX_ABS = 360.0
DEGREES_MIN_SPAN = 30.0
class SubPartPlan(BaseModel):
"""One sub-part of a :class:`PartPlan` — depth 1 by construction (a sub-part has no
children of its own, so a cycle cannot be expressed).
Sub-parts are a PLANNING device, not export nodes: the parent part is still exactly ONE
named object in the GLB and the contract gate still checks exactly the parent's bbox.
They exist so a part a human would call an *assembly* ("burr mechanism", "pegbox",
"belt housing") can be planned as the 3-6 shapes it really is — which is where the
measured judge reward lives — without adding contact surfaces the assembly gates must
police. See the complexity baseline: built-parts ÷ planned-parts is
the only complexity metric with a positive partial correlation to geometry_detail."""
name: LeakFreeName = Field(description="PascalCase, unique within the parent, e.g. Burr")
role: str = Field(default="", description="what this sub-part is, a few words")
description: str = Field(description="shape and construction in numbers")
bbox: BBox = Field(description="inside the parent's bbox, same frame")
material: str = Field(default="", description="material / finish when it differs from the parent's")
instances: int = Field(default=1, ge=1, description="identical copies inside the parent")
class PartPlan(BaseModel):
name: LeakFreeName = Field(description="PascalCase unique part name, e.g. SeatCushion")
role: str = Field(description="what this part is / does, one line")
description: str = Field(description="shape, construction and visible detail the builder must realise")
bbox: BBox
material: str = Field(default="", description="material / finish in plain words")
attach_to: str | None = Field(default=None, description="parent part name this part touches")
symmetry: Literal["none", "mirror_x", "mirror_y", "radial"] = "none"
instances: int = Field(default=1, ge=1, description="identical copies (e.g. 4 legs)")
children: list[SubPartPlan] = Field(
default_factory=list, max_length=8,
description="sub-parts of an ASSEMBLY part (a mechanism, a housing, a head) — still ONE named "
"object in the export; leave empty for a simple part such as a leg")
detail_hint: str = Field(
default="", description="one line telling the builder what makes THIS part read as real "
"(e.g. 'carries the visible mechanism — model the burrs, the shaft and the nut')")
@property
def leaf_count(self) -> int:
"""Shapes this part stands for: its own copies, or the sum of its children's."""
inner = sum(c.instances for c in self.children) or 1
return self.instances * inner
@model_validator(mode="after")
def _children_ok(self) -> PartPlan:
seen: set[str] = set()
pmin, pmax = self.bbox.min, self.bbox.max
for c in self.children:
key = to_snake(c.name)
if key == to_snake(self.name):
raise ValueError(f"part {self.name}: sub-part {c.name} repeats its parent's name")
if key in seen:
raise ValueError(f"part {self.name}: duplicate sub-part name (after normalisation): {c.name}")
seen.add(key)
cmin, cmax = c.bbox.min, c.bbox.max
for axis, lo, hi, clo, chi, ext in zip("xyz", pmin, pmax, cmin, cmax, self.bbox.extents, strict=True):
slack = max(SUBPART_SLACK_M, SUBPART_REL_SLACK * abs(ext))
over = max(lo - clo, chi - hi)
if over > slack:
raise ValueError(
f"part {self.name}: sub-part {c.name} sticks {over * 1000:.0f} mm out of the parent bbox on "
f"{axis} (parent {axis} in [{lo:.3f}, {hi:.3f}], sub-part [{clo:.3f}, {chi:.3f}], "
f"allowed slack {slack * 1000:.0f} mm) — either shrink/move the sub-part or grow the parent bbox")
return self
class StaticPlan(BaseModel):
object_name: str
summary: str
overall_bbox: BBox
style_notes: str = ""
parts: list[PartPlan] = Field(min_length=1)
acceptance: list[AcceptanceItem] = Field(default_factory=list)
@model_validator(mode="after")
def _unique_names(self) -> StaticPlan:
seen: set[str] = set()
for p in self.parts:
key = to_snake(p.name)
if key in seen:
raise ValueError(f"duplicate part name (after normalisation): {p.name}")
seen.add(key)
names = {to_snake(p.name) for p in self.parts}
for p in self.parts:
if p.attach_to and to_snake(p.attach_to) not in names:
raise ValueError(f"part {p.name} attaches to unknown part {p.attach_to}")
for p in self.parts:
for c in p.children:
if to_snake(c.name) in names:
raise ValueError(f"sub-part {p.name}.{c.name} has the same name as top-level part {c.name}; "
"either rename it or promote it to a top-level part")
return self
@property
def leaf_count(self) -> int:
"""Total shapes the plan asks for (parts × instances, sub-parts counted individually)."""
return sum(p.leaf_count for p in self.parts)
class MimicPlan(BaseModel):
"""This joint is driven by another: ``q = multiplier * q[joint] + offset``.
A coupled mechanism (umbrella ribs on one runner, a pantograph, a tambour) has ONE
input and many moving links. Declaring the coupling lets the sweep pose it the way
it really moves; without it every link is driven independently."""
joint: str = Field(description="the joint this one follows, by name")
multiplier: float = Field(default=1.0, description="q_this = multiplier * q_that + offset")
offset: float = Field(default=0.0)
class JointPlan(BaseModel):
name: LeakFreeName
type: Literal["revolute", "prismatic", "continuous", "fixed"]
parent: str = Field(description="parent link (part) name")
child: str = Field(description="child link (part) name")
axis: Vec3 = Field(description="unit axis in the plan frame")
pivot: Vec3 = Field(description="a point on the joint axis, WORLD coords (rest pose)")
lower: float = Field(default=0.0, description="rad for revolute, m for prismatic")
upper: float = Field(default=0.0)
rest: float = Field(default=0.0, description="joint value in the authored rest pose")
motion: str = Field(default="", description="what moving this joint does, one line")
mimic: MimicPlan | None = Field(default=None, description="set when this joint is driven by another")
@model_validator(mode="after")
def _sane(self) -> JointPlan:
n = math.sqrt(sum(a * a for a in self.axis))
if n < 1e-6:
raise ValueError(f"joint {self.name}: zero axis")
if abs(n - 1.0) > 1e-3:
self.axis = tuple(a / n for a in self.axis) # type: ignore[assignment]
if self.type in ("revolute", "prismatic"):
if self.upper < self.lower:
raise ValueError(f"joint {self.name}: upper < lower")
if not (self.lower - 1e-9 <= self.rest <= self.upper + 1e-9):
raise ValueError(f"joint {self.name}: rest {self.rest} outside [{self.lower},{self.upper}]")
if self.type == "revolute" and (self.upper - self.lower) > 2 * math.pi + 1e-6:
raise ValueError(f"joint {self.name}: revolute range > 2π, use continuous")
if self.type == "prismatic" and (self.upper - self.lower) > 5.0:
raise ValueError(f"joint {self.name}: prismatic range > 5 m is implausible")
if to_snake(self.parent) == to_snake(self.child):
# name BOTH sides: pydantic truncates the offending value after the joint name.
same = "" if self.parent == self.child else (
f" ('{self.parent}' and '{self.child}' are the same name once normalised)")
raise ValueError(
f"joint {self.name}: parent and child are both '{self.parent}'{same} — a joint "
f"connects TWO different links; name the moving link as child and what it is "
f"attached to as parent, or drop the joint if nothing moves")
return self
def _looks_like_degrees(lower: float, upper: float) -> bool:
"""Revolute limits the planner wrote in degrees: inside ±360 with a span of at least 30 (see the constants)."""
return abs(lower) <= DEGREES_MAX_ABS and abs(upper) <= DEGREES_MAX_ABS and upper - lower >= DEGREES_MIN_SPAN
def _promoted(child: dict, owner: dict) -> dict:
"""A sub-part a joint moves, as the top-level link it becomes (repairs 1 and 1c)."""
return {"name": child.get("name"), "role": child.get("role") or f"moving part of {owner.get('name')}",
"description": child.get("description", ""), "bbox": child.get("bbox"),
"material": child.get("material") or owner.get("material", ""),
"attach_to": owner.get("name"), "instances": child.get("instances", 1)}
def _raw_bounds(bbox: object) -> tuple[list[float], list[float]] | None:
"""``(lo, hi)`` of a raw ``{center, extents}`` bbox dict, or None when it is not one (repair 3)."""
if not (isinstance(bbox, dict) and isinstance(bbox.get("center"), (list, tuple))
and isinstance(bbox.get("extents"), (list, tuple))):
return None
try:
pairs = [(float(c), float(e) / 2) for c, e in zip(bbox["center"], bbox["extents"], strict=True)]
except (TypeError, ValueError):
return None
return [c - h for c, h in pairs], [c + h for c, h in pairs]
class ArticulatedPlan(StaticPlan):
root_link: str
joints: list[JointPlan] = Field(min_length=1)
normalisations: list[str] = Field(
default_factory=list,
description="filled by validate-plan, leave empty: automatic corrections applied to the plan "
"before validation (a sub-part promoted to a link because a joint moves it, revolute limits "
"written in degrees converted to radians or a > 2π radian range made continuous, swapped "
"or out-of-range limits clamped, a parent bbox grown around a sub-part)")
@model_validator(mode="before")
@classmethod
def _normalise_raw(cls, data: object) -> object:
"""Repair schema-shaped planner slips that are not design decisions:
1. a joint naming a sub-part promotes it to a top-level part;
1b/1c. a joint naming a part or sub-part by a unique fragment is resolved;
2. revolute limits written in degrees become radians; other ranges over 2π become ``continuous``;
2b. swapped limits are swapped back, an out-of-range ``rest`` is clamped;
3. a sub-part outside its parent's bbox grows the parent;
4. a ``root_link`` naming no part is rewritten when exactly one part matches.
Every repair is recorded in ``normalisations``; anything else fails validation.
"""
if not isinstance(data, dict):
return data
data = dict(data)
parts = [dict(p) for p in (data.get("parts") or []) if isinstance(p, dict)]
joints = [dict(j) for j in (data.get("joints") or []) if isinstance(j, dict)]
# harness-only field: any incoming value is dropped
notes: list[str] = []
if not parts or not joints:
return data
by_name = {to_snake(str(p.get("name", ""))): p for p in parts}
# 1. joints that move a sub-part → promote it
referenced = {to_snake(str(j.get(k, ""))) for j in joints for k in ("parent", "child")}
for part in list(parts):
kept = []
for child in part.get("children") or []:
if not isinstance(child, dict):
kept.append(child)
continue
key = to_snake(str(child.get("name", "")))
if key in referenced and key not in by_name:
promoted = _promoted(child, part)
parts.append(promoted)
by_name[key] = promoted
notes.append(f"promoted sub-part {part.get('name')}.{child.get('name')} to a link: a joint moves it")
else:
kept.append(child)
part["children"] = kept
# 1b. a joint naming a link by a unique fragment of a real part ("Lid" for "ChestLid")
known = set(by_name)
for j in joints:
for side in ("parent", "child"):
raw_name = str(j.get(side, ""))
key = to_snake(raw_name)
if not key or key in known:
continue
hits = [n for n in known if key in n.split("_") or n.endswith(f"_{key}") or n.startswith(f"{key}_")]
if len(hits) == 1:
j[side] = by_name[hits[0]].get("name")
notes.append(f"joint {j.get('name')}.{side} '{raw_name}' resolved to the one part it names: {j[side]}")
# 1c. a joint naming a sub-part by a fragment: WORD-SUBSET match ({glazed,door} within
# {glazed,front,door}; "arm" never matches "alarm"); a unique hit is promoted.
sub_index: dict[str, tuple[dict, dict]] = {}
for part in list(parts):
for child in part.get("children") or []:
if isinstance(child, dict) and child.get("name"):
sub_index[to_snake(str(child["name"]))] = (part, child)
for j in joints:
for side in ("parent", "child"):
raw_name = str(j.get(side, ""))
key = to_snake(raw_name)
if not key or key in by_name:
continue
kw = set(key.split("_"))
hits = [k for k in sub_index if kw <= set(k.split("_"))]
if len(hits) != 1:
continue
owner, child = sub_index[hits[0]]
ckey = to_snake(str(child["name"]))
if ckey not in by_name:
promoted = _promoted(child, owner)
parts.append(promoted)
by_name[ckey] = promoted
with contextlib.suppress(ValueError, KeyError):
owner["children"].remove(child)
notes.append(f"promoted sub-part {owner.get('name')}.{child.get('name')} to a link: "
f"joint {j.get('name')} names it")
j[side] = by_name[ckey].get("name")
notes.append(f"joint {j.get('name')}.{side} '{raw_name}' resolved to sub-part {j[side]}")
# 2. revolute joints with a > 2π range: degrees written for radians → radians; a radian
# range over 2π → continuous
for j in joints:
if j.get("type") != "revolute":
continue
try:
lower, upper = float(j.get("lower", 0.0)), float(j.get("upper", 0.0))
except (TypeError, ValueError):
continue
if upper - lower <= 2 * math.pi + 1e-6:
continue
if _looks_like_degrees(lower, upper):
j.update(lower=math.radians(lower), upper=math.radians(upper))
try:
rest = float(j.get("rest", 0.0))
except (TypeError, ValueError):
rest = None
if rest is not None and lower - 1e-9 <= rest <= upper + 1e-9:
j["rest"] = math.radians(rest)
notes.append(f"joint {j.get('name')}: limits looked like degrees ({lower:g}..{upper:g}) → radians")
lower, upper = float(j["lower"]), float(j["upper"])
span = upper - lower
if span > 2 * math.pi + 1e-6:
j.update(type="continuous", lower=0.0, upper=0.0, rest=0.0)
notes.append(f"joint {j.get('name')}: revolute range {span:.2f} rad > 2π → continuous")
# 2b. swapped or out-of-range limits → swap / clamp (see the docstring)
for j in joints:
if j.get("type") not in ("revolute", "prismatic"):
continue
try:
lower, upper = float(j.get("lower", 0.0)), float(j.get("upper", 0.0))
except (TypeError, ValueError):
continue
if upper < lower:
j["lower"], j["upper"] = upper, lower
notes.append(f"joint {j.get('name')}: limits swapped ({lower:g}..{upper:g} → {upper:g}..{lower:g})")
lower, upper = upper, lower
try:
rest = float(j.get("rest", 0.0))
except (TypeError, ValueError):
continue
if rest < lower - 1e-9 or rest > upper + 1e-9:
j["rest"] = min(max(rest, lower), upper)
notes.append(f"joint {j.get('name')}: rest {rest:g} outside [{lower:g},{upper:g}] → clamped to {j['rest']:g}")
# 3. sub-parts outside the parent bbox → grow the parent
for part in parts:
bounds = _raw_bounds(part.get("bbox"))
if bounds is None:
continue
lo, hi = bounds
grown = False
for child in part.get("children") or []:
cbounds = _raw_bounds(child.get("bbox") if isinstance(child, dict) else None)
if cbounds is None:
continue
clo, chi = cbounds
for a in range(3):
slack = max(SUBPART_SLACK_M, SUBPART_REL_SLACK * abs(hi[a] - lo[a]))
if lo[a] - clo[a] > slack or chi[a] - hi[a] > slack:
lo[a], hi[a] = min(lo[a], clo[a]), max(hi[a], chi[a])
grown = True
notes.append(f"part {part.get('name')}: bbox grown on {'xyz'[a]} around sub-part "
f"{child.get('name')}")
if grown:
part["bbox"] = {"center": [(lo[a] + hi[a]) / 2 for a in range(3)],
"extents": [hi[a] - lo[a] for a in range(3)]}
# 4. root_link that names no part: loose word-match against the part list
root = data.get("root_link")
if isinstance(root, str) and root.strip():
names = {to_snake(p.get("name", "")): p.get("name") for p in parts if p.get("name")}
rk = to_snake(root)
if rk not in names:
# word-boundary rule as in 1b, never bare substring
hits = [orig for k, orig in names.items()
if rk in k.split("_") or k.endswith(f"_{rk}") or k.startswith(f"{rk}_")]
if len(hits) == 1:
notes.append(f"root_link '{root}' named no part; rewrote to '{hits[0]}'")
data["root_link"] = hits[0]
elif not hits:
# 4b. nothing matches: the one part no joint names as a child is the root
children = {to_snake(str(j.get("child", ""))) for j in joints}
roots = [orig for k, orig in names.items() if k not in children]
if len(roots) == 1:
notes.append(f"root_link '{root}' named no part; rewrote to the one link no joint moves: '{roots[0]}'")
data["root_link"] = roots[0]
data["parts"], data["joints"], data["normalisations"] = parts, joints, notes
return data
@model_validator(mode="after")
def _tree(self) -> ArticulatedPlan:
links = {to_snake(p.name) for p in self.parts}
root = to_snake(self.root_link)
if root not in links:
raise ValueError(f"root_link {self.root_link} is not a part")
parent_of: dict[str, str] = {}
for j in self.joints:
p, c = to_snake(j.parent), to_snake(j.child)
if p not in links or c not in links:
unknown = ", ".join(n for n, k in ((j.parent, p), (j.child, c)) if k not in links)
subs = sorted({c.name for part in self.parts for c in part.children})
sub_note = (f" Sub-parts that exist but are NOT links: {', '.join(subs)} — a joint may "
f"only move a top-level part; name one of those exactly to promote it, or a real part."
if subs else "")
raise ValueError(
f"joint {j.name} references unknown link(s) {unknown} — the parts in this plan are: "
f"{', '.join(sorted(links))}. Use those exact names (or add the missing part).{sub_note}")
if c in parent_of:
raise ValueError(f"link {j.child} has two parent joints")
if c == root:
raise ValueError(f"root link {self.root_link} cannot be a joint child")
parent_of[c] = p
# every non-root link must reach root
for link in links - {root}:
seen, cur = set(), link
while cur != root:
if cur in seen or cur not in parent_of:
raise ValueError(f"link {link} is not connected to root {self.root_link} (single-root tree required)")
seen.add(cur)
cur = parent_of[cur]
self._check_mimics()
return self
def _check_mimics(self) -> None:
"""Every coupling must name a joint that exists, moves, and does not loop (``common.mimic_issues``)."""
by_name = {j.name: j for j in self.joints}
issues = mimic_issues([
MimicSpec(key=to_snake(j.name), name=j.name, movable=j.type != "fixed",
target=to_snake(j.mimic.joint) if j.mimic else None,
multiplier=j.mimic.multiplier if j.mimic else 1.0)
for j in self.joints])
for i in issues:
follower = by_name.get(i.joint)
wanted = follower.mimic.joint if follower is not None and follower.mimic else i.target
if i.kind == "out_of_range":
continue # only the lint warns about overshooting a limit
raise ValueError({
"immobile": f"joint {i.joint}: a fixed joint cannot mimic {wanted}",
"zero_multiplier": f"mimic of {wanted}: multiplier 0 means the joint cannot move; use type=fixed",
"self": f"joint {i.joint}: mimics itself",
"unknown_target": f"joint {i.joint}: mimic joint {wanted} is not a joint in this plan; "
f"the joints are: {', '.join(sorted(x.name for x in self.joints))}",
"immobile_target": f"joint {i.joint}: mimics {i.target}, which is fixed and never moves",
"cycle": f"joint {i.joint}: mimic chain loops back through {i.detail}",
}[i.kind])
class ZonePlan(BaseModel):
name: str = Field(description="PascalCase zone name, e.g. Harbour")
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")
#: the asset kinds each scene language plans: ``bpy`` / ``threejs`` = a procedural module,
#: ``blender_glb`` = a hero built as an object and shipped as a GLB
SCENE_ASSET_KINDS: dict[str, tuple[str, ...]] = {
"scene_threejs": ("threejs", "blender_glb"),
"scene_blender": ("bpy", "blender_glb"),
}
#: what ``AssetPlan.kind`` means to the planner of each scene language (scene_threejs keeps the field's own text)
SCENE_KIND_DOCS: dict[str, str] = {
"scene_blender": "bpy = a procedural Blender module (src/assets/<snake>.py, built once at the origin and "
"placed as collection instances); blender_glb = a hero built as an object and shipped as a GLB",
}
class AssetPlan(BaseModel):
name: str = Field(description="PascalCase asset name")
kind: Literal["threejs", "bpy", "blender_glb"] = Field(
description="threejs = procedural module; blender_glb = built with bpy and compiled to a GLB",
# default is scene_threejs's enum; ``scene_plan_schema`` swaps in the language's own
json_schema_extra={"enum": list(SCENE_ASSET_KINDS["scene_threejs"])},
)
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):
name: str
kind: Literal["glsl_material", "postprocess", "particles", "animated_geometry"]
description: str
target: str = Field(default="", description="zone / asset / scene it applies to")
#: a camera name becomes a render filename, so it is charset- and length-bounded
CAMERA_NAME_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")
#: Same name / fov / position rules as ``scene_host.mjs`` validateCameras.
class CameraPlan(BaseModel):
name: str = Field(description="letters/digits/_/- only; it becomes a render filename")
position: Vec3
look_at: Vec3
fov: float = Field(default=50.0, ge=5.0, le=150.0)
purpose: str = Field(default="", description="what the shot is of and what the judge should see in it")
@field_validator("name")
@classmethod
def _filename_safe(cls, v: str) -> str:
"""Reject (never mangle) unsafe names."""
if not CAMERA_NAME_RE.fullmatch(v):
raise ValueError(
f"camera name {v!r} must match [A-Za-z0-9_-]{{1,64}}: it becomes a render "
"filename (no spaces, dots, slashes or other path characters)")
return v
@model_validator(mode="after")
def _looks_somewhere(self) -> CameraPlan:
if all(abs(p - q) < 1e-6 for p, q in zip(self.position, self.look_at, strict=True)):
raise ValueError(f"camera {self.name!r}: position equals look_at (it looks nowhere)")
return self
class ScenePlan(BaseModel):
title: str
summary: str
setting: str = Field(description="place, era, weather, time of day")
mood: str = ""
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, 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,
description="only with interior: the enclosure itself is glass on a metal frame (glasshouse, "
"conservatory, palm house, greenhouse, glass atrium) — the environment builds glass walls and "
"roof on a frame grid, and the sun and the land outside come through them; false for a room "
"with windows",
)
zones: list[ZonePlan] = Field(min_length=1)
assets: list[AssetPlan] = Field(default_factory=list)
effects: list[EffectPlan] = Field(default_factory=list)
animation: list[str] = Field(default_factory=list, description="what moves and how")
cameras: list[CameraPlan] = Field(min_length=1, max_length=6)
acceptance: list[AcceptanceItem] = Field(default_factory=list)
@model_validator(mode="after")
def _names(self) -> ScenePlan:
assets = {to_snake(a.name) for a in self.assets}
zones = set()
for z in self.zones:
k = to_snake(z.name)
if k in zones:
raise ValueError(f"duplicate zone {z.name}")
zones.add(k)
for c in z.contents:
if to_snake(c) not in assets:
raise ValueError(f"zone {z.name} lists unknown asset {c}")
return self
def scene_plan_schema(language: Language | str) -> dict[str, Any]:
"""The ``ScenePlan`` JSON schema for ``language``: ``AssetPlan.kind``'s enum and description
are that language's. ``KeyError`` for a language that plans no scene."""
kinds = SCENE_ASSET_KINDS[Language(language).value]
schema = ScenePlan.model_json_schema()
kind = schema["$defs"]["AssetPlan"]["properties"]["kind"]
kind["enum"] = list(kinds)
doc = SCENE_KIND_DOCS.get(Language(language).value)
if doc:
kind["description"] = doc
return schema
class PassPlan(BaseModel):
name: str = Field(description="PascalCase pass name, e.g. Clouds, Bloom")
kind: Literal["fullscreen", "geometry", "postprocess", "feedback"] = "fullscreen"
description: str = Field(description="what this pass draws / computes, concrete")
elements: list[str] = Field(
default_factory=list, max_length=8,
description="optional: up to 8 named things this pass draws, each with its numbers")
detail_hint: str = Field(default="", description="one line: what makes THIS pass read as real")
class GraphicsPlan(BaseModel):
"""Plan for the graphics track (GLSL shader / raw OpenGL program)."""
title: str
summary: str
style: str = Field(description="visual style: palette, mood, references in words")
resolution: tuple[int, int] = (1280, 720)
duration_s: float = Field(default=8.0, description="loop length for judging / video")
passes: list[PassPlan] = Field(min_length=1)
uniforms: list[str] = Field(default_factory=list, description="uniform names the program exposes (u_time, u_resolution, ...)")
motion: str = Field(default="", description="what animates over time and how")
key_visuals: list[str] = Field(default_factory=list, description="visible elements a viewer must recognise")
acceptance: list[AcceptanceItem] = Field(default_factory=list)
Plan = StaticPlan | ArticulatedPlan | ScenePlan | GraphicsPlan