Skip to content

3D engine that AI agents drive

28.2 KB
Raw Blame
import { lightLimitAdvice } from './light-limit-advice.js';
import { invalidField, withFieldPrefix } from './field-error.js';
import { mat4 } from 'gl-matrix';
import { sceneBoundsOfParts } from './near-plane-fit.js';
import { createLightingState, updateLightingState, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS, MAXIMUM_SPECULAR_ANTI_ALIASING } from './lighting.js';
import { resolveEffects } from './effects.js';
import { resolveVolumeFog } from './volumetric.js';
import { resolveFogDetail } from './fog-field.js';
import { resolveLocalVolumesWith } from './local-volume-resolve.js';
import { LIQUID_OPTICS, resolveLiquidOptics } from './liquid-optics.js';
import { createLightingSetupMap, createCatalogEnvironmentMap, lightingSetupFields } from './lighting-setups.js';
import { agentSceneModule } from './agent-scene-modules.js';
import { lightShapeSupport, postStepSupport } from './shader-registry.js';
import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from './view-transform-names.js';
import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, isEnvironmentReference, isCubeLookReference } from './look-catalog.js';
import { DEFAULT_LIGHTING_SETUP, LIGHTING_SETUP_NAMES, DEFAULT_AMBIENT_OCCLUSION } from './agent-scene-capabilities.js';

// Grid volumes resolve in the volumeGrid module, which loads when a recipe names shape "grid".
function resolveGridVolumeOnDemand(input, resolved, label) {
  return agentSceneModule('volumeGrid').resolveGridVolume(input, resolved, label);
}

// The emission ramp of a local volume resolves in the volumeRamp module, which loads when a recipe names emissionRamp.
function resolveEmissionRampOnDemand(input, shape, label) {
  return agentSceneModule('volumeRamp').resolveEmissionRamp(input, shape, label);
}

// The longest list in a look is the longest light list.
const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS);

const ENVIRONMENT_FIELDS = [
  'world', 'ground', 'setup', 'hdri', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',
  'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'localVolumes', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind', 'sky',
];
const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];
const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];
const POINT_LIGHT_FIELDS = ['position', 'color', 'intensity', 'radius', 'range', 'castShadow', 'softFalloff', 'affects'];
const SPOT_LIGHT_FIELDS = ['position', 'direction', 'angle', 'penumbra', 'color', 'intensity', 'radius', 'range', 'castShadow', 'softFalloff', 'ies', 'affects'];
const AREA_LIGHT_FIELDS = ['position', 'direction', 'up', 'width', 'height', 'color', 'intensity', 'castShadow', 'ies', 'portal', 'affects'];
const VOLUME_VECTOR_FIELDS = ['minimum', 'maximum', 'color', 'ambient', 'drift'];
const VOLUME_NUMBER_FIELDS = ['density', 'steps', 'anisotropy', 'noiseAmount', 'noiseScale', 'maxDistance', 'shadowAmbient', 'heightFalloff', 'detailOctaves', 'detailAmount', 'warp', 'contrast', 'profileSoftness', 'keyScattering', 'scatterOctaves', 'multiScatter', 'multiExtinction', 'multiAnisotropy', 'keyTransmittance', 'surfaceTransmittance', 'beamRadius'];
export const VOLUME_FOG_FIELDS = Object.freeze([...VOLUME_VECTOR_FIELDS, ...VOLUME_NUMBER_FIELDS]);
const BLOOM_FIELDS = ['strength', 'threshold', 'radius'];
const DEPTH_OF_FIELD_FIELDS = ['blur', 'focusDistance'];
const MOTION_BLUR_FIELDS = ['shutter', 'objects'];
const MAXIMUM_SHADOW_CASCADES = 4;
const MAXIMUM_AFFECTED_NODES = 1024;

// Only a light that is linked carries the field, so recipes without links keep their exported shape.
function affectsFrom(light, label) {
  if (light.affects === undefined) {
    return {};
  }
  const names = light.affects;
  if (!Array.isArray(names) || names.length > MAXIMUM_AFFECTED_NODES || names.some(name => typeof name !== 'string' || name.length < 1 || name.length > 128)) {
    throw new TypeError(`${label} affects must be a list of at most ${MAXIMUM_AFFECTED_NODES} node IDs.`);
  }
  return { affects: [...names] };
}

