Skip to content
Kiln1.9Get Kiln

Latest published package: Kiln 1.9.0. Earlier versions below identify feature requirements or historical results.

The workspace library holds immutable, explicit material revisions. It is separate from the small embedded texture catalog. Source images are optional resource packs, not npm package data. An evaluator receives only the complete pinned records selected by its host. Authored source can resolve their approved resource IDs, but cannot read paths, fetch URLs, or supply resolver code.

kiln_material is advertised when a host supplies a material library. Its presets action lists these offline starting points; the presets and list actions accept a family tag such as rock. Each recipe produces base color, OpenGL normal, and packed metallic/roughness maps. They are synthetic starting points with stated physical repeat scales, not measured scans.

Preset Family Repeat scale Notes
warm-brick architecture 2 × 2 m Staggered masonry and shallow mortar relief
wood-grain wood 1 × 1 m Straight interior grain; no knots or end grain
brushed-metal metal 1 × 1 m Directional relief, fully metallic packed channel
woven-fabric fabric 0.5 × 0.5 m Crossed threads, matte dielectric
coarse-soil ground 2 × 2 m Granular soil for terrain and planting beds
beach-sand ground 1 × 1 m Fine pale grains with shallow wind ripples
coral-limestone rock 2 × 2 m Porous cream stone with pitted relief
coral-limestone-wet rock 2 × 2 m Darker, smoother wet stone; the same seed keeps the dry relief
palm-frond foliage 2 × 2 m Alpha-tested (MASK), double-sided cutout card, not tileable
driftwood wood 1 × 1 m Bleached silver-grey grain, deep weathering
thatch fiber 1 × 1 m Vertical straw strands in horizontal courses
lime-plaster architecture 2 × 2 m Off-white render with trowel clouding
oak wood 1 × 1 m Honey oak, tight straight grain; no knots
linen fabric 0.5 × 0.5 m Fine flax weave with slubs, matte
jute fiber 0.5 × 0.5 m Coarse open basket weave
basalt rock 2 × 2 m Dark fine-grained volcanic stone
terracotta architecture 1 × 1 m Unglazed fired clay with warm mottling
wicker fiber 0.5 × 0.5 m Rattan strands over and under
brushed-brass metal 1 × 1 m Warm brass, directional brushing, fully metallic

palm-frond saves a schemaVersion:2 record: its base color is a V3 RGBA silhouette with clamped sampling, so map it once across a card or a foliageCardGeo with the frond base at the bottom of the image. The other presets save V1 records and tile.

Create one with an explicit seed, creator, and a license the caller is authorized to apply:

{
  "action": "create-preset",
  "presetId": "wood-grain",
  "seed": 17,
  "size": 256,
  "creator": "Your project",
  "license": {
    "spdx": "CC0-1.0",
    "url": "https://creativecommons.org/publicdomain/zero/1.0/",
    "attribution": ""
  }
}

For CLI authoring, save the same JSON above as wood-options.json, then use:

node kiln.mjs material create-preset --file wood-options.json
node kiln.mjs material get RETURNED_MATERIAL_ID RETURNED_REVISION
node kiln.mjs material export RETURNED_MATERIAL_ID RETURNED_REVISION --out wood-payload.json

Copy the returned portableSpec into authored source with the exact dependency pin. Use compilePortableMaterialSpecV2 for portableSpec.schemaVersion === 2 and compilePortableMaterialSpecV3 for version 3. Existing presets return V2. Custom draft creation uses CLI material procedural --file draft.json, corresponding to MCP create-procedural. These paths need no imports from internal dist/ files or extra TypeScript loader. The public host APIs below are for a configured TypeScript toolchain; ordinary Node cannot directly execute TypeScript inside node_modules.

A new revision of an existing material can name the revision it replaces: parentRevision in the draft, or material procedural --file draft.json --parent sha256:.... It must be a saved revision of the same materialId. The field is optional, and the revision hash covers it when it is present, so a record without it keeps its id and the same draft with and without a parent are two revisions. get, list and the material export --maps sidecar report it. It survives export and import, and import does not require the parent to be in the receiving library. Revisions have no other order, so this is the only statement that one supersedes another.

