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
/**
* Levels of detail in the local viewer.
*
* three's GLTFLoader does not implement `MSFT_lod`: it draws each chain's LOD0 and everything
* outside the chains, which is the intended degrade. The viewer builds each chain's lower
* levels through the same parser, node by node, and keeps them detached until the level
* control asks for one; the chosen level then stands at LOD0's place among its siblings. A
* chain with fewer levels than the chosen one shows its last level. Chains Kiln wrote and
* chains another tool wrote load the same way. A lower level keeps its `KHR_node_visibility`
* flags, and every count is of what draws.
*/
import type * as THREE from 'three';
import type { GLTF } from 'three/addons/loaders/GLTFLoader.js';
import { applyNodeVisibility } from './visibility';
export interface ViewerLodChain {
/** The GLB node index identifies a chain within this loaded artifact. */
id: string;
label: string;
/** LOD0 first. LOD0 is in the scene as loaded; the lower levels start detached. */
levels: THREE.Object3D[];
}
export interface ViewerLevels {
chains: ViewerLodChain[];
/** Triangles the whole model draws at each level, LOD0 first. */
triangles: number[];
}
export interface ViewerLevelState {
/** Actual triangles in the current combination, including geometry outside the chains. */
triangles: number;
/** Whole-asset totals when every chain uses the same index. */
levels: number[];
chains: { id: string; label: string; level: number; triangles: number[] }[];
}
/** Triangles drawn by the meshes under `object`, instances counted; hidden subtrees draw none. */
export function countTriangles(object: THREE.Object3D): number {
let triangles = 0;
object.traverseVisible((node) => {
const mesh = node as THREE.Mesh & Partial<THREE.InstancedMesh>;
if (!mesh.isMesh) return;
const vertices = mesh.geometry.index?.count ?? mesh.geometry.attributes.position?.count ?? 0;
triangles += (vertices / 3) * (mesh.isInstancedMesh ? mesh.count! : 1);
});
return triangles;
}
interface NodeJson {
extensions?: { MSFT_lod?: { ids?: unknown } };
}
/**
* Build the lower levels of every chain whose LOD0 the loaded scene holds, or `undefined`
* when there is none. A chain that lists a node the scene already draws is skipped, as is a
* chain inside another chain's LOD0, so each level swaps whole.
*/
export async function loadViewerLevels(gltf: GLTF): Promise<ViewerLevels | undefined> {
const nodes = (gltf.parser.json as { nodes?: NodeJson[] }).nodes ?? [];
const inScene = new Map<number, THREE.Object3D>();
gltf.scene.traverse((object) => {
const index = gltf.parser.associations.get(object)?.nodes;
if (index !== undefined && !inScene.has(index)) inScene.set(index, object);
});
const bases = new Set<THREE.Object3D>();
const chains: ViewerLodChain[] = [];
for (const [index, base] of inScene) {
const ids = nodes[index]?.extensions?.MSFT_lod?.ids;
if (!Array.isArray(ids) || ids.length === 0) continue;
if (
ids.some((id) => !Number.isInteger(id) || !nodes[id as number] || inScene.has(id as number))
)
continue;
let ancestor = base.parent;
while (ancestor && !bases.has(ancestor)) ancestor = ancestor.parent;
if (ancestor) continue;
const levels: THREE.Object3D[] = [base];
for (const id of ids as number[])
levels.push((await gltf.parser.getDependency('node', id)) as THREE.Object3D);
applyNodeVisibility(gltf, levels.slice(1));
bases.add(base);
const label = (
base.name.replace(/[_ -]?LOD0$/i, '') ||
base.parent?.name ||
`Part ${index}`
).replace(/^Mesh_/, '');
chains.push({ id: String(index), label, levels });
}
if (chains.length === 0) return undefined;
const outside =
countTriangles(gltf.scene) -
chains.reduce((sum, chain) => sum + drawnChainTriangles(chain, 0), 0);
const depth = Math.max(...chains.map((chain) => chain.levels.length));
const triangles = Array.from(
{ length: depth },
(_, level) =>
outside + chains.reduce((sum, chain) => sum + drawnChainTriangles(chain, level), 0),
);
return { chains, triangles };
}
const levelOf = (chain: ViewerLodChain, level: number) =>
chain.levels[
Math.min(Math.max(Number.isFinite(level) ? Math.floor(level) : 0, 0), chain.levels.length - 1)
]!;
function drawnChainTriangles(chain: ViewerLodChain, index: number): number {
let parent = chain.levels.find((level) => level.parent)?.parent;
while (parent) {
if (!parent.visible) return 0;
parent = parent.parent;
}
return countTriangles(levelOf(chain, index));
}
function showChain(chain: ViewerLodChain, level: number): void {
const wanted = levelOf(chain, level);
const shown = chain.levels.find((candidate) => candidate.parent !== null);
if (!shown || shown === wanted) return;
const parent = shown.parent!;
parent.children[parent.children.indexOf(shown)] = wanted;
wanted.parent = parent;
shown.parent = null;
}
/** Show `level` in every chain, each at its LOD0's place among its siblings. */
export function showLevel(levels: ViewerLevels, level: number): void {
for (const chain of levels.chains) showChain(chain, level);
}
/** Choose one independent part without changing the other chains or authored visibility. */
export function showChainLevel(levels: ViewerLevels, id: string, level: number): boolean {
const chain = levels.chains.find((candidate) => candidate.id === id);
if (!chain) return false;
showChain(chain, level);
return true;
}
export function viewerLevelState(
levels: ViewerLevels | undefined,
root: THREE.Object3D,
): ViewerLevelState | undefined {
if (!levels) return undefined;
return {
triangles: countTriangles(root),
levels: levels.triangles,
chains: levels.chains.map((chain) => ({
id: chain.id,
label: chain.label,
level: chain.levels.findIndex((level) => level.parent !== null),
triangles: chain.levels.map((_, index) => drawnChainTriangles(chain, index)),
})),
};
}
/** Every level's object that is not in the scene now, for disposal and material toggles. */
export function detachedLevels(levels: ViewerLevels | undefined): THREE.Object3D[] {
return (levels?.chains ?? []).flatMap((chain) =>
chain.levels.filter((level) => level.parent === null),
);
}
/** Level choices for the control: `LOD1 · 1,234 triangles`. */
export function levelLabels(triangles: readonly number[]): string[] {
return triangles.map((count, level) => `LOD${level} · ${count.toLocaleString()} triangles`);
}
/** Every level's triangles on one line: `LOD0 1,200 · LOD1 450 triangles`. */
export function describeLevels(triangles: readonly number[]): string {
return `${triangles.map((count, level) => `LOD${level} ${count.toLocaleString()}`).join(' · ')} triangles`;
}