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.

12.0 KB
Raw Blame

Kiln Engine Agent Guide

Scope

This engine turns model-authored source into GLBs: rendering, QA, primitives, agent tools, arena, scenes, CLI, MCP and skills.

Read README.md before changing exports or shipped files. src/ holds runtime/tests; scripts/ holds repo checks. package.json owns files and exports; CHANGELOG.md records releases. Dated plans and reviews are historical, never overrides of code, this guide or the changelog, and never release acceptance.

Asset authoring

This guide covers engine changes. Author assets in a separate workspace with a live kiln_workspace server: exposing engine source and examples changes model outputs. Before asset authoring, read kiln-setup-workspace and create a workspace. Its maintained copy is skills/kiln-setup-workspace/, registered at .claude/skills/ and .agents/skills/.

Feed demonstrated authoring defects back into the maintained skills at the relevant boundary: shared shape and fit guidance in skills/kiln-author-asset/references/geometry-recipes.md; destination traversal, interaction and performance evidence in the QA integration reference. Keep scene-specific controllers and asset dimensions in authored workspaces. Interactive proving environments use the optional skills/kiln-compose-scene/ workflow and its runtime-scenes reference; scene terrain, controllers and optimization derivatives never become requirements for standalone assets. Guidance changes do not retroactively qualify an existing asset or replace its owner review. Generated workspaces copy these skills; verify the copies and package contents without silently rewriting existing authors' installed instructions.

Optional projects

Standalone assets, materials and review must work without projects. Do not infer membership from nearby projects or impose pack-specific defaults. Read the selection and delivery contracts: configured KILN_PROJECT is opt-in; --no-project / projectId: null overrides it. The collection named project is only a destination. Keep skills/, registered setup copies and the generated AGENTS.md/CLAUDE.md in scripts/create-workspace.mjs aligned; qualify fresh setup and managed upgrade without overwriting user customizations.

Library and gallery assets

The Workshop Library aggregates configured asset collections; collection project is workspace storage, not project membership. Keep collection-qualified IDs through browsing, revision selection and project links. Projects pin exact saved revisions. Live Review's optional host KILN_WORK_ITEM groups one authoring item across CLI/MCP sessions; never infer it from project, model name or source equality. Explicit observation workspaces stay separate sources. Build and check viewer changes through the installed package and the actual Library/Projects/Live Review flow, not only a separate comparison page.

Gallery assets are unvetted historical showcases, not golden outputs; regression comparisons do not establish their quality.

The tool registry is the single source of truth

src/tools/registry.ts owns tool names, descriptions and schemas; src/tools/capture-input.ts states the camera shapes once and src/tools/actions.ts checks what each flat action needs. Both Strands (src/agent/tools.ts) and stdio MCP must iterate it. Never hand-write definitions in a skin. Keep the name-parity test passing. docs/tools.md is the packaged manifest, generated by scripts/generate-tool-reference.ts. Records advertised opaque (draft, patch, payload, capture, shot) are served in full by Discovery shape: entries and validated when the tool runs; src/tools/__tests__/registry-contract.test.ts holds the size and shape budgets.

The stdio executable is a thin entry: src/mcp-server.ts bundles the protocol library and src/generated/mcp-manifest.json (regenerated by the mcp build) and loads dist/mcp-engine.mjs on the first call that needs the engine; handlers and cache hints are in src/mcp-core.ts. Never import the engine statically from the entry or the core; an engine-loading problem is a tool result naming the next step, never a dead server.

createKilnProgramToolRegistry supplies the fifteen base MCP tools. The packaged local host also injects kiln_project, kiln_material and kiln_review (eighteen; KILN_EXPORT_ROOT adds kiln_export_to); embeddings advertise these only when the host services exist. createKilnNativeToolRegistry uses the same definitions and adds kiln_finish: eleven tools by default, sixteen with an injected assetLibrary (the five delivery tools; an exportRoot adds kiln_export_to). A skill-resource reader adds kiln_skill_resource to either set.

Both skins use unified kiln_render: metrics, part paths, QA, images and fidelity share one evaluation. kiln_validate is the image-free syntax check. Review results are compact by default and detail: 'full' returns the complete QA report; compaction happens at the output boundary, after the retained artifact is recorded (src/tools/review-detail.ts).

Native completion uses kiln_finish({programRef}), defined in the registry. It selects an exact retained reviewed artifact without re-evaluation; completion and QA acceptance stay separate. A completion call runs alone; immutable edits and reads may run concurrently. The MCP surface has no terminal action because its host owns the outer loop and delivery.

Strands harness guidance is registered by src/agent/native-workflow.ts, outside the shared skills/ tree. Keep its completion/recovery protocol out of CLI/MCP setup, generated workspace instructions, Discovery and shared skills. See the native workflow boundary.

Host-injected render and cache boundaries

Kiln Discovery is kiln_discover / kiln discover; helper specs and the typed catalog live under src/discovery/, and ./discovery is the public entrypoint. Search is ranked local text retrieval with reviewed metadata: no models, network, provider keys or GPU, and no semantic enhancement without an explicit adoption decision.