function shadowCascadesFrom(value) {
  if (!Number.isInteger(value) || value < 0 || value > MAXIMUM_SHADOW_CASCADES) {
    throw new RangeError(`environment.shadowCascades must be an integer from 1 to ${MAXIMUM_SHADOW_CASCADES}, or 0 for the single shadow map.`);
  }
  return value;
}

/** Whether any light of the environment is limited to a list of nodes. */
export function environmentLinksLights(environment) {
  const lights = [...(environment.pointLights ?? []), ...(environment.spotLights ?? []), ...(environment.areaLights ?? [])];
  return environment.keyAffects !== undefined || lights.some(light => light.affects !== undefined);
}


function plainObject(value, label) {
  if (!value || typeof value !== 'object' || Array.isArray(value) ||
      (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
    throw new TypeError(`${label} must be a plain JSON object.`);
  }
}

function knownKeys(value, fields, label) {
  plainObject(value, label);
  for (const key of Reflect.ownKeys(value)) {
    if (typeof key !== 'string' || !fields.includes(key)) {
      throw new TypeError(`Unknown ${label} field: ${String(key)}. Use ${fields.join(', ')}.`);
    }
  }
}

// Domain resolvers accept ordinary values. Copy descriptors first so accessors never execute.
// A grid sequence (environment.localVolumes[].frames) may list as many names as local-volume-grid.js allows; keep this in step with VOLUME_GRID_SEQUENCE_MAX_FRAMES.
const MAX_FRAME_NAMES = 512;

function copiedJson(input, depth = 0, ancestors = new Set(), arrayLimit = MAX_LOOK_ARRAY_ENTRIES) {
  if (depth > 32) {
    throw new RangeError('Look JSON nesting exceeds 32 levels.');
  }
  if (input === null || typeof input === 'boolean' || typeof input === 'string') {
    return input;
  }
  if (typeof input === 'number') {
    if (!Number.isFinite(input) || !Number.isFinite(Math.fround(input))) {
      throw new TypeError('Look JSON numbers must be finite Float32 values.');
    }
    return input;
  }
  if (!input || typeof input !== 'object' || ancestors.has(input)) {
    throw new TypeError('Look must contain acyclic plain JSON data.');
  }
  const array = Array.isArray(input);
  if (array && (Object.getPrototypeOf(input) !== Array.prototype || input.length > arrayLimit)) {
    throw new TypeError(`Look JSON arrays must be ordinary arrays with at most ${arrayLimit} entries.`);
  }
  if (!array) {
    plainObject(input, 'Look');
  }
  ancestors.add(input);
  const result = array ? [] : {};
  for (const key of Reflect.ownKeys(input)) {
    if (array && key === 'length') {
      continue;
    }
    if (typeof key !== 'string' || key === '__proto__') {
      throw new TypeError('Look JSON keys must be ordinary strings.');
    }
    const descriptor = Object.getOwnPropertyDescriptor(input, key);
    if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
      throw new TypeError('Look JSON accessors and hidden fields are unsupported.');
    }
    if (array && key !== String(result.length)) {
      throw new TypeError('Look JSON arrays must be dense without extra fields.');
    }
    result[key] = copiedJson(descriptor.value, depth + 1, ancestors, key === 'frames' ? MAX_FRAME_NAMES : MAX_LOOK_ARRAY_ENTRIES);
  }
  if (array && result.length !== input.length) {
    throw new TypeError('Look JSON arrays cannot contain trailing holes.');
  }
  ancestors.delete(input);
  return result;
}

function exampleInRange(minimum, maximum) {
  if (minimum <= 1 && maximum >= 1) return '1';
  return String(minimum > 0 ? minimum : maximum);
}

function numberInRange(value, minimum, maximum, label) {
  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isFinite(Math.fround(value)) ||
      value < minimum || value > maximum) {
    const unbounded = minimum < -1e30 && maximum > 1e30;
    throw invalidField(label, value, unbounded ? 'a finite number, such as 0.5' : `a number from ${minimum} to ${maximum}, such as ${exampleInRange(minimum, maximum)}`);
  }
  return value;
}

