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.
Kiln JavaScript and TypeScript SDK
This describes the v1 package contract. Examples use @instruktlabs/kiln; install
a published version or a qualified local archive as described in the
installation guide. Use documentation matching the installed version.
A workspace made by kiln-init has no package.json, so import '@instruktlabs/kiln/render'
fails there until you install the package pinned to the Kiln runtime version you use; CLI/MCP
authoring does not need it.
Imports
Kiln ships compiled ESM and TypeScript declarations. The package root is a Node library entrypoint; importing it does not run the CLI or start a server. Consumers do not need Bun or a TypeScript runtime loader.
import { createDiscovery, engineIdentity, renderGLB, validateKilnCode } from '@instruktlabs/kiln';
const code = `function build() {
return new THREE.Mesh(boxGeo(1, 1, 1), gameMaterial(0x888888));
}`;
const validation = validateKilnCode(code);
const result = await renderGLB(code);
// result.glb is a Buffer containing the GLB. Persist or deliver it in your host.
The complete authoring and host APIs remain available through documented subpaths.
The original 55 export paths are retained; version 1.1 added four
host entrypoints below, and the game delivery contract adds delivery. The root exposes rendering, validation,
Discovery and engine identity; it does not re-export every name from every module.
CommonJS is not part of this release's contract.
Custom AssetLibrary hosts can import verifyAssetRecord and
resolveSavedAssetMaterials from @instruktlabs/kiln/assets/node. The latter resolves
the exact saved dependency manifests from a record's embedded material payload or
an injected MaterialLibrary; it never substitutes a newer material revision.
Use the existing material payload and asset-bundle encoders for portable delivery.
| Area | Subpaths |
|---|---|
| Root library | @instruktlabs/kiln |
| Authoring | primitives, geometry, deform, sweep, architecture, assembly, character, vehicle, palette, delivery |
| Materials | material-library, material-library/node, material-presets, material-recipes, material-resources, material-recipe-runtime, material-recipe-prompt, material-metrics, texture-resolver |
| Rendering and inspection | render, views, views/port, validation, metrics, inspect, qa, asset-export, kit |
| Host contracts | tools, tools/input, mcp, evaluator, discovery, discovery/portable, requirements, requirements/migration, contracts, prompt-api, profile |
| Records and storage | assets, projects, project-bundle, workspace, live-review, programs, cache, and each corresponding /node adapter |
| Composition | composer, world-runtime |
| Ranking math | arena |
| Optional agent workflows | agent, composer/agent |
| Experimental modeling | implicit |
Read the architecture reference for the domains and the
runtime contract for hosting boundaries. The export map is the public
entrypoint list. Files inside lib/, including declaration dependencies under
lib/_types/, are implementation details and are not additional public subpaths.
Stability in 1.x
The table classifies all 60 public entrypoints. The root and every listed subpath
except implicit are stable entrypoints for v1: their declared public signatures,
record shapes and documented behavior receive normal semantic-versioning
compatibility. Optional dependencies do not make the two agent APIs experimental.
The arena entry is pure ranking math and needs no model SDK or provider key.
Use the documentation shipped with the installed version; a checkout does not
change an already installed package's contract.
The exception follows the feature across imports: implicitSurface remains
experimental when re-exported by primitives or used in authoring globals, and
experimental Discovery recipes retain their individual labels. The alternative
Three.js exporter also remains experimental and explicitly selected. Changes to
these experimental features must be identified in release notes and migration
guidance; the rest of an entrypoint does not inherit that exception.
The deprecated setApprovedTextureResolver alias remains available from
material-resources; new hosts use setTrustedTextureByteResolver. Deprecation
does not authorize removal from a compatible 1.x release. Neither setter belongs
in generated code: trusted hosts own the approved resource boundary.
Human-readable prompts, descriptions, diagnostic prose and image pixels are not byte-stable API outputs. Consume documented structured records and version tags; ignore unknown additive result fields. Preserve an asset's exact engine identity and source/revision receipts for reproducible replay. Compatibility of the SDK does not imply identical generated GLB bytes or renderer output across releases. Persisted data and rebuild restrictions follow the migration contract.
Procedural RGBA surfaces
The primitives entrypoint and authored proceduralTexture helper accept an
explicit V3 recipe for bounded rectangular RGBA images, shape coverage, alpha
masks, palettes, dithering and seeded stamps. Pure V3 compilation returns pixels,
canonical JSON and a compiler-qualified recipe hash without creating a mesh.
Read the V3 contract for the exact limits and rounding
rules. V1/V2 remain supported with their existing pixels, hashes and sampler
defaults. The same entrypoint exposes textureAtlas and remapUVToAtlas for
named regions. Portable V3 materials add explicit per-map sampling; opt-in V2
material records persist recipes, compiled maps and exact dependency pins.
See the standalone material and atlas workflow.
Explicit character skinning
The character and primitives entrypoints expose opt-in createBoneChain and
createSkinnedPart; both are also sandbox helpers. createJointChain continues
to return ordinary rigid Object3D pivots. Bone chains use the same versioned
joint descriptors, infer an attached declared parent role and reject ambiguous
roles/names before attaching nodes. They do not choose anatomy or a body plan.
createSkinnedPart(name, geometry, material, { parent, bones, indices, weights })
clones unchanged geometry and binds it to the assembled hierarchy's current rest
pose. Supply exactly four indices and weights per vertex, in the explicit bone
array order. Indices must be valid even in zero-weight lanes. By default weights
must be in 0..1 and sum to one within 1e-5; normalizeWeights: true explicitly
normalizes positive finite sums. Zero sums are rejected. Optional local position,
Euler rotation (degrees), scale and semantic metadata match createPart's units.
The helper owns geometry, influence arrays and inverse bind matrices; bones and materials remain shared. Limits are 1024 bones, 262144 vertices and 128 MiB of cloned attributes plus new influence storage. These are helper limits, not new restrictions on direct Three.js authoring. Existing skin attributes and singular bind transforms are rejected. Set up rest transforms before binding; later rest edits/reparenting need deliberate rebinding. Animated bounds remain a consumer responsibility. The selected Three exporter is required to preserve skins; calling these helpers does not change the legacy default or select a converter.
inspectSkinIntegrity(root) from @instruktlabs/kiln/qa reads source bindings
without updating matrices, normalizing weights or repairing the scene. It returns
bounded findings, checked counts and current posed world bounds (including position
morphs). It is not an animation envelope, deformation-quality score or proof of
collision clearance. Rigid meshes do not acquire skin or body-plan requirements.
Export runs this check before bounds, texture baking or conversion. Invalid source
bindings produce an AssetQaBlockedError at the scene stage with mesh/joint or
vertex-range context and repair advice. This is mandatory input integrity, like
invalid geometry buffers; QA warning mode and derivative serialization do not
bypass it. The partial failure report does not claim the remaining QA rules ran.
The independent final glTF validation remains in place. Source Three skeletons
need their inverse-bind arrays populated; this does not change glTF's valid
identity-matrix default when the file omits inverseBindMatrices.
Execution and dependencies
The root SDK is Node-oriented. /node adapters use filesystem or server services;
the remaining names do not by themselves promise browser compatibility. Portable
record modules retain their existing boundaries. Browser use must follow a
documented, qualified entrypoint rather than importing the entire Node host.
Embedding interfaces added in 1.1
mcpexportscreateKilnMcpServer,createKilnToolHostandkilnMcpToolDefsfor Node hosts, using the shared tool registry and injectedKilnToolContext. It is an in-process embedding API. Thekiln-mcpexecutable keeps its separate lazy engine loading; importingmcploads the Node engine.discovery/portableprovides catalog/request validation, lexical indexing,createDiscoveryServiceand retired-helper guidance. Supply a catalog generated from the matching engine version. This browser-qualified entrypoint does not import Node's built-in catalog construction or execute authored programs.tools/inputexposes the shared action requirements and input-error formatting helpers without importing the engine registry or Node runtime.views/portexposes the existing renderer-port helpers and types, includingcaptureViewPngsViaPort. Reuse their deadline, cancellation and PNG-validation policy rather than implementing a second renderer adapter. It does not provide a renderer or authorize trusted execution of untrusted source.
These entries require 1.1 or later; 1.0.0 does not expose them. They contain no cloud-provider, account, tenant or hosted-service policy.
The requirements entry exports the host requirements store, binding context and
asset-requirements schema. Its optional validation statement
(ValidationProfileV1Schema, kiln.validation-profile.v1) declares destination
checks that the exact rule HOST_VALIDATION_PROFILE evaluates on the final GLB.
The qa entry exports evaluateValidationProfileGlb to run the same evaluation
on GLB bytes a host already holds. See the
host validation profile.
renderGLB defaults to trusted in-process execution. A hosted service accepting
untrusted programs must inject or select the qualified isolated evaluator described
in the runtime contract. A subprocess provides a worker boundary; it does not alone
establish filesystem, network or tenant isolation.
The installed isolated evaluator uses compiled JavaScript workers and readiness probes, without a TypeScript loader. Linux hosts still need the required namespace and resource-limit tools and must pass the actual readiness probe. An unavailable boundary fails closed; a successful local worker render is not proof of isolation.
Optional Strands workflows (agent and composer/agent) require Node 22.2.0+
and their documented peer dependencies. The core SDK, CLI and MCP retain the
separate Node compatibility contract in the installation guide.
Core SDK imports and consumer types must work without those optional peers.
Shared tool contracts contain host-neutral interfaces; they do not require the
Strands SDK to typecheck an ordinary CLI/MCP host.
Existing experimental features remain explicit: /implicit keeps its current
availability and limitations, and the community exporter stays explicitly selected. CPU
geometry previews do not establish texture or PBR material fidelity. Experimental
labels do not waive installation, export-resolution or resource-bound checks.
Discovery search and overview text include each entry's stable, experimental
or deprecated label alongside its limitations. The CLI, SDK and MCP use the same
catalog. A recipe's experimental label applies to that recipe; it does not change
the stability of the helpers it uses. Exact details retain the same structured
stability field. Implicit modeling remains available without a new opt-in switch;
the community exporter retains its explicit selection.
Named operation presentation
In package version 1.2.0 and later, embeddings can select
createKilnMcpServer(context, { toolPresentation: 'operations' }), or obtain the
same definitions through createKilnOperationToolRegistry(context) from tools.
The default MCP and native interfaces retain their existing grouped tools.
With asset and material storage, and without project/review or renderer-control
callbacks, the named presentation exposes 21 tools. Asset browsing becomes
kiln_assets_search with an optional collection; material browsing becomes
kiln_material_search with scope: 'all' | 'presets' | 'saved'. Material creation
uses kiln_material_create with a required definition discriminated by
kind: 'preset' | 'procedural'. Saving, importing, retrieval and source restoration
remain explicit operations. Renderer controls appear only when their callbacks
exist. Connected tools/list remains authoritative.
Action requirements and field constraints come from the shared engine registry. Generation rejects unclassified action/field additions and missing required fields. Hosts select supported operations and add their actual execution and persistence policy; do not copy domain schemas or assume a local read hint describes a quota-admitted cloud job. This API change does not publish a package or deploy a hosted service. Actual client acceptance is still required.
Maintainer qualification
node scripts/build-runtime.mjs all builds both executable bundles and the ESM SDK.
bun run build remains typechecking only. SDK output replaces the generated lib/
tree after successful compilation and module resolution, so removed modules cannot
linger in a new package.
On a fresh checkout, run bun run build:runtime before typechecking or running tests
that exercise public package imports. Rebuild after source changes; package tests
must exercise the generated code that a consumer will receive. Coverage measures
the source engine and excludes its generated lib/ copy without changing thresholds.
The package checks import core entrypoints and render through the installed worker.
With maintainer dependencies present, node scripts/smoke-package.mjs --types also
typechecks a clean installed consumer without optional peers. CI qualifies this
against the same tarball subsequently passed to the platform consumer jobs.
The core check covers 53 entrypoints, including arena. After installing the
optional peers, node scripts/smoke-sdk-types.mjs INSTALLED_PACKAGE --with-agent-peers
checks declarations for all 55. Import/type qualification does not establish live
model access or provider behavior.