Skip to content

Official Codebase of 3DCodeVerse

Python

cameras: a plan camera obeys the host's fov / position rules, and the host grades each camera problem itself

gaoypeng4fef6c601fb7
diff --git a/harness/codeverse3d/contracts/plan.py b/harness/codeverse3d/contracts/plan.py
index 772bbe19..42ab4495 100644
--- a/harness/codeverse3d/contracts/plan.py
+++ b/harness/codeverse3d/contracts/plan.py
@@ -574,11 +574,14 @@ class EffectPlan(BaseModel):
CAMERA_NAME_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")
+#: The scene host (``scene_host.mjs`` validateCameras) states the same name / fov / position
+#: rules for the cameras ``createScene`` returns; a plan that broke them used to validate here and
+#: then draw a WARN on src/scene.js every round that no agent owns (audit 2026-09-24 N10).
class CameraPlan(BaseModel):
name: str = Field(description="letters/digits/_/- only; it becomes a render filename")
position: Vec3
look_at: Vec3
- fov: float = 50.0
+ fov: float = Field(default=50.0, ge=5.0, le=150.0)
purpose: str = ""
@field_validator("name")
@@ -591,6 +594,12 @@ class CameraPlan(BaseModel):
"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
diff --git a/harness/codeverse3d/spatial/probes.py b/harness/codeverse3d/spatial/probes.py
index 2bab6123..406f2f76 100644
--- a/harness/codeverse3d/spatial/probes.py
+++ b/harness/codeverse3d/spatial/probes.py
@@ -140,9 +140,8 @@ def probe_report(summary: dict[str, Any], *, duration_ms: int = 0) -> tuple[Gate
msg += " — " + "; ".join(missing[:4])
findings.append(_f(gate, Severity.ERROR, f"[{stage}] {msg}"[:1500], target="src/scene.js",
hint=_BOOT_HINTS.get(stage, "fix the quoted error"), stage=stage))
- for p in boot.get("camera_problems", []):
- sev = Severity.ERROR if ("no valid cameras" in p or "not an array" in p or "must be" in p) else Severity.WARN
- findings.append(_f(gate, sev, f"cameras: {p}", target="src/scene.js",
+ for p in boot.get("camera_problems", []): # {severity, text}: the host grades each problem
+ findings.append(_f(gate, Severity(p["severity"]), f"cameras: {p['text']}", target="src/scene.js",
hint="cameras: [{name:'overview', position:[x,y,z], lookAt:[x,y,z], fov:50}, ...] (1-6 entries)"))
if boot.get("ok") and s.get("update_ok") is False:
findings.append(_f(gate, Severity.ERROR, f"update(t, dt) threw: {s.get('update_error', '')[:800]}", target="src/scene.js",
diff --git a/harness/runtime_js/lib/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjs
index 8669322d..1c12638c 100644
--- a/harness/runtime_js/lib/scene_host.mjs
+++ b/harness/runtime_js/lib/scene_host.mjs
@@ -88,32 +88,37 @@ function makeHostRenderer(width, height, opts) {
return { renderer: makeRenderer(canvas, width, height, { logDepth: !!opts.logDepth }), canvas };
}
+/** The authored cameras, and each problem as {severity, text}: the severity is decided HERE,
+ * where the problem is known (the python gate used to re-derive it from the wording).
+ * The plan's own cameras pass the same fov / position / name rules (contracts/plan.CameraPlan). */
function validateCameras(raw) {
const out = [];
const problems = [];
+ const error = (text) => problems.push({ severity: 'error', text });
+ const warn = (text) => problems.push({ severity: 'warn', text });
if (!Array.isArray(raw)) {
- problems.push('createScene().cameras is not an array');
+ error('createScene().cameras is not an array');
return { cameras: out, problems };
}
raw.forEach((c, i) => {
const p = c && c.position;
const l = c && c.lookAt;
const okVec = (v) => Array.isArray(v) && v.length === 3 && v.every((x) => Number.isFinite(x));
- if (!c || typeof c !== 'object') { problems.push(`cameras[${i}] is not an object`); return; }
- if (!okVec(p)) { problems.push(`cameras[${i}] position must be [x,y,z] finite numbers`); return; }
- if (!okVec(l)) { problems.push(`cameras[${i}] lookAt must be [x,y,z] finite numbers`); return; }
+ if (!c || typeof c !== 'object') { warn(`cameras[${i}] is not an object`); return; }
+ if (!okVec(p)) { error(`cameras[${i}] position must be [x,y,z] finite numbers`); return; }
+ if (!okVec(l)) { error(`cameras[${i}] lookAt must be [x,y,z] finite numbers`); return; }
const fov = Number.isFinite(c.fov) ? c.fov : 50;
- if (fov < 5 || fov > 150) problems.push(`cameras[${i}] fov ${fov} outside [5,150]`);
- if (p.every((x, k) => Math.abs(x - l[k]) < 1e-6)) problems.push(`cameras[${i}] position equals lookAt`);
+ if (fov < 5 || fov > 150) warn(`cameras[${i}] fov ${fov} outside [5,150]`);
+ if (p.every((x, k) => Math.abs(x - l[k]) < 1e-6)) warn(`cameras[${i}] position equals lookAt`);
const name = String(c.name || `cam_${i}`);
if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
- problems.push(`cameras[${i}] name ${JSON.stringify(name)} must match [A-Za-z0-9_-]{1,64} — it becomes a render filename`);
+ warn(`cameras[${i}] name ${JSON.stringify(name)} must match [A-Za-z0-9_-]{1,64} — it becomes a render filename`);
return;
}
out.push({ name, position: p.map(Number), lookAt: l.map(Number), fov });
});
- if (out.length === 0) problems.push('no valid cameras (author 1-6 {name, position, lookAt, fov})');
- if (out.length > 6) problems.push(`too many cameras (${out.length} > 6)`);
+ if (out.length === 0) error('no valid cameras (author 1-6 {name, position, lookAt, fov})');
+ if (out.length > 6) warn(`too many cameras (${out.length} > 6)`);
return { cameras: out, problems };
}
@@ -277,7 +282,7 @@ async function boot(opts) {
state.scene = result.scene;
state.cameras = cameras;
state.update = typeof result.update === 'function' ? result.update : null;
- if (!state.update) info.camera_problems.push('createScene().update(t, dt) is not a function (scene will be static)');
+ if (!state.update) info.camera_problems.push({ severity: 'warn', text: 'createScene().update(t, dt) is not a function (scene will be static)' });
info.stage = 'loads';
const tLd = performance.now();
@@ -363,7 +368,7 @@ async function boot(opts) {
// validateCameras already said WHY; carry it into the error.
if (!info.ok) {
info.error = 'createScene() returned no usable cameras'
- + (problems.length ? ': ' + problems.join('; ') : '');
+ + (problems.length ? ': ' + problems.map((q) => q.text).join('; ') : '');
}
info.stage = 'ready';
} catch (e) {
diff --git a/harness/tests/core/test_contracts.py b/harness/tests/core/test_contracts.py
index 3f1a0851..0a14ced7 100644
--- a/harness/tests/core/test_contracts.py
+++ b/harness/tests/core/test_contracts.py
@@ -94,6 +94,10 @@ def test_camera_plan_name_must_be_filename_safe():
for bad in ("x/../y", "/absolute", "a\\b", "a b", "a.png", "", "x" * 200):
with pytest.raises(ValidationError):
CameraPlan(name=bad, position=(0, 1.6, 5), look_at=(0, 0, 0))
+ # the scene host's other rules (audit 2026-09-24 N10): a plan camera it would flag fails here
+ for bad in ({"fov": 170}, {"fov": 2}, {"look_at": (0, 1.6, 5)}):
+ with pytest.raises(ValidationError):
+ CameraPlan(**{"name": "cam", "position": (0, 1.6, 5), "look_at": (0, 0, 0), **bad})
def test_budget_is_strict_but_recorded_specs_migrate_the_retired_cost_key():
diff --git a/harness/tests/scene_runtime/test_probes.py b/harness/tests/scene_runtime/test_probes.py
index cdbb4c6a..4f105ba3 100644
--- a/harness/tests/scene_runtime/test_probes.py
+++ b/harness/tests/scene_runtime/test_probes.py
@@ -21,6 +21,17 @@ def test_probe_scene_flags_bad_shape_and_cameras(starter_ws):
assert not gate.passed
assert "position must be [x,y,z]" in msgs and "no valid cameras" in msgs
assert census == {} or census.get("totals", {}).get("meshes") == 1 # census only when booted; boot fails on cameras here
+ # the host grades each camera problem itself ({severity, text}); nothing re-derives it from the wording
+ (starter_ws.src / "scene.js").write_text(
+ "import * as THREE from 'three';\n"
+ "export function createScene() { const scene = new THREE.Scene(); scene.add(new THREE.AmbientLight());\n"
+ " return { scene, update() {}, cameras: [{ name: 'x', position: [3, 3, 3], lookAt: [0, 0, 0], fov: 170 },\n"
+ " { name: 'bad name', position: [3, 3, 3], lookAt: [0, 0, 0] }, { name: 'y', position: [1, 2], lookAt: [0, 0, 0] }] }; }\n"
+ )
+ gate, _ = probe_scene(starter_ws)
+ graded = {f.message: f.severity for f in gate.findings if f.message.startswith("cameras: ")}
+ assert sorted(graded.values()) == ["error", "warn", "warn"], graded
+ assert [m for m, sev in graded.items() if sev == "error"][0].startswith("cameras: cameras[2] position must be")
def test_probe_scene_catches_update_throw_and_console_errors(starter_ws):