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.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
/**
* Kiln Primitives Library
*
* High-level helpers for 3D asset creation.
* Claude generates code using these primitives to keep files small.
*
* Copied from packages/client/src/lib/kiln/primitives.ts as the canonical
* source in @pixel-forge/core. The headless variant in scripts/export-glb.ts
* was verified structurally identical; the two have been reconciled here.
*/
import * as THREE from 'three';
import { AuthoringDiagnosticError, assertMaterialName } from './evaluator/authoring-diagnostic';
import {
assertDimension,
assertPrimitiveSegments,
assertPrimitiveGrid,
assertFiniteTriple,
GEOMETRY_ALLOCATION_LIMITS,
} from './geometry-budget';
import { buildWallPanels } from './wall-panels';
import { createBoneChain, createJointChain, createSkinnedPart } from './character';
import { describeAssembly, replicateAssembly } from './assembly';
import { defineLod } from './lod';
export { defineLod } from './lod';
import { markOpenShell } from './open-shell';
import {
anchor,
colliderBox,
colliderCapsule,
colliderHull,
defineModule,
port,
repeatInstances,
} from './delivery';
import { bakeSurfaceAttributes } from './surface-bake';
import { requireSolid } from './require-solid';
import { definePalette, type PaletteDeclarationV1 } from './palette-check';
import { type BudgetDeclarationV1, defineBudget } from './budget';
import { useCubicSpline } from './animation-cubic';
import {
CUBIC_INTERPOLATIONS,
cubicSplineValues,
isCubicInterpolation,
isCubicSplineTrack,
type CubicInterpolation,
} from './animation-spline';
export { markOpenShell } from './open-shell';
export * from './assembly';
export { createRoofPlanes } from './architecture';
export type { RoofPlanesOptions } from './architecture';
import {
createGableEndPanel,
createGableRoof,
createGableShell,
createRoofPlanes,
createRoofSurfaceLayout,
} from './architecture';
import * as gears from './gears';
import * as ops from './ops';
import * as geometry from './geometry';
import * as deform from './deform';
import * as sweep from './sweep';
import { simplifyGeometry } from './simplify';
import { implicitSurface } from './implicit';
import { catmullRomPath, metaballSurface, smoothOrganic, spiralPath, taperedTube } from './organic';
import { smoothUnion, sphereInside } from './sdf';
export * from './implicit';
export * from './organic';
export { smoothUnion, sphereInside } from './sdf';
export * from './sweep';
export * from './deform';
export * from './geometry';
import * as profile from './profile';
import * as solids from './solids';
import * as proceduralTextures from './procedural-texture';
import { seededRandom } from './seeded-random';
import * as textures from './textures';
import { textureAtlas, remapUVToAtlas } from './texture-atlas';
import type { TextureResolver } from './texture-resolver';
import {
compilePortableMaterialSpecV2,
compilePortableMaterialSpecV3,
} from './portable-material-runtime';
import { createVehicleFrame, createWheelAssembly, createWheelGeometrySet } from './vehicle';
import {
stampSemanticMetadataV1,
type SemanticMetadataV1,
type SemanticMetadataV1Input,
} from './contracts';
import * as uv from './uv';
import * as uvShapes from './uv-shapes';
import { projectUV } from './uv-project';
export { projectUV } from './uv-project';
export type { ProjectUVOptions } from './uv-project';
export { remapUV } from './uv-shapes';
export type { RemapUVOptions } from './uv-shapes';
export { textureAtlas, remapUVToAtlas } from './texture-atlas';
export type { AtlasUVOptionsV1 } from './texture-atlas';
export {
TextureAtlasError,
TEXTURE_ATLAS_COMPILER_ID,
TEXTURE_ATLAS_COMPILER_ID_V1_2,
TEXTURE_ATLAS_LIMITS,
TEXTURE_ATLAS_LIMITS_V1_2,
textureAtlasCompilerIdV1,
canonicalizeTextureAtlasSpecV1,
canonicalTextureAtlasJsonV1,
hashTextureAtlasSpecV1,
} from './texture-atlas-contract';
export type {
AtlasRectangleV1,
AtlasEdgeModeV1,
AtlasResourceExpectationV1,
TextureAtlasSourceV1,
TextureAtlasRegionV1,
TextureAtlasSpecV1,
TextureAtlasPackV1,
CanonicalTextureAtlasPackV1,
TextureAtlasCompilerIdV1,
CanonicalTextureAtlasSourceV1,
CanonicalTextureAtlasRegionV1,
CanonicalTextureAtlasSpecV1,
} from './texture-atlas-contract';
export { compileTextureAtlasSpecV1 } from './texture-atlas-pixels';
export type {
TextureAtlasCompileOptionsV1,
TextureAtlasBudgetV1,
TextureAtlasSourceManifestV1,
TextureAtlasRegionManifestV1,
TextureAtlasManifestV1,
CompiledTextureAtlasV1,
} from './texture-atlas-pixels';
export {
createGableEndPanel,
createGableRoof,
createGableShell,
createRoofSurfaceLayout,
} from './architecture';
export type {
GableEndPanelOptions,
GableRoofOptions,
GableShellOptions,
RoofFaceFrame,
RoofSurfaceLayoutOptions,
} from './architecture';
export { createBoneChain, createJointChain, createSkinnedPart } from './character';
export type {
BoneChainResultV1,
CreateSkinnedPartOptions,
CreateJointChainOptionsV1,
JointChainResultV1,
JointChainSegmentV1,
} from './character';
export {
createVehicleFrame,
createWheelAssembly,
createWheelGeometrySet,
} from './vehicle';
export { materialRecipe } from './material-recipe-runtime';
export type { ApplyMaterialRecipeOptions } from './material-recipe-runtime';
export type { MaterialRecipeId, MaterialRecipeOverridesV1 } from './material-recipes';
export {
compilePortableMaterialSpecV2,
compilePortableMaterialSpecV3,
} from './portable-material-runtime';
export {
canonicalizePortableMaterialSpecV3,
PortableMaterialV3Error,
PORTABLE_MATERIAL_V3_LIMITS,
} from './procedural-material-v3';
export type {
PortableMaterialSpecV3,
CanonicalPortableMaterialSpecV3,
PortableTextureRefV3,
CanonicalPortableTextureRefV3,
} from './procedural-material-v3';
export { canonicalizePortableSamplerV1 } from './portable-sampler';
export type { PortableSamplerV1, CanonicalPortableSamplerV1 } from './portable-sampler';
export {
compileProceduralTextureSpecV3,
canonicalizeProceduralTextureSpecV3,
canonicalProceduralTextureJsonV3,
hashProceduralTextureSpecV3,
PROCEDURAL_TEXTURE_V3_COMPILER_ID,
PROCEDURAL_TEXTURE_SPEC_VERSION_V3,
MAX_PROCEDURAL_V3_EDGE,
MAX_PROCEDURAL_V3_TEXELS,
MAX_PROCEDURAL_V3_OPERATIONS,
MAX_PROCEDURAL_V3_VERTICES,
MAX_PROCEDURAL_V3_STAMPS,
MAX_PROCEDURAL_V3_PALETTE,
MAX_PROCEDURAL_V3_WORK,
MAX_PROCEDURAL_V3_TRANSIENT_BYTES,
} from './procedural-texture-v3';
export type {
CompiledProceduralTextureV3,
RgbaV3,
PixelPointV3,
PixelRectangleV3,
ProceduralShapeV3,
ProceduralOperationV3,
CanonicalProceduralOperationV3,
ProceduralTextureSpecV3,
CanonicalProceduralTextureSpecV3,
} from './procedural-texture-v3';
export {
MAX_PORTABLE_MATERIAL_TEXELS,
MAX_PORTABLE_MATERIAL_TEXTURES,
MAX_PROCEDURAL_LAYERS,
MAX_PROCEDURAL_SIZE,
PORTABLE_MATERIAL_SPEC_VERSION,
PROCEDURAL_TEXTURE_SPEC_VERSION,
ProceduralTextureError,
canonicalProceduralTextureJsonV2,
canonicalizePortableMaterialSpecV2,
canonicalizeProceduralTextureSpecV2,
compileProceduralTextureSpecV2,
hashProceduralTextureSpecV2,
migrateProceduralTextureSpecV1,
} from './procedural-texture';
export type {
CanonicalPortableMaterialSpecV2,
CanonicalProceduralTextureSpecV2,
PortableMaterialSpecV2,
ProceduralLayer,
ProceduralTextureSpec,
ProceduralTextureSpecV1,
ProceduralTextureSpecV2,
} from './procedural-texture';
export type {
VehicleFrameOptions,
VehicleFrameResult,
WheelAssemblyOptions,
WheelAssemblyResult,
WheelGeometrySet,
WheelMaterialSet,
} from './vehicle';
type Vec3Tuple = [number, number, number];
function vectorToTuple(v: THREE.Vector3): Vec3Tuple {
return [v.x, v.y, v.z];
}
// =============================================================================
// Geometry Helpers
// =============================================================================
/**
* Creates the root Object3D for an asset.
*/
export function createRoot(name: string): THREE.Object3D {
const root = new THREE.Object3D();
root.name = name;
return root;
}
/**
* Creates a pivot (empty Object3D) for skeletal animation.
* Pivots are the joints that get animated; meshes are children.
*/
export function createPivot(
name: string,
position: [number, number, number] = [0, 0, 0],
parent?: THREE.Object3D,
): THREE.Object3D {
const pivot = new THREE.Object3D();
pivot.name = `Joint_${name}`;
pivot.position.set(...position);
if (parent) parent.add(pivot);
return pivot;
}
/**
* Creates a mesh with automatic pivot wrapping for animation.
* The mesh is automatically added to `parent` if provided.
*
* Returns the added Object3D (mesh or pivot) for reference.
* NOTE: Do NOT call .add() on the return value - it's already added!
*/
/**
* The three positional arguments, checked at the door.
*
* `new THREE.Mesh()` accepts anything at all and fails much later somewhere
* else. A dispatched model that wrote `createPart(root, { geo: boxGeo, material })`
* -- the shape most other scene APIs take, and the single most common way to get
* this call wrong -- got all the way to the exporter and died on
* `undefined is not an object (evaluating 'Object.keys(morphAttributes)')`.
* That message names nothing the author did and gives a model no way back, so it
* spends its remaining turns guessing. Three cheap instanceof checks turn the
* same mistake into a sentence that says what was passed, what was wanted, and
* what the call looks like when it is right.
*
* The tests are the `isBufferGeometry` / `isMaterial` flags rather than
* `instanceof`, and that is not a style choice. `three-subdivide` resolves its
* own copy of three, so `subdivide()` hands back a geometry whose prototype
* chain belongs to a different THREE -- `instanceof` says no to something that
* is a geometry in every way that matters, and the lighthouse's rocks go
* through exactly that path. Three.js ships those flags for this reason.
*/
function assertPartArgs(name: unknown, geometry: unknown, material: unknown): void {
const SIG =
'Signature: createPart(name, geometry, material, options?) -- ' +
"e.g. createPart('Hull', boxGeo(1, 1, 1), gameMaterial(0x808080), { parent: root }).";
if (typeof name !== 'string') {
const asObject = name as { isObject3D?: boolean; name?: string } | null;
const got =
asObject?.isObject3D === true
? `an Object3D ("${asObject.name || 'unnamed'}"). The parent belongs in the options object as { parent }, not first`
: `${name === null ? 'null' : typeof name}`;
throw new AuthoringDiagnosticError(
'PART_NAME_ARGUMENT',
`createPart: the first argument is the part NAME, a string, but got ${got}. ${SIG}`,
);
}
if ((geometry as { isBufferGeometry?: boolean } | null)?.isBufferGeometry !== true) {
let got: string;
if (typeof geometry === 'function') {
got =
'a function -- geometry helpers have to be CALLED, so boxGeo(1, 1, 1) rather than boxGeo';
} else if (geometry instanceof Promise) {
got =
'a Promise -- roundedBoxGeo, extrudeProfile, revolveProfile and simplifyGeometry are async, ' +
'so await the helper and mark build() async';
} else {
got =
geometry === null ? 'null' : geometry === undefined ? 'undefined' : `a ${typeof geometry}`;
}
throw new AuthoringDiagnosticError(
'PART_GEOMETRY_ARGUMENT',
`createPart("${name}"): the second argument must be a geometry, but got ${got}. ${SIG}`,
);
}
if ((material as { isMaterial?: boolean } | null)?.isMaterial !== true) {
const got =
typeof material === 'number'
? 'a number -- a colour is not a material, so wrap it: gameMaterial(0x808080)'
: material === null
? 'null'
: material === undefined
? 'undefined'
: `a ${typeof material}`;
throw new AuthoringDiagnosticError(
'PART_MATERIAL_ARGUMENT',
`createPart("${name}"): the third argument must be a material, but got ${got}. ${SIG}`,
);
}
}
export function createPart(
name: string,
geometry: THREE.BufferGeometry,
material: THREE.Material,
options: {
position?: [number, number, number];
rotation?: [number, number, number];
scale?: [number, number, number];
pivot?: boolean; // Wrap in pivot for animation
parent?: THREE.Object3D;
/** Versioned roles/relationships/local frames/sockets stamped on the returned
* helper node and preserved in glTF node extras. */
semantic?: SemanticMetadataV1 | SemanticMetadataV1Input;
} = {},
): THREE.Object3D {
assertPartArgs(name, geometry, material);
const mesh = new THREE.Mesh(geometry, material);
mesh.name = `Mesh_${name}`;
if (options.position) mesh.position.set(...options.position);
if (options.rotation)
mesh.rotation.set(
THREE.MathUtils.degToRad(options.rotation[0]),
THREE.MathUtils.degToRad(options.rotation[1]),
THREE.MathUtils.degToRad(options.rotation[2]),
);
if (options.scale) mesh.scale.set(...options.scale);
if (options.pivot) {
const pivot = new THREE.Object3D();
pivot.name = `Joint_${name}`;
pivot.add(mesh);
mesh.position.set(0, 0, 0); // Reset - pivot controls position
if (options.position) pivot.position.set(...options.position);
if (options.parent) options.parent.add(pivot);
if (options.semantic) stampSemanticMetadataV1(pivot, options.semantic);
return pivot; // Return the pivot (the animatable node)
}
if (options.parent) options.parent.add(mesh);
if (options.semantic) stampSemanticMetadataV1(mesh, options.semantic);
return mesh; // Return the mesh
}
// =============================================================================
// Common Shapes (game-ready low-poly)
// =============================================================================
export function capsuleGeo(radius: number, height: number, segments = 6): THREE.CapsuleGeometry {
assertDimension('capsuleGeo radius', radius);
assertDimension('capsuleGeo height (straight middle length)', height, true);
assertDimension('capsuleGeo outer half-length', height / 2 + radius);
assertPrimitiveSegments('capsuleGeo segments', segments, 3);
return new THREE.CapsuleGeometry(radius, height, 2, segments);
}
export function capsuleXGeo(radius: number, length: number, segments = 6): THREE.CapsuleGeometry {
const geo = capsuleGeo(radius, length, segments);
geo.rotateZ(-Math.PI / 2);
return geo;
}
export function capsuleZGeo(radius: number, length: number, segments = 6): THREE.CapsuleGeometry {
const geo = capsuleGeo(radius, length, segments);
geo.rotateX(Math.PI / 2);
return geo;
}
export function cylinderGeo(
radiusTop: number,
radiusBottom: number,
height: number,
segments = 8,
): THREE.CylinderGeometry {
assertDimension('cylinderGeo radiusTop', radiusTop, true);
assertDimension('cylinderGeo radiusBottom', radiusBottom, true);
if (radiusTop === 0 && radiusBottom === 0)
throw new RangeError('cylinderGeo requires at least one positive radius.');
assertDimension('cylinderGeo height', height);
assertPrimitiveSegments('cylinderGeo segments', segments, 3);
return new THREE.CylinderGeometry(radiusTop, radiusBottom, height, segments);
}
export function cylinderXGeo(
radiusTop: number,
radiusBottom: number,
length: number,
segments = 8,
): THREE.CylinderGeometry {
const geo = cylinderGeo(radiusTop, radiusBottom, length, segments);
geo.rotateZ(-Math.PI / 2);
return geo;
}
export function cylinderZGeo(
radiusTop: number,
radiusBottom: number,
length: number,
segments = 8,
): THREE.CylinderGeometry {
const geo = cylinderGeo(radiusTop, radiusBottom, length, segments);
geo.rotateX(Math.PI / 2);
return geo;
}
export function boxGeo(width: number, height: number, depth: number): THREE.BoxGeometry {
for (const [name, value] of Object.entries({ width, height, depth }))
assertDimension(`boxGeo ${name} (use planeGeo for a sheet)`, value);
return new THREE.BoxGeometry(width, height, depth);
}
export function sphereGeo(
radius: number,
widthSegments = 8,
heightSegments = 6,
): THREE.SphereGeometry {
assertDimension('sphereGeo radius', radius);
assertPrimitiveSegments('sphereGeo widthSegments', widthSegments, 3);
assertPrimitiveSegments('sphereGeo heightSegments', heightSegments, 2);
assertPrimitiveGrid('sphereGeo', widthSegments, heightSegments);
return new THREE.SphereGeometry(radius, widthSegments, heightSegments);
}
export function coneGeo(radius: number, height: number, segments = 8): THREE.ConeGeometry {
assertDimension('coneGeo radius', radius);
assertDimension('coneGeo height', height);
assertPrimitiveSegments('coneGeo segments', segments, 3);
return new THREE.ConeGeometry(radius, height, segments);
}
export function coneXGeo(radius: number, length: number, segments = 8): THREE.ConeGeometry {
const geo = coneGeo(radius, length, segments);
geo.rotateZ(-Math.PI / 2);
return geo;
}
export function coneZGeo(radius: number, length: number, segments = 8): THREE.ConeGeometry {
const geo = coneGeo(radius, length, segments);
geo.rotateX(Math.PI / 2);
return geo;
}
// Y-axis aliases. The base geometries (`cylinderGeo`, `capsuleGeo`, `coneGeo`)
// are already Y-axis by default, but LLMs see `*XGeo` / `*ZGeo` and infer a
// matching `*YGeo` sibling. Rather than argue the naming, we accept the
// symmetric form and route it to the base implementation. No behavior change
// for existing code.
export const cylinderYGeo = cylinderGeo;
export const capsuleYGeo = capsuleGeo;
export const coneYGeo = coneGeo;
/**
* Frame-first cylinder. Builds a Y-up cylinder of `height` at the origin,
* orients its axis to `normal`, and translates the center to `center`. Use
* this when the cylinder needs to point along a non-cardinal axis — struts
* inside CSG operands, antennas off a tilted surface, anything where the
* `*XGeo` / `*ZGeo` variants don't fit.
*
* `radiusTop === radiusBottom` for plain tubes; pass different values for a
* tapered/conical body without reaching for `coneGeo`.
*
* The returned geometry has its position pre-baked. You can pass it straight
* to `new THREE.Mesh(...)` without further rotation.
*/
export function cylinderOnAxis(
center: Vec3Tuple,
normal: Vec3Tuple,
radiusBottom: number,
height: number,
options: { radiusTop?: number; segments?: number } = {},
): THREE.CylinderGeometry {
const radiusTop = options.radiusTop ?? radiusBottom;
const segments = options.segments ?? 8;
assertFiniteTriple('cylinderOnAxis center', center);
assertFiniteTriple('cylinderOnAxis normal', normal);
const n = new THREE.Vector3(normal[0], normal[1], normal[2]);
const len = Math.hypot(...normal);
if (len < 1e-6) {
throw new Error(
`cylinderOnAxis: normal must be a non-zero vector (got [${normal.join(',')}]).`,
);
}
// Normalize by a component first so finite vectors cannot overflow lengthSq.
const magnitude = Math.max(...normal.map(Math.abs));
n.set(normal[0] / magnitude, normal[1] / magnitude, normal[2] / magnitude).normalize();
const geo = cylinderGeo(radiusTop, radiusBottom, height, segments);
// Quaternion from Y to normal.
const q = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), n);
geo.applyQuaternion(q);
geo.translate(center[0], center[1], center[2]);
return geo;
}
/**
* Tapered cone helper that exposes the bottom + top radius. The default Y-up
* `coneGeo` is apex-only (top radius locked at 0); for truncated/frustum
* shapes — soda cans, pylon caps, lampshades — pass a non-zero
* `radiusTop`. When `radiusTop === 0` it matches `coneGeo` exactly; when
* `radiusTop === radiusBottom` it matches `cylinderGeo`.
*
* `axis` selects the orientation:
* - `'y'` (default) — apex/cap on +Y, matches `coneGeo`
* - `'x'` — pre-rotated along +X, matches the `coneXGeo` family
* - `'z'` — pre-rotated along +Z
*/
export function taperConeGeo(
radiusBottom: number,
radiusTop: number,
height: number,
axis: 'x' | 'y' | 'z' = 'y',
segments = 8,
): THREE.CylinderGeometry {
if (!['x', 'y', 'z'].includes(axis)) throw new AuthoringDiagnosticError('TAPER_CONE_AXIS');
const geo = cylinderGeo(radiusTop, radiusBottom, height, segments);
if (axis === 'x') geo.rotateZ(-Math.PI / 2);
else if (axis === 'z') geo.rotateX(Math.PI / 2);
return geo;
}
export function torusGeo(
radius: number,
tube: number,
radialSegments = 8,
tubularSegments = 12,
): THREE.TorusGeometry {
assertDimension('torusGeo radius', radius);
assertDimension('torusGeo tube', tube);
assertDimension('torusGeo outer radius', radius + tube);
assertPrimitiveSegments('torusGeo radialSegments', radialSegments, 3);
assertPrimitiveSegments('torusGeo tubularSegments', tubularSegments, 3);
assertPrimitiveGrid('torusGeo', radialSegments, tubularSegments);
return new THREE.TorusGeometry(radius, tube, radialSegments, tubularSegments);
}
export function planeGeo(
width: number,
height: number,
widthSegments = 1,
heightSegments = 1,
): THREE.PlaneGeometry {
assertDimension('planeGeo width', width);
assertDimension('planeGeo height', height);
assertPrimitiveSegments('planeGeo widthSegments', widthSegments, 1);
assertPrimitiveSegments('planeGeo heightSegments', heightSegments, 1);
assertPrimitiveGrid('planeGeo', widthSegments, heightSegments);
return new THREE.PlaneGeometry(width, height, widthSegments, heightSegments);
}
/**
* Flat box sized for surface-attached decals: red stars on fuselages, hull
* numbers, stamps, dome windows on no-texture vehicles. Returns a very thin
* {@link THREE.BoxGeometry} so the decal has depth and is visibly attached
* to its host surface — unlike a bare {@link planeGeo} which renders as a
* disconnected 2-tri quad when it drifts away from a parent mesh.
*
* Always place the returned geometry with `position` + `rotation` on the
* host surface via `createPart`. Keep `depth` as small as 0.005 for
* paper-thin decals, or bump to 0.05 for raised plates / badges.
*
* ```ts
* // Red star on the fuselage side.
* const star = decalBox(0.18, 0.18, 0.01);
* createPart('Mesh_StarPort', star, gameMaterial(0xc61f2a), {
* position: [0.4, 0.6, 0.41], // on +Z fuselage surface
* rotation: [0, 0, 0],
* parent: fuselage,
* });
* ```
*/
export function decalBox(width: number, height: number, depth: number = 0.01): THREE.BoxGeometry {
assertDimension('decalBox width', width);
assertDimension('decalBox height', height);
assertDimension('decalBox depth', depth, true);
const d = Math.max(depth, 0.002);
return new THREE.BoxGeometry(width, height, d);
}
// =============================================================================
// Billboard / imposter primitives
// =============================================================================
export interface FoliageCardOptions {
/** Quad width in world units. */
width?: number;
/** Quad height in world units. */
height?: number;
/**
* Vertical pivot as a fraction of height: 0 = bottom, 0.5 = center, 1 = top.
* Foliage usually wants 0 so the card plants on the ground.
*/
yPivot?: number;
}
/**
* Double-sided quad for foliage / vegetation cards. Y-up facing +Z by default.
* The pivot is placed at `yPivot * height` below the quad center — set 0 to
* have the card root on the ground plane.
*
* Use with an alpha-tested material for leaves and billboard plants.
*/
function validateCardFrame(name: string, width: number, height: number, yPivot: number): void {
assertDimension(`${name} width`, width);
assertDimension(`${name} height`, height);
const shift = height * (0.5 - yPivot);
if (
!Number.isFinite(yPivot) ||
![shift - Math.fround(height / 2), shift + Math.fround(height / 2)].every((value) =>
Number.isFinite(Math.fround(value)),
)
)
throw new RangeError(`${name} yPivot must produce finite Float32 card coordinates.`);
}
export function foliageCardGeo(opts: FoliageCardOptions = {}): THREE.PlaneGeometry {
const w = opts.width ?? 1;
const h = opts.height ?? 1;
const yPivot = opts.yPivot ?? 0;
validateCardFrame('foliageCardGeo', w, h, yPivot);
const geom = new THREE.PlaneGeometry(w, h);
// Shift so the pivot offset becomes the local origin.
geom.translate(0, h * (0.5 - yPivot), 0);
geom.userData['kilnGeometryRole'] = 'foliageCard';
return geom;
}
export interface CrossedQuadsOptions {
width?: number;
height?: number;
/** Number of intersecting planes. 2 = X-cross, 3 = triple-star. Default 2. */
planes?: 2 | 3;
/** Y pivot fraction of height (see foliageCardGeo). Default 0. */
yPivot?: number;
}
/**
* Two or three planes intersecting along the Y axis — the classic "bush" or
* "cross-billboard" near-field vegetation primitive. Cheaper than real
* geometry, denser-looking than a single foliage card from any angle.
*/
export function crossedQuadsGeo(opts: CrossedQuadsOptions = {}): THREE.BufferGeometry {
const w = opts.width ?? 1;
const h = opts.height ?? 1;
const planes = opts.planes ?? 2;
const yPivot = opts.yPivot ?? 0;
validateCardFrame('crossedQuadsGeo', w, h, yPivot);
if (planes !== 2 && planes !== 3) throw new RangeError('crossedQuadsGeo planes must be 2 or 3.');
const geometries: THREE.PlaneGeometry[] = [];
for (let i = 0; i < planes; i++) {
const angle = (i / planes) * Math.PI;
const quad = new THREE.PlaneGeometry(w, h);
quad.translate(0, h * (0.5 - yPivot), 0);
quad.rotateY(angle);
geometries.push(quad);
}
// Merge into one BufferGeometry — deterministic + cheaper at draw time.
const out = new THREE.BufferGeometry();
const posCount = geometries.reduce((sum, g) => sum + (g.attributes.position?.count ?? 0), 0);
const positions = new Float32Array(posCount * 3);
const normals = new Float32Array(posCount * 3);
const uvs = new Float32Array(posCount * 2);
const indices: number[] = [];
let vOffset = 0;
for (const g of geometries) {
const p = g.attributes.position!;
const n = g.attributes.normal!;
const uv = g.attributes.uv!;
for (let i = 0; i < p.count; i++) {
positions[(vOffset + i) * 3] = p.getX(i);
positions[(vOffset + i) * 3 + 1] = p.getY(i);
positions[(vOffset + i) * 3 + 2] = p.getZ(i);
normals[(vOffset + i) * 3] = n.getX(i);
normals[(vOffset + i) * 3 + 1] = n.getY(i);
normals[(vOffset + i) * 3 + 2] = n.getZ(i);
uvs[(vOffset + i) * 2] = uv.getX(i);
uvs[(vOffset + i) * 2 + 1] = uv.getY(i);
}
const idx = g.index!;
for (let i = 0; i < idx.count; i++) {
indices.push(idx.getX(i) + vOffset);
}
vOffset += p.count;
}
out.setAttribute('position', new THREE.BufferAttribute(positions, 3));
out.setAttribute('normal', new THREE.BufferAttribute(normals, 3));
out.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
out.setIndex(indices);
out.userData['kilnGeometryRole'] = 'foliageCard';
return out;
}
export interface OctaGridPlaneOptions {
/** Atlas tile grid X. */
tilesX: number;
/** Atlas tile grid Y. */
tilesY: number;
/** Quad width in world units. Default 1. */
width?: number;
/** Quad height in world units. Default 1. */
height?: number;
/** 0 = bottom pivot, 0.5 = center, 1 = top. Default 0. */
yPivot?: number;
}
/**
* Atlas-ready billboard quad — same geometry as foliageCardGeo but the UV
* rect is [0, 1/tilesX]×[1 - 1/tilesY, 1] so a shader using viewDir->tileIdx
* can offset the UVs per-instance to sample the right imposter tile.
*
* The returned geometry has its UVs pre-scaled to cover exactly one tile.
* The shader (TIJ billboard material) is expected to add (tileX/tilesX,
* tileY/tilesY) to each vertex's UV at draw time.
*/
export function octaGridPlane(opts: OctaGridPlaneOptions): THREE.PlaneGeometry {
for (const key of ['tilesX', 'tilesY'] as const) {
if (!Number.isSafeInteger(opts[key]) || opts[key] <= 0) {
throw new RangeError(`octaGridPlane: ${key} must be a positive finite safe integer.`);
}
}
const w = opts.width ?? 1;
const h = opts.height ?? 1;
const yPivot = opts.yPivot ?? 0;
validateCardFrame('octaGridPlane', w, h, yPivot);
const geom = new THREE.PlaneGeometry(w, h);
geom.translate(0, h * (0.5 - yPivot), 0);
// Scale UVs so the quad covers one tile-sized rect in the top-left corner.
const uv = geom.attributes.uv!;
const du = 1 / opts.tilesX;
const dv = 1 / opts.tilesY;
for (let i = 0; i < uv.count; i++) {
uv.setX(i, uv.getX(i) * du);
// Top row — start at 1 - dv so the default samples the top-left tile.
uv.setY(i, 1 - dv + uv.getY(i) * dv);
}
uv.needsUpdate = true;
return geom;
}
export interface WingGeometryOptions {
span?: number;
rootChord?: number;
tipChord?: number;
sweep?: number;
thickness?: number;
dihedral?: number;
}
/**
* Trapezoid aircraft wing panel.
*
* Coordinate contract: +X forward, +Y up, +Z right. The root edge sits at
* local Z=0 and the panel extends toward +Z.
*
* **Parameter units (READ THIS — these are NOT angles):**
* - `sweep` is the **X-displacement of the tip leading edge in world units**
* (positive = tip moves aft along -X). NOT an angle in degrees/radians.
* - `dihedral` is the **Y-displacement of the tip in world units**
* (positive = tip rises). NOT an angle. For most aircraft you want a
* small value like 0.05–0.1 — a value of 1 with span=2 gives a 45°
* gull-wing, almost certainly wrong unless explicitly designing one.
* - `span` is wing length in world units (root to tip).
* - `rootChord` / `tipChord` / `thickness` are all world units.
*
* Quick reference: a real-aircraft-looking wing has dihedral roughly 2–7%
* of span (e.g. span=4, dihedral=0.1 to 0.25).
*/
export function wingGeo(options: WingGeometryOptions = {}): THREE.BufferGeometry {
const span = options.span ?? 1;
const rootChord = options.rootChord ?? 0.6;
const tipChord = options.tipChord ?? rootChord * 0.5;
const sweep = options.sweep ?? 0;
const thickness = options.thickness ?? 0.04;
const dihedral = options.dihedral ?? 0;
for (const [name, value] of Object.entries({ span, rootChord, thickness }))
assertDimension(`wingGeo ${name}`, value);
assertDimension('wingGeo tipChord', tipChord, true);
for (const [name, value] of Object.entries({ sweep, dihedral }))
if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value)))
throw new RangeError(`wingGeo ${name} must be finite and Float32-representable.`);
const rootLead = rootChord / 2;
const rootTrail = -rootChord / 2;
const tipLead = rootLead - sweep;
const tipTrail = tipLead - tipChord;
const halfThickness = thickness / 2;
const vertices = new Float32Array([
rootLead,
halfThickness,
0,
rootTrail,
halfThickness,
0,
tipLead,
dihedral + halfThickness,
span,
tipTrail,
dihedral + halfThickness,
span,
rootLead,
-halfThickness,
0,
rootTrail,
-halfThickness,
0,
tipLead,
dihedral - halfThickness,
span,
tipTrail,
dihedral - halfThickness,
span,
]);
if (!vertices.every(Number.isFinite))
throw new RangeError('wingGeo dimensions and offsets produce nonfinite Float32 vertices.');
const indices = [
0,
3,
2,
0,
1,
3, // top
4,
6,
7,
4,
7,
5, // bottom
0,
2,
6,
0,
6,
4, // leading edge
1,
5,
7,
1,
7,
3, // trailing edge
0,
4,
5,
0,
5,
1, // root cap
2,
3,
7,
2,
7,
6, // tip cap
];
const geo = new THREE.BufferGeometry();
geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
// A zero tip chord is a triangular wing: omit collapsed faces at the tip.
geo.setIndex(
tipChord === 0
? [0, 1, 3, 4, 7, 5, 0, 2, 6, 0, 6, 4, 1, 5, 7, 1, 7, 3, 0, 4, 5, 0, 5, 1]
: indices,
);
geo.computeVertexNormals();
return geo;
}
export interface WingPairOptions extends WingGeometryOptions {
rootX?: number;
rootY?: number;
/** Fuselage half-width / root offset. Roots attach at +/-rootZ. */
rootZ: number;
parent?: THREE.Object3D;
}
export function createWingPair(
name: string,
material: THREE.Material,
options: WingPairOptions,
): { right: THREE.Object3D; left: THREE.Object3D } {
const { parent, rootX = 0, rootY = 0, rootZ, ...wingOptions } = options;
assertFiniteTriple('createWingPair root position', [rootX, rootY, rootZ]);
const rightGeo = wingGeo(wingOptions);
const leftGeo = wingGeo(wingOptions);
leftGeo.scale(1, 1, -1);
// A baked reflection reverses orientation. Reverse every triangle before
// recomputing normals so single-sided rendering and exported solids agree.
const indices = leftGeo.getIndex()!;
for (let i = 0; i < indices.count; i += 3) {
const second = indices.getX(i + 1);
indices.setX(i + 1, indices.getX(i + 2));
indices.setX(i + 2, second);
}
indices.needsUpdate = true;
leftGeo.computeVertexNormals();
return {
right: createPart(`${name}Right`, rightGeo, material, {
position: [rootX, rootY, rootZ],
parent,
}),
left: createPart(`${name}Left`, leftGeo, material, {
position: [rootX, rootY, -rootZ],
parent,
}),
};
}
export interface BeamBetweenOptions {
segments?: number;
parent?: THREE.Object3D;
}
export function beamBetween(
name: string,
start: Vec3Tuple,
end: Vec3Tuple,
radius: number,
material: THREE.Material,
options: BeamBetweenOptions = {},
): THREE.Object3D {
const a = new THREE.Vector3(...start);
const b = new THREE.Vector3(...end);
const direction = b.clone().sub(a);
const length = direction.length();
if (length <= 1e-4) {
throw new Error(
`beamBetween("${name}"): start and end must be different points (got start=[${start.join(',')}], end=[${end.join(',')}], delta=${length.toExponential(2)}). Pick two distinct endpoints or switch to cylinderGeo with an explicit length + position.`,
);
}
const mesh = new THREE.Mesh(cylinderGeo(radius, radius, length, options.segments ?? 8), material);
mesh.name = `Mesh_${name}`;
mesh.position.copy(a.add(b).multiplyScalar(0.5));
mesh.quaternion.setFromUnitVectors(new THREE.Vector3(0, 1, 0), direction.normalize());
if (options.parent) options.parent.add(mesh);
return mesh;
}
/**
* Align world bounding boxes: translate `part` by the minimal
* world-space vector that closes the gap between its bounding box and the
* host's, plus a small `overlap` along the dominant gap axis (or the forced
* `axis`). The axis selects the overlap bias, not a movement constraint: gaps
* on other axes are also closed. AABB overlap does not prove surface contact.
*
* If the boxes already touch or overlap, the part is left in place.
* Returns `part` for chaining.
*/
export function snapTo(
part: THREE.Object3D,
host: THREE.Object3D,
options: { axis?: 'x' | 'y' | 'z'; overlap?: number } = {},
): THREE.Object3D {
const overlap = options.overlap ?? 0.02;
// Boxes in world space (works mid-build; matrices may be stale otherwise).
part.updateWorldMatrix(true, true);
host.updateWorldMatrix(true, true);
const a = new THREE.Box3().setFromObject(part);
const b = new THREE.Box3().setFromObject(host);
if (a.isEmpty() || b.isEmpty()) return part;
const delta = new THREE.Vector3();
for (const axis of ['x', 'y', 'z'] as const) {
if (a.min[axis] > b.max[axis]) delta[axis] = b.max[axis] - a.min[axis];
else if (a.max[axis] < b.min[axis]) delta[axis] = b.min[axis] - a.max[axis];
}
if (delta.lengthSq() === 0) return part; // AABBs already touch or overlap.
const dominant =
options.axis ??
(['x', 'y', 'z'] as const).reduce<'x' | 'y' | 'z'>(
(d, axis) => (Math.abs(delta[axis]) > Math.abs(delta[d]) ? axis : d),
'x',
);
if (delta[dominant] !== 0) delta[dominant] += Math.sign(delta[dominant]) * overlap;
else delta[dominant] = -overlap; // forced axis had no gap — bias into the host
// Convert the world delta into the part's parent space (handles rotated or
// scaled ancestors) by mapping two world points.
const parent = part.parent;
if (parent) {
const p0 = new THREE.Vector3();
part.getWorldPosition(p0);
const p1 = p0.clone().add(delta);
const l0 = parent.worldToLocal(p0.clone());
const l1 = parent.worldToLocal(p1.clone());
part.position.add(l1.sub(l0));
} else {
part.position.add(delta);
}
part.updateMatrixWorld(true);
return part;
}
export interface LadderOptions {
bottom: Vec3Tuple;
top: Vec3Tuple;
material: THREE.Material;
width?: number;
rungCount?: number;
railRadius?: number;
rungRadius?: number;
segments?: number;
/** Preferred parent-space width basis, projected perpendicular to the endpoints. */
widthAxis?: 'x' | 'z';
/** Explicit parent-space width direction; zero or parallel directions are rejected. */
widthDirection?: Vec3Tuple;
parent?: THREE.Object3D;
}
export interface LadderResult {
/** Root at bottom in parent coordinates; child placements are root-local. */
root: THREE.Object3D;
leftRail: THREE.Object3D;
rightRail: THREE.Object3D;
rungs: THREE.Object3D[];
}
export function createLadder(name: string, options: LadderOptions): LadderResult {
const {
bottom,
top,
material,
width = 0.42,
rungCount = 6,
railRadius = 0.025,
rungRadius = 0.02,
segments = 6,
widthAxis = 'x',
widthDirection,
parent,
} = options;
assertFiniteTriple('createLadder bottom', bottom);
assertFiniteTriple('createLadder top', top);
for (const [key, value] of Object.entries({ width, railRadius, rungRadius }))
assertDimension(`createLadder ${key}`, value);
assertPrimitiveSegments('createLadder segments', segments, 3);
if (
!Number.isSafeInteger(rungCount) ||
rungCount < 0 ||
rungCount > GEOMETRY_ALLOCATION_LIMITS.repeatedMeshes
)
throw new RangeError('createLadder rungCount must be an integer from 0 to 10000.');
if (widthAxis !== 'x' && widthAxis !== 'z')
throw new RangeError('createLadder widthAxis must be x or z.');
const bottomVec = new THREE.Vector3();
const topVec = new THREE.Vector3(...top).sub(new THREE.Vector3(...bottom));
const length = Math.hypot(topVec.x, topVec.y, topVec.z);
assertDimension('createLadder endpoint distance', length);
if (length <= 1e-4)
throw new RangeError('createLadder endpoints must be different by more than 1e-4.');
const along = topVec.clone().divideScalar(length);
if (widthDirection !== undefined)
assertFiniteTriple('createLadder widthDirection', widthDirection);
let across = widthDirection
? new THREE.Vector3(...widthDirection)
: widthAxis === 'x'
? new THREE.Vector3(1, 0, 0)
: new THREE.Vector3(0, 0, 1);
const largest = Math.max(Math.abs(across.x), Math.abs(across.y), Math.abs(across.z));
if (!largest) throw new RangeError('createLadder widthDirection must be nonzero.');
across.divideScalar(largest).normalize();
across.addScaledVector(along, -across.dot(along));
if (across.lengthSq() < 1e-12) {
if (widthDirection)
throw new RangeError('createLadder widthDirection must not be parallel to the endpoints.');
// Select the least-aligned canonical basis for a well-conditioned projection.
const axes = [
new THREE.Vector3(1, 0, 0),
new THREE.Vector3(0, 1, 0),
new THREE.Vector3(0, 0, 1),
];
across = axes.reduce((best, axis) =>
Math.abs(axis.dot(along)) < Math.abs(best.dot(along)) ? axis : best,
);
across.addScaledVector(along, -across.dot(along));
}
across.normalize();
const offset = across.clone().multiplyScalar(width / 2);
const root = new THREE.Object3D();
root.name = name;
root.position.set(...bottom);
const rotation = new THREE.Quaternion()
.setFromRotationMatrix(
new THREE.Matrix4().makeBasis(across, along, across.clone().cross(along)),
)
.toArray();
stampSemanticMetadataV1(root, {
roles: ['ladder'],
frames: [
{ id: 'bottom', translation: [0, 0, 0], rotation },
{ id: 'top', translation: vectorToTuple(topVec), rotation },
],
sockets: ['bottom', 'top'].map((id) => ({
id,
type: 'ladder-end',
frame: id,
compatibleTypes: ['ladder-end'],
})),
});
const leftBottom = bottomVec.clone().sub(offset);
const leftTop = topVec.clone().sub(offset);
const rightBottom = bottomVec.clone().add(offset);
const rightTop = topVec.clone().add(offset);
const leftRail = beamBetween(
`${name}LeftRail`,
vectorToTuple(leftBottom),
vectorToTuple(leftTop),
railRadius,
material,
{ parent: root, segments },
);
const rightRail = beamBetween(
`${name}RightRail`,
vectorToTuple(rightBottom),
vectorToTuple(rightTop),
railRadius,
material,
{ parent: root, segments },
);
const rungs: THREE.Object3D[] = [];
for (let i = 0; i < rungCount; i++) {
const t = (i + 1) / (rungCount + 1);
const center = bottomVec.clone().lerp(topVec, t);
rungs.push(
beamBetween(
`${name}Rung${i + 1}`,
vectorToTuple(center.clone().sub(offset)),
vectorToTuple(center.clone().add(offset)),
rungRadius,
material,
{ parent: root, segments },
),
);
}
stampSemanticMetadataV1(leftRail, { roles: ['ladder.rail', 'ladder.rail.left'] });
stampSemanticMetadataV1(rightRail, { roles: ['ladder.rail', 'ladder.rail.right'] });
rungs.forEach((rung, index) => {
stampSemanticMetadataV1(rung, { roles: ['ladder.rung', `ladder.rung.${index + 1}`] });
});
if (parent) parent.add(root);
return { root, leftRail, rightRail, rungs };
}
// =============================================================================
// Building / architecture helpers
// =============================================================================
//
// Enterable buildings are HOLLOW shells: thin walls around real interior space,
// real doorway gaps, a separable roof. These helpers make that correct-by-
// construction so the agent cannot accidentally fill the volume, forget the
// doorway, or mirror the roof slopes the wrong way. Openings are composed from
// box segments (jambs + lintel + sill), never CSG — solid opaque overlaps are
// robust where thin boolean cutters are fragile.
export interface WallOpening {
/** 'door' reaches the floor; 'window' is inset at `sill` height. */
kind?: 'door' | 'window';
/** Center of the opening along the wall length axis (0 = centered). */
offset?: number;
/** Opening width along the wall length axis. */
width?: number;
/** Opening height. */
height?: number;
/** Window sill height above the wall base (ignored for doors). */
sill?: number;
}
export interface WallWithOpeningOptions {
/** Wall length along its run axis. */
length: number;
/** Wall height (Y). Base sits at local Y=0. */
height: number;
/** Wall thickness along the perpendicular horizontal axis. */
thickness: number;
/** Which horizontal axis the wall runs along. Default 'z'. */
axis?: 'x' | 'z';
/** A single door/window cut. Mutually exclusive with `openings`. */
opening?: WallOpening;
/** Multiple rectangular cuts, including vertically stacked windows.
* Cuts may touch but must not overlap and must fit inside the wall sides/top. */
openings?: readonly WallOpening[];
parent?: THREE.Object3D;
}
/**
* A wall with rectangular door/window cuts, composed from solid box segments.
* Invalid, overlapping or out-of-bound cuts throw; they are never clipped.
* Runs along `axis`, base at local Y=0, centered on the
* length axis. Returns the wall container so the caller can position it.
*/
export function wallWithOpening(
name: string,
material: THREE.Material,
options: WallWithOpeningOptions,
): THREE.Object3D {
const { length, height, thickness, axis = 'z', opening, openings, parent } = options;
if (opening && openings)
throw new TypeError('wallWithOpening: use opening or openings, not both.');
const built = buildWallPanels(length, height, thickness, openings ?? (opening ? [opening] : []));
const group = new THREE.Object3D();
group.name = name;
const panel = (
suffix: string,
lenStart: number,
lenEnd: number,
yLo: number,
yHi: number,
): void => {
const segLen = lenEnd - lenStart;
const segH = yHi - yLo;
if (segLen <= 0 || segH <= 0) return;
const lenC = (lenStart + lenEnd) / 2;
const yC = (yLo + yHi) / 2;
const geo = axis === 'z' ? boxGeo(thickness, segH, segLen) : boxGeo(segLen, segH, thickness);
const pos: [number, number, number] = axis === 'z' ? [0, yC, lenC] : [lenC, yC, 0];
createPart(`${name}${suffix}`, geo, material, { position: pos, parent: group });
};
for (const segment of built.panels) {
panel(segment.suffix, segment.left, segment.right, segment.bottom, segment.top);
}
if (parent) parent.add(group);
return group;
}
export interface RoomOpening extends WallOpening {
/** Which wall the opening cuts. `front` faces +X. */
wall: 'front' | 'back' | 'left' | 'right';
}
export interface RoomOptions {
/** Side-to-side extent along Z. */
width?: number;
/** Front-to-back extent along X (front faces +X). */
depth?: number;
/** Wall height (Y). */
height?: number;
wallThickness?: number;
/** Lay a floor slab. Default true. */
floor?: boolean;
floorThickness?: number;
/** Per-wall openings. Defaults to a centered door on the front wall, so the
* room is ENTERABLE by default. */
openings?: RoomOpening[];
parent?: THREE.Object3D;
}
/**
* A hollow, enterable room: four thin walls + a floor, sized so a humanoid fits
* (defaults: 2.8m ceiling, a centered 1.1×2.1m front door). The keystone of an
* architecture asset — the agent builds onto/around it (roof via
* {@link createRoofPlanes}, fixtures as separate parts) but cannot ship a solid
* block or a sealed box. `front` faces +X; the floor top sits at the ground.
*/
export function room(
name: string,
material: THREE.Material,
options: RoomOptions = {},
): {
root: THREE.Object3D;
walls: Record<'front' | 'back' | 'left' | 'right', THREE.Object3D>;
floor: THREE.Object3D | null;
} {
const {
width = 4,
depth = 4,
height = 2.8,
wallThickness = 0.15,
floor = true,
floorThickness = 0.1,
parent,
} = options;
const openings = options.openings ?? [{ wall: 'front', kind: 'door' }];
const root = new THREE.Object3D();
root.name = name;
const wall = (
suffix: string,
len: number,
axis: 'x' | 'z',
pos: [number, number, number],
which: RoomOpening['wall'],
): THREE.Object3D => {
const w = wallWithOpening(`${name}_Wall${suffix}`, material, {
length: len,
height,
thickness: wallThickness,
axis,
openings: openings.filter((op) => op.wall === which),
parent: root,
});
w.position.set(...pos);
return w;
};
const walls = {
front: wall('Front', width, 'z', [depth / 2, 0, 0], 'front'),
back: wall('Back', width, 'z', [-depth / 2, 0, 0], 'back'),
left: wall('Left', depth, 'x', [0, 0, -width / 2], 'left'),
right: wall('Right', depth, 'x', [0, 0, width / 2], 'right'),
};
let floorObj: THREE.Object3D | null = null;
if (floor) {
floorObj = createPart(`${name}_Floor`, boxGeo(depth, floorThickness, width), material, {
position: [0, -floorThickness / 2, 0],
parent: root,
});
}
if (parent) parent.add(root);
return { root, walls, floor: floorObj };
}
export interface StairsOptions {
/** Number of steps. Default 8. */
steps?: number;
/** Total vertical climb. */
totalRise: number;
/** Total horizontal run along `axis`. */
totalRun: number;
/** Tread width along the perpendicular horizontal axis. */
width: number;
/** Direction the flight climbs toward. Default 'x'. */
axis?: 'x' | 'z';
treadThickness?: number;
/** Add a vertical riser face under each tread. Default true. */
riser?: boolean;
parent?: THREE.Object3D;
}
/**
* A straight flight of stairs: box treads (with optional risers) climbing
* `totalRise` over `totalRun` from local origin along `axis`. Signed rise/run
* support ascending or descending flights in either direction. Steps are named
* `Step_1..N` for engine use.
*/
export function createStairs(
name: string,
material: THREE.Material,
options: StairsOptions,
): { root: THREE.Object3D; steps: THREE.Object3D[] } {
const {
steps = 8,
totalRise,
totalRun,
width,
axis = 'x',
treadThickness = 0.08,
riser = true,
parent,
} = options;
if (
!Number.isSafeInteger(steps) ||
steps < 1 ||
steps > GEOMETRY_ALLOCATION_LIMITS.repeatedMeshes
) {
throw new RangeError(
`createStairs("${name}"): steps must be >= 1, <= 10000 and a finite safe integer (got ${steps}).`,
);
}
assertDimension('createStairs width', width);
assertDimension('createStairs treadThickness', treadThickness);
if (!Number.isFinite(totalRise) || !Number.isFinite(totalRun))
throw new RangeError('createStairs totalRise and totalRun must be finite.');
if (axis !== 'x' && axis !== 'z') throw new RangeError('createStairs axis must be x or z.');
if (Math.abs(totalRise) < 1e-4 || Math.abs(totalRun) < 1e-4) {
throw new Error(
`createStairs("${name}"): totalRise and totalRun must be non-zero (got rise=${totalRise}, run=${totalRun}).`,
);
}
const root = new THREE.Object3D();
root.name = name;
const stepRise = totalRise / steps;
const stepRun = totalRun / steps;
const stepList: THREE.Object3D[] = [];
for (let i = 0; i < steps; i++) {
const topY = (i + 1) * stepRise;
const alongC = (i + 0.5) * stepRun;
const treadGeo =
axis === 'x'
? boxGeo(Math.abs(stepRun), treadThickness, width)
: boxGeo(width, treadThickness, Math.abs(stepRun));
const treadPos: [number, number, number] =
axis === 'x'
? [alongC, topY - treadThickness / 2, 0]
: [0, topY - treadThickness / 2, alongC];
stepList.push(
createPart(`${name}Step${i + 1}`, treadGeo, material, { position: treadPos, parent: root }),
);
if (riser) {
const front = i * stepRun;
const riserGeo =
axis === 'x'
? boxGeo(treadThickness, Math.abs(stepRise), width)
: boxGeo(width, Math.abs(stepRise), treadThickness);
const riserPos: [number, number, number] =
axis === 'x'
? [front + (Math.sign(stepRun) * treadThickness) / 2, topY - stepRise / 2, 0]
: [0, topY - stepRise / 2, front + (Math.sign(stepRun) * treadThickness) / 2];
createPart(`${name}Riser${i + 1}`, riserGeo, material, { position: riserPos, parent: root });
}
}
if (parent) parent.add(root);
return { root, steps: stepList };
}
// =============================================================================
// Materials
// =============================================================================
/**
* Reject anything that is not a colour where a colour is expected.
*
* Every constructor here takes `(color, options)`, and a model that has met a
* different engine reaches for `gameMaterial({ color, roughness, metalness })`
* instead. That is not an error in three.js: `Color.set` ignores a plain object
* and leaves the colour at its default white, the options argument is absent so
* the material also takes default roughness and metalness, and the program runs
* to completion. What comes back is a white plastic part in the middle of a
* correctly-painted asset, which reads as the model having chosen it.
*
* An air-defence radar in `examples/` had every steel fitting on the vehicle
* blown out this way, and the header comment it wrote about the finish described
* a material that was never applied. So this fails closed, and says which shape
* it wanted, because the whole point of the catalog is that the API a model
* half-remembers is not the API it gets to use.
*/
function requireColor(color: unknown, fn: string): void {
if (typeof color === 'number' || typeof color === 'string') return;
const got =
color && typeof color === 'object'
? `an object with keys [${Object.keys(color as object).join(', ')}]`
: String(color);
throw new AuthoringDiagnosticError(
'MATERIAL_COLOR_ARGUMENT',
`${fn}(color, options?): color must be a hex number like 0x8c4a32 or a CSS string, got ${got}. ` +
`Material settings go in the SECOND argument: ${fn}(0x8c4a32, { roughness: 0.5, metalness: 0.9 }).`,
);
}
export function gameMaterial(
color: number | string,
options: {
metalness?: number;
roughness?: number;
emissive?: number | string;
emissiveIntensity?: number;
flatShading?: boolean;
/** Stable name written to the exported glTF material. */
name?: string;
} = {},
): THREE.MeshStandardMaterial {
requireColor(color, 'gameMaterial');
const material = new THREE.MeshStandardMaterial({
color,
metalness: options.metalness ?? 0,
roughness: options.roughness ?? 0.8,
emissive: options.emissive ?? 0x000000,
emissiveIntensity: options.emissiveIntensity ?? 1,
flatShading: options.flatShading ?? true,
});
if (options.name !== undefined) material.name = assertMaterialName(options.name, 'gameMaterial');
return material;
}
export function basicMaterial(
color: number | string,
options: { transparent?: boolean; opacity?: number; name?: string } = {},
): THREE.MeshBasicMaterial {
requireColor(color, 'basicMaterial');
const material = new THREE.MeshBasicMaterial({
color,
transparent: options.transparent ?? false,
opacity: options.opacity ?? 1,
});
if (options.name !== undefined) material.name = assertMaterialName(options.name, 'basicMaterial');
return material;
}
export function glassMaterial(
color: number | string,
options: { opacity?: number; roughness?: number; metalness?: number; name?: string } = {},
): THREE.MeshStandardMaterial {
requireColor(color, 'glassMaterial');
const material = new THREE.MeshStandardMaterial({
color,
transparent: true,
opacity: options.opacity ?? 0.35,
roughness: options.roughness ?? 0.1,
metalness: options.metalness ?? 0,
side: THREE.DoubleSide,
});
if (options.name !== undefined) material.name = assertMaterialName(options.name, 'glassMaterial');
return material;
}
export function lambertMaterial(
color: number | string,
options: { flatShading?: boolean; emissive?: number | string; name?: string } = {},
): THREE.MeshLambertMaterial {
requireColor(color, 'lambertMaterial');
const material = new THREE.MeshLambertMaterial({
color,
flatShading: options.flatShading ?? true,
emissive: options.emissive ?? 0x000000,
});
if (options.name !== undefined)
material.name = assertMaterialName(options.name, 'lambertMaterial');
return material;
}
// =============================================================================
// Animation Helpers
// =============================================================================
/**
* Keyframe interpolation mode.
* - LINEAR: default, straight between keyframes (rotations along the shortest arc).
* - STEP: discrete, hold value until next keyframe (good for robotic/mechanical motion).
* - CUBICSPLINE: one smooth curve through every key. Tangents are the slopes PCHIP computes:
* monotone, so the curve never overshoots a key, and zero where the value holds or turns.
* Two keys give a straight line.
* - EASE_IN, EASE_OUT, EASE_IN_OUT: each segment between consecutive keys starts at rest (s^2),
* ends at rest (2s - s^2) or both (3s^2 - 2s^3). One key pair makes a smooth swing.
* The last four export as standard glTF CUBICSPLINE samplers with the tangents baked in, and
* need at least two keys. See `animation-spline.ts`.
*/
export type TrackInterpolation = 'LINEAR' | 'STEP' | CubicInterpolation;
const TRACK_INTERPOLATIONS: readonly TrackInterpolation[] = [
'LINEAR',
'STEP',
...CUBIC_INTERPOLATIONS,
];
function threeInterpolation(mode?: TrackInterpolation): THREE.InterpolationModes {
if (mode !== undefined && !TRACK_INTERPOLATIONS.includes(mode)) {
throw new Error(`Animation interpolation must be one of ${TRACK_INTERPOLATIONS.join(', ')}.`);
}
return mode === 'STEP' ? THREE.InterpolateDiscrete : THREE.InterpolateLinear;
}
/** A track of `Type` with `interpolation`; the cubic modes store the glTF CUBICSPLINE layout. */
function interpolatedTrack<T extends THREE.KeyframeTrack>(
Type: new (
name: string,
times: number[],
values: number[],
interpolation?: THREE.InterpolationModes,
) => T,
name: string,
times: number[],
values: number[],
interpolation: TrackInterpolation | undefined,
): T {
if (!isCubicInterpolation(interpolation))
return new Type(name, times, values, threeInterpolation(interpolation));
const quaternion = (Type as unknown) === THREE.QuaternionKeyframeTrack;
return useCubicSpline(
new Type(
name,
times,
cubicSplineValues(times, values, quaternion ? 4 : 3, interpolation, quaternion),
),
);
}
function animationNumber(value: unknown, label: string): asserts value is number {
if (
typeof value !== 'number' ||
!Number.isFinite(value) ||
!Number.isFinite(Math.fround(value))
) {
throw new Error(`${label} must be finite and representable as float32.`);
}
}
function animationTarget(name: unknown): asserts name is string {
if (
typeof name !== 'string' ||
!name.trim() ||
name !== name.trim() ||
/[.[\]:/\\]/.test(name) ||
Array.from(name).some(
(character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
)
) {
throw new Error(
'Animation target must be an exact nonempty node name, without binding paths or property syntax.',
);
}
}
function animationVector(value: unknown, label: string): asserts value is [number, number, number] {
if (!Array.isArray(value) || value.length !== 3) {
throw new Error(`${label} must contain exactly three finite components.`);
}
for (const component of value) animationNumber(component, label);
}
function animationTimes(times: ArrayLike<number>, label: string): void {
if (times.length === 0) throw new Error(`${label} requires at least one keyframe time.`);
let previous = -Infinity;
for (let i = 0; i < times.length; i++) {
const time = times[i];
animationNumber(time, `${label} time ${i}`);
const stored = Math.fround(time);
if (time < 0 || stored <= previous) {
throw new Error(
`${label} times must be nonnegative and strictly increasing after float32 storage.`,
);
}
previous = stored;
}
}
function animationKeys(
target: string,
frames: Array<{ time: number }>,
channel: 'rotation' | 'position' | 'scale',
interpolation?: TrackInterpolation,
): void {
animationTarget(target);
threeInterpolation(interpolation);
if (!Array.isArray(frames) || frames.length === 0) {
throw new Error(`${channel}Track requires at least one keyframe.`);
}
if (isCubicInterpolation(interpolation) && frames.length < 2) {
throw new Error(
`${channel}Track ${interpolation} needs at least two keyframes; a single key is a constant pose, so use LINEAR.`,
);
}
for (const [i, frame] of frames.entries()) {
if (!frame || typeof frame !== 'object')
throw new Error(`${channel}Track keyframe ${i} must be an object.`);
animationVector(
(frame as unknown as Record<string, unknown>)[channel],
`${channel}Track ${channel} ${i}`,
);
}
animationTimes(
frames.map((frame) => frame.time),
`${channel}Track`,
);
}
/**
* Absolute local rotation: XYZ Euler angles in degrees, converted to unit quaternions.
* LINEAR uses shortest-arc quaternion interpolation, not linear Euler angles; the cubic modes
* and eases also take the shortest arc between keys. A two-key 0-to-360 degree track is
* stationary; use intermediate rotations (as spinAnimation does).
* Times are nonnegative seconds, strictly increasing after float32 storage.
* The exact target node must exist in the authored scene; this constructor has no scene.
*/
export function rotationTrack(
jointName: string,
keyframes: Array<{ time: number; rotation: [number, number, number] }>,
interpolation?: TrackInterpolation,
): THREE.QuaternionKeyframeTrack {
animationKeys(jointName, keyframes, 'rotation', interpolation);
const times: number[] = [];
const values: number[] = [];
const euler = new THREE.Euler();
const quat = new THREE.Quaternion();
for (const kf of keyframes) {
times.push(kf.time);
euler.set(
THREE.MathUtils.degToRad(kf.rotation[0]),
THREE.MathUtils.degToRad(kf.rotation[1]),
THREE.MathUtils.degToRad(kf.rotation[2]),
);
quat.setFromEuler(euler);
values.push(quat.x, quat.y, quat.z, quat.w);
}
return interpolatedTrack(
THREE.QuaternionKeyframeTrack,
`${jointName}.quaternion`,
times,
values,
interpolation,
);
}
/** Absolute parent-local positions in scene units. Times are nonnegative seconds. */
export function positionTrack(
jointName: string,
keyframes: Array<{ time: number; position: [number, number, number] }>,
interpolation?: TrackInterpolation,
): THREE.VectorKeyframeTrack {
animationKeys(jointName, keyframes, 'position', interpolation);
const times: number[] = [];
const values: number[] = [];
for (const kf of keyframes) {
times.push(kf.time);
values.push(...kf.position);
}
return interpolatedTrack(
THREE.VectorKeyframeTrack,
`${jointName}.position`,
times,
values,
interpolation,
);
}
/** Absolute local scale factors; finite zero and negative values remain intentional options. */
export function scaleTrack(
jointName: string,
keyframes: Array<{ time: number; scale: [number, number, number] }>,
interpolation?: TrackInterpolation,
): THREE.VectorKeyframeTrack {
animationKeys(jointName, keyframes, 'scale', interpolation);
const times: number[] = [];
const values: number[] = [];
for (const kf of keyframes) {
times.push(kf.time);
values.push(...kf.scale);
}
return interpolatedTrack(
THREE.VectorKeyframeTrack,
`${jointName}.scale`,
times,
values,
interpolation,
);
}
/**
* Create a TRS clip with nonnegative duration in seconds, or -1 to derive duration from
* the final stored key. An explicit duration must include every key (float32 rounding
* is allowed); zero is valid for time-zero static poses. Tracks remain shared references.
* Export adds held final samples when needed to preserve an explicit longer duration.
* Supports LINEAR, STEP and cubic-spline vector and quaternion tracks, not three.js smooth or
* Bezier interpolants or other channels. A cubic-spline track (CUBICSPLINE and the EASE_*
* shorthands) holds [in-tangent, value, out-tangent] per key and needs at least two keys.
* Quaternion key values must already be unit length (squared-length tolerance 1e-4).
* Validates target syntax, not scene existence/uniqueness: use scene inspection/QA for that.
* `options.loop` declares intent: true for a cycle, false for a one-shot. It is exported as
* the glTF animation extra `kilnLoopIntent` ('loop' | 'once') and reported by animation review;
* omitted means unspecified.
*/
export function createClip(
name: string,
duration: number,
tracks: THREE.KeyframeTrack[],
options?: { loop?: boolean },
): THREE.AnimationClip {
if (typeof name !== 'string' || !name.trim())
throw new Error('Animation clip name must be nonempty.');
animationNumber(duration, 'Animation clip duration');
if (duration < 0 && duration !== -1)
throw new Error('Animation clip duration must be nonnegative, or -1 for automatic duration.');
if (!Array.isArray(tracks) || tracks.length === 0)
throw new Error('Animation clip requires at least one track.');
const loop = clipLoopOption(options);
const names = new Set<string>();
for (const track of tracks) {
if (!(track instanceof THREE.KeyframeTrack))
throw new Error('Animation clip tracks must be KeyframeTrack instances.');
if (typeof track.name !== 'string')
throw new Error('Animation track target/channel must use a string name.');
const dot = track.name.lastIndexOf('.');
animationTarget(track.name.slice(0, dot));
const channel = track.name.slice(dot + 1);
if (!['position', 'scale', 'quaternion'].includes(channel)) {
throw new Error(
`Animation track ${track.name} has an unsupported channel; use position, quaternion or scale.`,
);
}
if (names.has(track.name))
throw new Error(`Duplicate animation target/channel: ${track.name}.`);
names.add(track.name);
const quaternion = channel === 'quaternion';
const Type = quaternion ? THREE.QuaternionKeyframeTrack : THREE.VectorKeyframeTrack;
if (!(track instanceof Type))
throw new Error(
`Animation channel ${channel} requires ${quaternion ? 'QuaternionKeyframeTrack' : 'VectorKeyframeTrack'}.`,
);
const cubic = isCubicSplineTrack(track);
const mode = track.getInterpolation();
if (!cubic && mode !== THREE.InterpolateLinear && mode !== THREE.InterpolateDiscrete) {
throw new Error(
'Animation interpolation must be LINEAR, STEP or CUBICSPLINE (the glTF sampler modes); three.js smooth and Bezier interpolants have no glTF form.',
);
}
animationTimes(track.times, track.name);
if (cubic && track.times.length < 2)
throw new Error(
`Animation track ${track.name} is a cubic spline and needs at least two keys.`,
);
const size = quaternion ? 4 : 3;
// A cubic-spline key is [in-tangent, value, out-tangent]; only the value is a pose.
const stride = cubic ? size * 3 : size;
if (track.values.length !== track.times.length * stride)
throw new Error(
`Animation track ${track.name} requires ${stride} values per keyframe${cubic ? ' (in-tangent, value and out-tangent)' : ''}.`,
);
for (const value of track.values) animationNumber(value, `Animation track ${track.name} value`);
if (quaternion) {
for (let i = cubic ? size : 0; i < track.values.length; i += stride) {
const lengthSquared =
track.values[i]! ** 2 +
track.values[i + 1]! ** 2 +
track.values[i + 2]! ** 2 +
track.values[i + 3]! ** 2;
if (Math.abs(lengthSquared - 1) > 1e-4)
throw new Error(`Animation track ${track.name} quaternion samples must be unit length.`);
}
}
if (duration !== -1 && track.times[track.times.length - 1]! > Math.fround(duration)) {
throw new Error(
`Animation clip duration ${duration} does not include every key of ${track.name}.`,
);
}
}
const clip = new THREE.AnimationClip(name, duration, tracks);
if (loop !== undefined) clip.userData.kilnLoopIntent = loop ? 'loop' : 'once';
return clip;
}
function clipLoopOption(options: unknown): boolean | undefined {
if (options === undefined) return undefined;
if (typeof options !== 'object' || options === null || Array.isArray(options))
throw new Error('Animation clip options must be an object such as { loop: true }.');
for (const key of Object.keys(options))
if (key !== 'loop')
throw new Error(`Animation clip option ${key} is unknown; the only option is loop.`);
const loop = (options as { loop?: unknown }).loop;
if (loop !== undefined && typeof loop !== 'boolean')
throw new Error('Animation clip loop must be true (a cycle) or false (a one-shot).');
return loop;
}
// =============================================================================
// Common Animation Patterns
// =============================================================================
export interface PositionAnimationOptions {
/** Authored parent-local position in scene units. Defaults to [0, 0, 0], preserving the origin-pivot pattern. */
basePosition?: [number, number, number];
}
function positionPresetBase(
duration: number,
amount: number,
options: PositionAnimationOptions,
): [number, number, number] {
animationNumber(duration, 'Animation preset duration');
if (duration <= 0) throw new Error('Animation preset duration must be positive.');
animationNumber(amount, 'Animation preset displacement');
if (!options || typeof options !== 'object' || Array.isArray(options))
throw new Error('Animation preset options must be an object.');
const base = options.basePosition === undefined ? [0, 0, 0] : options.basePosition;
animationVector(base, 'Animation preset basePosition');
return base;
}
/** Rise by amount along parent-local Y, then return to basePosition. Does not infer a rest pose. */
export function idleBreathing(
bodyJoint: string,
duration = 2,
amount = 0.02,
options: PositionAnimationOptions = {},
): THREE.AnimationClip {
const [x, y, z] = positionPresetBase(duration, amount, options);
return createClip('Idle', duration, [
positionTrack(bodyJoint, [
{ time: 0, position: [x, y, z] },
{ time: duration / 2, position: [x, y + amount, z] },
{ time: duration, position: [x, y, z] },
]),
]);
}
/** Move by height along parent-local Y and return. Supply basePosition to retain an authored offset. */
export function bobbingAnimation(
rootName: string,
duration = 2,
height = 0.1,
options: PositionAnimationOptions = {},
): THREE.AnimationClip {
const [x, y, z] = positionPresetBase(duration, height, options);
return createClip('Bob', duration, [
positionTrack(rootName, [
{ time: 0, position: [x, y, z] },
{ time: duration / 2, position: [x, y + height, z] },
{ time: duration, position: [x, y, z] },
]),
]);
}
/** Full turn from identity rotation. Use an unrotated animation pivot to retain a part's rest rotation. */
export function spinAnimation(
jointName: string,
duration = 2,
axis: 'x' | 'y' | 'z' = 'y',
): THREE.AnimationClip {
animationNumber(duration, 'Animation preset duration');
if (duration <= 0) throw new Error('Animation preset duration must be positive.');
if (!['x', 'y', 'z'].includes(axis)) throw new Error('Spin animation axis must be x, y or z.');
const rotation: [number, number, number] = [0, 0, 0];
const idx = axis === 'x' ? 0 : axis === 'y' ? 1 : 2;
const rotations: Array<{ time: number; rotation: [number, number, number] }> = [];
for (let i = 0; i <= 4; i++) {
const r: [number, number, number] = [...rotation];
r[idx] = (i * 90) % 360;
rotations.push({ time: (i * duration) / 4, rotation: r });
}
return createClip('Spin', duration, [rotationTrack(jointName, rotations)]);
}
// =============================================================================
// Utilities
// =============================================================================
// =============================================================================
// Instancing / Reuse (Wave 1B)
// =============================================================================
/** Own vertex buffers before deforming a memoized primitive. */
export function copyGeometry(geo: THREE.BufferGeometry): THREE.BufferGeometry {
return geo.clone();
}
/** Copy material properties. Referenced textures remain shared. */
export function copyMaterial<T extends THREE.Material>(mat: T): T {
return mat.clone();
}
/**
* Creates a new Object3D that reuses an existing part's geometry+material
* at a new transform. The cheapest way to replicate a part (wheel, bolt,
* window, fence-post) without duplicating GPU-side data.
*
* If `source` is a pivot (from `createPivot` or `createPart` with
* `pivot: true`), the instance replicates the first Mesh child's geometry.
*
* Automatically adds to `parent` when provided (mirrors createPart).
*/
export function createInstance(
name: string,
source: THREE.Object3D,
options: {
position?: [number, number, number];
rotation?: [number, number, number];
scale?: [number, number, number];
parent?: THREE.Object3D;
} = {},
): THREE.Object3D {
// Duck-typed `.isMesh` — sandbox-created meshes belong to a different
// module realm than this file's THREE import. See render.ts comment.
const isMesh = (o: THREE.Object3D | undefined): o is THREE.Mesh =>
!!(o as { isMesh?: boolean })?.isMesh;
const sourceMesh = isMesh(source)
? source
: (source.children.find(isMesh) as THREE.Mesh | undefined);
if (!sourceMesh) {
throw new Error(`createInstance("${name}"): source "${source.name}" has no Mesh to clone from`);
}
const mesh = new THREE.Mesh(sourceMesh.geometry, sourceMesh.material);
mesh.name = `Mesh_${name}`;
if (options.position) mesh.position.set(...options.position);
if (options.rotation)
mesh.rotation.set(
THREE.MathUtils.degToRad(options.rotation[0]),
THREE.MathUtils.degToRad(options.rotation[1]),
THREE.MathUtils.degToRad(options.rotation[2]),
);
if (options.scale) mesh.scale.set(...options.scale);
if (options.parent) options.parent.add(mesh);
return mesh;
}
// =============================================================================
// Introspection
// =============================================================================
export function countTriangles(root: THREE.Object3D): number {
let count = 0;
root.traverse((child) => {
if ((child as { isMesh?: boolean }).isMesh) {
const meshChild = child as THREE.Mesh;
const geometry = meshChild.geometry;
const copies = (meshChild as THREE.InstancedMesh).isInstancedMesh
? (meshChild as THREE.InstancedMesh).count
: 1;
if (geometry.index) {
count += Math.floor(geometry.index.count / 3) * copies;
} else {
const position = geometry.getAttribute('position');
if (position) count += Math.floor(position.count / 3) * copies;
}
} else if ((child as { isSprite?: boolean }).isSprite) {
// The canonical GLB bridge materializes every Three.js Sprite as one
// semantic camera-facing quad.
count += 2;
}
});
return Math.floor(count);
}
export function countMaterials(root: THREE.Object3D): number {
const materials = new Set<THREE.Material>();
root.traverse((child) => {
if ((child as { isMesh?: boolean }).isMesh) {
const meshChild = child as THREE.Mesh;
if (Array.isArray(meshChild.material)) {
meshChild.material.forEach((material) => {
materials.add(material);
});
} else {
materials.add(meshChild.material);
}
} else if ((child as { isSprite?: boolean }).isSprite) {
materials.add((child as THREE.Sprite).material);
}
});
return materials.size;
}
export function getJointNames(root: THREE.Object3D): string[] {
const joints: string[] = [];
root.traverse((child) => {
if (child.name.startsWith('Joint_')) {
joints.push(child.name);
}
});
return joints;
}
/** Count distinct material identities against an optional caller-selected budget.
* This is not asset validation and does not estimate draw calls. */
export function materialBudgetAdvisory(
root: THREE.Object3D,
options: { maxMaterials?: number } = {},
): {
materialCount: number;
maxMaterials: number | null;
exceeded: boolean | null;
warnings: string[];
} {
if (
!options ||
typeof options !== 'object' ||
Array.isArray(options) ||
Object.keys(options).some((key) => key !== 'maxMaterials')
) {
throw new Error('materialBudgetAdvisory: options may contain only maxMaterials.');
}
const requested = options.maxMaterials;
if (
requested !== undefined &&
(typeof requested !== 'number' || !Number.isSafeInteger(requested) || requested < 0)
) {
throw new Error('materialBudgetAdvisory: maxMaterials must be a nonnegative safe integer.');
}
const maxMaterials = requested === undefined ? null : requested;
const materialCount = countMaterials(root);
const exceeded = maxMaterials === null ? null : materialCount > maxMaterials;
return {
materialCount,
maxMaterials,
exceeded,
warnings: exceeded
? [
`Material count ${materialCount} exceeds the requested budget ${maxMaterials}. This count is not a draw-call estimate or an asset-validity verdict.`,
]
: [],
};
}
/**
* The full sandbox globals used when executing Kiln code. Kept in one place
* so render.ts and any future evaluator share the same surface area as what
* the LLM expects.
*
* Pass `usage` to tally how many times each primitive was invoked by the
* agent-generated `build()` call. The counter lives on the caller's object
* so render.ts can stash it into `render.meta.primitiveUsage` for
* downstream analysis. When omitted, wrapping is skipped (zero overhead).
*/
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;
palette?: PaletteDeclarationV1;
}
/** 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. */
textureResolver?: TextureResolver;
/** Host-owned diagnostic sink; defaults to the ambient console for library callers. */
console?: DiagnosticConsole;
}
export function buildSandboxGlobals(
usage?: Record<string, number>,
options: SandboxGlobalsOptions = {},
): Record<string, unknown> {
// CSG ops remain lazy at their own call sites, so importing the wrapper here
// is safe for Node ESM builds and still avoids manifold WASM init unless used.
const wrap = <F extends (...args: never[]) => unknown>(name: string, fn: F): F => {
if (!usage) return fn;
const wrapped = (...args: Parameters<F>): ReturnType<F> => {
usage[name] = (usage[name] ?? 0) + 1;
// `fn` IS an F, so this genuinely returns `ReturnType<F>`; tsc resolves the call
// through F's constraint and sees only `unknown`. The assertion states what holds
// by construction, and is narrower than typing the bound as `any`, which would
// silence the whole expression instead of this one step.
return fn(...args) as ReturnType<F>;
};
return wrapped as F;
};
// -- Lazy mesh cache (per-sandbox, not a process global) ---------------
//
// Pattern adapted from chili3d's lazy-mesher: each parametric geometry is
// memoised on stringified args, so repeated calls inside a single build()
// return the same BufferGeometry reference. Direct-library factories remain
// fresh allocations. Pass cached references directly for intentional sharing;
// call copyGeometry before mutating vertices so other parts stay unchanged.
// Export may also deduplicate identical resources independently of this cache.
//
// Each cached geometry is also stamped with a `kilnRanges` entry on its
// userData (B3 — sub-shape mapping). The renderer ignores it (gltf-
// transform doesn't serialise userData), but downstream tooling — a
// future click-to-edit interaction in the gallery viewer — can map a
// clicked triangle back to the primitive call that produced it.
const geoCache = new Map<string, THREE.BufferGeometry>();
let _kilnCallSeq = 0;
const stampKilnRange = (name: string, geo: THREE.BufferGeometry) => {
const idx = geo.getIndex();
const triCount = idx ? idx.count / 3 : (geo.getAttribute('position')?.count ?? 0) / 3;
const callId = ++_kilnCallSeq;
geo.userData = {
...(geo.userData ?? {}),
kilnRanges: [
{
name: `${name}#${callId}`,
start: 0,
count: Math.floor(triCount),
},
],
};
};
const cacheGeo = <F extends (...args: never[]) => THREE.BufferGeometry>(
name: string,
fn: F,
): F => {
const memoFn = (...args: Parameters<F>): THREE.BufferGeometry => {
let key: string;
try {
key = `${name}::${JSON.stringify(args)}`;
} catch {
// Args weren't JSON-stringifiable (circular ref, BufferGeometry,
// etc.) — bypass the cache rather than throw, but still tag the
// result with kilnRanges so downstream inspection works.
const result = fn(...args);
stampKilnRange(name, result);
return result;
}
const hit = geoCache.get(key);
if (hit) return hit;
const result = fn(...args);
stampKilnRange(name, result);
geoCache.set(key, result);
return result;
};
return memoFn as F;
};
// Compose: usage tracking (outer) + memoisation (inner). A cache hit
// still ticks the usage counter so the telemetry reflects what the
// agent wrote, not what was recomputed.
const wrapGeo = <F extends (...args: never[]) => THREE.BufferGeometry>(name: string, fn: F): F =>
wrap(name, cacheGeo(name, fn));
const loadApprovedTexture = (...args: unknown[]): Promise<THREE.DataTexture> => {
if (args.length !== 1 || typeof args[0] !== 'string') {
return Promise.reject(
new TypeError('loadApprovedTexture accepts exactly one approved resource ID string'),
);
}
if (!options.textureResolver) {
return Promise.reject(new Error('loadApprovedTexture: no host TextureResolver is installed'));
}
return options.textureResolver.loadApprovedTexture(args[0]);
};
const sandboxMaterialRecipe = (...args: unknown[]): Promise<THREE.MeshStandardMaterial> => {
if (args.length < 1 || args.length > 2 || typeof args[0] !== 'string') {
return Promise.reject(
new TypeError(
'materialRecipe accepts an approved recipe ID and optional bounded overrides',
),
);
}
if (!options.textureResolver) {
return Promise.reject(new Error('materialRecipe: no host TextureResolver is installed'));
}
return options.textureResolver.materialRecipe(args[0], args[1]);
};
const declarations: SandboxDeclarations = {};
const globals: Record<string, unknown> = {
createRoot: wrap('createRoot', createRoot),
describeAssembly: wrap('describeAssembly', describeAssembly),
replicateAssembly: wrap('replicateAssembly', replicateAssembly),
createPivot: wrap('createPivot', createPivot),
createJointChain: wrap('createJointChain', createJointChain),
createBoneChain: wrap('createBoneChain', createBoneChain),
createSkinnedPart: wrap('createSkinnedPart', createSkinnedPart),
createVehicleFrame: wrap('createVehicleFrame', createVehicleFrame),
createWheelGeometrySet: wrap('createWheelGeometrySet', createWheelGeometrySet),
createWheelAssembly: wrap('createWheelAssembly', createWheelAssembly),
createPart: wrap('createPart', createPart),
defineLod: wrap('defineLod', defineLod),
markOpenShell: wrap('markOpenShell', markOpenShell),
colliderBox: wrap('colliderBox', colliderBox),
colliderCapsule: wrap('colliderCapsule', colliderCapsule),
colliderHull: wrap('colliderHull', colliderHull),
anchor: wrap('anchor', anchor),
defineModule: wrap('defineModule', defineModule),
port: wrap('port', port),
repeatInstances: wrap('repeatInstances', repeatInstances),
bakeSurfaceAttributes: wrap('bakeSurfaceAttributes', bakeSurfaceAttributes),
requireSolid: wrap('requireSolid', requireSolid),
defineBudget: wrap(
'defineBudget',
(spec: Parameters<typeof defineBudget>[0], target?: THREE.Object3D) => {
const declaration = defineBudget(spec, target);
declarations.budget = declaration;
return declaration;
},
),
definePalette: wrap(
'definePalette',
(
colors: Parameters<typeof definePalette>[0],
opts?: Parameters<typeof definePalette>[1],
target?: THREE.Object3D,
) => {
const declaration = definePalette(colors, opts, target);
declarations.palette = declaration;
return declaration;
},
),
capsuleGeo: wrapGeo('capsuleGeo', capsuleGeo),
capsuleXGeo: wrapGeo('capsuleXGeo', capsuleXGeo),
capsuleYGeo: wrapGeo('capsuleYGeo', capsuleYGeo),
capsuleZGeo: wrapGeo('capsuleZGeo', capsuleZGeo),
cylinderGeo: wrapGeo('cylinderGeo', cylinderGeo),
cylinderXGeo: wrapGeo('cylinderXGeo', cylinderXGeo),
cylinderYGeo: wrapGeo('cylinderYGeo', cylinderYGeo),
cylinderZGeo: wrapGeo('cylinderZGeo', cylinderZGeo),
boxGeo: wrapGeo('boxGeo', boxGeo),
sphereGeo: wrapGeo('sphereGeo', sphereGeo),
coneGeo: wrapGeo('coneGeo', coneGeo),
coneXGeo: wrapGeo('coneXGeo', coneXGeo),
coneYGeo: wrapGeo('coneYGeo', coneYGeo),
coneZGeo: wrapGeo('coneZGeo', coneZGeo),
taperConeGeo: wrapGeo('taperConeGeo', taperConeGeo),
cylinderOnAxis: wrapGeo('cylinderOnAxis', cylinderOnAxis),
torusGeo: wrapGeo('torusGeo', torusGeo),
planeGeo: wrapGeo('planeGeo', planeGeo),
decalBox: wrapGeo('decalBox', decalBox),
foliageCardGeo: wrapGeo('foliageCardGeo', foliageCardGeo),
crossedQuadsGeo: wrapGeo('crossedQuadsGeo', crossedQuadsGeo),
octaGridPlane: wrapGeo('octaGridPlane', octaGridPlane),
wingGeo: wrapGeo('wingGeo', wingGeo),
createWingPair: wrap('createWingPair', createWingPair),
beamBetween: wrap('beamBetween', beamBetween),
createLadder: wrap('createLadder', createLadder),
snapTo: wrap('snapTo', snapTo),
room: wrap('room', room),
wallWithOpening: wrap('wallWithOpening', wallWithOpening),
createRoofPlanes: wrap('createRoofPlanes', createRoofPlanes),
createGableRoof: wrap('createGableRoof', createGableRoof),
createGableEndPanel: wrap('createGableEndPanel', createGableEndPanel),
createGableShell: wrap('createGableShell', createGableShell),
createRoofSurfaceLayout: wrap('createRoofSurfaceLayout', createRoofSurfaceLayout),
createStairs: wrap('createStairs', createStairs),
gameMaterial: wrap('gameMaterial', gameMaterial),
materialRecipe: wrap('materialRecipe', sandboxMaterialRecipe),
compilePortableMaterialSpecV2: wrap('compilePortableMaterialSpecV2', (...args: unknown[]) => {
if (args.length !== 1)
return Promise.reject(
new TypeError('compilePortableMaterialSpecV2 accepts exactly one material spec'),
);
return compilePortableMaterialSpecV2(args[0], { resolver: options.textureResolver });
}),
compilePortableMaterialSpecV3: wrap('compilePortableMaterialSpecV3', (...args: unknown[]) => {
if (args.length !== 1)
return Promise.reject(
new TypeError('compilePortableMaterialSpecV3 accepts exactly one material spec'),
);
return compilePortableMaterialSpecV3(args[0], { resolver: options.textureResolver });
}),
basicMaterial: wrap('basicMaterial', basicMaterial),
glassMaterial: wrap('glassMaterial', glassMaterial),
lambertMaterial: wrap('lambertMaterial', lambertMaterial),
rotationTrack: wrap('rotationTrack', rotationTrack),
positionTrack: wrap('positionTrack', positionTrack),
scaleTrack: wrap('scaleTrack', scaleTrack),
createClip: wrap('createClip', createClip),
spinAnimation: wrap('spinAnimation', spinAnimation),
bobbingAnimation: wrap('bobbingAnimation', bobbingAnimation),
idleBreathing: wrap('idleBreathing', idleBreathing),
implicitSurface: wrap('implicitSurface', implicitSurface),
metaballSurface: wrap('metaballSurface', metaballSurface),
catmullRomPath: wrap('catmullRomPath', catmullRomPath),
spiralPath: wrap('spiralPath', spiralPath),
taperedTube: wrap('taperedTube', taperedTube),
smoothOrganic: wrap('smoothOrganic', smoothOrganic),
smoothUnion: wrap('smoothUnion', smoothUnion),
sphereInside: wrap('sphereInside', sphereInside),
sweepProfile: wrap('sweepProfile', sweep.sweepProfile),
loftProfiles: wrap('loftProfiles', sweep.loftProfiles),
bend: wrap('bend', deform.bend),
twist: wrap('twist', deform.twist),
taper: wrap('taper', deform.taper),
displace: wrap('displace', deform.displace),
copyGeometry: wrap('copyGeometry', copyGeometry),
copyMaterial: wrap('copyMaterial', copyMaterial),
meshGeo: wrap('meshGeo', geometry.meshGeo),
parametricSurface: wrap('parametricSurface', geometry.parametricSurface),
creaseNormals: wrap('creaseNormals', geometry.creaseNormals),
geometryDiagnostics: wrap('geometryDiagnostics', geometry.geometryDiagnostics),
createInstance: wrap('createInstance', createInstance),
// CSG (async)
boolUnion: wrap('boolUnion', solids.boolUnion),
boolDiff: wrap('boolDiff', solids.boolDiff),
boolIntersect: wrap('boolIntersect', solids.boolIntersect),
hull: wrap('hull', solids.hull),
// Bevel / extrude / revolve (async — same manifold WASM as the CSG ops).
// NOT wrapGeo: these return a Promise, and the geometry memo/kilnRanges
// stamp in wrapGeo operates on a BufferGeometry synchronously.
roundedBoxGeo: wrap('roundedBoxGeo', profile.roundedBoxGeo),
extrudeProfile: wrap('extrudeProfile', profile.extrudeProfile),
revolveProfile: wrap('revolveProfile', profile.revolveProfile),
circleProfile: wrap('circleProfile', profile.circleProfile),
// Array/mirror/subdivide/curve ops
arrayLinear: wrap('arrayLinear', ops.arrayLinear),
arrayRadial: wrap('arrayRadial', ops.arrayRadial),
repeatAlongCurve: wrap('repeatAlongCurve', ops.repeatAlongCurve),
mirror: wrap('mirror', ops.mirror),
subdivide: wrap('subdivide', ops.subdivide),
mergeVertices: wrap('mergeVertices', ops.mergeVertices),
// Explicit lower-detail copy (async: meshoptimizer WASM). Never implicit.
simplifyGeometry: wrap('simplifyGeometry', simplifyGeometry),
curveToMesh: wrap('curveToMesh', ops.curveToMesh),
pipeAlongPath: wrap('pipeAlongPath', ops.pipeAlongPath),
lathe: wrap('lathe', ops.lathe),
revolveGeo: wrap('revolveGeo', ops.revolveGeo),
bezierCurve: wrap('bezierCurve', ops.bezierCurve),
// UV (async)
autoUnwrap: wrap('autoUnwrap', uv.autoUnwrap),
// Shape-aware unwraps (sync — preserve built-in directional UVs)
projectUV: wrap('projectUV', projectUV),
remapUV: wrap('remapUV', uvShapes.remapUV),
remapUVToAtlas: wrap('remapUVToAtlas', remapUVToAtlas),
// Parametric primitives
gearGeo: wrapGeo('gearGeo', gears.gearGeo),
bladeGeo: wrapGeo('bladeGeo', gears.bladeGeo),
// Closed approved textures. Paths, URLs, bytes, hashes, and resolver
// objects are intentionally not accepted by this one-argument closure.
loadApprovedTexture: wrap('loadApprovedTexture', loadApprovedTexture),
// Procedural textures (sync — no I/O, so no await)
proceduralTexture: wrap('proceduralTexture', proceduralTextures.proceduralTexture),
textureAtlas: wrap('textureAtlas', (...args: unknown[]) => {
if (args.length !== 1)
return Promise.reject(new TypeError('textureAtlas accepts exactly one atlas spec'));
return textureAtlas(args[0], { resources: options.textureResolver?.pinnedMaterialMaps });
}),
normalMapFromHeight: wrap('normalMapFromHeight', proceduralTextures.normalMapFromHeight),
pbrMaterial: wrap('pbrMaterial', textures.pbrMaterial),
foliageMaterial: wrap('foliageMaterial', textures.foliageMaterial),
countTriangles: wrap('countTriangles', countTriangles),
countMaterials: wrap('countMaterials', countMaterials),
getJointNames: wrap('getJointNames', getJointNames),
materialBudgetAdvisory: wrap('materialBudgetAdvisory', materialBudgetAdvisory),
seededRandom: wrap('seededRandom', seededRandom),
// THREE namespace is exposed so agents can `new THREE.Mesh(geo, mat)`
// as operands to CSG and other ops that expect Object3D inputs.
THREE,
Math,
console: options.console ?? console,
};
Object.defineProperty(globals, SANDBOX_DECLARATIONS, { value: declarations });
return globals;
}