function vectorInRange(value, minimum, maximum, label) {
  if (!Array.isArray(value) || value.length !== 3) {
    const example = exampleInRange(minimum, maximum);
    throw invalidField(label, value, `an array of three numbers from ${minimum} to ${maximum}, such as [${example}, ${example}, ${example}]`, TypeError);
  }
  return value.map((component, index) => numberInRange(component, minimum, maximum, `${label}[${index}]`));
}

function fallback(value, defaultValue) {
  return value === undefined ? defaultValue : value;
}

function directionFrom(value, label = 'lightDirection') {
  const direction = vectorInRange(value, -1e6, 1e6, label);
  const length = Math.hypot(...direction);
  if (length < 1e-6) {
    throw invalidField(label, direction, 'a direction that is not all zero, such as [0, -1, 0]');
  }
  return { direction, unitDirection: direction.map(component => component / length) };
}

function lightListFrom(value, maximum, name) {
  const lights = fallback(value, []);
  if (!Array.isArray(lights) || lights.length > maximum) {
    const advice = Array.isArray(lights) ? `; ${lightLimitAdvice(name.split('.').pop())}` : '';
    throw invalidField(name, Array.isArray(lights) ? `${lights.length} entries` : lights, `an array of at most ${maximum} lights, such as []${advice}`);
  }
  return lights;
}

function rangeFrom(light) {
  const range = numberInRange(fallback(light.range, 0), 0, 1e6, 'range');
  if (range !== 0 && range < 0.001) {
    throw invalidField('range', range, '0 for unlimited, or at least 0.001, such as 10');
  }
  return range;
}

// A light carries castShadow or softFalloff (an oriented disk, as Blender's Soft Falloff) only when true, so recipes without them keep their exported shape.
function lightFlagFrom(light, name) {
  const flag = fallback(light[name], false);
  if (typeof flag !== 'boolean') {
    throw invalidField(name, flag, 'true or false', TypeError);
  }
  return flag ? { [name]: flag } : {};
}

const shadowFieldFrom = light => lightFlagFrom(light, 'castShadow');
const softFalloffFieldFrom = light => lightFlagFrom(light, 'softFalloff');

// A portal is a rect area light that marks a window: Cook draws sky light through it and it emits nothing itself.
function portalFieldFrom(light) {
  const flag = fallback(light.portal, false);
  if (typeof flag !== 'boolean') {
    throw invalidField('portal', flag, 'true to mark a window (a rect area light with width and height above 0), or false', TypeError);
  }
  return flag ? { portal: true } : {};
}

function pointLightFrom(light) {
  knownKeys(light, POINT_LIGHT_FIELDS, 'point light');
  return {
    position: vectorInRange(light.position, -1e6, 1e6, 'position'),
    color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
    intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
    radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'radius'),
    range: rangeFrom(light),
    ...shadowFieldFrom(light),
    ...softFalloffFieldFrom(light),
    ...affectsFrom(light, 'point light'),
  };
}

function spotLightFrom(light) {
  knownKeys(light, SPOT_LIGHT_FIELDS, 'spot light');
  return {
    position: vectorInRange(light.position, -1e6, 1e6, 'position'),
    direction: directionFrom(light.direction, 'direction').direction,
    angle: numberInRange(fallback(light.angle, Math.PI / 4), 0.01, Math.PI / 2 - 0.01, 'angle'),
    penumbra: numberInRange(fallback(light.penumbra, 0.15), 0, 1, 'penumbra'),
    color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
    intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
    radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'radius'),
    range: rangeFrom(light),
    ...shadowFieldFrom(light),
    ...softFalloffFieldFrom(light),
    ...affectsFrom(light, 'spot light'),
  };
}

function areaLightFrom(light) {
  knownKeys(light, AREA_LIGHT_FIELDS, 'area light');
  const resolved = {
    position: vectorInRange(light.position, -1e6, 1e6, 'position'),
    direction: directionFrom(light.direction, 'direction').direction,
    width: numberInRange(light.width, 0.001, 1e4, 'width'),
    height: numberInRange(light.height, 0.001, 1e4, 'height'),
    color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
    intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
  };
  if (light.up !== undefined) resolved.up = directionFrom(light.up, 'up').direction;
  return { ...resolved, ...portalFieldFrom(light), ...affectsFrom(light, 'area light') };
}