list returns compact summaries and accepts a tag. get requires materialId and revisionId and returns provenance plus a code-ready portableSpec. create-procedural accepts an editable draft using the same bounded layer recipes as the existing procedural compiler. Opt-in drafts with schemaVersion:2 also support RGBA recipes, named atlases and explicit per-map samplers; see the standalone texture workflow. An optional derive: {"kind":"normal-from-height","strength":2} on a normal map converts the recipe’s height pixels through the existing wrapped normal derivation: Rec. 601 luma of the compiled RGB is read as height and alpha is ignored. It applies to V2 layer recipes and, in schemaVersion:2 drafts, to V3 RGBA recipes with usage: 'normal'; atlases and supplied bytes do not accept it. The saved recipe records derive, and verification recompiles through it. import accepts a complete normalized payload. None of these operations acquires source images from a provider.

Curated resource packs are complete normalized payloads: maps, recipes and source/license provenance, ready for explicit import. They are not npm package contents or public downloads; use a pack whose source and license you can verify, such as one exported from another workspace with material export:

node kiln.mjs material import --file /path/to/wood-pack.json

Use the selected payload’s actual local path. Importing it does not create a project or fetch its original source URLs. The five shipped procedural presets remain available without any resource pack.

Pin the returned material ID and revision hash before using its resource IDs. A project is optional: pass a pin array as MCP materialDependencies or CLI --materials pins.json for an individual operation, or put the array in a project’s materialDependencies for shared use. The pin’s resourceId is the material ID; its revisionId and sha256 both equal the manifest’s immutable revisionId. The compiler matching portableSpec.schemaVersion creates the material inside authored source. The host supplies complete map bytes through materialResources before build-cache lookup, including when evaluation uses the default subprocess.

Editable standalone asset ZIPs carry the saved dependency closure in materials.kiln.json; project ZIPs carry resources for their selected saved inventory as well as the current lock. Both preserve normalized maps, recipes and provenance without fetching original source URLs. Runtime GLBs already embed their rendering resources. An editable export fails clearly if a declared library dependency is unavailable; creating a project is not a workaround or requirement. Runtime exports can opt in to a texture manifest (--textures manifest) that names each embedded image by its exact sha256 and, when those bytes equal a map of the saved closure, by that material pin and slot. --textures external writes the images once as shared textures/<sha256>.<ext> files beside a .gltf. See runtime textures.

Physical repeat scale is recorded metadata. The author still chooses UV scale appropriate to the mesh. Repeating a one-meter material across a ten-meter wall requires corresponding UV repeats; recording meters does not silently change geometry or UVs.

Export maps as tiling textures

A destination that takes plain images, such as a game engine’s terrain layer, can export one saved revision’s maps as standalone PNGs:

node kiln.mjs material export coarse-soil RETURNED_REVISION --maps soil-maps --size 1024 --repeat 4

The command writes into the named directory, creating it when missing:

  • <id>.<slot>.png for each map, --size pixels square;
  • <id>.preview.png, the material on a lit plane repeated --tiles × --tiles (default 3, at most 8);
  • <id>.maps.json, the kiln.material-maps.v1 sidecar.

--repeat is the real-world edge of one tile in metres. It defaults to the recorded physicalSizeMeters when that is square, and is required otherwise. Sizes run from 4 to 4096. A map already at the requested size is copied byte for byte (method: "copy"). A V2 layer recipe without a height derivation samples UV space, so it is recompiled at a power-of-two size up to 1024 ("recipe", with the new recipe hash). Every other map is resampled ("resampled") with a separable Catmull-Rom cubic that follows the map’s wrap mode, so a repeating tile stays seamless; sRGB maps filter in linear light and normal maps are renormalized. Resampling is deterministic for a given engine and encoder.

The sidecar names the source material and revision, its name, parameters and source/license records; the size and repeat; and, for each map, its slot, file, usage, colour space (srgb for base colour and emissive, linear data for the rest), normal convention or channel packing, pixel size, byte count, sha256, method, wrap and the stored map it came from. Packed maps keep R=occlusion, G=roughness, B=metallic; split channels in the destination if it wants them apart.

The preview follows the same route as kiln_render: the configured GPU renderer (--render auto|cpu|gpu, default KILN_RENDER or auto) through the render port, else the CPU raster. Its preview.rendererId and preview.viewFidelity record which one drew it. A CPU preview has materialFaithful: false and shows the plane’s geometry, not the material; judge the material only from a materialFaithful: true preview. Maps larger than 1024 pixels are resampled to 1024 for the preview plane only (preview.mapSize).

