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.
Editable and runtime exports
Kiln keeps the saved revision as the canonical asset. Choose a delivery profile when exporting it; changing the profile never rebuilds the asset or changes its collection.
| Profile | Output | Use |
|---|---|---|
editable (default) |
Existing exact GLB, source, preview, manifest, or editable ZIP | Continue authoring, inspect build/review records, archive or share source |
runtime (opt in) |
Derived standalone GLB and a versioned metadata JSON sidecar | Deliver a smaller GLB to an application while retaining traceability |
editable describes the export policy, not a promise that an imported GLB has source.
A binary-only saved revision remains binary-only. Keep the editable ZIP when source
is available: a runtime sidecar is not a replacement for it.
Which option should I use?
- Continue editing or share a rebuildable asset: keep the default
editableprofile and export its ZIP. Export an editable GLB when you need the exact saved GLB. - Load an animated asset in a game or web scene: try
runtime. Kiln moves its duplicate review tracks out of the GLB, reducing the data the application loads. Compare the actual sizes; a static asset may gain nothing. Keep the sidecar for traceability and keep the editable ZIP for future authoring. - Need additional glTF feature preservation: separately compare the experimental Three.js converter described in the engine handoff guide. Preserve the baseline and check the result in the destination importer.
Converter and delivery profile are separate settings
| Setting | When it applies | Default | Optional choice | Why it exists |
|---|---|---|---|---|
| GLB converter | Source render/build | Established converter (legacy) |
Experimental Three.js converter (three) |
Compare preservation of features such as skin/morph data, extra UV sets and material extensions |
| Export profile | Delivery of an already-saved revision | editable |
runtime |
Keep exact authoring artifacts or externalize duplicate review data for application loading |
The converter is selected through the host's KILN_GLTF_EXPORTER environment or the
render library option. The delivery profile is selected through kiln_export, CLI
export --profile, or the asset-export library. Either converter can produce a saved
asset for either delivery profile. Changing the environment during an export does
not rebuild the saved GLB; create and save a new render when comparing converters.
The defaults preserve established workflows and complete review records. Runtime is opt in because moving review data changes its location and adds a companion file. The Three.js converter is experimental because native installation requirements, unsupported UV transforms and destination feature support still need qualification. Neither setting automatically enables mesh merging, geometry simplification, Draco, Meshopt or KTX2 compression. Those require separate choices and validation; the opt-in three.js runtime target is one such choice.
Material sidedness at export
glTF represents front-only or double-sided surfaces. Both Kiln converters preserve
FrontSide and DoubleSide. A used BackSide material now stops a source build
with EXPORT_MATERIAL_SIDE_UNSUPPORTED. The direct scene API names the part and
material; CLI/MCP carry closed repair advice without authored identifiers across
the evaluator boundary. Use kiln_source with query BackSide to locate the
authored material. This applies
in both warn and strict geometry modes and before texture baking or conversion;
unused material-array slots do not block export. Existing saved GLBs remain readable
and exporting their exact bytes does not rebuild them.
For a one-sided interior surface, author triangles facing inward and use
FrontSide. For a leaf or other deliberate sheet visible from either side, use
DoubleSide. Neither choice supplies thickness or missing caps. Do not flip only
normals to repair winding. Automatic back-only conversion is not provided: winding,
normal/tangent basis, groups, shared geometry and deformation data must remain
consistent. A destination shader override is an explicit runtime choice, separate
from the portable asset.
CLI
From an asset workspace, using the IDs returned by save or assets:
# Existing behavior: full editable ZIP, with byte-identical saved files.
node kiln.mjs export ASSET_ID REVISION_ID --out mech-editable.zip
# Explicit editable GLB: exact saved GLB bytes.
node kiln.mjs export ASSET_ID REVISION_ID --profile editable --format glb --out mech-editable.glb
# Runtime defaults to GLB; writes BOTH files below.
node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --out mech.glb
# mech.glb
# mech.kiln-metadata.json
Runtime requires GLB format and an output ending in .glb, except --textures external,
which writes .gltf (see runtime textures). Bundle/source formats
use editable. Use a portable filename stem containing ASCII letters, digits,
periods, underscores or hyphens, beginning with a letter or digit. The generated
sidecar filename must be at most 200 characters; Windows device names are rejected.
Directory paths may be absolute, but only the sibling filename enters provenance.
Exports never replace either destination; the error names the existing file. --json
prints a receipt naming both files with their bytes and sha256. Runtime stages both complete files,
then publishes the sidecar before the GLB using exclusive hard links on the destination
filesystem. A caught failure rolls back files owned by that call and preserves existing
files. Filesystems must support hard links. This is not a crash/power-loss transaction:
an interrupted process can leave a complete orphan sidecar. Remove that orphan or choose
fresh output names before retrying. A partial GLB is never published by this path.
MCP
kiln_export({ collection: "project", assetId, revisionId, profile: "runtime" })
The shared tool registry accepts editable (default) or runtime. Runtime returns
descriptors for runtime.glb and runtime.kiln-metadata.json, including byte sizes
and kiln://assets/... resource URIs. Read them through MCP resources/read.
These resources are derived from the pinned revision on demand, without persisting
a new revision. The local viewer host also serves those resource filenames through
its existing /files/ endpoint. The local viewer offers Original GLB and
Runtime GLB, plus a separate Runtime metadata download when that export is
ready. Keep the metadata's filename unchanged next to runtime.glb. Opened editable
ZIPs support the same export in the browser; a loose GLB retains its original download.
The public gallery also offers both GLBs and the matching metadata. Its sidecar identifies the gallery asset and exact source/GLB hashes; the program download is separate. Neither GLB contains the complete editable bundle. Gallery examples are historical showcases and may still contain modeling defects.
Runtime results do not reuse configured canonical download URLs: those would deliver the wrong GLB. Client support for saving MCP resources varies. No binary data is put into tool text. To write files, configure an export root (below) or use the local CLI.
Bytes before a save: programRef
kiln_export also takes a programRef in place of assetId and revisionId. It builds the program, saves nothing, and returns a kiln://programs/{program}/{sha256}/asset.glb resource with the size, hash, triangle count and draw diagnostics. A destination whose audit reads geometry can run before the save this way, so a repair lands before the revision exists rather than as its child. The bytes are the ones kiln_save then persists. The build runs again on read, and a program this host now builds to different bytes is refused rather than served under the old hash; export again for the current ones. The runtime profile needs a saved revision. The CLI's kiln render REF --out x.glb reaches the same bytes.
Writing files: kiln_export_to
When the host sets KILN_EXPORT_ROOT on the MCP server, it also advertises
kiln_export_to. Without the variable the tool list and kiln_export are unchanged.
Discovery capabilities report it as assets.exportTo, which is null when the tool is
absent and never shows the absolute root. Generated Codex workspaces forward the
variable from the shell that starts Codex, as the other harnesses' servers inherit it.
kiln_export_to({ collection: "project", assetId, revisionId, path: "game/door.glb" })
// game/door.glb
// game/door.kiln-metadata.json
kiln_export_to({ assetId, revisionId, path: "web/door.glb", target: "three" })
kiln_export_to({ assetId, revisionId, path: "archive/door.glb", profile: "editable" })
profileisruntime(default) oreditable, which writes the exact saved GLB only; ZIP and source stay resources.target: "three"requiresruntime, as in the CLI, and produces the same bytes asexport --profile runtime --target threewith the same file name.pathis relative to the root: forward slashes, at most 240 characters and 8 segments, each segment portable (the filename-stem rule above), ending in.glb..., absolute, drive-letter and UNC paths, backslashes and Windows device names are refused. The sidecar name is derived,<stem>.kiln-metadata.json, beside it.- Existing files are never replaced, through the same writer as the CLI. Directories that are symlinks or junctions are refused; missing directories are created.
- The receipt is the CLI
--jsonreceipt with paths relative to the root:ok,collection,assetId,revisionId,profile,target?,format: "glb",drawDiagnosticsandfiles[{ kind, path, bytes, sha256 }]. No absolute path or file bytes appear in tool text.
The root is host configuration, never a tool input: an existing absolute directory
(on Windows a drive or UNC path) that neither contains nor sits inside a collection
directory or the workspace .kiln/. It is a destination, not project membership.
Render output has no file destination: delivery starts from a saved revision.
TypeScript library
import { exportAssetGlb } from '@instruktlabs/kiln/asset-export';
const record = await library.read('project', assetId, revisionId);
const output = await exportAssetGlb(record, {
profile: 'runtime',
metadataFileName: 'mech.kiln-metadata.json',
});
if (output.profile === 'runtime') {
// Save output.glb as mech.glb and output.metadata.bytes under output.metadata.name.
// The helper performs no filesystem writes or network requests.
}
Omitting profile returns the exact canonical GLB bytes. Runtime verifies the saved
file inventory and hashes, validates the GLB chunk table, and returns deterministic
bytes for the same record and sibling filename. It does not serialize through a new
glTF exporter or decode/re-encode textures.
What runtime changes
Only scenes[].extras.kilnReviewClipsV1 is moved into the JSON sidecar. It contains
Kiln's authored animation review vocabulary, including advisory tracks that might not
have valid native glTF targets. Native animations remain authoritative for playback.
The sidecar retains each source scene index and its original review object.
The profile preserves glTF hierarchy, node names, sockets, transforms, mesh topology, materials, textures, skins, morph targets, native animation channels, and application extras. Every chunk after JSON, including the BIN chunk, is copied byte for byte. JSON values are preserved outside the named review field and the added provenance record. Existing metadata is not generally scrubbed, so user-authored extras can still contain information the author put there. The new provenance fields introduce no local paths, source text, build paths or provider information.
Assets with no review clips still receive the provenance link and an empty sidecar scene list; their GLB can grow slightly. This is not geometry optimization, compression, mesh merging, texture compression, or an FPS improvement. Measure actual delivery size and target-scene performance separately.
Fewer draw calls
--draws minimal (runtime profile only; draws: 'minimal' in exportAssetGlb) derives a
file with as few draws as the saved revision allows, and composes with --target three. The
saved revision does not change.
- Every mesh used by two or more nodes becomes an
EXT_mesh_gpu_instancingbatch, within the limits in the runtime notes: one handedness per batch, no shear, and tangent-bearing copies batched by the rotation they share. A batched copy loses its mesh. A mesh-less copy with no children or extensions is removed, name and all; one with either stays as a named node with no mesh. The batch node is named after its first copy,<copy>_Instances, with_1,_2and so on when that name is taken.- Nothing is batched when the file has animations, skins or review clips
(
scenes[].extras.kilnReviewClipsV1), or when any node has extras (semantic metadata included),KHR_node_visibility, anMSFT_lodchain or aJoint_*name. - In that case
drawReduction.batchingSkippedgives the reason, and only step 2 runs.
- Nothing is batched when the file has animations, skins or review clips
(
- Parts whose mesh has a single user merge per material, vertex layout and tangent handedness,
within cubes
--draw-cellmetres wide (default 15), so a viewer can still cull a large asset by region.- Never merged: blended and transmissive parts, and the nodes a consumer reads by name.
Those are animation and review-clip targets,
Joint_*pivots, nodes with extras, nodes a semantic relationship names, and visibility and LOD nodes. - A merged part keeps its node name, but its geometry can move to another node of its cell.
- Never merged: blended and transmissive parts, and the nodes a consumer reads by name.
Those are animation and review-clip targets,
Unlike optimize: 'full', it runs no palette(), which rewrites materials, and no weld(),
which splits accessors that parts share. On a 16 MB cathedral, weld() alone added 10 MB.
The sidecar's drawReduction reports:
- draws before and after, batches and merges;
- what stayed separate, and why;
instancing, one entry per batch:{ node, mesh, count, instances }. Hereinstances[i]is the name of the node that instanceireplaced, as in--target three'sdelivery.instancing. A consumer that found a copy by name finds it there.
Measured on copies of the 1,834-draw cathedral revision:
| Export | Draws | Triangles | Bytes | Time |
|---|---|---|---|---|
| Saved revision | 1,834 | 3,979,304 | 15,993,092 | |
--draws minimal |
283 | 3,979,304 | 15,851,728 | 1.5 s |
--draws minimal --target three |
283 | 3,979,304 | 6,839,500 | 1.9 s |
Batches cost a renderer more per draw than plain meshes do, so measure frame time in the target scene, not only the draw count.
In three r186, every batch costs load time, about 17 ms per render pass, for two reasons:
- A shader per batch. Below 1,024 copies,
nodes/accessors/Instance.jsstores a batch's matrices in a uniform array whose shader name and length are its own. - A node graph per batch.
RenderObjectadds eachInstancedMesh's uuid to its cache key, so three builds each batch's node graph separately.
The cathedral above has 176 batches. In an unmodified r186 viewer:
- WebGL2 compiled 203 programs and first drew at 33 s; the saved revision first drew at 4 s.
- WebGPU built 399 shader modules and held the page for 3.9 s after its first frame.
Two viewer changes remove most of that cost:
- Share shaders. Report a uniform-buffer limit of zero:
renderer.backend.capabilities.getUniformBufferLimit = () => 0afterinit(). Every batch then reads its matrices as instanced attributes, which are named by slot, so batches with the same material share a shader. That gave 29 programs on WebGL2 and 55 modules on WebGPU. Only skinning andRangeNoderead the same limit, and a skeleton then reads its bones from a texture. - Build ahead. Call
renderer.compileAsync(model, camera, scene)before the model is first drawn, on WebGPU too when it has many batches.compileAsyncyields between objects.
With both, WebGL2 first drew at 7.9 s. WebGPU had no task over 150 ms and first drew at 6.1 s, where the saved revision draws at 1.1 s.
three.js runtime target
--target three (runtime profile only) derives a GLB for a three.js application:
node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --target three --out door.glb
# door.glb
# door.kiln-metadata.json (version kiln.runtime-metadata.v1, target "three", delivery {...})
import { deliverThreeRuntimeGlb, exportAssetGlb } from '@instruktlabs/kiln/asset-export';
const output = await exportAssetGlb(record, { profile: 'runtime', target: 'three' });
// Or derive from any Kiln GLB without a saved record:
const { glb, delivery } = await deliverThreeRuntimeGlb(bytes, { ktx2Encoder });
What it does, in order:
- Identical accessors are merged. Under each node marked by
repeatInstances(parent), direct children with the same mesh content (accessors, material, mode) and no children, roles, extras, skin, morph weights or hidden flag become one node<parent>_InstanceswithEXT_mesh_gpu_instancing. Mirrored children form their own batch on a node scaled[-1, 1, 1], named<parent>_Instances_<n>like any further batch under that parent. A turned, stretched or mirrored child of a mesh withTANGENTstays separate. - Each collider's proxy mesh moves to a child
<collider>_Proxy, so the collider node keeps its authored transform (its scale is the collider size). - Vertices are reordered for compression, then quantized with
KHR_mesh_quantizationper mesh: position 14 bits, normal 10, texcoord 12, colour 8, weights 8. Position bits divide each mesh's largest half-extent into2^(bits-1) - 1steps, so 14 bits on a 10 m mesh is a grid of about 0.61 mm: enough to close a modelled seam or move a measured clearance.positionBits(CLI--position-bits) takes 8 to 16, orfloatto keep positions as 32-bit floats while the other classes stay quantized. The sidecar reports the step in metres for each mesh node (positionSteps) and the largest (maxPositionStep); a vertex moves by at most half its step. Check it against the smallest gap or clearance that matters before shipping. Underscore attributes such as_EDGEand_CAVITYare not quantized and stay FLOAT. Buffers are written withEXT_meshopt_compression(required) unless the caller passescompression: 'none'(CLI--compression none): then buffers stay plain, no Meshopt decoder is needed, and quantization, instancing and everything below stay. - Textures become KTX2 (
KHR_texture_basisu, required, no PNG fallback) only with--ktx2or a libraryktx2Encoder; otherwise the sidecar reportsktx2: { status: 'skipped' }and textures stay PNG or JPEG. See KTX2 textures.
Roles and kit extras, hidden collider nodes (KHR_node_visibility), anchors, ports and
MSFT_lod chains are kept.
A loader that never selects a level still downloads every lower one. maxLod: n (CLI
--max-lod n) keeps LOD0 to LODn of each chain in the default scene and removes the
rest, with the meshes, materials and textures only they used; 0 keeps LOD0 alone and
removes MSFT_lod. Thresholds in MSFT_screencoverage are cut to the kept levels. When a
chain loses levels, budget tiers above n leave the shipped kilnBudgetV1 declaration,
since they would otherwise be measured against fewer levels; the sidecar lists them as
budgetTiersOmitted. A dropped level that an animation targets is refused. Kiln still
does not select a level at runtime.
The sidecar delivery block states what a consumer needs:
| Field | Meaning |
|---|---|
extensionsUsed, extensionsRequired |
The derived GLB's extension sets |
compression |
{ extension: 'EXT_meshopt_compression', method: 'quantize' }, or { extension: 'none' } |
quantization |
Bits per attribute class (position is 'float32' when unquantized); customAttributes: 'float32'; positionSteps: [{ node, mesh, step }] in metres (skinned meshes in mesh units) and maxPositionStep |
nodeScale |
Every node whose matrix now carries a dequantization { scale, offset }, its localScale, and whether the mesh moved to a child (meshMovedToChild, authoredNode) |
colliderProxies |
Collider node and proxy child paths |
customAttributes |
Each underscore attribute, its mesh count, FLOAT, not normalized |
instancing |
Each batch node, its mesh, count and instance names in order |
ktx2 |
encoded or skipped with the texture count and reason; encoder (name, version, Basis WebAssembly hash and every setting) when the encoder declared it |
lod |
With maxLod only: { maxLod, chains: [{ path, levels, dropped }], budgetTiersOmitted }, where levels counts the kept levels and dropped names the removed ones |
preserved |
Counts of LOD chains, hidden nodes, colliders, anchors, ports and kit modules |
Quantization stores positions as normalized integers and moves the metre scale onto the node: read geometry through the node's world matrix. With Meshopt compression (the default) a loader needs the meshopt decoder; with three.js:
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
await MeshoptDecoder.ready;
const gltf = await new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).parseAsync(buffer, '');
With compression: 'none', new GLTFLoader().parseAsync(buffer, '') loads it without a
decoder. three's GLTFLoader keeps unknown node extensions in userData.gltfExtensions
(KHR_node_visibility, MSFT_lod) and lowercases custom attributes (_edge).
Kiln's tests load the derived GLB from both converters this way. On a very small asset
the extension JSON can outweigh the saved geometry; compare real assets.
KTX2 textures
--ktx2 (with --target three) encodes every PNG, JPEG or WebP image to KTX2 through
the optional peer [email protected]. Kiln does not install or bundle it; add it to the
installation that runs kiln:
npm install [email protected]
node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --target three --ktx2 --textures manifest --out door.glb --json
Without the peer, --ktx2 fails and names that install command. Another installed
version is refused, because the settings below are qualified on 0.6.0. The mode follows
the slot: ETC1S with the sRGB transfer function for base colour and emissive, UASTC with
Zstandard supercompression for normal, metallic-roughness, occlusion and other linear
maps (normal maps also use the encoder's normal-map preset). Every level gets mipmaps. An
image used by both an sRGB and a linear slot stops the export, because one encoding
cannot serve both; give each slot its own image.
delivery.ktx2.encoder records name, version, basisWasmSha256 and the exact
settings per profile, and the --json receipt repeats delivery.ktx2. Because the
sidecar hash is stamped into the GLB, these facts are bound to the delivered bytes. With
--textures manifest, each entry's sha256 is the KTX2 bytes and sourceSha256 the
image before encoding; a library pin is matched on the pre-encode bytes. Encoding the same
image twice gives identical bytes in Kiln's tests; if a platform ever differs, the
recorded version and settings are the contract, and the only cost is a new hash.
Encoding runs inside the same document as the rest of the target, so MSFT_lod chains,
roles and atlas provenance survive: every atlas reference is rebound to its KTX2 bytes and
MIME type and validated as import will validate it. The library form is:
import { createKtx2Encoder, exportAssetGlb } from '@instruktlabs/kiln/asset-export';
const output = await exportAssetGlb(record, {
profile: 'runtime',
target: 'three',
ktx2Encoder: await createKtx2Encoder(),
});
A host may pass its own ktx2Encoder instead. It receives { image, mimeType, name, colorSpace, slot }, must return bytes that start with the KTX2 identifier, and may carry
an identity property that Kiln records as delivery.ktx2.encoder.
A consumer needs KTX2Loader (with its Basis transcoder files served by the application)
in addition to the meshopt decoder:
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
const ktx2 = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).setKTX2Loader(ktx2);
Licences: ktx2-encoder is MIT. Its package bundles a precompiled Basis Universal
encoder (Apache-2.0, Binomial LLC) as WebAssembly, which links Zstandard (BSD-3-Clause)
and MIT-licensed image loaders, and the package ships THIRD_PARTY_NOTICES.md reproducing
the Basis Universal NOTICE. Kiln (MIT) only imports the peer that the user installed; it
redistributes none of that code, so the notice travels with the installed package. Anyone
who redistributes ktx2-encoder itself, for example inside a self-contained archive, must
keep that notice file. KTX2 output is data produced by the encoder, not a copy of it.
Runtime textures: manifest and shared files
Runtime GLBs embed every texture, so forty assets that use one library material carry
forty copies of its maps. Two opt-in choices let a host share them. Neither is the
default: without --textures, the GLB, sidecar and --json receipt bytes are unchanged.
kiln textures measures what a given set would save before you choose.
Manifest. --textures manifest (runtime profile, with or without --target three)
adds textures[] to the sidecar. The GLB is unchanged apart from the provenance hash of
that larger sidecar.
node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --textures manifest --out wall.glb
const output = await exportAssetGlb(record, { profile: 'runtime', textures: 'manifest' });
One entry per glTF image, sorted by image index:
| Field | Meaning |
|---|---|
image |
glTF image index |
sha256, bytes, mimeType |
Identity of the exact delivered bytes |
width, height |
Pixel size read from the image header |
colorSpace |
srgb when a base colour or emissive slot uses the image, otherwise linear |
sourceSha256 |
The bytes before KTX2 encoding, only when encoding changed them |
material |
{ pin: { resourceId, revisionId, sha256 }, slot }, only when the pre-encode bytes exactly equal a map in the record's saved material closure (materials.kiln.json). Never inferred from names |
uri |
External layout only: the image file relative to the .gltf |
Equal sha256 means equal bytes, so a host can deduplicate images across assets on that
key without decoding a GLB. Library textures keep their encoded bytes in the GLB, so two
assets that use one library map report the same sha256 and the same material.pin.
External textures. --textures external (requires --target three and --out
ending in .gltf) writes standard JSON glTF with content-addressed images instead of a
GLB, and implies the manifest with a uri on each entry:
node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --target three \
--textures external --out assets/wall.gltf --json
# assets/wall.gltf (asset.extras.kilnProvenanceV1 points at the sidecar)
# assets/wall.bin
# assets/wall.kiln-metadata.json
# assets/textures/<sha256>.png (or .jpg, .webp, .ktx2)
The file name of each texture is the hex SHA-256 of its exact bytes. Exports into one folder share those files:
- Textures are published first, then the sidecar, the
.binand the.gltflast. - An existing texture with the same bytes is reused and never rewritten; the receipt
marks it
"reused": true. A file with that name but different bytes stops the export before any model file is published. - The model files keep the never-replace rule: an existing
.gltf,.binor sidecar stops the export before any texture is written. - A failed export rolls back its model files but never removes a texture, even one it created, because a concurrent export may already reference it. A leftover texture is harmless.
The library form returns layout: 'gltf' with gltf, buffers, textures and
metadata to write, plus the equivalent embedded glb for inspection:
const output = await exportAssetGlb(record, {
profile: 'runtime',
target: 'three',
textures: 'external',
gltfFileName: 'wall.gltf',
metadataFileName: 'wall.kiln-metadata.json',
});
three.js loads the .gltf and resolves wall.bin and textures/... relative to it:
new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).loadAsync('assets/wall.gltf').
Plain --profile runtime keeps .glb only, because that profile copies the binary chunk
byte for byte. Kiln's tests validate the .gltf with gltf-validator and load it through
GLTFLoader. MCP kiln_export does not offer these options.
Measuring a set: kiln textures
The duplication is between assets, never inside one: the exporter already shares an
image an asset uses twice, so a per-asset count of distinct against embedded images is
equal on every asset Kiln has ever written. Measured over 160 assets in four real worlds,
within-asset duplicate images were 0 every time. kiln textures therefore reads a whole
delivered set:
kiln textures assets/imports # a delivery folder
kiln textures palm.glb fern.glb --json # or named files, with a receipt
49 assets · 119 embedded images · 24 distinct · 14,315,977 duplicated bytes (62.1% of 23,048,068 delivered bytes)
e29644e20915 425,509 B 512x512 image/png · 12 copies · saves 4,680,599 B · palm-a.glb, palm-b.glb, shrub-a.glb +9 more
It reads bytes and writes nothing, so it is safe to point at a frozen delivery folder.
Directories contribute their *.glb files; a named file that is not a readable GLB is
listed under skipped with the reason rather than failing the set. At most 1024 assets
are read at once. --json adds ok: true to the kiln.texture-sharing.v1 record:
assets, assetBytes, embeddedImages, distinctImages, embeddedImageBytes,
distinctImageBytes, duplicateImageBytes, and images[] — each distinct image's
sha256, bytes, mimeType, copies and the assets carrying it, largest saving
first, with width and height when the header is one Kiln reads. An image whose bytes
live in a buffer outside the GLB is not this GLB's to share, so that asset is skipped
with a reason rather than counted from the wrong bytes. The library export is textureSharingReport from
@instruktlabs/kiln/asset-export.
Worth measuring rather than assuming: across four real worlds the same mechanism saved 62.1%, 14.8%, 8.7% and 6.2% of delivered bytes. The saving is large only when the pack genuinely shares a material family, so the number that matters is the one for your set.
Pointer and hash contract
The runtime GLB contains this record in asset.extras.kilnProvenanceV1:
{
"version": "kiln.provenance.v1",
"profile": "runtime",
"metadata": {
"uri": "mech.kiln-metadata.json",
"sha256": "sha256:<64 lowercase hexadecimal characters>"
}
}
The sidecar uses version kiln.runtime-metadata.v1:
{
"version": "kiln.runtime-metadata.v1",
"source": {
"assetId": "a_example",
"revisionId": "r_example",
"glbSha256": "sha256:<canonical GLB hash>",
"sourceSha256": "sha256:<source file hash, when available>"
},
"scenes": [
{ "index": 0, "kilnReviewClipsV1": { "version": 1, "clips": [] } }
]
}
The pointer hash covers the exact UTF-8 sidecar bytes, not reserialized JSON. The
sidecar points back to the canonical input GLB hash, not the derived runtime GLB hash,
so there is no circular hash dependency. IDs and hashes let a tool locate and verify
the corresponding editable revision; they are integrity/provenance data, not signatures
or authenticated authorship. The sidecar deliberately does not embed the full manifest,
source or build record. Optional fields appear only when requested: target and
delivery with --target three, textures with --textures. In the external layout the
same record sits in the .gltf file's asset.extras.
The URI is informational, not a glTF buffer/image URI. Kiln does not automatically fetch it or execute its contents. Standard glTF playback works without the sidecar, including offline or after downloading only the GLB. A tool that explicitly reads it should verify the byte hash and version before using the data. Deploy both files together to retain the review provenance; keep the filename or regenerate the export.
An existing asset.extras.kilnProvenanceV1, or non-object asset.extras, causes runtime
export to fail instead of overwriting data. This also rejects applying runtime twice.
Export again from the canonical saved revision. An already-runtime GLB can still be
copied with the editable/default byte-preserving profile, but that does not restore
source or missing review metadata. Unknown versions of the owned review field fail
explicitly rather than being stripped.
Boundaries
Draft renders, renderGLB, kiln_render, save, collection files, editable bundles,
review tooling, and current exporter backend defaults are unchanged. Use canonical
assets for Kiln's complete review vocabulary; runtime GLBs retain only native playback
unless a separate consumer explicitly uses the sidecar. This feature is independent
of exporter backend qualification and optional geometry/texture compression.
Agent delivery checklist
- Read the request and select the profile for the actual delivery. Use the normal converter unless the task calls for an explicit experimental comparison. Report the converter actually used; changing a setting alone is not evidence of a rebuild.
- Save the accepted
programRefwithkiln_save, and retain its exact collection, asset ID and revision ID. Export that pinned revision. An existing imported GLB does not acquire editable source through either profile. - Keep the editable ZIP when source is available. For runtime delivery, save the
GLB and the named sidecar without renaming or reserializing the sidecar. The CLI
and, when the host sets an export root,
kiln_export_towrite the pair; other MCP resource delivery depends on the host's download support. - Verify that the runtime GLB loads and its native animations play independently. Verify the sidecar filename and byte hash when checking provenance. Use the canonical asset for Kiln's full review workflow; standard loaders do not fetch the sidecar or restore missing source.
- Report the files, measured sizes, checks performed and remaining limits. A smaller GLB does not establish lower draw calls, texture memory or higher frame rate.
Qualification results and repeatable local dogfood cover generated source, CLI/MCP/HTTP delivery, native playback and a full Jaeger asset.