Skip to content

3D engine that AI agents drive

9.5 KB
Raw Blame
import { meshFromGeometry } from './mesh-convert.js';
import { facesWithTag } from './mesh-data.js';
import { invalidField } from './field-error.js';
import { lintMesh } from './mesh-lint.js';
import { applyMeshEdits, evaluateMeshStack } from './mesh-recipe.js';
import { extractRender } from './mesh-render.js';
import { normalizeShapeKeys, shapeKeyTargets } from './mesh-shape-keys.js';
import { realizedGeometry } from './mesh-instances.js';
import { MESH_SMOOTH_ANGLE_DEFAULT } from './agent-scene-capabilities.js';

export { MESH_SMOOTH_ANGLE_DEFAULT };
export { needsMeshBooleans } from './agent-scene-modules.js';

// Compact, agent-facing mesh reports for scene geometry. Reports are cached per immutable geometry object, so
// repeated inspection of an unchanged scene costs nothing.

const reports = new WeakMap();

// Render geometry generated from a mesh recipe keeps its polygon mesh and edit results here.
const polygonMeshes = new WeakMap();

const CACHE_MAX_ENTRIES = 64;
const CACHE_MAX_BYTES = 64 * 1024 * 1024;

/**
 * Least-recently-used cache of evaluated meshes keyed by their recipe prefix (base, edits, then each stack node),
 * bounded by entry count and array bytes. Unchanged prefixes are reused when only later parts change.
 */
class MeshEvaluationCache {
  constructor() {
    this.entries = new Map();
    this.bytes = 0;
    this.hits = 0;
    this.misses = 0;
  }

  get(key) {
    const entry = this.entries.get(key);
    if (!entry) {
      this.misses++;
      return undefined;
    }
    this.hits++;
    this.entries.delete(key);
    this.entries.set(key, entry);
    return entry.value;
  }

  set(key, value) {
    const bytes = meshBytes(value.mesh);
    if (bytes > CACHE_MAX_BYTES) return;
    const previous = this.entries.get(key);
    if (previous) {
      this.bytes -= previous.bytes;
      this.entries.delete(key);
    }
    this.entries.set(key, { value, bytes });
    this.bytes += bytes;
    while (this.entries.size > CACHE_MAX_ENTRIES || this.bytes > CACHE_MAX_BYTES) {
      const [oldestKey, oldest] = this.entries.entries().next().value;
      this.entries.delete(oldestKey);
      this.bytes -= oldest.bytes;
    }
  }
}

function meshBytes(mesh) {
  let bytes = mesh.positions.byteLength + mesh.faceOffsets.byteLength + mesh.cornerVertices.byteLength +
    mesh.edgeVertices.byteLength + mesh.cornerEdges.byteLength;
  for (const domain of Object.values(mesh.attributes)) {
    for (const attribute of Object.values(domain)) bytes += attribute.data.byteLength;
  }
  return bytes;
}

const evaluationCache = new MeshEvaluationCache();

/** Hit and miss counts of the mesh evaluation cache, for tests and diagnostics. */
export function meshCacheStats() {
  return { hits: evaluationCache.hits, misses: evaluationCache.misses, entries: evaluationCache.entries.size, bytes: evaluationCache.bytes };
}

const foamGeometries = new WeakMap();

/**
 * The geometry a water part draws: when it carries the ocean's `foam` vertex group, a copy whose sky visibility channel holds
 * 1 - foam, which the water shader reads as the foam mask (a plain water part keeps 1, so no foam). One copy per geometry.
 */
export function waterFoamGeometry(geometry, material) {
  const foam = material.tag === 'water' ? geometry.vertexGroups?.foam : undefined;
  if (!foam || geometry.skyVisibility) return geometry;
  if (!foamGeometries.has(geometry)) foamGeometries.set(geometry, { ...geometry, skyVisibility: Float32Array.from(foam, weight => 1 - weight) });
  return foamGeometries.get(geometry);
}

/** Degrees of the smoothing default for ocean output. Choppiness folds the surface, and the default 30 would split its normals. */
export const OCEAN_SMOOTH_ANGLE_DEFAULT = 180;

/** The smoothAngle a mesh gets when the recipe sets none: 180 for a sea (an ocean edit or stack node), else the shared default. */
export function defaultSmoothAngle(edits = [], stack = []) {
  const makesOcean = operation => operation?.op === 'ocean';
  return edits.some(makesOcean) || stack.some(makesOcean) ? OCEAN_SMOOTH_ANGLE_DEFAULT : MESH_SMOOTH_ANGLE_DEFAULT;
}

/**
 * Build render geometry for a recipe `mesh` geometry: convert the base, run the edit log, evaluate the modifier
 * stack, and extract triangles with edges sharper than smoothAngle (degrees) kept hard, as Blender's auto smooth
 * does. `cacheKey` identifies the base; the edit result and every stack prefix are cached under it.
 */
