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
/** Project and material commands use the same immutable services as MCP and the local dashboard. */
import { open } from 'node:fs/promises';
import { resolve } from 'node:path';
import { FileWorkspace, localWorkspaceRoot } from './workspace-node';
import { MAX_PROJECT_BYTES } from './projects';
import { createKilnProjectDef } from './tools/projects';
import { createKilnMaterialDef } from './tools/materials';
import { MATERIAL_LIBRARY_LIMITS, materialLibraryPortableSpec } from './material-library';
import {
createMaterialLibraryPayload,
decodeMaterialLibraryPayload,
resolveMaterialRecordClosure,
} from './material-library-node';
import { createProceduralMaterialRecord } from './material-authoring-node';
import { exportMaterialMaps, validateMaterialMapExportOptions } from './material-map-export-node';
import { buildRenderPort, resolveRenderMode } from './cli-render-mode';
import { writeNewDestinationsAtomic } from './cli-output';
import { localAssetLibrary } from './assets-node';
import { exportWorkspaceProjectBundle, importWorkspaceProjectBundle } from './project-bundle-node';
import { PROJECT_BUNDLE_LIMITS } from './project-bundle';
export const PROJECT_USAGE = `
PROJECTS
kiln project list
kiln project get <id> [--revision <revision>]
kiln project create --name <name> [--id <id>]
kiln project create --file <project-draft.json>
kiln project update <id> --expected <revision> --file <project-patch.json>
kiln project export <id> --out <project.zip> [--revision <revision>] [--profile editable|runtime]
kiln project import <project.zip> --id <new-project-id> --collection <collection> [--name <name>]
kiln project check <id> [--revision <revision>]
MATERIALS
kiln material presets [--tag <tag>]
kiln material create-preset --file <preset-options.json>
kiln material list
kiln material get <id> <sha256:revision>
kiln material procedural --file <procedural-material-draft.json> [--parent <sha256:revision>]
kiln material import --file <portable-material-payload.json>
kiln material export <id> <sha256:revision> --out <portable-material-payload.json>
kiln material export <id> <sha256:revision> --maps <dir> --size <px> [--repeat <metres>]
[--tiles <n>] [--render auto|cpu|gpu]
Project changes create immutable revisions. Updates require the current expected
revision; supplied top-level fields replace their previous values.
Material imports verify embedded map bytes and provenance. Procedural creation
uses a JSON recipe with explicit creator/license records. These commands do not
fetch source URLs or read paths from imported JSON.
Legacy recipes retain their existing behavior. Opt-in schemaVersion 2 drafts
add explicit samplers and RGBA or named atlas recipes. Atlas sources pin exact
saved material revisions; export carries the complete verified dependency closure.
Project and material storage is under <workspace>/.kiln. KILN_WORKSPACE selects the
workspace. KILN_PROGRAM_STORE overrides only the source store when both are set.
Without KILN_WORKSPACE, its grandparent remains the workspace root for compatibility.
Projects are optional. Authoring stays standalone unless --project or KILN_PROJECT
selects a project; --no-project overrides that configured default. Use --materials
with an array of exact resourceId/revisionId/sha256 pins for standalone materials.
All commands return JSON; export refuses to overwrite an existing destination.
Project check composes the inventory items that state a placement, at their exact pinned
revisions, and reports parts of different modules that share volume or where an open surface
reaches inside a neighbour. An item with no placement is not composed. A placed item it cannot
read is reported unmeasured rather than clear. Findings are measurements, not verdicts, so the
command exits 0 with them.
Material export --maps writes <id>.<slot>.png for each map at --size pixels square,
<id>.preview.png (the material on a lit plane repeated --tiles × --tiles, default 3)
and the <id>.maps.json sidecar: each map's slot, colour space, size, sha256 and how it
was produced. A V2 layer recipe is recompiled at a power-of-two size up to 1024; other
sizes resample with a wrapped Catmull-Rom filter. --repeat is the real-world edge of one
tile in metres; it defaults to a square recorded physical size. The sidecar records the
preview's renderer and viewFidelity: a CPU preview shows geometry, not material.
`;
/** Read only the file the operator explicitly named, with a hard allocation bound. */
async function inputFile(path: string, limit: number): Promise<Buffer> {
const file = await open(resolve(path), 'r');
try {
const stat = await file.stat();
if (!stat.isFile()) throw new Error('Expected a regular file');
if (stat.size > limit) throw new Error(`File exceeds ${limit} bytes`);
// A bounded read also protects against a file that grows after stat.
const buffer = Buffer.alloc(Math.min(stat.size + 1, limit + 1));
let offset = 0;
while (offset < buffer.length) {
const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, offset);
if (!bytesRead) break;
offset += bytesRead;
}
if (offset > stat.size || offset > limit) throw new Error('File changed while reading');
return buffer.subarray(0, offset);
} finally {
await file.close();
}
}
async function jsonFile(path: string, limit: number): Promise<unknown> {
return JSON.parse((await inputFile(path, limit)).toString('utf8').replace(/^\uFEFF/, ''));
}
/** `material export --maps`: a strict decimal reading, then the SDK's own range checks. */
/** `--parent` sets a draft's parent, as `kiln save --parent` does; it never overrides a different one. */
function withParentFlag(draft: unknown, parent: string | undefined): unknown {
if (!parent || !draft || typeof draft !== 'object' || Array.isArray(draft)) return draft;
const stated = (draft as { parentRevision?: unknown }).parentRevision;
if (stated !== undefined && stated !== parent)
throw new Error(
`--parent ${parent} disagrees with the draft's parentRevision ${String(stated)}`,
);
return { ...draft, parentRevision: parent };
}
async function exportMaterialMapsCommand(
materials: FileWorkspace['materials'],
positional: readonly string[],
flags: Record<string, string>,
): Promise<unknown> {
const integer = (name: string) => {
const value = flags[name];
if (value === undefined) return undefined;
if (!/^[0-9]+$/.test(value)) throw new Error(`--${name} must be a whole number`);
return Number(value);
};
const size = integer('size');
if (size === undefined) throw new Error('material export --maps requires --size <px>');
const repeat = flags.repeat;
if (repeat !== undefined && !/^(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)$/.test(repeat))
throw new Error('--repeat must be a decimal number of metres');
const tiles = integer('tiles');
// Validate every option before reading the record or starting a renderer.
validateMaterialMapExportOptions({
size,
...(repeat !== undefined ? { repeatMeters: Number(repeat) } : {}),
...(tiles !== undefined ? { tiles } : {}),
});
const record = await materials.read(positional[0]!, positional[1]!);
const context = await buildRenderPort(resolveRenderMode(flags.render), undefined);
const result = await exportMaterialMaps(record, {
outDir: flags.maps!,
size,
...(repeat !== undefined ? { repeatMeters: Number(repeat) } : {}),
...(tiles !== undefined ? { tiles } : {}),
...(context.viewRenderPort ? { viewRenderPort: context.viewRenderPort } : {}),
...(context.viewRenderTimeoutMs ? { viewRenderTimeoutMs: context.viewRenderTimeoutMs } : {}),
...(context.viewRenderRequired ? { viewRenderRequired: true } : {}),
});
const { preview } = result.sidecar;
return {
materialId: result.sidecar.material.materialId,
revisionId: result.sidecar.material.revisionId,
directory: result.directory,
sidecar: result.sidecarPath,
files: result.files,
size: result.sidecar.size,
repeatMeters: result.sidecar.repeatMeters,
maps: result.sidecar.maps.map(({ slot, file, colorSpace, method }) => ({
slot,
file,
colorSpace,
method,
})),
preview: {
file: result.previewPath,
rendererId: preview.rendererId,
materialFaithful: preview.viewFidelity.materialFaithful,
delivered: preview.viewFidelity.delivered,
...(preview.viewFidelity.degradeReason
? { degradeReason: preview.viewFidelity.degradeReason }
: {}),
},
};
}
/** The `kiln_project` call behind each CLI action that is not a bundle transfer. */
async function projectToolCall(
action: string,
positional: readonly string[],
flags: Readonly<Record<string, string>>,
): Promise<unknown> {
if (action === 'list') return { action: 'list' };
if (action === 'get' || action === 'check')
return {
action,
projectId: positional[0],
...(flags.revision ? { revisionId: flags.revision } : {}),
};
if (action === 'create') {
if (flags.file && (flags.name || flags.id))
throw new Error('Use --file or --name with optional --id, not both');
if (!flags.file && !flags.name) throw new Error('project create requires --file or --name');
return {
action: 'create',
draft: flags.file
? await jsonFile(flags.file, MAX_PROJECT_BYTES)
: { name: flags.name, ...(flags.id ? { projectId: flags.id } : {}) },
};
}
if (!flags.file || !flags.expected)
throw new Error('project update requires --expected and --file');
return {
action: 'update',
projectId: positional[0],
expectedRevision: flags.expected,
patch: await jsonFile(flags.file, MAX_PROJECT_BYTES),
};
}
export async function projectMain(argv: readonly string[]): Promise<number> {
const [family, action] = argv;
if (argv.some((value) => value === '--help' || value === '-h')) {
console.log(PROJECT_USAGE);
return 0;
}
if (family !== 'project' && family !== 'material')
throw new Error('Expected project or material command');
const supported =
family === 'project'
? ['list', 'get', 'create', 'update', 'export', 'import', 'check']
: ['list', 'get', 'procedural', 'import', 'export', 'presets', 'create-preset'];
if (!action || !supported.includes(action))
throw new Error(`Unknown ${family} action. Run kiln ${family} --help.`);
const allowed: Record<string, string[]> = {
'project:list': [],
'project:get': ['revision'],
'project:create': ['file', 'name', 'id'],
'project:update': ['file', 'expected'],
'project:export': ['out', 'revision', 'profile'],
'project:import': ['id', 'collection', 'name'],
'project:check': ['revision'],
'material:list': [],
'material:presets': ['tag'],
'material:create-preset': ['file'],
'material:get': [],
'material:procedural': ['file', 'parent'],
'material:import': ['file'],
'material:export': ['out', 'maps', 'size', 'repeat', 'tiles', 'render'],
};
const flags: Record<string, string> = {};
const positional: string[] = [];
for (let index = 2; index < argv.length; index++) {
const value = argv[index]!;
if (!value.startsWith('--')) {
positional.push(value);
continue;
}
const key = value.slice(2);
if (!allowed[`${family}:${action}`]!.includes(key))
throw new Error(`Unsupported option ${value} for ${family} ${action}`);
if (Object.hasOwn(flags, key)) throw new Error(`Duplicate option ${value}`);
const next = argv[++index];
if (!next || next.startsWith('--')) throw new Error(`Missing value for ${value}`);
flags[key] = next;
}
const expectedArgs =
action === 'get' || action === 'export' || action === 'check'
? family === 'project'
? 1
: 2
: action === 'update' || (action === 'import' && family === 'project')
? 1
: 0;
if (positional.length !== expectedArgs)
throw new Error(
`${family} ${action} requires ${expectedArgs} positional argument${expectedArgs === 1 ? '' : 's'}`,
);
const workspace = new FileWorkspace(localWorkspaceRoot());
const store = workspace.projects;
if (family === 'project') {
if (action === 'export') {
if (!flags.out) throw new Error('project export requires --out');
const profile = flags.profile ?? 'editable';
if (profile !== 'editable' && profile !== 'runtime')
throw new Error('Project profile must be editable or runtime');
const bytes = await exportWorkspaceProjectBundle(
workspace,
localAssetLibrary(),
positional[0]!,
{ revisionId: flags.revision, profile },
);
const path = resolve(flags.out);
await writeNewDestinationsAtomic([{ path, data: bytes }]);
console.log(JSON.stringify({ ok: true, profile, path, bytes: bytes.length }));
return 0;
}
if (action === 'import') {
if (!flags.id || !flags.collection)
throw new Error('project import requires a new --id and explicit --collection');
const project = await importWorkspaceProjectBundle(
workspace,
localAssetLibrary(),
await inputFile(positional[0]!, PROJECT_BUNDLE_LIMITS.maxArchiveBytes),
{ projectId: flags.id, collectionId: flags.collection, name: flags.name },
);
console.log(JSON.stringify({ ok: true, project }, null, 2));
return 0;
}
const tool = createKilnProjectDef(store, undefined, localAssetLibrary());
console.log(
JSON.stringify(await tool.run(await projectToolCall(action, positional, flags)), null, 2),
);
return 0;
}
const materials = workspace.materials;
let output: unknown;
if (action === 'presets')
output = await createKilnMaterialDef(materials).run({
action: 'presets',
...(flags.tag ? { tag: flags.tag } : {}),
});
else if (action === 'create-preset') {
if (!flags.file) throw new Error('material create-preset requires --file');
const input = await jsonFile(flags.file, MATERIAL_LIBRARY_LIMITS.maxManifestBytes);
if (!input || typeof input !== 'object' || Array.isArray(input))
throw new Error('Preset options must be a JSON object');
output = await createKilnMaterialDef(materials).run({ ...input, action: 'create-preset' });
} else if (action === 'list')
output = await createKilnMaterialDef(materials).run({ action: 'list' });
else if (action === 'get' || action === 'export') {
const manifest =
action === 'get'
? (await materials.read(positional[0]!, positional[1]!)).manifest
: await materials.readManifest(positional[0]!, positional[1]!);
if (action === 'get')
output = {
manifest,
portableSpec: materialLibraryPortableSpec(manifest),
};
else if (flags.maps !== undefined) {
if (flags.out) throw new Error('Use --out or --maps, not both');
output = await exportMaterialMapsCommand(materials, positional, flags);
} else {
for (const name of ['size', 'repeat', 'tiles', 'render'])
if (flags[name] !== undefined)
throw new Error(`--${name} applies only to material export --maps`);
if (!flags.out) throw new Error('material export requires --out or --maps');
const records = await resolveMaterialRecordClosure([manifest], {
readManifest: (id, revision) => materials.readManifest(id, revision),
read: (id, revision) => materials.readRecordFiles(id, revision),
});
const payload = await createMaterialLibraryPayload(records);
const path = resolve(flags.out);
await writeNewDestinationsAtomic([{ path, data: JSON.stringify(payload, null, 2) }]);
output = {
file: path,
materialId: manifest.materialId,
revisionId: manifest.revisionId,
};
}
} else {
if (!flags.file) throw new Error(`material ${action} requires --file`);
const input = await jsonFile(
flags.file,
action === 'procedural' ? MATERIAL_LIBRARY_LIMITS.maxManifestBytes : 24 * 1024 * 1024,
);
if (action === 'procedural') {
const { record, dependencies } = await createProceduralMaterialRecord(
withParentFlag(input, flags.parent),
materials,
);
output = {
materials: await materials.import(
[record],
dependencies.length ? { materials: dependencies } : undefined,
),
};
} else
output = { materials: await materials.import(await decodeMaterialLibraryPayload(input)) };
}
console.log(JSON.stringify(output, null, 2));
return 0;
}