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.

24.5 KB
Raw Blame

Rendering and materials

Kiln provides CPU geometry views and GPU PBR views. Use the returned viewFidelity to determine which visual conclusions a render supports.

Review an authored animation with the same sampler used by MCP:

kiln animation asset.kiln.js --clip Walk --phases 0,0.25,0.5,0.75,1 --views walk.png --render gpu --json

A saved program reference can replace the source filename. Phases are fractions of clip duration; --frames 4 selects an evenly spaced count instead. Use --camera for a named angle, --shot camera.json for one shared camera-shot object, and --framing locked|follow. --per-frame writes numbered PNGs; the JSON receipt identifies their phases, paths and material fidelity. Images show posed derivatives of the exported clip, without changing source or replacing the delivery GLB. Use --render cpu when geometry-only review is sufficient. Intermediate samples can expose contact or attachment problems but do not establish continuous collision safety. See kiln animation --help for the complete options.

Mode Use
--render auto Use GPU views for textured or metallic scenes when available; otherwise use CPU geometry views
--render cpu Deterministic geometry review without a GPU
--render gpu Require GPU rendering; report failure if unavailable
--render-port URL Select a GPU render service

CPU views show silhouette, orientation, proportion, and contact. They do not reproduce the asset's PBR materials. Translucent (opacity below 1) surfaces are composited after opaque geometry, farthest first, so parts behind glazing stay visible whatever order the scene lists them in. Use GPU views to review textures, roughness, metalness, and normal relief. GPU output can vary by device and driver.

GLB review reconstructs skins with up to four joint influences per vertex, including normalized weights and inverse bind matrices. CPU triangles and pose bounds follow the sampled joint pose rather than the undeformed position buffer. Unsupported additional influence sets produce an explicit error. GLB review also reconstructs position/normal morph deltas, node-over-mesh default weights, and STEP, LINEAR or CUBICSPLINE weight animation before applying skin transforms. Missing target attributes contribute zero displacement. Other morph semantics retain GLB_FLAT_MORPH_TARGETS_UNSUPPORTED; they are not qualified by this path. Expanded morph attributes are bounded to 64 MiB per review scene, including zero-filled attributes. Weight tracks use the review limits of 4,096 keys and 16,384 scalar values. Invalid counts and nonfinite weights/deltas are rejected. Morph primitive children receive unique binding-safe names beneath the original named node; use that parent for a stable authored-part selection. Copies have independent morph influences. Loop-closure evidence remains transform-only and reports weight tracks as unassessed rather than labeling them as scale tracks. Isolated, two-sided and composed-scene review copies own their skeletons and preserve required hidden joint ancestors as transforms without drawing their geometry. Include all referenced bones in the review root; copying an incomplete hierarchy reports the missing dependency. Geometry and textures remain shared read-only, while two-sided overrides own their materials. Qualify material-faithful derivatives separately from the whole-character CPU view.

CPU views honor front-only, back-only and double-sided source materials in both camera paths. Facing follows triangle winding after deformation, with the mesh's world-transform reflection parity; changing vertex normals does not change culling. Visible back faces reverse their flat lighting normal. Disabling culling for a diagnostic view acts as a two-sided override. Singular transforms do not flip winding; collapsed triangles do not draw. CPU output remains geometry evidence, not PBR evidence. Back-only source materials are not directly portable to GLB; see material sidedness at export.

Both CPU camera paths sample pixel centres with top-left shared-edge ownership. They evaluate all three edges directly from canonical endpoints, preventing rounding gaps and duplicate blending where adjacent triangles meet. Near/far clipping uses direction-independent intersections. Interpolation uses unbiased edge weights, including reciprocal depth for perspective cameras. This is a floating-point geometry preview, not hardware subpixel/MSAA emulation; perimeter pixels can differ from GPU views. Degenerate or nonfinite projected triangles are discarded, and raster loops stay within the output image.

Review lighting

New GPU tool captures use review-neutral-v1. The rig uses the room PMREM environment at intensity 0.4352, white hemisphere light at 1.0879, and white key/fill/rim lights at 0.136/0.0204/0.0204. The directional positions remain [4,7,5], [-4,3,2], and [-2,5,-5]; shadows remain off. Exposure is 0.9.

