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.

14.4 KB
Raw Blame
import { z } from 'zod';
import { worldAabbFromLocal, type Aabb, type Vec3 } from './overlap';
import {
  assertNoPrototypeKeys,
  canonicalContractJson,
  sha256ContractBytes,
} from './contract-utils';

export const COLLIDER_POLICY_V1_SCHEMA_VERSION = 'kiln.collider-policy.v1' as const;
export const COLLIDER_ARTIFACT_V1_SCHEMA_VERSION = 'kiln.collider-artifact.v1' as const;
export const AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION =
  'kiln.authored-collider-geometry.v1' as const;
export const AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1 = Object.freeze({
  maxNodes: 64,
  maxVertices: 65_536,
  maxTriangles: 65_536,
});

const finite = z.number().finite();
const vec3 = z.tuple([finite, finite, finite]);
const sha256 = z.string().regex(/^sha256:[0-9a-f]{64}$/);
const id = z
  .string()
  .min(1)
  .max(256)
  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
const bounds = z
  .object({ min: vec3, max: vec3 })
  .strict()
  .superRefine((value, ctx) => {
    for (let axis = 0; axis < 3; axis++) {
      if (value.min[axis]! > value.max[axis]!) {
        ctx.addIssue({ code: 'custom', path: ['min', axis], message: 'min must not exceed max' });
      }
    }
  });

const policyCommon = {
  transformFrame: z.literal('asset-local'),
};

export const ColliderPolicyV1Schema = z.discriminatedUnion('kind', [
  z.object({ kind: z.literal('none'), ...policyCommon }).strict(),
  z.object({ kind: z.literal('bounds'), ...policyCommon }).strict(),
  z
    .object({
      kind: z.literal('authored-submesh'),
      ...policyCommon,
      nodeNames: z.array(id).min(1).max(64),
    })
    .strict()
    .superRefine((value, ctx) => {
      if (new Set(value.nodeNames).size !== value.nodeNames.length) {
        ctx.addIssue({ code: 'custom', path: ['nodeNames'], message: 'nodeNames must be unique' });
      }
    }),
  z
    .object({
      kind: z.literal('generated-mesh'),
      ...policyCommon,
      method: z.literal('bounds-box'),
    })
    .strict(),
]);

const primitive = z
  .object({
    nodeName: id,
    positions: z.array(finite).max(AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxVertices * 3),
    indices: z
      .array(z.number().int().nonnegative())
      .max(AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxTriangles * 3),
  })
  .strict()
  .superRefine((value, ctx) => {
    if (value.positions.length < 9 || value.positions.length % 3 !== 0) {
      ctx.addIssue({
        code: 'custom',
        path: ['positions'],
        message: 'positions must contain 3D vertices',
      });
    }
    if (value.indices.length < 3 || value.indices.length % 3 !== 0) {
      ctx.addIssue({
        code: 'custom',
        path: ['indices'],
        message: 'indices must contain triangles',
      });
    }
    const vertexCount = value.positions.length / 3;
    if (value.indices.some((index) => index >= vertexCount)) {
      ctx.addIssue({ code: 'custom', path: ['indices'], message: 'index exceeds vertex count' });
    }
  });

/** Strict output boundary for a host that flattens selected GLB mesh nodes into asset-local space. */
export const AuthoredColliderGeometryV1Schema = z
  .object({
    schemaVersion: z.literal(AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION),
    sourceArtifactSha256: sha256,
    transformFrame: z.literal('asset-local'),
    submeshes: z.array(primitive).min(1).max(AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxNodes),
  })
  .strict()
  .superRefine((value, ctx) => {
    if (new Set(value.submeshes.map((entry) => entry.nodeName)).size !== value.submeshes.length) {
      ctx.addIssue({
        code: 'custom',
        path: ['submeshes'],
        message: 'submesh nodeName must be unique',
      });
    }
    const vertexCount = value.submeshes.reduce((sum, entry) => sum + entry.positions.length / 3, 0);
    const triangleCount = value.submeshes.reduce((sum, entry) => sum + entry.indices.length / 3, 0);
    if (
      vertexCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxVertices ||
      triangleCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxTriangles
    ) {
      ctx.addIssue({
        code: 'custom',
        path: ['submeshes'],
        message: 'resolved collider geometry exceeds aggregate budget',
      });
    }
  });

