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.

feat(materials): natural presets for coastal and tropical scenes (#210) (#228)

Matthew Kissingerfa4cb3a016e0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41cca0ad..e47d5389 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,6 +55,12 @@ does not publish a package.
listed with their parts, the differing factors, what a merge needs and the projected
material count and grade. The advice is labelled optional and never changes the grade or
any QA disposition (#209).
+- Add natural material presets `beach-sand`, `coral-limestone`, `coral-limestone-wet`,
+ `palm-frond`, `driftwood` and `thatch`, tagged by family (`ground`, `rock`, `foliage`,
+ `wood`, `fiber`). `palm-frond` is an alpha-tested, double-sided cutout saved as a
+ `schemaVersion:2` record; `createMaterialPresetDraftAny` returns any preset's draft, and
+ preset summaries report `recordSchemaVersion`. The docs list the presets as a table that a
+ test keeps in step with the catalog (#210).
## 1.3.1 (2026-10-17)
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 1aaebedf..cc482e9d 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -45006,8 +45006,51 @@ var catalog2 = [
family: "ground",
physicalSizeMeters: { width: 2, height: 2 },
description: "Layered granular soil variation and subtle relief for terrain and planting beds."
+ },
+ {
+ id: "beach-sand",
+ name: "Pale beach sand",
+ family: "ground",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Fine pale grains with shallow wind ripples; no shells, wet edge or footprints."
+ },
+ {
+ id: "coral-limestone",
+ name: "Dry coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Porous cream stone with pitted relief for coastal rocks and walls."
+ },
+ {
+ id: "coral-limestone-wet",
+ name: "Wet coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "The dry limestone darkened and smoothed by water; the same seed keeps identical relief."
+ },
+ {
+ id: "palm-frond",
+ name: "Palm frond cutout",
+ family: "foliage",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Alpha-tested, double-sided frond card: a central rachis with tapering leaflets, base at the image bottom. Not tileable."
+ },
+ {
+ id: "driftwood",
+ name: "Weathered driftwood",
+ family: "wood",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Sun-bleached silver-grey grain with deep weathered relief and a dry matte finish."
+ },
+ {
+ id: "thatch",
+ name: "Straw thatch",
+ family: "fiber",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Vertical straw strands in horizontal courses for roofs and shelters."
}
];
+var RECORD_V2_PRESETS = new Set(["palm-frond"]);
var materialPresetOptionsSchema = z16.object({
seed: z16.number().int().min(-2147483648).max(2147483647),
size: z16.union([z16.literal(64), z16.literal(128), z16.literal(256), z16.literal(512)]).default(256),
@@ -45020,10 +45063,11 @@ function listMaterialPresets() {
...item,
physicalSizeMeters: { ...item.physicalSizeMeters },
tags: [item.family, "procedural"],
- recipeVersion: 1
+ recipeVersion: 1,
+ recordSchemaVersion: RECORD_V2_PRESETS.has(item.id) ? 2 : 1
}));
}
-function createMaterialPresetDraft(presetId, raw) {
+function createMaterialPresetDraftAny(presetId, raw) {
assertMaterialJson(raw);
const options = materialPresetOptionsSchema.parse(raw);
const preset = catalog2.find((item) => item.id === presetId);
@@ -45088,6 +45132,46 @@ function createMaterialPresetDraft(presetId, raw) {
stripes(3355443, 13421772, 32, 90, 0.4)
];
strength = 1;
+ } else if (presetId === "beach-sand") {
+ color = [noise(13613455, 15391670, 32), noise(11047274, 16182484, 64, 0.25)];
+ height = [noise(7368816, 9474192, 32), stripes(7105644, 9737364, 12, 15, 0.35)];
+ roughnessLow = 215;
+ roughnessHigh = 245;
+ strength = 1.5;
+ } else if (presetId === "coral-limestone" || presetId === "coral-limestone-wet") {
+ height = [noise(6316128, 10526880, 8), noise(3158064, 13684944, 32, 0.6)];
+ strength = 3;
+ if (presetId === "coral-limestone") {
+ color = [noise(13221540, 15327693, 8), noise(9076843, 14274747, 32, 0.3)];
+ roughnessLow = 200;
+ roughnessHigh = 240;
+ } else {
+ color = [noise(7300435, 9406064, 8), noise(4866871, 8221793, 32, 0.3)];
+ roughnessLow = 70;
+ roughnessHigh = 130;
+ }
+ } else if (presetId === "palm-frond") {
+ color = [];
+ height = [noise(7368816, 9474192, 16), stripes(6974058, 9868950, 24, 45, 0.4)];
+ roughnessLow = 140;
+ roughnessHigh = 190;
+ strength = 1;
+ } else if (presetId === "driftwood") {
+ color = [noise(9143158, 13222322, 4), stripes(7695713, 13814459, 48, 0, 0.35)];
+ height = [noise(5921370, 10855845, 4), stripes(4210752, 12632256, 48, 0, 0.45)];
+ roughnessLow = 200;
+ roughnessHigh = 245;
+ strength = 2.5;
+ } else if (presetId === "thatch") {
+ color = [
+ stripes(10585151, 14072698, 64, 90),
+ noise(7232050, 13150312, 16, 0.35),
+ stripes(6245415, 12098652, 8, 0, 0.25)
+ ];
+ height = [stripes(4210752, 12632256, 64, 90), stripes(5263440, 11579568, 8, 0, 0.4)];
+ roughnessLow = 220;
+ roughnessHigh = 250;
+ strength = 2.5;
} else {
color = [noise(5061676, 8942420, 4), noise(3418656, 10850155, 32, 0.25)];
height = [noise(5592405, 11184810, 8), noise(2236962, 14540253, 32, 0.3)];
@@ -45107,13 +45191,11 @@ function createMaterialPresetDraft(presetId, raw) {
}
]
};
- return {
+ const identity = {
materialId: options.materialId ?? preset.id,
name: preset.name,
tags: [preset.family, "procedural"],
- tileable: true,
physicalSizeMeters: { ...preset.physicalSizeMeters },
- parameters: { metalness: 1, roughness: 1 },
sources: [
{
id: "preset",
@@ -45124,25 +45206,113 @@ function createMaterialPresetDraft(presetId, raw) {
license: options.license,
originalFiles: []
}
- ],
+ ]
+ };
+ const derive = { kind: "normal-from-height", strength };
+ const roughnessMap = spec("metallicRoughness", [
+ noise(packed(roughnessLow), packed(roughnessHigh), 8)
+ ]);
+ if (presetId === "palm-frond") {
+ const sampler = {
+ minFilter: "linear-mipmap-linear",
+ magFilter: "linear",
+ wrapS: "clamp-to-edge",
+ wrapT: "clamp-to-edge"
+ };
+ return {
+ schemaVersion: 2,
+ ...identity,
+ tileable: false,
+ parameters: {
+ metalness: 1,
+ roughness: 1,
+ alphaMode: "mask",
+ alphaCutoff: 0.5,
+ doubleSided: true
+ },
+ maps: [
+ {
+ ...common,
+ slot: "baseColor",
+ sampler,
+ procedural: frondCutout(options.size, options.seed)
+ },
+ { ...common, slot: "normal", sampler, procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", sampler, procedural: roughnessMap }
+ ]
+ };
+ }
+ return {
+ materialId: identity.materialId,
+ name: identity.name,
+ tags: identity.tags,
+ tileable: true,
+ physicalSizeMeters: identity.physicalSizeMeters,
+ parameters: { metalness: 1, roughness: 1 },
+ sources: identity.sources,
maps: [
{ ...common, slot: "baseColor", procedural: spec("albedo", color) },
- {
- ...common,
- slot: "normal",
- procedural: spec("normal", height),
- derive: { kind: "normal-from-height", strength }
- },
- {
- ...common,
- slot: "metallicRoughness",
- procedural: spec("metallicRoughness", [
- noise(packed(roughnessLow), packed(roughnessHigh), 8)
- ])
- }
+ { ...common, slot: "normal", procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", procedural: roughnessMap }
]
};
}
+function presetRandom(seed) {
+ let state = seed >>> 0;
+ return () => {
+ state = state + 1831565813 >>> 0;
+ let t = state;
+ t = Math.imul(t ^ t >>> 15, t | 1);
+ t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+ return ((t ^ t >>> 14) >>> 0) / 4294967296;
+ };
+}
+function frondCutout(size, seed) {
+ const random = presetRandom(seed);
+ const unit = size / 64;
+ const centre = Math.round(size / 2);
+ const inside = (value) => Math.min(size - 2, Math.max(1, Math.round(value)));
+ const shade = (base, spread) => Math.min(255, Math.max(0, Math.round(base + (random() - 0.5) * spread)));
+ const operations = [];
+ const leaflets = 12;
+ for (let i = 0;i < leaflets; i++) {
+ const along = (i + 0.5) / leaflets;
+ const y = size - 3 * unit - along * (size - 8 * unit);
+ const width = Math.max(1, Math.round((2.4 - 1.4 * along) * unit));
+ for (const side of [-1, 1]) {
+ const reach = (0.44 - 0.3 * along) * size * (0.9 + 0.2 * random());
+ const rise = (0.08 + 0.06 * random()) * size;
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, inside(y)],
+ to: [inside(centre + side * reach), inside(y - rise)],
+ width
+ },
+ rgba: [shade(64, 24), shade(116, 30), shade(44, 18), 255]
+ });
+ }
+ }
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, size - 1],
+ to: [centre, inside(2 * unit)],
+ width: Math.max(1, Math.round(1.5 * unit))
+ },
+ rgba: [104, 98, 46, 255]
+ });
+ return {
+ schemaVersion: 3,
+ width: size,
+ height: size,
+ usage: "albedo",
+ background: [0, 0, 0, 0],
+ operations
+ };
+}
// src/tools/materials.ts
var MATERIAL_ACTIONS = [
@@ -45257,7 +45427,8 @@ function createKilnMaterialDef(library, presentation = "grouped") {
license: input.license,
materialId: input.materialId
}).filter(([, value]) => value !== undefined));
- const record = await createMaterialRecordV1(createMaterialPresetDraft(input.presetId, options));
+ const draft = createMaterialPresetDraftAny(input.presetId, options);
+ const record = "schemaVersion" in draft ? await createMaterialRecordV2(draft) : await createMaterialRecordV1(draft);
const [material] = await library.import([record]);
return materialResult(material);
}
diff --git a/dist/build.json b/dist/build.json
index 79d1fed3..6d3af712 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -40,10 +40,10 @@
"bundleHash": "sha256:520d921c096ae6886598aea30c98378cba2dd2ccf01984c0d4623bc16a661adb"
},
"agent-run": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -75,13 +75,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:82d23b6651688af117e951a6049dca4359e572639e3d14041f715d157cff2630"
+ "bundleHash": "sha256:33e567d79b6818228b247d767db3fecb3918b15986d6fcd346be7f23929130cc"
},
"agent-providers": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -116,10 +116,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -154,10 +154,10 @@
"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"
},
"cli": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -189,13 +189,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:ebd05f2ba4e429db70f7a48b4e67c8afbeaf49b63dfa0fb3804d130fe1deab4c"
+ "bundleHash": "sha256:32b7c89ba7f18992d04f438b02a3091e0caeedfd68959a0ab1a6e439a58cf7a5"
},
"engine": {
- "identity": "sha256:7ac7c7547ff2e4ab8ef3bbd87f3454091deec94a16e5951951cf688ccdf44609",
+ "identity": "sha256:4de3ab1a7f91fd2fa7f6da968cc033148dd1f92928ee3fb35f81d4bbe093019b",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "a65c95852a179170b5a563e919fbbb44e3e68bc3855b82844d8508db3f3a6518",
+ "sourceHash": "3345bf309f0d9c99601553cc1b322c39af698f45122c98a04344740f98729229",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -227,7 +227,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:91f4e7f1b401d03810c7e6b5aa8b322a0366246e3af55d8a4e7433cf5c3eeeee"
+ "bundleHash": "sha256:accf4fbac8de3b66f279ab590024f4bbe9a267b95fc427228e9fd3b239a78b33"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index 684ae1a3..d8106586 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -48349,10 +48349,11 @@ function listMaterialPresets() {
...item,
physicalSizeMeters: { ...item.physicalSizeMeters },
tags: [item.family, "procedural"],
- recipeVersion: 1
+ recipeVersion: 1,
+ recordSchemaVersion: RECORD_V2_PRESETS.has(item.id) ? 2 : 1
}));
}
-function createMaterialPresetDraft(presetId, raw) {
+function createMaterialPresetDraftAny(presetId, raw) {
assertMaterialJson(raw);
const options = materialPresetOptionsSchema.parse(raw);
const preset = catalog2.find((item) => item.id === presetId);
@@ -48417,6 +48418,46 @@ function createMaterialPresetDraft(presetId, raw) {
stripes(3355443, 13421772, 32, 90, 0.4)
];
strength = 1;
+ } else if (presetId === "beach-sand") {
+ color = [noise(13613455, 15391670, 32), noise(11047274, 16182484, 64, 0.25)];
+ height = [noise(7368816, 9474192, 32), stripes(7105644, 9737364, 12, 15, 0.35)];
+ roughnessLow = 215;
+ roughnessHigh = 245;
+ strength = 1.5;
+ } else if (presetId === "coral-limestone" || presetId === "coral-limestone-wet") {
+ height = [noise(6316128, 10526880, 8), noise(3158064, 13684944, 32, 0.6)];
+ strength = 3;
+ if (presetId === "coral-limestone") {
+ color = [noise(13221540, 15327693, 8), noise(9076843, 14274747, 32, 0.3)];
+ roughnessLow = 200;
+ roughnessHigh = 240;
+ } else {
+ color = [noise(7300435, 9406064, 8), noise(4866871, 8221793, 32, 0.3)];
+ roughnessLow = 70;
+ roughnessHigh = 130;
+ }
+ } else if (presetId === "palm-frond") {
+ color = [];
+ height = [noise(7368816, 9474192, 16), stripes(6974058, 9868950, 24, 45, 0.4)];
+ roughnessLow = 140;
+ roughnessHigh = 190;
+ strength = 1;
+ } else if (presetId === "driftwood") {
+ color = [noise(9143158, 13222322, 4), stripes(7695713, 13814459, 48, 0, 0.35)];
+ height = [noise(5921370, 10855845, 4), stripes(4210752, 12632256, 48, 0, 0.45)];
+ roughnessLow = 200;
+ roughnessHigh = 245;
+ strength = 2.5;
+ } else if (presetId === "thatch") {
+ color = [
+ stripes(10585151, 14072698, 64, 90),
+ noise(7232050, 13150312, 16, 0.35),
+ stripes(6245415, 12098652, 8, 0, 0.25)
+ ];
+ height = [stripes(4210752, 12632256, 64, 90), stripes(5263440, 11579568, 8, 0, 0.4)];
+ roughnessLow = 220;
+ roughnessHigh = 250;
+ strength = 2.5;
} else {
color = [noise(5061676, 8942420, 4), noise(3418656, 10850155, 32, 0.25)];
height = [noise(5592405, 11184810, 8), noise(2236962, 14540253, 32, 0.3)];
@@ -48436,13 +48477,11 @@ function createMaterialPresetDraft(presetId, raw) {
}
]
};
- return {
+ const identity = {
materialId: options.materialId ?? preset.id,
name: preset.name,
tags: [preset.family, "procedural"],
- tileable: true,
physicalSizeMeters: { ...preset.physicalSizeMeters },
- parameters: { metalness: 1, roughness: 1 },
sources: [
{
id: "preset",
@@ -48453,26 +48492,114 @@ function createMaterialPresetDraft(presetId, raw) {
license: options.license,
originalFiles: []
}
- ],
+ ]
+ };
+ const derive = { kind: "normal-from-height", strength };
+ const roughnessMap = spec("metallicRoughness", [
+ noise(packed(roughnessLow), packed(roughnessHigh), 8)
+ ]);
+ if (presetId === "palm-frond") {
+ const sampler = {
+ minFilter: "linear-mipmap-linear",
+ magFilter: "linear",
+ wrapS: "clamp-to-edge",
+ wrapT: "clamp-to-edge"
+ };
+ return {
+ schemaVersion: 2,
+ ...identity,
+ tileable: false,
+ parameters: {
+ metalness: 1,
+ roughness: 1,
+ alphaMode: "mask",
+ alphaCutoff: 0.5,
+ doubleSided: true
+ },
+ maps: [
+ {
+ ...common,
+ slot: "baseColor",
+ sampler,
+ procedural: frondCutout(options.size, options.seed)
+ },
+ { ...common, slot: "normal", sampler, procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", sampler, procedural: roughnessMap }
+ ]
+ };
+ }
+ return {
+ materialId: identity.materialId,
+ name: identity.name,
+ tags: identity.tags,
+ tileable: true,
+ physicalSizeMeters: identity.physicalSizeMeters,
+ parameters: { metalness: 1, roughness: 1 },
+ sources: identity.sources,
maps: [
{ ...common, slot: "baseColor", procedural: spec("albedo", color) },
- {
- ...common,
- slot: "normal",
- procedural: spec("normal", height),
- derive: { kind: "normal-from-height", strength }
- },
- {
- ...common,
- slot: "metallicRoughness",
- procedural: spec("metallicRoughness", [
- noise(packed(roughnessLow), packed(roughnessHigh), 8)
- ])
- }
+ { ...common, slot: "normal", procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", procedural: roughnessMap }
]
};
}
-var catalog2, materialPresetOptionsSchema;
+function presetRandom(seed) {
+ let state = seed >>> 0;
+ return () => {
+ state = state + 1831565813 >>> 0;
+ let t = state;
+ t = Math.imul(t ^ t >>> 15, t | 1);
+ t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+ return ((t ^ t >>> 14) >>> 0) / 4294967296;
+ };
+}
+function frondCutout(size, seed) {
+ const random = presetRandom(seed);
+ const unit = size / 64;
+ const centre = Math.round(size / 2);
+ const inside = (value) => Math.min(size - 2, Math.max(1, Math.round(value)));
+ const shade = (base, spread) => Math.min(255, Math.max(0, Math.round(base + (random() - 0.5) * spread)));
+ const operations = [];
+ const leaflets = 12;
+ for (let i = 0;i < leaflets; i++) {
+ const along = (i + 0.5) / leaflets;
+ const y = size - 3 * unit - along * (size - 8 * unit);
+ const width = Math.max(1, Math.round((2.4 - 1.4 * along) * unit));
+ for (const side of [-1, 1]) {
+ const reach = (0.44 - 0.3 * along) * size * (0.9 + 0.2 * random());
+ const rise = (0.08 + 0.06 * random()) * size;
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, inside(y)],
+ to: [inside(centre + side * reach), inside(y - rise)],
+ width
+ },
+ rgba: [shade(64, 24), shade(116, 30), shade(44, 18), 255]
+ });
+ }
+ }
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, size - 1],
+ to: [centre, inside(2 * unit)],
+ width: Math.max(1, Math.round(1.5 * unit))
+ },
+ rgba: [104, 98, 46, 255]
+ });
+ return {
+ schemaVersion: 3,
+ width: size,
+ height: size,
+ usage: "albedo",
+ background: [0, 0, 0, 0],
+ operations
+ };
+}
+var catalog2, RECORD_V2_PRESETS, materialPresetOptionsSchema;
var init_material_presets = __esm(() => {
init_material_library();
catalog2 = [
@@ -48510,8 +48637,51 @@ var init_material_presets = __esm(() => {
family: "ground",
physicalSizeMeters: { width: 2, height: 2 },
description: "Layered granular soil variation and subtle relief for terrain and planting beds."
+ },
+ {
+ id: "beach-sand",
+ name: "Pale beach sand",
+ family: "ground",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Fine pale grains with shallow wind ripples; no shells, wet edge or footprints."
+ },
+ {
+ id: "coral-limestone",
+ name: "Dry coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Porous cream stone with pitted relief for coastal rocks and walls."
+ },
+ {
+ id: "coral-limestone-wet",
+ name: "Wet coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "The dry limestone darkened and smoothed by water; the same seed keeps identical relief."
+ },
+ {
+ id: "palm-frond",
+ name: "Palm frond cutout",
+ family: "foliage",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Alpha-tested, double-sided frond card: a central rachis with tapering leaflets, base at the image bottom. Not tileable."
+ },
+ {
+ id: "driftwood",
+ name: "Weathered driftwood",
+ family: "wood",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Sun-bleached silver-grey grain with deep weathered relief and a dry matte finish."
+ },
+ {
+ id: "thatch",
+ name: "Straw thatch",
+ family: "fiber",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Vertical straw strands in horizontal courses for roofs and shelters."
}
];
+ RECORD_V2_PRESETS = new Set(["palm-frond"]);
materialPresetOptionsSchema = z18.object({
seed: z18.number().int().min(-2147483648).max(2147483647),
size: z18.union([z18.literal(64), z18.literal(128), z18.literal(256), z18.literal(512)]).default(256),
@@ -48572,7 +48742,8 @@ function createKilnMaterialDef(library, presentation = "grouped") {
license: input.license,
materialId: input.materialId
}).filter(([, value]) => value !== undefined));
- const record = await createMaterialRecordV1(createMaterialPresetDraft(input.presetId, options));
+ const draft = createMaterialPresetDraftAny(input.presetId, options);
+ const record = "schemaVersion" in draft ? await createMaterialRecordV2(draft) : await createMaterialRecordV1(draft);
const [material] = await library.import([record]);
return materialResult(material);
}
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index 54493000..195f79dd 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -49125,8 +49125,51 @@ var catalog2 = [
family: "ground",
physicalSizeMeters: { width: 2, height: 2 },
description: "Layered granular soil variation and subtle relief for terrain and planting beds."
+ },
+ {
+ id: "beach-sand",
+ name: "Pale beach sand",
+ family: "ground",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Fine pale grains with shallow wind ripples; no shells, wet edge or footprints."
+ },
+ {
+ id: "coral-limestone",
+ name: "Dry coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Porous cream stone with pitted relief for coastal rocks and walls."
+ },
+ {
+ id: "coral-limestone-wet",
+ name: "Wet coral limestone",
+ family: "rock",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "The dry limestone darkened and smoothed by water; the same seed keeps identical relief."
+ },
+ {
+ id: "palm-frond",
+ name: "Palm frond cutout",
+ family: "foliage",
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: "Alpha-tested, double-sided frond card: a central rachis with tapering leaflets, base at the image bottom. Not tileable."
+ },
+ {
+ id: "driftwood",
+ name: "Weathered driftwood",
+ family: "wood",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Sun-bleached silver-grey grain with deep weathered relief and a dry matte finish."
+ },
+ {
+ id: "thatch",
+ name: "Straw thatch",
+ family: "fiber",
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: "Vertical straw strands in horizontal courses for roofs and shelters."
}
];
+var RECORD_V2_PRESETS = new Set(["palm-frond"]);
var materialPresetOptionsSchema = z18.object({
seed: z18.number().int().min(-2147483648).max(2147483647),
size: z18.union([z18.literal(64), z18.literal(128), z18.literal(256), z18.literal(512)]).default(256),
@@ -49139,10 +49182,11 @@ function listMaterialPresets() {
...item,
physicalSizeMeters: { ...item.physicalSizeMeters },
tags: [item.family, "procedural"],
- recipeVersion: 1
+ recipeVersion: 1,
+ recordSchemaVersion: RECORD_V2_PRESETS.has(item.id) ? 2 : 1
}));
}
-function createMaterialPresetDraft(presetId, raw) {
+function createMaterialPresetDraftAny(presetId, raw) {
assertMaterialJson(raw);
const options = materialPresetOptionsSchema.parse(raw);
const preset = catalog2.find((item) => item.id === presetId);
@@ -49207,6 +49251,46 @@ function createMaterialPresetDraft(presetId, raw) {
stripes(3355443, 13421772, 32, 90, 0.4)
];
strength = 1;
+ } else if (presetId === "beach-sand") {
+ color = [noise(13613455, 15391670, 32), noise(11047274, 16182484, 64, 0.25)];
+ height = [noise(7368816, 9474192, 32), stripes(7105644, 9737364, 12, 15, 0.35)];
+ roughnessLow = 215;
+ roughnessHigh = 245;
+ strength = 1.5;
+ } else if (presetId === "coral-limestone" || presetId === "coral-limestone-wet") {
+ height = [noise(6316128, 10526880, 8), noise(3158064, 13684944, 32, 0.6)];
+ strength = 3;
+ if (presetId === "coral-limestone") {
+ color = [noise(13221540, 15327693, 8), noise(9076843, 14274747, 32, 0.3)];
+ roughnessLow = 200;
+ roughnessHigh = 240;
+ } else {
+ color = [noise(7300435, 9406064, 8), noise(4866871, 8221793, 32, 0.3)];
+ roughnessLow = 70;
+ roughnessHigh = 130;
+ }
+ } else if (presetId === "palm-frond") {
+ color = [];
+ height = [noise(7368816, 9474192, 16), stripes(6974058, 9868950, 24, 45, 0.4)];
+ roughnessLow = 140;
+ roughnessHigh = 190;
+ strength = 1;
+ } else if (presetId === "driftwood") {
+ color = [noise(9143158, 13222322, 4), stripes(7695713, 13814459, 48, 0, 0.35)];
+ height = [noise(5921370, 10855845, 4), stripes(4210752, 12632256, 48, 0, 0.45)];
+ roughnessLow = 200;
+ roughnessHigh = 245;
+ strength = 2.5;
+ } else if (presetId === "thatch") {
+ color = [
+ stripes(10585151, 14072698, 64, 90),
+ noise(7232050, 13150312, 16, 0.35),
+ stripes(6245415, 12098652, 8, 0, 0.25)
+ ];
+ height = [stripes(4210752, 12632256, 64, 90), stripes(5263440, 11579568, 8, 0, 0.4)];
+ roughnessLow = 220;
+ roughnessHigh = 250;
+ strength = 2.5;
} else {
color = [noise(5061676, 8942420, 4), noise(3418656, 10850155, 32, 0.25)];
height = [noise(5592405, 11184810, 8), noise(2236962, 14540253, 32, 0.3)];
@@ -49226,13 +49310,11 @@ function createMaterialPresetDraft(presetId, raw) {
}
]
};
- return {
+ const identity = {
materialId: options.materialId ?? preset.id,
name: preset.name,
tags: [preset.family, "procedural"],
- tileable: true,
physicalSizeMeters: { ...preset.physicalSizeMeters },
- parameters: { metalness: 1, roughness: 1 },
sources: [
{
id: "preset",
@@ -49243,25 +49325,113 @@ function createMaterialPresetDraft(presetId, raw) {
license: options.license,
originalFiles: []
}
- ],
+ ]
+ };
+ const derive = { kind: "normal-from-height", strength };
+ const roughnessMap = spec("metallicRoughness", [
+ noise(packed(roughnessLow), packed(roughnessHigh), 8)
+ ]);
+ if (presetId === "palm-frond") {
+ const sampler = {
+ minFilter: "linear-mipmap-linear",
+ magFilter: "linear",
+ wrapS: "clamp-to-edge",
+ wrapT: "clamp-to-edge"
+ };
+ return {
+ schemaVersion: 2,
+ ...identity,
+ tileable: false,
+ parameters: {
+ metalness: 1,
+ roughness: 1,
+ alphaMode: "mask",
+ alphaCutoff: 0.5,
+ doubleSided: true
+ },
+ maps: [
+ {
+ ...common,
+ slot: "baseColor",
+ sampler,
+ procedural: frondCutout(options.size, options.seed)
+ },
+ { ...common, slot: "normal", sampler, procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", sampler, procedural: roughnessMap }
+ ]
+ };
+ }
+ return {
+ materialId: identity.materialId,
+ name: identity.name,
+ tags: identity.tags,
+ tileable: true,
+ physicalSizeMeters: identity.physicalSizeMeters,
+ parameters: { metalness: 1, roughness: 1 },
+ sources: identity.sources,
maps: [
{ ...common, slot: "baseColor", procedural: spec("albedo", color) },
- {
- ...common,
- slot: "normal",
- procedural: spec("normal", height),
- derive: { kind: "normal-from-height", strength }
- },
- {
- ...common,
- slot: "metallicRoughness",
- procedural: spec("metallicRoughness", [
- noise(packed(roughnessLow), packed(roughnessHigh), 8)
- ])
- }
+ { ...common, slot: "normal", procedural: spec("normal", height), derive },
+ { ...common, slot: "metallicRoughness", procedural: roughnessMap }
]
};
}
+function presetRandom(seed) {
+ let state = seed >>> 0;
+ return () => {
+ state = state + 1831565813 >>> 0;
+ let t = state;
+ t = Math.imul(t ^ t >>> 15, t | 1);
+ t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+ return ((t ^ t >>> 14) >>> 0) / 4294967296;
+ };
+}
+function frondCutout(size, seed) {
+ const random = presetRandom(seed);
+ const unit = size / 64;
+ const centre = Math.round(size / 2);
+ const inside = (value) => Math.min(size - 2, Math.max(1, Math.round(value)));
+ const shade = (base, spread) => Math.min(255, Math.max(0, Math.round(base + (random() - 0.5) * spread)));
+ const operations = [];
+ const leaflets = 12;
+ for (let i = 0;i < leaflets; i++) {
+ const along = (i + 0.5) / leaflets;
+ const y = size - 3 * unit - along * (size - 8 * unit);
+ const width = Math.max(1, Math.round((2.4 - 1.4 * along) * unit));
+ for (const side of [-1, 1]) {
+ const reach = (0.44 - 0.3 * along) * size * (0.9 + 0.2 * random());
+ const rise = (0.08 + 0.06 * random()) * size;
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, inside(y)],
+ to: [inside(centre + side * reach), inside(y - rise)],
+ width
+ },
+ rgba: [shade(64, 24), shade(116, 30), shade(44, 18), 255]
+ });
+ }
+ }
+ operations.push({
+ op: "paint",
+ shape: {
+ kind: "line",
+ from: [centre, size - 1],
+ to: [centre, inside(2 * unit)],
+ width: Math.max(1, Math.round(1.5 * unit))
+ },
+ rgba: [104, 98, 46, 255]
+ });
+ return {
+ schemaVersion: 3,
+ width: size,
+ height: size,
+ usage: "albedo",
+ background: [0, 0, 0, 0],
+ operations
+ };
+}
// src/tools/materials.ts
var MATERIAL_ACTIONS = [
@@ -49376,7 +49546,8 @@ function createKilnMaterialDef(library, presentation = "grouped") {
license: input.license,
materialId: input.materialId
}).filter(([, value]) => value !== undefined));
- const record = await createMaterialRecordV1(createMaterialPresetDraft(input.presetId, options));
+ const draft = createMaterialPresetDraftAny(input.presetId, options);
+ const record = "schemaVersion" in draft ? await createMaterialRecordV2(draft) : await createMaterialRecordV1(draft);
const [material] = await library.import([record]);
return materialResult(material);
}
diff --git a/docs/material-library.md b/docs/material-library.md
index 3b5436d1..f2eaafa2 100644
--- a/docs/material-library.md
+++ b/docs/material-library.md
@@ -6,9 +6,27 @@ An evaluator receives only the complete pinned records selected by its host. Aut
resolve their approved resource IDs, but cannot read paths, fetch URLs, or supply resolver code.
`kiln_material` is advertised when a host supplies a material library. Its `presets` action lists
-five offline starting points: `warm-brick`, `wood-grain`, `brushed-metal`, `woven-fabric`, and
-`coarse-soil`. Each recipe produces base color, OpenGL normal, and packed metallic/roughness maps.
-They are synthetic starting points with stated physical repeat scales, not measured scans.
+these offline starting points; the `presets` and `list` actions accept a family `tag` such as `rock`.
+Each recipe produces base color, OpenGL normal, and packed metallic/roughness maps. They are
+synthetic starting points with stated physical repeat scales, not measured scans.
+
+| Preset | Family | Repeat scale | Notes |
+| --- | --- | --- | --- |
+| `warm-brick` | `architecture` | 2 × 2 m | Staggered masonry and shallow mortar relief |
+| `wood-grain` | `wood` | 1 × 1 m | Straight interior grain; no knots or end grain |
+| `brushed-metal` | `metal` | 1 × 1 m | Directional relief, fully metallic packed channel |
+| `woven-fabric` | `fabric` | 0.5 × 0.5 m | Crossed threads, matte dielectric |
+| `coarse-soil` | `ground` | 2 × 2 m | Granular soil for terrain and planting beds |
+| `beach-sand` | `ground` | 1 × 1 m | Fine pale grains with shallow wind ripples |
+| `coral-limestone` | `rock` | 2 × 2 m | Porous cream stone with pitted relief |
+| `coral-limestone-wet` | `rock` | 2 × 2 m | Darker, smoother wet stone; the same seed keeps the dry relief |
+| `palm-frond` | `foliage` | 2 × 2 m | Alpha-tested (MASK), double-sided cutout card, not tileable |
+| `driftwood` | `wood` | 1 × 1 m | Bleached silver-grey grain, deep weathering |
+| `thatch` | `fiber` | 1 × 1 m | Vertical straw strands in horizontal courses |
+
+`palm-frond` saves a `schemaVersion:2` record: its base color is a V3 RGBA silhouette with
+clamped sampling, so map it once across a card or a `foliageCardGeo` with the frond base at
+the bottom of the image. The other presets save V1 records and tile.
Create one with an explicit seed, creator, and a license the caller is authorized to apply:
@@ -103,6 +121,7 @@ const record = await createMaterialRecordV1(createMaterialPresetDraft('wood-grai
url: 'https://creativecommons.org/publicdomain/zero/1.0/', attribution: '' },
}));
await library.import([record]);
+// palm-frond needs createMaterialPresetDraftAny and createMaterialRecordV2.
// The JSON payload includes every normalized PNG, recipe, source hash and license record.
const payload = await createMaterialLibraryPayload([record]);
diff --git a/src/material-presets.test.ts b/src/material-presets.test.ts
index 6201ff1b..e81b856b 100644
--- a/src/material-presets.test.ts
+++ b/src/material-presets.test.ts
@@ -1,7 +1,17 @@
import { expect, test } from 'bun:test';
import sharp from 'sharp';
-import { createMaterialPresetDraft, listMaterialPresets } from './material-presets';
-import { createMaterialRecordV1, verifyMaterialRecordV1 } from './material-library-node';
+import { readFileSync } from 'node:fs';
+import {
+ createMaterialPresetDraft,
+ createMaterialPresetDraftAny,
+ listMaterialPresets,
+} from './material-presets';
+import {
+ createMaterialRecordV1,
+ createMaterialRecordV2,
+ verifyMaterialRecord,
+ verifyMaterialRecordV1,
+} from './material-library-node';
const options = {
seed: 19,
@@ -13,10 +23,10 @@ const options = {
attribution: '',
},
};
-test('shipped preset catalog covers five useful families with deterministic complete map recipes', async () => {
- const presets = listMaterialPresets();
- expect(new Set(presets.map((item) => item.family))).toEqual(
- new Set(['architecture', 'wood', 'metal', 'fabric', 'ground']),
+test('shipped preset catalog covers its families with deterministic complete map recipes', async () => {
+ const presets = listMaterialPresets().filter((item) => item.recordSchemaVersion === 1);
+ expect(new Set(listMaterialPresets().map((item) => item.family))).toEqual(
+ new Set(['architecture', 'wood', 'metal', 'fabric', 'ground', 'rock', 'foliage', 'fiber']),
);
for (const preset of presets) {
const draft = createMaterialPresetDraft(preset.id, options);
@@ -59,3 +69,84 @@ test('presets require explicit bounded seed and provenance and return independen
catalog[0]!.name = 'mutated';
expect(listMaterialPresets()[0]!.name).not.toBe('mutated');
});
+
+const presetRecord = (id: string, seed = options.seed) => {
+ const draft = createMaterialPresetDraftAny(id, { ...options, seed });
+ return 'schemaVersion' in draft ? createMaterialRecordV2(draft) : createMaterialRecordV1(draft);
+};
+const NATURAL = [
+ ['beach-sand', 'ground'],
+ ['coral-limestone', 'rock'],
+ ['coral-limestone-wet', 'rock'],
+ ['palm-frond', 'foliage'],
+ ['driftwood', 'wood'],
+ ['thatch', 'fiber'],
+] as const;
+
+test('natural presets follow the three-map preset contract and are deterministic per seed', async () => {
+ for (const [id, family] of NATURAL) {
+ const summary = listMaterialPresets().find((item) => item.id === id);
+ expect(summary).toMatchObject({ family, tags: [family, 'procedural'] });
+ const record = await presetRecord(id);
+ expect(record).toEqual(await presetRecord(id));
+ expect((await presetRecord(id, 20)).manifest.revisionId).not.toBe(record.manifest.revisionId);
+ expect(record.manifest.maps.map((map) => [map.slot, map.usage, map.colorSpace])).toEqual([
+ ['baseColor', 'albedo', 'srgb'],
+ ['normal', 'normal', 'linear'],
+ ['metallicRoughness', 'metallicRoughness', 'linear'],
+ ]);
+ expect(record.manifest.tags).toEqual([family, 'procedural']);
+ expect(record.manifest.physicalSizeMeters).toEqual(summary!.physicalSizeMeters);
+ expect(record.manifest.sources[0]?.license).toEqual(options.license);
+ await verifyMaterialRecord(record);
+ }
+});
+
+test('the palm frond is an alpha-tested, double-sided cutout with a real silhouette', async () => {
+ expect(() => createMaterialPresetDraft('palm-frond', options)).toThrow(
+ /createMaterialPresetDraftAny/,
+ );
+ const record = await presetRecord('palm-frond');
+ expect(record.manifest.schemaVersion).toBe(2);
+ expect(record.manifest.parameters).toMatchObject({ alphaMode: 'mask', doubleSided: true });
+ expect(record.manifest.tileable).toBe(false);
+ const alpha = new Set<number>();
+ const pixels = await sharp(record.files['baseColor.png']).raw().toBuffer();
+ for (let i = 3; i < pixels.length; i += 4) alpha.add(pixels[i]!);
+ expect(alpha).toEqual(new Set([0, 255]));
+});
+
+test('wet limestone darkens and smooths the dry stone while keeping its relief', async () => {
+ const [dry, wet] = await Promise.all([
+ presetRecord('coral-limestone'),
+ presetRecord('coral-limestone-wet'),
+ ]);
+ const mean = async (bytes: Uint8Array, channel: number) => {
+ const raw = await sharp(bytes).raw().toBuffer();
+ let sum = 0;
+ for (let i = channel; i < raw.length; i += 4) sum += raw[i]!;
+ return sum / (raw.length / 4);
+ };
+ expect(await mean(wet.files['baseColor.png']!, 0)).toBeLessThan(
+ 0.8 * (await mean(dry.files['baseColor.png']!, 0)),
+ );
+ expect(await mean(wet.files['metallicRoughness.png']!, 1)).toBeLessThan(
+ 0.7 * (await mean(dry.files['metallicRoughness.png']!, 1)),
+ );
+ expect(wet.files['normal.png']).toEqual(dry.files['normal.png']);
+});
+
+test('the docs preset table matches the shipped catalog', () => {
+ const docs = readFileSync(new URL('../docs/material-library.md', import.meta.url), 'utf8');
+ const rows = [
+ ...docs.matchAll(/^\| `([a-z-]+)` \| `([a-z]+)` \| ([\d.]+) × ([\d.]+) m \|/gm),
+ ].map((row) => [row[1], row[2], Number(row[3]), Number(row[4])]);
+ expect(rows).toEqual(
+ listMaterialPresets().map((item) => [
+ item.id,
+ item.family,
+ item.physicalSizeMeters.width,
+ item.physicalSizeMeters.height,
+ ]),
+ );
+});
diff --git a/src/material-presets.ts b/src/material-presets.ts
index 1aea1684..7fff5603 100644
--- a/src/material-presets.ts
+++ b/src/material-presets.ts
@@ -4,6 +4,7 @@ import {
assertMaterialJson,
materialLibraryIdSchema,
materialSourceSchema,
+ type ProceduralMaterialDraftV2,
} from './material-library';
import type { MaterialDraftV1 } from './material-library-node';
import type { ProceduralLayer, ProceduralTextureSpecV2 } from './procedural-material-v2';
@@ -46,7 +47,54 @@ const catalog = [
physicalSizeMeters: { width: 2, height: 2 },
description: 'Layered granular soil variation and subtle relief for terrain and planting beds.',
},
+ {
+ id: 'beach-sand',
+ name: 'Pale beach sand',
+ family: 'ground',
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: 'Fine pale grains with shallow wind ripples; no shells, wet edge or footprints.',
+ },
+ {
+ id: 'coral-limestone',
+ name: 'Dry coral limestone',
+ family: 'rock',
+ physicalSizeMeters: { width: 2, height: 2 },
+ description: 'Porous cream stone with pitted relief for coastal rocks and walls.',
+ },
+ {
+ id: 'coral-limestone-wet',
+ name: 'Wet coral limestone',
+ family: 'rock',
+ physicalSizeMeters: { width: 2, height: 2 },
+ description:
+ 'The dry limestone darkened and smoothed by water; the same seed keeps identical relief.',
+ },
+ {
+ id: 'palm-frond',
+ name: 'Palm frond cutout',
+ family: 'foliage',
+ physicalSizeMeters: { width: 2, height: 2 },
+ description:
+ 'Alpha-tested, double-sided frond card: a central rachis with tapering leaflets, base at the image bottom. Not tileable.',
+ },
+ {
+ id: 'driftwood',
+ name: 'Weathered driftwood',
+ family: 'wood',
+ physicalSizeMeters: { width: 1, height: 1 },
+ description:
+ 'Sun-bleached silver-grey grain with deep weathered relief and a dry matte finish.',
+ },
+ {
+ id: 'thatch',
+ name: 'Straw thatch',
+ family: 'fiber',
+ physicalSizeMeters: { width: 1, height: 1 },
+ description: 'Vertical straw strands in horizontal courses for roofs and shelters.',
+ },
] as const;
+/** Presets whose output needs a schemaVersion 2 record (here, a V3 RGBA cutout). */
+const RECORD_V2_PRESETS: ReadonlySet<string> = new Set(['palm-frond']);
export const materialPresetOptionsSchema = z
.object({
seed: z.number().int().min(-2147483648).max(2147483647),
@@ -65,19 +113,35 @@ export interface MaterialPresetSummary {
description: string;
tags: string[];
recipeVersion: number;
+ /** Material record version `create-preset` saves: 2 when the preset needs RGBA alpha. */
+ recordSchemaVersion: 1 | 2;
}
+export type MaterialPresetDraft = MaterialDraftV1 | ProceduralMaterialDraftV2;
export function listMaterialPresets(): MaterialPresetSummary[] {
return catalog.map((item) => ({
...item,
physicalSizeMeters: { ...item.physicalSizeMeters },
tags: [item.family, 'procedural'],
recipeVersion: 1,
+ recordSchemaVersion: RECORD_V2_PRESETS.has(item.id) ? 2 : 1,
}));
}
+/** A preset draft for `createMaterialRecordV1`. Presets that need a V2 record are refused. */
export function createMaterialPresetDraft(
presetId: string,
raw: MaterialPresetOptions,
): MaterialDraftV1 {
+ if (RECORD_V2_PRESETS.has(presetId))
+ throw new Error(
+ `${presetId} creates a schemaVersion 2 record; use createMaterialPresetDraftAny with createMaterialRecordV2.`,
+ );
+ return createMaterialPresetDraftAny(presetId, raw) as MaterialDraftV1;
+}
+/** Any preset's draft: schemaVersion 2 drafts go to `createMaterialRecordV2`, others to V1. */
+export function createMaterialPresetDraftAny(
+ presetId: string,
+ raw: MaterialPresetOptions,
+): MaterialPresetDraft {
assertMaterialJson(raw);
const options = materialPresetOptionsSchema.parse(raw);
const preset = catalog.find((item) => item.id === presetId);
@@ -147,6 +211,47 @@ export function createMaterialPresetDraft(
stripes(0x333333, 0xcccccc, 32, 90, 0.4),
];
strength = 1;
+ } else if (presetId === 'beach-sand') {
+ color = [noise(0xcfb98f, 0xeadbb6, 32), noise(0xa8916a, 0xf6ecd4, 64, 0.25)];
+ height = [noise(0x707070, 0x909090, 32), stripes(0x6c6c6c, 0x949494, 12, 15, 0.35)];
+ roughnessLow = 215;
+ roughnessHigh = 245;
+ strength = 1.5;
+ } else if (presetId === 'coral-limestone' || presetId === 'coral-limestone-wet') {
+ // Both variants share the pitted height, so one seed gives identical relief wet or dry.
+ height = [noise(0x606060, 0xa0a0a0, 8), noise(0x303030, 0xd0d0d0, 32, 0.6)];
+ strength = 3;
+ if (presetId === 'coral-limestone') {
+ color = [noise(0xc9bea4, 0xe9e1cd, 8), noise(0x8a806b, 0xd9d0bb, 32, 0.3)];
+ roughnessLow = 200;
+ roughnessHigh = 240;
+ } else {
+ color = [noise(0x6f6553, 0x8f8670, 8), noise(0x4a4337, 0x7d7461, 32, 0.3)];
+ roughnessLow = 70;
+ roughnessHigh = 130;
+ }
+ } else if (presetId === 'palm-frond') {
+ color = [];
+ height = [noise(0x707070, 0x909090, 16), stripes(0x6a6a6a, 0x969696, 24, 45, 0.4)];
+ roughnessLow = 140;
+ roughnessHigh = 190;
+ strength = 1;
+ } else if (presetId === 'driftwood') {
+ color = [noise(0x8b8376, 0xc9c1b2, 4), stripes(0x756d61, 0xd2cabb, 48, 0, 0.35)];
+ height = [noise(0x5a5a5a, 0xa5a5a5, 4), stripes(0x404040, 0xc0c0c0, 48, 0, 0.45)];
+ roughnessLow = 200;
+ roughnessHigh = 245;
+ strength = 2.5;
+ } else if (presetId === 'thatch') {
+ color = [
+ stripes(0xa1843f, 0xd6bb7a, 64, 90),
+ noise(0x6e5a32, 0xc8a868, 16, 0.35),
+ stripes(0x5f4c27, 0xb89c5c, 8, 0, 0.25),
+ ];
+ height = [stripes(0x404040, 0xc0c0c0, 64, 90), stripes(0x505050, 0xb0b0b0, 8, 0, 0.4)];
+ roughnessLow = 220;
+ roughnessHigh = 250;
+ strength = 2.5;
} else {
color = [noise(0x4d3c2c, 0x887354, 4), noise(0x342a20, 0xa58f6b, 32, 0.25)];
height = [noise(0x555555, 0xaaaaaa, 8), noise(0x222222, 0xdddddd, 32, 0.3)];
@@ -169,17 +274,15 @@ export function createMaterialPresetDraft(
},
],
};
- return {
+ const identity = {
materialId: options.materialId ?? preset.id,
name: preset.name,
tags: [preset.family, 'procedural'],
- tileable: true,
physicalSizeMeters: { ...preset.physicalSizeMeters },
- parameters: { metalness: 1, roughness: 1 },
sources: [
{
id: 'preset',
- kind: 'procedural',
+ kind: 'procedural' as const,
provider: 'Kiln material presets v1',
creator: options.creator,
assetId: preset.id,
@@ -187,21 +290,117 @@ export function createMaterialPresetDraft(
originalFiles: [],
},
],
+ };
+ const derive = { kind: 'normal-from-height' as const, strength };
+ const roughnessMap = spec('metallicRoughness', [
+ noise(packed(roughnessLow), packed(roughnessHigh), 8),
+ ]);
+ if (presetId === 'palm-frond') {
+ const sampler = {
+ minFilter: 'linear-mipmap-linear',
+ magFilter: 'linear',
+ wrapS: 'clamp-to-edge',
+ wrapT: 'clamp-to-edge',
+ } as const;
+ return {
+ schemaVersion: 2,
+ ...identity,
+ tileable: false,
+ parameters: {
+ metalness: 1,
+ roughness: 1,
+ alphaMode: 'mask',
+ alphaCutoff: 0.5,
+ doubleSided: true,
+ },
+ maps: [
+ {
+ ...common,
+ slot: 'baseColor',
+ sampler,
+ procedural: frondCutout(options.size, options.seed),
+ },
+ { ...common, slot: 'normal', sampler, procedural: spec('normal', height), derive },
+ { ...common, slot: 'metallicRoughness', sampler, procedural: roughnessMap },
+ ],
+ } as ProceduralMaterialDraftV2;
+ }
+ return {
+ materialId: identity.materialId,
+ name: identity.name,
+ tags: identity.tags,
+ tileable: true,
+ physicalSizeMeters: identity.physicalSizeMeters,
+ parameters: { metalness: 1, roughness: 1 },
+ sources: identity.sources,
maps: [
{ ...common, slot: 'baseColor', procedural: spec('albedo', color) },
- {
- ...common,
- slot: 'normal',
- procedural: spec('normal', height),
- derive: { kind: 'normal-from-height', strength },
- },
- {
- ...common,
- slot: 'metallicRoughness',
- procedural: spec('metallicRoughness', [
- noise(packed(roughnessLow), packed(roughnessHigh), 8),
- ]),
- },
+ { ...common, slot: 'normal', procedural: spec('normal', height), derive },
+ { ...common, slot: 'metallicRoughness', procedural: roughnessMap },
],
};
}
+
+/** Deterministic 32-bit generator for preset geometry; never Math.random. */
+function presetRandom(seed: number) {
+ let state = seed >>> 0;
+ return () => {
+ state = (state + 0x6d2b79f5) >>> 0;
+ let t = state;
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+/**
+ * V3 RGBA frond silhouette: a rachis up the image centre from the bottom edge, with paired
+ * leaflets that shorten and narrow toward the tip. Everything else is fully transparent.
+ */
+function frondCutout(size: number, seed: number) {
+ const random = presetRandom(seed);
+ const unit = size / 64;
+ const centre = Math.round(size / 2);
+ const inside = (value: number) => Math.min(size - 2, Math.max(1, Math.round(value)));
+ const shade = (base: number, spread: number) =>
+ Math.min(255, Math.max(0, Math.round(base + (random() - 0.5) * spread)));
+ const operations: object[] = [];
+ const leaflets = 12;
+ for (let i = 0; i < leaflets; i++) {
+ const along = (i + 0.5) / leaflets;
+ const y = size - 3 * unit - along * (size - 8 * unit);
+ const width = Math.max(1, Math.round((2.4 - 1.4 * along) * unit));
+ for (const side of [-1, 1]) {
+ const reach = (0.44 - 0.3 * along) * size * (0.9 + 0.2 * random());
+ const rise = (0.08 + 0.06 * random()) * size;
+ operations.push({
+ op: 'paint',
+ shape: {
+ kind: 'line',
+ from: [centre, inside(y)],
+ to: [inside(centre + side * reach), inside(y - rise)],
+ width,
+ },
+ rgba: [shade(64, 24), shade(116, 30), shade(44, 18), 255],
+ });
+ }
+ }
+ operations.push({
+ op: 'paint',
+ shape: {
+ kind: 'line',
+ from: [centre, size - 1],
+ to: [centre, inside(2 * unit)],
+ width: Math.max(1, Math.round(1.5 * unit)),
+ },
+ rgba: [104, 98, 46, 255],
+ });
+ return {
+ schemaVersion: 3 as const,
+ width: size,
+ height: size,
+ usage: 'albedo' as const,
+ background: [0, 0, 0, 0],
+ operations,
+ };
+}
diff --git a/src/tools/materials.test.ts b/src/tools/materials.test.ts
index 2a2beef3..95519419 100644
--- a/src/tools/materials.test.ts
+++ b/src/tools/materials.test.ts
@@ -141,7 +141,7 @@ test('material tools discover and instantiate shipped presets without external p
const catalog = (await tool.run({ action: 'presets', tag: 'wood' })) as {
presets: { id: string }[];
};
- expect(catalog.presets).toHaveLength(1);
+ expect(catalog.presets.map((preset) => preset.id)).toEqual(['wood-grain', 'driftwood']);
const input = {
action: 'create-preset',
presetId: catalog.presets[0]!.id,
@@ -153,4 +153,12 @@ test('material tools discover and instantiate shipped presets without external p
const result = (await tool.run(input)) as { material: { materialId: string } };
expect(result.material.materialId).toBe('wood-grain');
expect(await tool.run(input)).toEqual(result);
+ const frond = (await tool.run({ ...input, presetId: 'palm-frond' })) as {
+ material: { materialId: string; schemaVersion: number; parameters: object };
+ };
+ expect(frond.material).toMatchObject({
+ materialId: 'palm-frond',
+ schemaVersion: 2,
+ parameters: { alphaMode: 'mask', doubleSided: true },
+ });
});
diff --git a/src/tools/materials.ts b/src/tools/materials.ts
index 5f24ac12..beea3524 100644
--- a/src/tools/materials.ts
+++ b/src/tools/materials.ts
@@ -9,9 +9,13 @@ import {
type MaterialLibrary,
type MaterialManifest,
} from '../material-library';
-import { createMaterialRecordV1, decodeMaterialLibraryPayload } from '../material-library-node';
+import {
+ createMaterialRecordV1,
+ createMaterialRecordV2,
+ decodeMaterialLibraryPayload,
+} from '../material-library-node';
import { createProceduralMaterialRecord } from '../material-authoring-node';
-import { createMaterialPresetDraft, listMaterialPresets } from '../material-presets';
+import { createMaterialPresetDraftAny, listMaterialPresets } from '../material-presets';
import { nestedRecordDescription, requireActionFields } from './actions';
import type { KilnToolDef } from './registry';
import type { KilnActionContract } from './operation-contract';
@@ -188,9 +192,11 @@ export function createKilnMaterialDef(
materialId: input.materialId,
}).filter(([, value]) => value !== undefined),
);
- const record = await createMaterialRecordV1(
- createMaterialPresetDraft(input.presetId!, options as never),
- );
+ const draft = createMaterialPresetDraftAny(input.presetId!, options as never);
+ const record =
+ 'schemaVersion' in draft
+ ? await createMaterialRecordV2(draft)
+ : await createMaterialRecordV1(draft);
const [material] = await library.import([record]);
return materialResult(material!);
}