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.

feat(core): kiln.listPrimitives() self-describing catalog

Matt Kissinger73c62831eee3
diff --git a/__tests__/list-primitives.test.ts b/__tests__/list-primitives.test.ts
new file mode 100644
index 00000000..e889bd1d
--- /dev/null
+++ b/__tests__/list-primitives.test.ts
@@ -0,0 +1,79 @@
+/**
+ * Kiln primitive catalog tests (W3b.2)
+ *
+ * Verifies the self-describing catalog stays in sync with the actual
+ * sandbox globals exposed by `buildSandboxGlobals()`. Drift between the
+ * catalog and the real surface is a silent agent-facing bug, so we check
+ * it here rather than relying on documentation discipline.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { listPrimitives } from '../list-primitives';
+import { buildSandboxGlobals } from '../primitives';
+
+describe('kiln.listPrimitives', () => {
+ test('returns a non-empty catalog with expected shape', () => {
+ const spec = listPrimitives();
+ expect(spec.length).toBeGreaterThan(20);
+ for (const p of spec) {
+ expect(p.name).toMatch(/^[a-zA-Z_][a-zA-Z0-9_]*$/);
+ expect(p.signature).toContain(p.name);
+ expect(p.returns.length).toBeGreaterThan(0);
+ expect(p.description.length).toBeGreaterThan(0);
+ expect(p.example.length).toBeGreaterThan(0);
+ expect(['geometry', 'material', 'structure', 'animation', 'utility']).toContain(
+ p.category
+ );
+ }
+ });
+
+ test('every cataloged primitive is present in the sandbox globals', () => {
+ const globals = buildSandboxGlobals();
+ for (const p of listPrimitives()) {
+ expect(typeof globals[p.name]).toBe('function');
+ }
+ });
+
+ test('every sandbox function (except Math/console) appears in the catalog', () => {
+ const catalog = new Set(listPrimitives().map((p) => p.name));
+ const globals = buildSandboxGlobals();
+
+ const missing: string[] = [];
+ for (const [name, value] of Object.entries(globals)) {
+ if (name === 'Math' || name === 'console') continue;
+ if (typeof value !== 'function') continue;
+ if (!catalog.has(name)) missing.push(name);
+ }
+
+ expect(missing).toEqual([]);
+ });
+
+ test('returned array is a defensive copy', () => {
+ const a = listPrimitives();
+ const b = listPrimitives();
+ expect(a).not.toBe(b);
+ expect(a[0]).not.toBe(b[0]);
+ a[0]!.name = 'mutated';
+ expect(b[0]!.name).not.toBe('mutated');
+ });
+
+ test('contains canonical entries for the major primitive groups', () => {
+ const names = new Set(listPrimitives().map((p) => p.name));
+ for (const expected of [
+ 'createRoot',
+ 'createPivot',
+ 'createPart',
+ 'boxGeo',
+ 'sphereGeo',
+ 'cylinderGeo',
+ 'gameMaterial',
+ 'rotationTrack',
+ 'positionTrack',
+ 'createClip',
+ 'countTriangles',
+ ]) {
+ expect(names.has(expected)).toBe(true);
+ }
+ });
+});
diff --git a/index.ts b/index.ts
index d87e410f..a53c665e 100644
--- a/index.ts
+++ b/index.ts
@@ -37,6 +37,8 @@ export type {
InspectBoundingBox,
Vec3Tuple,
} from './inspect';
+export { listPrimitives } from './list-primitives';
+export type { PrimitiveSpec } from './list-primitives';
export {
buildUserPrompt,
getSystemPrompt,
diff --git a/list-primitives.ts b/list-primitives.ts
new file mode 100644
index 00000000..9915b829
--- /dev/null
+++ b/list-primitives.ts
@@ -0,0 +1,282 @@
+/**
+ * Kiln Primitive Catalog (W3b.2)
+ *
+ * Self-describing inventory of every helper function the Kiln sandbox
+ * exposes to generated code. Agents call `kiln.listPrimitives()` to
+ * discover the surface without reading `primitives.ts` directly.
+ *
+ * The list is hand-authored rather than JSDoc-parsed — the catalog is
+ * small (25 entries) and hand-authoring gives cleaner `signature` /
+ * `example` strings than we'd get from TS AST extraction. Drift is caught
+ * by `__tests__/list-primitives.test.ts` which asserts every entry
+ * matches a real sandbox global.
+ */
+
+export interface PrimitiveSpec {
+ /** Function name as it appears in the sandbox. */
+ name: string;
+ /** Human-readable signature (`"boxGeo(w: number, h: number, d: number)"`). */
+ signature: string;
+ /** Return type description (`"THREE.BufferGeometry"`). */
+ returns: string;
+ /** One-sentence summary of what the primitive does. */
+ description: string;
+ /** Idiomatic usage snippet agents can splice directly into generated code. */
+ example: string;
+ /** High-level grouping for filtering in agent UIs. */
+ category: 'geometry' | 'material' | 'structure' | 'animation' | 'utility';
+}
+
+const PRIMITIVES: PrimitiveSpec[] = [
+ // ---------------------------------------------------------------------------
+ // Structure
+ // ---------------------------------------------------------------------------
+ {
+ name: 'createRoot',
+ signature: 'createRoot(name: string)',
+ returns: 'THREE.Object3D',
+ category: 'structure',
+ description: 'Creates the root Object3D for an asset. Call first in build().',
+ example: "const root = createRoot('FuelDrum');",
+ },
+ {
+ name: 'createPivot',
+ signature: 'createPivot(name: string, position?: [x, y, z], parent?: Object3D)',
+ returns: 'THREE.Object3D (prefixed `Joint_`)',
+ category: 'structure',
+ description:
+ 'Creates an empty pivot node for skeletal animation. Name is auto-prefixed with `Joint_`.',
+ example: "const hip = createPivot('Hip', [0, 1, 0], root);",
+ },
+ {
+ name: 'createPart',
+ signature:
+ 'createPart(name, geometry, material, opts?: { position, rotation, scale, pivot, parent })',
+ returns: 'THREE.Object3D (mesh or wrapping pivot)',
+ category: 'structure',
+ description:
+ 'Creates a mesh, optionally wrapped in a pivot, and attaches it to `opts.parent`.',
+ example:
+ "createPart('Barrel', cylinderGeo(0.1, 0.1, 1), gameMaterial(0x556b2f), { position: [0, 0.5, 0], parent: root });",
+ },
+
+ // ---------------------------------------------------------------------------
+ // Geometry
+ // ---------------------------------------------------------------------------
+ {
+ name: 'boxGeo',
+ signature: 'boxGeo(width: number, height: number, depth: number)',
+ returns: 'THREE.BoxGeometry',
+ category: 'geometry',
+ description: '6-face box. 12 tris regardless of size. Cheapest geometry.',
+ example: 'const geo = boxGeo(1, 0.5, 2);',
+ },
+ {
+ name: 'sphereGeo',
+ signature: 'sphereGeo(radius: number, widthSegments?: 8, heightSegments?: 6)',
+ returns: 'THREE.SphereGeometry',
+ category: 'geometry',
+ description:
+ 'UV sphere. Default 8x6 segments = 84 tris. Bump segments for smoother curves.',
+ example: 'const geo = sphereGeo(0.5, 12, 8);',
+ },
+ {
+ name: 'cylinderGeo',
+ signature:
+ 'cylinderGeo(radiusTop: number, radiusBottom: number, height: number, segments?: 8)',
+ returns: 'THREE.CylinderGeometry',
+ category: 'geometry',
+ description:
+ 'Y-axis cylinder. Use radiusTop != radiusBottom for cones / tapered pieces.',
+ example: 'const geo = cylinderGeo(0.25, 0.25, 1, 12);',
+ },
+ {
+ name: 'capsuleGeo',
+ signature: 'capsuleGeo(radius: number, height: number, segments?: 6)',
+ returns: 'THREE.CapsuleGeometry',
+ category: 'geometry',
+ description: 'Stadium shape (cylinder with hemispherical caps). Good for limbs.',
+ example: 'const geo = capsuleGeo(0.1, 0.5, 6);',
+ },
+ {
+ name: 'coneGeo',
+ signature: 'coneGeo(radius: number, height: number, segments?: 8)',
+ returns: 'THREE.ConeGeometry',
+ category: 'geometry',
+ description: 'Y-axis cone (pointed up). Use for spikes, roofs, projectiles.',
+ example: 'const geo = coneGeo(0.3, 0.8, 8);',
+ },
+ {
+ name: 'torusGeo',
+ signature:
+ 'torusGeo(radius: number, tube: number, radialSegments?: 8, tubularSegments?: 12)',
+ returns: 'THREE.TorusGeometry',
+ category: 'geometry',
+ description: 'Donut shape. For rings, tyres, barrel ribs.',
+ example: 'const geo = torusGeo(0.4, 0.04, 8, 16);',
+ },
+ {
+ name: 'planeGeo',
+ signature:
+ 'planeGeo(width: number, height: number, widthSegments?: 1, heightSegments?: 1)',
+ returns: 'THREE.PlaneGeometry',
+ category: 'geometry',
+ description: 'Flat quad. Faces +Z by default. Rotate to use as ground / decal.',
+ example: 'const geo = planeGeo(4, 4);',
+ },
+
+ // ---------------------------------------------------------------------------
+ // Materials
+ // ---------------------------------------------------------------------------
+ {
+ name: 'gameMaterial',
+ signature:
+ 'gameMaterial(color, opts?: { metalness, roughness, emissive, emissiveIntensity, flatShading })',
+ returns: 'THREE.MeshStandardMaterial',
+ category: 'material',
+ description:
+ 'Flat-shaded PBR material. Default for game-ready low-poly. Use for 95% of parts.',
+ example: "const mat = gameMaterial(0x8b7355, { roughness: 0.9 });",
+ },
+ {
+ name: 'basicMaterial',
+ signature: 'basicMaterial(color, opts?: { transparent, opacity })',
+ returns: 'THREE.MeshBasicMaterial',
+ category: 'material',
+ description: 'Unlit flat material. For UI / effects where lighting is baked in.',
+ example: "const mat = basicMaterial(0xffffff, { transparent: true, opacity: 0.5 });",
+ },
+ {
+ name: 'glassMaterial',
+ signature: 'glassMaterial(color, opts?: { opacity, roughness, metalness })',
+ returns: 'THREE.MeshStandardMaterial',
+ category: 'material',
+ description: 'Semi-transparent double-sided material. Panels need ~0.05 offset to avoid z-fighting.',
+ example: 'const mat = glassMaterial(0x66ccff, { opacity: 0.3 });',
+ },
+ {
+ name: 'lambertMaterial',
+ signature: 'lambertMaterial(color, opts?: { flatShading, emissive })',
+ returns: 'THREE.MeshLambertMaterial',
+ category: 'material',
+ description: 'Cheaper than gameMaterial. No metalness/roughness. Use when PBR is overkill.',
+ example: "const mat = lambertMaterial(0x2a4d14, { flatShading: true });",
+ },
+
+ // ---------------------------------------------------------------------------
+ // Animation — keyframe tracks
+ // ---------------------------------------------------------------------------
+ {
+ name: 'rotationTrack',
+ signature:
+ 'rotationTrack(jointName: string, keyframes: Array<{ time, rotation: [xDeg, yDeg, zDeg] }>)',
+ returns: 'THREE.QuaternionKeyframeTrack',
+ category: 'animation',
+ description:
+ 'Rotation track in degrees, auto-converted to quaternions. Joint name must include `Joint_` prefix.',
+ example:
+ "rotationTrack('Joint_Lid', [{ time: 0, rotation: [0, 0, 0] }, { time: 1, rotation: [90, 0, 0] }]);",
+ },
+ {
+ name: 'positionTrack',
+ signature:
+ 'positionTrack(jointName: string, keyframes: Array<{ time, position: [x, y, z] }>)',
+ returns: 'THREE.VectorKeyframeTrack',
+ category: 'animation',
+ description: 'Position track in world units. Always use `position:` not `value:` in keyframes.',
+ example:
+ "positionTrack('Joint_Body', [{ time: 0, position: [0, 0, 0] }, { time: 1, position: [0, 0.1, 0] }]);",
+ },
+ {
+ name: 'scaleTrack',
+ signature:
+ 'scaleTrack(jointName: string, keyframes: Array<{ time, scale: [x, y, z] }>)',
+ returns: 'THREE.VectorKeyframeTrack',
+ category: 'animation',
+ description: 'Uniform or per-axis scale track.',
+ example:
+ "scaleTrack('Joint_Chest', [{ time: 0, scale: [1, 1, 1] }, { time: 1, scale: [1.1, 1.1, 1.1] }]);",
+ },
+ {
+ name: 'createClip',
+ signature: 'createClip(name: string, duration: number, tracks: KeyframeTrack[])',
+ returns: 'THREE.AnimationClip',
+ category: 'animation',
+ description: 'Collects tracks into a named clip. Returned from animate().',
+ example: "return [createClip('Open', 1, [rotationTrack('Joint_Lid', [...])])];",
+ },
+
+ // ---------------------------------------------------------------------------
+ // Animation — presets
+ // ---------------------------------------------------------------------------
+ {
+ name: 'idleBreathing',
+ signature: 'idleBreathing(bodyJoint: string, duration?: 2, amount?: 0.02)',
+ returns: 'THREE.AnimationClip',
+ category: 'animation',
+ description: 'Gentle Y-axis bob. For NPC idle states.',
+ example: "return [idleBreathing('Joint_Body')];",
+ },
+ {
+ name: 'bobbingAnimation',
+ signature: 'bobbingAnimation(rootName: string, duration?: 2, height?: 0.1)',
+ returns: 'THREE.AnimationClip',
+ category: 'animation',
+ description: 'Floating / bobbing loop for pickups and effects.',
+ example: "return [bobbingAnimation('Joint_Root', 1.5, 0.08)];",
+ },
+ {
+ name: 'spinAnimation',
+ signature: "spinAnimation(jointName: string, duration?: 2, axis?: 'x' | 'y' | 'z')",
+ returns: 'THREE.AnimationClip',
+ category: 'animation',
+ description: '360° rotation over `duration` around `axis`.',
+ example: "return [spinAnimation('Joint_Rotor', 0.5, 'y')];",
+ },
+
+ // ---------------------------------------------------------------------------
+ // Utility
+ // ---------------------------------------------------------------------------
+ {
+ name: 'countTriangles',
+ signature: 'countTriangles(root: Object3D)',
+ returns: 'number',
+ category: 'utility',
+ description: 'Sums triangle count across every mesh in the subtree.',
+ example: "meta.tris = countTriangles(root);",
+ },
+ {
+ name: 'countMaterials',
+ signature: 'countMaterials(root: Object3D)',
+ returns: 'number',
+ category: 'utility',
+ description: 'Unique material count (by reference) across the subtree.',
+ example: 'const mats = countMaterials(root);',
+ },
+ {
+ name: 'getJointNames',
+ signature: 'getJointNames(root: Object3D)',
+ returns: 'string[]',
+ category: 'utility',
+ description: 'All node names beginning with `Joint_`. Use to sanity-check animation targets.',
+ example: "const joints = getJointNames(root);",
+ },
+ {
+ name: 'validateAsset',
+ signature: "validateAsset(root: Object3D, category: 'character' | 'prop' | 'vfx' | 'environment')",
+ returns: '{ valid, errors, warnings }',
+ category: 'utility',
+ description: 'Warns on category-appropriate triangle / material budgets.',
+ example: "const v = validateAsset(root, 'prop');",
+ },
+];
+
+/**
+ * Return the full catalog of primitives available in the Kiln sandbox.
+ *
+ * Cheap: returns a pre-built static array (a new clone, so callers can
+ * mutate freely without corrupting internal state).
+ */
+export function listPrimitives(): PrimitiveSpec[] {
+ return PRIMITIVES.map((p) => ({ ...p }));
+}