function volumeFogFrom(input = {}) {
  knownKeys(input, VOLUME_FOG_FIELDS, 'volumeFog');
  for (const field of VOLUME_VECTOR_FIELDS) {
    if (Object.hasOwn(input, field)) {
      vectorInRange(input[field], -1e5, 1e5, `volumeFog.${field}`);
    }
  }
  for (const field of VOLUME_NUMBER_FIELDS) {
    if (Object.hasOwn(input, field)) {
      numberInRange(input[field], -Number.MAX_VALUE, Number.MAX_VALUE, `volumeFog.${field}`);
    }
  }
  const resolved = resolveVolumeFog(input);
  resolveFogDetail(resolved);
  return copiedJson(resolved);
}

/** The fields a physical sky fills from its sun and haze that a recipe may still set itself: its own value wins over the sky's. */
export const SKY_OVERRIDABLE_FIELDS = Object.freeze(['keyColor', 'fogColor', 'fogDensity']);

function environmentFrom(input = {}) {
  knownKeys(input, ENVIRONMENT_FIELDS, 'environment');
  const world = fallback(input.world, false);
  if (typeof world !== 'boolean') {
    throw invalidField('environment.world', world, 'true or false', TypeError);
  }
  const setup = fallback(input.setup, DEFAULT_LIGHTING_SETUP);
  if (!LIGHTING_SETUP_NAMES.includes(setup)) {
    throw invalidField('environment.setup', setup, `one of ${LIGHTING_SETUP_NAMES.join(', ')}`);
  }
  const defaults = lightingSetupFields(setup);
  const environment = {
    world,
    setup,
    environmentIntensity: numberInRange(fallback(input.environmentIntensity, 1), 0, 100, 'environment.environmentIntensity'),
    environmentRotation: numberInRange(fallback(input.environmentRotation, 0), -100, 100, 'environment.environmentRotation'),
    lightDirection: directionFrom(fallback(input.lightDirection, defaults.lightDirection), 'environment.lightDirection').direction,
    keyColor: vectorInRange(fallback(input.keyColor, defaults.keyColor), 0, 1000, 'environment.keyColor'),
    keyIntensity: numberInRange(fallback(input.keyIntensity, defaults.keyIntensity), 0, 100, 'environment.keyIntensity'),
    fillIntensity: numberInRange(fallback(input.fillIntensity, defaults.fillIntensity), 0, 100, 'environment.fillIntensity'),
    ambientIntensity: numberInRange(fallback(input.ambientIntensity, defaults.ambientIntensity), 0, 100, 'environment.ambientIntensity'),
    daylight: numberInRange(fallback(input.daylight, 1), 0, 100, 'environment.daylight'),
    pointLights: lightListFrom(input.pointLights, MAX_POINT_LIGHTS, 'environment.pointLights').map((light, index) => withFieldPrefix(`environment.pointLights[${index}]`, () => pointLightFrom(light))),
    skyTop: vectorInRange(fallback(input.skyTop, defaults.skyTop), 0, 1, 'environment.skyTop'),
    skyBottom: vectorInRange(fallback(input.skyBottom, defaults.skyBottom), 0, 1, 'environment.skyBottom'),
    fogColor: vectorInRange(fallback(input.fogColor, [0.35, 0.43, 0.43]), 0, 1, 'environment.fogColor'),
    fogDensity: input.fogDensity === undefined || input.fogDensity === null ? null : numberInRange(input.fogDensity, 0, 10, 'environment.fogDensity'),
    volumeFog: volumeFogFrom(input.volumeFog),
  };
  // Optional so recipes without these fields keep their exported shape.
  if (input.ground !== undefined) {
    if (typeof input.ground !== 'boolean') {
      throw invalidField('environment.ground', input.ground, 'true or false', TypeError);
    }
    environment.ground = input.ground;
  }
  if (input.objectReflections !== undefined) {
    if (typeof input.objectReflections !== 'boolean') {
      throw invalidField('environment.objectReflections', input.objectReflections, 'true or false', TypeError);
    }
    environment.objectReflections = input.objectReflections;
  }
  // `false` opts out of the floor sky trace that src/floor-sky-visibility.js gives sun-lit closed rooms.
  if (input.floorSkyTrace !== undefined) {
    if (typeof input.floorSkyTrace !== 'boolean') {
      throw invalidField('environment.floorSkyTrace', input.floorSkyTrace, 'true or false', TypeError);
    }
    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 (!Number.isFinite(input.sunBounce) || input.sunBounce < 0) {
      throw invalidField('environment.sunBounce', input.sunBounce, 'a number of 0 or more, such as 1', TypeError);
    }
    environment.sunBounce = input.sunBounce;
  }
  // Strength of the specular anti-aliasing that widens highlights where normals or normal map detail change within a pixel (src/lighting.js); 0 turns it off.
  if (input.specularAntiAliasing !== undefined) {
    environment.specularAntiAliasing = numberInRange(input.specularAntiAliasing, 0, MAXIMUM_SPECULAR_ANTI_ALIASING, 'environment.specularAntiAliasing');
  }
  // 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));
  }
  if (input.resolveCoplanar !== undefined) {
    if (input.resolveCoplanar !== 'offset' && input.resolveCoplanar !== false) {
      throw invalidField('environment.resolveCoplanar', input.resolveCoplanar, "'offset' or false", TypeError);
    }
    environment.resolveCoplanar = input.resolveCoplanar;
  }
  if (input.spotLights !== undefined) {
    environment.spotLights = lightListFrom(input.spotLights, MAX_SPOT_LIGHTS, 'environment.spotLights').map((light, index) => withFieldPrefix(`environment.spotLights[${index}]`, () => spotLightFrom(light)));
  }
  if (input.areaLights !== undefined) {
    environment.areaLights = lightListFrom(input.areaLights, MAX_AREA_LIGHTS, 'environment.areaLights').map((light, index) => withFieldPrefix(`environment.areaLights[${index}]`, () => areaLightFrom(light)));
  }
  // Optional like the lights above, so a recipe without local volumes keeps its exported shape.
  if (input.localVolumes !== undefined) {
    environment.localVolumes = copiedJson(resolveLocalVolumesWith(resolveGridVolumeOnDemand, input.localVolumes, 'environment.localVolumes', resolveEmissionRampOnDemand));
  }
  if (input.shadowCascades !== undefined) {
    environment.shadowCascades = shadowCascadesFrom(input.shadowCascades);
  }
  if (input.wind !== undefined && input.wind !== null) environment.wind = agentSceneModule('vegetation').normalizeWind(input.wind);
  // A catalog HDRI replaces the procedural sky map. The setup still supplies the key light: set keyIntensity 0 when the HDRI has its own sun.
  if (input.hdri !== undefined && input.hdri !== null) {
    if (typeof input.hdri !== 'string' || !isEnvironmentReference(input.hdri)) {
      throw invalidField('environment.hdri', input.hdri, `one of ${BUNDLED_ENVIRONMENT_NAMES.join(', ')} or the 64-character ID of a .hdr file in the asset catalog`);
    }
    environment.hdri = input.hdri;
  }
  if (input.viewTransform !== undefined) {
    if (!VIEW_TRANSFORM_NAMES.includes(input.viewTransform)) {
      throw invalidField('environment.viewTransform', input.viewTransform, `one of ${VIEW_TRANSFORM_NAMES.join(', ')}`);
    }
    environment.viewTransform = input.viewTransform;
  }
  if (input.look !== undefined && input.look !== null) {
    if (!LOOK_NAMES.includes(input.look) && !isCubeLookReference(input.look)) {
      throw invalidField('environment.look', input.look, `one of ${[...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES].join(', ')} or the 64-character ID of a .cube file in the asset catalog`);
    }
    environment.look = input.look;
  }
  if (input.keyAffects !== undefined) {
    environment.keyAffects = affectsFrom({ affects: input.keyAffects }, 'environment keyAffects').affects;
  }
  if (input.liquid !== undefined) {
    knownKeys(input.liquid, Object.keys(LIQUID_OPTICS), 'liquid');
    environment.liquid = copiedJson(resolveLiquidOptics(copiedJson(input.liquid)));
  }
  if (input.sky !== undefined && input.sky !== null) {
    // The sky derives these from its sun; a value written beside the sky is a choice and stays.
    const explicit = Object.fromEntries(SKY_OVERRIDABLE_FIELDS.filter(field => input[field] !== undefined && input[field] !== null).map(field => [field, environment[field]]));
    agentSceneModule('physicalSky').applyPhysicalSky(input.sky, environment, invalidField);
    Object.assign(environment, explicit);
  }
  lightShapeSupport.normalize?.(input, environment);
  updateLightingState(createLightingState(), environment, { world });
  return environment;
}

