Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
/**
* A delivery derivative with as few draw calls as the asset allows. Every repeated mesh becomes a
* GPU batch, then the one-off parts left over merge per material within spatial cells, so a viewer
* can still cull a large asset by region.
*
* Unlike `optimize: 'full'` this runs no `palette()`, which rewrites materials, and no `weld()`,
* which splits the accessors shared parts rely on: on a 16 MB cathedral `weld()` alone added 10 MB.
* Saved revisions are never rewritten by this pass; `exportAssetGlb` derives from them.
*/
import { type Document, Logger } from '@gltf-transform/core';
import { prune } from '@gltf-transform/functions';
import {
refreshAtlasDocumentProvenance,
validateAtlasDocumentProvenance,
} from './atlas-provenance';
import { createGltfIO } from './gltf-io';
import {
countInstanceBatches,
instanceByHandedness,
instancingBlocker,
} from './instance-handedness';
import { collectGlbMetrics } from './metrics';
import { assertFinalGlbValid } from './qa/gltf';
import { mergeRigidGroups, type RigidMergeSummary } from './rigid-merge';
/** Metres. Near the size a viewer's culling can use; set per export with `drawCellSize`. */
export const DEFAULT_DRAW_CELL_SIZE = 15;
/** Two copies already save a draw. The bake pass's higher threshold protects node names. */
const REPEAT_MIN = 2;
/**
* Metres a merged vertex may move through float32 rounding in its destination frame. The strict
* default rejects a metre-sized part baked 100 m from its destination, which rounds by about
* 8 micrometres. 0.1 mm stays far below a pixel at any distance the part is visible from.
*/
const POSITION_TOLERANCE = 1e-4;
export interface DrawReductionV1 {
drawsBefore: number;
drawsAfter: number;
batches: number;
instances: number;
/** Why no copy was batched, when something in the asset rules batching out. */
batchingSkipped?: string;
/**
* Each batch node, its mesh and the names of the nodes it replaced, in instance order: copy `i`
* is the batch's instance `i`. A batched copy loses its mesh, and one with no children or
* extensions is removed with its name; this is where its geometry went.
*/
instancing: { node: string; mesh: string; count: number; instances: string[] }[];
merges: number;
cellSize: number;
/** Primitives the merge left alone, by reason. */
locked: Record<string, number>;
/** Buckets left as authored because building or checking the join failed. */
rejected: RigidMergeSummary['rejected'];
}
export function assertDrawCellSize(cellSize: number): void {
if (!Number.isFinite(cellSize) || cellSize <= 0)
throw new Error('The draw cell size must be a positive number of metres');
}
/** Reduce a finished document's draw calls in place. */
export async function reduceDrawCalls(
doc: Document,
options: { cellSize?: number } = {},
): Promise<DrawReductionV1> {
const cellSize = options.cellSize ?? DEFAULT_DRAW_CELL_SIZE;
assertDrawCellSize(cellSize);
// Transform progress must not corrupt CLI JSON on stdout.
doc.setLogger(new Logger(Logger.Verbosity.WARN));
const drawsBefore = collectGlbMetrics(doc).drawCalls;
const batchingSkipped = instancingBlocker(doc);
const created = batchingSkipped ? [] : await instanceByHandedness(doc, REPEAT_MIN);
const { batches, instances } = countInstanceBatches(doc);
// `instance()` leaves batch nodes unnamed. Naming each after its first copy, uniquely, makes it
// addressable whether or not the exporter named the mesh.
const names = new Set(
doc
.getRoot()
.listNodes()
.map((node) => node.getName()),
);
const instancing = created.map(({ node, instances: copies }) => {
const mesh = node.getMesh()?.getName() ?? '';
const base = `${copies[0] || mesh || 'Mesh'}_Instances`;
let name = base;
for (let k = 1; names.has(name); k++) name = `${base}_${k}`;
names.add(name);
node.setName(name);
return { node: name, mesh, count: copies.length, instances: copies };
});
// Repeats are batches now. A copy left over shares its mesh with a batch, and baking it would
// duplicate geometry; mixed into a bucket it can also push the join past the vertex limit,
// which strands the true one-offs beside it. Only meshes with a single user merge.
const merge = mergeRigidGroups(doc, {
cellSize,
positionTolerance: POSITION_TOLERANCE,
expandSharedMeshes: false,
});
await doc.transform(prune({ keepLeaves: true, keepExtras: true, keepSolidTextures: true }));
const locked: Record<string, number> = {};
for (const { reason, primitives } of merge.locked)
locked[reason] = (locked[reason] ?? 0) + primitives;
return {
drawsBefore,
drawsAfter: collectGlbMetrics(doc).drawCalls,
batches,
instances,
...(batchingSkipped ? { batchingSkipped } : {}),
instancing,
merges: merge.merges,
cellSize,
locked,
rejected: merge.rejected,
};
}
/** {@link reduceDrawCalls} over GLB bytes, validated before they are handed back. */
export async function reduceGlbDrawCalls(
bytes: Uint8Array,
options: { cellSize?: number } = {},
): Promise<{ glb: Uint8Array; summary: DrawReductionV1 }> {
const io = createGltfIO();
const doc = await io.readBinary(bytes);
await validateAtlasDocumentProvenance(doc);
const summary = await reduceDrawCalls(doc, options);
await refreshAtlasDocumentProvenance(doc);
await validateAtlasDocumentProvenance(doc);
const glb = await io.writeBinary(doc);
await assertFinalGlbValid(glb);
return { glb, summary };
}