Review Neutral derives from the Khronos PBR Neutral construction, with glare compensation reduced from 0.04 to 0.015 for this measured rig, compression starting at 0.785 and highlight desaturation 0.15. It is a Kiln variant, not the unmodified Khronos mapper. The white lights and gentler display transform preserve base-colour hue while leaving orientation and specular cues. The analytic inverse keeps every named backdrop inside the tone-mapped pass, so clear pixels match the CPU table and silhouettes retain the existing MSAA path.

In the calibrated D3D12 chart, a key-facing metalness-0, roughness-1 panel authored as sRGB #C0362C reads (193,51,40), compared with (255,177,147) under neutral-studio-v1. Mean CIEDE2000 error over 24 ColorChecker sRGB patches plus that orange is 0.51 for the new rig, versus 28.09 for tool v1. This is a reference orientation calibration, not a promise that every shaded pixel equals its albedo. Roughness, surface orientation, reflections and the destination's lighting still change appearance. Review dark silhouettes on neutral or light when they merge with the dark backdrop. GPU images remain visual evidence only; QA receives no pixels.

Author albedo for the material and its calibrated destination; do not darken it to compensate for bright review lighting. Existing assets compensated for v1 may look too dark in the new rig and need individual material review. There is no automatic albedo conversion.

neutral-studio-v1 and gallery-studio-v1 retain their original lights and ACES exposures (1.38 and 0.9). Camera requests that already accept lightingPresetId can still select either ID; HTTP uses lighting_preset_id. Legacy direction-only requests use the new default. The website poster script continues to select gallery-studio-v1. Composer's former neutral-studio-v2 default had no renderer definition; new presentation documents now use review-neutral-v1. Saved documents naming the unsupported ID require an explicit edit; it is not aliased.

The tool input schemas and cache-key format are unchanged. An explicit lighting ID separates camera cache entries. Renderer source and dependency fingerprints also invalidate captures with an omitted lighting ID after this upgrade; old receipts retain their producer identity. Upgrade the host and renderer together. An incompatible service already on the shared socket is reported, never replaced automatically. Existing cached images remain historical evidence of their old rig.

Running the GPU renderer

render-service/ in this repository is the renderer: GLB bytes in, PBR PNG views out, headless three.js WebGPURenderer on Dawn. No browser and no X server.

Renderer code is included with Kiln. Keep optional dependencies enabled when installing the official package so its native GPU dependency can be installed at the package root. Check kiln service status before changing an installation; missing or incompatible dependencies require reinstalling Kiln with optional dependencies enabled. A source checkout uses bun install --frozen-lockfile at the repository root. Dependency readiness alone does not prove GPU/device support.

When local dependencies are available, CLI and MCP auto mode start the service lazily on the first view that needs PBR shading. A managed service is shared by compatible clients and survives the session that started it. It exits after five minutes with no admitted uploads, queued jobs or active renders. Health polling does not extend that timeout. RENDER_SERVICE_IDLE_MS configures managed idle time from 1 to 3,600,000 milliseconds.

kiln_renderer_status reads the session's renderer state and is advertised read-only, so hosts that auto-allow reads do not prompt for it. Besides the readiness fields below, it states what the next render uses: activeRoute is gpu or cpu, ready says that route can serve now, and fallback is { active: true, materialFaithful: false, reason } when views will be CPU geometry (a CPU-only host, a session that selected CPU before a service became healthy, or an attached GPU that stopped answering), otherwise { active: false }. A host that requires the GPU fails the render instead, with ready: false and no fallback. A scene that needs no PBR shading still renders on CPU over a GPU route, so the returned viewFidelity remains the evidence. kiln_renderer with action:"status" returns the same result for existing callers.

After renderer installation or repair, call kiln_renderer({action:"reprobe"}) in the existing MCP or native session. It refreshes the connection and resets a failed local startup attempt; the next view starts the service if needed. Reprobe does not install dependencies, start/stop a service, or render. It preserves the selected CPU/local/remote mode and credentials. Restart the host after changing environment variables, credentials or Kiln itself. kiln service reprobe checks readiness in its own CLI process; it cannot refresh a different running session.