/**
 * Setup-derived fields come with the setup name, so switching setups never keeps the old key light.
 * Fields in the patch itself still win.
 */
export function environmentPatchWithSetup(patch) {
  if (patch.setup === undefined) {
    return patch;
  }
  return { ...lightingSetupFields(patch.setup), ...patch };
}

/** The procedural environment map that lights a normalized environment; the same object returns while inputs hold. */
export function agentEnvironmentMap(environment) {
  if (environment.sky) {
    return agentSceneModule('physicalSky').createPhysicalSkyMap(environment);
  }
  if (environment.hdri) {
    return createCatalogEnvironmentMap(environment.hdri, { intensity: environment.environmentIntensity, rotation: environment.environmentRotation, showBackground: environment.world });
  }
  return createLightingSetupMap(environment.setup, {
    intensity: environment.environmentIntensity,
    rotation: environment.environmentRotation,
    showBackground: environment.world,
  });
}

function effectsFrom(input = {}) {
  knownKeys(input, [...EFFECT_FIELDS, ...postStepSupport.fields], 'effects');
  const groupFields = { bloom: BLOOM_FIELDS, depthOfField: DEPTH_OF_FIELD_FIELDS, motionBlur: MOTION_BLUR_FIELDS };
  for (const field of EFFECT_FIELDS) {
    if (!(field in groupFields) && Object.hasOwn(input, field)) {
      numberInRange(input[field], -Number.MAX_VALUE, Number.MAX_VALUE, `effects.${field}`);
    }
  }
  const groups = {};
  for (const [group, fields] of Object.entries(groupFields)) {
    groups[group] = fallback(input[group], {});
    knownKeys(groups[group], fields, group);
    for (const field of fields) {
      if (Object.hasOwn(groups[group], field)) {
        numberInRange(groups[group][field], -Number.MAX_VALUE, Number.MAX_VALUE, `${group}.${field}`);
      }
    }
  }
  const ambientOcclusion = fallback(input.ambientOcclusion, DEFAULT_AMBIENT_OCCLUSION);
  const resolved = resolveEffects({ ...input, ambientOcclusion, ...groups, bloom: { strength: 0.12, threshold: 1, radius: 1, ...groups.bloom } });
  return { ...resolved, exposure: numberInRange(fallback(input.exposure, 1), 0.01, 16, 'exposure'), ...postStepSupport.resolve?.(input) };
}

