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.

8.2 KB
Raw Blame

Kiln website

The public documentation, gallery, asset packs and interactive scenes live at kilnstudio.tools. This is a static Astro site on Cloudflare Pages. The separate hosted MCP application is open at kiln.instruktlabs.com for an introductory ten-account, invite-only launch. Request access through Discord.

Develop and check

Use the maintainer versions in ../toolchain.json, with the pinned Node on PATH. The media pipeline also needs an installed Chrome or Chromium.

node scripts/example-archive.mjs --fetch
cd scenes
bun install --frozen-lockfile
cd ../site
bun install --frozen-lockfile
bun run test
bun run assets
bun scripts/build-skills-discovery.mjs
bun run build
bun run preview

bun run build fetches SHA-256-pinned public assets and scene archives, creates media, builds the site and checks its output. It makes no model calls and deploys nothing. Generated downloads and build output remain ignored. bun run dev starts the Astro development server; stage the required scene/media inputs with a build first. The engine's root bun run lint also covers site source.

For a smaller documentation build, set KILN_SITE_PACKS=0; do not describe that build as qualifying the gallery or scenes. Release checks use packs enabled.

Where changes belong

Content Source
Installation and API guides ../docs/; src/lib/docs-navigation.ts selects published pages
npm release identity and install command ../.github/published-candidate.json and src/lib/config.ts
Homepage src/pages/index.astro
Featured worlds and individual assets src/data/site-curation.json; shared by homepage, scenes, packs and gallery
Gallery categories, tags and introduction dates src/data/gallery-taxonomy.json, keyed by canonical asset page
Asset, modular kit and scene sequence src/components/AssetToScene.astro, src/data/asset-to-scene.json and pinned files under public/workflow/
Gallery, packs and download records src/data/packs/, src/data/standalone/ and sealed delivery manifests
Historical gallery programs and credits Pinned Git history restored to ../.cache/example-archive/ by ../scripts/example-archive.mjs
Maintained scene source ../scenes/packages/
Scene archives and media src/data/scene-packs.json, scene-inputs.json and troy-delivery.json
Shared layout, navigation and style src/layouts/BaseLayout.astro, src/styles/global.css

The docs loader renders repository Markdown directly. Relative links resolve to published guides or repository files; do not maintain a second installation guide inside an Astro template. Include new public guides in the navigation allowlist. The build generates the agent-readable llms.txt and skills discovery index from the same maintained sources.

Version labels, release/download links and share cards read the same verified publication record used by package CI. Update that record after verifying a registry publication; no separate site version edit is needed. An unreleased checkout must label its new features accordingly. Package promotion and static website deployment are separate release steps.

Assets and scenes

The homepage, scene listing and pack listing lead with the curated Holodeck worlds. Earlier scenes and packs remain available below them. Change the explicit selections in site-curation.json to promote work; catalog import order is not presentation order. src/lib/site-curation.ts selects the cover from each world's recorded captures, and share cards use the same lead world.

Gallery categories describe the asset across packs. Keep scene-specific groups in their source catalogs, and maintain shared categories and search tags in gallery-taxonomy.json. Every current gallery page needs a record; missing records fail the build. addedOn is the date the asset first entered the committed catalog, not when it was authored or publicly released. Revisions and refreshed posters do not change that date. Featured sorting promotes the selected assets, then uses newest first with alphabetical ties. Filters and sorting are shareable URL parameters.

The repository README keeps only a small scene selection and live-game examples. Run node scripts/readme-showcase.mjs from site/ to regenerate its stills from the hash-verified captures named in ../assets/readme/selection.json. README views and widths are curated independently of the website's cover choices. Collage tiles use matching 16:9 frames; each selection can set its crop position. The generated ../assets/readme/holodeck-showcase.json records their source and output hashes.

The homepage uses one sequence: a Winter Cabin wall asset, its modular architecture kit assembling, its living floor and loft being furnished in cutaway views, then a capture of the finished Holodeck scene. The assembly uses 40 saved asset types and 173 placements from the catalog's exact world snapshot. Keep capture work in a separate workspace. Retain web/manifest.json (module revisions, model hashes, placements, world hash and scene capture record), the models under web/models/, web/scene.webp, wall.kiln.js, the capture page and web/captures/property/{frame-0000.png,...,proof.json}. The property film capture renders 1,020 fixed-time frames for a 34-second sequence at 30 fps. Its shot plan records the asset introduction, camera pullback, architecture assembly, living floor, a lower room tour, the staircase building upward, sleeping loft and final scene. The 17 interior treads and railings remain hidden during the living-room shots; they build with the loft landing afterward. Assets reveal in place through clipping groups, with clipped shadows and unchanged scale. Slow camera moves allow time to inspect the completed rooms. Run node scripts/stage-asset-to-scene.mjs WORKSPACE/kit from site/ with FFmpeg and FFprobe available. Intake checks the placed revisions against the catalog, model and source hashes, world identity, the complete frame sequence, encoded frame rate and WebGPU capture evidence. It stages one MP4, a GIF, a poster and the wall source at a content-addressed path. The workflow tests verify the staged files and the single-player presentation.

Public packs have source records under ../packs/; five runnable scenes have source under ../scenes/packages/. Large binaries are downloaded explicitly from Cloudflare R2. Follow the asset source guide to hydrate editable revisions and the scene guide to rebuild runtimes.

Normal builds consume the selected sealed deliveries. Changed media, models or runtime bundles need a new immutable release identity and matching checksums; never overwrite an existing delivery. A build does not confer owner acceptance on an asset. Keep its recorded revision, attribution and review status intact.

Gallery posters are single views, separate from saved multi-view review sheets. The shared scripts/rig-posters.mjs renderer records their exact model hashes, revisions, cameras and review rig in src/data/rig-posters.json. Staging must reuse these records rather than assigning a saved preview.png to poster. For Cabin, stage a preview delivery first, then run:

bun scripts/rig-posters.mjs cabin-woods-psx-horror --mirror /path/to/mirror
node scripts/fetch-mirror.mjs

This renders the staged runtime models, pins the new images and plans responsive variants. Public Cabin staging requires a matching poster for every asset and preserves the original review sheets and editable downloads. Uploading new mirror files and deploying the site remain separate release steps.

Deploy

Follow DEPLOYMENT.md to qualify an exact build and obtain the owner's deployment approval. The production Pages project is kilnstudio, branch production; downloads use kiln-assets. GitHub checks do not deploy the site. Use build-info.json and artifact-files.json to identify the actual served build instead of relying on a dated README checkpoint.

Earlier site rollout records and asset-staging procedures are preserved in the historical checkpoint archive. They retain their original candidate scope and are not current release acceptance.