kiln discover --capabilities --json and MCP kiln_discover({capabilities:true}) report renderer readiness without starting a renderer or requesting an image. Renderer selection uses an explicit --render first, then KILN_RENDER, then auto. The selected value must be auto, cpu or gpu; an invalid value names its source (--render or KILN_RENDER) in the error. An explicit valid option overrides even an invalid environment value. This applies to render/capture, generation, inspection, animation, saving and migration rebuilds. edit only edits retained source and never selects a renderer. With KILN_RENDER=cpu and no override, CLI commands neither discover nor start a render service. The CLI also reads KILN_RENDER_PORT_URL; MCP reports its session's selected route and attached port. configured describes routing, not successful rendering. on-demand means local dependencies are ready but no GPU has been tested; available means compatible health responded. authentication-required means a token is missing; authentication-unverified means one is configured but public health cannot prove it works. Unknown injected ports remain unknown. Each capability request refreshes health, while the session's route stays fixed. reprobeRequired identifies a session that can attach a newly ready renderer by calling kiln_renderer with action:"reprobe". Existing view operations keep their original connection; subsequent views use the refreshed one. Only actual returned viewFidelity establishes material evidence. CPU mode does not probe services, and ordinary Discovery searches remain offline.

The same capability response lists materials.approvedTextures as exact resource IDs grouped by allowed material slot. Placeholder swatches are excluded. Local workers report their embedded catalog; a resolver installed only in the parent process is not available to them. An external evaluator reports null unless its host declares resources. resourceEvidence: configuration-only means a resource can be requested, not that its bytes have been fetched or validated. The render still validates actual resource bytes and reports failures. Use loadApprovedTexture or materialRecipe with the listed IDs, and proceduralTexture for other surfaces.

Start it by hand from the Kiln installation root for a service that remains running even while idle:

node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs

On Windows, automatic startup uses the bundled Windows PowerShell launcher to isolate the shared renderer from shell output pipes. The CLI can then finish while the renderer remains available. Launcher failures are reported directly; if the native renderer exits during startup, use the manual command above to inspect its driver error output. Automatic startup does not capture that native stderr stream.

Managed services use port 8000 by default, or KILN_RENDER_SERVICE_PORT on the client. Set PORT to the matching value when starting a service manually. A manual start has RENDER_SERVICE_MODE=manual by default and no idle shutdown. Hosts never stop a shared service merely because their own session ends.

The socket is the registry. /health identifies the protocol, source and dependency build, capture producer, process and lifetime mode. A client joins only verified compatible health. An old, incompatible or unresponsive listener is reported and left in place; it is not treated as an available renderer or automatically replaced. The initiating PID records provenance and does not control the lifetime of other clients' work.

bun run kiln service status   # installation, health, build identity and lifetime
bun run kiln service start    # start a managed local service now, or report the current one
bun run kiln service reprobe  # fresh check; nonzero unless a running service is verified compatible
bun run kiln service stop     # explicitly stop the verified configured local service

status --json and reprobe --json print the same facts as one receipt (url, installation, listener) with the same exit codes. status and reprobe do not install packages or stop services. The old service prune command is removed. stop rechecks the configured loopback service's identity before signaling it; a remote service's reported PID never authorizes killing a local process. start uses the same launcher as an on-demand view and prints the port, renderer, process, lifetime and build fingerprint. It joins a current service rather than starting a second one, and exits nonzero without starting anything when the installation is not ready or a stale, foreign or unknown listener holds the socket; it never replaces a listener. The service it starts is managed, so it exits after its idle timeout and the next view that needs it starts it again; start one by hand, as above, for a service that stays running.

Either way it binds loopback, and widening that costs a token. POST /render takes a 48 MB GLB and renders it on the GPU one frame at a time, so an exposed bind with no auth hands any caller on that network both your GPU and a binary-asset parser. HOST widens the bind and a bind wider than loopback requires RENDER_SERVICE_TOKEN -- without one the service refuses to start rather than warning. RENDER_SERVICE_ALLOW_UNAUTHENTICATED=1 waives that when something in front of the process already authenticates for it. The container image sets HOST=0.0.0.0 itself, because a container binding loopback is unreachable through -p.