function shadowFrom(input = {}) {
  knownKeys(input, SHADOW_FIELDS, 'shadow');
  const shadow = {
    target: vectorInRange(fallback(input.target, [0, 1, 0]), -1e6, 1e6, 'shadow target'),
    extent: numberInRange(fallback(input.extent, 3.5), 0.01, 1e5, 'shadow extent'),
    distance: numberInRange(fallback(input.distance, 8), 0.01, 1e6, 'shadow distance'),
    near: numberInRange(fallback(input.near, 0.1), 0.001, 1e6, 'shadow near'),
    far: numberInRange(fallback(input.far, 15), 0.001, 1e6, 'shadow far'),
  };
  if (Math.fround(shadow.near) >= Math.fround(shadow.far)) {
    throw new RangeError('Shadow needs near < far at Float32 precision.');
  }
  return shadow;
}

function shadowBoundsFrom(shadow, direction) {
  const { unitDirection } = directionFrom(direction);
  const eye = shadow.target.map((component, axis) => component + unitDirection[axis] * shadow.distance);
  if (!eye.every(component => Number.isFinite(Math.fround(component))) ||
      eye.every((component, axis) => Math.fround(component) === Math.fround(shadow.target[axis]))) {
    throw new RangeError('Shadow eye and target must remain finite and distinguishable at Float32 precision.');
  }
  const up = Math.abs(unitDirection[1]) > 0.99 ? [0, 0, 1] : [0, 1, 0];
  const view = mat4.lookAt(mat4.create(), eye, shadow.target, up);
  const projection = mat4.ortho(mat4.create(), -shadow.extent, shadow.extent, -shadow.extent, shadow.extent, shadow.near, shadow.far);
  const combined = mat4.multiply(mat4.create(), projection, view);
  for (const matrix of [view, projection, combined]) {
    const determinant = mat4.determinant(matrix);
    if (!matrix.every(Number.isFinite) || !Number.isFinite(determinant) || determinant === 0) {
      throw new RangeError('Shadow view, projection, and combined matrices must remain finite and nonsingular at Float32 precision.');
    }
  }
  return { eye, target: [...shadow.target], up, extent: shadow.extent, near: shadow.near, far: shadow.far };
}

