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
Curate README with four matching scene captures (#285)
Matthew Kissingerd63206cf221f
diff --git a/README.md b/README.mdindex 79719550..4674b03b 100644--- a/README.md+++ b/README.md@@ -20,10 +20,49 @@ do not require a separate model API key.[Interactive scenes](https://kilnstudio.tools/scenes/) ·[Changelog](CHANGELOG.md)+## Made with Kiln++<table>+ <tr>+ <td width="50%" align="center">+ <a href="https://holodeck.kilnstudio.tools/worlds/meridian-sanctuary/"><img src="assets/readme/meridian-sanctuary.webp" alt="A marble causeway between mirror pools leading to Meridian Sanctuary's gate tower"></a><br>+ <a href="https://holodeck.kilnstudio.tools/worlds/meridian-sanctuary/"><strong>Meridian Sanctuary</strong></a>+ </td>+ <td width="50%" align="center">+ <a href="https://holodeck.kilnstudio.tools/worlds/crescent-cove/"><img src="assets/readme/crescent-cove.webp" alt="The canopied Cove seat among palms overlooking Crescent Cove's lagoon"></a><br>+ <a href="https://holodeck.kilnstudio.tools/worlds/crescent-cove/"><strong>Crescent Cove</strong></a>+ </td>+ </tr>+ <tr>+ <td width="50%" align="center">+ <a href="https://holodeck.kilnstudio.tools/worlds/winter-mountainside-cabin/"><img src="assets/readme/winter-mountainside-cabin.webp" alt="The timber cabin with its glazed gable, deck and stair among snow-covered firs and spruces"></a><br>+ <a href="https://holodeck.kilnstudio.tools/worlds/winter-mountainside-cabin/"><strong>Winter Mountainside Cabin</strong></a>+ </td>+ <td width="50%" align="center">+ <a href="https://kilnstudio.tools/scenes/golden-gate/"><img src="assets/readme/golden-gate.webp" alt="A blue sedan driving across Golden Gate Bridge, with traffic, suspension cables and a red tower ahead"></a><br>+ <a href="https://kilnstudio.tools/scenes/golden-gate/"><strong>Golden Gate</strong></a>+ </td>+ </tr>+</table>++Holodeck provides the runtime for Meridian Sanctuary, Crescent Cove and Winter+Mountainside Cabin; Kiln provides their editable assets and GLBs. Golden Gate is+one of the bundled interactive scenes.++Editable assets: [Meridian (53)](https://kilnstudio.tools/packs/holodeck/meridian-sanctuary/) ·+[Crescent Cove (49)](https://kilnstudio.tools/packs/holodeck/crescent-cove/) ·+[Winter Cabin (56)](https://kilnstudio.tools/packs/holodeck/winter-mountainside-cabin/) ·+[Golden Gate bridge](https://kilnstudio.tools/gallery/golden-gate-bridge/).++[Explore all scenes](https://kilnstudio.tools/scenes/) or+[browse the asset gallery](https://kilnstudio.tools/gallery/).+Scene code and asset content retain their own licences; each pack records its scope.+## From asset to sceneOne timber wall becomes part of a modular cabin kit. Assemble its floors, walls-and roof, furnish the kitchen and living room, then build the staircase, sleeping loft, bed and desk.+and roof, furnish the kitchen and living room, then build the staircase,+sleeping loft, bed and desk.The finished Winter Mountainside Cabin sits in a snowy Holodeck world.[](https://kilnstudio.tools/#workflow)@@ -31,25 +70,6 @@ The finished Winter Mountainside Cabin sits in a snowy Holodeck world.The assembly visualizes the saved Kiln modules; the final view is captured inHolodeck. Both use WebGPU rendering.-## Explore worlds made with Kiln--Walk these scenes on [Holodeck](https://holodeck.kilnstudio.tools/), then inspect-or remix the Kiln assets they use. Holodeck provides the world runtime; Kiln provides-editable asset source and GLBs.--| Meridian Sanctuary | Crescent Cove | Winter Mountainside Cabin |-| --- | --- | --- |-| [](https://holodeck.kilnstudio.tools/worlds/meridian-sanctuary/) | [](https://holodeck.kilnstudio.tools/worlds/crescent-cove/) | [](https://holodeck.kilnstudio.tools/worlds/winter-mountainside-cabin/) |--- **[Meridian Sanctuary](https://holodeck.kilnstudio.tools/worlds/meridian-sanctuary/):** marble arcades, mirror pools and floating sculpture. [53 assets and editable source](https://kilnstudio.tools/packs/holodeck/meridian-sanctuary/).-- **[Crescent Cove](https://holodeck.kilnstudio.tools/worlds/crescent-cove/):** tropical planting, coastal rock formations and a beach shelter. [49 assets and editable source](https://kilnstudio.tools/packs/holodeck/crescent-cove/).-- **[Winter Mountainside Cabin](https://holodeck.kilnstudio.tools/worlds/winter-mountainside-cabin/):** timber architecture, a furnished interior and snowy forest. [56 assets and editable source](https://kilnstudio.tools/packs/holodeck/winter-mountainside-cabin/).--[Explore all scenes](https://kilnstudio.tools/scenes/), including Troy, Farm,-Golden Gate, Foundry Floor and Cabin in the Woods, or-[browse the asset gallery](https://kilnstudio.tools/gallery/).-Scene code and asset content retain their own licences; each pack records its scope.-## Used in live gamesI build Sheepdog Sim, OBJEKT 62 and ski sim alongside Kiln, and use these gamesdiff --git a/assets/readme/golden-gate.webp b/assets/readme/golden-gate.webpnew file mode 100644index 00000000..5c835dd1Binary files /dev/null and b/assets/readme/golden-gate.webp differdiff --git a/assets/readme/holodeck-showcase.json b/assets/readme/holodeck-showcase.jsonindex 0b47ebe4..7b851fb9 100644--- a/assets/readme/holodeck-showcase.json+++ b/assets/readme/holodeck-showcase.json@@ -9,7 +9,11 @@"inputSha256": "3e8fe557bd28f440fab434f2fbd8f6800a8e6f35a608805069641a9fe3cc2de0","sha256": "df85d99367280e2fd96ddc1f77ab2fc88074fab0105989e7ddf6c3781b7214c1","width": 960,- "height": 540+ "height": 540,+ "framing": {+ "fit": "cover",+ "position": "centre"+ }},{"file": "crescent-cove.webp",@@ -20,18 +24,41 @@"inputSha256": "d543c038bc8086daeea22418baadbe554103f019f4209401f71b3f0fc15636c7","sha256": "18f101c8e69c45ce915eac28ac939ee97f1141b7bf7307ddc340c2e26fc88c9c","width": 960,- "height": 540+ "height": 540,+ "framing": {+ "fit": "cover",+ "position": "centre"+ }},{"file": "winter-mountainside-cabin.webp",- "alt": "The cabin’s living room: a sofa and armchair around the stone hearth, the loft stair and warm lantern light.",+ "alt": "The timber cabin with its glazed gable, deck and stair among snow-covered firs and spruces.","world": "https://holodeck.kilnstudio.tools/worlds/winter-mountainside-cabin/",- "view": "winter-mountainside-cabin-living",- "inputPath": "media/holodeck/scenes/dae991ffbe47771af0848295ef0a811d3d004809dcff0f4236b41879795e9ddb/winter-mountainside-cabin-living.png",- "inputSha256": "dae991ffbe47771af0848295ef0a811d3d004809dcff0f4236b41879795e9ddb",- "sha256": "82504dba41c2f493cdd4657ef28859a206a14bd544eb9767fcd76fd7705860ae",+ "view": "winter-mountainside-cabin-exterior",+ "inputPath": "media/holodeck/scenes/ae68557825df539a540e6054192ac1625bf87f19402b0a00b240334bf44a57bd/winter-mountainside-cabin-exterior.png",+ "inputSha256": "ae68557825df539a540e6054192ac1625bf87f19402b0a00b240334bf44a57bd",+ "sha256": "1deb821d1a9590f9e97db19c580fe325c49071df40a11293795202b62c55fdac","width": 960,- "height": 540+ "height": 540,+ "framing": {+ "fit": "cover",+ "position": "centre"+ }+ },+ {+ "file": "golden-gate.webp",+ "alt": "A blue sedan driving across the deck of the Golden Gate Bridge scene, with traffic around it and both towers ahead.",+ "world": "https://kilnstudio.tools/scenes/golden-gate/",+ "view": "drive",+ "inputPath": "media/scenes/golden-gate/g9-code5/golden-gate-scene-drive.png",+ "inputSha256": "487793596f730d5424c1b25016fbc27408d6d2ab707c57343acbbc6a52b1bc56",+ "sha256": "506c1d12e86d3333030db7affe525e408b7ac04ced80f08879234db0367e250e",+ "width": 960,+ "height": 540,+ "framing": {+ "fit": "cover",+ "position": "south"+ }}]}diff --git a/assets/readme/selection.json b/assets/readme/selection.jsonnew file mode 100644index 00000000..0110e340--- /dev/null+++ b/assets/readme/selection.json@@ -0,0 +1,6 @@+[+ { "worldId": "holodeck-meridian-sanctuary", "view": "meridian-sanctuary-arrival", "width": 960 },+ { "worldId": "holodeck-crescent-cove", "view": "crescent-cove-cove", "width": 960 },+ { "worldId": "holodeck-winter-mountainside-cabin", "view": "winter-mountainside-cabin-exterior", "width": 960 },+ { "worldId": "golden-gate", "view": "drive", "width": 960, "position": "south", "url": "https://kilnstudio.tools/scenes/golden-gate/" }+]diff --git a/assets/readme/winter-mountainside-cabin.webp b/assets/readme/winter-mountainside-cabin.webpindex 3db7a588..1ba28506 100644Binary files a/assets/readme/winter-mountainside-cabin.webp and b/assets/readme/winter-mountainside-cabin.webp differdiff --git a/site/README.md b/site/README.mdindex cf782363..3a33ff7d 100644--- a/site/README.md+++ b/site/README.md@@ -79,7 +79,10 @@ newest first with alphabetical ties. Filters and sorting are shareable URL paramThe 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 of the featured worlds. The generated+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 architecturediff --git a/site/scripts/readme-showcase.mjs b/site/scripts/readme-showcase.mjsindex 927fea50..03a208d8 100644--- a/site/scripts/readme-showcase.mjs+++ b/site/scripts/readme-showcase.mjs@@ -1,32 +1,62 @@import { mkdir, readFile, writeFile } from 'node:fs/promises';import { dirname, resolve } from 'node:path';-import { fileURLToPath } from 'node:url';+import { fileURLToPath, pathToFileURL } from 'node:url';import sharp from 'sharp';import { fetchPinnedFile, hashBytes } from './mirror-core.mjs';// Regenerate README stills from the same hash-verified captures used by the site.const site = resolve(dirname(fileURLToPath(import.meta.url)), '..');const json = async (path) => JSON.parse(await readFile(resolve(site, path), 'utf8'));-const curation = await json('src/data/site-curation.json');-const shots = await json('src/data/holodeck-shots.json');-const worlds = await json('src/data/holodeck-worlds.json');-const mirror = await json('src/data/mirror-manifest.json');-const output = resolve(site, '../assets/readme');-await mkdir(output, { recursive: true });-const images = [];-for (const id of curation.featuredWorlds) {- const shot = shots.packs[id][1];- const pin = mirror.files.find((file) => file.path === shot.inputPath);- if (!pin || pin.sha256 !== shot.sha256) throw new Error(`Missing scene capture pin: ${id}`);- const input = await fetchPinnedFile(pin, {- mirror: process.env.KILN_ASSET_MIRROR,- cache: resolve(site, '.cache/readme-showcase'),- base: mirror.base,+/** README choices are explicit and independent of site covers or capture ordering. */+export function selectReadmeShots(selections, shots, sceneMedia = {}) {+ const seen = new Set();+ return selections.map((pick) => {+ if (seen.has(pick.worldId)) throw new Error(`Duplicate README world: ${pick.worldId}`);+ seen.add(pick.worldId);+ let shot = shots.packs[pick.worldId]?.find((shot) => shot.view === pick.view);+ if (!shots.packs[pick.worldId]) {+ const scene = sceneMedia[pick.worldId];+ const source = scene?.capture?.view === pick.view ? scene : scene?.captures?.[pick.view];+ if (source?.poster && source.capture) {+ if (!pick.url) throw new Error(`Missing README scene URL: ${pick.worldId}`);+ shot = { ...source.poster, view: pick.view, sha256: source.capture.pngSha256, capture: {+ ...source.capture, world: pick.url,+ backend: source.capture.renderer?.backend === 'webgpu' ? 'WebGPU' : source.capture.renderer?.backend,+ } };+ }+ }+ if (!shot) throw new Error(`Missing README capture: ${pick.worldId}/${pick.view}`);+ if (!Number.isSafeInteger(pick.width) || pick.width < 320 || pick.width > 1920 || pick.width % 16 !== 0) throw new Error(`Invalid README width: ${pick.worldId}`);+ return { ...pick, shot };});- const { data, info } = await sharp(input).resize({ width: 960, withoutEnlargement: true }).webp({ quality: 85 }).toBuffer({ resolveWithObject: true });- const file = `${worlds.worlds[id]}.webp`;- await writeFile(resolve(output, file), data);- images.push({ file, alt: shot.alt, world: shot.capture.world, view: shot.view, inputPath: pin.path, inputSha256: pin.sha256, sha256: hashBytes(data), width: info.width, height: info.height });}-await writeFile(resolve(output, 'holodeck-showcase.json'), `${JSON.stringify({ images }, null, 2)}\n`);-console.log(`Wrote ${images.length} README scene images and their provenance.`);++async function main() {+ const selections = await json('../assets/readme/selection.json');+ const shots = await json('src/data/holodeck-shots.json');+ const sceneMedia = await json('src/data/scene-media.json');+ const worlds = await json('src/data/holodeck-worlds.json');+ const mirror = await json('src/data/mirror-manifest.json');+ const output = resolve(site, '../assets/readme');+ await mkdir(output, { recursive: true });+ const images = [];+ for (const { worldId: id, shot, width, position = 'centre' } of selectReadmeShots(selections, shots, sceneMedia)) {+ const pin = mirror.files.find((file) => file.path === shot.inputPath);+ if (!pin || pin.sha256 !== shot.sha256) throw new Error(`Missing scene capture pin: ${id}`);+ const input = await fetchPinnedFile(pin, {+ mirror: process.env.KILN_ASSET_MIRROR,+ cache: resolve(site, '.cache/readme-showcase'),+ base: mirror.base,+ });+ const height = width * 9 / 16;+ const { data, info } = await sharp(input).resize({ width, height, fit: 'cover', position, withoutEnlargement: true }).webp({ quality: 85 }).toBuffer({ resolveWithObject: true });+ if (info.width !== width || info.height !== height) throw new Error(`Capture is too small for the README frame: ${id}`);+ const file = `${worlds.worlds[id] ?? id}.webp`;+ await writeFile(resolve(output, file), data);+ images.push({ file, alt: shot.alt, world: shot.capture.world, view: shot.view, inputPath: pin.path, inputSha256: pin.sha256, sha256: hashBytes(data), width: info.width, height: info.height, framing: { fit: 'cover', position } });+ }+ await writeFile(resolve(output, 'holodeck-showcase.json'), `${JSON.stringify({ images }, null, 2)}\n`);+ console.log(`Wrote ${images.length} README scene images and their provenance.`);+}++if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) await main();diff --git a/site/scripts/readme-showcase.test.ts b/site/scripts/readme-showcase.test.tsnew file mode 100644index 00000000..22fd5213--- /dev/null+++ b/site/scripts/readme-showcase.test.ts@@ -0,0 +1,58 @@+import { expect, test } from 'bun:test';+import { createHash } from 'node:crypto';+import { readFile } from 'node:fs/promises';+import { resolve } from 'node:path';+import sharp from 'sharp';+import { selectReadmeShots } from './readme-showcase.mjs';++const shots = { packs: { cabin: [{ view: 'exterior' }, { view: 'interior' }] } };++test('README picks named views independently of the website cover and capture order', () => {+ const picks = [{ worldId: 'cabin', view: 'exterior', width: 960 }];+ expect(selectReadmeShots(picks, shots)).toEqual([{ ...picks[0], shot: { view: 'exterior' } }]);+ expect(selectReadmeShots(picks, { packs: { cabin: [...shots.packs.cabin].reverse() } })).toEqual(selectReadmeShots(picks, shots));+});++test('a missing named view or duplicate world is refused instead of choosing another image', () => {+ const pick = { worldId: 'cabin', view: 'exterior', width: 960 };+ expect(() => selectReadmeShots([{ ...pick, view: 'missing' }], shots)).toThrow(/missing/);+ expect(() => selectReadmeShots([pick, pick], shots)).toThrow(/Duplicate/);+});++test('a bundled scene uses its recorded capture and keeps its own destination', () => {+ const pick = { worldId: 'bridge', view: 'drive', width: 960, url: 'https://kilnstudio.tools/scenes/golden-gate/' };+ const media = { bridge: { poster: { inputPath: 'bridge-drive.png' }, capture: { view: 'drive', pngSha256: 'capture-hash', renderer: { backend: 'webgpu' } } } };+ const [selected] = selectReadmeShots([pick], shots, media);+ expect(selected.shot).toMatchObject({ view: 'drive', inputPath: 'bridge-drive.png', sha256: 'capture-hash', capture: { backend: 'WebGPU', world: pick.url } });+ expect(() => selectReadmeShots([{ ...pick, view: 'missing' }], shots, media)).toThrow(/Missing/);+});++test('README stills match the chosen WebGPU captures and recorded file hashes', async () => {+ const root = resolve(import.meta.dir, '../..');+ const json = async (file: string) => JSON.parse(await readFile(resolve(root, file), 'utf8'));+ const captures = await json('site/src/data/holodeck-shots.json');+ const picks = selectReadmeShots(await json('assets/readme/selection.json'), captures, await json('site/src/data/scene-media.json'));+ const { images } = await json('assets/readme/holodeck-showcase.json');+ const readme = await readFile(resolve(root, 'README.md'), 'utf8');+ expect(images).toHaveLength(picks.length);+ for (const [index, image] of images.entries()) {+ const pick = picks[index];+ expect(image.view).toBe(pick.shot.view);+ expect(pick.shot.capture.backend).toBe('WebGPU');+ expect(image.inputPath).toBe(pick.shot.inputPath);+ expect(image.inputSha256).toBe(pick.shot.sha256);+ expect(readme).toContain(image.world);+ const bytes = await readFile(resolve(root, 'assets/readme', image.file));+ expect(createHash('sha256').update(bytes).digest('hex')).toBe(image.sha256);+ const metadata = await sharp(bytes).metadata();+ expect([metadata.width, metadata.height]).toEqual([image.width, image.height]);+ expect(readme).toContain(`assets/readme/${image.file}`);+ }+});++test('all four collage images have the same 16:9 dimensions', async () => {+ const { images } = JSON.parse(await readFile(resolve(import.meta.dir, '../../assets/readme/holodeck-showcase.json'), 'utf8'));+ expect(images).toHaveLength(4);+ expect(new Set(images.map((image: { width: number; height: number }) => `${image.width}x${image.height}`)).size).toBe(1);+ for (const image of images) expect(image.width * 9).toBe(image.height * 16);+});