Skip to content

3D engine that AI agents drive

20.8 KB
Raw Blame
import { validateMorphGeometry, validateMorphPose } from './morph.js';
import { gltfExtensionsFromLayers, LAYER_TEXTURE_SLOTS } from './gltf-layers.js';
import { validateSkinGeometry } from './skinning.js';
import { boxProjectedGeometry, columnLengths } from './export-box-uv.js';
import { createTextureWriter } from './export-textures.js';
import { createGlbWriter } from './export-writer.js';
import { buildHierarchy, decomposeMatrix, hierarchyNodeFields, hostOfPart, normalizedWeights, relativeMatrix, writeAnimations, writeSkin } from './export-skeleton.js';

const EMISSIVE_STRENGTH = 'KHR_materials_emissive_strength';

function validateFloatChannel(values, length, label, bounded = false) {
  if (!(values instanceof Float32Array) || values.length !== length) {
    throw new TypeError(`${label} requires a Float32Array matching the vertex count.`);
  }
  for (const value of values) {
    if (!Number.isFinite(value) || (bounded && (value < 0 || value > 1))) {
      throw new RangeError(`${label} requires finite values${bounded ? ' within [0,1]' : ''}.`);
    }
  }
}

// glTF has no additive blending, so an add material is written as BLEND and loads back as blend.
const GLTF_ALPHA_MODES = { mask: 'MASK', blend: 'BLEND', add: 'BLEND' };

function writeAlphaFields(gltfMaterial, material) {
  const alphaMode = material.alphaMode ?? 'opaque';
  if (alphaMode !== 'opaque') {
    if (!Object.hasOwn(GLTF_ALPHA_MODES, alphaMode)) throw new Error("alphaMode must be 'opaque', 'mask', 'blend' or 'add'.");
    gltfMaterial.alphaMode = GLTF_ALPHA_MODES[alphaMode];
    validateFactor(material.opacity ?? 1, 'opacity');
    gltfMaterial.pbrMetallicRoughness.baseColorFactor[3] = material.opacity ?? 1;
  }
  if (alphaMode === 'mask') {
    validateFactor(material.alphaCutoff ?? 0.5, 'alphaCutoff');
    gltfMaterial.alphaCutoff = material.alphaCutoff ?? 0.5;
  }
  if (material.doubleSided === true) gltfMaterial.doubleSided = true;
}

function validateFactor(value, label, maximum = 1) {
  if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value)) || value < 0 || value > maximum) {
    throw new RangeError(`${label} requires a finite nonnegative Float32 value${maximum === 1 ? ' within [0,1]' : ''}.`);
  }
}

function validateColor(values, label) {
  if (!values || values.length !== 3) throw new TypeError(`${label} requires three linear RGB components.`);
  for (const value of values) validateFactor(value, label);
}

function validateGeometry(geometry, partName) {
  const count = geometry?.positions?.length;
  if (!Number.isSafeInteger(count) || count < 3 || count % 3 !== 0) {
    throw new TypeError('GLB positions require a nonempty array of XYZ vertices.');
  }
  validateFloatChannel(geometry.positions, count, 'GLB positions');
  validateFloatChannel(geometry.normals, count, 'GLB normals');
  for (let offset = 0; offset < count; offset += 3) {
    const length = Math.hypot(geometry.normals[offset], geometry.normals[offset + 1], geometry.normals[offset + 2]);
    if (Math.abs(length - 1) > 0.001) throw new RangeError('GLB normals require unit vectors.');
  }
  if (geometry.colors !== undefined) validateFloatChannel(geometry.colors, count, 'GLB colors', true);
  if (geometry.uvs !== undefined) validateFloatChannel(geometry.uvs, count / 3 * 2, 'GLB UVs');
  if (geometry.lightUvs !== undefined) validateFloatChannel(geometry.lightUvs, count / 3 * 2, 'GLB lightUvs');
  if (geometry.indices instanceof Uint32Array && geometry.indices.length === 0) {
    throw new RangeError(`GLB part ${partName} has no triangles. Terrain holes may cover the whole ground: lower a radius or move a center.`);
  }
  if (!(geometry.indices instanceof Uint32Array) || geometry.indices.length % 3 !== 0) {
    throw new TypeError('GLB indices require a nonempty Uint32Array of triangles.');
  }
  for (const index of geometry.indices) {
    if (index >= count / 3) throw new RangeError('GLB index exceeds the vertex count.');
  }
}

