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.

Curate README with four matching scene captures (#285)

Matthew Kissingerd63206cf221f
diff --git a/README.md b/README.md
index 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 scene
One 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.
[![A timber wall and cabin kit assembling, the kitchen and loft bed being furnished, then the finished snowy Holodeck world](site/public/workflow/winter-cabin/7f7f5f16317afd7d/workflow.gif)](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 in
Holodeck. 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 |
-| --- | --- | --- |
-| [![A marble causeway between mirror pools leading to Meridian Sanctuary's gate tower](assets/readme/meridian-sanctuary.webp)](https://holodeck.kilnstudio.tools/worlds/meridian-sanctuary/) | [![The canopied Cove seat among palms overlooking Crescent Cove's lagoon](assets/readme/crescent-cove.webp)](https://holodeck.kilnstudio.tools/worlds/crescent-cove/) | [![The Winter Mountainside Cabin living room, with a sofa, armchair, stone hearth and loft stair](assets/readme/winter-mountainside-cabin.webp)](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 games
I build Sheepdog Sim, OBJEKT 62 and ski sim alongside Kiln, and use these games
diff --git a/assets/readme/golden-gate.webp b/assets/readme/golden-gate.webp
new file mode 100644
index 00000000..5c835dd1
Binary files /dev/null and b/assets/readme/golden-gate.webp differ
diff --git a/assets/readme/holodeck-showcase.json b/assets/readme/holodeck-showcase.json
index 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.json
new file mode 100644
index 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.webp
index 3db7a588..1ba28506 100644
Binary files a/assets/readme/winter-mountainside-cabin.webp and b/assets/readme/winter-mountainside-cabin.webp differ
diff --git a/site/README.md b/site/README.md
index 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 param
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 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 architecture
diff --git a/site/scripts/readme-showcase.mjs b/site/scripts/readme-showcase.mjs
index 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.ts
new file mode 100644
index 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);
+});