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.

Show Kiln assets in live games (#188)

Matthew Kissinger3e8bbdbc7b9a
diff --git a/scripts/tier2-dogfood.test.mjs b/scripts/tier2-dogfood.test.mjs
index ea8a65a6..571040cd 100644
--- a/scripts/tier2-dogfood.test.mjs
+++ b/scripts/tier2-dogfood.test.mjs
@@ -582,10 +582,12 @@ describe('Tier 2 blind dogfood driver', () => {
}
mkdirSync(join(root, 'clone', '.git'));
- expect(discoverArtifacts(root).map(({ path }) => path)).toEqual([
- 'workspace/final.glb',
- 'workspace/final.kiln.js',
- ]);
+ // Directory enumeration order varies by filesystem; compare the discovered set.
+ expect(
+ discoverArtifacts(root)
+ .map(({ path }) => path)
+ .sort(),
+ ).toEqual(['workspace/final.glb', 'workspace/final.kiln.js']);
});
test('the deadline reports itself and ends the process', async () => {
diff --git a/site/scripts/static-validation-core.mjs b/site/scripts/static-validation-core.mjs
index 06977790..39b2d24a 100644
--- a/site/scripts/static-validation-core.mjs
+++ b/site/scripts/static-validation-core.mjs
@@ -373,6 +373,8 @@ export const scriptHashSource = (text) => `'sha256-${createHash('sha256').update
/** A file whose name carries a build content hash (Vite's `name.HASH.js` or `name-HASH.js`). */
const HASHED_NAME = /[.-][A-Za-z0-9_-]{8}\.(?:js|css|woff2|svg|png|jpg|webp|avif)$/;
+// Astro appends its variable-length transform hash to the imported image's Vite hash.
+const ASTRO_TRANSFORMED_IMAGE = /^_astro\/[^/]+\.[A-Za-z0-9_-]{8}_[A-Za-z0-9]{1,7}\.(?:png|jpg|jpeg|webp|avif|gif)$/;
/**
* The header layer (engineering review, finding 11; brief part 1, item 4). Every response gets nosniff, the referrer
@@ -410,7 +412,7 @@ export function headersErrors({ text, inlineScripts = [], files = [], sealedFile
const cacheControl = headersFor(rules, `/${file}`)['cache-control'] ?? '';
if ((cacheControl.match(/max-age=/g) ?? []).length > 1) errors.push(`/${file}: Cache-Control is set twice (${cacheControl})`);
const immutable = /immutable/.test(cacheControl);
- if (immutable && !HASHED_NAME.test(file) && !sealed.has(file)) errors.push(`/${file} is cached as immutable but its name carries no content hash`);
+ if (immutable && !HASHED_NAME.test(file) && !ASTRO_TRANSFORMED_IMAGE.test(file) && !sealed.has(file)) errors.push(`/${file} is cached as immutable but its name carries no content hash`);
if (!immutable && file.startsWith('_astro/')) errors.push(`/${file} is a hashed build file but is not cached as immutable`);
}
return errors;
diff --git a/site/scripts/static-validation.test.ts b/site/scripts/static-validation.test.ts
index fa931292..ab02e216 100644
--- a/site/scripts/static-validation.test.ts
+++ b/site/scripts/static-validation.test.ts
@@ -400,6 +400,16 @@ ${extra}`;
expect(headersErrors({ text: good, inlineScripts: [], files })).toEqual([`script-src lists ${scriptHashSource(script)}, which no page carries`]);
});
+ test('Astro image transforms retain the source content hash before the short transform hash', () => {
+ const files = ['_astro/objekt62.CSWQHgbU_1CyNvS.webp', '_astro/sheepdog-sim.DRJTkRDj_UK19i.webp'];
+ expect(headersErrors({ text: good, inlineScripts: [script], files })).toEqual([]);
+ for (const path of ['_astro/objekt62_1CyNvS.webp', '_astro/objekt62.CSWQHgbU_.webp', '_astro/objekt62.CSWQHgbU_1CyNvS.js']) {
+ expect(headersErrors({ text: good, inlineScripts: [script], files: [path] })).toEqual([
+ `/${path} is cached as immutable but its name carries no content hash`,
+ ]);
+ }
+ });
+
test('an enforced policy, a lost header, a blocked fullscreen or an unhashed immutable file are reported', () => {
const enforced = good.replace('Content-Security-Policy-Report-Only', 'Content-Security-Policy');
expect(headersErrors({ text: enforced, inlineScripts: [script] })).toEqual([
diff --git a/site/src/assets/live-games/objekt62.webp b/site/src/assets/live-games/objekt62.webp
new file mode 100644
index 00000000..669570d8
Binary files /dev/null and b/site/src/assets/live-games/objekt62.webp differ
diff --git a/site/src/assets/live-games/sheepdog-sim.webp b/site/src/assets/live-games/sheepdog-sim.webp
new file mode 100644
index 00000000..f6dd86c4
Binary files /dev/null and b/site/src/assets/live-games/sheepdog-sim.webp differ
diff --git a/site/src/data/live-games.json b/site/src/data/live-games.json
new file mode 100644
index 00000000..44751fa4
--- /dev/null
+++ b/site/src/data/live-games.json
@@ -0,0 +1,31 @@
+{
+ "images": [
+ {
+ "name": "sheepdog-sim",
+ "game": "Sheepdog Sim",
+ "source": "sds/captures/fence-kit/runtime-gate-1/webgpu-desktop/follow-gate.png",
+ "captured": "2026-10-17",
+ "note": "Existing native WebGPU production-build capture; house, barn, fences and trees. Full frame, WebP encoding only.",
+ "width": 1600,
+ "height": 900,
+ "originalSha256": "1dc924707c03a32b8f48b16b582db1ba937c3862eaeb4ffe1aa8803c68e690fa",
+ "imageSha256": "2dedf8779193cab74af2139e559301d6419beb853ae76a8c0973a7e6ea732cd0",
+ "bytes": 336142
+ },
+ {
+ "name": "objekt62",
+ "game": "OBJEKT-62",
+ "source": "https://objekt62.com/",
+ "captured": "2026-10-20",
+ "version": "0.21.2",
+ "note": "Fresh native WebGPU in-game browser capture. Survey rifle, outpost and distant monument. Full frame, WebP encoding only.",
+ "width": 1600,
+ "height": 900,
+ "originalSha256": "c6ee6f622e0208a6691487b87670f6e72e4310258f4fd7d05bd6bb10e373e899",
+ "imageSha256": "020d9f05a501832557186a0915dfd8125572e9418e5a9464c10872387cbedbff",
+ "bytes": 88322,
+ "buildSha": "9d82bb927f951389291731e64e0803140e523ae9",
+ "buildGeneratedAt": "2026-10-19T22:36:21.075Z"
+ }
+ ]
+}
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
index 0098ea45..ebaf97d4 100644
--- a/site/src/pages/index.astro
+++ b/site/src/pages/index.astro
@@ -8,6 +8,9 @@ import BaseLayout from "../layouts/BaseLayout.astro";
import HeroDrawing from "../components/HeroDrawing.astro";
import ResponsiveImage from "../components/ResponsiveImage.astro";
import ScenePoster from "../components/ScenePoster.astro";
+import { Image } from "astro:assets";
+import sheepdogGameShot from "../assets/live-games/sheepdog-sim.webp";
+import objektGameShot from "../assets/live-games/objekt62.webp";
import CodeBlock from "../components/CodeBlock.astro";
import { farm, vehicles, number, bounds } from "../lib/catalog";
import { harnessName, modelName } from "../lib/attribution";
@@ -168,6 +171,62 @@ const CARD_SIZES = "(max-width: 767px) calc(100vw - 32px), (max-width: 1279px) c
</div>
</div>
</div>
+ <section id="live-games" class="container section-space" aria-labelledby="live-games-heading">
+ <div class="grid gap-6 border-t border-ink pt-8 lg:grid-cols-2 lg:gap-12">
+ <div>
+ <p class="mb-3 font-mono text-code text-dim">Kiln in live games</p>
+ <h2 id="live-games-heading">I use Kiln in my own games.</h2>
+ </div>
+ <p class="max-w-reading text-dim">
+ I build Kiln, Sheepdog Sim and OBJEKT-62. Both games use Kiln-authored
+ assets, adapted to their own rendering and gameplay. Working on them
+ lets me test the whole path from editable source to an asset players
+ actually encounter.
+ </p>
+ </div>
+ <div class="mt-8 grid gap-8 md:grid-cols-2">
+ <article class="border-y border-rule py-6">
+ <figure>
+ <Image src={sheepdogGameShot} alt="A sheepdog faces the fenced pen, with the Kiln-authored farmhouse, red barn and trees behind it in Sheepdog Sim." widths={[480, 800, 1280, 1600]} sizes={CARD_SIZES} format="webp" loading="lazy" class="w-full" />
+ <figcaption class="mt-2 font-mono text-code text-dim">House, barn, fences and trees in the game.</figcaption>
+ </figure>
+ <h3 class="mt-5">Sheepdog Sim</h3>
+ <p class="mt-3 max-w-reading text-dim">
+ A sheep herding game in your browser. I authored its house, barn,
+ fences and trees with Kiln, then integrated them with the game's own
+ materials and rendering.
+ </p>
+ <p class="mt-3 max-w-reading text-dim">
+ The game is open source. Browse the repository to see how the assets
+ fit into a working game.
+ </p>
+ <div class="mt-5 flex flex-wrap gap-x-6 gap-y-2">
+ <a class="text-link" href="https://sheepdogsim.com/">
+ Play Sheepdog Sim <span aria-hidden="true">↗</span>
+ </a>
+ <a class="text-link" href="https://github.com/matthew-kissinger/sds">
+ Browse the source <span aria-hidden="true">↗</span>
+ </a>
+ </div>
+ </article>
+ <article class="border-y border-rule py-6">
+ <figure>
+ <Image src={objektGameShot} alt="The Kiln-authored survey rifle in the foreground, an outpost and parked aircraft ahead, and a monument on the distant desert horizon in OBJEKT-62." widths={[480, 800, 1280, 1600]} sizes={CARD_SIZES} format="webp" loading="lazy" class="w-full" />
+ <figcaption class="mt-2 font-mono text-code text-dim">Survey rifle and outpost · live 0.21.2.</figcaption>
+ </figure>
+ <h3 class="mt-5">OBJEKT-62</h3>
+ <p class="mt-3 max-w-reading text-dim">
+ A sci-fi survival game in your browser. I use Kiln for most of its
+ 3D assets, including guns, ship parts, vehicles, outpost modules and
+ salvage. They are integrated with the game's own materials, collision
+ and interaction systems.
+ </p>
+ <a class="text-link mt-5" href="https://objekt62.com/">
+ Play OBJEKT-62 <span aria-hidden="true">↗</span>
+ </a>
+ </article>
+ </div>
+ </section>
{PACKS_ENABLED && (
<>
<section class="container pt-16 md:pt-24" aria-labelledby="loop-heading">
diff --git a/skills/kiln-compose-scene/SKILL.md b/skills/kiln-compose-scene/SKILL.md
index b2dfd659..14ad95b7 100644
--- a/skills/kiln-compose-scene/SKILL.md
+++ b/skills/kiln-compose-scene/SKILL.md
@@ -1,12 +1,12 @@
---
name: kiln-compose-scene
-description: Compose existing assets into an exported scene or interactive proving environment, with deliberate placement, terrain, materials, integration checks and runtime qualification.
+description: Compose existing assets into an exported scene or interactive proving environment. Use Kiln welding to fit assets into a game's own geometry batches, materials, collision and interaction systems.
license: MIT
metadata:
kiln-workflow: workspace
---
-# Compose a scene from existing assets
+# Compose and weld a scene from existing assets
Use this optional workflow when the task concerns several assets. Keep placement separate from individual source authoring so moving an object does not regenerate its geometry.
@@ -14,6 +14,12 @@ A scene or environment can be a standalone deliverable. A Kiln project is option
Read the [composition API notes](references/composition-api.md) when using the library. These are host/project APIs, not tools automatically added to the Kiln MCP surface.
+For **Kiln welding**, where authored pieces become part of an existing game's
+structures and rendering, read [the welding workflow](references/welding.md).
+It covers placement, surface-role mapping, geometry batches and preserving
+moving parts, collision and interaction anchors. Welding is a consumer workflow,
+not a new Kiln tool or a requirement to fuse every vertex.
+
Choose the deliverable before composing. A single scene GLB and an interactive
application have different requirements; exporting a monolithic GLB is optional.
For terrain, animated environments, traversal or measured optimization, read
diff --git a/skills/kiln-compose-scene/references/welding.md b/skills/kiln-compose-scene/references/welding.md
new file mode 100644
index 00000000..5a3dbc1d
--- /dev/null
+++ b/skills/kiln-compose-scene/references/welding.md
@@ -0,0 +1,104 @@
+# Kiln welding
+
+Use this workflow to assemble Kiln assets into a destination game's structures
+and rendering. Keep individual editable revisions and a reproducible assembly;
+the merged geometry is a derived runtime artifact. The destination may be an
+existing game or a new scene. A Kiln project is optional.
+
+This workflow describes integration code in the consuming workspace. There is
+no `kiln_weld` tool. Inspect the installed tool/API contracts before choosing an
+export or loader; use the composition API reference for a single scene GLB.
+
+## Establish the assembly contract
+
+Read the game's loader, frame conventions, materials, collision and placement
+code before changing its integration. Identify the actual asset revisions and
+runtime exports, including metadata, required extensions and decoders. Verify
+the decoded result with that loader; a successful editable-GLB review does not
+prove that a compressed runtime file loads correctly.
+
+Give each placed instance a stable ID, source identity and explicit transform.
+Record the source units, axes, origin, bounds, surface roles, attachments and
+moving parts. Use authored sockets or the destination's layout to place parts.
+When matching sockets, align their orientations as well as their positions.
+Do not infer functional placement from a bounding box alone or stretch a piece
+to fit if that would distort openings, thicknesses or mechanisms.
+
+Keep the layout, role table and material bindings in the consuming workspace.
+Missing required roles or placement data should produce an actionable error,
+not silently select a similar-looking material or discard a part.
+
+## Choose what to combine
+
+Welding means fitting pieces into the scene's rendering and gameplay systems;
+it does not always require merging meshes or coincident vertices. Choose among
+ordinary placed meshes, instances of repeated geometry, and merged geometry
+based on the destination's measured costs and required behavior.
+
+For merging, group compatible geometry by material and shader attributes,
+render state, motion owner and useful spatial/culling region. A whole-world
+batch can lose culling and increase work. Keep doors, ramps, wheels, turrets,
+weapons, animated actors and removable pieces under the pivots or skeletons that
+own their motion. Merge within those owners when appropriate. Do not bake a
+moving part into a static structure to achieve a lower draw count.
+
+Map authored surface roles to the game's material families deliberately. Read
+the asset's actual role encoding; material names, vertex colors and metadata
+are not interchangeable universal conventions. Preserve UVs, normals, colors
+and custom channels required by the destination shader. A UV channel may carry
+procedural surface data rather than texture coordinates. Drop an attribute only
+after consuming its meaning and verifying that the destination does not need it.
+Check opacity, emission, shadows and material appearance in the game's renderer.
+
+## Bake into the correct frame
+
+Update the loaded hierarchy's world matrices before extracting geometry. Express
+each source mesh in its destination batch's local frame: destination-world inverse
+times the placed source-world transform. Apply units and axis conversion once,
+using the destination's conventions. Transform normals with the corresponding
+normal matrix. A negative determinant needs winding/handedness handling after
+baking; the renderer can no longer correct it through the old object's matrix.
+
+Decode quantized positions and honor their node transforms before writing new
+floating-point geometry. Do not mutate packed normalized attributes in place
+as though they already contained world-space metres. Skinned exports may carry
+dequantization in inverse bind matrices. Evaluate their bind/rest-pose transforms
+through the loader, or retain the skin when animation is needed; a mesh-node
+matrix alone is not sufficient. Rigid joint ownership is usable only when the
+asset actually has rigid weights. Do not generalize it to blended skinning.
+
+Preserve hard edges, material boundaries and UV seams. Mesh batching is not
+topological vertex welding: do not run a global proximity merge merely because
+parts touch. If seamless topology is required, treat it as a separate geometry
+edit with an appropriate tolerance and inspect the resulting shading and gaps.
+Avoid changing shared cached source geometry while baking several instances.
+
+## Preserve gameplay identity
+
+Carry collision shapes, sockets, interaction targets and semantic part IDs
+through the same frame conversion as the visible pieces. Keep their stable
+records available after render meshes are combined. A rendering batch is not
+automatically the right collision mesh or interaction owner. Maintain the
+destination's authoritative layout rather than reconstructing gameplay data
+from a finished screenshot or a broad AABB.
+
+Check required contacts and required gaps at actual interfaces: both ends of a
+support, doorway clearance, a socket's seated component and a moving mechanism's
+intermediate poses. Exercise doors, pickups, seats or weapon attachments when
+they are part of the task. Keep scene-specific dimensions, controllers and
+damage rules in the consuming workspace. See the runtime scene reference for
+traversal, camera and animation qualification.
+
+## Prove the destination result
+
+Compare the placed inputs and the derived batches for bounds, expected triangle
+coverage, surface-role assignment and preserved moving/interactive parts. Inspect
+representative mirrored or scaled placements when used. Run the real camera
+and relevant interactions, including repeated use and intermediate motion.
+
+Measure draw calls per pass and frame/startup costs in the actual destination,
+including the moving workload when relevant. Distinguish a deliberate art
+integration from a demonstrated performance improvement; fewer material groups
+or a valid GLB alone proves neither. Keep backend, camera, asset revisions and
+scene configuration with the evidence. Use current in-game captures to show the
+result and state any untested behavior or unqualified performance claims.