// A skinned part takes its pose from its joints, so only parts with a node transform need a valid matrix.
function validateMatrix(matrix, part, nodePaths) {
  if (!matrix || matrix.length !== 16 || Array.from(matrix).some(value => !Number.isFinite(value) || !Number.isFinite(Math.fround(value)))) {
    throw new RangeError('GLB matrix requires 16 finite components.');
  }
  if (matrix[3] !== 0 || matrix[7] !== 0 || matrix[11] !== 0 || matrix[15] !== 1) {
    throw new RangeError('GLB matrix requires an affine transform.');
  }
  validateTransformColumns(matrix, part, nodePaths);
}

function partLabel(part, nodePaths) {
  const path = nodePaths?.[part.name];
  return `part "${part.name}"${path && path !== part.name ? ` (${path})` : ''}`;
}

function materialLabel(part) {
  return part.material.id ? `material "${part.material.id}" of ${part.name}` : `material of part "${part.name}"`;
}

// An emissive color above 1 is allowed: the writer moves the excess into KHR_materials_emissive_strength.
function validateEmissiveColor(part) {
  const color = part.material.emissiveColor ?? part.material.color;
  if (!color || color.length !== 3 || Array.from(color).some(value => !Number.isFinite(Math.fround(value)) || value < 0)) {
    throw new RangeError(`GLB ${materialLabel(part)} needs emissiveColor as three finite numbers of 0 or more, such as [1, 0.5, 0.1].`);
  }
}

function validatePart(part) {
  const material = part.material;
  if (!material || typeof material !== 'object') throw new TypeError('GLB parts require a material.');
  validateColor(material.color, 'GLB base color');
  validateEmissiveColor(part);
  validateFactor(material.metallic, 'GLB metallic factor');
  validateFactor(material.roughness, 'GLB roughness factor');
  validateFactor(material.emission ?? 0, 'GLB emission', Infinity);
}

function validateTransformColumns(matrix, part, nodePaths) {
  const columns = [0, 4, 8].map(offset => {
    const values = [Math.fround(matrix[offset]), Math.fround(matrix[offset + 1]), Math.fround(matrix[offset + 2])];
    const length = Math.hypot(...values);
    // Three's matrix decomposition divides by scale, so zero scales cannot roundtrip.
    if (length === 0) throw new RangeError('GLB matrix requires nonzero scales.');
    return values.map(value => value / length);
  });
  // Normalized column products remove scale dependence and allow Float32 TRS roundoff.
  const tolerance = 8 * 2 ** -23;
  for (let first = 0; first < 3; first++) {
    for (let second = first + 1; second < 3; second++) {
      let dot = 0;
      for (let axis = 0; axis < 3; axis++) dot += columns[first][axis] * columns[second][axis];
      if (Math.abs(dot) > tolerance) throw new RangeError(`GLB ${partLabel(part, nodePaths)} cannot preserve shear: its world transform stretches along axes that are not at right angles, which a glTF node cannot hold. Put the stretch on the node that holds the mesh (the child), or give its parents a uniform scale.`);
    }
  }
}

