Skip to content

3D engine that AI agents drive

10.8 KB
Raw Blame
// Low-level geometry helpers for the vegetation addon: vector math, seeded noise,
// a mesh builder, swept tubes (branches) and leaf surfaces (leaf meshes and cards).

export const FULL_TURN = Math.PI * 2;
export const WORLD_UP = [0, 1, 0];

export function createRandom(seed) {
  let state = Math.floor(seed) >>> 0;
  return () => {
    state += 0x6d2b79f5;
    let mixed = Math.imul(state ^ state >>> 15, state | 1);
    mixed ^= mixed + Math.imul(mixed ^ mixed >>> 7, mixed | 61);
    return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
  };
}

export function lerp(first, second, amount) {
  return first + (second - first) * amount;
}

export function clamp(value, minimum, maximum) {
  return Math.min(maximum, Math.max(minimum, value));
}

export function randomInRange(random, range) {
  return lerp(range[0], range[1], random());
}

function hashLattice(latticeX, latticeY, seed) {
  let mixed = Math.imul(latticeX, 374761393) ^ Math.imul(latticeY, 668265263) ^ Math.imul(seed, 2147483647);
  mixed = Math.imul(mixed ^ mixed >>> 13, 1274126177);
  return ((mixed ^ mixed >>> 16) >>> 0) / 4294967296;
}

/** Smooth value noise in [0, 1]; a positive period makes it tile on that axis. */
export function valueNoise(x, y, seed, periodX = 0, periodY = 0) {
  const cellX = Math.floor(x);
  const cellY = Math.floor(y);
  const fractionX = x - cellX;
  const fractionY = y - cellY;
  const smoothX = fractionX * fractionX * (3 - 2 * fractionX);
  const smoothY = fractionY * fractionY * (3 - 2 * fractionY);
  const wrap = (value, period) => period > 0 ? ((value % period) + period) % period : value;
  const corner = (offsetX, offsetY) => hashLattice(wrap(cellX + offsetX, periodX), wrap(cellY + offsetY, periodY), seed);
  const top = lerp(corner(0, 0), corner(1, 0), smoothX);
  const bottom = lerp(corner(0, 1), corner(1, 1), smoothX);
  return lerp(top, bottom, smoothY);
}

export function addVectors(first, second) {
  return [first[0] + second[0], first[1] + second[1], first[2] + second[2]];
}

export function subtractVectors(first, second) {
  return [first[0] - second[0], first[1] - second[1], first[2] - second[2]];
}

export function scaleVector(vector, amount) {
  return [vector[0] * amount, vector[1] * amount, vector[2] * amount];
}

export function addScaled(base, direction, amount) {
  return [base[0] + direction[0] * amount, base[1] + direction[1] * amount, base[2] + direction[2] * amount];
}

export function dotProduct(first, second) {
  return first[0] * second[0] + first[1] * second[1] + first[2] * second[2];
}

export function crossProduct(first, second) {
  return [
    first[1] * second[2] - first[2] * second[1],
    first[2] * second[0] - first[0] * second[2],
    first[0] * second[1] - first[1] * second[0],
  ];
}

export function vectorLength(vector) {
  return Math.hypot(vector[0], vector[1], vector[2]);
}

export function normalized(vector) {
  const length = vectorLength(vector);
  if (length < 1e-9) return [0, 1, 0];
  return [vector[0] / length, vector[1] / length, vector[2] / length];
}

export function lerpVectors(first, second, amount) {
  return [lerp(first[0], second[0], amount), lerp(first[1], second[1], amount), lerp(first[2], second[2], amount)];
}

/** Two unit vectors perpendicular to the direction and to each other. */
export function createFrame(direction) {
  const helperAxis = Math.abs(direction[1]) < 0.9 ? WORLD_UP : [1, 0, 0];
  const first = normalized(crossProduct(direction, helperAxis));
  const second = crossProduct(direction, first);
  return { first, second };
}

