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.

11.6 KB
Raw Blame
/**
 * Parametric gear / blade geometry — Round 1
 *
 * Game-asset-grade (not real involute profiles). Built directly from
 * triangulated polygons, no CSG, no WASM. Fast and cheap.
 */

import * as THREE from 'three';
import { AuthoringDiagnosticError } from './evaluator/authoring-diagnostic';
import { assertDimension, assertPrimitiveSegments } from './geometry-budget';

// =============================================================================
// gearGeo
// =============================================================================

export interface GearOptions {
  /** Number of teeth around the rim. Default 12. */
  teeth?: number;
  /** Radius at the valley between teeth. Default 0.8. */
  rootRadius?: number;
  /** Radius at the tip of each tooth. Default 1.0. */
  tipRadius?: number;
  /** Radius of the center bore (0 = no hole). Default 0.2. */
  boreRadius?: number;
  /** Thickness along Y. Default 0.3. */
  height?: number;
  /**
   * Fraction of each tooth sector occupied by the tooth itself (0..1).
   * 0.5 = tooth and valley equally wide. Default 0.5.
   */
  toothWidthFrac?: number;
}

/**
 * Build a stylized gear directly — no CSG required.
 *
 * Geometry: for each tooth i ∈ [0, N):
 *   - the sector from θ = i·(2π/N) to (i+1)·(2π/N) is split at four angles
 *     → valley-start, tooth-start, tooth-end, valley-end
 *   - alternating radii root/tip/tip/root trace the crown profile
 * The profile is then extruded along Y and capped on both ends as an annulus
 * fan (a center bore is triangulated as a concentric inner ring).
 *
 * @example
 * const g = gearGeo({ teeth: 12 });
 * const mat = gameMaterial(0x909090, { metalness: 0.8, roughness: 0.3 });
 * createPart('Gear', g, mat, { parent: root });
 */
