Skip to content

Official Codebase of 3DCodeVerse

Python

scene lighting: the practical-light numbers are environment.js's PRACTICAL, stated once in the cookbook

gaoypengb2a0b5b341f4
diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js
index 79c2a6bf..9dd026a7 100644
--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js
+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/environment.js
@@ -537,6 +537,15 @@ const RIGS = {
discColor: 0xe9edf2 },
};
+/**
+ * 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`.
+ */
+export const PRACTICAL = Object.freeze({ emissiveIntensity: 3.0, intensity: 1.5, distance: 9, decay: 2 });
+
/**
* The matched sun + fill + environment + sun-disc package. Failing
* scenes break this package piecewise; built here, the env-map sun,
@@ -563,7 +572,7 @@ const RIGS = {
* the shadow frustum must cover (default 150); `azimuth`/`elevation`
* sun direction in degrees (per-mood defaults; golden sits low);
* `sunColor`/`intensity` sun overrides; `fill` hemisphere intensity,
- * clamped UP to the mood's readability floor (night floor 0.55);
+ * clamped UP to the mood's readability floor (its `fillFloor` in RIGS);
* `fillSky`/`fillGround` hex overrides of the hemisphere's colours (the
* baked environment's ground half follows `fillGround`);
* `zenith`/`horizon` hex overrides matching `worldShell()`'s (used by
diff --git a/harness/codeverse3d/prompts/scene_threejs/contract.md b/harness/codeverse3d/prompts/scene_threejs/contract.md
index 722b4072..f3f28d14 100644
--- a/harness/codeverse3d/prompts/scene_threejs/contract.md
+++ b/harness/codeverse3d/prompts/scene_threejs/contract.md
@@ -74,7 +74,8 @@ version of the same effect — the want → call table ships with this brief.
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 peak 1.5–4, not 20. `--no-post` / `C3D_POST=0` turns it off.
+bloom: author them at the cookbook's practical level (`PRACTICAL` in `lib/environment.js`),
+not 20. `--no-post` / `C3D_POST=0` turns it off.
## Forbidden
`document.*` / `window.*` except `window.innerWidth` — never create canvases or DOM;
diff --git a/harness/codeverse3d/prompts/scene_threejs/cookbook.md b/harness/codeverse3d/prompts/scene_threejs/cookbook.md
index 2c5aba53..0925a0bd 100644
--- a/harness/codeverse3d/prompts/scene_threejs/cookbook.md
+++ b/harness/codeverse3d/prompts/scene_threejs/cookbook.md
@@ -299,15 +299,22 @@ must still be something: a haze gradient plus 5–10 silhouette shapes.
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 is an emissive surface plus a small PointLight:
+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: 3.0 });
+ 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, 1.5, 9, 2); light.position.set(x, y, z);
+ 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
});
}
@@ -850,7 +857,8 @@ establishing → mid → detail. Compute positions from measured bounds/heightA
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 (`emissiveIntensity` ≤ 3, no white-out). Do not build an
+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
@@ -890,8 +898,9 @@ still read without it (`emissiveIntensity` ≤ 3, no white-out). Do not build a
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** → 30 PointLights kill the frame; ONE emissive material + 1–2
- real lights near the camera path.
+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
diff --git a/harness/codeverse3d/prompts/scene_threejs/system.md b/harness/codeverse3d/prompts/scene_threejs/system.md
index 9d29d8c5..5a0b6d58 100644
--- a/harness/codeverse3d/prompts/scene_threejs/system.md
+++ b/harness/codeverse3d/prompts/scene_threejs/system.md
@@ -39,9 +39,9 @@ What the gates name, measured over 32 recorded runs of this exact track:
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**: raise
- `emissiveIntensity` on the lamps themselves (2–6), put a `PointLight` (0.5–2) at each
- practical, and give dark materials a low but non-zero base colour so they read as
+ 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.
diff --git a/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md b/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md
index 6cc2101c..f2b0fba2 100644
--- a/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md
+++ b/harness/codeverse3d/skills/c3d-scene-lighting/SKILL.md
@@ -92,15 +92,18 @@ Working numbers for a scene lit from the SKY (day, overcast, dusk), straight fro
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 `emissiveIntensity`
-**2-6** with a PointLight **0.5-2** per practical. If the frame is blown instead: `intensity` at the
-floor, `fill` <= 1.2, sky below 0.9 white, `emissiveIntensity` <= 4 on large surfaces.
+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. One dim moon/sky key at
-**<= 0.2** for shape in the shadows, at most one low ambient **0.06-0.12**, and no
-HemisphereLight and no second DirectionalLight.
+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
@@ -119,10 +122,10 @@ it was not. Check the band on EVERY camera, including the harness rig views nobo
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 needs its OWN `PointLight` next to its emissive surface —
-`decay: 2`, `distance` 12-18 m, `intensity` 6-14, and enough of them (10-16 in a courtyard
-or a street) that the lit pools overlap into a readable picture. The practicals are the
-lighting rig; the emissive is only what the fixture looks like.
+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.
For a flat frame, add contrast rather than light: a shadow-casting key, materials with
genuinely different albedos, and a camera aimed at content rather than at sky.
diff --git a/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md b/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md
index e097a7c1..1c784203 100644
--- a/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md
+++ b/harness/codeverse3d/skills/c3d-scene-materials/SKILL.md
@@ -73,11 +73,11 @@ hovers on a blade of grass — the placement gate measures floaters.
## The tight shadow camera
-One key light (sun) at intensity 2.5-4 with `castShadow`, a dim
-`HemisphereLight` 0.3-0.6 fill with a ground-bounce colour, and no third light
-without a reason. Then TIGHTEN `light.shadow.camera.left/right/top/bottom` to
-the extent the cameras can actually see, `mapSize` 2048-4096: a shadow map
-stretched over two kilometres has metre-wide pixels and every shadow is mush.
+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
diff --git a/harness/tests/prompts/test_snippets_run.py b/harness/tests/prompts/test_snippets_run.py
index 0854b487..f40ac088 100644
--- a/harness/tests/prompts/test_snippets_run.py
+++ b/harness/tests/prompts/test_snippets_run.py
@@ -173,6 +173,7 @@ _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"
)
diff --git a/harness/tests/scene_prompts/test_quality_teaching.py b/harness/tests/scene_prompts/test_quality_teaching.py
index 387f3bbb..4216b7e5 100644
--- a/harness/tests/scene_prompts/test_quality_teaching.py
+++ b/harness/tests/scene_prompts/test_quality_teaching.py
@@ -51,3 +51,30 @@ def test_the_env_and_zone_briefs_hand_the_enclosure_to_env_for_an_interior() ->
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
+
+
+def test_the_practical_light_numbers_are_stated_once_and_are_the_libs() -> None:
+ """Audit N41: one scene session read PointLight 0.5–2 (system prompt, skill) and 6–14 with
+ 10–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."""
+ import re
+
+ from codeverse3d.languages.scene_threejs import lib_files
+ from codeverse3d.skills import skills_dir
+
+ env = next(p for p in lib_files() if p.name == "environment.js").read_text(encoding="utf-8")
+ 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"])
+ 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")}
+ restated = re.compile(r"PointLight\W{0,4}\(?\*{0,2}\d|`intensity` \d|emissive\w*`?\W{0,4}\*{0,2}\d|<= 0\.2|"
+ r"HemisphereLight` \d")
+ assert not {k: restated.findall(v) for k, v in others.items() if restated.search(v)}