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.

12.2 KB
Raw Blame
/**
 * 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),
          },
        ];
  });
}