Skip to content

3D engine that AI agents drive

13.0 KB
Raw Blame
// Code that most recipes never run loads on demand, so the agent scene entry stays small. A recipe that uses mesh
// editing, procedural modeling, motion, material patterns, terrain, light linking, cascaded shadows or the anisotropy and iridescence layers needs its module loaded before createAgentScene runs:
// call `await loadAgentSceneModules(recipe)` (or `loadAllAgentSceneModules()` in a host that does not mind the
// size). createAgentScene is still synchronous; when a needed module is missing it says which call to make.

const MODULE_LOADERS = {
  mesh: () => import('./agent-mesh-engine.js'),
  modeling: () => import('./modeling.js'),
  text: () => import('./text-geometry.js'),
  motion: () => import('./agent-motion.js'),
  motionBake: () => import('./agent-motion-bake.js'),
  motionTrackRemoval: () => import('./motion-track-removal.js'),
  springs: () => import('./spring-bones.js'),
  settle: () => import('./agent-settle.js'),
  drive: () => import('./agent-drive.js'),
  physics: () => import('./agent-physics.js'),
  fracture: () => import('./agent-fracture.js'),
  explosion: () => import('./agent-explosion.js'),
  vehicleDamage: () => import('./vehicle-damage.js'),
  cloth: () => import('./agent-cloth.js'),
  particles: () => import('./agent-particles.js'),
  bake: () => import('./agent-bake.js'),
  reflections: () => import('./agent-reflections.js'),
  patterns: () => import('./material-patterns.js'),
  relations: () => import('./agent-relations.js'),
  timeline: () => import('./film-timeline.js'),
  layerShaders: () => import('./material-layer-shaders.js'),
  emissionMask: () => import('./emission-mask.js'),
  liquidShader: () => import('./liquid-shader.js'),
  subsurfaceShader: () => import('./subsurface-shader.js'),
  fogShader: () => import('./fog-shader.js'),
  retroShader: () => import('./retro-shader.js'),
  glitterShader: () => import('./glitter-shader.js'),
  worldMaterials: () => import('./world-material-shader.js'),
  terrain: () => import('./agent-terrain.js'),
  navigation: () => import('./agent-navigation.js'),
  lightLinking: () => import('./light-linking.js'),
  cascades: () => import('./light-modules.js'),
  assets: () => import('./agent-scene-assets.js'),
  vegetation: () => import('./agent-vegetation.js'),
  crowd: () => import('./agent-crowd.js'),
  lineArt: () => import('./line-art.js'),
  viewTransform: () => import('./view-transform-shader.js'),
  coplanar: () => import('./coplanar-overlap.js'),
  unsupportedPart: () => import('./unsupported-part.js'),
  physicalSky: () => import('./physical-sky.js'),
  floorSky: () => import('./floor-sky-visibility.js'),
  userPass: () => import('./user-pass.js'),
  game: () => import('./game-setup.js'),
  objectMotionBlur: () => import('./object-motion-blur.js'),
  postSteps: () => import('./post-steps.js'),
  materialSnippet: () => import('./material-snippet.js'),
  volumeGrid: () => import('./local-volume-grid.js'),
  volumeRamp: () => import('./local-volume-ramp.js'),
};

const loadedModules = {};
const pendingLoads = {};
// Set by loadAllAgentSceneModules: the host runs any recipe and wants every default stage on (the MCP preview).
let hostLoadedEveryModule = false;
let manifoldLoader = null;
let physicsLoader = null;

// The two modules that switch a default stage on for every scene once loaded. Kept apart so createAgentScene can ask for just
// these without carrying the whole marker table.
const DEFAULT_STAGE_MARKERS = {
  // Flush faces are ranked whenever this is loaded (issue #751): the MCP preview registers it, loadAllAgentSceneModules loads it,
  // and so does a recipe that names resolveCoplanar or places an asset, since glTF models nest facades a few millimetres apart.
  // A recipe of plain primitives in a host without it stays free of the 85 KB of flush code, so it needs no on-demand module.
  coplanar: ['"resolveCoplanar"', '"asset":{'],
  // 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"'],
};

