Skip to content

3D engine that AI agents drive

10.8 KB
Raw Blame
import { quat, vec3 } from 'gl-matrix';
import { seededRandom } from './mesh-fields.js';

// The `place` record of an `instances` spec: what keeps, shapes and varies the points once a source made them.
//
//   "place": { "at": "vertices" | "faces",   surface source only: the vertices or face centres, not random points
//              "spacing": 0.8,               Poisson-disk minimum distance between kept points
//              "density": <number field>,    chance 0..1 that a point stays
//              "variants": ["rockA", "rockB", { "geometry": "rockC", "material": "moss" }],
//              "variant": <number field>,    index into variants (rounded down, wrapped); default seeded random
//              "rotation": <vector field>,   extra Euler turn, radians, X then Y then Z
//              "size": <number or vector field> }   scale per point; multiplies the `scale` range
//
// Every choice is a pure function of the point index and the seed, so a scene builds the same way each time.

export const PLACE_FIELDS = Object.freeze(['at', 'spacing', 'density', 'variants', 'variant', 'rotation', 'size', 'realize']);
export const MAX_VARIANTS = 16;
export const MAX_REALIZED_VERTICES = 250_000;
const MAX_SPACING = 1e6;
const MIN_SIZE = 0.001;
const MAX_SIZE = 1000;
const WELD_DIGITS = 1e5;

const CHANNEL_DENSITY = 40;
const CHANNEL_VARIANT = 41;

function placeError(message) {
  return new TypeError(`Instances: place ${message}`);
}

/** Check a `place` record and return it normalised; throws a TypeError that names the field. */
export function checkedPlace(place) {
  if (place === undefined) return {};
  if (!place || typeof place !== 'object' || Array.isArray(place)) throw placeError('must be an object.');
  for (const key of Object.keys(place)) {
    if (!PLACE_FIELDS.includes(key)) throw placeError(`does not take ${JSON.stringify(key.slice(0, 24))}; fields: ${PLACE_FIELDS.join(', ')}.`);
  }
  if (place.at !== undefined && place.at !== 'vertices' && place.at !== 'faces') throw placeError('at is "vertices" or "faces".');
  if (place.spacing !== undefined && !(typeof place.spacing === 'number' && place.spacing > 0 && place.spacing <= MAX_SPACING)) {
    throw placeError('spacing is a distance above 0.');
  }
  if (place.realize !== undefined && typeof place.realize !== 'boolean') throw placeError('realize must be boolean.');
  if (place.variant !== undefined && place.variants === undefined) throw placeError('variant needs a variants list.');
  const variants = place.variants === undefined ? null : variantList(place.variants);
  return { ...place, variants };
}

function variantList(entries) {
  if (!Array.isArray(entries) || entries.length < 1 || entries.length > MAX_VARIANTS) throw placeError(`variants is 1 to ${MAX_VARIANTS} entries.`);
  return entries.map(entry => {
    const record = typeof entry === 'string' ? { geometry: entry } : entry;
    const valid = record && typeof record === 'object' && !Array.isArray(record)
      && typeof record.geometry === 'string' && (record.material === undefined || typeof record.material === 'string')
      && Object.keys(record).every(key => key === 'geometry' || key === 'material');
    if (!valid) throw placeError('variants entries are a geometry id or { geometry, material }.');
    return record;
  });
}