function transportFrame(frame, direction) {
  const first = normalized(addScaled(frame.first, direction, -dotProduct(frame.first, direction)));
  return { first, second: crossProduct(direction, first) };
}

export function createMeshBuilder({ withColors = false } = {}) {
  const positions = [];
  const normals = [];
  const uvs = [];
  const colors = [];
  const indices = [];
  return {
    get vertexCount() {
      return positions.length / 3;
    },
    get triangleCount() {
      return indices.length / 3;
    },
    addVertex(position, normal, u, v, color = [1, 1, 1]) {
      positions.push(position[0], position[1], position[2]);
      normals.push(normal[0], normal[1], normal[2]);
      uvs.push(u, v);
      if (withColors) colors.push(color[0], color[1], color[2]);
      return positions.length / 3 - 1;
    },
    addTriangle(first, second, third) {
      if (first === second || second === third || first === third) return;
      indices.push(first, second, third);
    },
    build() {
      const geometry = {
        positions: new Float32Array(positions),
        normals: new Float32Array(normals),
        uvs: new Float32Array(uvs),
        indices: new Uint32Array(indices),
      };
      if (withColors) geometry.colors = new Float32Array(colors);
      return geometry;
    },
  };
}

// Below this many texture repeats around a ring the bark texture is not wrapped to a whole number:
// rounding would stretch a thin twig by more than a third, so it keeps true world scale instead.
const MINIMUM_WHOLE_REPEATS = 1.5;
const MINIMUM_UNDERSIDE_REACH = 0.25;

function wholeOrExactRepeats(exactRepeats) {
  return exactRepeats >= MINIMUM_WHOLE_REPEATS ? Math.round(exactRepeats) : exactRepeats;
}

/** Angle around the ring whose radial direction points most nearly straight down, or `fallback` on near-vertical rings. */
function undersideAngle(frame, fallback) {
  const downOnFirst = -frame.first[1];
  const downOnSecond = -frame.second[1];
  if (Math.hypot(downOnFirst, downOnSecond) < MINIMUM_UNDERSIDE_REACH) return fallback;
  return Math.atan2(downOnSecond, downOnFirst);
}

/**
 * Sweeps a tapered round tube along a polyline with parallel-transported rings.
 * By default `u` repeats a whole number of times around the base ring. With `worldScaleUv` every ring
 * gets `u` and `v` from its own circumference so texels keep one world size from trunk to twig, rings
 * wide enough to wrap whole tiles do so (no seam), and thinner rings put their seam on the underside.
 */
export function addTube(builder, points, radii, sides, tileSize, color = [1, 1, 1], { worldScaleUv = false } = {}) {
  const baseRepeats = Math.max(1, Math.round(FULL_TURN * radii[0] / tileSize));
  const firstVertex = builder.vertexCount;
  const lastIndex = points.length - 1;
  let frame = null;
  let along = 0;
  let seamAngle = 0;
  points.forEach((point, index) => {
    const tangent = normalized(subtractVectors(points[Math.min(index + 1, lastIndex)], points[Math.max(index - 1, 0)]));
    frame = frame ? transportFrame(frame, tangent) : createFrame(tangent);
    const exactRepeats = FULL_TURN * radii[index] / tileSize;
    const repeatsAround = worldScaleUv ? wholeOrExactRepeats(exactRepeats) : baseRepeats;
    const alongScale = worldScaleUv && exactRepeats > 1e-6 ? repeatsAround / exactRepeats : 1;
    if (index > 0) along += vectorLength(subtractVectors(point, points[index - 1])) / tileSize * alongScale;
    if (worldScaleUv) seamAngle = undersideAngle(frame, seamAngle);
    for (let side = 0; side <= sides; side++) {
      const angle = seamAngle + side / sides * FULL_TURN;
      const radial = addVectors(scaleVector(frame.first, Math.cos(angle)), scaleVector(frame.second, Math.sin(angle)));
      builder.addVertex(addScaled(point, radial, radii[index]), radial, side / sides * repeatsAround, along, color);
    }
  });
  const ringSize = sides + 1;
  for (let ring = 0; ring < lastIndex; ring++) {
    for (let side = 0; side < sides; side++) {
      const current = firstVertex + ring * ringSize + side;
      const next = current + ringSize;
      builder.addTriangle(current, current + 1, next);
      builder.addTriangle(current + 1, next + 1, next);
    }
  }
}