The engine defines the host-injected PbrRenderPort. Exported captureViewsViaPort is the single owner of the deadline, renderer/PNG validation, grid composition and never-throw CPU fallback. Do not duplicate that degrade policy in a host or add network/service knowledge to deterministic engine paths. Keep the two injection deadlines separate: the post-loop artifact sheet can wait; KilnToolContext.viewRenderPort serves the blocking in-loop kiln_render grid with a much lower per-call deadline.

Route by sceneNeedsPbrShading(root): bound texture or metalness > 0, never material type (gameMaterial and pbrMaterial both make MeshStandardMaterial). Host telemetry uses onViewsRendered; every kiln_render returns model-visible ViewFidelityV1. CPU geometry images are not material evidence. Tool definitions are prompt-cached: keep input schemas stable unless a change explicitly versions them.

review-neutral-v1 is the default review rig: a calibrated white rig with Review Neutral tone mapping, so a matte surface reads back near its authored albedo. Explicit lighting IDs stay in capture cache keys. src/views/background.ts owns the named backdrops; render-service/src/backdrops.mjs mirrors them, guarded by backdrop.test.ts, and render-service/src/display-transform.mjs makes GPU and CPU backdrop pixels match. Captures accept only neutral (default), dark or light, never free colours. Both capture-cache keys include the id; results echo capture.backdrop; kiln_save records preview.backdrop.

One render service per machine, and the socket is its registry. Sessions share port 8000 (or KILN_RENDER_SERVICE_PORT) and join only a validated compatible protocol, instance, build, dependency and capture identity. A timed-out listener is unknown, not a verified busy renderer. Stale, incompatible and foreign listeners are reported without replacement; kiln service stop is the explicit action. Managed services have a bounded idle lifetime (five minutes by default) protected by all admitted work; host exit must not kill a shared service or another client's work. Manual services stay long-lived. Service and host share render-service/src/build-identity.mjs; exact resolved dependency pins count. Do not add lease files or another discovery path. In-session kiln_renderer reprobe refreshes availability for the existing route and does not install dependencies.

Render requests are self-contained GLBs. Admission, upload time, decoded PNG allocations, geometry and scene depth are bounded before loading. Cancellation removes queued work. Propagate the optional second-argument execution signal through every PbrRenderPort wrapper, including capture caches, while deadline and CPU degradation stay in captureViewsViaPort.

The GPU is a view producer only, never gate evidence. QaContext is deliberately image-free so a QA rule structurally cannot read a render buffer. Do not add pixels to it.

src/views/renderer-id.ts calls readFileSync at MODULE LOAD. Reach CPU_RASTER_RENDERER_ID through existing lazy await import('../views') paths; static imports add a Node-only filesystem edge that no test catches.

Prompt-cache transports differ deliberately. Native Anthropic and Bedrock adapters consume a system [TextBlock, CachePointBlock]; OpenRouter-hosted Anthropic keeps plain system text and receives top-level cache_control: { type: 'ephemeral' } because its Vercel bridge drops cache-point blocks. Preserve that and the provider usage fields when changing model routing.

Toolchain and validation

Maintainer toolchain: Bun 1.4.2; Node 22.23.4; npm 12.2.0, pinned in toolchain.json. Consumer Node compatibility is defined separately in src/runtime-support.mjs and engines.node; do not add Bun or npm maintainer pins to end-user engines or use a Bun canary or implicit latest for a release gate.

bun install --frozen-lockfile
bun run check:toolchain
bun run check:skills
bun run build:runtime
node scripts/example-archive.mjs --fetch
bun run typecheck
bun run lint
bun run test
bun run test:render-service
bun run test:coverage

bun run build only typechecks. dist/ and SDK lib/ are built, not tracked: never commit them. Run bun run build:runtime on a fresh clone, after a pull and after runtime changes, before CLI/MCP dogfood and full gates. bun run test refuses a missing or stale build.

Fast loop: bun run build:runtime, nearest test file, then bun run typecheck && bun run lint && bun run test. The full offline gate adds bun run test:coverage, which emits coverage/lcov.info and enforces the line/function ratchet in bunfig.toml. Raise thresholds when practical; never lower them without a measured rationale. Live model tests are opt-in via bun run test:live.

bun run test is bun test src scripts and does not reach render-service/; run bun run test:render-service whenever you change it (CI requires it).

Private hosting: instruktlabs/kiln-hosted; public metadata: plugins/kiln-hosted/.

Tests use --timeout 20000 for cold Windows startup; a larger budget needs an explicit third test() argument with a measured-duration comment. Tests and CI pin KILN_RENDER=cpu so the coverage ratchet cannot vary with the runner's GPU; coverage is measured over src/ alone, and tests under scripts/ still run.

Use strict test-driven development for behavior changes: add a focused failing test, observe the expected failure, implement the smallest fix, and rerun both the focused and full gates. Preserve determinism: no Date.now() or Math.random() in render/rasterizer compute paths.

Safety

  • Never print, read unnecessarily, or commit provider keys, cloud credentials, .env*, or secrets.
  • Keep normal validation offline. Do not invoke live providers unless explicitly requested.
  • Do not commit, push, force-push, create remotes/releases, or publish packages without explicit user approval.
  • Live model and arena runs spend money. Keep them manual and out of CI.