For local render services, client sessions automatically inherit RENDER_SERVICE_TOKEN as a fallback when KILN_RENDER_TOKEN is unset, whether starting on demand or joining an existing local service sharing the same environment on port 8000. KILN_RENDER_TOKEN remains the explicit client credential: set it to override the local token or to authenticate against a remote service. Explicit remote endpoints (--render-port URL or KILN_RENDER_PORT_URL) never infer credentials from RENDER_SERVICE_TOKEN and require KILN_RENDER_TOKEN directly. An explicit URL with exactly the shared local socket's origin (http://127.0.0.1:8000, or the KILN_RENDER_SERVICE_PORT port) names that socket, not another device, so it is the local route with local credentials. See the service README for deployment and authentication options.

--render cpu neither probes nor starts a service. Local auto and gpu can start one on demand; gpu requires a successful GPU result instead of accepting a CPU fallback. An explicitly selected remote URL stays remote on failure and never starts a local GPU as a substitute. A URL naming the shared local socket takes the local route instead: it joins or starts the local service on demand, and starts it again after a managed service exits idle. Use the same compatible Kiln build on the renderer device.

In auto mode, ordinary untextured scenes with zero metalness and no advanced material extensions select CPU views, even when a GPU is available. Use --render gpu to review PBR appearance for these scenes, including roughness on nonmetallic surfaces. This deliberate CPU selection is distinct from an unavailable GPU service causing degradation. Read viewFidelity, degraded and degradeReason before drawing material conclusions. Structural QA does not use image pixels.

The service accepts self-contained GLB input: embed buffers and PNG images, or use bounded base64 data URIs. External URLs and file paths are rejected before loading. PNG was already the native decoder's supported image format; JPEG, WebP, AVIF and KTX images now fail explicitly instead of losing their maps silently. PNGs are limited to 4,096 pixels per dimension and 33,554,432 decoded pixels in total. Compressed geometry extensions are not supported. GLBs are limited to 48 MiB, with additional JSON, accessor and hierarchy bounds.

Admission includes uploads, queued jobs and running work: at most eight jobs and 256 MiB of reserved input bytes. Excess admission returns HTTP 503. A stalled upload expires after 15 seconds with HTTP 408. A disconnected queued job is removed immediately; active native work finishes before its resources are released and its canceled result is discarded. These are input and scheduling limits, not a total process-memory or GPU-memory ceiling.

Materials, and where the pixels come from

Nothing in this pipeline samples an image model, textures included. There are two ways a surface gets its detail, and a model authoring an asset reaches for both in the same program.

The first is procedural: a declarative stack of layers the model writes out as data, which the engine rasterizes into a texture.

const brick = proceduralTexture({
  schemaVersion: 2,
  size: 256,
  usage: 'albedo',
  layers: [
    { op: 'bricks', brick: 0x8c4a32, mortar: 0xbfb6a8, rows: 12, cols: 6, mortarWidth: 0.08 },
    { op: 'noise', colorA: 0x000000, colorB: 0x604030, scale: 24, octaves: 4, seed: 7,
      blend: 'multiply', opacity: 0.35 },
  ],
});

const wall = pbrMaterial({ albedo: brick, normal: normalMapFromHeight(brick), roughness: 0.9 });

The layer operations are strict objects; fields from another operation are errors:

op Required fields Optional operation fields
solid color —
checker colorA, colorB squares
stripes colorA, colorB count, angleDeg
gradient from, to angleDeg
bricks brick, mortar rows, cols, mortarWidth, stagger
noise colorA, colorB scale, octaves, seed
cellular colorA, colorB cellsX, cellsY, seed, jitterX, jitterY, metricX, metricY, weight, feature, range, borderOpen, borderWidth, facetSlope, facetBlend

Every layer also accepts blend (normal, multiply, screen, or overlay) and opacity from 0 to 1. Pattern counts are integers from 1 to 256; noise octaves are 1 to 6. Seeded noise is tileable and reproducible. Call kiln_discover({ ids: ["proceduralTexture"] }) to retrieve this contract and an executable example.