export const ColliderArtifactV1Schema = z
  .object({
    schemaVersion: z.literal(COLLIDER_ARTIFACT_V1_SCHEMA_VERSION),
    transformFrame: z.literal('asset-local'),
    sourceArtifactSha256: sha256,
    policy: ColliderPolicyV1Schema,
    bounds,
    primitives: z.array(primitive).max(64),
  })
  .strict()
  .superRefine((value, ctx) => {
    if (new Set(value.primitives.map((entry) => entry.nodeName)).size !== value.primitives.length) {
      ctx.addIssue({
        code: 'custom',
        path: ['primitives'],
        message: 'primitive nodeName must be unique',
      });
    }
    if (value.policy.kind === 'none' && value.primitives.length !== 0) {
      ctx.addIssue({
        code: 'custom',
        path: ['primitives'],
        message: 'none policy has no primitives',
      });
    }
    if (value.policy.kind !== 'none' && value.primitives.length === 0) {
      ctx.addIssue({
        code: 'custom',
        path: ['primitives'],
        message: 'collider policy requires geometry',
      });
    }
    if (value.primitives.length) {
      const derived = boundsOfPrimitives(value.primitives);
      if (
        derived.min.some((entry, axis) => entry !== value.bounds.min[axis]) ||
        derived.max.some((entry, axis) => entry !== value.bounds.max[axis])
      ) {
        ctx.addIssue({
          code: 'custom',
          path: ['bounds'],
          message: 'bounds must exactly enclose collider vertices',
        });
      }
    }
    const vertexCount = value.primitives.reduce(
      (sum, entry) => sum + entry.positions.length / 3,
      0,
    );
    const triangleCount = value.primitives.reduce(
      (sum, entry) => sum + entry.indices.length / 3,
      0,
    );
    if (
      vertexCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxVertices ||
      triangleCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxTriangles
    ) {
      ctx.addIssue({
        code: 'custom',
        path: ['primitives'],
        message: 'collider artifact exceeds aggregate geometry budget',
      });
    }
  });

export type ColliderPolicyV1 = z.infer<typeof ColliderPolicyV1Schema>;
export type ColliderArtifactV1 = z.infer<typeof ColliderArtifactV1Schema>;
type ParsedAuthoredColliderGeometryV1 = z.infer<typeof AuthoredColliderGeometryV1Schema>;
export type AuthoredColliderGeometryV1 = Omit<
  ParsedAuthoredColliderGeometryV1,
  'sourceArtifactSha256'
> & {
  sourceArtifactSha256: `sha256:${string}`;
};

export interface ResolveAuthoredColliderGeometryV1Request {
  schemaVersion: typeof AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION;
  sourceArtifactSha256: `sha256:${string}`;
  transformFrame: 'asset-local';
  nodeNames: readonly string[];
  limits: Readonly<typeof AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1>;
}

/** Host port: resolve only the requested hash-bound GLB nodes, never paths, URLs, or model code. */
export type ResolveAuthoredColliderGeometryV1Port = (
  request: ResolveAuthoredColliderGeometryV1Request,
) => Promise<unknown>;

export interface AuthoredColliderSubmeshV1 {
  nodeName: string;
  positions: readonly number[];
  indices: readonly number[];
}

export interface CompileColliderArtifactV1Input {
  sourceArtifactSha256: `sha256:${string}`;
  bounds: Aabb;
  authoredSubmeshes?: readonly AuthoredColliderSubmeshV1[];
}

