3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { forEachChunk } from './cooperative.js';
export const COMPONENT_TYPES = {
5120: Int8Array,
5121: Uint8Array,
5122: Int16Array,
5123: Uint16Array,
5125: Uint32Array,
5126: Float32Array,
};
const SPARSE_INDEX_COMPONENT_TYPES = [5121, 5123, 5125];
const COMPONENT_COUNTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
const NORMALIZATION_DIVISORS = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };
// Only the four integer types scale; a normalized flag on a float or 32-bit integer accessor changes nothing, as in three.js.
function divisorOf(attribute) {
return attribute.normalized ? NORMALIZATION_DIVISORS[attribute.componentType] ?? 1 : 1;
}
function fillFloats(attribute, values, divisor, from, to) {
for (let index = from; index < to; index++) {
const value = attribute.array[index];
values[index] = divisor === 1 ? value : Math.max(value / divisor, -1);
}
}
/** Float values of an attribute, with normalized integers scaled into zero to one or minus one to one. */
export function attributeFloats(attribute) {
const length = attribute.count * attribute.itemSize;
const values = new Float32Array(length);
fillFloats(attribute, values, divisorOf(attribute), 0, length);
return values;
}
/** The same values as attributeFloats, converted a chunk at a time with `checkpoint()` between chunks so a large attribute does not block the page. */
export async function attributeFloatsInSlices(attribute, checkpoint) {
const length = attribute.count * attribute.itemSize;
const values = new Float32Array(length);
const divisor = divisorOf(attribute);
await forEachChunk(length, checkpoint, (from, to) => fillFloats(attribute, values, divisor, from, to));
return values;
}
const MATRIX_COLUMNS = { MAT2: 2, MAT3: 3, MAT4: 4 };
/** Matrix columns as [tight bytes, stored bytes]: the glTF spec pads each MAT2 or MAT3 column to a multiple of 4 bytes. */
function columnBytesOf(accessor) {
const tight = MATRIX_COLUMNS[accessor.type] * COMPONENT_TYPES[accessor.componentType].BYTES_PER_ELEMENT;
return [tight, Math.ceil(tight / 4) * 4];
}
function elementBytesOf(accessor) {
const columns = MATRIX_COLUMNS[accessor.type];
if (columns) return columns * columnBytesOf(accessor)[1];
return COMPONENT_TYPES[accessor.componentType].BYTES_PER_ELEMENT * COMPONENT_COUNTS[accessor.type];
}
function removeColumnPadding(packed, accessor) {
const columns = MATRIX_COLUMNS[accessor.type];
const [tightBytes, storedBytes] = columnBytesOf(accessor);
if (!columns || tightBytes === storedBytes) return packed;
const tight = new Uint8Array(accessor.count * columns * tightBytes);
for (let column = 0; column < accessor.count * columns; column++) {
tight.set(packed.subarray(column * storedBytes, column * storedBytes + tightBytes), column * tightBytes);
}
return tight;
}
/** The distance between elements of a buffer view: its byteStride, which must hold one element and be a multiple of 4. */
function strideOf(view, elementBytes, viewIndex) {
if (!view.byteStride) return elementBytes;
if (!Number.isInteger(view.byteStride) || view.byteStride < elementBytes) {
throw new Error(`Invalid glTF bufferViews[${viewIndex}].byteStride ${view.byteStride}: an accessor element needs ${elementBytes} bytes. Fix: use a byteStride of at least ${elementBytes} that is a multiple of 4.`);
}
if (view.byteStride % 4 !== 0) {
throw new Error(`Invalid glTF bufferViews[${viewIndex}].byteStride ${view.byteStride}: it must be a multiple of 4. Fix: round it up to ${Math.ceil(view.byteStride / 4) * 4}.`);
}
return view.byteStride;
}
function checkElementsFit(source, offset, stride, count, elementBytes) {
if (!Number.isSafeInteger(offset) || offset < 0) {
throw new Error(`Invalid glTF byteOffset ${JSON.stringify(offset)}: it must be a non-negative integer. Fix: use an offset from 0 up to the buffer view length.`);
}
if (count > 0 && offset + (count - 1) * stride + elementBytes > source.length) {
throw new Error('glTF accessor exceeds its buffer view.');
}
}
// Tightly packed elements are one block of bytes. Uint8Array.prototype.slice copies even when `source` is a Node Buffer, whose own slice is a view.
function copyTightly(source, offset, count, elementBytes) {
return Uint8Array.prototype.slice.call(source, offset, offset + count * elementBytes);
}
function copyStridedRange(source, offset, stride, elementBytes, packed, from, to) {
for (let element = from; element < to; element++) {
const start = offset + element * stride;
packed.set(source.subarray(start, start + elementBytes), element * elementBytes);
}
}
function copyElements(source, offset, stride, count, elementBytes) {
checkElementsFit(source, offset, stride, count, elementBytes);
if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);
const packed = new Uint8Array(count * elementBytes);
copyStridedRange(source, offset, stride, elementBytes, packed, 0, count);
return packed;
}
async function copyElementsInSlices(source, offset, stride, count, elementBytes, checkpoint) {
checkElementsFit(source, offset, stride, count, elementBytes);
if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);
const packed = new Uint8Array(count * elementBytes);
await forEachChunk(count, checkpoint, (from, to) => copyStridedRange(source, offset, stride, elementBytes, packed, from, to));
return packed;
}
/** Sparse substitution needs a whole-number count of 1 up to the accessor count, and an indices and a values block. */
function checkSparseShape(accessor) {
const { count, indices, values } = accessor.sparse;
if (!Number.isInteger(count) || count < 1 || count > accessor.count || !indices || !values) {
throw new Error(`Invalid glTF sparse: it needs indices, values and a whole count from 1 to ${accessor.count}.`);
}
}
/**
* Indices of meshopt views that hold no elements (count 0) and that nothing reads: every accessor on them is empty. Other tools write
* such views for a mesh that simplified to nothing. A view that a non-empty accessor, a sparse accessor or an image reads is not listed,
* so it still fails with the count error instead of producing a short array.
*/
export function unreadEmptyMeshoptViews(document) {
const empty = new Set();
(document.bufferViews ?? []).forEach((view, index) => {
if (view?.extensions?.EXT_meshopt_compression?.count === 0) empty.add(index);
});
if (!empty.size) return empty;
for (const accessor of document.accessors ?? []) {
if (accessor.count === 0 && !accessor.sparse) continue;
empty.delete(accessor.bufferView);
empty.delete(accessor.sparse?.indices?.bufferView);
empty.delete(accessor.sparse?.values?.bufferView);
}
for (const image of document.images ?? []) empty.delete(image.bufferView);
return empty;
}
/**
* Reads accessors as tightly packed typed arrays, with sparse substitution and meshopt buffer views.
* `bufferBytes(index)` returns the bytes of a glTF buffer. `meshoptDecoder` replaces the built-in decoder of compressed views.
*/
export function createAccessorReader(document, bufferBytes, meshoptDecoder) {
const viewCache = new Map();
function plainViewBytes(view) {
const source = bufferBytes(view.buffer);
const offset = view.byteOffset ?? 0;
const length = view.byteLength;
if (!source || !Number.isSafeInteger(length) || length < 0 || offset < 0 || offset + length > source.length) {
throw new Error('glTF buffer view exceeds its buffer.');
}
return source.subarray(offset, offset + length);
}
/** Decode every meshopt view before any accessor is read, so reading stays synchronous. The decoder loads only for a file that has one. */
async function prepare() {
const views = document.bufferViews ?? [];
if (!views.some(view => view.extensions?.EXT_meshopt_compression)) return;
const { decodeMeshoptViews } = await import('./gltf-meshopt.js');
const skippedViews = unreadEmptyMeshoptViews(document);
for (const [index, bytes] of await decodeMeshoptViews(views, bufferBytes, meshoptDecoder, skippedViews)) viewCache.set(index, bytes);
}
function viewBytes(index) {
const view = document.bufferViews?.[index];
if (!view) throw new Error('Invalid glTF buffer view index.');
if (!viewCache.has(index)) viewCache.set(index, plainViewBytes(view));
return viewCache.get(index);
}
function planAccessor(index) {
const accessor = document.accessors?.[index];
if (!accessor) throw new Error('Invalid glTF accessor index.');
const ArrayType = COMPONENT_TYPES[accessor.componentType];
if (!ArrayType) throw new Error('Unsupported glTF accessor component type.');
const elementBytes = elementBytesOf(accessor);
const stride = accessor.bufferView === undefined ? 0 : strideOf(document.bufferViews[accessor.bufferView], elementBytes, accessor.bufferView);
return { accessor, ArrayType, itemSize: COMPONENT_COUNTS[accessor.type], elementBytes, stride };
}
function finishAccessor({ accessor, ArrayType, itemSize }, packed) {
const array = new ArrayType(removeColumnPadding(packed, accessor).buffer);
if (accessor.sparse) applySparse(accessor, array, itemSize);
return { array, itemSize, count: accessor.count, normalized: accessor.normalized === true, componentType: accessor.componentType };
}
function readAccessor(index) {
const plan = planAccessor(index);
const { accessor, elementBytes, stride } = plan;
const packed = accessor.bufferView === undefined
? new Uint8Array(accessor.count * elementBytes)
: copyElements(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes);
return finishAccessor(plan, packed);
}
/** The same accessor as readAccessor, copied a chunk at a time with `checkpoint()` between chunks. */
async function readAccessorInSlices(index, checkpoint) {
const plan = planAccessor(index);
const { accessor, elementBytes, stride } = plan;
const packed = accessor.bufferView === undefined
? new Uint8Array(accessor.count * elementBytes)
: await copyElementsInSlices(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes, checkpoint);
return finishAccessor(plan, packed);
}
function applySparse(accessor, array, itemSize, elementCount = accessor.count) {
checkSparseShape(accessor);
const { count, indices, values } = accessor.sparse;
const IndexType = SPARSE_INDEX_COMPONENT_TYPES.includes(indices.componentType) ? COMPONENT_TYPES[indices.componentType] : null;
if (!IndexType) throw new Error(`Unsupported sparse index component type ${indices.componentType}. Fix: use 5121, 5123 or 5125 (unsigned byte, short or int).`);
const indexBytes = copyElements(viewBytes(indices.bufferView), indices.byteOffset ?? 0, IndexType.BYTES_PER_ELEMENT, count, IndexType.BYTES_PER_ELEMENT);
const sparseIndices = new IndexType(indexBytes.buffer);
const itemBytes = array.BYTES_PER_ELEMENT * itemSize;
const valueBytes = copyElements(viewBytes(values.bufferView), values.byteOffset ?? 0, itemBytes, count, itemBytes);
const sparseValues = new array.constructor(valueBytes.buffer);
for (let item = 0; item < count; item++) {
if (sparseIndices[item] >= elementCount) throw new Error('Sparse accessor index is out of range.');
array.set(sparseValues.subarray(item * itemSize, (item + 1) * itemSize), sparseIndices[item] * itemSize);
}
}
/**
* Applies the sparse block of an accessor to data that did not come from its buffer view, such as a Draco-decoded attribute.
* KHR_draco_mesh_compression only replaces the accessor's bufferView and byteOffset, so sparse still substitutes on top.
*/
function applySparseToDecoded(index, attribute) {
const accessor = document.accessors?.[index];
if (!accessor?.sparse) return;
const ArrayType = COMPONENT_TYPES[accessor.componentType];
if (attribute.array.constructor !== ArrayType) {
throw new Error(`Accessor ${index} has a sparse block but its Draco data decoded as ${attribute.array.constructor.name}, not ${ArrayType?.name}. Fix: make the accessor componentType match the compressed attribute.`);
}
applySparse(accessor, attribute.array, attribute.itemSize, attribute.count);
}
return { prepare, readAccessor, readAccessorInSlices, viewBytes, applySparseToDecoded };
}