// Each test errs on the side of loading: a false positive costs a chunk, a false negative a clear error.
const MODULE_MARKERS = {
  mesh: ['"type":"mesh"', '"instances"'],
  modeling: ['"type":"lathe"', '"type":"extrude"', '"type":"tube"', '"type":"curve"', '"type":"sdf"', '"type":"cloud"'],
  text: ['"type":"text"'],
  motion: ['"motion":{', '"bake-motion"', '"add-explosion"'],
  motionBake: ['"bake-motion"'],
  motionTrackRemoval: ['"removeTracks"'],
  springs: ['"springs":{'],
  settle: ['"type":"settle"'],
  drive: ['"drive":{'],
  physics: ['"physics":{', '"fracture-node"', '"add-explosion"'],
  fracture: ['"type":"fragment"', '"fracture-node"', '"add-explosion"'],
  explosion: ['"add-explosion"'],
  vehicleDamage: ['"type":"dented"'],
  cloth: ['"cloth":{'],
  particles: ['"particles":{', '"add-explosion"'],
  bake: ['"bake":{'],
  // A metallic value of 0.5 or more may make a part reflective; the module skips a scene that has no smooth one.
  reflections: [/"metallic":(0\.[5-9]|1(?![0-9]))/],
  patterns: ['"pattern"'],
  relations: ['"relations":'],
  timeline: ['"timeline":{'],
  layerShaders: ['"anisotropy"', '"iridescence"', '"fresnel"', '"emissionMask"'],
  emissionMask: ['"emissionMask"'],
  liquidShader: ['"transmission"', '"liquid"', '"foam"'],
  subsurfaceShader: ['"subsurface"'],
  retroShader: ['"retro"'],
  glitterShader: ['"waterGlint"'],
  // Any mention loads it, because an edit can set the density through a path or the environment of an operation.
  fogShader: ['volumeFog', 'localVolumes', '"add-explosion"'],
  worldMaterials: ['"tag":"water"', '"waterPreset"', '"absorption"', '"turbidity"', '"caustics"', '"waterRamp"', '"vegetation":{', '"tag":"foliage"', '"tag":"grass"', '"tag":"terrain"', '"tag":"fire"', '"tag":"smoke"', '"moss"'],
  terrain: ['"type":"terrain"'],
  // No recipe text asks for it, only the path option of scene_inspect does, so a host loads it with loadAllAgentSceneModules.
  navigation: [],
  lightLinking: ['"affects"', '"keyAffects"'],
  // The cascade module also loads light-shapes (soft area shadows, IES profiles), so these markers bring both.
  cascades: [/"(?:shadowCascades|sunAngularRadius|ies)"|"areaLights":\[\{/],
  assets: ['"asset":{', '"sequence":{'],
  vegetation: ['"vegetation":{', '"wind":{'],
  crowd: ['"crowd":{'],
  lineArt: ['"lines":{', '"toon":'],
  viewTransform: ['"viewTransform":"agx"', '"viewTransform":"neutral"', '"viewTransform":"standard"', '"look":"'],
  // Flush faces are ranked whenever this is loaded (issue #751): the MCP preview registers it, loadAllAgentSceneModules loads it,
  // and so does a recipe that names resolveCoplanar or places an asset, since glTF models nest facades a few millimetres apart.
  // A recipe of plain primitives in a host without it stays free of the 85 KB of flush code, so it needs no on-demand module.
  coplanar: DEFAULT_STAGE_MARKERS.coplanar,
  // The support check needs no recipe text: the MCP preview and loadAllAgentSceneModules load it, and a plain host stays free of it.
  unsupportedPart: [],
  // 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: DEFAULT_STAGE_MARKERS.floorSky,
  physicalSky: ['"type":"physical"', '"type":"gradient"'],
  userPass: ['"postPasses"'],
  game: ['"game":{', '"set-game"'],
  materialSnippet: ['"snippet":{'],
  volumeGrid: ['"shape":"grid"'],
  volumeRamp: ['"emissionRamp"'],
  // Only a motionBlur object that sets a non-zero `objects` loads it; the common `"shutter":0` look does not.
  objectMotionBlur: [/"motionBlur":\{[^}]*"objects":(?!0[,}])/],
  postSteps: [/"(?:colorBalance|glare|lensDistortion|stylize|composite)"|"(?:distortion|flash)":[\[{]|"add-explosion"/],
};

/** Whether a recipe, operation list or edit list contains a boolean edit, which needs loadMeshBooleans() first. */
export function needsMeshBooleans(value) {
  return JSON.stringify(value ?? null).includes('"op":"boolean"');
}

/** True when a recipe or an operation list carries a physics section or a settle operation, so the host loads the solver first. */
export function needsPhysics(value) {
  const text = JSON.stringify(value ?? null);
  return text.includes('"physics":{') || text.includes('"fracture-node"') || text.includes('"type":"settle"') || (text.includes('"add-explosion"') && text.includes('"debris"'));
}

/** True when a recipe has a body with a float field, so the host passes { buoyancy: true } to loadPhysicsEngine. */
export function needsBuoyancy(value) {
  return JSON.stringify(value ?? null).includes('"float":{');
}

function namedModules(value, markers, fallback) {
  let text;
  try {
    text = JSON.stringify(value ?? null);
  } catch {
    return fallback;
  }
  const compact = text.replace(/"\s*:\s*/g, '":');
  return Object.keys(markers).filter(name => markers[name].some(marker => (marker instanceof RegExp ? marker.test(compact) : compact.includes(marker))));
}

/** Names of the on-demand modules a recipe, or a list of edit operations, needs. */
export function agentSceneModulesNeeded(value) {
  return namedModules(value, MODULE_MARKERS, Object.keys(MODULE_LOADERS));
}

/** Which default-stage modules (flush ranking, floor sky) a recipe or a list of edit operations names. */
export function defaultStageModulesNamed(value) {
  return namedModules(value, DEFAULT_STAGE_MARKERS, Object.keys(DEFAULT_STAGE_MARKERS));
}

function loadModule(name) {
  if (loadedModules[name]) return Promise.resolve(loadedModules[name]);
  pendingLoads[name] ??= MODULE_LOADERS[name]().then(module => {
    loadedModules[name] = module;
    if (name === 'mesh' && manifoldLoader) module.setManifoldModuleLoader(manifoldLoader);
    if (name === 'physics' && physicsLoader) module.setPhysicsModuleLoader(physicsLoader);
    return module;
  });
  return pendingLoads[name];
}

/** Load the modules a recipe (or a list of edit operations) needs. Safe to call repeatedly. */
export async function loadAgentSceneModules(value) {
  await Promise.all(agentSceneModulesNeeded(value).map(loadModule));
}

/** Load every on-demand module, for hosts that run any recipe an agent writes. */
export async function loadAllAgentSceneModules() {
  hostLoadedEveryModule = true;
  await Promise.all(Object.keys(MODULE_LOADERS).map(loadModule));
}

/** Entries that import a module statically register it here, so createAgentScene finds it without a load call. */
export function registerAgentSceneModule(name, module) {
  loadedModules[name] ??= module;
}

/** The loaded module, or an error that names the call that loads it. */
export function agentSceneModule(name) {
  const module = loadedModules[name];
  if (!module) {
    throw new Error(`This recipe needs the ${name} code, which loads on demand: await loadAgentSceneModules(recipe) before createAgentScene or apply.`);
  }
  return module;
}

export function allAgentSceneModulesLoaded() {
  return Object.keys(MODULE_LOADERS).every(name => loadedModules[name]);
}

export function agentSceneModuleLoaded(name) {
  return Boolean(loadedModules[name]);
}

/**
 * Whether a default stage that needs this module runs for one scene. A module another scene loaded earlier in the same
 * process does not count: the stage runs when the host loaded every module, or when this scene's own recipe or edits
 * asked for it (`requestedNames`, from agentSceneModulesNeeded). So a scene builds the same bytes whatever was built before it.
 */
export function agentSceneModuleActive(name, requestedNames) {
  return Boolean(loadedModules[name]) && (hostLoadedEveryModule || requestedNames.has(name));
}

/** Add a font table that recipes can name in a text geometry. Loads the text code first. */
export async function registerAgentSceneFont(name, fontData) {
  const module = await loadModule('text');
  module.registerFont(name, fontData);
}

/** Replace how the Manifold module is imported. Applied when the mesh code loads, if it has not yet. */
export function setManifoldModuleLoader(loader) {
  if (typeof loader !== 'function') throw new TypeError('The Manifold loader must be a function returning a module promise.');
  manifoldLoader = loader;
  loadedModules.mesh?.setManifoldModuleLoader(loader);
}

export async function loadMeshBooleans(options) {
  const mesh = await loadModule('mesh');
  return mesh.loadMeshBooleans(options);
}

export function meshBooleansLoaded() {
  return loadedModules.mesh?.meshBooleansLoaded() ?? false;
}

/** Replace how the Rapier module is imported. Applied when the physics code loads, if it has not yet. */
export function setPhysicsModuleLoader(loader) {
  if (typeof loader !== 'function') throw new TypeError('The physics loader must be a function returning a module promise.');
  physicsLoader = loader;
  loadedModules.physics?.setPhysicsModuleLoader(loader);
}

export async function loadPhysicsEngine(options) {
  const physics = await loadModule('physics');
  return physics.loadPhysicsEngine(options);
}

export function physicsEngineLoaded() {
  return loadedModules.physics?.physicsEngineLoaded() ?? false;
}