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
/**
* Triangle and draw budgets (delivery contract item 3).
*
* `defineBudget({ triangles, draws?, images?, decodedBytes?, materialTier? })` declares what the
* asset may cost: `triangles` is one number for LOD0 or a record of tiers
* (`{ LOD0: 4000, LOD1: 900, LOD2: 120 }`), and `draws` caps LOD0 draw calls. `images`,
* `decodedBytes` and `materialTier` declare material limits, measured in `budget.materials`;
* `triangles` is optional when one of them is declared. The declaration travels in the GLB as scene extras `kilnBudgetV1`,
* and every receipt measures the written bytes against it. Budgets are advisory: a failing
* tier never changes QA acceptance; only CLI `--strict-budget` turns it into an exit code.
*/
import type * as THREE from 'three';
import type {
BudgetReportV1,
BudgetTierV1,
LevelOfDetailChainV1,
MaterialBudgetCheckV1,
} from './contracts/integration';
import { AuthoringDiagnosticError } from './evaluator/authoring-diagnostic';
import {
MATERIAL_BUDGET_PROFILES_V1,
type MaterialBudgetLimitsV1,
type MaterialMetricsV1,
type MaterialReferenceTier,
} from './material-metrics';
/** Where a declaration lives: root userData until export, then default-scene extras. */
export const KILN_BUDGET_KEY = 'kilnBudgetV1';
export interface BudgetSpecV1 {
triangles?: number | Record<string, number>;
draws?: number;
/** Maximum embedded images. */
images?: number;
/** Maximum decoded RGBA8 image bytes, before mip overhead. */
decodedBytes?: number;
/** Adopt every figure of a reference tier, such as `web.portable.v1/standard`. */
materialTier?: MaterialReferenceTier;
}
/** Declared material limits; a tier's figures are resolved into the fields it sets. */
export interface MaterialBudgetDeclarationV1 {
tier?: MaterialReferenceTier;
images?: number;
decodedBytes?: number;
imageSize?: number;
blendedAreaRatio?: number;
}
export interface BudgetDeclarationV1 {
schemaVersion: 1;
/** Maximum drawn triangles per tier, LOD0 first. */
triangles: Record<string, number>;
/** Maximum LOD0 draw calls. */
draws?: number;
materials?: MaterialBudgetDeclarationV1;
}
/** True when a declaration replaces the reference-profile material notes. */
export const declaresMaterialLimits = (declaration: BudgetDeclarationV1 | undefined): boolean =>
declaration?.materials !== undefined;
/** The report when no budget was declared. */
export const noBudget = (): BudgetReportV1 => ({ status: 'none', tiers: [] });
const fail = (detail: string): never => {
throw new AuthoringDiagnosticError('DELIVERY_CONTRACT', `defineBudget(spec): ${detail}`);
};
const count = (label: string, value: unknown): number => {
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
fail(`${label} must be a positive integer, got ${String(value)}.`);
return value as number;
};
/**
* A cap on what the asset may carry, where zero is a real and stricter limit: an untextured
* asset declares `images: 0` honestly. `count` stays for what an asset must have.
*/
const capacity = (label: string, value: unknown): number => {
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
fail(`${label} must be a non-negative integer, got ${String(value)}.`);
return value as number;
};
const SPEC_SHAPE =
'{ triangles?: number | { LOD0, LOD1, ... }, draws?, images?, decodedBytes?, materialTier? }';
const ratio = (label: string, value: unknown): number => {
if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1)
fail(`${label} must be a number in (0, 1], got ${String(value)}.`);
return value as number;
};
/** A reference tier's figures; explicit limits in `value` override them. */
function materialLimits(value: Record<string, unknown>): MaterialBudgetDeclarationV1 | undefined {
const tierName = value.materialTier;
const materials: MaterialBudgetDeclarationV1 = {};
if (tierName !== undefined) {
const [profile, tier] = typeof tierName === 'string' ? tierName.split('/') : [];
const figures = (
MATERIAL_BUDGET_PROFILES_V1 as Partial<
Record<string, Partial<Record<string, MaterialBudgetLimitsV1>>>
>
)[profile ?? '']?.[tier ?? ''];
if (!figures)
fail(
`materialTier must be one of ${Object.entries(MATERIAL_BUDGET_PROFILES_V1)
.flatMap(([p, tiers]) => Object.keys(tiers).map((t) => `${p}/${t}`))
.join(', ')}, got ${JSON.stringify(tierName)}.`,
);
Object.assign(materials, {
tier: tierName as MaterialReferenceTier,
images: figures!.maxImageCount,
decodedBytes: figures!.maxDecodedBytesRgba8,
imageSize: figures!.maxImageDimension,
blendedAreaRatio: figures!.maxBlendedSurfaceAreaRatio,
});
}
if (value.images !== undefined) materials.images = capacity('images', value.images);
if (value.decodedBytes !== undefined)
materials.decodedBytes = capacity('decodedBytes', value.decodedBytes);
return Object.keys(materials).length ? materials : undefined;
}
/** A stored declaration's resolved material limits, as `materialLimits` wrote them. */
function storedMaterials(value: unknown): MaterialBudgetDeclarationV1 {
if (!value || typeof value !== 'object' || Array.isArray(value)) fail('materials is malformed.');
const stored = value as Record<string, unknown>;
const materials: MaterialBudgetDeclarationV1 = {};
for (const key of Object.keys(stored))
if (!['tier', 'images', 'decodedBytes', 'imageSize', 'blendedAreaRatio'].includes(key))
fail(`unknown materials field ${JSON.stringify(key)}.`);
if (stored.tier !== undefined) materials.tier = stored.tier as MaterialReferenceTier;
if (stored.images !== undefined) materials.images = capacity('images', stored.images);
if (stored.decodedBytes !== undefined)
materials.decodedBytes = capacity('decodedBytes', stored.decodedBytes);
if (stored.imageSize !== undefined) materials.imageSize = count('imageSize', stored.imageSize);
if (stored.blendedAreaRatio !== undefined)
materials.blendedAreaRatio = ratio('blendedAreaRatio', stored.blendedAreaRatio);
return materials;
}
/** Validate a spec into its detached declaration. Tier keys are LOD0, LOD1, ... */
export function normalizeBudget(spec: unknown): BudgetDeclarationV1 {
if (!spec || typeof spec !== 'object' || Array.isArray(spec)) fail(`spec must be ${SPEC_SHAPE}.`);
const value = spec as Record<string, unknown>;
// `materials` and an empty `triangles` record are the stored form a GLB carries back.
const stored = value.schemaVersion !== undefined;
const allowed = ['triangles', 'draws', 'images', 'decodedBytes', 'materialTier', 'schemaVersion'];
for (const key of Object.keys(value))
if (!allowed.includes(key) && !(stored && key === 'materials'))
fail(`unknown field ${JSON.stringify(key)}.`);
const materials =
stored && value.materials !== undefined
? storedMaterials(value.materials)
: materialLimits(value);
const triangles: Record<string, number> = {};
if (typeof value.triangles === 'number') triangles.LOD0 = count('triangles', value.triangles);
else if (
value.triangles &&
typeof value.triangles === 'object' &&
!Array.isArray(value.triangles)
) {
const entries = Object.entries(value.triangles as Record<string, unknown>);
if (entries.length === 0 && !(stored && (materials || value.draws !== undefined)))
fail('triangles needs at least one tier.');
for (const [tier, limit] of entries) {
if (!/^LOD(0|[1-9][0-9]?)$/.test(tier))
fail(`triangles tier ${JSON.stringify(tier)} must be named LOD0, LOD1, ...`);
triangles[tier] = count(`triangles.${tier}`, limit);
}
} else if (value.triangles !== undefined)
fail('triangles must be a positive integer or a record of LOD tiers.');
else if (value.draws === undefined && !materials)
fail(`spec must declare triangles, draws or a material limit: ${SPEC_SHAPE}.`);
const ordered = Object.fromEntries(
Object.entries(triangles).sort(([a], [b]) => Number(a.slice(3)) - Number(b.slice(3))),
);
return {
schemaVersion: 1,
triangles: ordered,
...(value.draws === undefined ? {} : { draws: count('draws', value.draws) }),
...(materials ? { materials } : {}),
};
}
/**
* Declare the asset's budget. With `target` (normally the root), the declaration is stamped
* on it; inside a Kiln program the sandbox stamps the returned root after build(). Returns the
* normalised declaration.
*/
export function defineBudget(spec: BudgetSpecV1, target?: THREE.Object3D): BudgetDeclarationV1 {
const declaration = normalizeBudget(spec);
if (target !== undefined) {
if ((target as { isObject3D?: boolean } | null)?.isObject3D !== true)
fail('target must be a scene node, normally the root.');
target.userData[KILN_BUDGET_KEY] = structuredClone(declaration);
}
return declaration;
}
/** The declaration a value holds, or undefined when it is absent or malformed. */
export function readBudgetDeclaration(value: unknown): BudgetDeclarationV1 | undefined {
if (value === undefined) return undefined;
try {
const declaration = normalizeBudget(value);
return (value as { schemaVersion?: unknown }).schemaVersion === 1 ? declaration : undefined;
} catch {
return undefined;
}
}
/**
* Measure a declaration against the written GLB. Tier n draws level min(n, last) of every
* `MSFT_lod` chain plus everything outside the chains; LOD0 is the manifest headline.
*/
export function evaluateBudget(
declaration: BudgetDeclarationV1,
measuredLod0: { triangles: number; draws: number; instancedDraws?: number },
chains: readonly LevelOfDetailChainV1[],
material?: MaterialMetricsV1,
): BudgetReportV1 {
// Reported beside draws, never judged (#200).
const instanced =
measuredLod0.instancedDraws === undefined
? {}
: { instancedDraws: measuredLod0.instancedDraws };
const outside =
measuredLod0.triangles - chains.reduce((sum, chain) => sum + chain.levels[0]!.triangles, 0);
const tierTriangles = (level: number) =>
outside +
chains.reduce(
(sum, chain) => sum + chain.levels[Math.min(level, chain.levels.length - 1)]!.triangles,
0,
);
const tiers: BudgetTierV1[] = Object.entries(declaration.triangles).map(([tier, limit]) => {
const level = Number(tier.slice(3));
const triangles = level === 0 ? measuredLod0.triangles : tierTriangles(level);
const drawsDeclared = level === 0 ? declaration.draws : undefined;
const pass =
triangles <= limit && (drawsDeclared === undefined || measuredLod0.draws <= drawsDeclared);
return {
tier,
declared: {
triangles: limit,
...(drawsDeclared === undefined ? {} : { draws: drawsDeclared }),
},
measured: {
triangles,
...(drawsDeclared === undefined ? {} : { draws: measuredLod0.draws, ...instanced }),
},
status: pass ? 'pass' : 'fail',
};
});
if (declaration.draws !== undefined && declaration.triangles.LOD0 === undefined)
tiers.unshift({
tier: 'LOD0',
declared: { draws: declaration.draws },
measured: { triangles: measuredLod0.triangles, draws: measuredLod0.draws, ...instanced },
status: measuredLod0.draws <= declaration.draws ? 'pass' : 'fail',
});
const materials = material ? evaluateMaterialLimits(declaration, material) : [];
const pass = [...tiers, ...materials].every((entry) => entry.status === 'pass');
return {
status: pass ? 'pass' : 'fail',
tiers,
...(materials.length ? { materials } : {}),
};
}
/** Each declared material limit against the written GLB's material metrics. */
function evaluateMaterialLimits(
declaration: BudgetDeclarationV1,
metrics: MaterialMetricsV1,
): MaterialBudgetCheckV1[] {
const declared = declaration.materials ?? {};
const measured: Record<MaterialBudgetCheckV1['limit'], number> = {
images: metrics.imageCount,
decodedBytes: metrics.decodedImageBytesRgba8,
imageSize: metrics.maxImageDimension,
blendedAreaRatio: metrics.blendedSurfaceAreaRatio,
};
return (Object.keys(measured) as MaterialBudgetCheckV1['limit'][]).flatMap((limit) => {
const value = declared[limit];
return value === undefined
? []
: [
{
limit,
declared: value,
measured: measured[limit],
status: measured[limit] <= value ? ('pass' as const) : ('fail' as const),
},
];
});
}