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
Add defineBudget with receipt reporting and --strict-budget
Matt Kissinger1992f65515f1
diff --git a/src/__tests__/__snapshots__/prompt-api.test.ts.snap b/src/__tests__/__snapshots__/prompt-api.test.ts.snapindex b80c1de5..026aeaae 100644--- a/src/__tests__/__snapshots__/prompt-api.test.ts.snap+++ b/src/__tests__/__snapshots__/prompt-api.test.ts.snap@@ -786,6 +786,13 @@ geometryDiagnostics(geometry: BufferGeometry, tolerance?: number)// tolerance and scale. Open boundaries are valid for sheets; closed edges do not certify a// self-intersection-free solid.// e.g. const topology = geometryDiagnostics(shell);+defineBudget(spec: { triangles: number | { LOD0, LOD1, ... }, draws?: number }, target?: Object3D)+ // Declares a triangle budget (one number for LOD0, or per LOD tier) and an optional LOD0+ // draw-call budget. Receipts report budget: { status, tiers: [{ tier, declared, measured,+ // status }] } measured from the GLB. Advisory: never QA acceptance.+ // NOTE: Only when the brief states a budget. Call once; tiers are LOD0, LOD1, ... matching+ // defineLod levels.+ // e.g. defineBudget({ triangles: { LOD0: 4000, LOD1: 900 }, draws: 3 });countTriangles(root: Object3D)// Sums placed mesh triangles across the subtree, including active InstancedMesh copies and// two triangles per sprite. Not draw calls or visible-frame cost.diff --git a/src/__tests__/delivery-budget.test.ts b/src/__tests__/delivery-budget.test.tsnew file mode 100644index 00000000..650fb65d--- /dev/null+++ b/src/__tests__/delivery-budget.test.ts@@ -0,0 +1,153 @@+/**+ * Triangle and draw budgets in the receipt (delivery contract item 3).+ *+ * `defineBudget({ triangles, draws? })` declares a budget in source. The declaration travels+ * as scene extras `kilnBudgetV1`, and the integration manifest, the CLI `--json` receipt and+ * `kiln_render` report `budget: { status, tiers: [{ tier, declared, measured, status }] }`.+ * Advisory by default: it never changes QA acceptance. CLI `--strict-budget` exits non-zero+ * when a tier fails.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';+import { join, resolve } from 'node:path';+import * as THREE from 'three';+import { defineBudget, KILN_BUDGET_KEY } from '../budget';+import { AuthoringDiagnosticError } from '../evaluator/authoring-diagnostic';+import { buildSandboxGlobals } from '../primitives';+import { renderGLBInProcess } from '../render';+import { createKilnProgramToolRegistry } from '../tools/registry';++const tiered = (budget: string) => `const meta={name:'Budgeted'};+function build(){+ const root=createRoot('Root');+ const m=gameMaterial('#777777');+ createPart('Base',boxGeo(1,0.2,1),m,{parent:root});+ const tiers=['Body_LOD0','Body_LOD1'].map((name)=>{const g=new THREE.Group();g.name=name;root.add(g);return g;});+ createPart('Hi',sphereGeo(0.5,16,12),m,{parent:tiers[0],position:[0,1,0]});+ createPart('Lo',boxGeo(1,1,1),m,{parent:tiers[1],position:[0,1,0]});+ defineLod(tiers,{screenCoverage:[0.2,0]});+ ${budget}+ return root;+}`;++describe('defineBudget', () => {+ test('normalises a number or a per-tier record and stamps a target', () => {+ const root = new THREE.Group();+ expect(defineBudget({ triangles: 500, draws: 4 }, root)).toEqual({+ schemaVersion: 1,+ triangles: { LOD0: 500 },+ draws: 4,+ });+ expect(root.userData[KILN_BUDGET_KEY]).toEqual({+ schemaVersion: 1,+ triangles: { LOD0: 500 },+ draws: 4,+ });+ expect(defineBudget({ triangles: { LOD0: 500, LOD1: 80 } })).toEqual({+ schemaVersion: 1,+ triangles: { LOD0: 500, LOD1: 80 },+ });+ for (const bad of [+ { triangles: 0 },+ { triangles: 1.5 },+ { triangles: { Body: 4 } },+ { triangles: 10, draws: -1 },+ { triangles: 10, extra: 1 },+ ])+ expect(() => defineBudget(bad as never)).toThrow(AuthoringDiagnosticError);+ expect(typeof buildSandboxGlobals().defineBudget).toBe('function');+ });++ test('reports each tier against the GLB, pass and fail', async () => {+ const result = await renderGLBInProcess(+ tiered(`defineBudget({ triangles: { LOD0: 400, LOD1: 20 }, draws: 2 });`),+ );+ const budget = result.integrationManifest.budget!;+ // Base (12) + Hi sphere (16 x 12 segments: 16 * (12 - 1) * 2 = 352) and Base + Lo box (12).+ expect(budget.tiers).toEqual([+ {+ tier: 'LOD0',+ declared: { triangles: 400, draws: 2 },+ measured: { triangles: 364, draws: 2 },+ status: 'pass',+ },+ { tier: 'LOD1', declared: { triangles: 20 }, measured: { triangles: 24 }, status: 'fail' },+ ]);+ expect(budget.status).toBe('fail');+ // Advisory: the asset still builds and QA does not block on it.+ expect(result.glb.length).toBeGreaterThan(0);+ });++ test('kiln_render metrics carry the budget, and status none when undeclared', async () => {+ const render = createKilnProgramToolRegistry().find((tool) => tool.name === 'kiln_render')!;+ const declared = (await render.run({+ code: tiered('defineBudget({ triangles: 100 });'),+ detail: 'lean',+ })) as { budget: { status: string; tiers: { tier: string }[] } };+ expect(declared.budget.status).toBe('fail');+ expect(declared.budget.tiers.map((tier) => tier.tier)).toEqual(['LOD0']);+ const undeclared = (await render.run({ code: tiered('') })) as { budget: unknown };+ expect(undeclared.budget).toEqual({ status: 'none', tiers: [] });+ });++ test('an undeclared budget is absent from the manifest', async () => {+ const result = await renderGLBInProcess(tiered(''));+ expect(result.integrationManifest.budget).toBeUndefined();+ });+});++describe('CLI budget receipt', () => {+ let directory: string;+ beforeAll(async () => {+ const base = resolve(import.meta.dir, '../../tmp');+ await mkdir(base, { recursive: true });+ directory = await mkdtemp(join(base, 'cli-budget-'));+ const built = await Bun.build({+ entrypoints: [resolve(import.meta.dir, '../cli.ts')],+ target: 'node',+ packages: 'external',+ outdir: directory,+ naming: 'cli.mjs',+ });+ expect(built.success).toBe(true);+ await writeFile(join(directory, 'pass.js'), tiered('defineBudget({ triangles: 400 });'));+ await writeFile(join(directory, 'fail.js'), tiered('defineBudget({ triangles: 100 });'));+ await writeFile(join(directory, 'none.js'), tiered(''));+ });+ afterAll(async () => {+ if (directory) await rm(directory, { recursive: true, force: true });+ });+ const run = (args: string[]) =>+ Bun.spawnSync(['node', join(directory, 'cli.mjs'), ...args], {+ cwd: directory,+ env: {+ ...process.env,+ KILN_EVALUATOR_MODE: 'in-process',+ KILN_BUILD_CACHE: 'off',+ KILN_WORKSPACE: directory,+ KILN_PROGRAM_STORE: join(directory, 'programs'),+ KILN_RENDER: 'cpu',+ },+ stdout: 'pipe',+ stderr: 'pipe',+ timeout: 20000,+ });++ test('the receipt carries the budget and --strict-budget exits non-zero on fail', () => {+ const none = run(['render', 'none.js', '--out', 'none.glb', '--json']);+ expect(none.exitCode).toBe(0);+ expect(JSON.parse(none.stdout.toString()).budget).toEqual({ status: 'none', tiers: [] });++ const failed = run(['render', 'fail.js', '--out', 'fail.glb', '--json']);+ expect(failed.exitCode).toBe(0);+ expect(JSON.parse(failed.stdout.toString()).budget.status).toBe('fail');++ const strict = run(['render', 'fail.js', '--out', 'fail.glb', '--json', '--strict-budget']);+ expect(strict.exitCode).not.toBe(0);+ expect(JSON.parse(strict.stdout.toString()).budget.status).toBe('fail');++ const passed = run(['render', 'pass.js', '--out', 'pass.glb', '--strict-budget']);+ expect(passed.exitCode).toBe(0);+ expect(passed.stdout.toString()).toContain('budget pass');+ });+});diff --git a/src/budget.ts b/src/budget.tsnew file mode 100644index 00000000..3eb76e9a--- /dev/null+++ b/src/budget.ts@@ -0,0 +1,146 @@+/**+ * Triangle and draw budgets (delivery contract item 3).+ *+ * `defineBudget({ triangles, draws? })` 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. 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 } from './contracts/integration';+import { AuthoringDiagnosticError } from './evaluator/authoring-diagnostic';++/** 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;+}++export interface BudgetDeclarationV1 {+ schemaVersion: 1;+ /** Maximum drawn triangles per tier, LOD0 first. */+ triangles: Record<string, number>;+ /** Maximum LOD0 draw calls. */+ draws?: number;+}++/** 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;+};++/** 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 { triangles: number | { LOD0, LOD1, ... }, draws? }.');+ const value = spec as Record<string, unknown>;+ for (const key of Object.keys(value))+ if (key !== 'triangles' && key !== 'draws' && key !== 'schemaVersion')+ fail(`unknown field ${JSON.stringify(key)}.`);+ 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) 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 fail('triangles must be a positive integer or a record of LOD tiers.');+ 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) }),+ };+}++/**+ * 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 },+ chains: readonly LevelOfDetailChainV1[],+): BudgetReportV1 {+ 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 }),+ },+ 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 },+ status: measuredLod0.draws <= declaration.draws ? 'pass' : 'fail',+ });+ return { status: tiers.every((tier) => tier.status === 'pass') ? 'pass' : 'fail', tiers };+}diff --git a/src/cli.ts b/src/cli.tsindex 511b541f..d9d143c5 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -73,6 +73,7 @@ OPTIONSstatus|reprobe print receipts; commands that printJSON already accept it; generate and view refuse it--detail <level> render --json: lean | compact | full QA detail (default: compact)+ --strict-budget render: exit 1 when a defineBudget tier fails (advisory otherwise)--offset <n> source --json: page start; pass the returned nextOffset--limit <n> source --json: page size in characters (1-16000)--query <text> source --json: find literal text at or after --offset@@ -111,6 +112,8 @@ interface Args extends WorkspaceSelection {query?: string;/** render --json: the shared result detail; compact unless asked otherwise. */detail?: ReviewDetail;+ /** render: a failing defineBudget tier makes the exit code non-zero. */+ strictBudget?: boolean;help: boolean;json: boolean;}@@ -146,6 +149,9 @@ export function parseArgs(argv: readonly string[]): Args {case '--out':args.out = next();break;+ case '--strict-budget':+ args.strictBudget = true;+ break;case '--json':args.json = true;break;@@ -340,6 +346,7 @@ async function emit(...(result.integrationManifest.vertexAttributes? { vertexAttributes: result.integrationManifest.vertexAttributes }: {}),+ budget: result.integrationManifest.budget ?? { status: 'none', tiers: [] },artifactGlbSha256: result.artifactGlbSha256,glbBytes: result.glb.length,warnings: result.warnings,@@ -381,6 +388,17 @@ async function emit(// Tris and bounds count what draws; a subtree KHR_node_visibility hides is listed apart.for (const node of result.integrationManifest.hiddenNodes ?? [])log(` hidden ${node.path} ${node.triangles} tris (not drawn, not in the headline)`);+ // A declared budget, tier by tier: advisory unless --strict-budget.+ const budget = result.integrationManifest.budget;+ if (budget) {+ const tiers = budget.tiers+ .map(+ (tier) =>+ `${tier.tier} ${tier.measured.triangles}/${tier.declared.triangles ?? '-'} tris${tier.declared.draws === undefined ? '' : ` ${tier.measured.draws}/${tier.declared.draws} draws`} ${tier.status}`,+ )+ .join('; ');+ log(` budget ${budget.status} ${tiers}`);+ }// Custom vertex attributes the GLB preserves, such as baked _EDGE and _CAVITY.for (const attribute of result.integrationManifest.vertexAttributes ?? [])log(` attribute ${attribute.name} on ${attribute.meshes.length} mesh(es)`);@@ -485,6 +503,11 @@ async function cmdRender(args: Args): Promise<number> {},() => emit(code, args, callContext, undefined, receipt),);+ const budget = (receipt as { budget?: { status?: string } }).budget;+ if (args.strictBudget && budget?.status === 'fail') {+ console.error('render: a defineBudget tier failed (--strict-budget).');+ return 1;+ }return 0;} catch (error) {if (!args.json) throw error;diff --git a/src/contracts/integration.ts b/src/contracts/integration.tsindex a39b29df..cc8e88d2 100644--- a/src/contracts/integration.ts+++ b/src/contracts/integration.ts@@ -132,6 +132,22 @@ export interface DeliveryVertexAttributeV1 {params?: Record<string, number>;}+/** One tier of a declared budget measured against the written GLB. */+export interface BudgetTierV1 {+ /** `LOD0`, `LOD1`, ...: tier n draws level min(n, last) of every chain. */+ tier: string;+ declared: { triangles?: number; draws?: number };+ measured: { triangles: number; draws?: number };+ status: 'pass' | 'fail';+}++/** A `defineBudget` declaration against the bytes. Advisory: never QA acceptance. */+export interface BudgetReportV1 {+ /** `none` when no budget was declared; `fail` when any tier fails. */+ status: 'pass' | 'fail' | 'none';+ tiers: BudgetTierV1[];+}+/** An advisory delivery finding. Never QA acceptance. */export interface DeliveryDiagnosticV1 {code: string;@@ -180,6 +196,8 @@ export interface IntegrationManifestV1 {kit?: DeliveryKitModuleV1;/** Kit ports in scene order, when the GLB has any. */ports?: DeliveryPortV1[];+ /** The declared budget measured against these bytes, when source declared one. */+ budget?: BudgetReportV1;/** Custom vertex attributes (`_EDGE`, `_CAVITY`) grouped by name and parameters. */vertexAttributes?: DeliveryVertexAttributeV1[];/** Advisory delivery findings (colliders, anchors, ports), when there are any. */diff --git a/src/discovery/helper-contracts.ts b/src/discovery/helper-contracts.tsindex 45b64623..8d71cfeb 100644--- a/src/discovery/helper-contracts.ts+++ b/src/discovery/helper-contracts.ts@@ -967,6 +967,41 @@ define(],},);+define(+ 'defineBudget',+ {+ units: 'Counts: triangles drawn and draw calls; no lengths.',+ axes: 'Not a placement operation.',+ origin: 'Not a placement operation.',+ ownership:+ 'Records one declaration: on target when given, otherwise on the root build() returns. Export writes it as default-scene extras kilnBudgetV1.',+ coordinates: 'Not a placement operation.',+ parameters: [+ 'triangles: a positive integer for LOD0, or a record of tiers named LOD0, LOD1, ... with positive integers.',+ 'draws: optional positive integer, the LOD0 draw-call cap.',+ 'target: optional scene node, normally the root.',+ ],+ topology: [noMesh],+ preservation: ['Changes no geometry, material or node.'],+ semantics: [+ 'Tier n is measured as level min(n, last) of every MSFT_lod chain plus everything outside the chains; LOD0 is the drawn headline. Hidden nodes are not counted.',+ 'The integration manifest, CLI render --json receipt and kiln_render results report budget: { status: pass | fail | none, tiers: [{ tier, declared, measured, status }] }.',+ 'Advisory: a failing tier never changes QA acceptance. CLI render --strict-budget exits 1 when any tier fails.',+ 'Invalid specs are a DELIVERY_CONTRACT build error.',+ ],+ cost: 'Metadata only; measurement reads the written GLB.',+ },+ {+ references: ['src/budget.ts', 'docs/delivery-contract.md'],+ tags: ['delivery', 'budget', 'performance', 'lod'],+ aliases: ['triangle budget', 'poly budget', 'draw call budget', 'performance budget'],+ intents: ['declare and check a triangle or draw budget'],+ summary:+ 'Declares triangle (per LOD tier) and draw-call budgets that every receipt measures against the GLB; advisory unless --strict-budget.',+ limitations: ['Does not simplify geometry or merge draws to meet a budget.'],+ related: [{ name: 'defineLod', relation: 'companion' }],+ },+);define('markOpenShell',{diff --git a/src/discovery/helper-specs.ts b/src/discovery/helper-specs.tsindex 45a18599..63f389fe 100644--- a/src/discovery/helper-specs.ts+++ b/src/discovery/helper-specs.ts@@ -276,6 +276,18 @@ const PRIMITIVES: HelperSpec[] = [promptNotes:'Only when the brief asks for wear or cavity attributes. Call it last, after parts are placed: cavity depends on placement. Each baked mesh gets its own geometry copy.',},+ {+ name: 'defineBudget',+ signature:+ 'defineBudget(spec: { triangles: number | { LOD0, LOD1, ... }, draws?: number }, target?: Object3D)',+ returns: '{ schemaVersion: 1, triangles: { LOD0, ... }, draws? } (the normalised declaration)',+ category: 'utility',+ description:+ 'Declares a triangle budget (one number for LOD0, or per LOD tier) and an optional LOD0 draw-call budget. Receipts report budget: { status, tiers: [{ tier, declared, measured, status }] } measured from the GLB. Advisory: never QA acceptance.',+ example: 'defineBudget({ triangles: { LOD0: 4000, LOD1: 900 }, draws: 3 });',+ promptNotes:+ 'Only when the brief states a budget. Call once; tiers are LOD0, LOD1, ... matching defineLod levels.',+ },{name: 'beamBetween',signature:diff --git a/src/evaluator/authoring-diagnostic.ts b/src/evaluator/authoring-diagnostic.tsindex 09cc71b9..766b0642 100644--- a/src/evaluator/authoring-diagnostic.ts+++ b/src/evaluator/authoring-diagnostic.ts@@ -75,7 +75,7 @@ export const LOD_SET_ADVICE =export const OPEN_SHELL_ADVICE ='markOpenShell(part, reason) marks a part as intentionally open: part is the mesh createPart returned or a group whose meshes it covers, and reason is a non-empty string of at most 200 characters saying why, for example markOpenShell(rail, "C-channel closed by the end plates"). The engine owns the kilnOpenShell userData key; set it only through markOpenShell. Call kiln_discover with ids ["markOpenShell"].';export const DELIVERY_CONTRACT_ADVICE =- 'Delivery helpers: colliderBox(size, { id }), colliderCapsule(radius, height, { id }) with height the total height of at least 2 * radius, colliderHull(mesh, { id }), anchor(kind, id), port(id) and defineModule(root, { footprint: [w, d], height, snapAxis: "x"|"y"|"z", origin: "corner"|"center" }). Ids and kinds are one segment of letters, digits, "_" or "-" with no dots; sizes are positive metres. The engine owns the kilnKit userData key; set it only through defineModule. Call kiln_discover with ids ["colliderBox", "anchor", "defineModule"].';+ 'Delivery helpers: colliderBox(size, { id }), colliderCapsule(radius, height, { id }) with height the total height of at least 2 * radius, colliderHull(mesh, { id }), anchor(kind, id), port(id) and defineModule(root, { footprint: [w, d], height, snapAxis: "x"|"y"|"z", origin: "corner"|"center" }). Ids and kinds are one segment of letters, digits, "_" or "-" with no dots; sizes are positive metres. The engine owns the kilnKit userData key; set it only through defineModule. defineBudget({ triangles: n | { LOD0, LOD1, ... }, draws? }) takes positive integers. Call kiln_discover with ids ["colliderBox", "anchor", "defineModule", "defineBudget"].';/*** The advice behind the generic rejection, when no closed cause crossed the boundary.* Engine-owned text only: it states the contract and names the two tools that answerdiff --git a/src/primitives.ts b/src/primitives.tsindex 703e7a41..59689d91 100644--- a/src/primitives.ts+++ b/src/primitives.ts@@ -26,6 +26,7 @@ export { defineLod } from './lod';import { markOpenShell } from './open-shell';import { anchor, colliderBox, colliderCapsule, colliderHull, defineModule, port } from './delivery';import { bakeSurfaceAttributes } from './surface-bake';+import { type BudgetDeclarationV1, defineBudget } from './budget';import { useCubicSpline } from './animation-cubic';import {CUBIC_INTERPOLATIONS,@@ -2132,6 +2133,13 @@ export function materialBudgetAdvisory(*/export type DiagnosticConsole = Pick<Console, 'log' | 'info' | 'debug' | 'warn' | 'error'>;+/** Declarations a program makes without a node; executeKilnCode stamps them on the root. */+export interface SandboxDeclarations {+ budget?: BudgetDeclarationV1;+}+/** Symbol-keyed, so it never becomes a sandbox global. */+export const SANDBOX_DECLARATIONS: unique symbol = Symbol('kiln.sandbox.declarations');+export interface SandboxGlobalsOptions {/** Host-owned closed resolver. Generated code receives only the bound* loadApprovedTexture(resourceId) closure, never this object. */@@ -2248,7 +2256,8 @@ export function buildSandboxGlobals(return options.textureResolver.materialRecipe(args[0], args[1]);};- return {+ const declarations: SandboxDeclarations = {};+ const globals: Record<string, unknown> = {createRoot: wrap('createRoot', createRoot),describeAssembly: wrap('describeAssembly', describeAssembly),replicateAssembly: wrap('replicateAssembly', replicateAssembly),@@ -2269,6 +2278,14 @@ export function buildSandboxGlobals(defineModule: wrap('defineModule', defineModule),port: wrap('port', port),bakeSurfaceAttributes: wrap('bakeSurfaceAttributes', bakeSurfaceAttributes),+ defineBudget: wrap(+ 'defineBudget',+ (spec: Parameters<typeof defineBudget>[0], target?: THREE.Object3D) => {+ const declaration = defineBudget(spec, target);+ declarations.budget = declaration;+ return declaration;+ },+ ),capsuleGeo: wrapGeo('capsuleGeo', capsuleGeo),capsuleXGeo: wrapGeo('capsuleXGeo', capsuleXGeo),capsuleYGeo: wrapGeo('capsuleYGeo', capsuleYGeo),@@ -2399,4 +2416,6 @@ export function buildSandboxGlobals(Math,console: options.console ?? console,};+ Object.defineProperty(globals, SANDBOX_DECLARATIONS, { value: declarations });+ return globals;}diff --git a/src/render.ts b/src/render.tsindex a0677655..cbcbca75 100644--- a/src/render.ts+++ b/src/render.ts@@ -74,7 +74,14 @@ import {type SnapPaletteSlot,} from './palette-snap';-import { buildSandboxGlobals, countTriangles, type DiagnosticConsole } from './primitives';+import {+ buildSandboxGlobals,+ countTriangles,+ type DiagnosticConsole,+ SANDBOX_DECLARATIONS,+ type SandboxDeclarations,+} from './primitives';+import { evaluateBudget, KILN_BUDGET_KEY, normalizeBudget, readBudgetDeclaration } from './budget';import {collectGlbMetrics,gradeInstanceability,@@ -279,6 +286,16 @@ export async function inspectGlbIntegration(const hiddenNodes = summarizeHiddenNodes(doc);const delivery = inspectDelivery(doc);const vertexAttributes = summarizeVertexAttributes(doc);+ const budgetDeclaration = readBudgetDeclaration(+ (scene.getExtras() as Record<string, unknown>)[KILN_BUDGET_KEY],+ );+ const budget = budgetDeclaration+ ? evaluateBudget(+ budgetDeclaration,+ { triangles: metrics.triangles, draws: metrics.drawCalls },+ levelsOfDetail,+ )+ : undefined;return {schemaVersion: 'kiln.integration-manifest.v1',@@ -322,6 +339,7 @@ export async function inspectGlbIntegration(...(delivery.anchors.length ? { anchors: delivery.anchors } : {}),...(delivery.kit ? { kit: delivery.kit } : {}),...(delivery.ports.length ? { ports: delivery.ports } : {}),+ ...(budget ? { budget } : {}),...(vertexAttributes.length ? { vertexAttributes } : {}),...(delivery.diagnostics.length ? { deliveryDiagnostics: delivery.diagnostics } : {}),structuralQa: {@@ -462,6 +480,13 @@ export async function executeKilnCode();}+ // Node-less declarations (defineBudget without a target) belong to the returned root.+ const declared = (globals as { [SANDBOX_DECLARATIONS]?: SandboxDeclarations })[+ SANDBOX_DECLARATIONS+ ];+ if (declared?.budget && root.userData[KILN_BUDGET_KEY] === undefined)+ root.userData[KILN_BUDGET_KEY] = declared.budget;+const clips = animate ? ((await animate(root)) ?? []) : [];return { meta: meta ?? {}, root, clips, primitiveUsage };@@ -1801,6 +1826,14 @@ export async function renderSceneToGLB(const scene = doc.getRoot().getDefaultScene()!;scene.setExtras({ ...scene.getExtras(), kilnAtlasProvenance: atlas.table });}+ // A declared budget travels in the bytes, so a receipt from the GLB alone can measure it.+ if (root.userData[KILN_BUDGET_KEY] !== undefined && opts.derivative !== true) {+ const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]!;+ scene.setExtras({+ ...scene.getExtras(),+ [KILN_BUDGET_KEY]: normalizeBudget(root.userData[KILN_BUDGET_KEY]),+ });+ }// Visibility flags and LOD chains are written before any pass merges or prunes nodes, so// those passes see them and keep them; flags first, while every node is still in place.applySurfaceBakeExtras(root, doc);diff --git a/src/tools/registry.ts b/src/tools/registry.tsindex 60821798..2641d905 100644--- a/src/tools/registry.ts+++ b/src/tools/registry.ts@@ -1070,6 +1070,9 @@ export interface KilnRenderViewsResult extends PartPreview {/** Outermost hidden nodes (visible = false) with their triangles; `tris`, `bbox` and the* default views leave them out. */hiddenNodes?: HiddenNodeV1[];+ /** The defineBudget declaration measured against the written GLB; `none` when undeclared.+ * Advisory: never QA acceptance. */+ budget?: import('../contracts').BudgetReportV1;/** Post-dedup instanceability grade (informational): how cheap to render at scale. */instanceability?: { grade: string; summary: string };/** Structured deterministic report; five dimensions remain separate. */@@ -1118,6 +1121,12 @@ function levelsOfDetailField(}/** The hidden subtrees the headline leaves out, when the GLB has any. */+/** The declared budget against the bytes, or status none: always present on a render. */+function budgetField(rendered: RenderResult): { budget?: import('../contracts').BudgetReportV1 } {+ if (!rendered.integrationManifest) return {};+ return { budget: rendered.integrationManifest.budget ?? { status: 'none', tiers: [] } };+}+function hiddenNodesField(rendered: RenderResult): { hiddenNodes?: HiddenNodeV1[] } {const hidden = rendered.integrationManifest?.hiddenNodes;return hidden?.length ? { hiddenNodes: hidden } : {};@@ -1207,6 +1216,7 @@ async function runRenderViews(lowestPart: metrics.lowestPart,...levelsOfDetailField(rendered, grid.viewLevels ?? lod0Views(grid.views.length)),...hiddenNodesField(rendered),+ ...budgetField(rendered),views: grid.views,capture: grid.capture,...(grid.captureCache ? { captureCache: grid.captureCache } : {}),@@ -1369,6 +1379,7 @@ async function runRenderViews(lowestPart: metrics.lowestPart,...levelsOfDetailField(rendered, lod0Views(grid.views.length)),...hiddenNodesField(rendered),+ ...budgetField(rendered),...(rendered.meta.instanceability? {instanceability: {diff --git a/src/tools/review-detail.ts b/src/tools/review-detail.tsindex ef3ed034..8e24ca16 100644--- a/src/tools/review-detail.ts+++ b/src/tools/review-detail.ts@@ -483,6 +483,7 @@ const LEAN_KEYS = ['distinctMaterials','bbox','lowestPart',+ 'budget','views','capture','gridWidth',