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.

9.7 KB
Raw Blame
/** Browser-safe sidecar contract for placing and validating a finished Kiln GLB. */

export const INTEGRATION_ASSET_ROLES = [
  'ground',
  'building',
  'wonder',
  'poi',
  'prop',
  'fill',
  'vehicle',
] as const;

export type IntegrationAssetRole = (typeof INTEGRATION_ASSET_ROLES)[number];

export interface IntegrationBoundsV1 {
  min: [number, number, number];
  max: [number, number, number];
  size: [number, number, number];
  center: [number, number, number];
}

/** One level of an `MSFT_lod` chain in the written GLB. */
export interface LevelOfDetailLevelV1 {
  /** 0 is LOD0, the node in the scene; higher numbers are the chain's lower levels in order. */
  level: number;
  name: string;
  /** Inspection path of the level: a shot subject that draws this level in LOD0's place. */
  path: string;
  /** Placed triangles in the level's subtree. */
  triangles: number;
  /** Present on the last level when `defineLod` declared it a card or billboard tier
   *  (`lod.impostor` role on that node). */
  impostor?: true;
}

/** One node `MSFT_lod` chain: LOD0 in the scene and the lower levels it lists. */
export interface LevelOfDetailChainV1 {
  /** Inspection path of the LOD0 node. */
  path: string;
  /** `extras.MSFT_screencoverage` on LOD0, when it is a list of numbers. */
  screenCoverage?: number[];
  /** LOD0 first. */
  levels: LevelOfDetailLevelV1[];
}

/** An outermost node that does not draw (`KHR_node_visibility` `visible: false`). */
export interface HiddenNodeV1 {
  /** Inspection path, as `kiln_inspect` `listParts` lists it. */
  path: string;
  name: string;
  /** Placed triangles in the hidden subtree; not in the headline. */
  triangles: number;
}

/** A chain in a review result: the level it drew in each view. */
export interface ReviewedLevelOfDetailChainV1 extends LevelOfDetailChainV1 {
  /** One entry per view, in view order: 0 when the view drew LOD0, otherwise the lower level
   *  a shot subject named. */
  drawn: number[];
}

/** A node transform relative to the asset root (the default scene), decomposed as glTF TRS. */
export interface DeliveryTransformV1 {
  translation: [number, number, number];
  /** Unit quaternion [x, y, z, w]. A consumer that collides with yaw only reads yaw from it. */
  rotation: [number, number, number, number];
  scale: [number, number, number];
}

/** The resolved shape of a collider proxy, in metres, measured from its transform. */
export type DeliveryColliderShapeV1 =
  | { kind: 'box'; size: [number, number, number] }
  /** `height` is the total end-to-end height along the node's local +Y, caps included. */
  | { kind: 'capsule'; radius: number; height: number }
  | { kind: 'hull'; vertices: number };

/** A hidden collider proxy node (`collider.<shape>.<id>` role). */
export interface DeliveryColliderV1 {
  role: string;
  id: string;
  /** Inspection path, as `kiln_inspect` `listParts` lists it. */
  path: string;
  name: string;
  transform: DeliveryTransformV1;
  shape: DeliveryColliderShapeV1;
}

/** A named point (`anchor.<kind>.<id>` role). */
export interface DeliveryAnchorV1 {
  role: string;
  kind: string;
  id: string;
  path: string;
  name: string;
  transform: DeliveryTransformV1;
}

/** `kilnKit` node extras on a `kit.module` root. Footprint is width along X, depth along Z. */
export interface KitModuleSpecV1 {
  footprint: [number, number];
  height: number;
  snapAxis: 'x' | 'y' | 'z';
  origin: 'corner' | 'center';
}

/** The kit module this GLB delivers (`kit.module` role). */
export interface DeliveryKitModuleV1 extends KitModuleSpecV1 {
  role: string;
  path: string;
  name: string;
  transform: DeliveryTransformV1;
}

/** A snap point (`kit.port.<id>` role). */
export interface DeliveryPortV1 {
  role: string;
  id: string;
  path: string;
  name: string;
  /** Inspection path of the kit module the port belongs to, when it is under one. */
  module?: string;
  transform: DeliveryTransformV1;
}

/** One custom vertex attribute in the written GLB and the meshes that carry it. */
export interface DeliveryVertexAttributeV1 {
  /** glTF attribute name, such as `_EDGE`; three's GLTFLoader lowercases it (`_edge`). */
  name: string;
  /** Inspection paths of the nodes whose mesh carries the attribute with these parameters. */
  meshes: string[];
  /** The bake parameters recorded in mesh extras `kilnSurfaceBakeV1`, when Kiln baked it. */
  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 };
  /**
   * `draws` is the LOD0 draw calls in the GLB before any consumer batching; the cap is
   * judged on it. `instancedDraws` (beside `draws`) is informational: the draws after the
   * three runtime target batches each `repeatInstances` group, never judged.
   */
  measured: { triangles: number; draws?: number; instancedDraws?: number };
  status: 'pass' | 'fail';
}

