3D engine that AI agents drive
WIP sun bounce (part of #462)
Nguyen Xuan Anc6c24a5a71a5
diff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex 8a92ea93..2b579e0a 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -18,6 +18,7 @@ import { applyLightLinks } from '/src/light-linking.js';import { applyWaterReflection, attachWaterReflection } from '/src/water-reflection.js';import { attachScreenSpaceWater } from './ssr-water.js';import { groundBounceEnvironment } from '/src/ground-bounce.js';+import { withSunBounce } from '/src/sun-bounce.js';import { applyDefaultFloorSky, applyFloorSkyVisibility } from '/src/floor-sky-visibility.js';import { installReversedDepth } from '/src/reversed-depth.js';@@ -27,7 +28,10 @@ const GROUND_BOUNCE = new URLSearchParams(location.search).get('groundBounce') !// The scene's environment with the light its floor bounces, when it has a plain one and nothing else gives that light (a bake, a closed room).function withDerivedGroundBounce(scene, drawnParts) {- return GROUND_BOUNCE ? groundBounceEnvironment(drawnParts, scene.environment) : scene.environment;+ const lit = GROUND_BOUNCE ? groundBounceEnvironment(drawnParts, scene.environment) : scene.environment;+ // ?sunBounce=<n> sets environment.sunBounce on every scene (default 1, 0 draws without the sunlit patches' lights).+ const sunBounce = new URLSearchParams(location.search).get('sunBounce');+ return withSunBounce(drawnParts, sunBounce === null ? lit : { ...lit, sunBounce: Number(sunBounce) });}// ?reversedDepth=on draws with reversed-Z (issue #310); the scenes draw with the standard depth buffer otherwise.diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 423a36ff..50fc261e 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -187,7 +187,9 @@ function syncAutomaticGround(record) {// The scene's environment lit by the sky map, with the light its floor bounces (src/ground-bounce.js): a floor part of the// recipe gives its own colour, and the automatic floor gives its own.function litEnvironment(parts, environment, hasAutomaticGround) {- return groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });+ const lit = groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });+ // A closed room a sun lights gets the lights of its sunlit patches (src/sun-bounce.js), once a recipe that names a sun has loaded the module.+ return agentSceneModuleLoaded('sunBounce') ? agentSceneModule('sunBounce').withSunBounce(parts, lit) : lit;}// A renderer takes its cascades at construction, so a change of the count (or of the extent that picks it) rebuilds.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 89393bdf..027d8f40 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -227,6 +227,7 @@ const environment = z.strictObject({lines: lines.nullable().optional(),objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),floorSkyTrace: z.boolean().optional().describe('false turns off the sky traced into floors of sun-lit closed rooms.'),+ sunBounce: z.number().min(0).optional().describe('Light the sunlit patches of a sun-lit closed room bounce on to the room: 0 off, 1 default, above 1 stronger.'),resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),diff --git a/src/agent-look.js b/src/agent-look.jsindex c9735d81..e89f7c3e 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -13,7 +13,7 @@ const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_Aconst ENVIRONMENT_FIELDS = ['world', 'ground', 'setup', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',- 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',+ 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',];const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];@@ -279,6 +279,13 @@ function environmentFrom(input = {}) {}environment.floorSkyTrace = input.floorSkyTrace;}+ // Scales the light the sunlit patches of a sun-lit closed room bounce on (src/sun-bounce.js); 0 turns it off.+ if (input.sunBounce !== undefined) {+ if (typeof input.sunBounce !== 'number' || !Number.isFinite(input.sunBounce) || input.sunBounce < 0) {+ throw new TypeError('environment.sunBounce must be a number of 0 or more.');+ }+ environment.sunBounce = input.sunBounce;+ }// Outlines and line geometry; null clears them. The module checks the fields and loads on demand.if (input.lines !== undefined && input.lines !== null) {environment.lines = copiedJson(agentSceneModule('lineArt').resolveLineArt(input.lines));diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex f29f708e..ad84766c 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -32,6 +32,7 @@ const MODULE_LOADERS = {viewTransform: () => import('./view-transform-shader.js'),coplanar: () => import('./coplanar-overlap.js'),floorSky: () => import('./floor-sky-visibility.js'),+ sunBounce: () => import('./sun-bounce.js'),userPass: () => import('./user-pass.js'),materialSnippet: () => import('./material-snippet.js'),};@@ -75,6 +76,7 @@ const MODULE_MARKERS = {coplanar: ['"resolveCoplanar"'],// A closed room a sun lights gets the floor sky trace by default. The recipe text can not say whether a room is closed, so a recipe that names its sun loads it and the module skips an open scene.floorSky: ['"keyColor"', '"keyIntensity"'],+ sunBounce: ['"keyColor"', '"keyIntensity"'],userPass: ['"postPasses"'],materialSnippet: ['"snippet":{'],};diff --git a/src/agent-scene.js b/src/agent-scene.jsindex ca153ed6..c4b6ea4e 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1422,7 +1422,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {knownKeys(operation, ['type', lookField], 'operation');const patch = operation[lookField];// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.- const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];+ const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);const nestedField = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };diff --git a/src/ground-bounce.js b/src/ground-bounce.jsindex ae6836ae..cf3fb47e 100644--- a/src/ground-bounce.js+++ b/src/ground-bounce.js@@ -184,7 +184,7 @@ function areaFacing(part, viewpoint) {return area}-function partDiffuseAlbedo(material) {+export function partDiffuseAlbedo(material) {const known = groundAlbedo(material)if (known) {return knowndiff --git a/src/sun-bounce.js b/src/sun-bounce.jsnew file mode 100644index 00000000..ae6b5190--- /dev/null+++ b/src/sun-bounce.js@@ -0,0 +1,213 @@+import { buildWorld, cosineDirection, hashUnit, radicalInverse, sceneScale } from './light-bake.js';+import { createTracer } from './ray-query.js';+import { CLOSED_ROOM_SHARE, closedRoomShare } from './closed-room.js';+import { partDiffuseAlbedo } from './ground-bounce.js';+import { MAX_POINT_LIGHTS } from './light-limits.js';++// Light a sunlit patch sends on to the rest of a closed room. The patches are found once, when the scene is prepared: surfaces+// of the room are sampled, the samples the sun reaches (a shadow ray) and that sit inside the room (most of a short cosine ray+// fan hits something) are grouped into a few patches by position and facing, and each patch becomes a point light just above+// it. Its flux is the sun's irradiance times the lit area times the surface's albedo, per colour channel, spread over the+// half space the patch looks into. A wall near a patch then gets more of it than a wall across the room, and a red carpet+// bounces red. It adds no shader code and nothing to the core entry; the cost is one trace when the parts are prepared, and+// one more point light for each patch in every frame.++export const SUN_BOUNCE_PATCH_LIGHTS = 6;+export const SUN_BOUNCE_SAMPLES = 20_000;+const ROOM_RAYS = 8;+// Share of the room rays that must hit something for a lit sample to count as inside the room (a roof's outer side hits nothing).+const ENCLOSED_SHARE = 0.5;+const CLUSTER_PASSES = 6;+// The light stands this many patch radii above its patch: close enough to light the patch's own surroundings, high enough not to+// brighten the patch itself much.+const LIFT_IN_RADII = 1;+// Fitted against Cycles on the reference halls (docs/lighting.md); environment.sunBounce multiplies it.+export const SUN_BOUNCE_GAIN = 1;+const KEY_THRESHOLD = 1e-3;+const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke']);++function isBounceSurface(part) {+ return part.material?.alphaMode !== 'blend' && !((part.material?.emission ?? 0) > 0) && !EXCLUDED_TAGS.has(part.material?.tag);+}++function sunOf(environment) {+ const keyColor = environment.keyColor ?? [1, 1, 1];+ const keyIntensity = environment.keyIntensity ?? 1;+ const length = Math.hypot(...environment.lightDirection);+ return { irradiance: keyColor.map(channel => channel * keyIntensity), direction: environment.lightDirection.map(component => component / length) };+}++function hasSun(environment) {+ const keyColor = environment.keyColor ?? [1, 1, 1];+ return Boolean(environment.lightDirection) && (environment.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]) > KEY_THRESHOLD;+}++// Lit, enclosed samples of the room's surfaces: position, outward normal and the flux the sample reflects, per channel.+function sampleLitSurfaces(parts, sun) {+ const world = buildWorld(parts);+ const tracer = createTracer(world);+ const offset = sceneScale(world.positions) * 1e-4;+ const { positions, indices, triangleOwner } = world;+ const albedoOfPart = parts.map(part => partDiffuseAlbedo(part.material ?? {}));+ const triangleCount = indices.length / 3;+ const corner = (triangle, slot, axis) => positions[indices[triangle * 3 + slot] * 3 + axis];+ const normals = new Float32Array(triangleCount * 3);+ const areas = new Float32Array(triangleCount);+ let sunFacingArea = 0;+ for (let triangle = 0; triangle < triangleCount; triangle++) {+ const edgeOne = [0, 1, 2].map(axis => corner(triangle, 1, axis) - corner(triangle, 0, axis));+ const edgeTwo = [0, 1, 2].map(axis => corner(triangle, 2, axis) - corner(triangle, 0, axis));+ const cross = [edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1], edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2], edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]];+ const length = Math.hypot(...cross);+ if (length < 1e-12) continue;+ areas[triangle] = length / 2;+ for (let axis = 0; axis < 3; axis++) normals[triangle * 3 + axis] = cross[axis] / length;+ const cosine = normals[triangle * 3] * sun.direction[0] + normals[triangle * 3 + 1] * sun.direction[1] + normals[triangle * 3 + 2] * sun.direction[2];+ if (cosine > 0 && isBounceSurface(parts[triangleOwner[triangle]])) sunFacingArea += areas[triangle];+ }+ const sampleArea = sunFacingArea / SUN_BOUNCE_SAMPLES;+ const samples = [];+ const fan = [0, 0, 0];+ let carried = 0;+ for (let triangle = 0; triangle < triangleCount; triangle++) {+ const normal = [normals[triangle * 3], normals[triangle * 3 + 1], normals[triangle * 3 + 2]];+ const cosine = normal[0] * sun.direction[0] + normal[1] * sun.direction[1] + normal[2] * sun.direction[2];+ if (cosine <= 0 || areas[triangle] === 0 || !isBounceSurface(parts[triangleOwner[triangle]])) continue;+ carried += areas[triangle] / sampleArea;+ for (let slot = 0; carried >= 1; slot++, carried -= 1) {+ let firstWeight = hashUnit(triangle, slot, 1);+ let secondWeight = hashUnit(triangle, slot, 2);+ if (firstWeight + secondWeight > 1) {+ firstWeight = 1 - firstWeight;+ secondWeight = 1 - secondWeight;+ }+ const point = [0, 1, 2].map(axis => corner(triangle, 0, axis) + firstWeight * (corner(triangle, 1, axis) - corner(triangle, 0, axis)) + secondWeight * (corner(triangle, 2, axis) - corner(triangle, 0, axis)));+ const origin = point.map((value, axis) => value + normal[axis] * offset);+ if (tracer.trace(origin[0], origin[1], origin[2], sun.direction[0], sun.direction[1], sun.direction[2], Infinity, true).nearestTriangle >= 0) continue;+ let blocked = 0;+ for (let ray = 0; ray < ROOM_RAYS; ray++) {+ cosineDirection(normal, (ray + 0.5) / ROOM_RAYS, radicalInverse(ray + 1), fan);+ if (tracer.trace(origin[0], origin[1], origin[2], fan[0], fan[1], fan[2], Infinity, true).nearestTriangle >= 0) blocked++;+ }+ if (blocked / ROOM_RAYS < ENCLOSED_SHARE) continue;+ const albedo = albedoOfPart[triangleOwner[triangle]];+ samples.push({ point, normal, flux: sun.irradiance.map((channel, index) => channel * cosine * sampleArea * albedo[index]) });+ }+ }+ return samples;+}++function luminanceOf(flux) {+ return flux[0] + flux[1] + flux[2];+}++// Groups samples into `count` patches by position and facing (weighted by flux), starting from the farthest-apart heavy samples.+function clusterSamples(samples, count, scale) {+ const features = samples.map(sample => [...sample.point, ...sample.normal.map(component => component * scale)]);+ const distance = (first, second) => first.reduce((total, value, index) => total + (value - second[index]) ** 2, 0);+ const centres = [features[samples.reduce((best, sample, index) => (luminanceOf(sample.flux) > luminanceOf(samples[best].flux) ? index : best), 0)]];+ const nearest = features.map(feature => distance(feature, centres[0]));+ while (centres.length < count) {+ let best = 0;+ for (let index = 1; index < samples.length; index++) {+ if (nearest[index] * luminanceOf(samples[index].flux) > nearest[best] * luminanceOf(samples[best].flux)) best = index;+ }+ if (nearest[best] === 0) break;+ centres.push(features[best]);+ features.forEach((feature, index) => { nearest[index] = Math.min(nearest[index], distance(feature, features[best])); });+ }+ const assignment = new Int32Array(samples.length);+ for (let pass = 0; pass < CLUSTER_PASSES; pass++) {+ const sums = centres.map(() => ({ weight: 0, total: new Array(6).fill(0) }));+ features.forEach((feature, index) => {+ let closest = 0;+ for (let centre = 1; centre < centres.length; centre++) {+ if (distance(feature, centres[centre]) < distance(feature, centres[closest])) closest = centre;+ }+ assignment[index] = closest;+ const weight = luminanceOf(samples[index].flux);+ sums[closest].weight += weight;+ feature.forEach((value, axis) => { sums[closest].total[axis] += value * weight; });+ });+ sums.forEach((sum, centre) => {+ if (sum.weight > 0) centres[centre] = sum.total.map(value => value / sum.weight);+ });+ }+ return centres.map((centre, index) => samples.filter((sample, sampleIndex) => assignment[sampleIndex] === index)).filter(group => group.length > 0);+}++function lightOfPatch(group, strength) {+ const flux = [0, 0, 0];+ const centre = [0, 0, 0];+ const facing = [0, 0, 0];+ let weight = 0;+ for (const sample of group) {+ const sampleWeight = luminanceOf(sample.flux);+ weight += sampleWeight;+ for (let axis = 0; axis < 3; axis++) {+ flux[axis] += sample.flux[axis];+ centre[axis] += sample.point[axis] * sampleWeight;+ facing[axis] += sample.normal[axis] * sampleWeight;+ }+ }+ const facingLength = Math.hypot(...facing) || 1;+ const normal = facing.map(component => component / facingLength);+ const middle = centre.map(component => component / weight);+ const radius = Math.sqrt(group.reduce((total, sample) => total + luminanceOf(sample.flux) * sample.point.reduce((sum, value, axis) => sum + (value - middle[axis]) ** 2, 0), 0) / weight);+ const lift = Math.max(radius * LIFT_IN_RADII, 0.05);+ // Spread over the half space in front of the patch: intensity = flux / (2 pi).+ const intensity = flux.map(channel => (strength * SUN_BOUNCE_GAIN * channel) / (2 * Math.PI));+ const peak = Math.max(...intensity, 1e-9);+ return { position: middle.map((value, axis) => value + normal[axis] * lift), color: intensity.map(channel => Math.min(channel / peak, 1)), intensity: Math.min(peak, 1e5), radius: lift };+}++/**+ * The point lights that stand for the sunlit patches of a closed room: `[]` when the scene has no sun, is not a closed room,+ * is drawn with a bake or has no lit, enclosed surface. `strength` multiplies every light (`environment.sunBounce`).+ * `maximumLights` caps how many patches there are.+ */+export function findSunBounceLights(parts, environment, { strength = 1, maximumLights = SUN_BOUNCE_PATCH_LIGHTS } = {}) {+ if (strength <= 0 || maximumLights <= 0 || !hasSun(environment) || parts.some(part => part.material?.lightMap)) return [];+ const share = closedRoomShare(parts, new Map(parts.map(part => [part.name, part.matrix])));+ if (share === null || share < CLOSED_ROOM_SHARE) return [];+ const surfaces = parts.filter(isBounceSurface);+ const sun = sunOf(environment);+ let samples;+ try {+ samples = sampleLitSurfaces(surfaces, sun);+ } catch {+ return [];+ }+ if (samples.length === 0) return [];+ const sceneSize = Math.max(...[0, 1, 2].map(axis => Math.max(...samples.map(sample => sample.point[axis])) - Math.min(...samples.map(sample => sample.point[axis]))), 1e-3);+ return clusterSamples(samples, maximumLights, sceneSize).map(group => lightOfPatch(group, strength));+}++const lightsOfParts = new WeakMap();++/**+ * The environment with the sunlit patches' lights added to its point lights. `environment.sunBounce` (default 1) scales+ * them; 0 returns the environment itself. The patches are found once for these parts and this sun and kept.+ */+export function withSunBounce(parts, environment) {+ const strength = environment.sunBounce ?? 1;+ if (strength <= 0 || !hasSun(environment)) return environment;+ const existing = environment.pointLights ?? [];+ const room = Math.min(SUN_BOUNCE_PATCH_LIGHTS, MAX_POINT_LIGHTS - existing.length);+ const key = JSON.stringify([parts.length, environment.keyColor, environment.keyIntensity, environment.lightDirection, room]);+ let remembered = lightsOfParts.get(parts);+ if (remembered?.key !== key) {+ remembered = { key, lights: findSunBounceLights(parts, environment, { strength: 1, maximumLights: room }), scaled: new Map() };+ lightsOfParts.set(parts, remembered);+ }+ if (remembered.lights.length === 0) return environment;+ if (!remembered.scaled.has(strength)) {+ remembered.scaled.set(strength, remembered.lights.map(light => scaledLight(light, strength)));+ }+ return { ...environment, pointLights: [...existing, ...remembered.scaled.get(strength)] };+}++function scaledLight(light, strength) {+ const peak = light.intensity * strength;+ return { ...light, intensity: Math.min(peak, 1e5) };+}