const TEXTURE_CHANNELS = ['map', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
const OPTION_NAMES = ['clips', 'nodes', 'maxTextureSize', 'nodePaths'];

function validateOptions(options) {
  if (!options || typeof options !== 'object') throw new TypeError('GLB export options must be an object.');
  for (const name of Object.keys(options)) {
    if (!OPTION_NAMES.includes(name)) throw new TypeError(`GLB export does not take ${name}. Options: ${OPTION_NAMES.join(', ')}.`);
  }
  if (options.clips !== undefined && !Array.isArray(options.clips)) throw new TypeError('GLB export clips must be an array.');
  if (options.nodes !== undefined && !Array.isArray(options.nodes)) throw new TypeError('GLB export nodes must be an array.');
}

// JOINTS_0 points into skin.joints; weight 0 padding slots may hold any index.
function validateJointIndices({ name, geometry: { skinIndices, skinWeights }, skin }) {
  const count = skin?.joints?.length;
  skinIndices?.forEach((joint, slot) => {
    if (count && skinWeights[slot] > 0 && !(joint < count)) throw new RangeError(`GLB part ${name} vertex ${slot >> 2} has joint index ${joint}, but its skin has ${count} joints.`);
  });
}

function validateSkinnedPart(part) {
  validateJointIndices(part);
  validateSkinGeometry(part.geometry, part.skin);
}

function createIdentityTracker() {
  const identities = new WeakMap();
  let next = 0;
  return object => {
    if (!identities.has(object)) identities.set(object, next++);
    return identities.get(object);
  };
}

function materialKeyOf(material, identify) {
  const textures = [...TEXTURE_CHANNELS, 'lightMap'].map(channel => material[channel] ? identify(material[channel]) : null);
  const layerTextures = Object.entries(material.layerMaps ?? {}).map(([name, descriptor]) => [name, identify(descriptor)]);
  const fields = { ...material };
  for (const channel of [...TEXTURE_CHANNELS, 'lightMap', 'layerMaps', 'pattern', 'boxMapScale', 'boxMapAxis']) delete fields[channel];
  return JSON.stringify([fields, textures, layerTextures, material.boxMapScale ?? 0, material.boxMapAxis ?? 1]);
}

/** Adds the layer textures to the KHR_materials_* objects, creating an extension that only has textures to carry. */
function writeLayerTextures(writer, textureWriter, material, layerExtensions) {
  for (const [extensionName, property] of LAYER_TEXTURE_SLOTS) {
    const descriptor = material.layerMaps?.[property];
    if (!descriptor) continue;
    if (!layerExtensions[extensionName]) {
      layerExtensions[extensionName] = {};
      writer.addExtension(extensionName);
    }
    layerExtensions[extensionName][property] = textureReference(textureWriter, descriptor, property);
  }
}

function textureReference(textureWriter, descriptor, channel) {
  const reference = { index: textureWriter.textureIndex(descriptor, channel) };
  if (descriptor.uvChannel === 1) reference.texCoord = 1;
  return reference;
}

/**
 * glTF has no light map slot, so a baked light map goes out as the emissive texture on TEXCOORD_1: the light that
 * arrives, tinted by the base colour factor and not by a base color texture. Parts with their own emission keep it.
 */
function writeLightMap(writer, textureWriter, material, gltfMaterial) {
  if (!material.lightMap || material.emissiveMap || (material.emission ?? 0) !== 0) return;
  const tint = Array.from(material.color, channel => channel * (1 - material.metallic));
  gltfMaterial.emissiveFactor = tint;
  gltfMaterial.emissiveTexture = { index: textureWriter.textureIndex(material.lightMap, 'lightMap'), texCoord: 1 };
  const strength = material.lightMapScale ?? 1;
  if (strength !== 1) {
    gltfMaterial.extensions = { ...gltfMaterial.extensions, [EMISSIVE_STRENGTH]: { emissiveStrength: strength } };
    writer.addExtension(EMISSIVE_STRENGTH, { required: true });
  }
}

/** An emissive factor holds at most 1 per channel: the excess moves into the strength, which renders the same. */
function foldEmissiveExcess(gltfMaterial, strength) {
  const peak = Math.max(...gltfMaterial.emissiveFactor);
  if (strength === 0 || peak <= 1) return strength;
  gltfMaterial.emissiveFactor = gltfMaterial.emissiveFactor.map(channel => channel / peak);
  return strength * peak;
}

function writeMaterial(writer, textureWriter, material) {
  const pbr = { baseColorFactor: [...material.color, 1], metallicFactor: material.metallic, roughnessFactor: material.roughness };
  const gltfMaterial = {
    pbrMetallicRoughness: pbr,
    emissiveFactor: (material.emission ?? 0) === 0 ? [0, 0, 0] : Array.from(material.emissiveColor ?? material.color),
  };
  writeAlphaFields(gltfMaterial, material);
  const layerExtensions = gltfExtensionsFromLayers(material);
  for (const extensionName of Object.keys(layerExtensions)) writer.addExtension(extensionName);
  writeLayerTextures(writer, textureWriter, material, layerExtensions);
  if (Object.keys(layerExtensions).length > 0) gltfMaterial.extensions = layerExtensions;
  const strength = foldEmissiveExcess(gltfMaterial, material.emission ?? 0);
  if (strength > 0 && strength < 1) {
    // KHR_materials_emissive_strength allows only values of 1 or more, so a weaker emission is folded into the factor.
    gltfMaterial.emissiveFactor = gltfMaterial.emissiveFactor.map(channel => channel * strength);
  } else if (strength > 1) {
    gltfMaterial.extensions = { ...gltfMaterial.extensions, [EMISSIVE_STRENGTH]: { emissiveStrength: strength } };
    writer.addExtension(EMISSIVE_STRENGTH, { required: true });
  }
  const textureOf = channel => textureReference(textureWriter, material[channel], channel);
  if (material.map) pbr.baseColorTexture = textureOf('map');
  if (material.metallicRoughnessMap) pbr.metallicRoughnessTexture = textureOf('metallicRoughnessMap');
  if (material.normalMap) gltfMaterial.normalTexture = { ...textureOf('normalMap'), scale: material.normalScale?.[0] ?? 1 };
  if (material.occlusionMap) gltfMaterial.occlusionTexture = { ...textureOf('occlusionMap'), strength: material.occlusionStrength ?? 1 };
  if (material.emissiveMap) gltfMaterial.emissiveTexture = textureOf('emissiveMap');
  writeLightMap(writer, textureWriter, material, gltfMaterial);
  return gltfMaterial;
}

function writeGeometry(writer, geometry) {
  const ARRAY_BUFFER = 34962;
  const attributes = { POSITION: writer.addAccessor(geometry.positions, 'VEC3', ARRAY_BUFFER), NORMAL: writer.addAccessor(geometry.normals, 'VEC3', ARRAY_BUFFER) };
  const primitive = { attributes, indices: writer.addAccessor(geometry.indices, 'SCALAR', 34963) };
  if (geometry.colors) attributes.COLOR_0 = writer.addAccessor(geometry.colors, 'VEC3', ARRAY_BUFFER);
  if (geometry.uvs) attributes.TEXCOORD_0 = writer.addAccessor(geometry.uvs, 'VEC2', ARRAY_BUFFER);
  if (geometry.lightUvs) attributes.TEXCOORD_1 = writer.addAccessor(geometry.lightUvs, 'VEC2', ARRAY_BUFFER);
  if (geometry.skinIndices) {
    attributes.JOINTS_0 = writer.addAccessor(Uint16Array.from(geometry.skinIndices), 'VEC4', ARRAY_BUFFER, { bounds: false });
    attributes.WEIGHTS_0 = writer.addAccessor(normalizedWeights(geometry.skinWeights), 'VEC4', ARRAY_BUFFER, { bounds: false });
  }
  if (geometry.morphTargets) {
    primitive.targets = geometry.morphTargets.map(target => {
      const channels = {};
      if (target.positions) channels.POSITION = writer.addAccessor(target.positions, 'VEC3', ARRAY_BUFFER);
      if (target.normals) channels.NORMAL = writer.addAccessor(target.normals, 'VEC3', ARRAY_BUFFER);
      return channels;
    });
  }
  return primitive;
}

function requireUvsForTextures(part) {
  const textured = TEXTURE_CHANNELS.some(channel => part.material[channel]);
  const boxMapped = (part.material.boxMapScale ?? 0) > 0;
  if (textured && !boxMapped && !part.geometry.uvs) {
    throw new RangeError(`GLB part ${part.name} has textures but its geometry has no uvs. Add a uv_unwrap node to the mesh stack, or set geometry.uvs.`);
  }
  if (usesSecondUvSet(part.material) && !part.geometry.lightUvs) {
    throw new RangeError(`GLB part ${part.name} has a lightMap or a map with uvChannel 1 but its geometry has no lightUvs. Set geometry.lightUvs, or use uvChannel 0 and remove the lightMap.`);
  }
}

function usesSecondUvSet(material) {
  const descriptors = [...TEXTURE_CHANNELS.map(channel => material[channel]), ...Object.values(material.layerMaps ?? {})];
  const lightMapWritten = Boolean(material.lightMap) && !material.emissiveMap && (material.emission ?? 0) === 0;
  return lightMapWritten || descriptors.some(descriptor => descriptor?.uvChannel === 1);
}

/**
 * Returns a self-contained GLB ArrayBuffer for the parts.
 * Options: `clips` (createAnimationClip form, track targets are node names), `nodes` (the `nodes` of a parsed asset,
 * which hold joints and groups, so skinned parts and clips keep their hierarchy), `maxTextureSize` (default 2048),
 * `nodePaths` (part name to a label such as "parent > child", which an error names).
 */
export function exportGlb(parts, options = {}) {
  if (!Array.isArray(parts) || parts.length === 0) throw new TypeError('GLB export requires a nonempty parts array.');
  validateOptions(options);
  const validatedGeometries = new Set();
  const morphMetadata = new Map();
  for (const part of parts) {
    if (!validatedGeometries.has(part?.geometry)) {
      validateGeometry(part?.geometry, part?.name);
      validatedGeometries.add(part.geometry);
    }
    validatePart(part);
    const metadata = morphMetadata.get(part.geometry);
    if (metadata) {
      validateMorphPose(part.morph, metadata);
    } else {
      morphMetadata.set(part.geometry, validateMorphGeometry(part.geometry, part.morph));
    }
    validateSkinnedPart(part);
    requireUvsForTextures(part);
  }
  const hierarchy = buildHierarchy(parts, options.nodes);
  const worldCache = new Map();
  parts.forEach((part, partIndex) => {
    if (part.skin) return;
    const host = part.matrix?.length === 16 ? hostOfPart(partIndex, hierarchy, worldCache) : null;
    validateMatrix(host ? relativeMatrix(part.matrix, host.world) : part.matrix, part, options.nodePaths);
  });
  const writer = createGlbWriter();
  const { document } = writer;
  const textureWriter = createTextureWriter(writer, options.maxTextureSize);
  const nodeIndexByName = new Map(hierarchy.map((node, index) => [node.name, index]));
  const geometries = new Map();
  const materials = new Map();
  const meshes = new Map();
  const skins = new Map();
  const identify = createIdentityTracker();

  function geometryFor(part) {
    const boxMapped = (part.material.boxMapScale ?? 0) > 0;
    const scale = columnLengths(part.matrix);
    const variant = boxMapped ? `box:${part.material.boxMapScale}:${part.material.boxMapAxis ?? 1}:${scale.join(',')}` : 'authored';
    if (!geometries.has(part.geometry)) geometries.set(part.geometry, new Map());
    const variants = geometries.get(part.geometry);
    if (!variants.has(variant)) {
      const source = boxMapped ? boxProjectedGeometry(part.geometry, scale, part.material.boxMapScale, part.material.boxMapAxis ?? 1) : part.geometry;
      variants.set(variant, writeGeometry(writer, source));
    }
    return variants.get(variant);
  }

  for (const node of hierarchy) document.nodes.push({ name: node.name, ...hierarchyNodeFields(node) });
  hierarchy.forEach((node, index) => {
    if (node.parent >= 0) (document.nodes[node.parent].children ??= []).push(index);
  });
  const sceneRoots = hierarchy.flatMap((node, index) => node.parent < 0 ? [index] : []);
  parts.forEach((part, partIndex) => {
    const geometry = geometryFor(part);
    const materialKey = materialKeyOf(part.material, identify);
    if (!materials.has(materialKey)) {
      materials.set(materialKey, document.materials.length);
      document.materials.push(writeMaterial(writer, textureWriter, part.material));
    }
    const material = materials.get(materialKey);
    const meshKey = `${geometry.indices}:${material}`;
    if (!meshes.has(meshKey)) {
      meshes.set(meshKey, document.meshes.length);
      // glTF has no field for morph target names; the common convention is mesh.extras.targetNames.
      const targetNames = part.geometry.morphTargetNames;
      document.meshes.push({ primitives: [{ ...geometry, material }], ...(targetNames ? { extras: { targetNames } } : {}) });
    }
    const host = part.skin ? null : hostOfPart(partIndex, hierarchy, worldCache);
    // The mesh node of an imported asset is one of its nodes: keep the mesh on it instead of nesting a same-named node.
    const mergeIntoHost = host && hierarchy[host.index].name === part.name && hierarchy[host.index].meshIds.length === 1;
    // Clips address nodes by name, and loaders rename duplicates, so a mesh node never shares a joint's name.
    const meshNodeName = nodeIndexByName.has(part.name) ? `${part.name} mesh` : part.name;
    const node = mergeIntoHost ? document.nodes[host.index] : { name: meshNodeName };
    node.mesh = meshes.get(meshKey);
    if (part.morph) node.weights = Array.from(part.morph.weights);
    if (part.skin) {
      // A skinned mesh takes its pose from its joints, so its own node stays at the origin.
      node.skin = writeSkin(writer, part.skin, nodeIndexByName, skins);
    } else if (!mergeIntoHost) {
      node.matrix = Array.from(host ? relativeMatrix(part.matrix, host.world) : part.matrix);
    }
    if (mergeIntoHost) return;
    document.nodes.push(node);
    const nodeIndex = document.nodes.length - 1;
    if (host) (document.nodes[host.index].children ??= []).push(nodeIndex);
    else sceneRoots.push(nodeIndex);
  });
  document.scenes[0].nodes = sceneRoots;
  if (options.clips?.length) {
    for (const [index, node] of document.nodes.entries()) {
      if (!nodeIndexByName.has(node.name)) nodeIndexByName.set(node.name, index);
    }
    writeAnimations(writer, options.clips, nodeIndexByName, nodeIndex => {
      const node = document.nodes[nodeIndex];
      if (!node.matrix) return;
      Object.assign(node, decomposeMatrix(node.matrix));
      delete node.matrix;
    });
  }
  return writer.finish();
}

export function downloadGlb(parts, options) {
  const url = URL.createObjectURL(new Blob([exportGlb(parts, options)], { type: 'model/gltf-binary' }));
  const link = document.createElement('a');
  link.href = url;
  link.download = 'crucible-wall-e.glb';
  link.click();
  setTimeout(() => URL.revokeObjectURL(url), 1000);
}