/** Deduplicated vertices (by position) or face centres of a render geometry, with normals. */
export function meshPoints(geometry, at, limit) {
  const positions = [];
  const normals = [];
  if (at === 'vertices') {
    const seen = new Set();
    for (let vertex = 0; vertex < geometry.positions.length / 3; vertex++) {
      const offset = vertex * 3;
      const key = [0, 1, 2].map(axis => Math.round(geometry.positions[offset + axis] * WELD_DIGITS)).join(',');
      if (seen.has(key)) continue;
      seen.add(key);
      positions.push(geometry.positions[offset], geometry.positions[offset + 1], geometry.positions[offset + 2]);
      normals.push(geometry.normals[offset], geometry.normals[offset + 1], geometry.normals[offset + 2]);
    }
  } else {
    for (let triangle = 0; triangle < geometry.indices.length / 3; triangle++) {
      const corners = [0, 1, 2].map(corner => geometry.indices[triangle * 3 + corner] * 3);
      const centre = [0, 1, 2].map(axis => corners.reduce((sum, corner) => sum + geometry.positions[corner + axis], 0) / 3);
      const edgeOne = [0, 1, 2].map(axis => geometry.positions[corners[1] + axis] - geometry.positions[corners[0] + axis]);
      const edgeTwo = [0, 1, 2].map(axis => geometry.positions[corners[2] + axis] - geometry.positions[corners[0] + axis]);
      const facing = [
        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(...facing);
      if (length === 0) continue;
      positions.push(...centre);
      normals.push(...facing.map(component => component / length));
    }
  }
  if (positions.length / 3 > limit) throw placeError(`at "${at}" found ${positions.length / 3} points; raise the surface count to ${limit} or more.`);
  return { positions: Float64Array.from(positions), normals: Float64Array.from(normals) };
}

/** Keep each point with the chance its density value gives. */
export function thinByDensity(indices, densities, seed) {
  return indices.filter(index => seededRandom(index, CHANNEL_DENSITY, seed) < densities[index]);
}

/**
 * Poisson-disk thinning by dart throwing: walk the points in order and keep one when no kept point is closer than
 * `spacing`. A hash grid with cells of the spacing keeps the check to the 27 nearby cells.
 */
export function thinBySpacing(indices, positions, spacing) {
  const cells = new Map();
  const cellOf = (index, axis) => Math.floor(positions[index * 3 + axis] / spacing);
  const kept = [];
  for (const index of indices) {
    const cell = [cellOf(index, 0), cellOf(index, 1), cellOf(index, 2)];
    if (!crowded(cells, cell, positions, index, spacing)) {
      kept.push(index);
      const key = cell.join(',');
      if (!cells.has(key)) cells.set(key, []);
      cells.get(key).push(index);
    }
  }
  return kept;
}

function crowded(cells, cell, positions, index, spacing) {
  for (let x = -1; x <= 1; x++) {
    for (let y = -1; y <= 1; y++) {
      for (let z = -1; z <= 1; z++) {
        const neighbours = cells.get(`${cell[0] + x},${cell[1] + y},${cell[2] + z}`);
        if (!neighbours) continue;
        for (const other of neighbours) {
          const distance = Math.hypot(
            positions[index * 3] - positions[other * 3],
            positions[index * 3 + 1] - positions[other * 3 + 1],
            positions[index * 3 + 2] - positions[other * 3 + 2],
          );
          if (distance < spacing) return true;
        }
      }
    }
  }
  return false;
}

/** The variant entry for a point: from the `variant` field when given, else a seeded random pick. */
export function pickVariant(variants, fieldValues, index, seed) {
  const raw = fieldValues ? Math.floor(fieldValues[index]) : Math.floor(seededRandom(index, CHANNEL_VARIANT, seed) * variants.length);
  return variants[((raw % variants.length) + variants.length) % variants.length];
}

/** Quaternion for XYZ Euler angles in radians (Rz * Ry * Rx, the node rotation order of the field language). */
export function eulerQuaternion(angleX, angleY, angleZ) {
  const turnX = quat.setAxisAngle(quat.create(), [1, 0, 0], angleX);
  const turnY = quat.setAxisAngle(quat.create(), [0, 1, 0], angleY);
  const turnZ = quat.setAxisAngle(quat.create(), [0, 0, 1], angleZ);
  return quat.multiply(quat.create(), quat.multiply(quat.create(), turnZ, turnY), turnX);
}

/** Scale triple from one number (uniform) or three (per axis), kept inside the scene's scale range. */
export function clampedSize(values, index, perAxis) {
  const pick = axis => Math.min(MAX_SIZE, Math.max(MIN_SIZE, values[perAxis ? index * 3 + axis : index]));
  return [pick(0), pick(1), pick(2)];
}

/**
 * Merge transformed copies of render geometries into one combined render geometry ({ positions, normals, indices,
 * ...(uvs), ...(colors) }), checked against `maxVertices` before allocating buffers.
 */
export function mergeRealizedInstances(entries, maxVertices = MAX_REALIZED_VERTICES) {
  const totalVertices = entries.reduce((sum, entry) => sum + entry.geometry.positions.length / 3, 0);
  if (totalVertices > maxVertices) {
    throw new RangeError(`Realized instances have ${totalVertices} vertices, over the limit of ${maxVertices}.`);
  }
  const totalIndices = entries.reduce((sum, entry) => sum + entry.geometry.indices.length, 0);
  const hasUvs = entries.some(entry => entry.geometry.uvs?.length);
  const hasColors = entries.some(entry => entry.geometry.colors?.length);
  const positions = new Float32Array(totalVertices * 3);
  const normals = new Float32Array(totalVertices * 3);
  const indices = new Uint32Array(totalIndices);
  const uvs = hasUvs ? new Float32Array(totalVertices * 2) : null;
  const colors = hasColors ? new Float32Array(totalVertices * 3) : null;
  if (colors) colors.fill(1);
  const point = [0, 0, 0];
  const normal = [0, 0, 0];
  let vertexBase = 0;
  let indexBase = 0;
  for (const { geometry, translation, rotation, scale } of entries) {
    const vertexCount = geometry.positions.length / 3;
    for (let vertex = 0; vertex < vertexCount; vertex++) {
      const sourceOffset = vertex * 3;
      const targetOffset = (vertexBase + vertex) * 3;
      point[0] = geometry.positions[sourceOffset] * scale[0];
      point[1] = geometry.positions[sourceOffset + 1] * scale[1];
      point[2] = geometry.positions[sourceOffset + 2] * scale[2];
      vec3.transformQuat(point, point, rotation);
      positions[targetOffset] = point[0] + translation[0];
      positions[targetOffset + 1] = point[1] + translation[1];
      positions[targetOffset + 2] = point[2] + translation[2];
      normal[0] = geometry.normals[sourceOffset] / scale[0];
      normal[1] = geometry.normals[sourceOffset + 1] / scale[1];
      normal[2] = geometry.normals[sourceOffset + 2] / scale[2];
      vec3.transformQuat(normal, normal, rotation);
      const normalLength = Math.hypot(normal[0], normal[1], normal[2]) || 1;
      normals[targetOffset] = normal[0] / normalLength;
      normals[targetOffset + 1] = normal[1] / normalLength;
      normals[targetOffset + 2] = normal[2] / normalLength;
    }
    if (uvs && geometry.uvs?.length === vertexCount * 2) uvs.set(geometry.uvs, vertexBase * 2);
    if (colors && geometry.colors?.length === vertexCount * 3) colors.set(geometry.colors, vertexBase * 3);
    for (let cursor = 0; cursor < geometry.indices.length; cursor++) {
      indices[indexBase + cursor] = vertexBase + geometry.indices[cursor];
    }
    vertexBase += vertexCount;
    indexBase += geometry.indices.length;
  }
  return {
    positions, normals, indices,
    ...(uvs ? { uvs } : {}),
    ...(colors ? { colors } : {}),
  };
}