function lobeNormal(forwardTilt, lateralTilt, normalAxis, forward, right) {
  return normalized(addVectors(addVectors(normalAxis, scaleVector(forward, forwardTilt)), scaleVector(right, lateralTilt)));
}

/**
 * Orthonormal frame for a leaf: `right` is horizontal so the face tilts toward the sky,
 * `normal` is the face normal, and `roll` turns the leaf about its own axis.
 */
export function createLeafFrame(forward, roll) {
  const horizontalRight = crossProduct(forward, WORLD_UP);
  const right = vectorLength(horizontalRight) < 1e-4 ? createFrame(forward).first : normalized(horizontalRight);
  const turned = addVectors(scaleVector(right, Math.cos(roll)), scaleVector(crossProduct(forward, right), Math.sin(roll)));
  return { forward, right: turned, normal: crossProduct(turned, forward) };
}

/**
 * Adds a curved leaf or card as rows of 2 or 3 columns, both faces, with shading
 * normals blended toward the canopy so a flat quad lights like part of a rounded crown.
 */
export function addLeafSurface(builder, surface) {
  const { origin, frame, length, width, rows, droop = 0, fold = 0, canopyNormal, canopyBlend = 0.5, colorBase, colorTip, brightness = 1 } = surface;
  const columns = fold > 0 ? [-1, 0, 1] : [-1, 1];
  const sides = surface.backFaces === false ? [1] : [1, -1];
  const rowIndicesBySide = sides.map((side) => rows.map(([progress, widthFactor]) => {
    const center = addScaled(addScaled(origin, frame.forward, length * progress), frame.normal, -droop * length * progress * progress);
    const half = width / 2 * widthFactor;
    const forwardTilt = 2 * droop * progress;
    const color = colorBase ? lerpVectors(colorBase, colorTip ?? colorBase, progress).map(channel => channel * brightness) : [brightness, brightness, brightness];
    const makeVertex = (column) => {
      const lateralTilt = column * fold;
      const faceNormal = scaleVector(lobeNormal(forwardTilt, lateralTilt, frame.normal, frame.forward, frame.right), side);
      const shading = normalized(addVectors(scaleVector(faceNormal, 1 - canopyBlend), scaleVector(canopyNormal, canopyBlend)));
      const lifted = column === 0 ? addScaled(center, frame.normal, fold * half) : center;
      return builder.addVertex(addScaled(lifted, frame.right, column * half), shading, (column + 1) / 2, 1 - progress, color);
    };
    if (half <= 0) {
      const shared = makeVertex(0);
      return columns.map(() => shared);
    }
    return columns.map(makeVertex);
  }));
  rowIndicesBySide.forEach((rowIndices, sideIndex) => {
    const front = sides[sideIndex] > 0;
    for (let row = 0; row < rows.length - 1; row++) {
      for (let column = 0; column < columns.length - 1; column++) {
        const a = rowIndices[row][column];
        const b = rowIndices[row][column + 1];
        const belowLeft = rowIndices[row + 1][column];
        const belowRight = rowIndices[row + 1][column + 1];
        if (front) {
          builder.addTriangle(a, b, belowLeft);
          builder.addTriangle(b, belowRight, belowLeft);
        } else {
          builder.addTriangle(a, belowLeft, b);
          builder.addTriangle(b, belowLeft, belowRight);
        }
      }
    }
  });
}

export function triangleCountOf(geometry) {
  return geometry.indices.length / 3;
}