Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

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.snap
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 511b541f..d9d143c5 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -73,6 +73,7 @@ OPTIONS
status|reprobe print receipts; commands that print
JSON 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 answer
diff --git a/src/primitives.ts b/src/primitives.ts
index 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.ts
index 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.ts
index 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.ts
index 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',