// A recipe that leaves `shadow` out gets a 7 m wide view around [0, 1, 0], and a bigger scene has no shadow data beyond it, so the sun reaches
// whatever lies outside (a sealed room 8 m wide came out as bright as one with a window, #1359). Such a scene gets a view fitted to its bounds, a
// little wider than they are. A scene wider than the largest view (the default world view's half width, 65 m) keeps the view as it was.
const SHADOW_FIT_PADDING = 1.1;
const LARGEST_FITTED_SHADOW_EXTENT = 65;
// A ground plane under a small subject must not stretch the view: a 1 m object on a 50 m plane would get a 40 m view and shadow texels 6 times
// larger than the default view gives it. A horizontal slab wider than this and at most 15 percent as thick as it is wide (bounds carry about 5 percent padding on each side) is left out of the fit
// when anything else is left (a room's 8 m floor stays in).
const GROUND_PLANE_MINIMUM_WIDTH = 10;
const GROUND_PLANE_THICKNESS_RATIO = 0.15;

function isGroundPlane(part) {
  const bounds = sceneBoundsOfParts([part]);
  if (!bounds) return false;
  const [width, height, depth] = bounds.maximum.map((value, axis) => value - bounds.minimum[axis]);
  const horizontal = Math.max(width, depth);
  return horizontal > GROUND_PLANE_MINIMUM_WIDTH && height <= horizontal * GROUND_PLANE_THICKNESS_RATIO;
}

function fitBoundsOf(parts) {
  const subjects = parts.filter(part => !isGroundPlane(part));
  return sceneBoundsOfParts(subjects.length > 0 ? subjects : parts);
}

/** The shadow a scene should use: the recipe's own when it set one, else a view fitted to the parts when they outgrow the default one. */
export function fitAgentShadow(shadow, parts) {
  const defaults = shadowFrom({});
  const isDefault = Object.keys(defaults).every(key => JSON.stringify(shadow[key]) === JSON.stringify(defaults[key]));
  if (!isDefault) return shadow;
  const bounds = sceneBoundsOfParts(parts) && fitBoundsOf(parts);
  if (!bounds) return shadow;
  const radius = Math.hypot(...bounds.maximum.map((value, axis) => value - bounds.minimum[axis])) / 2;
  const extent = radius * SHADOW_FIT_PADDING;
  if (!(extent > defaults.extent && extent <= LARGEST_FITTED_SHADOW_EXTENT)) return shadow;
  const target = bounds.maximum.map((value, axis) => (value + bounds.minimum[axis]) / 2);
  return { target, extent, distance: extent * 2.4, near: 1, far: extent * 5 };
}

/** Derive a detached directional shadow projector from validated ordinary JSON. */
export function resolveAgentShadow(inputShadow = {}, inputDirection = [-3, 6, 4]) {
  const shadow = shadowFrom(copiedJson(inputShadow));
  const direction = copiedJson(inputDirection);
  return shadowBoundsFrom(shadow, direction);
}

/** Normalize the complete look without mutating caller input or sharing default arrays. */
export function normalizeAgentLook(input = {}) {
  knownKeys(input, ['environment', 'effects', 'shadow'], 'look');
  const copied = copiedJson(input);
  const environment = environmentFrom(copied.environment);
  const effects = effectsFrom(copied.effects);
  const shadow = shadowFrom(copied.shadow);
  shadowBoundsFrom(shadow, environment.lightDirection);
  return { environment, effects, shadow };
}