Every file must be new. If one already exists the export stops and removes the files it had already written. --out keeps writing the portable JSON payload, and --maps and --out cannot be combined. Terrain-layer schemas, blend masks and destination tints belong to the destination, not to this export. Hosts call the same export from TypeScript:

import { FileMaterialLibrary, exportMaterialMaps } from '@instruktlabs/kiln/material-library/node';

const library = new FileMaterialLibrary('/workspace/.kiln/materials');
const record = await library.read('coarse-soil', revisionId);
const { sidecar, files } = await exportMaterialMaps(record, {
  outDir: 'soil-maps',
  size: 1024,
  repeatMeters: 4,
  // Optional: a PbrRenderPort for a material-faithful preview; without one the preview is CPU.
  // viewRenderPort, viewRenderTimeoutMs, viewRenderRequired
});

createMaterialMapExport returns the same files in memory without writing them.

Host API and portable export

import { FileMaterialLibrary, createMaterialLibraryPayload,
  decodeMaterialLibraryPayload } from '@instruktlabs/kiln/material-library/node';
import { createMaterialPresetDraft } from '@instruktlabs/kiln/material-presets';
import { createMaterialRecordV1 } from '@instruktlabs/kiln/material-library/node';

const library = new FileMaterialLibrary('/workspace/.kiln/materials');
const record = await createMaterialRecordV1(createMaterialPresetDraft('wood-grain', {
  seed: 17,
  creator: 'Your project',
  license: { spdx: 'CC0-1.0',
    url: 'https://creativecommons.org/publicdomain/zero/1.0/', attribution: '' },
}));
await library.import([record]);
// palm-frond needs createMaterialPresetDraftAny and createMaterialRecordV2.

// The JSON payload includes every normalized PNG, recipe, source hash and license record.
const payload = await createMaterialLibraryPayload([record]);
const json = JSON.stringify(payload);
// Transfer json as a local optional resource pack. The receiver needs no source URL access.
await anotherLibrary.import(await decodeMaterialLibraryPayload(JSON.parse(json)));

FileMaterialLibrary takes the storage directory itself. read(materialId, revisionId) verifies stored bytes before returning a complete record. Import validates every supplied record before writing and stores each revision atomically. Reimporting an identical revision is idempotent. Existing revisions cannot be replaced with different data.

External normalized maps must be PNG. Base color and emissive use sRGB; normal, occlusion and packed channels use linear data. Normal maps use OpenGL positive Y. Packed maps preserve R=occlusion, G=roughness, B=metallic. Binding a packed image only to metallicRoughness consumes green and blue; occlusion must be separately bound if wanted. Metalness/roughness factors multiply their texture channels, so use factors of one when the maps should control the full range.

Every external map names an original source file with its hash and size. The source includes provider, creator, URL and license. A map produced by a local deterministic program with no public URL uses a generated source instead: the same fields, no URL required, and a required generator record with the program’s name, version and sha256, its toolkit files’ hashes, the seed when it takes one, and runtime name/version pairs. Kiln checks that record’s shape, that each map names a file the source lists, and the stored bytes against their hashes, as it does for external maps. It does not run the generator or prove the bytes came from it; the record states a claim someone can reproduce. Recipe maps use a procedural source, so a recipe on a generated source is refused, and material export --maps copies the generator record into its sidecar with the other source fields. Derivations record the actual normalization steps and tool versions. Procedural maps retain canonical recipes, seeds, recipe hashes, decoded pixel hashes and encoder version. The revision hash covers this metadata and the normalized map hashes. Changing bytes, seed, derivation, scale, or provenance creates a different revision.

Payloads are bounded to 16 records, 16 MiB encoded PNG data and 16 million decoded pixels. Split larger libraries into task or theme packs; load only the operation’s pinned resources. Imported records have additional per-map and per-record bounds. Arbitrary scripts, accessors, functions, network references used as loaders, and executable recipes are rejected.

Acquisition and aesthetic curation stay host-side. Verify the asset’s license separately from API terms, retain originals and source/license snapshots outside the engine package, normalize maps, then qualify both embedded GLB output and material-faithful previews. A valid hash or passing glTF validator establishes integrity and structure, not suitability for a project or a target game engine.

Read this page in the repository