3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Square tiles over an area that pick a level of detail from the camera distance and rebuild only when it changes.
// Grass and ground clutter share it: each supplies `buildParts(tile, levelIndex)` and gets streamable parts back.
const HYSTERESIS = 1.1;
export const MAXIMUM_TILES = 262144;
/** Stable 32-bit hash of a tile (or any integer cell) and a seed. */
export function hashTile(seed, column, row) {
let mixed = Math.imul(column + 7919, 374761393) ^ Math.imul(row - 104729, 668265263) ^ Math.imul(seed, 2246822519);
mixed = Math.imul(mixed ^ mixed >>> 13, 1274126177);
return (mixed ^ mixed >>> 16) >>> 0;
}
/** Translation matrix that places tile-local geometry at the tile's corner. */
export function tileMatrix(tile) {
return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, tile.tileX, 0, tile.tileZ, 1]);
}
/**
* `levels` is a list of `{ distance }` from near to far; tiles past `cullDistance` are dropped.
* `buildParts(tile, levelIndex)` returns the tile's parts at that level (an empty array is fine).
* A tile keeps `tile.cache` between rebuilds for whatever the caller wants to plan once.
*/
export function createTileField({ area, tileSize, levels, cullDistance, terrainHeight, buildParts }) {
const extents = [area?.minX, area?.maxX, area?.minZ, area?.maxZ];
if (!extents.every(Number.isFinite) || area.maxX <= area.minX || area.maxZ <= area.minZ) {
throw new TypeError('area needs finite minX < maxX and minZ < maxZ; pass e.g. { minX: 0, maxX: 100, minZ: 0, maxZ: 100 }.');
}
if (!Number.isFinite(tileSize) || tileSize <= 0) throw new RangeError('tileSize must be a finite number > 0; pass e.g. 4.');
const columns = Math.ceil((area.maxX - area.minX) / tileSize);
const rows = Math.ceil((area.maxZ - area.minZ) / tileSize);
if (!(columns * rows <= MAXIMUM_TILES)) {
throw new RangeError(`The area needs ${columns} by ${rows} tiles, over the limit of ${MAXIMUM_TILES}. Pass a larger tileSize or a smaller area.`);
}
const tiles = [];
for (let row = 0; row < rows; row++) {
for (let column = 0; column < columns; column++) {
const tileX = area.minX + column * tileSize;
const tileZ = area.minZ + row * tileSize;
const centerX = tileX + tileSize / 2;
const centerZ = tileZ + tileSize / 2;
tiles.push({ column, row, tileX, tileZ, centerX, centerZ, centerY: terrainHeight(centerX, centerZ), level: -1, cache: {}, parts: [] });
}
}
function levelFor(tile, eye) {
const distance = Math.max(0, Math.hypot(eye[0] - tile.centerX, eye[1] - tile.centerY, eye[2] - tile.centerZ) - tileSize * 0.5);
if (distance > cullDistance) return -1;
let target = levels.findIndex(level => distance <= level.distance);
if (target === -1) target = levels.length - 1;
// Hysteresis: a tile only moves to a coarser level once it is clearly past the boundary, so tiles on an edge do not flicker.
if (tile.level >= 0 && target > tile.level && distance <= levels[tile.level].distance * HYSTERESIS) return tile.level;
return target;
}
let visibleParts = [];
function update(eye) {
if (!eye || eye.length < 3 || ![eye[0], eye[1], eye[2]].every(Number.isFinite)) throw new TypeError('update needs an eye position [x, y, z].');
let changed = false;
for (const tile of tiles) {
const target = levelFor(tile, eye);
if (target === tile.level) continue;
changed = true;
tile.level = target;
tile.parts = target === -1 ? [] : buildParts(tile, target);
}
if (changed) visibleParts = tiles.flatMap(tile => tile.parts);
return changed;
}
function stats() {
const levelCounts = levels.map(() => 0);
let visibleTiles = 0;
let triangles = 0;
let vertices = 0;
for (const tile of tiles) {
if (tile.parts.length === 0) continue;
visibleTiles += 1;
levelCounts[tile.level] += 1;
for (const part of tile.parts) {
triangles += part.geometry.indices.length / 3;
vertices += part.geometry.positions.length / 3;
}
}
// Position, normal, uv and colour floats per vertex, three 32-bit indices per triangle.
return { tiles: tiles.length, visibleTiles, levelCounts, triangles, vertices, geometryBytes: vertices * 11 * 4 + triangles * 12 };
}
return { get parts() { return visibleParts; }, update, stats };
}