Cellular layers

cellular is a periodic Worley (Voronoi) field that tiles exactly, because it wraps the cell index rather than the sample point. Use it for anything made of separate pieces: stones, crystals, cracked rock. kiln_discover({ ids: ["recipe:cellular-stone-v1"] }) has a worked fractured-rock program with rubble and granite adaptations.

Distances are in cell units, where one cell is 1 × 1 whatever cellsX and cellsY make it in UV. A cell's point sits in the box 0.5 ± jitter/2 on each axis, and the distance to it is sqrt((metricX·dx)² + (metricY·dy)²) + w.

Field Range and default Meaning
cellsX, cellsY 1 to 256, default 8 Cells per tile on each axis
seed signed 32-bit, default 0 Draws every cell's values
jitterX, jitterY 0 to 1, default 1 How far a point strays. Low jitterY keeps cells in rows
metricX, metricY 1 to 4, default 1 A larger metric flattens borders against that axis and thins the joints that cross it
weight 0 to 1, default 0 Upper limit of an additive per-cell weight drawn from the seed. It curves borders and varies cell size
feature default f1 What maps onto colorA→colorB, below
range 0.01 to 8, default 1 f1, f2, f2-f1, cell: the value that reaches colorB
borderOpen 0 to 1, default 0.5 border: fraction of borders that are open
borderWidth 0.001 to 1, default 0.05 border: width in distance units
facetSlope 0 to 1, default 0.5 facet: how far each cell's plane can tilt
facetBlend 0.001 to 1, default 0.1 facet: how far a plane reaches across its border
feature Value in 0..1
f1, f2 Distance to the nearest and second nearest cell point, divided by range
f2-f1 Their difference divided by range: 0 on a border, rising into the cell. It is not a true Euclidean distance
cell One flat random tone per cell, divided by range. A range below 1 saturates most cells at colorB, which leaves a sparse population: range: 0.16 keeps about a sixth of the cells toned
border 1 at the centre of an open border, falling to 0 at borderWidth. Open borders are chosen by a hash of the two cell ids in either order, so both sides agree, and a crack can end where it meets a closed border
facet A tilted plane per cell, for height. It blends over every cell within facetBlend of the nearest, so it has no step anywhere, including near corners

A field the chosen feature ignores is an error rather than something silently dropped, which keeps one meaning to each recipe hash. Reuse one layout object and seed across the layers and maps of a material so that its tone, joints and height line up.

cell has hard edges with no antialiasing. A flat tone change with no joint over it reads as a pasted patch close up, so keep contrast low between cells that share a closed border, or raise the size. A closed isotropic net reads as crazy paving, however exact it is: review on the GPU route, and use low jitterY, a metricY above 1 and a borderOpen below 1 to get bedded rock.

The search is exact for every seed. A sample's own point is at most (1 + jitter)/2 away on an axis, and a neighbour on the nearer side at most 1 + jitter/2, so those two cells bound F2 from above. An image k rings out is at least k - (1 + jitter)/2 away, scaled by that axis' metric, and weights only add. The search radius is the first ring whose lower bound reaches F2's upper bound, extended by facetBlend for facet: two rings at the default, and at most seven rings by two at the extremes. Full jitter makes the usual 3 × 3 window miss true neighbours. Tests hold this against an unbounded search, including layouts with every point planted at an extreme of its box.

Golden pixel hashes pin each feature. A V2 recipe hash has no compiler id, so changing this algorithm would move pixels under an unchanged hash: a change in behaviour needs a new field or op, not a new pin. V2 has size and layer limits but no work budget. Through V3 legacy-v2, a cellular layer is charged its own cost; see admission.

The bundled scanned library contains Poly Haven CC0 material families with recorded provenance. Use catalog IDs rather than file paths or URLs. Assets embed their textures and do not fetch them at runtime.

Procedural layers suit regular patterns such as brickwork and painted stripes. Scanned materials can provide irregular surfaces such as bark, soil, or leather. Choose based on the requested appearance and check the result in a material-faithful view.