export function gearGeo(opts: GearOptions = {}): THREE.BufferGeometry {
  const {
    teeth = 12,
    rootRadius = 0.8,
    tipRadius = 1.0,
    boreRadius = 0.2,
    height = 0.3,
    toothWidthFrac = 0.5,
  } = opts;

  assertPrimitiveSegments('gearGeo teeth', teeth, 3);
  assertDimension('gearGeo rootRadius', rootRadius);
  assertDimension('gearGeo tipRadius', tipRadius);
  assertDimension('gearGeo boreRadius', boreRadius, true);
  assertDimension('gearGeo height', height);
  if (!Number.isFinite(toothWidthFrac) || toothWidthFrac <= 0 || toothWidthFrac >= 1)
    throw new RangeError('gearGeo toothWidthFrac must be strictly between 0 and 1.');
  if (tipRadius <= rootRadius || boreRadius >= rootRadius) {
    throw new AuthoringDiagnosticError('GEAR_RADII_ORDER');
  }

  // Crown (outer) ring: 3 distinct points per tooth around XZ plane.
  // α = half-width of the valley within each sector (so the tooth spans
  // the central toothWidthFrac of the sector).
  const sector = (Math.PI * 2) / teeth;
  const alpha = (1 - toothWidthFrac) * (sector / 2);

  // Each valley end is the next tooth's valley start; emit it only once.
  type V2 = [number, number];
  const crown: V2[] = [];
  for (let i = 0; i < teeth; i++) {
    const base = i * sector;
    const a0 = base; // valley start
    const a1 = base + alpha; // tooth start
    const a2 = base + sector - alpha; // tooth end
    crown.push([rootRadius * Math.cos(a0), rootRadius * Math.sin(a0)]);
    crown.push([tipRadius * Math.cos(a1), tipRadius * Math.sin(a1)]);
    crown.push([tipRadius * Math.cos(a2), tipRadius * Math.sin(a2)]);
  }
  const N = crown.length; // 3 * teeth

  // Bore (inner) ring: one point per crown point so cap triangulation is a
  // clean strip between concentric rings. N points on a circle of boreRadius.
  const bore: V2[] = [];
  for (let i = 0; i < N; i++) {
    const t = Math.atan2(crown[i]![1], crown[i]![0]);
    bore.push([boreRadius * Math.cos(t), boreRadius * Math.sin(t)]);
  }

  const halfH = height / 2;

  // Vertex layout:
  //   [0 .. N-1]            crown top
  //   [N .. 2N-1]            crown bottom
  //   [2N .. 3N-1]           bore top
  //   [3N .. 4N-1]           bore bottom
  const positions: number[] = [];
  const indices: number[] = [];

  for (let i = 0; i < N; i++) {
    const p = crown[i]!;
    positions.push(p[0], halfH, p[1]);
  }
  for (let i = 0; i < N; i++) {
    const p = crown[i]!;
    positions.push(p[0], -halfH, p[1]);
  }
  for (let i = 0; i < N; i++) {
    const p = bore[i]!;
    positions.push(p[0], halfH, p[1]);
  }
  for (let i = 0; i < N; i++) {
    const p = bore[i]!;
    positions.push(p[0], -halfH, p[1]);
  }

  const crownTop = 0;
  const crownBot = N;
  const boreTop = 2 * N;
  const boreBot = 3 * N;

  // Winding convention: Three.js is right-handed (X right, Y up, Z out of
  // screen). A triangle (A,B,C) has normal = (B-A) × (C-A). For an outward
  // normal on the TOP face (+Y), we need (B-A) × (C-A) to point +Y — which
  // means A → B → C is CW when viewed from +Y looking down. (Equivalently:
  // CCW when viewed from -Y.) Getting this wrong back-face-culls the face.

  // Top cap: normal should point +Y. Verts go bore-inner → crown-outer-next
  // → crown-outer → ... so the triangle pair is (bA, cB, cA) and (bA, bB, cB).
  for (let i = 0; i < N; i++) {
    const j = (i + 1) % N;
    const cA = crownTop + i;
    const cB = crownTop + j;
    const bA = boreTop + i;
    const bB = boreTop + j;
    indices.push(bA, cB, cA);
    if (boreRadius > 0) indices.push(bA, bB, cB);
  }

  // Bottom cap: normal should point -Y. Reverse of top-cap winding.
  for (let i = 0; i < N; i++) {
    const j = (i + 1) % N;
    const cA = crownBot + i;
    const cB = crownBot + j;
    const bA = boreBot + i;
    const bB = boreBot + j;
    indices.push(bA, cA, cB);
    if (boreRadius > 0) indices.push(bA, cB, bB);
  }

  // Outer side wall: normal should point RADIALLY OUTWARD. Going around in
  // increasing angle (i→i+1) with top above bottom, the CW-from-outside
  // order is tA → tB → bB → bA. Triangles: (tA, tB, bB), (tA, bB, bA).
  for (let i = 0; i < N; i++) {
    const j = (i + 1) % N;
    const tA = crownTop + i;
    const tB = crownTop + j;
    const bA = crownBot + i;
    const bB = crownBot + j;
    indices.push(tA, tB, bB);
    indices.push(tA, bB, bA);
  }

  // Inner side wall (bore): normal should point INWARD toward axis.
  // Reverse of outer wall winding.
  for (let i = 0; boreRadius > 0 && i < N; i++) {
    const j = (i + 1) % N;
    const tA = boreTop + i;
    const tB = boreTop + j;
    const bA = boreBot + i;
    const bB = boreBot + j;
    indices.push(tA, bA, bB);
    indices.push(tA, bB, tB);
  }

  const geo = new THREE.BufferGeometry();
  geo.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
  geo.setIndex(indices);
  // Flat shading → each face gets its own normal (hard mechanical edges).
  const nonIndexed = geo.toNonIndexed();
  nonIndexed.computeVertexNormals();
  return nonIndexed;
}

// =============================================================================
// bladeGeo
// =============================================================================

export interface BladeOptions {
  /** Total blade length along +Y. Default 1.5. */
  length?: number;
  /** Width at the guard (base). Default 0.1. */
  baseWidth?: number;
  /** Cross-section thickness along Z. Default 0.015. */
  thickness?: number;
  /** Length of the tapered tip section at the top. Default 0.25. */
  tipLength?: number;
  /**
   * 0..1 — cross-section bevel. 0 = flat rectangle; 1 = diamond (centerline
   * ridge). Default 0 (flat) for simplicity; 0.5 for a bevelled edge.
   */
  edgeBevel?: number;
}

/**
 * Build a game-grade sword blade: tapered profile from base to shoulder,
 * then shoulder to tip point. Cross-section is a flat rectangle or an
 * optional diamond (edgeBevel > 0).
 *
 * Origin is at (0, 0, 0) = the base of the blade (guard side). Tip is at
 * (0, length, 0). Center the blade on the grip by translating after.
 *
 * @example
 * const b = bladeGeo({ length: 1.5, baseWidth: 0.08, tipLength: 0.3 });
 * createPart('Blade', b, steelMat, { position: [0, 0, 0], parent: root });
 */