export class ColliderCompileError extends Error {
  constructor(
    readonly code:
      | 'COLLIDER_AUTHORED_SUBMESH_MISSING'
      | 'COLLIDER_AUTHORED_SUBMESH_INVALID'
      | 'COLLIDER_SOURCE_HASH_MISMATCH'
      | 'COLLIDER_BUDGET_EXCEEDED',
    message: string,
  ) {
    super(`${code}: ${message}`);
    this.name = 'ColliderCompileError';
  }
}

export function parseColliderPolicyV1(input: unknown): ColliderPolicyV1 {
  assertNoPrototypeKeys(input);
  return ColliderPolicyV1Schema.parse(input);
}

export function parseAuthoredColliderGeometryV1(input: unknown): AuthoredColliderGeometryV1 {
  if (typeof input === 'object' && input !== null && 'submeshes' in input) {
    const submeshes = (input as { submeshes?: unknown }).submeshes;
    if (Array.isArray(submeshes)) {
      let vertices = 0;
      let triangles = 0;
      for (const submesh of submeshes) {
        if (typeof submesh !== 'object' || submesh === null) continue;
        const positions = (submesh as { positions?: unknown }).positions;
        const indices = (submesh as { indices?: unknown }).indices;
        if (Array.isArray(positions)) vertices += positions.length / 3;
        if (Array.isArray(indices)) triangles += indices.length / 3;
      }
      if (
        submeshes.length > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxNodes ||
        vertices > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxVertices ||
        triangles > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxTriangles
      ) {
        throw new ColliderCompileError(
          'COLLIDER_BUDGET_EXCEEDED',
          'resolved collider geometry exceeds node/vertex/triangle limits',
        );
      }
    }
  }
  assertNoPrototypeKeys(input);
  try {
    return AuthoredColliderGeometryV1Schema.parse(input) as AuthoredColliderGeometryV1;
  } catch (error) {
    if (error instanceof ColliderCompileError) throw error;
    throw new ColliderCompileError(
      'COLLIDER_AUTHORED_SUBMESH_INVALID',
      error instanceof Error ? error.message : String(error),
    );
  }
}

export function parseColliderArtifactV1(input: unknown): ColliderArtifactV1 {
  assertNoPrototypeKeys(input);
  return ColliderArtifactV1Schema.parse(input);
}

function boxPrimitive(value: Aabb) {
  const [x0, y0, z0] = value.min;
  const [x1, y1, z1] = value.max;
  return {
    nodeName: 'generated:bounds-box',
    positions: [
      x0,
      y0,
      z0,
      x1,
      y0,
      z0,
      x1,
      y1,
      z0,
      x0,
      y1,
      z0,
      x0,
      y0,
      z1,
      x1,
      y0,
      z1,
      x1,
      y1,
      z1,
      x0,
      y1,
      z1,
    ],
    indices: [
      0, 2, 1, 0, 3, 2, 4, 5, 6, 4, 6, 7, 0, 1, 5, 0, 5, 4, 3, 7, 6, 3, 6, 2, 0, 4, 7, 0, 7, 3, 1,
      2, 6, 1, 6, 5,
    ],
  };
}

function boundsOfPrimitives(primitives: readonly { positions: readonly number[] }[]): Aabb {
  const min: Vec3 = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
  const max: Vec3 = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
  for (const primitive of primitives) {
    for (let offset = 0; offset < primitive.positions.length; offset += 3) {
      for (let axis = 0; axis < 3; axis++) {
        min[axis] = Math.min(min[axis]!, primitive.positions[offset + axis]!);
        max[axis] = Math.max(max[axis]!, primitive.positions[offset + axis]!);
      }
    }
  }
  return { min, max };
}