/**
 * Optional optimization advice measured against a reference profile tier when the asset
 * declares no material limit. Never a requirement and never QA acceptance; a
 * `defineBudget` material limit replaces it.
 */
export interface MaterialAdviceV1 {
  code:
    | 'MATERIAL_TEXTURE_RESOLUTION_ADVICE'
    | 'MATERIAL_IMAGE_COUNT_ADVICE'
    | 'MATERIAL_DECODED_MEMORY_ADVICE'
    | 'MATERIAL_BLEND_AREA_ADVICE';
  disposition: 'advisory';
  /** The reference profile tier, such as `web.portable.v1/standard`. */
  reference: string;
  message: string;
  measurement: {
    name: string;
    actual: number;
    /** The reference tier's figure: a comparison point, not a cap. */
    reference: number;
    unit: 'px' | 'images' | 'bytes' | 'ratio';
  };
  advice: string;
}

/** One declared material limit against the written GLB. */
export interface MaterialBudgetCheckV1 {
  /** `images` count, `decodedBytes` RGBA8, `imageSize` longest edge px, `blendedAreaRatio`. */
  limit: 'images' | 'decodedBytes' | 'imageSize' | 'blendedAreaRatio';
  declared: number;
  measured: 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 or material limit fails. */
  status: 'pass' | 'fail' | 'none';
  tiers: BudgetTierV1[];
  /** Declared material limits, when the declaration has any. */
  materials?: MaterialBudgetCheckV1[];
}

/** One drawn material whose base colour is off the declared palette. */
export interface PaletteFindingV1 {
  material: string;
  /** The material's base colour factor as sRGB `#rrggbb`. */
  color: string;
  /** The nearest palette entry. */
  nearest: string;
  /** CIE 1976 delta E in CIELAB, rounded to 0.01. */
  deltaE: number;
  /** The factor tints a base colour texture; the texture itself is not judged. */
  textured?: true;
}

/** A `definePalette` declaration against the bytes. Advisory: never QA acceptance. */
export interface PaletteReportV1 {
  status: 'pass' | 'warn';
  colors: string[];
  threshold: number;
  checkedMaterials: number;
  /** Farthest first. */
  offPalette: PaletteFindingV1[];
}

/** An advisory delivery finding. Never QA acceptance. */
export interface DeliveryDiagnosticV1 {
  code: string;
  path: string;
  message: string;
}

export interface IntegrationManifestV1 {
  schemaVersion: 'kiln.integration-manifest.v1';
  analyzerVersion: 1;
  artifactSha256: string;
  units: 'm';
  axes: { forward: '+X'; up: '+Y'; right: '+Z' };
  bounds: IntegrationBoundsV1;
  pivot: { convention: 'author-origin'; position: [0, 0, 0] };
  ground: {
    groundY: 0;
    contactTolerance: 0.02;
    minY: number;
    offsetToGround: number;
    grounded: boolean;
  };
  defaultScene: { index: number; name: string };
  requestedRole?: IntegrationAssetRole;
  assessedRole?: IntegrationAssetRole;
  renderMetrics: {
    triangles: number;
    drawCalls: number;
    uniqueGeometries: number;
    uniqueMaterials: number;
    textureCount: number;
    transparentMaterials: number;
    skinned: boolean;
  };
  /** Node `MSFT_lod` chains in scene order, when the GLB has any. The bounds and render
   *  metrics above count LOD0 only, which is what a loader without the extension draws. */
  levelsOfDetail?: LevelOfDetailChainV1[];
  /** Outermost hidden nodes in scene order, when the GLB has any. The bounds and render
   *  metrics above count what draws; these triangles are not in them. */
  hiddenNodes?: HiddenNodeV1[];
  /** Collider proxies in scene order, when the GLB has any (additive in analyzer v1). */
  colliders?: DeliveryColliderV1[];
  /** Anchors in scene order, when the GLB has any. */
  anchors?: DeliveryAnchorV1[];
  /** The first kit module, when the GLB has one. */
  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;
  /** Optional optimization notes against a reference profile tier, when no material limit
   *  was declared and a figure is passed. Never a requirement. */
  materialAdvice?: MaterialAdviceV1[];
  /** The declared palette against the drawn materials, when source declared one. */
  palette?: PaletteReportV1;
  /** Custom vertex attributes (`_EDGE`, `_CAVITY`) grouped by name and parameters. */
  vertexAttributes?: DeliveryVertexAttributeV1[];
  /** Advisory delivery findings (colliders, anchors, ports), when there are any. */
  deliveryDiagnostics?: DeliveryDiagnosticV1[];
  structuralQa: {
    hasDefaultScene: boolean;
    finiteBounds: boolean;
    validatorErrors: number;
    validatorWarnings: number;
  };
  /** Visual composition/usability is deliberately assessed by browser QA, not inferred here. */
  visualQa: 'not_assessed';
}