3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { TAG_PREFIX, meshTags } from './mesh-data.js';
import { fieldFaceMask } from './mesh-fields.js';
import { faceNormals, faceCentroids } from './mesh-normals.js';
import { cornerFaces, edgeCornerTable } from './mesh-topology.js';
// Semantic face selection for agents. A rule is plain JSON; the result is a Uint8Array mask with one byte per face.
//
// { "all": true }
// { "tag": "top" } faces carrying a tag (tags double as named selections)
// { "normal": [0, 1, 0], "maxAngle": 10 } faces whose normal is within maxAngle degrees of a direction
// { "inside": { "min": [x, y, z], "max": [x, y, z] } } faces whose centroid lies in a box
// { "faces": [0, 4, 7] } explicit face indices
// { "and": [rule, ...] }, { "or": [rule, ...] }, { "not": rule }
// { "grow": rule, "steps": 1 } add faces sharing an edge, repeated
// { "field": expression } faces where a field expression (mesh-fields.js) is nonzero
// { "boundary": rule } faces of the selection that touch an unselected face or an open edge
export const MAX_RULE_DEPTH = 16;
const MAX_RULE_NODES = 256;
const RULE_KEYS = ['all', 'tag', 'normal', 'inside', 'faces', 'and', 'or', 'not', 'grow', 'boundary', 'field'];
function ruleError(message) {
return new TypeError(`Selection rule: ${message}`);
}
function vector3(value, label) {
if (!Array.isArray(value) || value.length !== 3 || !value.every(Number.isFinite)) throw ruleError(`${label} needs three finite numbers.`);
return value;
}
/** Faces sharing an edge with each face, as compressed rows (built lazily once per selection call). */
function faceAdjacency(mesh) {
const table = edgeCornerTable(mesh);
const facesOfCorners = cornerFaces(mesh);
const neighbors = Array.from({ length: mesh.faceCount }, () => []);
const openFaces = new Uint8Array(mesh.faceCount);
for (let edge = 0; edge < mesh.edgeCount; edge++) {
const start = table.edgeOffsets[edge];
const end = table.edgeOffsets[edge + 1];
if (end - start === 1) openFaces[facesOfCorners[table.edgeCorners[start]]] = 1;
for (let first = start; first < end; first++) {
for (let second = first + 1; second < end; second++) {
const faceFirst = facesOfCorners[table.edgeCorners[first]];
const faceSecond = facesOfCorners[table.edgeCorners[second]];
neighbors[faceFirst].push(faceSecond);
neighbors[faceSecond].push(faceFirst);
}
}
}
return { neighbors, openFaces };
}
/**
* Evaluate a selection rule on a mesh. Throws a TypeError naming the bad part of the rule, and a RangeError for an
* unknown tag (listing the known ones).
*/
export function selectFaces(mesh, rule) {
const cache = {};
let nodes = 0;
const normals = () => (cache.normals ??= faceNormals(mesh).normals);
const centroids = () => (cache.centroids ??= faceCentroids(mesh));
const adjacency = () => (cache.adjacency ??= faceAdjacency(mesh));
function evaluate(node, depth) {
nodes++;
if (nodes > MAX_RULE_NODES) throw ruleError(`more than ${MAX_RULE_NODES} rule nodes.`);
if (depth > MAX_RULE_DEPTH) throw ruleError(`nesting deeper than ${MAX_RULE_DEPTH}.`);
if (!node || typeof node !== 'object' || Array.isArray(node)) throw ruleError('each rule must be an object.');
const keys = Object.keys(node);
const kind = keys.find(key => RULE_KEYS.includes(key));
if (!kind) throw ruleError(`use one of ${RULE_KEYS.join(', ')}; got ${keys.join(', ') || 'nothing'}.`);
const mask = new Uint8Array(mesh.faceCount);
switch (kind) {
case 'all':
if (node.all !== true || keys.length !== 1) throw ruleError('"all" must be true and alone.');
mask.fill(1);
return mask;
case 'tag': {
if (typeof node.tag !== 'string' || keys.length !== 1) throw ruleError('"tag" needs one tag name.');
const attribute = mesh.attributes.face[TAG_PREFIX + node.tag];
if (!attribute) throw new RangeError(`Unknown tag ${node.tag}. Known tags: ${meshTags(mesh).join(', ') || 'none'}.`);
// A tag byte is any nonzero value; the rules below combine masks bitwise, so store plain 0 or 1.
for (let face = 0; face < mesh.faceCount; face++) mask[face] = attribute.data[face] ? 1 : 0;
return mask;
}
case 'normal': {
const extra = keys.filter(key => key !== 'normal' && key !== 'maxAngle');
if (extra.length) throw ruleError(`unknown fields ${extra.join(', ')} in a normal rule.`);
const direction = vector3(node.normal, 'normal');
const length = Math.hypot(...direction);
if (length === 0) throw ruleError('normal cannot be zero.');
const maxAngle = node.maxAngle ?? 10;
if (!Number.isFinite(maxAngle) || maxAngle < 0 || maxAngle > 180) throw ruleError('maxAngle is degrees from 0 to 180.');
const limit = Math.cos(maxAngle * Math.PI / 180) - 1e-9;
const faceNormal = normals();
for (let face = 0; face < mesh.faceCount; face++) {
const cosine = (faceNormal[face * 3] * direction[0] + faceNormal[face * 3 + 1] * direction[1] + faceNormal[face * 3 + 2] * direction[2]) / length;
if (cosine >= limit) mask[face] = 1;
}
return mask;
}
case 'inside': {
if (keys.length !== 1 || !node.inside || typeof node.inside !== 'object') throw ruleError('"inside" needs { min, max }.');
const minimum = vector3(node.inside.min, 'inside.min');
const maximum = vector3(node.inside.max, 'inside.max');
const centroid = centroids();
for (let face = 0; face < mesh.faceCount; face++) {
let contained = true;
for (let axis = 0; axis < 3; axis++) {
const value = centroid[face * 3 + axis];
if (value < minimum[axis] || value > maximum[axis]) contained = false;
}
if (contained) mask[face] = 1;
}
return mask;
}
case 'faces': {
if (keys.length !== 1 || !Array.isArray(node.faces)) throw ruleError('"faces" needs an array of face indices.');
if (node.faces.length > mesh.faceCount) throw ruleError(`"faces" lists ${node.faces.length} indices but the mesh has ${mesh.faceCount} faces; list each face once.`);
for (const face of node.faces) {
if (!Number.isInteger(face) || face < 0 || face >= mesh.faceCount) throw new RangeError(`Face index ${face} is outside 0..${mesh.faceCount - 1}.`);
mask[face] = 1;
}
return mask;
}
case 'and':
case 'or': {
const children = node[kind];
if (keys.length !== 1 || !Array.isArray(children) || children.length === 0) throw ruleError(`"${kind}" needs a nonempty array of rules.`);
if (kind === 'and') mask.fill(1);
for (const child of children) {
const childMask = evaluate(child, depth + 1);
for (let face = 0; face < mesh.faceCount; face++) {
mask[face] = kind === 'and' ? mask[face] & childMask[face] : mask[face] | childMask[face];
}
}
return mask;
}
case 'not': {
if (keys.length !== 1) throw ruleError('"not" takes one rule.');
const childMask = evaluate(node.not, depth + 1);
for (let face = 0; face < mesh.faceCount; face++) mask[face] = childMask[face] ? 0 : 1;
return mask;
}
case 'grow': {
const extra = keys.filter(key => key !== 'grow' && key !== 'steps');
if (extra.length) throw ruleError(`unknown fields ${extra.join(', ')} in a grow rule.`);
const steps = node.steps ?? 1;
if (!Number.isInteger(steps) || steps < 1 || steps > 64) throw ruleError('grow steps must be an integer from 1 to 64.');
mask.set(evaluate(node.grow, depth + 1));
const { neighbors } = adjacency();
for (let step = 0; step < steps; step++) {
const previous = mask.slice();
for (let face = 0; face < mesh.faceCount; face++) {
if (!previous[face]) continue;
for (const neighbor of neighbors[face]) mask[neighbor] = 1;
}
}
return mask;
}
case 'field': {
if (keys.length !== 1) throw ruleError('"field" takes one expression.');
return fieldFaceMask(mesh, node.field);
}
case 'boundary': {
if (keys.length !== 1) throw ruleError('"boundary" takes one rule.');
const inner = evaluate(node.boundary, depth + 1);
const { neighbors, openFaces } = adjacency();
for (let face = 0; face < mesh.faceCount; face++) {
if (!inner[face]) continue;
if (openFaces[face] || neighbors[face].some(neighbor => !inner[neighbor])) mask[face] = 1;
}
return mask;
}
}
throw ruleError(`unsupported rule ${kind}.`);
}
return evaluate(rule, 0);
}
export function countSelected(mask) {
let count = 0;
for (let index = 0; index < mask.length; index++) count += mask[index];
return count;
}