export function compileColliderArtifactV1(
  policyInput: unknown,
  input: CompileColliderArtifactV1Input,
): ColliderArtifactV1 {
  const policy = parseColliderPolicyV1(policyInput);
  const parsedBounds = bounds.parse(input.bounds);
  const sourceArtifactSha256 = sha256.parse(input.sourceArtifactSha256);
  let primitives: Array<{ nodeName: string; positions: number[]; indices: number[] }> = [];
  if (policy.kind === 'bounds' || policy.kind === 'generated-mesh') {
    primitives = [boxPrimitive(parsedBounds)];
  } else if (policy.kind === 'authored-submesh') {
    const available = new Map(
      (input.authoredSubmeshes ?? []).map((entry) => [entry.nodeName, entry]),
    );
    const missing = policy.nodeNames.filter((nodeName) => !available.has(nodeName));
    if (missing.length) {
      throw new ColliderCompileError(
        'COLLIDER_AUTHORED_SUBMESH_MISSING',
        `missing authored collider node(s): ${missing.join(', ')}`,
      );
    }
    try {
      primitives = [...policy.nodeNames].sort().map((nodeName) => {
        const source = available.get(nodeName)!;
        return primitive.parse({
          nodeName,
          positions: [...source.positions],
          indices: [...source.indices],
        });
      });
    } catch (error) {
      throw new ColliderCompileError(
        'COLLIDER_AUTHORED_SUBMESH_INVALID',
        error instanceof Error ? error.message : String(error),
      );
    }
  }
  const vertexCount = primitives.reduce((sum, entry) => sum + entry.positions.length / 3, 0);
  const triangleCount = primitives.reduce((sum, entry) => sum + entry.indices.length / 3, 0);
  if (
    vertexCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxVertices ||
    triangleCount > AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1.maxTriangles
  ) {
    throw new ColliderCompileError(
      'COLLIDER_BUDGET_EXCEEDED',
      'collider exceeds node/vertex/triangle limits',
    );
  }
  const artifactBounds = primitives.length ? boundsOfPrimitives(primitives) : parsedBounds;
  return parseColliderArtifactV1({
    schemaVersion: COLLIDER_ARTIFACT_V1_SCHEMA_VERSION,
    transformFrame: 'asset-local',
    sourceArtifactSha256,
    policy,
    bounds: artifactBounds,
    primitives,
  });
}

export function canonicalColliderArtifactV1Json(input: unknown): string {
  return canonicalContractJson(parseColliderArtifactV1(input));
}

export function encodeColliderArtifactV1(input: unknown): Uint8Array {
  return new TextEncoder().encode(canonicalColliderArtifactV1Json(input));
}

export function decodeColliderArtifactV1(bytes: Uint8Array): ColliderArtifactV1 {
  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
  const artifact = parseColliderArtifactV1(JSON.parse(text));
  if (canonicalColliderArtifactV1Json(artifact) !== text) {
    throw new TypeError('collider artifact bytes are not canonical');
  }
  return artifact;
}

export function hashColliderArtifactV1(input: unknown): Promise<`sha256:${string}`> {
  return sha256ContractBytes(encodeColliderArtifactV1(input));
}

export interface ColliderWorldTransformV1 {
  position: Vec3;
  rotationYDeg: number;
  uniformScale: number;
}

export function worldColliderAabbV1(input: unknown, transform: ColliderWorldTransformV1): Aabb {
  const artifact = parseColliderArtifactV1(input);
  if (
    !Number.isFinite(transform.rotationYDeg) ||
    !Number.isFinite(transform.uniformScale) ||
    transform.uniformScale <= 0
  ) {
    throw new TypeError('collider transform must have finite rotation and positive scale');
  }
  if (
    transform.position.length !== 3 ||
    transform.position.some((entry) => !Number.isFinite(entry))
  ) {
    throw new TypeError('collider transform position must be finite');
  }
  return worldAabbFromLocal(
    artifact.bounds.min,
    artifact.bounds.max,
    transform.position,
    transform.rotationYDeg,
    transform.uniformScale,
  );
}