export function bladeGeo(opts: BladeOptions = {}): THREE.BufferGeometry {
  const {
    length = 1.5,
    baseWidth = 0.1,
    thickness = 0.015,
    tipLength = 0.25,
    edgeBevel = 0,
  } = opts;

  for (const [name, value] of Object.entries({ length, baseWidth, thickness }))
    assertDimension(`bladeGeo ${name}`, value);
  assertDimension('bladeGeo tipLength', tipLength, true);
  if (!Number.isFinite(edgeBevel) || edgeBevel < 0 || edgeBevel > 1)
    throw new RangeError('bladeGeo edgeBevel must be between 0 and 1.');
  if (tipLength >= length) {
    throw new Error('bladeGeo: tipLength must be less than length');
  }

  const hw = baseWidth / 2;
  const ht = thickness / 2;
  const shoulderY = length - tipLength;

  // 5-point outline in the XY plane (top surface of the blade looking down
  // from +Z). Outline traced CCW for a +Z-facing top.
  //   base-left  → base-right → shoulder-right → tip → shoulder-left
  const outline: Array<[number, number]> = [
    [-hw, 0],
    [hw, 0],
    [hw, shoulderY],
    [0, length],
    [-hw, shoulderY],
  ];
  const n = outline.length; // 5

  // If edgeBevel = 0, build a prism: extrude the outline by ±thickness/2.
  // If edgeBevel > 0, add a centerline ridge on each side that pinches
  // inward from the full thickness toward the edge of the outline.
  const positions: number[] = [];
  const indices: number[] = [];

  if (edgeBevel <= 0) {
    // ----- Flat-profile prism -----
    // verts: 0..n-1 = top (+Z), n..2n-1 = bottom (-Z)
    for (const [x, y] of outline) positions.push(x, y, ht);
    for (const [x, y] of outline) positions.push(x, y, -ht);

    // Top face: triangle fan from base-left (idx 0).
    // Outline 0,1,2,3,4 → fan (0,1,2) (0,2,3) (0,3,4).
    for (let i = 1; i < n - 1; i++) {
      indices.push(0, i, i + 1);
    }
    // Bottom face: reversed winding. Indices n..2n-1.
    for (let i = 1; i < n - 1; i++) {
      indices.push(n, n + i + 1, n + i);
    }
    // Side walls: for each outline edge (i, i+1), connect top+bottom.
    for (let i = 0; i < n; i++) {
      const j = (i + 1) % n;
      const tA = i;
      const tB = j;
      const bA = n + i;
      const bB = n + j;
      indices.push(tA, bA, bB);
      indices.push(tA, bB, tB);
    }
  } else {
    // A convex XZ section at base and shoulder, joined to one sharp tip.
    // edgeBevel controls edge thickness; the center ridge stays at +/-ht.
    // Full diamond sections have four distinct corners, partial bevels six.
    const edge = ht * (1 - edgeBevel);
    const section: Array<[number, number]> =
      edgeBevel === 1
        ? [
            [-hw, 0],
            [0, -ht],
            [hw, 0],
            [0, ht],
          ]
        : [
            [-hw, -edge],
            [0, -ht],
            [hw, -edge],
            [hw, edge],
            [0, ht],
            [-hw, edge],
          ];
    const count = section.length;
    for (const y of [0, shoulderY]) for (const [x, z] of section) positions.push(x, y, z);
    const baseCenter = positions.length / 3;
    positions.push(0, 0, 0);
    const tip = positions.length / 3;
    positions.push(0, length, 0);
    for (let i = 0; i < count; i++) {
      const j = (i + 1) % count;
      // XZ section winding gives -Y at the base. Side and taper faces
      // consistently face outward; no closing strip overlaps the sides.
      indices.push(baseCenter, i, j);
      indices.push(i, count + j, j, i, count + i, count + j);
      indices.push(count + i, tip, count + j);
    }
  }

  const geo = new THREE.BufferGeometry();
  geo.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
  geo.setIndex(indices);
  // Flat shading: mechanical edges, crisp tip.
  const nonIndexed = geo.toNonIndexed();
  nonIndexed.computeVertexNormals();
  return nonIndexed;
}