export function generateMeshGeometry(baseGeometry, edits, {
  maxVertices, stack = [], smoothAngle = defaultSmoothAngle(edits, stack), resolveCutter, cacheKey, shapeKeys = [],
}) {
  const realized = cacheKey && realizedGeometry(cacheKey);
  if (realized) {
    if (realized.positions.length / 3 > maxVertices) {
      throw invalidField('edits', realized.positions.length / 3, `an edited mesh of at most ${maxVertices} render vertices (maxVertices); use fewer subdivisions or segments`);
    }
    return realized;
  }
  const editsKey = cacheKey === undefined ? undefined : `${cacheKey}|edits|${JSON.stringify(edits)}`;
  let edited = editsKey === undefined ? undefined : evaluationCache.get(editsKey);
  if (!edited) {
    const base = meshFromGeometry(baseGeometry());
    const outcome = applyMeshEdits(base, edits, {
      maxVertices, maxFaces: maxVertices,
      resolveCutter: resolveCutter && (cutter => meshFromGeometry(resolveCutter(cutter))),
    });
    edited = { mesh: outcome.mesh, result: outcome.results };
    if (editsKey !== undefined) evaluationCache.set(editsKey, edited);
  }
  const evaluated = evaluateMeshStack(edited.mesh, stack, { maxVertices, maxFaces: maxVertices, cache: evaluationCache, cacheKey: editsKey });
  const { geometry, renderVertexSource } = extractRender(evaluated.mesh, { sharpAngle: smoothAngle * Math.PI / 180 });
  if (geometry.positions.length / 3 > maxVertices) {
    throw invalidField('edits', geometry.positions.length / 3, `an edited mesh of at most ${maxVertices} render vertices (maxVertices); use fewer subdivisions or segments`);
  }
  const keys = normalizeShapeKeys(shapeKeys);
  if (keys.length) {
    geometry.morphTargets = shapeKeyTargets(evaluated.mesh, renderVertexSource, keys, { maxVertices, maxFaces: maxVertices, resolveCutter: resolveCutter && (cutter => meshFromGeometry(resolveCutter(cutter))) });
    geometry.morphTargetNames = keys.map(key => key.name);
    geometry.morphTargetValues = Float32Array.from(keys, key => key.value);
  }
  polygonMeshes.set(geometry, { mesh: evaluated.mesh, results: edited.result, stack: evaluated.results });
  return geometry;
}

/** Remember the polygon mesh and edit results behind geometry built outside generateMeshGeometry (imported parts). */
export function registerEditedMesh(geometry, mesh, results) {
  polygonMeshes.set(geometry, { mesh, results, stack: [] });
}

/**
 * Local-space positions of the faces that carry a mesh tag, shaped like geometry so bounds code can read them. Throws a
 * message naming the next step when the part is a plain shape, or the tag is unknown or on no faces.
 */
export function taggedFacePositions(geometry, tag) {
  const polygon = polygonMeshes.get(geometry);
  if (!polygon) {
    throw invalidField('region', tag, 'a tag on a mesh geometry; tag faces with a mesh_edit tag op, or drop region');
  }
  const { mesh } = polygon;
  const positions = [];
  for (const face of facesWithTag(mesh, tag)) {
    for (let corner = mesh.faceOffsets[face]; corner < mesh.faceOffsets[face + 1]; corner++) {
      const vertex = mesh.cornerVertices[corner];
      positions.push(mesh.positions[vertex * 3], mesh.positions[vertex * 3 + 1], mesh.positions[vertex * 3 + 2]);
    }
  }
  if (positions.length === 0) {
    throw invalidField('region', tag, 'a tag that is on some faces; tag faces with a mesh_edit tag op, or use another region');
  }
  return { positions: Float32Array.from(positions) };
}

function faceSizeHistogram(mesh) {
  const histogram = { triangles: 0, quads: 0, ngons: 0 };
  for (let face = 0; face < mesh.faceCount; face++) {
    const size = mesh.faceOffsets[face + 1] - mesh.faceOffsets[face];
    if (size === 3) histogram.triangles++;
    else if (size === 4) histogram.quads++;
    else histogram.ngons++;
  }
  return histogram;
}

function roundedBounds(bounds) {
  const round = value => Math.round(value * 1e5) / 1e5;
  return { min: bounds.min.map(round), max: bounds.max.map(round) };
}

/** The polygon mesh behind renderer geometry: the recipe's own mesh when it has one, else the welded, quad-joined view. */
export function polygonMeshOf(geometry) {
  return polygonMeshes.get(geometry)?.mesh ?? meshFromGeometry(geometry);
}

/**
 * Polygon view and lint of renderer geometry: counts, face sizes, connected parts, face tags, bounds and problems
 * with suggested fixes. The geometry is welded and joined into quads first, as meshFromGeometry does.
 */
export function meshReport(geometry) {
  let report = reports.get(geometry);
  if (report) return report;
  const polygon = polygonMeshes.get(geometry);
  const mesh = polygon?.mesh ?? meshFromGeometry(geometry);
  const lint = lintMesh(mesh, { geometry: true });
  report = Object.freeze({
    ok: lint.ok,
    counts: { ...lint.counts, triangles: geometry.indices.length / 3, renderVertices: geometry.positions.length / 3 },
    faces: faceSizeHistogram(mesh),
    valence: lint.valence,
    quadQuality: lint.quadQuality,
    topologyScore: lint.topologyScore,
    parts: lint.parts,
    tags: lint.tags,
    bounds: roundedBounds(lint.bounds),
    problems: lint.problems,
    ...(lint.skippedChecks ? { skippedChecks: lint.skippedChecks } : {}),
    ...(polygon ? { edits: polygon.results, stack: polygon.stack } : {}),
  });
  reports.set(geometry, report);
  return report;
}